tenbo-dashboard 0.1.0

package/scripts/validate-cli.test.ts

@@ -0,0 +1,152 @@
+import { describe, it, expect } from 'vitest';
+import { computeDiff, renderOutput, issueKey } from './validate-cli';
+import type { ValidateIssue } from '../src/types';
+
+const warn = (msg: string, scope = 'editor', itemId?: string): ValidateIssue => ({
+  level: 'warning',
+  message: msg,
+  scope,
+  itemId,
+});
+const err = (msg: string, scope = 'editor', itemId?: string): ValidateIssue => ({
+  level: 'error',
+  message: msg,
+  scope,
+  itemId,
+});
+
+const snap = (errors: ValidateIssue[] = [], warnings: ValidateIssue[] = []) => ({
+  generated_at: '2026-04-28T00:00:00Z',
+  errors,
+  warnings,
+});
+
+describe('issueKey', () => {
+  it('hashes message + scope + itemId/layerId stably', () => {
+    const a = warn('x', 'editor', 'ed-001');
+    const b = warn('x', 'editor', 'ed-001');
+    expect(issueKey(a)).toBe(issueKey(b));
+  });
+  it('distinguishes different itemIds with the same message', () => {
+    expect(issueKey(warn('x', 'editor', 'ed-001'))).not.toBe(issueKey(warn('x', 'editor', 'ed-002')));
+  });
+});
+
+describe('computeDiff', () => {
+  it('treats every finding as new when there is no previous snapshot', () => {
+    const cur = snap([], [warn('a', 'editor', 'ed-001'), warn('b', 'editor', 'ed-002')]);
+    const d = computeDiff(null, cur);
+    expect(d.newWarnings).toHaveLength(2);
+    expect(d.preExistingWarnings).toHaveLength(0);
+  });
+
+  it('treats identical findings as pre-existing', () => {
+    const w = [warn('a', 'editor', 'ed-001'), warn('b', 'editor', 'ed-002')];
+    const d = computeDiff(snap([], w), snap([], w));
+    expect(d.newWarnings).toHaveLength(0);
+    expect(d.preExistingWarnings).toHaveLength(2);
+  });
+
+  it('isolates one new warning against an otherwise-identical prior run', () => {
+    const prevW = [warn('a', 'editor', 'ed-001'), warn('b', 'editor', 'ed-002')];
+    const newW = [...prevW, warn('c', 'editor', 'ed-003')];
+    const d = computeDiff(snap([], prevW), snap([], newW));
+    expect(d.newWarnings).toHaveLength(1);
+    expect(d.newWarnings[0].message).toBe('c');
+    expect(d.preExistingWarnings).toHaveLength(2);
+  });
+
+  it('separates new vs pre-existing errors the same way', () => {
+    const prevE = [err('e1', 'editor', 'ed-010')];
+    const newE = [...prevE, err('e2', 'editor', 'ed-011')];
+    const d = computeDiff(snap(prevE), snap(newE));
+    expect(d.newErrors.map((e) => e.message)).toEqual(['e2']);
+    expect(d.preExistingErrors.map((e) => e.message)).toEqual(['e1']);
+  });
+});
+
+describe('renderOutput — default mode', () => {
+  it('first run with no prev snapshot lists every finding as new', () => {
+    const s = snap([], [warn('a', 'editor', 'ed-001')]);
+    const d = computeDiff(null, s);
+    const r = renderOutput(s, d, {});
+    expect(r.exitCode).toBe(0);
+    expect(r.stdout).toContain('1 new warning');
+    expect(r.stdout).toContain('a');
+  });
+
+  it('second run with identical findings emits the one-liner', () => {
+    const w = [warn('a', 'editor', 'ed-001'), warn('b', 'editor', 'ed-002')];
+    const s = snap([], w);
+    const d = computeDiff(snap([], w), s);
+    const r = renderOutput(s, d, {});
+    expect(r.exitCode).toBe(0);
+    expect(r.stdout).toMatch(/^tenbo validation passed \(0 errors, 2 warnings — all pre-existing\)/);
+    expect(r.stderr).toBe('');
+  });
+
+  it('reports a single new warning while folding pre-existing into the summary', () => {
+    const prev = [warn('a', 'editor', 'ed-001'), warn('b', 'editor', 'ed-002')];
+    const cur = [...prev, warn('c', 'editor', 'ed-003')];
+    const s = snap([], cur);
+    const d = computeDiff(snap([], prev), s);
+    const r = renderOutput(s, d, {});
+    expect(r.exitCode).toBe(0);
+    expect(r.stdout).toContain('1 new warning');
+    expect(r.stdout).toContain('c');
+    expect(r.stdout).toContain('2 pre-existing warnings');
+  });
+
+  it('exits 1 and prints new errors to stderr when a new error appears', () => {
+    const cur = snap([err('boom', 'editor', 'ed-001')], []);
+    const d = computeDiff(null, cur);
+    const r = renderOutput(cur, d, {});
+    expect(r.exitCode).toBe(1);
+    expect(r.stderr).toContain('1 new error');
+    expect(r.stderr).toContain('boom');
+  });
+});
+
+describe('renderOutput — verbose mode', () => {
+  it('lists all errors and warnings regardless of diff', () => {
+    const w = [warn('a', 'editor', 'ed-001'), warn('b', 'editor', 'ed-002')];
+    const s = snap([], w);
+    const d = computeDiff(snap([], w), s); // all pre-existing
+    const r = renderOutput(s, d, { verbose: true });
+    expect(r.exitCode).toBe(0);
+    const combined = r.stdout + r.stderr;
+    expect(combined).toContain('a');
+    expect(combined).toContain('b');
+    expect(combined).toContain('tenbo validation warnings (2)');
+  });
+
+  it('prints all errors with the FAILED header in verbose mode', () => {
+    const errs = [err('e1', 'editor', 'ed-010'), err('e2', 'editor', 'ed-011')];
+    const s = snap(errs, []);
+    const d = computeDiff(null, s);
+    const r = renderOutput(s, d, { verbose: true });
+    expect(r.exitCode).toBe(1);
+    expect(r.stderr).toContain('tenbo validation FAILED');
+    expect(r.stderr).toContain('e1');
+    expect(r.stderr).toContain('e2');
+  });
+});
+
+describe('renderOutput — json mode', () => {
+  it('emits the snapshot as JSON to stdout', () => {
+    const s = snap([], [warn('a', 'editor', 'ed-001')]);
+    const d = computeDiff(null, s);
+    const r = renderOutput(s, d, { json: true });
+    expect(r.exitCode).toBe(0);
+    const parsed = JSON.parse(r.stdout);
+    expect(parsed.warnings).toHaveLength(1);
+    expect(parsed.errors).toHaveLength(0);
+  });
+
+  it('exit code reflects errors even in JSON mode', () => {
+    const s = snap([err('boom')], []);
+    const d = computeDiff(null, s);
+    const r = renderOutput(s, d, { json: true });
+    expect(r.exitCode).toBe(1);
+  });
+});

package/scripts/validate-cli.ts

@@ -0,0 +1,181 @@
+/**
+ * validate-cli.ts — tenbo validator CLI with diff-based output.
+ *
+ * Default output: summarizes NEW errors / warnings vs the previous run's
+ *   `.tenbo/.validation-status.json` snapshot. Pre-existing findings are rolled
+ *   into a single summary line so the signal is the diff, not the absolute set.
+ * --verbose: full list of every finding (the historical behavior).
+ * --json:    full snapshot to stdout for CI consumers.
+ *
+ * The `.validation-status.json` schema is unchanged; only presentation changes.
+ */
+import { findRepoRoot } from '../src/api/lib/repoRoot';
+import { readState } from '../src/api/lib/tenboFs';
+import { validate } from '../src/api/lib/validator';
+import type { ValidateIssue } from '../src/types';
+import fs from 'node:fs';
+import path from 'node:path';
+
+interface Snapshot {
+  generated_at: string;
+  errors: ValidateIssue[];
+  warnings: ValidateIssue[];
+}
+
+interface DiffResult {
+  newErrors: ValidateIssue[];
+  preExistingErrors: ValidateIssue[];
+  newWarnings: ValidateIssue[];
+  preExistingWarnings: ValidateIssue[];
+}
+
+/** Stable hash for an issue: message + scope + (itemId|layerId). */
+export function issueKey(i: ValidateIssue): string {
+  const target = (i.itemId ?? '') + '::' + (i.layerId ?? '');
+  return `${i.message}||${i.scope ?? ''}||${target}`;
+}
+
+export function computeDiff(prev: Snapshot | null, current: Snapshot): DiffResult {
+  const prevErr = new Set((prev?.errors ?? []).map(issueKey));
+  const prevWarn = new Set((prev?.warnings ?? []).map(issueKey));
+  const newErrors: ValidateIssue[] = [];
+  const preExistingErrors: ValidateIssue[] = [];
+  const newWarnings: ValidateIssue[] = [];
+  const preExistingWarnings: ValidateIssue[] = [];
+  for (const e of current.errors) (prevErr.has(issueKey(e)) ? preExistingErrors : newErrors).push(e);
+  for (const w of current.warnings) (prevWarn.has(issueKey(w)) ? preExistingWarnings : newWarnings).push(w);
+  return { newErrors, preExistingErrors, newWarnings, preExistingWarnings };
+}
+
+export interface RenderOptions {
+  verbose?: boolean;
+  json?: boolean;
+}
+
+export interface RenderResult {
+  stdout: string;
+  stderr: string;
+  exitCode: number;
+}
+
+/** Pure renderer — testable without spawning a process. */
+export function renderOutput(snapshot: Snapshot, diff: DiffResult, opts: RenderOptions): RenderResult {
+  const out: string[] = [];
+  const err: string[] = [];
+
+  if (opts.json) {
+    out.push(JSON.stringify(snapshot, null, 2));
+    return {
+      stdout: out.join('\n') + '\n',
+      stderr: '',
+      exitCode: snapshot.errors.length ? 1 : 0,
+    };
+  }
+
+  if (opts.verbose) {
+    if (snapshot.errors.length) {
+      err.push('tenbo validation FAILED:');
+      for (const e of snapshot.errors) err.push(`  ❌ ${e.message}`);
+    } else {
+      out.push('tenbo validation: no errors.');
+    }
+    if (snapshot.warnings.length) {
+      const lines: string[] = [];
+      lines.push(`tenbo validation warnings (${snapshot.warnings.length}):`);
+      for (const w of snapshot.warnings) lines.push(`  ⚠️ ${w.message}`);
+      (snapshot.errors.length ? err : out).push(lines.join('\n'));
+    }
+    return {
+      stdout: out.join('\n') + (out.length ? '\n' : ''),
+      stderr: err.join('\n') + (err.length ? '\n' : ''),
+      exitCode: snapshot.errors.length ? 1 : 0,
+    };
+  }
+
+  // Default: diff-based summary.
+  const { newErrors, preExistingErrors, newWarnings, preExistingWarnings } = diff;
+  const totalErrors = newErrors.length + preExistingErrors.length;
+  const totalWarnings = newWarnings.length + preExistingWarnings.length;
+
+  if (newErrors.length === 0 && newWarnings.length === 0) {
+    out.push(
+      `tenbo validation passed (${totalErrors} errors, ${totalWarnings} warnings — all pre-existing). Run with --verbose to list.`,
+    );
+    return { stdout: out.join('\n') + '\n', stderr: '', exitCode: 0 };
+  }
+
+  if (newErrors.length > 0) {
+    err.push(`tenbo validation FAILED — ${newErrors.length} new error(s):`);
+    for (const e of newErrors) err.push(`  ❌ ${e.message}`);
+    err.push('');
+    err.push(
+      `Summary: ${newErrors.length} new errors, ${preExistingErrors.length} pre-existing errors, ${newWarnings.length} new warnings, ${preExistingWarnings.length} pre-existing warnings. Run with --verbose to list everything.`,
+    );
+    return { stdout: '', stderr: err.join('\n') + '\n', exitCode: 1 };
+  }
+
+  // newErrors === 0, newWarnings > 0
+  out.push(`tenbo validation passed with ${newWarnings.length} new warning(s):`);
+  for (const w of newWarnings) out.push(`  ⚠️ ${w.message}`);
+  out.push('');
+  out.push(
+    `Summary: 0 new errors, ${preExistingErrors.length} pre-existing errors, ${newWarnings.length} new warnings, ${preExistingWarnings.length} pre-existing warnings. Run with --verbose to list everything.`,
+  );
+  return { stdout: out.join('\n') + '\n', stderr: '', exitCode: 0 };
+}
+
+function readPrevSnapshot(statusPath: string): Snapshot | null {
+  if (!fs.existsSync(statusPath)) return null;
+  try {
+    const raw = JSON.parse(fs.readFileSync(statusPath, 'utf8'));
+    return {
+      generated_at: raw.generated_at ?? '',
+      errors: Array.isArray(raw.errors) ? raw.errors : [],
+      warnings: Array.isArray(raw.warnings) ? raw.warnings : [],
+    };
+  } catch {
+    return null;
+  }
+}
+
+function isMain(): boolean {
+  try {
+    const invoked = process.argv[1] ? path.resolve(process.argv[1]) : '';
+    const here = path.resolve(new URL(import.meta.url).pathname);
+    return invoked === here;
+  } catch {
+    return false;
+  }
+}
+
+if (isMain()) {
+  const args = process.argv.slice(2);
+  const verbose = args.includes('--verbose');
+  const json = args.includes('--json');
+
+  const cwd = process.cwd();
+  const repoRoot = findRepoRoot(cwd) ?? path.resolve(cwd, '..', '..');
+  const statusPath = path.join(repoRoot, '.tenbo', '.validation-status.json');
+  const prev = readPrevSnapshot(statusPath);
+
+  const state = readState(repoRoot);
+  const result = validate(state);
+  const snapshot: Snapshot = {
+    generated_at: new Date().toISOString(),
+    errors: result.errors,
+    warnings: result.warnings,
+  };
+
+  fs.writeFileSync(statusPath, JSON.stringify(snapshot, null, 2) + '\n');
+
+  const diff = computeDiff(prev, snapshot);
+  const rendered = renderOutput(snapshot, diff, { verbose, json });
+  if (rendered.stdout) process.stdout.write(rendered.stdout);
+  if (rendered.stderr) process.stderr.write(rendered.stderr);
+  if (!json && !verbose) {
+    // Add a trailing pointer to where the snapshot was written, to stderr so it
+    // doesn't pollute callers parsing stdout.
+    process.stderr.write(`(snapshot at ${path.relative(repoRoot, statusPath)})\n`);
+  }
+  process.exit(rendered.exitCode);
+}

package/src/App.tsx

@@ -0,0 +1,152 @@
+import { useEffect, useState } from 'react';
+import { TopBar } from './ui/TopBar';
+import { EmptyState } from './ui/EmptyState';
+import { LayerDrawer } from './ui/LayerDrawer';
+import { ItemModal } from './ui/ItemModal';
+import { useTenboState } from './hooks/useTenboState';
+import { useApiPatch } from './hooks/useApiPatch';
+import { tenboApi } from './api/client';
+import { useHashRoute } from './router/useHashRoute';
+import { modeFromRoute, type Mode } from './router/routes';
+import { LayerPage } from './ui/LayerPage/LayerPage';
+import { WorkspacePage } from './ui/WorkspacePage/WorkspacePage';
+import { ScopePage } from './ui/ScopePage/ScopePage';
+import { RoadmapPage } from './ui/RoadmapPage/RoadmapPage';
+import { HealthPage } from './ui/HealthPage/HealthPage';
+import { LayerDetailPage } from './ui/LayerDetailPage/LayerDetailPage';
+import { FindingModal } from './ui/FindingModal';
+import { DotGrid } from './ui/DotGrid';
+import type { Item, Layer, RelatedDoc } from './types';
+import type { Finding } from './api/lib/health/types';
+
+type Overlay =
+  | { kind: 'drawer'; scopeId: string; layer: Layer }
+  | { kind: 'modal'; scopeId: string; item: Item }
+  | null;
+
+export default function App() {
+  const { state, loadError, reload, generation } = useTenboState();
+  const patch = useApiPatch();
+  const { route, navigate } = useHashRoute();
+
+  const [overlay, setOverlay] = useState<Overlay>(null);
+  const [related, setRelated] = useState<RelatedDoc[]>([]);
+  const [openFinding, setOpenFinding] = useState<Finding | null>(null);
+
+  useEffect(() => {
+    tenboApi.getRelated().then(setRelated).catch(() => {});
+  }, [state]);
+
+  // Keep overlay item in sync with refreshed state
+  useEffect(() => {
+    if (!state || overlay?.kind !== 'modal') return;
+    const scope = state.scopes.find(s => s.id === overlay.scopeId);
+    const fresh = scope?.items.find(i => i.id === overlay.item.id)
+      ?? state.crossCuttingRoadmap?.find(i => i.id === overlay.item.id);
+    if (fresh && fresh !== overlay.item) {
+      setOverlay({ kind: 'modal', scopeId: overlay.scopeId, item: fresh });
+    }
+  }, [state]);
+
+  if (loadError && loadError.includes('404')) return <EmptyState message="No .tenbo/ found at the repo root." />;
+  if (loadError) return <div style={{ padding: 24, color: 'var(--error)' }}>Error: {loadError} <button onClick={reload}>retry</button></div>;
+  if (!state) return <div style={{ padding: 24 }}>Loading…</div>;
+
+  const mode = modeFromRoute(route);
+  const onSelectMode = (m: Mode) => {
+    if (m === mode) return;
+    if (m === 'roadmap') navigate({ kind: 'roadmap' });
+    else if (m === 'health') navigate({ kind: 'health' });
+    else navigate({ kind: 'docs-project', tab: 'overview' });
+  };
+
+  const handlePatch = async (scopeId: string, itemId: string, p: Partial<Item>) => {
+    await patch(scopeId, itemId, p);
+  };
+
+  const body = (() => {
+    if (route.kind === 'docs-project') return <WorkspacePage tab={route.tab} navigate={navigate} state={state} />;
+    if (route.kind === 'docs-layer') return <LayerPage scopeId={route.scopeId} layerId={route.layerId} tab={route.tab} navigate={navigate} state={state} generation={generation} />;
+    if (route.kind === 'docs-scope') return <ScopePage scopeId={route.scopeId} state={state} navigate={navigate} />;
+    if (route.kind === 'item') return <WorkspacePage tab="overview" navigate={navigate} state={state} />;
+    if (route.kind === 'health') return (
+      <HealthPage
+        state={state}
+        onSelectLayer={(scopeId, layerId) => navigate({ kind: 'health-layer', scopeId, layerId })}
+        onSelectFinding={setOpenFinding}
+      />
+    );
+    if (route.kind === 'health-layer') return (
+      <LayerDetailPage
+        state={state}
+        scopeId={route.scopeId}
+        layerId={route.layerId}
+        onBack={() => navigate({ kind: 'health' })}
+        onSelectFinding={setOpenFinding}
+      />
+    );
+    const scopeFilter = route.kind === 'roadmap' ? route.scope : undefined;
+    const layerFilter = route.kind === 'roadmap' ? route.layer : undefined;
+    return (
+      <RoadmapPage
+        state={state}
+        scopeFilter={scopeFilter}
+        layerFilter={layerFilter}
+        navigate={navigate}
+        onCardClick={(scopeId, item) => setOverlay({ kind: 'modal', scopeId, item })}
+        onPatch={handlePatch}
+      />
+    );
+  })();
+
+  return (
+    <>
+      <DotGrid />
+      <TopBar
+        mode={mode}
+        onSelectMode={onSelectMode}
+        onReload={reload}
+      />
+      {body}
+      {overlay?.kind === 'drawer' && (
+        <LayerDrawer
+          scopeId={overlay.scopeId}
+          layer={overlay.layer}
+          narrative={state.narratives[`${overlay.scopeId}/${overlay.layer.id}`] ?? null}
+          onClose={() => setOverlay(null)}
+        />
+      )}
+      {overlay?.kind === 'modal' && (
+        <ItemModal
+          item={overlay.item}
+          scopeId={overlay.scopeId}
+          layers={state.scopes.find(s => s.id === overlay.scopeId)?.layers ?? []}
+          relatedDocs={related}
+          state={state}
+          onClose={() => setOverlay(null)}
+          onPatch={async (p) => { await patch(overlay.scopeId, overlay.item.id, p); }}
+          onOpenFile={(path) => { tenboApi.openFile(path).catch(() => {}); }}
+          onPromoteRelated={async (path) => {
+            const cur = overlay.item.links ?? [];
+            if (!cur.includes(path)) {
+              await patch(overlay.scopeId, overlay.item.id, { links: [...cur, path] });
+            }
+          }}
+          onSelectItem={(sId, it) => {
+            // Cross-cutting items don't carry a scope — fall back to current scope
+            // so the modal still has a sensible scope for layer dropdowns.
+            setOverlay({ kind: 'modal', scopeId: sId ?? overlay.scopeId, item: it });
+          }}
+          navigate={navigate}
+        />
+      )}
+      <FindingModal
+        finding={openFinding}
+        allFindings={Object.values(state.metrics ?? {}).flatMap(m => m.findings ?? [])}
+        onClose={() => setOpenFinding(null)}
+        onOpenFile={(path) => { tenboApi.openFile(path).catch(() => {}); }}
+        onSelectFinding={setOpenFinding}
+      />
+    </>
+  );
+}

package/src/ErrorBoundary.tsx

@@ -0,0 +1,25 @@
+import { Component, ReactNode } from 'react';
+
+interface State { error: Error | null }
+
+export class ErrorBoundary extends Component<{ children: ReactNode }, State> {
+  state: State = { error: null };
+  static getDerivedStateFromError(error: Error) { return { error }; }
+  componentDidCatch(error: Error, info: unknown) {
+    console.error('UI crashed:', error, info);
+  }
+  render() {
+    if (this.state.error) {
+      return (
+        <div style={{ padding: 24, fontFamily: 'system-ui' }}>
+          <h2 style={{ color: 'var(--error)' }}>Something went wrong</h2>
+          <pre style={{ background: 'var(--bg-2)', padding: 12, borderRadius: 4, overflow: 'auto', fontSize: 12 }}>
+            {this.state.error.message}
+          </pre>
+          <button className="outlined-button" onClick={() => location.reload()}>Reload</button>
+        </div>
+      );
+    }
+    return this.props.children;
+  }
+}

package/src/api/client.ts

@@ -0,0 +1,41 @@
+import type { TenboState, RelatedDoc, Item, LayerDoc } from '../types';
+
+async function http<T>(url: string, init?: RequestInit): Promise<T> {
+  const r = await fetch(url, init);
+  if (!r.ok) throw new Error(`${init?.method ?? 'GET'} ${url} -> ${r.status}`);
+  return r.json() as Promise<T>;
+}
+
+export const tenboApi = {
+  getState(): Promise<TenboState> {
+    return http('/api/state');
+  },
+  getRelated(): Promise<RelatedDoc[]> {
+    return http('/api/related');
+  },
+  patchItem(scopeId: string, itemId: string, patch: Partial<Item>): Promise<{ ok: true }> {
+    return http(`/api/items/${itemId}`, {
+      method: 'PATCH',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ scope: scopeId, patch }),
+    });
+  },
+  reorder(scopeId: string, ids: string[]): Promise<{ ok: true }> {
+    return http('/api/items/reorder', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ scope: scopeId, ids }),
+    });
+  },
+  getLayerDocs(scopeId: string, layerId: string): Promise<LayerDoc[]> {
+    const params = new URLSearchParams({ scope: scopeId, layer: layerId });
+    return http(`/api/layer-docs?${params}`);
+  },
+  openFile(path: string): Promise<{ ok: true }> {
+    return http('/api/open', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ path }),
+    });
+  },
+};

package/src/api/lib/frontmatterScan.ts

@@ -0,0 +1,37 @@
+import { readdirSync, readFileSync, statSync, existsSync } from 'node:fs';
+import path from 'node:path';
+import matter from 'gray-matter';
+import type { RelatedDoc } from '../../types';
+
+const DEFAULT_DIRS = ['docs/superpowers/plans', 'docs/superpowers/specs'];
+
+function walk(dir: string, out: string[] = []): string[] {
+  if (!existsSync(dir)) return out;
+  for (const entry of readdirSync(dir)) {
+    const full = path.join(dir, entry);
+    const st = statSync(full);
+    if (st.isDirectory()) walk(full, out);
+    else if (st.isFile() && full.endsWith('.md')) out.push(full);
+  }
+  return out;
+}
+
+export function scanForRelated(repoRoot: string, extraDirs: string[] = []): RelatedDoc[] {
+  const dirs = [...DEFAULT_DIRS, ...extraDirs].map(d => path.join(repoRoot, d));
+  const files = dirs.flatMap(d => walk(d));
+  const out: RelatedDoc[] = [];
+  for (const file of files) {
+    const text = readFileSync(file, 'utf8');
+    const parsed = matter(text);
+    const itemId = parsed.data?.tenbo_item;
+    if (typeof itemId === 'string') {
+      const titleMatch = parsed.content.match(/^#\s+(.+)$/m);
+      out.push({
+        path: path.relative(repoRoot, file),
+        itemId,
+        title: titleMatch?.[1]?.trim(),
+      });
+    }
+  }
+  return out;
+}

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

@@ -0,0 +1,32 @@
+import { describe, it, expect } from 'vitest';
+import { analyzeAgingTodos, parseTodoLines } from './agingTodos';
+import { DEFAULT_HEALTH_CONFIG } from './config';
+
+describe('parseTodoLines', () => {
+  it('extracts TODO and FIXME with line numbers', () => {
+    const src = [
+      'function foo() {',
+      '  // TODO: fix this',
+      '  /* FIXME(poyi): broken */',
+      '  return 1;',
+      '}',
+    ].join('\n');
+    const matches = parseTodoLines(src);
+    expect(matches).toHaveLength(2);
+    expect(matches[0]).toEqual({ line: 2, text: 'TODO: fix this' });
+    expect(matches[1].line).toBe(3);
+  });
+
+  it('ignores TODO inside string literals', () => {
+    const src = `const s = "TODO this is a string";`;
+    expect(parseTodoLines(src)).toEqual([]);
+  });
+});
+
+describe('analyzeAgingTodos', () => {
+  // Smoke test: just ensure it returns an array on real-repo files without throwing.
+  it('does not throw on real files', () => {
+    const findings = analyzeAgingTodos(process.cwd(), 'lyr', [], DEFAULT_HEALTH_CONFIG);
+    expect(Array.isArray(findings)).toBe(true);
+  });
+});