@shrkcrft/cli 0.1.0-alpha.30 → 0.1.0-alpha.31

package/dist/diff/deleted-orphan-coverage.d.ts

@@ -0,0 +1,32 @@
+import type { IVerdictCoverage } from '@shrkcrft/core';
+import type { IDeletedOrphanScan } from './deleted-orphans.js';
+/**
+ * What an orphan scan EXAMINED against what the delete asked it to — the one
+ * coverage authority for `check orphans` and the `finish` orphans sub-gate.
+ *
+ * "Who still imports the deleted code?" has two sides, and the code-graph
+ * index must be current on both for a clean answer to mean anything:
+ *
+ *   - the DELETED side: a deleted source file the index does not know (the
+ *     index predates it, or was rebuilt after the delete) had its importers
+ *     never checked — expected, not examined;
+ *   - the IMPORTER side: a file added or edited since the index was built may
+ *     import the deleted code, and the index never read its current imports.
+ *     While any such file exists, NO deleted file's importer set is complete,
+ *     so every deleted file in scope is unexamined and the reason names the
+ *     files the index never read (`scan.indexDivergence`, measured by the one
+ *     freshness authority, `detectGraphFreshness`).
+ *
+ * Defining the unit as "indexed deleted files", or ignoring the importer side,
+ * would make either gap disappear by construction — the clean-over-a-stale-
+ * index verdict this closes.
+ *
+ * Only files the graph would index are in scope (`indexableDeleted`, the
+ * graph's `isGraphIndexablePath`), so deleting a README or a `dist/*.js` next
+ * to a `.ts` still reads clean. Nothing deleted, or nothing deleted that the
+ * graph indexes, is `expected: 0` — "nothing to examine" — which the caller may
+ * accept explicitly with `--allow-empty`; a stale index is irrelevant there
+ * (there is no deleted code for anything to import).
+ */
+export declare function deletedOrphanCoverage(scan: IDeletedOrphanScan): IVerdictCoverage;
+//# sourceMappingURL=deleted-orphan-coverage.d.ts.map

package/dist/diff/deleted-orphan-coverage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"deleted-orphan-coverage.d.ts","sourceRoot":"","sources":["../../src/diff/deleted-orphan-coverage.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AACvD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAU/D;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,kBAAkB,GAAG,gBAAgB,CA6ChF"}

package/dist/diff/deleted-orphan-coverage.js

@@ -0,0 +1,107 @@
+/** How many unexamined labels the coverage carries (the verdict line shows 5). */
+const LABEL_CAP = 20;
+/** How many files-changed-since-the-index the reason names before summarising. */
+const STALE_NAMES_IN_REASON = 3;
+const UNINDEXED_REASON = 'not in the code-graph index, so their importers were never checked';
+/**
+ * What an orphan scan EXAMINED against what the delete asked it to — the one
+ * coverage authority for `check orphans` and the `finish` orphans sub-gate.
+ *
+ * "Who still imports the deleted code?" has two sides, and the code-graph
+ * index must be current on both for a clean answer to mean anything:
+ *
+ *   - the DELETED side: a deleted source file the index does not know (the
+ *     index predates it, or was rebuilt after the delete) had its importers
+ *     never checked — expected, not examined;
+ *   - the IMPORTER side: a file added or edited since the index was built may
+ *     import the deleted code, and the index never read its current imports.
+ *     While any such file exists, NO deleted file's importer set is complete,
+ *     so every deleted file in scope is unexamined and the reason names the
+ *     files the index never read (`scan.indexDivergence`, measured by the one
+ *     freshness authority, `detectGraphFreshness`).
+ *
+ * Defining the unit as "indexed deleted files", or ignoring the importer side,
+ * would make either gap disappear by construction — the clean-over-a-stale-
+ * index verdict this closes.
+ *
+ * Only files the graph would index are in scope (`indexableDeleted`, the
+ * graph's `isGraphIndexablePath`), so deleting a README or a `dist/*.js` next
+ * to a `.ts` still reads clean. Nothing deleted, or nothing deleted that the
+ * graph indexes, is `expected: 0` — "nothing to examine" — which the caller may
+ * accept explicitly with `--allow-empty`; a stale index is irrelevant there
+ * (there is no deleted code for anything to import).
+ */
+export function deletedOrphanCoverage(scan) {
+    const unit = 'deleted code files';
+    const scopeLabel = scan.ref === 'STAGED' ? 'staged' : `vs ${scan.ref}`;
+    if (scan.deleted.length === 0) {
+        return { unit, expected: 0, examined: 0, reason: `nothing deleted (${scopeLabel})` };
+    }
+    const resolved = scan.report?.resolvedDeleted ?? [];
+    const resolvedSet = new Set(resolved);
+    const indexable = new Set(scan.indexableDeleted ?? scan.deleted);
+    const unindexed = (scan.report?.unresolvedDeleted ?? []).filter((p) => indexable.has(p) && !resolvedSet.has(p));
+    const expected = resolved.length + unindexed.length;
+    if (expected === 0) {
+        return {
+            unit,
+            expected: 0,
+            examined: 0,
+            reason: `${scan.deleted.length} file(s) deleted (${scopeLabel}), none of them source the code graph indexes`,
+        };
+    }
+    const stale = staleIndexReason(scan);
+    if (stale !== undefined) {
+        const inScope = [...resolved, ...unindexed];
+        return {
+            unit,
+            expected,
+            examined: 0,
+            unexamined: inScope.slice(0, LABEL_CAP),
+            unexaminedTotal: inScope.length,
+            reason: unindexed.length > 0 ? `not in the code-graph index, or ${stale}` : stale,
+        };
+    }
+    return {
+        unit,
+        expected,
+        examined: resolved.length,
+        ...(unindexed.length > 0
+            ? {
+                unexamined: unindexed.slice(0, LABEL_CAP),
+                unexaminedTotal: unindexed.length,
+                reason: UNINDEXED_REASON,
+            }
+            : {}),
+    };
+}
+/**
+ * Why the importer side is unexamined, or `undefined` when the index is current
+ * for every surviving file. Reads as the tail of `…, K <reason>: <files>`.
+ */
+function staleIndexReason(scan) {
+    const divergence = scan.indexDivergence;
+    if (divergence === undefined)
+        return undefined;
+    if (!divergence.measured)
+        return 'checked against an index whose freshness could not be measured';
+    const changed = divergence.changed;
+    // The package half of the freshness authority: a package entry that changed
+    // since the index (and that the delete does not explain) means a bare
+    // `import … from '<pkg>'` was never re-resolved — the same stale input.
+    const packages = divergence.packagesChanged ?? [];
+    if (changed.length === 0 && packages.length === 0)
+        return undefined;
+    const parts = [];
+    if (changed.length > 0) {
+        const shown = changed.slice(0, STALE_NAMES_IN_REASON).join(', ');
+        const more = changed.length > STALE_NAMES_IN_REASON ? `, +${changed.length - STALE_NAMES_IN_REASON} more` : '';
+        parts.push(`checked against a stale index that never read ${changed.length} file(s) changed since it was built (${shown}${more})`);
+    }
+    if (packages.length > 0) {
+        const shown = packages.slice(0, STALE_NAMES_IN_REASON).join(', ');
+        const more = packages.length > STALE_NAMES_IN_REASON ? `, +${packages.length - STALE_NAMES_IN_REASON} more` : '';
+        parts.push(`${changed.length > 0 ? 'whose' : 'checked against a stale index whose'} package entry changed since it was built (${shown}${more}), so imports through it were never re-resolved`);
+    }
+    return parts.join(', and ');
+}

package/dist/diff/deleted-orphan-scope-notes.d.ts

@@ -0,0 +1,23 @@
+import type { IVerdictCoverage } from '@shrkcrft/core';
+import type { IDeletedOrphanScan } from './deleted-orphans.js';
+/**
+ * What an orphan answer must say about its own scope, next to the verdict line.
+ * Shared by `check orphans` and `impact --deleted`, which answer the same
+ * question ("who still imports the deleted code?") from the same scan and so
+ * must explain a partial answer the same way.
+ *
+ *   - `index` — the `index` kv value, set when indexed code was deleted and the
+ *     importer side is stale (the index never read files changed since it was
+ *     built) or its freshness could not be measured;
+ *   - `lead`  — the NOT VERIFIED lead, set when the coverage left deleted code
+ *     unexamined: why, and the remedy (index the PRE-delete tree, re-run
+ *     `rerun`).
+ *
+ * The coverage itself comes from `deletedOrphanCoverage`, the one authority for
+ * what the scan examined; this only words it.
+ */
+export declare function deletedOrphanScopeNotes(scan: IDeletedOrphanScan, coverage: IVerdictCoverage, rerun: string): {
+    readonly index?: string;
+    readonly lead?: string;
+};
+//# sourceMappingURL=deleted-orphan-scope-notes.d.ts.map

package/dist/diff/deleted-orphan-scope-notes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"deleted-orphan-scope-notes.d.ts","sourceRoot":"","sources":["../../src/diff/deleted-orphan-scope-notes.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AACvD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAE/D;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,uBAAuB,CACrC,IAAI,EAAE,kBAAkB,EACxB,QAAQ,EAAE,gBAAgB,EAC1B,KAAK,EAAE,MAAM,GACZ;IAAE,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,CAqCrD"}

package/dist/diff/deleted-orphan-scope-notes.js

@@ -0,0 +1,49 @@
+/**
+ * What an orphan answer must say about its own scope, next to the verdict line.
+ * Shared by `check orphans` and `impact --deleted`, which answer the same
+ * question ("who still imports the deleted code?") from the same scan and so
+ * must explain a partial answer the same way.
+ *
+ *   - `index` — the `index` kv value, set when indexed code was deleted and the
+ *     importer side is stale (the index never read files changed since it was
+ *     built) or its freshness could not be measured;
+ *   - `lead`  — the NOT VERIFIED lead, set when the coverage left deleted code
+ *     unexamined: why, and the remedy (index the PRE-delete tree, re-run
+ *     `rerun`).
+ *
+ * The coverage itself comes from `deletedOrphanCoverage`, the one authority for
+ * what the scan examined; this only words it.
+ */
+export function deletedOrphanScopeNotes(scan, coverage, rerun) {
+    const divergence = scan.indexDivergence;
+    const packages = divergence?.packagesChanged ?? [];
+    const staleIndex = coverage.expected > 0 &&
+        divergence !== undefined &&
+        (!divergence.measured || divergence.changed.length > 0 || packages.length > 0);
+    const packageNote = packages.length > 0
+        ? `package entry changed (${packages.slice(0, 3).join(', ')}${packages.length > 3 ? `, +${packages.length - 3} more` : ''})`
+        : undefined;
+    const index = staleIndex && divergence !== undefined
+        ? divergence.measured
+            ? `stale — ${[
+                divergence.changed.length > 0 ? `${divergence.changed.length} file(s) changed since it was built` : undefined,
+                packageNote,
+            ]
+                .filter((s) => s !== undefined)
+                .join('; ')}`
+            : 'freshness could not be measured'
+        : undefined;
+    const staleLead = divergence !== undefined && divergence.measured && divergence.changed.length === 0 && packages.length > 0
+        ? `The code-graph index predates a package entry change (${packages.slice(0, 3).join(', ')}), so an import of the deleted code through it was never re-resolved.\n`
+        : 'The code-graph index predates files changed since it was built, so an import of the deleted code in them was never checked.\n';
+    const lead = coverage.expected > 0 && coverage.examined < coverage.expected
+        ? (staleIndex
+            ? staleLead
+            : 'Deleted source files the code-graph index does not know were never checked for importers.\n') +
+            `Index the PRE-delete tree (\`shrk graph index\`), then re-run \`${rerun}\`.`
+        : undefined;
+    return {
+        ...(index !== undefined ? { index } : {}),
+        ...(lead !== undefined ? { lead } : {}),
+    };
+}

package/dist/diff/deleted-orphans.d.ts

@@ -19,6 +19,38 @@ export interface IDeletedOrphanScan {
      * loading the graph, so there is no report (and none is needed).
      */
     readonly report?: IDeletedOrphanReport;
+    /**
+     * The deleted paths the code graph INDEXES (the graph's own authority,
+     * `isGraphIndexablePath` — extension AND skipped directories). A deleted
+     * README or `dist/x.js` is outside the orphan check's scope; a deleted `.ts`
+     * the index does not know is a gap in it. Present iff {@link report} is.
+     * Read by `deletedOrphanCoverage`.
+     */
+    readonly indexableDeleted?: readonly string[];
+    /**
+     * How the code-graph index diverges from the tree on disk, measured by the
+     * one freshness authority (`detectGraphFreshness`). `changed` = indexable
+     * files NEW or MODIFIED since the index was built, the deleted set excluded:
+     * each is a possible importer of the deleted code whose current imports the
+     * index never read, so a clean orphan answer over them proves nothing.
+     * `measured: false` = the divergence could not be measured (also never a
+     * pass). Present iff {@link report} is. Read by `deletedOrphanCoverage`.
+     */
+    readonly indexDivergence?: {
+        readonly measured: boolean;
+        readonly changed: readonly string[];
+        /**
+         * Workspace packages whose entry diverged since the index was built, that
+         * the delete does NOT explain (the one freshness authority's
+         * `packageDivergences`). Package entries are an index input no source
+         * fingerprint covers: after a package.json edit a bare `import … from
+         * '<pkg>'` resolves somewhere else, and the stale index still resolves it
+         * to the old entry — so an importer of the deleted code through it is
+         * invisible. A divergence whose indexed entry FILE is itself in the delete
+         * (dir unchanged) is explained: the orphan query covers imports of it.
+         */
+        readonly packagesChanged?: readonly string[];
+    };
     /** Why the scan failed. Present iff not `ok`. */
     readonly reason?: DeletedOrphanScanFailure;
     /** Human-readable failure detail. */

package/dist/diff/deleted-orphans.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"deleted-orphans.d.ts","sourceRoot":"","sources":["../../src/diff/deleted-orphans.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,yBAAyB,CAAC;AAGpE;;;;GAIG;AACH,MAAM,MAAM,wBAAwB,GAAG,kBAAkB,GAAG,eAAe,CAAC;AAE5E,+CAA+C;AAC/C,MAAM,WAAW,kBAAkB;IACjC,mFAAmF;IACnF,QAAQ,CAAC,EAAE,EAAE,OAAO,CAAC;IACrB,8EAA8E;IAC9E,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,8EAA8E;IAC9E,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC;;;;OAIG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,oBAAoB,CAAC;IACvC,iDAAiD;IACjD,QAAQ,CAAC,MAAM,CAAC,EAAE,wBAAwB,CAAC;IAC3C,qCAAqC;IACrC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,qBAAqB,CACzC,GAAG,EAAE,MAAM,EACX,IAAI,EAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,OAAO,CAAA;CAAE,GACzC,OAAO,CAAC,kBAAkB,CAAC,CAmC7B"}
+{"version":3,"file":"deleted-orphans.d.ts","sourceRoot":"","sources":["../../src/diff/deleted-orphans.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,yBAAyB,CAAC;AAGpE;;;;GAIG;AACH,MAAM,MAAM,wBAAwB,GAAG,kBAAkB,GAAG,eAAe,CAAC;AAE5E,+CAA+C;AAC/C,MAAM,WAAW,kBAAkB;IACjC,mFAAmF;IACnF,QAAQ,CAAC,EAAE,EAAE,OAAO,CAAC;IACrB,8EAA8E;IAC9E,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,8EAA8E;IAC9E,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC;;;;OAIG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,oBAAoB,CAAC;IACvC;;;;;;OAMG;IACH,QAAQ,CAAC,gBAAgB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC9C;;;;;;;;OAQG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE;QACzB,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;QAC3B,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;QACpC;;;;;;;;;WASG;QACH,QAAQ,CAAC,eAAe,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;KAC9C,CAAC;IACF,iDAAiD;IACjD,QAAQ,CAAC,MAAM,CAAC,EAAE,wBAAwB,CAAC;IAC3C,qCAAqC;IACrC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,qBAAqB,CACzC,GAAG,EAAE,MAAM,EACX,IAAI,EAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,OAAO,CAAA;CAAE,GACzC,OAAO,CAAC,kBAAkB,CAAC,CAoE7B"}

package/dist/diff/deleted-orphans.js

@@ -30,7 +30,7 @@ export async function computeDeletedOrphans(cwd, opts) {
     if (changed.deleted.length === 0) {
         return { ok: true, ref: changed.ref, deleted: [] };
     }
-    const { GraphStore, GraphQueryApi } = await import('@shrkcrft/graph');
+    const { GraphStore, GraphQueryApi, detectGraphFreshness, isGraphIndexablePath } = await import('@shrkcrft/graph');
     if (!new GraphStore(cwd).exists()) {
         return {
             ok: false,
@@ -42,5 +42,45 @@ export async function computeDeletedOrphans(cwd, opts) {
     }
     const { findDeletedOrphans } = await import('@shrkcrft/impact-engine');
     const report = findDeletedOrphans(GraphQueryApi.fromStore(cwd), changed.deleted);
-    return { ok: true, ref: changed.ref, deleted: changed.deleted, report };
+    // The importer side of the question: the index answers "who imports the
+    // deleted code?" only for files whose CURRENT imports it has read. A file
+    // added or edited since the index was built may import the deleted code and
+    // the query would never see it — the stale-input shape CLAUDE.md says must be
+    // loud-skipped, measured by the one freshness authority.
+    const freshness = detectGraphFreshness(cwd);
+    const deletedSet = new Set(changed.deleted);
+    const changedSinceIndex = [...freshness.added, ...freshness.modified]
+        .filter((p) => !deletedSet.has(p))
+        .sort((a, b) => a.localeCompare(b));
+    // The package half of the same authority (`graphFreshnessBehind` counts it):
+    // a package entry that diverged since the index, unless the delete itself
+    // explains it. Reading added+modified alone called an index "current" that
+    // `graph status` calls stale (round 11 review).
+    const divergences = freshness.packageDivergences ?? freshness.packagesChanged.map((name) => ({ name }));
+    const packagesChanged = divergences
+        .filter((d) => !deleteExplainsDivergence(d, deletedSet))
+        .map((d) => d.name)
+        .sort((a, b) => a.localeCompare(b));
+    return {
+        ok: true,
+        ref: changed.ref,
+        deleted: changed.deleted,
+        report,
+        indexableDeleted: changed.deleted.filter((p) => isGraphIndexablePath(p)),
+        indexDivergence: {
+            measured: freshness.hasIndex,
+            changed: changedSinceIndex,
+            ...(packagesChanged.length > 0 ? { packagesChanged } : {}),
+        },
+    };
+}
+/**
+ * A package-entry divergence the delete EXPLAINS: the indexed entry file is
+ * part of the delete and the package did not move. Imports of that entry are
+ * exactly what the orphan query checks, so the index is not stale about it.
+ */
+function deleteExplainsDivergence(d, deleted) {
+    return (typeof d.storedEntry === 'string' &&
+        deleted.has(d.storedEntry) &&
+        (d.currentDir === undefined || d.currentDir === d.storedDir));
 }

package/dist/dispatch/closest-match.d.ts

@@ -0,0 +1,15 @@
+/** Levenshtein edit distance — THE one (`@shrkcrft/inspector` `levenshtein`), under the CLI's name. */
+export declare const editDistance: (a: string, b: string) => number;
+/**
+ * Typo tolerance for an attempt: `max(1, floor(len / 4))` edits. A
+ * fingers-on-keys typo (`doctr`) is inside it; a different word is not.
+ */
+export declare function typoTolerance(attempt: string): number;
+/**
+ * Candidates within `tolerance` edits of `attempt` (case-insensitive), nearest
+ * first, ties broken lexically — deterministic. At most `limit`.
+ */
+export declare function closestMatches(attempt: string, candidates: Iterable<string>, limit?: number, tolerance?: number): string[];
+/** The single nearest candidate within `tolerance`, or `undefined`. */
+export declare function nearest(attempt: string, candidates: Iterable<string>, tolerance?: number): string | undefined;
+//# sourceMappingURL=closest-match.d.ts.map

package/dist/dispatch/closest-match.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"closest-match.d.ts","sourceRoot":"","sources":["../../src/dispatch/closest-match.ts"],"names":[],"mappings":"AAgBA,uGAAuG;AACvG,eAAO,MAAM,YAAY,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,KAAK,MAAoB,CAAC;AAE1E;;;GAGG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAErD;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAC5B,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,QAAQ,CAAC,MAAM,CAAC,EAC5B,KAAK,SAAI,EACT,SAAS,GAAE,MAA+B,GACzC,MAAM,EAAE,CAYV;AAED,uEAAuE;AACvE,wBAAgB,OAAO,CACrB,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,QAAQ,CAAC,MAAM,CAAC,EAC5B,SAAS,GAAE,MAA+B,GACzC,MAAM,GAAG,SAAS,CAEpB"}

package/dist/dispatch/closest-match.js

@@ -0,0 +1,47 @@
+/**
+ * The command-TYPO tolerance policy for command NAMES and flags.
+ *
+ * `main.ts` (unknown verb), `help` (unknown topic), the flag guard and the
+ * command-string resolver (`resolveCommandString`) used to carry their own
+ * Levenshtein copies with their own tolerances; two of them agreed only by
+ * coincidence. They all read this now.
+ *
+ * The DISTANCE is not defined here: it is `@shrkcrft/inspector`'s `levenshtein`
+ * (nearest-id.ts), the one edit distance every "did you mean" in the tree
+ * uses. An unknown DECLARED ID (a test id, a rule id, a check id) is not a
+ * command typo — those sites call `nearestIds` (prefix / substring affinity,
+ * a length-scaled cutoff), never this module.
+ */
+import { levenshtein } from '@shrkcrft/inspector';
+/** Levenshtein edit distance — THE one (`@shrkcrft/inspector` `levenshtein`), under the CLI's name. */
+export const editDistance = levenshtein;
+/**
+ * Typo tolerance for an attempt: `max(1, floor(len / 4))` edits. A
+ * fingers-on-keys typo (`doctr`) is inside it; a different word is not.
+ */
+export function typoTolerance(attempt) {
+    return Math.max(1, Math.floor(attempt.length / 4));
+}
+/**
+ * Candidates within `tolerance` edits of `attempt` (case-insensitive), nearest
+ * first, ties broken lexically — deterministic. At most `limit`.
+ */
+export function closestMatches(attempt, candidates, limit = 3, tolerance = typoTolerance(attempt)) {
+    const lower = attempt.toLowerCase();
+    const scored = [];
+    const seen = new Set();
+    for (const c of candidates) {
+        if (seen.has(c))
+            continue;
+        seen.add(c);
+        const d = editDistance(lower, c.toLowerCase());
+        if (d <= tolerance)
+            scored.push({ c, d });
+    }
+    scored.sort((x, y) => (x.d !== y.d ? x.d - y.d : x.c < y.c ? -1 : x.c > y.c ? 1 : 0));
+    return scored.slice(0, limit).map((s) => s.c);
+}
+/** The single nearest candidate within `tolerance`, or `undefined`. */
+export function nearest(attempt, candidates, tolerance = typoTolerance(attempt)) {
+    return closestMatches(attempt, candidates, 1, tolerance)[0];
+}

package/dist/dispatch/global-flags.d.ts

@@ -0,0 +1,94 @@
+import { type CommandRegistry, type IGlobalCompressDirective } from '../command-registry.js';
+/**
+ * The dispatcher's GLOBAL flags — accepted by every command, anywhere before
+ * the `--` sentinel: leading (`shrk --no-hints scaffolds list`), between the
+ * path tokens (`shrk scaffolds --no-hints list`) or trailing
+ * (`shrk scaffolds list --no-hints`).
+ *
+ * `--cwd`, `--exit-trailer` and the `--compress*` family are stripped from the
+ * argv before dispatch; `--strict` (also a per-command flag) and `--no-hints`
+ * reach the handler; `--help` / `-h` are intercepted before any body runs. The
+ * declared-flag guard accepts every one of them on top of a handler's own set,
+ * and the post-run read-tracking detector never judges them.
+ */
+export declare const GLOBAL_FLAGS: ReadonlySet<string>;
+/**
+ * The global flags that take a VALUE — `--cwd <dir>`, `--compress-type <t>`,
+ * `--compress-query <q>` (or the `--flag=value` form). A subset of
+ * {@link GLOBAL_FLAGS}; the pre-dispatch strip removes each with its value.
+ */
+export declare const GLOBAL_VALUE_FLAGS: ReadonlySet<string>;
+/**
+ * Presentation-only flags. An unread one is still WARNED about, but it never
+ * changes the exit: ignoring `--json` or `--verbose` loses formatting, not an
+ * input the verdict depended on. (`-v` is the short `--verbose`.)
+ */
+export declare const SOFT_FLAGS: ReadonlySet<string>;
+/**
+ * A global flag the trie descent steps OVER instead of stopping at — while it
+ * sits inside the command path. Before round 11 a leading `--no-hints` /
+ * `--strict` ended the descent at the first token, so `shrk --no-hints
+ * scaffolds list` reported "shrk doesn't have a `scaffolds list` command" and
+ * `shrk --strict doctor` suggested `shrk doctor`. The descent hoists these into
+ * the handler's argv (before any `--`), so the handler still sees its own
+ * `--strict`.
+ */
+export declare function isPathTransparentGlobal(token: string): boolean;
+/**
+ * A path-transparent global flag that may take the NEXT token as its value:
+ * the bare `--strict` (`doctor --strict warnings` reads `warnings` as the
+ * level). The descent steps over it only while the path continues after it;
+ * past the path it stays in front of its value, never turning the value into a
+ * positional. `--strict=<level>` and `--no-hints` are self-contained.
+ */
+export declare function bindsFollowingValue(token: string): boolean;
+/**
+ * The global flags `runCliInner` strips from ANYWHERE before dispatch
+ * (`extractGlobalCwd`, `extractGlobalCompress`, `extractGlobalExitTrailer`):
+ * every global except the path-transparent ones, which reach the handler, and
+ * `--help` / `-h`, which the help intercept answers. The command-string
+ * resolver strips exactly these, so a documented `shrk --cwd x doctor` and the
+ * real dispatch read the same command.
+ */
+export declare const STRIPPED_GLOBAL_FLAGS: ReadonlySet<string>;
+/**
+ * THE pre-dispatch strip: `--cwd`, `--exit-trailer` and the `--compress*`
+ * family ({@link STRIPPED_GLOBAL_FLAGS}) removed from anywhere before `--`, in
+ * the one order both readers use. `runCliInner` dispatches from `rest`, and
+ * `runCli` derives the verdict path (the pipe note, `--exit-trailer`, the usage
+ * record) from the SAME `rest` — before this, `runCli` stripped only `--cwd` and
+ * `--exit-trailer`, so a leading `--compress` ended the descent at the first
+ * token and `shrk --compress check wiring --exit-trailer` printed no trailer.
+ */
+export declare function stripPreDispatchGlobals(argv: readonly string[]): {
+    readonly cwd?: string;
+    readonly trailer: boolean;
+    readonly compress?: IGlobalCompressDirective;
+    readonly rest: string[];
+};
+/**
+ * Flags every command accepts implicitly — left out of an "Accepts:" list.
+ * `--strict` stays listed: it is also a per-command flag with its own meaning
+ * (`check --strict`).
+ */
+export declare const IMPLICIT_FLAGS: ReadonlySet<string>;
+/**
+ * THE trie-descent options for the dispatcher's global flags. `runCliInner`'s
+ * descent and {@link withoutPathGlobals} (the verdict path and the usage
+ * record) both pass exactly this, so they cannot disagree about where the
+ * command path ends.
+ */
+export declare const PATH_TRANSPARENCY: {
+    readonly transparent: typeof isPathTransparentGlobal;
+    readonly bindsValue: typeof bindsFollowingValue;
+};
+/**
+ * `argv` as the dispatcher reads it: the command path first — spelled as
+ * typed, the path-transparent global flags stepped over exactly as the trie
+ * descent steps over them — then everything else. The view `extractCommandPath`
+ * needs: a leading `--no-hints` does not zero out the verdict path (and with it
+ * `--exit-trailer`), and `doctor --strict warnings` keeps `warnings` as the
+ * value of `--strict`, never a path segment.
+ */
+export declare function withoutPathGlobals(argv: readonly string[], registry: CommandRegistry): string[];
+//# sourceMappingURL=global-flags.d.ts.map

package/dist/dispatch/global-flags.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"global-flags.d.ts","sourceRoot":"","sources":["../../src/dispatch/global-flags.ts"],"names":[],"mappings":"AAAA,OAAO,EAIL,KAAK,eAAe,EACpB,KAAK,wBAAwB,EAC9B,MAAM,wBAAwB,CAAC;AAEhC;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,YAAY,EAAE,WAAW,CAAC,MAAM,CAW3C,CAAC;AAEH;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,EAAE,WAAW,CAAC,MAAM,CAAuD,CAAC;AAE3G;;;;GAIG;AACH,eAAO,MAAM,UAAU,EAAE,WAAW,CAAC,MAAM,CAOzC,CAAC;AAEH;;;;;;;;GAQG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAE9D;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAE1D;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,qBAAqB,EAAE,WAAW,CAAC,MAAM,CAErD,CAAC;AAEF;;;;;;;;GAQG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG;IAChE,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,QAAQ,CAAC,EAAE,wBAAwB,CAAC;IAC7C,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,CAAC;CACzB,CAUA;AAED;;;;GAIG;AACH,eAAO,MAAM,cAAc,EAAE,WAAW,CAAC,MAAM,CAA4D,CAAC;AAE5G;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB;;;CAGpB,CAAC;AAEX;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,EAAE,QAAQ,EAAE,eAAe,GAAG,MAAM,EAAE,CAG/F"}

package/dist/dispatch/global-flags.js

@@ -0,0 +1,123 @@
+import { extractGlobalCompress, extractGlobalCwd, extractGlobalExitTrailer, } from "../command-registry.js";
+/**
+ * The dispatcher's GLOBAL flags — accepted by every command, anywhere before
+ * the `--` sentinel: leading (`shrk --no-hints scaffolds list`), between the
+ * path tokens (`shrk scaffolds --no-hints list`) or trailing
+ * (`shrk scaffolds list --no-hints`).
+ *
+ * `--cwd`, `--exit-trailer` and the `--compress*` family are stripped from the
+ * argv before dispatch; `--strict` (also a per-command flag) and `--no-hints`
+ * reach the handler; `--help` / `-h` are intercepted before any body runs. The
+ * declared-flag guard accepts every one of them on top of a handler's own set,
+ * and the post-run read-tracking detector never judges them.
+ */
+export const GLOBAL_FLAGS = new Set([
+    'cwd',
+    'strict',
+    'no-hints',
+    'exit-trailer',
+    'compress',
+    'ccr',
+    'compress-type',
+    'compress-query',
+    'help',
+    'h',
+]);
+/**
+ * The global flags that take a VALUE — `--cwd <dir>`, `--compress-type <t>`,
+ * `--compress-query <q>` (or the `--flag=value` form). A subset of
+ * {@link GLOBAL_FLAGS}; the pre-dispatch strip removes each with its value.
+ */
+export const GLOBAL_VALUE_FLAGS = new Set(['cwd', 'compress-type', 'compress-query']);
+/**
+ * Presentation-only flags. An unread one is still WARNED about, but it never
+ * changes the exit: ignoring `--json` or `--verbose` loses formatting, not an
+ * input the verdict depended on. (`-v` is the short `--verbose`.)
+ */
+export const SOFT_FLAGS = new Set([
+    'json',
+    'verbose',
+    'v',
+    'quiet',
+    'no-color',
+    'color',
+]);
+/**
+ * A global flag the trie descent steps OVER instead of stopping at — while it
+ * sits inside the command path. Before round 11 a leading `--no-hints` /
+ * `--strict` ended the descent at the first token, so `shrk --no-hints
+ * scaffolds list` reported "shrk doesn't have a `scaffolds list` command" and
+ * `shrk --strict doctor` suggested `shrk doctor`. The descent hoists these into
+ * the handler's argv (before any `--`), so the handler still sees its own
+ * `--strict`.
+ */
+export function isPathTransparentGlobal(token) {
+    return token === '--no-hints' || token === '--strict' || token.startsWith('--strict=');
+}
+/**
+ * A path-transparent global flag that may take the NEXT token as its value:
+ * the bare `--strict` (`doctor --strict warnings` reads `warnings` as the
+ * level). The descent steps over it only while the path continues after it;
+ * past the path it stays in front of its value, never turning the value into a
+ * positional. `--strict=<level>` and `--no-hints` are self-contained.
+ */
+export function bindsFollowingValue(token) {
+    return token === '--strict';
+}
+/**
+ * The global flags `runCliInner` strips from ANYWHERE before dispatch
+ * (`extractGlobalCwd`, `extractGlobalCompress`, `extractGlobalExitTrailer`):
+ * every global except the path-transparent ones, which reach the handler, and
+ * `--help` / `-h`, which the help intercept answers. The command-string
+ * resolver strips exactly these, so a documented `shrk --cwd x doctor` and the
+ * real dispatch read the same command.
+ */
+export const STRIPPED_GLOBAL_FLAGS = new Set([...GLOBAL_FLAGS].filter((f) => f !== 'help' && f !== 'h' && !isPathTransparentGlobal(`--${f}`)));
+/**
+ * THE pre-dispatch strip: `--cwd`, `--exit-trailer` and the `--compress*`
+ * family ({@link STRIPPED_GLOBAL_FLAGS}) removed from anywhere before `--`, in
+ * the one order both readers use. `runCliInner` dispatches from `rest`, and
+ * `runCli` derives the verdict path (the pipe note, `--exit-trailer`, the usage
+ * record) from the SAME `rest` — before this, `runCli` stripped only `--cwd` and
+ * `--exit-trailer`, so a leading `--compress` ended the descent at the first
+ * token and `shrk --compress check wiring --exit-trailer` printed no trailer.
+ */
+export function stripPreDispatchGlobals(argv) {
+    const { cwd, rest: afterCwd } = extractGlobalCwd(argv);
+    const { trailer, rest: afterTrailer } = extractGlobalExitTrailer(afterCwd);
+    const { directive, rest } = extractGlobalCompress(afterTrailer);
+    return {
+        ...(cwd !== undefined ? { cwd } : {}),
+        trailer,
+        ...(directive !== undefined ? { compress: directive } : {}),
+        rest,
+    };
+}
+/**
+ * Flags every command accepts implicitly — left out of an "Accepts:" list.
+ * `--strict` stays listed: it is also a per-command flag with its own meaning
+ * (`check --strict`).
+ */
+export const IMPLICIT_FLAGS = new Set([...GLOBAL_FLAGS].filter((f) => f !== 'strict'));
+/**
+ * THE trie-descent options for the dispatcher's global flags. `runCliInner`'s
+ * descent and {@link withoutPathGlobals} (the verdict path and the usage
+ * record) both pass exactly this, so they cannot disagree about where the
+ * command path ends.
+ */
+export const PATH_TRANSPARENCY = {
+    transparent: isPathTransparentGlobal,
+    bindsValue: bindsFollowingValue,
+};
+/**
+ * `argv` as the dispatcher reads it: the command path first — spelled as
+ * typed, the path-transparent global flags stepped over exactly as the trie
+ * descent steps over them — then everything else. The view `extractCommandPath`
+ * needs: a leading `--no-hints` does not zero out the verdict path (and with it
+ * `--exit-trailer`), and `doctor --strict warnings` keeps `warnings` as the
+ * value of `--strict`, never a path segment.
+ */
+export function withoutPathGlobals(argv, registry) {
+    const resolution = registry.resolve(argv, PATH_TRANSPARENCY);
+    return [...resolution.matchedTokens, ...resolution.rest];
+}

package/dist/dispatch/guard-invocation-input.d.ts

@@ -0,0 +1,24 @@
+import type { CommandRegistry, ICommandHandler, ParsedArgs } from '../command-registry.js';
+import type { ICommandIndex } from '../surface/i-command-index.js';
+/** What the dispatcher knows about one invocation when it asks the guard. */
+export interface IGuardInvocationInput {
+    /** The registry this run dispatches from (the command index is built from it). */
+    readonly registry: CommandRegistry;
+    /** The handler at the deepest matched trie path; `undefined` for a pure command group. */
+    readonly handler: ICommandHandler | undefined;
+    /** The canonical trie path the descent matched. */
+    readonly matchedPath: readonly string[];
+    /** The trie children at the matched node — a mixed-mode parent's or a group's verbs. */
+    readonly trieChildren: readonly string[];
+    /** The handler's parsed argv (the leftover tokens). */
+    readonly parsed: ParsedArgs;
+    /**
+     * Where a `PositionalMode.Path` token is looked up on disk. Absent → no token
+     * names a file: the disk-free reading the command-string resolver uses when it
+     * was given no project root.
+     */
+    readonly cwd?: string;
+    /** The command index of `registry`, when the caller already holds one (else built lazily, memoised per registry). */
+    readonly index?: ICommandIndex;
+}
+//# sourceMappingURL=guard-invocation-input.d.ts.map

package/dist/dispatch/guard-invocation-input.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"guard-invocation-input.d.ts","sourceRoot":"","sources":["../../src/dispatch/guard-invocation-input.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AAC3F,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,+BAA+B,CAAC;AAEnE,6EAA6E;AAC7E,MAAM,WAAW,qBAAqB;IACpC,kFAAkF;IAClF,QAAQ,CAAC,QAAQ,EAAE,eAAe,CAAC;IACnC,0FAA0F;IAC1F,QAAQ,CAAC,OAAO,EAAE,eAAe,GAAG,SAAS,CAAC;IAC9C,mDAAmD;IACnD,QAAQ,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;IACxC,wFAAwF;IACxF,QAAQ,CAAC,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;IACzC,uDAAuD;IACvD,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;IAC5B;;;;OAIG;IACH,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,qHAAqH;IACrH,QAAQ,CAAC,KAAK,CAAC,EAAE,aAAa,CAAC;CAChC"}

package/dist/dispatch/guard-invocation-input.js

@@ -0,0 +1 @@
+export {};