hex-audit 0.7.0 → 0.8.0

package/dashboard/lib/data.ts

@@ -41,26 +41,6 @@ export function readMarkdownFile(filename: string): string | null {
   }
 }
 
-/**
- * Write a JSON file to the output directory.
- */
-export function writeJsonFile(filename: string, data: unknown): void {
-  const filePath = path.join(getOutputDir(), filename);
-  fs.writeFileSync(filePath, JSON.stringify(data, null, 2), 'utf-8');
-}
-
-/**
- * Check if a file exists in the output directory.
- */
-export function fileExists(filename: string): boolean {
-  try {
-    const filePath = path.join(getOutputDir(), filename);
-    return fs.existsSync(filePath);
-  } catch {
-    return false;
-  }
-}
-
 /**
  * Get the output directory path.
  */
@@ -75,7 +55,8 @@ export function listSubdirs(dir: string): string[] {
   try {
     const fullPath = path.join(getOutputDir(), dir);
     if (!fs.existsSync(fullPath)) return [];
-    return fs.readdirSync(fullPath, { withFileTypes: true })
+    return fs
+      .readdirSync(fullPath, { withFileTypes: true })
       .filter((d) => d.isDirectory())
       .map((d) => d.name);
   } catch {

package/dashboard/lib/finding-markdown.ts

@@ -1,4 +1,4 @@
-import type { BoardIssue } from '@/app/issues/IssuesBoardClient';
+import type { BoardIssue } from '@/lib/types';
 
 /**
  * Single source of truth for the finding markdown format used by the board's

package/dashboard/lib/focus.ts

@@ -0,0 +1,42 @@
+'use client';
+
+/**
+ * Focus bridge to the Claude Code session: whatever the auditor selects here is
+ * written to `.hex/focus.json` (debounced) and read by the Hex MCP tool
+ * `hex_focus`, so "this function" in the CLI means what is selected here.
+ */
+export type FocusKind =
+  | 'function'
+  | 'card'
+  | 'diagram_node'
+  | 'code_range'
+  | 'invariant'
+  | 'comment';
+
+export interface FocusInput {
+  ref: string;
+  kind: FocusKind;
+  label: string;
+  file?: string;
+  line_start?: number;
+  line_end?: number;
+}
+
+let timer: ReturnType<typeof setTimeout> | null = null;
+let last = '';
+
+export function setFocus(input: FocusInput): void {
+  const key = JSON.stringify(input);
+  if (key === last) return;
+  if (timer) clearTimeout(timer);
+  timer = setTimeout(() => {
+    last = key;
+    void fetch('/api/focus', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: key,
+    }).catch(() => {
+      last = '';
+    });
+  }, 350);
+}

package/dashboard/lib/hotkeys.ts

@@ -0,0 +1,41 @@
+'use client';
+
+import { useEffect, useRef } from 'react';
+
+/** True when the keystroke belongs to a text field, the canvas, or a dialog input. */
+export function isTypingTarget(target: EventTarget | null): boolean {
+  const el = target as HTMLElement | null;
+  if (!el || typeof el.closest !== 'function') return false;
+  if (el.isContentEditable) return true;
+  const tag = el.tagName;
+  if (tag === 'INPUT' || tag === 'TEXTAREA' || tag === 'SELECT') return true;
+  // Excalidraw owns its own keyboard shortcuts.
+  if (el.closest('.excalidraw')) return true;
+  return false;
+}
+
+type Handler = (e: KeyboardEvent) => void;
+
+/**
+ * Single-key shortcuts (j, k, r, /, Escape ...). Ignored while typing, inside
+ * the canvas, and whenever a modifier other than Shift is held. The latest
+ * handler map is always used, so callers can pass inline closures.
+ */
+export function useHotkeys(map: Record<string, Handler>, enabled = true): void {
+  const ref = useRef(map);
+  ref.current = map;
+  useEffect(() => {
+    if (!enabled) return;
+    const onKey = (e: KeyboardEvent) => {
+      if (e.metaKey || e.ctrlKey || e.altKey) return;
+      if (e.defaultPrevented) return;
+      if (document.querySelector('[data-hex-palette]')) return;
+      const handler = ref.current[e.key];
+      if (!handler) return;
+      if (e.key !== 'Escape' && isTypingTarget(e.target)) return;
+      handler(e);
+    };
+    window.addEventListener('keydown', onKey);
+    return () => window.removeEventListener('keydown', onKey);
+  }, [enabled]);
+}

package/dashboard/lib/inline-markdown.test.ts

@@ -0,0 +1,11 @@
+import { describe, it, expect } from 'vitest';
+import { escapeBlockMarkers } from '../components/MarkdownRenderer';
+
+describe('escapeBlockMarkers', () => {
+  it('keeps numbered steps, bullets, headings and quotes inline', () => {
+    expect(escapeBlockMarkers('1. pull  2. price')).toBe('1\\. pull  2. price');
+    expect(escapeBlockMarkers('- one\n# two\n> three')).toBe('\\- one\n\\# two\n\\> three');
+    expect(escapeBlockMarkers('plain `code` and **bold**')).toBe('plain `code` and **bold**');
+    expect(escapeBlockMarkers('shares > 0 stays')).toBe('shares > 0 stays');
+  });
+});

package/dashboard/lib/live.ts

@@ -0,0 +1,32 @@
+'use client';
+
+import { useSyncExternalStore } from 'react';
+
+/**
+ * Tiny shared store for the file-watcher connection, written by AutoRefresh
+ * (the one EventSource) and read by the sidebar's live indicator.
+ */
+export interface LiveState {
+  connected: boolean;
+  lastUpdate: number;
+  lastFile: string | null;
+}
+
+let state: LiveState = { connected: false, lastUpdate: Date.now(), lastFile: null };
+const listeners = new Set<() => void>();
+
+export function setLive(patch: Partial<LiveState>): void {
+  state = { ...state, ...patch };
+  for (const l of listeners) l();
+}
+
+export function useLive(): LiveState {
+  return useSyncExternalStore(
+    (cb) => {
+      listeners.add(cb);
+      return () => listeners.delete(cb);
+    },
+    () => state,
+    () => state,
+  );
+}

package/dashboard/lib/pane-width.ts

@@ -0,0 +1,36 @@
+/**
+ * Resizable panes. A pane's width lives in the CSS variable `--w-<name>` on
+ * <html> and in localStorage (`hex.w.<name>`, a per-viewer convenience). This
+ * inline script restores every stored width before the first paint, so panes
+ * never jump after hydration.
+ */
+/** Expanded, the app sidebar is as wide as the auditor dragged it. */
+export const SIDEBAR_EXPANDED_W = 'var(--w-sidebar, 220px)';
+export const SIDEBAR_KEY = 'hex.sidebar';
+
+/**
+ * Inline boot script for the root layout: restore pane widths and the sidebar
+ * state before first paint. It lives here, not in a 'use client' module: a
+ * server component importing a string from a client module gets a client
+ * reference, not the string.
+ */
+export const LAYOUT_BOOT = () => WIDTH_BOOT + SIDEBAR_BOOT;
+
+const SIDEBAR_BOOT = `try{document.documentElement.style.setProperty('--sidebar-w',localStorage.getItem('${'hex.sidebar'}')==='collapsed'?'60px':'${'var(--w-sidebar, 220px)'}')}catch(e){}`;
+
+const WIDTH_BOOT = `try{for(var i=0;i<localStorage.length;i++){var k=localStorage.key(i);if(k&&k.indexOf('hex.w.')===0){var v=parseInt(localStorage.getItem(k)||'',10);if(v>0)document.documentElement.style.setProperty('--w-'+k.slice(6),v+'px')}}}catch(e){}`;
+
+export function setPaneWidth(name: string, px: number | null): void {
+  const root = document.documentElement.style;
+  if (px === null) root.removeProperty(`--w-${name}`);
+  else root.setProperty(`--w-${name}`, `${Math.round(px)}px`);
+}
+
+export function storePaneWidth(name: string, px: number | null): void {
+  try {
+    if (px === null) localStorage.removeItem(`hex.w.${name}`);
+    else localStorage.setItem(`hex.w.${name}`, String(Math.round(px)));
+  } catch {
+    /* storage blocked: the width still applies for this page view */
+  }
+}

package/dashboard/lib/server/board.ts

@@ -0,0 +1,229 @@
+/**
+ * Board cards: tracking.json is canonical for status + source; findings.json,
+ * ai-results/, external/ and spec-conformance.json fill in the body.
+ */
+import { listSubdirs, readJsonFile, readNestedJsonFile } from '@/lib/data';
+import { functionsForFinding } from '../../../src/core/dedup';
+import type { BoardColumn, BoardIssue, CardRef, CardValidation, SyncState } from '@/lib/types';
+import { projectRoot, readFacts } from './workspace';
+
+type Sev = BoardIssue['severity'];
+
+interface FindingsFile {
+  findings: Array<{
+    id: string;
+    title: string;
+    severity: Sev;
+    description?: string;
+    recommendation?: string;
+    resolution?: string;
+    update_from_client?: string;
+    root_cause?: { locations?: Array<{ file: string; snippet?: string }> };
+    poc?: { status?: string; file?: string | null; validation_memo?: string | null };
+    github?: { issue_number?: number; issue_url?: string; state?: string; sync_status?: string };
+    category?: string;
+    validation?: CardValidation;
+    source_ref?: string | null;
+  }>;
+}
+
+interface TrackingFile {
+  findings: Array<{
+    id: string;
+    title: string;
+    severity: Sev;
+    source?: string;
+    status?: string;
+    poc_status?: string;
+    poc_file?: string | null;
+    duplicates?: string[];
+    duplicate_of?: string | null;
+    notes?: string;
+    source_ref?: string | null;
+    validation?: CardValidation;
+  }>;
+}
+
+interface ComparisonFile {
+  duplicates?: Array<{
+    ai_finding: string;
+    matches: string;
+    match_signals?: Record<string, boolean | string>;
+    reasoning?: string;
+  }>;
+}
+
+interface AiResultFile {
+  tool?: string;
+  findings: Array<{
+    id: string;
+    title: string;
+    severity: Sev;
+    description?: string;
+    affected_code?: Array<{ file: string; snippet?: string }>;
+    category?: string;
+  }>;
+}
+
+interface SpecFile {
+  items?: Array<{
+    id: string;
+    spec_text: string;
+    finding: string;
+    code_location?: { file: string };
+  }>;
+}
+
+function syncState(
+  status: string | undefined,
+  github: { issue_number?: number; state?: string; sync_status?: string } | undefined,
+): SyncState {
+  if (status !== 'verified' && status !== 'synced') return 'none';
+  if (!github?.issue_number) return 'unsynced';
+  if (github.sync_status && github.sync_status !== 'in_sync') return 'conflict';
+  return github.state === 'closed' ? 'synced_closed' : 'synced_open';
+}
+
+export function statusToColumn(status: string | undefined): BoardColumn {
+  switch (status) {
+    case 'verified':
+      return 'verified';
+    case 'synced':
+      return 'synced';
+    case 'rejected':
+      return 'invalid';
+    case 'duplicate':
+      return 'duplicate';
+    default:
+      return 'potential';
+  }
+}
+
+export function buildBoard(): BoardIssue[] {
+  const findings = readJsonFile<FindingsFile>('findings.json') ?? { findings: [] };
+  const tracking = readJsonFile<TrackingFile>('tracking.json') ?? { findings: [] };
+  const comparison = readJsonFile<ComparisonFile>('comparison.json') ?? {};
+  const spec = readJsonFile<SpecFile>('spec-conformance.json') ?? {};
+  const facts = readFacts();
+  const root = projectRoot();
+
+  const findingById = new Map(findings.findings.map((f) => [f.id, f]));
+  const specById = new Map((spec.items ?? []).map((s) => [s.id, s]));
+  const aiById = new Map<string, AiResultFile['findings'][number]>();
+  for (const dir of ['ai-results', 'external']) {
+    for (const tool of listSubdirs(dir)) {
+      const file = readNestedJsonFile<AiResultFile>(`${dir}/${tool}/findings.json`);
+      for (const f of file?.findings ?? []) aiById.set(f.id, f);
+    }
+  }
+  const dupById = new Map((comparison.duplicates ?? []).map((d) => [d.ai_finding, d]));
+
+  const fnsFor = (
+    id: string,
+    title: string,
+    description: string,
+    locations: Array<{ file: string; snippet?: string }>,
+  ) => {
+    if (!facts) return [];
+    try {
+      return functionsForFinding(
+        facts,
+        { id, title, description, root_cause: { locations } },
+        root,
+      );
+    } catch {
+      return [];
+    }
+  };
+
+  const out: BoardIssue[] = [];
+  const seen = new Set<string>();
+
+  for (const t of tracking.findings) {
+    const f = findingById.get(t.id);
+    const ai = aiById.get(t.id);
+    const sp = specById.get(t.id);
+    const description = f?.description ?? ai?.description ?? sp?.finding ?? '';
+    const locations =
+      f?.root_cause?.locations?.map((l) => ({ file: l.file, snippet: l.snippet })) ??
+      ai?.affected_code?.map((l) => ({ file: l.file, snippet: l.snippet })) ??
+      (sp?.code_location?.file ? [{ file: sp.code_location.file }] : []);
+    const dup = dupById.get(t.id);
+    const title = t.title || f?.title || ai?.title || sp?.spec_text || t.id;
+    seen.add(t.id);
+    out.push({
+      id: t.id,
+      title,
+      severity: t.severity,
+      source: (t.source ?? 'manual') as BoardIssue['source'],
+      status: t.status ?? 'pending_validation',
+      column: statusToColumn(t.status),
+      description,
+      recommendation: f?.recommendation ?? '',
+      resolution: f?.resolution,
+      update_from_client: f?.update_from_client,
+      code_locations: locations,
+      github_issue_url: f?.github?.issue_url,
+      github_issue_number: f?.github?.issue_number,
+      github_state: f?.github?.state,
+      sync_state: syncState(t.status, f?.github),
+      duplicate_of: t.duplicate_of ?? dup?.matches ?? null,
+      match_signals: dup?.match_signals
+        ? {
+            contract: Boolean(dup.match_signals.contract),
+            function: Boolean(dup.match_signals.function),
+            root_cause: String(dup.match_signals.root_cause ?? ''),
+            attack_vector: String(dup.match_signals.attack_vector ?? ''),
+          }
+        : undefined,
+      reasoning: dup?.reasoning,
+      category: f?.category || ai?.category,
+      poc_status: (t.poc_status ?? f?.poc?.status) as BoardIssue['poc_status'],
+      poc_file: t.poc_file ?? f?.poc?.file ?? null,
+      notes: t.notes ?? '',
+      source_ref: t.source_ref ?? f?.source_ref ?? null,
+      validation: t.validation ?? f?.validation,
+      functions: fnsFor(t.id, title, description, locations),
+    });
+  }
+
+  // findings.json entries without a tracking row (legacy data) render as verified.
+  for (const f of findings.findings) {
+    if (seen.has(f.id)) continue;
+    const locations = f.root_cause?.locations ?? [];
+    out.push({
+      id: f.id,
+      title: f.title,
+      severity: f.severity,
+      source: 'manual',
+      status: 'verified',
+      column: 'verified',
+      description: f.description ?? '',
+      recommendation: f.recommendation ?? '',
+      resolution: f.resolution,
+      update_from_client: f.update_from_client,
+      code_locations: locations,
+      github_issue_url: f.github?.issue_url,
+      github_issue_number: f.github?.issue_number,
+      github_state: f.github?.state,
+      sync_state: syncState('verified', f.github),
+      duplicate_of: null,
+      category: f.category,
+      poc_status: f.poc?.status as BoardIssue['poc_status'],
+      poc_file: f.poc?.file ?? null,
+      notes: '',
+      source_ref: f.source_ref ?? null,
+      validation: f.validation,
+      functions: fnsFor(f.id, f.title, f.description ?? '', locations),
+    });
+  }
+  return out;
+}
+
+/** id → compact card for inspectors on other pages. */
+export function cardRefs(board: BoardIssue[] = buildBoard()): Record<string, CardRef> {
+  const out: Record<string, CardRef> = {};
+  for (const c of board)
+    out[c.id] = { id: c.id, title: c.title, severity: c.severity, column: c.column };
+  return out;
+}

package/dashboard/lib/server/diagrams.ts

@@ -0,0 +1,191 @@
+/**
+ * Diagram files under `.hex/model/diagrams/` as the dashboard edits them.
+ * Mirrors the contract in src/diagrams/build.ts: an edited scene carries
+ * `hex.edited = true` and is never overwritten by a rebuild; a rebuild of an
+ * edited scene writes `<name>.regenerated.excalidraw` and marks the index
+ * entry `stale`. Node builtins only.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import type { DiagramIndexEntry } from '@/lib/types';
+import { outDir } from './workspace';
+
+const NAME = /^[a-z0-9][a-z0-9-]*$/;
+
+export function validName(name: string): boolean {
+  return NAME.test(name);
+}
+
+export function diagramsDir(): string {
+  return path.join(outDir(), 'model', 'diagrams');
+}
+
+export function figuresDir(): string {
+  return path.join(outDir(), 'report', 'figures');
+}
+
+function writeJsonAtomic(file: string, data: unknown): void {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const tmp = file + '.tmp';
+  fs.writeFileSync(tmp, JSON.stringify(data, null, 2) + '\n', 'utf-8');
+  fs.renameSync(tmp, file);
+}
+
+function readJson<T>(file: string): T | null {
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf-8')) as T;
+  } catch {
+    return null;
+  }
+}
+
+export function readIndex(): DiagramIndexEntry[] {
+  return readJson<DiagramIndexEntry[]>(path.join(diagramsDir(), 'index.json')) ?? [];
+}
+
+function updateIndex(name: string, patch: Partial<DiagramIndexEntry>): DiagramIndexEntry | null {
+  const index = readIndex();
+  const entry = index.find((e) => e.name === name);
+  if (!entry) return null;
+  Object.assign(entry, patch);
+  writeJsonAtomic(path.join(diagramsDir(), 'index.json'), index);
+  return entry;
+}
+
+export interface SceneFile {
+  type: 'excalidraw';
+  version: number;
+  source?: string;
+  elements: unknown[];
+  appState?: Record<string, unknown>;
+  files?: Record<string, unknown>;
+  hex?: { name: string; type: string; spec_hash: string; edited?: boolean };
+}
+
+const scenePath = (name: string) => path.join(diagramsDir(), `${name}.excalidraw`);
+const regenPath = (name: string) => path.join(diagramsDir(), `${name}.regenerated.excalidraw`);
+const figurePath = (name: string) => path.join(figuresDir(), `${name}.png`);
+
+export function sceneMtime(name: string): number {
+  try {
+    return Math.floor(fs.statSync(scenePath(name)).mtimeMs);
+  } catch {
+    return 0;
+  }
+}
+
+export function figureMtime(name: string): number {
+  try {
+    return Math.floor(fs.statSync(figurePath(name)).mtimeMs);
+  } catch {
+    return 0;
+  }
+}
+
+export function readScene(name: string): SceneFile | null {
+  return readJson<SceneFile>(scenePath(name));
+}
+
+/** Save the auditor's edit: the scene becomes `edited` and rebuilds keep it. */
+export function saveEditedScene(
+  name: string,
+  scene: {
+    elements: unknown[];
+    appState?: Record<string, unknown>;
+    files?: Record<string, unknown>;
+  },
+): { mtime: number } {
+  const prev = readScene(name);
+  const index = readIndex().find((e) => e.name === name);
+  const appState = scene.appState ?? prev?.appState ?? {};
+  const next: SceneFile = {
+    type: 'excalidraw',
+    version: 2,
+    source: prev?.source ?? 'hex',
+    elements: scene.elements,
+    appState: {
+      viewBackgroundColor: (appState.viewBackgroundColor as string) ?? '#ffffff',
+      gridSize: (appState.gridSize as number | null) ?? null,
+    },
+    files: scene.files ?? prev?.files ?? {},
+    hex: {
+      name,
+      type: prev?.hex?.type ?? index?.type ?? 'custom',
+      spec_hash: prev?.hex?.spec_hash ?? index?.spec_hash ?? '',
+      edited: true,
+    },
+  };
+  writeJsonAtomic(scenePath(name), next);
+  updateIndex(name, { edited: true });
+  return { mtime: sceneMtime(name) };
+}
+
+/** "Use new layout": the regenerated scene replaces the edited one. */
+export function useRegenerated(name: string): void {
+  const regen = readJson<SceneFile>(regenPath(name));
+  if (!regen) throw new Error(`No regenerated layout for ${name}`);
+  writeJsonAtomic(scenePath(name), {
+    ...regen,
+    hex: { ...(regen.hex ?? { name, type: 'custom' }), edited: false },
+  });
+  fs.rmSync(regenPath(name), { force: true });
+  updateIndex(name, {
+    edited: false,
+    stale: false,
+    ...(regen.hex?.spec_hash ? { spec_hash: regen.hex.spec_hash } : {}),
+  });
+}
+
+/**
+ * "Keep mine": drop the regenerated layout and adopt its spec hash, so the
+ * next rebuild sees the edited scene as current instead of regenerating again.
+ */
+export function keepEdited(name: string): void {
+  const regen = readJson<SceneFile>(regenPath(name));
+  const current = readScene(name);
+  const specHash = regen?.hex?.spec_hash ?? current?.hex?.spec_hash ?? '';
+  if (current) {
+    writeJsonAtomic(scenePath(name), {
+      ...current,
+      hex: { ...(current.hex ?? { name, type: 'custom' }), spec_hash: specHash, edited: true },
+    });
+  }
+  fs.rmSync(regenPath(name), { force: true });
+  updateIndex(name, { stale: false, edited: true, ...(specHash ? { spec_hash: specHash } : {}) });
+}
+
+/** "Use in report": write `.hex/report/figures/<name>.png`. */
+export function writeFigure(name: string, png: Buffer): void {
+  fs.mkdirSync(figuresDir(), { recursive: true });
+  const tmp = figurePath(name) + '.tmp';
+  fs.writeFileSync(tmp, png);
+  fs.renameSync(tmp, figurePath(name));
+  updateIndex(name, { in_report: true });
+}
+
+export function removeFigure(name: string): void {
+  fs.rmSync(figurePath(name), { force: true });
+  updateIndex(name, { in_report: false });
+}
+
+export function readFigure(name: string): Buffer | null {
+  try {
+    return fs.readFileSync(figurePath(name));
+  } catch {
+    return null;
+  }
+}
+
+/** Every PNG under report/figures (the report shows those in the index's `in_report`, plus any others). */
+export function listFigures(): string[] {
+  try {
+    return fs
+      .readdirSync(figuresDir())
+      .filter((f) => f.endsWith('.png'))
+      .map((f) => f.replace(/\.png$/, ''))
+      .filter(validName)
+      .sort();
+  } catch {
+    return [];
+  }
+}

package/dashboard/lib/server/safe-path.ts

@@ -0,0 +1,28 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { projectRoot } from './workspace';
+
+/**
+ * Resolve `file` inside the audited project, or null. Both sides go through
+ * realpath (no symlink escapes), the target must be the root or sit under
+ * `root + sep` (no `/proj-evil` prefix tricks), and dotfiles, dot-dirs
+ * (`.env`, `.git`, `.hex`) and anything under node_modules are refused.
+ */
+export function resolveSafe(file: string): string | null {
+  let root: string;
+  try {
+    root = fs.realpathSync(projectRoot());
+  } catch {
+    return null;
+  }
+  let target: string;
+  try {
+    target = fs.realpathSync(path.resolve(root, file));
+  } catch {
+    return null;
+  }
+  if (target !== root && !target.startsWith(root + path.sep)) return null;
+  const segments = path.relative(root, target).split(path.sep);
+  if (segments.some((s) => s.startsWith('.') || s === 'node_modules')) return null;
+  return target;
+}