diff --git a/bin/gstack-pregate b/bin/gstack-pregate index c63d17e49..1dd04f857 100755 --- a/bin/gstack-pregate +++ b/bin/gstack-pregate @@ -221,10 +221,11 @@ function cmdClear(root: string, rest: string[]): number { if (!read.file) { process.stderr.write(resultLine('gstack-pregate clear', 'PREGATE_STALE', `${out} is missing or invalid; run gstack-pregate first`) + '\n'); return EXIT.fail; } const runs = rest.flatMap((a, i) => a === '--run' ? [rest[i + 1]!] : []); const runUrl = flag(rest, '--run-url'); - const checked = runs.length || runUrl ? runCheck(root, rest.includes('--allow-repo-commands')) : undefined; - if (checked && 'error' in checked && runs.length) { process.stderr.write(`gstack-pregate clear: ${checked.error}\n`); return EXIT.fail; } + const bundleLane = flag(rest, '--bundle-lane'); + const checked = runs.length || runUrl || bundleLane ? runCheck(root, lane, rest.includes('--allow-repo-commands')) : undefined; + if (checked && 'error' in checked && (runs.length || checked.profiled)) { process.stderr.write(`gstack-pregate clear: ${checked.error}${checked.profiled ? `; the base branch declares a run profile for ${lane}, so it clears only with --run` : ''}\n`); return EXIT.fail; } const evidence = checked && !('error' in checked) ? checked : undefined; - const decision = clearDecision(read.file, lane, { runUrl, runs, bundleLane: flag(rest, '--bundle-lane'), receiptPath: flag(rest, '--receipt'), evidence }, root); + const decision = clearDecision(read.file, lane, { runUrl, runs, bundleLane, receiptPath: flag(rest, '--receipt'), evidence }, root); if ('refused' in decision) { if (decision.refused === 'usage') { process.stderr.write(`gstack-pregate clear: ${decision.message}\n`); return EXIT.usage; } process.stderr.write(`gstack-pregate clear: receipt refused — ${decision.message}; fix: ${decision.fix ?? RESULT_CODES.PREGATE_RECEIPT_INVALID.fix} ${resultCodeSuffix('PREGATE_RECEIPT_INVALID')}\n`); @@ -235,17 +236,18 @@ function cmdClear(root: string, rest: string[]): number { if (/ runs=\S+ profiles=/.test(decision.receipt)) process.stdout.write(`REUSE: accepted ${lane} ${decision.receipt}\n`); if (decision.substitution) process.stdout.write(`PREGATE_RECEIPT_SUBSTITUTED: ${describeSubstitution(decision.substitution)}\n`); process.stdout.write(`PREGATE_CLEARED: ${lane} receipt=${decision.receipt} verdict=${file.verdict}${decision.attested ? ` (attested, not validated: ${lane} has no machine-checkable receipt)` : ''}\n`); + if (checked && 'error' in checked) process.stderr.write(`gstack-pregate clear: run profiles unavailable (${checked.error}); ${lane} was recorded without run verification\n`); return EXIT.ok; } /** The run-evidence inputs for `clear --run`: the base branch's run profiles, this repository on GitHub, and the gate's inventory command (a pin-file command, so only with --allow-repo-commands). */ -function runCheck(root: string, allowRepoCommands: boolean): RunCheck | { error: string } { +function runCheck(root: string, lane: string, allowRepoCommands: boolean): RunCheck | { error: string; profiled?: boolean } { const base = resolveBaseBranch(root); const loaded = loadConfigFromBase(root, base); if (isConfigUnavailable(loaded)) return { error: `the base branch's ${PREGATE_CONFIG_PATH} is unreadable (${loaded.detail}); run profiles come only from the base` }; if (loaded.errors.length) return { error: `the base branch's ${PREGATE_CONFIG_PATH} is invalid: ${loaded.errors.map(e => `${e.path}: ${e.message}`).join('; ')}` }; const repo = /github\.com[:/]([\w.-]+\/[\w.-]+?)(?:\.git)?\/?$/.exec(gitOut(root, ['remote', 'get-url', 'origin']) ?? '')?.[1]; - if (!repo) return { error: 'origin is not a github.com repository; run evidence is read from GitHub Actions' }; + if (!repo) return { error: 'origin is not a github.com repository; run evidence is read from GitHub Actions', profiled: lane === REMOTE_GATE_LANE ? !!loaded.config.remote_gate_runs : !!loaded.config.run_profiles[lane] }; return { repo, deps: ghRunDeps(repo, root), profiles: loaded.config.run_profiles, gateRuns: loaded.config.remote_gate_runs, now: new Date(), inventory: command => { diff --git a/docs/pregate.md b/docs/pregate.md index 3bf588201..8df0fbc7a 100644 --- a/docs/pregate.md +++ b/docs/pregate.md @@ -592,7 +592,10 @@ on prose: a pasted URL is only a pointer the verifier resolves. ``` Profiles are read only from `origin/`, so a pull request can tighten -them but never relax them. Each profile names the workflow file, the events it +them but never relax them. That covers the profile, not the suite it names: the +workflow file a run executed and the inventory command are the branch's own, as +the remote gate's script already is, so a diff to either is reviewed like any +other gate change. Each profile names the workflow file, the events it accepts, every job that must have passed (each exactly once), and the artifact holding the run's `tree.json`. `max_age_hours` (1–168, default 24) bounds how old the run may be, and `os` (`Linux`, `macOS`, `Windows`) requires @@ -613,8 +616,12 @@ once: - `tree.json` names this run, attempt, event and head. It is not a reuse record (a reuse is never evidence). Its tree equals the tree git computes for the run's head commit. -- No newer run of the same workflow on that head, or on pregate.json's own - head, failed, was cancelled or is still running. +- No run of the same workflow on that head, or on pregate.json's own head, + whose newest attempt started after this run was created failed, was + cancelled or is still running (`run_started_at`, so a red re-run of an older + run counts, and re-running this run does not hide a failure in between). +- Its event is `push` or `workflow_dispatch`. A `pull_request` run tests the + merge commit, not the head tree, so no profile may accept it. - The run finished within `max_age_hours`, and on the profile's OS when it names one. - For `pregate.json/remote_gate`: there is exactly one verified run per @@ -632,13 +639,21 @@ verification is named with its own reason (`fork_run`, `event_mismatch`, `run_not_success`, `job_missing`, `artifact_mismatch`, `artifact_reused`, `tree_mismatch`, `newer_run_vetoes`, `run_stale`, `os_mismatch`, `api_error`, …); the clear-level codes are `no_verified_run`, `tree_mismatch` (runs on -different trees), `inventory_failed`, `inventory_empty`, `inventory_uncovered` -and `no_tests`. Accepted, `clear` prints `REUSE: accepted `, and +different trees), `tree_not_stamp_only`, `inventory_failed`, `inventory_empty`, +`inventory_uncovered` and `no_tests`. A wrong run count or a lane with no +profile is a usage error (exit 2), not a REUSE refusal. When the base config or +the GitHub origin cannot be read, `--run` fails, and so do `--run-url` and +`--bundle-lane` for a lane the base profiles; any other lane is recorded as +before, with a warning naming the cause. Accepted, `clear` prints `REUSE: accepted `, and the receipt reads `remote-gate tree= tests= runs=/,… profiles=

,… heads= verified=