@shrkcrft/cli 0.1.0-alpha.11 → 0.1.0-alpha.13

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

@@ -350,13 +350,15 @@ export async function runGraphStatus(args) {
     }
     const verify = store.verifyDigest();
     const snap = store.loadSnapshot();
+    const manifestNodeCount = sumValues(snap.manifest.nodesByKind);
+    const manifestEdgeCount = sumValues(snap.manifest.edgesByKind);
     const payload = {
         ok: verify.ok,
         state: verify.ok ? 'fresh' : 'corrupt',
         schema: snap.manifest.schema,
         fileCount: snap.manifest.filesIndexed,
-        nodeCount: snap.nodes.size,
-        edgeCount: snap.edges.size,
+        nodeCount: manifestNodeCount,
+        edgeCount: manifestEdgeCount,
         lastIndexedAt: snap.manifest.lastIndexedAt,
         lastIndexDurationMs: snap.manifest.lastIndexDurationMs,
         workspacePackages: snap.manifest.workspacePackages,
@@ -394,8 +396,10 @@ export async function runGraphSearch(args) {
     const cwd = resolveCwd(args);
     const wantJson = flagBool(args, 'json');
     const query = args.positional[1];
-    if (!query) {
-        process.stderr.write('Usage: shrk graph search <query> [--kind file|symbol|package] [--limit N]\n');
+    const hasUnresolved = flagBool(args, 'has-unresolved-imports');
+    if (!query && !hasUnresolved) {
+        process.stderr.write('Usage: shrk graph search <query> [--kind file|symbol|package] [--limit N]\n' +
+            '       shrk graph search --kind file --has-unresolved-imports [--limit N]\n');
         return 2;
     }
     const kindFlag = flagString(args, 'kind');
@@ -403,7 +407,16 @@ export async function runGraphSearch(args) {
     const api = loadOrFail(cwd, wantJson);
     if (!api)
         return 1;
-    const matches = collectSearchMatches(api, query, kindFlag, limit);
+    let matches;
+    if (hasUnresolved) {
+        const all = api.filesWithUnresolvedImports();
+        matches = (query
+            ? all.filter((n) => (n.path ?? '').toLowerCase().includes(query.toLowerCase()))
+            : [...all]).slice(0, limit);
+    }
+    else {
+        matches = collectSearchMatches(api, query, kindFlag, limit);
+    }
     if (wantJson) {
         process.stdout.write(asJson({
             schema: 'sharkcraft.graph-search/v1',
@@ -414,11 +427,12 @@ export async function runGraphSearch(args) {
         }) + '\n');
         return 0;
     }
+    const headerLabel = query ?? (hasUnresolved ? 'files with unresolved imports' : '');
     if (matches.length === 0) {
-        process.stdout.write(`No matches for "${query}".\n`);
+        process.stdout.write(`No matches for "${headerLabel}".\n`);
         return 0;
     }
-    process.stdout.write(header(`Graph search: ${query}`));
+    process.stdout.write(header(`Graph search: ${headerLabel}`));
     for (const m of matches) {
         process.stdout.write(`  ${m.kind.padEnd(8)} ${m.label}${m.path ? '  ' + m.path : ''}${m.line ? ':' + m.line : ''}\n`);
     }
@@ -449,22 +463,29 @@ export async function runGraphContext(args) {
         process.stderr.write(`No graph node matched "${target}".\n`);
         return 1;
     }
-    const neighbours = api.neighbours(anchor.id);
+    const anchorFile = anchor.kind === NodeKind.File
+        ? anchor
+        : declaringFileOf(api, anchor.id) ?? (anchor.path ? api.findFile(anchor.path) : undefined);
+    const subjectNodeId = anchorFile?.id ?? anchor.id;
+    const neighbours = api.neighbours(subjectNodeId);
     const symbols = anchor.kind === NodeKind.File ? api.symbolsIn(anchor.id) : [];
+    const references = anchor.kind === NodeKind.Symbol ? dedupeNodes(api.referencesOf(anchor.id)) : [];
+    const callers = anchor.kind === NodeKind.Symbol ? dedupeNodes(api.callersOf(anchor.id)) : [];
     // Optional bridge enrichment: rules / paths / templates applying to
-    // the anchor file (only meaningful when anchor.kind === File).
+    // the anchor file (or a symbol's containing file).
     const bridgeStore = new BridgeStore(cwd);
-    const bridgeFor = (includeBridge && bridgeStore.exists() && anchor.kind === NodeKind.File && anchor.path)
-        ? RuleGraphQueryApi.fromStores(cwd).forFile(anchor.path)
+    const bridgeFor = (includeBridge && bridgeStore.exists() && anchorFile?.path)
+        ? RuleGraphQueryApi.fromStores(cwd).forFile(anchorFile.path)
         : undefined;
     // Optional framework enrichment.
     const frameworkStore = new FrameworkStore(cwd);
-    const frameworkEntities = (includeFramework && frameworkStore.exists() && anchor.kind === NodeKind.File && anchor.path)
-        ? FrameworkQueryApi.fromStore(cwd).forFile(anchor.path)
+    const frameworkEntities = (includeFramework && frameworkStore.exists() && anchorFile?.path)
+        ? FrameworkQueryApi.fromStore(cwd).forFile(anchorFile.path)
         : [];
     const payload = {
         schema: 'sharkcraft.graph-context/v1',
         anchor: nodeSummary(anchor),
+        declaredIn: anchor.kind === NodeKind.Symbol && anchorFile ? nodeSummary(anchorFile) : null,
         depth,
         importsFrom: neighbours.out
             .filter((o) => o.edge.kind === 'imports-file')
@@ -475,6 +496,8 @@ export async function runGraphContext(args) {
             .slice(0, 50)
             .map((i) => 'source' in i ? sourceSummary(i.source) : { id: 'unknown', resolved: false }),
         symbols: symbols.slice(0, 50).map(nodeSummary),
+        referencedBy: references.slice(0, 50).map(nodeSummary),
+        calledBy: callers.slice(0, 50).map(nodeSummary),
         bridge: bridgeFor
             ? {
                 rules: bridgeFor.rules.map((h) => ({
@@ -503,12 +526,29 @@ export async function runGraphContext(args) {
     }
     process.stdout.write(header(`Graph context: ${anchor.kind}:${anchor.label}`));
     process.stdout.write(kv('path', anchor.path ?? '(none)') + '\n');
+    if (anchor.line)
+        process.stdout.write(kv('line', String(anchor.line)) + '\n');
+    if (payload.declaredIn) {
+        process.stdout.write(kv('declared in', payload.declaredIn.path ?? payload.declaredIn.id) + '\n');
+    }
     if (payload.symbols.length > 0) {
         process.stdout.write(`\nDeclares ${payload.symbols.length} symbols:\n`);
         for (const s of payload.symbols.slice(0, 20)) {
             process.stdout.write(`  ${s.label}${s.line ? ':' + s.line : ''}\n`);
         }
     }
+    if (payload.referencedBy.length > 0) {
+        process.stdout.write(`\nReferenced by (${payload.referencedBy.length}):\n`);
+        for (const r of payload.referencedBy.slice(0, 20)) {
+            process.stdout.write(`  ← ${r.path ?? r.id}\n`);
+        }
+    }
+    if (payload.calledBy.length > 0) {
+        process.stdout.write(`\nCalled by (${payload.calledBy.length}):\n`);
+        for (const c of payload.calledBy.slice(0, 20)) {
+            process.stdout.write(`  ← ${c.path ?? c.id}\n`);
+        }
+    }
     if (payload.importsFrom.length > 0) {
         process.stdout.write(`\nImports from (${payload.importsFrom.length}):\n`);
         for (const o of payload.importsFrom.slice(0, 20)) {
@@ -610,7 +650,7 @@ export async function runGraphImpact(args) {
         process.stderr.write(`No graph node matched "${target}".\n`);
         return 1;
     }
-    const closure = reverseClosure(api, anchor.id, maxDepth, limit);
+    const closure = reverseClosure(api, anchor, maxDepth, limit);
     const direct = closure.layer[1] ?? [];
     const transitive = closure.all.filter((id) => id !== anchor.id && !direct.includes(id));
     const payload = {
@@ -740,6 +780,26 @@ function collectSearchMatches(api, query, kind, limit) {
         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 }))
@@ -752,21 +812,29 @@ function collectSearchMatches(api, query, kind, limit) {
     }
     return out.slice(0, limit);
 }
-function reverseClosure(api, startId, maxDepth, limit) {
-    const seen = new Set([startId]);
+function reverseClosure(api, anchor, maxDepth, limit) {
+    const seen = new Set([anchor.id]);
     const layer = {};
-    let frontier = [startId];
-    let depth = 1;
+    let frontier = directDependentsForAnchor(api, anchor);
     let truncated = false;
-    while (depth <= maxDepth && frontier.length > 0) {
+    frontier = frontier.filter((id) => !seen.has(id));
+    if (frontier.length > limit) {
+        frontier = frontier.slice(0, limit);
+        truncated = true;
+    }
+    for (const id of frontier)
+        seen.add(id);
+    if (frontier.length > 0)
+        layer[1] = frontier;
+    let depth = 2;
+    while (depth <= maxDepth && frontier.length > 0 && !truncated) {
         const next = [];
         for (const id of frontier) {
-            const importers = api.importersOf(id);
-            for (const imp of importers) {
-                if (seen.has(imp.id))
+            for (const dep of nextDependents(api, anchor.kind, id)) {
+                if (seen.has(dep.id))
                     continue;
-                seen.add(imp.id);
-                next.push(imp.id);
+                seen.add(dep.id);
+                next.push(dep.id);
                 if (seen.size - 1 >= limit) {
                     truncated = true;
                     break;
@@ -779,11 +847,50 @@ function reverseClosure(api, startId, maxDepth, limit) {
             layer[depth] = next;
         frontier = next;
         depth += 1;
-        if (truncated)
-            break;
     }
     return { all: [...seen], layer, truncated };
 }
+function directDependentsForAnchor(api, anchor) {
+    if (anchor.kind === NodeKind.Symbol) {
+        const owner = declaringFileOf(api, anchor.id);
+        const refs = dedupeNodes([...api.referencesOf(anchor.id), ...api.callersOf(anchor.id)])
+            .filter((n) => n.kind === NodeKind.File && n.id !== owner?.id)
+            .map((n) => n.id);
+        if (refs.length > 0)
+            return refs;
+        return owner ? api.importersOf(owner.id).map((n) => n.id) : [];
+    }
+    if (anchor.kind === NodeKind.Package) {
+        return api.packageDependents(packageNameFor(anchor)).map((n) => n.id);
+    }
+    return api.importersOf(anchor.id).map((n) => n.id);
+}
+function nextDependents(api, anchorKind, nodeId) {
+    if (anchorKind === NodeKind.Package) {
+        const node = api.neighbours(nodeId)?.node;
+        if (!node)
+            return [];
+        return api.packageDependents(packageNameFor(node));
+    }
+    return api.importersOf(nodeId);
+}
+function declaringFileOf(api, symbolId) {
+    const neighbours = api.neighbours(symbolId);
+    if (!neighbours)
+        return undefined;
+    for (const incoming of neighbours.in) {
+        if (incoming.edge.kind !== EdgeKind.DeclaresSymbol)
+            continue;
+        if ('resolved' in incoming.source)
+            continue;
+        if (incoming.source.kind === NodeKind.File)
+            return incoming.source;
+    }
+    return undefined;
+}
+function packageNameFor(node) {
+    return node.id.startsWith('package:') ? node.id.slice('package:'.length) : node.label;
+}
 function nodeSummary(n) {
     return {
         id: n.id,
@@ -816,3 +923,14 @@ function sumValues(record) {
         n += v;
     return n;
 }
+function dedupeNodes(nodes) {
+    const seen = new Set();
+    const out = [];
+    for (const node of nodes) {
+        if (seen.has(node.id))
+            continue;
+        seen.add(node.id);
+        out.push(node);
+    }
+    return out;
+}

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;AA0BhC,eAAO,MAAM,YAAY,EAAE,eA0M1B,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;AA0BhC,eAAO,MAAM,YAAY,EAAE,eA2M1B,CAAC"}

package/dist/commands/graph.command.js

@@ -17,8 +17,9 @@ const KNOWN_KINDS = [
 ];
 export const graphCommand = {
     name: 'graph',
-    description: 'Show the SharkCraft knowledge graph: nodes (knowledge/rules/paths/templates/pipelines/presets/packs/boundaries) and edges (related-template, preset-references, pipeline-step-references, …). Supports text|json|dot|mermaid output and an `export` subcommand for writing to file.',
-    usage: 'shrk [--cwd <dir>] graph [<id>] [--type <kind>] [--format text|json|dot|mermaid] [--output <file>] [--json] | shrk graph export --format dot|mermaid --output <file>',
+    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|callers|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|callers|cycles|unresolved|deps|why|export ...',
     async run(args) {
         // Code-intelligence subverbs (R65) don't need the knowledge graph —
         // dispatch them before the expensive inspection so they stay fast.

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;AAI9D;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,IAAI,MAAM,CAiD1C;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;EAyHpF"}
+{"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,CAmD1C;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"}

package/dist/commands/help.command.js

@@ -1,5 +1,21 @@
 import { header } from "../output/format-output.js";
 import { COMMAND_CATALOG, defaultShowInHelp } from "./command-catalog.js";
+const EXTRA_HELP_LINES = Object.freeze({
+    graph: [
+        '',
+        'Code-intelligence subverbs:',
+        '  graph index      — build or refresh the code graph',
+        '  graph status     — freshness, counts, and unresolved-import summary',
+        '  graph search     — find files/symbols/packages in the code graph',
+        '  graph context    — inspect one file or symbol with bridge enrichment',
+        '  graph impact     — reverse dependent closure for a file or symbol',
+        '  graph callers    — files that call/reference a symbol',
+        '  graph cycles     — list import cycles',
+        '  graph unresolved — list unresolved imports grouped by file',
+        '  graph deps       — inbound/outbound package dependencies',
+        '  graph why        — shortest-path explanation in the knowledge graph',
+    ],
+});
 /**
  * Product start screen for bare `shrk` / `shrk --help`. Shows the
  * curated ~20-command "starter" surface organized by workflow phase.
@@ -28,6 +44,7 @@ export function renderStartScreen() {
     lines.push('  $ shrk recommend "<task>"        — what should I do?');
     lines.push('  $ shrk context --task "<task>"   — token-budgeted relevant context');
     lines.push('  $ shrk task "<task>"             — full AI-ready task packet (JSON)');
+    lines.push('  $ shrk code-intel                — one-shot code-intelligence health summary');
     lines.push('  $ shrk coverage                  — what knowledge is missing');
     lines.push('');
     lines.push('Generate code safely:');
@@ -37,6 +54,7 @@ export function renderStartScreen() {
     lines.push('  $ shrk quality                   — pre-PR gate (doctor + boundaries + coverage + drift)');
     lines.push('');
     lines.push('Browse what shrk knows:');
+    lines.push('  $ shrk graph status             — current code-graph freshness and health');
     lines.push('  $ shrk knowledge list            — knowledge entries');
     lines.push('  $ shrk rules list                — rules + conventions');
     lines.push('  $ shrk templates list            — generator templates');
@@ -76,10 +94,13 @@ export function makeHelpCommand(registry) {
                     ? args.positional[0].split(/\s+/).filter(Boolean)
                     : args.positional.filter(Boolean);
                 const { handler, matchedPath, node } = registry.resolve(tokens);
-                if (handler && matchedPath.join(' ') === tokens.join(' ')) {
+                if (handler && matchedPath.join(' ') === tokens.join(' ') && node.children.size === 0) {
                     // Exact match on a callable command.
                     const canonical = registry.listCommandAliases().get(tokens[0]);
                     process.stdout.write(`${matchedPath.join(' ')} — ${handler.description}\n${handler.usage}\n`);
+                    const extra = EXTRA_HELP_LINES[matchedPath.join(' ')];
+                    if (extra)
+                        process.stdout.write(extra.join('\n') + '\n');
                     if (canonical && tokens.length === 1) {
                         process.stdout.write(`(alias for: ${canonical})\n`);
                     }

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;AAyVhC,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;AA0VhC,eAAO,MAAM,aAAa,EAAE,eA8V3B,CAAC"}

package/dist/commands/impact.command.js

@@ -209,13 +209,14 @@ async function runViaGraph(args) {
     const cwd = resolveCwd(args);
     const wantJson = flagBool(args, 'json') || flagString(args, 'format') === 'json';
     const positional = args.positional[0];
+    const viaGraphRaw = args.flags.get('via-graph');
     const files = flagList(args, 'files');
     const since = flagString(args, 'since');
     const symbol = flagString(args, 'symbol');
     const fileFlag = flagString(args, 'file');
     const limit = flagNumber(args, 'limit') ?? 200;
     const maxDepth = flagNumber(args, 'max-depth') ?? 5;
-    const target = positional ?? fileFlag;
+    const target = positional ?? fileFlag ?? (typeof viaGraphRaw === 'string' ? viaGraphRaw : undefined);
     const inputs = files.length > 0
         ? { kind: 'files', files }
         : symbol
@@ -295,7 +296,7 @@ export const impactCommand = {
         // graph-backed payload (sharkcraft.graph-impact-analysis/v3). Keeps
         // the legacy v2 inspector path as the default so existing
         // consumers don't shift.
-        if (flagBool(args, 'via-graph')) {
+        if (args.flags.has('via-graph')) {
             return runViaGraph(args);
         }
         const cwd = resolveCwd(args);

package/dist/commands/move-plan.command.d.ts

@@ -0,0 +1,23 @@
+import { type ICommandHandler } from '../command-registry.js';
+/**
+ * `shrk move-plan <source> <target>` — emit a structured plan for
+ * moving a source file to a new location. Read-only: NEVER moves
+ * anything itself, never rewrites imports. The agent (or a human)
+ * uses the plan to do the actual work.
+ *
+ * Covers:
+ *   - graph-traced importer rewrites (relative + package-name imports)
+ *   - exports to revisit if the source was re-exported from an index
+ *   - cross-package warnings (layer-order risks)
+ *   - a rollback plan that's the literal reverse of the move
+ *   - validation commands to run after applying
+ *
+ * Limitations:
+ *   - single-file only. Directory moves can be approximated by
+ *     listing the directory and running this command per file, or
+ *     wait for a `--folder` follow-up.
+ *   - `from '@shrkcrft/pkg/sub'` deep-import rewrites are best-effort;
+ *     ambiguous cases get reported as `review-manually`.
+ */
+export declare const movePlanCommand: ICommandHandler;
+//# sourceMappingURL=move-plan.command.d.ts.map

package/dist/commands/move-plan.command.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"move-plan.command.d.ts","sourceRoot":"","sources":["../../src/commands/move-plan.command.ts"],"names":[],"mappings":"AAGA,OAAO,EAAY,KAAK,eAAe,EAA+B,MAAM,wBAAwB,CAAC;AAqCrG;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,eAAe,EAAE,eA4M7B,CAAC"}