mandrel 2.85.0 → 2.87.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/docs/agentrc-reference.json +2 -1
- package/.agents/docs/configuration.md +36 -14
- package/.agents/schemas/agentrc.schema.json +48 -9
- package/.agents/scripts/coverage-capture.js +23 -3
- package/.agents/scripts/evidence-gate.js +2 -2
- package/.agents/scripts/lib/baselines/bundle-size-scorer.js +115 -0
- package/.agents/scripts/lib/baselines/coverage-updater-cli.js +129 -28
- package/.agents/scripts/lib/baselines/crap-updater-cli.js +31 -10
- package/.agents/scripts/lib/baselines/duplication-scanner.js +25 -1
- package/.agents/scripts/lib/baselines/refresh-service.js +55 -19
- package/.agents/scripts/lib/close-validation/process.js +6 -0
- package/.agents/scripts/lib/close-validation/runner.js +22 -6
- package/.agents/scripts/lib/config/gates/coverage.schema.js +1 -1
- package/.agents/scripts/lib/config/gates/shared.js +1 -1
- package/.agents/scripts/lib/config/quality.js +6 -2
- package/.agents/scripts/lib/config-settings-schema-delivery.js +41 -2
- package/.agents/scripts/lib/coverage-baseline.js +7 -6
- package/.agents/scripts/lib/coverage-capture.js +44 -0
- package/.agents/scripts/lib/full-suite-lock.js +98 -38
- package/.agents/scripts/lib/full-suite-queue.js +45 -18
- package/.agents/scripts/lib/generated/agentrc-validator.js +1 -1
- package/.agents/scripts/lib/observability/source-classifier.js +1 -0
- package/.agents/scripts/lib/orchestration/check-baselines/phases/evaluate.js +29 -2
- package/.agents/scripts/lib/orchestration/story-handoff.js +19 -1
- package/.agents/scripts/lib/suite-admission.js +410 -0
- package/.agents/scripts/update-bundle-size-baseline.js +56 -0
- package/.agents/scripts/update-coverage-baseline.js +16 -41
- package/.agents/scripts/update-duplication-baseline.js +13 -3
- package/docs/CHANGELOG.md +14 -0
- package/package.json +7 -1
|
@@ -135,8 +135,10 @@ Everything `/mandrel-deliver` and `single-story-close` consume: worktree isolati
|
|
|
135
135
|
|
|
136
136
|
| Key | Required | Type | Default | Description |
|
|
137
137
|
| --- | --- | --- | --- | --- |
|
|
138
|
-
| `execution` | No | `object` | — | Serialization of the
|
|
139
|
-
| `execution.fullSuiteLock` | No | `boolean` | `true` | Serialize full-suite spawns (`npm test` / `npm run test:coverage`) behind a
|
|
138
|
+
| `execution` | No | `object` | — | Serialization and capacity admission of the suite spawns delivery drives. |
|
|
139
|
+
| `execution.fullSuiteLock` | No | `boolean` | `true` | Serialize full-suite spawns (`npm test` / `npm run test:coverage`) behind a repository-level advisory lock shared by every worktree, so two concurrent deliveries do not run two suites against the same cores (see `capacity` / `workloads` for declared runs that may overlap). The lock queues, it never overlaps: a wait that expires with a live holder spawns nothing and exits 75 (resumable), naming the holder. A dead or non-heartbeating holder is taken over, and a broken lockfile proceeds unserialized, so the lock can never fail a delivery. Set false — or export `MANDREL_FULL_SUITE_LOCK=0` for one invocation — to disable. |
|
|
140
|
+
| `execution.capacity` | No | `integer` | — | Story #5668. The admission budget, in weight units (CPU workers), shared by every suite spawn across this repository's worktrees and sessions — runs in other repositories on the host are not counted. Unset → the host's `os.availableParallelism()`. A declared workload is admitted while the live weights plus its own fit, strictly first-in-first-out: nothing overtakes an earlier live waiter, so a queued full suite is never starved. |
|
|
141
|
+
| `execution.workloads[]` | No | `array<object>` | `[]` | Story #5668. Suite commands declared safe to run alongside others. A spawn whose argv (whitespace-normalized) EXACTLY equals `command` takes that `weight` and `resources`; anything else — and every spawn when this list is empty, the default — runs exclusively (full capacity, today's serialization). Isolation is never inferred from a flag, prefix or diff size. `weight` must count the run's nested worker pool (`--workers 4` → 4), and a full suite needs its own entry before anything can overlap it. Two runs naming a common `resources` entry (a database fixture, a shared coverage file) never overlap; worktree-local outputs need none. A weight above `capacity` refuses the run with exit 78 — nothing spawns, no credit is recorded. An expired wait still exits 75, resumably. Scheduling never changes a run's credit identity. `MANDREL_FULL_SUITE_LOCK=0` (one invocation) or `fullSuiteLock: false` turns admission off entirely; reach for the env hatch only when you have checked the runs share nothing. Each item has: command, weight, resources. |
|
|
140
142
|
| `docsFreshness` | No | `object` | — | Documentation-freshness scope: the files a change of consequence is expected to touch. Read by the audit-documentation lens to seed its target set; no delivery gate enforces it. |
|
|
141
143
|
| `docsFreshness.paths` | No | `array<string>` | `["README.md"]` | Repo-relative documentation paths the audit-documentation lens adds to its target set. |
|
|
142
144
|
| `tempRetention` | No | `object` | — | Story #4794. Auto-purge of spent temp artifacts once their Story lands. Classification is an allowlist: only the declared classes below are ever deleted, so unrecognized files under tempRoot are reported with their size and left alone (`/clean-temp` is the operator path for them). signals.ndjson is never purged by any path. |
|
|
@@ -167,8 +169,8 @@ Everything `/mandrel-deliver` and `single-story-close` consume: worktree isolati
|
|
|
167
169
|
| `quality.gates.coverage.tolerance.kind` | Yes | `"absolute"` \| `"percent"` | — | Whether `value` is read as raw metric units (`absolute`) or as a percentage of the baseline (`percent`). |
|
|
168
170
|
| `quality.gates.coverage.tolerance.value` | Yes | `number` | — | The tolerance magnitude. 0 means no drift is allowed. |
|
|
169
171
|
| `quality.gates.coverage.floors` | No | `object<map>` | `{"*":{"lines":90,"branches":85,"functions":90}}` | Workspace-keyed absolute floors: `{ "<workspace>": { "<metric>": number } }`. `"*"` is the project-wide catch-all; the metric keyset is open so per-rollup keys flow through without each gate enumerating them. Floors are absolute — unlike `tolerance`, they are enforced regardless of the baseline. |
|
|
170
|
-
| `quality.gates.coverage.components` | No | `object<map>` | — | Per-gate component map — component name to the glob list whose
|
|
171
|
-
| `quality.gates.coverage.coveragePath` | No | `string` | `"coverage/coverage-final.json"` | Repo-relative path to the Istanbul `coverage-final.json` the capture step writes and the gate reads. |
|
|
172
|
+
| `quality.gates.coverage.components` | No | `object<map>` | — | Per-gate component map — component name to the glob list whose rows roll up under it (matched against the row key: the file path, or the bundle name for bundle-size). `check-baselines` reports one rollup per component that matches a row and holds it to `floors.<component>`, falling back to `floors["*"]`. Defaults to `{ "*": ["**"] }` at the resolver layer. |
|
|
173
|
+
| `quality.gates.coverage.coveragePath` | No | `string` | `"coverage/coverage-final.json"` | Repo-relative path to the Istanbul `coverage-final.json` the capture step writes and the gate reads. The capture contract: `npm run test:coverage` MUST write Istanbul per-file JSON (the `json` reporter) here — the coverage and CRAP refreshes both read it. A `json-summary` (`coverage-summary.json`) alone cannot feed them, so a green capture that leaves no file here fails and a full-scope refresh refuses to run. |
|
|
172
174
|
| `quality.gates.coverage.captureScope` | No | `"full"` \| `"affected"` | `"full"` | What coverage-capture runs. `full` (default) runs `npm run test:coverage`. `affected` runs the consumer-owned `npm run test:coverage:affected` with the base ref in `MANDREL_COVERAGE_BASE_REF`, merges its rows over the prior artifact and stamps it `affected`; baseline rows the scoped run did not measure are treated as unmeasured, never removed. Falls back to `full` with a warning when the script is absent. Meant for consumers whose CI already enforces coverage on the full suite. |
|
|
173
175
|
| `quality.gates.coverage.timeoutMs` | No | `integer` | `600000` | Kill bound (ms) for one full-suite run — the coverage capture, the close-validation full-suite gate and the full-suite lock-wait budget all read it. The clock starts at spawn, never while queued on the host lock; a suite that signals `MANDREL_SUITE_READY_FILE` gets a fresh bound for its test phase, so worst-case wall is lock wait + 2 × timeoutMs. On expiry the run exits 124 so callers can tell a hang from a failure. |
|
|
174
176
|
| `quality.gates.crap` | No | `object` | — | CRAP (Change Risk Anti-Pattern) ratchet — per-method cyclomatic complexity joined against per-method coverage. |
|
|
@@ -178,7 +180,7 @@ Everything `/mandrel-deliver` and `single-story-close` consume: worktree isolati
|
|
|
178
180
|
| `quality.gates.crap.tolerance.kind` | Yes | `"absolute"` \| `"percent"` | — | Whether `value` is read as raw metric units (`absolute`) or as a percentage of the baseline (`percent`). |
|
|
179
181
|
| `quality.gates.crap.tolerance.value` | Yes | `number` | — | The tolerance magnitude. 0 means no drift is allowed. |
|
|
180
182
|
| `quality.gates.crap.floors` | No | `object<map>` | `{"*":{"max":30,"p95":20,"methodsAbove20":50}}` | Workspace-keyed absolute floors: `{ "<workspace>": { "<metric>": number } }`. `"*"` is the project-wide catch-all; the metric keyset is open so per-rollup keys flow through without each gate enumerating them. Floors are absolute — unlike `tolerance`, they are enforced regardless of the baseline. |
|
|
181
|
-
| `quality.gates.crap.components` | No | `object<map>` | — | Per-gate component map — component name to the glob list whose
|
|
183
|
+
| `quality.gates.crap.components` | No | `object<map>` | — | Per-gate component map — component name to the glob list whose rows roll up under it (matched against the row key: the file path, or the bundle name for bundle-size). `check-baselines` reports one rollup per component that matches a row and holds it to `floors.<component>`, falling back to `floors["*"]`. Defaults to `{ "*": ["**"] }` at the resolver layer. |
|
|
182
184
|
| `quality.gates.crap.targetDirs` | No | `string[]` or `{ append?, prepend? }` | `["src"]` | Directories whose JS sources the CRAP gate scores. Mandrel ships a `src/`-centric default; projects whose executable code lives elsewhere (e.g. this repo's `.agents/scripts/`) override here. The framework default is intentionally not auto-discovered, so an override is the explicit, auditable signal. |
|
|
183
185
|
| `quality.gates.crap.newMethodCeiling` | No | `integer` | `30` | Hard CRAP ceiling applied to a method the diff introduces. A new method above it fails the gate regardless of the baseline. |
|
|
184
186
|
| `quality.gates.crap.requireCoverage` | No | `boolean` | `true` | When true, the gate refuses to score without a coverage artifact rather than silently reporting complexity-only rows. |
|
|
@@ -195,7 +197,7 @@ Everything `/mandrel-deliver` and `single-story-close` consume: worktree isolati
|
|
|
195
197
|
| `quality.gates.maintainability.tolerance.kind` | Yes | `"absolute"` \| `"percent"` | — | Whether `value` is read as raw metric units (`absolute`) or as a percentage of the baseline (`percent`). |
|
|
196
198
|
| `quality.gates.maintainability.tolerance.value` | Yes | `number` | — | The tolerance magnitude. 0 means no drift is allowed. |
|
|
197
199
|
| `quality.gates.maintainability.floors` | No | `object<map>` | `{"*":{"min":70}}` | Workspace-keyed absolute floors: `{ "<workspace>": { "<metric>": number } }`. `"*"` is the project-wide catch-all; the metric keyset is open so per-rollup keys flow through without each gate enumerating them. Floors are absolute — unlike `tolerance`, they are enforced regardless of the baseline. |
|
|
198
|
-
| `quality.gates.maintainability.components` | No | `object<map>` | — | Per-gate component map — component name to the glob list whose
|
|
200
|
+
| `quality.gates.maintainability.components` | No | `object<map>` | — | Per-gate component map — component name to the glob list whose rows roll up under it (matched against the row key: the file path, or the bundle name for bundle-size). `check-baselines` reports one rollup per component that matches a row and holds it to `floors.<component>`, falling back to `floors["*"]`. Defaults to `{ "*": ["**"] }` at the resolver layer. |
|
|
199
201
|
| `quality.gates.maintainability.targetDirs` | No | `string[]` or `{ append?, prepend? }` | `[]` | Directories whose JS sources the maintainability gate scores. Mandrel ships a `src/`-centric default; projects whose executable code lives elsewhere (e.g. this repo's `.agents/scripts/` plus `tests/`) override here. The framework default is intentionally not auto-discovered, so an override is the explicit, auditable signal. |
|
|
200
202
|
| `quality.gates.maintainability.ignoreGlobs` | No | `array<string>` | `[]` | Minimatch glob patterns matched against the canonicalised repo-relative path of each discovered file. Files matching any pattern are excluded from MI discovery before scoring. Orthogonal to `components` (grouping) — a file excluded here never appears in any component bucket. Absent or empty preserves the existing IGNORED_DIRS-only behaviour (Story #3217). |
|
|
201
203
|
| `quality.gates.mutation` | No | `object` | — | Stryker mutation-score ratchet. Off in practice for most consumers — the baseline kind is registered but no framework path runs Stryker. |
|
|
@@ -205,7 +207,7 @@ Everything `/mandrel-deliver` and `single-story-close` consume: worktree isolati
|
|
|
205
207
|
| `quality.gates.mutation.tolerance.kind` | Yes | `"absolute"` \| `"percent"` | — | Whether `value` is read as raw metric units (`absolute`) or as a percentage of the baseline (`percent`). |
|
|
206
208
|
| `quality.gates.mutation.tolerance.value` | Yes | `number` | — | The tolerance magnitude. 0 means no drift is allowed. |
|
|
207
209
|
| `quality.gates.mutation.floors` | No | `object<map>` | `{"*":{"score":60}}` | Workspace-keyed absolute floors: `{ "<workspace>": { "<metric>": number } }`. `"*"` is the project-wide catch-all; the metric keyset is open so per-rollup keys flow through without each gate enumerating them. Floors are absolute — unlike `tolerance`, they are enforced regardless of the baseline. |
|
|
208
|
-
| `quality.gates.mutation.components` | No | `object<map>` | — | Per-gate component map — component name to the glob list whose
|
|
210
|
+
| `quality.gates.mutation.components` | No | `object<map>` | — | Per-gate component map — component name to the glob list whose rows roll up under it (matched against the row key: the file path, or the bundle name for bundle-size). `check-baselines` reports one rollup per component that matches a row and holds it to `floors.<component>`, falling back to `floors["*"]`. Defaults to `{ "*": ["**"] }` at the resolver layer. |
|
|
209
211
|
| `quality.gates.bundle-size` | No | `object` | — | Built-artifact size ratchet for web targets. Off by default — it needs declared bundles. |
|
|
210
212
|
| `quality.gates.bundle-size.enabled` | No | `boolean` | `false` | When false, the checker exits 0 with a skip line and the gate is reported as `skipped`, never omitted. |
|
|
211
213
|
| `quality.gates.bundle-size.baselinePath` | No | `string` | `"baselines/bundle-size.json"` | Repo-root-relative path to the gate's committed baseline artifact. |
|
|
@@ -213,7 +215,7 @@ Everything `/mandrel-deliver` and `single-story-close` consume: worktree isolati
|
|
|
213
215
|
| `quality.gates.bundle-size.tolerance.kind` | Yes | `"absolute"` \| `"percent"` | — | Whether `value` is read as raw metric units (`absolute`) or as a percentage of the baseline (`percent`). |
|
|
214
216
|
| `quality.gates.bundle-size.tolerance.value` | Yes | `number` | — | The tolerance magnitude. 0 means no drift is allowed. |
|
|
215
217
|
| `quality.gates.bundle-size.floors` | No | `object<map>` | `{"*":{}}` | Workspace-keyed absolute floors: `{ "<workspace>": { "<metric>": number } }`. `"*"` is the project-wide catch-all; the metric keyset is open so per-rollup keys flow through without each gate enumerating them. Floors are absolute — unlike `tolerance`, they are enforced regardless of the baseline. |
|
|
216
|
-
| `quality.gates.bundle-size.components` | No | `object<map>` | — | Per-gate component map — component name to the glob list whose
|
|
218
|
+
| `quality.gates.bundle-size.components` | No | `object<map>` | — | Per-gate component map — component name to the glob list whose rows roll up under it (matched against the row key: the file path, or the bundle name for bundle-size). `check-baselines` reports one rollup per component that matches a row and holds it to `floors.<component>`, falling back to `floors["*"]`. Defaults to `{ "*": ["**"] }` at the resolver layer. |
|
|
217
219
|
| `quality.gates.bundle-size.bundles[]` | No | `array<object>` | `[]` | The artifacts to weigh. Empty means the gate has nothing to do. Each item has: name, path, limit. |
|
|
218
220
|
| `quality.gates.duplication` | No | `object` | — | Code-duplication (DRY) gate (Story #3664). Shares the gate base and adds the scan-scope extras: the `targetDirs` the duplication scanner walks, the jscpd `formats` it reads there, and `ignoreGlobs` to exclude files from the scan. |
|
|
219
221
|
| `quality.gates.duplication.enabled` | No | `boolean` | `false` | When false, the checker exits 0 with a skip line and the gate is reported as `skipped`, never omitted. |
|
|
@@ -222,7 +224,7 @@ Everything `/mandrel-deliver` and `single-story-close` consume: worktree isolati
|
|
|
222
224
|
| `quality.gates.duplication.tolerance.kind` | Yes | `"absolute"` \| `"percent"` | — | Whether `value` is read as raw metric units (`absolute`) or as a percentage of the baseline (`percent`). |
|
|
223
225
|
| `quality.gates.duplication.tolerance.value` | Yes | `number` | — | The tolerance magnitude. 0 means no drift is allowed. |
|
|
224
226
|
| `quality.gates.duplication.floors` | No | `object<map>` | `{"*":{"percentage":25}}` | Workspace-keyed absolute floors: `{ "<workspace>": { "<metric>": number } }`. `"*"` is the project-wide catch-all; the metric keyset is open so per-rollup keys flow through without each gate enumerating them. Floors are absolute — unlike `tolerance`, they are enforced regardless of the baseline. |
|
|
225
|
-
| `quality.gates.duplication.components` | No | `object<map>` | — | Per-gate component map — component name to the glob list whose
|
|
227
|
+
| `quality.gates.duplication.components` | No | `object<map>` | — | Per-gate component map — component name to the glob list whose rows roll up under it (matched against the row key: the file path, or the bundle name for bundle-size). `check-baselines` reports one rollup per component that matches a row and holds it to `floors.<component>`, falling back to `floors["*"]`. Defaults to `{ "*": ["**"] }` at the resolver layer. |
|
|
226
228
|
| `quality.gates.duplication.targetDirs` | No | `string[]` or `{ append?, prepend? }` | `["src"]` | Directories whose sources — the languages `formats` selects — the duplication (DRY) gate scans for copy-paste clones. Mandrel ships a `src/`-centric default; projects whose executable code lives elsewhere (e.g. this repo's `.agents/scripts/`) override here. The framework default is intentionally not auto-discovered, so an override is the explicit, auditable signal (Story #3664). |
|
|
227
229
|
| `quality.gates.duplication.formats` | No | `array<string>` | `["javascript","jsx","typescript","tsx"]` | jscpd format names the duplication (DRY) gate scans under `targetDirs`. The default covers JavaScript, JSX, TypeScript and TSX; jscpd's `javascript` format alone reads only `.js`/`.es`/`.es6`/`.mjs`/`.cjs`. Names are jscpd's own vocabulary and are not restricted here. Widening the set adds rows, so re-seat the baseline with `npm run duplication:reanchor` after changing it. |
|
|
228
230
|
| `quality.gates.duplication.ignoreGlobs` | No | `array<string>` | `[]` | Minimatch glob patterns matched against the canonicalised repo-relative path of each discovered file. Files matching any pattern are excluded from duplication discovery before scanning. Orthogonal to `components` (grouping). Absent or empty preserves the existing behaviour (Story #3664). |
|
|
@@ -361,10 +363,30 @@ A config still carrying the retired key is a hard validation failure; the
|
|
|
361
363
|
`enabled` / `baselinePath` / `tolerance` (`{ kind, value }`) /
|
|
362
364
|
`floors` (`{ <workspace>: { <metric>: <number> } }`) /
|
|
363
365
|
`components` (`{ <component>: [<glob>] }`). The `crap` / `maintainability` /
|
|
364
|
-
`duplication` `targetDirs` default `["src"]`.
|
|
365
|
-
|
|
366
|
-
|
|
366
|
+
`duplication` `targetDirs` default `["src"]`. `components` slices the floor
|
|
367
|
+
check: `check-baselines` reports one rollup per component that matches a
|
|
368
|
+
row and holds it to `floors.<component>` (else `floors["*"]`), so a
|
|
369
|
+
component below its floor breaches even when the whole-repo `*` rollup
|
|
370
|
+
passes. The `bundle-size` gate has **no** `refreshTag`: its baseline is
|
|
371
|
+
generated by `node .agents/scripts/update-bundle-size-baseline.js` (always a
|
|
372
|
+
full refresh, never a build), and an intentional growth is acknowledged with
|
|
373
|
+
the one-shot `BUNDLE_SIZE_REFRESH=1` env var, not a config knob
|
|
367
374
|
(see [`quality-gates.md` § Bundle-size ratchet](https://github.com/dsj1984/mandrel/blob/main/docs/quality-gates.md#bundle-size-ratchet--one-shot-refreshacknowledge-story-151)).
|
|
375
|
+
- **Coverage capture contract.** `npm run test:coverage` (and
|
|
376
|
+
`test:coverage:affected`) MUST write Istanbul per-file JSON — the `json`
|
|
377
|
+
reporter's `coverage-final.json` — at `quality.gates.coverage.coveragePath`.
|
|
378
|
+
That one artifact feeds both the coverage and the CRAP refresh; a
|
|
379
|
+
`json-summary` (`coverage-summary.json`) alone cannot. With c8, list
|
|
380
|
+
`json` in `reporter`; with Vitest or Jest, add `json` to the coverage
|
|
381
|
+
reporters. `coverage-capture.js` fails a green run that leaves no artifact
|
|
382
|
+
there (and writes no capture stamp), and a full-scope coverage or CRAP
|
|
383
|
+
refresh with no artifact exits non-zero naming the path.
|
|
384
|
+
- **Duplication needs jscpd.** The duplication gate scans with `jscpd` 4, an
|
|
385
|
+
**optional peer dependency** of `mandrel`: a project that enables
|
|
386
|
+
`quality.gates.duplication` installs it itself — `npm i -D jscpd@^4`.
|
|
387
|
+
Without it, `update-duplication-baseline.js` exits non-zero naming that
|
|
388
|
+
command; `check-baselines` evaluates the committed baseline and does not
|
|
389
|
+
need jscpd.
|
|
368
390
|
Extend the list-valued gate keys with the deep-merge extender form (see
|
|
369
391
|
[How to extend](#how-to-extend)).
|
|
370
392
|
|
|
@@ -502,9 +524,9 @@ the lint ratchet, and the CRAP/MI gates.
|
|
|
502
524
|
| --------------------------------- | ------------------------------------ | ---------------------------------------------------------------------- |
|
|
503
525
|
| `baselines/coverage.json` | `update-coverage-baseline.js` | `node .agents/scripts/update-coverage-baseline.js` |
|
|
504
526
|
| `baselines/crap.json` | `update-crap-baseline.js` | `npm run crap:update` |
|
|
505
|
-
| `baselines/duplication.json` | `update-duplication-baseline.js` | `node .agents/scripts/update-duplication-baseline.js`
|
|
527
|
+
| `baselines/duplication.json` | `update-duplication-baseline.js` | `node .agents/scripts/update-duplication-baseline.js` (needs `jscpd@^4` installed) |
|
|
506
528
|
| `baselines/maintainability.json` | `update-maintainability-baseline.js` | `npm run maintainability:update` |
|
|
507
|
-
| `baselines/bundle-size.json` |
|
|
529
|
+
| `baselines/bundle-size.json` | `update-bundle-size-baseline.js` | Build first, then `node .agents/scripts/update-bundle-size-baseline.js`; for an intentional growth, run the check with `BUNDLE_SIZE_REFRESH=1` (see [Bundle-size ratchet](https://github.com/dsj1984/mandrel/blob/main/docs/quality-gates.md#bundle-size-ratchet--one-shot-refreshacknowledge-story-151)) |
|
|
508
530
|
|
|
509
531
|
These files are the contract — read by every gate (Story close, push hook, CI)
|
|
510
532
|
and regenerated only via tagged `baseline-refresh:` commits with a non-empty
|
|
@@ -355,12 +355,51 @@
|
|
|
355
355
|
"properties": {
|
|
356
356
|
"execution": {
|
|
357
357
|
"type": "object",
|
|
358
|
-
"description": "Serialization of the
|
|
358
|
+
"description": "Serialization and capacity admission of the suite spawns delivery drives.",
|
|
359
359
|
"properties": {
|
|
360
360
|
"fullSuiteLock": {
|
|
361
361
|
"type": "boolean",
|
|
362
|
-
"description": "Serialize full-suite spawns (`npm test` / `npm run test:coverage`) behind a
|
|
362
|
+
"description": "Serialize full-suite spawns (`npm test` / `npm run test:coverage`) behind a repository-level advisory lock shared by every worktree, so two concurrent deliveries do not run two suites against the same cores (see `capacity` / `workloads` for declared runs that may overlap). The lock queues, it never overlaps: a wait that expires with a live holder spawns nothing and exits 75 (resumable), naming the holder. A dead or non-heartbeating holder is taken over, and a broken lockfile proceeds unserialized, so the lock can never fail a delivery. Set false — or export `MANDREL_FULL_SUITE_LOCK=0` for one invocation — to disable.",
|
|
363
363
|
"default": true
|
|
364
|
+
},
|
|
365
|
+
"capacity": {
|
|
366
|
+
"type": "integer",
|
|
367
|
+
"minimum": 1,
|
|
368
|
+
"description": "Story #5668. The admission budget, in weight units (CPU workers), shared by every suite spawn across this repository's worktrees and sessions — runs in other repositories on the host are not counted. Unset → the host's `os.availableParallelism()`. A declared workload is admitted while the live weights plus its own fit, strictly first-in-first-out: nothing overtakes an earlier live waiter, so a queued full suite is never starved."
|
|
369
|
+
},
|
|
370
|
+
"workloads": {
|
|
371
|
+
"type": "array",
|
|
372
|
+
"description": "Story #5668. Suite commands declared safe to run alongside others. A spawn whose argv (whitespace-normalized) EXACTLY equals `command` takes that `weight` and `resources`; anything else — and every spawn when this list is empty, the default — runs exclusively (full capacity, today's serialization). Isolation is never inferred from a flag, prefix or diff size. `weight` must count the run's nested worker pool (`--workers 4` → 4), and a full suite needs its own entry before anything can overlap it. Two runs naming a common `resources` entry (a database fixture, a shared coverage file) never overlap; worktree-local outputs need none. A weight above `capacity` refuses the run with exit 78 — nothing spawns, no credit is recorded. An expired wait still exits 75, resumably. Scheduling never changes a run's credit identity. `MANDREL_FULL_SUITE_LOCK=0` (one invocation) or `fullSuiteLock: false` turns admission off entirely; reach for the env hatch only when you have checked the runs share nothing.",
|
|
373
|
+
"items": {
|
|
374
|
+
"type": "object",
|
|
375
|
+
"required": ["command", "weight"],
|
|
376
|
+
"properties": {
|
|
377
|
+
"command": {
|
|
378
|
+
"type": "string",
|
|
379
|
+
"not": {
|
|
380
|
+
"pattern": "([;&|`]|\\$\\()"
|
|
381
|
+
},
|
|
382
|
+
"minLength": 1,
|
|
383
|
+
"description": "The exact suite argv, as `project.commands.test` spells it (or `npm run test:coverage` for coverage capture)."
|
|
384
|
+
},
|
|
385
|
+
"weight": {
|
|
386
|
+
"type": "integer",
|
|
387
|
+
"minimum": 1,
|
|
388
|
+
"description": "CPU workers the run occupies, including its nested pool."
|
|
389
|
+
},
|
|
390
|
+
"resources": {
|
|
391
|
+
"type": "array",
|
|
392
|
+
"uniqueItems": true,
|
|
393
|
+
"items": {
|
|
394
|
+
"type": "string",
|
|
395
|
+
"pattern": "^[a-z0-9][a-z0-9-]*$"
|
|
396
|
+
},
|
|
397
|
+
"description": "Names of shared resources this run needs exclusively."
|
|
398
|
+
}
|
|
399
|
+
},
|
|
400
|
+
"additionalProperties": false
|
|
401
|
+
},
|
|
402
|
+
"default": []
|
|
364
403
|
}
|
|
365
404
|
},
|
|
366
405
|
"additionalProperties": false
|
|
@@ -583,7 +622,7 @@
|
|
|
583
622
|
},
|
|
584
623
|
"components": {
|
|
585
624
|
"type": "object",
|
|
586
|
-
"description": "Per-gate component map — component name to the glob list whose
|
|
625
|
+
"description": "Per-gate component map — component name to the glob list whose rows roll up under it (matched against the row key: the file path, or the bundle name for bundle-size). `check-baselines` reports one rollup per component that matches a row and holds it to `floors.<component>`, falling back to `floors[\"*\"]`. Defaults to `{ \"*\": [\"**\"] }` at the resolver layer.",
|
|
587
626
|
"additionalProperties": {
|
|
588
627
|
"type": "array",
|
|
589
628
|
"items": {
|
|
@@ -598,7 +637,7 @@
|
|
|
598
637
|
"pattern": "([;&|`]|\\$\\()"
|
|
599
638
|
},
|
|
600
639
|
"minLength": 1,
|
|
601
|
-
"description": "Repo-relative path to the Istanbul `coverage-final.json` the capture step writes and the gate reads.",
|
|
640
|
+
"description": "Repo-relative path to the Istanbul `coverage-final.json` the capture step writes and the gate reads. The capture contract: `npm run test:coverage` MUST write Istanbul per-file JSON (the `json` reporter) here — the coverage and CRAP refreshes both read it. A `json-summary` (`coverage-summary.json`) alone cannot feed them, so a green capture that leaves no file here fails and a full-scope refresh refuses to run.",
|
|
602
641
|
"default": "coverage/coverage-final.json"
|
|
603
642
|
},
|
|
604
643
|
"captureScope": {
|
|
@@ -676,7 +715,7 @@
|
|
|
676
715
|
},
|
|
677
716
|
"components": {
|
|
678
717
|
"type": "object",
|
|
679
|
-
"description": "Per-gate component map — component name to the glob list whose
|
|
718
|
+
"description": "Per-gate component map — component name to the glob list whose rows roll up under it (matched against the row key: the file path, or the bundle name for bundle-size). `check-baselines` reports one rollup per component that matches a row and holds it to `floors.<component>`, falling back to `floors[\"*\"]`. Defaults to `{ \"*\": [\"**\"] }` at the resolver layer.",
|
|
680
719
|
"additionalProperties": {
|
|
681
720
|
"type": "array",
|
|
682
721
|
"items": {
|
|
@@ -823,7 +862,7 @@
|
|
|
823
862
|
},
|
|
824
863
|
"components": {
|
|
825
864
|
"type": "object",
|
|
826
|
-
"description": "Per-gate component map — component name to the glob list whose
|
|
865
|
+
"description": "Per-gate component map — component name to the glob list whose rows roll up under it (matched against the row key: the file path, or the bundle name for bundle-size). `check-baselines` reports one rollup per component that matches a row and holds it to `floors.<component>`, falling back to `floors[\"*\"]`. Defaults to `{ \"*\": [\"**\"] }` at the resolver layer.",
|
|
827
866
|
"additionalProperties": {
|
|
828
867
|
"type": "array",
|
|
829
868
|
"items": {
|
|
@@ -931,7 +970,7 @@
|
|
|
931
970
|
},
|
|
932
971
|
"components": {
|
|
933
972
|
"type": "object",
|
|
934
|
-
"description": "Per-gate component map — component name to the glob list whose
|
|
973
|
+
"description": "Per-gate component map — component name to the glob list whose rows roll up under it (matched against the row key: the file path, or the bundle name for bundle-size). `check-baselines` reports one rollup per component that matches a row and holds it to `floors.<component>`, falling back to `floors[\"*\"]`. Defaults to `{ \"*\": [\"**\"] }` at the resolver layer.",
|
|
935
974
|
"additionalProperties": {
|
|
936
975
|
"type": "array",
|
|
937
976
|
"items": {
|
|
@@ -998,7 +1037,7 @@
|
|
|
998
1037
|
},
|
|
999
1038
|
"components": {
|
|
1000
1039
|
"type": "object",
|
|
1001
|
-
"description": "Per-gate component map — component name to the glob list whose
|
|
1040
|
+
"description": "Per-gate component map — component name to the glob list whose rows roll up under it (matched against the row key: the file path, or the bundle name for bundle-size). `check-baselines` reports one rollup per component that matches a row and holds it to `floors.<component>`, falling back to `floors[\"*\"]`. Defaults to `{ \"*\": [\"**\"] }` at the resolver layer.",
|
|
1002
1041
|
"additionalProperties": {
|
|
1003
1042
|
"type": "array",
|
|
1004
1043
|
"items": {
|
|
@@ -1095,7 +1134,7 @@
|
|
|
1095
1134
|
},
|
|
1096
1135
|
"components": {
|
|
1097
1136
|
"type": "object",
|
|
1098
|
-
"description": "Per-gate component map — component name to the glob list whose
|
|
1137
|
+
"description": "Per-gate component map — component name to the glob list whose rows roll up under it (matched against the row key: the file path, or the bundle name for bundle-size). `check-baselines` reports one rollup per component that matches a row and holds it to `floors.<component>`, falling back to `floors[\"*\"]`. Defaults to `{ \"*\": [\"**\"] }` at the resolver layer.",
|
|
1099
1138
|
"additionalProperties": {
|
|
1100
1139
|
"type": "array",
|
|
1101
1140
|
"items": {
|
|
@@ -4,7 +4,8 @@
|
|
|
4
4
|
* when the gate is off, no changed file is under `crap.targetDirs`, or the
|
|
5
5
|
* content-digest stamp matches; otherwise run `test:coverage` (or, under
|
|
6
6
|
* `coverage.captureScope: "affected"`, the consumer's `test:coverage:affected`)
|
|
7
|
-
* behind the host-level full-suite lock and stamp on success.
|
|
7
|
+
* behind the host-level full-suite lock and stamp on success. A green run that
|
|
8
|
+
* leaves no artifact at `coveragePath` fails (exit 1) and is never stamped.
|
|
8
9
|
*
|
|
9
10
|
* `--require-credited` must stay an argument, never a config read: as policy
|
|
10
11
|
* it also refused the depositing run, leaving no path that could deposit.
|
|
@@ -21,6 +22,7 @@ import {
|
|
|
21
22
|
creditedCapture,
|
|
22
23
|
filterFilesUnderTargets,
|
|
23
24
|
isCoverageFresh,
|
|
25
|
+
requireCaptureArtifact,
|
|
24
26
|
runCapture,
|
|
25
27
|
writeCaptureStamp,
|
|
26
28
|
} from './lib/coverage-capture.js';
|
|
@@ -67,6 +69,7 @@ export function parseArgs(argv) {
|
|
|
67
69
|
* computeContentDigestImpl?: typeof computeContentDigest,
|
|
68
70
|
* writeCaptureStampImpl?: typeof writeCaptureStamp,
|
|
69
71
|
* filterFilesUnderTargetsImpl?: typeof filterFilesUnderTargets,
|
|
72
|
+
* coverageArtifactExistsImpl?: (absPath: string) => boolean,
|
|
70
73
|
* logger?: { info: Function, warn: Function, error: Function },
|
|
71
74
|
* lockOptions?: object,
|
|
72
75
|
* env?: Record<string, string|undefined>,
|
|
@@ -85,6 +88,7 @@ export async function runCoverageCapture(argv = process.argv, deps = {}) {
|
|
|
85
88
|
computeContentDigestImpl = computeContentDigest,
|
|
86
89
|
writeCaptureStampImpl = writeCaptureStamp,
|
|
87
90
|
filterFilesUnderTargetsImpl = filterFilesUnderTargets,
|
|
91
|
+
coverageArtifactExistsImpl,
|
|
88
92
|
logger = Logger,
|
|
89
93
|
lockOptions = {},
|
|
90
94
|
env = process.env,
|
|
@@ -110,8 +114,10 @@ export async function runCoverageCapture(argv = process.argv, deps = {}) {
|
|
|
110
114
|
onLockProgress: lockHooks.onLockProgress,
|
|
111
115
|
...lockOptions,
|
|
112
116
|
});
|
|
113
|
-
const credited =
|
|
114
|
-
|
|
117
|
+
const credited = artifactCheckedCapture(locked, {
|
|
118
|
+
args,
|
|
119
|
+
crap,
|
|
120
|
+
existsSync: coverageArtifactExistsImpl,
|
|
115
121
|
logger,
|
|
116
122
|
});
|
|
117
123
|
let timings = null;
|
|
@@ -142,6 +148,20 @@ export async function runCoverageCapture(argv = process.argv, deps = {}) {
|
|
|
142
148
|
return code;
|
|
143
149
|
}
|
|
144
150
|
|
|
151
|
+
/**
|
|
152
|
+
* The credited runner, failing a green run that wrote no artifact.
|
|
153
|
+
*
|
|
154
|
+
* @param {Function} locked
|
|
155
|
+
* @param {{ args: object, crap: object, existsSync?: Function, logger: object }} opts
|
|
156
|
+
* @returns {(opts: object) => Promise<number>}
|
|
157
|
+
*/
|
|
158
|
+
function artifactCheckedCapture(locked, { args, crap, existsSync, logger }) {
|
|
159
|
+
return requireCaptureArtifact(
|
|
160
|
+
creditedCapture(locked, { requireCredited: args.requireCredited, logger }),
|
|
161
|
+
{ cwd: args.cwd, coveragePath: crap.coveragePath, existsSync, logger },
|
|
162
|
+
);
|
|
163
|
+
}
|
|
164
|
+
|
|
145
165
|
/** @returns {number|null} The exit code when no capture may run. */
|
|
146
166
|
function refusal({
|
|
147
167
|
crap,
|
|
@@ -5,7 +5,7 @@
|
|
|
5
5
|
* passed for the current HEAD and tree, and recording a pass for the next
|
|
6
6
|
* caller. `--standalone` is required: it keys evidence by Story id, the same
|
|
7
7
|
* keyspace close consults, so worker-side verify[] runs credit the close.
|
|
8
|
-
* `--gate test`
|
|
8
|
+
* `--gate test` is admitted through the full-suite lock.
|
|
9
9
|
*/
|
|
10
10
|
|
|
11
11
|
import { spawnSync } from 'node:child_process';
|
|
@@ -232,7 +232,7 @@ export function runLockedSuite(
|
|
|
232
232
|
const lockHooks = lockEventHooks(claimLockEventSink(env));
|
|
233
233
|
return withFullSuiteLockAsync(
|
|
234
234
|
{
|
|
235
|
-
...fullSuiteLockPolicy(config, env),
|
|
235
|
+
...fullSuiteLockPolicy(config, env, [cmd, ...args]),
|
|
236
236
|
cwd,
|
|
237
237
|
log,
|
|
238
238
|
rerunCommand: ['node', ...process.argv.slice(1)].join(' '),
|
|
@@ -0,0 +1,115 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Default scorer for the bundle-size baseline: weigh each declared
|
|
3
|
+
* `gates['bundle-size'].bundles[]` artifact on disk. It never builds the
|
|
4
|
+
* project — the artifacts must already exist.
|
|
5
|
+
*
|
|
6
|
+
* Row shape (kinds/bundle-size.js): `{ bundle, rawKb, gzippedKb }`, where a
|
|
7
|
+
* bundle's size is the sum over every file its `path` glob matches.
|
|
8
|
+
*/
|
|
9
|
+
|
|
10
|
+
import nodeFs from 'node:fs';
|
|
11
|
+
import path from 'node:path';
|
|
12
|
+
import { gzipSync } from 'node:zlib';
|
|
13
|
+
import { Minimatch } from 'minimatch';
|
|
14
|
+
|
|
15
|
+
/** Directories a bundle glob never descends into. */
|
|
16
|
+
const SKIPPED_DIRS = new Set(['.git', 'node_modules']);
|
|
17
|
+
|
|
18
|
+
/**
|
|
19
|
+
* @param {number} bytes
|
|
20
|
+
* @returns {number} KB, two decimals.
|
|
21
|
+
*/
|
|
22
|
+
function toKb(bytes) {
|
|
23
|
+
return Number((bytes / 1024).toFixed(2));
|
|
24
|
+
}
|
|
25
|
+
|
|
26
|
+
/**
|
|
27
|
+
* The leading glob-free directory of a POSIX pattern — the walk root.
|
|
28
|
+
*
|
|
29
|
+
* @param {string[]} segments
|
|
30
|
+
* @returns {string}
|
|
31
|
+
*/
|
|
32
|
+
function staticBase(segments) {
|
|
33
|
+
const firstMagic = segments.findIndex((s) => /[*?[\]{}()!]/.test(s));
|
|
34
|
+
const base =
|
|
35
|
+
firstMagic === -1 ? segments.slice(0, -1) : segments.slice(0, firstMagic);
|
|
36
|
+
return base.join('/');
|
|
37
|
+
}
|
|
38
|
+
|
|
39
|
+
/**
|
|
40
|
+
* @param {string} absDir
|
|
41
|
+
* @param {typeof nodeFs} fs
|
|
42
|
+
* @returns {string[]} Absolute file paths under `absDir`.
|
|
43
|
+
*/
|
|
44
|
+
function walkFiles(absDir, fs) {
|
|
45
|
+
if (!fs.existsSync(absDir)) return [];
|
|
46
|
+
const out = [];
|
|
47
|
+
for (const entry of fs.readdirSync(absDir, { withFileTypes: true })) {
|
|
48
|
+
const abs = path.join(absDir, entry.name);
|
|
49
|
+
if (entry.isDirectory()) {
|
|
50
|
+
if (!SKIPPED_DIRS.has(entry.name)) out.push(...walkFiles(abs, fs));
|
|
51
|
+
} else if (entry.isFile()) {
|
|
52
|
+
out.push(abs);
|
|
53
|
+
}
|
|
54
|
+
}
|
|
55
|
+
return out;
|
|
56
|
+
}
|
|
57
|
+
|
|
58
|
+
/**
|
|
59
|
+
* Repo-relative files a bundle `path` (literal or glob) matches, sorted.
|
|
60
|
+
*
|
|
61
|
+
* @param {string} pattern
|
|
62
|
+
* @param {string} cwd
|
|
63
|
+
* @param {typeof nodeFs} fs
|
|
64
|
+
* @returns {string[]} Absolute paths.
|
|
65
|
+
*/
|
|
66
|
+
function resolveBundleFiles(pattern, cwd, fs = nodeFs) {
|
|
67
|
+
const posix = pattern.replace(/\\/g, '/').replace(/^\.\//, '');
|
|
68
|
+
const matcher = new Minimatch(posix, { dot: true });
|
|
69
|
+
if (!matcher.hasMagic()) {
|
|
70
|
+
const abs = path.resolve(cwd, posix);
|
|
71
|
+
return fs.existsSync(abs) && fs.statSync(abs).isFile() ? [abs] : [];
|
|
72
|
+
}
|
|
73
|
+
const base = staticBase(posix.split('/'));
|
|
74
|
+
return walkFiles(path.resolve(cwd, base), fs)
|
|
75
|
+
.filter((abs) =>
|
|
76
|
+
matcher.match(path.relative(cwd, abs).split(path.sep).join('/')),
|
|
77
|
+
)
|
|
78
|
+
.sort();
|
|
79
|
+
}
|
|
80
|
+
|
|
81
|
+
/**
|
|
82
|
+
* @param {{ name: string, path: string }} bundle
|
|
83
|
+
* @param {string} cwd
|
|
84
|
+
* @param {typeof nodeFs} fs
|
|
85
|
+
* @returns {{ bundle: string, rawKb: number, gzippedKb: number }}
|
|
86
|
+
*/
|
|
87
|
+
function measureBundle(bundle, cwd, fs) {
|
|
88
|
+
const files = resolveBundleFiles(bundle.path, cwd, fs);
|
|
89
|
+
if (files.length === 0) {
|
|
90
|
+
throw new Error(
|
|
91
|
+
`[bundle-size] declared bundle "${bundle.name}" matches no file at "${bundle.path}" — build the project before refreshing; an unbuilt artifact is never recorded as 0 KB.`,
|
|
92
|
+
);
|
|
93
|
+
}
|
|
94
|
+
let raw = 0;
|
|
95
|
+
let gzipped = 0;
|
|
96
|
+
for (const abs of files) {
|
|
97
|
+
const bytes = fs.readFileSync(abs);
|
|
98
|
+
raw += bytes.length;
|
|
99
|
+
gzipped += gzipSync(bytes).length;
|
|
100
|
+
}
|
|
101
|
+
return { bundle: bundle.name, rawKb: toKb(raw), gzippedKb: toKb(gzipped) };
|
|
102
|
+
}
|
|
103
|
+
|
|
104
|
+
/**
|
|
105
|
+
* @param {{ cwd: string, quality?: object, fs?: typeof nodeFs }} opts
|
|
106
|
+
* @returns {(files: string[], opts: object) => object[]}
|
|
107
|
+
*/
|
|
108
|
+
export function buildBundleSizeScorer({ cwd, quality, fs = nodeFs } = {}) {
|
|
109
|
+
const declared = quality?.gates?.['bundle-size']?.bundles;
|
|
110
|
+
const bundles = Array.isArray(declared) ? declared : [];
|
|
111
|
+
return (_files, opts) => {
|
|
112
|
+
const effectiveCwd = opts?.cwd ?? cwd ?? process.cwd();
|
|
113
|
+
return bundles.map((bundle) => measureBundle(bundle, effectiveCwd, fs));
|
|
114
|
+
};
|
|
115
|
+
}
|