@xera-ai/core 0.9.8 → 0.10.0

package/src/bin-internal/fill-gap-finalize.ts

@@ -0,0 +1,115 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { z } from 'zod';
+
+const ProposalsSchema = z.object({
+  proposals: z.array(
+    z.object({
+      id: z.string().min(1),
+      ticketId: z.string().min(1),
+      title: z.string().min(1),
+      rationale: z.string().min(1),
+      gherkin: z.string().min(1),
+      satisfiesAcs: z.array(z.number().int().nonnegative()),
+    }),
+  ),
+});
+
+interface ParsedArgs {
+  accept: string;
+  ticket: string;
+  source?: string;
+  force: boolean;
+}
+
+function parseArgs(argv: string[]): ParsedArgs | { error: string } {
+  let accept: string | undefined;
+  let ticket: string | undefined;
+  let source: string | undefined;
+  let force = false;
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--accept') {
+      const v = argv[++i];
+      if (v !== undefined) accept = v;
+    } else if (a === '--ticket') {
+      const v = argv[++i];
+      if (v !== undefined) ticket = v;
+    } else if (a === '--source') {
+      const v = argv[++i];
+      if (v !== undefined) source = v;
+    } else if (a === '--force') {
+      force = true;
+    } else if (a === '--help-stub') {
+      /* no-op */
+    } else {
+      return { error: `unknown flag: ${a}` };
+    }
+  }
+  if (!accept || !ticket) return { error: 'required: --accept <proposal-id> --ticket <TICKET>' };
+  const out: ParsedArgs = { accept, ticket, force };
+  if (source !== undefined) out.source = source;
+  return out;
+}
+
+function formatDraft(
+  ticketId: string,
+  proposal: z.infer<typeof ProposalsSchema>['proposals'][number],
+): string {
+  const lines = [
+    `# Draft scenario for ${ticketId}`,
+    '',
+    `> ${proposal.rationale}`,
+    '',
+    proposal.gherkin,
+    '',
+  ];
+  if (proposal.satisfiesAcs.length > 0) {
+    lines.push(`<!-- satisfiesAcs: [${proposal.satisfiesAcs.join(', ')}] -->`);
+    lines.push('');
+  }
+  return lines.join('\n');
+}
+
+export async function fillGapFinalizeCmd(argv: string[]): Promise<number> {
+  if (argv.includes('--help-stub')) {
+    /* test scaffold no-op */
+  }
+  const parsed = parseArgs(argv);
+  if ('error' in parsed) {
+    console.error(`[fill-gap-finalize] ${parsed.error}`);
+    return 1;
+  }
+
+  const cwd = process.cwd();
+  const sourcePath = parsed.source ?? join(cwd, '.xera/coverage/proposals.json');
+  if (!existsSync(sourcePath)) {
+    console.error(`[fill-gap-finalize] source not found: ${sourcePath}`);
+    return 2;
+  }
+
+  let proposals: z.infer<typeof ProposalsSchema>;
+  try {
+    const raw = JSON.parse(readFileSync(sourcePath, 'utf8'));
+    proposals = ProposalsSchema.parse(raw);
+  } catch (e) {
+    console.error(`[fill-gap-finalize] invalid proposals: ${(e as Error).message}`);
+    return 2;
+  }
+
+  const proposal = proposals.proposals.find((p) => p.id === parsed.accept);
+  if (!proposal) {
+    console.error(`[fill-gap-finalize] proposal id "${parsed.accept}" not in source`);
+    return 2;
+  }
+
+  const ticketDir = join(cwd, '.xera', parsed.ticket);
+  mkdirSync(ticketDir, { recursive: true });
+  const draftPath = join(ticketDir, 'feature.draft.md');
+  if (existsSync(draftPath) && !parsed.force) {
+    console.error(`[fill-gap-finalize] ${draftPath} exists; pass --force to overwrite`);
+    return 3;
+  }
+  writeFileSync(draftPath, formatDraft(parsed.ticket, proposal));
+  return 0;
+}

package/src/bin-internal/fill-gap-prepare.ts

@@ -0,0 +1,150 @@
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { deriveSnapshot, loadAllEvents } from '../graph/store';
+import type { Snapshot } from '../graph/types';
+
+interface AreaContext {
+  mode: 'area';
+  area: string;
+  tickets: Array<{ id: string; summary: string; ac: string[] }>;
+  existingScenarios: Array<{ areaSlug: string; gherkin: string }>;
+}
+
+interface TicketContext {
+  mode: 'ticket';
+  ticket: { id: string; summary: string; ac: string[] };
+  unsatisfiedAcs: Array<{ index: number; text: string }>;
+  existingScenarios: Array<{ scenarioId: string; name: string; gherkin: string }>;
+}
+
+interface ParsedArgs {
+  area?: string;
+  ticket?: string;
+  outputDir?: string;
+}
+
+function parseArgs(argv: string[]): ParsedArgs | { error: string } {
+  const args: ParsedArgs = {};
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--area') {
+      const v = argv[++i];
+      if (v !== undefined) args.area = v;
+    } else if (a === '--ticket') {
+      const v = argv[++i];
+      if (v !== undefined) args.ticket = v;
+    } else if (a === '--output-dir') {
+      const v = argv[++i];
+      if (v !== undefined) args.outputDir = v;
+    } else if (a === '--help-stub') {
+      /* no-op */
+    } else {
+      return { error: `unknown flag: ${a}` };
+    }
+  }
+  if (!args.area && !args.ticket) return { error: 'one of --area or --ticket required' };
+  if (args.area && args.ticket) return { error: '--area and --ticket are mutually exclusive' };
+  return args;
+}
+
+function buildAreaContext(snap: Snapshot, area: string): AreaContext | null {
+  // Use modifiesAreas on ticket nodes (set from ticket.fetched) to find tickets for this area.
+  // edge.discovered with kind='modifies' is an additional source, but ticket.fetched also
+  // populates ticket.modifiesAreas directly — so check both.
+  const edgeTicketIds = new Set(
+    snap.edges.filter((e) => e.kind === 'modifies' && e.to === area).map((e) => e.from),
+  );
+  const ticketsForArea = Object.values(snap.tickets).filter(
+    (t) => t.modifiesAreas.includes(area) || edgeTicketIds.has(t.id),
+  );
+  if (ticketsForArea.length === 0) return null;
+
+  // existingScenarios from other areas — limit to 3 to keep prompt input small
+  const scenariosFromOtherAreas = Object.values(snap.scenarios)
+    .filter((s) => {
+      const t = snap.tickets[s.ticketId];
+      if (!t) return false;
+      return !t.modifiesAreas.includes(area) && t.modifiesAreas.length > 0;
+    })
+    .slice(0, 3)
+    .map((s) => {
+      const ownerTicket = snap.tickets[s.ticketId];
+      const areaSlug = ownerTicket?.modifiesAreas[0] ?? 'unknown';
+      return { areaSlug, gherkin: s.gherkin };
+    });
+
+  return {
+    mode: 'area',
+    area,
+    tickets: ticketsForArea.map((t) => ({ id: t.id, summary: t.summary, ac: t.ac })),
+    existingScenarios: scenariosFromOtherAreas,
+  };
+}
+
+function buildTicketContext(snap: Snapshot, ticketId: string): TicketContext | null {
+  const ticket = snap.tickets[ticketId];
+  if (!ticket) return null;
+
+  const acNodesForTicket = Object.values(snap.acNodes)
+    .filter((ac) => ac.ticketId === ticketId)
+    .sort((a, b) => a.index - b.index);
+  const satisfiedAcIds = new Set(
+    snap.edges
+      .filter((e) => e.kind === 'satisfies' && acNodesForTicket.some((ac) => ac.id === e.to))
+      .map((e) => e.to),
+  );
+  const unsatisfiedAcs = acNodesForTicket
+    .filter((ac) => !satisfiedAcIds.has(ac.id))
+    .map((ac) => ({ index: ac.index, text: ac.text }));
+
+  if (unsatisfiedAcs.length === 0) return null;
+
+  const existingScenarios = Object.values(snap.scenarios)
+    .filter((s) => s.ticketId === ticketId)
+    .map((s) => ({ scenarioId: s.id, name: s.name, gherkin: s.gherkin }));
+
+  return {
+    mode: 'ticket',
+    ticket: { id: ticket.id, summary: ticket.summary, ac: ticket.ac },
+    unsatisfiedAcs,
+    existingScenarios,
+  };
+}
+
+export async function fillGapPrepareCmd(argv: string[]): Promise<number> {
+  const parsed = parseArgs(argv);
+  if ('error' in parsed) {
+    console.error(`[fill-gap-prepare] ${parsed.error}`);
+    return 1;
+  }
+
+  const cwd = process.cwd();
+  const snap = deriveSnapshot(loadAllEvents(cwd));
+
+  let context: AreaContext | TicketContext | null;
+  let scope: string;
+  if (parsed.area) {
+    context = buildAreaContext(snap, parsed.area);
+    scope = parsed.area;
+    if (!context) {
+      console.error(
+        `[fill-gap-prepare] area "${parsed.area}" has no tickets modifying it; cannot fill`,
+      );
+      return 2;
+    }
+  } else {
+    context = buildTicketContext(snap, parsed.ticket!);
+    scope = parsed.ticket!;
+    if (!context) {
+      console.error(
+        `[fill-gap-prepare] ticket "${parsed.ticket}" not found or has no unsatisfied ACs`,
+      );
+      return 2;
+    }
+  }
+
+  const outDir = parsed.outputDir ?? join(cwd, '.xera/coverage', scope);
+  mkdirSync(outDir, { recursive: true });
+  writeFileSync(join(outDir, 'context.json'), JSON.stringify(context, null, 2));
+  return 0;
+}

package/src/bin-internal/graph-render.ts

@@ -1,8 +1,9 @@
-import { mkdirSync, renameSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
-import type { RenderOpts } from '../graph/render';
+import type { CoverageInput, RenderOpts } from '../graph/render';
 import { renderHtml, transformForVisNetwork } from '../graph/render';
 import { deriveSnapshot, loadAllEvents } from '../graph/store';
+import type { CoverageSnapshotPayload, Event } from '../graph/types';
 
 function parseDepth(s: string | undefined): 1 | 2 | 3 {
   const n = s ? Number.parseInt(s, 10) : 2;
@@ -21,18 +22,21 @@ export async function graphRenderCmd(argv: string[]): Promise<number> {
   let ticketId: string | undefined;
   let since: string | undefined;
   let depth: 1 | 2 | 3 = 2;
+  let includeCoverage = false;
 
   for (let i = 0; i < argv.length; i++) {
     if (argv[i] === '--out') outPath = argv[++i];
     else if (argv[i] === '--ticket') ticketId = argv[++i];
     else if (argv[i] === '--since') since = argv[++i];
     else if (argv[i] === '--depth') depth = parseDepth(argv[++i]);
+    else if (argv[i] === '--include-coverage') includeCoverage = true;
   }
 
   const repoRoot = process.cwd();
   const finalPath = outPath ?? join(repoRoot, '.xera/graph.html');
 
-  const snap = deriveSnapshot(loadAllEvents(repoRoot));
+  const events = loadAllEvents(repoRoot);
+  const snap = deriveSnapshot(events);
   const totalNodeCount =
     Object.keys(snap.tickets).length +
     Object.keys(snap.scenarios).length +
@@ -55,8 +59,32 @@ export async function graphRenderCmd(argv: string[]): Promise<number> {
   if (ticketId) opts.ticketId = ticketId;
   if (since) opts.since = since;
 
+  let coverage: CoverageInput | undefined;
+  if (includeCoverage) {
+    const reportPath = join(repoRoot, '.xera/coverage/report.json');
+    if (existsSync(reportPath)) {
+      const report = JSON.parse(readFileSync(reportPath, 'utf8'));
+      const snapshots = events
+        .filter(
+          (e): e is Extract<Event, { type: 'coverage.snapshot' }> => e.type === 'coverage.snapshot',
+        )
+        .map((e) => e.payload as CoverageSnapshotPayload);
+      coverage = { report, snapshots };
+    } else {
+      console.warn(
+        '[graph-render] --include-coverage: report.json not found; run /xera-coverage first',
+      );
+    }
+  }
+
   const data = transformForVisNetwork(snap, opts);
-  const html = renderHtml({ data, stats: data.stats, generatedAt: new Date().toISOString() });
+  const renderInput: Parameters<typeof renderHtml>[0] = {
+    data,
+    stats: data.stats,
+    generatedAt: new Date().toISOString(),
+  };
+  if (coverage) renderInput.coverage = coverage;
+  const html = renderHtml(renderInput);
 
   mkdirSync(dirname(finalPath), { recursive: true });
   const tmpPath = `${finalPath}.tmp`;

package/src/bin-internal/index.ts

@@ -1,4 +1,7 @@
+import { acCoverageBackfillFinalizeCmd } from './ac-coverage-backfill-finalize';
+import { acCoverageBackfillPrepareCmd } from './ac-coverage-backfill-prepare';
 import { authSetupCmd } from './auth-setup';
+import { coveragePrepareCmd } from './coverage-prepare';
 import { disputesCmd } from './disputes';
 import { doctorCmd } from './doctor';
 import { evalDeterministicCmd } from './eval-deterministic';
@@ -6,6 +9,8 @@ import { evalPrepareCmd } from './eval-prepare';
 import { evalReportCmd } from './eval-report';
 import { execCmd } from './exec';
 import { fetchCmd } from './fetch';
+import { fillGapFinalizeCmd } from './fill-gap-finalize';
+import { fillGapPrepareCmd } from './fill-gap-prepare';
 import { graphBackfillCmd } from './graph-backfill';
 import { graphEnrichCmd } from './graph-enrich';
 import { graphQueryCmd } from './graph-query';
@@ -26,13 +31,18 @@ import { validateFeatureCmd } from './validate-feature';
 import { verifyPromptsCmd } from './verify-prompts';
 
 const COMMANDS: Record<string, (argv: string[]) => Promise<number>> = {
+  'ac-coverage-backfill-finalize': acCoverageBackfillFinalizeCmd,
+  'ac-coverage-backfill-prepare': acCoverageBackfillPrepareCmd,
   'auth-setup': authSetupCmd,
+  'coverage-prepare': coveragePrepareCmd,
   disputes: disputesCmd,
   doctor: doctorCmd,
   'eval-deterministic': evalDeterministicCmd,
   'eval-prepare': evalPrepareCmd,
   'eval-report': evalReportCmd,
   exec: execCmd,
+  'fill-gap-finalize': fillGapFinalizeCmd,
+  'fill-gap-prepare': fillGapPrepareCmd,
   fetch: fetchCmd,
   'graph-backfill': graphBackfillCmd,
   'graph-enrich': graphEnrichCmd,

package/src/bin-internal/verify-prompts.ts

@@ -14,6 +14,8 @@ const IN_SCOPE_PROMPTS = [
   'extract-areas.md',
   'similarity-match.md',
   'classify-outdated.md',
+  'map-ac-to-scenarios.md',
+  'propose-scenarios.md', // NEW v0.8.2
 ] as const;
 
 const REQUIRED_SECTION_HEADING = '## Handling untrusted input';

package/src/config/schema.ts

@@ -111,6 +111,14 @@ const RunSchema = z
   })
   .prefault({});
 
+const CoverageSchema = z
+  .object({
+    staleAfterDays: z.number().int().positive().default(30),
+    criticalAreas: z.array(z.string().regex(/^[a-z0-9-]+$/)).default([]),
+    autoSnapshotOnCoverage: z.boolean().default(true),
+  })
+  .prefault({});
+
 export const XeraConfigSchema = z
   .object({
     jira: JiraSchema,
@@ -119,6 +127,7 @@ export const XeraConfigSchema = z
     ai: AISchema,
     reporting: ReportingSchema,
     run: RunSchema.prefault({}),
+    coverage: CoverageSchema,
     adapters: z
       .array(z.enum(['web', 'http']))
       .min(1)

package/src/coverage/index.ts

@@ -0,0 +1,29 @@
+export {
+  type AreaReportRow,
+  buildCoverageReport,
+  type CoverageReport,
+  type RenderOptions,
+  renderMarkdown,
+  type TicketReportRow,
+} from './report';
+export {
+  computeAcGapScore,
+  computeAreaRisk,
+  RISK_WEIGHTS,
+} from './risk';
+export {
+  type AcStatus,
+  type AreaStatus,
+  computeAcStatus,
+  computeAreaStatus,
+  computeScenarioStatus,
+  computeTicketStatus,
+  type ScenarioStatus,
+  type TicketStatus,
+} from './status';
+export type { CoverageConfig } from './types';
+export { DEFAULT_COVERAGE_CONFIG } from './types';
+export {
+  buildWhyArea,
+  buildWhyTicket,
+} from './why';

package/src/coverage/report.ts

@@ -0,0 +1,206 @@
+import type { Snapshot } from '../graph/types';
+import { computeAcGapScore, computeAreaRisk, RISK_WEIGHTS } from './risk';
+import { type AreaStatus, computeAcStatus, computeAreaStatus, computeTicketStatus } from './status';
+import type { CoverageConfig } from './types';
+
+export interface AreaReportRow {
+  id: string;
+  status: AreaStatus;
+  risk: number;
+  breakdown: {
+    recentTickets: number;
+    recentBugs: number;
+    criticalBoost: 1 | 2;
+  };
+}
+
+export interface TicketReportRow {
+  id: string;
+  summary: string;
+  acCount: number;
+  satisfiedCount: number;
+  gapScore: number;
+  unsatisfiedAcs: Array<{ index: number; text: string }>;
+}
+
+export interface CoverageReport {
+  generatedAt: string;
+  windowDays: number;
+  areas: AreaReportRow[];
+  tickets: TicketReportRow[];
+  acBackfillNeeded: boolean;
+}
+
+const STATUS_RANK: Record<AreaStatus, number> = {
+  UNCOVERED: 0,
+  STALE: 1,
+  COVERED: 2,
+};
+
+function daysBetween(a: Date, b: Date): number {
+  return Math.abs(a.getTime() - b.getTime()) / (1000 * 60 * 60 * 24);
+}
+
+export function buildCoverageReport(
+  snap: Snapshot,
+  config: CoverageConfig,
+  now: Date,
+): CoverageReport {
+  const areas: AreaReportRow[] = Object.keys(snap.areas).map((areaId) => {
+    const status = computeAreaStatus(areaId, snap, config.staleAfterDays, now);
+    const risk = computeAreaRisk(areaId, snap, config, now);
+
+    const recentTickets = snap.edges
+      .filter((e) => e.kind === 'modifies' && e.to === areaId)
+      .map((e) => snap.tickets[e.from])
+      .filter((t): t is NonNullable<typeof t> => t !== undefined)
+      .filter((t) => daysBetween(now, new Date(t.fetchedAt)) <= config.staleAfterDays).length;
+    const pomsInArea = snap.edges
+      .filter((e) => e.kind === 'covers' && e.to === areaId)
+      .map((e) => e.from);
+    const scenariosInArea = new Set(
+      snap.edges.filter((e) => e.kind === 'uses' && pomsInArea.includes(e.to)).map((e) => e.from),
+    );
+    const recentBugs = snap.classifications
+      .filter((c) => scenariosInArea.has(c.scenarioId))
+      .filter((c) => RISK_WEIGHTS.bugClassifications.has(c.classification))
+      .filter((c) => daysBetween(now, new Date(c.ts)) <= config.staleAfterDays).length;
+    const criticalBoost: 1 | 2 = config.criticalAreas.includes(areaId) ? 2 : 1;
+
+    return {
+      id: areaId,
+      status,
+      risk,
+      breakdown: { recentTickets, recentBugs, criticalBoost },
+    };
+  });
+
+  areas.sort((a, b) => {
+    if (STATUS_RANK[a.status] !== STATUS_RANK[b.status]) {
+      return STATUS_RANK[a.status] - STATUS_RANK[b.status];
+    }
+    if (a.status === 'COVERED') return a.id.localeCompare(b.id);
+    if (b.risk !== a.risk) return b.risk - a.risk;
+    return a.id.localeCompare(b.id);
+  });
+
+  const tickets: TicketReportRow[] = Object.values(snap.tickets)
+    .filter((t) => computeTicketStatus(t.id, snap, config.staleAfterDays, now) === 'INCOMPLETE')
+    .map((t) => {
+      const acs = Object.values(snap.acNodes)
+        .filter((ac) => ac.ticketId === t.id)
+        .sort((a, b) => a.index - b.index);
+      const unsatisfiedAcs = acs
+        .filter((ac) => computeAcStatus(ac.id, snap, config.staleAfterDays, now) === 'UNSATISFIED')
+        .map((ac) => ({ index: ac.index, text: ac.text }));
+      return {
+        id: t.id,
+        summary: t.summary,
+        acCount: acs.length,
+        satisfiedCount: acs.length - unsatisfiedAcs.length,
+        gapScore: computeAcGapScore(t.id, snap, config, now),
+        unsatisfiedAcs,
+      };
+    })
+    .sort((a, b) => b.gapScore - a.gapScore || a.id.localeCompare(b.id));
+
+  return {
+    generatedAt: now.toISOString(),
+    windowDays: config.staleAfterDays,
+    areas,
+    tickets,
+    acBackfillNeeded: needsBackfill(snap),
+  };
+}
+
+function needsBackfill(snap: Snapshot): boolean {
+  for (const ticket of Object.values(snap.tickets)) {
+    const acsForTicket = Object.values(snap.acNodes).filter((ac) => ac.ticketId === ticket.id);
+    if (acsForTicket.length === 0) continue;
+    const scenariosForTicket = Object.values(snap.scenarios).filter(
+      (s) => s.ticketId === ticket.id,
+    );
+    if (scenariosForTicket.length === 0) continue;
+    const hasAnyEdge = snap.edges.some(
+      (e) => e.kind === 'satisfies' && acsForTicket.some((ac) => ac.id === e.to),
+    );
+    if (!hasAnyEdge) return true;
+  }
+  return false;
+}
+
+export interface RenderOptions {
+  includeCovered?: boolean;
+}
+
+function pad(s: string, n: number): string {
+  return s.length >= n ? s : `${s}${' '.repeat(n - s.length)}`;
+}
+
+export function renderMarkdown(report: CoverageReport, options: RenderOptions = {}): string {
+  const lines: string[] = [];
+  const dateOnly = report.generatedAt.slice(0, 10);
+  lines.push('', `Coverage report — generated ${dateOnly} · window ${report.windowDays}d`, '');
+
+  const uncovered = report.areas.filter((a) => a.status === 'UNCOVERED');
+  if (uncovered.length > 0) {
+    lines.push(
+      `UNCOVERED — ${uncovered.length} area${uncovered.length === 1 ? '' : 's'}, sorted by risk`,
+    );
+    lines.push('');
+    uncovered.forEach((a, i) => {
+      const parts: string[] = [`${a.breakdown.recentTickets} tickets`];
+      if (a.breakdown.recentBugs > 0) parts.push(`${a.breakdown.recentBugs} bugs`);
+      if (a.breakdown.criticalBoost === 2) parts.push('critical ×2');
+      lines.push(`  #${i + 1}  ${pad(a.id, 10)} risk ${a.risk}    ${parts.join(' · ')}`);
+    });
+    lines.push('');
+  }
+
+  const stale = report.areas.filter((a) => a.status === 'STALE');
+  if (stale.length > 0) {
+    lines.push(
+      `STALE — ${stale.length} area${stale.length === 1 ? '' : 's'}, has tests but no PASS in ${report.windowDays}d`,
+    );
+    lines.push('');
+    stale.forEach((a, i) => {
+      lines.push(`  #${i + 1}  ${pad(a.id, 10)} (see --why ${a.id} for details)`);
+    });
+    lines.push('');
+  }
+
+  if (report.tickets.length > 0) {
+    lines.push(
+      `AC GAPS — ${report.tickets.length} ticket${report.tickets.length === 1 ? '' : 's'} with unsatisfied acceptance criteria`,
+    );
+    lines.push('');
+    for (const t of report.tickets) {
+      lines.push(
+        `  ${t.id}  ${t.satisfiedCount}/${t.acCount} ACs covered · gap_score ${t.gapScore}`,
+      );
+      for (const ac of t.unsatisfiedAcs) {
+        lines.push(`    ✗ AC-${ac.index}  ${ac.text}`);
+      }
+      lines.push('');
+    }
+  }
+
+  const covered = report.areas.filter((a) => a.status === 'COVERED');
+  if (covered.length > 0) {
+    if (options.includeCovered) {
+      lines.push(`COVERED — ${covered.length} area${covered.length === 1 ? '' : 's'}`);
+      lines.push('');
+      covered.forEach((a, i) => {
+        lines.push(`  #${i + 1}  ${pad(a.id, 10)} ok`);
+      });
+      lines.push('');
+    } else {
+      lines.push(
+        `COVERED — ${covered.length} area${covered.length === 1 ? '' : 's'} (collapsed; show with --all)`,
+      );
+      lines.push('');
+    }
+  }
+
+  return lines.join('\n');
+}