tenbo-dashboard 0.1.0

package/src/api/lib/health/agingTodos.ts

@@ -0,0 +1,97 @@
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { execSync } from 'node:child_process';
+import type { Finding, Severity } from './types';
+import type { HealthConfig } from './config';
+
+interface TodoMatch { line: number; text: string }
+
+/**
+ * Find TODO|FIXME markers in single-line and block comments. Crude but
+ * sufficient: we strip string literals before scanning to avoid false positives.
+ */
+export function parseTodoLines(source: string): TodoMatch[] {
+  const stripped = source.replace(/(["'`])(?:\\.|(?!\1).)*\1/g, (m) => ' '.repeat(m.length));
+  const lines = stripped.split('\n');
+  const out: TodoMatch[] = [];
+  for (let i = 0; i < lines.length; i++) {
+    const m = /(?:\/\/|\/\*|\*)\s*(TODO|FIXME)\b[^\n]*/i.exec(lines[i]);
+    if (!m) continue;
+    out.push({ line: i + 1, text: m[0].replace(/^[/*\s]+/, '') });
+  }
+  return out;
+}
+
+interface BlameInfo { author: string; commitHash: string; ageDays: number }
+
+function gitBlameLine(repoRoot: string, relPath: string, line: number): BlameInfo | null {
+  try {
+    const out = execSync(`git blame --line-porcelain -L ${line},${line} -- "${relPath}"`, {
+      cwd: repoRoot, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'],
+    });
+    const commitHash = out.split('\n')[0]?.split(' ')[0] ?? '';
+    const authorMatch = /^author (.+)$/m.exec(out);
+    const timeMatch = /^author-time (\d+)$/m.exec(out);
+    if (!commitHash || !timeMatch) return null;
+    const ts = Number(timeMatch[1]) * 1000;
+    const ageDays = Math.floor((Date.now() - ts) / (24 * 3600 * 1000));
+    return { author: authorMatch?.[1] ?? 'unknown', commitHash, ageDays };
+  } catch {
+    return null;
+  }
+}
+
+function severityForAge(ageDays: number, thresholds: HealthConfig['thresholds']['todo_age_months']): Severity | null {
+  const months = ageDays / 30;
+  if (months >= thresholds.critical) return 'critical';
+  if (months >= thresholds.warning) return 'warning';
+  if (months >= thresholds.info) return 'info';
+  return null;
+}
+
+export function analyzeAgingTodos(
+  repoRoot: string,
+  layerId: string,
+  files: string[],
+  config: HealthConfig,
+): Finding[] {
+  const findings: Finding[] = [];
+  for (const rel of files) {
+    let src: string;
+    try { src = readFileSync(path.resolve(repoRoot, rel), 'utf8'); } catch { continue; }
+    const todos = parseTodoLines(src);
+    if (todos.length === 0) continue;
+    const lines = src.split('\n');
+    for (const t of todos) {
+      const blame = gitBlameLine(repoRoot, rel, t.line);
+      if (!blame) continue;
+      const severity = severityForAge(blame.ageDays, config.thresholds.todo_age_months);
+      if (!severity) continue;
+      const ctx = lines.slice(Math.max(0, t.line - 2), t.line + 1).join('\n');
+      findings.push({
+        id: `${layerId}.aging-todos.${rel.replace(/\W/g, '_')}_${t.line}`,
+        signal: 'aging-todos',
+        severity,
+        confidence: 'high',
+        layer: layerId,
+        target: rel,
+        headline: `${path.basename(rel)}:${t.line} — ${blame.ageDays}d old`,
+        suggestion: {
+          summary: 'Resolve or remove this TODO',
+          rationale: `Created ${blame.ageDays} days ago by ${blame.author} (${blame.commitHash.slice(0, 7)}). Aging markers tend to outlive their relevance.`,
+          action_kind: 'resolve-todo',
+        },
+        details: {
+          kind: 'aging-todos',
+          line: t.line,
+          age_days: blame.ageDays,
+          commit_hash: blame.commitHash,
+          author: blame.author,
+          text: t.text,
+          context: ctx,
+        },
+      });
+    }
+  }
+  return findings;
+}

package/src/api/lib/health/archCompliance.test.ts

@@ -0,0 +1,26 @@
+import { describe, it, expect } from 'vitest';
+import { analyzeArchCompliance } from './archCompliance';
+
+describe('analyzeArchCompliance', () => {
+  it('flags files placed outside the conventional subfolders', () => {
+    const findings = analyzeArchCompliance('lyr', [
+      'apps/editor/src/domains/x/application/RunFoo.ts',     // ok
+      'apps/editor/src/domains/x/services/Bar.ts',           // ok
+      'apps/editor/src/domains/x/RandomThing.ts',            // FLAG
+      'apps/editor/src/domains/x/utility.ts',                // FLAG
+    ]);
+    expect(findings).toHaveLength(2);
+    expect(findings[0].signal).toBe('architecture-compliance');
+    expect(findings[0].severity).toBe('warning');
+  });
+
+  it('does not flag files inside conventional subfolders', () => {
+    const findings = analyzeArchCompliance('lyr', [
+      'apps/editor/src/domains/x/application/foo.ts',
+      'apps/editor/src/domains/x/domain/bar.ts',
+      'apps/editor/src/domains/x/infrastructure/baz.ts',
+      'apps/editor/src/domains/x/ui/q.tsx',
+    ]);
+    expect(findings).toEqual([]);
+  });
+});

package/src/api/lib/health/archCompliance.ts

@@ -0,0 +1,53 @@
+import path from 'node:path';
+import type { Finding } from './types';
+
+const CONVENTIONAL_FOLDERS = ['application', 'domain', 'infrastructure', 'services', 'ui', 'components', 'hooks', '__tests__'];
+
+/**
+ * Editor uses DDD-ish layout under each domain. We expect each file to live
+ * in one of CONVENTIONAL_FOLDERS. Files at the domain root, or in folders not
+ * in the list, get flagged.
+ */
+export function analyzeArchCompliance(
+  layerId: string,
+  files: string[],
+): Finding[] {
+  const findings: Finding[] = [];
+  for (const rel of files) {
+    const m = /\/domains\/[^/]+\/([^/]+)\//.exec(rel);
+    if (m) {
+      if (CONVENTIONAL_FOLDERS.includes(m[1])) continue;
+      findings.push(makeFinding(layerId, rel, m[1], 'unconventional-subfolder'));
+      continue;
+    }
+    const rootM = /\/domains\/[^/]+\/[^/]+$/.exec(rel);
+    if (rootM) {
+      findings.push(makeFinding(layerId, rel, '(root)', 'file-at-domain-root'));
+    }
+  }
+  return findings;
+}
+
+function makeFinding(layerId: string, rel: string, actual: string, rule: string): Finding {
+  const filename = path.basename(rel);
+  return {
+    id: `${layerId}.architecture-compliance.${filename.replace(/\W/g, '_')}`,
+    signal: 'architecture-compliance',
+    severity: 'warning',
+    confidence: 'medium',
+    layer: layerId,
+    target: rel,
+    headline: `${filename} is in a non-standard location ('${actual}')`,
+    suggestion: {
+      summary: `Move ${filename} to one of: application/, domain/, infrastructure/, services/, ui/`,
+      rationale: 'Editor domains follow a conventional folder layout. Files outside it are harder to locate during navigation and code review.',
+      action_kind: 'move-file',
+    },
+    details: {
+      kind: 'architecture-compliance',
+      expected_path_pattern: 'apps/editor/src/domains/<domain>/{application,domain,infrastructure,services,ui}/...',
+      actual_path: rel,
+      rule,
+    },
+  };
+}

package/src/api/lib/health/collectAll.test.ts

@@ -0,0 +1,49 @@
+import { describe, it, expect } from 'vitest';
+import { collectAll } from './collectAll';
+import { DEFAULT_HEALTH_CONFIG } from './config';
+import { findRepoRoot } from '../repoRoot';
+import type { Scope } from '../../../types';
+
+describe('collectAll', () => {
+  const repoRoot = findRepoRoot(process.cwd());
+
+  it('returns findings array with the layer id present in each finding', async () => {
+    if (!repoRoot) throw new Error('Could not find repo root');
+    const scope: Scope = {
+      id: 'editor', path: 'apps/editor', description: '',
+      layers: [{
+        id: 'visual-canvas', name: 'Visual Canvas', description: '',
+        files: ['src/domains/canvas/**'],
+        dependencies: { inbound: [], outbound: [], external: [] },
+      }],
+      items: [],
+    };
+    const findings = await collectAll(repoRoot, scope, DEFAULT_HEALTH_CONFIG);
+    expect(Array.isArray(findings)).toBe(true);
+    for (const f of findings) {
+      expect(f.layer).toBe('visual-canvas');
+    }
+  });
+
+  it('skips signals that are opted-out via config.ignore.layer_signals', async () => {
+    if (!repoRoot) throw new Error('Could not find repo root');
+    const scope: Scope = {
+      id: 'editor', path: 'apps/editor', description: '',
+      layers: [{
+        id: 'visual-canvas', name: 'Visual Canvas', description: '',
+        files: ['src/domains/canvas/**'],
+        dependencies: { inbound: [], outbound: [], external: [] },
+      }],
+      items: [],
+    };
+    const cfg = {
+      ...DEFAULT_HEALTH_CONFIG,
+      ignore: {
+        ...DEFAULT_HEALTH_CONFIG.ignore,
+        layer_signals: { 'visual-canvas': ['hotspot-files', 'aging-todos', 'doc-drift', 'test-coverage', 'architecture-compliance', 'dead-code', 'redundancy'] as const },
+      },
+    };
+    const findings = await collectAll(repoRoot, scope, cfg as any);
+    expect(findings).toEqual([]);
+  });
+});

package/src/api/lib/health/collectAll.ts

@@ -0,0 +1,78 @@
+import type { Scope } from '../../../types';
+import type { Finding, Signal } from './types';
+import type { HealthConfig } from './config';
+import { resolveLayerFiles } from './layerFiles';
+import { analyzeHotspotFiles } from './hotspotFiles';
+import { analyzeAgingTodos } from './agingTodos';
+import { analyzeDocDrift } from './docDrift';
+import { analyzeTestCoverage } from './testCoverage';
+import { analyzeArchCompliance } from './archCompliance';
+import { buildImportGraph } from './importGraph';
+import type { ImportGraph } from './importGraph';
+import { analyzeDeadCode } from './deadCode';
+import { analyzeCoupling } from './coupling';
+import { analyzeRedundancy } from './redundancy';
+
+interface AnalyzerArgs {
+  repoRoot: string;
+  scopeId: string;
+  layerId: string;
+  files: string[];
+  config: HealthConfig;
+  graph?: ImportGraph;
+}
+type AnalyzerFn = (args: AnalyzerArgs) => Finding[];
+
+const ANALYZERS: Record<Signal, AnalyzerFn | null> = {
+  'hotspot-files':            ({ repoRoot, layerId, files, config }) => analyzeHotspotFiles(repoRoot, layerId, files, config),
+  'aging-todos':              ({ repoRoot, layerId, files, config }) => analyzeAgingTodos(repoRoot, layerId, files, config),
+  'doc-drift':                ({ repoRoot, scopeId, layerId, files }) => analyzeDocDrift(repoRoot, scopeId, layerId, files),
+  'test-coverage':            ({ repoRoot, layerId, files }) => analyzeTestCoverage(repoRoot, layerId, files),
+  'architecture-compliance':  ({ layerId, files }) => analyzeArchCompliance(layerId, files),
+  'dead-code':                ({ repoRoot, layerId, files, graph }) => graph ? analyzeDeadCode(repoRoot, layerId, files, graph) : [],
+  'coupling':                 null, // dispatched once per scope after the layer loop
+  'redundancy':               null, // Phase 4
+};
+
+export async function collectAll(repoRoot: string, scope: Scope, config: HealthConfig): Promise<Finding[]> {
+  const filesByLayer = resolveLayerFiles(repoRoot, scope);
+  const allTsFiles = Object.values(filesByLayer).flat().filter(f => /\.tsx?$/.test(f));
+  let graph: ImportGraph | undefined;
+  try {
+    graph = buildImportGraph(repoRoot, allTsFiles);
+  } catch {
+    // No tsconfig or build error — skip import-graph dependent analyzers
+  }
+  const out: Finding[] = [];
+  for (const layer of scope.layers) {
+    const opted = new Set<Signal>(config.ignore.layer_signals[layer.id] ?? []);
+    const files = filesByLayer[layer.id] ?? [];
+    for (const [signal, fn] of Object.entries(ANALYZERS) as [Signal, AnalyzerFn | null][]) {
+      if (!fn) continue;
+      if (opted.has(signal)) continue;
+      try {
+        out.push(...fn({ repoRoot, scopeId: scope.id, layerId: layer.id, files, config, graph }));
+      } catch (e) {
+        // Analyzer failures don't break the whole report. Log and continue.
+        console.error(`[health] analyzer ${signal} failed for layer ${layer.id}:`, e);
+      }
+    }
+  }
+  // Coupling is a scope-wide analyzer — run once after per-layer loop
+  if (graph) {
+    try {
+      const couplingFindings = analyzeCoupling(filesByLayer, graph)
+        .filter(f => !(config.ignore.layer_signals[f.layer] ?? []).includes('coupling'));
+      out.push(...couplingFindings);
+    } catch (e) {
+      console.error('[health] analyzer coupling failed:', e);
+    }
+  }
+  // Redundancy is scope-wide and async (jscpd) — run after per-layer + coupling
+  const redundancyFindings = await analyzeRedundancy(repoRoot, filesByLayer, config).catch(e => {
+    console.error('[health] redundancy failed:', e);
+    return [] as Finding[];
+  });
+  out.push(...redundancyFindings.filter(f => !(config.ignore.layer_signals[f.layer] ?? []).includes('redundancy')));
+  return out;
+}

package/src/api/lib/health/config.test.ts

@@ -0,0 +1,45 @@
+import { describe, it, expect } from 'vitest';
+import { loadHealthConfig, DEFAULT_HEALTH_CONFIG } from './config';
+import { writeFileSync, mkdtempSync, mkdirSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+
+function makeRepo(): string {
+  const root = mkdtempSync(path.join(tmpdir(), 'tenbo-health-'));
+  mkdirSync(path.join(root, '.tenbo'), { recursive: true });
+  return root;
+}
+
+describe('loadHealthConfig', () => {
+  it('returns defaults when no config file exists', () => {
+    const root = makeRepo();
+    const cfg = loadHealthConfig(root);
+    expect(cfg).toEqual(DEFAULT_HEALTH_CONFIG);
+    rmSync(root, { recursive: true, force: true });
+  });
+
+  it('merges file values over defaults', () => {
+    const root = makeRepo();
+    writeFileSync(path.join(root, '.tenbo/health.config.yaml'), `
+thresholds:
+  hotspot_loc:
+    critical: 2000
+`);
+    const cfg = loadHealthConfig(root);
+    expect(cfg.thresholds.hotspot_loc.critical).toBe(2000);
+    expect(cfg.thresholds.hotspot_loc.warning).toBe(DEFAULT_HEALTH_CONFIG.thresholds.hotspot_loc.warning);
+    rmSync(root, { recursive: true, force: true });
+  });
+
+  it('preserves signal_weights override order', () => {
+    const root = makeRepo();
+    writeFileSync(path.join(root, '.tenbo/health.config.yaml'), `
+signal_weights:
+  - aging-todos
+  - dead-code
+`);
+    const cfg = loadHealthConfig(root);
+    expect(cfg.signal_weights[0]).toBe('aging-todos');
+    rmSync(root, { recursive: true, force: true });
+  });
+});

package/src/api/lib/health/config.ts

@@ -0,0 +1,54 @@
+import { existsSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+import { parse as parseYaml } from 'yaml';
+import { SIGNAL_WEIGHTS_DEFAULT, type Signal } from './types';
+
+export interface HealthConfig {
+  thresholds: {
+    hotspot_loc: { critical: number; warning: number; info: number };
+    hotspot_function_loc: number;
+    todo_age_months: { critical: number; warning: number; info: number };
+    redundancy_min_lines: number;
+  };
+  ignore: {
+    /** Repo-relative file paths exempted from hotspot-files signal. */
+    hotspot_files: string[];
+    /** Map of layer id -> array of signal ids to skip for that layer. */
+    layer_signals: Record<string, Signal[]>;
+  };
+  signal_weights: Signal[];
+}
+
+export const DEFAULT_HEALTH_CONFIG: HealthConfig = {
+  thresholds: {
+    hotspot_loc: { critical: 1000, warning: 500, info: 300 },
+    hotspot_function_loc: 150,
+    todo_age_months: { critical: 12, warning: 6, info: 3 },
+    redundancy_min_lines: 30,
+  },
+  ignore: {
+    hotspot_files: [],
+    layer_signals: {},
+  },
+  signal_weights: SIGNAL_WEIGHTS_DEFAULT,
+};
+
+export function loadHealthConfig(repoRoot: string): HealthConfig {
+  const p = path.join(repoRoot, '.tenbo', 'health.config.yaml');
+  if (!existsSync(p)) return DEFAULT_HEALTH_CONFIG;
+  const raw = parseYaml(readFileSync(p, 'utf8')) as Partial<HealthConfig> | null;
+  if (!raw) return DEFAULT_HEALTH_CONFIG;
+  return {
+    thresholds: {
+      hotspot_loc: { ...DEFAULT_HEALTH_CONFIG.thresholds.hotspot_loc, ...(raw.thresholds?.hotspot_loc ?? {}) },
+      hotspot_function_loc: raw.thresholds?.hotspot_function_loc ?? DEFAULT_HEALTH_CONFIG.thresholds.hotspot_function_loc,
+      todo_age_months: { ...DEFAULT_HEALTH_CONFIG.thresholds.todo_age_months, ...(raw.thresholds?.todo_age_months ?? {}) },
+      redundancy_min_lines: raw.thresholds?.redundancy_min_lines ?? DEFAULT_HEALTH_CONFIG.thresholds.redundancy_min_lines,
+    },
+    ignore: {
+      hotspot_files: raw.ignore?.hotspot_files ?? DEFAULT_HEALTH_CONFIG.ignore.hotspot_files,
+      layer_signals: raw.ignore?.layer_signals ?? DEFAULT_HEALTH_CONFIG.ignore.layer_signals,
+    },
+    signal_weights: raw.signal_weights ?? SIGNAL_WEIGHTS_DEFAULT,
+  };
+}

package/src/api/lib/health/coupling.test.ts

@@ -0,0 +1,40 @@
+import { describe, it, expect } from 'vitest';
+import { analyzeCoupling } from './coupling';
+import type { ImportGraph } from './importGraph';
+
+const stubGraph = (edges: Record<string, string[]>): ImportGraph => ({
+  importsFrom: (f) => edges[f] ?? [],
+  importedBy: () => [],
+  allFiles: () => Object.keys(edges),
+});
+
+describe('analyzeCoupling', () => {
+  it("flags imports that reach into another layer's internals", () => {
+    const filesByLayer = {
+      A: ['apps/editor/src/A/foo.ts'],
+      B: ['apps/editor/src/B/index.ts', 'apps/editor/src/B/internal.ts'],
+    };
+    const graph = stubGraph({
+      'apps/editor/src/A/foo.ts': ['apps/editor/src/B/internal.ts'],
+    });
+    const findings = analyzeCoupling(filesByLayer, graph);
+    expect(findings).toHaveLength(1);
+    expect(findings[0].layer).toBe('A');
+    expect(findings[0].details.kind).toBe('coupling');
+    if (findings[0].details.kind === 'coupling') {
+      expect(findings[0].details.crosses_public_api).toBe(false);
+    }
+  });
+
+  it("does not flag imports that go through layer's index.ts (public API)", () => {
+    const filesByLayer = {
+      A: ['apps/editor/src/A/foo.ts'],
+      B: ['apps/editor/src/B/index.ts'],
+    };
+    const graph = stubGraph({
+      'apps/editor/src/A/foo.ts': ['apps/editor/src/B/index.ts'],
+    });
+    const findings = analyzeCoupling(filesByLayer, graph);
+    expect(findings).toEqual([]);
+  });
+});

package/src/api/lib/health/coupling.ts

@@ -0,0 +1,66 @@
+import path from 'node:path';
+import type { Finding, Severity } from './types';
+import type { ImportGraph } from './importGraph';
+
+function isPublicApiPath(file: string): boolean {
+  const base = path.basename(file);
+  return base === 'index.ts' || base === 'index.tsx';
+}
+
+function severityFor(count: number): Severity {
+  if (count >= 5) return 'critical';
+  if (count >= 2) return 'warning';
+  return 'info';
+}
+
+export function analyzeCoupling(
+  filesByLayer: Record<string, string[]>,
+  graph: ImportGraph,
+): Finding[] {
+  const layerOf = new Map<string, string>();
+  for (const [layerId, files] of Object.entries(filesByLayer)) {
+    for (const f of files) layerOf.set(f, layerId);
+  }
+
+  type Reach = { source: string; targetLayer: string; targetFile: string; sourceFiles: string[] };
+  const reaches = new Map<string, Reach>();
+
+  for (const [sourceFile, sourceLayer] of layerOf.entries()) {
+    for (const targetFile of graph.importsFrom(sourceFile)) {
+      const targetLayer = layerOf.get(targetFile);
+      if (!targetLayer || targetLayer === sourceLayer) continue;
+      if (isPublicApiPath(targetFile)) continue;
+      const key = `${sourceLayer}->${targetFile}`;
+      const cur = reaches.get(key) ?? { source: sourceLayer, targetLayer, targetFile, sourceFiles: [] };
+      cur.sourceFiles.push(sourceFile);
+      reaches.set(key, cur);
+    }
+  }
+
+  const findings: Finding[] = [];
+  for (const r of reaches.values()) {
+    const severity = severityFor(r.sourceFiles.length);
+    findings.push({
+      id: `${r.source}.coupling.${r.targetFile.replace(/\W/g, '_')}`,
+      signal: 'coupling',
+      severity,
+      confidence: 'high',
+      layer: r.source,
+      target: r.targetFile,
+      headline: `${r.sourceFiles.length} import${r.sourceFiles.length === 1 ? '' : 's'} reach into ${r.targetLayer}/${path.basename(r.targetFile)}`,
+      suggestion: {
+        summary: `Extract a shared module or expose ${path.basename(r.targetFile)} via ${r.targetLayer}/index.ts`,
+        rationale: `Layer ${r.source} reaches into layer ${r.targetLayer}'s internals (${r.targetFile}). Reaching past the public API tightens coupling.`,
+        action_kind: 'extract-shared',
+      },
+      details: {
+        kind: 'coupling',
+        source_file: r.sourceFiles[0],
+        target_file: r.targetFile,
+        import_lines: [],
+        crosses_public_api: false,
+      },
+    });
+  }
+  return findings;
+}

package/src/api/lib/health/deadCode.test.ts

@@ -0,0 +1,23 @@
+import { describe, it, expect } from 'vitest';
+import { analyzeDeadCode } from './deadCode';
+import { buildImportGraph } from './importGraph';
+import { writeFileSync, mkdtempSync, mkdirSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+
+describe('analyzeDeadCode', () => {
+  it('flags a file with zero importers', () => {
+    const root = mkdtempSync(path.join(tmpdir(), 'dead-'));
+    writeFileSync(path.join(root, 'tsconfig.json'), JSON.stringify({ compilerOptions: { module: 'esnext', target: 'es2020' }, include: ['**/*.ts'] }));
+    mkdirSync(path.join(root, 'src'), { recursive: true });
+    writeFileSync(path.join(root, 'src/used.ts'), `export const x = 1;`);
+    writeFileSync(path.join(root, 'src/unused.ts'), `export const y = 1;`);
+    writeFileSync(path.join(root, 'src/entry.ts'), `import { x } from './used';\nexport const z = x;`);
+    const graph = buildImportGraph(root, ['src/entry.ts', 'src/used.ts', 'src/unused.ts']);
+
+    const findings = analyzeDeadCode(root, 'lyr', ['src/used.ts', 'src/unused.ts'], graph);
+    expect(findings.find(f => f.target === 'src/unused.ts')).toBeDefined();
+    expect(findings.find(f => f.target === 'src/used.ts')).toBeUndefined();
+    rmSync(root, { recursive: true, force: true });
+  });
+});

package/src/api/lib/health/deadCode.ts

@@ -0,0 +1,76 @@
+import { execSync } from 'node:child_process';
+import path from 'node:path';
+import type { Finding } from './types';
+import type { ImportGraph } from './importGraph';
+
+const ENTRY_PATTERNS = [
+  /\/main\.tsx?$/, /\/index\.tsx?$/, /\.test\.tsx?$/, /\.config\.[mc]?[jt]s$/, /vite\.config/,
+];
+
+function isLikelyEntry(file: string): boolean {
+  return ENTRY_PATTERNS.some(re => re.test(file));
+}
+
+function lastImportedCommit(repoRoot: string, file: string): string | null {
+  try {
+    const out = execSync(`git log -1 --pretty=format:%H -- "${file}"`, {
+      cwd: repoRoot, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'],
+    });
+    return out.trim() || null;
+  } catch {
+    return null;
+  }
+}
+
+function gitAgeDays(repoRoot: string, file: string): number {
+  try {
+    const out = execSync(`git log -1 --pretty=format:%at -- "${file}"`, {
+      cwd: repoRoot, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'],
+    });
+    const ts = Number(out.trim()) * 1000;
+    if (!ts) return 0;
+    return Math.floor((Date.now() - ts) / (24 * 3600 * 1000));
+  } catch {
+    return 0;
+  }
+}
+
+export function analyzeDeadCode(
+  repoRoot: string,
+  layerId: string,
+  files: string[],
+  graph: ImportGraph,
+): Finding[] {
+  const findings: Finding[] = [];
+  for (const rel of files) {
+    // Only analyze TypeScript/TSX source files
+    if (!/\.tsx?$/.test(rel)) continue;
+    if (rel.endsWith('.test.ts') || rel.endsWith('.test.tsx')) continue;
+    if (graph.importedBy(rel).length > 0) continue;
+    const filename = path.basename(rel);
+    const isEntry = isLikelyEntry(rel);
+    findings.push({
+      id: `${layerId}.dead-code.${filename.replace(/\W/g, '_')}`,
+      signal: 'dead-code',
+      severity: isEntry ? 'info' : 'critical',
+      confidence: isEntry ? 'low' : 'high',
+      layer: layerId,
+      target: rel,
+      headline: `${filename} has no in-repo importers`,
+      suggestion: {
+        summary: isEntry ? `Confirm ${filename} is intentionally an entry point` : `Delete ${filename}`,
+        rationale: isEntry
+          ? 'Looks like an entry point (main, index, config, test). Verify before deleting.'
+          : 'No file in the repo imports this. Likely safe to remove.',
+        action_kind: 'delete-file',
+      },
+      details: {
+        kind: 'dead-code',
+        exports: [],
+        last_imported_commit: lastImportedCommit(repoRoot, rel),
+        git_age_days: gitAgeDays(repoRoot, rel),
+      },
+    });
+  }
+  return findings;
+}

package/src/api/lib/health/docDrift.test.ts

@@ -0,0 +1,54 @@
+import { describe, it, expect } from 'vitest';
+import { analyzeDocDrift, extractFileRefs } from './docDrift';
+import { writeFileSync, mkdtempSync, mkdirSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+
+describe('extractFileRefs', () => {
+  it('pulls inline-code-fenced paths from markdown', () => {
+    const md = `Look at \`apps/editor/src/foo.ts\` and \`bar/baz.tsx\`.`;
+    expect(extractFileRefs(md)).toEqual(['apps/editor/src/foo.ts', 'bar/baz.tsx']);
+  });
+
+  it('ignores prose with no file-like tokens', () => {
+    expect(extractFileRefs('See the README. No paths here.')).toEqual([]);
+  });
+});
+
+describe('analyzeDocDrift', () => {
+  it('emits missing-ref finding when code-map.md references a file that does not exist', () => {
+    const root = mkdtempSync(path.join(tmpdir(), 'drift-'));
+    mkdirSync(path.join(root, '.tenbo/scopes/editor/layers/lyr'), { recursive: true });
+    writeFileSync(
+      path.join(root, '.tenbo/scopes/editor/layers/lyr/code-map.md'),
+      'See `apps/editor/src/missing.ts`.\n',
+    );
+    const findings = analyzeDocDrift(root, 'editor', 'lyr', []);
+    const broken = findings.find(f =>
+      f.details.kind === 'doc-drift' && f.details.drift_type === 'missing-ref'
+    );
+    expect(broken).toBeDefined();
+    rmSync(root, { recursive: true, force: true });
+  });
+
+  it('emits unreferenced-file info finding when a layer file is not mentioned in code-map.md', () => {
+    const root = mkdtempSync(path.join(tmpdir(), 'drift-'));
+    mkdirSync(path.join(root, 'apps/editor/src'), { recursive: true });
+    writeFileSync(path.join(root, 'apps/editor/src/known.ts'), 'export const x = 1;\n');
+    writeFileSync(path.join(root, 'apps/editor/src/orphan.ts'), 'export const y = 1;\n');
+    mkdirSync(path.join(root, '.tenbo/scopes/editor/layers/lyr'), { recursive: true });
+    writeFileSync(
+      path.join(root, '.tenbo/scopes/editor/layers/lyr/code-map.md'),
+      'See `apps/editor/src/known.ts`.\n',
+    );
+    const findings = analyzeDocDrift(root, 'editor', 'lyr', [
+      'apps/editor/src/known.ts',
+      'apps/editor/src/orphan.ts',
+    ]);
+    const orphan = findings.find(f =>
+      f.details.kind === 'doc-drift' && f.details.drift_type === 'unreferenced-file'
+    );
+    expect(orphan).toBeDefined();
+    rmSync(root, { recursive: true, force: true });
+  });
+});