@pnpm/deps.inspection.tree-builder 1001.1.3

package/LICENSE

@@ -0,0 +1,22 @@
+The MIT License (MIT)
+
+Copyright (c) 2015-2016 Rico Sta. Cruz and other contributors
+Copyright (c) 2016-2026 Zoltan Kochan and other contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,19 @@
+# @pnpm/reviewing.tree-builder
+
+> Creates a dependencies hierarchy for a symlinked \`node_modules\`
+
+<!--@shields('npm')-->
+[![npm version](https://img.shields.io/npm/v/tree-builder.svg)](https://www.npmjs.com/package/tree-builder)
+<!--/@-->
+
+A symlinked `node_modules` is created when installing using [pnpm](https://github.com/pnpm/pnpm).
+
+## Installation
+
+```
+pnpm add @pnpm/reviewing.tree-builder
+```
+
+## License
+
+MIT

package/lib/DependencyNode.d.ts

@@ -0,0 +1,28 @@
+export interface DependencyNode {
+    alias: string;
+    circular?: true;
+    deduped?: true;
+    /**
+     * When `deduped` is true, the number of transitive dependencies that were
+     * elided because this subtree was already expanded elsewhere in the tree.
+     */
+    dedupedDependenciesCount?: number;
+    /**
+     * Short hash of the peer dependency suffix in the depPath, used to
+     * distinguish deduped instances of the same package with different
+     * peer dependency resolutions.
+     */
+    peersSuffixHash?: string;
+    dependencies?: DependencyNode[];
+    dev?: boolean;
+    isPeer: boolean;
+    isSkipped: boolean;
+    isMissing: boolean;
+    name: string;
+    optional?: true;
+    path: string;
+    resolved?: string;
+    searched?: true;
+    version: string;
+    searchMessage?: string;
+}

package/lib/DependencyNode.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=DependencyNode.js.map

package/lib/TreeNodeId.d.ts

@@ -0,0 +1,18 @@
+import type { DepPath } from '@pnpm/types';
+export type TreeNodeId = TreeNodeIdImporter | TreeNodeIdPackage;
+/**
+ * A project local to the pnpm workspace.
+ */
+interface TreeNodeIdImporter {
+    readonly type: 'importer';
+    readonly importerId: string;
+}
+/**
+ * An npm package depended on externally.
+ */
+interface TreeNodeIdPackage {
+    readonly type: 'package';
+    readonly depPath: DepPath;
+}
+export declare function serializeTreeNodeId(treeNodeId: TreeNodeId): string;
+export {};

package/lib/TreeNodeId.js

@@ -0,0 +1,17 @@
+export function serializeTreeNodeId(treeNodeId) {
+    switch (treeNodeId.type) {
+        case 'importer': {
+            // Only serialize known fields from TreeNodeId. TypeScript is duck typed and
+            // objects can have any number of unknown extra fields.
+            const { type, importerId } = treeNodeId;
+            return JSON.stringify({ type, importerId });
+        }
+        case 'package': {
+            const { type, depPath } = treeNodeId;
+            return JSON.stringify({ type, depPath });
+        }
+        default:
+            throw new Error(`Unknown TreeNodeId type: ${treeNodeId.type}`);
+    }
+}
+//# sourceMappingURL=TreeNodeId.js.map

package/lib/buildDependenciesTree.d.ts

@@ -0,0 +1,25 @@
+import { type DependenciesField, type Finder, type Registries } from '@pnpm/types';
+import type { DependencyNode } from './DependencyNode.js';
+export interface DependenciesTree {
+    dependencies?: DependencyNode[];
+    devDependencies?: DependencyNode[];
+    optionalDependencies?: DependencyNode[];
+    unsavedDependencies?: DependencyNode[];
+}
+export declare function buildDependenciesTree(projectPaths: string[] | undefined, maybeOpts: {
+    depth: number;
+    excludePeerDependencies?: boolean;
+    include?: {
+        [dependenciesField in DependenciesField]: boolean;
+    };
+    registries?: Registries;
+    onlyProjects?: boolean;
+    search?: Finder;
+    showDedupedSearchMatches?: boolean;
+    lockfileDir: string;
+    checkWantedLockfileOnly?: boolean;
+    modulesDir?: string;
+    virtualStoreDirMaxLength: number;
+}): Promise<{
+    [projectDir: string]: DependenciesTree;
+}>;

package/lib/buildDependenciesTree.js

@@ -0,0 +1,184 @@
+import path from 'node:path';
+import { normalizeRegistries } from '@pnpm/config.normalize-registries';
+import { readModulesDir } from '@pnpm/fs.read-modules-dir';
+import { readModulesManifest } from '@pnpm/installing.modules-yaml';
+import { detectDepTypes } from '@pnpm/lockfile.detect-dep-types';
+import { getLockfileImporterId, readCurrentLockfile, readWantedLockfile, } from '@pnpm/lockfile.fs';
+import { safeReadPackageJsonFromDir } from '@pnpm/pkg-manifest.reader';
+import { StoreIndex } from '@pnpm/store.index';
+import { DEPENDENCIES_FIELDS } from '@pnpm/types';
+import normalizePath from 'normalize-path';
+import { realpathMissing } from 'realpath-missing';
+import { resolveLinkTarget } from 'resolve-link-target';
+import { buildDependencyGraph } from './buildDependencyGraph.js';
+import { getTree } from './getTree.js';
+export async function buildDependenciesTree(projectPaths, maybeOpts) {
+    if (!maybeOpts?.lockfileDir) {
+        throw new TypeError('opts.lockfileDir is required');
+    }
+    const modulesDir = await realpathMissing(path.join(maybeOpts.lockfileDir, maybeOpts.modulesDir ?? 'node_modules'));
+    const modules = await readModulesManifest(modulesDir);
+    const registries = normalizeRegistries({
+        ...maybeOpts?.registries,
+        ...modules?.registries,
+    });
+    const internalPnpmDir = path.join(modulesDir, '.pnpm');
+    const currentLockfile = await readCurrentLockfile(internalPnpmDir, { ignoreIncompatible: false });
+    const wantedLockfile = await readWantedLockfile(maybeOpts.lockfileDir, { ignoreIncompatible: false });
+    if (projectPaths == null) {
+        projectPaths = Object.keys(wantedLockfile?.importers ?? {})
+            .map((id) => path.join(maybeOpts.lockfileDir, id));
+    }
+    const result = {};
+    const lockfileToUse = maybeOpts.checkWantedLockfileOnly ? wantedLockfile : (currentLockfile ?? wantedLockfile);
+    if (!lockfileToUse) {
+        for (const projectPath of projectPaths) {
+            result[projectPath] = {};
+        }
+        return result;
+    }
+    const storeDir = modules?.storeDir;
+    const storeIndex = storeDir ? new StoreIndex(storeDir) : undefined;
+    const opts = {
+        depth: maybeOpts.depth || 0,
+        excludePeerDependencies: maybeOpts.excludePeerDependencies,
+        include: maybeOpts.include ?? {
+            dependencies: true,
+            devDependencies: true,
+            optionalDependencies: true,
+        },
+        lockfileDir: maybeOpts.lockfileDir,
+        checkWantedLockfileOnly: maybeOpts.checkWantedLockfileOnly,
+        onlyProjects: maybeOpts.onlyProjects,
+        registries,
+        search: maybeOpts.search,
+        showDedupedSearchMatches: maybeOpts.showDedupedSearchMatches ?? (maybeOpts.search != null),
+        skipped: new Set(modules?.skipped ?? []),
+        storeDir,
+        storeIndex,
+        modulesDir,
+        virtualStoreDir: modules?.virtualStoreDir,
+        virtualStoreDirMaxLength: modules?.virtualStoreDirMaxLength ?? maybeOpts.virtualStoreDirMaxLength,
+    };
+    // Build the dependency graph ONCE for all importers and share a single
+    // MaterializationCache so that identical subtrees are only materialized once.
+    const allRootIds = [];
+    for (const projectPath of projectPaths) {
+        const importerId = getLockfileImporterId(opts.lockfileDir, projectPath);
+        if (lockfileToUse.importers[importerId]) {
+            allRootIds.push({ type: 'importer', importerId });
+        }
+    }
+    const sharedGraph = buildDependencyGraph(allRootIds, {
+        currentPackages: lockfileToUse.packages ?? {},
+        importers: lockfileToUse.importers,
+        include: opts.include,
+        lockfileDir: opts.lockfileDir,
+        onlyProjects: opts.onlyProjects,
+    });
+    const sharedMaterializationCache = new Map();
+    const sharedDepTypes = detectDepTypes(lockfileToUse);
+    const ctx = {
+        currentLockfile: lockfileToUse,
+        wantedLockfile,
+        ...opts,
+        graph: sharedGraph,
+        materializationCache: sharedMaterializationCache,
+        depTypes: sharedDepTypes,
+    };
+    const getHierarchy = dependenciesHierarchyForPackage.bind(null, ctx);
+    const pairs = await Promise.all(projectPaths.map(async (projectPath) => {
+        return [
+            projectPath,
+            await getHierarchy(projectPath),
+        ];
+    }));
+    for (const [projectPath, dependenciesHierarchy] of pairs) {
+        result[projectPath] = dependenciesHierarchy;
+    }
+    storeIndex?.close();
+    return result;
+}
+async function dependenciesHierarchyForPackage(opts, projectPath) {
+    const { currentLockfile, wantedLockfile } = opts;
+    const importerId = getLockfileImporterId(opts.lockfileDir, projectPath);
+    if (!currentLockfile.importers[importerId])
+        return {};
+    const modulesDir = opts.modulesDir && path.isAbsolute(opts.modulesDir)
+        ? opts.modulesDir
+        : path.join(projectPath, opts.modulesDir ?? 'node_modules');
+    const currentPackages = currentLockfile.packages ?? {};
+    const wantedPackages = wantedLockfile?.packages ?? {};
+    // Build a map from alias → dependency field for post-categorization.
+    const result = {};
+    const fieldMap = new Map();
+    for (const field of DEPENDENCIES_FIELDS.sort().filter(f => opts.include[f])) {
+        result[field] = [];
+        const fieldDeps = currentLockfile.importers[importerId][field] ?? {};
+        for (const alias in fieldDeps) {
+            fieldMap.set(alias, field);
+        }
+    }
+    const parentId = { type: 'importer', importerId };
+    // Materialize the tree rooted at this importer in a single getTree call.
+    // materializeChildren handles all dedup, search, and circular detection.
+    // The depth is incremented by 1 because the importer itself is one level;
+    // opts.depth controls how deep *below* the direct dependencies we go.
+    const nodes = getTree({
+        ...opts,
+        currentPackages,
+        importers: currentLockfile.importers,
+        rewriteLinkVersionDir: projectPath,
+        maxDepth: opts.depth + 1,
+        wantedPackages,
+        modulesDir,
+    }, parentId);
+    // Categorize the materialized nodes into their dependency fields.
+    for (const node of nodes) {
+        const field = fieldMap.get(node.alias);
+        if (field != null) {
+            result[field].push(node);
+        }
+    }
+    // Handle unsaved dependencies (packages in node_modules but not in lockfile).
+    // When searching, unsaved deps are irrelevant — they aren't in the lockfile
+    // graph and can't have dependency subtrees showing paths to the search target.
+    if (!opts.search) {
+        const savedDeps = getAllDirectDependencies(currentLockfile.importers[importerId]);
+        const unsavedDeps = ((await readModulesDir(modulesDir)) ?? []).filter((directDep) => !savedDeps[directDep]);
+        if (unsavedDeps.length > 0)
+            await Promise.all(unsavedDeps.map(async (unsavedDep) => {
+                let pkgPath = path.join(modulesDir, unsavedDep);
+                let version;
+                try {
+                    pkgPath = await resolveLinkTarget(pkgPath);
+                    version = `link:${normalizePath(path.relative(projectPath, pkgPath))}`;
+                }
+                catch {
+                    // if error happened. The package is not a link
+                    const pkg = await safeReadPackageJsonFromDir(pkgPath);
+                    version = pkg?.version ?? 'undefined';
+                }
+                const pkg = {
+                    alias: unsavedDep,
+                    isMissing: false,
+                    isPeer: false,
+                    isSkipped: false,
+                    name: unsavedDep,
+                    path: pkgPath,
+                    version,
+                };
+                result.unsavedDependencies = result.unsavedDependencies ?? [];
+                result.unsavedDependencies.push(pkg);
+            }));
+    }
+    return result;
+}
+function getAllDirectDependencies(projectSnapshot) {
+    return {
+        ...projectSnapshot.dependencies,
+        ...projectSnapshot.devDependencies,
+        ...projectSnapshot.optionalDependencies,
+    };
+}
+//# sourceMappingURL=buildDependenciesTree.js.map

package/lib/buildDependencyGraph.d.ts

@@ -0,0 +1,30 @@
+import type { PackageSnapshots, ProjectSnapshot } from '@pnpm/lockfile.fs';
+import { type TreeNodeId } from './TreeNodeId.js';
+interface DependencyEdge {
+    alias: string;
+    ref: string;
+    target?: {
+        id: string;
+        nodeId: TreeNodeId;
+    };
+}
+interface DependencyGraphNode {
+    nodeId: TreeNodeId;
+    edges: DependencyEdge[];
+    peers: Set<string>;
+}
+export interface DependencyGraph {
+    nodes: Map<string, DependencyGraphNode>;
+}
+export declare function buildDependencyGraph(rootIds: TreeNodeId[], opts: {
+    currentPackages: PackageSnapshots;
+    importers: Record<string, ProjectSnapshot>;
+    include: {
+        dependencies?: boolean;
+        devDependencies?: boolean;
+        optionalDependencies?: boolean;
+    };
+    lockfileDir: string;
+    onlyProjects?: boolean;
+}): DependencyGraph;
+export {};

package/lib/buildDependencyGraph.js

@@ -0,0 +1,77 @@
+import { getTreeNodeChildId } from './getTreeNodeChildId.js';
+import { serializeTreeNodeId } from './TreeNodeId.js';
+export function buildDependencyGraph(rootIds, opts) {
+    const graph = { nodes: new Map() };
+    const queue = [...rootIds];
+    let queueIdx = 0;
+    const visited = new Set();
+    while (queueIdx < queue.length) {
+        const nodeId = queue[queueIdx++];
+        const serialized = serializeTreeNodeId(nodeId);
+        if (visited.has(serialized))
+            continue;
+        visited.add(serialized);
+        const snapshot = getSnapshot(nodeId, opts);
+        if (!snapshot) {
+            graph.nodes.set(serialized, { nodeId, edges: [], peers: new Set() });
+            continue;
+        }
+        // For importers, only include the dependency fields the caller selected.
+        // For packages, devDependencies don't exist in the lockfile.
+        const deps = nodeId.type === 'importer'
+            ? {
+                ...(opts.include.dependencies !== false ? snapshot.dependencies : undefined),
+                ...(opts.include.devDependencies !== false ? snapshot.devDependencies : undefined),
+                ...(opts.include.optionalDependencies ? snapshot.optionalDependencies : undefined),
+            }
+            : !opts.include.optionalDependencies
+                ? snapshot.dependencies
+                : {
+                    ...snapshot.dependencies,
+                    ...snapshot.optionalDependencies,
+                };
+        const peers = new Set(Object.keys(nodeId.type === 'package'
+            ? (opts.currentPackages[nodeId.depPath]?.peerDependencies ?? {})
+            : {}));
+        const edges = [];
+        if (deps != null) {
+            for (const alias in deps) {
+                const rawRef = deps[alias];
+                // Lockfile may expose ref as string (version) or inline { version, specifier }
+                const ref = typeof rawRef === 'string'
+                    ? rawRef
+                    : rawRef?.version;
+                if (ref == null)
+                    continue;
+                const targetNodeId = getTreeNodeChildId({
+                    parentId: nodeId,
+                    dep: { alias, ref },
+                    lockfileDir: opts.lockfileDir,
+                    importers: opts.importers,
+                });
+                // When onlyProjects is true, only follow edges to workspace importers
+                if (opts.onlyProjects && targetNodeId?.type !== 'importer') {
+                    continue;
+                }
+                const target = targetNodeId != null
+                    ? { id: serializeTreeNodeId(targetNodeId), nodeId: targetNodeId }
+                    : undefined;
+                edges.push({ alias, ref, target });
+                if (target && !visited.has(target.id)) {
+                    queue.push(target.nodeId);
+                }
+            }
+        }
+        graph.nodes.set(serialized, { nodeId, edges, peers });
+    }
+    return graph;
+}
+function getSnapshot(treeNodeId, opts) {
+    switch (treeNodeId.type) {
+        case 'importer':
+            return opts.importers[treeNodeId.importerId];
+        case 'package':
+            return opts.currentPackages[treeNodeId.depPath];
+    }
+}
+//# sourceMappingURL=buildDependencyGraph.js.map

package/lib/buildDependentsTree.d.ts

@@ -0,0 +1,46 @@
+import { type LockfileObject } from '@pnpm/lockfile.fs';
+import type { DependenciesField, DependencyManifest, Finder, Registries } from '@pnpm/types';
+export interface DependentNode {
+    name: string;
+    displayName?: string;
+    version: string;
+    dependents?: DependentNode[];
+    circular?: true;
+    deduped?: true;
+    /** Short hash distinguishing peer-dep variants of the same name@version */
+    peersSuffixHash?: string;
+    /** For importer leaf nodes: which dep field */
+    depField?: DependenciesField;
+}
+export interface DependentsTree {
+    name: string;
+    displayName?: string;
+    version: string;
+    /** Resolved filesystem path to this package */
+    path?: string;
+    /** Short hash distinguishing peer-dep variants of the same name@version */
+    peersSuffixHash?: string;
+    /** Message returned by the finder function, if any */
+    searchMessage?: string;
+    dependents: DependentNode[];
+}
+export interface ImporterInfo {
+    name: string;
+    version: string;
+}
+export declare function buildDependentsTree(packages: string[], projectPaths: string[], opts: {
+    lockfileDir: string;
+    include?: {
+        [field in DependenciesField]?: boolean;
+    };
+    modulesDir?: string;
+    registries?: Registries;
+    finders?: Finder[];
+    importerInfoMap: Map<string, ImporterInfo>;
+    lockfile: LockfileObject;
+    nameFormatter?: (info: {
+        name: string;
+        version: string;
+        manifest: DependencyManifest;
+    }) => string | undefined;
+}): Promise<DependentsTree[]>;