@shrkcrft/cli 0.1.0-alpha.21 → 0.1.0-alpha.23

package/dist/commands/gate.command.js

@@ -1,4 +1,5 @@
 import { QualityGateReportStore, renderGateReportMarkdown, runQualityGates, } from '@shrkcrft/quality-gates';
+import { inspectSharkcraft, resolveChangedFiles, resolveProjectConfig, } from '@shrkcrft/inspector';
 import { chmodSync, existsSync, mkdirSync, writeFileSync } from 'node:fs';
 import * as nodePath from 'node:path';
 import { flagBool, flagString, resolveCwd, } from "../command-registry.js";
@@ -18,7 +19,7 @@ import { asJson, header, kv } from "../output/format-output.js";
 export const gateCommand = {
     name: 'gate',
     description: 'Aggregator: runs the code-intelligence quality gates (graph freshness, architecture, impact-since-ref) and reports a single pass/fail.',
-    usage: 'shrk gate [--since <gitref>] [--fail-on critical,high] [--arch-all] [--disable arch,impact,api-diff] [--api-baseline <path>] [--no-fail-on-breaking] [--strict] [--no-persist] [--json] [--markdown] [--output <path>]\n         (the arch gate is baseline-relative by default once a baseline is frozen — fails only on NEW errors; --arch-all fails on total)\n         shrk gate scaffold-ci [--provider github|generic] [--force] [--json]\n         shrk gate scaffold-hook [--provider husky|raw] [--force] [--json]',
+    usage: 'shrk gate [--since <gitref>] [--changed-only] [--staged] [--files a,b,c] [--fail-on critical,high] [--arch-all] [--disable arch,impact,policy,knowledge-symbol,api-diff] [--api-baseline <path>] [--no-fail-on-breaking] [--strict] [--no-persist] [--json] [--markdown] [--output <path>]\n         (the arch gate is baseline-relative once a baseline is frozen — fails only on NEW errors; with no baseline it warns on errors rather than going perpetually red — --arch-all fails on total, --strict escalates the warn)\n         (--changed-only / --staged / --files / --since scope the wiring + policy + knowledge-symbol gates to the changeset; they also drive the impact gate — --since diffs the gitref, the others analyze the changed-file set)\n         shrk gate scaffold-ci [--provider github|generic] [--force] [--json]\n         shrk gate scaffold-hook [--provider husky|raw] [--force] [--json]',
     async run(args) {
         if (args.positional[0] === 'scaffold-ci') {
             const sliced = { ...args, positional: args.positional.slice(1) };
@@ -38,19 +39,115 @@ export const gateCommand = {
         const disableRaw = flagString(args, 'disable');
         const apiBaseline = flagString(args, 'api-baseline');
         const noFailOnBreaking = flagBool(args, 'no-fail-on-breaking');
-        const failOn = failOnRaw
+        // `--fail-on` accepts only `high` / `critical`. An unknown token used to
+        // silently REPLACE the default `['critical']`, leaving nothing able to fail
+        // the gate — reject it loudly (exit 2) instead.
+        const failOnTokens = failOnRaw
             ? failOnRaw.split(',').map((s) => s.trim()).filter(Boolean)
             : undefined;
+        if (failOnTokens) {
+            const allowedRisk = new Set(['high', 'critical']);
+            const unknown = failOnTokens.filter((t) => !allowedRisk.has(t));
+            if (unknown.length > 0) {
+                process.stderr.write(`Unknown --fail-on value(s): ${unknown.join(', ')}. Allowed: high, critical.\n`);
+                return 2;
+            }
+        }
+        const failOn = failOnTokens && failOnTokens.length > 0
+            ? failOnTokens
+            : undefined;
         const disable = disableRaw ? disableRaw.split(',').map((s) => s.trim()).filter(Boolean) : undefined;
         // --arch-all: fail on TOTAL architecture errors (ignore the frozen baseline).
         // By default the arch gate is baseline-relative — it fails only on NEW errors.
         const archAll = flagBool(args, 'arch-all');
+        // Changeset scope. `--changed-only` (tracked + untracked worktree),
+        // `--staged`, `--files`, and `--since` all narrow the wiring + policy +
+        // knowledge-symbol gates to the change. `--since` additionally drives the
+        // (ref-based) impact gate, as before.
+        const changedOnly = flagBool(args, 'changed-only');
+        const staged = flagBool(args, 'staged');
+        const filesRaw = flagString(args, 'files');
+        const fileList = filesRaw ? filesRaw.split(',').map((s) => s.trim()).filter(Boolean) : [];
+        const wantChangedScope = changedOnly || staged || Boolean(sinceRef) || fileList.length > 0;
+        let changedFiles;
+        if (wantChangedScope) {
+            const resolved = resolveChangedFiles({
+                projectRoot: cwd,
+                ...(fileList.length > 0 ? { files: fileList } : {}),
+                ...(staged ? { staged: true } : {}),
+                ...(sinceRef ? { since: sinceRef } : {}),
+                ...(changedOnly && !staged && !sinceRef && fileList.length === 0
+                    ? { includeWorktree: true }
+                    : {}),
+            });
+            changedFiles = resolved.files;
+        }
+        // Wiring + policy rules come from the project config; each gate is skipped
+        // (never red) when none are declared, so they're inert for projects that
+        // don't opt in. An INVALID config is surfaced (warn) rather than silently
+        // disabling the plane.
+        const loadedConfig = await resolveProjectConfig(cwd);
+        const wiringRules = loadedConfig.ok ? loadedConfig.value.config.wiringRules ?? [] : [];
+        const policyRules = loadedConfig.ok ? loadedConfig.value.config.policyRules ?? [] : [];
+        const configError = loadedConfig.ok ? undefined : loadedConfig.error.message;
+        // Pack-plane merge notes (missing/invalid pack rule files, dropped
+        // collisions) go to stderr so they never pollute the JSON/markdown report
+        // on stdout that CI consumes.
+        if (loadedConfig.ok) {
+            for (const d of loadedConfig.value.planeDiagnostics) {
+                process.stderr.write(`plane: ${d}\n`);
+            }
+        }
+        const scopeOpts = wantChangedScope
+            ? { changedOnly: true, changedFiles: changedFiles ?? [] }
+            : {};
+        // Knowledge symbol-ref integrity needs the loaded knowledge entries. The
+        // inspection is async, so we build it here and inject it; the gate stays
+        // synchronous and resolves the code graph itself. Best-effort — a failed
+        // inspection just skips the gate rather than failing `shrk gate`.
+        let inspection;
+        if (!disable?.includes('knowledge-symbol')) {
+            try {
+                inspection = await inspectSharkcraft({ cwd });
+            }
+            catch {
+                inspection = undefined;
+            }
+        }
         const report = runQualityGates({
             projectRoot: cwd,
             ...(archAll ? { arch: { baselineRelative: false } } : {}),
+            wiring: {
+                ...(configError
+                    ? { configError }
+                    : wiringRules.length > 0
+                        ? { rules: wiringRules }
+                        : {}),
+                ...scopeOpts,
+            },
+            policy: {
+                ...(configError
+                    ? { configError }
+                    : policyRules.length > 0
+                        ? { rules: policyRules }
+                        : {}),
+                ...scopeOpts,
+            },
+            ...(inspection
+                ? {
+                    knowledgeSymbol: {
+                        inspection,
+                        ...(wantChangedScope ? { changedFiles: changedFiles ?? [] } : {}),
+                    },
+                }
+                : {}),
             impact: {
                 ...(sinceRef ? { sinceRef } : {}),
                 ...(failOn ? { failOn } : {}),
+                // Scope the impact gate to the changeset too: with `--since` we keep the
+                // gitref diff; with `--changed-only` / `--staged` / `--files` (and no
+                // `--since`) we analyze the resolved changed-file set directly.
+                ...(wantChangedScope && !sinceRef ? { files: changedFiles ?? [] } : {}),
             },
             ...(apiBaseline
                 ? {

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":"AA0BA,OAAO,EAAoC,KAAK,UAAU,EAAE,MAAM,wBAAwB,CAAC;AAiI3F,wBAAsB,aAAa,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAgBrE;AA4FD,wBAAsB,cAAc,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CA+DtE;AAiBD,wBAAsB,kBAAkB,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAwF1E;AAID,wBAAsB,YAAY,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CA8EpE;AAID,wBAAsB,cAAc,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAmFtE;AAID,wBAAsB,cAAc,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAiDtE;AAID,wBAAsB,eAAe,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAgMvE;AAID,wBAAsB,cAAc,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CA8HtE;AAID;;;;;;GAMG;AACH,wBAAsB,YAAY,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CA+CpE;AAID,wBAAsB,eAAe,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAkGvE;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":"AA2BA,OAAO,EAAqD,KAAK,UAAU,EAAE,MAAM,wBAAwB,CAAC;AA+J5G,wBAAsB,aAAa,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAkBrE;AA4FD,wBAAsB,cAAc,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAkEtE;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,CA0MvE;AAID,wBAAsB,cAAc,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CA8HtE;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,CAkGvE;AAyBD;;;;;;;;;;;;GAYG;AACH,wBAAsB,YAAY,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAgHpE"}

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

@@ -5,14 +5,14 @@
  * 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, NodeKind, updateChanged, } from '@shrkcrft/graph';
+import { buildFullIndex, changedFilesSince, detectChangedAndDeleted, detectGraphFreshness, EdgeKind, GraphQueryApi, GraphStore, 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';
 import { existsSync } from 'node:fs';
 import * as nodePath from 'node:path';
 import { compactArrayToColumnar } from '@shrkcrft/compress';
-import { flagBool, flagString, resolveCwd } from "../command-registry.js";
+import { flagBool, flagPositiveInt, flagString, resolveCwd } from "../command-registry.js";
 import { asJson, header, kv } from "../output/format-output.js";
 import { maybeRunInWatchMode } from "../output/watch-loop.js";
 /**
@@ -59,6 +59,14 @@ function maybeColumnarize(payload, args) {
 }
 const STALE_HINT = `Index is missing or stale. Run 'shrk graph index' to build it.`;
 const STALE_RESULT_HINT = 'Some result files changed since the index was built — auto-refresh is on by default (you passed --no-refresh / SHRK_GRAPH_NO_REFRESH). Drop the opt-out, or run `shrk graph index --changed`, for fresh results.';
+const CORRUPT_HINT = 'code graph store is corrupt — run `shrk graph index` to rebuild.';
+/**
+ * Per-list display cap for `graph context`. The JSON payload always reports the
+ * true pre-slice count (`total<List>`) and a `<list>Truncated` flag so a
+ * high-fan-in node is never silently capped (mirrors runGraphCycles /
+ * runGraphCallers). Kept in sync with the MCP `get_graph_context` tool.
+ */
+const CONTEXT_LIST_CAP = 50;
 /**
  * Refresh-by-default: incrementally reindex changed/deleted files BEFORE
  * querying so an agent's just-saved edits are reflected, then print a one-line
@@ -122,8 +130,31 @@ function indexBehindHint(cwd) {
         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
+ * global report for any/no/bogus arg, so `shrk graph status foo` silently
+ * swallowed `foo`. Returns the exit code to use (2) when an unexpected
+ * positional[1+] is present, or null when the args are clean. `subverb` is
+ * positional[0]; anything at positional[1] is the offending extra.
+ */
+function strayPositionalError(args, subverb) {
+    const extra = args.positional[1];
+    if (extra === undefined)
+        return null;
+    if (flagBool(args, 'json')) {
+        process.stdout.write(asJson({ ok: false, error: 'unexpected-argument', argument: extra }) + '\n');
+    }
+    else {
+        process.stderr.write(`'shrk graph ${subverb}' takes no positional argument (got "${extra}"). Usage: shrk graph ${subverb} [--json]\n`);
+    }
+    return 2;
+}
 // ─── shrk graph index ─────────────────────────────────────────────────
 export async function runGraphIndex(args) {
+    const stray = strayPositionalError(args, 'index');
+    if (stray !== null)
+        return stray;
     // --watch: run the index once, then re-run on file changes. Every
     // tick after the first uses the incremental updater so a 5-file edit
     // takes < 100ms. Default watch path is the project root; pass
@@ -214,6 +245,9 @@ async function runGraphIndexOnce(args) {
 export async function runGraphCycles(args) {
     const cwd = resolveCwd(args);
     const wantJson = flagBool(args, 'json');
+    const stray = strayPositionalError(args, 'cycles');
+    if (stray !== null)
+        return stray;
     const limit = parseLimit(args);
     const minSize = parseMinSize(args);
     const store = new GraphStore(cwd);
@@ -230,7 +264,9 @@ export async function runGraphCycles(args) {
         process.stderr.write(STALE_HINT + '\n');
         return 1;
     }
-    const api = GraphQueryApi.fromStore(cwd);
+    const api = loadGuarded(() => GraphQueryApi.fromStore(cwd), wantJson);
+    if (!api)
+        return 1;
     const allCycles = api.cycles();
     const filtered = allCycles.filter((c) => c.size >= minSize);
     const limited = filtered.slice(0, limit);
@@ -289,6 +325,9 @@ function parseMinSize(args) {
 export async function runGraphUnresolved(args) {
     const cwd = resolveCwd(args);
     const wantJson = flagBool(args, 'json');
+    const stray = strayPositionalError(args, 'unresolved');
+    if (stray !== null)
+        return stray;
     const limit = parseLimit(args);
     const store = new GraphStore(cwd);
     if (!store.exists()) {
@@ -304,7 +343,9 @@ export async function runGraphUnresolved(args) {
         process.stderr.write(STALE_HINT + '\n');
         return 1;
     }
-    const snap = store.loadSnapshot();
+    const snap = loadGuarded(() => store.loadSnapshot(), wantJson);
+    if (!snap)
+        return 1;
     const groups = new Map();
     for (const e of snap.edges.values()) {
         if (e.kind !== EdgeKind.ImportsFile)
@@ -396,7 +437,9 @@ export async function runGraphDeps(args) {
         process.stderr.write(STALE_HINT + '\n');
         return 1;
     }
-    const api = GraphQueryApi.fromStore(cwd);
+    const api = loadGuarded(() => GraphQueryApi.fromStore(cwd), wantJson);
+    if (!api)
+        return 1;
     const pkgId = `package:${pkg}`;
     // Existence guard (mirrors the MCP tool): without it, an unknown package
     // name returns a confidently-wrong empty `dependsOn/dependedOnBy` that reads
@@ -453,6 +496,9 @@ export async function runGraphDeps(args) {
 export async function runGraphStatus(args) {
     const cwd = resolveCwd(args);
     const wantJson = flagBool(args, 'json');
+    const stray = strayPositionalError(args, 'status');
+    if (stray !== null)
+        return stray;
     const store = new GraphStore(cwd);
     if (!store.exists()) {
         const payload = {
@@ -468,8 +514,20 @@ export async function runGraphStatus(args) {
         process.stderr.write(STALE_HINT + '\n');
         return 1;
     }
-    const verify = store.verifyDigest();
-    const snap = store.loadSnapshot();
+    // A corrupt store (a truncated/garbled JSONL row) must surface as a `corrupt`
+    // status line + non-zero exit, NOT a raw `Fatal: JSON Parse error` crash.
+    let verify;
+    let snap;
+    try {
+        verify = store.verifyDigest();
+        snap = store.loadSnapshot();
+    }
+    catch (err) {
+        const code = emitCorruptStore(err, wantJson);
+        if (code !== null)
+            return code;
+        throw err;
+    }
     const manifestNodeCount = sumValues(snap.manifest.nodesByKind);
     const manifestEdgeCount = sumValues(snap.manifest.edgesByKind);
     // Honest freshness vs the working tree. `corrupt` (store self-integrity) and
@@ -536,40 +594,63 @@ export async function runGraphSearch(args) {
         return 2;
     }
     const kindFlag = flagString(args, 'kind');
-    const limit = Number(flagString(args, 'limit') ?? '20');
+    // NaN-safe --limit: a fat-fingered `--limit abc` must fall back to the default,
+    // not become `Number('abc') === NaN` (which zeroed the result via a NaN slice).
+    const limit = flagPositiveInt(args, 'limit', 20);
     maybeRefresh(args, cwd);
     const api = loadOrFail(cwd, wantJson);
     if (!api)
         return 1;
-    let matches;
+    // Compute the TRUE pre-slice match count so `total`/`truncated` stay honest —
+    // the old code reported the post-cap length as the total, so 285 matches read
+    // as `total: 20` with no signal there was more.
+    let page;
+    let total;
     if (hasUnresolved) {
         const all = api.filesWithUnresolvedImports();
-        matches = (query
+        const filtered = query
             ? all.filter((n) => (n.path ?? '').toLowerCase().includes(query.toLowerCase()))
-            : [...all]).slice(0, limit);
+            : [...all];
+        total = filtered.length;
+        page = filtered.slice(0, limit);
     }
     else {
-        matches = collectSearchMatches(api, query, kindFlag, limit);
-    }
+        const res = collectSearchMatches(api, query, kindFlag, limit);
+        page = res.matches;
+        total = res.total;
+    }
+    // Targeted staleness over the displayed page (parity with MCP / callers): drop
+    // deleted result files, flag modified ones, and reduce `total` by the
+    // deletions we observed so a dead file is never counted.
+    const summarised = page.map(toSearchHit);
+    const fresh = resultStaleness(api, cwd, summarised.map((m) => m.path));
+    const live = summarised.filter((m) => !m.path || !fresh.deletedSet.has(m.path));
+    const adjustedTotal = total - (summarised.length - live.length);
+    const truncated = adjustedTotal > limit;
     if (wantJson) {
         process.stdout.write(asJson({
             schema: 'sharkcraft.graph-search/v1',
             query,
             kind: kindFlag ?? 'any',
-            total: matches.length,
-            matches: matches.map(toSearchHit),
+            total: adjustedTotal,
+            truncated,
+            matches: live,
+            ...(fresh.field ?? {}),
         }) + '\n');
         return 0;
     }
     const headerLabel = query ?? (hasUnresolved ? 'files with unresolved imports' : '');
-    if (matches.length === 0) {
+    if (live.length === 0) {
         process.stdout.write(`No matches for "${headerLabel}".\n`);
         return 0;
     }
     process.stdout.write(header(`Graph search: ${headerLabel}`));
-    for (const m of matches) {
+    for (const m of live) {
         process.stdout.write(`  ${m.kind.padEnd(8)} ${m.label}${m.path ? '  ' + m.path : ''}${m.line ? ':' + m.line : ''}\n`);
     }
+    if (truncated) {
+        process.stdout.write(`\n(${adjustedTotal - live.length} more — pass --limit ${adjustedTotal} to see all)\n`);
+    }
     return 0;
 }
 // ─── shrk graph context ───────────────────────────────────────────────
@@ -581,7 +662,7 @@ export async function runGraphContext(args) {
         process.stderr.write('Usage: shrk graph context <fileOrSymbol> [--depth N] [--no-bridge] [--no-framework]\n');
         return 2;
     }
-    const depth = Math.max(1, Math.min(3, Number(flagString(args, 'depth') ?? '1')));
+    const depth = Math.min(3, flagPositiveInt(args, 'depth', 1));
     const includeBridge = !flagBool(args, 'no-bridge');
     const includeFramework = !flagBool(args, 'no-framework');
     maybeRefresh(args, cwd);
@@ -622,16 +703,18 @@ export async function runGraphContext(args) {
     const frameworkEntities = (includeFramework && frameworkStore.exists() && anchorFile?.path)
         ? FrameworkQueryApi.fromStore(cwd).forFile(anchorFile.path)
         : [];
-    const importsFromList = neighbours.out
-        .filter((o) => o.edge.kind === 'imports-file')
-        .slice(0, 50)
+    // Pre-slice the homogeneous filtered arrays so the payload can report the TRUE
+    // count + a truncated flag instead of silently capping each list at 50.
+    const importsFromAll = neighbours.out.filter((o) => o.edge.kind === 'imports-file');
+    const importedByAll = neighbours.in.filter((i) => i.edge.kind === 'imports-file');
+    const importsFromList = importsFromAll
+        .slice(0, CONTEXT_LIST_CAP)
         .map((o) => ('target' in o ? targetSummary(o.target) : { id: 'unknown', resolved: false }));
-    const importedByList = neighbours.in
-        .filter((i) => i.edge.kind === 'imports-file')
-        .slice(0, 50)
+    const importedByList = importedByAll
+        .slice(0, CONTEXT_LIST_CAP)
         .map((i) => ('source' in i ? sourceSummary(i.source) : { id: 'unknown', resolved: false }));
-    const referencedByList = references.slice(0, 50).map(nodeSummary);
-    const calledByList = callers.slice(0, 50).map(nodeSummary);
+    const referencedByList = references.slice(0, CONTEXT_LIST_CAP).map(nodeSummary);
+    const calledByList = callers.slice(0, CONTEXT_LIST_CAP).map(nodeSummary);
     // Staleness over the anchor + every referenced file: drop dead paths from the
     // usage lists, flag changed ones.
     const ctxPathOf = (x) => x.path;
@@ -649,10 +732,18 @@ export async function runGraphContext(args) {
         declaredIn: anchor.kind === NodeKind.Symbol && anchorFile ? nodeSummary(anchorFile) : null,
         depth,
         importsFrom: ctxDropDel(importsFromList),
+        totalImportsFrom: importsFromAll.length,
+        importsFromTruncated: importsFromAll.length > CONTEXT_LIST_CAP,
         importedBy: ctxDropDel(importedByList),
+        totalImportedBy: importedByAll.length,
+        importedByTruncated: importedByAll.length > CONTEXT_LIST_CAP,
         symbols: symbols.slice(0, 50).map(nodeSummary),
         referencedBy: ctxDropDel(referencedByList),
+        totalReferencedBy: references.length,
+        referencedByTruncated: references.length > CONTEXT_LIST_CAP,
         calledBy: ctxDropDel(calledByList),
+        totalCalledBy: callers.length,
+        calledByTruncated: callers.length > CONTEXT_LIST_CAP,
         ...(subtypes.length > 0 ? { subtypes: subtypes.slice(0, 50).map(nodeSummary) } : {}),
         ...(supertypes.length > 0 ? { supertypes: supertypes.slice(0, 50).map(nodeSummary) } : {}),
         ...(fresh.field ?? {}),
@@ -772,8 +863,8 @@ export async function runGraphImpact(args) {
         process.stderr.write('Usage: shrk graph impact <fileOrSymbol> [--max-depth N] [--limit N] [--full]\n');
         return 2;
     }
-    const maxDepth = Math.max(1, Math.min(10, Number(flagString(args, 'max-depth') ?? '5')));
-    const limit = Math.max(1, Number(flagString(args, 'limit') ?? '200'));
+    const maxDepth = Math.min(10, flagPositiveInt(args, 'max-depth', 5));
+    const limit = flagPositiveInt(args, 'limit', 200);
     maybeRefresh(args, cwd);
     // --full → delegate to the impact-engine for a richer v3 payload.
     if (wantFull) {
@@ -899,8 +990,22 @@ export async function runGraphImpact(args) {
 export async function runGraphHubs(args) {
     const cwd = resolveCwd(args);
     const wantJson = flagBool(args, 'json');
-    const limit = Math.max(1, Math.min(100, Number(flagString(args, 'limit') ?? '15')));
-    const pathScope = flagString(args, 'path');
+    const limit = Math.min(100, flagPositiveInt(args, 'limit', 15));
+    // A positional scope (`shrk graph hubs packages/cli`) is honoured the same as
+    // --path; passing BOTH is ambiguous, so error rather than silently ignoring
+    // the positional (which previously yielded a byte-identical global report).
+    const pathFlag = flagString(args, 'path');
+    const positionalPath = args.positional[1];
+    if (pathFlag && positionalPath) {
+        if (wantJson) {
+            process.stdout.write(asJson({ ok: false, error: 'ambiguous-path', positional: positionalPath, flag: pathFlag }) + '\n');
+        }
+        else {
+            process.stderr.write(`Pass the scope path either as a positional or with --path, not both (got "${positionalPath}" and --path ${pathFlag}).\n`);
+        }
+        return 2;
+    }
+    const pathScope = pathFlag ?? positionalPath;
     maybeRefresh(args, cwd);
     const api = loadOrFail(cwd, wantJson);
     if (!api)
@@ -1081,7 +1186,7 @@ export async function runGraphPath(args) {
         process.stderr.write('Usage: shrk graph path <from> <to> [--max-depth N] [--no-refresh] [--json]\n');
         return 2;
     }
-    const maxDepth = Math.max(1, Math.min(32, Number(flagString(args, 'max-depth') ?? '16')));
+    const maxDepth = Math.min(32, flagPositiveInt(args, 'max-depth', 16));
     maybeRefresh(args, cwd);
     const api = loadOrFail(cwd, wantJson);
     if (!api)
@@ -1183,6 +1288,45 @@ export async function runGraphPath(args) {
     return 0;
 }
 // ─── helpers ──────────────────────────────────────────────────────────
+/**
+ * Convert the typed corrupt-store error (one bad JSONL line) into a
+ * deterministic "rebuild the index" message + non-zero exit, instead of letting
+ * an unhandled `Fatal: JSON Parse error` escape the CLI. Returns the exit code
+ * (1) when `err` is a corrupt-store error, or null to signal "not mine — rethrow".
+ */
+function emitCorruptStore(err, wantJson) {
+    if (!isGraphStoreCorruptError(err))
+        return null;
+    if (wantJson) {
+        process.stdout.write(asJson({
+            ok: false,
+            state: 'corrupt',
+            nextCommand: 'shrk graph index',
+            message: CORRUPT_HINT,
+            ...(err.details ?? {}),
+        }) + '\n');
+    }
+    else {
+        process.stderr.write(CORRUPT_HINT + '\n');
+    }
+    return 1;
+}
+/**
+ * Run a store-loading thunk, mapping a corrupt store to a clean rebuild hint.
+ * Returns the loaded value, or undefined when the store was corrupt (the
+ * message + exit have already been emitted; the caller should `return 1`). Any
+ * other error is rethrown unchanged.
+ */
+function loadGuarded(load, wantJson) {
+    try {
+        return load();
+    }
+    catch (err) {
+        if (emitCorruptStore(err, wantJson) !== null)
+            return undefined;
+        throw err;
+    }
+}
 function loadOrFail(cwd, wantJson) {
     const store = new GraphStore(cwd);
     if (!store.exists()) {
@@ -1199,7 +1343,7 @@ function loadOrFail(cwd, wantJson) {
         }
         return undefined;
     }
-    return GraphQueryApi.fromStore(cwd);
+    return loadGuarded(() => GraphQueryApi.fromStore(cwd), wantJson);
 }
 function resolveAnchor(api, target) {
     // Exact node id wins.
@@ -1221,43 +1365,14 @@ function resolveAnchor(api, target) {
         return syms[0];
     return undefined;
 }
+/**
+ * Delegate to the shared {@link GraphQueryApi.searchNodes} so the CLI and the
+ * MCP `get_graph_search` tool can never disagree on results OR the honest
+ * pre-slice `total` (the two surfaces used to maintain divergent copies of this
+ * fuzzy-match logic). Returns the display page + the true match count.
+ */
 function collectSearchMatches(api, query, kind, limit) {
-    const out = [];
-    if (!kind || kind === 'file') {
-        const f = api.findFile(query);
-        if (f)
-            out.push(f);
-        // Fuzzy fallback: substring match on path/basename so `shrk graph
-        // search Foo --kind file` finds `libs/x/y/Foo.ts` without forcing the
-        // caller to type the full path. Skips the node if exact match already
-        // included it.
-        if (out.length < limit) {
-            const q = query.toLowerCase();
-            const seen = new Set(out.map((n) => n.id));
-            for (const node of api.allFiles()) {
-                if (seen.has(node.id))
-                    continue;
-                const p = node.path?.toLowerCase() ?? '';
-                const base = p.includes('/') ? p.slice(p.lastIndexOf('/') + 1) : p;
-                if (base.includes(q) || p.includes(q)) {
-                    out.push(node);
-                    seen.add(node.id);
-                    if (out.length >= limit)
-                        break;
-                }
-            }
-        }
-    }
-    if (!kind || kind === 'symbol') {
-        for (const s of api.findSymbol(query, { exact: false, limit }))
-            out.push(s);
-    }
-    if (!kind || kind === 'package') {
-        const p = api.neighbours(`package:${query}`);
-        if (p)
-            out.push(p.node);
-    }
-    return out.slice(0, limit);
+    return api.searchNodes(query, { ...(kind ? { kind } : {}), limit });
 }
 function reverseClosure(api, anchor, maxDepth, limit) {
     const seen = new Set([anchor.id]);

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,EAIL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AA4BhC,eAAO,MAAM,YAAY,EAAE,eA+M1B,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;AA4BhC,eAAO,MAAM,YAAY,EAAE,eAuN1B,CAAC"}

package/dist/commands/graph.command.js

@@ -52,6 +52,12 @@ export const graphCommand = {
         const graph = buildKnowledgeGraph(inspection);
         const sub = args.positional[0];
         const typeFlag = flagString(args, 'type');
+        // A typo'd `--type` would otherwise silently match zero nodes and return an
+        // empty summary / "no node" at exit 0/1. Reject loudly with the valid list.
+        if (typeFlag && !KNOWN_KINDS.includes(typeFlag)) {
+            process.stderr.write(`Unknown --type ${typeFlag}. Valid: ${KNOWN_KINDS.join(', ')}\n`);
+            return 2;
+        }
         const formatFlag = (flagString(args, 'format') ?? 'text');
         const outputFlag = flagString(args, 'output');
         // `shrk graph imports` — import-graph analysis.

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

@@ -1 +1 @@
-{"version":3,"file":"impact.command.d.ts","sourceRoot":"","sources":["../../src/commands/impact.command.ts"],"names":[],"mappings":"AAsBA,OAAO,EAML,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AA0VhC,eAAO,MAAM,aAAa,EAAE,eA8V3B,CAAC"}
+{"version":3,"file":"impact.command.d.ts","sourceRoot":"","sources":["../../src/commands/impact.command.ts"],"names":[],"mappings":"AAsBA,OAAO,EAML,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAibhC,eAAO,MAAM,aAAa,EAAE,eAsW3B,CAAC"}