hex-audit 0.7.0 → 0.8.0

package/dashboard/app/api/comments/route.ts

@@ -0,0 +1,158 @@
+import { NextRequest, NextResponse } from 'next/server';
+import { spawn } from 'node:child_process';
+import fs from 'node:fs';
+import { getOutputDirPath } from '@/lib/data';
+import { projectRoot } from '@/lib/server/workspace';
+import { resolveSafe } from '@/lib/server/safe-path';
+import {
+  addComment,
+  commentsForFile,
+  deleteComment,
+  editComment,
+  readComments,
+  removeCommentFromSource,
+  restoreComment,
+  writeCommentToSource,
+  type CodeComment,
+} from '../../../../src/core/comments';
+
+export const dynamic = 'force-dynamic';
+
+// Writing `// @audit` lines into a file shifts its line numbers, so facts.json
+// (which the Review page highlights by) is rebuilt in the background. Debounced
+// and single-flight: a burst of edits costs one build.
+let timer: ReturnType<typeof setTimeout> | null = null;
+let running = false;
+let again = false;
+
+function rebuildFacts(): 'rebuilding' | 'skipped' {
+  const cli = process.env.HEX_CLI;
+  if (!cli || !fs.existsSync(cli)) return 'skipped';
+  const run = () => {
+    if (running) {
+      again = true;
+      return;
+    }
+    running = true;
+    const child = spawn(process.execPath, [cli, 'facts', '--project', projectRoot()], {
+      stdio: 'ignore',
+    });
+    child.on('exit', () => {
+      running = false;
+      if (again) {
+        again = false;
+        run();
+      }
+    });
+    child.on('error', () => {
+      running = false;
+    });
+  };
+  if (timer) clearTimeout(timer);
+  timer = setTimeout(run, 800);
+  return 'rebuilding';
+}
+
+const bad = (error: string, status = 400) => NextResponse.json({ error }, { status });
+const fail = (err: unknown) => bad(err instanceof Error ? err.message : String(err), 500);
+
+/** GET ?file=src/Vault.sol → the comments on that file at their current lines. */
+export async function GET(request: NextRequest) {
+  const file = request.nextUrl.searchParams.get('file');
+  if (!file) return bad('Missing file');
+  if (!resolveSafe(file)) return bad('File not available', 403);
+  try {
+    return NextResponse.json({ comments: commentsForFile(getOutputDirPath(), file) });
+  } catch (err) {
+    return fail(err);
+  }
+}
+
+/**
+ * POST { action: 'add', file, line_start, line_end, text }
+ *      { action: 'restore', comment }          (undo a delete)
+ *      { action: 'write' | 'unwrite', id }     (put into / take out of the file)
+ */
+export async function POST(request: NextRequest) {
+  try {
+    const body = (await request.json()) as {
+      action?: string;
+      file?: string;
+      line_start?: number;
+      line_end?: number;
+      text?: string;
+      id?: string;
+      comment?: CodeComment;
+    };
+    const dir = getOutputDirPath();
+    switch (body.action ?? 'add') {
+      case 'add': {
+        if (!body.file || !resolveSafe(body.file)) return bad('File not available', 403);
+        if (!body.line_start || !body.text?.trim()) return bad('line_start and text are required');
+        const comment = addComment(dir, {
+          file: body.file,
+          line_start: body.line_start,
+          line_end: body.line_end ?? body.line_start,
+          text: body.text,
+        });
+        return NextResponse.json({ comment });
+      }
+      case 'restore': {
+        const c = body.comment;
+        if (!c?.id || !c.file || !resolveSafe(c.file)) return bad('Invalid comment');
+        return NextResponse.json({ comment: restoreComment(dir, c) });
+      }
+      case 'write':
+      case 'unwrite': {
+        if (!body.id) return bad('id is required');
+        const c = readComments(dir).find((x) => x.id === body.id);
+        if (!c || !resolveSafe(c.file)) return bad('Comment not available', 404);
+        const comment =
+          body.action === 'write'
+            ? writeCommentToSource(dir, body.id)
+            : removeCommentFromSource(dir, body.id);
+        return NextResponse.json({ comment, facts: rebuildFacts() });
+      }
+      default:
+        return bad(`Unknown action ${body.action}`);
+    }
+  } catch (err) {
+    return fail(err);
+  }
+}
+
+/** PATCH { id, text } → edit (rewrites the file's @audit lines when it sits there). */
+export async function PATCH(request: NextRequest) {
+  try {
+    const { id, text } = (await request.json()) as { id?: string; text?: string };
+    if (!id || !text?.trim()) return bad('id and text are required');
+    const dir = getOutputDirPath();
+    const before = readComments(dir).find((x) => x.id === id);
+    if (!before || !resolveSafe(before.file)) return bad('Comment not available', 404);
+    const comment = editComment(dir, id, text);
+    return NextResponse.json({
+      comment,
+      ...(before.in_source ? { facts: rebuildFacts() } : {}),
+    });
+  } catch (err) {
+    return fail(err);
+  }
+}
+
+/** DELETE ?id=C-001 → removes it (and its @audit lines); returns it for Undo. */
+export async function DELETE(request: NextRequest) {
+  try {
+    const id = request.nextUrl.searchParams.get('id');
+    if (!id) return bad('Missing id');
+    const dir = getOutputDirPath();
+    const before = readComments(dir).find((x) => x.id === id);
+    if (!before || !resolveSafe(before.file)) return bad('Comment not available', 404);
+    const comment = deleteComment(dir, id);
+    return NextResponse.json({
+      comment,
+      ...(before.in_source ? { facts: rebuildFacts() } : {}),
+    });
+  } catch (err) {
+    return fail(err);
+  }
+}

package/dashboard/app/api/diagrams/[name]/export/route.ts

@@ -0,0 +1,26 @@
+import { NextRequest, NextResponse } from 'next/server';
+import { removeFigure, validName, writeFigure } from '@/lib/server/diagrams';
+
+export const dynamic = 'force-dynamic';
+
+const PNG_MAGIC = Buffer.from([0x89, 0x50, 0x4e, 0x47]);
+
+/** "Use in report": the PNG body becomes `.hex/report/figures/<name>.png`. */
+export async function POST(request: NextRequest, { params }: { params: { name: string } }) {
+  if (!validName(params.name)) return NextResponse.json({ error: 'Invalid name' }, { status: 400 });
+  const buf = Buffer.from(await request.arrayBuffer());
+  if (buf.length < 8 || !buf.subarray(0, 4).equals(PNG_MAGIC)) {
+    return NextResponse.json({ error: 'Body must be a PNG' }, { status: 400 });
+  }
+  if (buf.length > 20 * 1024 * 1024)
+    return NextResponse.json({ error: 'PNG too large' }, { status: 413 });
+  writeFigure(params.name, buf);
+  return NextResponse.json({ ok: true });
+}
+
+/** Take the figure out of the report. */
+export async function DELETE(_req: NextRequest, { params }: { params: { name: string } }) {
+  if (!validName(params.name)) return NextResponse.json({ error: 'Invalid name' }, { status: 400 });
+  removeFigure(params.name);
+  return NextResponse.json({ ok: true });
+}

package/dashboard/app/api/diagrams/[name]/resolve/route.ts

@@ -0,0 +1,25 @@
+import { NextRequest, NextResponse } from 'next/server';
+import { keepEdited, useRegenerated, validName } from '@/lib/server/diagrams';
+
+export const dynamic = 'force-dynamic';
+
+/** Stale edited diagram: `{ action: 'use-new' | 'keep-mine' }`. */
+export async function POST(request: NextRequest, { params }: { params: { name: string } }) {
+  if (!validName(params.name)) return NextResponse.json({ error: 'Invalid name' }, { status: 400 });
+  const { action } = (await request.json().catch(() => ({}))) as { action?: string };
+  try {
+    if (action === 'use-new') useRegenerated(params.name);
+    else if (action === 'keep-mine') keepEdited(params.name);
+    else
+      return NextResponse.json(
+        { error: "action must be 'use-new' or 'keep-mine'" },
+        { status: 400 },
+      );
+    return NextResponse.json({ ok: true });
+  } catch (err) {
+    return NextResponse.json(
+      { error: err instanceof Error ? err.message : String(err) },
+      { status: 400 },
+    );
+  }
+}

package/dashboard/app/api/diagrams/[name]/route.ts

@@ -0,0 +1,37 @@
+import { NextRequest, NextResponse } from 'next/server';
+import { readScene, saveEditedScene, sceneMtime, validName } from '@/lib/server/diagrams';
+
+export const dynamic = 'force-dynamic';
+
+export async function GET(_req: NextRequest, { params }: { params: { name: string } }) {
+  if (!validName(params.name)) return NextResponse.json({ error: 'Invalid name' }, { status: 400 });
+  const scene = readScene(params.name);
+  if (!scene) return NextResponse.json({ error: 'Not found' }, { status: 404 });
+  return NextResponse.json({ scene, mtime: sceneMtime(params.name) });
+}
+
+/** Save an edited scene: writes `<name>.excalidraw` (hex.edited) and marks the index entry edited. */
+export async function PUT(request: NextRequest, { params }: { params: { name: string } }) {
+  if (!validName(params.name)) return NextResponse.json({ error: 'Invalid name' }, { status: 400 });
+  const body = (await request.json().catch(() => null)) as {
+    elements?: unknown;
+    appState?: Record<string, unknown>;
+    files?: Record<string, unknown>;
+  } | null;
+  if (!body || !Array.isArray(body.elements)) {
+    return NextResponse.json({ error: 'elements must be an array' }, { status: 400 });
+  }
+  try {
+    const { mtime } = saveEditedScene(params.name, {
+      elements: body.elements,
+      appState: body.appState,
+      files: body.files,
+    });
+    return NextResponse.json({ ok: true, mtime });
+  } catch (err) {
+    return NextResponse.json(
+      { error: err instanceof Error ? err.message : String(err) },
+      { status: 500 },
+    );
+  }
+}

package/dashboard/app/api/figures/[name]/route.ts

@@ -0,0 +1,15 @@
+import { NextRequest, NextResponse } from 'next/server';
+import { readFigure, validName } from '@/lib/server/diagrams';
+
+export const dynamic = 'force-dynamic';
+
+/** Serve `.hex/report/figures/<name>.png` for report thumbnails. */
+export async function GET(_req: NextRequest, { params }: { params: { name: string } }) {
+  const name = params.name.replace(/\.png$/, '');
+  if (!validName(name)) return NextResponse.json({ error: 'Invalid name' }, { status: 400 });
+  const png = readFigure(name);
+  if (!png) return NextResponse.json({ error: 'Not found' }, { status: 404 });
+  return new NextResponse(new Uint8Array(png), {
+    headers: { 'Content-Type': 'image/png', 'Cache-Control': 'no-cache' },
+  });
+}

package/dashboard/app/api/focus/route.ts

@@ -0,0 +1,35 @@
+import { NextRequest, NextResponse } from 'next/server';
+import fs from 'node:fs';
+import path from 'node:path';
+import { outDir } from '@/lib/server/workspace';
+
+export const dynamic = 'force-dynamic';
+
+const KINDS = new Set(['function', 'card', 'diagram_node', 'code_range', 'invariant', 'comment']);
+
+/**
+ * The dashboard's current selection → `.hex/focus.json`, read by the Hex MCP
+ * tool `hex_focus` so the Claude Code session knows what "this" means.
+ */
+export async function POST(request: NextRequest) {
+  const b = (await request.json().catch(() => ({}))) as Record<string, unknown>;
+  if (typeof b.ref !== 'string' || !b.ref || typeof b.kind !== 'string' || !KINDS.has(b.kind)) {
+    return NextResponse.json({ error: 'ref and kind are required' }, { status: 400 });
+  }
+  const int = (v: unknown) =>
+    typeof v === 'number' && Number.isFinite(v) ? Math.trunc(v) : undefined;
+  const focus = {
+    ref: b.ref.slice(0, 500),
+    kind: b.kind,
+    label: typeof b.label === 'string' ? b.label.slice(0, 500) : b.ref.slice(0, 500),
+    ...(typeof b.file === 'string' ? { file: b.file } : {}),
+    ...(int(b.line_start) !== undefined ? { line_start: int(b.line_start) } : {}),
+    ...(int(b.line_end) !== undefined ? { line_end: int(b.line_end) } : {}),
+    updated_at: new Date().toISOString(),
+  };
+  const file = path.join(outDir(), 'focus.json');
+  const tmp = file + '.tmp';
+  fs.writeFileSync(tmp, JSON.stringify(focus, null, 2) + '\n', 'utf-8');
+  fs.renameSync(tmp, file);
+  return NextResponse.json({ ok: true });
+}

package/dashboard/app/api/invariants/[id]/route.ts

@@ -0,0 +1,35 @@
+import { NextRequest, NextResponse } from 'next/server';
+import { outDir } from '@/lib/server/workspace';
+import { setInvariantStatus } from '../../../../../src/core/model';
+
+export const dynamic = 'force-dynamic';
+
+const STATUSES = new Set(['proposed', 'accepted', 'rejected']);
+
+/** Accept / reject (or restore to proposed) an invariant. */
+export async function POST(request: NextRequest, { params }: { params: { id: string } }) {
+  const { status, rationale } = (await request.json().catch(() => ({}))) as {
+    status?: string;
+    rationale?: string;
+  };
+  if (!status || !STATUSES.has(status)) {
+    return NextResponse.json(
+      { error: 'status must be proposed|accepted|rejected' },
+      { status: 400 },
+    );
+  }
+  try {
+    const inv = setInvariantStatus(
+      outDir(),
+      params.id,
+      status as 'proposed' | 'accepted' | 'rejected',
+      typeof rationale === 'string' && rationale.trim() ? rationale.trim() : undefined,
+    );
+    return NextResponse.json({ ok: true, invariant: inv });
+  } catch (err) {
+    return NextResponse.json(
+      { error: err instanceof Error ? err.message : String(err) },
+      { status: 400 },
+    );
+  }
+}

package/dashboard/app/api/issues/[id]/revert-auto/route.ts

@@ -0,0 +1,18 @@
+import { NextRequest, NextResponse } from 'next/server';
+import { getOutputDirPath } from '@/lib/data';
+import { revertAutoMove } from '../../../../../../src/core/issues';
+
+export const dynamic = 'force-dynamic';
+
+/** Undo an agent's auto-move: back to Potential, auto flag cleared. */
+export async function POST(_req: NextRequest, { params }: { params: { id: string } }) {
+  try {
+    const entry = revertAutoMove(getOutputDirPath(), params.id);
+    return NextResponse.json({ ok: true, id: params.id, status: entry.status });
+  } catch (err) {
+    return NextResponse.json(
+      { error: err instanceof Error ? err.message : String(err) },
+      { status: 400 },
+    );
+  }
+}

package/dashboard/app/api/nav/route.ts

@@ -0,0 +1,120 @@
+import { NextRequest, NextResponse } from 'next/server';
+import fs from 'node:fs';
+import { readFacts } from '@/lib/server/workspace';
+import { resolveSafe } from '@/lib/server/safe-path';
+import { enclosingDecl, readXref } from '@/lib/server/xref';
+import { callSites, readers, writers } from '../../../../src/facts/query';
+import type { XrefDecl } from '../../../../src/facts/xref';
+
+export const dynamic = 'force-dynamic';
+
+export interface NavSite {
+  /** The function the site sits in (a facts id), when there is one. */
+  from?: string;
+  fromName?: string;
+  /** That function's lines, so the viewer can open it whole. */
+  fromStart?: number;
+  fromEnd?: number;
+  file: string;
+  line: number;
+  /** The source line, trimmed, for the list. */
+  code: string;
+  kind: string;
+}
+
+/**
+ * GET ?key=<decl key> → upstream for one declaration: for functions and
+ * modifiers, every call site (facts call graph, including virtual dispatch);
+ * for state variables and everything else, every place the code refers to it,
+ * with reads and writes told apart.
+ */
+export async function GET(request: NextRequest) {
+  const key = request.nextUrl.searchParams.get('key');
+  if (!key) return NextResponse.json({ error: 'Missing key' }, { status: 400 });
+  const xref = readXref();
+  const facts = readFacts();
+  const decl: XrefDecl | undefined = xref?.decls[key];
+
+  const lines = new Map<string, string[]>();
+  const codeAt = (file: string, line: number) => {
+    if (!lines.has(file)) {
+      const abs = resolveSafe(file);
+      let text: string[] = [];
+      try {
+        if (abs) text = fs.readFileSync(abs, 'utf-8').split(/\r?\n/);
+      } catch {
+        /* unreadable: no snippet */
+      }
+      lines.set(file, text);
+    }
+    return (lines.get(file)![line - 1] ?? '').trim();
+  };
+  const nameOf = (id: string) => {
+    const d = xref?.decls[id];
+    return d ? `${d.contract ? `${d.contract}.` : ''}${d.name}` : id.replace(/\(.*$/, '');
+  };
+
+  let sites: NavSite[] = [];
+  const isCallable = decl
+    ? decl.kind === 'function' || decl.kind === 'modifier'
+    : key.includes('(');
+  if (isCallable && facts) {
+    const fns = new Map(facts.functions.map((f) => [f.id, f]));
+    sites = callSites(facts, key)
+      .filter((s) => s.line)
+      .map((s) => ({
+        from: s.from,
+        fromName: nameOf(s.from),
+        fromStart: fns.get(s.from)?.line_start,
+        fromEnd: fns.get(s.from)?.line_end,
+        file: s.file,
+        line: s.line!,
+        code: codeAt(s.file, s.line!),
+        kind: s.kind,
+      }));
+  } else if (xref) {
+    const writing = new Set(facts && decl?.kind === 'state_var' ? writers(facts, key) : []);
+    const reading = new Set(facts && decl?.kind === 'state_var' ? readers(facts, key) : []);
+    for (const [file, refs] of Object.entries(xref.refs)) {
+      for (const [line, , , k, def] of refs) {
+        if (k !== key || def) continue;
+        const enc = enclosingDecl(xref, file, line);
+        const kind =
+          decl?.kind !== 'state_var'
+            ? 'use'
+            : enc && writing.has(enc.key)
+              ? 'write'
+              : enc && reading.has(enc.key)
+                ? 'read'
+                : 'use';
+        sites.push({
+          ...(enc
+            ? {
+                from: enc.key,
+                fromName: nameOf(enc.key),
+                fromStart: enc.decl.line_start,
+                fromEnd: enc.decl.line_end,
+              }
+            : {}),
+          file,
+          line,
+          code: codeAt(file, line),
+          kind,
+        });
+      }
+    }
+  }
+  // One row per line: `totalShares == 0 ? x : y / totalShares` is one use, not two.
+  const seen = new Set<string>();
+  sites = sites
+    .filter((s) => {
+      const k = `${s.from ?? ''}|${s.file}|${s.line}|${s.kind}`;
+      if (seen.has(k)) return false;
+      seen.add(k);
+      return true;
+    })
+    .sort((a, b) => a.file.localeCompare(b.file) || a.line - b.line);
+
+  const impls = (xref?.impls[key] ?? []).map((i) => ({ ...i, decl: xref?.decls[i.id] ?? null }));
+  return NextResponse.json({ key, decl: decl ?? null, impls, sites });
+}

package/dashboard/app/api/palette/route.ts

@@ -0,0 +1,68 @@
+import { NextResponse } from 'next/server';
+import { buildBoard } from '@/lib/server/board';
+import { readIndex } from '@/lib/server/diagrams';
+import { outDir, readFacts } from '@/lib/server/workspace';
+import { readInvariants } from '../../../../src/core/model';
+
+export const dynamic = 'force-dynamic';
+
+export interface PaletteEntry {
+  kind: 'function' | 'contract' | 'card' | 'invariant' | 'diagram';
+  label: string;
+  detail?: string;
+  href: string;
+}
+
+/** Everything ⌘K can jump to beyond the six pages. */
+export async function GET() {
+  const entries: PaletteEntry[] = [];
+  const facts = readFacts();
+  if (facts) {
+    const interfaces = new Set(
+      facts.contracts.filter((c) => c.kind === 'interface').map((c) => c.name),
+    );
+    for (const c of facts.contracts) {
+      if (!c.in_scope || c.kind === 'interface') continue;
+      entries.push({
+        kind: 'contract',
+        label: c.name,
+        detail: c.file,
+        href: `/review?contract=${encodeURIComponent(c.name)}`,
+      });
+    }
+    for (const f of facts.functions) {
+      if (!f.in_scope || interfaces.has(f.contract) || f.nsloc <= 0) continue;
+      entries.push({
+        kind: 'function',
+        label: `${f.contract}.${f.name}`,
+        detail: f.signature,
+        href: `/review?fn=${encodeURIComponent(f.id)}`,
+      });
+    }
+  }
+  for (const c of buildBoard()) {
+    entries.push({
+      kind: 'card',
+      label: c.title,
+      detail: `${c.id} · ${c.severity}`,
+      href: `/issues?card=${encodeURIComponent(c.id)}`,
+    });
+  }
+  for (const i of readInvariants(outDir()).invariants) {
+    entries.push({
+      kind: 'invariant',
+      label: i.statement,
+      detail: i.id,
+      href: `/model?s=invariants&id=${encodeURIComponent(i.id)}`,
+    });
+  }
+  for (const d of readIndex()) {
+    entries.push({
+      kind: 'diagram',
+      label: d.title,
+      detail: 'Diagram',
+      href: `/model?d=${encodeURIComponent(d.name)}`,
+    });
+  }
+  return NextResponse.json({ entries });
+}

package/dashboard/app/api/progress/route.ts

@@ -1,36 +1,67 @@
 import { NextRequest, NextResponse } from 'next/server';
-import { readJsonFile, writeJsonFile } from '@/lib/data';
+import { outDir } from '@/lib/server/workspace';
+import {
+  markFunctions,
+  readProgress,
+  reviewSummary,
+  writeProgress,
+  REVIEW_STATES,
+  type ReviewState,
+} from '../../../../src/core/review';
 
-interface ProgressData {
-  updated_at: string;
-  reviewed_contracts: Record<string, boolean>;
-}
-
-const DEFAULT_PROGRESS: ProgressData = {
-  updated_at: new Date().toISOString(),
-  reviewed_contracts: {},
-};
+export const dynamic = 'force-dynamic';
 
+/** The review map: totals plus one row per reviewable function. */
 export async function GET() {
-  const data = readJsonFile<ProgressData>('progress.json');
-  return NextResponse.json(data ?? DEFAULT_PROGRESS);
+  return NextResponse.json(reviewSummary(outDir(), { blindSpots: 10 }));
 }
 
+/**
+ * Mark functions: `{ ids, state, note? }` → markFunctions (atomic write via
+ * src/core/review.ts). The legacy contract checklist payload
+ * `{ reviewed_contracts }` is still accepted and merged the same way.
+ */
 export async function POST(request: NextRequest) {
-  const body = await request.json() as { reviewed_contracts: Record<string, boolean> };
+  const body = (await request.json().catch(() => ({}))) as {
+    ids?: unknown;
+    state?: unknown;
+    note?: unknown;
+    reviewed_contracts?: unknown;
+  };
+  const dir = outDir();
 
-  if (!body.reviewed_contracts || typeof body.reviewed_contracts !== 'object') {
-    return NextResponse.json({ error: 'Invalid payload' }, { status: 400 });
+  if (Array.isArray(body.ids)) {
+    const ids = body.ids.filter((x): x is string => typeof x === 'string');
+    if (
+      !ids.length ||
+      typeof body.state !== 'string' ||
+      !REVIEW_STATES.includes(body.state as ReviewState)
+    ) {
+      return NextResponse.json(
+        { error: 'ids must be non-empty and state one of unread|read|questioned|cleared' },
+        { status: 400 },
+      );
+    }
+    const note = typeof body.note === 'string' && body.note.trim() ? body.note.trim() : undefined;
+    markFunctions(dir, ids, body.state as ReviewState, 'dashboard', note);
+    const s = reviewSummary(dir);
+    return NextResponse.json({
+      ok: true,
+      pct: s.pct,
+      counts: s.counts,
+      cleared_nsloc: s.cleared_nsloc,
+      total_nsloc: s.total_nsloc,
+    });
   }
 
-  const existing = readJsonFile<ProgressData>('progress.json') ?? { ...DEFAULT_PROGRESS };
-
-  // Merge: new values override existing
-  for (const [key, value] of Object.entries(body.reviewed_contracts)) {
-    existing.reviewed_contracts[key] = value;
+  if (body.reviewed_contracts && typeof body.reviewed_contracts === 'object') {
+    const data = readProgress(dir);
+    for (const [k, v] of Object.entries(body.reviewed_contracts as Record<string, unknown>)) {
+      data.reviewed_contracts[k] = Boolean(v);
+    }
+    writeProgress(dir, data);
+    return NextResponse.json({ ok: true });
   }
-  existing.updated_at = new Date().toISOString();
 
-  writeJsonFile('progress.json', existing);
-  return NextResponse.json(existing);
+  return NextResponse.json({ error: 'Invalid payload' }, { status: 400 });
 }

package/dashboard/app/api/xref/route.ts

@@ -0,0 +1,30 @@
+import { NextRequest, NextResponse } from 'next/server';
+import { readXref } from '@/lib/server/xref';
+import type { XrefDecl } from '../../../../src/facts/xref';
+
+export const dynamic = 'force-dynamic';
+
+/**
+ * GET ?file=src/Vault.sol → what the code viewer needs to make that file
+ * navigable: its references, the declarations they point at (and the
+ * declarations in the file), and where interface or virtual targets run.
+ */
+export async function GET(request: NextRequest) {
+  const file = request.nextUrl.searchParams.get('file');
+  if (!file) return NextResponse.json({ error: 'Missing file' }, { status: 400 });
+  const xref = readXref();
+  if (!xref) return NextResponse.json({ available: false });
+  const refs = xref.refs[file] ?? [];
+  const keys = new Set(refs.map((r) => r[3]));
+  for (const [k, d] of Object.entries(xref.decls)) if (d.file === file) keys.add(k);
+  const impls: Record<string, (typeof xref.impls)[string]> = {};
+  for (const k of [...keys]) {
+    const list = xref.impls[k];
+    if (!list) continue;
+    impls[k] = list;
+    for (const i of list) keys.add(i.id);
+  }
+  const decls: Record<string, XrefDecl> = {};
+  for (const k of keys) if (xref.decls[k]) decls[k] = xref.decls[k];
+  return NextResponse.json({ available: true, refs, decls, impls });
+}