hex-audit 0.6.3 → 0.8.0

package/dashboard/lib/server/workspace.ts

@@ -0,0 +1,113 @@
+/**
+ * Server-side reads shared by pages and API routes. Everything here goes
+ * through the canonical node-builtins-only modules in src/ (review, facts,
+ * notes, model, rules) so the dashboard and the CLI agree on every file.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { getOutputDirPath, readJsonFile } from '@/lib/data';
+import { reviewSummary } from '../../../src/core/review';
+import { loadFacts } from '../../../src/facts/query';
+import { readContractNote, readNotesIndex, resolveNoteTarget } from '../../../src/core/notes';
+import type { Facts } from '../../../src/types/index';
+import type { ContractNoteView, ReviewRow, ReviewTotals } from '@/lib/types';
+
+export function outDir(): string {
+  return getOutputDirPath();
+}
+
+/** The audited project root: the directory that holds `.hex/`. */
+export function projectRoot(): string {
+  return path.dirname(outDir());
+}
+
+export interface ProjectConfig {
+  project?: {
+    name?: string;
+    commit?: string;
+    chain?: string;
+    solidity_version?: string;
+    scope?: string[];
+    mode?: 'full' | 'diff';
+    diff?: { base_commit?: string };
+  };
+  settings?: { report?: { repository_url?: string; initial_commit?: string } };
+}
+
+export function readConfig(): ProjectConfig | null {
+  return readJsonFile<ProjectConfig>('config.json');
+}
+
+export function isDiffMode(): boolean {
+  return readConfig()?.project?.mode === 'diff';
+}
+
+export function readFacts(): Facts | null {
+  return loadFacts(outDir());
+}
+
+export function readReview(
+  blindSpots = 10,
+): ReviewTotals & { rows: ReviewRow[]; blind_spots: ReviewRow[] } {
+  return reviewSummary(outDir(), { blindSpots }) as ReviewTotals & {
+    rows: ReviewRow[];
+    blind_spots: ReviewRow[];
+  };
+}
+
+/** Diane's structured note for a contract, trimmed to what the inspector shows. */
+export function contractNoteView(contract: string): ContractNoteView {
+  const dir = outDir();
+  const target = resolveNoteTarget(dir, contract);
+  const note = readContractNote(dir, target);
+  return {
+    target,
+    contract,
+    marked_done: note.marked_done,
+    purpose: note.description.purpose,
+    functions: note.description.functions.map((f) => ({
+      id: f.id,
+      sig: f.sig,
+      fn_ref: (f as unknown as { fn_ref?: string }).fn_ref,
+      purpose: f.purpose,
+      access: f.access,
+      effects: f.effects,
+      notes: f.notes,
+      warnings: f.warnings,
+    })),
+    questions: note.questions,
+    leads: note.leads,
+  };
+}
+
+export function unprocessedSessions(): number {
+  return readNotesIndex(outDir()).sessions.filter((s) => !s.processed).length;
+}
+
+export function readGeneralNote(): string {
+  try {
+    return fs.readFileSync(path.join(outDir(), 'notes', 'general.md'), 'utf-8');
+  } catch {
+    return '';
+  }
+}
+
+/** Newest `.hex/fix-review/*.json` by `generated_at`. */
+export function latestFixReview<T extends { generated_at: string }>(): T | null {
+  const dir = path.join(outDir(), 'fix-review');
+  let best: T | null = null;
+  try {
+    for (const f of fs.readdirSync(dir)) {
+      if (!f.endsWith('.json')) continue;
+      try {
+        const data = JSON.parse(fs.readFileSync(path.join(dir, f), 'utf-8')) as T;
+        if (!best || Date.parse(data.generated_at) > Date.parse(best.generated_at)) best = data;
+      } catch {
+        /* skip unreadable */
+      }
+    }
+  } catch {
+    return null;
+  }
+  return best;
+}

package/dashboard/lib/server/xref.ts

@@ -0,0 +1,42 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { getOutputDirPath } from '@/lib/data';
+import type { Xref, XrefDecl } from '../../../src/facts/xref';
+
+let cache: { file: string; mtime: number; data: Xref } | null = null;
+
+/** `.hex/xref.json`, parsed once per change on disk; null when `hex facts` has not written it. */
+export function readXref(): Xref | null {
+  const file = path.join(getOutputDirPath(), 'xref.json');
+  let mtime: number;
+  try {
+    mtime = fs.statSync(file).mtimeMs;
+  } catch {
+    cache = null;
+    return null;
+  }
+  if (cache && cache.file === file && cache.mtime === mtime) return cache.data;
+  try {
+    const data = JSON.parse(fs.readFileSync(file, 'utf-8')) as Xref;
+    cache = { file, mtime, data };
+    return data;
+  } catch {
+    return null;
+  }
+}
+
+/** The function or modifier whose body holds `line` (the innermost, if nested). */
+export function enclosingDecl(
+  xref: Xref,
+  file: string,
+  line: number,
+): { key: string; decl: XrefDecl } | null {
+  let best: { key: string; decl: XrefDecl } | null = null;
+  for (const [key, decl] of Object.entries(xref.decls)) {
+    if (decl.file !== file || (decl.kind !== 'function' && decl.kind !== 'modifier')) continue;
+    if (line < decl.line_start || line > decl.line_end) continue;
+    if (!best || decl.line_end - decl.line_start < best.decl.line_end - best.decl.line_start)
+      best = { key, decl };
+  }
+  return best;
+}

package/dashboard/lib/solidity.test.ts

@@ -0,0 +1,37 @@
+import { describe, it, expect } from 'vitest';
+import { applyRefs, highlightSolidity } from './solidity';
+
+describe('applyRefs', () => {
+  const line = '        IToken(token).transferFrom(msg.sender, address(this), amount);';
+  const toks = highlightSolidity(line)[0];
+  const at = (word: string) => line.indexOf(word);
+
+  it('cuts references out of tokens without changing the text', () => {
+    const segs = applyRefs(toks, [
+      { col: at('IToken'), len: 6, key: 'IToken', def: false },
+      { col: at('token)'), len: 5, key: 'Vault.token', def: false },
+      {
+        col: at('transferFrom'),
+        len: 12,
+        key: 'IToken.transferFrom(address,address,uint256)',
+        def: false,
+      },
+    ]);
+    expect(segs.map((s) => s.text).join('')).toBe(line);
+    expect(segs.filter((s) => s.ref).map((s) => [s.text, s.ref])).toEqual([
+      ['IToken', 'IToken'],
+      ['token', 'Vault.token'],
+      ['transferFrom', 'IToken.transferFrom(address,address,uint256)'],
+    ]);
+  });
+
+  it('marks a declaration name and leaves lines without references alone', () => {
+    const decl = '    function deposit(uint256 amount) external returns (uint256 shares) {';
+    const t = highlightSolidity(decl)[0];
+    const segs = applyRefs(t, [
+      { col: decl.indexOf('deposit'), len: 7, key: 'Vault.deposit(uint256)', def: true },
+    ]);
+    expect(segs.find((s) => s.ref)).toMatchObject({ text: 'deposit', def: true });
+    expect(applyRefs(t, [])).toBe(t);
+  });
+});

package/dashboard/lib/solidity.ts

@@ -0,0 +1,191 @@
+/**
+ * A minimal Solidity highlighter: comments, strings, numbers, keywords, types,
+ * built-ins and declared names. No dependency, and it returns tokens per line
+ * so the viewer can render line numbers and range highlights cheaply.
+ */
+export type TokenKind =
+  | 'plain'
+  | 'comment'
+  | 'string'
+  | 'number'
+  | 'keyword'
+  | 'type'
+  | 'builtin'
+  | 'fn';
+
+export interface Token {
+  kind: TokenKind;
+  text: string;
+}
+
+const KEYWORDS = new Set(
+  (
+    'pragma solidity import from as contract interface library abstract is function modifier event error struct enum ' +
+    'returns return if else for while do break continue emit revert using constructor fallback receive ' +
+    'public private internal external view pure payable constant immutable override virtual memory storage calldata ' +
+    'new delete unchecked assembly try catch indexed anonymous let type true false wei gwei ether seconds minutes hours days weeks'
+  ).split(' '),
+);
+
+const BUILTINS = new Set(
+  'msg block tx abi require assert this super selfdestruct keccak256 sha256 ecrecover addmod mulmod gasleft blockhash'.split(
+    ' ',
+  ),
+);
+
+const TYPE_RE =
+  /^(address|bool|string|bytes\d*|u?int\d*|fixed\d*x?\d*|ufixed\d*x?\d*|mapping|byte)$/;
+
+/** Tokenize a whole source file into lines of tokens. */
+export function highlightSolidity(source: string): Token[][] {
+  const lines: Token[][] = [[]];
+  const push = (kind: TokenKind, text: string) => {
+    const parts = text.split('\n');
+    parts.forEach((part, i) => {
+      if (i > 0) lines.push([]);
+      if (part) {
+        const line = lines[lines.length - 1];
+        const last = line[line.length - 1];
+        if (last && last.kind === kind) last.text += part;
+        else line.push({ kind, text: part });
+      }
+    });
+  };
+
+  let i = 0;
+  let expectName = false;
+  const n = source.length;
+  while (i < n) {
+    const ch = source[i];
+    const next = source[i + 1];
+
+    if (ch === '/' && next === '/') {
+      const end = source.indexOf('\n', i);
+      const stop = end === -1 ? n : end;
+      push('comment', source.slice(i, stop));
+      i = stop;
+      continue;
+    }
+    if (ch === '/' && next === '*') {
+      const end = source.indexOf('*/', i + 2);
+      const stop = end === -1 ? n : end + 2;
+      push('comment', source.slice(i, stop));
+      i = stop;
+      continue;
+    }
+    if (ch === '"' || ch === "'") {
+      let j = i + 1;
+      while (j < n && source[j] !== ch && source[j] !== '\n') {
+        if (source[j] === '\\') j++;
+        j++;
+      }
+      push('string', source.slice(i, Math.min(n, j + 1)));
+      i = Math.min(n, j + 1);
+      continue;
+    }
+    if (/[0-9]/.test(ch) || (ch === '.' && next && /[0-9]/.test(next))) {
+      const m = /^(0x[0-9a-fA-F_]+|[0-9][0-9_]*(\.[0-9_]+)?([eE][-+]?[0-9_]+)?)/.exec(
+        source.slice(i, i + 80),
+      );
+      const text = m ? m[0] : ch;
+      push('number', text);
+      i += text.length;
+      continue;
+    }
+    if (/[A-Za-z_$]/.test(ch)) {
+      const m = /^[A-Za-z_$][A-Za-z0-9_$]*/.exec(source.slice(i, i + 120));
+      const word = m ? m[0] : ch;
+      let kind: TokenKind = 'plain';
+      if (expectName) {
+        kind = 'fn';
+        expectName = false;
+      } else if (KEYWORDS.has(word)) {
+        kind = 'keyword';
+        if (
+          [
+            'function',
+            'modifier',
+            'event',
+            'error',
+            'contract',
+            'interface',
+            'library',
+            'struct',
+            'enum',
+          ].includes(word)
+        ) {
+          expectName = true;
+        }
+      } else if (TYPE_RE.test(word)) {
+        kind = 'type';
+      } else if (BUILTINS.has(word)) {
+        kind = 'builtin';
+      } else if (source[i + word.length] === '(' && /^[a-z_]/.test(word)) {
+        kind = 'fn';
+      }
+      push(kind, word);
+      i += word.length;
+      continue;
+    }
+    if (!/\s/.test(ch)) expectName = false;
+    push('plain', ch);
+    i++;
+  }
+  return lines;
+}
+
+/** A highlighted piece of a line; `ref` when it names a declaration the viewer can navigate to. */
+export interface Seg extends Token {
+  ref?: string;
+  /** The declaration's own name (navigating from it lists its callers and uses). */
+  def?: boolean;
+}
+
+export interface LineRef {
+  /** 0-based UTF-16 column. */
+  col: number;
+  len: number;
+  key: string;
+  def: boolean;
+}
+
+/**
+ * Split a line's tokens at reference boundaries so each reference becomes its
+ * own segment. Text and token kinds are unchanged; joining the segments gives
+ * the line back.
+ */
+export function applyRefs(tokens: Token[], refs: LineRef[]): Seg[] {
+  if (refs.length === 0) return tokens;
+  const sorted = [...refs].sort((a, b) => a.col - b.col);
+  const out: Seg[] = [];
+  let col = 0;
+  let ri = 0;
+  for (const t of tokens) {
+    const start = col;
+    const end = col + t.text.length;
+    let cursor = start;
+    while (cursor < end) {
+      while (ri < sorted.length && sorted[ri].col + sorted[ri].len <= cursor) ri++;
+      const r = sorted[ri];
+      if (!r || r.col >= end) {
+        out.push({ kind: t.kind, text: t.text.slice(cursor - start) });
+        break;
+      }
+      if (r.col > cursor) {
+        out.push({ kind: t.kind, text: t.text.slice(cursor - start, r.col - start) });
+        cursor = r.col;
+        continue;
+      }
+      const segEnd = Math.min(end, r.col + r.len);
+      out.push({
+        kind: t.kind,
+        text: t.text.slice(cursor - start, segEnd - start),
+        ref: r.key,
+        ...(r.def ? { def: true } : {}),
+      });
+      cursor = segEnd;
+    }
+    col = end;
+  }
+  return out;
+}

package/dashboard/lib/source.ts

@@ -0,0 +1,28 @@
+'use client';
+
+const cache = new Map<string, { at: number; code: Promise<string> }>();
+const TTL = 15_000;
+
+/** Whole-file source, cached briefly so moving between functions in one file is instant. */
+export function fetchSource(file: string): Promise<string> {
+  const hit = cache.get(file);
+  if (hit && Date.now() - hit.at < TTL) return hit.code;
+  const code = fetch(`/api/code?file=${encodeURIComponent(file)}`)
+    .then(async (r) => {
+      const data = (await r.json().catch(() => ({}))) as { code?: string; error?: string };
+      if (!r.ok || typeof data.code !== 'string')
+        throw new Error(data.error ?? 'Could not load the file');
+      return data.code;
+    })
+    .catch((err) => {
+      cache.delete(file);
+      throw err;
+    });
+  cache.set(file, { at: Date.now(), code });
+  return code;
+}
+
+/** Drop the cached copy of `file` (Hex just changed it on disk). */
+export function invalidateSource(file: string): void {
+  cache.delete(file);
+}

package/dashboard/lib/types.ts

@@ -0,0 +1,164 @@
+/**
+ * Shapes shared by server pages and client components. Type-only imports from
+ * src/types are erased at build time, so nothing from zod reaches the bundle.
+ */
+import type {
+  FactsFunction,
+  Invariant,
+  ProtocolModel,
+  DiagramIndexEntry,
+  FixReview,
+} from '../../src/types/index';
+
+export type { FactsFunction, Invariant, ProtocolModel, DiagramIndexEntry, FixReview };
+
+export type Severity = 'Critical' | 'High' | 'Medium' | 'Low' | 'Info';
+export type ReviewState = 'unread' | 'read' | 'questioned' | 'cleared';
+
+export const SEVERITY_ORDER: Record<string, number> = {
+  Critical: 0,
+  High: 1,
+  Medium: 2,
+  Low: 3,
+  Info: 4,
+};
+
+/** One row of the review map (src/core/review.ts FunctionReviewRow). */
+export interface ReviewRow {
+  id: string;
+  contract: string;
+  name: string;
+  file: string;
+  line_start: number;
+  line_end: number;
+  nsloc: number;
+  is_entry_point: boolean;
+  state: ReviewState;
+  by?: string;
+  updated_at?: string;
+  note?: string;
+  risk: number;
+  risk_reasons: string[];
+  ai_seen: boolean;
+  cards: string[];
+  diff_depth?: number;
+}
+
+export interface ReviewTotals {
+  facts_source: 'solc-ast' | 'parser-fallback' | null;
+  total_nsloc: number;
+  cleared_nsloc: number;
+  pct: number;
+  counts: Record<ReviewState, number>;
+}
+
+/** A card as the board and the inspectors see it. */
+export type BoardColumn = 'potential' | 'verified' | 'synced' | 'invalid' | 'duplicate';
+export type SyncState = 'none' | 'unsynced' | 'synced_open' | 'synced_closed' | 'conflict';
+export type IssueSource =
+  | 'manual'
+  | 'auditagent'
+  | 'ai-audit'
+  | 'conformance'
+  | 'github'
+  | 'prior-audit'
+  | 'invariant';
+export type PocStatus = 'passing' | 'failing' | 'not_started';
+
+export const SOURCE_LABEL: Record<string, string> = {
+  manual: 'Manual',
+  auditagent: 'AuditAgent',
+  'ai-audit': 'AI audit',
+  conformance: 'Conformance',
+  github: 'GitHub',
+  'prior-audit': 'Prior audit',
+  invariant: 'Invariant',
+};
+
+export interface CardValidation {
+  verdict?: 'reproduced' | 'refuted' | 'uncertain' | 'valid_no_poc';
+  validated_by?: 'auditor' | 'agent';
+  memo?: string;
+  poc_file?: string;
+  poc_status?: PocStatus;
+  refuters?: number;
+  auto_moved_to?: 'verified' | 'rejected';
+  reverted_at?: string;
+  at?: string;
+}
+
+export interface BoardIssue {
+  id: string;
+  title: string;
+  severity: Severity;
+  source: IssueSource;
+  status: string;
+  column: BoardColumn;
+  description: string;
+  recommendation: string;
+  resolution?: string;
+  update_from_client?: string;
+  code_locations: Array<{ file: string; snippet?: string }>;
+  github_issue_url?: string;
+  github_issue_number?: number;
+  github_state?: string;
+  sync_state: SyncState;
+  duplicate_of: string | null;
+  match_signals?: {
+    contract: boolean;
+    function: boolean;
+    root_cause: string;
+    attack_vector: string;
+  };
+  reasoning?: string;
+  category?: string;
+  poc_status?: PocStatus;
+  poc_file?: string | null;
+  notes: string;
+  source_ref?: string | null;
+  validation?: CardValidation;
+  /** Function ids the card's code points into. */
+  functions: string[];
+}
+
+/** A compact card reference for inspectors on other pages. */
+export interface CardRef {
+  id: string;
+  title: string;
+  severity: Severity;
+  column: BoardColumn;
+}
+
+/** Diane note pieces shown in the Review inspector. */
+export interface NoteFn {
+  id: string;
+  sig: string;
+  fn_ref?: string;
+  purpose?: string;
+  access?: string;
+  effects?: string;
+  notes: string[];
+  warnings: string[];
+}
+export interface NoteQuestion {
+  id: string;
+  q: string;
+  answer?: string;
+}
+export interface NoteLead {
+  id: string;
+  text: string;
+  status: 'open' | 'logged' | 'dismissed';
+  ref?: string;
+  source?: string;
+}
+export interface ContractNoteView {
+  /** The note target in use (may be `Vault.sol` while the contract is `Vault`). */
+  target: string;
+  contract: string;
+  marked_done: boolean;
+  purpose: string[];
+  functions: NoteFn[];
+  questions: NoteQuestion[];
+  leads: NoteLead[];
+}

package/dashboard/lib/url.ts

@@ -0,0 +1,18 @@
+'use client';
+
+/**
+ * Keep the selection in the URL without a server round trip (Next 14.1+
+ * syncs window.history with useSearchParams), so reloads and ⌘K deep links
+ * land on the same item.
+ */
+export function replaceQuery(params: Record<string, string | null>): void {
+  const url = new URL(window.location.href);
+  for (const [k, v] of Object.entries(params)) {
+    if (v === null) url.searchParams.delete(k);
+    else url.searchParams.set(k, v);
+  }
+  const next = url.pathname + (url.searchParams.toString() ? `?${url.searchParams}` : '');
+  if (next !== window.location.pathname + window.location.search) {
+    window.history.replaceState(window.history.state, '', next);
+  }
+}

package/dashboard/lib/watcher.ts

@@ -5,40 +5,49 @@ let watcher: chokidar.FSWatcher | null = null;
 const listeners = new Set<(file: string) => void>();
 
 /**
- * Initialize file watcher for the output directory.
+ * Files the dashboard itself writes on every selection (focus.json) or that
+ * are scratch (atomic-write temps, caches, raw audio) must not trigger a
+ * refresh — otherwise selecting something would re-render the page.
  */
+function ignored(rel: string): boolean {
+  return (
+    rel === 'focus.json' ||
+    rel.endsWith('.tmp') ||
+    rel.startsWith('.cache/') ||
+    rel.startsWith('notes/audio/') ||
+    rel.split('/').some((s) => s === 'node_modules')
+  );
+}
+
+/** Watch `.hex/` for data the dashboard renders, including diagrams and report figures. */
 export function initWatcher(outputDir: string): void {
   if (watcher) return;
 
   watcher = chokidar.watch(
-    path.join(outputDir, '**/*.{json,md,mmd}'),
+    [
+      path.join(outputDir, '**/*.{json,md,mmd,txt,tex,excalidraw}'),
+      path.join(outputDir, 'ai-audit/**/*.tsv'),
+      path.join(outputDir, 'report/figures/*.png'),
+    ],
     {
       ignoreInitial: true,
-      awaitWriteFinish: {
-        stabilityThreshold: 300,
-        pollInterval: 100,
-      },
+      ignored: (p: string) =>
+        /[\\/]\.cache([\\/]|$)|[\\/]node_modules([\\/]|$)|[\\/]notes[\\/]audio([\\/]|$)/.test(p),
+      awaitWriteFinish: { stabilityThreshold: 250, pollInterval: 100 },
     },
   );
 
-  watcher.on('change', (filePath) => {
-    const relative = path.relative(outputDir, filePath).replace(/\\/g, '/');
-    for (const listener of listeners) {
-      listener(relative);
-    }
-  });
-
-  watcher.on('add', (filePath) => {
-    const relative = path.relative(outputDir, filePath).replace(/\\/g, '/');
-    for (const listener of listeners) {
-      listener(relative);
-    }
-  });
+  const emit = (filePath: string) => {
+    const rel = path.relative(outputDir, filePath).replace(/\\/g, '/');
+    if (ignored(rel)) return;
+    for (const l of listeners) l(rel);
+  };
+  watcher.on('change', emit);
+  watcher.on('add', emit);
+  watcher.on('unlink', emit);
 }
 
-/**
- * Subscribe to file change events.
- */
+/** Subscribe to file change events. */
 export function onFileChange(callback: (file: string) => void): () => void {
   listeners.add(callback);
   return () => listeners.delete(callback);

package/dashboard/tailwind.config.ts

@@ -40,7 +40,7 @@ const config: Config = {
           DEFAULT: 'var(--accent)',
           subtle: 'var(--accent-subtle)',
           secondary: 'var(--accent-secondary)',
-          warm: 'var(--accent-warm)',
+          contrast: 'var(--accent-contrast)',
         },
         severity: {
           critical: 'var(--critical)',
@@ -71,11 +71,14 @@ const config: Config = {
         md: 'var(--shadow-md)',
         lg: 'var(--shadow-lg)',
       },
+      transitionTimingFunction: {
+        out: 'var(--ease-out)',
+      },
       fontSize: {
         display: ['28px', { lineHeight: '1.2', fontWeight: '600' }],
-        title:   ['20px', { lineHeight: '1.3', fontWeight: '600' }],
+        title: ['20px', { lineHeight: '1.3', fontWeight: '600' }],
         heading: ['15px', { lineHeight: '1.4', fontWeight: '500' }],
-        body:    ['14px', { lineHeight: '1.55', fontWeight: '400' }],
+        body: ['14px', { lineHeight: '1.55', fontWeight: '400' }],
         caption: ['12px', { lineHeight: '1.4', fontWeight: '400' }],
       },
     },