@vltpkg/graph 0.0.0-3 → 0.0.0-30

package/dist/esm/modifiers.js

@@ -0,0 +1,330 @@
+import { parseBreadcrumb, specificitySort, } from '@vltpkg/dss-breadcrumb';
+import { error } from '@vltpkg/error-cause';
+import { Spec } from '@vltpkg/spec';
+import { asNormalizedManifest, assertRecordStringString, normalizeManifest, } from '@vltpkg/types';
+import { load } from '@vltpkg/vlt-json';
+/**
+ * Class representing loaded modifiers configuration for a project.
+ *
+ * Instances of this class can be used as a helper to modify the graph
+ * during the graph build ideal traversal time.
+ *
+ * ```
+ * const modifier = new GraphModifier(options)
+ * modifier.load(options)
+ * ```
+ *
+ * The `tryImporter` method can be used to register the initial importer
+ * node along with any modifier that includes an importer selector, e.g:
+ * `modifier.tryImporter(graph.mainImporter)`
+ *
+ * When traversing the graph, use the `tryNewDependency` method to check
+ * if a given dependency spec to the current traversed node has matching
+ * registered modifiers, e.g:
+ * `const entries = modifier.tryNewDependency(fromNode, depSpec)`
+ *
+ * Use `updateActiveEntry` to update a given active modifier entry state
+ * with the current node of the graph being traversed. e.g:
+ * ```
+ * for (const entry of entries)
+ *   modifier.updateActiveEntry(fromNode, entry)
+ * ```
+ */
+export class GraphModifier {
+    /** The loaded modifiers configuration */
+    #config;
+    /** A set of all modifiers loaded from vlt.json */
+    #modifiers = new Set();
+    /** A set of all edge modifiers loaded from vlt.json */
+    #edgeModifiers = new Set();
+    /** A set of all node modifiers loaded from vlt.json */
+    #nodeModifiers = new Set();
+    /**
+     * A map of initial entries, keyed by the name of the first breadcrumb
+     * item to its modifier entry. Useful for checking for non-importer
+     * starting breadcrumbs, e.g: `#a > #b`
+     */
+    #initialEntries = new Map();
+    /**
+     * A multi-level map of active entries, keyed by:
+     * - modifiers
+     * - edge name
+     * - from node
+     * that allows for retrieving seen {@link ModifierActiveEntry} instances
+     * in constant time.
+     */
+    #activeEntries = new Map();
+    /**
+     * A set of currently active modifiers, which are being parsed.
+     */
+    activeModifiers = new Set();
+    /** A set of all modifier string values loaded from vlt.json */
+    modifierNames = new Set();
+    constructor(options) {
+        this.load(options);
+    }
+    /**
+     * Load the modifiers definitions from vlt.json,
+     * converting the result into a GraphModifierConfigObject
+     */
+    get config() {
+        if (this.#config)
+            return this.#config;
+        return (this.#config =
+            load('modifiers', assertRecordStringString) ?? {});
+    }
+    /**
+     * Loads the modifiers defined in `vlt.json` into memory.
+     */
+    load(options) {
+        for (const [key, value] of Object.entries(this.config)) {
+            this.modifierNames.add(key);
+            const breadcrumb = parseBreadcrumb(key);
+            /* c8 ignore start - should not be possible */
+            if (!breadcrumb.last.name) {
+                throw error('Could not find name in breadcrumb', {
+                    found: key,
+                });
+            }
+            /* c8 ignore stop */
+            let mod;
+            if (typeof value === 'string') {
+                mod = {
+                    breadcrumb,
+                    query: key,
+                    refs: new Set(),
+                    spec: Spec.parse(breadcrumb.last.name, value, options),
+                    type: 'edge',
+                    value,
+                };
+                this.#edgeModifiers.add(mod);
+                /* c8 ignore start - TODO */
+            }
+            else {
+                const manifest = asNormalizedManifest(normalizeManifest(value));
+                mod = {
+                    breadcrumb,
+                    query: key,
+                    manifest,
+                    refs: new Set(),
+                    type: 'node',
+                    value: manifest,
+                };
+                this.#nodeModifiers.add(mod);
+            }
+            /* c8 ignore end */
+            this.#modifiers.add(mod);
+            // if the breadcrumb starts with an id, then add it to the
+            // map of initial entries, so that we can use it to match
+            if (breadcrumb.first.name) {
+                const initialSet = this.#initialEntries.get(breadcrumb.first.name) ?? new Set();
+                initialSet.add(mod);
+                this.#initialEntries.set(breadcrumb.first.name, initialSet);
+            }
+        }
+    }
+    /**
+     * Try matching the provided node against the top-level selectors. In case
+     * a match is found it will also register the active entry modifier and
+     * update the active entry to the current importer node.
+     */
+    tryImporter(importer) {
+        for (const modifier of this.#modifiers) {
+            // if the first item in the breadcrumb is an importer and it matches
+            // any of the valid top-level selectors, then register the modifier
+            const { first } = modifier.breadcrumb;
+            const matchRoot = first.value === ':root' && importer.mainImporter;
+            const matchWorkspace = first.value === ':workspace' && importer.importer;
+            const matchAny = first.value === ':project' || matchRoot || matchWorkspace;
+            if (first.importer && matchAny) {
+                const active = this.newModifier(importer, modifier);
+                const single = active.modifier.breadcrumb.single;
+                // only the importers will update the active entry right after
+                // registering it since tryImporter doesn't try to match from
+                // active dependencies
+                if (!single) {
+                    this.updateActiveEntry(importer, active);
+                }
+            }
+        }
+    }
+    /**
+     * Try matching the provided node and spec to the current
+     * active parsing modifier entries along with possible starting-level
+     * modifiers.
+     *
+     * Any entries in which the breachcrumb have already reached its last
+     * element will be prioritized, along with checking for specificity,
+     * the complete entry with the highest specificity will be returned or just
+     * the entry with the highest specificity if no complete entry is found.
+     * Returns `undefined` if no matching entry is found.
+     *
+     * This method works with the assumption that it's going to be called
+     * during a graph traversal, such that any ascendent has been checked
+     * and the active modifier entry state has been updated in the previous
+     * iteration.
+     */
+    tryNewDependency(from, spec) {
+        const { name, semver } = spec;
+        // here we use a map instead of a set so that we can associate each
+        // modifier active entry with its breadcrumb so that it's easier to
+        // pick the correct entry when we sort breadcrbumbs by specificity
+        const all = new Map();
+        for (const modifier of this.#modifiers) {
+            // if an active entry is found then returns that
+            const entry = this.#activeEntries
+                .get(modifier)
+                ?.get(name)
+                ?.get(from);
+            if (entry) {
+                all.set(entry.modifier.breadcrumb, entry);
+            }
+        }
+        // matches the name against the initial entries, this will make it so
+        // that modifier queries that start with a name (e.g: #a > #b) can
+        // match at any point of the graph traversal
+        const initialSet = this.#initialEntries.get(name) ?? new Set();
+        for (const initial of initialSet) {
+            const initialEntry = 
+            /* c8 ignore next - difficult to test branch */
+            this.#activeEntries.get(initial)?.get(name)?.get(from) ??
+                this.newModifier(from, initial);
+            all.set(initialEntry.modifier.breadcrumb, initialEntry);
+        }
+        // selects the active entry that should apply to this dependency,
+        // any active entry that is done parsing has the priority, if we
+        // find multiple entries then we use css specificity to pick a winner
+        // if we have multiple matches but no active entry is complete, then
+        // we pick the one with the highest specificity breadcrumb
+        const arr = [...all.values()];
+        const completeEntries = arr.filter(active => active.interactiveBreadcrumb.current ===
+            active.modifier.breadcrumb.last);
+        // deregister completed entries
+        for (const entry of completeEntries) {
+            this.deregisterModifier(entry.modifier);
+        }
+        // returns the highest specificity entry from either the complete entries
+        // if any were found or from any of the entries if available, otherwise
+        // it will return undefined as no entry is found in the `all` map
+        const entries = completeEntries.length ? completeEntries : arr;
+        return all.get(specificitySort(entries
+            // here we filter out any entries that do not match the
+            // pseudo selector comparators used in the breadcrumb item
+            .filter(i => i.interactiveBreadcrumb.current?.comparator({
+            semver,
+        }))
+            .map(i => i.modifier.breadcrumb))[0]);
+    }
+    /**
+     * Returns the set of {@link ModifierActiveEntry} instances that matches
+     * the provided {@link Dependency} specs for a given node.
+     *
+     * This method is mostly a helper to {@link GraphModifier.tryNewDependency}
+     * that handles the registered modifiers traversal lookup.
+     */
+    tryDependencies(from, dependencies) {
+        const modifierRefs = new Map();
+        for (const { spec } of dependencies) {
+            const active = this.tryNewDependency(from, spec);
+            if (active) {
+                modifierRefs.set(spec.name, active);
+            }
+        }
+        return modifierRefs;
+    }
+    /**
+     * Updates an active entry state keeping track of items in the multi-level
+     * active entries map. If the current breadcrumb state shows there's no more
+     * items left, then we deregister the modifier.
+     */
+    updateActiveEntry(from, active) {
+        const { modifier } = active;
+        const interactiveBreadcrumb = active.interactiveBreadcrumb.next();
+        const name = interactiveBreadcrumb.current?.name;
+        // if there's no name, or we're done parsing then we
+        // deregister the modifier instead of updating the entry
+        if (interactiveBreadcrumb.done || !name) {
+            this.deregisterModifier(modifier);
+            return;
+        }
+        // register the active modifier
+        this.activeModifiers.add(active);
+        active.modifier.refs.add({ from, name });
+        // optionally read or create the nested maps
+        const nameMap = this.#activeEntries.get(modifier) ??
+            new Map();
+        this.#activeEntries.set(modifier, nameMap);
+        const nodeMap = nameMap.get(name) ?? new Map();
+        nameMap.set(name, nodeMap);
+        // sets the active entry in the map
+        nodeMap.set(from, active);
+    }
+    /**
+     * Creates a new active modifier.
+     */
+    newModifier(from, modifier) {
+        return {
+            modifier,
+            interactiveBreadcrumb: modifier.breadcrumb.interactive(),
+            originalFrom: from,
+        };
+    }
+    /**
+     * Removes a previously registered modifier from the active entries.
+     */
+    deregisterModifier(modifier) {
+        for (const { from, name } of modifier.refs) {
+            const nodeMap = this.#activeEntries.get(modifier)?.get(name);
+            if (nodeMap) {
+                // if an entry is found, we remove it from the active set
+                const entry = nodeMap.get(from);
+                if (entry) {
+                    this.activeModifiers.delete(entry);
+                }
+                // then we remove the entry from the map
+                nodeMap.delete(from);
+                // if the map is empty, we remove it from the active entries map
+                if (!nodeMap.size) {
+                    this.#activeEntries.get(modifier)?.delete(name);
+                }
+            }
+        }
+    }
+    /**
+     * Operates in previously registered nodes and edges in order to put
+     * back in place any of the original edges that were referenced to in
+     * active (ongoing) breadcrumb parsing entries that were never completed.
+     *
+     * This method can be used to easily rollback any pending operations
+     * once the graph traversal is done.
+     */
+    rollbackActiveEntries() {
+        for (const modifier of this.activeModifiers) {
+            // if the modifier has an original edge, we can put it back in place
+            if (modifier.originalEdge) {
+                modifier.originalFrom.edgesOut.set(modifier.originalEdge.spec.name, modifier.originalEdge);
+            }
+            // then we deregister the modifier
+            this.deregisterModifier(modifier.modifier);
+        }
+    }
+    /**
+     * Convenience method to instantiate and load in one call.
+     * Returns undefined if the project does not have a vlt.json file,
+     * otherwise returns the loaded Modifiers instance.
+     */
+    static maybeLoad(options) {
+        const config = load('modifiers', assertRecordStringString);
+        if (!config)
+            return;
+        return new GraphModifier(options);
+    }
+    /**
+     * Convenience method to instantiate and load in one call.
+     * Throws if called on a directory that does not have a vlt.json file.
+     */
+    static load(options) {
+        return new GraphModifier(options);
+    }
+}
+//# sourceMappingURL=modifiers.js.map

package/dist/esm/modifiers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"modifiers.js","sourceRoot":"","sources":["../../src/modifiers.ts"],"names":[],"mappings":"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","sourcesContent":["import {\n  parseBreadcrumb,\n  specificitySort,\n} from '@vltpkg/dss-breadcrumb'\nimport { error } from '@vltpkg/error-cause'\nimport { Spec } from '@vltpkg/spec'\nimport {\n  asNormalizedManifest,\n  assertRecordStringString,\n  normalizeManifest,\n} from '@vltpkg/types'\nimport { load } from '@vltpkg/vlt-json'\nimport type {\n  ModifierBreadcrumb,\n  ModifierInteractiveBreadcrumb,\n} from '@vltpkg/dss-breadcrumb'\nimport type { SpecOptions } from '@vltpkg/spec'\nimport type { NormalizedManifest } from '@vltpkg/types'\nimport type { Edge } from './edge.ts'\nimport type { Node } from './node.ts'\nimport type { Dependency } from './dependencies.ts'\n\n/**\n * Loaded modifiers configuration as described in the `vlt.json` file.\n */\nexport type GraphModifierLoadedConfig = {\n  modifiers: GraphModifierConfigObject\n}\n\n/**\n * Type definition for the modifiers configuration object\n */\n// TODO: subtype string into a more specific type for Queries\nexport type GraphModifierConfigObject = Record<string, string>\n\n/**\n * Info needed to define a graph modifier.\n */\nexport type BaseModifierEntry = {\n  type: 'edge' | 'node'\n  query: string\n  breadcrumb: ModifierBreadcrumb\n  value: string | NormalizedManifest\n  refs: Set<{\n    name: string\n    from: Node\n  }>\n}\n\n/**\n * Extra info to define specifically a graph edge modifier.\n */\nexport type EdgeModifierEntry = BaseModifierEntry & {\n  type: 'edge'\n  spec: Spec\n  value: string\n}\n\n/**\n * Extra info to define the graph node modifier.\n */\nexport type NodeModifierEntry = BaseModifierEntry & {\n  type: 'node'\n  manifest: NormalizedManifest\n}\n\n/**\n * A graph modifier entry, which can be either an edge or a node modifier.\n */\nexport type ModifierEntry = EdgeModifierEntry | NodeModifierEntry\n\n/**\n * An object to track modifiers that have matched an initial part of the\n * breadcrumb. It holds pointers to both nodes and edges matched in the\n * current traversed graph on top of the modifier info and the breadcrumb\n * state that is used to track the current state of the parsing.\n */\nexport type ModifierActiveEntry = {\n  /**\n   * The modifier this active entry is working with.\n   */\n  modifier: ModifierEntry\n  /**\n   * The breadcrumb that is used to track the current state of the parsing.\n   */\n  interactiveBreadcrumb: ModifierInteractiveBreadcrumb\n  /**\n   * The first node to be affected by this modifier.\n   */\n  originalFrom: Node\n  /**\n   * The original edge that is being replaced with this entry.\n   */\n  originalEdge?: Edge\n  /**\n   * The modified edge that is being used to replace the original edge.\n   */\n  modifiedEdge?: Edge\n}\n\n/**\n * Class representing loaded modifiers configuration for a project.\n *\n * Instances of this class can be used as a helper to modify the graph\n * during the graph build ideal traversal time.\n *\n * ```\n * const modifier = new GraphModifier(options)\n * modifier.load(options)\n * ```\n *\n * The `tryImporter` method can be used to register the initial importer\n * node along with any modifier that includes an importer selector, e.g:\n * `modifier.tryImporter(graph.mainImporter)`\n *\n * When traversing the graph, use the `tryNewDependency` method to check\n * if a given dependency spec to the current traversed node has matching\n * registered modifiers, e.g:\n * `const entries = modifier.tryNewDependency(fromNode, depSpec)`\n *\n * Use `updateActiveEntry` to update a given active modifier entry state\n * with the current node of the graph being traversed. e.g:\n * ```\n * for (const entry of entries)\n *   modifier.updateActiveEntry(fromNode, entry)\n * ```\n */\nexport class GraphModifier {\n  /** The loaded modifiers configuration */\n  #config?: GraphModifierConfigObject\n  /** A set of all modifiers loaded from vlt.json */\n  #modifiers = new Set<ModifierEntry>()\n  /** A set of all edge modifiers loaded from vlt.json */\n  #edgeModifiers = new Set<EdgeModifierEntry>()\n  /** A set of all node modifiers loaded from vlt.json */\n  #nodeModifiers = new Set<NodeModifierEntry>()\n  /**\n   * A map of initial entries, keyed by the name of the first breadcrumb\n   * item to its modifier entry. Useful for checking for non-importer\n   * starting breadcrumbs, e.g: `#a > #b`\n   */\n  #initialEntries = new Map<string, Set<ModifierEntry>>()\n  /**\n   * A multi-level map of active entries, keyed by:\n   * - modifiers\n   * - edge name\n   * - from node\n   * that allows for retrieving seen {@link ModifierActiveEntry} instances\n   * in constant time.\n   */\n  #activeEntries = new Map<\n    ModifierEntry,\n    Map<string, Map<Node, ModifierActiveEntry>>\n  >()\n  /**\n   * A set of currently active modifiers, which are being parsed.\n   */\n  activeModifiers = new Set<ModifierActiveEntry>()\n  /** A set of all modifier string values loaded from vlt.json */\n  modifierNames = new Set<string>()\n\n  constructor(options: SpecOptions) {\n    this.load(options)\n  }\n\n  /**\n   * Load the modifiers definitions from vlt.json,\n   * converting the result into a GraphModifierConfigObject\n   */\n  get config(): GraphModifierConfigObject {\n    if (this.#config) return this.#config\n    return (this.#config =\n      load('modifiers', assertRecordStringString) ?? {})\n  }\n\n  /**\n   * Loads the modifiers defined in `vlt.json` into memory.\n   */\n  load(options: SpecOptions) {\n    for (const [key, value] of Object.entries(this.config)) {\n      this.modifierNames.add(key)\n      const breadcrumb = parseBreadcrumb(key)\n      /* c8 ignore start - should not be possible */\n      if (!breadcrumb.last.name) {\n        throw error('Could not find name in breadcrumb', {\n          found: key,\n        })\n      }\n      /* c8 ignore stop */\n      let mod: ModifierEntry\n      if (typeof value === 'string') {\n        mod = {\n          breadcrumb,\n          query: key,\n          refs: new Set(),\n          spec: Spec.parse(breadcrumb.last.name, value, options),\n          type: 'edge',\n          value,\n        } satisfies EdgeModifierEntry\n        this.#edgeModifiers.add(mod)\n        /* c8 ignore start - TODO */\n      } else {\n        const manifest = asNormalizedManifest(\n          normalizeManifest(value),\n        )\n        mod = {\n          breadcrumb,\n          query: key,\n          manifest,\n          refs: new Set(),\n          type: 'node',\n          value: manifest,\n        } satisfies NodeModifierEntry\n        this.#nodeModifiers.add(mod)\n      }\n      /* c8 ignore end */\n      this.#modifiers.add(mod)\n      // if the breadcrumb starts with an id, then add it to the\n      // map of initial entries, so that we can use it to match\n      if (breadcrumb.first.name) {\n        const initialSet =\n          this.#initialEntries.get(breadcrumb.first.name) ?? new Set()\n        initialSet.add(mod)\n        this.#initialEntries.set(breadcrumb.first.name, initialSet)\n      }\n    }\n  }\n\n  /**\n   * Try matching the provided node against the top-level selectors. In case\n   * a match is found it will also register the active entry modifier and\n   * update the active entry to the current importer node.\n   */\n  tryImporter(importer: Node) {\n    for (const modifier of this.#modifiers) {\n      // if the first item in the breadcrumb is an importer and it matches\n      // any of the valid top-level selectors, then register the modifier\n      const { first } = modifier.breadcrumb\n      const matchRoot =\n        first.value === ':root' && importer.mainImporter\n      const matchWorkspace =\n        first.value === ':workspace' && importer.importer\n      const matchAny =\n        first.value === ':project' || matchRoot || matchWorkspace\n      if (first.importer && matchAny) {\n        const active = this.newModifier(importer, modifier)\n        const single = active.modifier.breadcrumb.single\n        // only the importers will update the active entry right after\n        // registering it since tryImporter doesn't try to match from\n        // active dependencies\n        if (!single) {\n          this.updateActiveEntry(importer, active)\n        }\n      }\n    }\n  }\n\n  /**\n   * Try matching the provided node and spec to the current\n   * active parsing modifier entries along with possible starting-level\n   * modifiers.\n   *\n   * Any entries in which the breachcrumb have already reached its last\n   * element will be prioritized, along with checking for specificity,\n   * the complete entry with the highest specificity will be returned or just\n   * the entry with the highest specificity if no complete entry is found.\n   * Returns `undefined` if no matching entry is found.\n   *\n   * This method works with the assumption that it's going to be called\n   * during a graph traversal, such that any ascendent has been checked\n   * and the active modifier entry state has been updated in the previous\n   * iteration.\n   */\n  tryNewDependency(\n    from: Node,\n    spec: Spec,\n  ): ModifierActiveEntry | undefined {\n    const { name, semver } = spec\n    // here we use a map instead of a set so that we can associate each\n    // modifier active entry with its breadcrumb so that it's easier to\n    // pick the correct entry when we sort breadcrbumbs by specificity\n    const all = new Map<\n      ModifierBreadcrumb | undefined,\n      ModifierActiveEntry\n    >()\n    for (const modifier of this.#modifiers) {\n      // if an active entry is found then returns that\n      const entry = this.#activeEntries\n        .get(modifier)\n        ?.get(name)\n        ?.get(from)\n      if (entry) {\n        all.set(entry.modifier.breadcrumb, entry)\n      }\n    }\n    // matches the name against the initial entries, this will make it so\n    // that modifier queries that start with a name (e.g: #a > #b) can\n    // match at any point of the graph traversal\n    const initialSet =\n      this.#initialEntries.get(name) ?? new Set<ModifierEntry>()\n    for (const initial of initialSet) {\n      const initialEntry =\n        /* c8 ignore next - difficult to test branch */\n        this.#activeEntries.get(initial)?.get(name)?.get(from) ??\n        this.newModifier(from, initial)\n      all.set(initialEntry.modifier.breadcrumb, initialEntry)\n    }\n    // selects the active entry that should apply to this dependency,\n    // any active entry that is done parsing has the priority, if we\n    // find multiple entries then we use css specificity to pick a winner\n    // if we have multiple matches but no active entry is complete, then\n    // we pick the one with the highest specificity breadcrumb\n    const arr = [...all.values()]\n    const completeEntries = arr.filter(\n      active =>\n        active.interactiveBreadcrumb.current ===\n        active.modifier.breadcrumb.last,\n    )\n    // deregister completed entries\n    for (const entry of completeEntries) {\n      this.deregisterModifier(entry.modifier)\n    }\n    // returns the highest specificity entry from either the complete entries\n    // if any were found or from any of the entries if available, otherwise\n    // it will return undefined as no entry is found in the `all` map\n    const entries = completeEntries.length ? completeEntries : arr\n    return all.get(\n      specificitySort(\n        entries\n          // here we filter out any entries that do not match the\n          // pseudo selector comparators used in the breadcrumb item\n          .filter(i =>\n            i.interactiveBreadcrumb.current?.comparator({\n              semver,\n            }),\n          )\n          .map(i => i.modifier.breadcrumb),\n      )[0],\n    )\n  }\n\n  /**\n   * Returns the set of {@link ModifierActiveEntry} instances that matches\n   * the provided {@link Dependency} specs for a given node.\n   *\n   * This method is mostly a helper to {@link GraphModifier.tryNewDependency}\n   * that handles the registered modifiers traversal lookup.\n   */\n  tryDependencies(\n    from: Node,\n    dependencies: Dependency[] | Edge[],\n  ): Map<string, ModifierActiveEntry> {\n    const modifierRefs = new Map<string, ModifierActiveEntry>()\n    for (const { spec } of dependencies) {\n      const active = this.tryNewDependency(from, spec)\n      if (active) {\n        modifierRefs.set(spec.name, active)\n      }\n    }\n    return modifierRefs\n  }\n\n  /**\n   * Updates an active entry state keeping track of items in the multi-level\n   * active entries map. If the current breadcrumb state shows there's no more\n   * items left, then we deregister the modifier.\n   */\n  updateActiveEntry(from: Node, active: ModifierActiveEntry): void {\n    const { modifier } = active\n    const interactiveBreadcrumb = active.interactiveBreadcrumb.next()\n    const name = interactiveBreadcrumb.current?.name\n\n    // if there's no name, or we're done parsing then we\n    // deregister the modifier instead of updating the entry\n    if (interactiveBreadcrumb.done || !name) {\n      this.deregisterModifier(modifier)\n      return\n    }\n\n    // register the active modifier\n    this.activeModifiers.add(active)\n    active.modifier.refs.add({ from, name })\n\n    // optionally read or create the nested maps\n    const nameMap =\n      this.#activeEntries.get(modifier) ??\n      new Map<string, Map<Node, ModifierActiveEntry>>()\n    this.#activeEntries.set(modifier, nameMap)\n    const nodeMap =\n      nameMap.get(name) ?? new Map<Node, ModifierActiveEntry>()\n    nameMap.set(name, nodeMap)\n\n    // sets the active entry in the map\n    nodeMap.set(from, active)\n  }\n\n  /**\n   * Creates a new active modifier.\n   */\n  newModifier(\n    from: Node,\n    modifier: ModifierEntry,\n  ): ModifierActiveEntry {\n    return {\n      modifier,\n      interactiveBreadcrumb: modifier.breadcrumb.interactive(),\n      originalFrom: from,\n    }\n  }\n\n  /**\n   * Removes a previously registered modifier from the active entries.\n   */\n  deregisterModifier(modifier: ModifierEntry): void {\n    for (const { from, name } of modifier.refs) {\n      const nodeMap = this.#activeEntries.get(modifier)?.get(name)\n      if (nodeMap) {\n        // if an entry is found, we remove it from the active set\n        const entry = nodeMap.get(from)\n        if (entry) {\n          this.activeModifiers.delete(entry)\n        }\n        // then we remove the entry from the map\n        nodeMap.delete(from)\n        // if the map is empty, we remove it from the active entries map\n        if (!nodeMap.size) {\n          this.#activeEntries.get(modifier)?.delete(name)\n        }\n      }\n    }\n  }\n\n  /**\n   * Operates in previously registered nodes and edges in order to put\n   * back in place any of the original edges that were referenced to in\n   * active (ongoing) breadcrumb parsing entries that were never completed.\n   *\n   * This method can be used to easily rollback any pending operations\n   * once the graph traversal is done.\n   */\n  rollbackActiveEntries(): void {\n    for (const modifier of this.activeModifiers) {\n      // if the modifier has an original edge, we can put it back in place\n      if (modifier.originalEdge) {\n        modifier.originalFrom.edgesOut.set(\n          modifier.originalEdge.spec.name,\n          modifier.originalEdge,\n        )\n      }\n      // then we deregister the modifier\n      this.deregisterModifier(modifier.modifier)\n    }\n  }\n\n  /**\n   * Convenience method to instantiate and load in one call.\n   * Returns undefined if the project does not have a vlt.json file,\n   * otherwise returns the loaded Modifiers instance.\n   */\n  static maybeLoad(options: SpecOptions) {\n    const config = load('modifiers', assertRecordStringString)\n    if (!config) return\n    return new GraphModifier(options)\n  }\n\n  /**\n   * Convenience method to instantiate and load in one call.\n   * Throws if called on a directory that does not have a vlt.json file.\n   */\n  static load(options: SpecOptions) {\n    return new GraphModifier(options)\n  }\n}\n"]}

package/dist/esm/node.d.ts

@@ -1,9 +1,8 @@
 import type { PathScurry } from 'path-scurry';
 import type { DepID } from '@vltpkg/dep-id';
 import type { Spec, SpecOptions } from '@vltpkg/spec';
-import type { Integrity, Manifest, DependencyTypeShort } from '@vltpkg/types';
+import type { Integrity, NormalizedManifest, DependencyTypeShort, GraphLike, NodeLike } from '@vltpkg/types';
 import { Edge } from './edge.ts';
-import type { GraphLike, NodeLike } from './types.ts';
 export type NodeOptions = SpecOptions & {
     projectRoot: string;
     graph: GraphLike;
@@ -34,6 +33,10 @@ export declare class Node implements NodeLike {
     isDev(): this is Node & {
         dev: true;
     };
+    /**
+     * True if there's a manifest-confused package name.
+     */
+    confused: boolean;
     /**
      * List of edges coming into this node.
      */
@@ -43,6 +46,11 @@ export declare class Node implements NodeLike {
      * 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.
      */
@@ -66,7 +74,7 @@ export declare class Node implements NodeLike {
     /**
      * The manifest this node represents in the graph.
      */
-    manifest?: Manifest;
+    manifest?: NormalizedManifest;
     /**
      * Project where this node resides
      */
@@ -77,6 +85,12 @@ export declare class Node implements NodeLike {
      * 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
@@ -89,6 +103,16 @@ export declare class Node implements NodeLike {
      * 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;
+    };
     /**
      * The file system location for this node.
      */
@@ -107,13 +131,15 @@ export declare class Node implements NodeLike {
      * directly inside the node's directory.
      */
     nodeModules(scurry: PathScurry): string;
-    constructor(options: NodeOptions, id?: DepID, manifest?: Manifest, spec?: Spec, name?: string, version?: 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.
@@ -130,19 +156,42 @@ export declare class Node implements NodeLike {
      * 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;
         id: DepID;
         name: string;
         version: string | undefined;
         location: string;
         importer: boolean;
-        manifest: Manifest | undefined;
+        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;
+        } | undefined;
     };
     toString(): string;
 }
+export declare const isNode: (value: unknown) => value is Node;
+export declare const asNode: (value: unknown) => Node;
 //# sourceMappingURL=node.d.ts.map

package/dist/esm/node.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"node.d.ts","sourceRoot":"","sources":["../../src/node.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAE7C,OAAO,KAAK,EAAE,KAAK,EAAc,MAAM,gBAAgB,CAAA;AAEvD,OAAO,KAAK,EAAE,IAAI,EAAE,WAAW,EAAE,MAAM,cAAc,CAAA;AACrD,OAAO,KAAK,EACV,SAAS,EACT,QAAQ,EACR,mBAAmB,EACpB,MAAM,eAAe,CAAA;AACtB,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAA;AAChC,OAAO,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAA;AAIrD,MAAM,MAAM,WAAW,GAAG,WAAW,GAAG;IACtC,WAAW,EAAE,MAAM,CAAA;IACnB,KAAK,EAAE,SAAS,CAAA;CACjB,CAAA;AAED,qBAAa,IAAK,YAAW,QAAQ;;IACnC,IAAI,CAAC,MAAM,CAAC,WAAW,CAAC,WAEvB;IAMD;;;;;;OAMG;IACH,IAAI,QAAQ,IAGW,OAAO,CAD7B;IACD,IAAI,QAAQ,CAAC,QAAQ,EAAE,OAAO,EAS7B;IAED,UAAU,IAAI,IAAI,IAAI,IAAI,GAAG;QAAE,QAAQ,EAAE,IAAI,CAAA;KAAE;IAK/C;;;;;OAKG;IACH,IAAI,GAAG,IAGM,OAAO,CADnB;IACD,IAAI,GAAG,CAAC,GAAG,EAAE,OAAO,EASnB;IAED,KAAK,IAAI,IAAI,IAAI,IAAI,GAAG;QAAE,GAAG,EAAE,IAAI,CAAA;KAAE;IAIrC;;OAEG;IACH,OAAO,YAAkB;IAEzB;;;OAGG;IACH,QAAQ,oBAA0B;IAElC;;OAEG;IACH,EAAE,EAAE,KAAK,CAAA;IAET;;OAEG;IACH,QAAQ,UAAQ;IAEhB;;OAEG;IACH,YAAY,UAAQ;IAEpB;;OAEG;IACH,KAAK,EAAE,SAAS,CAAA;IAEhB;;OAEG;IACH,SAAS,CAAC,EAAE,SAAS,CAAA;IAErB;;OAEG;IACH,QAAQ,CAAC,EAAE,QAAQ,CAAA;IAEnB;;OAEG;IACH,WAAW,EAAE,MAAM,CAAA;IAEnB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAA;IASjB,IAAI,IAAI,WAIP;IAED;;;;;OAKG;IACH,OAAO,CAAC,EAAE,MAAM,CAAA;IAEhB;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAA;IAEjB;;OAEG;IACH,IAAI,QAAQ,IAAI,MAAM,CAQrB;IAED,IAAI,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAM5B;IAED;;OAEG;IACH,gBAAgB,CAAC,MAAM,EAAE,UAAU,GAAG,MAAM;IAI5C;;;;;;;OAOG;IACH,WAAW,CAAC,MAAM,EAAE,UAAU,GAAG,MAAM;gBAQrC,OAAO,EAAE,WAAW,EACpB,EAAE,CAAC,EAAE,KAAK,EACV,QAAQ,CAAC,EAAE,QAAQ,EACnB,IAAI,CAAC,EAAE,IAAI,EACX,IAAI,CAAC,EAAE,MAAM,EACb,OAAO,CAAC,EAAE,MAAM;IAuBlB;;;;OAIG;IACH,UAAU,IAAI,OAAO;IAkBrB,MAAM,CAAC,KAAK,EAAE,IAAI;IAIlB;;OAEG;IACH,mBAAmB,CAAC,QAAQ,EAAE,MAAM;IAKpC;;;;OAIG;IACH,WAAW;IAgBX,kBAAkB;IAclB;;OAEG;IACH,UAAU,CAAC,IAAI,EAAE,mBAAmB,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC,EAAE,IAAI;IAO7D,MAAM;;;;;;;;;;;;;IAgBN,QAAQ;CAGT"}
+{"version":3,"file":"node.d.ts","sourceRoot":"","sources":["../../src/node.ts"],"names":[],"mappings":"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"}

package/dist/esm/node.js

@@ -1,5 +1,6 @@
-import { getId, hydrateTuple, splitDepID } from '@vltpkg/dep-id';
+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 {
@@ -8,6 +9,7 @@ export class Node {
     }
     #options;
     #location;
+    #rawManifest;
     #optional = false;
     /**
      * True if a node is only reachable via optional or peerOptional edges from
@@ -57,6 +59,10 @@ export class Node {
     isDev() {
         return this.#dev;
     }
+    /**
+     * True if there's a manifest-confused package name.
+     */
+    confused = false;
     /**
      * List of edges coming into this node.
      */
@@ -66,6 +72,11 @@ export class Node {
      * 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.
      */
@@ -100,6 +111,12 @@ export class Node {
      * 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
@@ -124,6 +141,12 @@ export class Node {
      * 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;
     /**
      * The file system location for this node.
      */
@@ -201,6 +224,11 @@ export class Node {
             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;
     }
@@ -250,6 +278,33 @@ export class Node {
         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,
@@ -257,16 +312,36 @@ export class Node {
             version: this.version,
             location: this.location,
             importer: this.importer,
-            manifest: this.manifest,
+            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,
+            ...(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;
+};
 //# sourceMappingURL=node.js.map