knodin 0.7.6 → 0.8.2

package/dist/src/visualization.js

@@ -0,0 +1,515 @@
+import { execFileSync } from "node:child_process";
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { compareBytes } from "./compare.js";
+import { layoutGraph } from "./graph-layout.js";
+const DEFAULT_BYTE_BUDGET = 32_768;
+/** Repo scope draws coordinates for many nodes, so it needs a larger default. */
+const DEFAULT_REPO_BYTE_BUDGET = 524_288;
+const MIN_BYTE_BUDGET = 4_096;
+const MAX_BYTE_BUDGET = 2_097_152;
+const MAX_CALL_FLOW_EDGES = 20;
+/** Repo-scope caps. Exceeding either truncates and is reported honestly. */
+const MAX_REPO_NODES = 400;
+const MAX_REPO_EDGES = 900;
+/** Communities requested from `map()` for repo scope; 12 is the call-flow bound. */
+const REPO_COMMUNITY_TOP_N = 60;
+/** Palette for community fills. Fixed order keeps colour assignment stable. */
+const COMMUNITY_COLORS = [
+    "#4c78d8",
+    "#f58518",
+    "#e45756",
+    "#72b7b2",
+    "#54a24b",
+    "#eeca3b",
+    "#b279a2",
+    "#ff9da6",
+    "#9d755d",
+    "#bab0ac",
+];
+function round2(value) {
+    return Math.round(value * 100) / 100;
+}
+function shortLabel(id, granularity) {
+    if (granularity === "symbol")
+        return id;
+    const segments = id.split("/");
+    return segments.length <= 2 ? id : segments.slice(-2).join("/");
+}
+/**
+ * Builds the repo-scope graph from `map()` output.
+ *
+ * Returns pre-cap totals alongside the capped node and edge lists so the
+ * caller can report what was withheld rather than presenting a sample as if it
+ * were the whole graph.
+ */
+function buildRepoGraph(map, graph, granularity) {
+    // Rank so that truncation keeps exact evidence before heuristics.
+    const ranked = [...mergeEdges(graph).values()].sort(compareArtifactEdges);
+    const edges = ranked.slice(0, MAX_REPO_EDGES);
+    const nodes = buildRepoNodes(endpointsOf(edges), granularity, {
+        degreeOf: indexDegrees(map, graph, granularity),
+        communityOf: indexCommunities(map),
+    });
+    // Keep the highest-degree nodes, then drop edges that lost an endpoint.
+    const kept = nodes.slice(0, MAX_REPO_NODES);
+    const keptIds = new Set(kept.map((node) => node.id));
+    return {
+        nodes: kept,
+        edges: edges.filter((edge) => keptIds.has(edge.from) && keptIds.has(edge.to)),
+        nodeTotal: endpointsOf(ranked).size,
+        // Distinct relationships before the node/edge caps. Duplicate records
+        // that merged into one drawn edge are not "withheld", so they must not
+        // inflate the denominator and make an untruncated graph look truncated.
+        edgeTotal: ranked.length,
+    };
+}
+/** Symbol/file -> community name, from whichever membership map() populated. */
+function indexCommunities(map) {
+    const communityOf = new Map();
+    for (const community of map.communities) {
+        for (const file of community.files ?? [])
+            communityOf.set(file, community.name);
+        for (const symbol of community.symbols ?? [])
+            communityOf.set(symbol, community.name);
+    }
+    return communityOf;
+}
+/**
+ * Node id -> reference degree. Symbol granularity keeps map()'s symbol-scoped
+ * hubs; file granularity uses the per-file degree the dependency graph already
+ * computed.
+ */
+function indexDegrees(map, graph, granularity) {
+    const degreeOf = new Map();
+    if (granularity === "symbol")
+        for (const hub of map.hubs)
+            degreeOf.set(hub.symbol, hub.degree);
+    else
+        for (const [file, degree] of Object.entries(graph.degrees))
+            degreeOf.set(file, degree);
+    return degreeOf;
+}
+/**
+ * Collapses the dependency graph's records into the edges the artifact draws:
+ * one per distinct (from, to, kind), keyed so that duplicates merge instead of
+ * being drawn on top of each other.
+ */
+function mergeEdges(graph) {
+    const merged = new Map();
+    for (const edge of graph.edges) {
+        // Endpoints are used exactly as stored under both granularities. A file is
+        // a valid node in the symbol view too, and inventing a symbol for one would
+        // be a fabrication — so there is nothing to resolve. This was a function
+        // whose two branches both returned their argument, which read as though a
+        // mapping happened here.
+        const from = edge.fromFile;
+        const to = edge.toFile;
+        if (!from || !to || from === to)
+            continue;
+        // JSON encoding rather than a delimiter. Both endpoints are file paths,
+        // which may contain any byte except NUL and `/`, so no printable separator
+        // is collision-proof — and reaching for NUL is how this file acquired two
+        // raw 0x00 bytes, which blinds grep across the whole file while still
+        // reporting success. Encoding the tuple sidesteps the choice entirely.
+        const key = JSON.stringify([from, to, edge.kind]);
+        const existing = merged.get(key);
+        // Exact only when a narrow source declaration backs the edge at full
+        // confidence; anything weaker must read as heuristic.
+        const label = edge.sourceEvidence && edge.confidence >= 1 ? "exact" : "heuristic";
+        if (existing) {
+            // A merged pair is only "exact" when every contributing edge was.
+            if (label === "heuristic")
+                existing.label = "heuristic";
+            continue;
+        }
+        merged.set(key, {
+            from,
+            to,
+            kind: edge.kind,
+            evidence: edge.sourceEvidence ?? "no narrow source declaration recorded",
+            label,
+        });
+    }
+    return merged;
+}
+/** Distinct node ids touched by `edges`, in first-appearance order. */
+function endpointsOf(edges) {
+    const ids = new Set();
+    for (const edge of edges) {
+        ids.add(edge.from);
+        ids.add(edge.to);
+    }
+    return ids;
+}
+/**
+ * Materializes drawable nodes for `ids`, ordered by the degree that decides
+ * which of them survive the node cap.
+ */
+function buildRepoNodes(ids, granularity, index) {
+    return [...ids]
+        .map((id) => ({
+        id,
+        label: shortLabel(id, granularity),
+        weight: index.degreeOf.get(id) ?? 1,
+        community: index.communityOf.get(id),
+    }))
+        .sort(compareRepoNodes);
+}
+/**
+ * Byte order, not localeCompare: these sorts decide which edges and nodes
+ * survive the caps, so collation differing by host locale or ICU build would
+ * change the artifact's contents, not merely its ordering — and this file
+ * promises byte-identical output from identical evidence.
+ */
+function compareArtifactEdges(left, right) {
+    if (left.label !== right.label)
+        return left.label === "exact" ? -1 : 1;
+    if (left.from !== right.from)
+        return compareBytes(left.from, right.from);
+    return compareBytes(left.to, right.to);
+}
+/** Highest degree first; byte order breaks ties, for the reason above. */
+function compareRepoNodes(left, right) {
+    return left.weight === right.weight
+        ? compareBytes(left.id, right.id)
+        : right.weight - left.weight;
+}
+function html(value) {
+    return value
+        .replaceAll("&", "&amp;")
+        .replaceAll("<", "&lt;")
+        .replaceAll(">", "&gt;")
+        .replaceAll('"', "&quot;");
+}
+function sourceCommit(repo) {
+    try {
+        return execFileSync("git", ["rev-parse", "HEAD"], {
+            cwd: repo,
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"],
+        }).trim();
+    }
+    catch {
+        return "unavailable";
+    }
+}
+function safeOutput(repo, output) {
+    if (!output || path.extname(output).toLowerCase() !== ".html")
+        throw new Error("knodin visualize: --output must be a repository-relative .html path");
+    const absolute = path.resolve(repo, output);
+    if (absolute === repo || !absolute.startsWith(`${repo}${path.sep}`))
+        throw new Error("knodin visualize: output path must stay inside the repository");
+    const targetStat = fs.lstatSync(absolute, { throwIfNoEntry: false });
+    if (targetStat?.isSymbolicLink())
+        throw new Error("knodin visualize: output path may not be a symlink");
+    if (targetStat) {
+        const realTarget = fs.realpathSync(absolute);
+        if (!realTarget.startsWith(`${repo}${path.sep}`))
+            throw new Error("knodin visualize: output path may not follow a symlink outside the repository");
+    }
+    let parent = path.dirname(absolute);
+    while (!fs.existsSync(parent) && parent !== repo)
+        parent = path.dirname(parent);
+    const realParent = fs.realpathSync(parent);
+    if (realParent !== repo && !realParent.startsWith(`${repo}${path.sep}`))
+        throw new Error("knodin visualize: output path may not traverse a symlink outside the repository");
+    return { absolute, relative: path.relative(repo, absolute).replaceAll(path.sep, "/") };
+}
+/**
+ * Renders the repo-scope artifact: an inline SVG with coordinates computed at
+ * generation time, plus a community legend and honest totals. No script tags
+ * and no external references, so the file works offline and unchanged evidence
+ * reproduces identical bytes.
+ */
+function renderRepo(input) {
+    const { positions, viewport } = layoutGraph(input.nodes.map((node) => ({ id: node.id, weight: node.weight })), input.edges.map((edge) => ({ from: edge.from, to: edge.to })), input.commit);
+    const at = new Map(positions.map((position) => [position.id, position]));
+    // Colour by community, in first-appearance order for stable assignment.
+    const colorOf = new Map();
+    for (const node of input.nodes) {
+        if (!node.community || colorOf.has(node.community))
+            continue;
+        colorOf.set(node.community, COMMUNITY_COLORS[colorOf.size % COMMUNITY_COLORS.length]);
+    }
+    const unassigned = "#9aa5b1";
+    const maxWeight = Math.max(1, ...input.nodes.map((node) => node.weight));
+    const edgeSvg = input.edges
+        .map((edge) => {
+        const from = at.get(edge.from);
+        const to = at.get(edge.to);
+        if (!from || !to)
+            return "";
+        // Dashed strokes mark heuristic or inferred evidence; solid means the
+        // edge is backed by a narrow source declaration.
+        const dash = edge.label === "heuristic" ? ' stroke-dasharray="4 3"' : "";
+        const title = html(`${edge.from} → ${edge.to} (${edge.kind}, ${edge.label})`);
+        return `<line x1="${from.x}" y1="${from.y}" x2="${to.x}" y2="${to.y}" stroke="#c3ccd8" stroke-width="1"${dash}><title>${title}</title></line>`;
+    })
+        .join("");
+    const nodeSvg = input.nodes
+        .map((node) => {
+        const position = at.get(node.id);
+        if (!position)
+            return "";
+        const radius = 3 + 9 * Math.sqrt(node.weight / maxWeight);
+        const fill = node.community ? (colorOf.get(node.community) ?? unassigned) : unassigned;
+        const community = node.community ? ` — ${node.community}` : " — unassigned";
+        const title = `${node.label}${community} (degree ${node.weight})`;
+        return `<circle cx="${position.x}" cy="${position.y}" r="${round2(radius)}" fill="${fill}" fill-opacity="0.85" stroke="#ffffff" stroke-width="1"><title>${html(title)}</title></circle>`;
+    })
+        .join("");
+    const legendRows = input.communities
+        .map((community) => {
+        const swatch = colorOf.get(community.name) ?? unassigned;
+        return `<li><span class="sw" style="background:${swatch}"></span>${html(community.name)} <span class="meta">${community.size} symbols, cohesion ${community.cohesion.toFixed(3)}</span></li>`;
+    })
+        .join("");
+    const shown = (count, total, noun) => count === total
+        ? `all ${total} ${noun}`
+        : `${count} of ${total} ${noun} (${total - count} withheld by the artifact budget)`;
+    return `<!doctype html>
+<html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"><title>knodin repository graph</title><style>body{font:16px system-ui,sans-serif;margin:2rem auto;max-width:78rem;color:#172033;background:#f6f8fb;line-height:1.45}section{background:#fff;border:1px solid #d9dee7;border-radius:.55rem;padding:1rem 1.25rem;margin:1rem 0}svg{width:100%;height:auto;background:#fdfefe;border-radius:.4rem}ul{list-style:none;padding:0;columns:2;column-gap:2rem}li{margin:.35rem 0;break-inside:avoid}.sw{display:inline-block;width:.75rem;height:.75rem;border-radius:.2rem;margin-right:.5rem;vertical-align:baseline}.meta{color:#526170;font-size:.85em}code{background:#edf1f6;padding:.1rem .3rem;border-radius:.2rem}.key{color:#526170;font-size:.9em}</style></head>
+<body><h1>knodin repository graph</h1><p>Generated locally from the persisted knodin graph; no hosted service was contacted. Source commit <code>${html(input.commit)}</code>; index freshness <code>${html(input.freshness)}</code>; granularity <code>${html(input.granularity)}</code>.</p>
+<section><h2>Architecture</h2><svg viewBox="0 0 ${viewport} ${viewport}" xmlns="http://www.w3.org/2000/svg" role="img" aria-label="Repository dependency graph">${edgeSvg}${nodeSvg}</svg>
+<p class="key">Solid edges carry a narrow source declaration. Dashed edges are heuristic or inferred and are not proof of a relationship. Node size follows reference degree.</p></section>
+<section><h2>Coverage</h2><p>Showing ${shown(input.nodes.length, input.nodeTotal, input.granularity === "file" ? "files" : "symbols")}, ${shown(input.edges.length, input.edgeTotal, "relationships")}, and ${shown(input.communities.length, input.communityTotal, "communities")}.</p></section>
+<section><h2>Communities</h2><ul>${legendRows || "<li>No communities were returned.</li>"}</ul></section>
+</body></html>\n`;
+}
+function render(input) {
+    const communityRows = input.communities
+        .map((community) => {
+        const files = (community.files ?? []).slice(0, 12).join(", ") || "no file detail returned";
+        const symbols = (community.symbols ?? []).slice(0, 12).join(", ") || "no symbol detail returned";
+        return `<details><summary>${html(community.name)} <span>${community.size} symbols</span></summary><p>Cohesion: ${community.cohesion.toFixed(3)}</p><p><strong>Files:</strong> ${html(files)}</p><p><strong>Symbols:</strong> ${html(symbols)}</p></details>`;
+    })
+        .join("\n");
+    const hotspot = (kind, rows) => rows
+        .map((node) => {
+        const metric = "degree" in node ? `degree ${node.degree}` : `betweenness ${node.betweenness.toFixed(3)}`;
+        return `<li><strong>${kind}</strong> ${html(node.symbol)} — ${html(metric)}; ${html(node.filePath || "unresolved file")} (${html(node.communityId ?? "unassigned")})</li>`;
+    })
+        .join("\n");
+    const edgeRows = (edges) => edges
+        .map((edge) => `<li data-evidence="${edge.label}"><code>${html(edge.from)}</code> → <code>${html(edge.to)}</code> <span>${html(edge.kind)}</span><br><small>${edge.label === "exact" ? "Source evidence" : "Heuristic source evidence"}: ${html(edge.evidence)}</small></li>`)
+        .join("\n") || "<li>No bounded source-evidenced relationships were returned.</li>";
+    return `<!doctype html>
+<html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"><title>knodin architecture visualization</title><style>body{font:16px system-ui,sans-serif;margin:2rem auto;max-width:74rem;color:#172033;background:#f6f8fb;line-height:1.45}section{background:#fff;border:1px solid #d9dee7;border-radius:.55rem;padding:1rem 1.25rem;margin:1rem 0}details{border-top:1px solid #e5e9ef;padding:.6rem 0}summary{cursor:pointer;font-weight:650}summary span,small{color:#526170}li{margin:.55rem 0}code{background:#edf1f6;padding:.1rem .3rem;border-radius:.2rem;overflow-wrap:anywhere}[data-evidence=heuristic]{border-left:3px solid #d18a00;padding-left:.55rem}</style></head>
+<body><h1>knodin local architecture visualization</h1><p>Generated locally from the persisted knodin graph. Source commit <code>${html(input.commit)}</code>; Index freshness <code>${html(input.freshness)}</code>; ${input.truncated ? "some lists are bounded by the artifact budget." : "all displayed lists fit the requested artifact budget."}</p>
+<section><h2>Subsystem drill-down</h2>${communityRows || "<p>No communities were returned.</p>"}</section>
+<section><h2>Hub and bridge inspection</h2><ul>${hotspot("Hub", input.hubs)}${hotspot("Bridge", input.bridges)}</ul></section>
+<section><h2>Architecture relationships</h2><ul>${edgeRows(input.architectureEdges)}</ul></section>
+<section><h2>Call-flow navigation</h2><p>Static downstream traversal from <code>${html(input.entry)}</code>, depth ${input.depth}; this is not a runtime trace.</p><ul>${edgeRows(input.callFlowEdges)}</ul></section>
+</body></html>\n`;
+}
+/**
+ * Repo-scope artifact. Renders the whole architecture graph rather than a
+ * traversal from one entry, so it consults `map()` alone.
+ *
+ * Budget pressure sheds edges first, then nodes, then communities — losing
+ * relationships degrades the drawing least, and the coverage section keeps
+ * reporting the pre-truncation totals throughout.
+ */
+async function writeRepoVisualization(engine, repo, output, options) {
+    // map() supplies community membership and naming; dependencyGraph() supplies
+    // the complete edge set. Using map()'s ranked edges here would draw a sample
+    // while the coverage line implied it was the whole graph.
+    const [map, dependencies] = await Promise.all([
+        engine.map(repo, "standard", { topN: REPO_COMMUNITY_TOP_N, sort: "size" }),
+        engine.dependencyGraph(repo),
+    ]);
+    const graph = buildRepoGraph(map, dependencies, options.granularity);
+    const communityTotal = map.communityCount ?? map.communities.length;
+    const commit = sourceCommit(repo);
+    const freshness = map.staleness ?? "unknown";
+    let nodes = graph.nodes;
+    let edges = graph.edges;
+    let communities = map.communities.map((community) => ({
+        name: community.name,
+        size: community.size,
+        cohesion: community.cohesion,
+    }));
+    let truncated = graph.nodes.length < graph.nodeTotal ||
+        graph.edges.length < graph.edgeTotal ||
+        communities.length < communityTotal;
+    let artifact = "";
+    for (;;) {
+        artifact = renderRepo({
+            commit,
+            freshness,
+            granularity: options.granularity,
+            nodes,
+            edges,
+            communities,
+            nodeTotal: graph.nodeTotal,
+            edgeTotal: graph.edgeTotal,
+            communityTotal,
+            truncated,
+        });
+        if (Buffer.byteLength(artifact) <= options.byteBudget)
+            break;
+        truncated = true;
+        if (edges.length)
+            edges = edges.slice(0, -1);
+        else if (nodes.length)
+            nodes = nodes.slice(0, -1);
+        else if (communities.length)
+            communities = communities.slice(0, -1);
+        else
+            throw new Error("knodin visualize: budget is too small for visualization metadata");
+    }
+    fs.mkdirSync(path.dirname(output.absolute), { recursive: true });
+    fs.writeFileSync(output.absolute, artifact);
+    return {
+        outputPath: output.relative,
+        bytes: Buffer.byteLength(artifact),
+        sha256: crypto.createHash("sha256").update(artifact).digest("hex"),
+        byteBudget: options.byteBudget,
+        truncated,
+        indexFreshness: freshness,
+        scope: "repo",
+        callFlow: { entry: "", depth: 0, edgeCount: 0, truncated: false },
+        repo: {
+            granularity: options.granularity,
+            nodeCount: nodes.length,
+            nodeTotal: graph.nodeTotal,
+            edgeCount: edges.length,
+            edgeTotal: graph.edgeTotal,
+            communityCount: communities.length,
+            communityTotal,
+        },
+    };
+}
+/**
+ * Bounded architecture relationships from `map()`.
+ *
+ * Only edges carrying source evidence are drawn, and an edge is "exact" only
+ * when it was extracted at full confidence — anything the engine labelled
+ * heuristic, or merely inferred, must read as heuristic here too.
+ */
+function toArchitectureEdges(edges) {
+    return edges
+        .filter((edge) => Boolean(edge.sourceEvidence))
+        .slice(0, MAX_CALL_FLOW_EDGES)
+        .map((edge) => ({
+        from: edge.from,
+        to: edge.to,
+        kind: edge.kind,
+        evidence: edge.sourceEvidence ?? "",
+        label: edge.confidenceLabel === "heuristic" || edge.provenance !== "EXTRACTED"
+            ? "heuristic"
+            : "exact",
+    }));
+}
+/**
+ * Bounded call-flow relationships from the downstream traversal.
+ *
+ * Traversal edges carry their evidence on the data-flow record when there is
+ * one; otherwise the file and line stand in, naming what is missing rather than
+ * rendering a blank.
+ */
+function toCallFlowEdges(edges) {
+    return edges.slice(0, MAX_CALL_FLOW_EDGES).map((edge) => ({
+        from: edge.from,
+        to: edge.to,
+        kind: edge.kind ?? "call",
+        evidence: edge.dataFlow?.evidence ??
+            `${edge.fromFile ?? "unresolved file"}:${edge.line ?? "unknown line"}`,
+        label: edge.dataFlow?.heuristic || edge.provenance === "INFERRED"
+            ? "heuristic"
+            : "exact",
+    }));
+}
+/**
+ * Applies defaults and rejects an unusable request before any work is done.
+ *
+ * Every ceiling and enum names the flag that sets it, because these surface on
+ * the CLI and an error the operator cannot act on is just a failure.
+ */
+function validateRequest(request) {
+    const scope = request.scope ?? "call-flow";
+    if (scope !== "call-flow" && scope !== "repo")
+        throw new Error("knodin visualize: --scope must be call-flow or repo");
+    const granularity = request.granularity ?? "file";
+    if (granularity !== "file" && granularity !== "symbol")
+        throw new Error("knodin visualize: --granularity must be file or symbol");
+    const entry = (request.entry ?? "").trim();
+    // Repo scope draws the whole graph, so it has no entry to resolve.
+    if (scope === "call-flow" && !entry)
+        throw new Error("knodin visualize: an entry selector is required");
+    const depth = request.depth ?? 3;
+    if (!Number.isInteger(depth) || depth < 1 || depth > 6)
+        throw new Error("knodin visualize: --depth must be an integer from 1 through 6");
+    const byteBudget = request.byteBudget ?? (scope === "repo" ? DEFAULT_REPO_BYTE_BUDGET : DEFAULT_BYTE_BUDGET);
+    if (!Number.isInteger(byteBudget) || byteBudget < MIN_BYTE_BUDGET || byteBudget > MAX_BYTE_BUDGET)
+        throw new Error(`knodin visualize: --max-bytes must be an integer from ${MIN_BYTE_BUDGET} through ${MAX_BYTE_BUDGET}`);
+    return { scope, granularity, entry, depth, byteBudget };
+}
+export async function writeVisualization(engine, repoPath, request) {
+    const repo = fs.realpathSync(repoPath);
+    const output = safeOutput(repo, request.outputPath);
+    const { scope, granularity, entry, depth, byteBudget } = validateRequest(request);
+    if (scope === "repo")
+        return writeRepoVisualization(engine, repo, output, {
+            granularity,
+            byteBudget,
+        });
+    const [map, traversal] = await Promise.all([
+        engine.map(repo, "standard", { topN: 12, sort: "name" }),
+        engine.query("traverse", entry, repo, undefined, MAX_CALL_FLOW_EDGES, depth, "standard", request.selector, undefined, { direction: "downstream", relationKinds: ["call"], includeDataFlow: true }),
+    ]);
+    if (traversal.ambiguity || traversal.count === 0)
+        throw new Error("knodin visualize: entry selector did not resolve to a traversable symbol");
+    const architectureEdges = toArchitectureEdges(map.edges);
+    const callFlowEdges = toCallFlowEdges(traversal.edges ?? []);
+    let communities = map.communities.slice(0, 12);
+    let hubs = map.hubs.slice(0, 10);
+    let bridges = map.bridges.slice(0, 10);
+    let architecture = architectureEdges;
+    let callFlow = callFlowEdges;
+    let truncated = Boolean(traversal.truncated);
+    let artifact = "";
+    for (;;) {
+        artifact = render({
+            commit: sourceCommit(repo),
+            freshness: map.staleness ?? "unknown",
+            communities,
+            hubs,
+            bridges,
+            architectureEdges: architecture,
+            callFlowEdges: callFlow,
+            entry,
+            depth,
+            truncated,
+        });
+        if (Buffer.byteLength(artifact) <= byteBudget)
+            break;
+        truncated = true;
+        if (architecture.length)
+            architecture = architecture.slice(0, -1);
+        else if (callFlow.length)
+            callFlow = callFlow.slice(0, -1);
+        else if (communities.length)
+            communities = communities.slice(0, -1);
+        else if (hubs.length)
+            hubs = hubs.slice(0, -1);
+        else if (bridges.length)
+            bridges = bridges.slice(0, -1);
+        else
+            throw new Error("knodin visualize: budget is too small for visualization metadata");
+    }
+    fs.mkdirSync(path.dirname(output.absolute), { recursive: true });
+    fs.writeFileSync(output.absolute, artifact);
+    return {
+        outputPath: output.relative,
+        bytes: Buffer.byteLength(artifact),
+        sha256: crypto.createHash("sha256").update(artifact).digest("hex"),
+        byteBudget,
+        truncated,
+        indexFreshness: map.staleness ?? "unknown",
+        scope: "call-flow",
+        callFlow: { entry, depth, edgeCount: callFlow.length, truncated: Boolean(traversal.truncated) },
+    };
+}

package/dist/src/wait-for-fresh.js

@@ -0,0 +1,98 @@
+import childProcess from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { attachLifecycleHealth, inspectLifecycleHealth } from "./lifecycle-health.js";
+const delay = (milliseconds) => new Promise((resolve) => setTimeout(resolve, milliseconds));
+const PROCESSOR_RETRY_MS = 500;
+function installedProcessorIsRunning(repo) {
+    try {
+        const pid = Number(fs.readFileSync(path.join(repo, ".knodin", "hooks", "refresh.lock", "pid"), "utf-8"));
+        if (!Number.isInteger(pid) || pid <= 0)
+            return false;
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function launchInstalledLifecycleProcessor(repo) {
+    const processor = path.join(repo, ".knodin", "hooks", "background-index.sh");
+    if (fs.statSync(processor).mode & 0o111) {
+        const child = childProcess.spawn(processor, [], {
+            cwd: repo,
+            stdio: "ignore",
+            detached: process.platform !== "win32",
+            windowsHide: true,
+        });
+        child.once("error", () => undefined);
+        child.unref();
+    }
+}
+function requiresStructuralRepair(graph) {
+    if (Object.values(graph.orphaned).some((count) => count > 0))
+        return true;
+    const ordinary = [
+        "indexed file no longer exists: ",
+        "indexed file is no longer eligible: ",
+        "indexed snapshot differs from disk: ",
+    ];
+    return graph.missing.records.some((record) => !ordinary.some((prefix) => record.startsWith(prefix)));
+}
+function launchQueuedProcessorIfNeeded(repo, elapsed, timeoutMs, lastAttemptAt, processQueuedEvents) {
+    if (elapsed >= timeoutMs ||
+        inspectLifecycleHealth(repo).queuedEvents === 0 ||
+        installedProcessorIsRunning(repo) ||
+        elapsed - lastAttemptAt < PROCESSOR_RETRY_MS)
+        return lastAttemptAt;
+    try {
+        processQueuedEvents(repo);
+    }
+    catch {
+        // Lifecycle health retains the queued event and wait remains truthful.
+    }
+    return elapsed;
+}
+function completedStatus(graph) {
+    if (graph.status === "healthy" && graph.freshness.state === "fresh")
+        return "fresh";
+    if (graph.status === "repair-needed" && requiresStructuralRepair(graph))
+        return "repair-needed";
+    if (graph.freshness.state === "unknown")
+        return "unknown";
+    return null;
+}
+async function reconcileOrdinaryDrift(engine, repo, graph) {
+    const shouldReconcile = (graph.status === "stale" || graph.status === "repair-needed") &&
+        graph.freshness.state !== "queued";
+    if (!shouldReconcile)
+        return graph;
+    await engine.query("stats", "", repo);
+    return attachLifecycleHealth(repo, await engine.status(repo, { audit: "deep" }));
+}
+function completedResult(status, startedAt, polls, graph) {
+    return { status, waitedMs: Date.now() - startedAt, polls, graph };
+}
+/** Wait for queued work and reconcile ordinary drift; structural repair stays explicit. */
+export async function waitForFresh(engine, repo, timeoutMs = 30_000, processQueuedEvents = launchInstalledLifecycleProcessor) {
+    const startedAt = Date.now();
+    let polls = 0;
+    let lastProcessorAttemptAt = Number.NEGATIVE_INFINITY;
+    for (;;) {
+        polls++;
+        const beforeStatusElapsed = Date.now() - startedAt;
+        lastProcessorAttemptAt = launchQueuedProcessorIfNeeded(repo, beforeStatusElapsed, timeoutMs, lastProcessorAttemptAt, processQueuedEvents);
+        let graph = attachLifecycleHealth(repo, await engine.status(repo, { audit: "cached" }));
+        let status = completedStatus(graph);
+        if (status)
+            return completedResult(status, startedAt, polls, graph);
+        graph = await reconcileOrdinaryDrift(engine, repo, graph);
+        status = completedStatus(graph);
+        if (status)
+            return completedResult(status, startedAt, polls, graph);
+        const elapsed = Date.now() - startedAt;
+        if (elapsed >= timeoutMs)
+            return { status: "timeout", waitedMs: elapsed, polls, graph };
+        await delay(Math.min(100, timeoutMs - elapsed));
+    }
+}