mandrel 2.87.0 → 2.88.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 (156) hide show
  1. package/.agents/README.md +29 -0
  2. package/.agents/agents/auditor.md +4 -3
  3. package/.agents/docs/agentrc-reference.json +2 -1
  4. package/.agents/docs/configuration.md +12 -8
  5. package/.agents/docs/workflows.md +1 -1
  6. package/.agents/schemas/agentrc.schema.json +11 -5
  7. package/.agents/schemas/story-deliver-terminal.schema.json +1 -1
  8. package/.agents/schemas/story-progress.schema.json +5 -0
  9. package/.agents/scripts/audit-to-stories.js +3 -2
  10. package/.agents/scripts/boot-sweep.js +3 -2
  11. package/.agents/scripts/check-arch-cycles.js +19 -41
  12. package/.agents/scripts/check-context-budget.js +16 -44
  13. package/.agents/scripts/check-cyclomatic.js +13 -37
  14. package/.agents/scripts/check-dead-exports.js +16 -46
  15. package/.agents/scripts/clean-worktrees.js +1 -6
  16. package/.agents/scripts/deliver-run.js +11 -0
  17. package/.agents/scripts/diagnose-friction.js +3 -3
  18. package/.agents/scripts/lib/baselines/coverage-updater-cli.js +6 -14
  19. package/.agents/scripts/lib/baselines/crap-updater-cli.js +36 -26
  20. package/.agents/scripts/lib/baselines/duplication-scanner.js +20 -1
  21. package/.agents/scripts/lib/baselines/env-overrides.js +39 -34
  22. package/.agents/scripts/lib/baselines/kernel.js +3 -2
  23. package/.agents/scripts/lib/baselines/kinds/crap.js +14 -38
  24. package/.agents/scripts/lib/baselines/preview-gates.js +4 -1
  25. package/.agents/scripts/lib/baselines/refresh-service.js +65 -22
  26. package/.agents/scripts/lib/baselines/writer.js +5 -1
  27. package/.agents/scripts/lib/bdd-runner-detect.js +7 -10
  28. package/.agents/scripts/lib/child-exec.js +14 -1
  29. package/.agents/scripts/lib/child-stream.js +122 -0
  30. package/.agents/scripts/lib/clean-temp.js +19 -13
  31. package/.agents/scripts/lib/cli-args.js +49 -0
  32. package/.agents/scripts/lib/codex/skills-projection.js +1 -12
  33. package/.agents/scripts/lib/config/gates/mutation.schema.js +2 -2
  34. package/.agents/scripts/lib/config/gh-config-dir.js +63 -0
  35. package/.agents/scripts/lib/config/github.js +2 -0
  36. package/.agents/scripts/lib/config/paths.js +14 -3
  37. package/.agents/scripts/lib/config-resolver.js +78 -64
  38. package/.agents/scripts/lib/config-settings-schema-delivery.js +4 -3
  39. package/.agents/scripts/lib/config-settings-schema.js +7 -0
  40. package/.agents/scripts/lib/coverage-baseline.js +2 -2
  41. package/.agents/scripts/lib/coverage-capture.js +16 -1
  42. package/.agents/scripts/lib/crap-utils.js +59 -47
  43. package/.agents/scripts/lib/full-suite-lock.js +1 -10
  44. package/.agents/scripts/lib/gates/baseline-store.js +10 -0
  45. package/.agents/scripts/lib/generated/agentrc-validator.js +1 -1
  46. package/.agents/scripts/lib/gh-exec.js +45 -2
  47. package/.agents/scripts/lib/gh-transport.js +27 -0
  48. package/.agents/scripts/lib/git-utils.js +16 -9
  49. package/.agents/scripts/lib/maintainability-engine.js +27 -6
  50. package/.agents/scripts/lib/maintainability-utils.js +14 -1
  51. package/.agents/scripts/lib/orchestration/check-baselines/phases/evaluate.js +4 -1
  52. package/.agents/scripts/lib/orchestration/evidence-stream.js +186 -0
  53. package/.agents/scripts/lib/orchestration/file-assumptions.js +2 -19
  54. package/.agents/scripts/lib/orchestration/git-cleanup/phases/branches-reap.js +3 -7
  55. package/.agents/scripts/lib/orchestration/git-cleanup/phases/git-probes-ff.js +34 -40
  56. package/.agents/scripts/lib/orchestration/git-cleanup/phases/git-probes.js +4 -3
  57. package/.agents/scripts/lib/orchestration/plan-persist/persist-helpers.js +2 -19
  58. package/.agents/scripts/lib/orchestration/pr-watch.js +1 -5
  59. package/.agents/scripts/lib/orchestration/project-meta-cache.js +17 -4
  60. package/.agents/scripts/lib/orchestration/reassert-status-column.js +1 -8
  61. package/.agents/scripts/lib/orchestration/resolve-stories.js +1 -0
  62. package/.agents/scripts/lib/orchestration/review-providers/native.js +2 -2
  63. package/.agents/scripts/lib/orchestration/single-story-close/phase-timer.js +43 -0
  64. package/.agents/scripts/lib/orchestration/single-story-close/phases/confirm-merge.js +37 -13
  65. package/.agents/scripts/lib/orchestration/single-story-close/phases/finish.js +264 -0
  66. package/.agents/scripts/lib/orchestration/single-story-close/phases/open-pr.js +68 -0
  67. package/.agents/scripts/lib/orchestration/single-story-close/phases/pre-push.js +106 -0
  68. package/.agents/scripts/lib/orchestration/single-story-close/phases/reconcile-done.js +43 -35
  69. package/.agents/scripts/lib/orchestration/single-story-close/phases/review-halt.js +52 -0
  70. package/.agents/scripts/lib/orchestration/single-story-close/result.js +273 -0
  71. package/.agents/scripts/lib/orchestration/single-story-close/runner.js +68 -776
  72. package/.agents/scripts/lib/orchestration/story-close/context-budget-writeback.js +20 -9
  73. package/.agents/scripts/lib/orchestration/story-close/duplication-close-rescore.js +2 -2
  74. package/.agents/scripts/lib/orchestration/story-close/ratchet-shrink-writeback.js +20 -12
  75. package/.agents/scripts/lib/orchestration/story-handoff.js +50 -21
  76. package/.agents/scripts/lib/orchestration/story-progress.js +32 -12
  77. package/.agents/scripts/lib/orchestration/ticket-validator.js +3 -13
  78. package/.agents/scripts/lib/qa/resolve-selection.js +1 -8
  79. package/.agents/scripts/lib/single-story/confirm-and-land.js +33 -0
  80. package/.agents/scripts/lib/single-story-sweep/reconcile-closing.js +43 -11
  81. package/.agents/scripts/lib/single-story-sweep/sweep-lock.js +130 -30
  82. package/.agents/scripts/lib/skills/parse-skill.js +1 -4
  83. package/.agents/scripts/lib/story-body/story-body.js +12 -1
  84. package/.agents/scripts/lib/suite-admission.js +3 -11
  85. package/.agents/scripts/lib/temp-retention.js +25 -11
  86. package/.agents/scripts/lib/test-run-credit.js +2 -5
  87. package/.agents/scripts/lib/transpile.js +193 -31
  88. package/.agents/scripts/lib/util/paths.js +31 -0
  89. package/.agents/scripts/lib/util/sleep.js +15 -0
  90. package/.agents/scripts/lib/validation-evidence.js +29 -3
  91. package/.agents/scripts/lib/wave-runner/live-probe.js +24 -0
  92. package/.agents/scripts/lib/workers/crap-worker.js +23 -12
  93. package/.agents/scripts/lib/workers/maintainability-report-worker.js +18 -12
  94. package/.agents/scripts/lib/workflow-closure.js +1 -8
  95. package/.agents/scripts/notify.js +83 -90
  96. package/.agents/scripts/plan-context.js +8 -4
  97. package/.agents/scripts/providers/github/auth.js +14 -30
  98. package/.agents/scripts/providers/github/blocked-by-add.js +11 -27
  99. package/.agents/scripts/providers/github/compose.js +1 -0
  100. package/.agents/scripts/providers/github/gh-token-diagnostics.js +130 -0
  101. package/.agents/scripts/providers/github/identity.js +158 -0
  102. package/.agents/scripts/providers/github/issues.js +2 -2
  103. package/.agents/scripts/providers/github/mappers.js +16 -19
  104. package/.agents/scripts/providers/github/projects-v2-graphql.js +4 -36
  105. package/.agents/scripts/providers/github/request-helpers.js +44 -0
  106. package/.agents/scripts/providers/github/sub-issue-add.js +11 -28
  107. package/.agents/scripts/providers/github.js +10 -2
  108. package/.agents/scripts/quality-preview.js +6 -19
  109. package/.agents/scripts/single-story-confirm-merge.js +8 -20
  110. package/.agents/scripts/single-story-init.js +0 -1
  111. package/.agents/scripts/stories-wave-tick.js +60 -46
  112. package/.agents/scripts/story-handoff.js +2 -23
  113. package/.agents/scripts/story-review-compute.js +3 -22
  114. package/.agents/scripts/sync-claude-agents.js +1 -12
  115. package/.agents/scripts/sync-claude-commands.js +1 -12
  116. package/.agents/scripts/update-crap-baseline.js +10 -19
  117. package/.agents/scripts/update-ticket-state.js +44 -45
  118. package/.agents/templates/docs/audit-sweep-runbook.md +1 -1
  119. package/.agents/workflows/audit-accessibility.md +1 -1
  120. package/.agents/workflows/audit-adrs.md +1 -1
  121. package/.agents/workflows/audit-architecture.md +1 -1
  122. package/.agents/workflows/audit-baselines.md +2 -2
  123. package/.agents/workflows/audit-clean-code.md +1 -1
  124. package/.agents/workflows/audit-data-model.md +1 -1
  125. package/.agents/workflows/audit-dependencies.md +1 -1
  126. package/.agents/workflows/audit-devops.md +1 -1
  127. package/.agents/workflows/audit-documentation.md +1 -1
  128. package/.agents/workflows/audit-exceptions.md +2 -2
  129. package/.agents/workflows/audit-mobile.md +1 -1
  130. package/.agents/workflows/audit-navigability.md +1 -1
  131. package/.agents/workflows/audit-performance.md +1 -1
  132. package/.agents/workflows/audit-privacy.md +1 -1
  133. package/.agents/workflows/audit-quality.md +1 -1
  134. package/.agents/workflows/audit-security.md +1 -1
  135. package/.agents/workflows/audit-seo.md +1 -1
  136. package/.agents/workflows/audit-sre.md +1 -1
  137. package/.agents/workflows/audit-to-stories.md +9 -7
  138. package/.agents/workflows/audit-ux-ui.md +1 -1
  139. package/.agents/workflows/helpers/audit-lens-core.md +8 -5
  140. package/.agents/workflows/helpers/deliver-digest.md +4 -5
  141. package/.agents/workflows/helpers/deliver-story-reference.md +4 -4
  142. package/.agents/workflows/mandrel-deliver.md +3 -1
  143. package/README.md +6 -3
  144. package/docs/CHANGELOG.md +29 -0
  145. package/lib/cli/doctor-checks/codex.js +240 -0
  146. package/lib/cli/doctor-checks/merge-driver.js +79 -0
  147. package/lib/cli/doctor-checks/payload.js +201 -0
  148. package/lib/cli/doctor-checks/read-json.js +16 -0
  149. package/lib/cli/doctor-checks/runtime-deps.js +146 -0
  150. package/lib/cli/doctor-checks/spawn.js +18 -0
  151. package/lib/cli/doctor-checks/sync-parity.js +205 -0
  152. package/lib/cli/doctor-checks/test-credit-path.js +270 -0
  153. package/lib/cli/doctor-checks/toolchain.js +137 -0
  154. package/lib/cli/doctor-checks/version-current.js +82 -0
  155. package/lib/cli/registry.js +40 -1330
  156. package/package.json +1 -1
@@ -10,9 +10,9 @@
10
10
  * `lib/dead-exports-mode.js`.
11
11
  */
12
12
 
13
- import fs from 'node:fs';
14
13
  import path from 'node:path';
15
14
  import process from 'node:process';
15
+ import { parseGateArgv } from './lib/cli-args.js';
16
16
  import { runAsCli } from './lib/cli-utils.js';
17
17
  import {
18
18
  extractRowsFromKnip,
@@ -20,6 +20,9 @@ import {
20
20
  runKnip,
21
21
  } from './lib/dead-exports-knip.js';
22
22
  import { resolveDeadExportsMode } from './lib/dead-exports-mode.js';
23
+ import { readJsonBaseline } from './lib/gates/baseline-store.js';
24
+
25
+ export { readJsonBaseline as loadBaseline };
23
26
 
24
27
  /**
25
28
  * `--knip-output` is a test seam: a pre-captured knip JSON instead of a spawn.
@@ -28,49 +31,16 @@ import { resolveDeadExportsMode } from './lib/dead-exports-mode.js';
28
31
  * @returns {{ baselinePath: string | null, json: boolean, knipOutputPath: string | null, production: boolean }}
29
32
  */
30
33
  export function parseArgv(argv = []) {
31
- let baselinePath = null;
32
- let json = false;
33
- let knipOutputPath = null;
34
- let production = false;
35
- for (let i = 0; i < argv.length; i += 1) {
36
- const a = argv[i];
37
- if (a === '--baseline') {
38
- const next = argv[i + 1];
39
- if (next && !next.startsWith('--')) {
40
- baselinePath = next;
41
- i += 1;
42
- }
43
- } else if (a === '--json') {
44
- json = true;
45
- } else if (a === '--production') {
46
- production = true;
47
- } else if (a === '--knip-output') {
48
- const next = argv[i + 1];
49
- if (next && !next.startsWith('--')) {
50
- knipOutputPath = next;
51
- i += 1;
52
- }
53
- }
54
- }
55
- return { baselinePath, json, knipOutputPath, production };
56
- }
57
-
58
- /**
59
- * `null` when missing or unparseable.
60
- *
61
- * @param {string} baselinePath
62
- * @returns {{ kernelVersion?: string, rows?: Array<{file: string, symbol: string}> } | null}
63
- */
64
- export function loadBaseline(baselinePath) {
65
- try {
66
- if (!fs.existsSync(baselinePath)) return null;
67
- const raw = fs.readFileSync(baselinePath, 'utf-8');
68
- const parsed = JSON.parse(raw);
69
- if (!parsed || typeof parsed !== 'object') return null;
70
- return parsed;
71
- } catch {
72
- return null;
73
- }
34
+ const flags = parseGateArgv(argv, {
35
+ strings: ['baseline', 'knip-output'],
36
+ booleans: ['json', 'production'],
37
+ });
38
+ return {
39
+ baselinePath: flags.baseline,
40
+ json: flags.json,
41
+ knipOutputPath: flags['knip-output'],
42
+ production: flags.production,
43
+ };
74
44
  }
75
45
 
76
46
  /**
@@ -123,7 +93,7 @@ export function renderDiff(diff, label = 'dead-exports') {
123
93
  * stdout?: { write: (s: string) => void },
124
94
  * stderr?: { write: (s: string) => void },
125
95
  * runKnipImpl?: typeof runKnip,
126
- * loadBaselineImpl?: typeof loadBaseline,
96
+ * loadBaselineImpl?: typeof readJsonBaseline,
127
97
  * }} [opts]
128
98
  * @returns {Promise<number>} exit code: 0 = clean or removals-only; 1 = added exports detected
129
99
  */
@@ -133,7 +103,7 @@ export async function runCli({
133
103
  stdout = process.stdout,
134
104
  stderr = process.stderr,
135
105
  runKnipImpl = runKnip,
136
- loadBaselineImpl = loadBaseline,
106
+ loadBaselineImpl = readJsonBaseline,
137
107
  } = {}) {
138
108
  const { baselinePath, json, knipOutputPath, production } = parseArgv(argv);
139
109
  const {
@@ -22,6 +22,7 @@ import { spawnCapture } from './lib/child-exec.js';
22
22
  import { runAsCli } from './lib/cli-utils.js';
23
23
  import { PROJECT_ROOT, resolveConfig } from './lib/config-resolver.js';
24
24
  import * as defaultGit from './lib/git-utils.js';
25
+ import { STDERR_LOGGER } from './lib/Logger.js';
25
26
  import { AGENT_LABELS } from './lib/label-constants.js';
26
27
  import { createProvider } from './lib/provider-factory.js';
27
28
  import { makeGhRunner } from './lib/single-story-sweep/protection-ctx.js';
@@ -46,12 +47,6 @@ export const CLASSES = Object.freeze({
46
47
  const WORKTREE_DIR = '.worktrees';
47
48
 
48
49
  /** Removal-seam diagnostics go to stderr: stdout carries the table / JSON. */
49
- const STDERR_LOGGER = Object.freeze({
50
- info: (m) => process.stderr.write(`${m}\n`),
51
- warn: (m) => process.stderr.write(`${m}\n`),
52
- error: (m) => process.stderr.write(`${m}\n`),
53
- });
54
-
55
50
  const writeStdout = (text) => process.stdout.write(`${text}\n`);
56
51
 
57
52
  const HELP = `Usage: node .agents/scripts/clean-worktrees.js [options]
@@ -19,6 +19,7 @@ import { getPaths, resolveConfig } from './lib/config-resolver.js';
19
19
  import { Logger } from './lib/Logger.js';
20
20
  import { ensureDocsDigest } from './lib/orchestration/docs-digest.js';
21
21
  import { resolveResumeEffort } from './lib/orchestration/resume-effort.js';
22
+ import { NEXT_COMMANDS } from './lib/orchestration/story-deliver-terminal.js';
22
23
  import { expandIdList } from './lib/util/parse-id-list.js';
23
24
  import { runProbedStoriesWaveTick } from './stories-wave-tick.js';
24
25
 
@@ -54,6 +55,7 @@ const USAGE = {
54
55
  '--merge-watch-mode async is added to every close command when the run holds\nmore than one Story, and omitted for a run of one. Close sees a single Story\nand cannot make that call for itself.',
55
56
  'Every close command carries --worker-model, and --worker-effort when the\nStory resumes after a prior block: every Story a beat hands out is\nworker-dispatched, including a one-Story resume.',
56
57
  'Each ready[] entry carries effort: "high" after one local un-recovered\nstory-blocked signal, "xhigh" after two or more, null otherwise. Pass a\nnon-null effort as the Agent call\'s effort; omit the parameter for null.',
58
+ 'confirm[] lists every Story in the run that is closed but not yet\nagent::done (a superseded not_planned/duplicate close excluded), each with\nthe single-story-confirm-merge.js command that finishes its flip and land\ntail. Run each verbatim on every beat, before the epilogue. It is advisory:\nit never gates done.',
57
59
  'Exit codes:\n 0 beat emitted\n 1 input error\n 2 dependency cycle (cycleError)\n 3 wedged\n 4 blocked — the HITL pause; stop the loop, do not poll',
58
60
  ],
59
61
  };
@@ -545,6 +547,7 @@ export async function runDeliverRunBeat(
545
547
  workerEffort: effortById.get(storyId) ?? null,
546
548
  }),
547
549
  })),
550
+ confirm: renderConfirmEntries(tick.confirm),
548
551
  done: tick.epilogueDue === true,
549
552
  doneStories: tick.done ?? [],
550
553
  inFlight: tick.inFlight ?? 0,
@@ -567,6 +570,14 @@ export async function runDeliverRunBeat(
567
570
  };
568
571
  }
569
572
 
573
+ /** Closed Stories owing the done flip; advisory, never gates `done`. */
574
+ function renderConfirmEntries(ids) {
575
+ return (Array.isArray(ids) ? ids : []).map((id) => ({
576
+ id,
577
+ command: NEXT_COMMANDS.confirmMerge(id),
578
+ }));
579
+ }
580
+
570
581
  /**
571
582
  * @param {string[]} argv
572
583
  * @returns {{ stories?: string, handoff: string[], concurrency?: string, runId?: string, cwd?: string }}
@@ -308,16 +308,16 @@ export async function main(args = process.argv.slice(2)) {
308
308
  Logger.error(remediation);
309
309
  Logger.error('----------------------------------------\n');
310
310
 
311
- process.exit(abnormal?.exitCode ?? result.status);
312
- } else {
313
- process.exit(0);
311
+ return abnormal?.exitCode ?? result.status;
314
312
  }
313
+ return 0;
315
314
  }
316
315
 
317
316
  import { runAsCli } from './lib/cli-utils.js';
318
317
 
319
318
  runAsCli(import.meta.url, main, {
320
319
  source: 'DiagnoseFriction',
320
+ propagateExitCode: true,
321
321
  usage: {
322
322
  invocation:
323
323
  'node .agents/scripts/diagnose-friction.js [--story <id>] [--epic <id>] --cmd <cmd> <args...>',
@@ -1,8 +1,7 @@
1
1
  /**
2
2
  * The `update-coverage-baseline` CLI's testable logic. The scorer stays
3
- * bespoke (not the refresh-service default) because it logs when the coverage
4
- * artifact is missing on a scoped refresh; a full-scope refresh rethrows, since
5
- * `refreshBaseline` has no empty-rows guard and would write an empty baseline.
3
+ * bespoke (not the refresh-service default) because it logs an unreadable
4
+ * coverage artifact before refusing it.
6
5
  */
7
6
 
8
7
  import fs from 'node:fs';
@@ -53,19 +52,13 @@ export function resolveCoverageUpdaterScope(argv = []) {
53
52
  return { fullScope, diffScopeRef };
54
53
  }
55
54
 
56
- /**
57
- * A full-scope refresh rethrows a read failure — over zero rows it would
58
- * write an empty baseline; a scoped one logs it and yields `null`.
59
- *
60
- * @returns {object|null}
61
- */
62
- function readOrReport(readCoverage, cwd, opts, logger) {
55
+ /** Logs a read failure and rethrows it: an empty row set would erase rows. */
56
+ function readOrRefuse(readCoverage, cwd, logger) {
63
57
  try {
64
58
  return readCoverage(cwd);
65
59
  } catch (err) {
66
- if (opts?.fullScope) throw err;
67
60
  logger.error(`[Coverage] ❌ ${err.message}`);
68
- return null;
61
+ throw err;
69
62
  }
70
63
  }
71
64
 
@@ -84,8 +77,7 @@ function buildCoverageUpdaterScorer(
84
77
  ) {
85
78
  return (files, opts) => {
86
79
  const effectiveCwd = opts?.cwd ?? cwd;
87
- const raw = readOrReport(readCoverage, effectiveCwd, opts, logger);
88
- if (raw === null) return [];
80
+ const raw = readOrRefuse(readCoverage, effectiveCwd, logger);
89
81
  const c8Config = loadScope(effectiveCwd);
90
82
  const scores = score({
91
83
  raw,
@@ -9,7 +9,7 @@ import path from 'node:path';
9
9
  import { getBaselines, getQuality, resolveConfig } from '../config-resolver.js';
10
10
  import {
11
11
  isCoverageFresh,
12
- missingCoverageArtifactMessage,
12
+ MissingCoverageArtifactError,
13
13
  } from '../coverage-capture.js';
14
14
  import { loadCoverage as loadCoverageDefault } from '../coverage-utils.js';
15
15
  import { checkResolutionFloor, scanAndScore } from '../crap-utils.js';
@@ -136,40 +136,51 @@ function reportScanSummary(summary, logger = Logger) {
136
136
  }
137
137
  }
138
138
 
139
+ /** @param {string} coverageAbs */
140
+ function refuseMissingCoverage(coverageAbs) {
141
+ throw new MissingCoverageArtifactError(coverageAbs, { prefix: '[CRAP] ' });
142
+ }
143
+
139
144
  /**
140
- * No artifact under `requireCoverage`: a full-scope refresh throws naming the
141
- * capture contract (zero rows would write an empty baseline); a scoped one
142
- * warns and yields no rows.
145
+ * `refreshBaseline` options for the CRAP updater. With no scope flag the
146
+ * service derives the diff via `origin/main..HEAD` (its default refs). The
147
+ * transpiler stamp resolves from the anchors the scorer resolves compilers
148
+ * from: the target dirs and the project root.
143
149
  *
144
- * @param {string} coverageAbs
145
- * @param {{ coveragePath: string }} options
146
- * @param {{ fullScope?: boolean } | undefined} opts
147
- * @param {{ warn: Function }} logger
148
- * @returns {object[]}
150
+ * @param {ReturnType<typeof resolveCrapUpdaterOptions>} options
151
+ * @param {{loadCoverage: Function, epsilon?: number, cwd?: string,
152
+ * scan?: Function, logger?: object}} deps
153
+ * @returns {object}
149
154
  */
150
- function noCoverageRows(coverageAbs, options, opts, logger) {
151
- if (opts?.fullScope) {
152
- throw new Error(`[CRAP] ${missingCoverageArtifactMessage(coverageAbs)}`);
153
- }
154
- logger.warn(
155
- `[CRAP] ⚠ No coverage artifact at ${options.coveragePath}. All files will be skipped under requireCoverage=true.`,
156
- );
157
- logger.warn(
158
- "[CRAP] ⚠ Run 'npm run test:coverage' before 'npm run crap:update'.",
159
- );
160
- return [];
155
+ export function buildCrapRefreshOptions(
156
+ options,
157
+ { epsilon, cwd = process.cwd(), ...scorerDeps },
158
+ ) {
159
+ return {
160
+ kind: 'crap',
161
+ writePath: options.absBaselinePath,
162
+ epsilon,
163
+ scorer: buildCrapUpdaterScorer(options, scorerDeps),
164
+ extrasContext: { cwd, targetDirs: options.targetDirs },
165
+ ...scopeFields(options),
166
+ };
167
+ }
168
+
169
+ function scopeFields({ fullScope, diffScopeRef }) {
170
+ if (fullScope) return { fullScope: true };
171
+ return diffScopeRef ? { baseRef: diffScopeRef } : {};
161
172
  }
162
173
 
163
174
  /**
164
175
  * Fails closed on a missing coverage artifact under `requireCoverage` (throws
165
- * on a full-scope refresh; warns with no rows on a scoped one) and on a resolution rate below the floor (throws before anything is
166
- * written: a broken join is wrong, not sparse).
176
+ * on every scope) and on a resolution rate below the floor (throws before
177
+ * anything is written: a broken join is wrong, not sparse).
167
178
  *
168
179
  * @param {ReturnType<typeof resolveCrapUpdaterOptions>} options
169
180
  * @param {{loadCoverage: Function, scan?: Function, logger?: object}} deps
170
181
  * @returns {(files: string[], opts: object) => Promise<object[]>}
171
182
  */
172
- export function buildCrapUpdaterScorer(
183
+ function buildCrapUpdaterScorer(
173
184
  options,
174
185
  { loadCoverage, scan = scanAndScore, logger = Logger } = {},
175
186
  ) {
@@ -179,9 +190,8 @@ export function buildCrapUpdaterScorer(
179
190
  ? options.coveragePath
180
191
  : path.resolve(effectiveCwd, options.coveragePath);
181
192
  const coverage = loadCoverage(coverageAbs);
182
- if (!coverage && options.requireCoverage) {
183
- return noCoverageRows(coverageAbs, options, opts, logger);
184
- }
193
+ if (!coverage && options.requireCoverage)
194
+ refuseMissingCoverage(coverageAbs);
185
195
 
186
196
  const summary = await scan({
187
197
  targetDirs: options.targetDirs,
@@ -105,11 +105,13 @@ function cloneLineNumbers(dup, maxLine) {
105
105
  /**
106
106
  * Pure. Both sides of each clone pair accrue lines; overlapping clones are
107
107
  * unioned per file so a line counts once. Every counted file gets a row.
108
+ * `partners` names the other files sharing a clone with this one; the
109
+ * refresh service widens a diff scope with it, and `projectRow` drops it.
108
110
  *
109
111
  * @param {Array<{duplicationA?: object, duplicationB?: object}>} clones
110
112
  * @param {Map<string, number>|Record<string, number>} fileLineCounts
111
113
  * @param {string} [cwd]
112
- * @returns {Array<{path: string, duplicatedLines: number, totalLines: number, percentage: number}>}
114
+ * @returns {Array<{path: string, duplicatedLines: number, totalLines: number, percentage: number, partners: string[]}>}
113
115
  */
114
116
  export function buildDuplicationRows(
115
117
  clones,
@@ -118,19 +120,23 @@ export function buildDuplicationRows(
118
120
  ) {
119
121
  const counts = toLineCountMap(fileLineCounts);
120
122
  const dupLinesByFile = new Map();
123
+ const partnersByFile = new Map();
121
124
  // Seed every visited file with an empty set so clean files get a 0-row.
122
125
  for (const file of counts.keys()) {
123
126
  dupLinesByFile.set(file, new Set());
124
127
  }
125
128
  for (const clone of clones ?? []) {
129
+ const files = [];
126
130
  for (const side of [clone?.duplicationA, clone?.duplicationB]) {
127
131
  if (!side) continue;
128
132
  const file = relativisePath(side.sourceId, cwd);
129
133
  if (!file) continue;
134
+ files.push(file);
130
135
  const set = dupLinesByFile.get(file) ?? new Set();
131
136
  for (const n of cloneLineNumbers(side, counts.get(file))) set.add(n);
132
137
  dupLinesByFile.set(file, set);
133
138
  }
139
+ addClonePartners(partnersByFile, files);
134
140
  }
135
141
  const rows = [];
136
142
  for (const [file, lineSet] of dupLinesByFile) {
@@ -143,11 +149,24 @@ export function buildDuplicationRows(
143
149
  duplicatedLines,
144
150
  totalLines,
145
151
  percentage: Number(percentage.toFixed(2)),
152
+ partners: [...(partnersByFile.get(file) ?? [])].sort(),
146
153
  });
147
154
  }
148
155
  return rows;
149
156
  }
150
157
 
158
+ /**
159
+ * @param {Map<string, Set<string>>} partnersByFile
160
+ * @param {string[]} files both sides of one clone
161
+ */
162
+ function addClonePartners(partnersByFile, files) {
163
+ for (const file of files) {
164
+ const partners = partnersByFile.get(file) ?? new Set();
165
+ for (const other of files) if (other !== file) partners.add(other);
166
+ partnersByFile.set(file, partners);
167
+ }
168
+ }
169
+
151
170
  function toLineCountMap(fileLineCounts) {
152
171
  if (fileLineCounts instanceof Map) return fileLineCounts;
153
172
  const map = new Map();
@@ -9,6 +9,30 @@ import { Logger } from '../Logger.js';
9
9
  // the pre-push hook from ratcheting on noise.
10
10
  const MI_DEFAULT_TOLERANCE = 0.5;
11
11
 
12
+ /**
13
+ * A non-negative numeric env override of `key`, or `current` (with a warning)
14
+ * when the value is malformed. An unset or empty var keeps `current` silently.
15
+ *
16
+ * @param {{ env: NodeJS.ProcessEnv, varName: string, key: string, current: number, overrides: string[] }} opts
17
+ * @returns {number}
18
+ */
19
+ function readNonNegativeEnv({ env, varName, key, current, overrides }) {
20
+ const raw = env?.[varName];
21
+ if (raw === undefined || raw === '') return current;
22
+ const parsed = Number(raw);
23
+ if (Number.isFinite(parsed) && parsed >= 0) {
24
+ overrides.push(`${key}=${parsed} (${varName})`);
25
+ return parsed;
26
+ }
27
+ Logger.warn(
28
+ `[CRAP] ⚠ ignoring malformed ${varName}=${raw}; keeping config value ${current}`,
29
+ );
30
+ return current;
31
+ }
32
+
33
+ const finiteOr = (value, fallback) =>
34
+ Number.isFinite(value) ? value : fallback;
35
+
12
36
  /**
13
37
  * @param {{ newMethodCeiling?: unknown, tolerance?: unknown, refreshTag?: unknown }} crapConfig
14
38
  * @param {NodeJS.ProcessEnv} env
@@ -16,46 +40,27 @@ const MI_DEFAULT_TOLERANCE = 0.5;
16
40
  */
17
41
  export function resolveCrapEnvOverrides(crapConfig, env) {
18
42
  const overrides = [];
19
- let newMethodCeiling = Number.isFinite(crapConfig?.newMethodCeiling)
20
- ? crapConfig.newMethodCeiling
21
- : 30;
43
+ const newMethodCeiling = readNonNegativeEnv({
44
+ env,
45
+ varName: 'CRAP_NEW_METHOD_CEILING',
46
+ key: 'newMethodCeiling',
47
+ current: finiteOr(crapConfig?.newMethodCeiling, 30),
48
+ overrides,
49
+ });
22
50
  // Coverage rounding across CI environments shifts a CRAP score by ~0.01;
23
51
  // real regressions cross whole integers and clear 0.05 trivially.
24
- let tolerance = Number.isFinite(crapConfig?.tolerance)
25
- ? crapConfig.tolerance
26
- : 0.05;
52
+ const tolerance = readNonNegativeEnv({
53
+ env,
54
+ varName: 'CRAP_TOLERANCE',
55
+ key: 'tolerance',
56
+ current: finiteOr(crapConfig?.tolerance, 0.05),
57
+ overrides,
58
+ });
59
+ const rawRefreshTag = env?.CRAP_REFRESH_TAG;
27
60
  let refreshTag =
28
61
  typeof crapConfig?.refreshTag === 'string' && crapConfig.refreshTag.length
29
62
  ? crapConfig.refreshTag
30
63
  : 'baseline-refresh:';
31
-
32
- const rawCeiling = env?.CRAP_NEW_METHOD_CEILING;
33
- if (rawCeiling !== undefined && rawCeiling !== '') {
34
- const parsed = Number(rawCeiling);
35
- if (Number.isFinite(parsed) && parsed >= 0) {
36
- newMethodCeiling = parsed;
37
- overrides.push(`newMethodCeiling=${parsed} (CRAP_NEW_METHOD_CEILING)`);
38
- } else {
39
- Logger.warn(
40
- `[CRAP] ⚠ ignoring malformed CRAP_NEW_METHOD_CEILING=${rawCeiling}; keeping config value ${newMethodCeiling}`,
41
- );
42
- }
43
- }
44
-
45
- const rawTolerance = env?.CRAP_TOLERANCE;
46
- if (rawTolerance !== undefined && rawTolerance !== '') {
47
- const parsed = Number(rawTolerance);
48
- if (Number.isFinite(parsed) && parsed >= 0) {
49
- tolerance = parsed;
50
- overrides.push(`tolerance=${parsed} (CRAP_TOLERANCE)`);
51
- } else {
52
- Logger.warn(
53
- `[CRAP] ⚠ ignoring malformed CRAP_TOLERANCE=${rawTolerance}; keeping config value ${tolerance}`,
54
- );
55
- }
56
- }
57
-
58
- const rawRefreshTag = env?.CRAP_REFRESH_TAG;
59
64
  if (typeof rawRefreshTag === 'string' && rawRefreshTag.length > 0) {
60
65
  refreshTag = rawRefreshTag;
61
66
  overrides.push(`refreshTag=${rawRefreshTag} (CRAP_REFRESH_TAG)`);
@@ -233,12 +233,13 @@ function tryGetKindModule(kind) {
233
233
  *
234
234
  * @param {string} kind
235
235
  * @param {object|null} baseline
236
+ * @param {object} [ctx] Passed through to the kind's hook (e.g. scan anchors).
236
237
  * @returns {string|null} Operator-facing message, or null when compatible.
237
238
  */
238
- export function checkBaselineSemantics(kind, baseline) {
239
+ export function checkBaselineSemantics(kind, baseline, ctx = {}) {
239
240
  const mod = tryGetKindModule(kind);
240
241
  if (typeof mod?.assertBaselineCompatible !== 'function') return null;
241
- return mod.assertBaselineCompatible(baseline);
242
+ return mod.assertBaselineCompatible(baseline, ctx);
242
243
  }
243
244
 
244
245
  /**
@@ -3,7 +3,6 @@
3
3
  * `{ path, method, startLine, crap }`.
4
4
  */
5
5
 
6
- import fs from 'node:fs';
7
6
  import path from 'node:path';
8
7
  import { fileURLToPath } from 'node:url';
9
8
  import {
@@ -12,6 +11,7 @@ import {
12
11
  deriveFixGuidance,
13
12
  } from '../../crap-engine.js';
14
13
  import { isAnonymousMethodLabel } from '../../crap-method-identity.js';
14
+ import { resolveEscomplexVersion } from '../../crap-utils.js';
15
15
  import { Logger } from '../../Logger.js';
16
16
  import { resolveTsTranspilerVersion } from '../../transpile.js';
17
17
  import {
@@ -42,43 +42,16 @@ export { loadCrapBaseline } from './_crap-read.js';
42
42
 
43
43
  const __filename = fileURLToPath(import.meta.url);
44
44
 
45
- /** The package that computes the metrics; its version stamps the scorer identity. */
46
- const SCORER_PACKAGE = 'escomplex-plugin-metrics-module';
47
-
48
45
  /**
49
- * Resolve the scorer version from the nearest `node_modules/<SCORER_PACKAGE>`,
50
- * walking up. Returns the `'0.0.0'` "unknown environment" sentinel when not
51
- * found, which makes the writer refuse to persist. The walk-up can escape a
52
- * worktree into the parent checkout, so a local pass does not prove CI's.
46
+ * Scorer version, walked up from this module's directory; the `'0.0.0'`
47
+ * sentinel (unknown environment) makes the writer refuse to persist. The
48
+ * walk-up can escape a worktree into the parent checkout, so a local pass
49
+ * does not prove CI's.
53
50
  *
54
51
  * @returns {string}
55
52
  */
56
53
  export function kernelVersion() {
57
- let dir = path.dirname(__filename);
58
- const { root } = path.parse(dir);
59
- while (true) {
60
- const pkgPath = path.join(
61
- dir,
62
- 'node_modules',
63
- SCORER_PACKAGE,
64
- 'package.json',
65
- );
66
- if (fs.existsSync(pkgPath)) {
67
- try {
68
- const parsed = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
69
- if (parsed && typeof parsed.version === 'string') {
70
- return parsed.version;
71
- }
72
- } catch {
73
- // fall through to parent lookup
74
- }
75
- }
76
- if (dir === root) break;
77
- const parent = path.dirname(dir);
78
- if (parent === dir) break;
79
- dir = parent;
80
- }
81
- return '0.0.0';
54
+ return resolveEscomplexVersion(path.dirname(__filename));
82
55
  }
83
56
 
84
57
  /**
@@ -96,15 +69,17 @@ const SCORING_SEMANTICS = 'method-identity-v3';
96
69
  * change can move every TS row's `startLine` (half the row identity key), so
97
70
  * `tsTranspilerVersion` is stamped for the `ts-transpiler-drift` axis.
98
71
  * `provenanceStamped` is a positive marker that per-row provenance was
99
- * recorded; no other stamp can detect its absence.
72
+ * recorded; no other stamp can detect its absence. `ctx` carries the scan's
73
+ * `cwd` / `targetDirs` so the stamp names the compiler the scorer resolved.
100
74
  *
75
+ * @param {{ cwd?: string, targetDirs?: string[] }} [ctx]
101
76
  * @returns {{scoringSemantics: string, tsTranspilerVersion: string,
102
77
  * provenanceStamped: boolean}}
103
78
  */
104
- export function envelopeExtras() {
79
+ export function envelopeExtras(ctx = {}) {
105
80
  return {
106
81
  scoringSemantics: SCORING_SEMANTICS,
107
- tsTranspilerVersion: resolveTsTranspilerVersion(),
82
+ tsTranspilerVersion: resolveTsTranspilerVersion(ctx),
108
83
  provenanceStamped: true,
109
84
  };
110
85
  }
@@ -621,13 +596,14 @@ const LOADED_ENVELOPE_AXES = [
621
596
  * closed on a message, so an incompatible baseline is never silently compared.
622
597
  *
623
598
  * @param {object|null} baseline A loaded v2 baseline envelope.
624
- * @param {{runningTsTranspilerVersion?: string}} [ctx]
599
+ * @param {{runningTsTranspilerVersion?: string, cwd?: string,
600
+ * targetDirs?: string[]}} [ctx]
625
601
  * @returns {string|null} Operator-facing message, or null when compatible.
626
602
  */
627
603
  export function assertBaselineCompatible(baseline, ctx = {}) {
628
604
  if (!baseline) return null;
629
605
  const runningTsTranspilerVersion =
630
- ctx.runningTsTranspilerVersion ?? resolveTsTranspilerVersion();
606
+ ctx.runningTsTranspilerVersion ?? resolveTsTranspilerVersion(ctx);
631
607
  for (const name of LOADED_ENVELOPE_AXES) {
632
608
  const axis = CRAP_COMPAT_AXES.find((a) => a.name === name);
633
609
  const message = axis?.check({ baseline, runningTsTranspilerVersion });
@@ -215,7 +215,10 @@ export async function runCrapPreview({
215
215
 
216
216
  // An incompatible baseline yields no meaningful verdict. Fail open:
217
217
  // `check-baselines` still gates the merge.
218
- const incompatible = assertBaselineCompatible(baseline);
218
+ const incompatible = assertBaselineCompatible(baseline, {
219
+ cwd,
220
+ targetDirs: crap.targetDirs,
221
+ });
219
222
  if (incompatible) {
220
223
  return {
221
224
  exitCode: 0,