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 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.3.2
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).
@@ -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.3.2
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
- [`examples/claude-code/`](../examples/claude-code/) has a working PreToolUse hook. The same two calls 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.
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 a maintainer | only an approval is missing (a test change, a policy loosening, commits without proof) | a maintainer reviews and adds the label the verify run names |
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 workflow changed | the pull request changes a CI file, so its own run can't be trusted | a maintainer reviews the workflow change and adds `pocp-approve-workflow` |
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 generic. What the run asks for is in the run's summary, which the status links to.
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
 
@@ -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.2",
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 === TEXT.waiting) 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}`);
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(`::error title=POCP::${c.kind === 'net' ? 'net change ' : ''}${c.commit.slice(0, 12)} ${commitProblems(c).join(' | ').replace(/\r?\n/g, ' ')}\n`);
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 || [])];
@@ -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
- // The pre-commit hook sets POCP_GATE_SOURCE=hook. Drop it so checks don't inherit it.
7
- const source = process.env.POCP_GATE_SOURCE === 'hook' ? 'hook' : 'gate';
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);
@@ -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
- const lines = await engine.addTrailersToFile(rest[0], { source: rest[1] });
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();
@@ -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.ok ? 'verified' : 'NOT verified'}: ${result.commits.length} commit(s) in ${result.range} · ${Date.now() - started}ms`,
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.ok ? 'verified' : 'NOT verified'}: ${result.commit.slice(0, 12)} subject ${shortDigest(result.subject)} · ${Date.now() - started}ms`,
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' : '';
@@ -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 && globs.some((gl) => matchGlob(p, gl))) touched.add(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
 
@@ -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 });
@@ -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)) if (st === 'missing' || st === 'no pocp block') problems.push(`${name}: ${st}`);
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.3.2';
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
 
@@ -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 { matchGlob } from './glob.js';
11
- import { DEFAULT_CI_FILES } from './store.js';
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
- export const APPROVE_WORKFLOW_LABEL = 'pocp-approve-workflow';
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
- /** Changed paths (including the old path of a rename) that are CI files. */
62
- export function changedWorkflowFiles(files, globs) {
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
- for (const f of files || []) for (const p of [f.filename, f.previous_filename]) if (p && globs.some((g) => matchGlob(p, g))) hit.add(p);
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
- return status('pending', TEXT.workflow, `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);
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;