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

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

@@ -1 +1 @@
-{"version":3,"file":"check.command.d.ts","sourceRoot":"","sources":["../../src/commands/check.command.ts"],"names":[],"mappings":"AAoBA,OAAO,EAML,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAurBhC,eAAO,MAAM,YAAY,EAAE,eAyE1B,CAAC"}
+{"version":3,"file":"check.command.d.ts","sourceRoot":"","sources":["../../src/commands/check.command.ts"],"names":[],"mappings":"AAoBA,OAAO,EAML,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAkzBhC,eAAO,MAAM,YAAY,EAAE,eA0E1B,CAAC"}

package/dist/commands/check.command.js

@@ -4,9 +4,11 @@ import * as nodePath from 'node:path';
 import { flagBool, flagNumber, flagString, flagVars, resolveCwd, } from "../command-registry.js";
 import { asJson, header, kv } from "../output/format-output.js";
 import { maybeRunInWatchMode } from "../output/watch-loop.js";
+import { computeDeletedOrphans } from "../diff/deleted-orphans.js";
+import { renderWiringExplain } from "./wiring.command.js";
 import { validateTemplateVariables } from '@shrkcrft/templates';
 import { FileChangeType, planGeneration } from '@shrkcrft/generator';
-import { evaluateBoundaries, loadTsconfigPaths, runWiring, scanImports, summarizeImports, } from '@shrkcrft/boundaries';
+import { evaluateBoundaries, explainWiring, loadTsconfigPaths, runWiring, scanImports, summarizeImports, } from '@shrkcrft/boundaries';
 function knowledgeGroup(inspection) {
     const dup = inspection.validationIssues.filter((i) => i.code === 'duplicate-id');
     const missing = inspection.validationIssues.filter((i) => i.code !== 'duplicate-id');
@@ -542,6 +544,27 @@ async function checkWiring(args) {
     }
     const rules = loaded.value.config.wiringRules ?? [];
     const planeDiagnostics = loaded.value.planeDiagnostics;
+    // `--explain <ruleId>`: dry-run ONE rule and print the declared + registered
+    // sets it extracts (file:line), the set-difference, and the verdict — the
+    // author-loop view of what the gate sees, without re-running the whole gate.
+    if (args.flags.has('explain')) {
+        const explainId = flagString(args, 'explain');
+        if (!explainId) {
+            process.stderr.write('Usage: shrk check wiring --explain <ruleId> [--json]\n');
+            return 2;
+        }
+        const rule = rules.find((r) => r.id === explainId);
+        if (!rule) {
+            const ids = rules.map((r) => r.id);
+            if (wantJson) {
+                process.stdout.write(asJson({ ok: false, error: 'not-found', ruleId: explainId, available: ids }) + '\n');
+                return 2;
+            }
+            process.stderr.write(`No wiring rule "${explainId}". Configured rules: ${ids.length > 0 ? ids.join(', ') : '(none)'}\n`);
+            return 2;
+        }
+        return renderWiringExplain(explainWiring(cwd, rule), wantJson);
+    }
     if (rules.length === 0) {
         if (wantJson) {
             process.stdout.write(asJson({ schema: 'sharkcraft.wiring/v1', rules: [], violations: [], verdict: 'pass' }) + '\n');
@@ -619,12 +642,94 @@ async function checkWiring(args) {
     }
     return report.verdict === 'errors' ? 1 : 0;
 }
+/**
+ * `shrk check orphans [--since <ref>] [--staged]`: first-class, diff-robust
+ * reverse-closure over REMOVED files. Reads the deleted files from the diff
+ * (vs `--since`, or the staged index with `--staged`) and queries the
+ * code-graph snapshot for surviving files that still import them or reference a
+ * symbol they declared — alias-resolved, incl. barrel re-exports. Each survivor
+ * is an error with `file:line`; the type checker misses a deleted barrel
+ * re-export or string-keyed registration, so this is a write-safety guard an
+ * agent can't replicate natively. Generalizes `impact --deleted`; pairs with
+ * the composite `finish` gate.
+ */
+async function checkOrphans(args) {
+    const cwd = resolveCwd(args);
+    const wantJson = flagBool(args, 'json');
+    const since = flagString(args, 'since');
+    const staged = flagBool(args, 'staged');
+    const scan = await computeDeletedOrphans(cwd, {
+        ...(since ? { since } : {}),
+        ...(staged ? { staged: true } : {}),
+    });
+    if (!scan.ok) {
+        if (wantJson) {
+            process.stdout.write(asJson({
+                schema: 'sharkcraft.deleted-orphans/v1',
+                error: scan.error,
+                reason: scan.reason,
+                orphans: [],
+            }) + '\n');
+            return 2;
+        }
+        process.stdout.write(header('Orphan check'));
+        process.stdout.write(scan.reason === 'diff-unavailable'
+            ? `  ✗ Cannot resolve diff: ${scan.error ?? 'unknown'}\n`
+            : `  ✗ ${scan.error ?? 'orphan check unavailable'}\n`);
+        return 2;
+    }
+    const scopeLabel = staged ? 'staged' : `vs ${scan.ref}`;
+    // Nothing deleted → there is nothing to check. Report a LOUD skip, not a
+    // green "no orphans" — "checked nothing" must never read as "verified clean".
+    if (scan.deleted.length === 0) {
+        if (wantJson) {
+            process.stdout.write(asJson({
+                schema: 'sharkcraft.deleted-orphans/v1',
+                skipped: true,
+                ref: scan.ref,
+                resolvedDeleted: [],
+                unresolvedDeleted: [],
+                orphans: [],
+                diagnostics: [`no deleted files (${scopeLabel}) — nothing to check`],
+            }) + '\n');
+            return 0;
+        }
+        process.stdout.write(header('Orphan check'));
+        process.stdout.write(`  ! Nothing deleted (${scopeLabel}) — orphan check skipped.\n`);
+        return 0;
+    }
+    const report = scan.report;
+    if (wantJson) {
+        process.stdout.write(asJson(report) + '\n');
+        return report.orphans.length > 0 ? 1 : 0;
+    }
+    process.stdout.write(header('Orphan check'));
+    process.stdout.write(kv('deleted files', `${scan.deleted.length} (${scopeLabel})`) + '\n');
+    if (report.orphans.length === 0) {
+        process.stdout.write('\nNo orphaned importers — nothing still references the deleted code. ✓\n');
+        for (const d of report.diagnostics.slice(0, 5))
+            process.stdout.write(`  ! ${d}\n`);
+        return 0;
+    }
+    process.stdout.write(`\n${report.orphans.length} surviving importer(s) still reference deleted code:\n`);
+    for (const o of report.orphans.slice(0, 100)) {
+        const loc = o.path ? `${o.path}${o.line ? `:${o.line}` : ''}` : o.id;
+        const detail = o.via === 'reference' && o.symbol ? `references \`${o.symbol}\`` : 'imports';
+        process.stdout.write(`  ✗ ${loc} ${detail} from deleted ${o.deletedFile}\n`);
+    }
+    if (report.orphans.length > 100) {
+        process.stdout.write(`  … (${report.orphans.length - 100} more)\n`);
+    }
+    for (const d of report.diagnostics.slice(0, 5))
+        process.stdout.write(`  ! ${d}\n`);
+    return 1;
+}
 // Main shrk check + subcommands
 // ────────────────────────────────────────────────────────────────────────
 export const checkCommand = {
     name: 'check',
     description: 'Run SharkCraft-level validation across knowledge / rules / templates / pipelines / packs / action hints / doctor. `check boundaries [--watch [--paths a,b] [--debounce N] [--once]]` re-runs the boundary scan on file changes.',
-    usage: 'shrk [--cwd <dir>] check [packs|pipelines|knowledge|generation|boundaries|imports|wiring] [--strict] [--min-score <0-100>] [--changed-only] [--since <ref>] [--only <ids>] [--json] [--watch [--paths <list>] [--debounce N] [--once]]',
+    usage: 'shrk [--cwd <dir>] check [packs|pipelines|knowledge|generation|boundaries|imports|wiring|orphans] [--strict] [--min-score <0-100>] [--changed-only] [--since <ref>] [--staged] [--only <ids>] [--json] [--watch [--paths <list>] [--debounce N] [--once]]',
     async run(args) {
         const sub = args.positional[0];
         // `check generation <id> <name>` legitimately takes extra positionals;
@@ -647,6 +752,8 @@ export const checkCommand = {
             return checkImports(args);
         if (sub === 'wiring')
             return checkWiring(args);
+        if (sub === 'orphans')
+            return checkOrphans(args);
         if (sub === 'registry-lifecycle') {
             const cwd = resolveCwd(args);
             const { buildRegistryLifecycleReport, renderRegistryLifecycleReportText } = await import('@shrkcrft/inspector');

package/dist/commands/command-catalog.d.ts

@@ -245,6 +245,17 @@ export declare function commandLifecycle(e: ICommandCatalogEntry): CommandLifecy
  * membership.
  */
 export declare function defaultShowInHelp(e: ICommandCatalogEntry): boolean;
+/**
+ * The "explain / dry-run" command family: entries that show you what a gate,
+ * ranker, or graph *sees* before you act (`search tuning explain`, `wiring
+ * explain`/`wiring test`, `boundaries explain`, `surface explain`, …). Several
+ * carry an Advanced surface, so {@link defaultShowInHelp} hides them despite
+ * being high-value — which is exactly why an agent finds them only by guessing.
+ * `shrk --full-help` lists this family in a dedicated section so they stop
+ * being hidden. Returns callable entries only (retired/deprecated/alias and
+ * R46-pruned are excluded), sorted by command.
+ */
+export declare function listExplainFamily(): readonly ICommandCatalogEntry[];
 /**
  * Short "Use this when…" line derived from `surface`, `taskRole`,
  * `preferredCommand`, `replacedBy`, and `machineOnly`. Empty string when

package/dist/commands/command-catalog.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"command-catalog.d.ts","sourceRoot":"","sources":["../../src/commands/command-catalog.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"command-catalog.d.ts","sourceRoot":"","sources":["../../src/commands/command-catalog.ts"],"names":[],"mappings":"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"}

package/dist/commands/command-catalog.js

@@ -390,6 +390,14 @@ export const COMMAND_CATALOG = Object.freeze([
         surface: CommandSurface.Common,
         taskRole: CommandTaskRole.Validate,
     }),
+    entry({
+        command: 'check orphans',
+        description: 'Write-safety guard: after deleting file(s)/export(s), finds surviving files that still import them or reference a symbol they declared — alias-resolved, incl. barrel re-exports the type checker misses. Reverse-closure over the diff vs --since (or --staged) against the code-graph snapshot; each survivor reported with file:line. [--since <ref>] [--staged] [--json]',
+        category: 'core',
+        safetyLevel: SafetyLevel.ReadOnly,
+        surface: CommandSurface.Common,
+        taskRole: CommandTaskRole.Validate,
+    }),
     entry({
         command: 'policy-lint',
         description: 'Lint template/markup, stylesheet, and AOT-invisible TS surfaces against config-defined policyRules[] — sees `.html` files AND inline `template:` strings that tsc/AOT cannot. Deterministic; no AI. [--surface template|style|ts] [--changed-only] [--only <ids>] [--json]',
@@ -398,6 +406,46 @@ export const COMMAND_CATALOG = Object.freeze([
         surface: CommandSurface.Common,
         taskRole: CommandTaskRole.Validate,
     }),
+    entry({
+        command: 'wiring explain',
+        description: 'Dry-run ONE configured wiringRule and print the declared set + registered set it extracts (token + file:line), the alias-resolved set-difference, and the verdict — the author-loop view of what `check wiring` sees, without re-running the gate. [--json]',
+        category: 'core',
+        safetyLevel: SafetyLevel.ReadOnly,
+        surface: CommandSurface.Advanced,
+        taskRole: CommandTaskRole.Explain,
+    }),
+    entry({
+        command: 'wiring test',
+        description: 'Dry-run an EPHEMERAL candidate wiring rule (a .json file or inline JSON) against the live tree — see the declared/registered sets + diff it would produce before committing it to sharkcraft.config.ts. Never writes config. [--json]',
+        category: 'core',
+        safetyLevel: SafetyLevel.ReadOnly,
+        surface: CommandSurface.Advanced,
+        taskRole: CommandTaskRole.Explain,
+    }),
+    entry({
+        command: 'wiring chain',
+        description: 'Registration/DI graph query: the declared → provided → consumed chain of a token across files/layers, alias-resolved, with file:line at each hop + a verdict (wired / unprovided / orphan). Models runtime wiring imports can\'t see. Idioms from sharkcraft.config.ts registrationGraph[]. [--json]',
+        category: 'analysis',
+        safetyLevel: SafetyLevel.ReadOnly,
+        surface: CommandSurface.Advanced,
+        taskRole: CommandTaskRole.Inspect,
+    }),
+    entry({
+        command: 'wiring unprovided',
+        description: 'Registration/DI graph query: tokens DECLARED or INJECTED but never PROVIDED — the silent-at-runtime class (typecheck/AOT-green, resolves to undefined at runtime). The write-safety check imports/grep structurally can\'t do. [--json]',
+        category: 'analysis',
+        safetyLevel: SafetyLevel.ReadOnly,
+        surface: CommandSurface.Advanced,
+        taskRole: CommandTaskRole.Validate,
+    }),
+    entry({
+        command: 'wiring orphans',
+        description: 'Registration/DI graph query: tokens PROVIDED/registered that nothing CONSUMES — a build-clean dead registration (or a sign the consumer was renamed/removed). [--json]',
+        category: 'analysis',
+        safetyLevel: SafetyLevel.ReadOnly,
+        surface: CommandSurface.Advanced,
+        taskRole: CommandTaskRole.Inspect,
+    }),
     entry({
         command: 'reuse',
         description: 'Intent → the canonical primitive to reuse: matches your intent against config reusePrimitives[] then resolves the symbol through the code graph (transitive star-barrels) to its import path, sibling exports, and real consumer files to copy. Read-only; no AI.',
@@ -415,6 +463,14 @@ export const COMMAND_CATALOG = Object.freeze([
         surface: CommandSurface.Common,
         taskRole: CommandTaskRole.Validate,
     }),
+    entry({
+        command: 'finish',
+        description: 'Composite "is this changeset safe to finish?" gate: EXECUTES boundaries + import-hygiene + wiring + policy + deleted-orphans changed-only inline, plus an impact summary, and returns ONE pass/fail. The trustworthy "done?" call after editing — superset of diff-check; honors 0-rules→skipped. Read-only. [files… | --staged | --since <ref>] [--json]',
+        category: 'core',
+        safetyLevel: SafetyLevel.ReadOnly,
+        surface: CommandSurface.Common,
+        taskRole: CommandTaskRole.Validate,
+    }),
     entry({
         command: 'review',
         description: 'PR-review packet — changed files, affected rules, missing tests heuristic.',
@@ -1658,6 +1714,14 @@ export const COMMAND_CATALOG = Object.freeze([
         safetyLevel: SafetyLevel.ReadOnly,
         mcpAvailable: true,
     }),
+    entry({
+        command: 'trace literal',
+        description: 'Trace an EXACT string literal across the codebase, classified by direction: declare → register → consume sites of a cross-fence contract (kind slug, permission id, route key) the type system can\'t link and grep can\'t classify. Resolves `const X = "lit"` aliases. Generalizes `registry … where` to any literal — no pre-declared registry. [--glob <g>] [--no-aliases] [--limit N] [--json]',
+        category: 'analysis',
+        safetyLevel: SafetyLevel.ReadOnly,
+        surface: CommandSurface.Advanced,
+        taskRole: CommandTaskRole.Inspect,
+    }),
     entry({
         command: 'feedback',
         description: 'Feedback ingestion (ingest|summarize|actions|convert-to-backlog). Read-only.',
@@ -3664,6 +3728,7 @@ const PRIMARY_VERBS_ALLOWLIST = new Set([
     'gen',
     'apply',
     'check',
+    'finish',
     'quality',
     'plan',
     'fix',
@@ -3734,6 +3799,32 @@ export function defaultShowInHelp(e) {
     const surface = commandSurface(e);
     return surface === CommandSurface.Primary || surface === CommandSurface.Common;
 }
+/**
+ * The "explain / dry-run" command family: entries that show you what a gate,
+ * ranker, or graph *sees* before you act (`search tuning explain`, `wiring
+ * explain`/`wiring test`, `boundaries explain`, `surface explain`, …). Several
+ * carry an Advanced surface, so {@link defaultShowInHelp} hides them despite
+ * being high-value — which is exactly why an agent finds them only by guessing.
+ * `shrk --full-help` lists this family in a dedicated section so they stop
+ * being hidden. Returns callable entries only (retired/deprecated/alias and
+ * R46-pruned are excluded), sorted by command.
+ */
+export function listExplainFamily() {
+    return COMMAND_CATALOG.filter((e) => {
+        const lc = commandLifecycle(e);
+        if (lc === CommandLifecycle.Deprecated ||
+            lc === CommandLifecycle.Retired ||
+            lc === CommandLifecycle.Alias) {
+            return false;
+        }
+        if (R46_OVERLAY[e.command])
+            return false;
+        const role = commandTaskRole(e);
+        return role === CommandTaskRole.Explain || /(^|\s)explain$/.test(e.command);
+    })
+        .slice()
+        .sort((a, b) => a.command.localeCompare(b.command));
+}
 /**
  * Short "Use this when…" line derived from `surface`, `taskRole`,
  * `preferredCommand`, `replacedBy`, and `machineOnly`. Empty string when

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

@@ -0,0 +1,3 @@
+import { type ICommandHandler } from '../command-registry.js';
+export declare const finishCommand: ICommandHandler;
+//# sourceMappingURL=finish.command.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"finish.command.d.ts","sourceRoot":"","sources":["../../src/commands/finish.command.ts"],"names":[],"mappings":"AACA,OAAO,EAIL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AA8DhC,eAAO,MAAM,aAAa,EAAE,eAmB3B,CAAC"}

package/dist/commands/finish.command.js

@@ -0,0 +1,70 @@
+import { flagBool, flagString, resolveCwd, } from "../command-registry.js";
+import { asJson, bullet, header, kv } from "../output/format-output.js";
+import { runFinishGates } from "../finish/run-finish.js";
+function resolveScope(args, cwd) {
+    const staged = flagBool(args, 'staged');
+    const since = flagString(args, 'since');
+    const filesRaw = flagString(args, 'files');
+    const files = filesRaw
+        ? filesRaw.split(',').map((s) => s.trim()).filter((s) => s.length > 0)
+        : args.positional.filter((s) => s.length > 0);
+    if (files.length > 0)
+        return { mode: 'files', options: { projectRoot: cwd, files } };
+    if (staged)
+        return { mode: 'staged', options: { projectRoot: cwd, staged: true } };
+    if (since)
+        return { mode: 'since', options: { projectRoot: cwd, since } };
+    return { mode: 'worktree', options: { projectRoot: cwd, includeWorktree: true } };
+}
+const STATUS_GLYPH = {
+    pass: '✓',
+    fail: '✗',
+    skipped: '–',
+};
+function renderText(report) {
+    process.stdout.write(header('Finish — is this changeset safe to complete?'));
+    process.stdout.write(kv('scope', `${report.scope.mode} (${report.scope.fileCount} file${report.scope.fileCount === 1 ? '' : 's'})`) +
+        '\n');
+    for (const g of report.gates) {
+        process.stdout.write(`  ${STATUS_GLYPH[g.status]} ${g.name.padEnd(11)} ${g.status.padEnd(8)} ${g.detail}\n`);
+    }
+    if (report.impact.ran) {
+        process.stdout.write(kv('impact', `risk=${report.impact.risk}, ${report.impact.directDependents} direct / ${report.impact.transitiveDependents} transitive dependents`) +
+            '\n');
+    }
+    else if (report.impact.note) {
+        process.stdout.write(kv('impact', `(skipped — ${report.impact.note})`) + '\n');
+    }
+    process.stdout.write(kv('verdict', report.verdict) + '\n\n');
+    process.stdout.write(report.summary + '\n');
+    const failing = report.gates.filter((g) => g.status === 'fail');
+    for (const g of failing) {
+        process.stdout.write(`\n${g.name} — failing items:\n`);
+        for (const item of g.items.slice(0, 15)) {
+            const loc = item.file ? `${item.file}${item.line ? `:${item.line}` : ''}` : '';
+            process.stdout.write(bullet(`${loc ? loc + ' — ' : ''}${item.message}`) + '\n');
+        }
+        if (g.items.length > 15) {
+            process.stdout.write(`  … and ${g.items.length - 15} more (pass --json for the full list).\n`);
+        }
+    }
+    process.stdout.write(`\nNext: ${report.nextAction}\n`);
+}
+export const finishCommand = {
+    name: 'finish',
+    description: 'Composite "is this changeset safe to finish?" gate: EXECUTES every deterministic changed-only check inline — boundaries + import-hygiene + wiring + policy + deleted-orphans — plus an impact summary, and returns ONE pass/fail. The single trustworthy "done?" call after editing (superset of `diff-check`; honors 0-rules→skipped). Read-only.',
+    usage: 'shrk [--cwd <dir>] finish [files... | --files a.ts,b.ts | --staged | --since <ref>] [--json]',
+    booleanFlags: new Set(['json', 'staged']),
+    async run(args) {
+        const cwd = resolveCwd(args);
+        const wantJson = flagBool(args, 'json');
+        const { mode, options } = resolveScope(args, cwd);
+        const report = await runFinishGates({ cwd, mode, scope: options });
+        if (wantJson) {
+            process.stdout.write(asJson(report) + '\n');
+            return report.verdict === 'fail' ? 1 : 0;
+        }
+        renderText(report);
+        return report.verdict === 'fail' ? 1 : 0;
+    },
+};

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

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

@@ -12,7 +12,7 @@ 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, flagPositiveInt, flagString, resolveCwd } from "../command-registry.js";
+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";
 /**
@@ -67,6 +67,24 @@ const CORRUPT_HINT = 'code graph store is corrupt — run `shrk graph index` to
  * runGraphCallers). Kept in sync with the MCP `get_graph_context` tool.
  */
 const CONTEXT_LIST_CAP = 50;
+/**
+ * Resolve a `--limit N` per-list cap for the graph read commands. Absent → the
+ * command's `fallback` (the historical default — 50 for `context`, 200 for
+ * `callers`/`impact`); `--limit 0` (or any non-positive) → unbounded so a
+ * consumer can pull the full set off a high-fan-in barrel/hub in one call.
+ * Returns `Infinity` for the unbounded case: `arr.slice(0, Infinity)` yields
+ * every row and `len > Infinity` is `false`, so the `<list>Truncated` flag stays
+ * honest (never "truncated" when nothing was dropped). Malformed `--limit abc`
+ * (NaN) degrades to `fallback`, matching `flagPositiveInt`.
+ */
+function resolveListLimit(args, fallback) {
+    const v = flagNumber(args, 'limit');
+    if (v === undefined)
+        return fallback;
+    if (v <= 0)
+        return Number.POSITIVE_INFINITY;
+    return Math.floor(v);
+}
 /**
  * Refresh-by-default: incrementally reindex changed/deleted files BEFORE
  * querying so an agent's just-saved edits are reflected, then print a one-line
@@ -659,10 +677,11 @@ export async function runGraphContext(args) {
     const wantJson = flagBool(args, 'json');
     const target = args.positional[1];
     if (!target) {
-        process.stderr.write('Usage: shrk graph context <fileOrSymbol> [--depth N] [--no-bridge] [--no-framework]\n');
+        process.stderr.write('Usage: shrk graph context <fileOrSymbol> [--depth N] [--limit N|0] [--no-bridge] [--no-framework]\n');
         return 2;
     }
     const depth = Math.min(3, flagPositiveInt(args, 'depth', 1));
+    const cap = resolveListLimit(args, CONTEXT_LIST_CAP);
     const includeBridge = !flagBool(args, 'no-bridge');
     const includeFramework = !flagBool(args, 'no-framework');
     maybeRefresh(args, cwd);
@@ -708,13 +727,13 @@ export async function runGraphContext(args) {
     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)
+        .slice(0, cap)
         .map((o) => ('target' in o ? targetSummary(o.target) : { id: 'unknown', resolved: false }));
     const importedByList = importedByAll
-        .slice(0, CONTEXT_LIST_CAP)
+        .slice(0, cap)
         .map((i) => ('source' in i ? sourceSummary(i.source) : { id: 'unknown', resolved: false }));
-    const referencedByList = references.slice(0, CONTEXT_LIST_CAP).map(nodeSummary);
-    const calledByList = callers.slice(0, CONTEXT_LIST_CAP).map(nodeSummary);
+    const referencedByList = references.slice(0, cap).map(nodeSummary);
+    const calledByList = callers.slice(0, 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;
@@ -733,19 +752,19 @@ export async function runGraphContext(args) {
         depth,
         importsFrom: ctxDropDel(importsFromList),
         totalImportsFrom: importsFromAll.length,
-        importsFromTruncated: importsFromAll.length > CONTEXT_LIST_CAP,
+        importsFromTruncated: importsFromAll.length > cap,
         importedBy: ctxDropDel(importedByList),
         totalImportedBy: importedByAll.length,
-        importedByTruncated: importedByAll.length > CONTEXT_LIST_CAP,
-        symbols: symbols.slice(0, 50).map(nodeSummary),
+        importedByTruncated: importedByAll.length > cap,
+        symbols: symbols.slice(0, cap).map(nodeSummary),
         referencedBy: ctxDropDel(referencedByList),
         totalReferencedBy: references.length,
-        referencedByTruncated: references.length > CONTEXT_LIST_CAP,
+        referencedByTruncated: references.length > 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) } : {}),
+        calledByTruncated: callers.length > cap,
+        ...(subtypes.length > 0 ? { subtypes: subtypes.slice(0, cap).map(nodeSummary) } : {}),
+        ...(supertypes.length > 0 ? { supertypes: supertypes.slice(0, cap).map(nodeSummary) } : {}),
         ...(fresh.field ?? {}),
         bridge: bridgeFor
             ? {
@@ -860,11 +879,11 @@ export async function runGraphImpact(args) {
     const wantFull = flagBool(args, 'full');
     const target = args.positional[1];
     if (!target) {
-        process.stderr.write('Usage: shrk graph impact <fileOrSymbol> [--max-depth N] [--limit N] [--full]\n');
+        process.stderr.write('Usage: shrk graph impact <fileOrSymbol> [--max-depth N] [--limit N|0] [--full]\n');
         return 2;
     }
     const maxDepth = Math.min(10, flagPositiveInt(args, 'max-depth', 5));
-    const limit = flagPositiveInt(args, 'limit', 200);
+    const limit = resolveListLimit(args, 200);
     maybeRefresh(args, cwd);
     // --full → delegate to the impact-engine for a richer v3 payload.
     if (wantFull) {
@@ -949,7 +968,8 @@ export async function runGraphImpact(args) {
         schema: 'sharkcraft.graph-impact/v1',
         anchor: nodeSummary(anchor),
         maxDepth,
-        limit,
+        // 0 signals "unbounded" (`--limit 0`); JSON can't carry Infinity.
+        limit: Number.isFinite(limit) ? limit : 0,
         truncated: closure.truncated,
         directDependents: liveDirect,
         transitiveDependents: liveTransitive,
@@ -1052,16 +1072,15 @@ export async function runGraphCallers(args) {
     const wantJson = flagBool(args, 'json');
     const target = args.positional[1];
     if (!target) {
-        process.stderr.write('Usage: shrk graph callers <symbol> [--mode call|reference] [--limit N] [--no-refresh]\n');
+        process.stderr.write('Usage: shrk graph callers <symbol> [--mode call|reference] [--limit N|0] [--no-refresh]\n');
         return 2;
     }
     const mode = (flagString(args, 'mode') ?? 'call');
-    // --limit N: cap the returned call sites (default 200). `total` still reports
-    // the true uncapped count, so a truncated result stays honest. Guard against
-    // non-numeric input — `Number('foo')` is NaN and `slice(0, NaN)` would zero
-    // the callers list while `total` kept showing the real count.
-    const parsedLimit = Number.parseInt(flagString(args, 'limit') ?? '200', 10);
-    const limit = Number.isFinite(parsedLimit) && parsedLimit > 0 ? parsedLimit : 200;
+    // --limit N: cap the returned call sites (default 200; `--limit 0` = all).
+    // `total` still reports the true uncapped count, so a truncated result stays
+    // honest. resolveListLimit guards non-numeric input (NaN → fallback) so a
+    // fat-fingered `--limit foo` can't zero the list via `slice(0, NaN)`.
+    const limit = resolveListLimit(args, 200);
     maybeRefresh(args, cwd);
     const api = loadOrFail(cwd, wantJson);
     if (!api)

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;AAqB9D;;;;;;;;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;EA2HpF"}
+{"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;AA4B9D;;;;;;;;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;EAwIpF"}

package/dist/commands/help.command.js

@@ -1,5 +1,11 @@
 import { header } from "../output/format-output.js";
-import { COMMAND_CATALOG, defaultShowInHelp } from "./command-catalog.js";
+import { COMMAND_CATALOG, defaultShowInHelp, listExplainFamily } from "./command-catalog.js";
+/** First sentence of a catalog description, for the compact explain-family list. */
+function firstSentence(description) {
+    const dot = description.indexOf('. ');
+    const head = dot > 0 ? description.slice(0, dot + 1) : description;
+    return head.length > 100 ? head.slice(0, 97).trimEnd() + '…' : head;
+}
 const EXTRA_HELP_LINES = Object.freeze({
     graph: [
         '',
@@ -60,7 +66,7 @@ export function renderStartScreen() {
     lines.push('Discover the rest (everything stays callable — this screen shows ~17 of ~70 verbs):');
     lines.push('  $ shrk surface list              — full catalog by tier');
     lines.push('  $ shrk help <command>            — usage for a specific command');
-    lines.push('  $ shrk --full-help               — long, exhaustive help');
+    lines.push('  $ shrk --full-help               — long, exhaustive help (incl. the explain/dry-run family)');
     lines.push('  $ shrk --about                   — what shrk is and is not');
     lines.push('');
     lines.push('Free-form input is fine — `shrk "<task>"` routes to `shrk recommend`.');
@@ -188,6 +194,18 @@ export function makeHelpCommand(registry) {
                     process.stdout.write(`  ${group} ${s.name.padEnd(10)} — ${s.description}\n`);
                 }
             }
+            // Explain / dry-run family — several carry an Advanced surface and are
+            // filtered out of the listings above, so surface them explicitly. These
+            // show you what a gate, ranker, or graph SEES before you act; an agent
+            // would otherwise find them only by guessing (the #4.4 friction).
+            const explainFamily = listExplainFamily();
+            if (explainFamily.length > 0) {
+                process.stdout.write(header('Inspect / explain (dry-run what a gate, ranker, or graph sees)'));
+                for (const e of explainFamily) {
+                    process.stdout.write(`  ${e.command.padEnd(24)} — ${firstSentence(e.description)}\n`);
+                }
+                process.stdout.write('  (also: shrk check wiring --explain <ruleId>)\n');
+            }
             process.stdout.write('\nRun `shrk help <command>` for detailed usage.\n');
             return 0;
         },

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;AAibhC,eAAO,MAAM,aAAa,EAAE,eAsW3B,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;AA2ahC,eAAO,MAAM,aAAa,EAAE,eAsW3B,CAAC"}