#!/usr/bin/env bun // Enforce, as a gate step, that `wiki/Realtime.md` and the wire protocol still name the same // frames. `FRAME_KINDS` in `packages/realtime/src/sync-protocol.ts` is the wire; the page is the // only public description of it, and nothing cross-referenced the two — so renaming a frame left // the published protocol documentation describing a frame that no longer exists. Runs on // `x verify`'s `manifest` step, beside the other "a committed file still describes the code" rules. // // TWO DIRECTIONS, DELIBERATELY UNEQUAL, because frame names are ordinary English words and error // codes are not: // source -> page a FLOOR. The kind must appear as a word somewhere on the page. It catches the // case that matters — a frame added or renamed and never documented, whose new // name appears nowhere — and it cannot catch a new frame called `update`. // page -> source PRECISE. A backticked token immediately followed by "frame" is the page // naming a frame, and it must be one that exists. // // bun run scripts/wiki-frames.ts [--json] import { FRAME_KINDS } from '@ultimat3/realtime'; import { renderFixShellArg } from '../packages/core/src/error-render'; import { parseScriptArgs } from './lib/args'; import type { Finding } from './lib/log'; import { report } from './lib/log'; import { repoRoot } from './lib/run'; export const FRAMES_PAGE = 'wiki/Realtime.md'; export const PROTOCOL_FILE = 'packages/realtime/src/sync-protocol.ts'; /** * `undocumented`: the wire has a frame the page never names. `unknown`: the page has one the wire * does not. `absent`: there is no page at all — see `FrameDocInput.page`. */ export type FrameDocGapKind = 'undocumented' | 'unknown' | 'absent'; export interface FrameDocGap { readonly kind: FrameDocGapKind; readonly frame: string; } export interface FrameDocInput { /** `FRAME_KINDS`, whole — the wire's own list, never a copy of it. */ readonly kinds: readonly string[]; /** * `wiki/Realtime.md`, verbatim — or `undefined` when the page does not exist, which is NOT the * same as an empty one and is not "nothing to check". Deleting or renaming the page satisfied * every rule below by having nothing to compare, so the one input this file is about could be * removed and the `manifest` step would report pass over a wire protocol with no public * description at all. That is the false green this file exists to close, reproduced inside it. */ readonly page: string | undefined; } /** `` `subscribe` frame ``, `` `reconnect` frames `` — the page naming a frame, unambiguously. */ const NAMED_FRAME = /`([a-z][a-z0-9-]*)` frames?\b/g; /** Pure, so the negative case is a fixture rather than an edit to a published page. */ export function checkFrameDocs(input: FrameDocInput): readonly FrameDocGap[] { // One finding, not ten: "the page is gone" is one fact and one edit, and listing every frame as // undocumented would bury it. `kinds` empty means there is no wire here either — a tree that // ships no protocol owes no page. if (input.page === undefined) { return input.kinds.length === 0 ? [] : [{ kind: 'absent', frame: '' }]; } // Collapsed, because a `` `subscribe` frame `` that wraps across two lines is still one phrase. const page = input.page.replace(/\s+/g, ' '); const gaps: FrameDocGap[] = []; for (const kind of input.kinds) { // Every `FrameKind` is a lowercase identifier, so the name carries no regex metacharacter. if (new RegExp(`\\b${kind}\\b`, 'i').test(page)) continue; gaps.push({ kind: 'undocumented', frame: kind }); } const known = new Set(input.kinds); for (const match of page.matchAll(NAMED_FRAME)) { const frame = match[1] ?? ''; if (known.has(frame)) continue; gaps.push({ kind: 'unknown', frame }); } return gaps; } const undocumentedFinding = (gap: FrameDocGap): Finding => ({ code: 'X_FRAME_DOCS_STALE', cause: `${PROTOCOL_FILE} sends a "${gap.frame}" frame and ${FRAMES_PAGE} never names it, so the only public description of the wire protocol is missing a frame clients receive`, fix: `grep -n 'Inbound frame order' ${FRAMES_PAGE} # document the ${gap.frame} frame there — one row of that table, or a sentence naming \`${gap.frame}\``, at: FRAMES_PAGE, }); const unknownFinding = (gap: FrameDocGap): Finding => ({ code: 'X_FRAME_DOCS_STALE', cause: `${FRAMES_PAGE} names a \`${gap.frame}\` frame and FRAME_KINDS has no such kind, so the published protocol documents a frame no node sends`, fix: `grep -n ${renderFixShellArg(gap.frame, '')} ${FRAMES_PAGE} # rename \`${gap.frame}\` there to the kind that replaced it (FRAME_KINDS in ${PROTOCOL_FILE} is the list), or delete the sentence`, at: FRAMES_PAGE, }); const absentFinding = (): Finding => ({ code: 'X_FRAME_DOCS_STALE', cause: `${PROTOCOL_FILE} ships ${FRAME_KINDS.length} wire frames and ${FRAMES_PAGE} does not exist, so the protocol has no public description at all — and every rule that compares the two passes by having nothing to compare`, fix: `git checkout -- ${renderFixShellArg(FRAMES_PAGE, '')} # restores the deleted page — or, if it moved, update FRAMES_PAGE in scripts/wiki-frames.ts to where it went`, at: FRAMES_PAGE, }); const FINDINGS: Readonly Finding>> = Object.assign( Object.create(null), { undocumented: undocumentedFinding, unknown: unknownFinding, absent: absentFinding, } satisfies Record Finding>, ); export const frameDocGapFindingFor = (gap: FrameDocGap): Finding => FINDINGS[gap.kind](gap); /** * Read the page and the protocol, then check them. The one impure step. * * ABSENCE IS A FINDING HERE, gated on the protocol actually being in this tree. The condition is * derived, never "is this the framework repo": a tree that ships * `packages/realtime/src/sync-protocol.ts` owes the page that describes it, and a synthetic root in * `scripts/verify.test.ts` ships neither, so it is silent for a reason rather than by exemption. */ export async function frameDocGaps(root: string): Promise { if (!(await Bun.file(`${root}/${PROTOCOL_FILE}`).exists())) return []; const page = Bun.file(`${root}/${FRAMES_PAGE}`); return checkFrameDocs({ kinds: FRAME_KINDS, page: (await page.exists()) ? await page.text() : undefined, }); } /** What this repo contributes to `x verify`'s `manifest` step. */ export const frameDocFindings = async (root: string): Promise => (await frameDocGaps(root)).map(frameDocGapFindingFor); if (import.meta.main) { const args = parseScriptArgs(Bun.argv.slice(2)); const gaps = await frameDocGaps(repoRoot()); report( { ok: gaps.length === 0, script: 'wiki-frames', summary: gaps.length === 0 ? `${FRAME_KINDS.length} frame kinds, every one named by ${FRAMES_PAGE} and no others` : `${gaps.length} frame(s) where ${FRAMES_PAGE} and the wire protocol disagree`, findings: gaps.map(frameDocGapFindingFor), }, args.json, ); }