tenbo-dashboard 0.1.0

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

@@ -0,0 +1,29 @@
+import { describe, it, expect } from 'vitest';
+import type { Finding } from './types';
+import { SEVERITY_RANK, SIGNAL_WEIGHTS_DEFAULT } from './types';
+
+describe('health types', () => {
+  it('SEVERITY_RANK orders critical > warning > info', () => {
+    expect(SEVERITY_RANK.critical).toBeGreaterThan(SEVERITY_RANK.warning);
+    expect(SEVERITY_RANK.warning).toBeGreaterThan(SEVERITY_RANK.info);
+  });
+
+  it('SIGNAL_WEIGHTS_DEFAULT places dead-code first', () => {
+    expect(SIGNAL_WEIGHTS_DEFAULT[0]).toBe('dead-code');
+  });
+
+  it('Finding type has the expected shape', () => {
+    const f: Finding = {
+      id: 'x.dead-code.foo',
+      signal: 'dead-code',
+      severity: 'critical',
+      confidence: 'high',
+      layer: 'x',
+      target: 'apps/editor/foo.ts',
+      headline: 'foo has no consumers',
+      suggestion: { summary: 'Delete file', rationale: 'unused', action_kind: 'delete-file' },
+      details: { kind: 'dead-code', exports: [], last_imported_commit: null, git_age_days: 0 },
+    };
+    expect(f.signal).toBe('dead-code');
+  });
+});

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

@@ -0,0 +1,85 @@
+export type Severity = 'critical' | 'warning' | 'info';
+
+export type Confidence = 'high' | 'medium' | 'low';
+
+export type Signal =
+  | 'hotspot-files'
+  | 'dead-code'
+  | 'coupling'
+  | 'doc-drift'
+  | 'test-coverage'
+  | 'aging-todos'
+  | 'architecture-compliance'
+  | 'redundancy';
+
+export type ActionKind =
+  | 'delete-file'
+  | 'unexport'
+  | 'split-file'
+  | 'extract-shared'
+  | 'move-file'
+  | 'update-doc'
+  | 'add-test'
+  | 'resolve-todo';
+
+export interface Suggestion {
+  summary: string;       // imperative one-liner
+  rationale: string;     // why
+  action_kind: ActionKind;
+}
+
+// Signal-specific details payloads (discriminated union)
+export type FindingDetails =
+  | { kind: 'hotspot-files'; loc: number; top_functions: { name: string; loc: number }[]; commits_30d: number; split_candidates: string[] }
+  | { kind: 'dead-code'; exports: string[]; last_imported_commit: string | null; git_age_days: number }
+  | { kind: 'coupling'; source_file: string; target_file: string; import_lines: number[]; crosses_public_api: boolean }
+  | { kind: 'doc-drift'; drift_type: 'missing-ref' | 'unreferenced-file' | 'stale-section'; doc_path: string; doc_mtime_iso: string | null; code_mtime_iso: string | null; affected_files: string[] }
+  | { kind: 'test-coverage'; suggested_test_path: string }
+  | { kind: 'aging-todos'; line: number; age_days: number; commit_hash: string; author: string; text: string; context: string }
+  | { kind: 'architecture-compliance'; expected_path_pattern: string; actual_path: string; rule: string }
+  | { kind: 'redundancy'; copies: { path: string; lines: [number, number] }[]; similarity_pct: number };
+
+export interface Finding {
+  id: string;             // "<layer>.<signal>.<short-target>"
+  signal: Signal;
+  severity: Severity;
+  confidence: Confidence;
+  layer: string;
+  target: string;         // primary file path (repo-relative)
+  headline: string;
+  suggestion: Suggestion;
+  details: FindingDetails;
+}
+
+export const SEVERITY_RANK: Record<Severity, number> = {
+  critical: 3,
+  warning: 2,
+  info: 1,
+};
+
+export const SIGNAL_WEIGHTS_DEFAULT: Signal[] = [
+  'dead-code',
+  'hotspot-files',
+  'coupling',
+  'architecture-compliance',
+  'redundancy',
+  'doc-drift',
+  'test-coverage',
+  'aging-todos',
+];
+
+export const CONFIDENCE_RANK: Record<Confidence, number> = {
+  high: 3,
+  medium: 2,
+  low: 1,
+};
+
+// Compile-time guarantee that FindingDetails has exactly one variant per Signal.
+// If Signal gains a value or FindingDetails loses one (or vice versa),
+// these aliases will fail to type-check and the build breaks.
+type _SignalsCoverDetails = Exclude<Signal, FindingDetails['kind']> extends never ? true : never;
+type _DetailsCoverSignals = Exclude<FindingDetails['kind'], Signal> extends never ? true : never;
+const _signalCoverage: _SignalsCoverDetails = true;
+const _detailsCoverage: _DetailsCoverSignals = true;
+void _signalCoverage;
+void _detailsCoverage;

package/src/api/lib/http.ts

@@ -0,0 +1,34 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+
+export function readBody<T = unknown>(req: IncomingMessage): Promise<T> {
+  return new Promise((resolve, reject) => {
+    let buf = '';
+    req.on('data', (c: Buffer) => (buf += c));
+    req.on('end', () => {
+      try { resolve(JSON.parse(buf || '{}') as T); } catch (e) { reject(e); }
+    });
+    req.on('error', reject);
+  });
+}
+
+export function json(res: ServerResponse, body: unknown, status = 200): void {
+  res.statusCode = status;
+  res.setHeader('Content-Type', 'application/json');
+  res.end(JSON.stringify(body));
+}
+
+export function error(res: ServerResponse, status: number, message: string): void {
+  json(res, { error: message }, status);
+}
+
+/** Wraps a handler so any thrown error becomes a 500 JSON response. */
+export function withErrorHandling<T extends (...args: any[]) => any>(handler: T): T {
+  return (async (...args: Parameters<T>) => {
+    const [, res] = args as unknown as [IncomingMessage, ServerResponse];
+    try {
+      return await handler(...args);
+    } catch (err) {
+      error(res, 500, String(err));
+    }
+  }) as T;
+}

package/src/api/lib/metrics.test.ts

@@ -0,0 +1,81 @@
+import { mkdtempSync, mkdirSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { describe, it, expect } from 'vitest';
+import { computeScopeMetrics, globMatches } from './metrics';
+import type { Scope } from '../../types';
+
+function tmp(structure: Record<string, string>) {
+  const root = mkdtempSync(path.join(tmpdir(), 'tenbo-metrics-'));
+  for (const [rel, content] of Object.entries(structure)) {
+    const full = path.join(root, rel);
+    mkdirSync(path.dirname(full), { recursive: true });
+    writeFileSync(full, content);
+  }
+  return root;
+}
+
+describe('computeScopeMetrics', () => {
+  it('counts files matching glob and totals lines', () => {
+    const root = tmp({
+      'src/a.ts': 'one\ntwo\nthree\n',
+      'src/b.ts': 'one\n',
+    });
+    const scope: Scope = {
+      id: 'e', path: '.', description: 'x',
+      layers: [{ id: 'l', name: 'L', description: 'x', files: ['src/**/*.ts'], dependencies: { outbound: ['x'] } } as any],
+      items: [],
+    };
+    const m = computeScopeMetrics(root, scope, {});
+    expect(m.layers.l.file_count).toBe(2);
+    expect(m.layers.l.total_lines).toBe(4);
+    expect(m.layers.l.outbound_deps).toBe(1);
+  });
+
+  it('computes intent_age_days from layerDocs mtime', () => {
+    const sevenDaysAgo = Date.now() - 7 * 24 * 3600 * 1000;
+    const m = computeScopeMetrics('/x', {
+      id: 'e', path: '.', description: 'x',
+      layers: [{ id: 'l', name: 'L', description: 'x', files: [] } as any],
+      items: [],
+    }, { 'e/l': { hasIntent: true, hasCodeMap: false, intentMtime: sevenDaysAgo, codeMapMtime: null, intentEmpty: false } });
+    expect(m.layers.l.intent_age_days).toBe(7);
+  });
+
+  it('matches `src/**/*.ts` across zero and many intermediate segments', () => {
+    const root = tmp({
+      'src/a.ts': 'x\n',
+      'src/sub/b.ts': 'x\n',
+      'src/sub/deep/c.ts': 'x\n',
+    });
+    const scope: Scope = {
+      id: 'e', path: '.', description: 'x',
+      layers: [{ id: 'l', name: 'L', description: 'x', files: ['src/**/*.ts'] } as any],
+      items: [],
+    };
+    const m = computeScopeMetrics(root, scope, {});
+    expect(m.layers.l.file_count).toBe(3);
+  });
+});
+
+describe('globMatches', () => {
+  it('handles `src/**/*.ts` with zero or many segments', () => {
+    expect(globMatches('src/**/*.ts', 'src/a.ts')).toBe(true);
+    expect(globMatches('src/**/*.ts', 'src/sub/a.ts')).toBe(true);
+    expect(globMatches('src/**/*.ts', 'src/sub/deep/a.ts')).toBe(true);
+    expect(globMatches('src/**/*.ts', 'other/a.ts')).toBe(false);
+  });
+
+  it('handles leading `**/` matching root', () => {
+    expect(globMatches('**/foo.ts', 'foo.ts')).toBe(true);
+    expect(globMatches('**/foo.ts', 'dir/foo.ts')).toBe(true);
+    expect(globMatches('**/foo.ts', 'dir/sub/foo.ts')).toBe(true);
+  });
+
+  it('honors `*` segment-non-crossing', () => {
+    expect(globMatches('src/*.ts', 'src/a.ts')).toBe(true);
+    expect(globMatches('src/*.ts', 'src/sub/a.ts')).toBe(false);
+    expect(globMatches('*.ts', 'a.ts')).toBe(true);
+    expect(globMatches('*.ts', 'sub/a.ts')).toBe(false);
+  });
+});

package/src/api/lib/metrics.ts

@@ -0,0 +1,78 @@
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import path from 'node:path';
+import type { LayerDocs, Scope, ScopeMetrics, LayerMetrics } from '../../types';
+
+function matchGlob(repoRoot: string, scopePath: string, globs: string[]): string[] {
+  const root = path.resolve(repoRoot, scopePath);
+  const matches: string[] = [];
+  if (!existsSync(root)) return matches;
+  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 rel = path.relative(root, full).split(path.sep).join('/');
+        if (globs.some(g => globMatches(g, rel))) matches.push(full);
+      }
+    }
+  }
+  walk(root);
+  return matches;
+}
+
+export function globMatches(glob: string, rel: string): boolean {
+  // Convert glob to RegExp. `/**/` collapses to "any number of path segments
+  // including zero" so `src/**/*.ts` matches both `src/a.ts` and `src/foo/a.ts`.
+  // A leading `**/` similarly collapses, so `**/foo.ts` matches both `foo.ts`
+  // (root) and `dir/foo.ts`. Bare `**` becomes `.*`; `*` becomes `[^/]*`.
+  // Placeholders protect each transformation from later passes.
+  const escaped = glob
+    .replace(/[.+^${}()|[\]\\]/g, '\\$&')
+    .replace(/^\*\*\//, '__LEADGLOBSTAR__')
+    .replace(/\/\*\*\//g, '__SLASHGLOBSTARSLASH__')
+    .replace(/\*\*/g, '__GLOBSTAR__')
+    .replace(/\*/g, '[^/]*')
+    .replace(/__GLOBSTAR__/g, '.*')
+    .replace(/__SLASHGLOBSTARSLASH__/g, '(?:/|/.*/)')
+    .replace(/__LEADGLOBSTAR__/g, '(?:|.*/)');
+  return new RegExp('^' + escaped + '$').test(rel);
+}
+
+function lineCount(filePath: string): number {
+  const content = readFileSync(filePath, 'utf8');
+  if (content.length === 0) return 0;
+  return content.split('\n').length - (content.endsWith('\n') ? 1 : 0);
+}
+
+export function computeScopeMetrics(
+  repoRoot: string,
+  scope: Scope,
+  layerDocs: Record<string, LayerDocs>,
+): ScopeMetrics {
+  const layers: Record<string, LayerMetrics> = {};
+  for (const layer of scope.layers) {
+    const matched = matchGlob(repoRoot, scope.path, layer.files ?? []);
+    const totalLines = matched.reduce((sum, f) => sum + lineCount(f), 0);
+    const outbound = layer.dependencies?.outbound?.length ?? 0;
+    const docs = layerDocs[`${scope.id}/${layer.id}`];
+    const intentAgeDays = docs?.intentMtime != null
+      ? Math.floor((Date.now() - docs.intentMtime) / (24 * 3600 * 1000))
+      : null;
+    const layerItems = scope.items.filter(i => i.layer === layer.id || i.layers?.includes(layer.id));
+    const nowItems = layerItems.filter(i => i.status === 'now').length;
+    const pctNow = layerItems.length === 0 ? 0 : Math.round((nowItems / layerItems.length) * 100);
+    layers[layer.id] = {
+      file_count: matched.length,
+      total_lines: totalLines,
+      outbound_deps: outbound,
+      deep_dive_count: 0, // populated by readDeepDiveCount when wired up
+      intent_age_days: intentAgeDays,
+      pct_roadmap_in_now: pctNow,
+    };
+  }
+  return { generated_at: new Date().toISOString(), layers, findings: [] };
+}

package/src/api/lib/metricsRefresh.test.ts

@@ -0,0 +1,54 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { mkdtempSync, rmSync, mkdirSync, writeFileSync, existsSync, statSync, utimesSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { ensureFresh } from './metricsRefresh.js';
+
+let dir: string;
+
+beforeEach(() => {
+  dir = mkdtempSync(path.join(tmpdir(), 'tenbo-mr-'));
+  const scope = path.join(dir, '.tenbo', 'scopes', 'editor');
+  const layer = path.join(scope, 'layers', 'foo');
+  mkdirSync(layer, { recursive: true });
+  writeFileSync(path.join(dir, '.tenbo', 'workspace.yaml'), 'scopes:\n  - id: editor\n    path: scopes/editor\n');
+  writeFileSync(path.join(scope, 'architecture.yaml'), 'scope: editor\nlayers:\n  - id: foo\n    name: Foo\n    description: A small layer.\n    files: ["src/**"]\n    dependencies: { inbound: [], outbound: [], external: [] }\n');
+  writeFileSync(path.join(scope, 'roadmap.yaml'), 'items: []\n');
+  writeFileSync(path.join(layer, 'intent.md'), '# Foo\n');
+  writeFileSync(path.join(layer, 'code-map.md'), '# Foo map\n');
+});
+
+afterEach(() => rmSync(dir, { recursive: true, force: true }));
+
+describe('ensureFresh', () => {
+  it('writes metrics.json when it is missing', async () => {
+    const metricsPath = path.join(dir, '.tenbo', 'scopes', 'editor', 'metrics.json');
+    expect(existsSync(metricsPath)).toBe(false);
+    const result = await ensureFresh(dir, 'editor');
+    expect(existsSync(metricsPath)).toBe(true);
+    expect(result.layers).toBeDefined();
+  });
+
+  it('does not rewrite metrics.json when it is fresh', async () => {
+    const metricsPath = path.join(dir, '.tenbo', 'scopes', 'editor', 'metrics.json');
+    await ensureFresh(dir, 'editor');
+    const firstMtime = statSync(metricsPath).mtimeMs;
+    const future = new Date(firstMtime + 1000);
+    utimesSync(metricsPath, future, future);
+    const newMtime = statSync(metricsPath).mtimeMs;
+    await ensureFresh(dir, 'editor');
+    expect(statSync(metricsPath).mtimeMs).toBe(newMtime);
+  });
+
+  it('rewrites metrics.json when a tracked file is newer', async () => {
+    const metricsPath = path.join(dir, '.tenbo', 'scopes', 'editor', 'metrics.json');
+    await ensureFresh(dir, 'editor');
+    // Age metrics.json well into the past so the staleness check fires.
+    const stale = new Date(Date.now() - 60_000);
+    utimesSync(metricsPath, stale, stale);
+    const aged = statSync(metricsPath).mtimeMs;
+    await ensureFresh(dir, 'editor');
+    const after = statSync(metricsPath).mtimeMs;
+    expect(after).toBeGreaterThan(aged);
+  });
+});

package/src/api/lib/metricsRefresh.ts

@@ -0,0 +1,147 @@
+import path from 'node:path';
+import { existsSync, readdirSync, readFileSync, renameSync, statSync, writeFileSync } from 'node:fs';
+import { parse as parseSimple } from 'yaml';
+import { computeScopeMetrics } from './metrics.js';
+import { collectAll } from './health/collectAll.js';
+import { loadHealthConfig } from './health/config.js';
+import type { LayerDocs, Scope, ScopeMetrics, Item, Layer } from '../../types.js';
+
+const TRACKED_FILES = ['architecture.yaml', 'roadmap.yaml'];
+const TRACKED_LAYER_FILES = ['intent.md', 'code-map.md'];
+const FS_MTIME_TOLERANCE_MS = 1000;
+
+function safeMtime(p: string): number {
+  try { return statSync(p).mtimeMs; } catch { return 0; }
+}
+
+function latestMtimeUnder(scopeDir: string, repoRoot: string, scopePath: string): number {
+  let latest = 0;
+  for (const f of TRACKED_FILES) {
+    latest = Math.max(latest, safeMtime(path.join(scopeDir, f)));
+  }
+  const layersDir = path.join(scopeDir, 'layers');
+  let layerEntries: string[] = [];
+  try { layerEntries = readdirSync(layersDir); } catch { layerEntries = []; }
+  for (const layer of layerEntries) {
+    const layerDir = path.join(layersDir, layer);
+    let isDir = false;
+    try { isDir = statSync(layerDir).isDirectory(); } catch { continue; }
+    if (!isDir) continue;
+    for (const f of TRACKED_LAYER_FILES) {
+      latest = Math.max(latest, safeMtime(path.join(layerDir, f)));
+    }
+  }
+  // Health findings depend on the scope's source files and the health config.
+  // Without these, edits to source code (or threshold tuning) would be served
+  // from a stale metrics.json cache.
+  latest = Math.max(latest, safeMtime(path.join(repoRoot, '.tenbo', 'health.config.yaml')));
+  latest = Math.max(latest, latestMtimeInTree(path.resolve(repoRoot, scopePath)));
+  return latest;
+}
+
+function latestMtimeInTree(root: string): number {
+  let latest = 0;
+  let entries: string[];
+  try { entries = readdirSync(root); } catch { return 0; }
+  for (const entry of entries) {
+    if (entry === 'node_modules' || entry === '.git' || entry === 'dist' || entry === 'build') continue;
+    const full = path.join(root, entry);
+    let st;
+    try { st = statSync(full); } catch { continue; }
+    if (st.isDirectory()) {
+      latest = Math.max(latest, latestMtimeInTree(full));
+    } else {
+      latest = Math.max(latest, st.mtimeMs);
+    }
+  }
+  return latest;
+}
+
+function readScope(repoRoot: string, scopeId: string): Scope {
+  const tenbo = path.join(repoRoot, '.tenbo');
+  const wsText = readFileSync(path.join(tenbo, 'workspace.yaml'), 'utf8');
+  const ws = parseSimple(wsText) as { scopes?: { id: string; path: string; description?: string }[] };
+  const ref = ws.scopes?.find(s => s.id === scopeId);
+  if (!ref) throw new Error(`scope not found in workspace.yaml: ${scopeId}`);
+  const archText = readFileSync(path.join(tenbo, 'scopes', scopeId, 'architecture.yaml'), 'utf8');
+  const arch = parseSimple(archText) as { layers?: Layer[] };
+  const roadText = readFileSync(path.join(tenbo, 'scopes', scopeId, 'roadmap.yaml'), 'utf8');
+  const road = parseSimple(roadText) as { items?: Item[] };
+  return {
+    id: ref.id,
+    path: ref.path,
+    description: ref.description ?? '',
+    layers: arch.layers ?? [],
+    items: road.items ?? [],
+  };
+}
+
+function readLayerDocsForScope(repoRoot: string, scopeId: string): Record<string, LayerDocs> {
+  const dir = path.join(repoRoot, '.tenbo', 'scopes', scopeId, 'layers');
+  if (!existsSync(dir)) return {};
+  const out: Record<string, LayerDocs> = {};
+  for (const entry of readdirSync(dir)) {
+    const full = path.join(dir, entry);
+    let entrySt;
+    try { entrySt = statSync(full); } catch { continue; }
+    if (!entrySt.isDirectory()) continue;
+    const intentPath = path.join(full, 'intent.md');
+    const codeMapPath = path.join(full, 'code-map.md');
+    const intentExists = existsSync(intentPath);
+    const codeMapExists = existsSync(codeMapPath);
+    let intentEmpty = false;
+    if (intentExists) {
+      try {
+        const stripped = readFileSync(intentPath, 'utf8')
+          .replace(/<!--[\s\S]*?-->/g, '')
+          .replace(/^#.*$/gm, '')
+          .trim();
+        intentEmpty = stripped.length === 0;
+      } catch {
+        intentEmpty = false;
+      }
+    }
+    out[`${scopeId}/${entry}`] = {
+      hasIntent: intentExists,
+      hasCodeMap: codeMapExists,
+      intentMtime: intentExists ? statSync(intentPath).mtimeMs : null,
+      codeMapMtime: codeMapExists ? statSync(codeMapPath).mtimeMs : null,
+      intentEmpty,
+    };
+  }
+  return out;
+}
+
+export interface EnsureFreshOptions {
+  force?: boolean;
+}
+
+export async function ensureFresh(repoRoot: string, scopeId: string, opts: EnsureFreshOptions = {}): Promise<ScopeMetrics> {
+  const scopeDir = path.join(repoRoot, '.tenbo', 'scopes', scopeId);
+  const metricsPath = path.join(scopeDir, 'metrics.json');
+  const scope = readScope(repoRoot, scopeId);
+  const latestSource = latestMtimeUnder(scopeDir, repoRoot, scope.path);
+  const metricsMtime = safeMtime(metricsPath);
+
+  // Tolerance absorbs filesystem mtime precision loss (some FSes round to seconds)
+  // when comparing the metrics.json mtime against the latest tracked source mtime.
+  if (!opts.force && metricsMtime > 0 && metricsMtime + FS_MTIME_TOLERANCE_MS >= latestSource) {
+    try {
+      const raw = readFileSync(metricsPath, 'utf8');
+      return JSON.parse(raw) as ScopeMetrics;
+    } catch {
+      // Fall through to recompute on parse error (truncated/corrupt cache).
+    }
+  }
+
+  const layerDocs = readLayerDocsForScope(repoRoot, scopeId);
+  const baseMetrics = computeScopeMetrics(repoRoot, scope, layerDocs);
+  const healthConfig = loadHealthConfig(repoRoot);
+  const findings = await collectAll(repoRoot, scope, healthConfig);
+  const metrics: ScopeMetrics = { ...baseMetrics, findings };
+  // Atomic write: rename is atomic on POSIX so partial writes can't corrupt the cache.
+  const tmpPath = metricsPath + '.tmp';
+  writeFileSync(tmpPath, JSON.stringify(metrics, null, 2));
+  renameSync(tmpPath, metricsPath);
+  return metrics;
+}

package/src/api/lib/phases.test.ts

@@ -0,0 +1,76 @@
+import { describe, it, expect } from 'vitest';
+import { derivePhaseStatus, effectiveStatus, phaseProgress, isIsoDate } from './phases';
+import type { Item, Phase } from '../../types';
+
+const ph = (id: number, status: Phase['status'], extra: Partial<Phase> = {}): Phase => ({
+  id,
+  title: `phase ${id}`,
+  status,
+  ...extra,
+});
+
+describe('derivePhaseStatus', () => {
+  it('returns done when every phase is done', () => {
+    expect(derivePhaseStatus([ph(1, 'done'), ph(2, 'done')])).toBe('done');
+  });
+
+  it('returns now if any phase is now (even with later mixed in)', () => {
+    expect(derivePhaseStatus([ph(1, 'done'), ph(2, 'now'), ph(3, 'later')])).toBe('now');
+  });
+
+  it('returns next when no now but some next', () => {
+    expect(derivePhaseStatus([ph(1, 'done'), ph(2, 'next'), ph(3, 'later')])).toBe('next');
+  });
+
+  it('returns later when only later/done remain', () => {
+    expect(derivePhaseStatus([ph(1, 'done'), ph(2, 'later')])).toBe('later');
+  });
+
+  it('returns later for an empty list', () => {
+    expect(derivePhaseStatus([])).toBe('later');
+  });
+});
+
+describe('effectiveStatus', () => {
+  it('uses stored status when phases are absent', () => {
+    const item = { id: 'ed-001', title: 't', status: 'next', description: 'd' } as Item;
+    expect(effectiveStatus(item)).toBe('next');
+  });
+
+  it('uses derived status when phases are present', () => {
+    const item = {
+      id: 'ed-001',
+      title: 't',
+      status: 'later',
+      description: 'd',
+      phases: [ph(1, 'done'), ph(2, 'now')],
+    } as Item;
+    expect(effectiveStatus(item)).toBe('now');
+  });
+});
+
+describe('phaseProgress', () => {
+  it('counts done and total and surfaces the active phase', () => {
+    const phases = [ph(1, 'done'), ph(2, 'now'), ph(3, 'later')];
+    const p = phaseProgress(phases);
+    expect(p.done).toBe(1);
+    expect(p.total).toBe(3);
+    expect(p.active?.id).toBe(2);
+  });
+
+  it('omits active when no phase is now', () => {
+    const p = phaseProgress([ph(1, 'done'), ph(2, 'next')]);
+    expect(p.active).toBeUndefined();
+  });
+});
+
+describe('isIsoDate', () => {
+  it('accepts YYYY-MM-DD', () => {
+    expect(isIsoDate('2026-04-27')).toBe(true);
+  });
+  it('rejects other formats', () => {
+    expect(isIsoDate('2026-4-27')).toBe(false);
+    expect(isIsoDate('04/27/2026')).toBe(false);
+    expect(isIsoDate('2026-04-27T00:00:00Z')).toBe(false);
+  });
+});

package/src/api/lib/phases.ts

@@ -0,0 +1,48 @@
+/**
+ * Shared helpers for the optional `phases:` field on roadmap items.
+ *
+ * Roll-up rule (single source of truth, mirrored in the validator and the viewer):
+ *   - `done`  if every phase has status `done`
+ *   - `now`   if any phase has status `now`
+ *   - else `next`  if any phase has status `next`
+ *   - else `later`
+ *
+ * Items without `phases:` are unaffected — their explicit `status:` is the source
+ * of truth.
+ */
+import type { Item, Phase, Status } from '../../types';
+
+export const VALID_PHASE_STATUSES: ReadonlySet<Status> = new Set(['now', 'next', 'later', 'done']);
+
+/** YYYY-MM-DD shape check. Does not validate calendar correctness. */
+export function isIsoDate(s: string): boolean {
+  return /^\d{4}-\d{2}-\d{2}$/.test(s);
+}
+
+/** Compute a derived item status from a non-empty phase list. */
+export function derivePhaseStatus(phases: Phase[]): Status {
+  if (phases.length === 0) return 'later';
+  if (phases.every((p) => p.status === 'done')) return 'done';
+  if (phases.some((p) => p.status === 'now')) return 'now';
+  if (phases.some((p) => p.status === 'next')) return 'next';
+  return 'later';
+}
+
+/** Returns the effective status for an item — derived if phases present, else stored. */
+export function effectiveStatus(item: Item): Status {
+  if (item.phases && item.phases.length > 0) return derivePhaseStatus(item.phases);
+  return item.status;
+}
+
+export interface PhaseProgress {
+  done: number;
+  total: number;
+  /** Phase currently `now`, if any. Useful for highlighting. */
+  active?: Phase;
+}
+
+export function phaseProgress(phases: Phase[]): PhaseProgress {
+  const done = phases.filter((p) => p.status === 'done').length;
+  const active = phases.find((p) => p.status === 'now');
+  return { done, total: phases.length, ...(active ? { active } : {}) };
+}