@vyuhlabs/dxkit 2.6.0 → 2.7.0

package/dist/explore/cli/file.js

@@ -0,0 +1,139 @@
+"use strict";
+/**
+ * `vyuh-dxkit explore file <path>` — drill into a single file's
+ * neighborhood. Per CLAUDE.md Rule 12: graph traversal flows through
+ * queries.ts.
+ *
+ * If the user passes an absolute path, convert to project-relative
+ * (the graph artifact uses project-relative paths throughout).
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runFile = runFile;
+const path = __importStar(require("node:path"));
+const queries_1 = require("../queries");
+const format_1 = require("../format");
+function runFile(graph, positionals, values, cwd) {
+    const rawPath = positionals[0];
+    if (!rawPath) {
+        process.stderr.write('Usage: vyuh-dxkit explore file <path>\nProvide a path (relative or absolute) to a source file in the repo.\n');
+        process.exit(1);
+    }
+    // Convert absolute to project-relative if needed. Graphify writes
+    // project-relative paths to graph.json so the lookup key must
+    // match that shape.
+    const resolved = path.isAbsolute(rawPath)
+        ? path.relative(cwd, rawPath).replace(/\\/g, '/')
+        : rawPath.replace(/\\/g, '/');
+    const result = (0, queries_1.fileSummaryQuery)(graph, resolved);
+    if (values.json) {
+        (0, format_1.printJson)((0, format_1.envelope)('explore.file', { path: resolved }, graph, result));
+        return;
+    }
+    if (!result.found) {
+        (0, format_1.printMarkdown)((0, format_1.markdownHeader)('File', resolved, graph), `File \`${resolved}\` is not in the graph. Common reasons:\n` +
+            `- File doesn't exist (typo in path?)\n` +
+            `- Excluded by .dxkit-ignore / minified-detection / unsupported extension\n` +
+            `- Pack for this file's language isn't active in the project`);
+        return;
+    }
+    const symbolRows = result.symbols.map((s) => ({
+        Kind: s.kind,
+        Symbol: s.label,
+        Line: s.line ?? '',
+        Exported: s.exported === undefined ? '?' : s.exported ? '✓' : '·',
+        'Calls in': s.callsIn,
+        'Calls out': s.callsOut,
+    }));
+    const symbolHeaders = ['Kind', 'Symbol', 'Line', 'Exported', 'Calls in', 'Calls out'];
+    const callerRows = result.callerFiles
+        .slice(0, 20)
+        .map((c) => ({ File: c.sourceFile, Calls: c.count }));
+    const calleeRows = result.calleeFiles
+        .slice(0, 20)
+        .map((c) => ({ File: c.sourceFile, Calls: c.count }));
+    const sections = [];
+    sections.push((0, format_1.markdownHeader)('File', resolved, graph));
+    // Community + summary line
+    const summary = [];
+    if (result.communityId !== undefined) {
+        const dir = result.communityLabel || '—';
+        const pack = result.communityPack || '—';
+        summary.push(`**Community**: ${result.communityId} (${dir}, ${pack})`);
+    }
+    const kindCounts = {};
+    for (const s of result.symbols)
+        kindCounts[s.kind] = (kindCounts[s.kind] ?? 0) + 1;
+    const symBreakdown = Object.entries(kindCounts)
+        .map(([k, c]) => `${c} ${k}${c === 1 ? '' : 's'}`)
+        .join(', ');
+    if (symBreakdown)
+        summary.push(`**Symbols**: ${symBreakdown}`);
+    const exportedSymbols = result.symbols.filter((s) => s.exported === true);
+    if (exportedSymbols.length > 0) {
+        summary.push(`**Exported**: ${exportedSymbols
+            .map((s) => s.label)
+            .slice(0, 8)
+            .join(', ')}${exportedSymbols.length > 8 ? ` (+${exportedSymbols.length - 8} more)` : ''}`);
+    }
+    if (summary.length > 0)
+        sections.push(summary.join('\n'));
+    if (symbolRows.length > 0) {
+        sections.push('### Symbols defined here');
+        sections.push((0, format_1.markdownTable)(symbolHeaders, symbolRows));
+    }
+    if (callerRows.length > 0) {
+        sections.push(`### Callers (${result.callerFiles.length} file${result.callerFiles.length === 1 ? '' : 's'})`);
+        sections.push((0, format_1.markdownTable)(['File', 'Calls'], callerRows));
+    }
+    else {
+        sections.push('### Callers\n\nNo other files call into this file. Either it is a leaf module (entry point, top-level CLI handler) or its consumers are outside the graphify-extracted set.');
+    }
+    if (calleeRows.length > 0) {
+        sections.push(`### Callees (${result.calleeFiles.length} file${result.calleeFiles.length === 1 ? '' : 's'})`);
+        sections.push((0, format_1.markdownTable)(['File', 'Calls'], calleeRows));
+    }
+    if (result.importsOut.length > 0) {
+        sections.push(`### Imports out (${result.importsOut.length} file${result.importsOut.length === 1 ? '' : 's'})`);
+        sections.push(result.importsOut.map((i) => `- ${i.sourceFile}`).join('\n'));
+    }
+    if (result.importsIn.length > 0) {
+        sections.push(`### Imports in (${result.importsIn.length} file${result.importsIn.length === 1 ? '' : 's'})`);
+        sections.push(result.importsIn.map((i) => `- ${i.sourceFile}`).join('\n'));
+    }
+    sections.push((0, format_1.markdownFooter)('Drill into a caller: `vyuh-dxkit explore file <path>`.'));
+    (0, format_1.printMarkdown)(...sections);
+}
+//# sourceMappingURL=file.js.map

package/dist/explore/cli/file.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"file.js","sourceRoot":"","sources":["../../../src/explore/cli/file.ts"],"names":[],"mappings":"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"}

package/dist/explore/cli/hot-files.d.ts

@@ -0,0 +1,11 @@
+/**
+ * `vyuh-dxkit explore hot-files` — files most depended on.
+ *
+ * Pure pipeline: parse args → call hotFilesQuery → format output.
+ * No graph traversal in here (CLAUDE.md Rule 12 enforces);
+ * everything goes through src/explore/queries.ts.
+ */
+import type { Graph } from '../types';
+import type { ExploreCliValues } from '../../explore-cli';
+export declare function runHotFiles(graph: Graph, _positionals: ReadonlyArray<string>, values: ExploreCliValues): void;
+//# sourceMappingURL=hot-files.d.ts.map

package/dist/explore/cli/hot-files.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hot-files.d.ts","sourceRoot":"","sources":["../../../src/explore/cli/hot-files.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAWH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,UAAU,CAAC;AACtC,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAI1D,wBAAgB,WAAW,CACzB,KAAK,EAAE,KAAK,EACZ,YAAY,EAAE,aAAa,CAAC,MAAM,CAAC,EACnC,MAAM,EAAE,gBAAgB,GACvB,IAAI,CAqCN"}

package/dist/explore/cli/hot-files.js

@@ -0,0 +1,63 @@
+"use strict";
+/**
+ * `vyuh-dxkit explore hot-files` — files most depended on.
+ *
+ * Pure pipeline: parse args → call hotFilesQuery → format output.
+ * No graph traversal in here (CLAUDE.md Rule 12 enforces);
+ * everything goes through src/explore/queries.ts.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runHotFiles = runHotFiles;
+const queries_1 = require("../queries");
+const format_1 = require("../format");
+const DEFAULT_LIMIT = 20;
+function runHotFiles(graph, _positionals, values) {
+    const limit = parseLimit(values.limit, DEFAULT_LIMIT);
+    const results = (0, queries_1.hotFilesQuery)(graph, limit);
+    if (values.json) {
+        (0, format_1.printJson)((0, format_1.envelope)('explore.hot-files', { limit }, graph, results));
+        return;
+    }
+    // Markdown: header, table, footer hint.
+    const rows = results.map((r) => ({
+        Path: r.sourceFile,
+        'Calls in': r.callsIn,
+        'Imports in': r.importsIn,
+        'Calls out': r.callsOut,
+        Community: r.communityLabel
+            ? `${r.communityId} (${r.communityLabel})`
+            : r.communityId !== undefined
+                ? String(r.communityId)
+                : '',
+    }));
+    const headers = ['Path', 'Calls in', 'Imports in', 'Calls out', 'Community'];
+    if (results.length === 0) {
+        (0, format_1.printMarkdown)((0, format_1.markdownHeader)('Hot files', "what's central?", graph), 'No files found in the graph. Either the repo has no inbound call edges, or the graph artifact is empty.');
+        return;
+    }
+    (0, format_1.printMarkdown)((0, format_1.markdownHeader)('Hot files', "what's central?", graph), (0, format_1.markdownTable)(headers, rows), explainResults(results), (0, format_1.markdownFooter)('Drill into one: `vyuh-dxkit explore file <path>`.'));
+}
+/**
+ * One-line interpretation hint below the table. A file with high
+ * "calls in" + low "calls out" is foundational infrastructure;
+ * inverting that signals a coordinator / orchestrator.
+ */
+function explainResults(results) {
+    if (results.length === 0)
+        return '';
+    const top = results[0];
+    const ratio = top.callsOut > 0 ? top.callsIn / top.callsOut : top.callsIn;
+    if (ratio >= 3) {
+        return `A file with high "calls in" + low "calls out" is foundational infrastructure. \`${top.sourceFile}\` looks like one.`;
+    }
+    return 'A file with high "calls in" + low "calls out" is foundational infrastructure.';
+}
+function parseLimit(raw, defaultValue) {
+    if (!raw)
+        return defaultValue;
+    const n = parseInt(raw, 10);
+    if (isNaN(n) || n < 1)
+        return defaultValue;
+    return Math.min(n, 1000); // sanity cap
+}
+//# sourceMappingURL=hot-files.js.map

package/dist/explore/cli/hot-files.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hot-files.js","sourceRoot":"","sources":["../../../src/explore/cli/hot-files.ts"],"names":[],"mappings":";AAAA;;;;;;GAMG;;AAgBH,kCAyCC;AAvDD,wCAA+D;AAC/D,sCAOmB;AAInB,MAAM,aAAa,GAAG,EAAE,CAAC;AAEzB,SAAgB,WAAW,CACzB,KAAY,EACZ,YAAmC,EACnC,MAAwB;IAExB,MAAM,KAAK,GAAG,UAAU,CAAC,MAAM,CAAC,KAAK,EAAE,aAAa,CAAC,CAAC;IACtD,MAAM,OAAO,GAAG,IAAA,uBAAa,EAAC,KAAK,EAAE,KAAK,CAAC,CAAC;IAE5C,IAAI,MAAM,CAAC,IAAI,EAAE,CAAC;QAChB,IAAA,kBAAS,EAAC,IAAA,iBAAQ,EAAC,mBAAmB,EAAE,EAAE,KAAK,EAAE,EAAE,KAAK,EAAE,OAAO,CAAC,CAAC,CAAC;QACpE,OAAO;IACT,CAAC;IAED,wCAAwC;IACxC,MAAM,IAAI,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;QAC/B,IAAI,EAAE,CAAC,CAAC,UAAU;QAClB,UAAU,EAAE,CAAC,CAAC,OAAO;QACrB,YAAY,EAAE,CAAC,CAAC,SAAS;QACzB,WAAW,EAAE,CAAC,CAAC,QAAQ;QACvB,SAAS,EAAE,CAAC,CAAC,cAAc;YACzB,CAAC,CAAC,GAAG,CAAC,CAAC,WAAW,KAAK,CAAC,CAAC,cAAc,GAAG;YAC1C,CAAC,CAAC,CAAC,CAAC,WAAW,KAAK,SAAS;gBAC3B,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,WAAW,CAAC;gBACvB,CAAC,CAAC,EAAE;KACT,CAAC,CAAC,CAAC;IACJ,MAAM,OAAO,GAAG,CAAC,MAAM,EAAE,UAAU,EAAE,YAAY,EAAE,WAAW,EAAE,WAAW,CAAU,CAAC;IAEtF,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACzB,IAAA,sBAAa,EACX,IAAA,uBAAc,EAAC,WAAW,EAAE,iBAAiB,EAAE,KAAK,CAAC,EACrD,yGAAyG,CAC1G,CAAC;QACF,OAAO;IACT,CAAC;IAED,IAAA,sBAAa,EACX,IAAA,uBAAc,EAAC,WAAW,EAAE,iBAAiB,EAAE,KAAK,CAAC,EACrD,IAAA,sBAAa,EAAC,OAAO,EAAE,IAAI,CAAC,EAC5B,cAAc,CAAC,OAAO,CAAC,EACvB,IAAA,uBAAc,EAAC,mDAAmD,CAAC,CACpE,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,SAAS,cAAc,CAAC,OAAwB;IAC9C,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IACpC,MAAM,GAAG,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IACvB,MAAM,KAAK,GAAG,GAAG,CAAC,QAAQ,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,GAAG,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC;IAC1E,IAAI,KAAK,IAAI,CAAC,EAAE,CAAC;QACf,OAAO,mFAAmF,GAAG,CAAC,UAAU,oBAAoB,CAAC;IAC/H,CAAC;IACD,OAAO,+EAA+E,CAAC;AACzF,CAAC;AAED,SAAS,UAAU,CAAC,GAAuB,EAAE,YAAoB;IAC/D,IAAI,CAAC,GAAG;QAAE,OAAO,YAAY,CAAC;IAC9B,MAAM,CAAC,GAAG,QAAQ,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;IAC5B,IAAI,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC;QAAE,OAAO,YAAY,CAAC;IAC3C,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC,CAAC,aAAa;AACzC,CAAC"}

package/dist/explore/context-hook.d.ts

@@ -0,0 +1,42 @@
+/**
+ * `vyuh-dxkit context-hook` — the Claude Code PreToolUse hook that
+ * delivers the token-reduction win passively. Wired into a scaffolded
+ * repo's `.claude/settings.json` with a `Grep|Glob` matcher: when an
+ * agent is about to search the codebase, this hook injects a slim
+ * structural map as `additionalContext` so the agent needs fewer
+ * follow-up whole-file reads.
+ *
+ * THE CONTRACT IS FAIL-OPEN + ADDITIVE. This hook can only ever ADD
+ * context; it never blocks the tool, never replaces grep output, and
+ * stays a silent no-op (exit 0, no stdout) on ANY problem — missing
+ * graph.json, parse error, no keyword match, unreadable stdin. So
+ * Claude Code behaves exactly as it does today whenever the graph is
+ * absent or unhelpful; the hook is pure upside.
+ *
+ * Claude Code passes the tool call as JSON on stdin
+ * (`{ tool_name, tool_input: { pattern, ... }, ... }`) and reads a
+ * JSON object on stdout with `hookSpecificOutput.additionalContext`.
+ */
+import { type ContextResult } from './queries';
+import type { Graph } from './types';
+/**
+ * Entry point for `case 'context-hook'`. Reads stdin, runs the query,
+ * writes the hook output. Wrapped so nothing it does can fail the
+ * tool call: every failure path resolves to a silent no-op.
+ */
+export declare function runContextHook(cwd: string): Promise<void>;
+/**
+ * Extract the search keyword from the PreToolUse payload. Both Grep
+ * and Glob carry it on `tool_input.pattern`. Returns undefined for
+ * anything we can't confidently read (→ no-op upstream).
+ */
+export declare function extractPattern(rawStdin: string): string | undefined;
+/**
+ * Compact `additionalContext` body. Terser than the CLI's markdown
+ * (the hook pays this cost on every grep): an anchor line, blast
+ * radius, and the top symbols grouped by their leading community.
+ * Leads with a one-line provenance + best-effort caveat so the agent
+ * calibrates trust.
+ */
+export declare function formatHookContext(result: ContextResult, graph: Graph): string;
+//# sourceMappingURL=context-hook.d.ts.map

package/dist/explore/context-hook.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-hook.d.ts","sourceRoot":"","sources":["../../src/explore/context-hook.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAAgB,KAAK,aAAa,EAAE,MAAM,WAAW,CAAC;AAE7D,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAKrC;;;;GAIG;AACH,wBAAsB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CA0B/D;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAcnE;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,aAAa,EAAE,KAAK,EAAE,KAAK,GAAG,MAAM,CAiC7E"}

package/dist/explore/context-hook.js

@@ -0,0 +1,131 @@
+"use strict";
+/**
+ * `vyuh-dxkit context-hook` — the Claude Code PreToolUse hook that
+ * delivers the token-reduction win passively. Wired into a scaffolded
+ * repo's `.claude/settings.json` with a `Grep|Glob` matcher: when an
+ * agent is about to search the codebase, this hook injects a slim
+ * structural map as `additionalContext` so the agent needs fewer
+ * follow-up whole-file reads.
+ *
+ * THE CONTRACT IS FAIL-OPEN + ADDITIVE. This hook can only ever ADD
+ * context; it never blocks the tool, never replaces grep output, and
+ * stays a silent no-op (exit 0, no stdout) on ANY problem — missing
+ * graph.json, parse error, no keyword match, unreadable stdin. So
+ * Claude Code behaves exactly as it does today whenever the graph is
+ * absent or unhelpful; the hook is pure upside.
+ *
+ * Claude Code passes the tool call as JSON on stdin
+ * (`{ tool_name, tool_input: { pattern, ... }, ... }`) and reads a
+ * JSON object on stdout with `hookSpecificOutput.additionalContext`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runContextHook = runContextHook;
+exports.extractPattern = extractPattern;
+exports.formatHookContext = formatHookContext;
+const queries_1 = require("./queries");
+const load_1 = require("./load");
+/** Stingier than the manual CLI's 2000 — the hook fires on every grep. */
+const HOOK_BUDGET = 1500;
+/**
+ * Entry point for `case 'context-hook'`. Reads stdin, runs the query,
+ * writes the hook output. Wrapped so nothing it does can fail the
+ * tool call: every failure path resolves to a silent no-op.
+ */
+async function runContextHook(cwd) {
+    try {
+        const raw = await readStdin();
+        if (!raw.trim())
+            return;
+        const pattern = extractPattern(raw);
+        if (!pattern)
+            return;
+        const graph = (0, load_1.tryLoadGraph)(cwd);
+        if (!graph)
+            return;
+        const result = (0, queries_1.contextQuery)(graph, pattern, { budget: HOOK_BUDGET, substring: true });
+        if (!result.matched || result.selection.length === 0)
+            return;
+        const additionalContext = formatHookContext(result, graph);
+        process.stdout.write(JSON.stringify({
+            hookSpecificOutput: {
+                hookEventName: 'PreToolUse',
+                additionalContext,
+            },
+        }));
+    }
+    catch {
+        // Fail-open: errors produce no output; the tool proceeds normally.
+    }
+}
+/**
+ * Extract the search keyword from the PreToolUse payload. Both Grep
+ * and Glob carry it on `tool_input.pattern`. Returns undefined for
+ * anything we can't confidently read (→ no-op upstream).
+ */
+function extractPattern(rawStdin) {
+    let parsed;
+    try {
+        parsed = JSON.parse(rawStdin);
+    }
+    catch {
+        return undefined;
+    }
+    if (!parsed || typeof parsed !== 'object')
+        return undefined;
+    const toolInput = parsed.tool_input;
+    if (!toolInput || typeof toolInput !== 'object')
+        return undefined;
+    const pattern = toolInput.pattern;
+    if (typeof pattern !== 'string')
+        return undefined;
+    const trimmed = pattern.trim();
+    return trimmed.length > 0 ? trimmed : undefined;
+}
+/**
+ * Compact `additionalContext` body. Terser than the CLI's markdown
+ * (the hook pays this cost on every grep): an anchor line, blast
+ * radius, and the top symbols grouped by their leading community.
+ * Leads with a one-line provenance + best-effort caveat so the agent
+ * calibrates trust.
+ */
+function formatHookContext(result, graph) {
+    const lines = [];
+    lines.push(`dxkit graph context for \`${result.query}\` (from .dxkit/reports/graph.json, generated ${graph.meta.generatedAt.slice(0, 10)} — structural hint, grep results remain authoritative):`);
+    if (result.anchor) {
+        const a = result.anchor;
+        const where = a.line ? `${a.sourceFile}:${a.line}` : a.sourceFile;
+        lines.push(`- Start here: \`${a.symbol}\` (${where}), called from ${a.calledFrom} place(s).`);
+    }
+    if (result.blastRadius.callers > 0) {
+        lines.push(`- Blast radius: ${result.blastRadius.callers} caller(s) across ${result.blastRadius.callerFiles} file(s).`);
+    }
+    // Top symbols overall (seeds first, then by in-degree), capped tight.
+    const top = [...result.selection]
+        .sort((a, b) => a.hop - b.hop || b.callsIn - a.callsIn)
+        .slice(0, 10);
+    if (top.length > 0) {
+        lines.push('- Relevant symbols:');
+        for (const s of top) {
+            const where = s.line ? `${s.sourceFile}:${s.line}` : s.sourceFile;
+            lines.push(`    ${s.symbol} (${where})`);
+        }
+    }
+    if (result.truncated) {
+        lines.push(`- (+${result.omittedCount} more symbols in the wider neighborhood)`);
+    }
+    return lines.join('\n');
+}
+/** Read all of stdin as a string. Resolves '' if stdin is a TTY/empty. */
+function readStdin() {
+    return new Promise((resolve) => {
+        if (process.stdin.isTTY) {
+            resolve('');
+            return;
+        }
+        const chunks = [];
+        process.stdin.on('data', (c) => chunks.push(Buffer.from(c)));
+        process.stdin.on('end', () => resolve(Buffer.concat(chunks).toString('utf-8')));
+        process.stdin.on('error', () => resolve(''));
+    });
+}
+//# sourceMappingURL=context-hook.js.map

package/dist/explore/context-hook.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-hook.js","sourceRoot":"","sources":["../../src/explore/context-hook.ts"],"names":[],"mappings":"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"}

package/dist/explore/finding-context.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Finding-enrichment adapter — attaches graph context (module
+ * membership + blast radius + enclosing symbol) to analyzer findings
+ * that carry a `file` (+ optional `line`). Consumed by the detailed
+ * report builders for the `vuln` / `test-gaps` / `quality` commands
+ * when the user passes `--graph-context`.
+ *
+ * Per CLAUDE.md Rule 12 this is the only layer (alongside the context
+ * hook + dashboard adapter) that loads the graph for finding
+ * enrichment; analyzers receive the pre-built `DetailedGraphContext`
+ * and never touch graph.json themselves. All graph math stays in
+ * `queries.ts:findingContextQuery`.
+ *
+ * THE CONTRACT IS FAIL-OPEN + ADDITIVE, like the context hook: a
+ * missing / corrupt / stale graph degrades to `undefined` (no
+ * enrichment), never an error. Findings render exactly as they do
+ * today whenever the graph is absent.
+ */
+import { type FindingContext } from './queries';
+/** A finding's location — the enrichment key. `line` optional (file-level findings). */
+export interface FindingLocation {
+    file: string;
+    line?: number;
+}
+/**
+ * The enrichment payload stored on a detailed report. `generatedAt` +
+ * `truncated` carry the graph.json provenance so a reader can detect a
+ * stale enrichment (the graph predates the analyzed commit) without
+ * re-loading the artifact. `contexts` is keyed by `locationKey` and
+ * holds only `found: true` entries — files absent from the graph
+ * produce no key (the renderer treats a missing key as "no context").
+ */
+export interface DetailedGraphContext {
+    generatedAt: string;
+    truncated: boolean;
+    contexts: Record<string, FindingContext>;
+}
+export interface BuildFindingContextOpts {
+    /** Budget cap: only the first N unique locations are enriched (bloat guard). */
+    maxFindings?: number;
+    /** Sample size of caller files surfaced per finding. */
+    topCallerFiles?: number;
+}
+/** Stable lookup key for a finding location. */
+export declare function locationKey(file: string, line?: number): string;
+/**
+ * Build per-finding graph context for a list of finding locations.
+ * Fail-open: returns `undefined` when the graph can't be loaded.
+ *
+ * Dedupes identical locations (same file:line surfaced by multiple
+ * tools) and budget-caps the work at `maxFindings` unique locations.
+ * Only `found: true` contexts are stored — a finding in a file the
+ * graph never parsed contributes no key, keeping the payload lean on
+ * repos where graphify covers only part of the tree.
+ */
+export declare function buildFindingContextMap(cwd: string, locations: ReadonlyArray<FindingLocation>, opts?: BuildFindingContextOpts): DetailedGraphContext | undefined;
+/**
+ * Compact one-cell rendering for a markdown table: `role · N caller
+ * files`. Returns `—` when there's no context for the location (file
+ * not in the graph). Used by the detailed report renderers.
+ */
+export declare function formatGraphContextCell(ctx: FindingContext | undefined): string;
+/**
+ * Provenance + honesty line printed above an enriched section so the
+ * reader knows the context is a structural hint tied to a specific
+ * graph snapshot (and that graphify can conflate same-name symbols).
+ */
+export declare function graphContextProvenanceLine(gc: DetailedGraphContext): string;
+//# sourceMappingURL=finding-context.d.ts.map

package/dist/explore/finding-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"finding-context.d.ts","sourceRoot":"","sources":["../../src/explore/finding-context.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAGH,OAAO,EAAuB,KAAK,cAAc,EAAE,MAAM,WAAW,CAAC;AAGrE,wFAAwF;AACxF,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,oBAAoB;IACnC,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,OAAO,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;CAC1C;AAED,MAAM,WAAW,uBAAuB;IACtC,gFAAgF;IAChF,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,wDAAwD;IACxD,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,gDAAgD;AAChD,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAE/D;AAED;;;;;;;;;GASG;AACH,wBAAgB,sBAAsB,CACpC,GAAG,EAAE,MAAM,EACX,SAAS,EAAE,aAAa,CAAC,eAAe,CAAC,EACzC,IAAI,GAAE,uBAA4B,GACjC,oBAAoB,GAAG,SAAS,CA4BlC;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,cAAc,GAAG,SAAS,GAAG,MAAM,CAY9E;AAED;;;;GAIG;AACH,wBAAgB,0BAA0B,CAAC,EAAE,EAAE,oBAAoB,GAAG,MAAM,CAI3E"}

package/dist/explore/finding-context.js

@@ -0,0 +1,102 @@
+"use strict";
+/**
+ * Finding-enrichment adapter — attaches graph context (module
+ * membership + blast radius + enclosing symbol) to analyzer findings
+ * that carry a `file` (+ optional `line`). Consumed by the detailed
+ * report builders for the `vuln` / `test-gaps` / `quality` commands
+ * when the user passes `--graph-context`.
+ *
+ * Per CLAUDE.md Rule 12 this is the only layer (alongside the context
+ * hook + dashboard adapter) that loads the graph for finding
+ * enrichment; analyzers receive the pre-built `DetailedGraphContext`
+ * and never touch graph.json themselves. All graph math stays in
+ * `queries.ts:findingContextQuery`.
+ *
+ * THE CONTRACT IS FAIL-OPEN + ADDITIVE, like the context hook: a
+ * missing / corrupt / stale graph degrades to `undefined` (no
+ * enrichment), never an error. Findings render exactly as they do
+ * today whenever the graph is absent.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.locationKey = locationKey;
+exports.buildFindingContextMap = buildFindingContextMap;
+exports.formatGraphContextCell = formatGraphContextCell;
+exports.graphContextProvenanceLine = graphContextProvenanceLine;
+const load_1 = require("./load");
+const queries_1 = require("./queries");
+const languages_1 = require("../languages");
+/** Stable lookup key for a finding location. */
+function locationKey(file, line) {
+    return typeof line === 'number' ? `${file}:${line}` : file;
+}
+/**
+ * Build per-finding graph context for a list of finding locations.
+ * Fail-open: returns `undefined` when the graph can't be loaded.
+ *
+ * Dedupes identical locations (same file:line surfaced by multiple
+ * tools) and budget-caps the work at `maxFindings` unique locations.
+ * Only `found: true` contexts are stored — a finding in a file the
+ * graph never parsed contributes no key, keeping the payload lean on
+ * repos where graphify covers only part of the tree.
+ */
+function buildFindingContextMap(cwd, locations, opts = {}) {
+    const graph = (0, load_1.tryLoadGraph)(cwd);
+    if (!graph)
+        return undefined;
+    const max = opts.maxFindings ?? 200;
+    const contexts = {};
+    let enriched = 0;
+    for (const loc of locations) {
+        if (enriched >= max)
+            break;
+        const key = locationKey(loc.file, loc.line);
+        if (key in contexts)
+            continue;
+        const ctx = (0, queries_1.findingContextQuery)(graph, loc.file, loc.line, {
+            topCallerFiles: opts.topCallerFiles,
+        });
+        enriched++;
+        if (!ctx.found)
+            continue;
+        // Stamp the file's call-graph reliability (Rule 6: the fact comes
+        // from the language pack, not a hardcoded table here). Only record
+        // the non-default values to keep the payload lean — absent ⇒ 'full'.
+        const rel = (0, languages_1.languageForFile)(loc.file)?.callGraphReliability;
+        contexts[key] = rel && rel !== 'full' ? { ...ctx, callGraphReliability: rel } : ctx;
+    }
+    return {
+        generatedAt: graph.meta.generatedAt,
+        truncated: graph.meta.truncated,
+        contexts,
+    };
+}
+/**
+ * Compact one-cell rendering for a markdown table: `role · N caller
+ * files`. Returns `—` when there's no context for the location (file
+ * not in the graph). Used by the detailed report renderers.
+ */
+function formatGraphContextCell(ctx) {
+    if (!ctx || !ctx.found)
+        return '—';
+    const role = ctx.community?.role ?? 'unclustered';
+    // For languages graphify can't resolve call edges for (C#), the
+    // caller count is untrustworthy — suppress it rather than print a
+    // misleading "0 caller files" (which a fixing agent could read as
+    // "safe to change"). The module/role label is still reliable.
+    if (ctx.callGraphReliability === 'unreliable') {
+        return `${role} · blast radius n/a (call graph)`;
+    }
+    const n = ctx.blastRadius.callerFiles;
+    return `${role} · ${n} caller file${n === 1 ? '' : 's'}`;
+}
+/**
+ * Provenance + honesty line printed above an enriched section so the
+ * reader knows the context is a structural hint tied to a specific
+ * graph snapshot (and that graphify can conflate same-name symbols).
+ */
+function graphContextProvenanceLine(gc) {
+    const date = gc.generatedAt.slice(0, 10);
+    const stale = gc.truncated ? ' (graph truncated — coverage partial)' : '';
+    return `_Graph context column from \`.dxkit/reports/graph.json\` (generated ${date}${stale}) — structural hint; blast radius is file-level, same-name symbols may conflate call edges, and it reads \`n/a\` for languages whose call graph graphify can't resolve (a blank is not "0 callers"/"safe to change")._`;
+}
+//# sourceMappingURL=finding-context.js.map

package/dist/explore/finding-context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"finding-context.js","sourceRoot":"","sources":["../../src/explore/finding-context.ts"],"names":[],"mappings":"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"}