@skill-map/cli 0.21.0 → 0.22.0

package/dist/kernel/index.d.ts

@@ -759,55 +759,6 @@ interface IExtensionBase {
     viewContributions?: Record<string, IViewContribution>;
 }
 
-/**
- * `.skillmapignore` parser + filter facade. Wraps `ignore` (kaelzhang)
- * with the project-local layering: bundled defaults → `config.ignore`
- * (from `.skill-map/settings.json`) → `.skillmapignore` file content.
- *
- * Why a wrapper instead of exposing `ignore` directly:
- *
- * 1. Single-source defaults — `src/config/defaults/skillmapignore` is
- *    the canonical default list, loaded once at module init (or at
- *    explicit build time, depending on bundling). The runtime never
- *    re-reads it per scan.
- * 2. Stable interface — Providers and the orchestrator depend on a
- *    minimal `IIgnoreFilter` shape, so the underlying library can be
- *    swapped without touching every consumer.
- * 3. Path normalization — every consumer passes the path RELATIVE to
- *    the scan root (POSIX separators); the wrapper guarantees that
- *    contract before delegating to `ignore`.
- */
-interface IIgnoreFilter {
-    /**
-     * Returns `true` when `relativePath` should be skipped. The caller
-     * MUST pass paths relative to the scan root, with POSIX separators
-     * (forward slashes), no leading `/`. Directories MAY be passed with
-     * or without trailing `/`; the wrapper does not require it.
-     */
-    ignores(relativePath: string): boolean;
-}
-
-/**
- * `ProgressEmitterPort` — emits progress events during long operations.
- *
- * Shape-only today. The full event catalog (`run.started`,
- * `job.claimed`, `model.delta`, etc.) is normative in
- * `spec/job-events.md`; this port carries an open `data` payload so
- * adapters can emit any documented event without type churn.
- */
-interface ProgressEvent {
-    type: string;
-    timestamp: string;
-    runId?: string;
-    jobId?: string;
-    data?: unknown;
-}
-type TProgressListener = (event: ProgressEvent) => void;
-interface ProgressEmitterPort {
-    emit(event: ProgressEvent): void;
-    subscribe(listener: TProgressListener): () => void;
-}
-
 /**
  * Plugin-surface types, hand-written to mirror
  * `spec/schemas/plugins-registry.schema.json#/$defs/PluginManifest` and the
@@ -913,9 +864,11 @@ interface IPluginManifest {
  *
  * - `incompatible-spec`: manifest parsed fine but `semver.satisfies` failed
  *   against the installed `@skill-map/spec` version.
- * - `invalid-manifest`: `plugin.json` missing, unparseable, or failing AJV.
- * - `load-error`: manifest passed but an extension module failed to import
- *   or the imported manifest failed its extension-kind schema.
+ * - `invalid-manifest`: `plugin.json` missing, unparseable, failing AJV on
+ *   the base manifest schema, OR the exported extension shape failed its
+ *   kind-specific schema (per spec/architecture.md §Plugin discovery —
+ *   "AJV rejects unknown `slot` names with `invalid-manifest`").
+ * - `load-error`: manifest parsed but an extension module failed to import.
  */
 /**
  * Possible outcomes after the loader sees a plugin.json. Mirrors the
@@ -1252,6 +1205,34 @@ interface IPriorExtractorRun {
     sidecarAnnotationsHash: string;
 }
 
+/**
+ * `.skillmapignore` parser + filter facade. Wraps `ignore` (kaelzhang)
+ * with the project-local layering: bundled defaults → `config.ignore`
+ * (from `.skill-map/settings.json`) → `.skillmapignore` file content.
+ *
+ * Why a wrapper instead of exposing `ignore` directly:
+ *
+ * 1. Single-source defaults — `src/config/defaults/skillmapignore` is
+ *    the canonical default list, loaded once at module init (or at
+ *    explicit build time, depending on bundling). The runtime never
+ *    re-reads it per scan.
+ * 2. Stable interface — Providers and the orchestrator depend on a
+ *    minimal `IIgnoreFilter` shape, so the underlying library can be
+ *    swapped without touching every consumer.
+ * 3. Path normalization — every consumer passes the path RELATIVE to
+ *    the scan root (POSIX separators); the wrapper guarantees that
+ *    contract before delegating to `ignore`.
+ */
+interface IIgnoreFilter {
+    /**
+     * Returns `true` when `relativePath` should be skipped. The caller
+     * MUST pass paths relative to the scan root, with POSIX separators
+     * (forward slashes), no leading `/`. Directories MAY be passed with
+     * or without trailing `/`; the wrapper does not require it.
+     */
+    ignores(relativePath: string): boolean;
+}
+
 /**
  * Provider runtime contract. Walks filesystem roots and emits raw node
  * records; classification maps path conventions to a node kind.
@@ -1395,15 +1376,6 @@ type TProviderKindIcon = {
 };
 interface IProvider extends IExtensionBase {
     kind: 'provider';
-    /**
-     * Filesystem directory (relative to user home or project root) where this
-     * Provider's content lives. Required. Examples: `'~/.claude'` for the
-     * Claude Provider, `'~/.cursor'` for a hypothetical Cursor Provider.
-     * The kernel walks this directory during boot/scan to discover nodes;
-     * `sm doctor` validates the directory exists and emits a non-blocking
-     * warning when it does not.
-     */
-    explorationDir: string;
     /**
      * Catalog of node kinds this Provider emits. Keyed by kind name. Every
      * kind the Provider can `classify()` MUST have an entry; an entry is
@@ -2153,6 +2125,182 @@ interface IHook extends IExtensionBase {
     on(ctx: IHookContext): void | Promise<void>;
 }
 
+/**
+ * `ProgressEmitterPort` — emits progress events during long operations.
+ *
+ * Shape-only today. The full event catalog (`run.started`,
+ * `job.claimed`, `model.delta`, etc.) is normative in
+ * `spec/job-events.md`; this port carries an open `data` payload so
+ * adapters can emit any documented event without type churn.
+ */
+interface ProgressEvent {
+    type: string;
+    timestamp: string;
+    runId?: string;
+    jobId?: string;
+    data?: unknown;
+}
+type TProgressListener = (event: ProgressEvent) => void;
+interface ProgressEmitterPort {
+    emit(event: ProgressEvent): void;
+    subscribe(listener: TProgressListener): () => void;
+}
+
+/**
+ * Per-node extractor invocation: build a fresh `IExtractorContext` for
+ * each extractor, validate every emitted link / contribution against
+ * the declared catalog, fold enrichment partials into per-`(node,
+ * extractor)` records, and surface emit-time drops as
+ * `extension.error` events.
+ *
+ * Also hosts the post-walk recompute helpers that re-derive
+ * `linksOutCount` / `linksInCount` / `externalRefsCount` on every node
+ * from the final merged link buffer, plus the `IExtractorRunRecord`
+ * and `IEnrichmentRecord` types those records eventually persist as.
+ */
+
+/**
+ * Spec § A.9 — runs to persist into `scan_extractor_runs`. One entry
+ * per `(nodePath, qualifiedExtractorId)` pair the orchestrator decided
+ * "this extractor is current for this body". Includes both freshly-run
+ * pairs (extractor invoked this scan) and reused pairs (cached node, the
+ * extractor's prior run still applies to the same body hash). Excludes
+ * obsolete pairs — extractors that ran in the prior but are no longer
+ * registered — so a replace-all persist drops them automatically.
+ */
+interface IExtractorRunRecord {
+    nodePath: string;
+    extractorId: string;
+    bodyHashAtRun: string;
+    ranAt: number;
+    /**
+     * sha256 of the canonical-form sidecar annotations the Extractor saw
+     * at run time. Always populated (an absent sidecar canonicalises to
+     * `{}` so the hash is stable). Used unconditionally by the cache
+     * decision alongside `bodyHashAtRun`: a sidecar-only edit invalidates
+     * the cached run for every applicable Extractor on that node.
+     */
+    sidecarAnnotationsHashAtRun: string;
+}
+/**
+ * Spec § A.8 — universal enrichment layer.
+ *
+ * One entry per `(nodePath, qualifiedExtractorId)` pair an Extractor
+ * produced via `ctx.enrichNode(...)` during the walk. Attribution is
+ * preserved per-Extractor (rather than merged client-side as B.1 did)
+ * so the persistence layer can:
+ *
+ *   - upsert a single row per pair (stable PRIMARY KEY conflict on
+ *     re-extract);
+ *   - feed `mergeNodeWithEnrichments` with `enrichedAt`-sorted partials
+ *     for last-write-wins per field at read time.
+ *
+ * `value` is the cumulative merge across every `enrichNode` call that
+ * Extractor made for this node within this scan — multiple
+ * `ctx.enrichNode({...})` calls inside one `extract(ctx)` invocation
+ * fold into a single row, but two different Extractors hitting the
+ * same node yield two distinct rows.
+ *
+ * `isProbabilistic` is reserved: Extractors are deterministic-only, so
+ * every record produced by the orchestrator sets it to `false`. The
+ * field is kept on the record (and the row in `node_enrichments`) so a
+ * future Action-issued enrichment can populate it without reshaping
+ * the persistence contract — see spec `architecture.md`
+ * §Extractor · enrichment layer.
+ */
+interface IEnrichmentRecord {
+    nodePath: string;
+    extractorId: string;
+    bodyHashAtEnrichment: string;
+    value: Partial<Node>;
+    enrichedAt: number;
+    isProbabilistic: boolean;
+}
+/**
+ * Run a set of extractors against a single node, collecting their link
+ * emissions and node-enrichment partials. Each extractor is invoked
+ * exactly once with a fresh `IExtractorContext`. Caller decides what
+ * to do with the returned arrays (push into per-scan buffers, write to
+ * a focused refresh result, etc.).
+ *
+ * Exported so `cli/commands/refresh.ts` can reuse the same wiring it
+ * needs for re-running a single extractor against a single node — the
+ * pre-extraction code in `refresh.ts` was hand-duplicating this loop
+ * (audit item V4).
+ *
+ * Within this call, multiple `enrichNode(partial)` calls from the same
+ * extractor against the same node fold into one record (last-write-wins
+ * per field) — same contract as the in-scan path.
+ */
+declare function runExtractorsForNode(opts: {
+    extractors: IExtractor[];
+    node: Node;
+    body: string;
+    frontmatter: Record<string, unknown>;
+    bodyHash: string;
+    emitter: ProgressEmitterPort;
+    /**
+     * Spec § A.12 — per-plugin `ctx.store` wrappers keyed by `pluginId`.
+     * The map's lookup is per-extractor inside the loop, so callers that
+     * don't track plugin storage can omit it; the resulting `ctx.store`
+     * stays `undefined` (the existing contract).
+     */
+    pluginStores?: ReadonlyMap<string, IPluginStore>;
+}): Promise<{
+    internalLinks: Link[];
+    externalLinks: Link[];
+    enrichments: IEnrichmentRecord[];
+    contributions: IContributionRecord[];
+}>;
+
+/**
+ * Rename + orphan classification per `spec/db-schema.md` §Rename
+ * detection. Pure: takes the prior `ScanResult` and the current node
+ * set, mutates the supplied `issues` array in place, and returns the
+ * `RenameOp[]` the persistence layer must apply inside the same tx as
+ * the scan zone replace-all.
+ */
+
+/**
+ * Confidence-tagged plan to repoint `state_*` references from one node
+ * path to another. Emitted by the rename heuristic during `runScan` and
+ * consumed by `persistScanResult` so the FK migration runs inside the
+ * same transaction as the scan zone replace-all.
+ */
+interface RenameOp {
+    from: string;
+    to: string;
+    confidence: 'high' | 'medium';
+}
+/**
+ * Pure rename / orphan classification per `spec/db-schema.md` §Rename
+ * detection. Mutates `issues` in place — caller passes the in-progress
+ * issue list; returns the `RenameOp[]` for the persistence layer to
+ * apply inside its tx.
+ *
+ * Pipeline (1-to-1: a `newPath` claimed by one stage cannot be reused
+ * by another):
+ *
+ *   1. **High-confidence**: pair each `deletedPath` with a `newPath`
+ *      that has the same `bodyHash`. No issue, no prompt.
+ *   2. **Medium-confidence (1:1)**: of the remaining deletions, pair
+ *      each with the *unique* unclaimed `newPath` that shares its
+ *      `frontmatterHash`. Emits `auto-rename-medium` (severity warn)
+ *      with `data: { from, to, confidence: 'medium' }`.
+ *   3. **Ambiguous (N:1)**: when a single `newPath` has more than one
+ *      remaining frontmatter-matching candidate, emit ONE
+ *      `auto-rename-ambiguous` issue per `newPath`, listing all
+ *      candidates in `data.candidates`. NO migration.
+ *   4. **Orphan**: every `deletedPath` left after steps 1-3 yields one
+ *      `orphan` issue (severity info) with `data: { path: <deletedPath> }`.
+ *
+ * Determinism: `deletedPaths` and `newPaths` are iterated in lex-asc
+ * order so the same input always produces the same matches —
+ * required for reproducible tests and conformance fixtures (the spec
+ * does not prescribe an order, but stability is the obvious contract).
+ */
+declare function detectRenamesAndOrphans(prior: ScanResult, current: Node[], issues: Issue[]): RenameOp[];
+
 /**
  * Scan orchestrator — runs the Provider → extractor → analyzer pipeline across
  * every registered extension and emits `ProgressEmitterPort` events in
@@ -2219,17 +2367,6 @@ interface IScanExtensions {
      */
     hooks?: IHook[];
 }
-/**
- * Confidence-tagged plan to repoint `state_*` references from one node
- * path to another. Emitted by the rename heuristic during `runScan` and
- * consumed by `persistScanResult` so the FK migration runs inside the
- * same transaction as the scan zone replace-all.
- */
-interface RenameOp {
-    from: string;
-    to: string;
-    confidence: 'high' | 'medium';
-}
 interface RunScanOptions {
     /**
      * Filesystem roots to walk. Spec requires `minItems: 1`; passing an
@@ -2393,63 +2530,6 @@ interface RunScanOptions {
      */
     cwd?: string;
 }
-/**
- * Spec § A.9 — runs to persist into `scan_extractor_runs`. One entry
- * per `(nodePath, qualifiedExtractorId)` pair the orchestrator decided
- * "this extractor is current for this body". Includes both freshly-run
- * pairs (extractor invoked this scan) and reused pairs (cached node, the
- * extractor's prior run still applies to the same body hash). Excludes
- * obsolete pairs — extractors that ran in the prior but are no longer
- * registered — so a replace-all persist drops them automatically.
- */
-interface IExtractorRunRecord {
-    nodePath: string;
-    extractorId: string;
-    bodyHashAtRun: string;
-    ranAt: number;
-    /**
-     * sha256 of the canonical-form sidecar annotations the Extractor saw
-     * at run time. Always populated (an absent sidecar canonicalises to
-     * `{}` so the hash is stable). Used unconditionally by the cache
-     * decision alongside `bodyHashAtRun`: a sidecar-only edit invalidates
-     * the cached run for every applicable Extractor on that node.
-     */
-    sidecarAnnotationsHashAtRun: string;
-}
-/**
- * Spec § A.8 — universal enrichment layer.
- *
- * One entry per `(nodePath, qualifiedExtractorId)` pair an Extractor
- * produced via `ctx.enrichNode(...)` during the walk. Attribution is
- * preserved per-Extractor (rather than merged client-side as B.1 did)
- * so the persistence layer can:
- *
- *   - upsert a single row per pair (stable PRIMARY KEY conflict on
- *     re-extract);
- *   - feed `mergeNodeWithEnrichments` with `enrichedAt`-sorted partials
- *     for last-write-wins per field at read time.
- *
- * `value` is the cumulative merge across every `enrichNode` call that
- * Extractor made for this node within this scan — multiple
- * `ctx.enrichNode({...})` calls inside one `extract(ctx)` invocation
- * fold into a single row, but two different Extractors hitting the
- * same node yield two distinct rows.
- *
- * `isProbabilistic` is reserved: Extractors are deterministic-only, so
- * every record produced by the orchestrator sets it to `false`. The
- * field is kept on the record (and the row in `node_enrichments`) so a
- * future Action-issued enrichment can populate it without reshaping
- * the persistence contract — see spec `architecture.md`
- * §Extractor · enrichment layer.
- */
-interface IEnrichmentRecord {
-    nodePath: string;
-    extractorId: string;
-    bodyHashAtEnrichment: string;
-    value: Partial<Node>;
-    enrichedAt: number;
-    isProbabilistic: boolean;
-}
 /**
  * Same as `runScan` but also returns the rename heuristic's `RenameOp[]`
  * — the high- and medium-confidence renames the persistence layer must
@@ -2472,70 +2552,16 @@ declare function runScanWithRenames(_kernel: Kernel, options: RunScanOptions): P
     freshlyRunTuples: ReadonlySet<string>;
 }>;
 declare function runScan(_kernel: Kernel, options: RunScanOptions): Promise<ScanResult>;
+
 /**
- * Run a set of extractors against a single node, collecting their link
- * emissions and node-enrichment partials. Each extractor is invoked
- * exactly once with a fresh `IExtractorContext`. Caller decides what
- * to do with the returned arrays (push into per-scan buffers, write to
- * a focused refresh result, etc.).
- *
- * Exported so `cli/commands/refresh.ts` can reuse the same wiring it
- * needs for re-running a single extractor against a single node — the
- * pre-extraction code in `refresh.ts` was hand-duplicating this loop
- * (audit item V4).
- *
- * Within this call, multiple `enrichNode(partial)` calls from the same
- * extractor against the same node fold into one record (last-write-wins
- * per field) — same contract as the in-scan path.
- */
-declare function runExtractorsForNode(opts: {
-    extractors: IExtractor[];
-    node: Node;
-    body: string;
-    frontmatter: Record<string, unknown>;
-    bodyHash: string;
-    emitter: ProgressEmitterPort;
-    /**
-     * Spec § A.12 — per-plugin `ctx.store` wrappers keyed by `pluginId`.
-     * The map's lookup is per-extractor inside the loop, so callers that
-     * don't track plugin storage can omit it; the resulting `ctx.store`
-     * stays `undefined` (the existing contract).
-     */
-    pluginStores?: ReadonlyMap<string, IPluginStore>;
-}): Promise<{
-    internalLinks: Link[];
-    externalLinks: Link[];
-    enrichments: IEnrichmentRecord[];
-    contributions: IContributionRecord[];
-}>;
-/**
- * Pure rename / orphan classification per `spec/db-schema.md` §Rename
- * detection. Mutates `issues` in place — caller passes the in-progress
- * issue list; returns the `RenameOp[]` for the persistence layer to
- * apply inside its tx.
- *
- * Pipeline (1-to-1: a `newPath` claimed by one stage cannot be reused
- * by another):
- *
- *   1. **High-confidence**: pair each `deletedPath` with a `newPath`
- *      that has the same `bodyHash`. No issue, no prompt.
- *   2. **Medium-confidence (1:1)**: of the remaining deletions, pair
- *      each with the *unique* unclaimed `newPath` that shares its
- *      `frontmatterHash`. Emits `auto-rename-medium` (severity warn)
- *      with `data: { from, to, confidence: 'medium' }`.
- *   3. **Ambiguous (N:1)**: when a single `newPath` has more than one
- *      remaining frontmatter-matching candidate, emit ONE
- *      `auto-rename-ambiguous` issue per `newPath`, listing all
- *      candidates in `data.candidates`. NO migration.
- *   4. **Orphan**: every `deletedPath` left after steps 1-3 yields one
- *      `orphan` issue (severity info) with `data: { path: <deletedPath> }`.
- *
- * Determinism: `deletedPaths` and `newPaths` are iterated in lex-asc
- * order so the same input always produces the same matches —
- * required for reproducible tests and conformance fixtures (the spec
- * does not prescribe an order, but stability is the obvious contract).
+ * Node-construction helpers: hash a body, canonicalise frontmatter /
+ * sidecar annotations, resolve the sidecar overlay for a given relative
+ * path, and produce a fresh `Node` (validating its frontmatter on the
+ * way out). Also hosts `mergeNodeWithEnrichments` + `IPersistedEnrichment`
+ * — the read-time merge of author frontmatter with the A.8 enrichment
+ * layer.
  */
-declare function detectRenamesAndOrphans(prior: ScanResult, current: Node[], issues: Issue[]): RenameOp[];
+
 /**
  * Spec § A.8 — produce the merged read-time view of a Node.
  *