@vyuhlabs/dxkit 2.6.0 → 2.7.1

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

package/dist/explore/format.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Shared output helpers for the explore CLI subcommands. Pure
+ * formatters — JSON envelope shape + markdown table builders — so
+ * each subcommand handler stays a thin pipeline (parse args → call
+ * queries → format output).
+ *
+ * Per the Sprint 0 design (`tmp/2.7-explore-cli-design.md`):
+ *   - JSON mode emits a stable envelope: command / args / meta / results
+ *   - Markdown mode emits header → meta line → result block → footer hint
+ *   - Adding fields later is additive; never mutate existing field
+ *     names within v1
+ */
+import type { Graph } from './types';
+/**
+ * Stable JSON envelope every `--json` mode subcommand emits. Skills
+ * and scripts consume `results` directly; `meta` carries the artifact
+ * provenance so consumers can detect a stale graph + decide whether
+ * to suggest `--refresh`.
+ */
+export interface ExploreEnvelope<T> {
+    command: string;
+    args: Record<string, unknown>;
+    meta: {
+        schemaVersion: number;
+        graphGeneratedAt: string;
+        truncated: boolean;
+    };
+    results: T;
+}
+/**
+ * Build the JSON envelope from a query result + the graph metadata.
+ * Pure function — no I/O, no side effects. Subcommands call this in
+ * `--json` mode and print the result via `JSON.stringify`.
+ */
+export declare function envelope<T>(command: string, args: Record<string, unknown>, graph: Graph, results: T): ExploreEnvelope<T>;
+/**
+ * Build the standard markdown header that every subcommand emits.
+ * Includes the meta line (file count + node count + generation
+ * timestamp) so the reader knows what artifact they're looking at,
+ * plus a truncation note when applicable.
+ */
+export declare function markdownHeader(title: string, framing: string, graph: Graph): string;
+/**
+ * Build a markdown table from a row set. `headers` defines the
+ * column order; `rows` is an array of records keyed by the same
+ * header strings. Missing values render as empty strings.
+ */
+export declare function markdownTable<R extends Record<string, string | number>>(headers: ReadonlyArray<keyof R & string>, rows: ReadonlyArray<R>): string;
+/**
+ * Build the standard footer hint pointing at the natural next
+ * subcommand. Optional; subcommands omit when no clear next step.
+ */
+export declare function markdownFooter(hint: string): string;
+/**
+ * Print a JSON envelope to stdout. Output is single-line (no
+ * pretty-print) so it stays pipe-friendly for `jq` consumers.
+ */
+export declare function printJson<T>(env: ExploreEnvelope<T>): void;
+/**
+ * Print markdown sections to stdout, joined by a blank line. Each
+ * section is a multi-line string built by the helpers above.
+ */
+export declare function printMarkdown(...sections: string[]): void;
+//# sourceMappingURL=format.d.ts.map

package/dist/explore/format.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"format.d.ts","sourceRoot":"","sources":["../../src/explore/format.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAErC;;;;;GAKG;AACH,MAAM,WAAW,eAAe,CAAC,CAAC;IAChC,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9B,IAAI,EAAE;QACJ,aAAa,EAAE,MAAM,CAAC;QACtB,gBAAgB,EAAE,MAAM,CAAC;QACzB,SAAS,EAAE,OAAO,CAAC;KACpB,CAAC;IACF,OAAO,EAAE,CAAC,CAAC;CACZ;AAED;;;;GAIG;AACH,wBAAgB,QAAQ,CAAC,CAAC,EACxB,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,KAAK,EAAE,KAAK,EACZ,OAAO,EAAE,CAAC,GACT,eAAe,CAAC,CAAC,CAAC,CAWpB;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,GAAG,MAAM,CAanF;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,EACrE,OAAO,EAAE,aAAa,CAAC,MAAM,CAAC,GAAG,MAAM,CAAC,EACxC,IAAI,EAAE,aAAa,CAAC,CAAC,CAAC,GACrB,MAAM,CAaR;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEnD;AAED;;;GAGG;AACH,wBAAgB,SAAS,CAAC,CAAC,EAAE,GAAG,EAAE,eAAe,CAAC,CAAC,CAAC,GAAG,IAAI,CAE1D;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,GAAG,QAAQ,EAAE,MAAM,EAAE,GAAG,IAAI,CAEzD"}

package/dist/explore/format.js

@@ -0,0 +1,99 @@
+"use strict";
+/**
+ * Shared output helpers for the explore CLI subcommands. Pure
+ * formatters — JSON envelope shape + markdown table builders — so
+ * each subcommand handler stays a thin pipeline (parse args → call
+ * queries → format output).
+ *
+ * Per the Sprint 0 design (`tmp/2.7-explore-cli-design.md`):
+ *   - JSON mode emits a stable envelope: command / args / meta / results
+ *   - Markdown mode emits header → meta line → result block → footer hint
+ *   - Adding fields later is additive; never mutate existing field
+ *     names within v1
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.envelope = envelope;
+exports.markdownHeader = markdownHeader;
+exports.markdownTable = markdownTable;
+exports.markdownFooter = markdownFooter;
+exports.printJson = printJson;
+exports.printMarkdown = printMarkdown;
+/**
+ * Build the JSON envelope from a query result + the graph metadata.
+ * Pure function — no I/O, no side effects. Subcommands call this in
+ * `--json` mode and print the result via `JSON.stringify`.
+ */
+function envelope(command, args, graph, results) {
+    return {
+        command,
+        args,
+        meta: {
+            schemaVersion: graph.schemaVersion,
+            graphGeneratedAt: graph.meta.generatedAt,
+            truncated: graph.meta.truncated,
+        },
+        results,
+    };
+}
+/**
+ * Build the standard markdown header that every subcommand emits.
+ * Includes the meta line (file count + node count + generation
+ * timestamp) so the reader knows what artifact they're looking at,
+ * plus a truncation note when applicable.
+ */
+function markdownHeader(title, framing, graph) {
+    const m = graph.meta;
+    const dateOnly = m.generatedAt.slice(0, 10);
+    const lines = [
+        `## ${title} — ${framing}`,
+        '',
+        `From .dxkit/reports/graph.json (generated ${dateOnly}, ${m.sourceFilesInGraph} source files, ${graph.nodes.length} nodes).`,
+    ];
+    if (m.truncated) {
+        lines.push('');
+        lines.push(`> ⚠ Graph is truncated: ${m.truncatedReason}. Results may be incomplete.`);
+    }
+    return lines.join('\n');
+}
+/**
+ * Build a markdown table from a row set. `headers` defines the
+ * column order; `rows` is an array of records keyed by the same
+ * header strings. Missing values render as empty strings.
+ */
+function markdownTable(headers, rows) {
+    if (rows.length === 0)
+        return '';
+    const lines = [];
+    lines.push('| ' + headers.join(' | ') + ' |');
+    lines.push('|' + headers.map(() => '---').join('|') + '|');
+    for (const row of rows) {
+        const cells = headers.map((h) => {
+            const v = row[h];
+            return v === undefined || v === null ? '' : String(v);
+        });
+        lines.push('| ' + cells.join(' | ') + ' |');
+    }
+    return lines.join('\n');
+}
+/**
+ * Build the standard footer hint pointing at the natural next
+ * subcommand. Optional; subcommands omit when no clear next step.
+ */
+function markdownFooter(hint) {
+    return `\n${hint}`;
+}
+/**
+ * Print a JSON envelope to stdout. Output is single-line (no
+ * pretty-print) so it stays pipe-friendly for `jq` consumers.
+ */
+function printJson(env) {
+    process.stdout.write(JSON.stringify(env) + '\n');
+}
+/**
+ * Print markdown sections to stdout, joined by a blank line. Each
+ * section is a multi-line string built by the helpers above.
+ */
+function printMarkdown(...sections) {
+    process.stdout.write(sections.filter((s) => s && s.length > 0).join('\n\n') + '\n');
+}
+//# sourceMappingURL=format.js.map

package/dist/explore/format.js.map

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

package/dist/explore/load.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Canonical graph loader. Per CLAUDE.md Rule 12, every consumer of
+ * `.dxkit/reports/graph.json` reads via `loadGraph(cwd)` — never
+ * `JSON.parse` directly. Arch-check enforces; this is the only file
+ * that may parse the artifact.
+ *
+ * Throws typed errors so callers can react precisely:
+ *   - GraphNotFoundError      → file doesn't exist (suggest --refresh)
+ *   - GraphSchemaVersionError → wire-format newer than the loader knows
+ *   - GraphCorruptError       → missing/malformed required field
+ */
+import { GRAPH_REPORT_PATH, type Graph } from './types';
+export { GRAPH_REPORT_PATH };
+export declare class GraphNotFoundError extends Error {
+    readonly absPath: string;
+    constructor(absPath: string);
+}
+export declare class GraphSchemaVersionError extends Error {
+    readonly absPath: string;
+    readonly found: unknown;
+    readonly expected: number;
+    constructor(absPath: string, found: unknown, expected: number);
+}
+export declare class GraphCorruptError extends Error {
+    readonly absPath: string;
+    readonly detail: string;
+    constructor(absPath: string, detail: string);
+}
+/**
+ * Read + validate + index the graph artifact. The returned `Graph`
+ * carries convenience indices (`nodeById`, `edgesFromNode`, ...)
+ * built once at load time; queries in `./queries.ts` read from these
+ * maps for O(1) traversal rather than repeatedly scanning the arrays.
+ *
+ * Validation is intentionally lightweight — top-level shape + required
+ * fields per node/edge. Deep schema validation (every optional field's
+ * types, referential integrity of every edge endpoint) would catch
+ * more but cost more on every load; instead we trust the producer and
+ * surface unexpected shapes as runtime errors at the query layer.
+ */
+export declare function loadGraph(cwd: string): Graph;
+/**
+ * Fail-open variant of {@link loadGraph}: returns undefined on ANY
+ * error (missing file, parse failure, schema mismatch) instead of
+ * throwing. For additive, never-block consumers — the PreToolUse
+ * context hook and the finding-enrichment pass — where a missing or
+ * stale graph must degrade to "no context", never an error.
+ */
+export declare function tryLoadGraph(cwd: string): Graph | undefined;
+//# sourceMappingURL=load.d.ts.map

package/dist/explore/load.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"load.d.ts","sourceRoot":"","sources":["../../src/explore/load.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAIH,OAAO,EACL,iBAAiB,EAGjB,KAAK,KAAK,EAIX,MAAM,SAAS,CAAC;AAIjB,OAAO,EAAE,iBAAiB,EAAE,CAAC;AAE7B,qBAAa,kBAAmB,SAAQ,KAAK;aACf,OAAO,EAAE,MAAM;gBAAf,OAAO,EAAE,MAAM;CAM5C;AAED,qBAAa,uBAAwB,SAAQ,KAAK;aAE9B,OAAO,EAAE,MAAM;aACf,KAAK,EAAE,OAAO;aACd,QAAQ,EAAE,MAAM;gBAFhB,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,OAAO,EACd,QAAQ,EAAE,MAAM;CAOnC;AAED,qBAAa,iBAAkB,SAAQ,KAAK;aAExB,OAAO,EAAE,MAAM;aACf,MAAM,EAAE,MAAM;gBADd,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM;CAKjC;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,KAAK,CAa5C;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,KAAK,GAAG,SAAS,CAM3D"}

package/dist/explore/load.js

@@ -0,0 +1,197 @@
+"use strict";
+/**
+ * Canonical graph loader. Per CLAUDE.md Rule 12, every consumer of
+ * `.dxkit/reports/graph.json` reads via `loadGraph(cwd)` — never
+ * `JSON.parse` directly. Arch-check enforces; this is the only file
+ * that may parse the artifact.
+ *
+ * Throws typed errors so callers can react precisely:
+ *   - GraphNotFoundError      → file doesn't exist (suggest --refresh)
+ *   - GraphSchemaVersionError → wire-format newer than the loader knows
+ *   - GraphCorruptError       → missing/malformed required field
+ */
+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.GraphCorruptError = exports.GraphSchemaVersionError = exports.GraphNotFoundError = exports.GRAPH_REPORT_PATH = void 0;
+exports.loadGraph = loadGraph;
+exports.tryLoadGraph = tryLoadGraph;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const types_1 = require("./types");
+Object.defineProperty(exports, "GRAPH_REPORT_PATH", { enumerable: true, get: function () { return types_1.GRAPH_REPORT_PATH; } });
+class GraphNotFoundError extends Error {
+    absPath;
+    constructor(absPath) {
+        super(`No graph.json at ${absPath}. Run \`vyuh-dxkit health\` or pass \`--refresh\` to regenerate.`);
+        this.absPath = absPath;
+        this.name = 'GraphNotFoundError';
+    }
+}
+exports.GraphNotFoundError = GraphNotFoundError;
+class GraphSchemaVersionError extends Error {
+    absPath;
+    found;
+    expected;
+    constructor(absPath, found, expected) {
+        super(`graph.json at ${absPath} declares schemaVersion=${String(found)}; this dxkit reads schemaVersion=${expected}. Upgrade dxkit (\`npm install -g @vyuhlabs/dxkit@latest\`) to read newer artifacts.`);
+        this.absPath = absPath;
+        this.found = found;
+        this.expected = expected;
+        this.name = 'GraphSchemaVersionError';
+    }
+}
+exports.GraphSchemaVersionError = GraphSchemaVersionError;
+class GraphCorruptError extends Error {
+    absPath;
+    detail;
+    constructor(absPath, detail) {
+        super(`graph.json at ${absPath} is malformed: ${detail}. Regenerate with \`--refresh\`.`);
+        this.absPath = absPath;
+        this.detail = detail;
+        this.name = 'GraphCorruptError';
+    }
+}
+exports.GraphCorruptError = GraphCorruptError;
+/**
+ * Read + validate + index the graph artifact. The returned `Graph`
+ * carries convenience indices (`nodeById`, `edgesFromNode`, ...)
+ * built once at load time; queries in `./queries.ts` read from these
+ * maps for O(1) traversal rather than repeatedly scanning the arrays.
+ *
+ * Validation is intentionally lightweight — top-level shape + required
+ * fields per node/edge. Deep schema validation (every optional field's
+ * types, referential integrity of every edge endpoint) would catch
+ * more but cost more on every load; instead we trust the producer and
+ * surface unexpected shapes as runtime errors at the query layer.
+ */
+function loadGraph(cwd) {
+    const absPath = path.join(cwd, types_1.GRAPH_REPORT_PATH);
+    if (!fs.existsSync(absPath)) {
+        throw new GraphNotFoundError(absPath);
+    }
+    let raw;
+    try {
+        raw = JSON.parse(fs.readFileSync(absPath, 'utf-8'));
+    }
+    catch (err) {
+        throw new GraphCorruptError(absPath, err instanceof Error ? err.message : 'JSON parse failed');
+    }
+    const json = validateAndUpgrade(absPath, raw);
+    return indexGraph(json);
+}
+/**
+ * Fail-open variant of {@link loadGraph}: returns undefined on ANY
+ * error (missing file, parse failure, schema mismatch) instead of
+ * throwing. For additive, never-block consumers — the PreToolUse
+ * context hook and the finding-enrichment pass — where a missing or
+ * stale graph must degrade to "no context", never an error.
+ */
+function tryLoadGraph(cwd) {
+    try {
+        return loadGraph(cwd);
+    }
+    catch {
+        return undefined;
+    }
+}
+function validateAndUpgrade(absPath, raw) {
+    if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
+        throw new GraphCorruptError(absPath, 'top-level value is not an object');
+    }
+    const obj = raw;
+    const v = obj.schemaVersion;
+    if (typeof v !== 'number') {
+        throw new GraphCorruptError(absPath, 'schemaVersion is missing or not a number');
+    }
+    if (v > types_1.GRAPH_SCHEMA_VERSION) {
+        throw new GraphSchemaVersionError(absPath, v, types_1.GRAPH_SCHEMA_VERSION);
+    }
+    // Future migrations: switch on v here when v2+ lands. Today v === 1
+    // is the only supported version; no migration needed.
+    for (const key of ['meta', 'nodes', 'edges', 'communities', 'symbolIndex']) {
+        if (!(key in obj)) {
+            throw new GraphCorruptError(absPath, `missing required top-level field "${key}"`);
+        }
+    }
+    if (!Array.isArray(obj.nodes)) {
+        throw new GraphCorruptError(absPath, '"nodes" is not an array');
+    }
+    if (!Array.isArray(obj.edges)) {
+        throw new GraphCorruptError(absPath, '"edges" is not an array');
+    }
+    if (!Array.isArray(obj.communities)) {
+        throw new GraphCorruptError(absPath, '"communities" is not an array');
+    }
+    // Trust the rest; runtime errors in queries surface deeper issues.
+    return raw;
+}
+function indexGraph(json) {
+    const nodeById = new Map();
+    for (const n of json.nodes)
+        nodeById.set(n.id, n);
+    const edgesFromNode = new Map();
+    const edgesToNode = new Map();
+    for (const e of json.edges) {
+        const fromList = edgesFromNode.get(e.from) ?? [];
+        fromList.push(e);
+        edgesFromNode.set(e.from, fromList);
+        const toList = edgesToNode.get(e.to) ?? [];
+        toList.push(e);
+        edgesToNode.set(e.to, toList);
+    }
+    const nodesByFile = new Map();
+    for (const n of json.nodes) {
+        const list = nodesByFile.get(n.sourceFile) ?? [];
+        list.push(n);
+        nodesByFile.set(n.sourceFile, list);
+    }
+    const communityById = new Map();
+    const communityByNode = new Map();
+    for (const c of json.communities) {
+        communityById.set(c.id, c);
+        for (const nid of c.nodeIds)
+            communityByNode.set(nid, c);
+    }
+    return {
+        ...json,
+        nodeById,
+        edgesFromNode,
+        edgesToNode,
+        nodesByFile,
+        communityById,
+        communityByNode,
+    };
+}
+//# sourceMappingURL=load.js.map

package/dist/explore/load.js.map

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