@pnpm/deps.inspection.tree-builder 1001.1.3

package/lib/getTree.js

@@ -0,0 +1,220 @@
+import path from 'node:path';
+import { lexCompare } from '@pnpm/util.lex-comparator';
+import { getPkgInfo } from './getPkgInfo.js';
+import { peersSuffixHashFromDepPath } from './peersSuffixHash.js';
+import { serializeTreeNodeId } from './TreeNodeId.js';
+export function getTree(opts, parentId) {
+    const ancestors = new Set();
+    ancestors.add(serializeTreeNodeId(parentId));
+    const ctx = {
+        ...opts,
+        ancestors,
+    };
+    const result = materializeChildren(ctx, parentId, opts.maxDepth, opts.parentDir);
+    // Mark circular back-edges.  materializeChildren truncates dependencies
+    // at cycle boundaries but does not set the `circular` flag, so that cached
+    // subtrees stay context-independent.  fixCircularRefs walks the final tree
+    // and adds `circular: true` wherever a node's path matches an ancestor.
+    //
+    // Seed the ancestors with parentDir (the filesystem path of parentId) so
+    // that back-edges to the root of this subtree are detected — the root
+    // itself does not appear as a node in the tree, only its children do.
+    const circularAncestors = new Set();
+    if (opts.parentDir) {
+        circularAncestors.add(opts.parentDir);
+    }
+    return fixCircularRefs(result.nodes, circularAncestors);
+}
+// ---------------------------------------------------------------------------
+// Materialize DependencyNode[] tree from the graph
+// ---------------------------------------------------------------------------
+function materializeCacheKey(nodeId, depth) {
+    if (depth === Infinity)
+        return nodeId;
+    return `${nodeId}@d${depth}`;
+}
+/**
+ * Core materialization function.  Walks the pre-built dependency graph to
+ * produce the `DependencyNode[]` tree that downstream renderers expect.
+ *
+ * The cache is keyed by `(nodeId, remainingDepth)` and stores the
+ * `DependencyNode[]` children of a given node.  It is populated
+ * unconditionally, including results where recursion was truncated at a
+ * cycle boundary.  Cycle detection uses a mutable `ancestors` Set to
+ * stop recursion but does NOT set the `circular` flag — that is handled
+ * by `fixCircularRefs` in a separate pass over the final tree.  This
+ * keeps cached subtrees free of context-dependent circular markers.
+ */
+function materializeChildren(ctx, parentId, maxDepth, parentDir) {
+    if (maxDepth <= 0)
+        return { nodes: [], count: 0, hasSearchMatch: false, searchMessages: [] };
+    const parentSerialized = serializeTreeNodeId(parentId);
+    const graphNode = ctx.graph.nodes.get(parentSerialized);
+    if (!graphNode) {
+        throw new Error(`Node ${parentSerialized} not found in the dependency graph`);
+    }
+    const childTreeMaxDepth = maxDepth - 1;
+    const linkedPathBaseDir = parentId.type === 'importer'
+        ? path.join(ctx.lockfileDir, parentId.importerId)
+        : ctx.lockfileDir;
+    const resultDependencies = [];
+    let resultCount = 0;
+    let resultHasSearchMatch = false;
+    const resultSearchMessages = ctx.showDedupedSearchMatches ? [] : undefined;
+    // Sort edges by alias so that deduplication is deterministic:
+    // the alphabetically-first dependency always gets fully expanded.
+    const sortedEdges = [...graphNode.edges].sort((a, b) => lexCompare(a.alias, b.alias));
+    for (const edge of sortedEdges) {
+        if (ctx.onlyProjects && edge.target?.nodeId.type !== 'importer') {
+            continue;
+        }
+        const { pkgInfo: packageInfo, readManifest } = getPkgInfo({
+            ...ctx,
+            alias: edge.alias,
+            ref: edge.ref,
+            peers: graphNode.peers,
+            linkedPathBaseDir,
+            parentDir,
+        });
+        const searchMatch = ctx.search?.({
+            alias: edge.alias,
+            name: packageInfo.name,
+            version: packageInfo.version,
+            readManifest,
+        });
+        let newEntry = null;
+        let childCount = 0;
+        let dedupedHasSearchMatch = false;
+        let dedupedSearchMessages = [];
+        if (edge.target == null) {
+            // External link or unresolvable — no traversal possible
+            if (ctx.search == null || searchMatch) {
+                newEntry = packageInfo;
+            }
+            else {
+                continue;
+            }
+        }
+        else {
+            let dependencies;
+            let childHasSearchMatch = false;
+            let childSearchMessages = [];
+            let dedupedCount;
+            const circular = ctx.ancestors.has(edge.target.id);
+            if (circular) {
+                dependencies = [];
+            }
+            else {
+                const cacheKey = materializeCacheKey(edge.target.id, childTreeMaxDepth);
+                const cached = ctx.materializationCache.get(cacheKey);
+                if (cached !== undefined) {
+                    // This subtree was already returned to a parent elsewhere in
+                    // the output tree — elide it to avoid repeating the same nodes.
+                    dependencies = [];
+                    if (cached.count > 0) {
+                        dedupedCount = cached.count;
+                    }
+                    if (ctx.showDedupedSearchMatches) {
+                        dedupedHasSearchMatch = cached.hasSearchMatch;
+                        dedupedSearchMessages = cached.searchMessages;
+                    }
+                }
+                else {
+                    ctx.ancestors.add(edge.target.id);
+                    const childResult = materializeChildren(ctx, edge.target.nodeId, childTreeMaxDepth, packageInfo.path);
+                    ctx.ancestors.delete(edge.target.id);
+                    dependencies = childResult.nodes;
+                    childCount = childResult.count;
+                    childHasSearchMatch = childResult.hasSearchMatch;
+                    childSearchMessages = childResult.searchMessages;
+                    // Always cache — even results with circular truncations.
+                    ctx.materializationCache.set(cacheKey, {
+                        count: childCount,
+                        hasSearchMatch: childHasSearchMatch,
+                        searchMessages: childSearchMessages,
+                    });
+                }
+                if (childHasSearchMatch || dedupedHasSearchMatch) {
+                    resultHasSearchMatch = true;
+                }
+                resultSearchMessages?.push(...childSearchMessages, ...dedupedSearchMessages);
+            }
+            if (dependencies.length > 0) {
+                newEntry = {
+                    ...packageInfo,
+                    dependencies,
+                };
+            }
+            else if (ctx.search == null || searchMatch || dedupedHasSearchMatch) {
+                newEntry = packageInfo;
+            }
+            else {
+                continue;
+            }
+            if (dedupedCount != null) {
+                newEntry.deduped = true;
+                newEntry.dedupedDependenciesCount = dedupedCount;
+            }
+            if (edge.target.nodeId.type === 'package') {
+                const peerHash = peersSuffixHashFromDepPath(edge.target.nodeId.depPath);
+                if (peerHash != null) {
+                    newEntry.peersSuffixHash = peerHash;
+                }
+            }
+        }
+        if (searchMatch) {
+            newEntry.searched = true;
+            resultHasSearchMatch = true;
+            if (typeof searchMatch === 'string') {
+                newEntry.searchMessage = searchMatch;
+                resultSearchMessages?.push(searchMatch);
+            }
+        }
+        else if (dedupedHasSearchMatch) {
+            newEntry.searched = true;
+            if (dedupedSearchMessages.length > 0) {
+                newEntry.searchMessage = dedupedSearchMessages.join('\n');
+            }
+        }
+        if (!newEntry.isPeer || !ctx.excludePeerDependencies || newEntry.dependencies?.length) {
+            resultDependencies.push(newEntry);
+            resultCount += 1 + (newEntry.dependencies?.length ? childCount : 0);
+        }
+    }
+    return {
+        count: resultCount,
+        hasSearchMatch: resultHasSearchMatch,
+        nodes: resultDependencies,
+        searchMessages: resultSearchMessages ?? [],
+    };
+}
+/**
+ * Walks the materialized DependencyNode[] tree and marks circular back-edges.
+ * A node whose `path` matches an ancestor is a cycle — it gets
+ * `circular: true` and its dependencies (if any) are stripped.
+ *
+ * With deduplication in place (deduped nodes are leaves), the walk is O(N).
+ */
+function fixCircularRefs(nodes, ancestors) {
+    let changed = false;
+    const result = nodes.map(node => {
+        // A node whose path matches an ancestor is a circular back-edge.
+        if (node.path && ancestors.has(node.path)) {
+            changed = true;
+            const { dependencies: _, deduped: _d, dedupedDependenciesCount: _c, ...rest } = node;
+            return { ...rest, circular: true };
+        }
+        if (!node.dependencies?.length)
+            return node;
+        ancestors.add(node.path);
+        const fixedDeps = fixCircularRefs(node.dependencies, ancestors);
+        ancestors.delete(node.path);
+        if (fixedDeps !== node.dependencies) {
+            changed = true;
+            return { ...node, dependencies: fixedDeps };
+        }
+        return node;
+    });
+    return changed ? result : nodes;
+}
+//# sourceMappingURL=getTree.js.map

package/lib/getTreeNodeChildId.d.ts

@@ -0,0 +1,12 @@
+import { type ProjectSnapshot } from '@pnpm/lockfile.fs';
+import type { TreeNodeId } from './TreeNodeId.js';
+export interface GetTreeNodeChildIdOpts {
+    readonly parentId: TreeNodeId;
+    readonly dep: {
+        readonly alias: string;
+        readonly ref: string;
+    };
+    readonly lockfileDir: string;
+    readonly importers: Record<string, ProjectSnapshot>;
+}
+export declare function getTreeNodeChildId(opts: GetTreeNodeChildIdOpts): TreeNodeId | undefined;

package/lib/getTreeNodeChildId.js

@@ -0,0 +1,36 @@
+import path from 'node:path';
+import { refToRelative } from '@pnpm/deps.path';
+import { getLockfileImporterId } from '@pnpm/lockfile.fs';
+export function getTreeNodeChildId(opts) {
+    const depPath = refToRelative(opts.dep.ref, opts.dep.alias);
+    if (depPath !== null) {
+        return { type: 'package', depPath };
+    }
+    switch (opts.parentId.type) {
+        case 'importer': {
+            // This should be a link given depPath is null.
+            //
+            // TODO: Consider updating refToRelative (or writing a new function) to
+            // return an enum so there's no implicit assumptions.
+            const linkValue = opts.dep.ref.slice('link:'.length);
+            // It's a bit roundabout to prepend the lockfile dir only to remove it
+            // through getLockfileImporterId, but we can be more certain the right
+            // importerId is created by reusing the getLockfileImporterId function.
+            const absoluteLinkedPath = path.join(opts.lockfileDir, opts.parentId.importerId, linkValue);
+            const childImporterId = getLockfileImporterId(opts.lockfileDir, absoluteLinkedPath);
+            // A 'link:' reference may refer to a package outside of the pnpm workspace.
+            // Return undefined in that case since it would be difficult to list/traverse
+            // that package outside of the pnpm workspace.
+            const isLinkOutsideWorkspace = opts.importers[childImporterId] == null;
+            return isLinkOutsideWorkspace
+                ? undefined
+                : { type: 'importer', importerId: childImporterId };
+        }
+        case 'package':
+            // In theory an external package could be overridden to link to a
+            // dependency in the pnpm workspace. Avoid traversing through this
+            // edge case for now.
+            return undefined;
+    }
+}
+//# sourceMappingURL=getTreeNodeChildId.js.map

package/lib/index.d.ts

@@ -0,0 +1,4 @@
+export { buildDependenciesTree, type DependenciesTree } from './buildDependenciesTree.js';
+export { buildDependentsTree, type DependentNode, type DependentsTree, type ImporterInfo } from './buildDependentsTree.js';
+export { createPackagesSearcher } from './createPackagesSearcher.js';
+export { type DependencyNode } from './DependencyNode.js';

package/lib/index.js

@@ -0,0 +1,5 @@
+export { buildDependenciesTree } from './buildDependenciesTree.js';
+export { buildDependentsTree } from './buildDependentsTree.js';
+export { createPackagesSearcher } from './createPackagesSearcher.js';
+export {} from './DependencyNode.js';
+//# sourceMappingURL=index.js.map

package/lib/peersSuffixHash.d.ts

@@ -0,0 +1 @@
+export declare function peersSuffixHashFromDepPath(depPath: string): string | undefined;

package/lib/peersSuffixHash.js

@@ -0,0 +1,9 @@
+import crypto from 'node:crypto';
+import { parseDepPath } from '@pnpm/deps.path';
+export function peersSuffixHashFromDepPath(depPath) {
+    const { peerDepGraphHash } = parseDepPath(depPath);
+    if (!peerDepGraphHash)
+        return undefined;
+    return crypto.createHash('sha256').update(peerDepGraphHash).digest('hex').slice(0, 4);
+}
+//# sourceMappingURL=peersSuffixHash.js.map

package/lib/readManifestFromCafs.d.ts

@@ -0,0 +1,11 @@
+import { type StoreIndex } from '@pnpm/store.index';
+import type { DependencyManifest } from '@pnpm/types';
+/**
+ * Attempts to read a package manifest from the content-addressable store (CAFS)
+ * using its integrity hash. Returns `undefined` if the manifest cannot be read.
+ */
+export declare function readManifestFromCafs(storeDir: string, storeIndex: StoreIndex, pkg: {
+    integrity: string;
+    name: string;
+    version: string;
+}): DependencyManifest | undefined;

package/lib/readManifestFromCafs.js

@@ -0,0 +1,26 @@
+import { getFilePathByModeInCafs } from '@pnpm/store.cafs';
+import { storeIndexKey } from '@pnpm/store.index';
+import { loadJsonFileSync } from 'load-json-file';
+/**
+ * Attempts to read a package manifest from the content-addressable store (CAFS)
+ * using its integrity hash. Returns `undefined` if the manifest cannot be read.
+ */
+export function readManifestFromCafs(storeDir, storeIndex, pkg) {
+    try {
+        const pkgId = `${pkg.name}@${pkg.version}`;
+        const indexPath = storeIndexKey(pkg.integrity, pkgId);
+        const pkgIndex = storeIndex.get(indexPath);
+        if (!pkgIndex)
+            return undefined;
+        const pkgJsonEntry = pkgIndex.files.get('package.json');
+        if (pkgJsonEntry) {
+            const filePath = getFilePathByModeInCafs(storeDir, pkgJsonEntry.digest, pkgJsonEntry.mode);
+            return loadJsonFileSync(filePath);
+        }
+    }
+    catch {
+        // Fall through to undefined
+    }
+    return undefined;
+}
+//# sourceMappingURL=readManifestFromCafs.js.map

package/lib/resolvePackagePath.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Resolves the filesystem path for a package identified by its depPath.
+ *
+ * For local virtual stores, the path is constructed directly.
+ * For global virtual stores (where virtualStoreDir is outside modulesDir),
+ * symlinks are resolved to find the actual store location.
+ */
+export declare function resolvePackagePath(opts: {
+    depPath: string;
+    name: string;
+    alias: string;
+    virtualStoreDir: string;
+    virtualStoreDirMaxLength: number;
+    modulesDir?: string;
+    parentDir?: string;
+}): string;

package/lib/resolvePackagePath.js

@@ -0,0 +1,47 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { depPathToFilename } from '@pnpm/deps.path';
+/**
+ * Resolves the filesystem path for a package identified by its depPath.
+ *
+ * For local virtual stores, the path is constructed directly.
+ * For global virtual stores (where virtualStoreDir is outside modulesDir),
+ * symlinks are resolved to find the actual store location.
+ */
+export function resolvePackagePath(opts) {
+    let fullPackagePath = path.join(opts.virtualStoreDir, depPathToFilename(opts.depPath, opts.virtualStoreDirMaxLength), 'node_modules', opts.name);
+    // Resolve symlink for global virtual store.
+    // Global virtual store is detected when virtualStoreDir is outside the project's node_modules.
+    const resolvedVirtualStoreDir = path.resolve(opts.virtualStoreDir);
+    const resolvedModulesDir = opts.modulesDir ? path.resolve(opts.modulesDir) : undefined;
+    const isGlobalVirtualStore = resolvedModulesDir &&
+        !resolvedVirtualStoreDir.startsWith(resolvedModulesDir + path.sep) &&
+        resolvedVirtualStoreDir !== resolvedModulesDir;
+    if (isGlobalVirtualStore) {
+        try {
+            let nodeModulesDir;
+            if (opts.parentDir) {
+                // parentDir example: /store/.../node_modules/express
+                //                    /store/.../node_modules/@scope/pkg
+                // We need the node_modules directory to find sibling packages
+                nodeModulesDir = path.dirname(opts.parentDir);
+                // For scoped packages (@org/pkg), go up one more level
+                if (path.basename(nodeModulesDir).startsWith('@')) {
+                    nodeModulesDir = path.dirname(nodeModulesDir);
+                }
+            }
+            else if (opts.modulesDir) {
+                nodeModulesDir = opts.modulesDir;
+            }
+            else {
+                return fullPackagePath;
+            }
+            fullPackagePath = fs.realpathSync(path.join(nodeModulesDir, opts.alias));
+        }
+        catch {
+            // Fallback to constructed path if symlink doesn't exist
+        }
+    }
+    return fullPackagePath;
+}
+//# sourceMappingURL=resolvePackagePath.js.map

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "@pnpm/deps.inspection.tree-builder",
+  "version": "1001.1.3",
+  "description": "Creates a dependencies hierarchy for a symlinked `node_modules`",
+  "keywords": [
+    "pnpm",
+    "pnpm11",
+    "dependencies",
+    "hierarchy",
+    "node_modules"
+  ],
+  "license": "MIT",
+  "funding": "https://opencollective.com/pnpm",
+  "repository": "https://github.com/pnpm/pnpm/tree/main/deps/inspection/tree-builder",
+  "homepage": "https://github.com/pnpm/pnpm/tree/main/deps/inspection/tree-builder#readme",
+  "bugs": {
+    "url": "https://github.com/pnpm/pnpm/issues"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "exports": {
+    ".": "./lib/index.js"
+  },
+  "files": [
+    "lib",
+    "!*.map"
+  ],
+  "dependencies": {
+    "@pnpm/npm-package-arg": "^2.0.0",
+    "@pnpm/util.lex-comparator": "^3.0.2",
+    "load-json-file": "^7.0.1",
+    "normalize-path": "^3.0.0",
+    "realpath-missing": "^2.0.0",
+    "resolve-link-target": "^3.0.0",
+    "semver": "^7.7.2",
+    "@pnpm/config.normalize-registries": "1000.1.4",
+    "@pnpm/config.matcher": "1000.1.0",
+    "@pnpm/deps.path": "1001.1.3",
+    "@pnpm/fs.read-modules-dir": "1000.0.0",
+    "@pnpm/lockfile.fs": "1001.1.21",
+    "@pnpm/installing.modules-yaml": "1000.3.6",
+    "@pnpm/lockfile.utils": "1003.0.3",
+    "@pnpm/lockfile.detect-dep-types": "1001.0.16",
+    "@pnpm/pkg-manifest.reader": "1000.1.2",
+    "@pnpm/store.index": "1000.0.0-0",
+    "@pnpm/store.cafs": "1000.0.19",
+    "@pnpm/types": "1000.9.0"
+  },
+  "devDependencies": {
+    "@types/normalize-path": "^3.0.2",
+    "@types/semver": "7.7.1",
+    "@pnpm/constants": "1001.3.1",
+    "@pnpm/deps.inspection.tree-builder": "1001.1.3",
+    "@pnpm/test-fixtures": "1000.0.0"
+  },
+  "engines": {
+    "node": ">=22.13"
+  },
+  "jest": {
+    "preset": "@pnpm/jest-config"
+  },
+  "scripts": {
+    "lint": "eslint \"src/**/*.ts\" \"test/**/*.ts\"",
+    "_test": "cross-env NODE_OPTIONS=\"$NODE_OPTIONS --experimental-vm-modules --disable-warning=ExperimentalWarning --disable-warning=DEP0169\" jest",
+    "test": "pnpm run compile && pnpm run _test",
+    "compile": "tsgo --build && pnpm run lint --fix"
+  }
+}