@vyuhlabs/dxkit 2.6.0 → 2.7.0

package/dist/explore/cli/api-surface.d.ts

@@ -0,0 +1,12 @@
+/**
+ * `vyuh-dxkit explore api-surface` — exported symbols with no
+ * internal callers (likely public API or CLI entry points).
+ *
+ * Reads per-pack exportDetection reliability from the canonical
+ * registry helper. Packs declared 'unreliable' (today: ruby) are
+ * excluded with an explanatory note.
+ */
+import type { Graph } from '../types';
+import type { ExploreCliValues } from '../../explore-cli';
+export declare function runApiSurface(graph: Graph, _positionals: ReadonlyArray<string>, values: ExploreCliValues): void;
+//# sourceMappingURL=api-surface.d.ts.map

package/dist/explore/cli/api-surface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-surface.d.ts","sourceRoot":"","sources":["../../../src/explore/cli/api-surface.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAYH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,UAAU,CAAC;AACtC,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAI1D,wBAAgB,aAAa,CAC3B,KAAK,EAAE,KAAK,EACZ,YAAY,EAAE,aAAa,CAAC,MAAM,CAAC,EACnC,MAAM,EAAE,gBAAgB,GACvB,IAAI,CAuDN"}

package/dist/explore/cli/api-surface.js

@@ -0,0 +1,57 @@
+"use strict";
+/**
+ * `vyuh-dxkit explore api-surface` — exported symbols with no
+ * internal callers (likely public API or CLI entry points).
+ *
+ * Reads per-pack exportDetection reliability from the canonical
+ * registry helper. Packs declared 'unreliable' (today: ruby) are
+ * excluded with an explanatory note.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runApiSurface = runApiSurface;
+const languages_1 = require("../../languages");
+const queries_1 = require("../queries");
+const format_1 = require("../format");
+const DEFAULT_LIMIT = 25;
+function runApiSurface(graph, _positionals, values) {
+    const limit = parseLimit(values.limit, DEFAULT_LIMIT);
+    const declarations = (0, languages_1.allExportDetectionDeclarations)();
+    const unreliablePacks = declarations
+        .filter((d) => d.reliability === 'unreliable')
+        .map((d) => ({ pack: d.pack, strategy: d.strategy }));
+    const packsExcluded = unreliablePacks.map((u) => u.pack);
+    const results = (0, queries_1.apiSurfaceQuery)(graph, packsExcluded, limit);
+    if (values.json) {
+        (0, format_1.printJson)((0, format_1.envelope)('explore.api-surface', { limit, excluded: unreliablePacks }, graph, results));
+        return;
+    }
+    const sections = [];
+    sections.push((0, format_1.markdownHeader)('API surface', 'exported symbols with no internal callers', graph));
+    if (unreliablePacks.length > 0) {
+        sections.push(`*Excluded packs* (export detection unreliable): ` +
+            unreliablePacks.map((u) => `**${u.pack}** (${u.strategy})`).join('; '));
+    }
+    if (results.length === 0) {
+        sections.push('No exported symbols without internal callers found. Either the codebase has no public API surface graphify could detect, or every exported symbol has at least one internal caller.');
+        (0, format_1.printMarkdown)(...sections);
+        return;
+    }
+    sections.push((0, format_1.markdownTable)(['Path', 'Symbol', 'Kind', 'Pack'], results.map((r) => ({
+        Path: r.line ? `${r.sourceFile}:${r.line}` : r.sourceFile,
+        Symbol: r.symbol,
+        Kind: r.kind,
+        Pack: r.pack,
+    }))));
+    sections.push('These are likely public API or CLI entry points. Verify before deleting — a missing internal caller can mean "external consumer only" rather than "dead code." Future releases will add a dedicated dead-code analyzer with stronger heuristics.');
+    sections.push((0, format_1.markdownFooter)('Drill into one: `vyuh-dxkit explore file <path>`.'));
+    (0, format_1.printMarkdown)(...sections);
+}
+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=api-surface.js.map

package/dist/explore/cli/api-surface.js.map

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

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

@@ -0,0 +1,10 @@
+/**
+ * `vyuh-dxkit explore communities` — natural-module summary.
+ *
+ * Pure pipeline: parse args → call communitiesQuery → format output.
+ * Per CLAUDE.md Rule 12: graph traversal flows through queries.ts.
+ */
+import type { Graph } from '../types';
+import type { ExploreCliValues } from '../../explore-cli';
+export declare function runCommunities(graph: Graph, _positionals: ReadonlyArray<string>, values: ExploreCliValues): void;
+//# sourceMappingURL=communities.d.ts.map

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

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

package/dist/explore/cli/communities.js

@@ -0,0 +1,47 @@
+"use strict";
+/**
+ * `vyuh-dxkit explore communities` — natural-module summary.
+ *
+ * Pure pipeline: parse args → call communitiesQuery → format output.
+ * Per CLAUDE.md Rule 12: graph traversal flows through queries.ts.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runCommunities = runCommunities;
+const queries_1 = require("../queries");
+const format_1 = require("../format");
+const DEFAULT_LIMIT = 8;
+function runCommunities(graph, _positionals, values) {
+    const limit = parseLimit(values.limit, DEFAULT_LIMIT);
+    const results = (0, queries_1.communitiesQuery)(graph, limit);
+    if (values.json) {
+        (0, format_1.printJson)((0, format_1.envelope)('explore.communities', { limit }, graph, results));
+        return;
+    }
+    if (results.length === 0) {
+        (0, format_1.printMarkdown)((0, format_1.markdownHeader)('Communities', 'natural modules in this repo', graph), 'No communities found in the graph. Either the repo is too small for Louvain clustering to find structure, or the graph artifact is empty.');
+        return;
+    }
+    const rows = results.map((r) => ({
+        ID: r.id,
+        Dir: r.dominantSourceDir || '—',
+        Pack: r.dominantPack || '—',
+        Nodes: r.nodeCount,
+        Cohesion: r.cohesion.toFixed(2),
+        'Top hot files': r.topHotFiles.map((f) => basename(f)).join(', ') || '—',
+    }));
+    const headers = ['ID', 'Dir', 'Pack', 'Nodes', 'Cohesion', 'Top hot files'];
+    (0, format_1.printMarkdown)((0, format_1.markdownHeader)('Communities', 'natural modules in this repo', graph), (0, format_1.markdownTable)(headers, rows), (0, format_1.markdownFooter)("Drill into a community's central file: `vyuh-dxkit explore file <path>`."));
+}
+function basename(p) {
+    const i = p.lastIndexOf('/');
+    return i >= 0 ? p.slice(i + 1) : p;
+}
+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=communities.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"communities.js","sourceRoot":"","sources":["../../../src/explore/cli/communities.ts"],"names":[],"mappings":";AAAA;;;;;GAKG;;AAgBH,wCAoCC;AAlDD,wCAA8C;AAC9C,sCAOmB;AAInB,MAAM,aAAa,GAAG,CAAC,CAAC;AAExB,SAAgB,cAAc,CAC5B,KAAY,EACZ,YAAmC,EACnC,MAAwB;IAExB,MAAM,KAAK,GAAG,UAAU,CAAC,MAAM,CAAC,KAAK,EAAE,aAAa,CAAC,CAAC;IACtD,MAAM,OAAO,GAAG,IAAA,0BAAgB,EAAC,KAAK,EAAE,KAAK,CAAC,CAAC;IAE/C,IAAI,MAAM,CAAC,IAAI,EAAE,CAAC;QAChB,IAAA,kBAAS,EAAC,IAAA,iBAAQ,EAAC,qBAAqB,EAAE,EAAE,KAAK,EAAE,EAAE,KAAK,EAAE,OAAO,CAAC,CAAC,CAAC;QACtE,OAAO;IACT,CAAC;IAED,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACzB,IAAA,sBAAa,EACX,IAAA,uBAAc,EAAC,aAAa,EAAE,8BAA8B,EAAE,KAAK,CAAC,EACpE,2IAA2I,CAC5I,CAAC;QACF,OAAO;IACT,CAAC;IAED,MAAM,IAAI,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;QAC/B,EAAE,EAAE,CAAC,CAAC,EAAE;QACR,GAAG,EAAE,CAAC,CAAC,iBAAiB,IAAI,GAAG;QAC/B,IAAI,EAAE,CAAC,CAAC,YAAY,IAAI,GAAG;QAC3B,KAAK,EAAE,CAAC,CAAC,SAAS;QAClB,QAAQ,EAAE,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC;QAC/B,eAAe,EAAE,CAAC,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,GAAG;KACzE,CAAC,CAAC,CAAC;IACJ,MAAM,OAAO,GAAG,CAAC,IAAI,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,UAAU,EAAE,eAAe,CAAU,CAAC;IAErF,IAAA,sBAAa,EACX,IAAA,uBAAc,EAAC,aAAa,EAAE,8BAA8B,EAAE,KAAK,CAAC,EACpE,IAAA,sBAAa,EAAC,OAAO,EAAE,IAAI,CAAC,EAC5B,IAAA,uBAAc,EAAC,0EAA0E,CAAC,CAC3F,CAAC;AACJ,CAAC;AAED,SAAS,QAAQ,CAAC,CAAS;IACzB,MAAM,CAAC,GAAG,CAAC,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;IAC7B,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AACrC,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;AAC3B,CAAC"}

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

@@ -0,0 +1,16 @@
+/**
+ * `vyuh-dxkit context <query>` — the token-reduction surface. Returns
+ * a slim, relevance-ranked structural slice for a query instead of the
+ * full-file dump an agent would otherwise grep + read. Same payload
+ * serves the human at a terminal and the LLM via the PreToolUse hook.
+ *
+ * Output is lean markdown by default (LLMs parse it natively + it's
+ * more token-efficient than JSON); `--json` emits the stable envelope
+ * for pipelines. The content is anchor-first ("start here"), grouped
+ * by community for orientation, framed by blast radius, and honest
+ * about truncation + same-name conflation.
+ */
+import type { Graph } from '../types';
+import type { ExploreCliValues } from '../../explore-cli';
+export declare function runContext(graph: Graph, positionals: ReadonlyArray<string>, values: ExploreCliValues): void;
+//# sourceMappingURL=context.d.ts.map

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

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

package/dist/explore/cli/context.js

@@ -0,0 +1,118 @@
+"use strict";
+/**
+ * `vyuh-dxkit context <query>` — the token-reduction surface. Returns
+ * a slim, relevance-ranked structural slice for a query instead of the
+ * full-file dump an agent would otherwise grep + read. Same payload
+ * serves the human at a terminal and the LLM via the PreToolUse hook.
+ *
+ * Output is lean markdown by default (LLMs parse it natively + it's
+ * more token-efficient than JSON); `--json` emits the stable envelope
+ * for pipelines. The content is anchor-first ("start here"), grouped
+ * by community for orientation, framed by blast radius, and honest
+ * about truncation + same-name conflation.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runContext = runContext;
+const queries_1 = require("../queries");
+const format_1 = require("../format");
+const DEFAULT_BUDGET = 2000;
+function runContext(graph, positionals, values) {
+    const keyword = positionals[0];
+    if (!keyword) {
+        process.stderr.write('Usage: vyuh-dxkit context <query> [--substring] [--budget 2000] [--depth N] [--json]\n');
+        process.exit(1);
+    }
+    const budget = parsePositiveInt(values.budget, DEFAULT_BUDGET);
+    const depth = values.depth !== undefined ? parsePositiveInt(values.depth, Infinity) : undefined;
+    const substring = !!values.substring;
+    const result = (0, queries_1.contextQuery)(graph, keyword, { budget, substring, maxDepth: depth });
+    if (values.json) {
+        (0, format_1.printJson)((0, format_1.envelope)('context', { query: keyword, budget, substring, depth: depth ?? null }, graph, result));
+        return;
+    }
+    const sections = [(0, format_1.markdownHeader)('Context', `\`${keyword}\``, graph)];
+    if (!result.matched) {
+        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 symbols matched \`${keyword}\`. Did you mean:\n\n${lines}\n\nRerun with \`--substring\` to expand from these, or pick one above.`);
+        }
+        else {
+            sections.push(`No symbols matched \`${keyword}\` (no close alternatives either). Try a different keyword or \`--substring\` for broader matching.`);
+        }
+        (0, format_1.printMarkdown)(...sections);
+        return;
+    }
+    // Anchor — the "start here" line.
+    if (result.anchor) {
+        const a = result.anchor;
+        const where = a.line ? `${a.sourceFile}:${a.line}` : a.sourceFile;
+        sections.push(`**Start here:** \`${a.symbol}\` — \`${where}\` (called from ${a.calledFrom} place${a.calledFrom === 1 ? '' : 's'}).`);
+    }
+    // Blast radius — change-impact framing.
+    const { callers, callerFiles } = result.blastRadius;
+    if (callers > 0) {
+        sections.push(`**Blast radius:** changing the matched symbol${result.selection.some((s) => s.hop === 0) ? '(s)' : ''} touches ${callers} caller${callers === 1 ? '' : 's'} across ${callerFiles} file${callerFiles === 1 ? '' : 's'}.`);
+    }
+    else {
+        sections.push('**Blast radius:** no internal callers — likely an entry point or public API.');
+    }
+    // Community-grouped symbol listing (orientation). Each group is
+    // ranked seeds-first then by call in-degree, and capped for
+    // readability — the markdown is a scannable map, not an exhaustive
+    // dump. The full selection is always available via `--json`.
+    const PER_COMMUNITY_CAP = 12;
+    for (const group of result.byCommunity) {
+        const heading = group.communityId !== undefined
+            ? `### ${group.role} (community ${group.communityId})`
+            : `### ${group.role}`;
+        const lines = [heading];
+        const groupSel = dedupeBySymbol(result.selection
+            .filter((s) => group.symbols.includes(s.symbol))
+            .sort((a, b) => a.hop - b.hop || b.callsIn - a.callsIn));
+        for (const s of groupSel.slice(0, PER_COMMUNITY_CAP)) {
+            const where = s.line ? `${s.sourceFile}:${s.line}` : s.sourceFile;
+            const seed = s.hop === 0 ? ' _[seed]_' : '';
+            lines.push(`- \`${s.symbol}\` — \`${where}\` (${s.callsIn} in / ${s.callsOut} out)${seed}`);
+        }
+        if (groupSel.length > PER_COMMUNITY_CAP) {
+            lines.push(`- _+${groupSel.length - PER_COMMUNITY_CAP} more in this cluster_`);
+        }
+        sections.push(lines.join('\n'));
+    }
+    // Honest truncation footer.
+    if (result.truncated) {
+        sections.push(`_+${result.omittedCount} more symbol${result.omittedCount === 1 ? '' : 's'} omitted to fit the ${result.budget}-token budget — narrow the query or raise \`--budget\`._`);
+    }
+    // Same-name conflation caveat — only when there's any risk worth noting.
+    sections.push('_Note: graphify conflates same-name symbols across files, so call counts are best-effort._');
+    (0, format_1.printMarkdown)(...sections);
+}
+/**
+ * Collapse repeated symbol names within a community group. The BFS can
+ * surface the same stripped label from two different files (graphify's
+ * same-name conflation); the listing keeps the first (lowest-hop)
+ * occurrence so the output stays scannable.
+ */
+function dedupeBySymbol(nodes) {
+    const seen = new Set();
+    const out = [];
+    for (const n of nodes) {
+        const key = `${n.symbol}\x00${n.sourceFile}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        out.push(n);
+    }
+    return out;
+}
+function parsePositiveInt(raw, defaultValue) {
+    if (!raw)
+        return defaultValue;
+    const n = parseInt(raw, 10);
+    if (isNaN(n) || n < 1)
+        return defaultValue;
+    return n;
+}
+//# sourceMappingURL=context.js.map

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

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

package/dist/explore/cli/entry-points.d.ts

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

package/dist/explore/cli/entry-points.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"entry-points.d.ts","sourceRoot":"","sources":["../../../src/explore/cli/entry-points.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAaH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,UAAU,CAAC;AACtC,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAI1D,wBAAgB,cAAc,CAC5B,KAAK,EAAE,KAAK,EACZ,YAAY,EAAE,aAAa,CAAC,MAAM,CAAC,EACnC,MAAM,EAAE,gBAAgB,EACxB,GAAG,EAAE,MAAM,GACV,IAAI,CAgFN"}

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":";AAAA;;;;;;;GAOG;;AAkBH,wCAqFC;AArGD,yCAAsC;AACtC,+CAA8F;AAC9F,wCAAqE;AACrE,sCAOmB;AAInB,MAAM,aAAa,GAAG,EAAE,CAAC;AAEzB,SAAgB,cAAc,CAC5B,KAAY,EACZ,YAAmC,EACnC,MAAwB,EACxB,GAAW;IAEX,MAAM,KAAK,GAAG,UAAU,CAAC,MAAM,CAAC,KAAK,EAAE,aAAa,CAAC,CAAC;IAEtD,MAAM,KAAK,GAAG,IAAA,eAAM,EAAC,GAAG,CAAC,CAAC;IAC1B,MAAM,YAAY,GAAG,IAAA,oCAAwB,EAAC,KAAK,CAAC,SAAS,CAAC,CAAC;IAC/D,MAAM,UAAU,GAAG,IAAA,yBAAa,EAAC,KAAK,CAAC,SAAS,CAAC,CAAC;IAClD,MAAM,UAAU,GAAG,IAAA,8BAAkB,EAAC,KAAK,CAAC,SAAS,CAAC,CAAC;IAEvD,MAAM,OAAO,GAAG,IAAA,0BAAgB,EAAC,KAAK,EAAE,YAAY,EAAE,UAAU,EAAE,KAAK,CAAC,CAAC;IAEzE,IAAI,MAAM,CAAC,IAAI,EAAE,CAAC;QAChB,IAAA,kBAAS,EACP,IAAA,iBAAQ,EACN,sBAAsB,EACtB,EAAE,KAAK,EAAE,YAAY,EAAE,UAAU,EAAE,KAAK,EAAE,KAAK,CAAC,IAAI,CAAC,KAAK,EAAE,EAC5D,KAAK,EACL,OAAO,CACR,CACF,CAAC;QACF,OAAO;IACT,CAAC;IAED,IAAI,YAAY,CAAC,MAAM,KAAK,CAAC,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACzD,IAAA,sBAAa,EACX,IAAA,uBAAc,EAAC,cAAc,EAAE,yBAAyB,EAAE,KAAK,CAAC,EAChE,0DAA0D,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,eAAe,QAAQ;YAC9G,8NAA8N,CACjO,CAAC;QACF,OAAO;IACT,CAAC;IAED,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACzB,IAAA,sBAAa,EACX,IAAA,uBAAc,EAAC,cAAc,EAAE,yBAAyB,EAAE,KAAK,CAAC,EAChE,qEAAqE;YACnE,mBAAmB,CAAC,GAAG,YAAY,EAAE,GAAG,UAAU,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM;YAC3F,2GAA2G,CAC9G,CAAC;QACF,OAAO;IACT,CAAC;IAED,qDAAqD;IACrD,MAAM,OAAO,GAAG,IAAI,GAAG,EAA8B,CAAC;IACtD,KAAK,MAAM,CAAC,IAAI,OAAO,EAAE,CAAC;QACxB,MAAM,GAAG,GAAG,CAAC,CAAC,aAAa,CAAC;QAC5B,MAAM,IAAI,GAAG,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC;QACpC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QACb,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;IACzB,CAAC;IAED,MAAM,QAAQ,GAAa,EAAE,CAAC;IAC9B,QAAQ,CAAC,IAAI,CAAC,IAAA,uBAAc,EAAC,cAAc,EAAE,yBAAyB,EAAE,KAAK,CAAC,CAAC,CAAC;IAEhF,0DAA0D;IAC1D,MAAM,SAAS,GAAa,EAAE,CAAC;IAC/B,IAAI,UAAU,EAAE,UAAU;QAAE,SAAS,CAAC,IAAI,CAAC,kBAAkB,UAAU,CAAC,UAAU,IAAI,CAAC,CAAC;IACxF,IAAI,UAAU,EAAE,MAAM;QAAE,SAAS,CAAC,IAAI,CAAC,cAAc,UAAU,CAAC,MAAM,IAAI,CAAC,CAAC;IAC5E,IAAI,UAAU,EAAE,MAAM;QAAE,SAAS,CAAC,IAAI,CAAC,cAAc,UAAU,CAAC,MAAM,IAAI,CAAC,CAAC;IAC5E,IAAI,SAAS,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACzB,QAAQ,CAAC,IAAI,CAAC,sBAAsB,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAC/D,CAAC;IAED,KAAK,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,OAAO,EAAE,CAAC;QACnC,QAAQ,CAAC,IAAI,CAAC,OAAO,UAAU,CAAC,IAAI,CAAC,KAAK,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC;QAC1D,QAAQ,CAAC,IAAI,CACX,IAAA,sBAAa,EACX,CAAC,MAAM,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,CAAU,EAChD,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;YACf,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,UAAU,IAAI,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,UAAU;YACzD,MAAM,EAAE,CAAC,CAAC,MAAM;YAChB,WAAW,EAAE,CAAC,CAAC,QAAQ;YACvB,IAAI,EAAE,CAAC,CAAC,IAAI;SACb,CAAC,CAAC,CACJ,CACF,CAAC;IACJ,CAAC;IAED,QAAQ,CAAC,IAAI,CAAC,IAAA,uBAAc,EAAC,mDAAmD,CAAC,CAAC,CAAC;IAEnF,IAAA,sBAAa,EAAC,GAAG,QAAQ,CAAC,CAAC;AAC7B,CAAC;AAED,SAAS,UAAU,CAAC,CAAS;IAC3B,IAAI,CAAC,CAAC;QAAE,OAAO,CAAC,CAAC;IACjB,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;AACzC,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;AAC3B,CAAC"}

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"}