@vltpkg/graph 0.0.0-13 → 0.0.0-15

package/dist/esm/modifiers.d.ts

@@ -0,0 +1,199 @@
+import { Spec } from '@vltpkg/spec';
+import type { ModifierBreadcrumb, ModifierInteractiveBreadcrumb } from '@vltpkg/dss-breadcrumb';
+import type { SpecOptions } from '@vltpkg/spec';
+import type { Manifest } from '@vltpkg/types';
+import type { Edge } from './edge.ts';
+import type { Node } from './node.ts';
+import type { Dependency } from './dependencies.ts';
+/**
+ * Loaded modifiers configuration as described in the `vlt.json` file.
+ */
+export type GraphModifierLoadedConfig = {
+    modifiers: GraphModifierConfigObject;
+};
+/**
+ * Type definition for the modifiers configuration object
+ */
+export type GraphModifierConfigObject = Record<string, string>;
+/**
+ * Info needed to define a graph modifier.
+ */
+export type BaseModifierEntry = {
+    type: 'edge' | 'node';
+    query: string;
+    breadcrumb: ModifierBreadcrumb;
+    value: string | Manifest;
+    refs: Set<{
+        name: string;
+        from: Node;
+    }>;
+};
+/**
+ * Extra info to define specifically a graph edge modifier.
+ */
+export type EdgeModifierEntry = BaseModifierEntry & {
+    type: 'edge';
+    spec: Spec;
+    value: string;
+};
+/**
+ * Extra info to define the graph node modifier.
+ */
+export type NodeModifierEntry = BaseModifierEntry & {
+    type: 'node';
+    manifest: Manifest;
+};
+/**
+ * A graph modifier entry, which can be either an edge or a node modifier.
+ */
+export type ModifierEntry = EdgeModifierEntry | NodeModifierEntry;
+/**
+ * An object to track modifiers that have matched an initial part of the
+ * breadcrumb. It holds pointers to both nodes and edges matched in the
+ * current traversed graph on top of the modifier info and the breadcrumb
+ * state that is used to track the current state of the parsing.
+ */
+export type ModifierActiveEntry = {
+    /**
+     * The modifier this active entry is working with.
+     */
+    modifier: ModifierEntry;
+    /**
+     * The breadcrumb that is used to track the current state of the parsing.
+     */
+    interactiveBreadcrumb: ModifierInteractiveBreadcrumb;
+    /**
+     * The first node to be affected by this modifier.
+     */
+    originalFrom: Node;
+    /**
+     * The original edge that is being replaced with this entry.
+     */
+    originalEdge?: Edge;
+    /**
+     * The modified edge that is being used to replace the original edge.
+     */
+    modifiedEdge?: Edge;
+};
+/**
+ * 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 name to the current traversed node has matching
+ * registered modifiers, e.g:
+ * `const entries = modifier.tryNewDependency(fromNode, depName)`
+ *
+ * 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 declare class GraphModifier {
+    #private;
+    /**
+     * A set of currently active modifiers, which are being parsed.
+     */
+    activeModifiers: Set<ModifierActiveEntry>;
+    constructor(options: SpecOptions);
+    /**
+     * Load the modifiers definitions from vlt.json,
+     * converting the result into a GraphModifierConfigObject
+     */
+    get config(): GraphModifierConfigObject;
+    /**
+     * Loads the modifiers defined in `vlt.json` into memory.
+     */
+    load(options: SpecOptions): void;
+    /**
+     * Check if a given importer dependency name has potentially a registered
+     * modifier. In case of an ambiguous modifier, the method will always
+     * return `true`, it only returns `false` in the case that only fully
+     * qualified modifiers are registered and none are targeting the given
+     * top-level dependency name.
+     *
+     * This method is useful to help avoiding traversing the sub graph of
+     * a direct dependency when we know that it's impossible to ever match
+     * beforehand.
+     */
+    maybeHasModifier(depName: string): boolean;
+    /**
+     * 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: Node): void;
+    /**
+     * Try matching the provided node and dependency name 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: Node, name: string): ModifierActiveEntry | undefined;
+    /**
+     * 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: Node, dependencies: Dependency[]): Map<string, ModifierActiveEntry>;
+    /**
+     * 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: Node, active: ModifierActiveEntry): void;
+    /**
+     * Creates a new active modifier.
+     */
+    newModifier(from: Node, modifier: ModifierEntry): ModifierActiveEntry;
+    /**
+     * Removes a previously registered modifier from the active entries.
+     */
+    deregisterModifier(modifier: ModifierEntry): void;
+    /**
+     * 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(): void;
+    /**
+     * 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: SpecOptions): GraphModifier | undefined;
+    /**
+     * 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: SpecOptions): GraphModifier;
+}
+//# sourceMappingURL=modifiers.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"modifiers.d.ts","sourceRoot":"","sources":["../../src/modifiers.ts"],"names":[],"mappings":"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"}

package/dist/esm/modifiers.js

@@ -0,0 +1,342 @@
+import { parseBreadcrumb, specificitySort, } from '@vltpkg/dss-breadcrumb';
+import { error } from '@vltpkg/error-cause';
+import { Spec } from '@vltpkg/spec';
+import { asManifest, assertRecordStringString } 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 name to the current traversed node has matching
+ * registered modifiers, e.g:
+ * `const entries = modifier.tryNewDependency(fromNode, depName)`
+ *
+ * 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();
+    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)) {
+            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 = asManifest(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);
+            }
+        }
+    }
+    /**
+     * Check if a given importer dependency name has potentially a registered
+     * modifier. In case of an ambiguous modifier, the method will always
+     * return `true`, it only returns `false` in the case that only fully
+     * qualified modifiers are registered and none are targeting the given
+     * top-level dependency name.
+     *
+     * This method is useful to help avoiding traversing the sub graph of
+     * a direct dependency when we know that it's impossible to ever match
+     * beforehand.
+     */
+    maybeHasModifier(depName) {
+        for (const mod of this.#modifiers) {
+            const matchingName = mod.breadcrumb.first.importer &&
+                mod.breadcrumb.first.next?.name === depName;
+            const rootlessBreadcrumb = !mod.breadcrumb.first.importer;
+            if (rootlessBreadcrumb || matchingName) {
+                return true;
+            }
+        }
+        return false;
+    }
+    /**
+     * 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 dependency name 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, name) {
+        // 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.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.name);
+            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 { asManifest, assertRecordStringString } 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 { Manifest } 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 | Manifest\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: Manifest\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 name to the current traversed node has matching\n * registered modifiers, e.g:\n * `const entries = modifier.tryNewDependency(fromNode, depName)`\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\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      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 = asManifest(value)\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   * Check if a given importer dependency name has potentially a registered\n   * modifier. In case of an ambiguous modifier, the method will always\n   * return `true`, it only returns `false` in the case that only fully\n   * qualified modifiers are registered and none are targeting the given\n   * top-level dependency name.\n   *\n   * This method is useful to help avoiding traversing the sub graph of\n   * a direct dependency when we know that it's impossible to ever match\n   * beforehand.\n   */\n  maybeHasModifier(depName: string): boolean {\n    for (const mod of this.#modifiers) {\n      const matchingName =\n        mod.breadcrumb.first.importer &&\n        mod.breadcrumb.first.next?.name === depName\n      const rootlessBreadcrumb = !mod.breadcrumb.first.importer\n      if (rootlessBreadcrumb || matchingName) {\n        return true\n      }\n    }\n    return false\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 dependency name 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    name: string,\n  ): ModifierActiveEntry | undefined {\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(entries.map(i => i.modifier.breadcrumb))[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[],\n  ): Map<string, ModifierActiveEntry> {\n    const modifierRefs = new Map<string, ModifierActiveEntry>()\n    for (const { spec } of dependencies) {\n      const active = this.tryNewDependency(from, spec.name)\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

@@ -81,6 +81,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
@@ -157,6 +163,7 @@ export declare class Node implements NodeLike {
         dev: boolean;
         optional: boolean;
         confused: boolean;
+        modifier: string | undefined;
     };
     toString(): string;
 }

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

@@ -1 +1 @@
-{"version":3,"file":"node.d.ts","sourceRoot":"","sources":["../../src/node.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"node.d.ts","sourceRoot":"","sources":["../../src/node.ts"],"names":[],"mappings":"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"}

package/dist/esm/node.js

@@ -105,6 +105,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
@@ -294,6 +300,7 @@ export class Node {
             dev: this.dev,
             optional: this.optional,
             confused: this.confused,
+            modifier: this.modifier,
             ...(this.confused ?
                 { rawManifest: this.#rawManifest }
                 : undefined),