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

package/dist/dependencies.js

@@ -0,0 +1,111 @@
+import { error } from '@vltpkg/error-cause';
+import { Spec } from '@vltpkg/spec/browser';
+import { dependencyTypes, longDependencyTypes, shortDependencyTypes, } from '@vltpkg/types';
+export const isDependencyTypeShort = (obj) => shortDependencyTypes.has(obj);
+export const isDependencySaveType = (obj) => shortDependencyTypes.has(obj) ||
+    obj === 'implicit';
+export const asDependencyTypeShort = (obj) => {
+    if (!isDependencyTypeShort(obj)) {
+        throw error('Invalid dependency type', {
+            found: obj,
+            validOptions: [...shortDependencyTypes],
+        });
+    }
+    return obj;
+};
+const isObj = (o) => !!o && typeof o === 'object';
+// TODO: it would be nice to have a @vltpkg/spec.isSpec method
+export const isDependency = (o) => 
+// TODO: it would be nice to have a @vltpkg/spec.isSpec method
+isObj(o) &&
+    isObj(o.spec) &&
+    !!o.spec.type &&
+    isDependencySaveType(o.type);
+export const asDependency = (obj) => {
+    if (!isDependency(obj)) {
+        throw error('Invalid dependency', { found: obj });
+    }
+    return obj;
+};
+/**
+ * Get the {@link DependencyTypeShort} from a {@link DependencyTypeLong}.
+ */
+export const shorten = (typeLong, name, manifest) => {
+    const shortName = dependencyTypes.get(typeLong);
+    if (!shortName) {
+        throw error('Invalid dependency type name', {
+            found: typeLong,
+            validOptions: [...longDependencyTypes],
+        });
+    }
+    if (shortName !== 'peer') {
+        return shortName;
+    }
+    if (name &&
+        manifest?.peerDependenciesMeta?.[name]?.optional === true) {
+        return 'peerOptional';
+    }
+    return 'peer';
+};
+const isStringArray = (a) => Array.isArray(a) && !a.some(b => typeof b !== 'string');
+/*
+ * Retrieves a map of all dependencies, of all types, that can be iterated
+ * on and consulted when parsing the directory contents of a given node.
+ */
+export const getRawDependencies = (node) => {
+    const dependencies = new Map();
+    const bundleDeps = node.manifest?.bundleDependencies ?? [];
+    // if it's an importer, bundleDeps are just normal. if it's a dep,
+    // then they're ignored entirely.
+    const bundled = (!node.importer &&
+        !node.id.startsWith('git') &&
+        isStringArray(bundleDeps)) ?
+        new Set(bundleDeps)
+        : new Set();
+    for (const depType of longDependencyTypes) {
+        const obj = node.manifest?.[depType];
+        // only care about devDeps for importers and git or symlink deps
+        // technically this will also include devDeps for tarball file: specs,
+        // but that is likely rare enough to not worry about too much.
+        if (depType === 'devDependencies' &&
+            !node.importer &&
+            !node.id.startsWith('git') &&
+            !node.id.startsWith('file')) {
+            continue;
+        }
+        if (obj) {
+            for (const [name, bareSpec] of Object.entries(obj)) {
+                // if it's a bundled dependency, we just ignore it entirely.
+                if (bundled.has(name))
+                    continue;
+                dependencies.set(name, {
+                    name,
+                    type: depType,
+                    bareSpec,
+                    registry: node.registry,
+                });
+            }
+        }
+    }
+    return dependencies;
+};
+/**
+ * Retrieves a map of all dependencies, of all types, that can be inferred
+ * from a given node manifest, including missing dependencies.
+ */
+export const getDependencies = (node, options) => {
+    const res = new Map();
+    const dependencies = getRawDependencies(node);
+    for (const { name, type, bareSpec } of dependencies.values()) {
+        const depType = shorten(type, name, node.manifest);
+        const spec = Spec.parse(name, bareSpec, {
+            ...options,
+            registry: node.registry,
+        });
+        res.set(name, {
+            spec,
+            type: depType,
+        });
+    }
+    return res;
+};

package/dist/diff.d.ts

@@ -0,0 +1,119 @@
+import type { InspectOptions } from 'node:util';
+import type { Edge } from './edge.ts';
+import type { Graph } from './graph.ts';
+import type { Node } from './node.ts';
+declare const kCustomInspect: unique symbol;
+/**
+ * A Diff object is a representation of a set of changes from one
+ * graph to another, typically from the actual graph as it is reified
+ * on disk, to an intended ideal graph.
+ *
+ * The naming convention can get a bit confusing here, because it's a
+ * set of directed changes from one set of directed objects to another.
+ *
+ * Within the context the Diff object, `from` is the Graph we're coming from,
+ * and `to` is the Graph we're trying to create.
+ */
+export declare class Diff {
+    from: Graph;
+    to: Graph;
+    projectRoot: string;
+    /**
+     * If changes need to be made later for failures of optional nodes,
+     * set this flag so that we know to call graph.gc() at the appropriate time.
+     */
+    hadOptionalFailures: boolean;
+    /**
+     * Collection of nodes to add and delete
+     */
+    nodes: {
+        /** Nodes in the `to` graph that are not in the `from` graph */
+        add: Set<Node>;
+        /** Nodes in the `from` graph that are not in the `to` graph */
+        delete: Set<Node>;
+    };
+    /**
+     * Collection of nodes to add and delete
+     */
+    edges: {
+        /** Edges in the `to` graph that are not found in the `from` graph */
+        add: Set<Edge>;
+        /** Edges in the `from` graph that are not found in the `to` graph */
+        delete: Set<Edge>;
+    };
+    /**
+     * True if the diff only contains optional nodes (computed during construction)
+     */
+    optionalOnly: boolean;
+    get [Symbol.toStringTag](): string;
+    constructor(from: Graph, to: Graph);
+    [kCustomInspect](_: number, options?: InspectOptions): string;
+    hasChanges(): boolean;
+    toJSON(): {
+        nodes: {
+            add: {
+                rawManifest?: import("@vltpkg/types").Override<import("@vltpkg/types").Manifest, import("@vltpkg/types").NormalizedFields> | undefined;
+                peerSetHash?: string | undefined;
+                id: import("@vltpkg/dep-id").DepID;
+                name: string;
+                version: string | undefined;
+                location: string;
+                importer: boolean;
+                manifest: import("@vltpkg/types").Override<import("@vltpkg/types").Manifest, import("@vltpkg/types").NormalizedFields> | undefined;
+                projectRoot: string;
+                integrity: `sha512-${string}` | undefined;
+                resolved: string | undefined;
+                dev: boolean;
+                optional: boolean;
+                confused: boolean;
+                modifier: string | undefined;
+                platform: {
+                    engines?: Record<string, string>;
+                    os?: string[] | string;
+                    cpu?: string[] | string;
+                    libc?: string[] | string;
+                } | undefined;
+                buildState: "none" | "needed" | "built" | "failed";
+            }[];
+            delete: {
+                rawManifest?: import("@vltpkg/types").Override<import("@vltpkg/types").Manifest, import("@vltpkg/types").NormalizedFields> | undefined;
+                peerSetHash?: string | undefined;
+                id: import("@vltpkg/dep-id").DepID;
+                name: string;
+                version: string | undefined;
+                location: string;
+                importer: boolean;
+                manifest: import("@vltpkg/types").Override<import("@vltpkg/types").Manifest, import("@vltpkg/types").NormalizedFields> | undefined;
+                projectRoot: string;
+                integrity: `sha512-${string}` | undefined;
+                resolved: string | undefined;
+                dev: boolean;
+                optional: boolean;
+                confused: boolean;
+                modifier: string | undefined;
+                platform: {
+                    engines?: Record<string, string>;
+                    os?: string[] | string;
+                    cpu?: string[] | string;
+                    libc?: string[] | string;
+                } | undefined;
+                buildState: "none" | "needed" | "built" | "failed";
+            }[];
+        };
+        edges: {
+            add: {
+                from: import("@vltpkg/dep-id").DepID;
+                to: import("@vltpkg/dep-id").DepID | undefined;
+                type: import("@vltpkg/types").DependencyTypeShort;
+                spec: string;
+            }[];
+            delete: {
+                from: import("@vltpkg/dep-id").DepID;
+                to: import("@vltpkg/dep-id").DepID | undefined;
+                type: import("@vltpkg/types").DependencyTypeShort;
+                spec: string;
+            }[];
+        };
+    };
+}
+export {};

package/dist/diff.js

@@ -0,0 +1,151 @@
+import { error } from '@vltpkg/error-cause';
+// XXX should file deps *always* be considered changed?
+// unless the thing containing it wasn't possibly changed because it's inside
+// a dep that didn't change?
+// Same with remote deps
+const kCustomInspect = Symbol.for('nodejs.util.inspect.custom');
+/**
+ * A Diff object is a representation of a set of changes from one
+ * graph to another, typically from the actual graph as it is reified
+ * on disk, to an intended ideal graph.
+ *
+ * The naming convention can get a bit confusing here, because it's a
+ * set of directed changes from one set of directed objects to another.
+ *
+ * Within the context the Diff object, `from` is the Graph we're coming from,
+ * and `to` is the Graph we're trying to create.
+ */
+export class Diff {
+    from;
+    to;
+    projectRoot;
+    /**
+     * If changes need to be made later for failures of optional nodes,
+     * set this flag so that we know to call graph.gc() at the appropriate time.
+     */
+    hadOptionalFailures = false;
+    /**
+     * Collection of nodes to add and delete
+     */
+    nodes = {
+        /** Nodes in the `to` graph that are not in the `from` graph */
+        add: new Set(),
+        /** Nodes in the `from` graph that are not in the `to` graph */
+        delete: new Set(),
+    };
+    /**
+     * Collection of nodes to add and delete
+     */
+    edges = {
+        /** Edges in the `to` graph that are not found in the `from` graph */
+        add: new Set(),
+        /** Edges in the `from` graph that are not found in the `to` graph */
+        delete: new Set(),
+    };
+    /**
+     * True if the diff only contains optional nodes (computed during construction)
+     */
+    optionalOnly = true;
+    get [Symbol.toStringTag]() {
+        return '@vltpkg/graph.Diff';
+    }
+    constructor(from, to) {
+        this.from = from;
+        this.to = to;
+        this.projectRoot = from.projectRoot;
+        if (to.projectRoot !== from.projectRoot) {
+            throw error('projectRoot mismatch in Graph diff', {
+                wanted: from.projectRoot,
+                found: to.projectRoot,
+            });
+        }
+        for (const [id, node] of this.from.nodes) {
+            if (!this.to.nodes.get(id)?.equals(node)) {
+                this.nodes.delete.add(node);
+            }
+        }
+        for (const [id, node] of this.to.nodes) {
+            if (!this.from.nodes.get(id)?.equals(node)) {
+                this.nodes.add.add(node);
+                if (!node.optional) {
+                    this.optionalOnly = false;
+                }
+            }
+        }
+        for (const edge of this.to.edges) {
+            // the node with this dep, in the from  graph
+            const fromNode = this.from.nodes.get(edge.from.id);
+            const fromEdge = fromNode?.edgesOut.get(edge.spec.name);
+            if (fromEdge?.to?.id === edge.to?.id)
+                continue;
+            if (fromEdge?.to)
+                this.edges.delete.add(fromEdge);
+            if (edge.to) {
+                this.edges.add.add(edge);
+                if (!edge.optional) {
+                    this.optionalOnly = false;
+                }
+            }
+        }
+        for (const edge of this.from.edges) {
+            // the node with this dep, in the to graph
+            const toNode = this.to.nodes.get(edge.from.id);
+            const toEdge = toNode?.edgesOut.get(edge.spec.name);
+            if (toEdge?.to?.id === edge.to?.id)
+                continue;
+            if (edge.to)
+                this.edges.delete.add(edge);
+            if (toEdge?.to)
+                this.edges.add.add(toEdge);
+        }
+    }
+    [kCustomInspect](_, options) {
+        const red = options?.colors ? ['\x1b[31m', '\x1b[m'] : ['', ''];
+        const green = options?.colors ? ['\x1b[32m', '\x1b[m'] : ['', ''];
+        const lines = [];
+        for (const node of this.nodes.add) {
+            lines.push(`+ ${node.id}`);
+        }
+        for (const node of this.nodes.delete) {
+            lines.push(`- ${node.id}`);
+        }
+        for (const edge of this.edges.add) {
+            /* c8 ignore next */
+            const to = edge.to?.id ?? '';
+            lines.push(`+ ${edge.from.id} ${edge.type} ${edge.spec} ${to}`.trim());
+        }
+        for (const edge of this.edges.delete) {
+            /* c8 ignore next */
+            const to = edge.to?.id ?? '';
+            lines.push(`- ${edge.from.id} ${edge.type} ${edge.spec} ${to}`.trim());
+        }
+        const wrap = (s, c) => c.join(s);
+        const color = options?.colors ?
+            (s) => wrap(s, s.startsWith('+') ? green : red)
+            : (s) => s;
+        return `${this[Symbol.toStringTag]} {
+${lines
+            .sort((a, b) => a.substring(1).localeCompare(b.substring(1), 'en'))
+            .map(s => '  ' + color(s))
+            .join('\n')}
+}`;
+    }
+    hasChanges() {
+        return (this.nodes.add.size > 0 ||
+            this.nodes.delete.size > 0 ||
+            this.edges.add.size > 0 ||
+            this.edges.delete.size > 0);
+    }
+    toJSON() {
+        return {
+            nodes: {
+                add: [...this.nodes.add].map(node => node.toJSON()),
+                delete: [...this.nodes.delete].map(node => node.toJSON()),
+            },
+            edges: {
+                add: [...this.edges.add].map(edge => edge.toJSON()),
+                delete: [...this.edges.delete].map(edge => edge.toJSON()),
+            },
+        };
+    }
+}

package/dist/edge.d.ts

@@ -0,0 +1,46 @@
+import type { Spec } from '@vltpkg/spec';
+import type { InspectOptions } from 'node:util';
+import type { DependencyTypeShort, EdgeLike } from '@vltpkg/types';
+import type { Node } from './node.ts';
+declare const kCustomInspect: unique symbol;
+export declare class Edge implements EdgeLike {
+    get [Symbol.toStringTag](): string;
+    [kCustomInspect](_: number, options: InspectOptions): string;
+    /**
+     * The Node this Edge is connecting from, this is usually the dependent.
+     */
+    from: Node;
+    /**
+     * The node this Edge is connecting to, this is usually a direct dependency.
+     */
+    to?: Node;
+    /**
+     * What type of dependency relationship `from` and `to` nodes have.
+     */
+    type: DependencyTypeShort;
+    /**
+     * The defined spec value for `to` as parsed from the dependent metadata.
+     */
+    spec: Spec;
+    constructor(type: DependencyTypeShort, spec: Spec, from: Node, to?: Node);
+    /**
+     * The name of the dependency `to` as defined in the dependent metadata.
+     */
+    get name(): string;
+    /**
+     * This edge was defined as part of a `devDependencies` in `package.json`
+     */
+    get dev(): boolean;
+    get optional(): boolean;
+    get peer(): boolean;
+    get peerOptional(): boolean;
+    valid(): boolean;
+    toJSON(): {
+        from: import("@vltpkg/dep-id").DepID;
+        to: import("@vltpkg/dep-id").DepID | undefined;
+        type: DependencyTypeShort;
+        spec: string;
+    };
+    toString(): string;
+}
+export {};

package/dist/edge.js

@@ -0,0 +1,77 @@
+import { satisfies } from '@vltpkg/satisfies';
+import { inspect } from 'node:util';
+const kCustomInspect = Symbol.for('nodejs.util.inspect.custom');
+export class Edge {
+    get [Symbol.toStringTag]() {
+        return '@vltpkg/graph.Edge';
+    }
+    [kCustomInspect](_, options) {
+        const str = inspect({
+            from: this.from.id,
+            type: this.type,
+            spec: String(this.spec),
+            to: this.to?.id,
+        }, options);
+        return `${this[Symbol.toStringTag]} ${str}`;
+    }
+    /**
+     * The Node this Edge is connecting from, this is usually the dependent.
+     */
+    from;
+    /**
+     * The node this Edge is connecting to, this is usually a direct dependency.
+     */
+    to;
+    /**
+     * What type of dependency relationship `from` and `to` nodes have.
+     */
+    type;
+    /**
+     * The defined spec value for `to` as parsed from the dependent metadata.
+     */
+    spec;
+    constructor(type, spec, from, to) {
+        this.from = from;
+        this.to = to;
+        this.type = type;
+        this.spec = spec;
+    }
+    /**
+     * The name of the dependency `to` as defined in the dependent metadata.
+     */
+    get name() {
+        return this.spec.name;
+    }
+    /**
+     * This edge was defined as part of a `devDependencies` in `package.json`
+     */
+    get dev() {
+        return this.type === 'dev';
+    }
+    get optional() {
+        return this.type === 'peerOptional' || this.type === 'optional';
+    }
+    get peer() {
+        return this.type === 'peer' || this.type === 'peerOptional';
+    }
+    get peerOptional() {
+        return this.type === 'peerOptional';
+    }
+    valid() {
+        return !this.to ?
+            this.optional
+            : satisfies(this.to.id, this.spec, this.from.location, this.from.projectRoot);
+    }
+    toJSON() {
+        return {
+            from: this.from.id,
+            to: this.to?.id,
+            type: this.type,
+            spec: String(this.spec),
+        };
+    }
+    toString() {
+        const to = `${this.name}${this.to ? '' : ' (missing)'}`;
+        return `Edge from: ${this.from.id} --|${this.type}|--> ${to}`;
+    }
+}

package/dist/fixup-added-names.d.ts

@@ -0,0 +1,18 @@
+import { Spec } from '@vltpkg/spec';
+import type { Dependency } from './dependencies.ts';
+import type { Manifest } from '@vltpkg/types';
+import type { SpecOptions } from '@vltpkg/spec';
+/**
+ * When adding new dependencies, it's very common to not have a dependency
+ * name directly available to reference, e.g: `file:local/folder` or
+ * `remote:tarball-url.tgz`. In these cases, a placeholder `(unknown)` name
+ * is used in the `Spec` object and the `add` Map structure that holds
+ * references to added dependencies will use the stringified spec as a key.
+ *
+ * This helper function fixes unknown names in the `add` map by replacing
+ * placeholder specs with the correct names from the provided manifest.
+ *
+ * It also fixes empty bareSpec values (from CLI args like `vlt install foo`)
+ * by calculating the proper semver range from the resolved manifest version.
+ */
+export declare const fixupAddedNames: (add: Map<string, Dependency> | undefined, manifest: Pick<Manifest, "name" | "version"> | undefined, options: SpecOptions, spec: Spec) => Spec;

package/dist/fixup-added-names.js

@@ -0,0 +1,46 @@
+import { Spec } from '@vltpkg/spec';
+import { calculateSaveValue } from "./reify/calculate-save-value.js";
+/**
+ * When adding new dependencies, it's very common to not have a dependency
+ * name directly available to reference, e.g: `file:local/folder` or
+ * `remote:tarball-url.tgz`. In these cases, a placeholder `(unknown)` name
+ * is used in the `Spec` object and the `add` Map structure that holds
+ * references to added dependencies will use the stringified spec as a key.
+ *
+ * This helper function fixes unknown names in the `add` map by replacing
+ * placeholder specs with the correct names from the provided manifest.
+ *
+ * It also fixes empty bareSpec values (from CLI args like `vlt install foo`)
+ * by calculating the proper semver range from the resolved manifest version.
+ */
+export const fixupAddedNames = (add, manifest, options, spec) => {
+    // Handle nameless dependencies
+    if (add && manifest?.name && spec.name === '(unknown)') {
+        const s = add.get(String(spec));
+        if (s) {
+            // removes the previous, placeholder entry key
+            add.delete(String(spec));
+            // replaces spec with a version with the correct name
+            spec = Spec.parse(manifest.name, spec.bareSpec, options);
+            // updates the add map with the fixed up spec
+            const n = {
+                type: s.type,
+                spec,
+            };
+            add.set(manifest.name, n);
+        }
+    }
+    // Fix empty bareSpec (usually from CLI args like `vlt install foo`)
+    // by calculating the proper semver range from the resolved manifest version
+    if (add && manifest?.version && !spec.bareSpec) {
+        const addEntry = add.get(spec.name);
+        if (addEntry) {
+            const saveValue = calculateSaveValue(spec.final.type, spec, undefined, manifest.version);
+            if (saveValue && saveValue !== spec.bareSpec) {
+                spec = Spec.parse(spec.name, saveValue, options);
+                addEntry.spec = spec;
+            }
+        }
+    }
+    return spec;
+};