proof-of-change 1.3.2 → 1.4.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +26 -1
- package/docs/QUICKSTART.md +1 -1
- package/docs/REFERENCE.md +2 -2
- package/docs/STATUS.md +3 -3
- package/examples/github/pocp.yml +11 -0
- package/package.json +2 -2
- package/src/approvals.js +2 -2
- package/src/cli/shared.js +8 -2
- package/src/commands/gate.js +4 -2
- package/src/commands/trailer.js +9 -1
- package/src/commands/verify.js +72 -6
- package/src/decision.js +7 -2
- package/src/doctor.js +2 -1
- package/src/engine/policy-at.js +2 -4
- package/src/engine/range.js +1 -1
- package/src/engine/verify.js +2 -2
- package/src/explain.js +144 -0
- package/src/finding.js +1 -0
- package/src/init.js +27 -3
- package/src/schema.js +1 -1
- package/src/status-report.js +50 -11
- package/src/store.js +26 -3
package/README.md
CHANGED
|
@@ -39,7 +39,7 @@ npx pocp init --hooks --github
|
|
|
39
39
|
**On another CI** (GitLab, Jenkins, plain shell). In CI: keep your existing test step, and add:
|
|
40
40
|
|
|
41
41
|
```bash
|
|
42
|
-
npm install --prefix "$HOME/.pocp" --no-save --ignore-scripts proof-of-change@1.
|
|
42
|
+
npm install --prefix "$HOME/.pocp" --no-save --ignore-scripts proof-of-change@1.4.0
|
|
43
43
|
node "$HOME/.pocp/node_modules/proof-of-change/bin/pocp.js" verify origin/main..HEAD --require-coverage --rerun
|
|
44
44
|
```
|
|
45
45
|
|
|
@@ -47,6 +47,31 @@ Install the verifier outside the checkout and run it with `node`, as the GitHub
|
|
|
47
47
|
|
|
48
48
|
[docs/QUICKSTART.md](docs/QUICKSTART.md) walks through all of this on a non-JavaScript project.
|
|
49
49
|
|
|
50
|
+
## With Claude Code, Codex, Cursor and pre-commit
|
|
51
|
+
|
|
52
|
+
**Claude Code.** Install the plugin:
|
|
53
|
+
|
|
54
|
+
```text
|
|
55
|
+
/plugin marketplace add harriswekselblatt/pocp
|
|
56
|
+
/plugin install pocp@pocp
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
In a repository that uses POCP, it stops Claude from going around it: no `git commit --no-verify` or `core.hooksPath` change to skip the gate, no force-push over proven commits, and no approving its own test or policy change (adding a `pocp-approve-*` label, `pocp approve`, `--accept-*`). Each refusal tells Claude what to do instead. It also teaches Claude the POCP workflow. It guards against an agent cutting corners, not one set on hiding what it does; CI is still the check.
|
|
60
|
+
|
|
61
|
+
**Codex, Cursor and other agents.** Paste [examples/agent-instructions.md](examples/agent-instructions.md) into the agent's instructions: `AGENTS.md` for Codex, a file in `.cursor/rules/` for Cursor. Instructions guide the agent; the git hooks and CI enforce.
|
|
62
|
+
|
|
63
|
+
**pre-commit.** If you manage hooks with [pre-commit](https://pre-commit.com), use POCP's hooks instead of `pocp init --hooks`:
|
|
64
|
+
|
|
65
|
+
```yaml
|
|
66
|
+
default_install_hook_types: [pre-commit, prepare-commit-msg, post-commit]
|
|
67
|
+
repos:
|
|
68
|
+
- repo: https://github.com/harriswekselblatt/pocp
|
|
69
|
+
rev: v1.4.0
|
|
70
|
+
hooks: [{ id: pocp-gate }, { id: pocp-trailer }, { id: pocp-land }]
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
Then `pre-commit install`. `pocp doctor` recognises them.
|
|
74
|
+
|
|
50
75
|
## Evaluation
|
|
51
76
|
|
|
52
77
|
A benchmark of POCP 1.2.3 on p-map (JS), boltons (Python) and gjson (Go): 180 cases and 1,260 runs, 68 of the cases held out until the scoring script was locked ([full report](eval/campaign-123/README.md)). The protocol was frozen by hash before the runs. The freeze record isn't public, so that order rests on my account. The raw records and the scripts that score them are public in [pocp-eval](https://github.com/harriswekselblatt/pocp-eval).
|
package/docs/QUICKSTART.md
CHANGED
|
@@ -200,7 +200,7 @@ Verify every pull request. verify re-runs each required check itself, on the exa
|
|
|
200
200
|
by the base branch's rules; your existing test step stays as it is:
|
|
201
201
|
|
|
202
202
|
```bash
|
|
203
|
-
npm install --prefix "$HOME/.pocp" --no-save --ignore-scripts proof-of-change@1.
|
|
203
|
+
npm install --prefix "$HOME/.pocp" --no-save --ignore-scripts proof-of-change@1.4.0
|
|
204
204
|
node "$HOME/.pocp/node_modules/proof-of-change/bin/pocp.js" verify origin/main..HEAD --require-coverage --rerun
|
|
205
205
|
```
|
|
206
206
|
|
package/docs/REFERENCE.md
CHANGED
|
@@ -142,7 +142,7 @@ Every repository decides for itself, in `.proof/config.json` (a policy file, so
|
|
|
142
142
|
- **`ci.mode`**: `"github"` (the default: CI checks every pull request) or `"local"` (no CI: the git hooks are the gate). `pocp init --local` sets it; `pocp ci off` disables POCP's workflows on GitHub and sets it, `pocp ci on` enables them and removes it. Only `pocp doctor` and the wording of the gate's and verify's approval steps read it; verify checks the same things in either mode. What local mode gives up: [QUICKSTART](QUICKSTART.md#no-ci-local-mode).
|
|
143
143
|
- **`ci.require_pull_request`, `ci.enforce_admins`, `ci.require_up_to_date`** (all on by default): every change goes through a pull request; admins can't merge past the required checks; and a pull request must include the latest base branch before it merges (GitHub's "require branches to be up to date"). The last one is what makes "the code being merged is the code that was verified" true: without it, a pull request verified against an older base merges into a newer one, and the combination was never checked. The cost: when the base moves, each open pull request needs "Update branch" and a fresh CI run before it can merge. Set any of them to `false` to opt out; doctor then reports it, and turning one off later is a policy loosening.
|
|
144
144
|
- **Merge queues are not supported yet.** GitHub's merge queue and Graphite's run CI on a temporary commit the queue builds, not on the pull request's head. POCP's workflow runs on pull request events and reports on the pull request's head, so a queue that requires `pocp` would wait for a result that never comes. Until POCP supports them, use "require branches to be up to date" instead.
|
|
145
|
-
- **CI definitions are protected.** Changing `.github/workflows/`, `.gitlab-ci.yml`, a `Jenkinsfile` and similar (`ci.files`) needs a packet and, in CI, the same approval as loosening the rules, since an edited workflow could switch POCP off. `ci.files` can protect any other path the same way, such as an evaluation's datasets, graders and results; verify reports those as "protected files changed". Setting `ci.files` replaces the default list, so include the defaults you want to keep (dropping one is reported as a loosening).
|
|
145
|
+
- **CI definitions are protected.** Changing `.github/workflows/`, `.gitlab-ci.yml`, a `Jenkinsfile` and similar (`ci.files`) needs a packet and, in CI, the same approval as loosening the rules, since an edited workflow could switch POCP off. `ci.files` can protect any other path the same way, such as an evaluation's datasets, graders and results; verify reports those as "protected files changed". Setting `ci.files` replaces the default list, so include the defaults you want to keep (dropping one is reported as a loosening). `ci.files_except` (since 1.4) takes globs out of what `ci.files` protects, such as the READMEs in a protected folder (`"eval/**/README.md"`). It never exempts a CI definition (the default list, or any `action.yml`/`action.yaml`), adding an exemption is reported as a loosening, and a pull request is judged only by the exemptions its base already has.
|
|
146
146
|
- **Loosening includes narrowing.** Dropping a glob from a requirement (keeping its command), replacing the test guard's globs, lowering `area_depth`, or widening the environment checks see are loosenings too; until approved, the base's values stay in force.
|
|
147
147
|
|
|
148
148
|
Nothing here assumes GitHub Actions or a test matrix. [`examples/`](../examples/) has GitHub, GitLab and plain-shell versions.
|
|
@@ -169,7 +169,7 @@ Anything that can run a command can use POCP. Two useful places:
|
|
|
169
169
|
- **Giving those approvals:** `pocp approvals` lists every open PR across your repositories whose verify fails only for a maintainer's label, with what each label approves (the reason and the test or CI/policy files, with line counts). `pocp approve owner/repo#12` (also `pocp approvals --approve`) shows every approval the PR waits for, each with its diff, and adds all of them only after you type the PR's number once; it refuses to run without a person at a terminal, has no flag that skips the question, and adds nothing if the PR got new commits while you read it. An agent may list what is waiting; it never approves.
|
|
170
170
|
- **Adopting:** `pocp doctor` checks hooks, policy, the CI workflow and its approval labels, Actions access to a private POCP action, branch protection against `ci.required_checks`, and that the first adoption PR carries only `.proof/` and CI files. It only reads.
|
|
171
171
|
|
|
172
|
-
[`
|
|
172
|
+
The Claude Code plugin ([`plugins/pocp/`](../plugins/pocp/), README "With Claude Code, Codex, Cursor and pre-commit") refuses the commands that go around POCP and teaches the workflow; `pocp check-edit` and `pocp gate --json` work from any harness. [`examples/agent-instructions.md`](../examples/agent-instructions.md) is a block to paste into your agent's instructions file so it works with POCP instead of around it.
|
|
173
173
|
|
|
174
174
|
## Misses and the ratchet
|
|
175
175
|
|
package/docs/STATUS.md
CHANGED
|
@@ -5,9 +5,9 @@ POCP reports its result on a pull request as one commit status, **`pocp`**, on t
|
|
|
5
5
|
| `pocp` | Means | What clears it |
|
|
6
6
|
|---|---|---|
|
|
7
7
|
| ✅ success | verified: the required checks passed on this exact code | nothing; it's done |
|
|
8
|
-
| 🟡 pending: waiting for
|
|
8
|
+
| 🟡 pending: waiting for approval | only approvals are missing (a test change, a policy loosening, protected files, a CI change) | the status names every label needed and, when it fits, the one command that adds them all (`gh pr edit N -R owner/repo --add-label pocp-approve-tests,pocp-approve-policy`); the verify run says in plain words what each approves |
|
|
9
9
|
| 🟡 pending: inconclusive | a check didn't finish: it timed out, was killed or didn't start | re-run the job; or fix the hang or the time limit; or, for a test change, a maintainer adds `pocp-approve-inconclusive` |
|
|
10
|
-
| 🟡 pending: CI
|
|
10
|
+
| 🟡 pending: waiting for approval, CI changed | the pull request changes a CI file, so its own run can't be trusted until a maintainer adds `pocp-approve-workflow` | the same one command: it lists `pocp-approve-workflow` together with every label the run asked for, so nothing turns up one at a time |
|
|
11
11
|
| 🟡 pending: waiting for verify | no finished run for this pull request, its base and its head yet, or a newer run or re-run is still going | wait; after the base branch moves, re-run |
|
|
12
12
|
| 🟡 pending: data incomplete | GitHub's answers about the pull request were incomplete or didn't add up (for example, more files than GitHub lists, or an API error) | re-run the reporter; split a very large pull request |
|
|
13
13
|
| 🟡 pending: shared head | another open pull request has the same head commit | close all but one |
|
|
@@ -78,7 +78,7 @@ Two workflows:
|
|
|
78
78
|
|
|
79
79
|
If your `pocp.yml` was written before the `pocp-run` step existed, add it (`pocp init --github --force` rewrites the example): without it no run counts, and the status stays pending.
|
|
80
80
|
|
|
81
|
-
The status text is
|
|
81
|
+
The status text is built from fixed words only: nothing a pull request writes reaches it. A waiting run's `needs-tests`, `needs-policy` and `needs-inconclusive` steps (from verify's `needs` output, since 1.4) pick which of the fixed label names it lists, with the pull request's number and repository, as `Waiting for approval. Run: gh pr edit N -R owner/repo --add-label …` (or the labels alone when the command doesn't fit GitHub's 140 characters). Those steps choose text only: the state comes from the rules above, and a pull request that lists the wrong labels only names the wrong labels on a status that stays pending. A `pocp.yml` without them gets the generic "Waiting for a maintainer's approval" text. What each label approves, in plain words, is in the run's summary, which the status links to.
|
|
82
82
|
|
|
83
83
|
## Give the reporter its own identity
|
|
84
84
|
|
package/examples/github/pocp.yml
CHANGED
|
@@ -100,6 +100,17 @@ jobs:
|
|
|
100
100
|
- name: approval-coverage
|
|
101
101
|
if: env.APPROVE_COVERAGE != 'false'
|
|
102
102
|
run: 'true'
|
|
103
|
+
# Which labels verify says it waits for (its `needs` output), so the pocp status can name
|
|
104
|
+
# them all, with one command to add them. They change only that text, never the result.
|
|
105
|
+
- name: needs-tests
|
|
106
|
+
if: contains(steps.verify.outputs.needs, 'pocp-approve-tests')
|
|
107
|
+
run: 'true'
|
|
108
|
+
- name: needs-policy
|
|
109
|
+
if: contains(steps.verify.outputs.needs, 'pocp-approve-policy')
|
|
110
|
+
run: 'true'
|
|
111
|
+
- name: needs-inconclusive
|
|
112
|
+
if: contains(steps.verify.outputs.needs, 'pocp-approve-inconclusive')
|
|
113
|
+
run: 'true'
|
|
103
114
|
# Exactly one of these runs. Green needs the verify step's own success; the code output
|
|
104
115
|
# only picks waiting / inconclusive / failed. A missing or unknown code is a failure.
|
|
105
116
|
- name: verified
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "proof-of-change",
|
|
3
|
-
"version": "1.
|
|
3
|
+
"version": "1.4.0",
|
|
4
4
|
"description": "Proof of Change Protocol: risky changes carry proof that was run, tied to the exact code it tested.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"bin": { "pocp": "bin/pocp.js" },
|
|
@@ -11,7 +11,7 @@
|
|
|
11
11
|
"test:unit": "node --test test/unit.test.js test/unit-more.test.js test/git.test.js test/git-object-reads.test.js test/guard-classify.test.js test/runner-env.test.js test/runner-git-env.test.js test/status-report.test.js test/status-report-integrity.test.js test/github-schema.test.js test/ci-up-to-date.test.js test/install-hint.test.js test/workflow-status.test.js"
|
|
12
12
|
},
|
|
13
13
|
"engines": { "node": ">=20" },
|
|
14
|
-
"keywords": ["git", "pre-commit", "proof", "verification", "ai-agents", "ci", "regression"],
|
|
14
|
+
"keywords": ["git", "pre-commit", "proof", "verification", "ai-agents", "ci", "regression", "claude-code", "coding-agents", "codex", "test-integrity", "github-action"],
|
|
15
15
|
"license": "MIT",
|
|
16
16
|
"author": "Harris Wekselblatt",
|
|
17
17
|
"repository": { "type": "git", "url": "git+https://github.com/harriswekselblatt/pocp.git" },
|
package/src/approvals.js
CHANGED
|
@@ -4,7 +4,7 @@ import { summarizeFindings } from './decision.js';
|
|
|
4
4
|
import { withFacts } from './finding.js';
|
|
5
5
|
import { POLICY_FILES } from './policy.js';
|
|
6
6
|
import { PocpBaseError } from './errors.js';
|
|
7
|
-
import { STATUS_CONTEXT, TEXT } from './status-report.js';
|
|
7
|
+
import { isWaitingText, STATUS_CONTEXT, TEXT } from './status-report.js';
|
|
8
8
|
|
|
9
9
|
// `pocp approvals`: every open pull request whose POCP verify fails only because it waits for
|
|
10
10
|
// a maintainer's label, in one list, and a deliberate way for that maintainer to give each one.
|
|
@@ -244,7 +244,7 @@ export async function approvePr({ ref, repo, label, interactive, ask, say }) {
|
|
|
244
244
|
if (!st) {
|
|
245
245
|
// Never "nothing to approve" while the pocp status waits for a maintainer.
|
|
246
246
|
const wait = reporterStatus(r, pr.headRefOid);
|
|
247
|
-
if (wait?.state === 'pending' && wait.description
|
|
247
|
+
if (wait?.state === 'pending' && isWaitingText(wait.description)) throw new ApprovalsError(`${r}#${number}: the "${STATUS_CONTEXT}" status waits for a maintainer's approval, but no verify run on this head says which; open ${wait.target_url || pr.url}`);
|
|
248
248
|
throw new ApprovalsError(`${r}#${number}: POCP verify is not failing on this pull request's head, so there is nothing to approve`);
|
|
249
249
|
}
|
|
250
250
|
if (st.state === 'blocked') throw new ApprovalsError(`${r}#${number}: verify fails for more than an approval (${st.check}); a label would not fix it. Open ${st.check_url || st.url}`);
|
package/src/cli/shared.js
CHANGED
|
@@ -7,6 +7,7 @@ import { createPocp } from '../engine.js';
|
|
|
7
7
|
import { loadHost } from '../host.js';
|
|
8
8
|
import { remedyLines, whoOf } from '../remedies.js';
|
|
9
9
|
import { shortDigest } from '../hash.js';
|
|
10
|
+
import { approvalMarkdown } from '../explain.js';
|
|
10
11
|
|
|
11
12
|
export const list = (v) => (v === undefined ? [] : [].concat(v));
|
|
12
13
|
|
|
@@ -89,12 +90,15 @@ export function formatGate(r) {
|
|
|
89
90
|
}
|
|
90
91
|
|
|
91
92
|
/** On GitHub Actions, add a results table to the job summary and error annotations. */
|
|
92
|
-
export function writeGithubSummary(result, rows, commitProblems, ms, { annotations = true } = {}) {
|
|
93
|
+
export function writeGithubSummary(result, rows, commitProblems, ms, { annotations = true, approvalPlan = null } = {}) {
|
|
93
94
|
const file = process.env.GITHUB_STEP_SUMMARY;
|
|
94
95
|
// Annotations are printed to stdout, so never in --json mode: machine output stays pure JSON.
|
|
95
96
|
if (annotations && process.env.GITHUB_ACTIONS === 'true') {
|
|
97
|
+
// A result that only waits for a label isn't an error: it is said as a warning, and the
|
|
98
|
+
// approval annotation below is what "pocp approvals" reads.
|
|
99
|
+
const level = result.approval?.only ? 'warning' : 'error';
|
|
96
100
|
for (const c of rows) {
|
|
97
|
-
if (!c.ok) process.stdout.write(
|
|
101
|
+
if (!c.ok) process.stdout.write(`::${level} title=POCP::${c.kind === 'net' ? 'net change ' : ''}${c.commit.slice(0, 12)} ${commitProblems(c).join(' | ').replace(/\r?\n/g, ' ')}\n`);
|
|
98
102
|
}
|
|
99
103
|
for (const f of result.rerun_failures || []) process.stdout.write(`::error title=POCP rerun::${f.packet}: ${f.problem}\n`);
|
|
100
104
|
// Machine-readable, for "pocp approvals": what a maintainer's label would clear.
|
|
@@ -116,6 +120,8 @@ export function writeGithubSummary(result, rows, commitProblems, ms, { annotatio
|
|
|
116
120
|
];
|
|
117
121
|
if (result.isolation) lines.push('', result.isolation.secure ? 'Checks ran isolated: each as a fresh unprivileged user.' : 'Checks ran as the job\'s own user (cooperative runner): not the hosted secure profile.');
|
|
118
122
|
if (result.approval?.only) lines.push('', `Waiting only for a maintainer: ${result.approval.needs.map((n) => `\`${n.label}\``).join(' and ')} (see \`pocp approvals\`).`);
|
|
123
|
+
// In plain words: what each label approves, what adding it means, and one command for all.
|
|
124
|
+
if (approvalPlan) lines.push('', `**${result.ok ? 'The `pocp` status also waits for a maintainer' : 'For the maintainer'}**`, '', ...approvalMarkdown(approvalPlan, esc));
|
|
119
125
|
// What to do, who acts first (verify's next steps).
|
|
120
126
|
if (result.next_steps?.length) lines.push('', '**What to do**', '', ...result.next_steps.map((x) => `- **${whoOf(x)}** · \`${x.code}\`: ${esc(x.next)}`));
|
|
121
127
|
const reruns = [...(result.reruns || []), ...(result.net?.reruns || [])];
|
package/src/commands/gate.js
CHANGED
|
@@ -3,8 +3,10 @@ import { EXIT } from '../errors.js';
|
|
|
3
3
|
import { formatGate, localizeCommands, out } from '../cli/shared.js';
|
|
4
4
|
|
|
5
5
|
export async function run({ engine, flags, json }) {
|
|
6
|
-
//
|
|
7
|
-
|
|
6
|
+
// pocp's pre-commit hook sets POCP_GATE_SOURCE=hook, and the pre-commit framework sets
|
|
7
|
+
// PRE_COMMIT=1 for the hooks it runs (.pre-commit-hooks.yaml). Drop pocp's own variable so
|
|
8
|
+
// checks don't inherit it.
|
|
9
|
+
const source = process.env.POCP_GATE_SOURCE === 'hook' || process.env.PRE_COMMIT === '1' ? 'hook' : 'gate';
|
|
8
10
|
delete process.env.POCP_GATE_SOURCE;
|
|
9
11
|
const r = await engine.gate({ prove: Boolean(flags.prove), mode: flags.mode, source });
|
|
10
12
|
if (json) out(true, r);
|
package/src/commands/trailer.js
CHANGED
|
@@ -7,7 +7,15 @@ import { out } from '../cli/shared.js';
|
|
|
7
7
|
export async function run({ engine, json, rest }) {
|
|
8
8
|
if (rest[0]) {
|
|
9
9
|
if (!fs.existsSync(rest[0])) throw new UsageError(`no such message file: ${rest[0]}`);
|
|
10
|
-
|
|
10
|
+
// The commit's source: git's second argument to prepare-commit-msg, or, from the pre-commit
|
|
11
|
+
// framework, which passes only the message file, its PRE_COMMIT_COMMIT_MSG_SOURCE. Merges and
|
|
12
|
+
// squashes get no trailers, as pocp's own hook skips them.
|
|
13
|
+
const source = rest[1] ?? process.env.PRE_COMMIT_COMMIT_MSG_SOURCE ?? undefined;
|
|
14
|
+
if (source === 'merge' || source === 'squash') {
|
|
15
|
+
out(json, { trailers: [] }, null);
|
|
16
|
+
return EXIT.ok;
|
|
17
|
+
}
|
|
18
|
+
const lines = await engine.addTrailersToFile(rest[0], { source });
|
|
11
19
|
out(json, { trailers: lines }, null);
|
|
12
20
|
} else {
|
|
13
21
|
const lines = await engine.trailers();
|
package/src/commands/verify.js
CHANGED
|
@@ -2,19 +2,21 @@
|
|
|
2
2
|
import fs from 'node:fs';
|
|
3
3
|
import path from 'node:path';
|
|
4
4
|
import { COOPERATIVE } from '../runner.js';
|
|
5
|
-
import { dontRewrite, verifyRemedy, whoOf } from '../remedies.js';
|
|
5
|
+
import { dontRewrite, pullRequestRef, verifyRemedy, whoOf } from '../remedies.js';
|
|
6
6
|
import { EXIT } from '../errors.js';
|
|
7
7
|
import { VERIFY_EXIT } from '../approvals.js';
|
|
8
8
|
import { createRevCheckout } from '../workspace.js';
|
|
9
9
|
import { decideVerify } from '../decision.js';
|
|
10
10
|
import { errWrite, evidenceSummary, list, out, writeGithubSummary } from '../cli/shared.js';
|
|
11
11
|
import { failedOutputLines } from '../output-tail.js';
|
|
12
|
-
import { git, resolveRev } from '../git.js';
|
|
12
|
+
import { git, resolveRev, showFile } from '../git.js';
|
|
13
|
+
import { approvalLines, approvalPlan, APPROVE_WORKFLOW_LABEL, explainWorkflow, sortLabels } from '../explain.js';
|
|
14
|
+
import { withDefaults } from '../store.js';
|
|
15
|
+
import { changedWorkflowFiles, githubClient, workflowFiles } from '../status-report.js';
|
|
13
16
|
import { readCiResults } from '../ci-results.js';
|
|
14
17
|
import { shortDigest } from '../hash.js';
|
|
15
18
|
import { UsageError } from '../cli-args.js';
|
|
16
19
|
import { freshnessFacts, labelFreshness } from '../label-freshness.js';
|
|
17
|
-
import { githubClient } from '../status-report.js';
|
|
18
20
|
|
|
19
21
|
// Which label gives each approval (examples/github/pocp.yml).
|
|
20
22
|
const APPROVAL_LABELS = Object.freeze({
|
|
@@ -49,6 +51,50 @@ async function labelVerdicts(engine, flags, headRev, token) {
|
|
|
49
51
|
return verdicts;
|
|
50
52
|
}
|
|
51
53
|
|
|
54
|
+
/**
|
|
55
|
+
* The CI files a range changes that the trusted reporter (pocp-status.yml) holds for
|
|
56
|
+
* pocp-approve-workflow, by the reporter's own rule (status-report.js): the base's ci.files and
|
|
57
|
+
* ci.files_except, CI definitions always included, over the pull request's diff from its merge
|
|
58
|
+
* base. Empty in local mode, outside a range, or when the base runs no reporter.
|
|
59
|
+
*/
|
|
60
|
+
export function workflowLabelFiles(root, range, cfg) {
|
|
61
|
+
if (cfg.ci?.mode === 'local' || !range || !range.includes('..')) return [];
|
|
62
|
+
const [b, h] = range.split(/\.\.\.?/);
|
|
63
|
+
const base = git(root, ['rev-parse', '--verify', '--quiet', `${b}^{commit}`], { allowFail: true });
|
|
64
|
+
const head = git(root, ['rev-parse', '--verify', '--quiet', `${h || 'HEAD'}^{commit}`], { allowFail: true });
|
|
65
|
+
if (!base || !head) return [];
|
|
66
|
+
if (!git(root, ['grep', '-l', '-F', 'status-report', base, '--', '.github/workflows'], { allowFail: true })) return [];
|
|
67
|
+
let baseConfig = null;
|
|
68
|
+
try {
|
|
69
|
+
const text = showFile(root, base, '.proof/config.json');
|
|
70
|
+
baseConfig = text === null ? null : withDefaults(JSON.parse(text));
|
|
71
|
+
} catch { /* an unreadable base config: the defaults still apply */ }
|
|
72
|
+
const mb = git(root, ['merge-base', base, head], { allowFail: true }) || base;
|
|
73
|
+
const files = (git(root, ['diff', '--name-only', '--no-renames', '-z', mb, head], { trim: false, allowFail: true }) || '').split('\0').filter(Boolean);
|
|
74
|
+
return changedWorkflowFiles(files.map((filename) => ({ filename })), workflowFiles(baseConfig), baseConfig?.ci?.files_except || []);
|
|
75
|
+
}
|
|
76
|
+
|
|
77
|
+
/** verify's first line: a result that waits only for labels says so, so it doesn't read as a failure. */
|
|
78
|
+
const headline = (result) => (result.ok ? 'verified' : decideVerify(result)?.only ? 'NOT verified yet: waiting for a maintainer\'s approval' : 'NOT verified');
|
|
79
|
+
|
|
80
|
+
/** The labels on the pull request when this run's event fired (GitHub's event payload), or []. */
|
|
81
|
+
function eventLabels() {
|
|
82
|
+
try {
|
|
83
|
+
const ev = JSON.parse(fs.readFileSync(process.env.GITHUB_EVENT_PATH, 'utf8'));
|
|
84
|
+
return (ev.pull_request?.labels || []).map((l) => l.name);
|
|
85
|
+
} catch {
|
|
86
|
+
return [];
|
|
87
|
+
}
|
|
88
|
+
}
|
|
89
|
+
|
|
90
|
+
/** The pull request verify is checking: { number, repository }, from flags or GitHub's environment. */
|
|
91
|
+
function pullRequestOf(flags) {
|
|
92
|
+
const ref = pullRequestRef();
|
|
93
|
+
const number = Number(flags['pull-request']) || Number(ref?.split('#')[1]) || null;
|
|
94
|
+
const repository = flags.repo || process.env.GITHUB_REPOSITORY || null;
|
|
95
|
+
return { number, repository };
|
|
96
|
+
}
|
|
97
|
+
|
|
52
98
|
export async function run({ engine, flags, isolated, json, rest }) {
|
|
53
99
|
const started = Date.now();
|
|
54
100
|
// The token for --label-freshness: read, then taken out of this process's environment before
|
|
@@ -154,7 +200,7 @@ export async function run({ engine, flags, isolated, json, rest }) {
|
|
|
154
200
|
rows = [...result.commits, ...(result.net ? [result.net] : [])];
|
|
155
201
|
if (!result.ok) steps = nextSteps([...rows, { findings: rangeFindings(result) }]);
|
|
156
202
|
human = [
|
|
157
|
-
`${result
|
|
203
|
+
`${headline(result)}: ${result.commits.length} commit(s) in ${result.range} · ${Date.now() - started}ms`,
|
|
158
204
|
...result.commits.map((c) => ` ${c.ok ? 'ok ' : 'BAD'} ${c.commit.slice(0, 12)}${c.ok ? '' : `: ${commitProblems(c).join(' | ')}`}`),
|
|
159
205
|
...(result.net ? [` ${result.net.ok ? 'ok ' : 'BAD'} net change ${result.net.base.slice(0, 12)}..${result.net.commit.slice(0, 12)}${result.net.ok ? '' : `: ${commitProblems(result.net).join(' | ')}`}`] : []),
|
|
160
206
|
...(result.notes || []).map((n) => ` note: ${n}`),
|
|
@@ -168,7 +214,7 @@ export async function run({ engine, flags, isolated, json, rest }) {
|
|
|
168
214
|
rows = [result];
|
|
169
215
|
if (!result.ok) steps = nextSteps([result]);
|
|
170
216
|
human = [
|
|
171
|
-
`${result
|
|
217
|
+
`${headline(result)}: ${result.commit.slice(0, 12)} subject ${shortDigest(result.subject)} · ${Date.now() - started}ms`,
|
|
172
218
|
...result.notes.map((n) => ` note: ${n}`),
|
|
173
219
|
...result.warnings.map((w) => ` warning: ${w}`),
|
|
174
220
|
...result.packets.map((p) => ` ${p.id}: ${p.ok ? 'ok' : p.problems.join('; ')}${p.evidence && Object.keys(p.evidence).length ? ` · evidence: ${evidenceSummary(p.evidence)}` : ''}`),
|
|
@@ -183,8 +229,28 @@ export async function run({ engine, flags, isolated, json, rest }) {
|
|
|
183
229
|
if (verdicts) result.label_freshness = Object.fromEntries(Object.entries(verdicts).map(([l, v]) => [l, v.ok ? { ok: true, how: v.how } : v]));
|
|
184
230
|
// One decision for the library and the CLI, from typed findings (src/decision.js).
|
|
185
231
|
if (!result.ok) result.approval = decideVerify(result);
|
|
232
|
+
// What a maintainer approves, in plain words, and the one command that adds every label
|
|
233
|
+
// (explain.js). Words only: the decision above is already made.
|
|
234
|
+
const local = engine.config().ci?.mode === 'local';
|
|
235
|
+
const wfFiles = workflowLabelFiles(engine.root, rest[0], engine.config());
|
|
236
|
+
const waitingOnly = !result.ok && result.approval?.only;
|
|
237
|
+
const wfNeed = wfFiles.length && (result.ok || waitingOnly) && !eventLabels().includes(APPROVE_WORKFLOW_LABEL) ? [{ label: APPROVE_WORKFLOW_LABEL, files: wfFiles, plain: [explainWorkflow(wfFiles)] }] : [];
|
|
238
|
+
if (wfNeed.length) result.workflow_approval = { label: APPROVE_WORKFLOW_LABEL, files: wfFiles };
|
|
239
|
+
const pr = pullRequestOf(flags);
|
|
240
|
+
const plan = local ? null : approvalPlan(waitingOnly ? result.approval.needs : [], { extra: wfNeed, number: pr.number, repository: pr.repository });
|
|
241
|
+
const block = approvalLines(plan, ' ');
|
|
242
|
+
if (plan) result.approval_request = plan;
|
|
243
|
+
if (block.length) human += `\n ${result.ok ? 'the pocp status also waits for a maintainer (CI files changed):' : "waiting only for a maintainer's approval; nothing else is wrong:"}\n${block.join('\n')}`;
|
|
244
|
+
const labelsNeeded = sortLabels([...(waitingOnly ? result.approval.needs.map((n) => n.label) : []), ...wfNeed.map((n) => n.label)]);
|
|
245
|
+
if (labelsNeeded.length && !local) result.labels_needed = labelsNeeded;
|
|
246
|
+
// For the trusted reporter's pending text (needs-* steps in pocp.yml); never its result.
|
|
247
|
+
if (process.env.GITHUB_OUTPUT && result.labels_needed) {
|
|
248
|
+
try {
|
|
249
|
+
fs.appendFileSync(process.env.GITHUB_OUTPUT, `needs=${result.labels_needed.join(',')}\n`);
|
|
250
|
+
} catch { /* the pending text falls back to the generic wait */ }
|
|
251
|
+
}
|
|
186
252
|
if (steps.length) result.next_steps = steps;
|
|
187
|
-
writeGithubSummary(result, rows, commitProblems, Date.now() - started, { annotations: !json });
|
|
253
|
+
writeGithubSummary(result, rows, commitProblems, Date.now() - started, { annotations: !json, approvalPlan: plan });
|
|
188
254
|
out(json, result, human);
|
|
189
255
|
if (result.ok) return EXIT.ok;
|
|
190
256
|
// --exit-detail: 4 when only a maintainer's approval is missing, 5 when something didn't
|
package/src/decision.js
CHANGED
|
@@ -2,6 +2,7 @@
|
|
|
2
2
|
// The library and the CLI both use decideVerify, so they classify a result the same way, and
|
|
3
3
|
// no remedy or detail text can change the outcome.
|
|
4
4
|
import { factsOf } from './finding.js';
|
|
5
|
+
import { explainFinding } from './explain.js';
|
|
5
6
|
import { APPROVE_INCONCLUSIVE_LABEL, APPROVE_POLICY_LABEL, APPROVE_TESTS_LABEL } from './remedies.js';
|
|
6
7
|
|
|
7
8
|
/** The label a maintainer adds for each kind of approval. */
|
|
@@ -34,7 +35,8 @@ export function resolutionOf(finding) {
|
|
|
34
35
|
|
|
35
36
|
/**
|
|
36
37
|
* Summarize blocking findings and re-run failures.
|
|
37
|
-
* Returns { only, needs: [{ label, kind, reasons, files }], outcome, unfinished_reruns }.
|
|
38
|
+
* Returns { only, needs: [{ label, kind, reasons, files, plain }], outcome, unfinished_reruns }.
|
|
39
|
+
* `plain`: what the label approves, in words for a maintainer who doesn't read code.
|
|
38
40
|
* The outcome follows one precedence: 'failed' when anything needs a fix (or nothing explains
|
|
39
41
|
* the failure), else 'inconclusive' when anything didn't finish or needs an inconclusive
|
|
40
42
|
* approval, else 'waiting' for the listed approvals. An approval never hides a failure, and an
|
|
@@ -55,8 +57,11 @@ export function summarizeFindings(findings = [], rerunFailures = []) {
|
|
|
55
57
|
continue;
|
|
56
58
|
}
|
|
57
59
|
const label = APPROVAL_LABEL[r.approval];
|
|
58
|
-
const n = needs.get(label) || { label, kind: r.approval, reasons: [], files: [] };
|
|
60
|
+
const n = needs.get(label) || { label, kind: r.approval, reasons: [], files: [], plain: [] };
|
|
59
61
|
if (!n.reasons.includes(f.detail)) n.reasons.push(f.detail);
|
|
62
|
+
// Words for the maintainer (explain.js); they never change the decision.
|
|
63
|
+
const plain = explainFinding(f);
|
|
64
|
+
if (plain && !n.plain.includes(plain)) n.plain.push(plain);
|
|
60
65
|
for (const file of r.files) if (!n.files.includes(file)) n.files.push(file);
|
|
61
66
|
needs.set(label, n);
|
|
62
67
|
}
|
package/src/doctor.js
CHANGED
|
@@ -156,7 +156,8 @@ export async function runDoctor(engine, { base, offline = false } = {}) {
|
|
|
156
156
|
: 'the existing hook hands over to another program (or exits) before reaching pocp, so the gate is silently off',
|
|
157
157
|
fix: `pocp hooks install (it moves the original hook to <hook>.pre-pocp and chains it: the original runs first, then pocp)`,
|
|
158
158
|
});
|
|
159
|
-
} else if (h.problems.length) add({ id: 'hooks', status: 'problem', what: h.problems.join('; '), why: 'git skips a hook that is missing or not executable', fix: 'pocp hooks install' });
|
|
159
|
+
} else if (h.problems.length) add({ id: 'hooks', status: 'problem', what: h.problems.join('; '), why: 'git skips a hook that is missing or not executable', fix: h.managedBy === 'pre-commit' ? 'add the missing pocp hook ids to .pre-commit-config.yaml, then pre-commit install' : 'pocp hooks install' });
|
|
160
|
+
else if (h.managedBy === 'pre-commit') add({ id: 'hooks', status: 'ok', what: 'hooks run through the pre-commit framework (pocp-gate, pocp-trailer, pocp-land), which installs pocp for them' });
|
|
160
161
|
else {
|
|
161
162
|
// The order the hooks use: POCP_BIN, the project's own copy, PATH, then the pocp that installed them.
|
|
162
163
|
const local = fs.existsSync(path.join(root, 'node_modules', '.bin', 'pocp')) ? 'node_modules/.bin/pocp' : '';
|
package/src/engine/policy-at.js
CHANGED
|
@@ -4,8 +4,7 @@
|
|
|
4
4
|
// files a change touched (changedCiFiles).
|
|
5
5
|
import fs from 'node:fs';
|
|
6
6
|
import * as g from '../git.js';
|
|
7
|
-
import { rulesWithDefaults, validateConfig, withDefaults } from '../store.js';
|
|
8
|
-
import { matchGlob } from '../glob.js';
|
|
7
|
+
import { ciProtects, rulesWithDefaults, validateConfig, withDefaults } from '../store.js';
|
|
9
8
|
import { validateRules } from '../rules.js';
|
|
10
9
|
import { blockingRule, combinePolicy, EXCEPTIONS_FILE, POLICY_FILES, policyLoosenings } from '../policy.js';
|
|
11
10
|
import { policyKeyWarnings } from '../schema.js';
|
|
@@ -136,9 +135,8 @@ export function createPolicyAt({ root }) {
|
|
|
136
135
|
|
|
137
136
|
/** CI definition files a change touched (ci.files globs). */
|
|
138
137
|
function changedCiFiles(changes, cfg) {
|
|
139
|
-
const globs = cfg.ci?.files || [];
|
|
140
138
|
const touched = new Set();
|
|
141
|
-
for (const c of changes) for (const p of [c.path, c.oldPath]) if (p &&
|
|
139
|
+
for (const c of changes) for (const p of [c.path, c.oldPath]) if (p && ciProtects(p, cfg.ci)) touched.add(p);
|
|
142
140
|
return [...touched].sort();
|
|
143
141
|
}
|
|
144
142
|
|
package/src/engine/range.js
CHANGED
|
@@ -258,7 +258,7 @@ export function createRange({ opts, root, emit, hostName, hostRequirements, host
|
|
|
258
258
|
? 'no rule requires a check covering these files, so nothing independent can run the old tests (add a requirement covering them)'
|
|
259
259
|
: `the mechanical check did not pass: ${r.summary}`;
|
|
260
260
|
const detail = `existing tests or test setup changed (${guard.files.join(', ')}) in the pull request's net change ${span}; ${why}. Re-run with --accept-test-change once a person approves`;
|
|
261
|
-
const testApproval = { approval: 'tests', files: guard.files };
|
|
261
|
+
const testApproval = { approval: 'tests', files: guard.files, ...(r?.result ? { guard: r.result } : {}) };
|
|
262
262
|
const netUnfinished = Boolean(guardRerun && r && !r.passed && r.result?.unfinished);
|
|
263
263
|
if (guard.mode === 'block' && !independent && netUnfinished) {
|
|
264
264
|
if (!options.acceptInconclusive) finding('test_inconclusive', `existing tests or test setup changed (${guard.files.join(', ')}) in the pull request's net change ${span} and the check didn't finish: ${r.summary}. Re-run verify, or re-run with --accept-inconclusive once a person approves`, { files: guard.files });
|
package/src/engine/verify.js
CHANGED
|
@@ -376,7 +376,7 @@ export function createVerify({ opts, root, emit, hostName, hostRequirements, hos
|
|
|
376
376
|
// Attest mode with no packet: nothing can carry a sign-off, so a rules check that didn't
|
|
377
377
|
// pass needs the approval, as on a range's net change.
|
|
378
378
|
if (commitGuard.mode === 'attest' && rulesRun && !(rulesRun.passed && rulesRun.checks_from !== 'packet') && !acceptTestChange) {
|
|
379
|
-
commitFinding('test_change', `existing tests or test setup changed (${notInJobs.join(', ')}); ${rulesRun.checks_from === 'packet' ? 'no rule requires a check covering these files, so nothing independent can run the old tests (add a requirement covering them)' : `the mechanical check did not pass: ${rulesRun.summary}`}. Re-run with --accept-test-change once a person approves`, { approval: 'tests', files: notInJobs });
|
|
379
|
+
commitFinding('test_change', `existing tests or test setup changed (${notInJobs.join(', ')}); ${rulesRun.checks_from === 'packet' ? 'no rule requires a check covering these files, so nothing independent can run the old tests (add a requirement covering them)' : `the mechanical check did not pass: ${rulesRun.summary}`}. Re-run with --accept-test-change once a person approves`, { approval: 'tests', files: notInJobs, ...(rulesRun.result ? { guard: rulesRun.result } : {}) });
|
|
380
380
|
}
|
|
381
381
|
if (commitGuard.mode !== 'block') return;
|
|
382
382
|
// Independent: re-run here or signed by a trusted key, with checks the rules chose.
|
|
@@ -409,7 +409,7 @@ export function createVerify({ opts, root, emit, hostName, hostRequirements, hos
|
|
|
409
409
|
: results.some((r) => r.passed)
|
|
410
410
|
? ['the mechanical check passed only locally (re-run verify with --rerun to check it here)', 'local_only']
|
|
411
411
|
: ['no mechanical check covers them'];
|
|
412
|
-
commitFinding('test_change', `existing tests or test setup changed (${toReview.join(', ')}); ${why}. Re-run with --accept-test-change once a person approves`, { files: toReview, ...(variant ? { variant } : { approval: 'tests' }) });
|
|
412
|
+
commitFinding('test_change', `existing tests or test setup changed (${toReview.join(', ')}); ${why}. Re-run with --accept-test-change once a person approves`, { files: toReview, ...(variant ? { variant } : { approval: 'tests' }), ...(failed?.result ? { guard: failed.result } : {}) });
|
|
413
413
|
}
|
|
414
414
|
|
|
415
415
|
return { verify, findingSink, reportPolicy };
|
package/src/explain.js
ADDED
|
@@ -0,0 +1,144 @@
|
|
|
1
|
+
// Every hold, said in plain words for a maintainer who doesn't read code: what changed, in
|
|
2
|
+
// terms of behaviour, what the approval label means, and the one command that adds every
|
|
3
|
+
// label a pull request waits for. Built from typed facts only (finding.js), never from a
|
|
4
|
+
// finding's detail text, and never used to decide anything: decision.js decides.
|
|
5
|
+
import { factsOf } from './finding.js';
|
|
6
|
+
import { DEFAULT_CI_FILES } from './store.js';
|
|
7
|
+
import { matchGlob } from './glob.js';
|
|
8
|
+
|
|
9
|
+
export const APPROVE_WORKFLOW_LABEL = 'pocp-approve-workflow';
|
|
10
|
+
|
|
11
|
+
/** What adding each label says, in the maintainer's words. None of them says "I reviewed the code". */
|
|
12
|
+
export const LABEL_MEANS = Object.freeze({
|
|
13
|
+
'pocp-approve-tests': 'I accept this change in what the code does, or in what its tests check',
|
|
14
|
+
'pocp-approve-policy': 'I accept this change to the rules or protected files',
|
|
15
|
+
'pocp-approve-inconclusive': "I accept merging without that check's result",
|
|
16
|
+
'pocp-approve-coverage': 'I accept these files going in without proof',
|
|
17
|
+
[APPROVE_WORKFLOW_LABEL]: 'I accept this change to the CI workflow',
|
|
18
|
+
});
|
|
19
|
+
|
|
20
|
+
// The order labels are listed in, so the same pull request always gets the same command.
|
|
21
|
+
const ORDER = ['pocp-approve-tests', 'pocp-approve-policy', 'pocp-approve-inconclusive', 'pocp-approve-coverage', APPROVE_WORKFLOW_LABEL];
|
|
22
|
+
const rank = (label) => (ORDER.includes(label) ? ORDER.indexOf(label) : ORDER.length);
|
|
23
|
+
export const sortLabels = (labels) => [...new Set(labels)].sort((a, b) => rank(a) - rank(b) || a.localeCompare(b));
|
|
24
|
+
|
|
25
|
+
const quoteList = (xs, n = 3) => {
|
|
26
|
+
const shown = xs.slice(0, n).map((x) => `"${x}"`);
|
|
27
|
+
const more = xs.length > n ? ` and ${xs.length - n} more` : '';
|
|
28
|
+
return shown.length > 1 ? `${shown.slice(0, -1).join(', ')} and ${shown.at(-1)}${more}` : `${shown[0]}${more}`;
|
|
29
|
+
};
|
|
30
|
+
const fileList = (xs, n = 4) => (xs.length > n ? `${xs.slice(0, n).join(', ')} and ${xs.length - n} more` : xs.join(', '));
|
|
31
|
+
const plural = (n, one, many) => (n === 1 ? one : many);
|
|
32
|
+
|
|
33
|
+
/** The failing test names a guard result recorded for the old tests on the new code. */
|
|
34
|
+
function failingOldTests(guard) {
|
|
35
|
+
const names = guard?.adjudication?.failing_on_new_code || (guard?.old_tests?.runs || []).filter((r) => !r.passed).flatMap((r) => r.failed_tests || []);
|
|
36
|
+
return [...new Set(names)];
|
|
37
|
+
}
|
|
38
|
+
|
|
39
|
+
/** One plain sentence for what the test guard found, from its result (guard-check.js), or null. */
|
|
40
|
+
export function explainGuard(guard, files = []) {
|
|
41
|
+
if (!guard) return null;
|
|
42
|
+
const where = files.length ? ` (${fileList(files)})` : '';
|
|
43
|
+
switch (guard.verdict) {
|
|
44
|
+
case 'behavior-changed': {
|
|
45
|
+
const names = failingOldTests(guard);
|
|
46
|
+
const who = names.length ? `The old ${plural(names.length, 'test', 'tests')} ${quoteList(names)} now ${plural(names.length, 'fails', 'fail')}` : 'Old tests that passed before now fail';
|
|
47
|
+
return `${who} on the new code: the change makes the code do something different from what ${plural(names.length, 'that test', 'those tests')} checked, and the edited tests accept the new behaviour. Approve only if that change in behaviour is intended.`;
|
|
48
|
+
}
|
|
49
|
+
case 'detection-dropped': {
|
|
50
|
+
const lost = guard.detection?.lost || [];
|
|
51
|
+
const ex = lost[0];
|
|
52
|
+
const example = ex ? ` (for example in ${ex.file} line ${ex.line}, changing \`${ex.before}\` to \`${ex.after}\`)` : '';
|
|
53
|
+
const n = lost.length || 1;
|
|
54
|
+
return `POCP planted ${plural(n, 'a small bug', `${n} small bugs`)} in the code that the old tests caught and the edited tests${where} miss${example}: the tests now check less than before. Approve only if checking less there is intended.`;
|
|
55
|
+
}
|
|
56
|
+
case 'baseline-red':
|
|
57
|
+
return `Existing tests were edited${where}, and the old tests were already failing before this change, so POCP can't tell whether the change altered what the code does. Approve only if you accept the edited tests as they are.`;
|
|
58
|
+
case 'needs-review': {
|
|
59
|
+
const why = (guard.structural?.reasons || []).slice(0, 2).map((r) => `${r.file}: ${r.why}`).join('; ');
|
|
60
|
+
return `Tests or test setup changed${where}. The old tests still pass on the new code, but fast mode plants no bugs, so POCP can't show the edited tests still catch what they caught${why ? ` (${why})` : ''}. Approve only if you accept the test edits.`;
|
|
61
|
+
}
|
|
62
|
+
default:
|
|
63
|
+
return null;
|
|
64
|
+
}
|
|
65
|
+
}
|
|
66
|
+
|
|
67
|
+
/** Plain words for one blocking finding a label resolves (decision.js resolutionOf), or null. */
|
|
68
|
+
export function explainFinding(finding) {
|
|
69
|
+
const facts = factsOf(finding);
|
|
70
|
+
const files = facts.files || [];
|
|
71
|
+
switch (finding.code) {
|
|
72
|
+
case 'test_change':
|
|
73
|
+
return explainGuard(facts.guard, files)
|
|
74
|
+
|| `Existing tests or test setup were edited (${fileList(files)}) and POCP couldn't check on its own that they still catch what they caught. Approve only if you accept the test edits.`;
|
|
75
|
+
case 'test_inconclusive':
|
|
76
|
+
return `A check on the edited tests (${fileList(files)}) didn't finish (it timed out or was stopped), so nothing is known about them yet. Re-run the job first; approve only if it keeps happening and you accept not knowing.`;
|
|
77
|
+
case 'ci_config_changed': {
|
|
78
|
+
const ci = files.filter((f) => DEFAULT_CI_FILES.some((gl) => matchGlob(f, gl)));
|
|
79
|
+
return ci.length
|
|
80
|
+
? `The CI setup that checks pull requests changed (${fileList(ci)}). Approve only if you meant to change how CI checks code.`
|
|
81
|
+
: `Files this repository protects changed (${fileList(files)}): they can change its results, for example its evaluation. Approve only if that change is intended.`;
|
|
82
|
+
}
|
|
83
|
+
case 'policy_loosened': {
|
|
84
|
+
const what = String(finding.detail || '').replace(/^policy loosened without approval: /, '').replace(/\s*[(;]\s*re-run with [^)]*\)?\s*$/, '').split('; ').filter(Boolean);
|
|
85
|
+
return `This change loosens POCP's own rules (${what.length > 3 ? `${what.slice(0, 3).join('; ')}; and ${what.length - 3} more` : what.join('; ')}), so later changes are checked less strictly. Approve only if you want that.`;
|
|
86
|
+
}
|
|
87
|
+
default:
|
|
88
|
+
return null;
|
|
89
|
+
}
|
|
90
|
+
}
|
|
91
|
+
|
|
92
|
+
/** The plain line for the CI workflow label (status-report.js decides when it is needed). */
|
|
93
|
+
export const explainWorkflow = (files) => `This pull request changes CI files that produce POCP's own result (${fileList(files)}), so that result can't be trusted until you accept the new workflow. Approve only if you meant to change CI.`;
|
|
94
|
+
|
|
95
|
+
/**
|
|
96
|
+
* The one command that adds every label in `labels` to a pull request. `number` and
|
|
97
|
+
* `repository` ("owner/name") may be unknown: the command then says where they go.
|
|
98
|
+
*/
|
|
99
|
+
export function addLabelsCommand(labels, { number = null, repository = null } = {}) {
|
|
100
|
+
if (!labels.length) return null;
|
|
101
|
+
return `gh pr edit ${number || '<number>'}${repository ? ` -R ${repository}` : ''} --add-label ${sortLabels(labels).join(',')}`;
|
|
102
|
+
}
|
|
103
|
+
|
|
104
|
+
/**
|
|
105
|
+
* What a maintainer is asked, for a verify that waits for labels: per label, what changed and
|
|
106
|
+
* what the label means, then the one command. `needs` is decision.js's list (label, plain);
|
|
107
|
+
* `extra` adds labels verify can't see itself (the reporter's pocp-approve-workflow).
|
|
108
|
+
* Returns { items: [{ label, plain, means }], command } or null when nothing is asked.
|
|
109
|
+
*/
|
|
110
|
+
export function approvalPlan(needs = [], { extra = [], number = null, repository = null } = {}) {
|
|
111
|
+
const all = [...needs, ...extra].sort((a, b) => rank(a.label) - rank(b.label));
|
|
112
|
+
if (!all.length) return null;
|
|
113
|
+
return {
|
|
114
|
+
items: all.map((n) => ({ label: n.label, plain: n.plain || [], means: LABEL_MEANS[n.label] || null })),
|
|
115
|
+
command: addLabelsCommand(all.map((n) => n.label), { number, repository }),
|
|
116
|
+
};
|
|
117
|
+
}
|
|
118
|
+
|
|
119
|
+
const meansLine = (means) => `Adding it means: "${means}". It does not mean "I reviewed the code".`;
|
|
120
|
+
const commandIntro = (n) => `Add ${plural(n, 'it', `all ${n}`)} with one command:`;
|
|
121
|
+
|
|
122
|
+
/** approvalPlan as text lines for verify's output. */
|
|
123
|
+
export function approvalLines(plan, indent = ' ') {
|
|
124
|
+
if (!plan) return [];
|
|
125
|
+
const lines = [];
|
|
126
|
+
for (const it of plan.items) {
|
|
127
|
+
lines.push(`${indent}${it.label}:`);
|
|
128
|
+
for (const p of it.plain) lines.push(`${indent} ${p}`);
|
|
129
|
+
if (it.means) lines.push(`${indent} ${meansLine(it.means)}`);
|
|
130
|
+
}
|
|
131
|
+
lines.push(`${indent}${commandIntro(plan.items.length)} ${plan.command}`);
|
|
132
|
+
return lines;
|
|
133
|
+
}
|
|
134
|
+
|
|
135
|
+
/** approvalPlan as Markdown for the job summary (`esc` escapes table-unsafe text). */
|
|
136
|
+
export function approvalMarkdown(plan, esc = (x) => x) {
|
|
137
|
+
if (!plan) return [];
|
|
138
|
+
const lines = [];
|
|
139
|
+
for (const it of plan.items) {
|
|
140
|
+
lines.push(`- \`${it.label}\`${it.plain.length ? `: ${esc(it.plain.join(' '))}` : ''}${it.means ? ` ${esc(meansLine(it.means))}` : ''}`);
|
|
141
|
+
}
|
|
142
|
+
lines.push('', commandIntro(plan.items.length), '', '```', plan.command, '```');
|
|
143
|
+
return lines;
|
|
144
|
+
}
|
package/src/finding.js
CHANGED
|
@@ -7,6 +7,7 @@
|
|
|
7
7
|
// files the exact files it is about (repository paths)
|
|
8
8
|
// variant which case of a code it is, where the remedy differs (e.g. 'local_only')
|
|
9
9
|
// errorCode the code of the error that caused a problem (e.g. 'clean_mode_refused')
|
|
10
|
+
// guard the test guard's result behind a test_change (guard-check.js), for plain words (explain.js)
|
|
10
11
|
//
|
|
11
12
|
// They are kept under a symbol, so they are not part of the JSON output or of a result's
|
|
12
13
|
// enumerable keys.
|
package/src/init.js
CHANGED
|
@@ -384,6 +384,9 @@ export function hooksHealth(cwd) {
|
|
|
384
384
|
const dir = hooksDir(root);
|
|
385
385
|
const hooks = {};
|
|
386
386
|
const problems = [];
|
|
387
|
+
const preCommitConfig = path.join(root, '.pre-commit-config.yaml');
|
|
388
|
+
const pcConfig = fs.existsSync(preCommitConfig) ? fs.readFileSync(preCommitConfig, 'utf8') : '';
|
|
389
|
+
let managedBy = null;
|
|
387
390
|
for (const name of Object.keys(HOOKS)) {
|
|
388
391
|
const file = path.join(dir, name);
|
|
389
392
|
if (!fs.existsSync(file)) {
|
|
@@ -391,6 +394,19 @@ export function hooksHealth(cwd) {
|
|
|
391
394
|
continue;
|
|
392
395
|
}
|
|
393
396
|
const text = fs.readFileSync(file, 'utf8');
|
|
397
|
+
// Installed by the pre-commit framework (`pre-commit install`), which runs pocp from the
|
|
398
|
+
// hook ids in .pre-commit-hooks.yaml instead of pocp's own block.
|
|
399
|
+
if (text.includes(PRE_COMMIT_MARK)) {
|
|
400
|
+
const id = PRE_COMMIT_HOOK_IDS[name];
|
|
401
|
+
if (new RegExp(`\\bid:\\s*["']?${id}\\b`).test(pcConfig)) {
|
|
402
|
+
hooks[name] = 'ok (pre-commit)';
|
|
403
|
+
managedBy = 'pre-commit';
|
|
404
|
+
} else {
|
|
405
|
+
hooks[name] = 'no pocp block';
|
|
406
|
+
problems.push(`${name}: run by the pre-commit framework, but .pre-commit-config.yaml has no "${id}" hook (add it, then run pre-commit install)`);
|
|
407
|
+
}
|
|
408
|
+
continue;
|
|
409
|
+
}
|
|
394
410
|
const before = text.includes(CHAIN_MARK) ? '' : text.slice(0, Math.max(0, text.indexOf(HOOK_BEGIN)));
|
|
395
411
|
const interp = before && nonShellInterpreter(before);
|
|
396
412
|
const unreachable = before && !interp && unreachableReason(before);
|
|
@@ -409,11 +425,19 @@ export function hooksHealth(cwd) {
|
|
|
409
425
|
}
|
|
410
426
|
const installed = Object.values(hooks).some((v) => v !== 'missing' && v !== 'no pocp block');
|
|
411
427
|
if (installed) {
|
|
412
|
-
for (const [name, st] of Object.entries(hooks))
|
|
428
|
+
for (const [name, st] of Object.entries(hooks)) {
|
|
429
|
+
if (st === 'missing' && managedBy === 'pre-commit') problems.push(`${name}: missing (add ${name} to default_install_hook_types in .pre-commit-config.yaml, then run pre-commit install)`);
|
|
430
|
+
else if ((st === 'missing' || st === 'no pocp block') && !problems.some((p) => p.startsWith(`${name}:`))) problems.push(`${name}: ${st}`);
|
|
431
|
+
}
|
|
413
432
|
}
|
|
414
|
-
return { dir, hooks, installed, problems };
|
|
433
|
+
return { dir, hooks, installed, problems, managedBy };
|
|
415
434
|
}
|
|
416
435
|
|
|
436
|
+
// pre-commit (https://pre-commit.com) writes this line into every hook it installs.
|
|
437
|
+
const PRE_COMMIT_MARK = '# File generated by pre-commit';
|
|
438
|
+
// The hook ids in .pre-commit-hooks.yaml that do each git hook's job.
|
|
439
|
+
export const PRE_COMMIT_HOOK_IDS = Object.freeze({ 'pre-commit': 'pocp-gate', 'prepare-commit-msg': 'pocp-trailer', 'post-commit': 'pocp-land' });
|
|
440
|
+
|
|
417
441
|
// The GitHub workflows a project copies to run POCP in CI (examples/github), written by
|
|
418
442
|
// `pocp init --github` with the action pinned to this POCP's release.
|
|
419
443
|
export const GITHUB_WORKFLOWS = Object.freeze(['pocp.yml', 'pocp-status.yml']);
|
|
@@ -426,7 +450,7 @@ const PKG_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..'
|
|
|
426
450
|
// The newest POCP release that has a tag on GitHub. A development or pre-release build (a
|
|
427
451
|
// version like 1.1.0-dev.0, as on main between releases) has no tag of its own, so the
|
|
428
452
|
// workflows it writes pin this instead of a ref that doesn't exist. Update it with each release.
|
|
429
|
-
export const RELEASED_ACTION_REF = 'v1.
|
|
453
|
+
export const RELEASED_ACTION_REF = 'v1.4.0';
|
|
430
454
|
|
|
431
455
|
/** The release tag the workflows pin by default: "v<version>" for a release, else RELEASED_ACTION_REF. */
|
|
432
456
|
export function releaseRef() {
|
package/src/schema.js
CHANGED
|
@@ -36,7 +36,7 @@ export const CONFIG_SCHEMA = Object.freeze({
|
|
|
36
36
|
sign: { key: LEAF, principal: LEAF },
|
|
37
37
|
guard: { tests: LEAF, test_globs: LEAF, runner_globs: LEAF, extra_test_globs: LEAF, extra_runner_globs: LEAF, mutants: LEAF, seed: LEAF },
|
|
38
38
|
verify: { fail_on: LEAF, require_ci: LEAF },
|
|
39
|
-
ci: { files: LEAF, branch: LEAF, required_checks: LEAF, require_pull_request: LEAF, enforce_admins: LEAF, require_up_to_date: LEAF, workflow_approver: LEAF, reporter_app_id: LEAF, mode: LEAF },
|
|
39
|
+
ci: { files: LEAF, files_except: LEAF, branch: LEAF, required_checks: LEAF, require_pull_request: LEAF, enforce_admins: LEAF, require_up_to_date: LEAF, workflow_approver: LEAF, reporter_app_id: LEAF, mode: LEAF },
|
|
40
40
|
eval: { exclude: LEAF },
|
|
41
41
|
});
|
|
42
42
|
|
package/src/status-report.js
CHANGED
|
@@ -7,8 +7,8 @@
|
|
|
7
7
|
// trusted only when the pull request's diff changes no CI file. Everything is fetched fresh from
|
|
8
8
|
// GitHub's API on each call, so the order events arrive in doesn't matter.
|
|
9
9
|
|
|
10
|
-
import {
|
|
11
|
-
import {
|
|
10
|
+
import { ciProtects, DEFAULT_CI_FILES } from './store.js';
|
|
11
|
+
import { addLabelsCommand, APPROVE_WORKFLOW_LABEL, sortLabels } from './explain.js';
|
|
12
12
|
import { approvedByWriter, CARRYABLE, carriedOver, COMPARE_FILES_CAP, gatherCarry, gatherLabelEvents, labelFreshness, listAll, MARKER_PREFIX } from './label-freshness.js';
|
|
13
13
|
|
|
14
14
|
// The label rule lives in label-freshness.js, shared with verify.
|
|
@@ -17,7 +17,8 @@ export { CARRYABLE, carriedOver, COMPARE_FILES_CAP };
|
|
|
17
17
|
export const STATUS_CONTEXT = 'pocp';
|
|
18
18
|
export const WORKFLOW_PATH = '.github/workflows/pocp.yml';
|
|
19
19
|
export const VERIFY_JOB = 'verify';
|
|
20
|
-
|
|
20
|
+
// The label that approves a change to the CI files (explain.js names what it means).
|
|
21
|
+
export { APPROVE_WORKFLOW_LABEL };
|
|
21
22
|
// Marker steps the trusted workflow runs only when it passed that approval to verify.
|
|
22
23
|
export const APPROVAL_MARKERS = Object.freeze({
|
|
23
24
|
'approval-tests': 'pocp-approve-tests',
|
|
@@ -25,6 +26,15 @@ export const APPROVAL_MARKERS = Object.freeze({
|
|
|
25
26
|
'approval-inconclusive': 'pocp-approve-inconclusive',
|
|
26
27
|
'approval-coverage': 'pocp-approve-coverage',
|
|
27
28
|
});
|
|
29
|
+
// Steps the trusted workflow runs for each label verify says it waits for (verify's `needs`
|
|
30
|
+
// output). They choose the pending text only, never the state: a pull request's own workflow can
|
|
31
|
+
// run any step it likes, and a wrong list only names the wrong labels on a status that stays
|
|
32
|
+
// pending. A workflow without them gets the generic text.
|
|
33
|
+
export const NEEDS_MARKERS = Object.freeze({
|
|
34
|
+
'needs-tests': 'pocp-approve-tests',
|
|
35
|
+
'needs-policy': 'pocp-approve-policy',
|
|
36
|
+
'needs-inconclusive': 'pocp-approve-inconclusive',
|
|
37
|
+
});
|
|
28
38
|
// GitHub's "list pull request files" returns at most this many files. A list that reaches it may
|
|
29
39
|
// be missing the rest, so it never shows that no CI file changed.
|
|
30
40
|
export const FILES_CAP = 3000;
|
|
@@ -42,7 +52,6 @@ export const TEXT = Object.freeze({
|
|
|
42
52
|
inconclusive: "Inconclusive: a check didn't finish. Re-run it, or a maintainer approves.",
|
|
43
53
|
failed: 'Not verified: see the verify run.',
|
|
44
54
|
pending: 'Waiting for verify.',
|
|
45
|
-
workflow: 'CI workflow changed: a maintainer reviews it and adds pocp-approve-workflow.',
|
|
46
55
|
approvalGone: 'An approval this result relied on was removed: approve again.',
|
|
47
56
|
incomplete: "Not verified: GitHub's data for this pull request was incomplete. Re-run, or split a very large pull request.",
|
|
48
57
|
sharedHead: 'Another open pull request has this same head commit, and a status is per commit: close all but one.',
|
|
@@ -53,15 +62,40 @@ export const TEXT = Object.freeze({
|
|
|
53
62
|
});
|
|
54
63
|
|
|
55
64
|
|
|
65
|
+
/**
|
|
66
|
+
* The pending text for a pull request that waits only for labels: every label, and the one
|
|
67
|
+
* command that adds them all when it fits GitHub's 140 characters, else the labels alone.
|
|
68
|
+
*/
|
|
69
|
+
export function waitingText(labels, { number, repository } = {}) {
|
|
70
|
+
if (!labels?.length) return TEXT.waiting;
|
|
71
|
+
const sorted = sortLabels(labels);
|
|
72
|
+
const run = `Waiting for approval. Run: ${addLabelsCommand(sorted, { number, repository })}`;
|
|
73
|
+
if (run.length <= 140) return run;
|
|
74
|
+
const named = `Waiting for approval: add ${sorted.join(', ')} (command in the verify run)`;
|
|
75
|
+
return named.length <= 140 ? named : `Waiting for approval: add ${sorted.join(', ')}`.slice(0, 140);
|
|
76
|
+
}
|
|
77
|
+
|
|
78
|
+
/** Whether a status description is a wait for labels (either wording). */
|
|
79
|
+
export const isWaitingText = (d) => d === TEXT.waiting || String(d || '').startsWith('Waiting for approval');
|
|
80
|
+
|
|
81
|
+
/** The labels a run's needs-* steps say verify waits for. */
|
|
82
|
+
export function runNeeds(job) {
|
|
83
|
+
return Object.entries(NEEDS_MARKERS).filter(([step]) => stepOf(job, step)?.conclusion === 'success').map(([, label]) => label);
|
|
84
|
+
}
|
|
85
|
+
|
|
56
86
|
/** The CI files a pull request may not change without a maintainer (the base's ci.files, defaults always included). */
|
|
57
87
|
export function workflowFiles(baseConfig) {
|
|
58
88
|
return [...new Set([...DEFAULT_CI_FILES, ...(baseConfig?.ci?.files || [])])];
|
|
59
89
|
}
|
|
60
90
|
|
|
61
|
-
/**
|
|
62
|
-
|
|
91
|
+
/**
|
|
92
|
+
* Changed paths (including the old path of a rename) that are CI files: they match `globs` and
|
|
93
|
+
* no `except` glob (the base's ci.files_except), which never exempts a CI definition (ciProtects).
|
|
94
|
+
*/
|
|
95
|
+
export function changedWorkflowFiles(files, globs, except = []) {
|
|
63
96
|
const hit = new Set();
|
|
64
|
-
|
|
97
|
+
const ci = { files: globs, files_except: except };
|
|
98
|
+
for (const f of files || []) for (const p of [f.filename, f.previous_filename]) if (p && ciProtects(p, ci, { withDefaults: true })) hit.add(p);
|
|
65
99
|
return [...hit].sort();
|
|
66
100
|
}
|
|
67
101
|
|
|
@@ -123,7 +157,7 @@ export function runIdentity(job, number, baseSha) {
|
|
|
123
157
|
}
|
|
124
158
|
|
|
125
159
|
// Every step the trusted workflow runs to evaluate a pull request.
|
|
126
|
-
const POCP_STEPS = new Set(['verify', 'verified', 'waiting', 'inconclusive', 'failed', ...Object.keys(APPROVAL_MARKERS)]);
|
|
160
|
+
const POCP_STEPS = new Set(['verify', 'verified', 'waiting', 'inconclusive', 'failed', ...Object.keys(APPROVAL_MARKERS), ...Object.keys(NEEDS_MARKERS)]);
|
|
127
161
|
const isPocpStep = (s) => POCP_STEPS.has(s.name) || String(s.name || '').startsWith(MARKER_PREFIX);
|
|
128
162
|
|
|
129
163
|
/**
|
|
@@ -169,6 +203,7 @@ export function filesIncomplete(files, changedFiles) {
|
|
|
169
203
|
* repository, "owner/name"
|
|
170
204
|
* files: [{ filename, previous_filename }], the pull request's diff from its merge base
|
|
171
205
|
* ci_globs, workflowFiles(base config)
|
|
206
|
+
* ci_except, the base's ci.files_except (never exempts a CI definition)
|
|
172
207
|
* runs: [{ id, workflow_id, path, event, head_sha, repository, status, conclusion, created_at, run_started_at, run_attempt, html_url, job }],
|
|
173
208
|
* label_events: [{ label, actor, permission, created_at }], "labeled" events of approval labels
|
|
174
209
|
* label_events_complete, whether every event was read (approvals need it)
|
|
@@ -229,7 +264,7 @@ export function decideStatus(facts) {
|
|
|
229
264
|
break;
|
|
230
265
|
}
|
|
231
266
|
|
|
232
|
-
const changed = changedWorkflowFiles(facts.files, facts.ci_globs || workflowFiles(null));
|
|
267
|
+
const changed = changedWorkflowFiles(facts.files, facts.ci_globs || workflowFiles(null), facts.ci_except || []);
|
|
233
268
|
let via = '';
|
|
234
269
|
if (changed.length) {
|
|
235
270
|
// The run's steps come from the pull request's own workflow: not evidence until a
|
|
@@ -241,7 +276,10 @@ export function decideStatus(facts) {
|
|
|
241
276
|
const approved = pr.labels.includes(APPROVE_WORKFLOW_LABEL) && approvedByWriter(facts, APPROVE_WORKFLOW_LABEL, sha)
|
|
242
277
|
&& (!independent || (lastWorkflowLabel?.actor && pr.author && lastWorkflowLabel.actor !== pr.author));
|
|
243
278
|
if (!approved) {
|
|
244
|
-
|
|
279
|
+
// Every label at once: the workflow label, and whatever the newest run says verify waits
|
|
280
|
+
// for (text only: this run's steps aren't trusted, and the status stays pending).
|
|
281
|
+
const also = newest || unknown ? runNeeds((newest || unknown).job) : [];
|
|
282
|
+
return status('pending', waitingText([APPROVE_WORKFLOW_LABEL, ...also], { number: pr.number, repository: facts.repository }), `CI files changed (${changed.join(', ')}), so the run's results aren't trusted until ${independent ? 'a writer other than the author' : 'a writer'} adds ${APPROVE_WORKFLOW_LABEL} after this head's first run`, newest);
|
|
245
283
|
}
|
|
246
284
|
via = `; CI files changed (${changed.join(', ')}), workflow approved with ${APPROVE_WORKFLOW_LABEL}`;
|
|
247
285
|
}
|
|
@@ -273,6 +311,7 @@ export function decideStatus(facts) {
|
|
|
273
311
|
return status('success', TEXT.verified, `run ${newest.id} verified${approvals.length ? ` with ${approvals.join(', ')}` : ''}${how}${via}`, newest);
|
|
274
312
|
}
|
|
275
313
|
if (outcome === 'failed') return status('failure', TEXT.failed, `run ${newest.id} failed (${stepSummary(newest.job)})${via}`, newest);
|
|
314
|
+
if (outcome === 'waiting') return status('pending', waitingText(runNeeds(newest.job), { number: pr.number, repository: facts.repository }), `run ${newest.id} is waiting${via}`, newest);
|
|
276
315
|
return status('pending', TEXT[outcome], `run ${newest.id} is ${outcome}${via}`, newest);
|
|
277
316
|
}
|
|
278
317
|
|
|
@@ -338,7 +377,7 @@ export function githubClient({ token, api = 'https://api.github.com', fetchImpl
|
|
|
338
377
|
/** Fetch every fact decideStatus needs, fresh. */
|
|
339
378
|
export async function gather(gh, { repository, sha, prNumber, baseConfig, workflowPath = WORKFLOW_PATH }) {
|
|
340
379
|
const repo = `/repos/${repository}`;
|
|
341
|
-
const facts = { event_sha: sha, repository, ci_globs: workflowFiles(baseConfig), workflow_approver: baseConfig?.ci?.workflow_approver || 'independent', pr: null, base_sha: null, changed_files: null, head_prs: [], incomplete: [], files: [], runs: [], label_events: [], force_pushes: [] };
|
|
380
|
+
const facts = { event_sha: sha, repository, ci_globs: workflowFiles(baseConfig), ci_except: baseConfig?.ci?.files_except || [], workflow_approver: baseConfig?.ci?.workflow_approver || 'independent', pr: null, base_sha: null, changed_files: null, head_prs: [], incomplete: [], files: [], runs: [], label_events: [], force_pushes: [] };
|
|
342
381
|
const need = (r) => {
|
|
343
382
|
if (!r.complete) facts.incomplete.push(r.reason || 'a list was cut short');
|
|
344
383
|
return r.items;
|
package/src/store.js
CHANGED
|
@@ -3,7 +3,7 @@ import fs from 'node:fs';
|
|
|
3
3
|
import path from 'node:path';
|
|
4
4
|
import { PROOF_DIR } from './git.js';
|
|
5
5
|
import { DEFAULT_GUARD_MODE, DEFAULT_GUARD_MUTANTS, DEFAULT_GUARD_SEED, effectiveGuardGlobs } from './guard.js';
|
|
6
|
-
import { globProblem } from './glob.js';
|
|
6
|
+
import { globProblem, matchGlob } from './glob.js';
|
|
7
7
|
import { PocpBaseError } from './errors.js';
|
|
8
8
|
import { packetProblem } from './records.js';
|
|
9
9
|
|
|
@@ -24,6 +24,23 @@ export const DEFAULT_CI_FILES = Object.freeze([
|
|
|
24
24
|
'bitbucket-pipelines.yml', '.buildkite/**', '.drone.yml', '.woodpecker/**', '.woodpecker.yml',
|
|
25
25
|
]);
|
|
26
26
|
|
|
27
|
+
/**
|
|
28
|
+
* Whether ci.files protects `file`: it matches a ci.files glob and no ci.files_except glob.
|
|
29
|
+
* files_except narrows what a repository chose to protect (say, the READMEs in a protected
|
|
30
|
+
* folder); it never exempts a CI definition (DEFAULT_CI_FILES), which can switch POCP off.
|
|
31
|
+
* `withDefaults`: CI definitions count even when ci.files leaves them out (the reporter's rule).
|
|
32
|
+
*/
|
|
33
|
+
export function ciProtects(file, ci, { withDefaults: defaults = false } = {}) {
|
|
34
|
+
if (!file) return false;
|
|
35
|
+
const globs = (list) => (Array.isArray(list) ? list.filter((gl) => typeof gl === 'string') : []);
|
|
36
|
+
// A GitHub Action's definition anywhere (a composite action a workflow uses, like
|
|
37
|
+
// status/action.yml) counts as a CI definition too, so no exemption reaches it.
|
|
38
|
+
const definition = DEFAULT_CI_FILES.some((gl) => matchGlob(file, gl)) || /(^|\/)action\.ya?ml$/.test(file);
|
|
39
|
+
if (defaults && DEFAULT_CI_FILES.some((gl) => matchGlob(file, gl))) return true;
|
|
40
|
+
if (!globs(ci?.files).some((gl) => matchGlob(file, gl))) return false;
|
|
41
|
+
return definition || !globs(ci?.files_except).some((gl) => matchGlob(file, gl));
|
|
42
|
+
}
|
|
43
|
+
|
|
27
44
|
export const DEFAULT_CONFIG = Object.freeze({
|
|
28
45
|
pocp: 1,
|
|
29
46
|
packet_ttl_days: 14,
|
|
@@ -42,7 +59,7 @@ export const DEFAULT_CONFIG = Object.freeze({
|
|
|
42
59
|
sign: { key: null, principal: null },
|
|
43
60
|
guard: { tests: DEFAULT_GUARD_MODE, test_globs: null, runner_globs: null, mutants: DEFAULT_GUARD_MUTANTS, seed: DEFAULT_GUARD_SEED },
|
|
44
61
|
verify: { fail_on: [...FINDING_CODES], require_ci: [] },
|
|
45
|
-
ci: { files: [...DEFAULT_CI_FILES], branch: null, required_checks: [], require_pull_request: true, enforce_admins: true, require_up_to_date: true, workflow_approver: 'independent', mode: 'github' },
|
|
62
|
+
ci: { files: [...DEFAULT_CI_FILES], files_except: [], branch: null, required_checks: [], require_pull_request: true, enforce_admins: true, require_up_to_date: true, workflow_approver: 'independent', mode: 'github' },
|
|
46
63
|
});
|
|
47
64
|
|
|
48
65
|
// Calibrated on real history: counting only code and config, these thresholds asked for
|
|
@@ -391,6 +408,7 @@ export function validateConfig(config) {
|
|
|
391
408
|
if (!isStrArray(v.require_ci)) problems.push('verify.require_ci must be an array of commands');
|
|
392
409
|
const ci = c.ci || {};
|
|
393
410
|
if (!isStrArray(ci.files)) problems.push('ci.files must be an array of globs');
|
|
411
|
+
if (ci.files_except !== undefined && !isStrArray(ci.files_except)) problems.push('ci.files_except must be an array of globs');
|
|
394
412
|
if (ci.branch !== null && typeof ci.branch !== 'string') problems.push('ci.branch must be a branch name or null');
|
|
395
413
|
if (!isStrArray(ci.required_checks)) problems.push('ci.required_checks must be an array of check names');
|
|
396
414
|
for (const k of ['require_pull_request', 'enforce_admins']) if (typeof ci[k] !== 'boolean') problems.push(`ci.${k} must be true or false`);
|
|
@@ -398,7 +416,7 @@ export function validateConfig(config) {
|
|
|
398
416
|
if (ci.reporter_app_id != null && !(Number.isInteger(ci.reporter_app_id) && ci.reporter_app_id > 0)) problems.push('ci.reporter_app_id must be a GitHub App id (a positive whole number)');
|
|
399
417
|
if (!['independent', 'any-writer'].includes(ci.workflow_approver)) problems.push('ci.workflow_approver must be "independent" or "any-writer"');
|
|
400
418
|
if (!['github', 'local'].includes(ci.mode)) problems.push('ci.mode must be "github" (CI checks every pull request) or "local" (the git hooks only)');
|
|
401
|
-
const globLists = { 'guard.test_globs': guard.test_globs, 'guard.runner_globs': guard.runner_globs, 'guard.extra_test_globs': guard.extra_test_globs, 'guard.extra_runner_globs': guard.extra_runner_globs, 'ci.files': ci.files, 'eval.exclude': c.eval?.exclude };
|
|
419
|
+
const globLists = { 'guard.test_globs': guard.test_globs, 'guard.runner_globs': guard.runner_globs, 'guard.extra_test_globs': guard.extra_test_globs, 'guard.extra_runner_globs': guard.extra_runner_globs, 'ci.files': ci.files, 'ci.files_except': ci.files_except, 'eval.exclude': c.eval?.exclude };
|
|
402
420
|
for (const [k, list] of Object.entries(globLists)) {
|
|
403
421
|
if (!isStrArray(list)) continue;
|
|
404
422
|
for (const gl of list) if (globProblem(gl)) problems.push(`${k}: ${globProblem(gl)}`);
|
|
@@ -423,6 +441,8 @@ export function configWeakening(base, head) {
|
|
|
423
441
|
// Local mode turns off what doctor checks of CI and makes you the approver: a change can't choose it for itself.
|
|
424
442
|
if ((base.ci?.mode ?? 'github') !== 'local' && head.ci?.mode === 'local') out.push('ci.mode switched to "local" (no CI)');
|
|
425
443
|
for (const gl of base.ci?.files || []) if (!(head.ci?.files || []).includes(gl)) out.push(`ci.files no longer protects "${gl}"`);
|
|
444
|
+
const exempt = (c) => (Array.isArray(c?.ci?.files_except) ? c.ci.files_except : []);
|
|
445
|
+
for (const gl of exempt(head)) if (!exempt(base).includes(gl)) out.push(`ci.files_except now exempts "${gl}"`);
|
|
426
446
|
for (const check of base.ci?.required_checks || []) {
|
|
427
447
|
if (!(head.ci?.required_checks || []).includes(check)) out.push(`ci.required_checks no longer requires "${check}"`);
|
|
428
448
|
}
|
|
@@ -458,6 +478,9 @@ export function strictConfig(base, head) {
|
|
|
458
478
|
if (Number.isInteger(base.guard?.mutants) && !(out.guard.mutants >= base.guard.mutants)) out.guard.mutants = base.guard.mutants;
|
|
459
479
|
if (Number.isInteger(base.guard?.seed)) out.guard.seed = base.guard.seed;
|
|
460
480
|
out.ci.files = [...new Set([...(base.ci?.files || []), ...(head.ci?.files || [])])];
|
|
481
|
+
// An exemption counts only once both sides have it.
|
|
482
|
+
const list = (x) => (Array.isArray(x) ? x : []);
|
|
483
|
+
out.ci.files_except = list(head.ci?.files_except).filter((gl) => list(base.ci?.files_except).includes(gl));
|
|
461
484
|
out.ci.required_checks = [...new Set([...(base.ci?.required_checks || []), ...(head.ci?.required_checks || [])])];
|
|
462
485
|
out.ci.require_pull_request = base.ci?.require_pull_request === true || head.ci?.require_pull_request === true;
|
|
463
486
|
out.ci.enforce_admins = base.ci?.enforce_admins === true || head.ci?.enforce_admins === true;
|