tenbo-dashboard 0.1.0

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

@@ -0,0 +1,99 @@
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import path from 'node:path';
+import type { Finding } from './types';
+
+/**
+ * Return file-like tokens from inline-code spans in a markdown document.
+ * We require a `/` and a `.ext` to avoid matching prose words.
+ */
+export function extractFileRefs(md: string): string[] {
+  const out: string[] = [];
+  const re = /`([^`\n]+)`/g;
+  let m: RegExpExecArray | null;
+  while ((m = re.exec(md))) {
+    const candidate = m[1].trim();
+    if (/^[\w./@-]+\.[a-zA-Z]{1,5}$/.test(candidate) && candidate.includes('/')) out.push(candidate);
+  }
+  return out;
+}
+
+export function analyzeDocDrift(
+  repoRoot: string,
+  scopeId: string,
+  layerId: string,
+  layerFiles: string[],
+): Finding[] {
+  const docPath = path.join(repoRoot, '.tenbo/scopes', scopeId, 'layers', layerId, 'code-map.md');
+  if (!existsSync(docPath)) return [];
+  const md = readFileSync(docPath, 'utf8');
+  const docMtime = statSync(docPath).mtimeMs;
+  const refs = extractFileRefs(md);
+  const refSet = new Set(refs);
+  const findings: Finding[] = [];
+
+  // 1. missing-ref: file in code-map.md doesn't exist on disk
+  const broken: string[] = [];
+  for (const ref of refs) {
+    if (!existsSync(path.join(repoRoot, ref))) broken.push(ref);
+  }
+  if (broken.length > 0) {
+    const severity = broken.length >= 3 ? 'critical' : 'warning';
+    findings.push({
+      id: `${layerId}.doc-drift.missing-ref`,
+      signal: 'doc-drift',
+      severity,
+      confidence: 'high',
+      layer: layerId,
+      target: path.relative(repoRoot, docPath).split(path.sep).join('/'),
+      headline: `code-map.md references ${broken.length} non-existent file${broken.length === 1 ? '' : 's'}`,
+      suggestion: {
+        summary: 'Update code-map.md to remove or correct broken references',
+        rationale: `${broken.length} reference${broken.length === 1 ? '' : 's'} point to files that no longer exist.`,
+        action_kind: 'update-doc',
+      },
+      details: {
+        kind: 'doc-drift',
+        drift_type: 'missing-ref',
+        doc_path: path.relative(repoRoot, docPath).split(path.sep).join('/'),
+        doc_mtime_iso: new Date(docMtime).toISOString(),
+        code_mtime_iso: null,
+        affected_files: broken,
+      },
+    });
+  }
+
+  // 2. unreferenced-file: layer file not mentioned anywhere in code-map.md
+  const orphan: string[] = [];
+  for (const f of layerFiles) {
+    if (refSet.has(f)) continue;
+    const base = path.basename(f);
+    if (md.includes(base)) continue;
+    orphan.push(f);
+  }
+  if (orphan.length > 0) {
+    findings.push({
+      id: `${layerId}.doc-drift.unreferenced-file`,
+      signal: 'doc-drift',
+      severity: 'info',
+      confidence: 'medium',
+      layer: layerId,
+      target: path.relative(repoRoot, docPath).split(path.sep).join('/'),
+      headline: `${orphan.length} file${orphan.length === 1 ? '' : 's'} in this layer not mentioned in code-map.md`,
+      suggestion: {
+        summary: 'Add new files to code-map.md or confirm they belong in this layer',
+        rationale: `These files exist in the layer's source paths but are not referenced anywhere in code-map.md.`,
+        action_kind: 'update-doc',
+      },
+      details: {
+        kind: 'doc-drift',
+        drift_type: 'unreferenced-file',
+        doc_path: path.relative(repoRoot, docPath).split(path.sep).join('/'),
+        doc_mtime_iso: new Date(docMtime).toISOString(),
+        code_mtime_iso: null,
+        affected_files: orphan,
+      },
+    });
+  }
+
+  return findings;
+}

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

@@ -0,0 +1,49 @@
+import { describe, it, expect } from 'vitest';
+import { analyzeHotspotFiles } from './hotspotFiles';
+import { DEFAULT_HEALTH_CONFIG } from './config';
+import { writeFileSync, mkdtempSync, mkdirSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+
+function makeFile(root: string, rel: string, lines: number): string {
+  const full = path.join(root, rel);
+  mkdirSync(path.dirname(full), { recursive: true });
+  writeFileSync(full, Array.from({ length: lines }, (_, i) => `// line ${i}`).join('\n'));
+  return rel;
+}
+
+describe('analyzeHotspotFiles', () => {
+  it('flags files exceeding LOC thresholds', () => {
+    const root = mkdtempSync(path.join(tmpdir(), 'hotspot-'));
+    const small = makeFile(root, 'small.ts', 100);
+    const medium = makeFile(root, 'medium.ts', 350);
+    const large = makeFile(root, 'large.ts', 700);
+    const huge = makeFile(root, 'huge.ts', 1500);
+
+    const findings = analyzeHotspotFiles(root, 'lyr', [small, medium, large, huge], DEFAULT_HEALTH_CONFIG);
+
+    expect(findings.find(f => f.target === 'small.ts')).toBeUndefined();
+    expect(findings.find(f => f.target === 'medium.ts')?.severity).toBe('info');
+    expect(findings.find(f => f.target === 'large.ts')?.severity).toBe('warning');
+    expect(findings.find(f => f.target === 'huge.ts')?.severity).toBe('critical');
+    rmSync(root, { recursive: true, force: true });
+  });
+
+  it('respects ignore.hotspot_files', () => {
+    const root = mkdtempSync(path.join(tmpdir(), 'hotspot-'));
+    const huge = makeFile(root, 'huge.ts', 1500);
+    const cfg = { ...DEFAULT_HEALTH_CONFIG, ignore: { ...DEFAULT_HEALTH_CONFIG.ignore, hotspot_files: ['huge.ts'] } };
+    const findings = analyzeHotspotFiles(root, 'lyr', [huge], cfg);
+    expect(findings).toEqual([]);
+    rmSync(root, { recursive: true, force: true });
+  });
+
+  it('produces a structured suggestion with action_kind=split-file', () => {
+    const root = mkdtempSync(path.join(tmpdir(), 'hotspot-'));
+    const huge = makeFile(root, 'huge.ts', 1500);
+    const findings = analyzeHotspotFiles(root, 'lyr', [huge], DEFAULT_HEALTH_CONFIG);
+    expect(findings[0].suggestion.action_kind).toBe('split-file');
+    expect(findings[0].details.kind).toBe('hotspot-files');
+    rmSync(root, { recursive: true, force: true });
+  });
+});

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

@@ -0,0 +1,70 @@
+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';
+
+function lineCount(absPath: string): number {
+  const content = readFileSync(absPath, 'utf8');
+  if (content.length === 0) return 0;
+  return content.split('\n').length - (content.endsWith('\n') ? 1 : 0);
+}
+
+function severityFor(loc: number, t: HealthConfig['thresholds']['hotspot_loc']): Severity | null {
+  if (loc >= t.critical) return 'critical';
+  if (loc >= t.warning) return 'warning';
+  if (loc >= t.info) return 'info';
+  return null;
+}
+
+function commits30d(repoRoot: string, relPath: string): number {
+  try {
+    const out = execSync(`git log --since="30 days ago" --pretty=format:%H -- "${relPath}"`, {
+      cwd: repoRoot, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'],
+    });
+    return out.trim() === '' ? 0 : out.trim().split('\n').length;
+  } catch {
+    return 0;
+  }
+}
+
+export function analyzeHotspotFiles(
+  repoRoot: string,
+  layerId: string,
+  files: string[],         // repo-relative
+  config: HealthConfig,
+): Finding[] {
+  const findings: Finding[] = [];
+  const ignored = new Set(config.ignore.hotspot_files);
+  for (const rel of files) {
+    if (ignored.has(rel)) continue;
+    const abs = path.resolve(repoRoot, rel);
+    let loc: number;
+    try { loc = lineCount(abs); } catch { continue; }
+    const severity = severityFor(loc, config.thresholds.hotspot_loc);
+    if (!severity) continue;
+    const filename = path.basename(rel);
+    findings.push({
+      id: `${layerId}.hotspot-files.${filename.replace(/\W/g, '_')}`,
+      signal: 'hotspot-files',
+      severity,
+      confidence: 'high',
+      layer: layerId,
+      target: rel,
+      headline: `${filename} (${loc.toLocaleString()} LOC)`,
+      suggestion: {
+        summary: `Split ${filename} into smaller files`,
+        rationale: `${loc.toLocaleString()} LOC exceeds ${severity} threshold of ${config.thresholds.hotspot_loc[severity].toLocaleString()}.`,
+        action_kind: 'split-file',
+      },
+      details: {
+        kind: 'hotspot-files',
+        loc,
+        top_functions: [],
+        commits_30d: commits30d(repoRoot, rel),
+        split_candidates: [],
+      },
+    });
+  }
+  return findings;
+}

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

@@ -0,0 +1,29 @@
+import { describe, it, expect } from 'vitest';
+import { buildImportGraph } from './importGraph';
+import { writeFileSync, mkdtempSync, mkdirSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+
+function makeTSConfig(root: string) {
+  writeFileSync(path.join(root, 'tsconfig.json'), JSON.stringify({
+    compilerOptions: { module: 'esnext', target: 'es2020', moduleResolution: 'bundler', allowJs: false, strict: false },
+    include: ['**/*.ts'],
+  }));
+}
+
+describe('buildImportGraph', () => {
+  it('records import edges between files', () => {
+    const root = mkdtempSync(path.join(tmpdir(), 'graph-'));
+    makeTSConfig(root);
+    mkdirSync(path.join(root, 'src'), { recursive: true });
+    writeFileSync(path.join(root, 'src/a.ts'), `import { x } from './b';\nexport const a = x;`);
+    writeFileSync(path.join(root, 'src/b.ts'), `export const x = 1;`);
+    writeFileSync(path.join(root, 'src/c.ts'), `export const c = 2;`);
+
+    const graph = buildImportGraph(root, ['src/a.ts', 'src/b.ts', 'src/c.ts']);
+    expect(graph.importsFrom('src/a.ts')).toContain('src/b.ts');
+    expect(graph.importedBy('src/b.ts')).toContain('src/a.ts');
+    expect(graph.importedBy('src/c.ts')).toEqual([]);
+    rmSync(root, { recursive: true, force: true });
+  });
+});

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

@@ -0,0 +1,51 @@
+import { Project } from 'ts-morph';
+import path from 'node:path';
+
+export interface ImportGraph {
+  importsFrom(file: string): string[];
+  importedBy(file: string): string[];
+  allFiles(): string[];
+}
+
+/**
+ * Build an import graph for the given repo-relative TS/TSX files.
+ * Resolution uses the repo's tsconfig if found at <repoRoot>/tsconfig.json,
+ * otherwise a default config.
+ */
+export function buildImportGraph(repoRoot: string, files: string[]): ImportGraph {
+  const tsconfigPath = path.join(repoRoot, 'tsconfig.json');
+  const project = new Project({
+    tsConfigFilePath: tsconfigPath,
+    skipAddingFilesFromTsConfig: true,
+    skipFileDependencyResolution: false,
+  });
+  const absFiles = files.map(f => path.resolve(repoRoot, f));
+  project.addSourceFilesAtPaths(absFiles);
+
+  const fwd = new Map<string, Set<string>>();
+  const bwd = new Map<string, Set<string>>();
+  const ensure = (m: Map<string, Set<string>>, k: string) => {
+    let s = m.get(k);
+    if (!s) { s = new Set(); m.set(k, s); }
+    return s;
+  };
+
+  for (const sf of project.getSourceFiles()) {
+    const fromAbs = sf.getFilePath();
+    const fromRel = path.relative(repoRoot, fromAbs).split(path.sep).join('/');
+    if (!files.includes(fromRel)) continue;
+    for (const decl of sf.getImportDeclarations()) {
+      const target = decl.getModuleSpecifierSourceFile();
+      if (!target) continue; // external module
+      const toAbs = target.getFilePath();
+      const toRel = path.relative(repoRoot, toAbs).split(path.sep).join('/');
+      ensure(fwd, fromRel).add(toRel);
+      ensure(bwd, toRel).add(fromRel);
+    }
+  }
+  return {
+    importsFrom: (f) => Array.from(fwd.get(f) ?? []),
+    importedBy: (f) => Array.from(bwd.get(f) ?? []),
+    allFiles: () => files,
+  };
+}

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

@@ -0,0 +1,46 @@
+import { describe, it, expect } from 'vitest';
+import { resolveLayerFiles } from './layerFiles';
+import { findRepoRoot } from '../repoRoot';
+import type { Scope } from '../../../types';
+
+describe('resolveLayerFiles', () => {
+  const repoRoot = findRepoRoot(process.cwd());
+
+  it('returns repo-relative paths bucketed by layer', () => {
+    if (!repoRoot) throw new Error('Could not find repo root');
+    // Use a real fixture: this repo's editor scope.
+    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 result = resolveLayerFiles(repoRoot, scope);
+    expect(result['visual-canvas']).toBeDefined();
+    expect(result['visual-canvas'].length).toBeGreaterThan(0);
+    // Paths are repo-relative
+    expect(result['visual-canvas'][0]).toMatch(/^apps\/editor\/src\/domains\/canvas\//);
+  });
+
+  it('returns empty array for layer with no matching files', () => {
+    if (!repoRoot) throw new Error('Could not find repo root');
+    const scope: Scope = {
+      id: 'editor', path: 'apps/editor', description: '',
+      layers: [{
+        id: 'nonexistent', name: '', description: '',
+        files: ['src/domains/does-not-exist/**'],
+        dependencies: { inbound: [], outbound: [], external: [] },
+      }],
+      items: [],
+    };
+    const result = resolveLayerFiles(repoRoot, scope);
+    expect(result['nonexistent']).toEqual([]);
+  });
+});

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

@@ -0,0 +1,40 @@
+import { existsSync, readdirSync, statSync } from 'node:fs';
+import path from 'node:path';
+import type { Scope } from '../../../types';
+import { globMatches } from '../metrics';
+
+/**
+ * Returns a map of layerId -> array of repo-relative file paths.
+ */
+export function resolveLayerFiles(repoRoot: string, scope: Scope): Record<string, string[]> {
+  const out: Record<string, string[]> = {};
+  for (const layer of scope.layers) {
+    out[layer.id] = matchLayerFiles(repoRoot, scope.path, layer.files ?? []);
+  }
+  return out;
+}
+
+function matchLayerFiles(repoRoot: string, scopePath: string, globs: string[]): string[] {
+  const root = path.resolve(repoRoot, scopePath);
+  if (!existsSync(root)) return [];
+  const matches: string[] = [];
+  function walk(dir: string) {
+    let entries: string[];
+    try { entries = readdirSync(dir); } catch { return; }
+    for (const entry of entries.sort()) {
+      const full = path.join(dir, entry);
+      let st;
+      try { st = statSync(full); } catch { continue; }
+      if (st.isDirectory()) walk(full);
+      else {
+        const relToScope = path.relative(root, full).split(path.sep).join('/');
+        if (globs.some(g => globMatches(g, relToScope))) {
+          const relToRepo = path.relative(repoRoot, full).split(path.sep).join('/');
+          matches.push(relToRepo);
+        }
+      }
+    }
+  }
+  walk(root);
+  return matches;
+}

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

@@ -0,0 +1,24 @@
+import { describe, it, expect } from 'vitest';
+import { analyzeRedundancy } from './redundancy';
+import { DEFAULT_HEALTH_CONFIG } from './config';
+import { writeFileSync, mkdtempSync, mkdirSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+
+describe('analyzeRedundancy', () => {
+  it('flags duplicated blocks across files', async () => {
+    const root = mkdtempSync(path.join(tmpdir(), 'dup-'));
+    mkdirSync(path.join(root, 'src/A'), { recursive: true });
+    mkdirSync(path.join(root, 'src/B'), { recursive: true });
+    const block = Array.from({ length: 40 }, (_, i) => `  console.log("dup line ${i}");`).join('\n');
+    const wrap = (b: string) => `export function f() {\n${b}\n}\n`;
+    writeFileSync(path.join(root, 'src/A/foo.ts'), wrap(block));
+    writeFileSync(path.join(root, 'src/B/bar.ts'), wrap(block));
+
+    const filesByLayer = { A: ['src/A/foo.ts'], B: ['src/B/bar.ts'] };
+    const findings = await analyzeRedundancy(root, filesByLayer, DEFAULT_HEALTH_CONFIG);
+    expect(findings.length).toBeGreaterThan(0);
+    expect(findings[0].signal).toBe('redundancy');
+    rmSync(root, { recursive: true, force: true });
+  }, 30000);
+});

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

@@ -0,0 +1,162 @@
+// FALLBACK: jscpd v4's ESM bundle has a broken `colors/safe` import in Node 22
+// (missing `.js` extension), so the programmatic `detectClones` API cannot be
+// imported directly. Instead we shell out to the jscpd CLI (CommonJS entry
+// point — no ESM problem), parse its JSON report from a temp output dir, and
+// clean up after ourselves.
+import path from 'node:path';
+import { execFileSync } from 'node:child_process';
+import { existsSync, mkdtempSync, rmSync, readFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { fileURLToPath } from 'node:url';
+import type { HealthConfig } from './config';
+import type { Finding, Severity } from './types';
+
+// jscpd's exports map blocks require.resolve('jscpd/package.json') and
+// require.resolve('jscpd/bin/jscpd'). Instead, walk up from this file's
+// directory to find the nearest node_modules/.bin/jscpd shell wrapper.
+const _thisDir = path.dirname(fileURLToPath(import.meta.url));
+
+function jscpdBin(): string {
+  let dir = _thisDir;
+  for (let i = 0; i < 8; i++) {
+    const candidate = path.join(dir, 'node_modules', '.bin', 'jscpd');
+    if (existsSync(candidate)) return candidate;
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return 'jscpd'; // fallback: rely on PATH
+}
+
+interface JscpdFile {
+  name: string;   // may be absolute or relative to cwd
+  start: number;
+  end: number;
+  startLoc?: { line: number };
+  endLoc?: { line: number };
+}
+
+interface JscpdClone {
+  firstFile: JscpdFile;
+  secondFile: JscpdFile;
+  lines?: number;
+}
+
+function layerOf(
+  filesByLayer: Record<string, string[]>,
+  filePath: string,
+  repoRoot: string,
+): string | undefined {
+  // jscpd returns paths relative to cwd (repoRoot) or absolute — normalize both.
+  const rel = path.isAbsolute(filePath)
+    ? path.relative(repoRoot, filePath)
+    : filePath;
+  for (const [layerId, files] of Object.entries(filesByLayer)) {
+    if (files.includes(rel)) return layerId;
+  }
+  return undefined;
+}
+
+function severityFor(copyCount: number, sameLayer: boolean): Severity {
+  if (copyCount >= 3) return 'critical';
+  if (!sameLayer) return 'warning';
+  return 'info';
+}
+
+function resolveFilePath(filePath: string, repoRoot: string): string {
+  if (path.isAbsolute(filePath)) return path.relative(repoRoot, filePath);
+  // jscpd may return paths relative to cwd where the command ran (repoRoot)
+  return filePath;
+}
+
+export async function analyzeRedundancy(
+  repoRoot: string,
+  filesByLayer: Record<string, string[]>,
+  config: HealthConfig,
+): Promise<Finding[]> {
+  const allFiles = Object.values(filesByLayer).flat().filter(f => /\.tsx?$/.test(f));
+  if (allFiles.length === 0) return [];
+
+  const absPaths = allFiles.map(f =>
+    path.isAbsolute(f) ? f : path.join(repoRoot, f),
+  );
+
+  const outDir = mkdtempSync(path.join(tmpdir(), 'jscpd-'));
+  try {
+    try {
+      // jscpd .bin wrapper is a shell script; execute via sh to be safe.
+      execFileSync(
+        jscpdBin(),
+        [
+          '--reporters', 'json',
+          '--output', outDir,
+          '--min-lines', String(config.thresholds.redundancy_min_lines),
+          '--silent',
+          ...absPaths,
+        ],
+        { cwd: repoRoot, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] },
+      );
+    } catch {
+      // jscpd exits with code 1 when duplications exceed the threshold.
+      // The report file is still written — only bail below if it's missing.
+    }
+
+    let report: { duplicates?: JscpdClone[] };
+    try {
+      const raw = readFileSync(path.join(outDir, 'jscpd-report.json'), 'utf8');
+      report = JSON.parse(raw) as { duplicates?: JscpdClone[] };
+    } catch {
+      // No report file — no supported files found or jscpd failed entirely.
+      return [];
+    }
+
+    const clones = report.duplicates ?? [];
+    const findings: Finding[] = [];
+
+    for (const clone of clones) {
+      const pathA = resolveFilePath(clone.firstFile.name, repoRoot);
+      const pathB = resolveFilePath(clone.secondFile.name, repoRoot);
+
+      const layerA = layerOf(filesByLayer, pathA, repoRoot);
+      const layerB = layerOf(filesByLayer, pathB, repoRoot);
+      const layer = layerA ?? layerB ?? 'unknown';
+
+      const startA = clone.firstFile.startLoc?.line ?? clone.firstFile.start;
+      const endA = clone.firstFile.endLoc?.line ?? clone.firstFile.end;
+      const startB = clone.secondFile.startLoc?.line ?? clone.secondFile.start;
+      const endB = clone.secondFile.endLoc?.line ?? clone.secondFile.end;
+      const lineCount = clone.lines ?? (endA - startA + 1);
+
+      const sameLayer = layerA !== undefined && layerA === layerB;
+      const severity = severityFor(2, sameLayer);
+
+      const idKey = `${pathA.replace(/\W/g, '_')}_L${startA}`;
+      findings.push({
+        id: `${layer}.redundancy.${idKey}`,
+        signal: 'redundancy',
+        severity,
+        confidence: 'high',
+        layer,
+        target: pathA,
+        headline: `${path.basename(pathA)} duplicates ${lineCount} lines into ${path.basename(pathB)}`,
+        suggestion: {
+          summary: `Extract the duplicated ${lineCount}-line block into a shared module`,
+          rationale: `Identical code in ${path.basename(pathA)} (L${startA}-${endA}) and ${path.basename(pathB)} (L${startB}-${endB}) creates maintenance risk — one fix must land in both places.`,
+          action_kind: 'extract-shared',
+        },
+        details: {
+          kind: 'redundancy',
+          copies: [
+            { path: pathA, lines: [startA, endA] },
+            { path: pathB, lines: [startB, endB] },
+          ],
+          similarity_pct: 100,
+        },
+      });
+    }
+
+    return findings;
+  } finally {
+    rmSync(outDir, { recursive: true, force: true });
+  }
+}

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

@@ -0,0 +1,33 @@
+import { describe, it, expect } from 'vitest';
+import { analyzeTestCoverage } from './testCoverage';
+import { writeFileSync, mkdtempSync, mkdirSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+
+describe('analyzeTestCoverage', () => {
+  it('flags use case files without sibling tests', () => {
+    const root = mkdtempSync(path.join(tmpdir(), 'cov-'));
+    mkdirSync(path.join(root, 'src/domains/x/application'), { recursive: true });
+    const a = 'src/domains/x/application/RunFooUseCase.ts';
+    const b = 'src/domains/x/application/RunBarUseCase.ts';
+    writeFileSync(path.join(root, a), 'export class RunFooUseCase {}');
+    writeFileSync(path.join(root, b), 'export class RunBarUseCase {}');
+    writeFileSync(path.join(root, 'src/domains/x/application/RunFooUseCase.test.ts'), 'test("x", () => {});');
+
+    const findings = analyzeTestCoverage(root, 'lyr', [a, b]);
+    expect(findings).toHaveLength(1);
+    expect(findings[0].target).toBe(b);
+    expect(findings[0].severity).toBe('warning');
+    rmSync(root, { recursive: true, force: true });
+  });
+
+  it('flags non-use-case infrastructure files at info severity when missing tests', () => {
+    const root = mkdtempSync(path.join(tmpdir(), 'cov-'));
+    mkdirSync(path.join(root, 'src/domains/x/infrastructure'), { recursive: true });
+    const a = 'src/domains/x/infrastructure/SupabaseRepo.ts';
+    writeFileSync(path.join(root, a), 'export class SupabaseRepo {}');
+    const findings = analyzeTestCoverage(root, 'lyr', [a]);
+    expect(findings.find(f => f.target === a)?.severity).toBe('info');
+    rmSync(root, { recursive: true, force: true });
+  });
+});

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

@@ -0,0 +1,55 @@
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import type { Finding, Severity } from './types';
+
+const USE_CASE_RE = /\/application\/[^/]*UseCase\.ts$/;
+const INFRA_RE = /\/infrastructure\/[^/]+\.ts$/;
+const TEST_SIBLING_PATTERNS = ['.test.ts', '.test.tsx'];
+
+function siblingTestPath(repoRoot: string, file: string): string | null {
+  const dir = path.dirname(file);
+  const base = path.basename(file).replace(/\.tsx?$/, '');
+  for (const suffix of TEST_SIBLING_PATTERNS) {
+    const candidate = path.join(dir, base + suffix);
+    if (existsSync(path.resolve(repoRoot, candidate))) return candidate;
+    const inFolder = path.join(dir, '__tests__', base + suffix);
+    if (existsSync(path.resolve(repoRoot, inFolder))) return inFolder;
+  }
+  return null;
+}
+
+export function analyzeTestCoverage(
+  repoRoot: string,
+  layerId: string,
+  files: string[],
+): Finding[] {
+  const findings: Finding[] = [];
+  for (const rel of files) {
+    if (rel.endsWith('.test.ts') || rel.endsWith('.test.tsx')) continue;
+    const isUseCase = USE_CASE_RE.test(rel);
+    const isInfra = INFRA_RE.test(rel);
+    if (!isUseCase && !isInfra) continue;
+    if (siblingTestPath(repoRoot, rel)) continue;
+    const severity: Severity = isUseCase ? 'warning' : 'info';
+    const filename = path.basename(rel);
+    const suggestedTestPath = rel.replace(/\.tsx?$/, '.test.ts');
+    findings.push({
+      id: `${layerId}.test-coverage.${filename.replace(/\W/g, '_')}`,
+      signal: 'test-coverage',
+      severity,
+      confidence: 'high',
+      layer: layerId,
+      target: rel,
+      headline: `${filename} has no test`,
+      suggestion: {
+        summary: `Add test at ${suggestedTestPath}`,
+        rationale: isUseCase
+          ? 'Application-layer use cases are core behavior and should have unit tests.'
+          : 'Infrastructure adapters benefit from a focused test against their interface.',
+        action_kind: 'add-test',
+      },
+      details: { kind: 'test-coverage', suggested_test_path: suggestedTestPath },
+    });
+  }
+  return findings;
+}