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

package/dist/commands/graph-code-subverbs.d.ts

@@ -15,6 +15,21 @@ export declare function runGraphImpact(args: ParsedArgs): Promise<number>;
  * radius of ONE node; hubs = the nodes with the biggest blast radius).
  */
 export declare function runGraphHubs(args: ParsedArgs): Promise<number>;
+/**
+ * Every module with an import edge INTO the target — the query a module
+ * relocation or deletion actually needs.
+ *
+ * `graph callers <Symbol>` is symbol-scoped and counts call sites, so it misses
+ * the two edges that decide whether a module can move: a type-only import (no
+ * call site exists) and a re-export (the module stays publicly surfaced under
+ * another path). `graph context <file>` lists importers but frames them as
+ * "what surrounds the file you are about to edit". Neither answers "enumerate
+ * everything that would break", which is why the task otherwise falls back to a
+ * hand-rolled grep that misses aliased specifiers, `.js`-suffixed ESM
+ * specifiers, and re-export chains — the exact edges the graph already
+ * resolves.
+ */
+export declare function runGraphImporters(args: ParsedArgs): Promise<number>;
 export declare function runGraphCallers(args: ParsedArgs): Promise<number>;
 /**
  * `shrk graph path <from> <to>` — does code A actually reach code B?

package/dist/commands/graph-code-subverbs.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"graph-code-subverbs.d.ts","sourceRoot":"","sources":["../../src/commands/graph-code-subverbs.ts"],"names":[],"mappings":"AA2BA,OAAO,EAAiE,KAAK,UAAU,EAAE,MAAM,wBAAwB,CAAC;AAgLxH,wBAAsB,aAAa,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAkBrE;AA4FD,wBAAsB,cAAc,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAkFtE;AAiBD,wBAAsB,kBAAkB,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CA2F1E;AAID,wBAAsB,YAAY,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CA+EpE;AAID,wBAAsB,cAAc,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CA+FtE;AAID,wBAAsB,cAAc,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAwEtE;AAID,wBAAsB,eAAe,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CA2MvE;AAID,wBAAsB,cAAc,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CA+HtE;AAID;;;;;;GAMG;AACH,wBAAsB,YAAY,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAgEpE;AAID,wBAAsB,eAAe,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAiGvE;AAyBD;;;;;;;;;;;;GAYG;AACH,wBAAsB,YAAY,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAgHpE"}
+{"version":3,"file":"graph-code-subverbs.d.ts","sourceRoot":"","sources":["../../src/commands/graph-code-subverbs.ts"],"names":[],"mappings":"AA8BA,OAAO,EAAiE,KAAK,UAAU,EAAE,MAAM,wBAAwB,CAAC;AAqKxH,wBAAsB,aAAa,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAkBrE;AA4FD,wBAAsB,cAAc,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAgHtE;AAiBD,wBAAsB,kBAAkB,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CA0G1E;AAID,wBAAsB,YAAY,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CA+EpE;AAID,wBAAsB,cAAc,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CA+GtE;AAID,wBAAsB,cAAc,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAwEtE;AAID,wBAAsB,eAAe,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CA2MvE;AAID,wBAAsB,cAAc,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CA+HtE;AAID;;;;;;GAMG;AACH,wBAAsB,YAAY,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAgEpE;AAID;;;;;;;;;;;;;GAaG;AACH,wBAAsB,iBAAiB,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CA0FzE;AA4CD,wBAAsB,eAAe,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAiGvE;AAyBD;;;;;;;;;;;;GAYG;AACH,wBAAsB,YAAY,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAgHpE"}

package/dist/commands/graph-code-subverbs.js

@@ -5,7 +5,7 @@
  * focused. The entry command imports each `run*` and routes when the
  * first positional matches the subverb name.
  */
-import { buildFullIndex, changedFilesSince, detectChangedAndDeleted, detectGraphFreshness, EdgeKind, GraphQueryApi, GraphStore, hasCallGraphReferences, isGraphStoreCorruptError, NodeKind, updateChanged, } from '@shrkcrft/graph';
+import { buildFullIndex, changedFilesSince, detectChangedAndDeleted, detectGraphFreshness, EdgeKind, GraphQueryApi, GraphStore, graphFreshnessBehind, graphFreshnessCoverage, graphFreshnessRemedy, hasCallGraphReferences, isGraphStoreCorruptError, NodeKind, updateChanged, } from '@shrkcrft/graph';
 import { analyzeGraphImpact } from '@shrkcrft/impact-engine';
 import { BridgeStore, RuleGraphQueryApi } from '@shrkcrft/rule-graph';
 import { FrameworkQueryApi, FrameworkStore } from '@shrkcrft/framework-scanners';
@@ -15,6 +15,9 @@ import { compactArrayToColumnar } from '@shrkcrft/compress';
 import { flagBool, flagNumber, flagPositiveInt, flagString, resolveCwd } from "../command-registry.js";
 import { asJson, header, kv } from "../output/format-output.js";
 import { maybeRunInWatchMode } from "../output/watch-loop.js";
+import { indexBehindHint } from "../graph/index-behind-hint.js";
+import { settleVerdict } from "../gates/settle-verdict.js";
+import { verdictLine } from "../gates/verdict-line.js";
 /**
  * Opt-in `--table`/`--compact`: columnarise each homogeneous object-array field
  * of a graph `--json` payload (compact, still valid JSON, reversible via
@@ -133,21 +136,6 @@ function resultStaleness(api, cwd, paths) {
             : null,
     };
 }
-/**
- * A "the index is N files behind" qualifier for a not-found / empty result, so
- * an agent doesn't read a bare "not-found" as "this symbol doesn't exist / is
- * safe to create" when the truth is "it's in a file the index hasn't seen yet."
- * Runs the full freshness walk — only call it on the rare miss path.
- */
-function indexBehindHint(cwd) {
-    const f = detectGraphFreshness(cwd);
-    if (!f.hasIndex)
-        return null;
-    const behind = f.modified.length + f.added.length + f.deleted.length;
-    if (behind === 0)
-        return null;
-    return `Index is ${behind} file(s) behind (${f.modified.length} modified, ${f.added.length} new, ${f.deleted.length} deleted) — run \`shrk graph index --changed\` and retry.`;
-}
 /**
  * Reject a stray positional on a subverb that takes NO file argument
  * (status/cycles/unresolved/index). These previously printed a byte-identical
@@ -295,6 +283,16 @@ export async function runGraphCycles(args) {
     const typeOnlyLoopCount = Math.max(0, api.cycles({ includeTypeEdges: true }).length - runtimeCycles.length);
     const filtered = allCycles.filter((c) => c.size >= minSize);
     const limited = filtered.slice(0, limit);
+    // A cycle verdict is DERIVED from the persisted index: over an index behind
+    // the working tree, a cycle among the changed files cannot show, so the
+    // clean answer is NOT VERIFIED (2), never "No cycles ✓" (round 11 review
+    // R11-GAP-1). THE freshness authority decides — `detectGraphFreshness`, the
+    // one `graph status` reads — through the shared coverage record.
+    const freshness = detectGraphFreshness(cwd);
+    const staleCoverage = graphFreshnessCoverage(freshness, 'graph index');
+    const settled = settleVerdict(0, staleCoverage ? [staleCoverage] : []);
+    const behind = graphFreshnessBehind(freshness);
+    const indexState = !freshness.hasIndex ? 'unmeasured' : behind > 0 ? 'stale' : 'fresh';
     if (wantJson) {
         process.stdout.write(asJson({
             ok: true,
@@ -306,17 +304,31 @@ export async function runGraphCycles(args) {
                 size: c.size,
                 paths: c.paths ?? c.nodeIds.map((id) => id.replace(/^file:/, '')),
             })),
+            freshness: {
+                state: indexState,
+                behind,
+                ...(staleCoverage ? { nextCommand: graphFreshnessRemedy(freshness) } : {}),
+            },
+            ...(staleCoverage ? { coverage: staleCoverage } : {}),
+            exitCode: settled.exit,
+            verdict: settled.verdict,
+            shortfalls: settled.shortfalls,
         }) + '\n');
-        return 0;
+        return settled.exit;
     }
     process.stdout.write(header('Graph cycles'));
     process.stdout.write(kv('total', String(filtered.length)) + '\n');
+    if (staleCoverage) {
+        process.stdout.write(kv('index', `${indexState} — ${behind} change(s) since it was built; run \`${graphFreshnessRemedy(freshness)}\``) + '\n');
+    }
     if (!includeTypeEdges && typeOnlyLoopCount > 0) {
         process.stdout.write(kv('type-only loops', `${typeOnlyLoopCount} (excluded — compile-time only; --include-type-edges to audit)`) + '\n');
     }
+    const kind = includeTypeEdges ? '' : 'runtime ';
     if (filtered.length === 0) {
-        process.stdout.write(`\nNo ${includeTypeEdges ? '' : 'runtime '}cycles in the file-import graph. ✓\n`);
-        return 0;
+        const line = verdictLine(settled, `No ${kind}cycles in the file-import graph. ✓`, `No ${kind}cycles in the INDEXED graph — but the index is behind the working tree, so a cycle among the changed files cannot show.`);
+        process.stdout.write(`\n${line}\n`);
+        return settled.exit;
     }
     process.stdout.write(kv('shown', `${limited.length}/${filtered.length}`) + '\n');
     process.stdout.write('\n');
@@ -335,7 +347,10 @@ export async function runGraphCycles(args) {
     if (filtered.length > limit) {
         process.stdout.write(`\n(${filtered.length - limit} more — pass --limit ${filtered.length} to see all)\n`);
     }
-    return 0;
+    const tail = verdictLine(settled, '');
+    if (tail)
+        process.stdout.write(`\n${tail}\n`);
+    return settled.exit;
 }
 function parseLimit(args) {
     const raw = flagString(args, 'limit');
@@ -407,6 +422,12 @@ export async function runGraphUnresolved(args) {
         g.specifiers = [...new Set(g.specifiers)].sort();
     const total = list.reduce((n, g) => n + g.specifiers.length, 0);
     const limited = list.slice(0, limit);
+    // A listing (not a verdict verb, so its exit is unchanged) — but a ✓ over an
+    // index behind the working tree is a clean answer derived from a stale input,
+    // so it is dropped and the gap named (the shared freshness record).
+    const freshness = detectGraphFreshness(cwd);
+    const stale = graphFreshnessCoverage(freshness) !== undefined;
+    const behind = graphFreshnessBehind(freshness);
     if (wantJson) {
         process.stdout.write(asJson({
             ok: true,
@@ -417,6 +438,11 @@ export async function runGraphUnresolved(args) {
                 path: g.path ?? g.from.replace(/^file:/, ''),
                 unresolved: g.specifiers,
             })),
+            freshness: {
+                state: !freshness.hasIndex ? 'unmeasured' : stale ? 'stale' : 'fresh',
+                behind,
+                ...(stale ? { nextCommand: graphFreshnessRemedy(freshness) } : {}),
+            },
         }) + '\n');
         return 0;
     }
@@ -424,7 +450,9 @@ export async function runGraphUnresolved(args) {
     process.stdout.write(kv('total edges', String(total)) + '\n');
     process.stdout.write(kv('files', String(list.length)) + '\n');
     if (list.length === 0) {
-        process.stdout.write('\nNo unresolved imports. ✓\n');
+        process.stdout.write(stale
+            ? `\nNo unresolved imports in the INDEXED graph — the index is ${behind} change(s) behind the working tree; run \`${graphFreshnessRemedy(freshness)}\` for a current answer.\n`
+            : '\nNo unresolved imports. ✓\n');
         return 0;
     }
     process.stdout.write(kv('shown', `${limited.length}/${list.length}`) + '\n');
@@ -564,7 +592,10 @@ export async function runGraphStatus(args) {
     // `stale` (disk drift) are orthogonal — a store can be digest-valid yet
     // stale — so precedence is corrupt > stale > fresh.
     const fresh = detectGraphFreshness(cwd);
-    const behind = fresh.modified.length + fresh.added.length + fresh.deleted.length;
+    // Files AND workspace package entries (a package.json-only edit changes what
+    // a bare import resolves to while every source file is byte-identical).
+    const behind = graphFreshnessBehind(fresh);
+    const pkgsChanged = fresh.packagesChanged;
     const state = !verify.ok ? 'corrupt' : behind > 0 ? 'stale' : 'fresh';
     const payload = {
         ok: verify.ok,
@@ -586,7 +617,11 @@ export async function runGraphStatus(args) {
         modifiedSinceIndex: fresh.modified.length,
         newSinceIndex: fresh.added.length,
         deletedSinceIndex: fresh.deleted.length,
-        ...(behind > 0 ? { nextCommand: 'shrk graph index --changed' } : {}),
+        packagesChangedSinceIndex: pkgsChanged.length,
+        ...(pkgsChanged.length > 0 ? { packagesChanged: pkgsChanged } : {}),
+        // An incremental update does not re-resolve unchanged files' imports of a
+        // package whose entry changed; only a full index does.
+        ...(behind > 0 ? { nextCommand: graphFreshnessRemedy(fresh) } : {}),
     };
     if (wantJson) {
         process.stdout.write(asJson(payload) + '\n');
@@ -594,7 +629,11 @@ export async function runGraphStatus(args) {
     }
     process.stdout.write(header('Graph status'));
     process.stdout.write(kv('schema', payload.schema) + '\n');
-    process.stdout.write(kv('files', String(payload.fileCount)) + '\n');
+    // "files indexed", not "files": this is the size of the STORED snapshot, and
+    // it deliberately does not move when a new file appears on disk — that shows
+    // up on the `drift` line below. Reading it as a live count is how an added
+    // file looks invisible to the index.
+    process.stdout.write(kv('files indexed', String(payload.fileCount)) + '\n');
     process.stdout.write(kv('nodes', String(payload.nodeCount)) + '\n');
     process.stdout.write(kv('edges', String(payload.edgeCount)) + '\n');
     process.stdout.write(kv('packages', String(payload.workspacePackages.length)) + '\n');
@@ -608,7 +647,11 @@ export async function runGraphStatus(args) {
     process.stdout.write(kv('last indexed', payload.lastIndexedAt) + '\n');
     process.stdout.write(kv('state', payload.state) + '\n');
     if (behind > 0) {
-        process.stdout.write(kv('drift', `${fresh.modified.length} modified, ${fresh.added.length} new, ${fresh.deleted.length} deleted since index — run \`shrk graph index --changed\``) + '\n');
+        const pkgPart = pkgsChanged.length > 0
+            ? `, ${pkgsChanged.length} workspace package(s) changed (${pkgsChanged.slice(0, 3).join(', ')}${pkgsChanged.length > 3 ? `, +${pkgsChanged.length - 3} more` : ''})`
+            : '';
+        const remedy = `\`${graphFreshnessRemedy(fresh)}\``;
+        process.stdout.write(kv('drift', `${fresh.modified.length} modified, ${fresh.added.length} new, ${fresh.deleted.length} deleted${pkgPart} since index — run ${remedy}`) + '\n');
     }
     return verify.ok ? 0 : 1;
 }
@@ -1078,6 +1121,141 @@ export async function runGraphHubs(args) {
     }
     return 0;
 }
+// ─── shrk graph importers ─────────────────────────────────────────────
+/**
+ * Every module with an import edge INTO the target — the query a module
+ * relocation or deletion actually needs.
+ *
+ * `graph callers <Symbol>` is symbol-scoped and counts call sites, so it misses
+ * the two edges that decide whether a module can move: a type-only import (no
+ * call site exists) and a re-export (the module stays publicly surfaced under
+ * another path). `graph context <file>` lists importers but frames them as
+ * "what surrounds the file you are about to edit". Neither answers "enumerate
+ * everything that would break", which is why the task otherwise falls back to a
+ * hand-rolled grep that misses aliased specifiers, `.js`-suffixed ESM
+ * specifiers, and re-export chains — the exact edges the graph already
+ * resolves.
+ */
+export async function runGraphImporters(args) {
+    const cwd = resolveCwd(args);
+    const wantJson = flagBool(args, 'json');
+    const target = args.positional[1];
+    if (!target) {
+        process.stderr.write('Usage: shrk graph importers <file|module-specifier> [--mode import|reexport|type-only|all] [--limit N|0] [--no-refresh]\n');
+        return 2;
+    }
+    const modeRaw = flagString(args, 'mode') ?? 'all';
+    if (!IMPORTER_MODES.includes(modeRaw)) {
+        process.stderr.write(`Unknown --mode "${modeRaw}" for 'shrk graph importers'. Valid: ${IMPORTER_MODES.join(', ')}.\n`);
+        return 2;
+    }
+    const mode = modeRaw;
+    const limit = resolveListLimit(args, 200);
+    maybeRefresh(args, cwd);
+    const api = loadOrFail(cwd, wantJson);
+    if (!api)
+        return 1;
+    const file = resolveModuleTarget(api, target);
+    if (!file) {
+        const behind = indexBehindHint(cwd);
+        const payload = { ok: false, error: 'not-found', target, ...(behind ? { hint: behind } : {}) };
+        if (wantJson) {
+            process.stdout.write(asJson(payload) + '\n');
+            return 1;
+        }
+        process.stderr.write(`No module matched "${target}". Pass a repo-relative file path or a package specifier.${behind ? ' ' + behind : ''}\n`);
+        return 1;
+    }
+    const all = api.importerEdgesOf(file.id);
+    const selected = all.filter((e) => matchesImporterMode(e, mode));
+    // Targeted staleness over the target + the reported importers, same as
+    // `callers`: drop importers whose file is gone, flag those that changed.
+    const fresh = resultStaleness(api, cwd, [file.path, ...selected.map((e) => e.node.path)]);
+    const live = selected.filter((e) => !e.node.path || !fresh.deletedSet.has(e.node.path));
+    const counts = {
+        import: all.filter((e) => e.kind === 'import' && !e.typeOnly).length,
+        reexport: all.filter((e) => e.kind === 'reexport').length,
+        typeOnly: all.filter((e) => e.typeOnly).length,
+    };
+    const payload = {
+        schema: 'sharkcraft.graph-importers/v1',
+        module: nodeSummary(file),
+        mode,
+        total: live.length,
+        counts,
+        importers: live.slice(0, limit).map((e) => ({
+            ...nodeSummary(e.node),
+            edge: e.typeOnly ? 'type-only' : e.kind,
+        })),
+        ...(counts.reexport > 0
+            ? {
+                note: `${counts.reexport} importer(s) RE-EXPORT this module — deleting or moving it changes a public surface. ` +
+                    'Run with --mode reexport to isolate the bridge chain.',
+            }
+            : {}),
+        ...(fresh.field ?? {}),
+    };
+    if (wantJson) {
+        process.stdout.write(asJson(maybeColumnarize(payload, args)) + '\n');
+        return 0;
+    }
+    process.stdout.write(header(`Graph importers: ${file.path ?? file.id} (${mode})`));
+    process.stdout.write(kv('total', String(live.length)) + '\n');
+    process.stdout.write(kv('by edge', `${counts.import} value · ${counts.typeOnly} type-only · ${counts.reexport} re-export`) + '\n');
+    if (payload.note)
+        process.stdout.write(`  ⓘ ${payload.note}\n`);
+    for (const i of payload.importers.slice(0, Math.min(50, limit))) {
+        process.stdout.write(`  ${i.path ?? i.id}  [${i.edge}]\n`);
+    }
+    if (live.length > Math.min(50, limit)) {
+        process.stdout.write(`  … (${live.length - Math.min(50, limit)} more — pass --limit 0 for all)\n`);
+    }
+    if (fresh.field) {
+        process.stdout.write(`\n  ⚠ ${fresh.modified.length} result file(s) changed, ${fresh.deleted.length} deleted since indexing — run \`shrk graph index --changed\`.\n`);
+    }
+    return 0;
+}
+const IMPORTER_MODES = ['import', 'reexport', 'type-only', 'all'];
+/**
+ * `--mode import` means a VALUE import specifically. A type-only edge is
+ * reported under `type-only` and nowhere else, so the three narrow modes
+ * partition the set and an author cannot double-count by summing them.
+ */
+function matchesImporterMode(edge, mode) {
+    if (mode === 'all')
+        return true;
+    if (mode === 'type-only')
+        return edge.typeOnly;
+    if (mode === 'reexport')
+        return edge.kind === 'reexport';
+    return edge.kind === 'import' && !edge.typeOnly;
+}
+/**
+ * Resolve an importers target to a FILE node, from either a repo-relative path
+ * or a package specifier — both name the same node, and an author asking "who
+ * imports @scope/pkg" should not have to know its entry path first.
+ */
+function resolveModuleTarget(api, target) {
+    const direct = api.findFile(target);
+    if (direct)
+        return direct;
+    if (target.startsWith('file:'))
+        return api.neighbours(target)?.node;
+    // A package or aliased specifier: whichever file the INDEXER resolved it to.
+    // Deriving the entry point here instead would be a second resolver that
+    // disagrees with the graph on exactly the aliased edges this query exists to
+    // surface.
+    const bySpecifier = api.fileForSpecifier(target);
+    if (bySpecifier)
+        return bySpecifier;
+    // A path missing its extension, or a directory meaning its index.
+    for (const ext of ['.ts', '.tsx', '.js', '.jsx', '/index.ts', '/index.js']) {
+        const f = api.findFile(target + ext);
+        if (f)
+            return f;
+    }
+    return undefined;
+}
 // ─── shrk graph callers ───────────────────────────────────────────────
 export async function runGraphCallers(args) {
     const cwd = resolveCwd(args);

package/dist/commands/graph.command.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"graph.command.d.ts","sourceRoot":"","sources":["../../src/commands/graph.command.ts"],"names":[],"mappings":"AAUA,OAAO,EAKL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAqFhC,eAAO,MAAM,YAAY,EAAE,eAqO1B,CAAC"}
+{"version":3,"file":"graph.command.d.ts","sourceRoot":"","sources":["../../src/commands/graph.command.ts"],"names":[],"mappings":"AAUA,OAAO,EAIL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAiLhC,eAAO,MAAM,YAAY,EAAE,eAyO1B,CAAC"}

package/dist/commands/graph.command.js

@@ -1,32 +1,23 @@
 import { mkdirSync, writeFileSync } from 'node:fs';
 import * as nodePath from 'node:path';
 import { analyzeImportGraph, buildKnowledgeGraph, findGraphPath, getGraphNode, inspectSharkcraft, } from '@shrkcrft/inspector';
-import { firstUnknownFlag, flagBool, flagString, resolveCwd, } from "../command-registry.js";
-import { ExitCode } from "../exit-codes.js";
+import { flagBool, flagString, resolveCwd, } from "../command-registry.js";
+import { nearest } from "../dispatch/closest-match.js";
+import { isVerbShaped } from "../dispatch/guard-invocation.js";
+import { PositionalMode } from "../dispatch/positional-mode.js";
+import { usageExitFor } from "../exit-codes.js";
 import { asJson, header, kv } from "../output/format-output.js";
 /**
- * The code-intelligence subverbs that share one arg parser. Each is guarded so
- * an unrecognized/misspelled flag is rejected loudly instead of parsing as a
- * silent `true` that reads as a confident opt-in (a25 §2.1). The allow-set is
- * the UNION of every flag any code-graph subverb reads, plus the global flags,
- * so a real flag is never false-rejected — only a genuinely unknown token is.
+ * The flags the code-intelligence subverbs accept — the UNION of every flag
+ * any of them reads, plus the global / meta flags, so a real flag is never
+ * false-rejected (a25 §2.1). Declared as each code subverb's `flags`
+ * (`GRAPH_SUBVERBS`): the dispatcher refuses any other flag BEFORE the subverb
+ * runs, exiting `usageExitFor` — 3 on the verdict verb `graph cycles`, 2
+ * elsewhere. (Round 11 moved this out of an inline guard in `run`.)
  */
-const CODE_GRAPH_SUBVERBS = new Set([
-    'index',
-    'status',
-    'search',
-    'context',
-    'impact',
-    'path',
-    'hubs',
-    'callers',
-    'cycles',
-    'unresolved',
-    'deps',
-]);
 const CODE_GRAPH_ALLOWED_FLAGS = new Set([
     // code-subverb flags (union across index/status/search/context/impact/path/
-    // hubs/callers/cycles/unresolved/deps)
+    // hubs/callers/importers/cycles/unresolved/deps)
     'changed',
     'compact',
     'depth',
@@ -58,7 +49,53 @@ const CODE_GRAPH_ALLOWED_FLAGS = new Set([
     'no-color',
     'color',
 ]);
-import { runGraphCallers, runGraphContext, runGraphCycles, runGraphDeps, runGraphHubs, runGraphImpact, runGraphIndex, runGraphPath, runGraphSearch, runGraphStatus, runGraphUnresolved, } from "./graph-code-subverbs.js";
+import { runGraphCallers, runGraphContext, runGraphCycles, runGraphDeps, runGraphHubs, runGraphImpact, runGraphImporters, runGraphIndex, runGraphPath, runGraphSearch, runGraphStatus, runGraphUnresolved, } from "./graph-code-subverbs.js";
+function codeGraphSubverb(name, description, usage, positionals) {
+    return {
+        name,
+        description,
+        usage,
+        flags: CODE_GRAPH_ALLOWED_FLAGS,
+        ...(positionals !== undefined ? { positionals } : {}),
+    };
+}
+/**
+ * Every subverb `graph` dispatches from `positional[0]` — the code-intelligence
+ * family (each with the code-graph flag set) plus the knowledge-graph `why` /
+ * `export` / `imports`. Any other token is an asset-graph node id (Free).
+ * Declared so `help graph importers` prints real usage and the command index
+ * lists them (they have no catalog rows of their own).
+ */
+const GRAPH_SUBVERBS = [
+    codeGraphSubverb('index', 'Build or refresh the code graph (`--changed` for incremental; `--watch` keeps it fresh).', 'shrk graph index [--changed] [--since <ref>] [--full] [--watch [--paths a,b] [--debounce N] [--once]] [--json]'),
+    codeGraphSubverb('status', 'Code-graph freshness, counts, and the unresolved-import summary.', 'shrk graph status [--json]'),
+    codeGraphSubverb('search', 'Find files / symbols / packages in the code graph.', 'shrk graph search <query> [--kind file|symbol|package] [--limit N] [--json]', PositionalMode.Free),
+    codeGraphSubverb('context', 'Inspect one file or symbol with bridge enrichment.', 'shrk graph context <fileOrSymbol> [--depth N] [--limit N|0] [--no-bridge] [--no-framework] [--json]', PositionalMode.Free),
+    codeGraphSubverb('impact', 'The reverse dependent closure of a file or symbol.', 'shrk graph impact <fileOrSymbol> [--max-depth N] [--limit N|0] [--full] [--json]', PositionalMode.Free),
+    codeGraphSubverb('path', 'Is code A wired to code B? The shortest import / call path.', 'shrk graph path <from> <to> [--max-depth N] [--no-refresh] [--json]', PositionalMode.Free),
+    codeGraphSubverb('hubs', 'The most-depended-on symbols / files (load-bearing code; scope it to a subsystem).', 'shrk graph hubs [--limit N] [--path <dir>] [--mode <mode>] [--json]'),
+    codeGraphSubverb('callers', 'The files that call / reference a symbol, as path:line.', 'shrk graph callers <symbol> [--mode call|reference] [--limit N|0] [--no-refresh] [--json]', PositionalMode.Free),
+    codeGraphSubverb('importers', 'Every module that imports a module — alias / type-only / re-export aware.', 'shrk graph importers <file|module-specifier> [--mode import|reexport|type-only|all] [--limit N|0] [--no-refresh] [--json]', PositionalMode.Free),
+    codeGraphSubverb('cycles', 'The import cycles (type-only edges excluded unless --include-type-edges).', 'shrk graph cycles [--include-type-edges] [--min-size N] [--limit N] [--json]'),
+    codeGraphSubverb('unresolved', 'The unresolved imports, grouped by file.', 'shrk graph unresolved [--json]'),
+    codeGraphSubverb('deps', 'Inbound / outbound package dependencies.', 'shrk graph deps <package-name> [--json]', PositionalMode.Free),
+    {
+        name: 'why',
+        description: 'The shortest-path explanation between two knowledge-graph nodes.',
+        usage: 'shrk graph why <fromId> <toId> [--json]',
+        positionals: PositionalMode.Free,
+    },
+    {
+        name: 'export',
+        description: 'Write the knowledge graph as dot / mermaid / json.',
+        usage: 'shrk graph export --format dot|mermaid|json --output <file>',
+    },
+    {
+        name: 'imports',
+        description: 'Import-graph analysis: cycles, fan-in / fan-out, orphans.',
+        usage: 'shrk graph imports [--cycles] [--fan-in] [--fan-out] [--orphans] [--json]',
+    },
+];
 const KNOWN_KINDS = [
     'knowledge',
     'rule',
@@ -72,27 +109,19 @@ const KNOWN_KINDS = [
 ];
 export const graphCommand = {
     name: 'graph',
-    description: 'Show the SharkCraft knowledge graph and the code-intelligence graph surface. Use `shrk graph <id>` for asset-graph nodes and `shrk graph index|status|search|context|impact|path|hubs|callers|cycles|unresolved|deps|why|export` for code-graph workflows.',
+    // Free: any token that names no subverb is an asset-graph node id.
+    positionals: PositionalMode.Free,
+    subverbs: GRAPH_SUBVERBS,
+    description: 'Show the SharkCraft knowledge graph and the code-intelligence graph surface. Use `shrk graph <id>` for asset-graph nodes and `shrk graph index|status|search|context|impact|path|hubs|callers|importers|cycles|unresolved|deps|why|export` for code-graph workflows.',
     usage: 'shrk [--cwd <dir>] graph [<id>] [--type <kind>] [--format text|json|dot|mermaid] [--output <file>] [--json]\n' +
-        'shrk graph index|status|search|context|impact|path|hubs|callers|cycles|unresolved|deps|why|export ...\n' +
+        'shrk graph index|status|search|context|impact|path|hubs|callers|importers|cycles|unresolved|deps|why|export ...\n' +
         'shrk graph path <from> <to>   — is code A wired to code B? (shortest import/call path)\n' +
         'shrk graph hubs [--limit N] [--path <dir>]   — most-depended-on symbols/files (load-bearing code; scope to a subsystem)',
     async run(args) {
         // Code-intelligence subverbs (R65) don't need the knowledge graph —
-        // dispatch them before the expensive inspection so they stay fast.
+        // dispatch them before the expensive inspection so they stay fast. Their
+        // flags were already judged by the dispatcher (GRAPH_SUBVERBS `flags`).
         const earlySub = args.positional[0];
-        // Reject unknown/misspelled flags on the code-graph family BEFORE dispatch:
-        // an unrecognized flag must never parse as a silent success (a25 §2.1). Any
-        // real flag is in the union allow-set, so this only fires on a genuine typo.
-        if (typeof earlySub === 'string' && CODE_GRAPH_SUBVERBS.has(earlySub)) {
-            const unknown = firstUnknownFlag(args, CODE_GRAPH_ALLOWED_FLAGS);
-            if (unknown) {
-                const dash = unknown.length === 1 ? '-' : '--';
-                process.stderr.write(`unknown option '${dash}${unknown}' for 'shrk graph ${earlySub}'. ` +
-                    `Run 'shrk graph --help' for valid flags.\n`);
-                return ExitCode.NotVerified;
-            }
-        }
         if (earlySub === 'index')
             return runGraphIndex(args);
         if (earlySub === 'status')
@@ -109,6 +138,8 @@ export const graphCommand = {
             return runGraphHubs(args);
         if (earlySub === 'callers')
             return runGraphCallers(args);
+        if (earlySub === 'importers')
+            return runGraphImporters(args);
         if (earlySub === 'cycles')
             return runGraphCycles(args);
         if (earlySub === 'unresolved')
@@ -214,6 +245,17 @@ export const graphCommand = {
         if (id) {
             const node = getGraphNode(graph, typeFlag ? { kind: typeFlag, id } : { id });
             if (!node) {
+                // A verb-shaped id one typo from a graph subverb (`graph statsu`,
+                // `graph importrs foo`) is a mistyped verb, not a missing node: name
+                // the closest subverb and exit as the usage error it is — never the
+                // failure verdict 1 of an absent node.
+                const sub = isVerbShaped(id) ? nearest(id, GRAPH_SUBVERBS.map((s) => s.name)) : undefined;
+                if (sub !== undefined) {
+                    process.stderr.write(`\`shrk graph\` has no \`${id}\` subcommand, and no graph node is named "${id}".\n` +
+                        `  Did you mean \`shrk graph ${sub}\`?\n` +
+                        '  Run `shrk help graph` for usage.\n');
+                    return usageExitFor('graph');
+                }
                 process.stderr.write(`No graph node for "${id}".\n`);
                 return 1;
             }

package/dist/commands/help.command.d.ts

@@ -1,21 +1,45 @@
-import type { CommandRegistry } from '../command-registry.js';
+import { type CommandRegistry } from '../command-registry.js';
+import { type ISurfaceSummary } from '../surface/surface-summary.js';
+/** `help`'s arguments: a ParsedArgs subset (callers may pass positional + flags only). */
+interface IHelpArgs {
+    positional: string[];
+    flags: Map<string, string | boolean>;
+    globalCwd?: string;
+}
 /**
  * Product start screen for bare `shrk` / `shrk --help`. Shows the
  * curated ~20-command "starter" surface organized by workflow phase.
  * Everything else stays callable; users see the full ~70-verb catalog
  * via `shrk --full-help` or browse it through `shrk surface list`.
  *
+ * `shown(command)` is the repository's surface: a curated line whose command
+ * `surface.hidden` hides, or the surface gate refuses (`surface.disabled`,
+ * experimental, tool-maintenance), is dropped — and a section left empty with
+ * it. The default shows every line (the text is then byte-identical to the
+ * pre-round-11 screen).
+ *
  * Returns the lines (without trailing newline). Pulled into a function
  * so tests can assert on the structure without grepping stdout.
  */
-export declare function renderStartScreen(): string;
+export declare function renderStartScreen(shown?: (command: string) => boolean): string;
+/**
+ * `--full-help`, rendered FROM the surface summary. Without `all` it lists
+ * exactly the views whose `visibleInHelp` is true — every one at least once —
+ * so `surface.hidden`, profiles, `surface.disabled` and the tool-maintenance
+ * host gate all reach it. With `all` it lists every view, annotated
+ * `(hidden)` / `(gated: …)` rather than dropped.
+ *
+ * Placement (not visibility) still reads the catalog: a visible view on the
+ * rent-paying surface goes under its top-level verb or group; an explain /
+ * dry-run view goes in its own section (and, when it is also rent-paying, in
+ * its group too).
+ */
+export declare function renderFullHelp(registry: CommandRegistry, summary: ISurfaceSummary, all: boolean): string;
 export declare function makeHelpCommand(registry: CommandRegistry): {
     name: string;
     description: string;
     usage: string;
-    run(args: {
-        positional: string[];
-        flags: Map<string, string | boolean>;
-    }): number;
+    run(args: IHelpArgs): number | Promise<number>;
 };
+export {};
 //# sourceMappingURL=help.command.d.ts.map

package/dist/commands/help.command.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"help.command.d.ts","sourceRoot":"","sources":["../../src/commands/help.command.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AA4H9D;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,IAAI,MAAM,CAwC1C;AAED,wBAAgB,eAAe,CAAC,QAAQ,EAAE,eAAe;;;;cAK3C;QAAE,UAAU,EAAE,MAAM,EAAE,CAAC;QAAC,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,CAAA;KAAE,GAAG,MAAM;EA2KpF"}
+{"version":3,"file":"help.command.d.ts","sourceRoot":"","sources":["../../src/commands/help.command.ts"],"names":[],"mappings":"AACA,OAAO,EAAc,KAAK,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAW1E,OAAO,EAIL,KAAK,eAAe,EACrB,MAAM,+BAA+B,CAAC;AAIvC,0FAA0F;AAC1F,UAAU,SAAS;IACjB,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC;IACrC,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAwJD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,GAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAoB,GAAG,MAAM,CA0B1F;AA0DD;;;;;;;;;;;GAWG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,eAAe,EAAE,OAAO,EAAE,eAAe,EAAE,GAAG,EAAE,OAAO,GAAG,MAAM,CAmFxG;AAcD,wBAAgB,eAAe,CAAC,QAAQ,EAAE,eAAe;;;;cAO3C,SAAS,GAAG,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;EA6GjD"}