@shrkcrft/cli 0.1.0-alpha.22 → 0.1.0-alpha.24

package/dist/commands/wiring.command.js

@@ -0,0 +1,384 @@
+import { buildRegistrationGraph, explainWiring, registrationChain, registrationGraphSignature, registrationOrphans, registrationUnprovided, } from '@shrkcrft/boundaries';
+import { resolveProjectConfig } from '@shrkcrft/inspector';
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import * as nodePath from 'node:path';
+import { flagBool, resolveCwd } from "../command-registry.js";
+import { asJson, header, kv } from "../output/format-output.js";
+const SITE_DISPLAY_CAP = 50;
+/**
+ * Render an {@link IWiringExplain} to stdout. Shared by `wiring explain`,
+ * `wiring test`, and `check wiring --explain` so all three speak the same
+ * dialect. JSON emits the full payload; text mirrors `search tuning explain`
+ * (header → loaded sets → per-site detail → the set-difference → verdict).
+ * Always returns 0 — explain is informational, the verdict is in the output.
+ */
+export function renderWiringExplain(report, wantJson) {
+    if (wantJson) {
+        process.stdout.write(asJson(report) + '\n');
+        return 0;
+    }
+    process.stdout.write(header(`Wiring explain: ${report.ruleId} (${report.mode})`));
+    if (report.description)
+        process.stdout.write(`  ${report.description}\n`);
+    if (report.groupBy)
+        process.stdout.write(kv('groupBy', report.groupBy) + '\n');
+    process.stdout.write(kv('declared', `${report.declared.distinctCount} distinct across ${report.declared.filesScanned} file(s)`) +
+        '\n');
+    process.stdout.write(kv('registered', `${report.registered.distinctCount} distinct across ${report.registered.filesScanned} file(s)`) + '\n');
+    if (report.declared.error)
+        process.stdout.write(`  ! declared side: ${report.declared.error}\n`);
+    if (report.registered.error) {
+        process.stdout.write(`  ! registered side: ${report.registered.error}\n`);
+    }
+    writeSites('Declared sites', report.declared.sites);
+    writeSites('Registered sites', report.registered.sites);
+    if (report.declaredNotRegistered.length > 0) {
+        process.stdout.write(`\nDeclared but NOT registered (${report.declaredNotRegistered.length}):\n`);
+        for (const s of report.declaredNotRegistered.slice(0, SITE_DISPLAY_CAP)) {
+            process.stdout.write(`  ✗ ${s.token}  (${s.file}:${s.line})\n`);
+        }
+        if (report.declaredNotRegistered.length > SITE_DISPLAY_CAP) {
+            process.stdout.write(`  … (${report.declaredNotRegistered.length - SITE_DISPLAY_CAP} more)\n`);
+        }
+    }
+    if (report.registeredNotDeclared.length > 0) {
+        process.stdout.write(`\nRegistered but NOT declared (parity, ${report.registeredNotDeclared.length}):\n`);
+        for (const s of report.registeredNotDeclared.slice(0, SITE_DISPLAY_CAP)) {
+            process.stdout.write(`  ✗ ${s.token}  (${s.file}:${s.line})\n`);
+        }
+        if (report.registeredNotDeclared.length > SITE_DISPLAY_CAP) {
+            process.stdout.write(`  … (${report.registeredNotDeclared.length - SITE_DISPLAY_CAP} more)\n`);
+        }
+    }
+    for (const d of report.diagnostics)
+        process.stdout.write(`  ! ${d}\n`);
+    process.stdout.write(`\nVerdict: ${report.verdict}\n`);
+    return 0;
+}
+function writeSites(label, sites) {
+    process.stdout.write(`\n${label} (${sites.length}):\n`);
+    if (sites.length === 0) {
+        process.stdout.write('  (none extracted)\n');
+        return;
+    }
+    for (const s of sites.slice(0, SITE_DISPLAY_CAP)) {
+        process.stdout.write(`  • ${s.token}  (${s.file}:${s.line})\n`);
+    }
+    if (sites.length > SITE_DISPLAY_CAP) {
+        process.stdout.write(`  … (${sites.length - SITE_DISPLAY_CAP} more)\n`);
+    }
+}
+/** Light structural check: a candidate must at least name an id + both sides. */
+function validateCandidate(raw) {
+    if (raw === null || typeof raw !== 'object') {
+        return { error: 'candidate must be a JSON object describing a wiring rule' };
+    }
+    const r = raw;
+    if (typeof r['id'] !== 'string' || r['id'].length === 0) {
+        return { error: 'candidate is missing a non-empty string "id"' };
+    }
+    const declared = r['declared'];
+    if (declared === null || typeof declared !== 'object' || !Array.isArray(declared.files)) {
+        return { error: 'candidate "declared" must be a source object with a files[] glob list' };
+    }
+    if (r['registered'] === undefined) {
+        return { error: 'candidate is missing "registered" (a source object or an array of them)' };
+    }
+    // Deeper misconfiguration (bad regex / no capture group) is surfaced as a
+    // diagnostic by the engine, not rejected here — that is the point of a dry run.
+    return { rule: raw };
+}
+async function wiringExplain(args) {
+    const cwd = resolveCwd(args);
+    const wantJson = flagBool(args, 'json');
+    const ruleId = args.positional[1];
+    if (!ruleId) {
+        process.stderr.write('Usage: shrk wiring explain <ruleId> [--json]\n');
+        return 2;
+    }
+    const loaded = await resolveProjectConfig(cwd);
+    if (!loaded.ok) {
+        const msg = loaded.error.message;
+        if (wantJson)
+            process.stdout.write(asJson({ ok: false, error: msg }) + '\n');
+        else
+            process.stderr.write(`Could not load config: ${msg}\n`);
+        return 1;
+    }
+    const rules = loaded.value.config.wiringRules ?? [];
+    const rule = rules.find((r) => r.id === ruleId);
+    if (!rule) {
+        const ids = rules.map((r) => r.id);
+        if (wantJson) {
+            process.stdout.write(asJson({ ok: false, error: 'not-found', ruleId, available: ids }) + '\n');
+            return 2;
+        }
+        process.stderr.write(`No wiring rule "${ruleId}". Configured rules: ${ids.length > 0 ? ids.join(', ') : '(none)'}\n`);
+        return 2;
+    }
+    return renderWiringExplain(explainWiring(cwd, rule), wantJson);
+}
+async function wiringTest(args) {
+    const cwd = resolveCwd(args);
+    const wantJson = flagBool(args, 'json');
+    const candidateArg = args.positional[1];
+    if (!candidateArg) {
+        process.stderr.write('Usage: shrk wiring test <candidate.json | inline-json> [--json]\n' +
+            '  Dry-runs an ephemeral wiring rule against the live tree without writing config.\n');
+        return 2;
+    }
+    // A leading `{` is treated as inline JSON; otherwise the arg is a file path.
+    let source;
+    if (candidateArg.trimStart().startsWith('{')) {
+        source = candidateArg;
+    }
+    else {
+        if (!existsSync(candidateArg)) {
+            const msg = `candidate file not found: ${candidateArg}`;
+            if (wantJson)
+                process.stdout.write(asJson({ ok: false, error: msg }) + '\n');
+            else
+                process.stderr.write(msg + '\n');
+            return 2;
+        }
+        source = readFileSync(candidateArg, 'utf8');
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(source);
+    }
+    catch (e) {
+        const msg = `candidate is not valid JSON: ${e instanceof Error ? e.message : String(e)}`;
+        if (wantJson)
+            process.stdout.write(asJson({ ok: false, error: msg }) + '\n');
+        else
+            process.stderr.write(msg + '\n');
+        return 2;
+    }
+    const { rule, error } = validateCandidate(parsed);
+    if (!rule) {
+        if (wantJson)
+            process.stdout.write(asJson({ ok: false, error }) + '\n');
+        else
+            process.stderr.write(`Invalid candidate: ${error}\n`);
+        return 2;
+    }
+    return renderWiringExplain(explainWiring(cwd, rule), wantJson);
+}
+/**
+ * Load the configured DI/registration idioms and build the graph, cached by a
+ * signature of the exact source files it reads + an idiom hash. Repeated session
+ * queries (chain + unprovided + orphans) reuse ONE scan; any edit to a matched
+ * file shifts the signature and rebuilds, so the cache can never return a stale
+ * verdict (no `shrk graph index` required — the cache tracks its real data
+ * source, not the unrelated code-graph digest). Best-effort — any read/write
+ * error falls back to a fresh build.
+ */
+async function loadRegistrationGraph(cwd) {
+    const loaded = await resolveProjectConfig(cwd);
+    if (!loaded.ok)
+        return { ok: false, idioms: [], error: loaded.error.message };
+    const idioms = loaded.value.config.registrationGraph ?? [];
+    if (idioms.length === 0)
+        return { ok: true, idioms: [] };
+    const cacheKey = registrationCacheKey(cwd, idioms);
+    const cachePath = nodePath.join(cwd, '.sharkcraft', 'cache', 'registration-graph.json');
+    if (cacheKey) {
+        const cached = readRegistrationCache(cachePath, cacheKey);
+        if (cached)
+            return { ok: true, idioms, graph: cached };
+    }
+    const graph = buildRegistrationGraph(cwd, idioms);
+    if (cacheKey)
+        writeRegistrationCache(cachePath, cacheKey, graph);
+    return { ok: true, idioms, graph };
+}
+/**
+ * `<file-signature>:<idiom-hash>` — keyed on the mtime/size signature of the
+ * exact files the graph is built from (its real data source), NOT the code-graph
+ * index digest. Any source edit shifts the signature even when no reindex has
+ * run, so the persisted cache can never return a stale wiring verdict. Undefined
+ * only if signing itself throws (then the query rebuilds every time).
+ */
+function registrationCacheKey(cwd, idioms) {
+    try {
+        const signature = registrationGraphSignature(cwd, idioms);
+        const idiomHash = createHash('sha1').update(JSON.stringify(idioms)).digest('hex').slice(0, 16);
+        return `${signature}:${idiomHash}`;
+    }
+    catch {
+        return undefined;
+    }
+}
+function readRegistrationCache(cachePath, key) {
+    try {
+        if (!existsSync(cachePath))
+            return undefined;
+        const cached = JSON.parse(readFileSync(cachePath, 'utf8'));
+        return cached.key === key && cached.graph ? cached.graph : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function writeRegistrationCache(cachePath, key, graph) {
+    try {
+        mkdirSync(nodePath.dirname(cachePath), { recursive: true });
+        writeFileSync(cachePath, JSON.stringify({ key, graph }));
+    }
+    catch {
+        // best-effort cache; a write failure never breaks the query.
+    }
+}
+function noIdiomsHint(wantJson) {
+    if (wantJson) {
+        process.stdout.write(asJson({ schema: 'sharkcraft.registration-graph/v1', idioms: [], tokens: [] }) + '\n');
+        return 0;
+    }
+    process.stdout.write(header('Registration graph'));
+    process.stdout.write('  No registration idioms configured. Declare `registrationGraph[]` in\n' +
+        '  sharkcraft.config.ts (declared/provided/consumed shapes) to model your DI\n' +
+        '  wiring as a queryable graph — see docs/wiring.md.\n');
+    return 0;
+}
+function siteLine(s) {
+    return `${s.file}:${s.line} [${s.idiom}]`;
+}
+async function wiringChain(args) {
+    const cwd = resolveCwd(args);
+    const wantJson = flagBool(args, 'json');
+    const token = args.positional[1];
+    if (!token) {
+        process.stderr.write('Usage: shrk wiring chain <token> [--json]\n');
+        return 2;
+    }
+    const loaded = await loadRegistrationGraph(cwd);
+    if (!loaded.ok) {
+        if (wantJson)
+            process.stdout.write(asJson({ ok: false, error: loaded.error }) + '\n');
+        else
+            process.stderr.write(`Could not load config: ${loaded.error}\n`);
+        return 1;
+    }
+    if (!loaded.graph)
+        return noIdiomsHint(wantJson);
+    const chain = registrationChain(loaded.graph, token);
+    if (!chain) {
+        if (wantJson) {
+            process.stdout.write(asJson({ ok: false, error: 'not-found', token }) + '\n');
+            return 1;
+        }
+        process.stdout.write(header(`Wiring chain: ${token}`));
+        process.stdout.write('  Token not found in the registration graph.\n');
+        return 1;
+    }
+    if (wantJson) {
+        process.stdout.write(asJson(chain) + '\n');
+        return 0;
+    }
+    process.stdout.write(header(`Wiring chain: ${token}`));
+    const section = (label, sites) => {
+        process.stdout.write(`\n${label} (${sites.length}):\n`);
+        if (sites.length === 0)
+            process.stdout.write('  (none)\n');
+        for (const s of sites)
+            process.stdout.write(`  • ${siteLine(s)}\n`);
+    };
+    section('declared', chain.declared);
+    section('provided', chain.provided);
+    section('consumed', chain.consumed);
+    if (!chain.isProvided && (chain.isDeclared || chain.isConsumed)) {
+        process.stdout.write('\n  ⚠ UNPROVIDED — declared/injected but never provided (silent at runtime).\n');
+    }
+    else if (chain.isProvided && !chain.isConsumed) {
+        process.stdout.write('\n  ⚠ ORPHAN — provided but nothing consumes it.\n');
+    }
+    else {
+        process.stdout.write('\n  ✓ declared → provided → consumed.\n');
+    }
+    return 0;
+}
+async function wiringUnprovided(args) {
+    const cwd = resolveCwd(args);
+    const wantJson = flagBool(args, 'json');
+    const loaded = await loadRegistrationGraph(cwd);
+    if (!loaded.ok) {
+        if (wantJson)
+            process.stdout.write(asJson({ ok: false, error: loaded.error }) + '\n');
+        else
+            process.stderr.write(`Could not load config: ${loaded.error}\n`);
+        return 1;
+    }
+    if (!loaded.graph)
+        return noIdiomsHint(wantJson);
+    const unprovided = registrationUnprovided(loaded.graph);
+    if (wantJson) {
+        process.stdout.write(asJson({ schema: loaded.graph.schema, total: unprovided.length, unprovided }) + '\n');
+        return unprovided.length > 0 ? 1 : 0;
+    }
+    process.stdout.write(header('Unprovided tokens (declared/injected but never provided)'));
+    if (unprovided.length === 0) {
+        process.stdout.write('  ✓ Every declared/injected token has a provider. ✓\n');
+        return 0;
+    }
+    process.stdout.write(`  ${unprovided.length} token(s) resolve to nothing at runtime:\n`);
+    for (const u of unprovided) {
+        const site = u.declared[0] ?? u.consumed[0];
+        const where = site ? `  (${siteLine(site)})` : '';
+        process.stdout.write(`  ✗ ${u.token}${where}\n`);
+    }
+    return 1;
+}
+async function wiringOrphans(args) {
+    const cwd = resolveCwd(args);
+    const wantJson = flagBool(args, 'json');
+    const loaded = await loadRegistrationGraph(cwd);
+    if (!loaded.ok) {
+        if (wantJson)
+            process.stdout.write(asJson({ ok: false, error: loaded.error }) + '\n');
+        else
+            process.stderr.write(`Could not load config: ${loaded.error}\n`);
+        return 1;
+    }
+    if (!loaded.graph)
+        return noIdiomsHint(wantJson);
+    const orphans = registrationOrphans(loaded.graph);
+    if (wantJson) {
+        process.stdout.write(asJson({ schema: loaded.graph.schema, total: orphans.length, orphans }) + '\n');
+        return 0;
+    }
+    process.stdout.write(header('Orphan registrations (provided but nothing consumes)'));
+    if (orphans.length === 0) {
+        process.stdout.write('  ✓ Every provided token is consumed somewhere. ✓\n');
+        return 0;
+    }
+    process.stdout.write(`  ${orphans.length} provided token(s) nothing injects:\n`);
+    for (const o of orphans) {
+        const site = o.provided[0];
+        process.stdout.write(`  • ${o.token}${site ? `  (${siteLine(site)})` : ''}\n`);
+    }
+    return 0;
+}
+const WIRING_USAGE = 'shrk wiring explain <ruleId> | test <candidate.json|inline> | chain <token> | unprovided | orphans [--json]';
+export const wiringCommand = {
+    name: 'wiring',
+    description: 'Author-loop + runtime-wiring queries (no config write): `explain <ruleId>` / `test <candidate>` show what a wiring rule extracts; `chain <token>` / `unprovided` / `orphans` query the DI/registration graph (declared→provided→consumed) for the silent-at-runtime bugs imports can\'t see.',
+    usage: WIRING_USAGE,
+    booleanFlags: new Set(['json']),
+    async run(args) {
+        const sub = args.positional[0];
+        if (sub === 'explain')
+            return wiringExplain(args);
+        if (sub === 'test')
+            return wiringTest(args);
+        if (sub === 'chain')
+            return wiringChain(args);
+        if (sub === 'unprovided')
+            return wiringUnprovided(args);
+        if (sub === 'orphans')
+            return wiringOrphans(args);
+        process.stderr.write(`Usage: ${WIRING_USAGE}\n`);
+        return 2;
+    },
+};

package/dist/diff/collect-changed-paths.d.ts

@@ -1,7 +1,7 @@
 /**
- * CLI-side `--since <ref>` helper. Thin wrapper over `git diff
- * --name-status <ref>...HEAD` that returns the changed file set + a
- * deleted file set + an `isAvailable` flag so callers can fall back
+ * CLI-side `--since <ref>` helper. Thin wrapper over a two-dot `git diff
+ * --name-status <ref>` (working tree vs `<ref>`) that returns the changed file
+ * set + a deleted file set + an `isAvailable` flag so callers can fall back
  * to whole-tree mode cleanly.
  *
  * Default ref resolution when `--since` is passed without a value:
@@ -23,5 +23,7 @@ export declare function resolveDefaultSinceRef(cwd: string): string | undefined;
 export declare function collectChangedPaths(opts: {
     cwd: string;
     ref?: string;
+    /** Read the staged (index) diff instead of diffing against a ref. */
+    staged?: boolean;
 }): IChangedPaths;
 //# sourceMappingURL=collect-changed-paths.d.ts.map

package/dist/diff/collect-changed-paths.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"collect-changed-paths.d.ts","sourceRoot":"","sources":["../../src/diff/collect-changed-paths.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,aAAa;IAC5B,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3B,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3B,WAAW,EAAE,OAAO,CAAC;IACrB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAMD,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAYtE;AAED,wBAAgB,mBAAmB,CAAC,IAAI,EAAE;IACxC,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,CAAC,EAAE,MAAM,CAAC;CACd,GAAG,aAAa,CA+ChB"}
+{"version":3,"file":"collect-changed-paths.d.ts","sourceRoot":"","sources":["../../src/diff/collect-changed-paths.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,aAAa;IAC5B,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3B,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3B,WAAW,EAAE,OAAO,CAAC;IACrB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAMD,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAOtE;AAoCD,wBAAgB,mBAAmB,CAAC,IAAI,EAAE;IACxC,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,qEAAqE;IACrE,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB,GAAG,aAAa,CAwDhB"}

package/dist/diff/collect-changed-paths.js

@@ -1,22 +1,72 @@
-import { execSync } from 'node:child_process';
 import * as nodePath from 'node:path';
+import { runGitLines } from '@shrkcrft/shared';
 const DEFAULT_REF_CANDIDATES = ['origin/main', 'main', 'origin/master', 'master'];
 const PER_PROCESS_CACHE = new Map();
 export function resolveDefaultSinceRef(cwd) {
     for (const candidate of DEFAULT_REF_CANDIDATES) {
-        try {
-            execSync(`git -C "${cwd}" rev-parse --verify --quiet "${candidate}"`, {
-                stdio: 'pipe',
-            });
+        if (runGitLines(cwd, ['rev-parse', '--verify', '--quiet', candidate]).ok) {
             return candidate;
         }
-        catch {
-            // try next
-        }
     }
     return undefined;
 }
+function toPosix(path) {
+    return nodePath.normalize(path).split(nodePath.sep).join('/');
+}
+/**
+ * Split `git diff --name-status` lines into changed vs deleted POSIX paths.
+ * Rename/copy detection is ON by default for `git diff`, so a rename emits a
+ * TAB-separated `R<score>\t<old>\t<new>` (copy: `C<score>\t<old>\t<new>`) — the
+ * status field is `R100`, not a bare letter. The old path of a RENAME is gone
+ * (so the orphan check must treat it as deleted); a COPY keeps its source. Every
+ * other status (A/M/T/…) carries a single path. Parsing the status by its first
+ * letter + splitting on TAB is what makes a `git mv` that orphans an importer
+ * visible to `check orphans` / `finish` instead of silently dropped.
+ */
+function parseNameStatus(lines) {
+    const changed = [];
+    const deleted = [];
+    for (const line of lines) {
+        const parts = line.split('\t');
+        if (parts.length < 2)
+            continue;
+        const code = parts[0][0];
+        if (code === 'D') {
+            deleted.push(toPosix(parts[1]));
+        }
+        else if ((code === 'R' || code === 'C') && parts.length >= 3) {
+            // R<score>\t<old>\t<new> (rename) / C<score>\t<old>\t<new> (copy).
+            if (code === 'R')
+                deleted.push(toPosix(parts[1])); // old path renamed away
+            changed.push(toPosix(parts[2])); // new path is added
+        }
+        else {
+            changed.push(toPosix(parts[1]));
+        }
+    }
+    return { changed, deleted };
+}
 export function collectChangedPaths(opts) {
+    if (opts.staged) {
+        const cacheKey = `${opts.cwd}::staged`;
+        const cached = PER_PROCESS_CACHE.get(cacheKey);
+        if (cached)
+            return cached;
+        const out = runGitLines(opts.cwd, ['diff', '--name-status', '--cached']);
+        if (!out.ok) {
+            return {
+                ref: 'STAGED',
+                changed: [],
+                deleted: [],
+                isAvailable: false,
+                ...(out.error ? { error: out.error } : {}),
+            };
+        }
+        const { changed, deleted } = parseNameStatus(out.lines);
+        const result = { ref: 'STAGED', changed, deleted, isAvailable: true };
+        PER_PROCESS_CACHE.set(cacheKey, result);
+        return result;
+    }
     const ref = opts.ref ?? resolveDefaultSinceRef(opts.cwd);
     if (!ref) {
         return {
@@ -27,42 +77,29 @@ export function collectChangedPaths(opts) {
             error: 'no resolvable default branch (tried origin/main, main, origin/master, master)',
         };
     }
-    const cacheKey = `${opts.cwd}::${ref}`;
+    // Namespace the ref cache key so a branch/tag literally named `staged` can't
+    // collide with the `::staged` index-diff key above.
+    const cacheKey = `${opts.cwd}::ref::${ref}`;
     const cached = PER_PROCESS_CACHE.get(cacheKey);
     if (cached)
         return cached;
-    try {
-        // Two-dot diff against the ref to match the inspector's
-        // `getChangedFiles({ since })` behavior — includes both committed
-        // changes and the working tree relative to <ref>.
-        const stdout = execSync(`git -C "${opts.cwd}" diff --name-status "${ref}"`, { stdio: ['ignore', 'pipe', 'pipe'], encoding: 'utf8' });
-        const changed = [];
-        const deleted = [];
-        for (const line of stdout.split('\n')) {
-            const trimmed = line.trim();
-            if (!trimmed)
-                continue;
-            const m = trimmed.match(/^(\w)\s+(.+)$/);
-            if (!m)
-                continue;
-            const [, status, path] = m;
-            const norm = nodePath.normalize(path).split(nodePath.sep).join('/');
-            if (status === 'D')
-                deleted.push(norm);
-            else
-                changed.push(norm);
-        }
-        const result = { ref, changed, deleted, isAvailable: true };
-        PER_PROCESS_CACHE.set(cacheKey, result);
-        return result;
-    }
-    catch (e) {
+    // Two-dot diff against the ref to match the inspector's
+    // `getChangedFiles({ since })` behavior — includes both committed
+    // changes and the working tree relative to <ref>. `runGitLines` is
+    // shell-free + high-maxBuffer, so a large changeset no longer ENOBUFS-crashes
+    // the `impact --deleted` orphan check (this is its only write-safety guard).
+    const out = runGitLines(opts.cwd, ['diff', '--name-status', ref]);
+    if (!out.ok) {
         return {
             ref,
             changed: [],
             deleted: [],
             isAvailable: false,
-            error: e instanceof Error ? e.message : String(e),
+            ...(out.error ? { error: out.error } : {}),
         };
     }
+    const { changed, deleted } = parseNameStatus(out.lines);
+    const result = { ref, changed, deleted, isAvailable: true };
+    PER_PROCESS_CACHE.set(cacheKey, result);
+    return result;
 }

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

@@ -0,0 +1,42 @@
+import type { IDeletedOrphanReport } from '@shrkcrft/impact-engine';
+/**
+ * Why the scan could not produce an orphan report (so callers pick an exit
+ * code / message): the diff was unavailable (no resolvable ref, git error) or
+ * the code-graph store is missing.
+ */
+export type DeletedOrphanScanFailure = 'diff-unavailable' | 'graph-missing';
+/** Result of {@link computeDeletedOrphans}. */
+export interface IDeletedOrphanScan {
+    /** True when the diff resolved (and, when anything was deleted, the graph too). */
+    readonly ok: boolean;
+    /** What was diffed: `'STAGED'` for `--staged`, otherwise the resolved ref. */
+    readonly ref: string;
+    /** Deleted files read from the diff (empty list is a valid, clean result). */
+    readonly deleted: readonly string[];
+    /**
+     * The alias-resolved orphan report. Present iff `ok` AND something was
+     * deleted — when `deleted` is empty the scan short-circuits clean without
+     * loading the graph, so there is no report (and none is needed).
+     */
+    readonly report?: IDeletedOrphanReport;
+    /** Why the scan failed. Present iff not `ok`. */
+    readonly reason?: DeletedOrphanScanFailure;
+    /** Human-readable failure detail. */
+    readonly error?: string;
+}
+/**
+ * Diff-driven reverse-closure: read the files DELETED in the changeset (vs
+ * `since`, or the staged index when `staged`), then query the code-graph
+ * snapshot for surviving files that still import them or reference a symbol
+ * they declared (alias-resolved, incl. barrel re-exports). The shared core
+ * behind `impact --deleted`, `check orphans`, and the composite `finish` gate.
+ *
+ * Never throws: a bad diff → `{ reason: 'diff-unavailable' }`, a missing index
+ * → `{ reason: 'graph-missing' }`. Graph + engine are imported lazily so a
+ * command that never hits the orphan path doesn't pay to load them.
+ */
+export declare function computeDeletedOrphans(cwd: string, opts: {
+    since?: string;
+    staged?: boolean;
+}): Promise<IDeletedOrphanScan>;
+//# sourceMappingURL=deleted-orphans.d.ts.map

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

@@ -0,0 +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"}

package/dist/diff/deleted-orphans.js

@@ -0,0 +1,46 @@
+import { collectChangedPaths } from "./collect-changed-paths.js";
+/**
+ * Diff-driven reverse-closure: read the files DELETED in the changeset (vs
+ * `since`, or the staged index when `staged`), then query the code-graph
+ * snapshot for surviving files that still import them or reference a symbol
+ * they declared (alias-resolved, incl. barrel re-exports). The shared core
+ * behind `impact --deleted`, `check orphans`, and the composite `finish` gate.
+ *
+ * Never throws: a bad diff → `{ reason: 'diff-unavailable' }`, a missing index
+ * → `{ reason: 'graph-missing' }`. Graph + engine are imported lazily so a
+ * command that never hits the orphan path doesn't pay to load them.
+ */
+export async function computeDeletedOrphans(cwd, opts) {
+    const changed = collectChangedPaths({
+        cwd,
+        ...(opts.since ? { ref: opts.since } : {}),
+        ...(opts.staged ? { staged: true } : {}),
+    });
+    if (!changed.isAvailable) {
+        return {
+            ok: false,
+            ref: changed.ref,
+            deleted: [],
+            reason: 'diff-unavailable',
+            ...(changed.error ? { error: changed.error } : {}),
+        };
+    }
+    // Nothing deleted → clean by definition; don't pay to load the graph (and
+    // don't fail when no index exists — there is nothing to check).
+    if (changed.deleted.length === 0) {
+        return { ok: true, ref: changed.ref, deleted: [] };
+    }
+    const { GraphStore, GraphQueryApi } = await import('@shrkcrft/graph');
+    if (!new GraphStore(cwd).exists()) {
+        return {
+            ok: false,
+            ref: changed.ref,
+            deleted: changed.deleted,
+            reason: 'graph-missing',
+            error: 'code-graph store missing — run `shrk graph index` first.',
+        };
+    }
+    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 };
+}