diff --git a/.github/scripts/gen-inputs-table.ts b/.github/scripts/gen-inputs-table.ts index a5471ba9a..0736bc7f6 100644 --- a/.github/scripts/gen-inputs-table.ts +++ b/.github/scripts/gen-inputs-table.ts @@ -51,17 +51,8 @@ const row = lineOf([ backticked, ]); -/** What action-docs writes between its markers, by position after the opening marker's own line ends: - * - * "" the rest of the marker line - * "## Inputs" - * "" - * "| name | description | required | default |" - * "| --- | --- | --- | --- |" - * one row per input a description never holds a "|" (test/docs/inputs.test.ts) - * "" before the closing marker - * - * A region of blank lines alone (a fresh marker pair) is also a rendering's shape. */ +/** The first entry is the rest of the opening marker's own line. A "|" in a description would split its rendered row + * past `row`'s four cells and refuse it as authored, so test/docs/inputs.test.ts pins every description free of one. */ const LEADING: ((line: string) => boolean)[] = [ (line) => line === "", (line) => line === "## Inputs", diff --git a/.github/scripts/release-pipeline.ts b/.github/scripts/release-pipeline.ts index 1d807ca02..d9d04f161 100644 --- a/.github/scripts/release-pipeline.ts +++ b/.github/scripts/release-pipeline.ts @@ -10,27 +10,14 @@ * refs/tags/vX -> the same commit, moved on each release in the line * * Every artifact is a function of its main commit alone, so runs for different commits never wait on each other - * and a rerun mints the same name and verifies instead of appending. latest and vX move through movePointer alone: - * forward along main, under a compare-and-set on the value origin advertised, never back. + * and a rerun mints the same name and verifies instead of appending. latest and vX move through movePointer alone. + * Every subcommand but prerelease-version runs under a workflow step, bare or in the step's shell; no step runs two. * - * release-please cuts the DRAFT release without a tag (`draft` on, `force-tag-creation` off); one subcommand runs - * per workflow step: + * release-please cuts the DRAFT release without a tag (`draft` on, `force-tag-creation` off) and creates or + * refreshes the release PR only when a releasable commit lands (release-please-config.json leaves always-update + * off); that refresh is what publishes the `next` pre-release. * - * package-commit post-green.yml GITHUB_SHA, RUN_URL (optional) - * anchor update-release-pr.yml GITHUB_SHA - * npm-verdict next update-release-pr.yml GITHUB_SHA, NPM_REGISTRY_URL (optional) - * npm-confirm next update-release-pr.yml GITHUB_SHA, NPM_REGISTRY_URL (optional), NPM_CONFIRM_PAUSE_MS (optional) - * npm-verdict stable update-release.yml TAG, GITHUB_SHA, NPM_REGISTRY_URL (optional) - * npm-floor both publish jobs (nothing; npm on PATH) - * package, retag-major update-release.yml TAG, GITHUB_SHA, RUN_URL (optional, package only) - * boundary-check, anchor-check checks.yml (the checkout alone) - * prerelease-version by hand GITHUB_SHA (the version a commit's next publish carries) - * - * The `next` pre-release publishes when release-please creates or refreshes the release PR, which it does only when a - * releasable commit lands (release-please-config.json leaves always-update off); npm-verdict next is the guard on - * npm state that follows, never the decision to publish. - * - * Node builtins only: bun runs this before `bun install`. Tests: test/scripts/release-pipeline*.test.ts over release-pipeline-fixture.ts. + * Node builtins only: bun runs this before `bun install`. */ import { execFileSync, spawnSync } from "node:child_process"; @@ -454,15 +441,9 @@ export interface PointerMove { * The one way a pointer (latest, vX) moves: forward along main, never back. A pointer's source is its commit's * parent when that parent is on main; the candidate's source is on main by its caller's check. * - * pointer's source is the candidate's or descends from it -> left: the same package, or a rerun of an older commit's run - * same source, another tree -> refused: two builds of one main commit - * pointer's source unknown (off main, a root) -> moved: a value this pipeline did not mint - * otherwise -> moved, under a lease on the value observed - * * A value left in place must be a package of the commit it is read as packaging, or a hand-pushed bare child of a * newer commit would stand as "already past". Main's head is read AFTER the pointer on every pass: a pointer a rival - * moved to a newer commit's package has that commit on main by then. A lease lost to a rival re-observes and - * decides again; a push refused with the ref unmoved is thrown. + * moved to a newer commit's package has that commit on main by then. */ export function movePointer(cwd: string, ref: string, candidate: Packaged): PointerMove { for (let attempt = 1; attempt <= PUSH_ATTEMPTS; attempt++) { diff --git a/src/discovery/discover.ts b/src/discovery/discover.ts index bc9c2b70b..ab798b995 100644 --- a/src/discovery/discover.ts +++ b/src/discovery/discover.ts @@ -89,15 +89,14 @@ export interface ExcludePattern { } /** - * `nocase`: repository names compare case-insensitively on GitHub. `dot`: a leading "." is an ordinary character - * in a repository name (".github"), not the hidden-file marker picomatch skips by default. `posix`: "[!ab]" is a - * negated class, as in a shell, instead of a class holding "!". `fastpaths: false`: the shortcut regexes picomatch - * mints for star-led patterns demand a character after a literal dot, so "*.*" would miss "archive."; the full - * parser keeps "*" any run of characters. `debug`: an invalid class like "[z-a]" throws instead of compiling to a - * never-matching regex. `windows: false`: the main entry otherwise follows the host OS, and a slug is a GitHub - * identifier, not a path, so the matcher is the same on every runner. `literalBrackets: false`: a class compiles - * to the class alone, not an alternation with its literal text, which no name holds; thousands of classes then - * compile in milliseconds instead of reaching the engine's size limit. + * picomatch is built for file paths and a slug is a GitHub identifier, so each option is set for a name, none left to its default: + * nocase -> GitHub compares repository names case-insensitively + * dot -> a leading "." is an ordinary name character (".github"), not the hidden-file marker + * posix -> "[!ab]" is a negated class, as in a shell, not a class holding "!" + * fastpaths -> the star-led shortcut regexes demand a character after a literal dot, so "*.*" would miss "archive." + * debug -> an invalid class like "[z-a]" throws instead of compiling to a never-matching regex + * windows -> pinned: only picomatch's main callable reads the host OS; makeRe never does + * literalBrackets -> no alternation with the class's literal text (no name holds it); thousands compile in milliseconds, under the engine's limit */ const EXCLUDE_GLOB_OPTIONS = { nocase: true, diff --git a/src/flows/settings-write.ts b/src/flows/settings-write.ts index ae8cdad4a..90e900768 100644 --- a/src/flows/settings-write.ts +++ b/src/flows/settings-write.ts @@ -1,13 +1,13 @@ /** - * The one place a run writes a settings document (a snapshot, the merged file, init's starting file): staged beside - * the destination and renamed into place, so a write that fails partway (disk full, an interrupted run) leaves the - * previous file intact instead of a truncated one. The rename is atomic on POSIX and a single replace call on - * Windows. The staging name is unique to the write (pid and random bytes), so no file of the user's is ever unlinked - * or written through: an existing path there fails the write instead. A destination that is a symlink is replaced by - * the rename, the link itself, never its referent, so the written document is always a regular file at `path`. The - * guards over the writer hold one promise: an input layer is never the destination, under any name the read follows - * or the rename reaches; deliberate evasion (hardlinks, mounts, races) is out of scope. A hard crash mid-write leaves - * the staging file for the user to remove (.gitignore hides it); no run sweeps a file another process may be writing. + * The one place a run writes a settings document (a snapshot, the merged file, init's starting file). The guards + * over the writer hold one promise: an input layer is never the destination, under any name the read follows or the + * rename reaches. Deliberate evasion (hardlinks, mounts, races) is out of scope. + * + * staged beside the destination, renamed in -> a write that fails partway leaves the previous file intact + * the rename -> atomic on POSIX, a single replace call on Windows + * a symlink at the destination -> the link itself is replaced, never its referent: `path` is always a regular file after + * a hard crash mid-write -> the staging file is left for the user to remove (.gitignore hides it); no run + * sweeps a file another process may be writing */ import { randomBytes } from "node:crypto"; diff --git a/src/github/secret-scan.ts b/src/github/secret-scan.ts index b49378ab0..6e00136d4 100644 --- a/src/github/secret-scan.ts +++ b/src/github/secret-scan.ts @@ -49,9 +49,6 @@ function renderKeyPath(path: readonly string[]): string { * a property -> read through its descriptor; an enumerable accessor is rejected UNREAD (a getter could sabotage globals) * an object's keys -> only Object.keys are copied, so symbol and non-enumerable keys never reach the copy (array indices do) * a container again -> rejected when it is one of its own ancestors (a YAML alias cycle); a sibling alias is copied twice - * the wire -> only the copy is sent - * - * A rejection is the NotPlainData the walk hands up, an instance no payload value can be. */ function normalizePlainData( value: unknown, diff --git a/src/sections/contract/errors.ts b/src/sections/contract/errors.ts index 34bc49fef..3ff241dde 100644 --- a/src/sections/contract/errors.ts +++ b/src/sections/contract/errors.ts @@ -14,15 +14,11 @@ import { grantFor, type SectionPermission, samePermission } from "./permissions. * What ends a section's work, as a value. `message` is the whole line the loops report; `kind` is read for policy * alone (a denial's partial-success handling in engine/orchestrate.ts), never to rebuild prose. * - * request kinds (failureFor and the request helpers): rate-limit, rejected, server-error, unauthorized, - * validation, transport, malformed - * duplicate kinds (the identity checks): declared-duplicate, live-duplicate - * live-shape -> GitHub's answer parsed but cannot be reconciled (an item without an id, a repeated rule type) - * refused -> the section declines to proceed: the settings file conflicts with live state, an actor cannot - * be resolved, a write would drop live values the file omits - * unverified -> a write landed but its echo disagrees with what was set - * thrown -> an exception escaped a section: the client's own throw on an unmarked request, or a BUG - * invariant; the loops report its message like any other failure + * live-shape -> GitHub's answer parsed but cannot be reconciled (an item without an id, a repeated rule type) + * refused -> the section declines to proceed: the settings file conflicts with live state, an actor cannot be + * resolved, a write would drop live values the file omits + * unverified -> a write landed but its echo disagrees with what was set + * thrown -> an exception escaped a section: the client's own throw on an unmarked request, or a BUG invariant */ export type SectionFailure = | { diff --git a/src/sections/shared/roles.ts b/src/sections/shared/roles.ts index 55e6741f8..35f940572 100644 --- a/src/sections/shared/roles.ts +++ b/src/sections/shared/roles.ts @@ -45,13 +45,7 @@ const STANDARD_PERMISSIONS = ["pull", "triage", "push", "maintain", "admin"] as * The two wrong spellings hide until apply: "write" on an existing Write collaborator converges with zero drift * (the live role_name IS "write") while the same entry on a new one PUTs {"permission":"write"} and 422s. * - * read, write (any case) -> the vocabulary GET reports a role in; the grant takes pull, push - * Push, ADMIN (a mis-cased standard) -> the lowercase form - * "", " push", "push\n" (block scalar) -> nothing to grant, or whitespace GitHub would not match - * - * One regex, so the published schema carries the same rule as a `pattern` (a pattern has no flags, hence the - * case classes): an exact standard permission, or one line with no whitespace at either end that folds to none - * of the seven words. + * One regex, so the published schema carries the same rule as a `pattern`; a pattern has no flags, hence the case classes. */ const REFUSED_FOLDED = [...STANDARD_PERMISSIONS, ...PERMISSION_FOR_ROLE.keys()]; const caseless = (word: string) => [...word].map((c) => `[${c.toUpperCase()}${c}]`).join("");