mandrel 2.70.0 → 2.72.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/.agents/README.md +8 -9
- package/.agents/agents/acceptance-critic.md +1 -0
- package/.agents/agents/auditor.md +1 -0
- package/.agents/agents/plan-critic.md +1 -0
- package/.agents/agents/story-worker.md +63 -64
- package/.agents/docs/agentrc-reference.json +2 -1
- package/.agents/docs/configuration.md +7 -8
- package/.agents/rules/git-conventions-reference.md +2 -2
- package/.agents/schemas/agentrc.schema.json +19 -2
- package/.agents/schemas/story-deliver-terminal.schema.json +10 -1
- package/.agents/scripts/acceptance-eval.js +194 -15
- package/.agents/scripts/deliver-run.js +92 -43
- package/.agents/scripts/lib/audit-suite/index.js +1 -1
- package/.agents/scripts/lib/audit-suite/story-checklist.js +65 -0
- package/.agents/scripts/lib/audit-to-stories/audit-label-taxonomy.js +2 -2
- package/.agents/scripts/lib/bootstrap/issue-forms-template.js +1 -1
- package/.agents/scripts/lib/cli-args.js +22 -0
- package/.agents/scripts/lib/close-validation/gates.js +17 -3
- package/.agents/scripts/lib/config/agent-models.js +117 -0
- package/.agents/scripts/lib/config-settings-schema-delivery.js +13 -1
- package/.agents/scripts/lib/config-settings-schema-quality.js +1 -1
- package/.agents/scripts/lib/generated/agentrc-validator.js +1 -1
- package/.agents/scripts/lib/git/sync-from-base.js +89 -17
- package/.agents/scripts/lib/label-taxonomy.js +13 -3
- package/.agents/scripts/lib/notifications/notifier.js +11 -15
- package/.agents/scripts/lib/observability/close-telemetry.js +19 -3
- package/.agents/scripts/lib/observability/source-classifier.js +1 -0
- package/.agents/scripts/lib/orchestration/cancelled-run-discount.js +129 -0
- package/.agents/scripts/lib/orchestration/code-review.js +2 -2
- package/.agents/scripts/lib/orchestration/deliver-recover.js +166 -34
- package/.agents/scripts/lib/orchestration/file-assumptions.js +45 -11
- package/.agents/scripts/lib/orchestration/plan-context.js +17 -10
- package/.agents/scripts/lib/orchestration/plan-persist/changes-repair.js +130 -24
- package/.agents/scripts/lib/orchestration/plan-persist/run-plan-persist.js +19 -16
- package/.agents/scripts/lib/orchestration/plan-persist/story-ops.js +1 -0
- package/.agents/scripts/lib/orchestration/plan-persist/summary.js +4 -3
- package/.agents/scripts/lib/orchestration/pr-watch.js +14 -3
- package/.agents/scripts/lib/orchestration/resolve-stories.js +10 -2
- package/.agents/scripts/lib/orchestration/review-providers/native.js +5 -165
- package/.agents/scripts/lib/orchestration/single-story-close/failed-terminal.js +14 -2
- package/.agents/scripts/lib/orchestration/single-story-close/phases/auto-merge.js +45 -0
- package/.agents/scripts/lib/orchestration/single-story-close/phases/base-sync.js +162 -58
- package/.agents/scripts/lib/orchestration/single-story-close/phases/confirm-merge.js +58 -6
- package/.agents/scripts/lib/orchestration/single-story-close/phases/merge-wait-recovery.js +296 -0
- package/.agents/scripts/lib/orchestration/single-story-close/phases/options.js +20 -4
- package/.agents/scripts/lib/orchestration/single-story-close/phases/post-land.js +52 -6
- package/.agents/scripts/lib/orchestration/single-story-close/phases/pull-request.js +2 -2
- package/.agents/scripts/lib/orchestration/single-story-close/phases/story-branch-catch-up.js +50 -0
- package/.agents/scripts/lib/orchestration/single-story-close/phases/worktree-reap.js +64 -52
- package/.agents/scripts/lib/orchestration/single-story-close/phases/worktree-restore.js +133 -0
- package/.agents/scripts/lib/orchestration/single-story-close/runner.js +187 -74
- package/.agents/scripts/lib/orchestration/story-deliver-terminal.js +46 -6
- package/.agents/scripts/lib/orchestration/story-handoff.js +849 -0
- package/.agents/scripts/lib/orchestration/story-init-result.js +83 -0
- package/.agents/scripts/lib/orchestration/task-body-validator.js +35 -5
- package/.agents/scripts/lib/orchestration/ticket-validator-sizing.js +1 -1
- package/.agents/scripts/lib/orchestration/ticket-validator.js +20 -2
- package/.agents/scripts/lib/single-story/confirm-merge.js +44 -7
- package/.agents/scripts/lib/story-body/story-body.js +40 -5
- package/.agents/scripts/lib/templates/decomposer-prompts.js +33 -36
- package/.agents/scripts/pr-watch-with-update.js +5 -0
- package/.agents/scripts/single-story-close.js +8 -0
- package/.agents/scripts/single-story-confirm-merge.js +34 -3
- package/.agents/scripts/single-story-init.js +17 -32
- package/.agents/scripts/story-handoff.js +112 -0
- package/.agents/scripts/sync-claude-agents.js +58 -27
- package/.agents/workflows/helpers/acceptance-self-eval.md +24 -18
- package/.agents/workflows/helpers/code-review.md +3 -3
- package/.agents/workflows/helpers/deliver-digest.md +79 -80
- package/.agents/workflows/helpers/deliver-light.md +9 -7
- package/.agents/workflows/helpers/deliver-reference.md +38 -22
- package/.agents/workflows/helpers/deliver-story-reference.md +39 -18
- package/.agents/workflows/helpers/deliver-story.md +30 -23
- package/.agents/workflows/helpers/plan-reference.md +24 -9
- package/.agents/workflows/helpers/worktree-lifecycle.md +5 -5
- package/docs/CHANGELOG.md +31 -0
- package/lib/cli/registry.js +7 -0
- package/package.json +4 -3
- package/.agents/scripts/lib/orchestration/review-providers/scoped-lint.js +0 -272
|
@@ -173,9 +173,23 @@ anything a plan authored.
|
|
|
173
173
|
is then a dry-run **warning**, not a rejection. `deletes` stays explicit —
|
|
174
174
|
a bare path can never express a removal — and a `deletes` naming a path
|
|
175
175
|
absent at base is the one `changes[]` shape still refused.
|
|
176
|
-
-
|
|
177
|
-
|
|
178
|
-
|
|
176
|
+
- **`## Spec` decides.** Every load-bearing mechanism is chosen there with
|
|
177
|
+
its why; a choice is left to the deliverer only when it is genuinely not
|
|
178
|
+
load-bearing. It stays contract-level — no per-file behavior narration —
|
|
179
|
+
and as long as the work needs. There is no word or token budget.
|
|
180
|
+
- **`## Context` is the handoff.** An optional text section after `## Spec`:
|
|
181
|
+
entry points (file + symbol), the pattern to mirror, the test file or
|
|
182
|
+
harness to extend, known traps, the scoped test command — verified facts,
|
|
183
|
+
tersely, never a walkthrough. Backticked repo paths in it are probed at
|
|
184
|
+
persist and **warn** when absent at base.
|
|
185
|
+
- **`references[]` names the read-first files.** Author the files the
|
|
186
|
+
deliverer should read before editing. A bare path is the default: persist
|
|
187
|
+
derives `exists` by probing base and warns, never refuses, on an absent one.
|
|
188
|
+
- **Slicing checkpoints may end `— verify: <exact command>`** — encouraged
|
|
189
|
+
past two checkpoints, so each stage is proven before the next starts.
|
|
190
|
+
|
|
191
|
+
Context, References and checkpoint verify commands are advisory like
|
|
192
|
+
`changes[]`; `acceptance[]` / `verify[]` stay the only binding contract.
|
|
179
193
|
|
|
180
194
|
A faithfully-filled skeleton — placeholders replaced, pre-resolved entries
|
|
181
195
|
kept — passes the persist ticket validators with no round-trip.
|
|
@@ -183,10 +197,10 @@ kept — passes the persist ticket validators with no round-trip.
|
|
|
183
197
|
### Authored entry shape
|
|
184
198
|
|
|
185
199
|
Each `stories.json` entry: `slug` (`^[a-z0-9][a-z0-9-]*$`), `type: "story"`,
|
|
186
|
-
`title`, `body` (`goal`, optional `spec`, `changes[]`
|
|
187
|
-
by default, or `{path, assumption}` with
|
|
188
|
-
`creates|refactors-existing|deletes` to pin one, `
|
|
189
|
-
`
|
|
200
|
+
`title`, `body` (`goal`, optional `slicing` / `spec` / `context`, `changes[]`
|
|
201
|
+
— a **bare path string** by default, or `{path, assumption}` with
|
|
202
|
+
`creates|refactors-existing|deletes` to pin one, optional `references[]` and
|
|
203
|
+
`non_goals`), top-level `acceptance[]`, `verify[]` (each a **bare
|
|
190
204
|
command** — there is no tier suffix), and `depends_on[]` (a sibling slug, or
|
|
191
205
|
`#<id>` for an existing open Story).
|
|
192
206
|
|
|
@@ -368,7 +382,8 @@ Commit subjects are not scanned — the `commit-msg` hook and
|
|
|
368
382
|
**Warnings — listed, then the persist proceeds:** a `creates` on a path that
|
|
369
383
|
exists at base or a `refactors-existing` on one that does not (including a
|
|
370
384
|
path the base branch deleted or renamed, named with the removing commit), a
|
|
371
|
-
goal or
|
|
385
|
+
goal, acceptance or `## Context` path absent at base, a bare `references[]`
|
|
386
|
+
entry absent at base, an empty `verify[]`, a source id
|
|
372
387
|
assigned to the primary Story by default, a `verify[]` command naming an
|
|
373
388
|
absent test file, an `open-question` in a body (`Flag if…`, `TBD`, a trailing
|
|
374
389
|
`?`), and a `pinned-identifier` in an acceptance item — a backticked bare symbol
|
|
@@ -376,7 +391,7 @@ that is not a path, a label, a kebab token, a flag or a command, which the
|
|
|
376
391
|
advisory `changes[]` is free to reshape out from under the criterion. The
|
|
377
392
|
list also names every **repair** the run applied — a plain-string bullet or a
|
|
378
393
|
trailing parenthetical rewritten into `{ path, assumption }` by probing base,
|
|
379
|
-
and an `AC-<n>:` handle normalised off an acceptance item. The same list rides
|
|
394
|
+
a bare reference present at base derived as `exists`, and an `AC-<n>:` handle normalised off an acceptance item. The same list rides
|
|
380
395
|
the result envelope as `warnings[]` and `repairs[]`, carried from the
|
|
381
396
|
write-free pass onto the chained run's envelope.
|
|
382
397
|
|
|
@@ -50,9 +50,9 @@ root, and shell-metacharacter injection in `root`.
|
|
|
50
50
|
| **Sweep** | Operator-driven (`WorktreeManager.sweepStaleLocks`) | Stale `*.lock` files under `.git/` (older than 5 min) are removed before GC. |
|
|
51
51
|
| **GC** | Operator-driven (`WorktreeManager.gc`) | Orphan `.worktrees/story-*` whose Stories are closed are reaped if clean. |
|
|
52
52
|
| **Force-drain** | Operator-driven (`drain-pending-cleanup.js`) | Retries `.worktrees/.pending-cleanup.json` (`git worktree remove` then `fs.rm`); Windows-only escalation enumerates user-mode handle holders and `taskkill`s them before re-trying. |
|
|
53
|
-
| **Ensure** | `single-story-init.js` (entry for `/mandrel-deliver`)
|
|
53
|
+
| **Ensure** | `single-story-init.js` (entry for `/mandrel-deliver`); close and the `--wait` resume when it is missing | `git worktree add .worktrees/story-<id>/` on the `story-<id>` branch (fetched from origin when no local ref remains). |
|
|
54
54
|
| **Run** | During Story execution | Agent runs inside the worktree; HEAD/reflog activity is isolated. |
|
|
55
|
-
| **Reap** | After
|
|
55
|
+
| **Reap** | After a confirmed merge, in the post-land tail (`tail.worktreeReap`) | `git worktree remove`, before the local ref reap — refuses a dirty tree. A `pending`, `blocked` or `failed` close keeps the worktree. |
|
|
56
56
|
|
|
57
57
|
The `WorktreeManager` (`.agents/scripts/lib/worktree-manager.js`) is the single
|
|
58
58
|
authority for `ensure`, `reap`, `list`, `isSafeToRemove`, `gc`, `prune`, and
|
|
@@ -86,7 +86,7 @@ epic-runner. The lifecycle surfaces that do run automatically are:
|
|
|
86
86
|
| Entry point | Script / caller | What it cleans |
|
|
87
87
|
| --------------------------------- | -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
|
|
88
88
|
| Story init (`/mandrel-deliver <storyId>`) | `single-story-init.js` boot sweep (`sweepMergedStoryBranches`) | Merged/closed `story-*` branches (local + origin) from prior runs; it then creates only its own worktree. |
|
|
89
|
-
| Story close
|
|
89
|
+
| Story land (close's wait, or `--wait`) | The post-land tail's worktree-reap step (`WorktreeManager.reap`) | The per-Story worktree; on a Windows EBUSY-class lock the entry is deferred into `.worktrees/.pending-cleanup.json`. |
|
|
90
90
|
| Drain pending-cleanup (operator) | `drain-pending-cleanup.js` (run directly — see below) | The pending-cleanup ledger, with optional Windows handle-holder escalation. This is the only path that drains the ledger. |
|
|
91
91
|
|
|
92
92
|
Operator takeaway: if worktrees or stale locks accumulate, run
|
|
@@ -95,8 +95,8 @@ Operator takeaway: if worktrees or stale locks accumulate, run
|
|
|
95
95
|
|
|
96
96
|
## Draining the pending-cleanup ledger
|
|
97
97
|
|
|
98
|
-
`.worktrees/.pending-cleanup.json` accumulates entries when
|
|
99
|
-
|
|
98
|
+
`.worktrees/.pending-cleanup.json` accumulates entries when the
|
|
99
|
+
post-land tail cannot remove a worktree on Windows because of
|
|
100
100
|
an EBUSY-class lock. If the holder is a long-lived user-mode process (a
|
|
101
101
|
stranded test runner, a lingering biome/tsc, a node REPL), the lock
|
|
102
102
|
never clears and the entry pins.
|
package/docs/CHANGELOG.md
CHANGED
|
@@ -15,6 +15,37 @@ All notable changes to this project will be documented in this file.
|
|
|
15
15
|
-->
|
|
16
16
|
<!-- markdownlint-disable-file MD004 MD012 MD037 -->
|
|
17
17
|
|
|
18
|
+
## [2.72.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.71.0...mandrel-v2.72.0) (2026-10-01)
|
|
19
|
+
|
|
20
|
+
|
|
21
|
+
### Added
|
|
22
|
+
|
|
23
|
+
* close keeps the worktree until land, self-syncs a DIRTY PR, re-arms a disarmed PR, and recover names both ([#5533](https://github.com/dsj1984/mandrel/issues/5533)) ([#5537](https://github.com/dsj1984/mandrel/issues/5537)) ([5e0fd9c](https://github.com/dsj1984/mandrel/commit/5e0fd9c8e2bcc7984188db291f20d3171c234c69))
|
|
24
|
+
|
|
25
|
+
|
|
26
|
+
### Fixed
|
|
27
|
+
|
|
28
|
+
* pr-watch ignores a required check from a concurrency-cancelled run while a live run on the same head exists ([#5534](https://github.com/dsj1984/mandrel/issues/5534)) ([#5535](https://github.com/dsj1984/mandrel/issues/5535)) ([caa2d6a](https://github.com/dsj1984/mandrel/commit/caa2d6ab935dd70d2ba40b3b8e952e4587a1ef1e))
|
|
29
|
+
|
|
30
|
+
## [2.71.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.70.0...mandrel-v2.71.0) (2026-09-30)
|
|
31
|
+
|
|
32
|
+
|
|
33
|
+
### Added
|
|
34
|
+
|
|
35
|
+
* close resolves baseline-only merge conflicts, hands other conflicts back to the delivering agent, and retries a failed done-label write instead of blocking for a human ([#5520](https://github.com/dsj1984/mandrel/issues/5520)) ([#5527](https://github.com/dsj1984/mandrel/issues/5527)) ([2e56566](https://github.com/dsj1984/mandrel/commit/2e565668bf0f02fc0c84b71779a50bec72ff84f4))
|
|
36
|
+
* deliver: the worker's tail is one story-handoff command that hands fixable failures back instead of blocking, the worker never writes agent::closing, and self-eval starts from a verdict skeleton ([#5518](https://github.com/dsj1984/mandrel/issues/5518)) ([#5524](https://github.com/dsj1984/mandrel/issues/5524)) ([74d2ef2](https://github.com/dsj1984/mandrel/commit/74d2ef2411efcb6a5a116401af5a52448cbd78fe))
|
|
37
|
+
* notify on agent::blocked, refuse agent::review-spec Stories at delivery, drop the native reviewer's duplicate lint pass, and correct the drift the SDLC review found ([#5517](https://github.com/dsj1984/mandrel/issues/5517)) ([#5523](https://github.com/dsj1984/mandrel/issues/5523)) ([7330307](https://github.com/dsj1984/mandrel/commit/7330307013a1678287dd0192a3f9042abca92432))
|
|
38
|
+
* plan: author Stories as a grounded handoff — decided Spec, References, a probed Context section and verifiable Slicing checkpoints, in a prompt no longer than today's ([#5516](https://github.com/dsj1984/mandrel/issues/5516)) ([#5522](https://github.com/dsj1984/mandrel/issues/5522)) ([f7b8388](https://github.com/dsj1984/mandrel/commit/f7b8388524737cf230eaa6a3bf19860b45d10ce5))
|
|
39
|
+
* role agents declare a model default, delivery.routing.agentModels overrides it per role, and close records the dispatched worker's model ([#5519](https://github.com/dsj1984/mandrel/issues/5519)) ([#5526](https://github.com/dsj1984/mandrel/issues/5526)) ([39a93d8](https://github.com/dsj1984/mandrel/commit/39a93d86942c2814cdea5b0074e7f352e3db832e))
|
|
40
|
+
* story-handoff preflight runs the standalone ratchets CI's baselines job runs, so a dead-export or cycle is fix-required at handoff instead of a CI red ([#5528](https://github.com/dsj1984/mandrel/issues/5528)) ([#5530](https://github.com/dsj1984/mandrel/issues/5530)) ([23c44d0](https://github.com/dsj1984/mandrel/commit/23c44d062b9a771373bf82b32ea7a70839af6446))
|
|
41
|
+
|
|
42
|
+
|
|
43
|
+
### Fixed
|
|
44
|
+
|
|
45
|
+
* **agents:** stop story-worker flipping agent::closing at hand-off (refs [#5515](https://github.com/dsj1984/mandrel/issues/5515)) ([#5521](https://github.com/dsj1984/mandrel/issues/5521)) ([1f5b564](https://github.com/dsj1984/mandrel/commit/1f5b5649747b9dad826205f9819bc12738bbe55e))
|
|
46
|
+
* **deps:** clear brace-expansion, fast-uri, and markdown-it advisories ([#5508](https://github.com/dsj1984/mandrel/issues/5508)) ([fd97225](https://github.com/dsj1984/mandrel/commit/fd972259f111390d9ca1515d1a5cde45995c1709)), closes [#5507](https://github.com/dsj1984/mandrel/issues/5507)
|
|
47
|
+
* story-handoff: a non-fast-forward push rejection is fix-required, not blocked ([#5525](https://github.com/dsj1984/mandrel/issues/5525)) ([#5529](https://github.com/dsj1984/mandrel/issues/5529)) ([332389c](https://github.com/dsj1984/mandrel/commit/332389c03fcaf9497b134d4574ae7a1a712d62b6))
|
|
48
|
+
|
|
18
49
|
## [2.70.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.69.0...mandrel-v2.70.0) (2026-09-29)
|
|
19
50
|
|
|
20
51
|
|
package/lib/cli/registry.js
CHANGED
|
@@ -868,6 +868,10 @@ const TEST_CREDIT_DEPOSIT_COMMAND =
|
|
|
868
868
|
const COVERAGE_CAPTURE_COMMAND =
|
|
869
869
|
'node .agents/scripts/coverage-capture.js --cwd <workCwd>';
|
|
870
870
|
|
|
871
|
+
/** The worker's one tail command; it runs whichever depositor applies. */
|
|
872
|
+
const STORY_HANDOFF_COMMAND =
|
|
873
|
+
'node .agents/scripts/story-handoff.js --story <storyId> --cwd <workCwd>';
|
|
874
|
+
|
|
871
875
|
const TEST_CREDIT_REMEDY = `run the suite through the depositor instead of bare \`npm test\`: ${TEST_CREDIT_DEPOSIT_COMMAND}`;
|
|
872
876
|
|
|
873
877
|
const PRE_PUSH_REMEDY =
|
|
@@ -1010,6 +1014,9 @@ function describePrePushHook(projectRoot, readFileImpl) {
|
|
|
1010
1014
|
function runTestCreditPath({ projectRoot, readFile = fs.readFileSync } = {}) {
|
|
1011
1015
|
const root = projectRoot ?? process.cwd();
|
|
1012
1016
|
const parts = [
|
|
1017
|
+
{
|
|
1018
|
+
detail: `the worker's \`${STORY_HANDOFF_COMMAND}\` runs the credited run close reads`,
|
|
1019
|
+
},
|
|
1013
1020
|
describeCreditedRun({
|
|
1014
1021
|
scripts: readProjectScripts(root, readFile),
|
|
1015
1022
|
crapEnabled: isCrapEnabled(root, readFile),
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "mandrel",
|
|
3
|
-
"version": "2.
|
|
3
|
+
"version": "2.72.0",
|
|
4
4
|
"description": "Claude Code-first opinionated workflow framework: instructions, skills, rules, and SDLC workflows that govern AI coding assistants.",
|
|
5
5
|
"files": [
|
|
6
6
|
".agents/",
|
|
@@ -85,7 +85,7 @@
|
|
|
85
85
|
"author": "",
|
|
86
86
|
"license": "MIT",
|
|
87
87
|
"bin": {
|
|
88
|
-
"mandrel": "
|
|
88
|
+
"mandrel": "bin/mandrel.js"
|
|
89
89
|
},
|
|
90
90
|
"type": "module",
|
|
91
91
|
"bugs": {
|
|
@@ -141,11 +141,12 @@
|
|
|
141
141
|
"peerDependencies.@cucumber/gherkin": "OPTIONAL peer, mirroring the `typescript` precedent, and deliberately NOT a runtime dependency. `check-gherkin-corpus.js` is the only consumer and it is opt-in behind `qa.gherkinLint`, so a consumer with no BDD tier must gain nothing from an upgrade. The devDependency alongside it is what lets this repository's own suite drive the real parser. The gate resolves it through a require path anchored at the consumer project — `.agents/` reaches a consumer by plain file copy, so a bare specifier would resolve against the consumer's module chain, which under a non-hoisting linker need not hold it.",
|
|
142
142
|
"overrides.js-yaml": "COUPLED to devDependencies.markdownlint-cli2 — do not bump either alone, and do NOT drop this override. It is load-bearing: markdownlint-cli2 0.22.x pulls js-yaml 4.1.1, which carries GHSA-52cp-r559-cp3m (high) and GHSA-h67p-54hq-rp68 (moderate); removing the override was measured to reintroduce both (1 high + 1 moderate), while with it in place `npm audit` is clean. An npm override also wins over a transitive package's own pin, so this tree-wide ^4.3.2 is imposed on every js-yaml consumer regardless of what they declare — and markdownlint-cli2 0.23.x declares an exact js-yaml 5.2.1. A dry-run bump confirmed the trap: markdownlint-cli2 0.23.1 resolves against js-yaml 4.3.0, two majors off what it declares, silently. The only safe move is to raise this override and bump markdownlint-cli2 in ONE reviewed commit (first confirming cosmiconfig, under @commitlint/cli, tolerates the same major). renovate.json excludes markdownlint-cli2 from devDependency auto-merge so that pair cannot drift apart unattended. The floor has since been raised twice for advisories against the pinned range itself (most recently to ^4.3.2 for GHSA-2883-xcg3-v3hh, whose fix is 4.3.2) — raising it is safe and does NOT touch the coupling above; check-pinned-override-notes.js now fails the build if this sentence and the pin disagree.",
|
|
143
143
|
"dependencies.js-yaml": "States the SAME range as overrides.js-yaml above. The two are deliberate duplicates — npm has no way to reference the direct range from the overrides block — so they MUST move in lockstep; changing one without the other silently splits the direct and transitive resolutions.",
|
|
144
|
+
"overrides.markdown-it": "Load-bearing: markdownlint-cli2 0.22.1 declares an EXACT markdown-it 14.1.1, which carries GHSA-253c-mchw-3w2r (moderate — quadratic linkify paths block the event loop). The advisory’s vulnerable range is everything < 14.3.1, so this tree-wide ^14.3.1 pin is what clears it. npm’s own `audit fix --force` instead proposes markdownlint-cli2 0.23.3, a breaking bump coupled to the js-yaml major above; do not take it. `npm run lint` is what must be re-run if this pin moves.",
|
|
144
145
|
"overrides.smol-toml": "Load-bearing: markdownlint-cli2 0.22.1 declares an EXACT smol-toml 1.6.1, which carries GHSA-7w5x-hrqm-74c2 (high — denial of service via malformed TOML). The advisory’s vulnerable range is everything <= 1.7.0, so no lockfile-only resolution reaches a patched version and this tree-wide ^1.7.1 pin is what clears it. npm’s own `audit fix --force` instead proposes markdownlint-cli2 0.21.0 — a DOWNGRADE presented as a breaking change; do not take it. An npm override wins over a transitive package’s own exact pin, so markdownlint-cli2 runs against a minor it never declared: `npm run lint` was confirmed green under the forced version and is what must be re-run if this pin moves. knip declares ^1.6.1 and is satisfied natively. smol-toml is NOT a direct dependency, so unlike overrides.js-yaml there is no lockstep duplicate range to keep in sync."
|
|
145
146
|
},
|
|
146
147
|
"overrides": {
|
|
147
148
|
"js-yaml": "^4.3.2",
|
|
148
|
-
"markdown-it": "^14.
|
|
149
|
+
"markdown-it": "^14.3.1",
|
|
149
150
|
"smol-toml": "^1.7.1"
|
|
150
151
|
}
|
|
151
152
|
}
|
|
@@ -1,272 +0,0 @@
|
|
|
1
|
-
/**
|
|
2
|
-
* review-providers/scoped-lint.js — scoped biome + markdownlint over the
|
|
3
|
-
* changed surface. Runners resolve on disk before spawning (`npx --no biome`
|
|
4
|
-
* exits 0 silently when biome is absent), and each surface is classified
|
|
5
|
-
* independently so one failure cannot become the other's verdict.
|
|
6
|
-
*/
|
|
7
|
-
|
|
8
|
-
import { spawnSync } from 'node:child_process';
|
|
9
|
-
import { existsSync } from 'node:fs';
|
|
10
|
-
import path from 'node:path';
|
|
11
|
-
|
|
12
|
-
const CODE_EXTENSIONS = /\.(js|mjs|cjs|jsx|ts|tsx|json|jsonc)$/i;
|
|
13
|
-
|
|
14
|
-
/**
|
|
15
|
-
* npx's unresolvable-bin output: the legacy message or current npm's E404.
|
|
16
|
-
* Matching the E404 code, not any `npm error` line, keeps genuine runner
|
|
17
|
-
* errors out.
|
|
18
|
-
*/
|
|
19
|
-
const NPX_UNRESOLVABLE =
|
|
20
|
-
/could not determine executable to run|npm (?:error|ERR!)\s+code\s+E404/i;
|
|
21
|
-
|
|
22
|
-
/** Biome's exit-1 when every path is config-excluded: an empty scope, not a failure. */
|
|
23
|
-
const BIOME_EMPTY_SCOPE = /No files were processed in the specified paths/i;
|
|
24
|
-
|
|
25
|
-
/**
|
|
26
|
-
* Markdown runners in preference order, each with its own argument shape:
|
|
27
|
-
* cli2 rejects `--ignore`, which cli v1 takes.
|
|
28
|
-
*/
|
|
29
|
-
const MARKDOWN_RUNNERS = Object.freeze([
|
|
30
|
-
Object.freeze({ bin: 'markdownlint-cli2', extraArgs: Object.freeze([]) }),
|
|
31
|
-
Object.freeze({
|
|
32
|
-
bin: 'markdownlint',
|
|
33
|
-
extraArgs: Object.freeze(['--ignore', 'node_modules']),
|
|
34
|
-
}),
|
|
35
|
-
]);
|
|
36
|
-
|
|
37
|
-
const CODE_RUNNERS = Object.freeze([
|
|
38
|
-
Object.freeze({ bin: 'biome', extraArgs: Object.freeze([]) }),
|
|
39
|
-
]);
|
|
40
|
-
|
|
41
|
-
const DEGRADATION_REASONS = Object.freeze({
|
|
42
|
-
RUNNER_NOT_INSTALLED: 'runner-not-installed',
|
|
43
|
-
RUNNER_NOT_RESOLVABLE: 'runner-not-resolvable',
|
|
44
|
-
UNPARSEABLE_OUTPUT: 'unparseable-output',
|
|
45
|
-
});
|
|
46
|
-
|
|
47
|
-
/**
|
|
48
|
-
* Spawn one lint runner through `npx --no` (never install on the fly).
|
|
49
|
-
*
|
|
50
|
-
* @param {string} bin
|
|
51
|
-
* @param {string[]} args
|
|
52
|
-
* @param {string} cwd
|
|
53
|
-
* @returns {{ status: number, stdout: string, stderr: string }}
|
|
54
|
-
*/
|
|
55
|
-
function spawnLintRunner(bin, args, cwd) {
|
|
56
|
-
const result = spawnSync('npx', ['--no', bin, ...args], {
|
|
57
|
-
cwd,
|
|
58
|
-
encoding: 'utf-8',
|
|
59
|
-
shell: process.platform === 'win32',
|
|
60
|
-
});
|
|
61
|
-
return {
|
|
62
|
-
status: result.status ?? 1,
|
|
63
|
-
stdout: result.stdout ?? '',
|
|
64
|
-
stderr: result.stderr ?? '',
|
|
65
|
-
};
|
|
66
|
-
}
|
|
67
|
-
|
|
68
|
-
/**
|
|
69
|
-
* First candidate installed under `<cwd>/node_modules/.bin`, else `null`.
|
|
70
|
-
* Deliberately local-only: a global runner reads as absent and degrades
|
|
71
|
-
* honestly rather than trusting an unresolved spawn.
|
|
72
|
-
*
|
|
73
|
-
* @param {ReadonlyArray<{ bin: string, extraArgs: ReadonlyArray<string> }>} candidates
|
|
74
|
-
* @param {string} cwd
|
|
75
|
-
* @param {(p: string) => boolean} existsFn Injected for testing.
|
|
76
|
-
* @returns {{ bin: string, extraArgs: ReadonlyArray<string> }|null}
|
|
77
|
-
*/
|
|
78
|
-
function resolveRunner(candidates, cwd, existsFn) {
|
|
79
|
-
for (const candidate of candidates) {
|
|
80
|
-
const base = path.join(cwd, 'node_modules', '.bin', candidate.bin);
|
|
81
|
-
if (existsFn(base)) return candidate;
|
|
82
|
-
if (
|
|
83
|
-
process.platform === 'win32' &&
|
|
84
|
-
(existsFn(`${base}.cmd`) || existsFn(`${base}.ps1`))
|
|
85
|
-
) {
|
|
86
|
-
return candidate;
|
|
87
|
-
}
|
|
88
|
-
}
|
|
89
|
-
return null;
|
|
90
|
-
}
|
|
91
|
-
|
|
92
|
-
/**
|
|
93
|
-
* Zero counts with `executionFailed: true`, so it can never read as clean.
|
|
94
|
-
*
|
|
95
|
-
* @returns {ReturnType<typeof parseLintOutput>}
|
|
96
|
-
*/
|
|
97
|
-
function unresolvedRunnerSummary() {
|
|
98
|
-
return {
|
|
99
|
-
errors: 0,
|
|
100
|
-
warnings: 0,
|
|
101
|
-
parsed: false,
|
|
102
|
-
executionFailed: true,
|
|
103
|
-
emptyScope: false,
|
|
104
|
-
reason: DEGRADATION_REASONS.RUNNER_NOT_INSTALLED,
|
|
105
|
-
};
|
|
106
|
-
}
|
|
107
|
-
|
|
108
|
-
/**
|
|
109
|
-
* Resolve one surface's runner and, only if it resolved, spawn and classify it.
|
|
110
|
-
*
|
|
111
|
-
* @param {{
|
|
112
|
-
* label: string,
|
|
113
|
-
* candidates: ReadonlyArray<{ bin: string, extraArgs: ReadonlyArray<string> }>,
|
|
114
|
-
* buildArgs: (runner: { bin: string, extraArgs: ReadonlyArray<string> }) => string[],
|
|
115
|
-
* cwd: string,
|
|
116
|
-
* runnerFn: typeof spawnLintRunner,
|
|
117
|
-
* existsFn: (p: string) => boolean,
|
|
118
|
-
* }} args
|
|
119
|
-
* @returns {{ surface: string, summary: ReturnType<typeof parseLintOutput> }}
|
|
120
|
-
*/
|
|
121
|
-
function runSurface({ label, candidates, buildArgs, cwd, runnerFn, existsFn }) {
|
|
122
|
-
const runner = resolveRunner(candidates, cwd, existsFn);
|
|
123
|
-
if (runner === null) {
|
|
124
|
-
return { surface: label, summary: unresolvedRunnerSummary() };
|
|
125
|
-
}
|
|
126
|
-
return {
|
|
127
|
-
surface: runner.bin,
|
|
128
|
-
summary: parseLintOutput(runnerFn(runner.bin, buildArgs(runner), cwd)),
|
|
129
|
-
};
|
|
130
|
-
}
|
|
131
|
-
|
|
132
|
-
/**
|
|
133
|
-
* @param {string[]} changedFiles
|
|
134
|
-
* @returns {{ code: string[], md: string[] }}
|
|
135
|
-
*/
|
|
136
|
-
export function partitionFilesForLint(changedFiles) {
|
|
137
|
-
const code = [];
|
|
138
|
-
const md = [];
|
|
139
|
-
for (const f of changedFiles) {
|
|
140
|
-
if (CODE_EXTENSIONS.test(f)) code.push(f);
|
|
141
|
-
else if (/\.md$/i.test(f)) md.push(f);
|
|
142
|
-
}
|
|
143
|
-
return { code, md };
|
|
144
|
-
}
|
|
145
|
-
|
|
146
|
-
/**
|
|
147
|
-
* A non-zero exit matching no reporter format is `executionFailed`, except
|
|
148
|
-
* biome's empty-scope exit.
|
|
149
|
-
*
|
|
150
|
-
* @param {{ status?: number, stdout?: string, stderr?: string }} result
|
|
151
|
-
* @returns {{ errors: number, warnings: number, parsed: boolean, executionFailed: boolean, emptyScope: boolean, reason: string|null }}
|
|
152
|
-
*/
|
|
153
|
-
export function parseLintOutput(result) {
|
|
154
|
-
const combined = `${result.stdout ?? ''}\n${result.stderr ?? ''}`;
|
|
155
|
-
|
|
156
|
-
let errors = 0;
|
|
157
|
-
let warnings = 0;
|
|
158
|
-
let parsed = false;
|
|
159
|
-
|
|
160
|
-
for (const m of combined.matchAll(/Found\s+(\d+)\s+error/gi)) {
|
|
161
|
-
errors += Number(m[1]);
|
|
162
|
-
parsed = true;
|
|
163
|
-
}
|
|
164
|
-
for (const m of combined.matchAll(/Found\s+(\d+)\s+warning/gi)) {
|
|
165
|
-
warnings += Number(m[1]);
|
|
166
|
-
parsed = true;
|
|
167
|
-
}
|
|
168
|
-
const mdSummary = combined.match(/Summary:\s+(\d+)\s+error/i);
|
|
169
|
-
if (mdSummary) {
|
|
170
|
-
errors += Number(mdSummary[1]);
|
|
171
|
-
parsed = true;
|
|
172
|
-
}
|
|
173
|
-
|
|
174
|
-
const failedExit = !parsed && (result.status ?? 0) !== 0;
|
|
175
|
-
const emptyScope = failedExit && BIOME_EMPTY_SCOPE.test(combined);
|
|
176
|
-
const executionFailed = failedExit && !emptyScope;
|
|
177
|
-
const reason = executionFailed
|
|
178
|
-
? NPX_UNRESOLVABLE.test(combined)
|
|
179
|
-
? DEGRADATION_REASONS.RUNNER_NOT_RESOLVABLE
|
|
180
|
-
: DEGRADATION_REASONS.UNPARSEABLE_OUTPUT
|
|
181
|
-
: null;
|
|
182
|
-
|
|
183
|
-
return { errors, warnings, parsed, executionFailed, emptyScope, reason };
|
|
184
|
-
}
|
|
185
|
-
|
|
186
|
-
/**
|
|
187
|
-
* Counts add and `executionFailed` is the OR; `surfaces[]` keeps what the
|
|
188
|
-
* lossy OR cannot answer.
|
|
189
|
-
*
|
|
190
|
-
* @param {Array<{ surface: string, summary: ReturnType<typeof parseLintOutput> }>} surfaces
|
|
191
|
-
*/
|
|
192
|
-
function mergeSurfaceSummaries(surfaces) {
|
|
193
|
-
const rows = surfaces.map(({ surface, summary }) => ({
|
|
194
|
-
surface,
|
|
195
|
-
parsed: summary.parsed,
|
|
196
|
-
errors: summary.errors,
|
|
197
|
-
warnings: summary.warnings,
|
|
198
|
-
executionFailed: summary.executionFailed,
|
|
199
|
-
reason: summary.reason ?? DEGRADATION_REASONS.UNPARSEABLE_OUTPUT,
|
|
200
|
-
}));
|
|
201
|
-
const total = (field) => rows.reduce((sum, row) => sum + row[field], 0);
|
|
202
|
-
|
|
203
|
-
return {
|
|
204
|
-
errors: total('errors'),
|
|
205
|
-
warnings: total('warnings'),
|
|
206
|
-
parsed: rows.some((row) => row.parsed),
|
|
207
|
-
executionFailed: rows.some((row) => row.executionFailed),
|
|
208
|
-
skipped: false,
|
|
209
|
-
mode: 'changed-only',
|
|
210
|
-
degradations: rows
|
|
211
|
-
.filter((row) => row.executionFailed)
|
|
212
|
-
.map(({ surface, reason }) => ({ surface, reason })),
|
|
213
|
-
surfaces: rows.map(({ reason, ...row }) => row),
|
|
214
|
-
};
|
|
215
|
-
}
|
|
216
|
-
|
|
217
|
-
/**
|
|
218
|
-
* @param {string[]} changedFiles
|
|
219
|
-
* @param {string} cwd
|
|
220
|
-
* @param {typeof spawnLintRunner} [runnerFn]
|
|
221
|
-
* @param {{ existsFn?: (p: string) => boolean }} [deps]
|
|
222
|
-
* @returns {{ errors: number, warnings: number, parsed: boolean, skipped: boolean, mode: 'changed-only'|'off', executionFailed: boolean, degradations: Array<{ surface: string, reason: string }>, surfaces: Array<{ surface: string, parsed: boolean, errors: number, warnings: number, executionFailed: boolean }> }}
|
|
223
|
-
*/
|
|
224
|
-
export function runScopedLint(
|
|
225
|
-
changedFiles,
|
|
226
|
-
cwd,
|
|
227
|
-
runnerFn = spawnLintRunner,
|
|
228
|
-
deps = {},
|
|
229
|
-
) {
|
|
230
|
-
const { existsFn = existsSync } = deps;
|
|
231
|
-
const { code, md } = partitionFilesForLint(changedFiles);
|
|
232
|
-
if (code.length === 0 && md.length === 0) {
|
|
233
|
-
return {
|
|
234
|
-
errors: 0,
|
|
235
|
-
warnings: 0,
|
|
236
|
-
parsed: false,
|
|
237
|
-
skipped: true,
|
|
238
|
-
mode: 'changed-only',
|
|
239
|
-
executionFailed: false,
|
|
240
|
-
degradations: [],
|
|
241
|
-
surfaces: [],
|
|
242
|
-
};
|
|
243
|
-
}
|
|
244
|
-
|
|
245
|
-
const surfaces = [];
|
|
246
|
-
if (code.length > 0) {
|
|
247
|
-
surfaces.push(
|
|
248
|
-
runSurface({
|
|
249
|
-
label: 'biome',
|
|
250
|
-
candidates: CODE_RUNNERS,
|
|
251
|
-
buildArgs: (runner) => ['lint', ...code, ...runner.extraArgs],
|
|
252
|
-
cwd,
|
|
253
|
-
runnerFn,
|
|
254
|
-
existsFn,
|
|
255
|
-
}),
|
|
256
|
-
);
|
|
257
|
-
}
|
|
258
|
-
if (md.length > 0) {
|
|
259
|
-
surfaces.push(
|
|
260
|
-
runSurface({
|
|
261
|
-
label: 'markdownlint',
|
|
262
|
-
candidates: MARKDOWN_RUNNERS,
|
|
263
|
-
buildArgs: (runner) => [...md, ...runner.extraArgs],
|
|
264
|
-
cwd,
|
|
265
|
-
runnerFn,
|
|
266
|
-
existsFn,
|
|
267
|
-
}),
|
|
268
|
-
);
|
|
269
|
-
}
|
|
270
|
-
|
|
271
|
-
return mergeSurfaceSummaries(surfaces);
|
|
272
|
-
}
|