@skill-map/cli 0.61.5 → 0.62.0

package/dist/kernel/index.d.ts

@@ -1341,19 +1341,33 @@ interface ScanResult {
      */
     tokenizer?: string;
     /**
-     * Effective recommended cap on the number of files the walker accepted
-     * during this scan (`scan.maxNodes` from settings, default 256). The UI
-     * raises the "oversized graph" banner when
-     * `stats.filesWalked >= recommendedNodeLimit`. Absent on synthetic fixtures
-     * that bypass the walker.
-     */
-    recommendedNodeLimit?: number;
-    /**
-     * Override applied via `--max-nodes <N>` on the verb that ran the scan, or
-     * `null` when no override was passed (the value above came from the
-     * setting). Bidirectional: can raise OR lower the recommended limit.
-     */
-    overrideMaxNodes?: number | null;
+     * Effective walk ceiling for this scan (`--max-scan <N>` override on
+     * `sm scan` / `sm watch` / `sm serve`, else `scan.maxScan` from
+     * settings, default 50000). The scan walks, parses, analyzes, and
+     * reference-validates the full corpus up to this number, so references
+     * resolve across the whole project regardless of how many nodes the
+     * map renders. Mirrors `scan_meta.scan_ceiling`. Absent on synthetic
+     * fixtures that bypass the walker.
+     */
+    scanCeiling?: number;
+    /**
+     * True when the walker reached `scanCeiling` and dropped files in
+     * stable provider-walker order, false otherwise. Drives the CLI "scan
+     * truncated" notice and the UI persistent banner pointing at the
+     * `.skillmapignore` editor. Mirrors `scan_meta.scan_truncated`. Absent
+     * on synthetic fixtures that bypass the walker.
+     */
+    scanTruncated?: boolean;
+    /**
+     * Effective map render cap for this scan (`--max-nodes <N>` override,
+     * else `scan.maxNodes` from settings, default 256). Does NOT bound the
+     * scan (the full corpus up to `scanCeiling` is persisted and the
+     * folders tree shows all of it); it only bounds the graph projection.
+     * The UI projects the selected folder branch capped at this number and
+     * raises an in-view banner when a branch exceeds it. Mirrors
+     * `scan_meta.max_render_nodes`. Absent on synthetic fixtures.
+     */
+    maxRenderNodes?: number;
     /**
      * Files the walker skipped because their on-disk size exceeded
      * `scan.maxFileSizeBytes` (default 1 MiB). Each entry is the
@@ -1779,6 +1793,59 @@ interface INodeCounts {
     links: number;
     issues: number;
 }
+/**
+ * Lightweight per-node projection for the BFF `/api/folders` endpoint.
+ * Carries only the cheap scalar columns the SPA folders tree needs
+ * (`path`, `kind`, the two link counts, total tokens, mtime), never the
+ * full `Node` (no frontmatter, body, links, signals, contributions).
+ * Pushed straight from `scan_nodes` so a 50K corpus does not hydrate the
+ * whole `ScanResult` into memory.
+ */
+interface ILiteNode {
+    path: string;
+    kind: string;
+    linksInCount: number;
+    linksOutCount: number;
+    tokensTotal: number | null;
+    modifiedAtMs: number | null;
+    /**
+     * The persisted `scan_nodes.sidecar_status`, null when there is no
+     * parseable sidecar. Lets the folders rail flag staleness corpus-wide,
+     * sibling of the issue counts.
+     */
+    sidecarStatus: string | null;
+}
+/**
+ * Per-node issue incidence counts by severity, output of
+ * `port.scans.issueCountsByPath()`. One entry per node that has at least
+ * one error- or warn-severity issue whose `nodeIds` array includes the
+ * path; nodes with no error / warn issues are absent from the map. The
+ * `info` severity is intentionally ignored (the SPA badges only error /
+ * warn). Counts are issue incidence (one per matching issue), the same
+ * semantics the UI's `countIssuesByPath` rolls up per node.
+ */
+interface IIssueIncidenceCount {
+    error: number;
+    warn: number;
+}
+/**
+ * Output of `port.scans.loadBranch(...)`, the prefix-union + capped
+ * graph projection the BFF `/api/branch` endpoint returns. `nodes` is
+ * the first `LIMIT` nodes of the union (every requested prefix's
+ * subtree) in stable path order (`ORDER BY path`); `links` carries only
+ * edges whose source AND target are both in that node set; `issues`
+ * carries only those whose `nodeIds` intersect it. `total` is the count
+ * of nodes in the union BEFORE the cap (so the route can compute
+ * `truncated`). `paths` echoes the (de-duped) requested prefixes; the
+ * whole-corpus case (no prefix) echoes `[]`.
+ */
+interface IBranchProjection {
+    nodes: Node[];
+    links: Link[];
+    issues: Issue[];
+    total: number;
+    paths: string[];
+}
 /**
  * Lightweight option bag for `port.scans.persist`. Mirrors the optional
  * inputs of the `persistScanResult(db, result, inputs)` free function
@@ -2310,6 +2377,26 @@ interface IRawNode {
      * Empty / undefined on the happy path.
      */
     parseIssues?: readonly IParseIssue[];
+    /**
+     * Incremental-walk fast path. `true` when the walker matched this
+     * file's on-disk `mtime` against the prior scan snapshot (via
+     * `IProviderWalkOptions.priorMtimes`) and SKIPPED reading + parsing the
+     * body, the dominant per-file cost. For such a record `body` /
+     * `frontmatter` / `frontmatterRaw` are empty placeholders: the
+     * orchestrator reuses the prior node verbatim and reads the body
+     * (through `reread`) ONLY when a sidecar change forces re-extraction.
+     * Absent / `false` means a normal record whose body was read eagerly.
+     */
+    unchanged?: boolean;
+    /**
+     * Present only on an `unchanged` record: a lazy reader that performs
+     * the deferred `readFile` + parse and returns the body / frontmatter
+     * the walker skipped. The orchestrator calls it only when it must
+     * actually re-extract (a sidecar edit on an otherwise-unchanged file).
+     * Keeps the read + parse logic in the walker (single source) rather
+     * than duplicating it in the orchestrator.
+     */
+    reread?: () => Promise<Pick<IRawNode, 'body' | 'frontmatterRaw' | 'frontmatter' | 'parseIssues'>>;
 }
 /**
  * Runtime descriptor of one Provider kind, populated by the loader from
@@ -2809,6 +2896,30 @@ interface IProviderWalkOptions {
         path: string;
         bytes: number;
     }) => void;
+    /**
+     * Incremental-walk hint: prior-scan file mtimes keyed by root-relative
+     * path (the same form as `IRawNode.path`). When supplied, the kernel
+     * walker compares each file's on-disk `mtime` against this map and, on
+     * a match, yields a lightweight `unchanged` record WITHOUT reading or
+     * parsing the body (the dominant cost on a re-scan). The orchestrator
+     * builds this from the prior snapshot only when cache reuse is on and
+     * the tokenizer is unchanged; absent means "read every file" (the
+     * full-scan default). A Provider shipping its own `walk()` MAY honour
+     * it for the same speedup but is not required to.
+     */
+    priorMtimes?: ReadonlyMap<string, number>;
+    /**
+     * Scoped-walk hint for the watcher's incremental path: an explicit
+     * list of ABSOLUTE file paths to read instead of traversing the
+     * roots. When supplied, the kernel walker skips traversal entirely and
+     * reads ONLY these paths (those matching the provider's `extensions`,
+     * existing on disk, passing the size guard), yielding a normal
+     * `IRawNode` per match. Built by the orchestrator from chokidar's
+     * changed-path list; absent means "traverse the roots" (the full-scan
+     * default). A Provider shipping its own `walk()` MAY honour it for the
+     * same speedup but is not required to.
+     */
+    scopedPaths?: readonly string[];
 }
 /**
  * Declarative read config a Provider declares via `IProvider.read`.
@@ -4081,21 +4192,35 @@ interface RunScanOptions {
      */
     activeProvider?: string | null;
     /**
-     * Recommended cap on the number of nodes the walker classifies
-     * (mirror of `scan.maxNodes` in settings, default 256). Threaded
-     * through to `walkAndExtract` so the cap can fire and so
-     * `ScanResult.recommendedNodeLimit` is populated. Absent → the
-     * orchestrator falls back to 256 (the design default), keeping
-     * out-of-band callers and synthetic fixtures safe.
+     * Walk-intake ceiling (mirror of `scan.maxScan` in settings, default
+     * 50000). Threaded through to `walkAndExtract` so the ceiling can fire
+     * (dropping extra files in stable order) and so `ScanResult.scanCeiling`
+     * / `ScanResult.scanTruncated` are populated. Absent → the orchestrator
+     * falls back to 50000 (the design default), keeping out-of-band callers
+     * and synthetic fixtures safe.
      */
-    recommendedNodeLimit?: number;
+    scanCeiling?: number;
     /**
-     * Per-invocation override of the recommended cap (when `--max-nodes
-     * <N>` was passed). `null` (or absent) means no override; the
-     * recommended limit applies. Bidirectional: any positive integer
-     * replaces the recommended limit for the duration of this scan.
+     * Per-invocation override of the walk ceiling (when `--max-scan <N>`
+     * was passed). `null` (or absent) means no override; the configured
+     * ceiling applies. Bidirectional: any positive integer replaces the
+     * ceiling for the duration of this scan.
      */
-    overrideMaxNodes?: number | null;
+    overrideScanCeiling?: number | null;
+    /**
+     * Map render cap (mirror of `scan.maxNodes` in settings, default 256).
+     * Pure metadata: it does NOT bound the walk. Threaded through to
+     * `walkAndExtract` only so `ScanResult.maxRenderNodes` is populated and
+     * the UI knows how many nodes to project onto the canvas. Absent → the
+     * orchestrator falls back to 256.
+     */
+    maxRenderNodes?: number;
+    /**
+     * Per-invocation override of the render cap (when `--max-nodes <N>`
+     * was passed). `null` (or absent) means no override; the configured
+     * render cap applies. Bidirectional. Never bounds the walk.
+     */
+    overrideMaxRenderNodes?: number | null;
     /**
      * Mirror of `scan.maxFileSizeBytes` (default 1 MiB). Threaded into
      * `walkAndExtract` so the walker skips any file larger than this
@@ -4104,6 +4229,38 @@ interface RunScanOptions {
      * size limit (out-of-band callers and synthetic fixtures stay safe).
      */
     maxFileSizeBytes?: number;
+    /**
+     * Watcher-only incremental fast path (pure perf, identical output to a
+     * full scan). When supplied AND a prior snapshot exists AND
+     * `enableCache` is on AND the tokenizer is unchanged, the orchestrator
+     * does NOT traverse the directory tree. Instead it:
+     *
+     *   - re-reads + re-extracts ONLY the files in `changed` (scoped read,
+     *     no `readdir`), and
+     *   - injects every other prior node as an `unchanged` record through
+     *     the SAME cache machinery the mtime-gate uses (`applyFullCacheHit`),
+     *     reusing its node + links + extractor runs verbatim, and
+     *   - drops the files in `removed` (the rename / orphan heuristic over
+     *     prior-vs-merged handles the disappearance + any rename).
+     *
+     * Paths are root-relative POSIX (the same form as `node.path`). A
+     * sidecar (`.sm`) path in either set is mapped to its `.md` node so a
+     * sidecar edit re-processes the node. The downstream analysis phases
+     * (resolver, post-walk transforms, analyzers, broken-ref,
+     * name-collision) always run over the fully-merged graph, so global
+     * validation stays correct (a changed file's new link to an unchanged
+     * file resolves; an unchanged file's link to a removed file breaks).
+     *
+     * `filesWalked` reflects only the scoped reads (far fewer than the
+     * corpus), `scanTruncated` stays `false` (the ceiling never fires on a
+     * scoped read). Absent (boot, `sm scan`, `sm scan --changed`,
+     * meta-file change) falls back to the full-traversal + mtime-gate path,
+     * byte-identical to today.
+     */
+    incrementalChangedPaths?: {
+        changed: ReadonlySet<string>;
+        removed: ReadonlySet<string>;
+    };
 }
 /**
  * Same as `runScan` but also returns the rename heuristic's `RenameOp[]`
@@ -4608,6 +4765,15 @@ interface StoragePort {
          * `node.kind` is open string per `node.schema.json`).
          */
         load(): Promise<ScanResult>;
+        /**
+         * Metadata-only `ScanResult`: every scalar field plus real
+         * `COUNT(*)` stats, but empty `nodes` / `links` / `issues` arrays.
+         * Reads only the single `scan_meta` row plus the counts, never the
+         * node / link / issue tables, so the BFF `GET /api/scan?meta=1` boot
+         * fetch stays cheap on a large corpus. The SPA pairs it with
+         * `/api/folders` (tree) and `/api/branch` (map).
+         */
+        loadMeta(): Promise<ScanResult>;
         /**
          * Spec § A.9, fine-grained extractor-runs cache breadcrumbs.
          * Returns `Map<nodePath, Map<qualifiedExtractorId, IPriorExtractorRun>>`.
@@ -4629,6 +4795,47 @@ interface StoragePort {
          * is not in the persisted scan.
          */
         findNode(path: string): Promise<INodeBundle | null>;
+        /**
+         * Lightweight full-corpus node list `{ path, kind }[]`, ordered by
+         * `path` ASC. Backs the BFF `/api/folders` endpoint: the SPA folders
+         * tree renders the whole scanned corpus (up to `scan.maxScan`)
+         * without hydrating the full `ScanResult`. Pushes the projection to
+         * SQL (`SELECT path, kind`), never loads the rest of the row.
+         */
+        listLiteNodes(): Promise<ILiteNode[]>;
+        /**
+         * Per-node issue incidence counts by severity, keyed by node path.
+         * Expands every `scan_issues.node_ids_json` array with SQLite
+         * `json_each` and groups by `(value, severity)` so the count is
+         * computed in SQL, not by loading every issue into memory. Only
+         * error / warn severities are tallied (the SPA badges ignore
+         * `info`); nodes with no error / warn issue are absent from the
+         * map. Backs the `errorCount` / `warnCount` fields on `/api/folders`.
+         */
+        issueCountsByPath(): Promise<Map<string, IIssueIncidenceCount>>;
+        /**
+         * Effective map-render cap recorded by the latest scan
+         * (`scan_meta.max_render_nodes`). Returns the design default (256)
+         * when no `scan_meta` row exists (DB freshly migrated / never
+         * scanned). Backs the `/api/branch` cap default + clamp ceiling.
+         */
+        effectiveMaxRenderNodes(): Promise<number>;
+        /**
+         * Prefix-union, capped graph projection for the BFF `/api/branch`
+         * endpoint. A node is in the branch when, for ANY prefix in
+         * `prefixes`, its `path === prefix` or starts with `prefix + '/'`;
+         * the per-prefix subtrees are UNIONed. An empty `prefixes` array
+         * selects the whole corpus. Identical prefixes are de-duped
+         * defensively. `nodes` is the first `limit` matching nodes of the
+         * union in stable path order (`ORDER BY path LIMIT`); `links`
+         * carries only edges whose source AND target are both in `nodes`;
+         * `issues` carries only those whose `nodeIds` intersect `nodes`.
+         * `total` is the count of union nodes BEFORE the cap (so the route
+         * can compute `truncated`); `paths` echoes the de-duped prefixes.
+         * All scoping + capping happens in SQL so a 50K corpus never
+         * hydrates into memory.
+         */
+        loadBranch(prefixes: string[], limit: number): Promise<IBranchProjection>;
     };
     /**
      * Phase 3 / View contribution system, read access to