diff --git a/FORK_CHANGES.md b/FORK_CHANGES.md new file mode 100644 index 0000000000000..83ae5032ac685 --- /dev/null +++ b/FORK_CHANGES.md @@ -0,0 +1,58 @@ +# Fork changes + +This repository is a fork of [T3 Code](https://github.com/pingdotgg/t3code). This page lists every +change the fork makes, one line each: what it does, why, its setting and default, and the pull +requests. The fork's settings are explained in [docs/fork/README.md](docs/fork/README.md), which also +says how to install the fork today. + +The rule for every change: a machine that never names a fork setting behaves as upstream's T3 Code. +A setting is written as `server.` (the server's `settings.json`) or `projectOverride.` +(one project's overrides). A test (`packages/shared/src/forkDocs.test.ts`) fails when a fork setting +is missing here or a setting named here does not exist. + +## In T3 Code itself + +| Change | Why | Setting | Default | PR | +| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------- | -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| The server, the CLI and the desktop app look for updates in this fork's releases, not upstream's. | A fork build must never "update" to an upstream build and lose the fork's changes. | none | always | [#1](https://github.com/scuttletoby/t3code/pull/1) | +| A server installed as a boot service can update itself once no thread is working, after an optional "is it quiet?" command agrees. | Updates without someone watching, and without cutting off running work. | `server.automaticUpdates`, `server.automaticUpdatesQuietCommand` | off | [#5](https://github.com/scuttletoby/t3code/pull/5) | +| Every fork setting has a pinned default, and lives in the fork's own file (`forkSettings.ts`). | An upstream sync can never switch a fork feature on, and a new setting touches no upstream file. | none | always | [#171](https://github.com/scuttletoby/t3code/pull/171), [#185](https://github.com/scuttletoby/t3code/pull/185) | +| The server keeps a history of each provider account's usage-limit readings. | Pacing needs to know how fast a limit is being used, not only where it stands. | none | always (read only) | [#24](https://github.com/scuttletoby/t3code/pull/24) | +| The server reads usage limits every 10 minutes while no app is open. | Pacing has current numbers on a machine nobody is looking at. | `server.headlessUsageRefreshInterval` | on (10 minutes); read only | [#42](https://github.com/scuttletoby/t3code/pull/42) | +| Usage pacing: a reserve of each limit window kept free for the person, and an even pace for agents. | Agents should not use up a subscription before its owner needs it. | `server.usagePacing` | off | [#52](https://github.com/scuttletoby/t3code/pull/52) | +| The pacing gate on `delegate_task`: advise only, or move, lower the effort of, or hold a task on an account that is ahead of pace. | Delegated work follows the pace without the agent having to check. | `server.usagePacingGate`, `server.usagePacingLowerEffort` | off | [#73](https://github.com/scuttletoby/t3code/pull/73) | +| Agent slots: `delegate_task` is refused above a number of running agents per machine or account, or below a memory floor. | Too many agents at once can overload a small machine. | `server.agentSlots` | off | [#84](https://github.com/scuttletoby/t3code/pull/84), [#89](https://github.com/scuttletoby/t3code/pull/89) | +| Waits: agents can wait for a pull request, a file, a system unit, a named check command or a free agent slot (`wait_for`, `wait_list`, `wait_cancel`), and are woken when it happens. | An agent no longer polls or sleeps while it waits. | `server.waitFor`, `server.waitChecks`, `projectOverride.waitChecks` | off | [#84](https://github.com/scuttletoby/t3code/pull/84), [#90](https://github.com/scuttletoby/t3code/pull/90), [#91](https://github.com/scuttletoby/t3code/pull/91), [#103](https://github.com/scuttletoby/t3code/pull/103), [#106](https://github.com/scuttletoby/t3code/pull/106), [#109](https://github.com/scuttletoby/t3code/pull/109), [#110](https://github.com/scuttletoby/t3code/pull/110), [#116](https://github.com/scuttletoby/t3code/pull/116), [#119](https://github.com/scuttletoby/t3code/pull/119) | +| Settings pages for waits, wait checks and agent slots. | Switch these on without editing a file. | `server.waitFor`, `server.waitChecks`, `server.agentSlots` | off | [#104](https://github.com/scuttletoby/t3code/pull/104) | +| The fork's checks on `delegate_task` (pacing, slots) sit behind one fork module. | Fewer fork lines in upstream's code, so syncs conflict less. No change in behaviour. | none | always | [#174](https://github.com/scuttletoby/t3code/pull/174) | +| A pure capacity rule for "dynamic slots" (one budget per machine), with shared test cases. Not wired into anything yet. | A later step replaces fixed agent counts with what the machine can take. | none | not used | [#203](https://github.com/scuttletoby/t3code/pull/203) | +| File links in chat open in the files viewer, full size, or in an editor on a remote machine, and can be downloaded, from their menu. | File links were only copyable on remote machines and had no menu on touch screens. | none | always | [#17](https://github.com/scuttletoby/t3code/pull/17) | +| A hidden read-only command, `t3 __fork-report --base-dir `, prints what a T3 home holds and which fork features are on. | The go-live kit checks a build and a home before switching, without writing anything. | none | only when run | [#172](https://github.com/scuttletoby/t3code/pull/172), [#184](https://github.com/scuttletoby/t3code/pull/184) | +| `t3 serve --hold-work` starts a server on a copy of a T3 home with all agent work held. | Look at a new build's threads and migrations on a copy before it replaces a running T3. | none | only with the flag | [#175](https://github.com/scuttletoby/t3code/pull/175) | +| Docs: one machine for new work through upstream's load-balancing weights; settings saved with an early draft's client setting for it still load. | Upstream already has the feature, so the fork's own setting was removed. | none | - | [#25](https://github.com/scuttletoby/t3code/pull/25) | + +## Repository, CI and releases + +These change only how this repository is built, tested and released, not the app. + +| Change | Why | Setting | Default | PR | +| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- | ----------------------------------------- | ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Fork release workflow: builds `v.fork.` with the Linux and Windows CLI archives and unsigned desktop apps. | The fork needs its own releases to install and update from. | none | run by hand or by fork-follow | [#2](https://github.com/scuttletoby/t3code/pull/2) | +| fork-follow: once a day, rebase the fork onto upstream's newest tag, test, and release only when green; on trouble, open one issue. | Stay close to upstream without manual work. | repository variable `FORK_FOLLOW_CHANNEL` | `nightly` | [#4](https://github.com/scuttletoby/t3code/pull/4), [#22](https://github.com/scuttletoby/t3code/pull/22), [#66](https://github.com/scuttletoby/t3code/pull/66) | +| Fork tests: upstream's test jobs, run on GitHub-hosted runners or on the repository's own machines chosen per run. | Fast CI that does not need upstream's runner labels. | repository variable `CI_RUNNERS` | `auto` | [#6](https://github.com/scuttletoby/t3code/pull/6), [#8](https://github.com/scuttletoby/t3code/pull/8), [#13](https://github.com/scuttletoby/t3code/pull/13) | +| Fleet runners: one-job runners started on demand on the repository's own machines, each behind walls, plus a link from a desktop machine. | Use spare machines for CI without letting a job reach the host. | repository variable `CI_RUNNERS` | `auto` | [#53](https://github.com/scuttletoby/t3code/pull/53), [#74](https://github.com/scuttletoby/t3code/pull/74), [#191](https://github.com/scuttletoby/t3code/pull/191), [#192](https://github.com/scuttletoby/t3code/pull/192), [#194](https://github.com/scuttletoby/t3code/pull/194), [#195](https://github.com/scuttletoby/t3code/pull/195), [#196](https://github.com/scuttletoby/t3code/pull/196), [#197](https://github.com/scuttletoby/t3code/pull/197), [#198](https://github.com/scuttletoby/t3code/pull/198), [#205](https://github.com/scuttletoby/t3code/pull/205), [#208](https://github.com/scuttletoby/t3code/pull/208) | +| Checks that refuse database schema and migration changes, fork changes to some upstream files, and fork lines outside the pinned seams. | Keep the fork thin, so upstream syncs stay easy and a database never needs a fork step. | none | always | [#3](https://github.com/scuttletoby/t3code/pull/3), [#97](https://github.com/scuttletoby/t3code/pull/97), [#185](https://github.com/scuttletoby/t3code/pull/185) | +| Pull requests from outside run nothing; four outside-started upstream workflows and `issue-vouch.yml` are deleted and kept deleted. | No code from an outside pull request runs with this repository's runners or tokens. | none | always | [#12](https://github.com/scuttletoby/t3code/pull/12), [#14](https://github.com/scuttletoby/t3code/pull/14), [#23](https://github.com/scuttletoby/t3code/pull/23) | +| A weekly check that the repository's interaction limit never lapses. | Outsiders cannot post while the limit holds. | none | always | [#30](https://github.com/scuttletoby/t3code/pull/30) | +| Secret scan on every push and pull request. | The fork is public: no token or key may land in it. | none | always | [#75](https://github.com/scuttletoby/t3code/pull/75), [#206](https://github.com/scuttletoby/t3code/pull/206), [#207](https://github.com/scuttletoby/t3code/pull/207), [#212](https://github.com/scuttletoby/t3code/pull/212) | +| fork-ci: CI actions any repository can pin (docs-scope, gradle-cache, job-changed, fleet-route, ci-demand, pinned), with their own releases. | Shared CI building blocks, kept general. | none | only where pinned | [#15](https://github.com/scuttletoby/t3code/pull/15), [#16](https://github.com/scuttletoby/t3code/pull/16), [#27](https://github.com/scuttletoby/t3code/pull/27), [#35](https://github.com/scuttletoby/t3code/pull/35), [#55](https://github.com/scuttletoby/t3code/pull/55), [#94](https://github.com/scuttletoby/t3code/pull/94), [#113](https://github.com/scuttletoby/t3code/pull/113), [#141](https://github.com/scuttletoby/t3code/pull/141) | +| fork-ci PR queue: merges armed pull requests in order once their reviews and checks pass. | Merges without someone watching each pull request. | none | only where used | [#18](https://github.com/scuttletoby/t3code/pull/18), [#19](https://github.com/scuttletoby/t3code/pull/19), [#20](https://github.com/scuttletoby/t3code/pull/20), [#21](https://github.com/scuttletoby/t3code/pull/21), [#32](https://github.com/scuttletoby/t3code/pull/32), [#61](https://github.com/scuttletoby/t3code/pull/61), [#70](https://github.com/scuttletoby/t3code/pull/70), [#71](https://github.com/scuttletoby/t3code/pull/71) | +| fork-ci head check and head gate: the queue's required check, posted by a GitHub App and judged by the default branch's code. | A pull request cannot fake its own required check. See [gate trust](docs/fork/gate-trust.md). | none | only where used | [#33](https://github.com/scuttletoby/t3code/pull/33), [#85](https://github.com/scuttletoby/t3code/pull/85), [#87](https://github.com/scuttletoby/t3code/pull/87) | +| Host kits (`fork-kit/`): `gh-apps` (GitHub App tokens for agents), `heavy` (run builds in a capped slice), `golive` (move a boot service to a new build; core and `check` so far). | Things the fork installs on a machine, each with an installer, a self-check and tests. | none | only when installed | [#86](https://github.com/scuttletoby/t3code/pull/86), [#173](https://github.com/scuttletoby/t3code/pull/173), [#182](https://github.com/scuttletoby/t3code/pull/182), [#183](https://github.com/scuttletoby/t3code/pull/183) | +| Design notes: host tools (agents on a person's own computer). | Design for review; no code yet. | none | - | [#26](https://github.com/scuttletoby/t3code/pull/26) | + +## Adding a line + +A pull request that adds or changes a fork feature adds or changes its line here. A new fork setting +also needs its row in `packages/contracts/src/forkDefaults.ts` and its row and section in +[docs/fork/README.md](docs/fork/README.md) (steps in [updates.md](docs/fork/updates.md#adding-a-fork-setting)). diff --git a/docs/fork/README.md b/docs/fork/README.md new file mode 100644 index 0000000000000..f54dc66bc8859 --- /dev/null +++ b/docs/fork/README.md @@ -0,0 +1,203 @@ +# The fork: settings and install + +Fork only. This fork is T3 Code with a thin set of changes on top; every change is listed in +[FORK_CHANGES.md](../../FORK_CHANGES.md). This page lists every fork setting: what it does, its +default, and how to switch it on. Then it says how to install the fork today. + +The rule: a machine whose settings never name a fork setting behaves as upstream's T3 Code. Every +fork switch is off by default, except one read-only refresh of usage limits. + +## Where settings live + +Server settings are in `settings.json` in the server's `userdata` folder (by default +`~/.t3/userdata/settings.json`). The server reads the file again when it changes; no restart is +needed. Some fork settings also have a row in the app's **Settings** pages (named below). A +project's overrides are set in **Settings** with that project chosen at the top ("Applying settings +for …", see [project settings](../user/project-settings.md)). An agent's tools cannot change any +fork setting. + +To check what a T3 home has switched on without changing anything, the fork's hidden command +`t3 __fork-report --base-dir ` prints it as JSON. + +## Settings + +The defaults, "off" and "decided in" below come from one table in the code, +[`packages/contracts/src/forkDefaults.ts`](../../packages/contracts/src/forkDefaults.ts). A test +(`packages/shared/src/forkDocs.test.ts`) fails when this table and that one differ, or a setting has +no section below. "Off" means the default leaves the machine as upstream's would be. + +| Setting | Default | Off | Decided in | +| ---------------------------------------------------------------------------- | ------------------- | --- | ------------------------------------------------------ | +| [`server.automaticUpdates`](#serverautomaticupdates) | `false` | yes | [#41](https://github.com/scuttletoby/t3code/issues/41) | +| [`server.automaticUpdatesQuietCommand`](#serverautomaticupdatesquietcommand) | `""` | yes | [#5](https://github.com/scuttletoby/t3code/issues/5) | +| [`server.usagePacing`](#serverusagepacing) | `{}` | yes | [#52](https://github.com/scuttletoby/t3code/issues/52) | +| [`server.usagePacingGate`](#serverusagepacinggate) | `"off"` | yes | [#73](https://github.com/scuttletoby/t3code/issues/73) | +| [`server.usagePacingLowerEffort`](#serverusagepacinglowereffort) | `{}` | yes | [#73](https://github.com/scuttletoby/t3code/issues/73) | +| [`server.waitFor`](#serverwaitfor) | `{"enabled":false}` | yes | [#84](https://github.com/scuttletoby/t3code/issues/84) | +| [`server.waitChecks`](#serverwaitchecks) | `{}` | yes | [#84](https://github.com/scuttletoby/t3code/issues/84) | +| [`server.agentSlots`](#serveragentslots) | `{"enabled":false}` | yes | [#84](https://github.com/scuttletoby/t3code/issues/84) | +| [`server.headlessUsageRefreshInterval`](#serverheadlessusagerefreshinterval) | `600000` | no | [#42](https://github.com/scuttletoby/t3code/issues/42) | +| [`projectOverride.waitChecks`](#projectoverridewaitchecks) | not set | yes | [#84](https://github.com/scuttletoby/t3code/issues/84) | + +For `waitFor` and `agentSlots` only the `enabled` switch is pinned; their other fields are tuning +that does nothing while the switch is off. + +## Each setting + +### `server.automaticUpdates` + +A server installed as a boot service (`t3 service install`) updates itself to the newest fork release +once no thread is working. Off: it updates only when someone runs `t3 update` or presses **Update**. +Upstream has a setting of this name pending (not on its `main` yet); the fork keeps `false` through every sync. + +Switch on in `settings.json`: `"automaticUpdates": true`. There is no Settings row for it yet. An +admin policy with updates `"off"` still wins. Details: [updates.md](updates.md). + +### `server.automaticUpdatesQuietCommand` + +An optional program asked before each automatic update; a non-zero exit means "not now". Used only +while `automaticUpdates` is on. Empty: no program is asked. + +Set in `settings.json`: `"automaticUpdatesQuietCommand": "/path/to/quiet-check"`. Details: +[updates.md](updates.md). + +### `server.usagePacing` + +Per provider instance (account): `reservePercent` keeps that many points of each limit window free +for the person, released over the window's last 12 hours; `burnFirst` spends this account first; +`noLimits` says the account has no usage limits (an API key). An account without an entry has no +reserve. Only the pacing gate (`usagePacingGate`) acts on it. + +Set in `settings.json`: + +```json +{ "usagePacing": { "": { "reservePercent": 20 } } } +``` + +The key is the provider instance id, for example `codex` or `codex_work`. There is no Settings row for it yet. + +### `server.usagePacingGate` + +What happens when an agent starts a task with `delegate_task`. `"off"`: nothing, as upstream. +`"advise"`: the task starts as asked and the reply carries a note about the pace. `"enforce"`: a task +on an account that is ahead of its pace moves to another account of the same provider, runs at a +lower effort (`usagePacingLowerEffort`), or is refused for now and the agent asks again later. + +Switch on in `settings.json`: `"usagePacingGate": "advise"` (try `advise` before `enforce`). There +is no Settings row for it yet. + +### `server.usagePacingLowerEffort` + +For `"enforce"`: what each effort level turns into while an account is ahead of pace and no other +account has room, for example `{ "high": "medium", "medium": "medium" }`. A task at a level not +listed is held instead. Empty: no effort is ever lowered. + +Set in `settings.json`: `"usagePacingLowerEffort": { "high": "medium" }`. + +### `server.waitFor` + +Waits: an agent calls `wait_for` to wait for a pull request (checks done or merged), a file (there or +gone), a system unit, a named check command (`waitChecks`) or a free agent slot, and its thread is +woken with the result. `wait_list` and `wait_cancel` list and end them. While off, waits are neither +judged nor delivered; listing and cancelling still work. Other fields set deadlines, limits per +thread and how often each kind is checked. + +Switch on: **Settings → Threads**, section Waits (shown while a server is connected), "Let agents wait for events", or in `settings.json`: +`"waitFor": { "enabled": true }`. + +### `server.waitChecks` + +Named commands an agent can wait on by name (`wait_for` with a check). Each runs as a program with +fixed arguments, no shell; exit 0 means the event happened. It runs unsandboxed in the project folder +with the server's environment, so use fixed programs that run no files from the repository (no test +runners or build scripts). Only the person can add one; agents cannot. + +Add one: **Settings → Threads**, section Wait checks, **Add check**, or in `settings.json`: + +```json +{ "waitChecks": { "build-done": { "argv": ["test", "-f", "/tmp/build.done"] } } } +``` + +Used only while `waitFor` is on. + +### `server.agentSlots` + +Limits on running agents: `delegate_task` is refused above `maxPerMachine` agents on this server, +above `maxPerAccount` per provider account, or below `minFreeMemoryMb` of free memory. Threads +started in other ways are counted but never refused. With `waitFor` on, an agent can wait for a slot +instead of retrying. + +Switch on: **Settings → Threads**, section Agent slots, "Limit running agents", or in `settings.json`: +`"agentSlots": { "enabled": true, "maxPerMachine": 4 }`. With `enabled` and no limits set, nothing is +refused. + +### `server.headlessUsageRefreshInterval` + +How often the server reads usage limits while no app is open, in milliseconds. On by default every +10 minutes, so pacing has current numbers on a machine nobody is looking at. Read only: it changes no +thread, setting or install. Never more often than the provider status refresh. + +Switch off in `settings.json`: `"headlessUsageRefreshInterval": 0`. + +### `projectOverride.waitChecks` + +A project's own list of wait checks. It replaces the server's list for that project as a whole (a +project lists every check it uses). Not set: the project uses the server's checks. + +Set: **Settings**, choose the project at the top, then **Wait checks**. + +### A setting the fork removed + +An early draft had a client setting for one "anchor machine" for new work. It was removed before it +shipped: upstream's load balancing does the same. Settings saved with it still load. See +[anchor-machine.md](anchor-machine.md). + +## Install the fork today + +There is no one-line installer for the fork yet: `t3.codes/install.sh` and upstream's docs install +upstream's T3 Code. Two ways work today. + +**From a fork release (Linux x64).** The [fork's releases](https://github.com/scuttletoby/t3code/releases) +have the CLI archive for Linux x64 and Windows x64, and desktop apps for Linux, Windows and macOS. +The desktop apps are not signed, so macOS and Windows warn before they open. On Linux, the +installer script takes a mirror and an exact version: + +```sh +curl -fsSL https://raw.githubusercontent.com/scuttletoby/t3code/main/scripts/install.sh \ + | T3CODE_VERSION= \ + T3CODE_RELEASE_BASE_URL=https://github.com/scuttletoby/t3code/releases/download sh +``` + +`t3 update` on a fork build then looks only at the fork's releases. Every fork switch starts off. + +**From source.** Same as upstream's [development setup](../operations/development.md#first-checkout), +with this repository: + +```sh +git clone https://github.com/scuttletoby/t3code +cd t3code && vp i && vp run build:desktop +node apps/server/dist/bin.mjs +``` + +A build made this way does not know it is the fork: its `t3 update` and `t3 service install` would +fetch upstream's releases. Do not use them on it; update it with `git pull` and a rebuild. + +**A machine that already runs T3 as a boot service.** Do not switch it by hand. The go-live kit +([fork-kit/golive](../../fork-kit/golive/README.md)) is for this: today it has only its read-only +`check`. Its copy, rehearsal on the copy, switch and way back are not written yet, and the kits are +not yet installable from the release branch. Until then, try a build on a copy with +`t3 serve --hold-work --base-dir ` ([updates.md](updates.md#trying-a-build-on-a-copy-serve---hold-work)). + +Not there yet: a fork installer URL, a macOS CLI archive, signed desktop apps, and the go-live +switch. + +## Other fork pages + +- [updates.md](updates.md): update defaults, how a test pins them, the nightly sync runbook, + `serve --hold-work`. +- [anchor-machine.md](anchor-machine.md): one machine for new work, with upstream load balancing. +- [gate-trust.md](gate-trust.md): what the head gate proves, and the owner's steps. +- [host-tools.md](host-tools.md): design for agents on a person's own computer (no code yet). +- [`.github/fork-fleet.md`](../../.github/fork-fleet.md): the fleet runners and `CI_RUNNERS`. +- [`fork-ci/README.md`](../../fork-ci/README.md) and [`fork-kit/README.md`](../../fork-kit/README.md): + CI actions and host kits. diff --git a/docs/fork/updates.md b/docs/fork/updates.md index a98e2931ec6a2..bc32839597fbf 100644 --- a/docs/fork/updates.md +++ b/docs/fork/updates.md @@ -57,6 +57,9 @@ watches; it changes nothing on the machine, and `0` turns it off. that decision as `decidedIn`. 4. An agent tool may not write it: `FORK_AGENT_WRITABLE_KEYS` stays empty unless a pull request gives the reason. +5. Add its row and section to [README.md](README.md) and name it in + [FORK_CHANGES.md](../../FORK_CHANGES.md); `packages/shared/src/forkDocs.test.ts` fails until both + match the row in `forkDefaults.ts`. A key written straight into `settings.ts` is refused by the seam check, whatever its comment says. diff --git a/packages/shared/src/forkDocs.test.ts b/packages/shared/src/forkDocs.test.ts new file mode 100644 index 0000000000000..4c87ea8056581 --- /dev/null +++ b/packages/shared/src/forkDocs.test.ts @@ -0,0 +1,101 @@ +// @effect-diagnostics nodeBuiltinImport:off - reads the fork's docs from the repository. +/// + +// Fork: the fork's settings docs follow the one pin table (forkDefaults.ts), so a new fork setting +// without a docs row, or a docs row for a setting that does not exist, fails here. +import { FORK_SETTING_DEFAULTS, type ForkSettingDefault } from "@t3tools/contracts/forkDefaults"; +import * as NodeFS from "node:fs"; +import { describe, expect, it } from "vite-plus/test"; + +const repoFile = (path: string) => + NodeFS.readFileSync(new URL(`../../../${path}`, import.meta.url), "utf8"); + +const README = repoFile("docs/fork/README.md"); +const CHANGES = repoFile("FORK_CHANGES.md"); + +const rowId = (row: ForkSettingDefault) => `${row.scope}.${row.key}`; +const pinned = FORK_SETTING_DEFAULTS.map(rowId).toSorted(); +const byId = new Map(FORK_SETTING_DEFAULTS.map((row) => [rowId(row), row] as const)); + +/** A setting as the docs write it: `server.`, `projectOverride.` or `client.`. */ +const SETTING_ID = /`((?:server|projectOverride|client)\.[A-Za-z0-9]+)`/gu; + +/** The lines of one `## ` section, without its heading. */ +function section(markdown: string, heading: string): ReadonlyArray { + const lines = markdown.split("\n"); + const start = lines.indexOf(`## ${heading}`); + if (start === -1) throw new Error(`docs/fork/README.md has no "## ${heading}" section`); + const end = lines.findIndex((line, index) => index > start && line.startsWith("## ")); + return lines.slice(start + 1, end === -1 ? undefined : end); +} + +interface TableRow { + readonly line: string; + readonly cells: ReadonlyArray; +} + +/** Body rows of the first table in `lines` (no header, no separator). */ +function tableRows(lines: ReadonlyArray): ReadonlyArray { + const first = lines.findIndex((line) => line.startsWith("|")); + if (first === -1) return []; + const table = lines.slice(first); + const last = table.findIndex((line) => !line.startsWith("|")); + return table.slice(2, last === -1 ? undefined : last).map((line) => ({ + line, + cells: line + .split("|") + .slice(1, -1) + .map((cell) => cell.trim()), + })); +} + +/** The default cell as the README writes it: the settings file's JSON, or "not set". */ +const defaultCell = (row: ForkSettingDefault) => + row.default === undefined ? "not set" : `\`${JSON.stringify(row.default)}\``; + +const settingRows = tableRows(section(README, "Settings")); + +describe("fork settings docs (docs/fork/README.md)", () => { + it("has one table row for each fork setting and none for anything else", () => { + // A row whose first cell names no setting counts as "(no setting)" and fails the comparison. + const ids = settingRows.map( + (row) => [...row.cells[0]!.matchAll(SETTING_ID)][0]?.[1] ?? row.line, + ); + expect(ids.toSorted()).toEqual(pinned); + }); + + it.each(settingRows.map((row) => [row.cells[0]!, row] as const))( + "row %s matches its pin", + (_label, { cells }) => { + const id = [...cells[0]!.matchAll(SETTING_ID)][0]?.[1] ?? ""; + const row = byId.get(id); + expect(row, `no fork setting ${id}`).toBeDefined(); + if (row === undefined) return; + expect(cells[0]).toBe(`[\`${id}\`](#${id.toLowerCase().replace(".", "")})`); + expect(cells[1]).toBe(defaultCell(row)); + expect(cells[2]).toBe(row.off ? "yes" : "no"); + expect(cells[3]).toBe( + `[${row.decidedIn}](https://github.com/scuttletoby/t3code/issues/${row.decidedIn.slice(1)})`, + ); + }, + ); + + it("has one section for each fork setting", () => { + const headings = section(README, "Each setting") + .map((line) => /^### `([^`]+)`$/u.exec(line)?.[1]) + .filter((id) => id !== undefined); + expect(headings.toSorted()).toEqual(pinned); + }); +}); + +describe("fork changes list (FORK_CHANGES.md)", () => { + const named = new Set([...CHANGES.matchAll(SETTING_ID)].map((match) => match[1]!)); + + it("names every fork setting", () => { + expect(pinned.filter((id) => !named.has(id))).toEqual([]); + }); + + it("names no setting that does not exist", () => { + expect([...named].filter((id) => !byId.has(id))).toEqual([]); + }); +});