@monoes/monograph 1.0.0 → 1.2.0

package/src/storage/suppressions.ts

@@ -0,0 +1,145 @@
+import type Database from 'better-sqlite3';
+import { randomUUID } from 'crypto';
+
+export interface Suppression {
+  id: string;
+  filePath: string;
+  line: number;     // 0 = file-wide
+  rule: string;
+  addedAt: string;
+  lastSeenAt?: string;
+}
+
+export interface StaleSuppression extends Suppression {
+  reason: string;  // 'issue_resolved' | 'file_deleted'
+}
+
+// Add a suppression
+export function addSuppression(
+  db: Database.Database,
+  filePath: string,
+  line: number,
+  rule: string,
+): Suppression {
+  const id = randomUUID();
+  const addedAt = new Date().toISOString();
+
+  db.prepare(`
+    INSERT INTO suppressions (id, file_path, line, rule, added_at, last_seen_at)
+    VALUES (?, ?, ?, ?, ?, NULL)
+  `).run(id, filePath, line, rule, addedAt);
+
+  return { id, filePath, line, rule, addedAt };
+}
+
+// List all suppressions (optionally filter by rule or file)
+export function listSuppressions(
+  db: Database.Database,
+  filePath?: string,
+  rule?: string,
+): Suppression[] {
+  let sql = `SELECT id, file_path, line, rule, added_at, last_seen_at FROM suppressions WHERE 1=1`;
+  const params: unknown[] = [];
+
+  if (filePath) {
+    sql += ` AND file_path = ?`;
+    params.push(filePath);
+  }
+  if (rule) {
+    sql += ` AND rule = ?`;
+    params.push(rule);
+  }
+  sql += ` ORDER BY added_at DESC`;
+
+  const rows = db.prepare(sql).all(...params) as {
+    id: string;
+    file_path: string;
+    line: number;
+    rule: string;
+    added_at: string;
+    last_seen_at: string | null;
+  }[];
+
+  return rows.map(r => ({
+    id: r.id,
+    filePath: r.file_path,
+    line: r.line,
+    rule: r.rule,
+    addedAt: r.added_at,
+    ...(r.last_seen_at != null ? { lastSeenAt: r.last_seen_at } : {}),
+  }));
+}
+
+// Remove a suppression
+export function removeSuppression(db: Database.Database, id: string): void {
+  db.prepare(`DELETE FROM suppressions WHERE id = ?`).run(id);
+}
+
+// Check if a finding is suppressed
+// A suppression with line=0 is file-wide and matches any line for the same file+rule
+export function isSuppressed(
+  db: Database.Database,
+  filePath: string,
+  line: number,
+  rule: string,
+): Suppression | null {
+  const row = db.prepare(`
+    SELECT id, file_path, line, rule, added_at, last_seen_at
+    FROM suppressions
+    WHERE file_path = ? AND rule = ? AND (line = 0 OR line = ?)
+    LIMIT 1
+  `).get(filePath, rule, line) as {
+    id: string;
+    file_path: string;
+    line: number;
+    rule: string;
+    added_at: string;
+    last_seen_at: string | null;
+  } | undefined;
+
+  if (!row) return null;
+
+  return {
+    id: row.id,
+    filePath: row.file_path,
+    line: row.line,
+    rule: row.rule,
+    addedAt: row.added_at,
+    ...(row.last_seen_at != null ? { lastSeenAt: row.last_seen_at } : {}),
+  };
+}
+
+// Find stale suppressions
+// A suppression is stale if:
+//   - the file no longer exists in the graph (reason: 'file_deleted')
+//   - the file exists but no active finding matches file+rule (reason: 'issue_resolved')
+export function findStaleSuppressions(
+  db: Database.Database,
+  activeFindings: Array<{ filePath: string; rule: string }>,
+): StaleSuppression[] {
+  const suppressions = listSuppressions(db);
+  if (suppressions.length === 0) return [];
+
+  // Build a set of all file paths in the graph
+  const graphFiles = new Set<string>(
+    (db.prepare(`SELECT DISTINCT file_path FROM nodes WHERE file_path IS NOT NULL`).all() as { file_path: string }[])
+      .map(r => r.file_path),
+  );
+
+  // Build a set of active finding keys: "filePath::rule"
+  const activeFindingKeys = new Set<string>(
+    activeFindings.map(f => `${f.filePath}::${f.rule}`),
+  );
+
+  const stale: StaleSuppression[] = [];
+
+  for (const s of suppressions) {
+    if (!graphFiles.has(s.filePath)) {
+      stale.push({ ...s, reason: 'file_deleted' });
+    } else if (!activeFindingKeys.has(`${s.filePath}::${s.rule}`)) {
+      stale.push({ ...s, reason: 'issue_resolved' });
+    }
+  }
+
+  return stale;
+}

package/src/storage/unlinked-refs.ts

@@ -0,0 +1,117 @@
+import type Database from 'better-sqlite3';
+
+export interface UnlinkedReference {
+  sourceId: string;
+  sourceName: string;
+  sourceFilePath: string | null;
+  sourceLabel: string;
+  targetName: string;   // the symbol that was mentioned
+  mentionContext: string | null; // snippet of where it was mentioned (from properties.summary)
+  confidence: 'high' | 'medium' | 'low';
+}
+
+/**
+ * Find nodes that mention a target symbol by name in their metadata
+ * (summary, file_path, norm_label) but have no explicit edge to any node
+ * with that name. These are "mentioned but not linked" — latent coupling.
+ *
+ * @param db - open monograph database
+ * @param targetName - symbol name to search for (e.g. "UserService")
+ * @param options.limit - max results (default 50)
+ * @param options.excludeSourceId - skip this node id (avoid self-match)
+ */
+export function findUnlinkedReferences(
+  db: Database.Database,
+  targetName: string,
+  options: { limit?: number; excludeSourceId?: string } = {},
+): UnlinkedReference[] {
+  const limit = options.limit ?? 50;
+  const excludeSourceId = options.excludeSourceId ?? '';
+  const pattern = `%${targetName}%`;
+
+  // Step 1: Find all node IDs that already have an explicit edge to any node
+  // whose name matches targetName — these are "already linked" and excluded.
+  const linkedRows = db.prepare(`
+    SELECT DISTINCT e.source_id FROM edges e
+    JOIN nodes n ON n.id = e.target_id
+    WHERE n.name = ?
+  `).all(targetName) as { source_id: string }[];
+
+  const linkedIds = new Set(linkedRows.map(r => r.source_id));
+
+  // Step 2: Find nodes that mention targetName in name, norm_label, or
+  // properties JSON — but are NOT in the linked set and not self.
+  const rows = db.prepare(`
+    SELECT n.id, n.name, n.file_path, n.label, n.properties
+    FROM nodes n
+    WHERE (
+      n.name LIKE ? OR
+      n.norm_label LIKE ? OR
+      (n.properties IS NOT NULL AND n.properties LIKE ?)
+    )
+    AND n.name != ?
+    LIMIT ?
+  `).all(pattern, pattern, pattern, targetName, limit * 4) as Array<{
+    id: string;
+    name: string;
+    file_path: string | null;
+    label: string;
+    properties: string | null;
+  }>;
+
+  const results: UnlinkedReference[] = [];
+
+  for (const row of rows) {
+    // Skip nodes that already have an explicit edge to the target
+    if (linkedIds.has(row.id)) continue;
+    // Skip the excluded node (e.g. the target node itself)
+    if (excludeSourceId && row.id === excludeSourceId) continue;
+
+    // Determine confidence and extract mention context
+    let confidence: 'high' | 'medium' | 'low';
+    let mentionContext: string | null = null;
+
+    if (row.name.includes(targetName)) {
+      // Target name appears in the symbol's own name
+      confidence = 'high';
+    } else if (row.file_path !== null && row.file_path.includes(targetName)) {
+      // Appears in the file path
+      confidence = 'medium';
+    } else {
+      // Only in properties.summary
+      confidence = 'low';
+    }
+
+    // Extract a 100-char context window from properties.summary if available
+    if (row.properties !== null) {
+      try {
+        const props = JSON.parse(row.properties) as Record<string, unknown>;
+        const summary = typeof props['summary'] === 'string' ? props['summary'] : null;
+        if (summary !== null && summary.includes(targetName)) {
+          const idx = summary.indexOf(targetName);
+          const start = Math.max(0, idx - 50);
+          const end = Math.min(summary.length, idx + targetName.length + 50);
+          mentionContext = summary.slice(start, end);
+          // Refine confidence: if we previously set 'low' due to no name/path match,
+          // and properties match confirms it, keep 'low'. Otherwise stay as-is.
+        }
+      } catch {
+        // Malformed JSON — skip
+      }
+    }
+
+    results.push({
+      sourceId: row.id,
+      sourceName: row.name,
+      sourceFilePath: row.file_path,
+      sourceLabel: row.label,
+      targetName,
+      mentionContext,
+      confidence,
+    });
+
+    if (results.length >= limit) break;
+  }
+
+  return results;
+}

package/src/types.ts

@@ -5,7 +5,8 @@ export type NodeLabel =
   | 'Variable' | 'Struct' | 'Enum' | 'Macro' | 'Typedef' | 'Union'
   | 'Namespace' | 'Trait' | 'Impl' | 'TypeAlias' | 'Const' | 'Static'
   | 'Property' | 'Record' | 'Delegate' | 'Annotation' | 'Constructor'
-  | 'Template' | 'Module' | 'Process' | 'Route' | 'Community' | 'Concept';
+  | 'Template' | 'Module' | 'Process' | 'Route' | 'Community' | 'Concept'
+  | 'Section' | 'Document' | 'Tool' | 'Entity' | 'Field';
 
 export const SYMBOL_NODE_LABELS = new Set<NodeLabel>([
   'Function', 'Class', 'Method', 'Interface', 'Variable', 'Struct', 'Enum',
@@ -17,10 +18,15 @@ export const SYMBOL_NODE_LABELS = new Set<NodeLabel>([
 // ── Edge relations ────────────────────────────────────────────────────────────
 
 export type EdgeRelation =
-  | 'CONTAINS' | 'DEFINES' | 'CALLS' | 'IMPORTS' | 'EXTENDS' | 'IMPLEMENTS'
+  | 'CONTAINS' | 'DEFINES' | 'CALLS' | 'IMPORTS' | 'RE_EXPORTS' | 'EXTENDS' | 'IMPLEMENTS'
   | 'HAS_METHOD' | 'HAS_PROPERTY' | 'ACCESSES' | 'METHOD_OVERRIDES'
   | 'METHOD_IMPLEMENTS' | 'MEMBER_OF' | 'STEP_IN_PROCESS' | 'HANDLES_ROUTE'
-  | 'FETCHES' | 'HANDLES_TOOL' | 'ENTRY_POINT_OF' | 'WRAPS' | 'QUERIES';
+  | 'FETCHES' | 'HANDLES_TOOL' | 'ENTRY_POINT_OF' | 'WRAPS' | 'QUERIES'
+  | 'REFERENCES' | 'PARENT_SECTION' | 'TAGGED_AS' | 'HAS_FIELD'
+  // Doc KG — contextual proximity
+  | 'CO_OCCURS'
+  // Doc KG — LLM-inferred semantic relations
+  | 'DESCRIBES' | 'CAUSES' | 'CONTRASTS_WITH' | 'PART_OF' | 'RELATED_TO' | 'USES' | 'STRUCTURALLY_SIMILAR';
 
 // ── Confidence ────────────────────────────────────────────────────────────────
 
@@ -45,9 +51,18 @@ export interface MonographNode {
   communityId?: number;
   isExported: boolean;
   language?: string;
+  reachabilityRole?: 'runtime' | 'test' | 'support' | 'unreachable';
   properties?: Record<string, unknown>;
 }
 
+// ── Evidence ──────────────────────────────────────────────────────────────────
+
+export interface EvidenceEntry {
+  kind: string;      // e.g., 'import', 'call', 'heuristic', 'inferred'
+  weight: number;    // 0-1
+  note?: string;     // human-readable explanation
+}
+
 // ── Edges ─────────────────────────────────────────────────────────────────────
 
 export interface MonographEdge {
@@ -57,6 +72,9 @@ export interface MonographEdge {
   relation: EdgeRelation;
   confidence: EdgeConfidence;
   confidenceScore: number;
+  weight?: number;
+  reason?: string;
+  evidence?: EvidenceEntry[];
 }
 
 // ── Communities ───────────────────────────────────────────────────────────────
@@ -76,6 +94,22 @@ export interface GodNode extends MonographNode {
   outDegree: number;
 }
 
+// ── Complexity metrics ────────────────────────────────────────────────────────
+
+export interface ComplexityMetrics {
+  cyclomaticComplexity: number;
+  cognitiveComplexity: number;
+  linesOfCode: number;
+  paramCount: number;
+}
+
+export interface CrapScore {
+  cc: number;
+  coverage: number;   // 0-1
+  score: number;      // CC² × (1-coverage)³ + CC
+  risk: 'low' | 'medium' | 'high' | 'critical';
+}
+
 // ── Surprising connections ────────────────────────────────────────────────────
 
 export interface SurprisingConnection {
@@ -91,7 +125,39 @@ export type SuggestedQuestion =
   | { type: 'bridge_node'; node: MonographNode; commA: number; commB: number }
   | { type: 'verify_inferred'; edge: MonographEdge; inferredFrom: string }
   | { type: 'isolated_nodes'; nodes: MonographNode[]; reason: string }
-  | { type: 'low_cohesion'; community: MonographCommunity };
+  | { type: 'low_cohesion'; community: MonographCommunity }
+  | { type: 'no_signal'; edge: MonographEdge; reason: string }
+  | { type: 'thin_community'; communityId: number; memberCount: number; reason: string };
+
+// ── Finding actions (structured remediation steps) ────────────────────────────
+
+export type FindingActionType =
+  | 'investigate'     // read/understand the file
+  | 'refactor'        // reduce complexity or coupling
+  | 'delete'          // safe to remove
+  | 'add-test'        // add test coverage
+  | 'add-import'      // add missing import edge
+  | 'extract'         // extract to separate module
+  | 'review'          // human review required
+  | 'add-edge';       // add explicit graph relationship
+
+export interface FindingAction {
+  type: FindingActionType;
+  file?: string;       // target file path
+  symbol?: string;     // specific symbol/export name
+  description: string; // human-readable instruction
+  confidence: 'high' | 'medium' | 'low';
+}
+
+export interface AnnotatedFinding {
+  title: string;
+  severity: 'error' | 'warning' | 'info';
+  nodeId?: string;
+  nodeName?: string;
+  filePath?: string | null;
+  introduced?: boolean;
+  actions: FindingAction[];
+}
 
 // ── ID generation ─────────────────────────────────────────────────────────────
 

package/src/validation/extraction-validator.ts

@@ -0,0 +1,54 @@
+import type { MonographNode, MonographEdge, EdgeConfidence, NodeLabel } from '../types.js';
+
+export interface ValidationResult {
+  valid: boolean;
+  errors: string[];
+}
+
+const VALID_LABELS = new Set<NodeLabel>([
+  'File', 'Folder', 'Function', 'Class', 'Method', 'Interface',
+  'Variable', 'Struct', 'Enum', 'Macro', 'Typedef', 'Union',
+  'Namespace', 'Trait', 'Impl', 'TypeAlias', 'Const', 'Static',
+  'Property', 'Record', 'Delegate', 'Annotation', 'Constructor',
+  'Template', 'Module', 'Process', 'Route', 'Community', 'Concept',
+  'Document', 'Tool', 'Entity', 'Field',
+]);
+
+const VALID_CONFIDENCES = new Set<EdgeConfidence>(['EXTRACTED', 'INFERRED', 'AMBIGUOUS']);
+
+export function validateExtraction(
+  nodes: MonographNode[],
+  edges: MonographEdge[],
+): ValidationResult {
+  const errors: string[] = [];
+  const nodeIds = new Set(nodes.map(n => n.id));
+
+  for (const n of nodes) {
+    if (!n.id) errors.push(`Node missing id: ${JSON.stringify(n.name)}`);
+    if (!n.name) errors.push(`Node ${n.id} missing name`);
+    if (!VALID_LABELS.has(n.label as NodeLabel)) {
+      errors.push(`Node ${n.id} has invalid label: ${n.label}`);
+    }
+    if (typeof n.isExported !== 'boolean') {
+      errors.push(`Node ${n.id}: isExported must be boolean`);
+    }
+  }
+
+  for (const e of edges) {
+    if (!e.id) errors.push(`Edge missing id`);
+    if (!nodeIds.has(e.sourceId)) {
+      errors.push(`Edge ${e.id}: sourceId '${e.sourceId}' references unknown node`);
+    }
+    if (!nodeIds.has(e.targetId)) {
+      errors.push(`Edge ${e.id}: targetId '${e.targetId}' references unknown node`);
+    }
+    if (!VALID_CONFIDENCES.has(e.confidence)) {
+      errors.push(`Edge ${e.id}: invalid confidence '${e.confidence}'`);
+    }
+    if (typeof e.confidenceScore !== 'number') {
+      errors.push(`Edge ${e.id}: confidenceScore must be number`);
+    }
+  }
+
+  return { valid: errors.length === 0, errors };
+}

package/src/watch/watch-runner.ts

@@ -0,0 +1,64 @@
+import { extname, basename, relative } from 'node:path';
+
+const SOURCE_EXTENSIONS = new Set([
+  'ts','tsx','mts','cts','js','jsx','mjs','cjs',
+  'vue','svelte','astro','mdx','css','scss',
+]);
+
+const CONFIG_FILENAMES = new Set([
+  'package.json', '.fallowrc.json', '.fallowrc.jsonc',
+  'fallow.toml', '.fallow.toml', 'tsconfig.json',
+  'monograph.json', 'monograph.config.json', '.monographrc.json',
+]);
+
+export function isRelevantSource(filePath: string): boolean {
+  const ext = extname(filePath).replace('.', '');
+  return SOURCE_EXTENSIONS.has(ext);
+}
+
+export function isRelevantConfig(filePath: string): boolean {
+  return CONFIG_FILENAMES.has(basename(filePath));
+}
+
+export function collectChangedPaths(rawPaths: string[], root: string): string[] {
+  const seen = new Set<string>();
+  const result: string[] = [];
+  for (const p of rawPaths) {
+    if (!isRelevantSource(p) && !isRelevantConfig(p)) continue;
+    const rel = relative(root, p);
+    if (!seen.has(rel)) { seen.add(rel); result.push(rel); }
+  }
+  return result;
+}
+
+export interface WatchRunnerOptions {
+  root: string;
+  noCache?: boolean;
+  quiet?: boolean;
+  clearScreen?: boolean;
+  debounceMs?: number;
+  includeEntryExports?: boolean;
+  onAnalysis: (changedPaths: string[]) => Promise<void>;
+  loadConfig: () => Promise<unknown>;
+}
+
+export async function reloadConfigOrKeepPrevious<T>(
+  current: T,
+  loader: () => Promise<T>,
+  onError?: (err: unknown) => void,
+): Promise<T> {
+  try {
+    return await loader();
+  } catch (err) {
+    onError?.(err);
+    return current;
+  }
+}
+
+export function debounce<T extends (...args: unknown[]) => void>(fn: T, ms: number): T {
+  let timer: ReturnType<typeof setTimeout> | null = null;
+  return ((...args: unknown[]) => {
+    if (timer !== null) clearTimeout(timer);
+    timer = setTimeout(() => { timer = null; fn(...args); }, ms);
+  }) as T;
+}

package/src/watch/watcher.ts

@@ -1,6 +1,7 @@
 import chokidar from 'chokidar';
 import { EventEmitter } from 'events';
 import { isSupportedExtension } from '../parsers/loader.js';
+import type { PipelineProgress } from '../types.js';
 import { extname } from 'path';
 import { platform } from 'os';
 
@@ -8,6 +9,31 @@ export interface WatcherOptions {
   debounceMs?: number;  // default 3000ms
 }
 
+export interface WatchAsyncOptions extends WatcherOptions {
+  onProgress?: (p: PipelineProgress) => void;
+  force?: boolean;
+  codeOnly?: boolean;
+  llmMaxSections?: number;
+}
+
+/** Convenience: start a watcher and trigger buildAsync on every change. Returns stop() fn. */
+export async function watchAsync(
+  repoPath: string,
+  opts: WatchAsyncOptions = {},
+): Promise<{ stop: () => Promise<void> }> {
+  const { buildAsync } = await import('../pipeline/orchestrator.js');
+  const watcher = new MonographWatcher(repoPath, { debounceMs: opts.debounceMs ?? 3000 });
+
+  watcher.on('monograph:updated', async (files: string[]) => {
+    opts.onProgress?.({ phase: 'watch', message: `Changed: ${files.slice(0, 3).join(', ')}` });
+    await buildAsync(repoPath, { onProgress: opts.onProgress, force: opts.force, codeOnly: opts.codeOnly, llmMaxSections: opts.llmMaxSections ?? 0 });
+    opts.onProgress?.({ phase: 'watch', message: 'Graph rebuilt.' });
+  });
+
+  await watcher.start();
+  return { stop: () => watcher.stop() };
+}
+
 export class MonographWatcher extends EventEmitter {
   private watcher: chokidar.FSWatcher | null = null;
   private debounceTimer: ReturnType<typeof setTimeout> | null = null;

package/src/web/analyze-api.ts

@@ -0,0 +1,144 @@
+import type { Server, IncomingMessage, ServerResponse } from 'http';
+import { buildAsync } from '../pipeline/orchestrator.js';
+import { countNodes } from '../storage/node-store.js';
+import { countEdges } from '../storage/edge-store.js';
+import { openDb, closeDb } from '../storage/db.js';
+import { resolve, join, sep } from 'path';
+
+// ── Types ─────────────────────────────────────────────────────────────────────
+
+export interface AnalyzeRequest {
+  repoPath: string;
+  codeOnly?: boolean;
+  force?: boolean;
+}
+
+export interface AnalyzeProgressEvent {
+  type: 'progress' | 'complete' | 'error';
+  phase?: string;
+  message?: string;
+  error?: string;
+  nodeCount?: number;
+  edgeCount?: number;
+}
+
+// ── SSE helpers ───────────────────────────────────────────────────────────────
+
+function sendEvent(res: ServerResponse, event: AnalyzeProgressEvent): void {
+  res.write(`data: ${JSON.stringify(event)}\n\n`);
+}
+
+function parseQueryParams(url: string): { repoPath?: string; codeOnly?: boolean; force?: boolean } {
+  const parsed = new URL(url, 'http://localhost');
+  const repoPath = parsed.searchParams.get('repoPath') ?? undefined;
+  const codeOnly = parsed.searchParams.has('codeOnly')
+    ? parsed.searchParams.get('codeOnly') !== 'false'
+    : undefined;
+  const force = parsed.searchParams.has('force')
+    ? parsed.searchParams.get('force') !== 'false'
+    : undefined;
+  return { repoPath, codeOnly, force };
+}
+
+// ── Route handler ─────────────────────────────────────────────────────────────
+
+async function handleAnalyze(req: IncomingMessage, res: ServerResponse): Promise<void> {
+  const { repoPath, codeOnly, force } = parseQueryParams(req.url ?? '/');
+
+  if (!repoPath) {
+    res.writeHead(400, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify({ error: 'repoPath query parameter is required' }));
+    return;
+  }
+
+  // Set SSE headers
+  res.writeHead(200, {
+    'Content-Type': 'text/event-stream',
+    'Cache-Control': 'no-cache',
+    'Connection': 'keep-alive',
+    'Access-Control-Allow-Origin': 'http://localhost',
+  });
+
+  const dbPath = resolve(join(repoPath, '.monomind', 'monograph.db'));
+
+  try {
+    await buildAsync(repoPath, {
+      codeOnly,
+      force,
+      onProgress: (p) => {
+        sendEvent(res, {
+          type: 'progress',
+          phase: p.phase,
+          message: p.message,
+        });
+      },
+    });
+
+    const db = openDb(dbPath);
+    try {
+      const nodeCount = countNodes(db);
+      const edgeCount = countEdges(db);
+      sendEvent(res, { type: 'complete', nodeCount, edgeCount });
+    } finally {
+      closeDb(db);
+    }
+  } catch (err) {
+    sendEvent(res, { type: 'error', error: `Build failed: ${String(err)}` });
+  } finally {
+    res.end();
+  }
+}
+
+// ── Route registration ────────────────────────────────────────────────────────
+
+/**
+ * Register the /api/analyze SSE endpoint on an existing HTTP server.
+ *
+ * GET /api/analyze?repoPath=<path>&codeOnly=<bool>&force=<bool>
+ *
+ * Responds with Content-Type: text/event-stream
+ * Emits:
+ *   data: {"type":"progress","phase":"scan","message":"Scanning files..."}\n\n
+ *   data: {"type":"complete","nodeCount":123,"edgeCount":456}\n\n
+ *   (or on error)
+ *   data: {"type":"error","error":"Build failed: ..."}\n\n
+ */
+export function registerAnalyzeRoute(
+  server: Server,
+  pathPrefix: string = '/api',
+  /** Allowlisted repo root — only this path (and its subdirectories) may be analyzed */
+  allowedRepoRoot?: string,
+): void {
+  const analyzePath = `${pathPrefix}/analyze`;
+
+  server.on('request', (req: IncomingMessage, res: ServerResponse) => {
+    const url = req.url ?? '/';
+    const pathname = url.split('?')[0];
+
+    if (pathname !== analyzePath || req.method !== 'GET') return;
+
+    // DNS rebinding protection: reject requests with a non-localhost Host header
+    const host = ((req.headers['host'] ?? '').split(':')[0] ?? '').toLowerCase();
+    if (host !== 'localhost' && host !== '127.0.0.1' && host !== '::1' && host !== '') {
+      res.writeHead(403, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ error: 'Forbidden' }));
+      return;
+    }
+
+    // If an allowedRepoRoot was provided, enforce it before handling
+    if (allowedRepoRoot) {
+      const { repoPath } = parseQueryParams(url);
+      if (repoPath) {
+        const resolved = resolve(repoPath);
+        const root = resolve(allowedRepoRoot);
+        if (resolved !== root && !resolved.startsWith(root + sep)) {
+          res.writeHead(403, { 'Content-Type': 'application/json' });
+          res.end(JSON.stringify({ error: 'repoPath outside allowed root' }));
+          return;
+        }
+      }
+    }
+
+    void handleAnalyze(req, res);
+  });
+}