mandrel 2.88.0 → 2.89.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.
Files changed (29) hide show
  1. package/.agents/docs/agentrc-reference.json +3 -1
  2. package/.agents/docs/configuration.md +2 -0
  3. package/.agents/schemas/agentrc.schema.json +13 -0
  4. package/.agents/scripts/coverage-capture.js +32 -49
  5. package/.agents/scripts/lib/audit-baselines/gate-surface.js +24 -11
  6. package/.agents/scripts/lib/audit-baselines/read.js +4 -2
  7. package/.agents/scripts/lib/audit-baselines/surface-entry.js +95 -11
  8. package/.agents/scripts/lib/baselines/crap-preview-scan.js +3 -1
  9. package/.agents/scripts/lib/baselines/crap-updater-cli.js +2 -0
  10. package/.agents/scripts/lib/baselines/kinds/crap.js +37 -16
  11. package/.agents/scripts/lib/baselines/preview-gates.js +1 -0
  12. package/.agents/scripts/lib/close-validation/gates.js +40 -9
  13. package/.agents/scripts/lib/config/gates/crap.schema.js +15 -0
  14. package/.agents/scripts/lib/config/quality.js +49 -1
  15. package/.agents/scripts/lib/coverage-capture-affected.js +2 -1
  16. package/.agents/scripts/lib/coverage-capture-fullscope.js +2 -2
  17. package/.agents/scripts/lib/coverage-capture-incremental.js +1 -1
  18. package/.agents/scripts/lib/coverage-capture-passes.js +143 -0
  19. package/.agents/scripts/lib/coverage-capture-usage.js +1 -1
  20. package/.agents/scripts/lib/coverage-capture.js +30 -15
  21. package/.agents/scripts/lib/crap-utils.js +6 -2
  22. package/.agents/scripts/lib/generated/agentrc-validator.js +1 -1
  23. package/.agents/scripts/lib/maintainability-utils.js +6 -1
  24. package/.agents/scripts/lib/orchestration/check-baselines/phases/evaluate.js +1 -1
  25. package/.agents/scripts/lib/orchestration/verify-credit.js +4 -1
  26. package/.agents/scripts/update-crap-baseline.js +2 -2
  27. package/.agents/workflows/audit-baselines.md +7 -2
  28. package/docs/CHANGELOG.md +13 -0
  29. package/package.json +1 -1
@@ -152,7 +152,9 @@
152
152
  "incrementalCoverage": {
153
153
  "skipWhenUnchanged": true,
154
154
  "baselineJoin": false
155
- }
155
+ },
156
+ "coveragePath": null,
157
+ "captureScript": "test:coverage"
156
158
  },
157
159
  "maintainability": {
158
160
  "enabled": true,
@@ -191,6 +191,8 @@ Everything `/mandrel-deliver` and `single-story-close` consume: worktree isolati
191
191
  | `quality.gates.crap.incrementalCoverage.skipWhenUnchanged` | No | `boolean` | `true` | Skip the capture entirely when no changed file under `crap.targetDirs` versus `baseRef` was touched. The only measured saving, and gate-semantics-neutral. Defaults to true. |
192
192
  | `quality.gates.crap.incrementalCoverage.baselineJoin` | No | `boolean` | `false` | Let the CRAP join resolve a method in a file the diff did not touch from its committed baseline row instead of requiring fresh coverage for it. A gate loosening, not a saving — defaults to false. |
193
193
  | `quality.gates.crap.incrementalCoverage.baseRef` | No | `string` | — | Default git ref the changed-file set is computed against, for a caller that passes no `--ref`. A `--ref` the caller named wins over this value, so a caller that anchors another gate on the same ref — `.husky/pre-push`, which passes `--ref origin/main` and then previews `--changed-since origin/main` — resolves ONE scope for both steps (Story #5365). Omitted and unpassed, the gate’s own default `main` applies. |
194
+ | `quality.gates.crap.coveragePath` | No | `string` \| `null` | `null` | Repo-relative Istanbul `coverage-final.json` the CRAP gate joins against (Story #5717). `null` or unset falls back to `delivery.quality.gates.coverage.coveragePath`. When it differs from that path the CRAP gate has its OWN coverage source: `coverage-capture.js` refreshes it full-scope via `captureScript`, and the handoff seat, close preview and `update-crap-baseline.js` read it. It must live in a different directory from the coverage gate's artifact (the capture stamp is per directory); a same-directory path is refused at config resolution. |
195
+ | `quality.gates.crap.captureScript` | No | `string` | `"test:coverage"` | npm script name (run as `npm run <script>`, never a shell command) that writes the CRAP coverage artifact. Close registers the coverage-capture gate, and the capture refusal and credited-run probe key, on this script. |
194
196
  | `quality.gates.maintainability` | No | `object` | — | Maintainability-index ratchet. Scores per file as the average over its methods, so deleting a small high-MI method can legitimately lower a file’s score. |
195
197
  | `quality.gates.maintainability.enabled` | No | `boolean` | `true` | When false, the checker exits 0 with a skip line and the gate is reported as `skipped`, never omitted. |
196
198
  | `quality.gates.maintainability.baselinePath` | No | `string` | `"baselines/maintainability.json"` | Repo-root-relative path to the gate's committed baseline artifact. |
@@ -807,6 +807,19 @@
807
807
  }
808
808
  },
809
809
  "additionalProperties": false
810
+ },
811
+ "coveragePath": {
812
+ "type": ["string", "null"],
813
+ "minLength": 1,
814
+ "description": "Repo-relative Istanbul `coverage-final.json` the CRAP gate joins against (Story #5717). `null` or unset falls back to `delivery.quality.gates.coverage.coveragePath`. When it differs from that path the CRAP gate has its OWN coverage source: `coverage-capture.js` refreshes it full-scope via `captureScript`, and the handoff seat, close preview and `update-crap-baseline.js` read it. It must live in a different directory from the coverage gate's artifact (the capture stamp is per directory); a same-directory path is refused at config resolution.",
815
+ "default": null
816
+ },
817
+ "captureScript": {
818
+ "type": "string",
819
+ "minLength": 1,
820
+ "pattern": "^[A-Za-z0-9@:._/-]+$",
821
+ "description": "npm script name (run as `npm run <script>`, never a shell command) that writes the CRAP coverage artifact. Close registers the coverage-capture gate, and the capture refusal and credited-run probe key, on this script.",
822
+ "default": "test:coverage"
810
823
  }
811
824
  },
812
825
  "additionalProperties": false
@@ -6,6 +6,8 @@
6
6
  * `coverage.captureScope: "affected"`, the consumer's `test:coverage:affected`)
7
7
  * behind the host-level full-suite lock and stamp on success. A green run that
8
8
  * leaves no artifact at `coveragePath` fails (exit 1) and is never stamped.
9
+ * An own CRAP source gets a second, always full-scope pass via
10
+ * `crap.captureScript` (`lib/coverage-capture-passes.js`).
9
11
  *
10
12
  * `--require-credited` must stay an argument, never a config read: as policy
11
13
  * it also refused the depositing run, leaving no path that could deposit.
@@ -28,6 +30,10 @@ import {
28
30
  } from './lib/coverage-capture.js';
29
31
  import { tryScopedCapture } from './lib/coverage-capture-affected.js';
30
32
  import { runFullScopeCapture } from './lib/coverage-capture-fullscope.js';
33
+ import {
34
+ captureRefusal,
35
+ runCapturePasses,
36
+ } from './lib/coverage-capture-passes.js';
31
37
  import { handleCoverageCaptureHelp } from './lib/coverage-capture-usage.js';
32
38
  import { lockedCapture } from './lib/full-suite-lock.js';
33
39
  import { Logger } from './lib/Logger.js';
@@ -97,13 +103,8 @@ export async function runCoverageCapture(argv = process.argv, deps = {}) {
97
103
  const args = parseArgs(argv);
98
104
  const config = resolveConfigImpl({ cwd: args.cwd });
99
105
  const { crap, coverage } = getQualityImpl(config);
100
- const refused = refusal({
101
- crap,
102
- cwd: args.cwd,
103
- readPackageScriptsImpl,
104
- hasNpmScriptImpl,
105
- logger,
106
- });
106
+ const scripts = readPackageScriptsImpl(args.cwd);
107
+ const refused = captureRefusal({ crap, scripts, hasNpmScriptImpl, logger });
107
108
  if (refused !== null) return refused;
108
109
 
109
110
  // Outermost first: the credit probe announces or refuses the run, and only
@@ -114,25 +115,30 @@ export async function runCoverageCapture(argv = process.argv, deps = {}) {
114
115
  onLockProgress: lockHooks.onLockProgress,
115
116
  ...lockOptions,
116
117
  });
117
- const credited = artifactCheckedCapture(locked, {
118
- args,
119
- crap,
120
- existsSync: coverageArtifactExistsImpl,
121
- logger,
122
- });
123
118
  let timings = null;
124
- const capture = (captureOpts) =>
125
- credited({
126
- ...captureOpts,
127
- onTimings: (t) => {
128
- timings = t;
129
- },
119
+ const makeCapture = (source) => {
120
+ const credited = artifactCheckedCapture(locked, {
121
+ args,
122
+ source,
123
+ existsSync: coverageArtifactExistsImpl,
124
+ logger,
130
125
  });
131
- const code = await runCaptureScopes({
126
+ return (captureOpts) =>
127
+ credited({
128
+ ...captureOpts,
129
+ onTimings: (t) => {
130
+ timings = t;
131
+ },
132
+ });
133
+ };
134
+ const code = await runCapturePasses({
132
135
  crap,
133
136
  coverage,
134
137
  args,
135
- capture,
138
+ scripts,
139
+ hasNpmScriptImpl,
140
+ makeCapture,
141
+ runShared: runCaptureScopes,
136
142
  deps: {
137
143
  getChangedFilesImpl,
138
144
  isCoverageFreshImpl,
@@ -149,41 +155,18 @@ export async function runCoverageCapture(argv = process.argv, deps = {}) {
149
155
  }
150
156
 
151
157
  /**
152
- * The credited runner, failing a green run that wrote no artifact.
158
+ * The credited runner, failing a green run that wrote no artifact at the
159
+ * pass's source.
153
160
  *
154
161
  * @param {Function} locked
155
- * @param {{ args: object, crap: object, existsSync?: Function, logger: object }} opts
162
+ * @param {{ args: object, source: { coveragePath: string, script?: string, configKey?: string }, existsSync?: Function, logger: object }} opts
156
163
  * @returns {(opts: object) => Promise<number>}
157
164
  */
158
- function artifactCheckedCapture(locked, { args, crap, existsSync, logger }) {
165
+ function artifactCheckedCapture(locked, { args, source, existsSync, logger }) {
159
166
  return requireCaptureArtifact(
160
167
  creditedCapture(locked, { requireCredited: args.requireCredited, logger }),
161
- { cwd: args.cwd, coveragePath: crap.coveragePath, existsSync, logger },
162
- );
163
- }
164
-
165
- /** @returns {number|null} The exit code when no capture may run. */
166
- function refusal({
167
- crap,
168
- cwd,
169
- readPackageScriptsImpl,
170
- hasNpmScriptImpl,
171
- logger,
172
- }) {
173
- if (crap.enabled === false) {
174
- logger.info('[coverage-capture] CRAP gate disabled — skipping capture.');
175
- return 0;
176
- }
177
- if (hasNpmScriptImpl(readPackageScriptsImpl(cwd), 'test:coverage')) {
178
- return null;
179
- }
180
- // Name the fix rather than propagate npm's opaque "Missing script" exit.
181
- logger.error(
182
- '[coverage-capture] ✖ No "test:coverage" script in package.json. ' +
183
- 'Add one (e.g. "test:coverage": "node --test --experimental-test-coverage") ' +
184
- 'or disable the CRAP gate via delivery.quality.gates.crap.enabled=false.',
168
+ { ...source, cwd: args.cwd, existsSync, logger },
185
169
  );
186
- return 1;
187
170
  }
188
171
 
189
172
  function reportTimings(timings, logger, lockHooks) {
@@ -5,41 +5,54 @@
5
5
  */
6
6
 
7
7
  import path from 'node:path';
8
- import { ALL_KINDS, baselinePathFor, GATE_KINDS } from './kinds.js';
8
+ import { ALL_KINDS, baselinePathFor } from './kinds.js';
9
9
  import { listFilesUnder, readJsonFile } from './read.js';
10
- import { surfaceEntryFor } from './surface-entry.js';
10
+ import { scannerSkipDirsFor, surfaceEntryFor } from './surface-entry.js';
11
11
 
12
12
  /**
13
- * The file universe `ignoreGlobs` are checked against.
13
+ * One gate's declared `targetDirs`, deduplicated.
14
14
  *
15
15
  * @param {object | null | undefined} quality
16
+ * @param {string} kind
16
17
  * @returns {string[]}
17
18
  */
18
- function declaredTargetDirs(quality) {
19
+ function targetDirsOf(quality, kind) {
19
20
  const dirs = new Set();
20
- for (const kind of GATE_KINDS) {
21
- for (const dir of quality?.gates?.[kind]?.targetDirs ?? []) {
22
- if (typeof dir === 'string' && dir.length > 0) dirs.add(dir);
23
- }
21
+ for (const dir of quality?.gates?.[kind]?.targetDirs ?? []) {
22
+ if (typeof dir === 'string' && dir.length > 0) dirs.add(dir);
24
23
  }
25
24
  return [...dirs].sort();
26
25
  }
27
26
 
27
+ /**
28
+ * The files one gate's scanner could visit: its own `targetDirs`, walked with
29
+ * its own skip set.
30
+ *
31
+ * @param {string} cwd
32
+ * @param {object | null | undefined} quality
33
+ * @param {string} kind
34
+ * @returns {string[]}
35
+ */
36
+ function candidateFilesFor(cwd, quality, kind) {
37
+ const skip = scannerSkipDirsFor(kind);
38
+ return targetDirsOf(quality, kind).flatMap((dir) =>
39
+ listFilesUnder(cwd, dir, skip),
40
+ );
41
+ }
42
+
28
43
  /**
29
44
  * @param {{ cwd: string, quality: object, now?: Date, run?: Function }} args
30
45
  * @returns {{ entries: object[], baselines: Map<string, object|null> }}
31
46
  * `baselines` is carried forward so later sections never re-read from disk.
32
47
  */
33
48
  export function buildGateSurface({ cwd, quality, now = new Date(), run }) {
34
- const files = declaredTargetDirs(quality).flatMap((dir) =>
35
- listFilesUnder(cwd, dir),
36
- );
37
49
  const io = { cwd, run };
38
50
  const entries = [];
39
51
  const baselines = new Map();
40
52
  for (const kind of ALL_KINDS) {
41
53
  const relPath = baselinePathFor(kind, quality);
42
54
  const read = readJsonFile(path.resolve(cwd, relPath));
55
+ const files = candidateFilesFor(cwd, quality, kind);
43
56
  entries.push(
44
57
  surfaceEntryFor({ kind, quality, read, relPath, files, now, io }),
45
58
  );
@@ -33,10 +33,12 @@ export function readJsonFile(absolutePath) {
33
33
  /**
34
34
  * @param {string} repoRoot
35
35
  * @param {string} rootDir repo-relative directory to walk
36
+ * @param {Iterable<string>} [scannerSkip] directory names a gate's scanner
37
+ * never descends into, skipped on top of the lens's own cost guard
36
38
  * @returns {string[]} sorted repo-relative posix paths
37
39
  */
38
- export function listFilesUnder(repoRoot, rootDir) {
39
- const skip = new Set(['node_modules', '.git', '.worktrees']);
40
+ export function listFilesUnder(repoRoot, rootDir, scannerSkip = []) {
41
+ const skip = new Set(['node_modules', '.git', '.worktrees', ...scannerSkip]);
40
42
  const out = [];
41
43
  const walk = (abs) => {
42
44
  let entries;
@@ -6,6 +6,7 @@
6
6
  */
7
7
 
8
8
  import picomatch from 'picomatch';
9
+ import { IGNORED_DIRS } from '../maintainability-utils.js';
9
10
  import { GATE_KINDS, KIND_SPECS, measuredTotalOf, rollupOf } from './kinds.js';
10
11
  import { stalenessOf } from './staleness.js';
11
12
 
@@ -32,19 +33,98 @@ function isStubInstrument({ rowCount, rollup }) {
32
33
  return rowCount === 0 && isAllZeroRollup(rollup);
33
34
  }
34
35
 
36
+ /**
37
+ * Directory names each gate's own scanner never descends into. CRAP and
38
+ * maintainability share the `scanDirectory` walk; duplication runs jscpd with
39
+ * `gitignore: false` over its `targetDirs`, so it skips nothing. A kind absent
40
+ * here declares no `ignoreGlobs` and skips nothing.
41
+ *
42
+ * @type {Readonly<Record<string, ReadonlySet<string>>>}
43
+ */
44
+ const SCANNER_SKIP_DIRS = Object.freeze({
45
+ crap: IGNORED_DIRS,
46
+ maintainability: IGNORED_DIRS,
47
+ });
48
+
49
+ const NO_SKIP = new Set();
50
+
51
+ /**
52
+ * @param {string} kind
53
+ * @returns {ReadonlySet<string>}
54
+ */
55
+ export function scannerSkipDirsFor(kind) {
56
+ return SCANNER_SKIP_DIRS[kind] ?? NO_SKIP;
57
+ }
58
+
59
+ /**
60
+ * Generated or installed trees: absent from a fresh checkout, present after an
61
+ * install or build. A glob aimed at one is load-bearing whenever the gate's
62
+ * scanner would descend there, whatever is on disk today.
63
+ */
64
+ const GENERATED_TREE_DIRS = new Set([
65
+ 'node_modules',
66
+ 'dist',
67
+ 'build',
68
+ 'out',
69
+ 'coverage',
70
+ '.next',
71
+ ]);
72
+
73
+ const GLOB_META = /[*?[\]{}()!+@]/;
74
+
75
+ /**
76
+ * A glob is latent when one of its literal segments names a generated tree the
77
+ * scanner would walk into, so an empty match today is not evidence of death.
78
+ *
79
+ * @param {string} glob
80
+ * @param {ReadonlySet<string>} scannerSkipDirs
81
+ * @returns {boolean}
82
+ */
83
+ function isLatentGlob(glob, scannerSkipDirs) {
84
+ return glob
85
+ .split('/')
86
+ .some(
87
+ (segment) =>
88
+ !GLOB_META.test(segment) &&
89
+ GENERATED_TREE_DIRS.has(segment) &&
90
+ !scannerSkipDirs.has(segment),
91
+ );
92
+ }
93
+
94
+ /**
95
+ * @param {unknown} glob
96
+ * @param {ReadonlySet<string>} scannerSkipDirs
97
+ * @returns {boolean} a non-empty, non-latent glob string
98
+ */
99
+ function isJudgeableGlob(glob, scannerSkipDirs) {
100
+ return (
101
+ typeof glob === 'string' &&
102
+ glob.length > 0 &&
103
+ !isLatentGlob(glob, scannerSkipDirs)
104
+ );
105
+ }
106
+
107
+ /**
108
+ * @param {string} glob
109
+ * @param {string[]} files
110
+ * @returns {boolean}
111
+ */
112
+ function matchesNothing(glob, files) {
113
+ const isMatch = picomatch(glob, { dot: true });
114
+ return !files.some((f) => isMatch(f));
115
+ }
116
+
35
117
  /**
36
118
  * @param {string[]} ignoreGlobs
37
- * @param {string[]} files repo-relative posix paths
38
- * @returns {string[]} globs matching zero files
119
+ * @param {string[]} files repo-relative posix paths the gate's scanner walks
120
+ * @param {ReadonlySet<string>} scannerSkipDirs
121
+ * @returns {string[]} non-latent globs matching zero files
39
122
  */
40
- function findDeadIgnoreGlobs(ignoreGlobs, files) {
41
- const dead = [];
42
- for (const glob of ignoreGlobs ?? []) {
43
- if (typeof glob !== 'string' || glob.length === 0) continue;
44
- const isMatch = picomatch(glob, { dot: true });
45
- if (!files.some((f) => isMatch(f))) dead.push(glob);
46
- }
47
- return dead;
123
+ function findDeadIgnoreGlobs(ignoreGlobs, files, scannerSkipDirs) {
124
+ return (ignoreGlobs ?? []).filter(
125
+ (glob) =>
126
+ isJudgeableGlob(glob, scannerSkipDirs) && matchesNothing(glob, files),
127
+ );
48
128
  }
49
129
 
50
130
  /**
@@ -79,7 +159,11 @@ export function surfaceEntryFor({
79
159
  rowCount: rows.length,
80
160
  measured: measuredTotalOf(kind, baseline),
81
161
  ...stalenessOf({ kind, gateBlock, rows, relPath, baseline, now, io }),
82
- deadIgnoreGlobs: findDeadIgnoreGlobs(gateBlock?.ignoreGlobs, files),
162
+ deadIgnoreGlobs: findDeadIgnoreGlobs(
163
+ gateBlock?.ignoreGlobs,
164
+ files,
165
+ scannerSkipDirsFor(kind),
166
+ ),
83
167
  parseError,
84
168
  };
85
169
  }
@@ -122,7 +122,9 @@ export async function computeCrapPreviewScan({
122
122
  envelope.cyclomaticAdvisories = listCyclomaticAdvisories(scan.rows);
123
123
  // Above the drifted-row ratio every verdict is an artefact of a mis-keyed
124
124
  // join: say so once and fail open.
125
- const basis = assessComparisonBasis(result);
125
+ const basis = assessComparisonBasis(result, {
126
+ captureScript: crap.captureScript,
127
+ });
126
128
  if (!basis.sound) {
127
129
  return {
128
130
  exitCode: 0,
@@ -91,6 +91,7 @@ export function resolveCrapUpdaterOptions(
91
91
  minMethodResolutionRate:
92
92
  crap.minMethodResolutionRate ?? DEFAULT_MIN_RESOLUTION_RATE,
93
93
  coveragePath,
94
+ captureScript: crap.captureScript ?? 'test:coverage',
94
95
  baselinePath,
95
96
  absBaselinePath: path.isAbsolute(baselinePath)
96
97
  ? baselinePath
@@ -208,6 +209,7 @@ function buildCrapUpdaterScorer(
208
209
  const refusal = checkResolutionFloor(
209
210
  summary.resolution,
210
211
  options.minMethodResolutionRate,
212
+ options.captureScript,
211
213
  );
212
214
  if (refusal) throw new Error(refusal);
213
215
 
@@ -420,7 +420,7 @@ export const INCOMPATIBLE_BASELINE_DIAGNOSTIC = 'crap-baseline-incompatible';
420
420
  *
421
421
  * @param {{total?: number, comparable?: number, provenanceMismatched?: number,
422
422
  * incomparable?: number}} compareResult
423
- * @param {{ratio?: number, minSample?: number}} [opts]
423
+ * @param {{ratio?: number, minSample?: number, captureScript?: string}} [opts]
424
424
  */
425
425
  export function assessComparisonBasis(compareResult, opts = {}) {
426
426
  const ratio = Number.isFinite(opts.ratio)
@@ -451,7 +451,7 @@ export function assessComparisonBasis(compareResult, opts = {}) {
451
451
  'the same line coordinates, so every per-method verdict below would ' +
452
452
  'be derived from a mis-keyed join rather than from your change. ' +
453
453
  'They are suppressed.\n' +
454
- " Re-seed the baseline: run 'npm run test:coverage' then " +
454
+ ` Re-seed the baseline: run 'npm run ${captureScriptOf(opts)}' then ` +
455
455
  "'npm run crap:update -- --full-scope' and commit the result with a " +
456
456
  "'baseline-refresh:' subject. The authoritative check-baselines gate " +
457
457
  'still gates the merge.',
@@ -459,10 +459,27 @@ export function assessComparisonBasis(compareResult, opts = {}) {
459
459
  };
460
460
  }
461
461
 
462
- const RESEED_REMEDY =
463
- "Re-derive the baseline: run 'npm run test:coverage' then " +
464
- "'npm run crap:update -- --full-scope' and commit the result with a " +
465
- "'baseline-refresh:' subject.";
462
+ /**
463
+ * The CRAP capture script an operator hint names — the resolved
464
+ * `gates.crap.captureScript` when the caller passes it, else the default.
465
+ *
466
+ * @param {{ captureScript?: string } | undefined} ctx
467
+ * @returns {string}
468
+ */
469
+ function captureScriptOf(ctx) {
470
+ return typeof ctx?.captureScript === 'string' && ctx.captureScript.length > 0
471
+ ? ctx.captureScript
472
+ : 'test:coverage';
473
+ }
474
+
475
+ /** @param {{ captureScript?: string } | undefined} ctx */
476
+ function reseedRemedy(ctx) {
477
+ return (
478
+ `Re-derive the baseline: run 'npm run ${captureScriptOf(ctx)}' then ` +
479
+ "'npm run crap:update -- --full-scope' and commit the result with a " +
480
+ "'baseline-refresh:' subject."
481
+ );
482
+ }
466
483
 
467
484
  /**
468
485
  * Compat axes for `evaluateBaselineCompatibility`: `{ name, severity, check }`,
@@ -477,7 +494,7 @@ export const CRAP_COMPAT_AXES = [
477
494
  {
478
495
  name: 'scoring-semantics-drift',
479
496
  severity: 'fatal',
480
- check: ({ baseline }) => {
497
+ check: ({ baseline, captureScript }) => {
481
498
  if (!baseline) return null;
482
499
  const stamped = baseline.scoringSemantics ?? null;
483
500
  if (stamped === SCORING_SEMANTICS) return null;
@@ -485,14 +502,14 @@ export const CRAP_COMPAT_AXES = [
485
502
  `[CRAP] scoring semantics changed: baseline=${stamped ?? '<unstamped>'} ` +
486
503
  `running=${SCORING_SEMANTICS}. Rows scored by the previous per-method ` +
487
504
  'coverage join are not comparable to rows scored by the current one, ' +
488
- `so this baseline cannot be compared. ${RESEED_REMEDY}`
505
+ `so this baseline cannot be compared. ${reseedRemedy({ captureScript })}`
489
506
  );
490
507
  },
491
508
  },
492
509
  {
493
510
  name: 'ts-transpiler-drift',
494
511
  severity: 'fatal',
495
- check: ({ baseline, runningTsTranspilerVersion }) => {
512
+ check: ({ baseline, runningTsTranspilerVersion, captureScript }) => {
496
513
  if (!baseline) return null;
497
514
  if (!isKnownVersion(runningTsTranspilerVersion)) return null;
498
515
  const baselineTs = baseline.tsTranspilerVersion;
@@ -505,7 +522,7 @@ export const CRAP_COMPAT_AXES = [
505
522
  `[CRAP] tsTranspilerVersion changed: baseline=${baselineTs} running=${runningTsTranspilerVersion}. ` +
506
523
  "A TS row's startLine is an original-source coordinate only because the transpiler's " +
507
524
  'sourcemap said so, and that coordinate is half the row identity key — so rows scored ' +
508
- `under the previous transpiler are not comparable to rows scored under this one. ${RESEED_REMEDY}`
525
+ `under the previous transpiler are not comparable to rows scored under this one. ${reseedRemedy({ captureScript })}`
509
526
  );
510
527
  },
511
528
  },
@@ -515,7 +532,7 @@ export const CRAP_COMPAT_AXES = [
515
532
  // scoped to transpiled rows because pure-JS coordinates coincide.
516
533
  name: 'provenance-unstamped',
517
534
  severity: 'fatal',
518
- check: ({ baseline }) =>
535
+ check: ({ baseline, captureScript }) =>
519
536
  baseline &&
520
537
  baseline.provenanceStamped !== true &&
521
538
  hasTranspiledRows(baseline)
@@ -524,7 +541,7 @@ export const CRAP_COMPAT_AXES = [
524
541
  'asserts by omission that every row is an original-source coordinate. ' +
525
542
  '`startLine` is half the row identity key, so the comparator would ' +
526
543
  'key those rows against a coordinate space they are not in and ' +
527
- `report regressions no edit can satisfy. ${RESEED_REMEDY}`
544
+ `report regressions no edit can satisfy. ${reseedRemedy({ captureScript })}`
528
545
  : null,
529
546
  },
530
547
  {
@@ -534,7 +551,7 @@ export const CRAP_COMPAT_AXES = [
534
551
  // `anonymous` marker.
535
552
  name: 'anon-identity-unstamped',
536
553
  severity: 'fatal',
537
- check: ({ baseline }) => {
554
+ check: ({ baseline, captureScript }) => {
538
555
  if (!baseline) return null;
539
556
  const stale = (baseline.rows ?? []).filter(
540
557
  (row) => isAnonymousMethodLabel(row?.method) && row?.anonymous !== true,
@@ -547,7 +564,7 @@ export const CRAP_COMPAT_AXES = [
547
564
  'envelope claims the current scoring semantics. Those ordinals ' +
548
565
  'renumber whenever any anonymous function is added or removed, so the ' +
549
566
  'comparator would score the live methods against the new-method ' +
550
- `ceiling instead of their own baseline. ${RESEED_REMEDY}`
567
+ `ceiling instead of their own baseline. ${reseedRemedy({ captureScript })}`
551
568
  );
552
569
  },
553
570
  },
@@ -597,7 +614,7 @@ const LOADED_ENVELOPE_AXES = [
597
614
  *
598
615
  * @param {object|null} baseline A loaded v2 baseline envelope.
599
616
  * @param {{runningTsTranspilerVersion?: string, cwd?: string,
600
- * targetDirs?: string[]}} [ctx]
617
+ * targetDirs?: string[], captureScript?: string}} [ctx]
601
618
  * @returns {string|null} Operator-facing message, or null when compatible.
602
619
  */
603
620
  export function assertBaselineCompatible(baseline, ctx = {}) {
@@ -606,7 +623,11 @@ export function assertBaselineCompatible(baseline, ctx = {}) {
606
623
  ctx.runningTsTranspilerVersion ?? resolveTsTranspilerVersion(ctx);
607
624
  for (const name of LOADED_ENVELOPE_AXES) {
608
625
  const axis = CRAP_COMPAT_AXES.find((a) => a.name === name);
609
- const message = axis?.check({ baseline, runningTsTranspilerVersion });
626
+ const message = axis?.check({
627
+ baseline,
628
+ runningTsTranspilerVersion,
629
+ captureScript: ctx.captureScript,
630
+ });
610
631
  if (message) return message;
611
632
  }
612
633
  return null;
@@ -218,6 +218,7 @@ export async function runCrapPreview({
218
218
  const incompatible = assertBaselineCompatible(baseline, {
219
219
  cwd,
220
220
  targetDirs: crap.targetDirs,
221
+ captureScript: crap.captureScript,
221
222
  });
222
223
  if (incompatible) {
223
224
  return {
@@ -4,7 +4,11 @@ import { existsSync } from 'node:fs';
4
4
 
5
5
  import { _internals as baselineReaderInternals } from '../baselines/reader.js';
6
6
  import { getChangedFiles } from '../changed-files.js';
7
- import { COVERAGE_GATE_DEFAULTS, getQuality } from '../config/quality.js';
7
+ import {
8
+ COVERAGE_GATE_DEFAULTS,
9
+ CRAP_GATE_DEFAULTS,
10
+ getQuality,
11
+ } from '../config/quality.js';
8
12
  import { filterFilesUnderTargets } from '../coverage-capture.js';
9
13
  import { hasNpmScript, readPackageScripts } from '../npm-scripts.js';
10
14
  import { KNOWN_KINDS } from '../orchestration/check-baselines/phases/parse-args.js';
@@ -70,7 +74,22 @@ export function isCrapGateEnabled(config) {
70
74
  }
71
75
 
72
76
  /**
73
- * Coverage-capture registers when the CRAP gate is on AND a `test:coverage`
77
+ * The npm script that writes the CRAP coverage artifact —
78
+ * `gates.crap.captureScript`, default `test:coverage`. Read
79
+ * from the unresolved block for the same reason as {@link isCrapGateEnabled}.
80
+ *
81
+ * @param {object|undefined|null} config - Canonical resolved config.
82
+ * @returns {string}
83
+ */
84
+ function crapCaptureScript(config) {
85
+ const script = config?.delivery?.quality?.gates?.crap?.captureScript;
86
+ return typeof script === 'string' && script.trim().length > 0
87
+ ? script.trim()
88
+ : CRAP_GATE_DEFAULTS.captureScript;
89
+ }
90
+
91
+ /**
92
+ * Coverage-capture registers when the CRAP gate is on AND the CRAP capture
74
93
  * script exists; {@link resolveCreditedDepositor} builds on it.
75
94
  *
76
95
  * @param {object|undefined|null} config - Canonical resolved config.
@@ -78,7 +97,10 @@ export function isCrapGateEnabled(config) {
78
97
  * @returns {boolean}
79
98
  */
80
99
  function isCoverageCaptureActive(config, scripts) {
81
- return isCrapGateEnabled(config) && hasNpmScript(scripts, 'test:coverage');
100
+ return (
101
+ isCrapGateEnabled(config) &&
102
+ hasNpmScript(scripts, crapCaptureScript(config))
103
+ );
82
104
  }
83
105
 
84
106
  /**
@@ -341,10 +363,19 @@ function coverageCaptureRunsSuite({
341
363
 
342
364
  /**
343
365
  * Names every suite the capture can run: under `captureScope: "affected"` a
344
- * red may come from a delta refresh the base-sync triggered, not the Story.
366
+ * red may come from a delta refresh the base-sync triggered, not the Story;
367
+ * a non-default `gates.crap.captureScript` is named beside `test:coverage`.
368
+ *
369
+ * @param {string} captureScript The CRAP capture script ({@link crapCaptureScript}).
370
+ * @returns {string}
345
371
  */
346
- const COVERAGE_CAPTURE_HINT =
347
- 'Coverage capture failed — its suite run (`npm run test:coverage`, or `npm run test:coverage:affected` under `captureScope: "affected"`, including a delta refresh keyed on the stamped commit after a base-sync) exited non-zero. The coverage-capture log names which ran; fix the failing tests or coverage-threshold breaches, then re-run close.';
372
+ function coverageCaptureHint(captureScript) {
373
+ const crapScript =
374
+ captureScript === CRAP_GATE_DEFAULTS.captureScript
375
+ ? ''
376
+ : `, the CRAP gate's own \`npm run ${captureScript}\` (\`gates.crap.captureScript\`)`;
377
+ return `Coverage capture failed — its suite run (\`npm run test:coverage\`${crapScript}, or \`npm run test:coverage:affected\` under \`captureScope: "affected"\`, including a delta refresh keyed on the stamped commit after a base-sync) exited non-zero. The coverage-capture log names which ran; fix the failing tests or coverage-threshold breaches, then re-run close.`;
378
+ }
348
379
 
349
380
  const COVERAGE_CAPTURE_ARGS = Object.freeze([
350
381
  '.agents/scripts/coverage-capture.js',
@@ -407,8 +438,8 @@ export const GATE_TIMEOUT_HINT = `The gate outran the suite timeout (\`delivery.
407
438
  /**
408
439
  * Build the close-validation gate list, cheapest fast-fail first: typecheck →
409
440
  * lint → [test] → format → [quality-preview-mi] → [coverage-capture →
410
- * quality-preview-crap] → check-baselines. Coverage-capture registers only when CRAP is enabled AND a
411
- * `test:coverage` script exists; it then carries test-failure signalling and
441
+ * quality-preview-crap] → check-baselines. Coverage-capture registers only when CRAP is enabled AND its
442
+ * capture script (`gates.crap.captureScript`, default `test:coverage`) exists; it then carries test-failure signalling and
412
443
  * the plain `test` gate is dropped, so there is always exactly one test gate.
413
444
  *
414
445
  * @param {{ config?: object, baseBranch?: string, cwd?: string, packageScripts?: Record<string, string>, presentBaselines?: string[]|Set<string>, log?: (message: string) => void, getChangedFilesImpl?: typeof getChangedFiles }} [opts]
@@ -520,7 +551,7 @@ export function buildDefaultGates({
520
551
  name: 'coverage-capture',
521
552
  cmd: 'node',
522
553
  args: [...COVERAGE_CAPTURE_ARGS],
523
- hint: COVERAGE_CAPTURE_HINT,
554
+ hint: coverageCaptureHint(crapCaptureScript(config)),
524
555
  lockEventChannel: true,
525
556
  ...(captureSkipPredicted
526
557
  ? { skip: { reason: 'incremental-no-crap-changes' } }