// Turns `docs/idea/14-roadmap.md` from prose into a gate step. Three rules, all decidable without // running the demo app: (1) the roadmap file exists at all — deleting it must not silently pass // every other rule; (2) every milestone row carries a status marker — the table this file guards // shipped with zero, and a silent regression back to that state is exactly the bug a reader would // not notice; (3) a milestone the table marks shipped still has every artifact its own "Ships" // column names on disk — a status marker nobody checks is a claim, not a gate; (4) no plan // tracker reads `in_progress` with no commit in its directory for 30 days (`lib/roadmap-stale-plans.ts`). // // bun run scripts/roadmap.ts [--json] // why: `existsSync` and `join` have no Bun equivalent for this job: `Bun.file().exists()` is async and // answers `false` for a directory, and one required artifact (`packages/cli/src/templates`) is a // directory. import { existsSync } from 'node:fs'; import { join } from 'node:path'; import type { Finding, HostCheck } from '@ultimat3/cli'; import { renderFixShellArg } from '../packages/core/src/error-render'; import { parseScriptArgs } from './lib/args'; import { report } from './lib/log'; import { gitTrackerEdits, undatedFindings } from './lib/plan-tracker-dated'; import { gitLastTouch, type StaleDeps, stalePlanFindings } from './lib/roadmap-stale-plans'; import { repoRoot } from './lib/run'; export const ROADMAP_FILE = 'docs/idea/14-roadmap.md'; export type MilestoneStatus = 'shipped' | 'in-progress'; export const STATUS_MARK: Readonly> = { shipped: '✅', 'in-progress': '🚧', }; const STATUS_BY_MARK: ReadonlyMap = new Map( Object.entries(STATUS_MARK).map(([status, mark]) => [mark, status as MilestoneStatus]), ); /** * Repo-relative paths each milestone's own "Ships" column claims exist, checked only once the * table marks that milestone shipped — an in-progress milestone's artifacts are still landing, so * their absence is not yet a regression. * * Status and title are **not** mirrored here: they are read back out of the table itself, so the * roadmap is the one place either is stated (axiom 2). Only these paths live in code, because the * "Ships" column is prose naming packages, not a machine-readable path list. */ export const REQUIRED_ARTIFACTS: Readonly> = Object.assign( Object.create(null), { 0: [ 'packages/core/src/index.ts', 'packages/schema/src/index.ts', 'scripts/boundaries.ts', 'packages/cli/src/cmd-verify.ts', ], 1: [ 'packages/http/src/index.ts', 'packages/entity/src/index.ts', 'packages/policy/src/index.ts', ], 2: [ 'packages/action/src/index.ts', 'packages/query/src/index.ts', 'packages/cli/src/app-openapi.ts', ], 3: ['packages/render/src/index.ts', 'packages/cli/src/app-boundaries.ts'], 4: ['packages/seo/src/index.ts', 'packages/cli/src/budgets.ts'], 5: [ 'packages/jobs/src/index.ts', 'packages/mail/src/index.ts', 'packages/storage/src/index.ts', ], 6: ['packages/realtime/src/index.ts'], 7: ['packages/cache/src/index.ts'], 8: [ 'packages/pwa/src/index.ts', 'packages/cli/src/retained-assets.ts', 'packages/cli/e2e/six-deploys.e2e.test.ts', ], 9: ['packages/ai/src/index.ts', 'packages/mcp/src/index.ts'], 10: [ 'packages/admin/src/index.ts', 'packages/create-ultimate/src/index.ts', 'packages/cli/src/templates', ], 11: [ 'docker/Dockerfile', 'docker/docker-compose.dev.yml', 'docker/docker-compose.prod.yml', 'docker/helm', 'packages/cli/src/cmd-build.ts', 'wiki/Error-Codes.md', 'CHANGELOG.md', ], } satisfies Record, ); export const MILESTONE_NUMBERS: readonly number[] = Object.keys(REQUIRED_ARTIFACTS) .map(Number) .sort((a, b) => a - b); /** The milestone table's own header, so the row scan is bounded by the table it belongs to and a * numeric first cell in the benchmark table further down is never read as a milestone. */ const MILESTONE_TABLE_HEADER = /^\|\s*#\s*\|/; /** * Every `| n |` row the table actually holds. `MILESTONE_NUMBERS` is derived from the hardcoded * artifact map, so rule (2) only ever asked about 0-11 — appending `| 12 | | **Multi-region** |` * with no status marker was a row `checkRoadmap` never looked at, and the step reported green over * exactly the regression its own header says it catches. */ export function milestoneNumbersIn(markdown: string): readonly number[] { const lines = markdown.split('\n'); const start = lines.findIndex((line) => MILESTONE_TABLE_HEADER.test(line.trim())); if (start === -1) return []; const found: number[] = []; for (const line of lines.slice(start + 1)) { const row = line.trim(); if (!row.startsWith('|')) break; const match = /^\|\s*(\d+)\s*\|/.exec(row); if (match?.[1] !== undefined) found.push(Number.parseInt(match[1], 10)); } return [...new Set(found)].sort((a, b) => a - b); } export interface MilestoneRow { readonly n: number; readonly status: MilestoneStatus; readonly title: string; } /** * Read milestone `n` back out of its own `| n | marker | **Title** | ships | done when |` row. * `undefined` means the row is absent, or present with no marker this table defines — the two * cases rule (2) exists to catch, and the caller reports them identically. */ export function milestoneRow(markdown: string, n: number): MilestoneRow | undefined { const line = markdown .split('\n') .find((candidate) => new RegExp(`^\\|\\s*${n}\\s*\\|`).test(candidate)); if (line === undefined) return undefined; const cells = line.split('|').map((cell) => cell.trim()); const marker = [...STATUS_BY_MARK.keys()].find((mark) => cells[2]?.includes(mark) === true); const status = marker === undefined ? undefined : STATUS_BY_MARK.get(marker); if (status === undefined) return undefined; return { n, status, title: (cells[3] ?? '').replaceAll('*', '').trim() }; } // No `docs:` line, deliberately. This file used to build `https://ultimate.dev/errors/`, // a host that answered 404 on every error the framework ever threw; `UltimateError`'s constructor // now resolves the registered descriptor from `ERROR_DOCS_URL` in `@ultimat3/core`, and a `Finding` // that omits the field inherits that instead of hard-coding a second, wrong answer. const missingFileFinding = (): Finding => ({ code: 'X_ROADMAP_FILE_MISSING', cause: `${ROADMAP_FILE} does not exist, so no milestone status or shipped artifact can be checked`, fix: `git checkout -- ${renderFixShellArg(ROADMAP_FILE, '')}`, at: ROADMAP_FILE, }); const missingStatusFinding = (n: number): Finding => ({ code: 'X_ROADMAP_STATUS_MISSING', cause: `milestone ${n} has no row in the milestone table, or its row's status cell holds neither ${STATUS_MARK.shipped} nor ${STATUS_MARK['in-progress']}`, fix: `grep -n '^| ${renderFixShellArg(String(n), '')} |' ${ROADMAP_FILE} # put "${STATUS_MARK.shipped}" or "${STATUS_MARK['in-progress']}" in that row's second cell, then: bun run scripts/roadmap.ts --json`, at: ROADMAP_FILE, }); const unverifiedFinding = (row: MilestoneRow, missing: readonly string[]): Finding => ({ code: 'X_ROADMAP_MILESTONE_UNVERIFIED', cause: `milestone ${row.n} ("${row.title}") is marked ${STATUS_MARK.shipped} but ${missing.join(', ')} ${missing.length === 1 ? 'does' : 'do'} not exist`, fix: `git checkout -- ${missing.join(' ')} — or edit ${ROADMAP_FILE} and put "${STATUS_MARK['in-progress']}" in the status cell of the row starting "| ${row.n} |"`, at: ROADMAP_FILE, }); const untrackedFinding = (row: MilestoneRow): Finding => ({ code: 'X_ROADMAP_MILESTONE_UNTRACKED', cause: `milestone ${row.n} ("${row.title}") has a row in ${ROADMAP_FILE} but scripts/roadmap.ts declares no artifacts for it, so its status marker verifies nothing`, fix: `grep -n 'REQUIRED_ARTIFACTS' scripts/roadmap.ts # add a "${row.n}: [...]" entry there naming the paths that row's "Ships" column promises — an empty list is the deliberate answer for a milestone that ships nothing yet — then: bun run scripts/roadmap.ts --json`, at: ROADMAP_FILE, }); /** Each milestone's "Done when" as a build error rather than a sentence nobody re-reads. */ const tableFindings = async (root: string): Promise => { const path = join(root, ROADMAP_FILE); if (!existsSync(path)) return [missingFileFinding()]; const markdown = await Bun.file(path).text(); const findings: Finding[] = []; // The union, not the artifact map's keys: a milestone this script has never heard of is exactly // the row rules (2) and (3) are blind to, and a milestone the table dropped is still required. const numbers = [...new Set([...MILESTONE_NUMBERS, ...milestoneNumbersIn(markdown)])].sort( (a, b) => a - b, ); for (const n of numbers) { const row = milestoneRow(markdown, n); if (row === undefined) { findings.push(missingStatusFinding(n)); continue; } if (REQUIRED_ARTIFACTS[n] === undefined) { findings.push(untrackedFinding(row)); continue; } if (row.status !== 'shipped') continue; const missing = (REQUIRED_ARTIFACTS[n] ?? []).filter((rel) => !existsSync(join(root, rel))); if (missing.length > 0) findings.push(unverifiedFinding(row, missing)); } return findings; }; /** The step over its two readers, injectable so a test pins the clock and the history. */ export const roadmapCheck = (deps: StaleDeps): HostCheck => async (root) => [ ...(await tableFindings(root)), ...(await stalePlanFindings(root, deps)), ...undatedFindings( (await deps.trackerEdits?.(root)) ?? [], new Date(deps.now()).toISOString().slice(0, 10), ), ]; /** What the gate runs: git for the dates, and the one wall clock read in this step. */ export const ROADMAP_DEPS: StaleDeps = { now: () => Date.now(), lastTouch: gitLastTouch, trackerEdits: gitTrackerEdits, }; export const checkRoadmap: HostCheck = roadmapCheck(ROADMAP_DEPS); if (import.meta.main) { const args = parseScriptArgs(Bun.argv.slice(2)); const findings = await checkRoadmap(repoRoot()); report( { ok: findings.length === 0, script: 'roadmap', summary: findings.length === 0 ? `${MILESTONE_NUMBERS.length} milestones, every status marked and every shipped artifact present` : `${findings.length} roadmap finding(s) across ${MILESTONE_NUMBERS.length} milestones`, findings, data: { file: ROADMAP_FILE, milestones: MILESTONE_NUMBERS }, }, args.json, ); }