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

package/dist/node.d.ts

@@ -0,0 +1,234 @@
+import type { PathScurry } from 'path-scurry';
+import type { DepID } from '@vltpkg/dep-id';
+import type { Spec, SpecOptions } from '@vltpkg/spec';
+import type { Integrity, NormalizedManifest, DependencyTypeShort, GraphLike, NodeLike } from '@vltpkg/types';
+import { Edge } from './edge.ts';
+import type { Graph } from './graph.ts';
+export type NodeOptions = SpecOptions & {
+    projectRoot: string;
+    graph: GraphLike;
+};
+export declare class Node implements NodeLike {
+    #private;
+    get [Symbol.toStringTag](): string;
+    /**
+     * True if a node is only reachable via optional or peerOptional edges from
+     * any importer.
+     *
+     * Setting this to false, if previously set to true, will also unset
+     * the flag on any optional-flagged non-optional dependencies.
+     */
+    get optional(): boolean;
+    set optional(optional: boolean);
+    isOptional(): this is Node & {
+        optional: true;
+    };
+    /**
+     * True if a node is only reachable via dev edges from any importer.
+     *
+     * Setting this to false, if previously set to true, will also unset
+     * the flag on any dev-flagged non-dev dependencies.
+     */
+    get dev(): boolean;
+    set dev(dev: boolean);
+    isDev(): this is Node & {
+        dev: true;
+    };
+    /**
+     * True if there's a manifest-confused package name.
+     */
+    confused: boolean;
+    /**
+     * True if this node has been extracted to the file system.
+     */
+    extracted: boolean;
+    /**
+     * List of edges coming into this node.
+     */
+    edgesIn: Set<Edge>;
+    /**
+     * List of edges from this node into other nodes. This usually represents
+     * that the connected node is a direct dependency of this node.
+     */
+    edgesOut: Map<string, Edge>;
+    /**
+     * A `mainImporter` node may have workspace connected to it,
+     * equivalent to its `edgesOut` linked deps.
+     */
+    workspaces: Map<string, Edge> | undefined;
+    /**
+     * A reference to the {@link DepID} this node represents in the graph.
+     */
+    id: DepID;
+    /**
+     * True if this node is an importer node.
+     */
+    importer: boolean;
+    /**
+     * True if this node is the project root node.
+     */
+    mainImporter: boolean;
+    /**
+     * A reference to the graph this node is a part of.
+     */
+    graph: Graph;
+    /**
+     * The manifest integrity value.
+     */
+    integrity?: Integrity;
+    /**
+     * The manifest this node represents in the graph.
+     */
+    manifest?: NormalizedManifest;
+    /**
+     * Project where this node resides
+     */
+    projectRoot: string;
+    /**
+     * For registry nodes, this is the registry we fetched them from.
+     * Needed because their un-prefixed dependencies need to come from
+     * the same registry, if it's not the default.
+     */
+    registry?: string;
+    /**
+     * If this node has been modified as part of applying a {@link GraphModifier}
+     * then this field will contain the modifier query that was applied.
+     * Otherwise, it will be `undefined`.
+     */
+    modifier: string | undefined;
+    get name(): string;
+    /**
+     * The version of the package represented by this node, this is usually
+     * equivalent to `manifest.version` but in a few ways it may differ such as
+     * nodes loaded from a lockfile that lacks a loaded manifest.
+     * This field should be used to retrieve package versions instead.
+     */
+    version?: string;
+    /**
+     * An address {@link PackageInfoClient} may use to extract this package.
+     */
+    resolved?: string;
+    /**
+     * Platform requirements (engines, os, cpu) extracted from manifest.
+     * Stored separately for optional dependencies to enable platform checks
+     * when manifest is not loaded.
+     */
+    platform?: {
+        engines?: Record<string, string>;
+        os?: string[] | string;
+        cpu?: string[] | string;
+        libc?: string[] | string;
+    };
+    /**
+     * Record of binary names to their paths in the package, if any.
+     */
+    bins?: Record<string, string>;
+    /**
+     * True if this node has been built as part of the reify step.
+     */
+    built: boolean;
+    /**
+     * Build state of this node - tracks whether it needs building, has been built, or failed.
+     * - 'none': No build state (default)
+     * - 'needed': Node needs to be built
+     * - 'built': Node has been successfully built
+     * - 'failed': Node build has failed
+     */
+    buildState: 'none' | 'needed' | 'built' | 'failed';
+    /**
+     * Deterministic unique string used to identify (and ultimately duplicate)
+     * nodes that are affected by a peer context set modified resolution.
+     * These are appended to the node {@link DepID} as the `extra` suffix.
+     */
+    peerSetHash?: string;
+    /**
+     * True if this node is detached from the graph.
+     * This is used to indicate that the node is not part of the graph
+     * although the node is still available as part of the resolution process.
+     * Allows for skipping fetching manifests for detached nodes.
+     */
+    detached: boolean;
+    /**
+     * The file system location for this node.
+     */
+    get location(): string;
+    set location(location: string);
+    /**
+     * The resolved location of the node in the file system.
+     */
+    resolvedLocation(scurry: PathScurry): string;
+    /**
+     * The location of the node_modules folder where this node's edgesOut
+     * should be linked into. For nodes in the store, this is the parent
+     * directory, since they're extracted into a node_modules folder
+     * side by side with links to their deps. For nodes outside of the store
+     * (ie, importers and arbitrary link deps) this is the node_modules folder
+     * directly inside the node's directory.
+     */
+    nodeModules(scurry: PathScurry): string;
+    constructor(options: NodeOptions, id?: DepID, manifest?: NormalizedManifest, spec?: Spec, name?: string, version?: string);
+    /**
+     * return true if this node is located in the vlt store
+     * memoized the first time it's called, since the store location
+     * doesn't change within the context of a single operation.
+     */
+    inVltStore(): boolean;
+    get options(): SpecOptions;
+    set options(_opts: SpecOptions);
+    equals(other: Node): boolean;
+    /**
+     * Sets the node as an importer along with its location.
+     */
+    setImporterLocation(location: string): void;
+    /**
+     * Sets the appropriate resolve / integrity value for this node.
+     * Note that other places might also set these values, like for
+     * example the lockfile that might have already have this info.
+     */
+    setResolved(): void;
+    setDefaultLocation(): void;
+    /**
+     * Add an edge from this node connecting it to a direct dependency.
+     */
+    addEdgesTo(type: DependencyTypeShort, spec: Spec, node?: Node): Edge;
+    /**
+     * The raw manifest before any modifications.
+     * If not set, falls back to the current manifest.
+     */
+    get rawManifest(): NormalizedManifest | undefined;
+    /**
+     * Sets this node as having a manifest-confused manifest.
+     */
+    setConfusedManifest(fixed: NormalizedManifest, confused?: NormalizedManifest): void;
+    /**
+     * Sets this node as having a manifest-confused manifest.
+     */
+    maybeSetConfusedManifest(spec: Spec, confused?: NormalizedManifest): void;
+    toJSON(): {
+        rawManifest?: import("@vltpkg/types").Override<import("@vltpkg/types").Manifest, import("@vltpkg/types").NormalizedFields> | undefined;
+        peerSetHash?: string | undefined;
+        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";
+    };
+    toString(): string;
+}
+export declare const isNode: (value: unknown) => value is Node;
+export declare const asNode: (value: unknown) => Node;

package/dist/node.js

@@ -0,0 +1,388 @@
+import { isPackageNameConfused, getId, hydrateTuple, splitDepID, } from '@vltpkg/dep-id';
+import { typeError } from '@vltpkg/error-cause';
+import { expandNormalizedManifestSymbols } from '@vltpkg/types';
+import { Edge } from "./edge.js";
+import { stringifyNode } from "./stringify-node.js";
+export class Node {
+    get [Symbol.toStringTag]() {
+        return '@vltpkg/graph.Node';
+    }
+    #options;
+    #location;
+    #rawManifest;
+    #optional = false;
+    /**
+     * True if a node is only reachable via optional or peerOptional edges from
+     * any importer.
+     *
+     * Setting this to false, if previously set to true, will also unset
+     * the flag on any optional-flagged non-optional dependencies.
+     */
+    get optional() {
+        return this.#optional;
+    }
+    set optional(optional) {
+        const before = this.#optional;
+        this.#optional = optional;
+        if (before && !optional) {
+            // unset for all deps, as well
+            for (const { to, optional } of this.edgesOut.values()) {
+                if (!optional && to?.optional)
+                    to.optional = false;
+            }
+        }
+    }
+    isOptional() {
+        return this.#optional;
+    }
+    #dev = false;
+    /**
+     * True if a node is only reachable via dev edges from any importer.
+     *
+     * Setting this to false, if previously set to true, will also unset
+     * the flag on any dev-flagged non-dev dependencies.
+     */
+    get dev() {
+        return this.#dev;
+    }
+    set dev(dev) {
+        const before = this.#dev;
+        this.#dev = dev;
+        if (before && !dev) {
+            // unset for all deps, as well
+            for (const { to, dev } of this.edgesOut.values()) {
+                if (!dev && to?.dev)
+                    to.dev = false;
+            }
+        }
+    }
+    isDev() {
+        return this.#dev;
+    }
+    /**
+     * True if there's a manifest-confused package name.
+     */
+    confused = false;
+    /**
+     * True if this node has been extracted to the file system.
+     */
+    extracted = false;
+    /**
+     * List of edges coming into this node.
+     */
+    edgesIn = new Set();
+    /**
+     * List of edges from this node into other nodes. This usually represents
+     * that the connected node is a direct dependency of this node.
+     */
+    edgesOut = new Map();
+    /**
+     * A `mainImporter` node may have workspace connected to it,
+     * equivalent to its `edgesOut` linked deps.
+     */
+    workspaces;
+    /**
+     * A reference to the {@link DepID} this node represents in the graph.
+     */
+    id;
+    /**
+     * True if this node is an importer node.
+     */
+    importer = false;
+    /**
+     * True if this node is the project root node.
+     */
+    mainImporter = false;
+    /**
+     * A reference to the graph this node is a part of.
+     */
+    graph;
+    /**
+     * The manifest integrity value.
+     */
+    integrity;
+    /**
+     * The manifest this node represents in the graph.
+     */
+    manifest;
+    /**
+     * Project where this node resides
+     */
+    projectRoot;
+    /**
+     * For registry nodes, this is the registry we fetched them from.
+     * Needed because their un-prefixed dependencies need to come from
+     * the same registry, if it's not the default.
+     */
+    registry;
+    /**
+     * If this node has been modified as part of applying a {@link GraphModifier}
+     * then this field will contain the modifier query that was applied.
+     * Otherwise, it will be `undefined`.
+     */
+    modifier;
+    /**
+     * The name of the package represented by this node, this is usually
+     * equivalent to `manifest.name` but in a few ways it may differ such as
+     * nodes loaded from a lockfile that lacks a loaded manifest.
+     * This field should be used to retrieve package names instead.
+     */
+    #name;
+    get name() {
+        if (this.#name)
+            return this.#name;
+        this.#name = this.id;
+        return this.#name;
+    }
+    /**
+     * The version of the package represented by this node, this is usually
+     * equivalent to `manifest.version` but in a few ways it may differ such as
+     * nodes loaded from a lockfile that lacks a loaded manifest.
+     * This field should be used to retrieve package versions instead.
+     */
+    version;
+    /**
+     * An address {@link PackageInfoClient} may use to extract this package.
+     */
+    resolved;
+    /**
+     * Platform requirements (engines, os, cpu) extracted from manifest.
+     * Stored separately for optional dependencies to enable platform checks
+     * when manifest is not loaded.
+     */
+    platform;
+    /**
+     * Record of binary names to their paths in the package, if any.
+     */
+    bins;
+    /**
+     * True if this node has been built as part of the reify step.
+     */
+    built = false;
+    /**
+     * Build state of this node - tracks whether it needs building, has been built, or failed.
+     * - 'none': No build state (default)
+     * - 'needed': Node needs to be built
+     * - 'built': Node has been successfully built
+     * - 'failed': Node build has failed
+     */
+    buildState = 'none';
+    /**
+     * Deterministic unique string used to identify (and ultimately duplicate)
+     * nodes that are affected by a peer context set modified resolution.
+     * These are appended to the node {@link DepID} as the `extra` suffix.
+     */
+    peerSetHash;
+    /**
+     * True if this node is detached from the graph.
+     * This is used to indicate that the node is not part of the graph
+     * although the node is still available as part of the resolution process.
+     * Allows for skipping fetching manifests for detached nodes.
+     */
+    detached = false;
+    /**
+     * The file system location for this node.
+     */
+    get location() {
+        if (this.#location) {
+            return this.#location;
+        }
+        this.#location = `./node_modules/.vlt/${this.id}/node_modules/${this.name}`;
+        // if using the default location, it is in the store
+        this.inVltStore = () => true;
+        return this.#location;
+    }
+    set location(location) {
+        this.#location = location;
+        // reset memoization, since it might be elsewhere now
+        if (this.inVltStore !== Node.prototype.inVltStore) {
+            this.inVltStore = Node.prototype.inVltStore;
+        }
+    }
+    /**
+     * The resolved location of the node in the file system.
+     */
+    resolvedLocation(scurry) {
+        return scurry.cwd.resolve(this.location).fullpath();
+    }
+    /**
+     * The location of the node_modules folder where this node's edgesOut
+     * should be linked into. For nodes in the store, this is the parent
+     * directory, since they're extracted into a node_modules folder
+     * side by side with links to their deps. For nodes outside of the store
+     * (ie, importers and arbitrary link deps) this is the node_modules folder
+     * directly inside the node's directory.
+     */
+    nodeModules(scurry) {
+        const loc = this.resolvedLocation(scurry);
+        return this.inVltStore() ?
+            loc.substring(0, loc.length - this.name.length - 1)
+            : scurry.resolve(loc, 'node_modules');
+    }
+    constructor(options, id, manifest, spec, name, version) {
+        this.#options = options;
+        this.projectRoot = options.projectRoot;
+        if (id) {
+            this.id = id;
+        }
+        else {
+            if (!manifest || !spec) {
+                throw typeError('A new Node needs either a manifest & spec or an id parameter', {
+                    manifest,
+                });
+            }
+            this.id = getId(spec, manifest);
+        }
+        this.graph = options.graph;
+        this.manifest = manifest;
+        this.#name = name || this.manifest?.name;
+        this.version = version || this.manifest?.version;
+    }
+    /**
+     * return true if this node is located in the vlt store
+     * memoized the first time it's called, since the store location
+     * doesn't change within the context of a single operation.
+     */
+    inVltStore() {
+        // technically this just means it's in *a* vlt store, but we can safely
+        // assume that a user won't construct a path like this by accident,
+        // and there's only ever one store in any given project.
+        const inStore = this.location.endsWith(`.vlt/${this.id}/node_modules/${this.name}`);
+        this.inVltStore = () => inStore;
+        return inStore;
+    }
+    #registryNodeResolved(tuple) {
+        const spec = hydrateTuple(tuple, this.#name, this.#options);
+        this.resolved =
+            this.manifest?.dist?.tarball || spec.conventionalRegistryTarball;
+        this.integrity ??= this.manifest?.dist?.integrity;
+    }
+    get options() {
+        return this.#options;
+    }
+    /* c8 ignore next */
+    set options(_opts) { }
+    equals(other) {
+        return this.id === other.id && this.location === other.location;
+    }
+    /**
+     * Sets the node as an importer along with its location.
+     */
+    setImporterLocation(location) {
+        this.#location = location;
+        this.importer = true;
+    }
+    /**
+     * Sets the appropriate resolve / integrity value for this node.
+     * Note that other places might also set these values, like for
+     * example the lockfile that might have already have this info.
+     */
+    setResolved() {
+        // file | remote | workspace type of ids all points to a URI that
+        // can be used as the `resolved` value, so we split the dep id
+        // for these cases.
+        const tuple = splitDepID(this.id);
+        const [type, resolved] = tuple;
+        switch (type) {
+            case 'remote': {
+                this.resolved = resolved;
+                this.integrity ??= this.manifest?.dist?.integrity;
+                break;
+            }
+            case 'registry':
+                this.#registryNodeResolved(tuple);
+                break;
+            default:
+                this.resolved = resolved;
+                break;
+        }
+    }
+    setDefaultLocation() {
+        const def = `./node_modules/.vlt/${this.id}/node_modules/${this.name}`;
+        // only relocate if the location is in node_modules already
+        if (!this.importer &&
+            (!this.#location ||
+                (this.#location !== def &&
+                    /^(?:\.\/)?node_modules\//.test(this.#location)))) {
+            this.#location = def;
+        }
+    }
+    /**
+     * Add an edge from this node connecting it to a direct dependency.
+     */
+    addEdgesTo(type, spec, node) {
+        const edge = new Edge(type, spec, this, node);
+        node?.edgesIn.add(edge);
+        this.edgesOut.set(spec.name, edge);
+        return edge;
+    }
+    /**
+     * The raw manifest before any modifications.
+     * If not set, falls back to the current manifest.
+     */
+    get rawManifest() {
+        return this.#rawManifest ?? this.manifest;
+    }
+    /**
+     * Sets this node as having a manifest-confused manifest.
+     */
+    setConfusedManifest(fixed, confused) {
+        this.manifest = fixed;
+        this.#rawManifest = confused;
+        this.confused = true;
+        this.#name = this.manifest.name;
+    }
+    /**
+     * Sets this node as having a manifest-confused manifest.
+     */
+    maybeSetConfusedManifest(spec, confused) {
+        if (isPackageNameConfused(spec, this.manifest?.name)) {
+            this.setConfusedManifest({
+                ...this.manifest,
+                name: spec.name,
+            }, confused);
+        }
+    }
+    toJSON() {
+        return {
+            id: this.id,
+            name: this.name,
+            version: this.version,
+            location: this.location,
+            importer: this.importer,
+            manifest: this.manifest &&
+                expandNormalizedManifestSymbols(this.manifest),
+            projectRoot: this.projectRoot,
+            integrity: this.integrity,
+            resolved: this.resolved,
+            dev: this.dev,
+            optional: this.optional,
+            confused: this.confused,
+            modifier: this.modifier,
+            platform: this.platform,
+            buildState: this.buildState,
+            ...(this.peerSetHash ?
+                { peerSetHash: this.peerSetHash }
+                : undefined),
+            ...(this.confused ?
+                { rawManifest: this.#rawManifest }
+                : undefined),
+        };
+    }
+    toString() {
+        return stringifyNode(this);
+    }
+}
+export const isNode = (value) => {
+    return (typeof value === 'object' &&
+        value != null &&
+        'id' in value &&
+        'manifest' in value &&
+        value[Symbol.toStringTag] === '@vltpkg/graph.Node');
+};
+export const asNode = (value) => {
+    if (!isNode(value)) {
+        throw typeError('Expected a node', { found: value });
+    }
+    return value;
+};

package/dist/non-empty-list.d.ts

@@ -0,0 +1,2 @@
+export declare const isNonEmptyList: <T>(list: T[]) => list is [first: T, ...rest: T[]];
+export declare const nonEmptyList: <T>(nodes: T[]) => [first: T, ...rest: T[]] | undefined;

package/dist/non-empty-list.js

@@ -0,0 +1,2 @@
+export const isNonEmptyList = (list) => !!list.length;
+export const nonEmptyList = (nodes) => isNonEmptyList(nodes) ? nodes : undefined;

package/dist/reify/add-edge.d.ts

@@ -0,0 +1,9 @@
+import type { RollbackRemove } from '@vltpkg/rollback-remove';
+import type { PathScurry } from 'path-scurry';
+import type { Edge } from '../edge.ts';
+/**
+ * reify an edge into a node_modules folder, with bins linked
+ * this does NOT chmod the bins to 0o777, because they might not exist
+ * until scripts are run, in the case of non-store deps like workspaces
+ */
+export declare const addEdge: (edge: Edge, scurry: PathScurry, remover: RollbackRemove, bins?: Record<string, string>) => Promise<void>;