@vltpkg/graph 1.0.0-rc.23 → 1.0.0-rc.25

package/dist/visualization/human-readable-output.js

@@ -0,0 +1,163 @@
+import { defaultRegistryName } from '@vltpkg/spec';
+import { splitDepID } from '@vltpkg/dep-id';
+import { styleText as utilStyleText } from 'node:util';
+const styleText = (format, s) => utilStyleText(format, s, { validateStream: false });
+const chars = new Map(Object.entries({
+    connection: '─',
+    down: '│',
+    'last-child': '└',
+    'middle-child': '├',
+    t: '┬',
+}));
+const isSelected = (options, edge, node) => (!node || options.nodes.includes(node)) &&
+    (!edge || options.edges.includes(edge));
+/**
+ * Returns a map of tree items to be printed.
+ */
+const getTreeItems = (initialItems, options) => {
+    const seenNodes = new Set();
+    const treeItems = new Map();
+    const traverse = new Set(initialItems);
+    for (const item of traverse) {
+        if (item.node) {
+            if (seenNodes.has(item.node)) {
+                item.seen = true;
+                continue;
+            }
+            seenNodes.add(item.node);
+            const edges = [...item.node.edgesOut.values()];
+            const workspaces = item.node.workspaces ? [...item.node.workspaces.values()] : [];
+            const allEdges = [...edges, ...workspaces].sort((a, b) => a.name.localeCompare(b.name, 'en'));
+            // keeps track of seen edge names to avoid duplicating printed
+            // items when a workspace is also a regular dependency of the root
+            const seenEdgeName = new Set();
+            for (const edge of allEdges) {
+                if (seenEdgeName.has(edge.name)) {
+                    continue;
+                }
+                seenEdgeName.add(edge.name);
+                const toItems = treeItems.get(edge) ?? new Map();
+                const nextItem = {
+                    edge,
+                    node: edge.to,
+                    hasSibling: false,
+                    padding: '',
+                    prefix: '',
+                    seen: false,
+                    include: isSelected(options, edge, edge.to),
+                    parent: item,
+                };
+                toItems.set(edge.to, nextItem);
+                treeItems.set(edge, toItems);
+                traverse.add(nextItem);
+            }
+        }
+    }
+    for (const item of [...traverse].reverse()) {
+        if (item.include && item.parent) {
+            item.parent.include = true;
+        }
+    }
+    return treeItems;
+};
+/**
+ * Returns a human-readable output of the graph.
+ */
+export function humanReadableOutput(options, { colors }) {
+    const { importers } = options;
+    const createStyleText = (style) => (s) => colors ? styleText(style, s) : s;
+    const dim = createStyleText('dim');
+    const red = createStyleText('red');
+    const reset = createStyleText('reset');
+    const yellow = createStyleText('yellow');
+    const initialItems = new Set();
+    for (const importer of importers) {
+        initialItems.add({
+            name: importer.name,
+            edge: undefined,
+            node: importer,
+            prefix: '',
+            padding: '',
+            hasSibling: false,
+            seen: false,
+            include: isSelected(options, undefined, importer),
+            parent: undefined,
+        });
+    }
+    const treeItems = getTreeItems(initialItems, options);
+    let res = '';
+    const traverse = (item) => {
+        let header = '';
+        let content = '';
+        const name = item.name;
+        const decoratedName = (options.highlightSelection &&
+            isSelected(options, item.edge, item.node) &&
+            name) ?
+            yellow(name)
+            : name;
+        if (!item.node && item.include) {
+            const missing = item.edge?.type.endsWith('ptional') ?
+                dim('(missing optional)')
+                : red('(missing)');
+            return `${item.padding}${item.prefix}${decoratedName} ${missing}\n`;
+        }
+        header += `${item.padding}${item.prefix}${decoratedName}\n`;
+        // seen items need not to be printed or traversed
+        if (!item.seen) {
+            const edges = item.node ? [...item.node.edgesOut.values()] : [];
+            const workspaces = item.node?.workspaces ?
+                [...item.node.workspaces.values()]
+                : [];
+            const allEdges = [...edges, ...workspaces].sort((a, b) => a.name.localeCompare(b.name, 'en'));
+            const nextItems = allEdges.map(i => treeItems.get(i)?.get(i.to));
+            const includedItems = nextItems.filter(i => i?.include);
+            for (const nextItem of nextItems) {
+                /* c8 ignore next -- impossible but TS doesn't know that */
+                if (!nextItem)
+                    continue;
+                const parent = item;
+                const isLast = includedItems.indexOf(nextItem) === includedItems.length - 1;
+                // prefixes the node name with the registry name
+                // if a custom registry name is found
+                const depIdTuple = nextItem.node?.id && splitDepID(nextItem.node.id);
+                const hasCustomReg = depIdTuple?.[0] === 'registry' &&
+                    depIdTuple[1] &&
+                    depIdTuple[1] !== defaultRegistryName;
+                const nodeName = hasCustomReg ?
+                    `${depIdTuple[1]}:${nextItem.node?.name}`
+                    : nextItem.node?.name;
+                const toName = nextItem.node?.version ?
+                    `${nodeName}@${nextItem.node.version}`
+                    : nodeName;
+                const nextChar = isLast ? 'last-child' : 'middle-child';
+                const aliasedPackage = hasCustomReg ||
+                    (nextItem.node?.name &&
+                        nextItem.edge?.name !== nextItem.node.name);
+                nextItem.name =
+                    nextItem.node?.confused ?
+                        `${nextItem.edge?.name} ${red('(confused)')}`
+                        : nextItem.edge?.spec.overridden ?
+                            /* c8 ignore next */
+                            `${nextItem.edge.name}@${nextItem.node?.version || nextItem.edge.spec.bareSpec}${aliasedPackage ? ` (${toName})` : ''} ${yellow('(overridden)')}`
+                            : aliasedPackage ? `${nextItem.edge?.name} (${toName})`
+                                : `${nextItem.edge?.name}@${nextItem.node?.version || nextItem.edge?.spec.bareSpec}`;
+                nextItem.padding =
+                    parent.prefix.length ?
+                        `${parent.padding}${parent.hasSibling ? chars.get('down') : ' '} `
+                        : '';
+                nextItem.prefix = `${chars.get(nextChar)}${chars.get('connection')}${chars.get('connection')} `;
+                nextItem.hasSibling = !isLast;
+                content += traverse(nextItem);
+            }
+        }
+        const regularConnection = `${chars.get('connection')} `;
+        const parentConnection = `${chars.get('t')} `;
+        return item.include ?
+            `${content ? header.replace(regularConnection, parentConnection) : header}${content}`
+            : '';
+    };
+    for (const item of initialItems) {
+        res += traverse(item);
+    }
+    return reset(res);
+}

package/dist/visualization/json-output.d.ts

@@ -0,0 +1,41 @@
+import type { DepID } from '@vltpkg/dep-id';
+import type { EdgeLike, NodeLike } from '@vltpkg/types';
+/**
+ * A JSON output item describes a package that is present in the install
+ * graph. It represents an edge plus it's linking Node.
+ */
+export type JSONOutputItem = {
+    /**
+     * The name of the package.
+     */
+    name: string;
+    /**
+     * A reference to the id of the Node that this package is linked from.
+     */
+    fromID?: DepID;
+    /**
+     * The dependency spec definition for this package.
+     */
+    spec?: string;
+    /**
+     * The package type.
+     */
+    type?: EdgeLike['type'];
+    /**
+     * A representation of the package object that fulfills this dependency.
+     */
+    to?: NodeLike;
+    /**
+     * Whether this edge was overridden by a graph modifier.
+     */
+    overridden: boolean;
+};
+export type JSONOutputGraph = {
+    edges: EdgeLike[];
+    nodes: NodeLike[];
+    importers: Set<NodeLike>;
+};
+/**
+ * Returns a JSON string representation of the graph.
+ */
+export declare function jsonOutput({ edges, nodes, importers, }: JSONOutputGraph): JSONOutputItem[];

package/dist/visualization/json-output.js

@@ -0,0 +1,50 @@
+/**
+ * Returns a JSON string representation of the graph.
+ */
+export function jsonOutput({ edges, nodes, importers, }) {
+    const res = [];
+    const seenIds = new Set();
+    // Collects edge & it's linked nodes as json output items
+    const orderedEdges = [...edges].sort((a, b) => {
+        const aIsWorkspace = a.spec.type === 'workspace';
+        const bIsWorkspace = b.spec.type === 'workspace';
+        if (aIsWorkspace && !bIsWorkspace)
+            return -1;
+        /* c8 ignore next */
+        if (!aIsWorkspace && bIsWorkspace)
+            return 1;
+        return 0; // preserve original order otherwise
+    });
+    for (const edge of orderedEdges) {
+        if (edge.to)
+            seenIds.add(edge.to.id);
+        res.push({
+            name: edge.name,
+            fromID: edge.from.id,
+            spec: String(edge.spec),
+            type: edge.type,
+            to: edge.to,
+            overridden: edge.spec.overridden,
+        });
+    }
+    // Collects included importer nodes json output items
+    /* c8 ignore next 3 */
+    const orderedImporters = [...importers].sort((a, b) => {
+        if (!a.name)
+            return 1;
+        if (!b.name)
+            return -1;
+        return a.name.localeCompare(b.name);
+    });
+    for (const node of orderedImporters) {
+        if (!nodes.includes(node) || seenIds.has(node.id))
+            continue;
+        res.unshift({
+            /* c8 ignore next - name can't be missing but ts won't know */
+            name: node.name || node.id,
+            to: node,
+            overridden: false,
+        });
+    }
+    return res;
+}

package/dist/visualization/mermaid-output.d.ts

@@ -0,0 +1,17 @@
+import type { EdgeLike, NodeLike } from '@vltpkg/types';
+export type MermaidOutputGraph = {
+    edges: EdgeLike[];
+    importers: Set<NodeLike>;
+    nodes: NodeLike[];
+    highlightSelection?: boolean;
+};
+/**
+ * Generates a short identifier for a given index following the pattern:
+ * 0 -> a, 1 -> b, ..., 25 -> z, 26 -> A, ..., 51 -> Z, 52 -> aa, 53 -> ab, etc.
+ * This implements a bijective base-52 numbering system where a-z = 0-25, A-Z = 26-51
+ */
+export declare function generateShortId(index: number): string;
+/**
+ * Returns a mermaid string representation of the graph.
+ */
+export declare function mermaidOutput(options: MermaidOutputGraph): string;

package/dist/visualization/mermaid-output.js

@@ -0,0 +1,170 @@
+import { Edge } from "../edge.js";
+import { Node } from "../node.js";
+let missingCount = 0;
+const isSelected = (options, edge, node) => (!node || options.nodes.includes(node)) &&
+    /* c8 ignore next */ (!edge || options.edges.includes(edge));
+/**
+ * Generates a short identifier for a given index following the pattern:
+ * 0 -> a, 1 -> b, ..., 25 -> z, 26 -> A, ..., 51 -> Z, 52 -> aa, 53 -> ab, etc.
+ * This implements a bijective base-52 numbering system where a-z = 0-25, A-Z = 26-51
+ */
+export function generateShortId(index) {
+    const base = 52;
+    // Helper function to convert a digit (0-51) to character
+    const digitToChar = (digit) => {
+        if (digit < 26) {
+            // a-z (0-25)
+            return String.fromCharCode(97 + digit);
+        }
+        else {
+            // A-Z (26-51)
+            return String.fromCharCode(65 + (digit - 26));
+        }
+    };
+    // Bijective base-52 conversion
+    let result = '';
+    let num = index + 1; // Convert to 1-based for bijective base
+    while (num > 0) {
+        num--; // Adjust for 0-based indexing in each position
+        const remainder = num % base;
+        result = digitToChar(remainder) + result;
+        num = Math.floor(num / base);
+    }
+    return result;
+}
+/**
+ * Creates a mapping from DepID to short identifier
+ */
+function createDepIdMapping(importers) {
+    const mapping = new Map();
+    const uniqueDepIds = new Set();
+    // Collect all unique DepIDs from nodes & importers
+    const [importer] = importers;
+    if (importer) {
+        for (const node of importer.graph.nodes.values()) {
+            uniqueDepIds.add(node.id);
+        }
+    }
+    // Create mapping for each unique DepID
+    let index = 0;
+    for (const depId of uniqueDepIds) {
+        mapping.set(depId, generateShortId(index++));
+    }
+    return mapping;
+}
+/**
+ * Returns a node reference: on the first occurrence of a node, returns the full label;
+ * on subsequent occurrences, returns just the shortId.
+ *
+ * Note: Mutates the `labeledNodes` set as a side effect to track which nodes have already
+ * been labeled. This tracking is shared across multiple importers to prevent duplicate
+ * labels in the output.
+ */
+const nodeRef = (node, labeledNodes, depIdMapping, options) => {
+    const shortId = depIdMapping.get(node.id) /* c8 ignore next - should not be possible */ ?? '';
+    const selectedClass = (options.highlightSelection &&
+        isSelected(options, undefined, node)) ?
+        ':::a'
+        : '';
+    if (labeledNodes.has(node.id)) {
+        return shortId + selectedClass;
+    }
+    labeledNodes.add(node.id);
+    return `${shortId}("${String(node).replaceAll('@', '#64;')}")${selectedClass}`;
+};
+function parseNode(seenNodes, labeledNodes, includedItems, depIdMapping, options, node, isImporter = false) {
+    if (seenNodes.has(node.id) || !includedItems.get(node)) {
+        return '';
+    }
+    seenNodes.add(node.id);
+    // For importers, render the node label first as a standalone line before processing edges,
+    // since they appear at the top of the graph. Non-importer nodes are labeled inline as part of edge definitions.
+    const nodeLabel = isImporter ?
+        nodeRef(node, labeledNodes, depIdMapping, options)
+        : '';
+    // Include both regular edges and workspace edges (if any)
+    const allEdges = [
+        ...node.edgesOut.values(),
+        ...(node.workspaces?.values() ?? []),
+    ];
+    const edges = allEdges
+        .map(e => parseEdge(seenNodes, labeledNodes, includedItems, depIdMapping, options, e))
+        .filter(Boolean)
+        .join('\n');
+    // Only render node standalone for importers, others are rendered as part of edges
+    if (isImporter) {
+        /* c8 ignore next */
+        return `${nodeLabel}${edges.length ? '\n' : ''}${edges}`;
+    }
+    return edges;
+}
+function parseEdge(seenNodes, labeledNodes, includedItems, depIdMapping, options, edge) {
+    if (!includedItems.get(edge)) {
+        return '';
+    }
+    const edgeType = edge.type === 'prod' ? '' : ` (${edge.type})`;
+    const edgeResult = nodeRef(edge.from, labeledNodes, depIdMapping, options) +
+        ` -->|"${String(edge.spec).replaceAll('@', '#64;')}${edgeType}"| `;
+    const missingLabel = edge.type.endsWith('ptional') ? 'Missing Optional' : 'Missing';
+    if (!edge.to) {
+        return edgeResult + `missing-${missingCount++}(${missingLabel})`;
+    }
+    // Label the target node first so that if it's referenced again later in the graph,
+    // it will use the short identifier instead of repeating the full label.
+    const toRef = nodeRef(edge.to, labeledNodes, depIdMapping, options);
+    const childEdges = parseNode(seenNodes, labeledNodes, includedItems, depIdMapping, options, edge.to);
+    return edgeResult + toRef + (childEdges ? '\n' + childEdges : '');
+}
+/**
+ * Returns a mermaid string representation of the graph.
+ */
+export function mermaidOutput(options) {
+    const { edges, importers, nodes, highlightSelection } = options;
+    const seen = new Set();
+    const includedItems = new Map();
+    const traverse = new Set([...importers].map(i => ({ self: i, parent: undefined })));
+    for (const item of traverse) {
+        if (seen.has(item.self))
+            continue;
+        seen.add(item.self);
+        if (item.self instanceof Edge) {
+            if (edges.includes(item.self)) {
+                includedItems.set(item.self, true);
+            }
+            if (item.self.to) {
+                traverse.add({ self: item.self.to, parent: item.self });
+            }
+        }
+        if (item.self instanceof Node) {
+            if (nodes.includes(item.self)) {
+                includedItems.set(item.self, true);
+            }
+            for (const edge of item.self.edgesOut.values()) {
+                traverse.add({ self: edge, parent: item.self });
+            }
+            // Also traverse workspace edges (only mainImporter has these)
+            if (item.self.workspaces) {
+                for (const edge of item.self.workspaces.values()) {
+                    traverse.add({ self: edge, parent: item.self });
+                }
+            }
+        }
+    }
+    for (const item of [...traverse].reverse()) {
+        if (includedItems.has(item.self) && item.parent) {
+            includedItems.set(item.parent, true);
+        }
+    }
+    // Create DepID to short identifier mapping
+    const depIdMapping = createDepIdMapping(importers);
+    // Track nodes that have had their label printed (shared across all importers)
+    const labeledNodes = new Set();
+    // Track nodes that have been processed (shared across all importers to avoid duplicates)
+    const seenNodes = new Set();
+    const graphOutput = [...importers]
+        .map(i => parseNode(seenNodes, labeledNodes, includedItems, depIdMapping, options, i, true))
+        .filter(Boolean)
+        .join('\n');
+    const styleDefinition = highlightSelection ? '\nclassDef a fill:gold,color:#242424' : '';
+    return 'flowchart TD\n' + graphOutput + styleDefinition;
+}

package/dist/visualization/object-like-output.d.ts

@@ -0,0 +1,2 @@
+import type { GraphLike } from '@vltpkg/types';
+export declare function objectLikeOutput(graph: GraphLike): string;

package/dist/visualization/object-like-output.js

@@ -0,0 +1,47 @@
+import { inspect } from 'node:util';
+const addInspect = (o, fn) => (o[inspect.custom] = fn);
+function parseNode(seenNodes, graph, node) {
+    addInspect(node, () => {
+        const res = 'Node ' +
+            inspect(seenNodes.has(node) ?
+                { ref: node.id }
+                : {
+                    id: node.id,
+                    location: node.location,
+                    ...(node.importer ? { importer: true } : null),
+                    ...(node.dev ? { dev: true } : null),
+                    ...(node.optional ? { optional: true } : null),
+                    ...(node.resolved ? { resolved: node.resolved } : null),
+                    ...(node.integrity ?
+                        { integrity: node.integrity }
+                        : null),
+                    ...(node.edgesOut.size ?
+                        {
+                            edgesOut: [...node.edgesOut.values()].map(i => {
+                                seenNodes.add(node);
+                                return parseEdge(seenNodes, graph, i);
+                            }),
+                        }
+                        : (seenNodes.add(node), null)),
+                }, { depth: Infinity });
+        return res;
+    });
+    return node;
+}
+function parseEdge(seenNodes, graph, edge) {
+    addInspect(edge, () => {
+        const missingNode = `[missing package]: <${edge.name}@${edge.spec.bareSpec}>`;
+        const toLabel = edge.to ?
+            inspect(parseNode(seenNodes, graph, edge.to), {
+                depth: Infinity,
+            })
+            : missingNode;
+        return `Edge spec(${String(edge.spec)}) -${edge.type}-> to: ${toLabel}`;
+    });
+    return edge;
+}
+export function objectLikeOutput(graph) {
+    const seenNodes = new Set();
+    const importers = [...graph.importers];
+    return inspect(importers.map(i => parseNode(seenNodes, graph, i)), { depth: Infinity });
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@vltpkg/graph",
   "description": "A library that helps understanding & expressing what happens on an install",
-  "version": "1.0.0-rc.23",
+  "version": "1.0.0-rc.25",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/vltpkg/vltpkg.git",
@@ -12,33 +12,33 @@
     "email": "support@vlt.sh"
   },
   "dependencies": {
-    "@vltpkg/cmd-shim": "1.0.0-rc.23",
-    "@vltpkg/dep-id": "1.0.0-rc.23",
-    "@vltpkg/dss-breadcrumb": "1.0.0-rc.23",
-    "@vltpkg/error-cause": "1.0.0-rc.23",
-    "@vltpkg/fast-split": "1.0.0-rc.23",
-    "@vltpkg/graph-run": "1.0.0-rc.23",
-    "@vltpkg/init": "1.0.0-rc.23",
-    "@vltpkg/output": "1.0.0-rc.23",
-    "@vltpkg/package-info": "1.0.0-rc.23",
-    "@vltpkg/package-json": "1.0.0-rc.23",
-    "@vltpkg/pick-manifest": "1.0.0-rc.23",
-    "@vltpkg/query": "1.0.0-rc.23",
-    "@vltpkg/rollback-remove": "1.0.0-rc.23",
-    "@vltpkg/run": "1.0.0-rc.23",
-    "@vltpkg/satisfies": "1.0.0-rc.23",
-    "@vltpkg/security-archive": "1.0.0-rc.23",
-    "@vltpkg/spec": "1.0.0-rc.23",
-    "@vltpkg/types": "1.0.0-rc.23",
-    "@vltpkg/vlt-json": "1.0.0-rc.23",
-    "@vltpkg/workspaces": "1.0.0-rc.23",
+    "@vltpkg/cmd-shim": "1.0.0-rc.25",
+    "@vltpkg/dep-id": "1.0.0-rc.25",
+    "@vltpkg/dss-breadcrumb": "1.0.0-rc.25",
+    "@vltpkg/error-cause": "1.0.0-rc.25",
+    "@vltpkg/fast-split": "1.0.0-rc.25",
+    "@vltpkg/graph-run": "1.0.0-rc.25",
+    "@vltpkg/init": "1.0.0-rc.25",
+    "@vltpkg/output": "1.0.0-rc.25",
+    "@vltpkg/package-info": "1.0.0-rc.25",
+    "@vltpkg/package-json": "1.0.0-rc.25",
+    "@vltpkg/pick-manifest": "1.0.0-rc.25",
+    "@vltpkg/query": "1.0.0-rc.25",
+    "@vltpkg/rollback-remove": "1.0.0-rc.25",
+    "@vltpkg/run": "1.0.0-rc.25",
+    "@vltpkg/satisfies": "1.0.0-rc.25",
+    "@vltpkg/security-archive": "1.0.0-rc.25",
+    "@vltpkg/spec": "1.0.0-rc.25",
+    "@vltpkg/types": "1.0.0-rc.25",
+    "@vltpkg/vlt-json": "1.0.0-rc.25",
+    "@vltpkg/workspaces": "1.0.0-rc.25",
     "path-scurry": "^2.0.1",
     "promise-call-limit": "^3.0.2"
   },
   "devDependencies": {
     "@eslint/js": "^9.39.1",
     "@types/node": "^22.19.2",
-    "@vltpkg/vlt-json": "1.0.0-rc.23",
+    "@vltpkg/vlt-json": "1.0.0-rc.25",
     "eslint": "^9.39.1",
     "prettier": "^3.7.4",
     "tap": "^21.5.0",