@vltpkg/graph 1.4.0 → 1.6.0

package/README.md

@@ -78,15 +78,74 @@ minimal filesystem changes (creating/deleting links, writing
 lockfiles, hoisting, lifecycle scripts) to make the on-disk install
 match the Ideal graph. Returns `{ diff, buildQueue }`.
 
-### `install(options, add?): Promise<{ graph, diff, buildQueue }>`
+### `install(options, add?): Promise<{ graph, diff, buildQueue, skills? }>`
 
 High-level install orchestration that handles graph building, reify,
 and lockfile management. Supports `--frozen-lockfile`,
-`--clean-install`, and `--lockfile-only` modes.
+`--clean-install`, and `--lockfile-only` modes. With `allowSkills` (a
+DSS query whose selectors may end with `:skill()`, validated up
+front), links the agent skills of matching packages afterwards (see
+`linkSkills`) into `skillsDirs` (unset: detected) and returns the
+result as `skills`. Unset or `:not(*)`: no skills work, the skills
+code is not loaded. `update` and `uninstall` take `allowSkills` too.
+
+### `listSkills(options): Promise<{ project, graph, skills, dirs, skipped? }>`
+
+Lists the agent skills (dirs with a `SKILL.md`, see
+https://agentskills.io/specification) shipped by installed packages in
+the vlt store and the project's workspaces (a root `SKILL.md`, then
+`<dir>/SKILL.md` in `skills/`, `dist/skills/` and `.agents/skills/`;
+the first skill of a name wins), from one version per package (a
+direct dep or workspace, else the highest), with the agent skill dirs
+each is linked in, `project`: the main importer name, and the `graph`.
+`options.target` is a DSS query selecting packages (default `*`); a
+selector ending with `:skill(<name>, …)` keeps only those skills of
+its packages. Creates nothing.
+
+### `linkSkills(options): Promise<LinkSkillsResult>`
+
+Links the skills picked by `options.target` (as in `listSkills`; comma
+lists are a union) into each agent skill dir (junctions on Windows):
+`options.skillsDirs`, else `.agents/skills`, plus `<folder>/skills`
+for each agent folder at the project root, `.claude/skills` inside
+Claude Code (`options.env`), and existing `.<name>/skills` dirs. Dirs
+must resolve inside the project, not in `node_modules` (else
+`skipped`, as are fs errors) and are created only when a skill is
+picked. One package per name, among picked skills, in every dir: the
+one the first existing link points to while its skill is installed,
+else a direct dep or workspace, then DepID; the others are reported in
+`conflicts` as `<mount> (<package>)`. Installs keep a dir's link to
+another installed skill. A link follows its package to the picked
+version. Then removes links whose skill is no longer installed:
+dangling, package not in the graph, or no longer shipped. With
+`options.apply`, also removes every other vlt link in the scanned
+dirs. Only vlt links (into a `node_modules/.vlt` store, or listed in
+the dir's `.gitignore` block and pointing to a workspace or dangling)
+are ever replaced or removed; anything else in the way is reported in
+`conflicts`. Keeps a marked block of link names in each dir's
+`.gitignore` (`gitignore` lists the ones it could not edit). Linked
+packages get private copies of files hardlinked from the global store.
+`:skill()` patterns that match no skill of their packages are returned
+in `unmatched`. Security queries fail closed: skills of npm registry
+packages with no security data are left out (in `listSkills` too) and
+returned in `unscanned` with `unscannedReason` (by `linkSkills`:
+unless still linked).
+
+### `assertQuery(selector, flag, partSelectors?): Promise<void>`
+
+Throws `EUSAGE` unless `selector` is a valid DSS query.
+`partSelectors` (e.g. `['skill']`) allows `:skill()`.
+
+### `hasSkills(node): Promise<boolean>`
+
+`:skills` provider for `Query`: true when an installed package ships
+agent skills, as `listSkills` finds them.
 
 ### `mermaidOutput(graph): string`
 
-Generates Mermaid flowchart syntax from graph data.
+Generates Mermaid flowchart syntax from graph data. `graph.children`
+(`Map<DepID, { label, edge? }[]>`) draws leaves under nodes, e.g.
+`vlt skills list` skills.
 
 ### `humanReadableOutput(graph, options): string`
 

package/dist/actual/load.js

@@ -2,7 +2,7 @@ import { asDepID, hydrate, joinDepIDTuple, joinExtra, splitDepID, splitExtra, }
 import { Spec } from '@vltpkg/spec';
 import { graphStep } from '@vltpkg/output';
 import { isObject } from '@vltpkg/types';
-import { shorten, getRawDependencies, getDependencies, } from "../dependencies.js";
+import { shorten, getRawDependencies, getDependencies, asDependencySpecError, } from "../dependencies.js";
 import { Graph } from "../graph.js";
 import { loadHidden } from "../lockfile/load.js";
 import { saveHidden } from "../lockfile/save.js";
@@ -178,13 +178,19 @@ const parseDir = (options, scurry, packageJson, depsFound, graph, fromNode, curr
             const type = deps?.type || 'dependencies';
             const bareSpec = deps?.bareSpec || '*';
             const depType = shorten(type, alias, fromNode.manifest);
-            let spec = Spec.parse(alias, bareSpec, {
-                ...options,
-                // fall back to options.registry (which the lockfile merges into)
-                // so importer-level edges don't silently revert to the default
-                // npm registry. see vltpkg/vltpkg#1580.
-                registry: fromNode.registry ?? options.registry,
-            });
+            let spec;
+            try {
+                spec = Spec.parse(alias, bareSpec, {
+                    ...options,
+                    // fall back to options.registry (which the lockfile merges into)
+                    // so importer-level edges don't silently revert to the default
+                    // npm registry. see vltpkg/vltpkg#1580.
+                    registry: fromNode.registry ?? options.registry,
+                });
+            }
+            catch (er) {
+                throw asDependencySpecError(er, fromNode, depType);
+            }
             // Check for active modifiers and replace spec if a modifier is complete
             const { spec: modifiedSpec, queryModifier } = maybeApplyModifierToSpec(spec, alias, modifierRefs);
             spec = modifiedSpec;
@@ -240,10 +246,16 @@ const parseDir = (options, scurry, packageJson, depsFound, graph, fromNode, curr
     for (const { name, type, bareSpec } of dependencies.values()) {
         if (!seenDeps.has(name)) {
             const depType = shorten(type, name, fromNode.manifest);
-            let spec = Spec.parse(name, bareSpec, {
-                ...options,
-                registry: fromNode.registry ?? options.registry,
-            });
+            let spec;
+            try {
+                spec = Spec.parse(name, bareSpec, {
+                    ...options,
+                    registry: fromNode.registry ?? options.registry,
+                });
+            }
+            catch (er) {
+                throw asDependencySpecError(er, fromNode, depType);
+            }
             // Check for active modifiers and replace spec for missing dependencies
             const { spec: modifiedSpec, queryModifier } = maybeApplyModifierToSpec(spec, name, modifierRefs);
             // a `-` modifier removes the dependency, so it is not missing

package/dist/build.js

@@ -4,10 +4,12 @@ import { build as reifyBuild } from "./reify/build.js";
 import { Diff } from "./diff.js";
 import { Graph } from "./graph.js";
 import { Query } from '@vltpkg/query';
-import { SecurityArchive } from '@vltpkg/security-archive';
+import { SecurityArchive, usesNpmRegistry, } from '@vltpkg/security-archive';
 import { saveHidden } from "./lockfile/save.js";
+import { hasSkills } from "./skills/lazy.js";
 /**
- * Filter nodes using a DSS query string
+ * Filter nodes using a DSS query string. `skipped` holds matched nodes
+ * left out because they have no security data, `skippedReason` says why.
  */
 const filterNodesByQuery = async (targetQuery, graph) => {
     /* c8 ignore start */
@@ -25,11 +27,30 @@ const filterNodesByQuery = async (targetQuery, graph) => {
         nodes,
         importers,
         securityArchive,
+        hasSkills,
     });
     const { nodes: resultNodes } = await query.search(targetQuery, {
         signal: new AbortController().signal,
     });
-    return new Set(resultNodes.map(node => node.id));
+    // fail closed: never run scripts of pkgs with no security data, be it
+    // from a timed out request or not scanned by socket.dev yet
+    const allowed = new Set();
+    const skipped = new Set();
+    for (const node of resultNodes) {
+        if (securityArchive &&
+            !securityArchive.has(node.id) &&
+            usesNpmRegistry(node)) {
+            skipped.add(node.id);
+        }
+        else {
+            allowed.add(node.id);
+        }
+    }
+    return {
+        allowed,
+        skipped,
+        skippedReason: securityArchive?.timedOut ? 'timeout' : 'unscanned',
+    };
 };
 /**
  * Build the project based on actual graph state and build state from lockfile
@@ -54,7 +75,7 @@ export const build = async (options) => {
         loadManifests: true,
     });
     // Filter nodes using target query provided
-    const targetFilteredNodes = await filterNodesByQuery(target, actualGraph);
+    const { allowed: targetFilteredNodes, skipped, skippedReason, } = await filterNodesByQuery(target, actualGraph);
     // Create a total diff including the actual graph as 'to'
     const diff = new Diff(new Graph({
         ...options,
@@ -83,5 +104,9 @@ export const build = async (options) => {
             graph: actualGraph,
         });
     }
-    return buildResult;
+    // needed builds left out for lack of security data
+    const skippedNodes = [...diff.nodes.add].filter(node => skipped.has(node.id));
+    return skippedNodes.length ?
+        { ...buildResult, skipped: skippedNodes, skippedReason }
+        : buildResult;
 };

package/dist/dependencies.d.ts

@@ -74,6 +74,17 @@ export declare const shorten: (typeLong: DependencyTypeLong, name?: string, mani
  */
 export declare const shouldInstallDepType: (node: NodeLike, depType: DependencyTypeLong) => boolean;
 export declare const getRawDependencies: (node: NodeLike) => Map<string, RawDependency>;
+/**
+ * Maps short dependency types to the `package.json` field declaring them.
+ */
+export declare const longDependencyTypeNames: Record<DependencyTypeShort, DependencyTypeLong>;
+/**
+ * Point an `ECONFIG` spec error (eg: an undefined `catalog:`) at the
+ * package.json & dependency type that declared it. `source` names the
+ * file the spec was read from when not the manifest (eg: a lockfile).
+ * Other values are returned as is.
+ */
+export declare const asDependencySpecError: (er: unknown, from: NodeLike, type: DependencyTypeShort, source?: string) => unknown;
 /**
  * Retrieves a map of all dependencies, of all types, that can be inferred
  * from a given node manifest, including missing dependencies.

package/dist/dependencies.js

@@ -1,6 +1,6 @@
 import { error } from '@vltpkg/error-cause';
 import { Spec } from '@vltpkg/spec/browser';
-import { dependencyTypes, longDependencyTypes, shortDependencyTypes, } from '@vltpkg/types';
+import { isErrorWithCause, isObject, dependencyTypes, longDependencyTypes, shortDependencyTypes, } from '@vltpkg/types';
 export const isDependencyTypeShort = (obj) => shortDependencyTypes.has(obj);
 export const isDependencySaveType = (obj) => shortDependencyTypes.has(obj) ||
     obj === 'implicit';
@@ -113,6 +113,40 @@ export const getRawDependencies = (node) => {
     }
     return dependencies;
 };
+/**
+ * Maps short dependency types to the `package.json` field declaring them.
+ */
+export const longDependencyTypeNames = {
+    prod: 'dependencies',
+    dev: 'devDependencies',
+    optional: 'optionalDependencies',
+    peer: 'peerDependencies',
+    peerOptional: 'peerDependencies',
+};
+// `./`-relative unless already relative or absolute
+const manifestPath = ({ location = '.' }) => `${/^(?:\.\.?(?:\/|$)|\/|[a-z]:)/i.test(location) ? '' : './'}${location}/package.json`;
+/**
+ * Point an `ECONFIG` spec error (eg: an undefined `catalog:`) at the
+ * package.json & dependency type that declared it. `source` names the
+ * file the spec was read from when not the manifest (eg: a lockfile).
+ * Other values are returned as is.
+ */
+export const asDependencySpecError = (er, from, type, source) => {
+    if (!isErrorWithCause(er) ||
+        !isObject(er.cause) ||
+        er.cause.code !== 'ECONFIG') {
+        return er;
+    }
+    const pj = manifestPath(from);
+    const depType = longDependencyTypeNames[type];
+    return error(er.message, {
+        ...er.cause,
+        from: source ?
+            `${source} (${pj} ${depType})`
+            : `${pj} (${depType})`,
+        cause: er,
+    }, asDependencySpecError);
+};
 /**
  * Retrieves a map of all dependencies, of all types, that can be inferred
  * from a given node manifest, including missing dependencies.
@@ -122,12 +156,18 @@ export const getDependencies = (node, options) => {
     const dependencies = getRawDependencies(node);
     for (const { name, type, bareSpec } of dependencies.values()) {
         const depType = shorten(type, name, node.manifest);
-        const spec = Spec.parse(name, bareSpec, {
-            ...options,
-            // fall back to options.registry so deps don't lose the configured
-            // registry when the node itself has none. see vltpkg/vltpkg#1580.
-            registry: node.registry ?? options.registry,
-        });
+        let spec;
+        try {
+            spec = Spec.parse(name, bareSpec, {
+                ...options,
+                // fall back to options.registry so deps don't lose the configured
+                // registry when the node itself has none. see vltpkg/vltpkg#1580.
+                registry: node.registry ?? options.registry,
+            });
+        }
+        catch (er) {
+            throw asDependencySpecError(er, node, depType);
+        }
         res.set(name, {
             spec,
             type: depType,

package/dist/filter-nodes-by-query.d.ts

@@ -0,0 +1,39 @@
+import type { QueryOptions } from '@vltpkg/query';
+import type { DepID } from '@vltpkg/dep-id';
+import type { Graph } from './graph.ts';
+/**
+ * One top-level selector of a query: the ids it matched, and its
+ * `:skill()` patterns (unset: every skill).
+ */
+export type QueryPartIds = {
+    ids: Set<DepID>;
+    patterns?: string[];
+};
+/**
+ * Matched npm registry pkgs with no security data, and why: the
+ * request timed out, or socket.dev has not scanned them yet.
+ */
+export type Unscanned = {
+    ids: Set<DepID>;
+    reason: 'timeout' | 'unscanned';
+};
+/**
+ * Filter nodes using a DSS query string
+ */
+export declare const filterNodesByQuery: (graph: Graph, selector?: string) => Promise<Set<DepID>>;
+/**
+ * {@link filterNodesByQuery} for `allow-skills`: accepts `:skill()`,
+ * and also returns one entry per top-level selector. Unlike it, keeps
+ * `unscanned` pkgs: callers must drop them (fail closed).
+ */
+export declare const filterNodesByQueryParts: (graph: Graph, selector?: string) => Promise<{
+    ids: Set<DepID>;
+    parts: QueryPartIds[];
+    unscanned?: Unscanned;
+}>;
+/**
+ * Throw `EUSAGE` unless `selector` is a valid DSS query. Runs it on an
+ * empty graph: no fs, network or security data needed. `partSelectors`
+ * allows e.g. `:skill()`.
+ */
+export declare const assertQuery: (selector: string, flag: string, partSelectors?: QueryOptions["partSelectors"]) => Promise<void>;

package/dist/filter-nodes-by-query.js

@@ -0,0 +1,100 @@
+import { error } from '@vltpkg/error-cause';
+import { Query } from '@vltpkg/query';
+import { SecurityArchive, usesNpmRegistry, } from '@vltpkg/security-archive';
+import { asError } from '@vltpkg/types';
+import { hasSkills } from "./skills/lazy.js";
+const toIds = (nodes) => new Set(nodes.map(n => n.id));
+const search = async (graph, selector, partSelectors) => {
+    /* c8 ignore start */
+    const securityArchive = Query.hasSecuritySelectors(selector) ?
+        await SecurityArchive.start({
+            nodes: [...graph.nodes.values()],
+        })
+        : undefined;
+    /* c8 ignore stop */
+    const res = await new Query({
+        edges: graph.edges,
+        nodes: new Set(graph.nodes.values()),
+        importers: graph.importers,
+        securityArchive,
+        hasSkills,
+        partSelectors,
+    }).search(selector, { signal: new AbortController().signal });
+    if (!securityArchive)
+        return res;
+    // fail closed: callers skip pkgs with no security data, be it from a
+    // timed out request or not scanned by socket.dev yet
+    const ids = toIds(res.nodes.filter(n => !securityArchive.has(n.id) && usesNpmRegistry(n)));
+    if (!ids.size)
+        return res;
+    const reason = securityArchive.timedOut ? 'timeout' : 'unscanned';
+    return { ...res, unscanned: { ids, reason } };
+};
+/**
+ * Filter nodes using a DSS query string
+ */
+export const filterNodesByQuery = async (graph, selector) => {
+    // shortcut no packages included
+    if (selector === ':not(*)' /* c8 ignore next */ || !selector) {
+        return new Set();
+    }
+    // shortcut all packages included
+    if (selector === '*') {
+        return new Set(graph.nodes.keys());
+    }
+    const { nodes, unscanned } = await search(graph, selector);
+    return toIds(nodes.filter(n => !unscanned?.ids.has(n.id)));
+};
+/**
+ * {@link filterNodesByQuery} for `allow-skills`: accepts `:skill()`,
+ * and also returns one entry per top-level selector. Unlike it, keeps
+ * `unscanned` pkgs: callers must drop them (fail closed).
+ */
+export const filterNodesByQueryParts = async (graph, selector) => {
+    if (!selector || selector === ':not(*)') {
+        return { ids: new Set(), parts: [] };
+    }
+    if (selector === '*') {
+        const ids = new Set(graph.nodes.keys());
+        return { ids, parts: [{ ids }] };
+    }
+    const res = await search(graph, selector, ['skill']);
+    return {
+        ids: toIds(res.nodes),
+        /* c8 ignore next -- always set when opted in */
+        parts: (res.parts ?? []).map(p => ({
+            ids: toIds(p.nodes),
+            ...(p.patterns && { patterns: p.patterns }),
+        })),
+        ...(res.unscanned && { unscanned: res.unscanned }),
+    };
+};
+/**
+ * Throw `EUSAGE` unless `selector` is a valid DSS query. Runs it on an
+ * empty graph: no fs, network or security data needed. `partSelectors`
+ * allows e.g. `:skill()`.
+ */
+export const assertQuery = async (selector, flag, partSelectors) => {
+    try {
+        await new Query({
+            edges: new Set(),
+            nodes: new Set(),
+            importers: new Set(),
+            securityArchive: new Map(),
+            hasSkills,
+            partSelectors,
+        }).search(selector, { signal: new AbortController().signal });
+    }
+    catch (cause) {
+        const { message, cause: c } = asError(cause);
+        // a typo's suggestions, e.g. `:skill` for `:skills`
+        const validOptions = c?.validOptions ??
+            (c?.wanted === undefined ? undefined : [c.wanted]);
+        throw error(`Invalid --${flag} query: ${message}`, {
+            code: 'EUSAGE',
+            found: selector,
+            cause,
+            ...(validOptions && { validOptions }),
+        }, assertQuery);
+    }
+};

package/dist/graph.js

@@ -347,6 +347,9 @@ export class Graph {
                 }
                 return edge;
             }
+            // a stale edgesIn ref would let removing the old target drop
+            // the new edge from `from.edgesOut`
+            edge.to?.edgesIn.delete(edge);
             this.edges.delete(edge);
         }
         this.mutations++;

package/dist/ideal/append-nodes.js

@@ -5,7 +5,7 @@ import { satisfies } from '@vltpkg/satisfies';
 import { parse as parseVersion } from '@vltpkg/semver';
 import { longDependencyTypes, normalizeManifest } from '@vltpkg/types';
 import { fixupAddedNames } from "../fixup-added-names.js";
-import { addKey, shorten, shouldInstallDepType, } from "../dependencies.js";
+import { addKey, asDependencySpecError, shorten, shouldInstallDepType, } from "../dependencies.js";
 import { removeOptionalSubgraph } from "../remove-optional-subgraph.js";
 import { isPathSecurityError } from "../path-security-error.js";
 import { extractNode } from "../reify/extract-node.js";
@@ -419,7 +419,7 @@ const fetchManifestsForDeps = async (packageInfo, graph, fromNode, deps, scurry,
  * vlt store are extracted immediately (in parallel) instead of waiting for
  * the full ideal graph to be built. This significantly improves install time.
  */
-const processPlacementTasks = async (graph, options, placementTasks, add, modifiers, scurry, packageInfo, extractPromises, actual, seenExtracted, remover, transientAdd, transientRemove) => {
+const processPlacementTasks = async (graph, options, placementTasks, add, modifiers, scurry, packageInfo, extractPromises, actual, seenExtracted, remover, transientAdd, transientRemove, explicit) => {
     const childDepsToProcess = [];
     // Note: placementTasks are already sorted by fetchManifestsForDeps
     // using compareByHasPeerDeps to ensure non-peer deps are processed first.
@@ -431,18 +431,31 @@ const processPlacementTasks = async (graph, options, placementTasks, add, modifi
         // reify step to properly update the package.json file dependencies
         // using the correct names retrieved from the manifest data
         const additiveMap = fromNode.importer ? add : transientAdd?.get(fromNode.id);
+        // a nameless explicit add is known by its fixed up name from here on
+        const explicitKeys = explicit?.get(fromNode.id);
+        const wasExplicit = explicitKeys?.has(addKey(spec));
         spec = fixupAddedNames(additiveMap, manifest, options, spec);
+        if (wasExplicit)
+            explicitKeys?.add(spec.name);
         // handles missing manifest resolution
         if (!manifest) {
             if (!edgeOptional && fromNode.isOptional()) {
                 // failed resolution of a non-optional dep of an optional node
                 // have to clean up the dependents
-                removeOptionalSubgraph(graph, fromNode);
+                for (const n of removeOptionalSubgraph(graph, fromNode)) {
+                    // pruned importer deps: nothing to save, unless requested
+                    for (const { from, name } of n.edgesIn) {
+                        if (from.importer && !explicit?.get(from.id)?.has(name)) {
+                            add?.delete(name);
+                        }
+                    }
+                }
                 continue;
             }
             else if (edgeOptional) {
-                // failed resolution of an optional dep, just ignore it,
-                // nothing to prune because we never added it in the first place.
+                // failed resolution of an optional dep: skip it and drop it
+                // from the add map, nothing to prune or save
+                additiveMap?.delete(addKey(spec));
                 continue;
             }
             else {
@@ -549,15 +562,20 @@ const processPlacementTasks = async (graph, options, placementTasks, add, modifi
                     // might need to skip already placed peer deps here
                     if (bundled.has(name))
                         continue;
-                    const dep = {
-                        type: shorten(depTypeName, name, manifest),
-                        spec: Spec.parse(name, bareSpec, {
+                    const type = shorten(depTypeName, name, manifest);
+                    let depSpec;
+                    try {
+                        depSpec = Spec.parse(name, bareSpec, {
                             ...options,
                             // git/file/remote parents have no spec.registry, so fall
                             // back to the configured one. see vltpkg/vltpkg#1580.
                             registry: spec.registry ?? options.registry,
-                        }),
-                    };
+                        });
+                    }
+                    catch (er) {
+                        throw asDependencySpecError(er, node, type);
+                    }
+                    const dep = { type, spec: depSpec };
                     if (depTypeName === 'peerDependencies') {
                         nextPeerDeps.set(name, dep);
                     }
@@ -733,7 +751,7 @@ export const appendNodes = async (packageInfo, graph, fromNode, deps, scurry, op
                 graph.addEdge(type, spec, fromNode, toNode);
             }
             // Place nodes and collect child deps
-            const placed = await processPlacementTasks(graph, options, result.placementTasks, add, modifiers, scurry, packageInfo, extractPromises, actual, seenExtracted, remover, transientAdd, transientRemove);
+            const placed = await processPlacementTasks(graph, options, result.placementTasks, add, modifiers, scurry, packageInfo, extractPromises, actual, seenExtracted, remover, transientAdd, transientRemove, explicit);
             levelResults.push(placed);
         }
         // ============================================================

package/dist/ideal/get-importer-specs.js

@@ -1,5 +1,5 @@
 import { longDependencyTypes } from '@vltpkg/types';
-import { shorten, asDependency } from "../dependencies.js";
+import { shorten, asDependency, asDependencySpecError, } from "../dependencies.js";
 import { removeSatisfiedSpecs } from "./remove-satisfied-specs.js";
 import { Spec } from '@vltpkg/spec';
 const hasDepName = (importer, edge) => {
@@ -72,7 +72,13 @@ export const getImporterSpecs = (options) => {
                 edge.type === type) {
                 continue;
             }
-            const spec = Spec.parse(depName, depSpec, options);
+            let spec;
+            try {
+                spec = Spec.parse(depName, depSpec, options);
+            }
+            catch (er) {
+                throw asDependencySpecError(er, importer, type);
+            }
             // a `-` modifier removes this dependency, nothing to place; an
             // edge from before (e.g. a qualifier now matching) has to go
             if (options.modifiers?.removesImporterEdge(importer, spec)) {
@@ -137,11 +143,15 @@ export const getImporterSpecs = (options) => {
                     if (edge?.to && edge.spec.bareSpec === depSpec)
                         continue;
                     // add the dependency to the addDeps map
-                    const dependency = asDependency({
-                        spec: Spec.parse(depName, depSpec, options),
-                        type: shorten(depType, depName, manifest),
-                    });
-                    addDeps.set(depName, dependency);
+                    const type = shorten(depType, depName, manifest);
+                    let spec;
+                    try {
+                        spec = Spec.parse(depName, depSpec, options);
+                    }
+                    catch (er) {
+                        throw asDependencySpecError(er, node, type);
+                    }
+                    addDeps.set(depName, asDependency({ spec, type }));
                 }
             }
             // store in transientAdd if there are any dependencies

package/dist/ideal/remove-satisfied-specs.js

@@ -31,18 +31,26 @@ export const removeSatisfiedSpecs = ({ add, graph, modifiers, }) => {
             const depIsCatalog = dependency.spec.type === 'catalog';
             if (edgeIsCatalog !== depIsCatalog)
                 continue;
+            // a governed edge is checked against the modifier value (e.g.
+            // `workspace:*` to a versionless workspace), not its own spec: one
+            // built before the modifier applied must be rebuilt
+            const mod = modifiers?.importerEdgeModifier(importer, dependency.spec);
             // If the current graph edge is already valid, then we remove that
             // dependency item from the list of items to be added to the graph
-            if (satisfies(edge.to?.id, dependency.spec, edge.from.location, graph.projectRoot, graph.monorepo)) {
-                // a governed edge carries the modifier value by construction:
-                // healing it to the manifest text would only be undone by the
-                // rebuild that re-applies the override. `implicit` is not a real
-                // edge type, it means "keep what the edge already is", so it
-                // never makes an edge stale
-                if ((edge.spec.bareSpec !== dependency.spec.bareSpec ||
-                    (dependency.type !== 'implicit' &&
-                        edge.type !== dependency.type)) &&
-                    !modifiers?.targetsImporterEdge(importer, dependency.spec)) {
+            if (satisfies(edge.to?.id, mod?.type === 'edge' ? mod.spec : dependency.spec, edge.from.location, graph.projectRoot, graph.monorepo)) {
+                // `implicit` is not a real edge type, it means "keep what the
+                // edge already is", so it never makes an edge stale
+                const typeChanged = dependency.type !== 'implicit' &&
+                    edge.type !== dependency.type;
+                if (mod) {
+                    // keeps the modifier value, the rebuild would re-apply it
+                    // anyway; only the type follows the manifest
+                    if (typeChanged) {
+                        staleSpecs.set(edge, { ...dependency, spec: edge.spec });
+                    }
+                }
+                else if (edge.spec.bareSpec !== dependency.spec.bareSpec ||
+                    typeChanged) {
                     staleSpecs.set(edge, dependency);
                 }
                 dependencies.delete(name);

package/dist/index.d.ts

@@ -15,6 +15,9 @@ export * from './update.ts';
 export * from './diff.ts';
 export * from './modifiers.ts';
 export * from './virtual-root.ts';
+export type { DiscoveredSkills, LinkSkillsOptions, LinkSkillsResult, ListSkillsResult, MountResult, Skill, SkillFrontmatter, SkillMount, SkillRow, SkillsDir, SkillsOptions, UnmatchedPattern, UnscannedSkills, } from './skills/index.ts';
+export { hasSkills, linkSkills, listSkills } from './skills/lazy.ts';
+export { assertQuery } from './filter-nodes-by-query.ts';
 import type { LoadOptions as ActualLoadOptions } from './actual/load.ts';
 export declare const actual: {
     load: (options: ActualLoadOptions) => import("./graph.ts").Graph;

package/dist/index.js

@@ -15,6 +15,8 @@ export * from "./update.js";
 export * from "./diff.js";
 export * from "./modifiers.js";
 export * from "./virtual-root.js";
+export { hasSkills, linkSkills, listSkills } from "./skills/lazy.js";
+export { assertQuery } from "./filter-nodes-by-query.js";
 import { load as actualLoad } from "./actual/load.js";
 export const actual = { load: actualLoad };
 import { load as lockfileLoad, loadData as lockfileLoadData, } from "./lockfile/load.js";