mandrel 2.114.0 → 2.115.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 (28) hide show
  1. package/.agents/docs/agentrc-reference.json +1 -0
  2. package/.agents/docs/configuration.md +10 -4
  3. package/.agents/schemas/agentrc.schema.json +7 -1
  4. package/.agents/scripts/acceptance-eval.js +2 -2
  5. package/.agents/scripts/ceremony-derive.js +15 -2
  6. package/.agents/scripts/lib/baselines/crap-preview-scan.js +15 -8
  7. package/.agents/scripts/lib/baselines/crap-preview-touched.js +140 -0
  8. package/.agents/scripts/lib/baselines/crap-prune.js +86 -0
  9. package/.agents/scripts/lib/baselines/kinds/crap.js +12 -4
  10. package/.agents/scripts/lib/baselines/seat-missing.js +1 -1
  11. package/.agents/scripts/lib/config/gates/coverage.schema.js +1 -1
  12. package/.agents/scripts/lib/config/gates/crap.schema.js +7 -0
  13. package/.agents/scripts/lib/config/quality.js +3 -0
  14. package/.agents/scripts/lib/coverage-capture-delta.js +26 -3
  15. package/.agents/scripts/lib/coverage-capture-own-fix.js +35 -19
  16. package/.agents/scripts/lib/coverage-capture.js +62 -14
  17. package/.agents/scripts/lib/crap-engine.js +3 -5
  18. package/.agents/scripts/lib/crap-utils.js +12 -2
  19. package/.agents/scripts/lib/generated/agentrc-validator.js +2 -2
  20. package/.agents/scripts/lib/git-branch-lifecycle.js +2 -1
  21. package/.agents/scripts/lib/orchestration/handoff-gates.js +25 -8
  22. package/.agents/scripts/lib/orchestration/story-handoff.js +131 -41
  23. package/.agents/scripts/single-story-init.js +43 -5
  24. package/.agents/scripts/story-handoff.js +6 -2
  25. package/.agents/workflows/helpers/deliver-digest.md +3 -3
  26. package/.agents/workflows/helpers/deliver-reference.md +13 -4
  27. package/docs/CHANGELOG.md +13 -0
  28. package/package.json +1 -1
@@ -156,6 +156,7 @@
156
156
  "skipWhenUnchanged": true,
157
157
  "baselineJoin": false
158
158
  },
159
+ "previewScope": "file",
159
160
  "coveragePath": null
160
161
  },
161
162
  "maintainability": {
@@ -187,7 +187,7 @@ Everything `/mandrel-deliver` and `single-story-close` consume: worktree isolati
187
187
  | `quality.gates.coverage.ciRatchetCheck` | No | `string` \| `null` | `null` | Name of the consumer's CI check (check-run or status context) that runs `coverage-ratchet.js` on a deferred PR. Required by `suiteOfRecord: ci`; when set, confirm-merge holds `agent::done` on a PR carrying the `Coverage-deferred:` key line until this check is green on the PR head. Default `null`. |
188
188
  | `quality.gates.coverage.nonInputGlobs` | No | `array<string>` | `[]` | Repo-relative picomatch globs naming paths no test reads. A matching path is dropped from both sides of the coverage delta-refresh overlap check and from the re-measured set — a delta of only matching, baseline and coverage-directory paths restamps without a run — and from the overlap check of close's `test` delta re-credit (its incoming count and emptiness test are unchanged). It never changes the suite-input filter, the tree digest or stamp freshness. Default `[]`: nothing is built in, so Markdown counts as an input unless declared here. |
189
189
  | `quality.gates.coverage.captureHandlesConfigChanges` | No | `boolean` | `false` | Declares that the affected capture script, given `MANDREL_COVERAGE_BASE_REF`, widens its own selection when a coverage-determining config file (`package.json`, a lockfile, `tsconfig*.json`, a test-runner config) changes. When `true`, such a file in the coverage delta no longer refuses the delta refresh. Close's `test` delta re-credit refuses on a config file under either value. Default `false`. |
190
- | `quality.gates.coverage.ownFixDeltaMaxFiles` | No | `integer` | `0` | Opt-in own-fix delta refresh for `captureScope: affected`. `0` (default) keeps it off. `N >= 1` lets a delta that today's rule refuses for a Story overlap or a config file be re-measured as a delta when it splits, along HEAD's first-parent chain, into base-sync merges that pass today's rule and the Story's own non-merge commits touching at most `N` suite-input files, with no config file, no deleted or renamed suite input and no net line removal in a test file. Rows outside the delta can go stale high; validate against full captures before raising it. `10` is a reasonable start. |
190
+ | `quality.gates.coverage.ownFixDeltaMaxFiles` | No | `integer` | `0` | Opt-in own-fix delta refresh for `captureScope: affected`. `0` (default) keeps it off. `N >= 1` lets a delta that today's rule refuses for a Story overlap or a config file be re-measured as a delta when it splits, along HEAD's first-parent chain, into base-sync merges that pass today's rule and the Story's own non-merge commits touching at most `N` suite-input files, with no config file, no deleted or renamed suite input and no test file: a changed test moves the rows of sources mandrel cannot name, so it refuses the split. A red capture keeps the last green stamp for this split alone. Rows outside the delta can go stale in either direction; validate against full captures before raising it. `10` is a reasonable start. |
191
191
  | `quality.gates.crap` | No | `object` | — | CRAP (Change Risk Anti-Pattern) ratchet — per-method cyclomatic complexity joined against per-method coverage. |
192
192
  | `quality.gates.crap.enabled` | No | `boolean` | `true` | When false, the checker exits 0 with a skip line and the gate is reported as `skipped`, never omitted. |
193
193
  | `quality.gates.crap.baselinePath` | No | `string` | `"baselines/crap.json"` | Repo-root-relative path to the gate's committed baseline artifact. |
@@ -205,6 +205,7 @@ Everything `/mandrel-deliver` and `single-story-close` consume: worktree isolati
205
205
  | `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. |
206
206
  | `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. |
207
207
  | `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 default is `origin/<project.baseBranch>` (`origin/main` by default), so a local base branch that trails the remote cannot widen the set; a clone where that remote ref does not resolve falls back to the local base branch with a warning. |
208
+ | `quality.gates.crap.previewScope` | No | `"file"` \| `"touched-methods"` | `"file"` | What the CRAP preview judges in a changed file. `file` compares every method to its row. `touched-methods` compares only methods whose line range intersects a hunk of the diff against the base: other regressions print as informational rows and pass. New methods always face `newMethodCeiling`, and a method whose hunks cannot be read is judged. |
208
209
  | `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. Its capture stamp sits beside it, so it may share a directory with the coverage gate's artifact. |
209
210
  | `quality.gates.crap.captureScript` | No | `string` | — | `package.json` script (never a shell command) that writes the CRAP gate's OWN coverage artifact, spawned as `<pm> run <script>`. Valid only beside an own `coveragePath`: without one the CRAP gate reads the coverage gate's artifact, so this key is refused and `delivery.quality.gates.coverage.captureScript` runs. Unset beside an own `coveragePath`, it is the coverage gate's `captureScript`. |
210
211
  | `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. |
@@ -551,12 +552,17 @@ only when **every** guard holds:
551
552
  - the own part holds no coverage-determining config file;
552
553
  - the own part touches at most `N` suite-input paths in the delta;
553
554
  - no own commit deletes or renames a suite-input path;
554
- - no own-part test file (`*.test.*` / `*.spec.*`, or under a `tests`, `test`,
555
- `__tests__`, `spec` or `e2e` directory) has net line removals across
556
- `<commit>..HEAD`;
555
+ - the own part changes no test file (`*.test.*` / `*.spec.*`, or under a
556
+ `tests`, `test`, `__tests__`, `spec` or `e2e` directory): only the test
557
+ graph knows which sources a test reaches;
557
558
  - no own commit is reachable from `origin/<baseBranch>` (that would be a
558
559
  fast-forwarded base commit).
559
560
 
561
+ A red, killed or crashed capture restores the prior artifact and keeps the
562
+ last green stamp as a `.superseded` sibling. It never reads as fresh; it only
563
+ seeds this split, under the same guards, so the next own fix need not re-pay
564
+ the whole slice.
565
+
560
566
  An eligible plan logs `needs an own-fix delta refresh — re-measuring <k>
561
567
  file(s) changed since <sha> (<n> own file(s), <m> base file(s))` with
562
568
  verdict `own-fix-delta-refresh`. A refusal logs the ordinary `delta refresh
@@ -788,7 +788,7 @@
788
788
  "type": "integer",
789
789
  "minimum": 0,
790
790
  "maximum": 50,
791
- "description": "Opt-in own-fix delta refresh for `captureScope: affected`. `0` (default) keeps it off. `N >= 1` lets a delta that today's rule refuses for a Story overlap or a config file be re-measured as a delta when it splits, along HEAD's first-parent chain, into base-sync merges that pass today's rule and the Story's own non-merge commits touching at most `N` suite-input files, with no config file, no deleted or renamed suite input and no net line removal in a test file. Rows outside the delta can go stale high; validate against full captures before raising it. `10` is a reasonable start.",
791
+ "description": "Opt-in own-fix delta refresh for `captureScope: affected`. `0` (default) keeps it off. `N >= 1` lets a delta that today's rule refuses for a Story overlap or a config file be re-measured as a delta when it splits, along HEAD's first-parent chain, into base-sync merges that pass today's rule and the Story's own non-merge commits touching at most `N` suite-input files, with no config file, no deleted or renamed suite input and no test file: a changed test moves the rows of sources mandrel cannot name, so it refuses the split. A red capture keeps the last green stamp for this split alone. Rows outside the delta can go stale in either direction; validate against full captures before raising it. `10` is a reasonable start.",
792
792
  "default": 0
793
793
  }
794
794
  },
@@ -940,6 +940,12 @@
940
940
  },
941
941
  "additionalProperties": false
942
942
  },
943
+ "previewScope": {
944
+ "type": "string",
945
+ "enum": ["file", "touched-methods"],
946
+ "description": "What the CRAP preview judges in a changed file. `file` compares every method to its row. `touched-methods` compares only methods whose line range intersects a hunk of the diff against the base: other regressions print as informational rows and pass. New methods always face `newMethodCeiling`, and a method whose hunks cannot be read is judged.",
947
+ "default": "file"
948
+ },
943
949
  "coveragePath": {
944
950
  "type": ["string", "null"],
945
951
  "minLength": 1,
@@ -22,7 +22,7 @@ import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
22
22
  import path from 'node:path';
23
23
  import { fileURLToPath } from 'node:url';
24
24
  import { parseArgs } from 'node:util';
25
- import { deriveCeremony } from './ceremony-derive.js';
25
+ import { deriveCeremony, resolveDefaultBaseRef } from './ceremony-derive.js';
26
26
  import { runAsCli } from './lib/cli-utils.js';
27
27
  import { getDeliveryRouting } from './lib/config/delivery-routing.js';
28
28
  import { resolvedTempRoot } from './lib/config/temp-paths.js';
@@ -261,7 +261,7 @@ export async function initVerdictSkeleton({ storyId, cwd, config }, deps = {}) {
261
261
  }
262
262
  const ceremony = deriveCeremonyImpl({
263
263
  storyId,
264
- baseRef: config?.project?.baseBranch ?? 'main',
264
+ baseRef: resolveDefaultBaseRef({ config, cwd }),
265
265
  cwd,
266
266
  ceremonyProfile: getDeliveryRouting(config).ceremonyProfile,
267
267
  });
@@ -19,6 +19,7 @@ import { getDeliveryRouting } from './lib/config/delivery-routing.js';
19
19
  import { resolveConfig } from './lib/config-resolver.js';
20
20
  import { resolveCeremonyForRisk } from './lib/orchestration/ceremony-routing.js';
21
21
  import { computeChangeSet } from './lib/orchestration/change-set.js';
22
+ import { resolveSharedBaseRef } from './lib/orchestration/review-base-ref.js';
22
23
  import { deriveChangeLevel } from './lib/orchestration/review-depth.js';
23
24
 
24
25
  const USAGE = {
@@ -30,7 +31,7 @@ const USAGE = {
30
31
  ['--story <id>', 'Story issue number; the head ref is story-<id>.'],
31
32
  [
32
33
  '--base <ref>',
33
- 'Base ref for the three-dot diff (default: project.baseBranch, normally main).',
34
+ 'Base ref for the three-dot diff (default: origin/<project.baseBranch>, else project.baseBranch).',
34
35
  ],
35
36
  [
36
37
  '--cwd <path>',
@@ -39,6 +40,18 @@ const USAGE = {
39
40
  ],
40
41
  };
41
42
 
43
+ /**
44
+ * The default change-set base: the remote ref handoff and close diff against,
45
+ * so a stale local base cannot score others' commits as the Story's.
46
+ *
47
+ * @param {{ config: object, cwd: string }} args
48
+ * @returns {string}
49
+ */
50
+ export function resolveDefaultBaseRef({ config, cwd }) {
51
+ const baseBranch = config?.project?.baseBranch ?? 'main';
52
+ return resolveSharedBaseRef({ baseBranch, cwd }).ref ?? baseBranch;
53
+ }
54
+
42
55
  /**
43
56
  * @param {string[]} argv
44
57
  * @returns {{ storyId: number|null, base: string|null, cwd: string|null }}
@@ -137,7 +150,7 @@ export async function runCeremonyDeriveCli(
137
150
  const envelope = deriveCeremony(
138
151
  {
139
152
  storyId,
140
- baseRef: base ?? config?.project?.baseBranch ?? 'main',
153
+ baseRef: base ?? resolveDefaultBaseRef({ config, cwd: workCwd }),
141
154
  cwd: workCwd,
142
155
  ceremonyProfile: getDeliveryRouting(config).ceremonyProfile,
143
156
  },
@@ -4,7 +4,6 @@
4
4
  */
5
5
 
6
6
  import path from 'node:path';
7
- import { COVERAGE_CAPTURE_DEFAULTS } from '../config/gates/coverage.schema.js';
8
7
  import { loadCoverage } from '../coverage-utils.js';
9
8
  import {
10
9
  KERNEL_VERSION,
@@ -13,6 +12,12 @@ import {
13
12
  } from '../crap-utils.js';
14
13
  import { CYCLOMATIC_CEILING } from '../cyclomatic-ceiling.js';
15
14
  import { resolveCrapPreviewIncremental } from './crap-preview-incremental.js';
15
+ import {
16
+ outsideDiffDiagnostics,
17
+ previewCoveragePath,
18
+ previewNotRun,
19
+ resolveIsJudged,
20
+ } from './crap-preview-touched.js';
16
21
  import { resolveCrapEnvOverrides } from './env-overrides.js';
17
22
  import {
18
23
  buildCrapReport,
@@ -57,12 +62,6 @@ export function listCyclomaticAdvisories(rows) {
57
62
  }));
58
63
  }
59
64
 
60
- function loadPreviewCoverage(crap, cwd) {
61
- const coveragePath =
62
- crap.coveragePath ?? COVERAGE_CAPTURE_DEFAULTS.coveragePath;
63
- return loadCoverage(path.resolve(cwd, coveragePath));
64
- }
65
-
66
65
  /**
67
66
  * @param {{
68
67
  * crap: object,
@@ -72,6 +71,7 @@ function loadPreviewCoverage(crap, cwd) {
72
71
  * diffRef: string|null,
73
72
  * baseline: { rows: object[] },
74
73
  * baseBranch?: string,
74
+ * git?: Function,
75
75
  * }} opts
76
76
  * @returns {Promise<{ exitCode: number, envelope: object }>}
77
77
  */
@@ -83,19 +83,22 @@ export async function computeCrapPreviewScan({
83
83
  diffRef,
84
84
  baseline,
85
85
  baseBranch,
86
+ git,
86
87
  }) {
87
88
  const targetDirs = Array.isArray(crap.targetDirs) ? crap.targetDirs : [];
88
89
  const crapIgnoreGlobs = Array.isArray(crap.ignoreGlobs)
89
90
  ? crap.ignoreGlobs
90
91
  : [];
91
92
  const requireCoverage = crap.requireCoverage !== false;
92
- const coverage = loadPreviewCoverage(crap, cwd);
93
93
  // The configured tolerance keeps the preview aligned with the authoritative
94
94
  // gate: deltas at or under it are demoted, not failed.
95
95
  const { newMethodCeiling, tolerance } = resolveCrapEnvOverrides(
96
96
  crap,
97
97
  process.env,
98
98
  );
99
+ const notRun = previewNotRun({ crap, targetDirs, cwd, scope, diffRef });
100
+ if (notRun) return notRun;
101
+ const coverage = loadCoverage(path.resolve(cwd, previewCoveragePath(crap)));
99
102
  const incremental = resolveCrapPreviewIncremental({
100
103
  crap,
101
104
  diffRef,
@@ -118,6 +121,7 @@ export async function computeCrapPreviewScan({
118
121
  baselineRows,
119
122
  newMethodCeiling,
120
123
  tolerance,
124
+ isJudged: resolveIsJudged({ crap, diffRef, baseBranch, cwd, git }),
121
125
  });
122
126
  const envelope = buildCrapReport({
123
127
  compareResult: result,
@@ -128,6 +132,9 @@ export async function computeCrapPreviewScan({
128
132
  scopeInfo: { scope, diffRef },
129
133
  });
130
134
  envelope.cyclomaticAdvisories = listCyclomaticAdvisories(scan.rows);
135
+ if (result.informational.length > 0) {
136
+ envelope.diagnostics = outsideDiffDiagnostics(result.informational);
137
+ }
131
138
  const exitCode = hasCrapRegressions(result) ? 1 : 0;
132
139
  return { exitCode, envelope };
133
140
  }
@@ -0,0 +1,140 @@
1
+ /**
2
+ * `crap.previewScope: touched-methods`: which regressions the preview judges,
3
+ * from the hunks of the diff against the base; and the preview's own absence
4
+ * when no fresh artifact exists.
5
+ */
6
+
7
+ import fs from 'node:fs';
8
+ import path from 'node:path';
9
+ import { COVERAGE_CAPTURE_DEFAULTS } from '../config/gates/coverage.schema.js';
10
+ import { COORDINATE_ORIGINAL } from '../crap-coordinates.js';
11
+ import { KERNEL_VERSION, resolveEscomplexVersion } from '../crap-utils.js';
12
+ import { gitSpawn } from '../git-utils.js';
13
+ import {
14
+ buildCrapReport,
15
+ compareCrap,
16
+ suppressVerdicts,
17
+ } from './kinds/crap.js';
18
+ import { isCaptureFresh } from './seat-missing.js';
19
+
20
+ export function previewCoveragePath(crap) {
21
+ return crap.coveragePath ?? COVERAGE_CAPTURE_DEFAULTS.coveragePath;
22
+ }
23
+
24
+ /** Why the artifact cannot be joined, or `null` when it matches the tree. */
25
+ function coverageAbsence(crap, targetDirs, cwd) {
26
+ const coveragePath = previewCoveragePath(crap);
27
+ if (isCaptureFresh({ coveragePath, targetDirs }, { cwd })) return null;
28
+ return fs.existsSync(path.resolve(cwd, coveragePath))
29
+ ? `${coveragePath} does not match the current tree`
30
+ : `no coverage artifact at ${coveragePath}`;
31
+ }
32
+
33
+ /** The verdict-free report of a preview that scored nothing. */
34
+ function notRunResult({ reason, scope, diffRef, newMethodCeiling }) {
35
+ const envelope = buildCrapReport({
36
+ compareResult: compareCrap({ currentRows: [], baselineRows: [] }),
37
+ kernelVersion: KERNEL_VERSION,
38
+ escomplexVersion: resolveEscomplexVersion(),
39
+ newMethodCeiling,
40
+ scopeInfo: { scope, diffRef },
41
+ });
42
+ const diagnostic = {
43
+ name: 'crap-coverage-not-fresh',
44
+ message: `CRAP half did not run: ${reason}`,
45
+ };
46
+ return { exitCode: 0, envelope: suppressVerdicts(envelope, diagnostic) };
47
+ }
48
+
49
+ /** The not-run result when no artifact matches the tree, else `null`. */
50
+ export function previewNotRun({ crap, targetDirs, cwd, scope, diffRef }) {
51
+ const reason = coverageAbsence(crap, targetDirs, cwd);
52
+ if (!reason) return null;
53
+ const { newMethodCeiling } = crap;
54
+ return notRunResult({ reason, scope, diffRef, newMethodCeiling });
55
+ }
56
+
57
+ /**
58
+ * New-side line ranges per file of a `-U0` diff. Hunk bodies are skipped by
59
+ * count, so an added line reading `+++ b/x` opens no file.
60
+ *
61
+ * @param {string} text
62
+ * @returns {Map<string, Array<[number, number]>>}
63
+ */
64
+ function parseDiffHunks(text) {
65
+ const hunks = new Map();
66
+ let ranges = null;
67
+ let body = 0;
68
+ for (const line of text.split(/\r?\n/)) {
69
+ if (body > 0) {
70
+ body -= 1;
71
+ continue;
72
+ }
73
+ if (line.startsWith('+++ ')) {
74
+ const file = /^\+\+\+ b\/(.+)$/.exec(line)?.[1];
75
+ ranges = file ? [] : null;
76
+ if (file) hunks.set(file, ranges);
77
+ continue;
78
+ }
79
+ const m = /^@@ -\d+(?:,(\d+))? \+(\d+)(?:,(\d+))? @@/.exec(line);
80
+ if (!m) continue;
81
+ const [removed, start, added] = [m[1] ?? 1, m[2], m[3] ?? 1].map(Number);
82
+ body = removed + added;
83
+ // A pure deletion names the line before it.
84
+ ranges?.push([start, start + Math.max(added - 1, 0)]);
85
+ }
86
+ return hunks;
87
+ }
88
+
89
+ /** The hunks of the diff from `ref`'s merge-base; `null` when unreadable. */
90
+ function readDiffHunks(ref, cwd, git) {
91
+ const base = git(cwd, 'merge-base', ref, 'HEAD');
92
+ if (base?.status !== 0) return null;
93
+ const diff = git(
94
+ cwd,
95
+ 'diff',
96
+ '-U0',
97
+ '--no-color',
98
+ '--no-ext-diff',
99
+ '--src-prefix=a/',
100
+ '--dst-prefix=b/',
101
+ String(base.stdout).trim(),
102
+ );
103
+ return diff?.status === 0 ? parseDiffHunks(String(diff.stdout)) : null;
104
+ }
105
+
106
+ /**
107
+ * The `compareCrap` predicate for `previewScope`. Fails closed: a row with
108
+ * no original-coordinate span, or a file with no readable hunks, is judged.
109
+ *
110
+ * @returns {((row: object) => boolean)|undefined}
111
+ */
112
+ export function resolveIsJudged({
113
+ crap,
114
+ diffRef,
115
+ baseBranch,
116
+ cwd,
117
+ git = gitSpawn,
118
+ }) {
119
+ if (crap.previewScope !== 'touched-methods') return undefined;
120
+ const hunks = readDiffHunks(diffRef ?? `origin/${baseBranch}`, cwd, git);
121
+ if (!hunks) return undefined;
122
+ return (row) => {
123
+ const ranges = hunks.get(row.file);
124
+ if (
125
+ !ranges ||
126
+ row.coordinateSystem !== COORDINATE_ORIGINAL ||
127
+ !Number.isFinite(row.endLine)
128
+ ) {
129
+ return true;
130
+ }
131
+ return ranges.some(([s, e]) => s <= row.endLine && e >= row.startLine);
132
+ };
133
+ }
134
+
135
+ export function outsideDiffDiagnostics(informational) {
136
+ return informational.map((v) => ({
137
+ name: 'crap-regression-outside-diff',
138
+ message: `informational: ${v.file}::${v.method} crap ${v.crap.toFixed(2)} > baseline ${v.baseline.toFixed(2)}, outside this diff's hunks`,
139
+ }));
140
+ }
@@ -0,0 +1,86 @@
1
+ /**
2
+ * Stale-row prune for the CRAP baseline: statically derived, so it runs
3
+ * before any coverage exists.
4
+ */
5
+
6
+ import nodeFs from 'node:fs';
7
+ import path from 'node:path';
8
+ import { execFileCaptureAsync } from '../child-exec.js';
9
+ import { calculateCrapForSource, UNSCORABLE } from '../crap-engine.js';
10
+ import { methodStem } from '../crap-method-identity.js';
11
+ import { prepareSourceForScoring } from '../transpile.js';
12
+ import { assertEnvelope } from './envelope.js';
13
+ import { canonicalizeBaselinePath } from './path-canon.js';
14
+ import { readPriorState } from './refresh-service.js';
15
+ import { assertCrapPriorCurrent } from './seat-missing.js';
16
+ import { writeFile as writeEnvelopeFile } from './writer.js';
17
+
18
+ /** The branch's changed files, both sides of a rename. */
19
+ async function changedFiles({ baseRef, headRef, cwd }) {
20
+ const { stdout } = await execFileCaptureAsync(
21
+ 'git',
22
+ ['diff', '--name-only', '--no-renames', `${baseRef}...${headRef}`],
23
+ { cwd },
24
+ );
25
+ return stdout.split(/\r?\n/).filter((line) => line.trim().length > 0);
26
+ }
27
+
28
+ /**
29
+ * The method stems a source file yields now: empty for a deleted file,
30
+ * `null` when it cannot be scored, so its rows are kept.
31
+ *
32
+ * @param {string} abs
33
+ * @param {typeof nodeFs} fs
34
+ * @returns {Set<string>|null}
35
+ */
36
+ function currentMethodStems(abs, fs) {
37
+ if (!fs.existsSync(abs)) return new Set();
38
+ const prepared = prepareSourceForScoring(abs);
39
+ if (prepared.error) return null;
40
+ const rows = calculateCrapForSource(prepared.code, null, prepared.mapLine);
41
+ if (rows === UNSCORABLE) return null;
42
+ return new Set(rows.map((row) => methodStem(row.method)));
43
+ }
44
+
45
+ /** Prior rows minus each change-set file's rows whose stem no longer exists. */
46
+ function withoutStaleRows(rows, changed, stemsOf) {
47
+ const stems = new Map();
48
+ return rows.filter((row) => {
49
+ if (!changed.has(row.path)) return true;
50
+ if (!stems.has(row.path)) stems.set(row.path, stemsOf(row.path));
51
+ return stems.get(row.path)?.has(methodStem(row.method)) ?? true;
52
+ });
53
+ }
54
+
55
+ /**
56
+ * Drop the CRAP rows of change-set files whose method no longer exists.
57
+ * Siblings collapse by stem, so a surviving namesake keeps the row.
58
+ *
59
+ * @param {{writePath: string, baseRef: string, headRef?: string, cwd?: string,
60
+ * gitDiff?: Function, fs?: typeof nodeFs}} opts
61
+ * @returns {Promise<{pruned: number}>}
62
+ */
63
+ export async function pruneStaleCrapRows({
64
+ writePath,
65
+ baseRef,
66
+ headRef = 'HEAD',
67
+ cwd = process.cwd(),
68
+ gitDiff = changedFiles,
69
+ fs = nodeFs,
70
+ }) {
71
+ const { envelope, ahead } = readPriorState(writePath, fs, 'crap');
72
+ if (ahead || !envelope) return { pruned: 0 };
73
+ assertCrapPriorCurrent('crap', envelope);
74
+ const changed = new Set(
75
+ (await gitDiff({ baseRef, headRef, cwd })).map(canonicalizeBaselinePath),
76
+ );
77
+ const rows = withoutStaleRows(envelope.rows, changed, (relPath) =>
78
+ currentMethodStems(path.resolve(cwd, relPath), fs),
79
+ );
80
+ const pruned = envelope.rows.length - rows.length;
81
+ if (pruned === 0) return { pruned };
82
+ const next = { ...envelope, rows };
83
+ assertEnvelope(next);
84
+ writeEnvelopeFile(writePath, next, { fsImpl: fs });
85
+ return { pruned };
86
+ }
@@ -264,19 +264,23 @@ export function checkCrapRegression(row, baseline, tolerance, kind) {
264
264
  * (`drifted`) instead of reporting them new and removed. Unpaired current
265
265
  * rows face the new-method ceiling; unpaired baseline rows are `removed`.
266
266
  * Unscorable rows (null crap/coverage) are bucketed and excluded from
267
- * `comparable` so they cannot dilute a ratio.
267
+ * `comparable` so they cannot dilute a ratio. A regression whose row
268
+ * `isJudged` rejects lands in `informational` and fails nothing.
268
269
  */
269
270
  export function compareCrap({
270
271
  currentRows,
271
272
  baselineRows,
272
273
  newMethodCeiling,
273
274
  tolerance,
275
+ isJudged = () => true,
274
276
  }) {
275
277
  const rows = currentRows ?? [];
276
278
  const state = {
277
279
  uncoveredFiles: deriveUncoveredFiles(currentRows),
278
280
  newMethodCeiling,
279
281
  tolerance: Number.isFinite(tolerance) ? tolerance : 0,
282
+ isJudged,
283
+ informational: [],
280
284
  claimed: new Set(),
281
285
  verdicts: new Array(rows.length).fill(null),
282
286
  regressions: 0,
@@ -314,6 +318,7 @@ export function compareCrap({
314
318
  unscorable: unscorableRows.length,
315
319
  removed: removedRows.length,
316
320
  violations: state.verdicts.filter((v) => v !== null),
321
+ informational: state.informational,
317
322
  unscorableRows,
318
323
  removedRows,
319
324
  };
@@ -322,10 +327,13 @@ export function compareCrap({
322
327
  /** Score one (current, baseline) pair into the verdict slot `idx`. */
323
328
  function scorePair(state, idx, row, baseline, kind) {
324
329
  const v = checkCrapRegression(row, baseline, state.tolerance, kind);
325
- if (v) {
326
- state.regressions += 1;
327
- state.verdicts[idx] = v;
330
+ if (!v) return;
331
+ if (!state.isJudged(row)) {
332
+ state.informational.push(v);
333
+ return;
328
334
  }
335
+ state.regressions += 1;
336
+ state.verdicts[idx] = v;
329
337
  }
330
338
 
331
339
  /** A current row with no baseline row: the new-method ceiling. */
@@ -153,7 +153,7 @@ function buildSeatedEnvelope({ kind, priorEnvelope, seated }) {
153
153
  }
154
154
 
155
155
  /** A behind CRAP baseline needs a full re-seed; seating would mix semantics. */
156
- function assertCrapPriorCurrent(kind, envelope) {
156
+ export function assertCrapPriorCurrent(kind, envelope) {
157
157
  if (kind !== 'crap' || !envelope) return;
158
158
  const stamp = envelope.scoringSemantics;
159
159
  if (classifyScoringSemantics(stamp) !== 'behind') return;
@@ -128,7 +128,7 @@ export const COVERAGE_GATE = {
128
128
  minimum: 0,
129
129
  maximum: 50,
130
130
  description:
131
- "Opt-in own-fix delta refresh for `captureScope: affected`. `0` (default) keeps it off. `N >= 1` lets a delta that today's rule refuses for a Story overlap or a config file be re-measured as a delta when it splits, along HEAD's first-parent chain, into base-sync merges that pass today's rule and the Story's own non-merge commits touching at most `N` suite-input files, with no config file, no deleted or renamed suite input and no net line removal in a test file. Rows outside the delta can go stale high; validate against full captures before raising it. `10` is a reasonable start.",
131
+ "Opt-in own-fix delta refresh for `captureScope: affected`. `0` (default) keeps it off. `N >= 1` lets a delta that today's rule refuses for a Story overlap or a config file be re-measured as a delta when it splits, along HEAD's first-parent chain, into base-sync merges that pass today's rule and the Story's own non-merge commits touching at most `N` suite-input files, with no config file, no deleted or renamed suite input and no test file: a changed test moves the rows of sources mandrel cannot name, so it refuses the split. A red capture keeps the last green stamp for this split alone. Rows outside the delta can go stale in either direction; validate against full captures before raising it. `10` is a reasonable start.",
132
132
  default: COVERAGE_GATE_DEFAULTS.ownFixDeltaMaxFiles,
133
133
  },
134
134
  },
@@ -49,6 +49,13 @@ export const CRAP_GATE = {
49
49
  default: [...CRAP_GATE_DEFAULTS.ignoreGlobs],
50
50
  },
51
51
  incrementalCoverage: INCREMENTAL_COVERAGE_SCHEMA,
52
+ previewScope: {
53
+ type: 'string',
54
+ enum: ['file', 'touched-methods'],
55
+ description:
56
+ 'What the CRAP preview judges in a changed file. `file` compares every method to its row. `touched-methods` compares only methods whose line range intersects a hunk of the diff against the base: other regressions print as informational rows and pass. New methods always face `newMethodCeiling`, and a method whose hunks cannot be read is judged.',
57
+ default: CRAP_GATE_DEFAULTS.previewScope,
58
+ },
52
59
  coveragePath: {
53
60
  type: ['string', 'null'],
54
61
  minLength: 1,
@@ -58,6 +58,7 @@ export const CRAP_GATE_DEFAULTS = Object.freeze({
58
58
  // Healthy runs resolve ~98%; a coordinate mismatch resolves 4–6%.
59
59
  minMethodResolutionRate: 0.75,
60
60
  incrementalCoverage: DEFAULT_INCREMENTAL_COVERAGE,
61
+ previewScope: 'file',
61
62
  });
62
63
 
63
64
  export const MAINTAINABILITY_GATE_DEFAULTS = Object.freeze({
@@ -86,6 +87,7 @@ const CRAP_GATE_KEYS = new Set([
86
87
  'incrementalCoverage',
87
88
  'coveragePath',
88
89
  'captureScript',
90
+ 'previewScope',
89
91
  ]);
90
92
 
91
93
  const COVERAGE_GATE_KEYS = new Set([
@@ -260,6 +262,7 @@ export function resolveMaintainabilityCrap(userCrap, coverageGate) {
260
262
  enabled: userCrap.enabled ?? defaults.enabled,
261
263
  targetDirs: resolveListValue(defaults.targetDirs, userCrap.targetDirs),
262
264
  newMethodCeiling: userCrap.newMethodCeiling ?? defaults.newMethodCeiling,
265
+ previewScope: userCrap.previewScope ?? defaults.previewScope,
263
266
  ...resolveCrapCoverageSource(userCrap, coverage),
264
267
  tolerance: toleranceScalar(
265
268
  userCrap.tolerance,
@@ -16,7 +16,7 @@ import {
16
16
  filterSuiteInputPaths,
17
17
  stampIsStale,
18
18
  } from './coverage-capture.js';
19
- import { judgeOwnFix } from './coverage-capture-own-fix.js';
19
+ import { judgeOwnFix, supersededSeed } from './coverage-capture-own-fix.js';
20
20
  import { gitSpawn } from './git-utils.js';
21
21
 
22
22
  /** Basenames whose change moves coverage beyond the files it names. */
@@ -268,6 +268,8 @@ function canRestamp(rule, delta) {
268
268
  return !delta.some(isCoverageConfigFile);
269
269
  }
270
270
 
271
+ const OWN_FIX_ONLY = 'a red run left only the own-fix split';
272
+
271
273
  /** Main's committed delta since the stamp, judged by the shared rule. */
272
274
  function classifyCommittedDelta({
273
275
  cwd,
@@ -318,8 +320,9 @@ function classifyDeltaRefresh({
318
320
  gitSpawnImpl: spawn = gitSpawn,
319
321
  readFileSync = fs.readFileSync,
320
322
  computeContentDigestImpl = computeContentDigest,
323
+ readStamp = readCaptureStamp,
321
324
  }) {
322
- const stamp = readCaptureStamp(cwd, crap.coveragePath, { readFileSync });
325
+ const stamp = readStamp(cwd, crap.coveragePath, { readFileSync });
323
326
  const no = (reason) => ({ eligible: false, reason, stamp });
324
327
  if (typeof stamp?.digest !== 'string') return no('no digest stamp');
325
328
  if (!stampStale({ stamp, cwd, crap, computeContentDigestImpl }))
@@ -377,7 +380,7 @@ function reportPlan(plan, crap, logger) {
377
380
  *
378
381
  * @returns {{ baseRef: string, dropFiles: string[], runCaptureImpl?: () => Promise<number> } | null}
379
382
  */
380
- export function planDeltaRefresh({
383
+ function planFromStamp({
381
384
  freshness,
382
385
  crap,
383
386
  coverage,
@@ -402,3 +405,23 @@ export function planDeltaRefresh({
402
405
  );
403
406
  return null;
404
407
  }
408
+
409
+ /** A superseded stamp seeds the own-fix split and no other delta. */
410
+ function classifySuperseded(stamp, opts) {
411
+ const plan = classifyDeltaRefresh({ ...opts, readStamp: () => stamp });
412
+ if (!plan.eligible || plan.ownFix) return plan;
413
+ return { ...plan, eligible: false, reason: OWN_FIX_ONLY };
414
+ }
415
+
416
+ /** @see planFromStamp; after a red run the plan also names the prior to merge. */
417
+ export function planDeltaRefresh(opts) {
418
+ const seed = supersededSeed(opts);
419
+ if (!seed) return planFromStamp(opts);
420
+ const plan = planFromStamp({
421
+ ...opts,
422
+ freshness: { reason: 'stale' },
423
+ prior: seed.prior,
424
+ classifyDeltaRefreshImpl: (o) => classifySuperseded(seed.stamp, o),
425
+ });
426
+ return plan && { ...plan, prior: seed.prior };
427
+ }