@vyuhlabs/dxkit 2.5.2 → 2.7.0

package/dist/explore/cli/entry-points.js

@@ -0,0 +1,85 @@
+"use strict";
+/**
+ * `vyuh-dxkit explore entry-points` — what does this repo do?
+ *
+ * Cross-references graph nodes with the active packs'
+ * architecturalShape (per CLAUDE.md Rule 8 — no hardcoded framework
+ * strings here). Detects the project's stack via `detect(cwd)` so
+ * only active-pack patterns contribute.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runEntryPoints = runEntryPoints;
+const detect_1 = require("../../detect");
+const languages_1 = require("../../languages");
+const queries_1 = require("../queries");
+const format_1 = require("../format");
+const DEFAULT_LIMIT = 10;
+function runEntryPoints(graph, _positionals, values, cwd) {
+    const limit = parseLimit(values.limit, DEFAULT_LIMIT);
+    const stack = (0, detect_1.detect)(cwd);
+    const primaryPaths = (0, languages_1.allPrimaryComponentPaths)(stack.languages);
+    const routePaths = (0, languages_1.allRoutePaths)(stack.languages);
+    const vocabulary = (0, languages_1.dominantVocabulary)(stack.languages);
+    const results = (0, queries_1.entryPointsQuery)(graph, primaryPaths, routePaths, limit);
+    if (values.json) {
+        (0, format_1.printJson)((0, format_1.envelope)('explore.entry-points', { limit, primaryPaths, routePaths, packs: graph.meta.packs }, graph, results));
+        return;
+    }
+    if (primaryPaths.length === 0 && routePaths.length === 0) {
+        (0, format_1.printMarkdown)((0, format_1.markdownHeader)('Entry points', 'what does this repo do?', graph), `No entry-point patterns declared for the active packs (${graph.meta.packs.join(', ') || 'none detected'}).\n\n` +
+            'Each language pack declares its own primary-component / route path conventions in `LanguageSupport.architecturalShape` (CLAUDE.md Rule 8). Packs without conventional entry-point paths (e.g. Rust) intentionally omit them.');
+        return;
+    }
+    if (results.length === 0) {
+        (0, format_1.printMarkdown)((0, format_1.markdownHeader)('Entry points', 'what does this repo do?', graph), `No source files matched the active packs' entry-point patterns.\n\n` +
+            `Patterns tried: ${[...primaryPaths, ...routePaths].map((p) => `\`${p}\``).join(', ')}\n\n` +
+            `Either this repo has no conventional entry points, or the patterns don't match this codebase's structure.`);
+        return;
+    }
+    // Group by componentType + emit one table per group.
+    const grouped = new Map();
+    for (const r of results) {
+        const key = r.componentType;
+        const list = grouped.get(key) ?? [];
+        list.push(r);
+        grouped.set(key, list);
+    }
+    const sections = [];
+    sections.push((0, format_1.markdownHeader)('Entry points', 'what does this repo do?', graph));
+    // Vocabulary line so the reader knows the pack's framing.
+    const vocabLine = [];
+    if (vocabulary?.components)
+        vocabLine.push(`components → **${vocabulary.components}**`);
+    if (vocabulary?.routes)
+        vocabLine.push(`routes → **${vocabulary.routes}**`);
+    if (vocabulary?.models)
+        vocabLine.push(`models → **${vocabulary.models}**`);
+    if (vocabLine.length > 0) {
+        sections.push(`*Pack vocabulary*: ${vocabLine.join(', ')}.`);
+    }
+    for (const [type, rows] of grouped) {
+        sections.push(`### ${capitalize(type)} (${rows.length})`);
+        sections.push((0, format_1.markdownTable)(['Path', 'Symbol', 'Calls out', 'Pack'], rows.map((r) => ({
+            Path: r.line ? `${r.sourceFile}:${r.line}` : r.sourceFile,
+            Symbol: r.symbol,
+            'Calls out': r.callsOut,
+            Pack: r.pack,
+        }))));
+    }
+    sections.push((0, format_1.markdownFooter)('Drill into one: `vyuh-dxkit explore file <path>`.'));
+    (0, format_1.printMarkdown)(...sections);
+}
+function capitalize(s) {
+    if (!s)
+        return s;
+    return s[0].toUpperCase() + s.slice(1);
+}
+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);
+}
+//# sourceMappingURL=entry-points.js.map

package/dist/explore/cli/entry-points.js.map

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

package/dist/explore/cli/feature.d.ts

@@ -0,0 +1,16 @@
+/**
+ * `vyuh-dxkit explore feature <keyword>` — where is feature X
+ * implemented? The marquee query of the explore CLI.
+ *
+ * Three-stage resolution (per Sprint 0 spec):
+ *   1. Direct symbolIndex match
+ *   2. Substring expansion (opt-in via --substring; off by default)
+ *   3. Structural expansion (community + 1-hop callers/callees)
+ *
+ * On zero hits, prints "did you mean..." suggestions from
+ * edit-distance against symbolIndex keys.
+ */
+import type { Graph } from '../types';
+import type { ExploreCliValues } from '../../explore-cli';
+export declare function runFeature(graph: Graph, positionals: ReadonlyArray<string>, values: ExploreCliValues): void;
+//# sourceMappingURL=feature.d.ts.map

package/dist/explore/cli/feature.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"feature.d.ts","sourceRoot":"","sources":["../../../src/explore/cli/feature.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAWH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,UAAU,CAAC;AACtC,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAI1D,wBAAgB,UAAU,CACxB,KAAK,EAAE,KAAK,EACZ,WAAW,EAAE,aAAa,CAAC,MAAM,CAAC,EAClC,MAAM,EAAE,gBAAgB,GACvB,IAAI,CA4DN"}

package/dist/explore/cli/feature.js

@@ -0,0 +1,89 @@
+"use strict";
+/**
+ * `vyuh-dxkit explore feature <keyword>` — where is feature X
+ * implemented? The marquee query of the explore CLI.
+ *
+ * Three-stage resolution (per Sprint 0 spec):
+ *   1. Direct symbolIndex match
+ *   2. Substring expansion (opt-in via --substring; off by default)
+ *   3. Structural expansion (community + 1-hop callers/callees)
+ *
+ * On zero hits, prints "did you mean..." suggestions from
+ * edit-distance against symbolIndex keys.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runFeature = runFeature;
+const queries_1 = require("../queries");
+const format_1 = require("../format");
+const DEFAULT_LIMIT = 50;
+function runFeature(graph, positionals, values) {
+    const keyword = positionals[0];
+    if (!keyword) {
+        process.stderr.write('Usage: vyuh-dxkit explore feature <keyword> [--substring] [--limit 50]\n');
+        process.exit(1);
+    }
+    const limit = parseLimit(values.limit, DEFAULT_LIMIT);
+    const substring = !!values.substring;
+    const result = (0, queries_1.featureQuery)(graph, keyword, { limit, substring });
+    if (values.json) {
+        (0, format_1.printJson)((0, format_1.envelope)('explore.feature', { keyword, limit, substring }, graph, result));
+        return;
+    }
+    const sections = [];
+    sections.push((0, format_1.markdownHeader)('Feature', `\`${keyword}\``, graph));
+    if (result.results.length === 0) {
+        if (result.suggestions.length > 0) {
+            const lines = result.suggestions
+                .map((s) => `  - \`${s.key}\` (${s.hits} hit${s.hits === 1 ? '' : 's'})`)
+                .join('\n');
+            sections.push(`No exact symbol match for \`${keyword}\`. Related symbols (substring or typo-distance):\n\n${lines}\n\nRerun with \`--substring\` to expand structurally from these (the typical "where is X implemented?" workflow), or pick a specific symbol above.`);
+        }
+        else {
+            sections.push(`No symbols matched \`${keyword}\` (no close alternatives found either). Try a different keyword, rerun with \`--substring\` for broader matching, or check \`vyuh-dxkit explore communities\` to see the natural-module structure.`);
+        }
+        (0, format_1.printMarkdown)(...sections);
+        return;
+    }
+    // Summary line + central entry point (if any).
+    const totalSeeds = result.results.reduce((sum, c) => sum + c.seedHits, 0);
+    sections.push(`**Seed matches**: ${totalSeeds} symbol${totalSeeds === 1 ? '' : 's'} across ${result.results.length} cluster${result.results.length === 1 ? '' : 's'}.`);
+    // Per-cluster sections.
+    for (const cluster of result.results) {
+        sections.push(buildClusterSection(cluster));
+    }
+    if (result.centralEntryPoint) {
+        const cep = result.centralEntryPoint;
+        const where = cep.line ? `${cep.sourceFile}:${cep.line}` : cep.sourceFile;
+        sections.push(`\nThe most-called seed symbol is **\`${cep.symbol}\`** at \`${where}\` — called from ${cep.calledFrom} place${cep.calledFrom === 1 ? '' : 's'}. A natural starting read.`);
+    }
+    sections.push((0, format_1.markdownFooter)('Drill into one: `vyuh-dxkit explore file <path>`.'));
+    (0, format_1.printMarkdown)(...sections);
+}
+function buildClusterSection(cluster) {
+    const lines = [];
+    const id = cluster.clusterId + 1;
+    const role = cluster.role;
+    const seedNote = cluster.seedHits === 0 ? ' (expansion only — no direct seed)' : '';
+    lines.push(`### Cluster ${id} — ${role}${seedNote}`);
+    if (cluster.communityId !== undefined) {
+        lines.push(`*Community*: ${cluster.communityId}${cluster.dominantSourceDir ? ` (${cluster.dominantSourceDir})` : ''}`);
+    }
+    if (cluster.keySymbols.length > 0) {
+        lines.push(`*Key symbols*: ${cluster.keySymbols.map((s) => `\`${s}\``).join(', ')}`);
+    }
+    lines.push('');
+    lines.push((0, format_1.markdownTable)(['File'], cluster.files.slice(0, 12).map((f) => ({ File: f }))));
+    if (cluster.files.length > 12) {
+        lines.push(`\n*+ ${cluster.files.length - 12} more file${cluster.files.length - 12 === 1 ? '' : 's'}*`);
+    }
+    return lines.join('\n');
+}
+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);
+}
+//# sourceMappingURL=feature.js.map

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

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

package/dist/explore/cli/file.d.ts

@@ -0,0 +1,12 @@
+/**
+ * `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).
+ */
+import type { Graph } from '../types';
+import type { ExploreCliValues } from '../../explore-cli';
+export declare function runFile(graph: Graph, positionals: ReadonlyArray<string>, values: ExploreCliValues, cwd: string): void;
+//# sourceMappingURL=file.d.ts.map

package/dist/explore/cli/file.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file.d.ts","sourceRoot":"","sources":["../../../src/explore/cli/file.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAYH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,UAAU,CAAC;AACtC,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAE1D,wBAAgB,OAAO,CACrB,KAAK,EAAE,KAAK,EACZ,WAAW,EAAE,aAAa,CAAC,MAAM,CAAC,EAClC,MAAM,EAAE,gBAAgB,EACxB,GAAG,EAAE,MAAM,GACV,IAAI,CAqHN"}

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