Skip to content

fork-changes-list: fail closed on unusual forkDefaults rows (#396) - #404

Merged
scuttletoby merged 2 commits into
mainfrom
fork-changes-list-row-shapes
Nov 17, 2026
Merged

scuttletoby merged 2 commits into
mainfrom
fork-changes-list-row-shapes

Conversation

@scuttletoby

Copy link
Copy Markdown
Owner

Fixes #396

What and why

Follow-ups from the lens on #389.

1. The settings-table reader fails closed on unusual rows (.github/scripts/fork-changes-list.cjs). pinnedIds read forkDefaults.ts as text and only counted scope:. Four shapes were skipped with no error, so a setting written that way could be missing from FORK_CHANGES.md and no test would go red:

Shape Before Now
spread ...EXTRA_ROWS, missed throws: `...EXTRA_ROWS,` is not a `{ ... }` row
helper call row("server", "x"), missed throws: not a { ... } row
shorthand { scope, key: "x" } (one line or several) missed throws: 0 "scope:" but 0 read
]; at column 0 inside a row table cut short, later rows missed throws: a row is still open at the table's "];"
an entry on the = [ line itself missed throws: `...` after the table's "["

The reader now walks the table line by line. Between rows, a non-blank line must be { (opening a row that ends at } / },), a whole { ... } row on one line, or a // comment. Each row must read as exactly one scope: "<scope>", key: "<key>". Each error names the line in forkDefaults.ts. Today's real table still reads 22 of 22 (22 scope: inside the table; the 23rd scope: in the file is the interface field, outside the table).

2. fork-owned-reads.test.py:62: dropped the "*" not in l filter on OWNED_DOCS. A name counts only when it equals a list line exactly, and that is what keeps runbook pointers out. With today's list (only FORK_CHANGES.md ends in .md), the filter changed nothing. Two notes:

  • The scan's path regex does allow * in a name. So with a future *.md line, code that writes that same glob (for example glob(".github/fork-*.md")) now counts as a read of owned docs. That errs red, which is the safe direction.
  • The comment now says that exact equality is the guard. The planted see .github/fork-fleet.md check still shows that a runbook pointer is not a read.

Tests (run as fork-tests runs them)

  • node --test .github/scripts/fork-changes-list.test.cjs: 8 pass. Changes:
    • New: one case per shape, red first. Before the fix, each of the 5 shapes read silently, e.g. the spread gave ["client.after","server.waitFor"] with no error.
    • New: a one-line row and a // comment between rows still read.
    • The existing "row it cannot read" assertion now matches the per-row message (line N: 1 "scope:" but 0 read).
  • python3 -I -B .github/scripts/fork-owned-reads.test.py: all passed, before and after. Item 2 changes nothing for the current list, so it has no red test.
  • Mutation checks. I disabled one guard at a time and each run went red:
    • the non-object-entry throw
    • the row-still-open throw
    • the per-row "exactly one scope/key" check
    • the head-line remainder check
    • reading one-line rows
  • Formatting and lint: the oxfmt --check and oxlint that ship with vite-plus, run without a config, pass on both .cjs files. Main's copies pass the same command, so it matches the repo's settings. vp check itself needs the workspace install, which this JS/Python-only change skipped. CI's lint job runs it.

State question

  • An old branch with an unusual row meets the new check: its merge commit is read by the new reader in the workflows job, which goes red. The error names the forkDefaults.ts line and says to write the setting as its own { ... } object literal. Nothing is skipped silently.
  • Empty table (= [\n];): throws no row read (existing test). A one-line = []; followed by another array is no longer misread as that array's rows: it throws `];` after the table's "[" (new test).
  • Table missing: throws no "export const FORK_SETTING_DEFAULTS ... = [" table. A missing closing ]; throws no closing "];" line. Both are existing tests and still pass.
  • Re-run: the reader is a pure function of the checked-out text, so a re-run gives the same answer.

General vs project

  • General: reading source as text has to name every shape it accepts and throw on anything else, rather than count one marker. A count of one marker silently passes entries that do not contain it.
  • Project: the accepted shapes match how this repo's formatter writes FORK_SETTING_DEFAULTS (two-space rows, { on its own line or a one-line row).

🤖 Generated with Claude Code

scuttletoby and others added 2 commits November 17, 2026 22:43
The FORK_SETTING_DEFAULTS text reader only counted `scope:`, so a spread,
a helper call or a shorthand `{ scope, ... }` row was skipped without an
error, and a column-0 `];` inside a row ended the table early. Each entry
between rows must now be a `{ ... }` object literal, each row must read
as exactly one scope and key, and a row still open at the `];` throws.
Errors name the line in forkDefaults.ts.

fork-owned-reads.test.py: drop the `"*" not in l` filter on OWNED_DOCS.
Names compare exactly, so it changed nothing for the current list.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@scuttletoby

Copy link
Copy Markdown
Owner Author

lens: state verdict: SAFE (head 51e332b)
read at: 51e332b

Lens: correctness + state. Read-only. I ran only node --test .github/scripts/fork-changes-list.test.cjs (8 pass) and python3 -I -B .github/scripts/fork-owned-reads.test.py (all passed). Probes were run against pinnedIds from a scratch script.

(1) Fail-closed: shapes the PR does not list (37 probes)

Throw (fail closed):

  • a trailing // note after a row's },, on the last row, on a one-line row, or on the scope: line
  • a template-string scope
  • key before scope
  • an extra field between scope and key
  • a nested row-like object in a value
  • a tab-indented table, or trailing whitespace after {
  • ] as const; or ] satisfies X;, with or without a later \n]; in the file
  • = then [ on the next line
  • rows moved into a const and spread in (...S,)
  • a re-export from another file
  • a conditional spread ...(flag ? [..] : [])
  • a /* */ line between rows
  • a key with _, or key: KEY
  • an empty table, a comment-only table, or a missing table
  • a template string in reason that holds \n },
  • CRLF line endings (moot: .gitattributes has * text=auto eol=lf)

Pass with the right list:

  • single quotes
  • a row over 8 lines with a nested multi-line object
  • a commented-out row, a commented-out old head line above the real table
  • ...BASE inside a row before scope
  • a duplicate row
  • a row closing } with no comma (not valid TS anyway)

Pass with a wrong list (the real risk). I found none for a formatted file a person would plausibly write. The ones I found are below as findings. Each is contrived, and none is a regression: main's text count missed more.

(2) Today's table

pinnedIds(forkDefaults.ts) gives 22 ids. I checked them by hand against packages/contracts/src/forkDefaults.ts:33-220:

  • server (16): automaticUpdates, automaticUpdatesQuietCommand, usagePacing, usagePacingGate, usagePacingLowerEffort, waitFor, waitChecks, playtest, handoff, reviewRules, agentSlots, headlessUsageRefreshInterval, mcpProfiles, mcpProfile, mcpSubagentProfile, mcpThreadProfiles
  • projectOverride (6): mcpProfile, mcpSubagentProfile, waitChecks, playtest, handoff, reviewRules

Exact match. The interface's readonly scope: (line 14) is outside the table.

(3) Item 2: fork-owned-reads.test.py:63

This is safe in both directions.

  • Today: OWNED_DOCS is {"FORK_CHANGES.md"} with or without the filter (computed both ways).
  • Future .github/fork-*.md line: a runbook pointer .github/fork-fleet.md is not equal to the glob, so it still does not count (no false red). A literal .github/fork-*.md in app code does count, and owned() says true for it. That is a real read, so red is correct.
  • Cannot hide a read: the set only grows, and it is used only as an allow-in at :121.
  • Repo today: no scanned (non-owned) file writes a fork *.md glob. The *.md hits in git grep are all in fork-owned files.

(4) State

  • Old branch: its merge commit is read by the new reader and goes red with the line number. Nothing passes silently.

  • Empty, missing, or unclosed table: all throw (probed).

  • Re-run: pinnedIds is a pure function of the text, and readRepoFile reads HEAD in the sparse checkout, so the answer is deterministic.

  • forkDefaults.ts mid-refactor on a PR branch: each of these throws:

    • a split into consts plus spreads
    • a re-export
    • a move to another file
    • as const / satisfies

    A commented-out old head line is ignored correctly. A second table with another name (e.g. FORK_SETTING_DEFAULTS_CLIENT) is not read; that is unchanged from main. forkDefaults.test.ts keys off FORK_SETTING_DEFAULTS, so that table is still the one source.

Findings

  • minor, .github/scripts/fork-changes-list.cjs:66-68, test gap. Mutation M3b survived: dropping || scopes !== 1 keeps all 8 tests green. That half is the only guard against a row with one unreadable and one readable scope:. With it removed, { scope: SCOPE, key: "x", note: { scope: "server", key: "a" } } reads silently as server.a (verified). Suggest one assert.throws case for it in the fail-closed test.

  • minor, .github/scripts/fork-changes-list.cjs:66-67. The per-row count looks at the row's whole text, including // and /* */ comments and nested values, not only its own top-level property. So these pass and read server.a, while the row's real id comes from the spread:

    • {\n // scope: "server", key: "a"\n ...ROW_B,\n }
    • {\n default: { scope: "server", key: "a" },\n ...ROW_B,\n }
    • { /* scope: "server", key: "a" */ ...ROW_B }

    The same applies to { scope: "server", key: "a", ...OTHER }, where the spread can override scope/key at runtime. These are contrived. A cheap fix: throw on any row line that starts with ..., and drop // lines from the row text before counting.

  • nit, .github/scripts/fork-changes-list.cjs:20. ROW_ONE_LINE's .* takes two entries on one line as one row when the second has no scope:. For example, { scope: "client", key: "b" }, { ...EXTRA }, reads only client.b and silently drops EXTRA. Only an unformatted file can reach this, because the formatter puts each element of a broken array on its own line and lint goes red first. Rejecting }, { inside a one-line row would close it.

  • nit, .github/scripts/fork-changes-list.cjs:70. When a row's close is not recognised ( }, // note, or a } with no comma), the next row is swallowed. The error then reads line N: 2 "scope:" but 2 read, which looks fine and does not name the cause. When scopes > 1, a hint such as "(is each row's }, on its own line?)" would help.

  • nit, test gap. Mutation M6 survived: ROW_CLOSE's two-space anchor is not pinned. Loosening it to any indent only causes a false red on a row with a multi-line nested value, not a silent miss. A multi-line default: {\n x: 1,\n }, row in the "reads" test would pin it. The PR code reads that shape correctly.

Mutations

Each mutation was applied one at a time, then git checkout; the tree was clean afterwards and 8/8 pass.

# Guard broken Result
M1 the non-row-entry throw (:54 → else if (false)) red (#396 test)
M2 the row-still-open throw (:60 → if (false)) red (#396 test)
M3 the per-row exactly-one check (:68 → if (false)) red (2 tests)
M3b drop || scopes !== 1 only survived: silent server.a (see minor above)
M3c drop read.length !== 1 only red
M4 the head-line remainder (:39 → if (false)) red (#396 test)
M5 read one-line rows (:53 → else if (false)) red (2 tests)
M6 ROW_CLOSE to /^\s*\},?$/ survived: fails closed (false red only), nit above
M7 the empty-table throw (:64 → if (false)) red

No blocker or major. The two minors are a missing test for an existing guard and a contrived fail-open path. Neither is a regression, and either can go in this PR or a follow-up.

@scuttletoby
scuttletoby marked this pull request as ready for review November 17, 2026 22:05
@scuttletoby
scuttletoby merged commit 2f3c54b into main Nov 17, 2026
25 checks passed
scuttletoby added a commit that referenced this pull request Nov 18, 2026
)

* fork-changes-list: fail closed on unusual forkDefaults rows (#396)

The FORK_SETTING_DEFAULTS text reader only counted `scope:`, so a spread,
a helper call or a shorthand `{ scope, ... }` row was skipped without an
error, and a column-0 `];` inside a row ended the table early. Each entry
between rows must now be a `{ ... }` object literal, each row must read
as exactly one scope and key, and a row still open at the `];` throws.
Errors name the line in forkDefaults.ts.

fork-owned-reads.test.py: drop the `"*" not in l` filter on OWNED_DOCS.
Names compare exactly, so it changed nothing for the current list.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fork-changes-list: keep pinnedIds' doc comment to 4 lines

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
scuttletoby added a commit that referenced this pull request Nov 18, 2026
)

* fork-changes-list: fail closed on unusual forkDefaults rows (#396)

The FORK_SETTING_DEFAULTS text reader only counted `scope:`, so a spread,
a helper call or a shorthand `{ scope, ... }` row was skipped without an
error, and a column-0 `];` inside a row ended the table early. Each entry
between rows must now be a `{ ... }` object literal, each row must read
as exactly one scope and key, and a row still open at the `];` throws.
Errors name the line in forkDefaults.ts.

fork-owned-reads.test.py: drop the `"*" not in l` filter on OWNED_DOCS.
Names compare exactly, so it changed nothing for the current list.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fork-changes-list: keep pinnedIds' doc comment to 4 lines

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

fork-changes-list: fail on unusual forkDefaults row shapes (#389 follow-ups)

1 participant