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
13 changes: 2 additions & 11 deletions .github/scripts/gen-inputs-table.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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",
Expand Down
33 changes: 7 additions & 26 deletions .github/scripts/release-pipeline.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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";
Expand Down Expand Up @@ -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++) {
Expand Down
17 changes: 8 additions & 9 deletions src/discovery/discover.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand Down
18 changes: 9 additions & 9 deletions src/flows/settings-write.ts
Original file line number Diff line number Diff line change
@@ -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";
Expand Down
3 changes: 0 additions & 3 deletions src/github/secret-scan.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand Down
14 changes: 5 additions & 9 deletions src/sections/contract/errors.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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 =
| {
Expand Down
8 changes: 1 addition & 7 deletions src/sections/shared/roles.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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("");
Expand Down
Loading