@skill-map/cli 0.32.0 → 0.34.0

package/dist/kernel/index.d.ts

@@ -501,7 +501,26 @@ interface IExtensionBase {
  */
 type NodeKind = 'skill' | 'agent' | 'command' | 'markdown';
 type LinkKind = 'invokes' | 'references' | 'mentions' | 'supersedes';
-type Confidence = 'high' | 'medium' | 'low';
+/**
+ * Extractor's self-assessed confidence, normalized to `[0..1]`. Drives
+ * UI edge opacity in the graph view (more confident = more opaque edge).
+ * Migrated from the legacy `'high' | 'medium' | 'low'` string union to
+ * a numeric range so callers can express finer granularity than three
+ * buckets. The named tiers below (`ConfidenceTier`) preserve the
+ * legacy buckets as constants for callers that prefer bucket-thinking.
+ *
+ * Reference scoring (guideline, not contract):
+ *
+ *   `1.0`  structured input (sidecar `supersedes`)
+ *   `0.95` unambiguous syntax (`[text](file.md)`, `https://…`)
+ *   `0.85` strong signal with one inference (`@file.md`)
+ *   `0.5`  genuine ambiguity (`@bare-handle`)
+ *
+ * Validation: the orchestrator's `validateLink` rejects values outside
+ * `[0..1]` with an `extension.error` event, mirroring the LinkKind
+ * enum check. Missing confidence defaults to `ConfidenceTier.MEDIUM`.
+ */
+type Confidence = number;
 type Severity = 'error' | 'warn' | 'info';
 type Stability = 'experimental' | 'stable' | 'deprecated';
 /**
@@ -569,6 +588,25 @@ interface Node {
      * truthy `isFavorite` only ever lands when the BFF set it.
      */
     isFavorite?: boolean;
+    /**
+     * When `true`, the node is synthetic / derived: it does not correspond
+     * to a single file on disk. Reconstructed on every scan from the
+     * file(s) listed in `derivedFrom`. Synthetic nodes use a non-filesystem
+     * path scheme (e.g. `mcp://github`) so the identifier is stable and
+     * visibly non-physical. See
+     * [`node.schema.json`](../../spec/schemas/node.schema.json) for the
+     * normative contract. Absent / `false` for ordinary filesystem-backed
+     * entities. Stability: experimental.
+     */
+    virtual?: boolean;
+    /**
+     * Paths of the source files this node was derived from. Required (and
+     * only meaningful) when `virtual === true`. Drives invalidation: any
+     * change to a listed source between scans propagates into the virtual
+     * node's hashes. Empty / absent when the node is a regular filesystem
+     * entity (the `path` itself is the source).
+     */
+    derivedFrom?: string[];
 }
 /**
  * Drift status of a co-located `.sm` sidecar relative to the live
@@ -621,6 +659,83 @@ interface Link {
     location?: LinkLocation | null;
     raw?: string | null;
 }
+/**
+ * Scope of a `Signal` within its originating node. Mirrors
+ * `signal.schema.json#/properties/scope`.
+ *
+ *   - `body` = markdown body or equivalent prose payload.
+ *   - `frontmatter` = parsed metadata block at the top of the file.
+ *   - `sidecar` = co-located `.sm` overlay.
+ */
+type SignalScope = 'body' | 'frontmatter' | 'sidecar';
+/**
+ * Surface context for a body-scope `Signal`. Mirrors
+ * `signal.schema.json#/properties/context/enum`. Null when the signal is in
+ * normal prose or when the context concept does not apply (frontmatter /
+ * sidecar scopes).
+ */
+type SignalContext = 'code-block' | 'inline-code' | 'escaped';
+/**
+ * Byte-range location for a body-scope `Signal`. `start` is inclusive,
+ * `end` is exclusive (one past the last char).
+ */
+interface SignalRange {
+    start: number;
+    end: number;
+}
+/**
+ * One alternative interpretation of a `Signal`. The resolver picks the
+ * winning candidate per Signal and materialises it as a `Link`; the
+ * rejected candidates remain on `IAnalyzerContext.signals` for
+ * collision-detection and conflict-visualisation analyzers.
+ *
+ * `confidence` is numeric `[0..1]`, identical shape to the `Link`'s
+ * `Confidence` type after the Phase 4 migration. No conversion needed
+ * when the resolver materialises a winning candidate.
+ */
+interface SignalCandidate {
+    extractorId: string;
+    kind: LinkKind;
+    target: string;
+    /** `[0..1]`. Reference scoring guideline lives in `signal.schema.json`. */
+    confidence: number;
+    rationale?: string;
+    trigger?: LinkTrigger | null;
+}
+/**
+ * Intermediate Representation (IR) emitted by extractors via
+ * `ctx.emitSignal(signal)`. The kernel's resolver phase consumes
+ * `Signal[]` and produces final `Link[]` per the active Provider's
+ * `resolverRules`. Opt-in: extractors with unambiguous detections keep
+ * using `ctx.emitLink(link)` directly. See
+ * [`signal.schema.json`](../../spec/schemas/signal.schema.json) for the
+ * normative contract.
+ */
+interface Signal {
+    /** `node.path` of the originating node. */
+    source: string;
+    scope: SignalScope;
+    /**
+     * Byte-range location within the source. Required for `scope: 'body'`,
+     * optional otherwise. Powers collision detection between extractors
+     * (overlapping ranges) and code-block awareness (the orchestrator can
+     * mark ranges that fall inside code spans).
+     */
+    range?: SignalRange | null;
+    /**
+     * Structured-data location for `frontmatter` / `sidecar` scopes. Each
+     * entry is a step of the path: object keys are strings, array indices
+     * are integers serialised as strings. Example: `['tools', '0']`. Null
+     * for body scope or when the extractor does not track field locations.
+     */
+    fieldPath?: string[] | null;
+    /** Verbatim matched text (body) or stringified value (frontmatter / sidecar). */
+    raw: string;
+    /** Surface context. Null when in normal prose or when not applicable. */
+    context?: SignalContext | null;
+    /** One or more alternative interpretations. At least one. */
+    candidates: SignalCandidate[];
+}
 interface IssueFix {
     summary?: string;
     autofixable?: boolean;
@@ -1828,6 +1943,36 @@ interface IProviderReadConfig {
  * Confidence is per-emit (no manifest-level default).
  */
 
+/**
+ * Payload accepted by `IExtractorCallbacks.emitNode`. A loose subset of
+ * `Node` because the kernel fills the rest from the emission context:
+ *
+ *   - `bodyHash`, `frontmatterHash` are computed from `derivedFrom` (the
+ *     hash of the sources concatenated in declared order, so the
+ *     virtual node's hashes drift when any source changes).
+ *   - `bytes`, `linksOutCount`, `linksInCount`, `externalRefsCount`
+ *     default to zero counts on emission; the orchestrator's
+ *     post-extraction recompute pass fills them in once links resolve.
+ *
+ * The emitter MUST supply `path` (canonical id), `kind` (registered in
+ * a Provider's catalog), `derivedFrom` (one or more existing-node paths
+ * the virtual node is derived from), and SHOULD supply `frontmatter`
+ * with the metadata the UI / analyzers will surface.
+ */
+interface IEmittedNode {
+    /** Synthetic identifier. Use a non-filesystem scheme (`mcp://`, etc). */
+    path: string;
+    /** Kind declared in some Provider's `kinds` catalog. */
+    kind: string;
+    /** Required for virtual nodes: paths of the source(s). */
+    derivedFrom: string[];
+    /** Always true on this surface; the kernel mirrors it to `Node.virtual`. */
+    virtual: true;
+    /** Provider id the node is attributed to (e.g. `'claude'`). */
+    provider: string;
+    /** Optional structured metadata the UI / analyzers read. */
+    frontmatter?: Record<string, unknown>;
+}
 /**
  * Output callbacks supplied by the kernel on the extractor context.
  */
@@ -1839,6 +1984,35 @@ interface IExtractorCallbacks {
      * `extension.error` event.
      */
     emitLink(link: Link): void;
+    /**
+     * Emit a multi-candidate `Signal` for the kernel's resolver phase to
+     * collapse into a single Link (or reject). Use this instead of
+     * `emitLink` when the detection carries genuine ambiguity (multiple
+     * plausible kinds / targets), needs byte-range awareness for
+     * collision detection, or needs numeric confidence with
+     * sub-tier granularity. Unambiguous detectors should keep using
+     * `emitLink` directly. See
+     * [`signal.schema.json`](../../../spec/schemas/signal.schema.json) for the
+     * normative contract. Validated against the same closed kind enum;
+     * off-spec Signals (no candidates, off-enum kind, confidence outside
+     * `[0..1]`) drop silently with an `extension.error` event.
+     */
+    emitSignal(signal: Signal): void;
+    /**
+     * Phase 5, emit a synthetic / virtual `Node` derived from the
+     * scanning context (frontmatter, sidecar, config). Used by the
+     * `core/mcp-tools` extractor to materialise an `mcp://<name>` node
+     * out of a `tools: [mcp__<name>__*]` frontmatter entry, and by the
+     * future Cursor / Codex MCP-config extractors that walk
+     * `.cursor/mcp.json` / `~/.codex/config.toml`. The kernel
+     * deduplicates by `node.path` against the walker's nodes AND across
+     * extractor emissions: the FIRST emission of a given path wins,
+     * subsequent emissions are silently ignored (idempotent semantics so
+     * N skills referencing the same MCP collapse into one node). Emitted
+     * nodes carry `virtual: true` and `derivedFrom: [...]` per
+     * [`node.schema.json`](../../../spec/schemas/node.schema.json).
+     */
+    emitNode(node: IEmittedNode): void;
     /**
      * Merge canonical, kernel-curated properties onto the current node's
      * enrichment layer. The author-supplied frontmatter stays untouched
@@ -2004,6 +2178,18 @@ interface IAnalyzerContext {
      * absolute path when present.
      */
     cwd?: string;
+    /**
+     * Signals emitted by extractors during the scan, before the resolver
+     * collapsed them into `links`. Populated when at least one extractor
+     * opted into the Signal IR path (`ctx.emitSignal` in
+     * `IExtractorCallbacks`). Empty / absent when every extractor used
+     * `emitLink` directly (legacy and unambiguous paths). Treat as
+     * read-only. Analyzers consume this for collision detection
+     * (overlapping `range` from different extractors), fragmentation
+     * detection, and conflict-visualisation; the resolved `links` remain
+     * the source of truth for graph-level analyses.
+     */
+    signals?: readonly Signal[];
     /**
      * Emit a per-node view contribution declared in this analyzer's
      * manifest `viewContributions` map. Sync, void return; the
@@ -2489,6 +2675,8 @@ declare function runExtractorsForNode(opts: {
     externalLinks: Link[];
     enrichments: IEnrichmentRecord[];
     contributions: IContributionRecord[];
+    signals: Signal[];
+    virtualNodes: Node[];
 }>;
 
 /**
@@ -2508,7 +2696,14 @@ declare function runExtractorsForNode(opts: {
 interface RenameOp {
     from: string;
     to: string;
-    confidence: 'high' | 'medium';
+    /**
+     * Rename-heuristic confidence as a numeric tier. Body-hash matches
+     * use `ConfidenceTier.HIGH` (`0.9`); frontmatter-hash matches use
+     * `ConfidenceTier.MEDIUM` (`0.6`). Consumers that surface the tier
+     * as a string (e.g. issue analyzerId `auto-rename-<tier>`) call
+     * `renameTierLabel(confidence)` to recover the legacy label.
+     */
+    confidence: number;
 }
 /**
  * Pure rename / orphan classification per `spec/db-schema.md` §Rename
@@ -2524,7 +2719,7 @@ interface RenameOp {
  *   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' }`.
+ *      with `data: { from, to, confidence: ConfidenceTier.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
@@ -2774,6 +2969,25 @@ interface RunScanOptions {
      * concept (out-of-band tests, embedders).
      */
     cwd?: string;
+    /**
+     * Active provider lens for this scan, gating provider-specific
+     * extractors against both the node's provider AND the lens (per
+     * `spec/architecture.md` §Universal extractors and per-provider
+     * extractors). Three interpretations:
+     *
+     *   - `string`: explicit lens. Provider-specific extractors run only
+     *     when their declared `precondition.provider` includes BOTH this
+     *     value AND the node's provider.
+     *   - `null`: explicit "no lens". Provider-specific extractors are
+     *     unconditionally skipped (spec-strict).
+     *   - `undefined`: kernel auto-detects from `options.roots[0]` using
+     *     filesystem markers (`.claude/`, `.gemini/`, `.codex/`,
+     *     `AGENTS.md`). Convenient default for out-of-band callers
+     *     (integration tests, embedders) that don't thread a settings
+     *     reader. Production callers (scan-runner) resolve upstream and
+     *     pass `string | null` explicitly, never `undefined`.
+     */
+    activeProvider?: string | null;
 }
 /**
  * Same as `runScan` but also returns the rename heuristic's `RenameOp[]`