Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .github/fork-ci-tests.txt
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
3 changes: 3 additions & 0 deletions .github/fork-owned-paths.txt
Original file line number Diff line number Diff line change
Expand Up @@ -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
85 changes: 85 additions & 0 deletions .github/scripts/fork-changes-list.cjs
Original file line number Diff line number Diff line change
@@ -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.<key>`, `projectOverride.<key>` or `client.<key>`. */
const SETTING_ID = /`((?:server|projectOverride|client)\.[A-Za-z0-9]+)`/gu;

/**
* `<scope>.<key>` 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: "<scope>", key: "<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 };
110 changes: 110 additions & 0 deletions .github/scripts/fork-changes-list.test.cjs
Original file line number Diff line number Diff line change
@@ -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<ForkSettingDefault> = [\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));
});
6 changes: 3 additions & 3 deletions .github/scripts/fork-owned-paths.test.py
Original file line number Diff line number Diff line change
Expand Up @@ -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/",
Expand Down
9 changes: 7 additions & 2 deletions .github/scripts/fork-owned-reads.test.py
Original file line number Diff line number Diff line change
Expand Up @@ -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"(?<![\w.-])(" + "|".join(map(re.escape, ROOTS)) + r")(/[\w.*/-]*)?")
# A doc the list owns by its own line (FORK_CHANGES.md): naming it is a read, unlike a runbook a message points to
# (a `.md` matched by a wider line such as `.github/fork-*`).
OWNED_DOCS = {l for l in LIST_LINES if l.endswith(".md") and not l.startswith("!") and "*" not in l}
# A fork-owned folder named alone, as in `path.join(root, "fork-ci", name)`: counts as a path inside it.
FOLDERS = {l.rstrip("/") for l in LIST_LINES if l.endswith("/") and l.count("/") == 1}
# A path built from quoted parts: `".github", "fork-x"` (path.join), `Path(".github") / "fork-x"`, `".github/" + "x"`.
Expand Down Expand Up @@ -114,7 +117,7 @@ def reads(files, tracked_files):
name = (m.group(1) + (m.group(2) or "")).rstrip(".")
if not m.group(2) and m.group(1) in FOLDERS and not re.match(r"[\w.-]", t[m.end():m.end() + 1]):
name += "/"
if not name.endswith(".md"): # a runbook a message points to is not read
if not name.endswith(".md") or name in OWNED_DOCS: # a runbook a message points to is not read
found.add((path, name.rstrip("/") + ("/x" if name.endswith("/") else "")))
for m in SIBLING_RE.finditer(text):
name = m.group(1) or m.group(2) + ".py"
Expand Down Expand Up @@ -171,6 +174,7 @@ def reads(files, tracked_files):
"native/f.py": 'kit = Path("fork-kit") / "heavy"\n',
"evals/g.ts": 'const a = join(root, "fork-ci", name);\nconst b = ".github/" + "fork-ci-tests.txt";\n',
".github/scripts/h.py": 'm = importlib.import_module("fork_workflow_expr")\n',
"packages/shared/src/i.test.ts": 'const changes = repoFile("FORK_CHANGES.md");\n',
}
got = reads({**PLANTED, "apps/web/src/d.ts": "// reads .github/fork-ci-tests.txt and fork-ci/x\n"
" * fork-kit/heavy, see .github/fork-fleet.md\nconst p = '.github/pull_request_template.md';\n"
Expand All @@ -184,7 +188,8 @@ def reads(files, tracked_files):
(".github/scripts/fork-test-shards.cjs", ".github/scripts/fork-seam-check.cjs"),
("infra/e.ts", ".github/fork-ci-tests.txt"), ("native/f.py", "fork-kit/heavy"),
("native/f.py", "fork-kit/x"), ("evals/g.ts", "fork-ci/x"), ("evals/g.ts", ".github/fork-ci-tests.txt"),
(".github/scripts/h.py", ".github/scripts/fork_workflow_expr.py")}, str(sorted(got)))
(".github/scripts/h.py", ".github/scripts/fork_workflow_expr.py"),
("packages/shared/src/i.test.ts", "FORK_CHANGES.md")}, str(sorted(got)))

print(f"\n{len(failures)} failed" if failures else "\nall passed")
sys.exit(1 if failures else 0)
4 changes: 2 additions & 2 deletions FORK_CHANGES.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,8 +7,8 @@ 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.<key>` (the server's `settings.json`) or `projectOverride.<key>`
(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

Expand Down
5 changes: 3 additions & 2 deletions docs/fork/updates.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down
17 changes: 3 additions & 14 deletions packages/shared/src/forkDocs.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,9 @@
/// <reference types="vite-plus/client" />

// 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";
Expand All @@ -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();
Expand Down Expand Up @@ -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([]);
});
});
Loading