From 2cca645d9f38ff8c6de68abac32b21fdfbc6dde4 Mon Sep 17 00:00:00 2001 From: scuttletoby <123843277+scuttletoby@users.noreply.github.com> Date: Tue, 17 Nov 2026 22:14:24 +0100 Subject: [PATCH] fork CI: FORK_CHANGES.md checks move to the workflows job so fork-only PRs skip app tests (#259) The FORK_CHANGES.md checks (every fork setting named, no unknown setting) move from the vitest file packages/shared/src/forkDocs.test.ts to .github/scripts/fork-changes-list.test.cjs, which reads forkDefaults.ts as text and runs in Fork tests' `workflows` job on every pull request. FORK_CHANGES.md is now fork-owned, so a fork feature pull request that only adds its line there skips the app jobs. fork-owned-reads.test.py now counts a read of a `.md` file the list owns by its own line, so an app test reading FORK_CHANGES.md again is caught. Co-Authored-By: Claude Opus 5.5 --- .github/fork-ci-tests.txt | 1 + .github/fork-owned-paths.txt | 3 + .github/scripts/fork-changes-list.cjs | 85 ++++++++++++++++ .github/scripts/fork-changes-list.test.cjs | 110 +++++++++++++++++++++ .github/scripts/fork-owned-paths.test.py | 6 +- .github/scripts/fork-owned-reads.test.py | 9 +- FORK_CHANGES.md | 4 +- docs/fork/updates.md | 5 +- packages/shared/src/forkDocs.test.ts | 17 +--- 9 files changed, 217 insertions(+), 23 deletions(-) create mode 100644 .github/scripts/fork-changes-list.cjs create mode 100644 .github/scripts/fork-changes-list.test.cjs diff --git a/.github/fork-ci-tests.txt b/.github/fork-ci-tests.txt index bf1ce7a94f272..b7d5030366887 100644 --- a/.github/fork-ci-tests.txt +++ b/.github/fork-ci-tests.txt @@ -28,6 +28,7 @@ .github/scripts/fork-owned-reads.test.py run by .github/workflows/fork-tests.yml .github/scripts/fork-pr-queue-workflow.test.py .github/scripts/fork-ci-release.test.py +.github/scripts/fork-changes-list.test.cjs .github/scripts/fork-release-workflow.test.py .github/scripts/fork-release.test.sh ~5s .github/scripts/fork-run-alert.test.sh diff --git a/.github/fork-owned-paths.txt b/.github/fork-owned-paths.txt index d13ff5d8178fc..565e0ac1a0b73 100644 --- a/.github/fork-owned-paths.txt +++ b/.github/fork-owned-paths.txt @@ -28,6 +28,9 @@ fork-kit/ !.github/scripts/fork-vitest-gc-check.cjs !.github/fork-fleet.json +# The fork's changes list; fork-changes-list.test.cjs (the `workflows` job) checks it against forkDefaults.ts. +FORK_CHANGES.md + # The secret scan's settings; the `secrets` job runs on every pull request. .gitleaks.toml .gitleaksignore diff --git a/.github/scripts/fork-changes-list.cjs b/.github/scripts/fork-changes-list.cjs new file mode 100644 index 0000000000000..4cb407c58d129 --- /dev/null +++ b/.github/scripts/fork-changes-list.cjs @@ -0,0 +1,85 @@ +// Fork only: FORK_CHANGES.md names every fork setting of the pin table (packages/contracts/src/forkDefaults.ts, +// read as text) and no setting that does not exist. Run by fork-changes-list.test.cjs in Fork tests' `workflows` +// job, which runs on every pull request, so FORK_CHANGES.md can be fork-owned (.github/fork-owned-paths.txt) and a +// fork feature pull request that only adds its line there still skips the app jobs. +const { execFileSync } = require("node:child_process"); +const fs = require("node:fs"); +const path = require("node:path"); + +const ROOT = path.resolve(__dirname, "../.."); +const CHANGES = "FORK_CHANGES.md"; +const DEFAULTS = "packages/contracts/src/forkDefaults.ts"; +const SCOPES = ["server", "projectOverride", "client"]; + +/** A setting as the docs write it: `server.`, `projectOverride.` or `client.`. */ +const SETTING_ID = /`((?:server|projectOverride|client)\.[A-Za-z0-9]+)`/gu; + +/** + * `.` of each row of FORK_SETTING_DEFAULTS in forkDefaults.ts's text. Throws when the table is not + * found, is empty, or has a `scope:` the parse cannot pair with its `key:` (fail closed: a row it cannot read + * would otherwise go unchecked). + */ +function pinnedIds(text) { + const start = text.search(/^export const FORK_SETTING_DEFAULTS\b[^=]*=\s*\[/mu); + if (start === -1) + throw new Error(`${DEFAULTS}: no "export const FORK_SETTING_DEFAULTS ... = [" table`); + const end = text.indexOf("\n];", start); + if (end === -1) + throw new Error(`${DEFAULTS}: the FORK_SETTING_DEFAULTS table has no closing "];" line`); + const table = text.slice(start, end); + const scopes = [...table.matchAll(/\bscope:/gu)].length; + const rows = [...table.matchAll(/\bscope:\s*(["'])(\w+)\1,\s*key:\s*(["'])([A-Za-z0-9]+)\3/gu)]; + if (rows.length === 0) throw new Error(`${DEFAULTS}: no row read from FORK_SETTING_DEFAULTS`); + if (rows.length !== scopes) { + throw new Error( + `${DEFAULTS}: ${scopes} "scope:" in FORK_SETTING_DEFAULTS but ${rows.length} read as ` + + '`scope: "", key: ""` (write each row that way)', + ); + } + const unknown = rows.filter((row) => !SCOPES.includes(row[2])); + if (unknown.length > 0) { + throw new Error(`${DEFAULTS}: unknown scope ${unknown.map((row) => row[2]).join(", ")}`); + } + return rows.map((row) => `${row[2]}.${row[4]}`).sort(); +} + +/** The settings FORK_CHANGES.md names, sorted and without repeats. */ +function namedIds(text) { + return [...new Set([...text.matchAll(SETTING_ID)].map((match) => match[1]))].sort(); +} + +/** { missing: pinned settings the list does not name, unknown: named settings that are not pinned }. */ +function compare(pinned, named) { + return { + missing: pinned.filter((id) => !named.includes(id)), + unknown: named.filter((id) => !pinned.includes(id)), + }; +} + +function git(args, root) { + return execFileSync("git", args, { + cwd: root, + encoding: "utf8", + stdio: ["ignore", "pipe", "pipe"], + }); +} + +/** + * A repository file's text. The `workflows` job's sparse checkout may leave it out of the working tree; then (and + * only in a sparse checkout) it is read from the checked-out commit, whose objects git fetches on demand. A file + * missing from a full checkout is an error, as is one missing from the commit. + */ +function readRepoFile(file, root = ROOT) { + const full = path.join(root, file); + if (fs.existsSync(full)) return fs.readFileSync(full, "utf8"); + let sparse = ""; + try { + sparse = git(["config", "--bool", "core.sparseCheckout"], root).trim(); + } catch { + // not set: a full checkout + } + if (sparse !== "true") throw new Error(`${file} is missing from the checkout`); + return git(["show", `HEAD:${file}`], root); +} + +module.exports = { CHANGES, DEFAULTS, SETTING_ID, pinnedIds, namedIds, compare, readRepoFile }; diff --git a/.github/scripts/fork-changes-list.test.cjs b/.github/scripts/fork-changes-list.test.cjs new file mode 100644 index 0000000000000..89563b7c4ddc6 --- /dev/null +++ b/.github/scripts/fork-changes-list.test.cjs @@ -0,0 +1,110 @@ +// FORK_CHANGES.md against the fork's pin table (fork-changes-list.cjs), and the guards that keep the check honest. +// node --test .github/scripts/fork-changes-list.test.cjs +const assert = require("node:assert/strict"); +const { execFileSync } = require("node:child_process"); +const fs = require("node:fs"); +const os = require("node:os"); +const path = require("node:path"); +const test = require("node:test"); +const { + CHANGES, + DEFAULTS, + pinnedIds, + namedIds, + compare, + readRepoFile, +} = require("./fork-changes-list.cjs"); + +// Read once: a file that cannot be read fails both checks below. +const read = () => { + const pinned = pinnedIds(readRepoFile(DEFAULTS)); + return { pinned, ...compare(pinned, namedIds(readRepoFile(CHANGES))) }; +}; + +test(`${CHANGES} names every fork setting (${DEFAULTS})`, () => { + const { pinned, missing } = read(); + assert.ok(pinned.length > 0); + assert.deepEqual( + missing, + [], + `fork settings ${CHANGES} does not name: add each to its change's line`, + ); +}); + +test(`${CHANGES} names no setting that does not exist`, () => { + const { unknown } = read(); + assert.deepEqual(unknown, [], `settings ${CHANGES} names that ${DEFAULTS} does not pin`); +}); + +const TABLE = (rows) => + `export interface ForkSettingDefault {\n readonly scope: ForkSettingScope;\n}\n\n` + + `export const FORK_SETTING_DEFAULTS: ReadonlyArray = [\n${rows}];\n\n` + + `const after = [{ scope: "server", key: "notARow" }];\n`; +const ROW = (scope, key, extra = "") => + ` {\n scope: "${scope}",\n key: "${key}",\n default: { enabled: false },${extra}\n off: true,\n },\n`; + +test("pinnedIds reads each row's scope and key, and nothing outside the table", () => { + assert.deepEqual( + pinnedIds(TABLE(ROW("server", "waitFor") + ROW("projectOverride", "waitChecks"))), + ["projectOverride.waitChecks", "server.waitFor"], + ); +}); + +test("pinnedIds fails closed: no table, an empty one, a row it cannot read, an unknown scope", () => { + assert.throws( + () => pinnedIds("export const OTHER = [\n];\n"), + /no "export const FORK_SETTING_DEFAULTS/u, + ); + assert.throws(() => pinnedIds(TABLE("")), /no row read/u); + assert.throws( + () => + pinnedIds(TABLE(ROW("server", "waitFor") + ` {\n scope: SCOPE,\n key: "x",\n },\n`)), + /2 "scope:" .* but 1 read/u, + ); + assert.throws(() => pinnedIds(TABLE(ROW("machine", "x"))), /unknown scope machine/u); + assert.throws(() => pinnedIds("export const FORK_SETTING_DEFAULTS = [\n"), /no closing/u); +}); + +test("namedIds takes only `scope.key` in backticks; compare finds missing and unknown settings", () => { + const named = namedIds( + "`server.waitFor`, `server.waitFor`, server.bare, `other.key`, `client.theme`\n", + ); + assert.deepEqual(named, ["client.theme", "server.waitFor"]); + assert.deepEqual(compare(["server.agentSlots", "server.waitFor"], named), { + missing: ["server.agentSlots"], + unknown: ["client.theme"], + }); + // An empty list names nothing: every setting is missing. + assert.deepEqual(compare(["server.waitFor"], namedIds("")), { + missing: ["server.waitFor"], + unknown: [], + }); +}); + +function repo(t) { + const root = fs.mkdtempSync(path.join(os.tmpdir(), "fork-changes-list-")); + t.after(() => fs.rmSync(root, { recursive: true, force: true })); + const git = (...args) => + execFileSync("git", args, { cwd: root, stdio: "pipe", encoding: "utf8" }); + git("init", "-q"); + fs.mkdirSync(path.join(root, "kept")); + fs.writeFileSync(path.join(root, "kept/a.txt"), "kept\n"); + fs.writeFileSync(path.join(root, "left.txt"), "from the commit\n"); + git("add", "."); + git("-c", "user.name=t", "-c", "user.email=t@example.invalid", "commit", "-qm", "files"); + return { root, git }; +} + +test("readRepoFile reads the working tree, and the commit only for a file a sparse checkout left out", (t) => { + const { root, git } = repo(t); + fs.writeFileSync(path.join(root, "left.txt"), "edited\n"); + assert.equal(readRepoFile("left.txt", root), "edited\n"); + fs.rmSync(path.join(root, "left.txt")); + // A full checkout with the file gone (deleted, not left out): an error, not the committed copy. + assert.throws(() => readRepoFile("left.txt", root), /missing from the checkout/u); + git("checkout", "-q", "--", "left.txt"); + git("sparse-checkout", "set", "--no-cone", "/kept/"); + assert.equal(fs.existsSync(path.join(root, "left.txt")), false); + assert.equal(readRepoFile("left.txt", root), "from the commit\n"); + assert.throws(() => readRepoFile("not-in-the-commit.txt", root)); +}); diff --git a/.github/scripts/fork-owned-paths.test.py b/.github/scripts/fork-owned-paths.test.py index 670367a08f6c4..952bd19c004f0 100644 --- a/.github/scripts/fork-owned-paths.test.py +++ b/.github/scripts/fork-owned-paths.test.py @@ -159,17 +159,17 @@ def fork_only(out): REAL = owned([ "fork-ci/actions/pr-queue/pr_queue.py", "fork-kit/heavy/heavy", ".github/scripts/fork-fleet-walls.py", ".github/scripts/fork-fleet-walls/linux", ".github/scripts/fork_workflow_expr.py", ".github/fork-ci-tests.txt", - ".gitleaks.toml", + ".gitleaks.toml", "FORK_CHANGES.md", # never ".github/fork-owned-paths.txt", ".github/scripts/fork-owned-paths.cjs", ".github/workflows/fork-tests.yml", ".github/workflows/fork-checks.yml", ".github/actions/ci-changes/action.yml", ".github/scripts/ci-changes.cjs", ".github/scripts/fork-fleet.py", ".github/scripts/fork-test-shards.cjs", ".github/scripts/fork-vitest-gc-check.cjs", ".github/fork-fleet.json", "fork-ci/package.json", "fork-kit/x/tsconfig.json", "package.json", "apps/web/src/a.ts", - "docs/fork/README.md", "scripts/release-smoke.ts", "FORK_CHANGES.md", "fork-ci", "fork-cix/a", + "docs/fork/README.md", "scripts/release-smoke.ts", "fork-ci", "fork-cix/a", ]) want_owned = {p for p in REAL if p.startswith(("fork-ci/actions", "fork-kit/heavy")) or p in { ".github/scripts/fork-fleet-walls.py", ".github/scripts/fork-fleet-walls/linux", ".github/scripts/fork_workflow_expr.py", - ".github/fork-ci-tests.txt", ".gitleaks.toml"}} + ".github/fork-ci-tests.txt", ".gitleaks.toml", "FORK_CHANGES.md"}} check("list: the fork's own folders and scripts are fork-owned; the rest, and every NEVER path, are not", {p for p, v in REAL.items() if v} == want_owned, json.dumps({p: v for p, v in REAL.items() if v != (p in want_owned)})) check("list: NEVER wins over a line that owns everything under .github/", diff --git a/.github/scripts/fork-owned-reads.test.py b/.github/scripts/fork-owned-reads.test.py index ae60c512c56e7..6b59c940dc077 100644 --- a/.github/scripts/fork-owned-reads.test.py +++ b/.github/scripts/fork-owned-reads.test.py @@ -57,6 +57,9 @@ def owned(paths): LIST_LINES = [l.strip() for l in LIST.read_text().splitlines() if l.strip() and not l.startswith("#")] ROOTS = sorted({l.lstrip("!").split("/")[0] for l in LIST_LINES}) PATH_RE = re.compile(r"(?` (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. +(one project's overrides). A test (`.github/scripts/fork-changes-list.test.cjs`) fails when a fork +setting is missing here or a setting named here does not exist. ## In T3 Code itself diff --git a/docs/fork/updates.md b/docs/fork/updates.md index 6d9c587b2fcc2..10ec3671272d8 100644 --- a/docs/fork/updates.md +++ b/docs/fork/updates.md @@ -82,8 +82,9 @@ watches; it changes nothing on the machine, and `0` turns it off. 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`. + [FORK_CHANGES.md](../../FORK_CHANGES.md); `packages/shared/src/forkDocs.test.ts` (the README) and + `.github/scripts/fork-changes-list.test.cjs` (FORK_CHANGES.md) fail 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 index 4c87ea8056581..ca5353ccd4a6b 100644 --- a/packages/shared/src/forkDocs.test.ts +++ b/packages/shared/src/forkDocs.test.ts @@ -2,7 +2,9 @@ /// // 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. +// without a docs row, or a docs row for a setting that does not exist, fails here. The fork's changes +// list is checked by .github/scripts/fork-changes-list.test.cjs (Fork tests' `workflows` job), so a pull +// request that changes only fork-owned files skips this app job. import { FORK_SETTING_DEFAULTS, type ForkSettingDefault } from "@t3tools/contracts/forkDefaults"; import * as NodeFS from "node:fs"; import { describe, expect, it } from "vite-plus/test"; @@ -11,7 +13,6 @@ 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(); @@ -87,15 +88,3 @@ describe("fork settings docs (docs/fork/README.md)", () => { 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([]); - }); -});