mandrel 2.89.0 → 2.91.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 (175) hide show
  1. package/.agents/README.md +47 -7
  2. package/.agents/agents/story-worker.md +20 -0
  3. package/.agents/audit-checklists/lean.md +26 -0
  4. package/.agents/docs/agentrc-reference.json +5 -6
  5. package/.agents/docs/configuration.md +38 -30
  6. package/.agents/docs/workflows.md +7 -1
  7. package/.agents/instructions.md +3 -1
  8. package/.agents/runtime-deps.json +0 -2
  9. package/.agents/schemas/agentrc.schema.json +46 -45
  10. package/.agents/schemas/audit-rules.json +19 -0
  11. package/.agents/scripts/acceptance-eval.js +2 -6
  12. package/.agents/scripts/audit-exceptions.js +2 -4
  13. package/.agents/scripts/board-backfill.js +253 -0
  14. package/.agents/scripts/check-arch-cycles.js +1 -5
  15. package/.agents/scripts/check-context-budget.js +1 -5
  16. package/.agents/scripts/check-cyclomatic.js +1 -5
  17. package/.agents/scripts/check-dead-exports.js +23 -14
  18. package/.agents/scripts/check-doc-links.js +4 -4
  19. package/.agents/scripts/check-test-temp-hygiene.js +29 -33
  20. package/.agents/scripts/coverage-capture.js +14 -6
  21. package/.agents/scripts/diagnose-friction.js +8 -10
  22. package/.agents/scripts/generate-workflows-doc.js +5 -0
  23. package/.agents/scripts/lib/audit-exceptions/adapters/index.js +2 -0
  24. package/.agents/scripts/lib/audit-exceptions/adapters/inline-suppressions.js +36 -27
  25. package/.agents/scripts/lib/audit-exceptions/adapters/shortcut-markers.js +70 -0
  26. package/.agents/scripts/lib/audit-exceptions/adapters/source-scan.js +26 -0
  27. package/.agents/scripts/lib/audit-to-stories/audit-lenses.js +1 -0
  28. package/.agents/scripts/lib/baseline-schema-registry.js +3 -5
  29. package/.agents/scripts/lib/baselines/bundle-size-scorer.js +11 -28
  30. package/.agents/scripts/lib/baselines/components.js +5 -5
  31. package/.agents/scripts/lib/baselines/crap-preview-scan.js +4 -1
  32. package/.agents/scripts/lib/baselines/crap-updater-cli.js +6 -4
  33. package/.agents/scripts/lib/baselines/duplication-scanner.js +4 -10
  34. package/.agents/scripts/lib/baselines/kinds/crap.js +4 -2
  35. package/.agents/scripts/lib/baselines/kinds/duplication.js +4 -2
  36. package/.agents/scripts/lib/baselines/kinds/kind-factory.js +13 -6
  37. package/.agents/scripts/lib/baselines/refresh-service.js +10 -13
  38. package/.agents/scripts/lib/baselines/writer.js +4 -4
  39. package/.agents/scripts/lib/bdd-scenario-scanner.js +26 -31
  40. package/.agents/scripts/lib/bootstrap/gh-list.js +4 -5
  41. package/.agents/scripts/lib/bootstrap/gh-preflight.js +13 -8
  42. package/.agents/scripts/lib/child-exec.js +4 -4
  43. package/.agents/scripts/lib/claude/agents-projection.js +170 -0
  44. package/.agents/scripts/lib/claude/commands-projection.js +184 -0
  45. package/.agents/scripts/lib/close-validation/commands.js +28 -117
  46. package/.agents/scripts/lib/close-validation/gates.js +54 -48
  47. package/.agents/scripts/lib/close-validation/process.js +5 -1
  48. package/.agents/scripts/lib/close-validation/projections/crap.js +2 -1
  49. package/.agents/scripts/lib/close-validation/projections/maintainability.js +50 -15
  50. package/.agents/scripts/lib/config/agentrc-overlay.js +4 -7
  51. package/.agents/scripts/lib/config/commands.js +82 -7
  52. package/.agents/scripts/lib/config/explain.js +2 -1
  53. package/.agents/scripts/lib/config/gates/coverage.schema.js +39 -3
  54. package/.agents/scripts/lib/config/gates/crap-incremental-coverage.schema.js +1 -1
  55. package/.agents/scripts/lib/config/gates/crap.schema.js +5 -3
  56. package/.agents/scripts/lib/config/gates/duplication.schema.js +6 -11
  57. package/.agents/scripts/lib/config/gates/shared.js +2 -2
  58. package/.agents/scripts/lib/config/git-roots.js +120 -0
  59. package/.agents/scripts/lib/config/quality.js +46 -50
  60. package/.agents/scripts/lib/config/review-chain-default.js +4 -3
  61. package/.agents/scripts/lib/config/review-provider-clis.js +11 -0
  62. package/.agents/scripts/lib/config/temp-paths.js +3 -37
  63. package/.agents/scripts/lib/config-resolver.js +5 -9
  64. package/.agents/scripts/lib/config-settings-schema-delivery.js +2 -2
  65. package/.agents/scripts/lib/config-settings-schema-quality.js +3 -2
  66. package/.agents/scripts/lib/config-settings-schema.js +6 -7
  67. package/.agents/scripts/lib/coverage-baseline.js +2 -1
  68. package/.agents/scripts/lib/coverage-capture-affected.js +4 -3
  69. package/.agents/scripts/lib/coverage-capture-fullscope.js +3 -1
  70. package/.agents/scripts/lib/coverage-capture-passes.js +119 -34
  71. package/.agents/scripts/lib/coverage-capture-usage.js +1 -1
  72. package/.agents/scripts/lib/coverage-capture.js +80 -43
  73. package/.agents/scripts/lib/coverage-utils.js +34 -16
  74. package/.agents/scripts/lib/cpu-pool.js +2 -4
  75. package/.agents/scripts/lib/crap-engine.js +19 -1
  76. package/.agents/scripts/lib/crap-utils.js +2 -1
  77. package/.agents/scripts/lib/dead-exports-knip.js +29 -11
  78. package/.agents/scripts/lib/detect-package-manager.js +13 -0
  79. package/.agents/scripts/lib/feedback-loop/graduator-gh.js +4 -2
  80. package/.agents/scripts/lib/full-suite-lock.js +25 -9
  81. package/.agents/scripts/lib/gates/baseline-store.js +2 -10
  82. package/.agents/scripts/lib/generated/agentrc-validator.js +4 -1
  83. package/.agents/scripts/lib/gh-env.js +72 -0
  84. package/.agents/scripts/lib/gh-exec.js +26 -1
  85. package/.agents/scripts/lib/maintainability-utils.js +8 -8
  86. package/.agents/scripts/lib/npm-scripts.js +1 -1
  87. package/.agents/scripts/lib/observability/signal-validator.js +2 -6
  88. package/.agents/scripts/lib/observability/source-classifier.js +1 -0
  89. package/.agents/scripts/lib/observability/terse-result.js +2 -6
  90. package/.agents/scripts/lib/orchestration/board-access-latch.js +112 -0
  91. package/.agents/scripts/lib/orchestration/ci-rerun-guard.js +10 -13
  92. package/.agents/scripts/lib/orchestration/column-sync.js +107 -52
  93. package/.agents/scripts/lib/orchestration/deliver-recover.js +2 -1
  94. package/.agents/scripts/lib/orchestration/git-cleanup/phases/git-probes.js +3 -3
  95. package/.agents/scripts/lib/orchestration/lifecycle/emit-ledger-event.js +2 -6
  96. package/.agents/scripts/lib/orchestration/light-suitability.js +5 -7
  97. package/.agents/scripts/lib/orchestration/pr-watch.js +7 -7
  98. package/.agents/scripts/lib/orchestration/project-meta-cache.js +2 -11
  99. package/.agents/scripts/lib/orchestration/project-meta-resolver.js +44 -17
  100. package/.agents/scripts/lib/orchestration/review-deposit.js +2 -9
  101. package/.agents/scripts/lib/orchestration/review-providers/callers-context.js +219 -0
  102. package/.agents/scripts/lib/orchestration/review-providers/code-review.js +53 -5
  103. package/.agents/scripts/lib/orchestration/review-providers/codex-cli.js +2 -2
  104. package/.agents/scripts/lib/orchestration/review-providers/llm-review.js +96 -0
  105. package/.agents/scripts/lib/orchestration/review-providers/mi-exemptions.js +2 -2
  106. package/.agents/scripts/lib/orchestration/review-providers/native.js +13 -19
  107. package/.agents/scripts/lib/orchestration/review-providers/review-depth.js +3 -2
  108. package/.agents/scripts/lib/orchestration/review-providers/review-provider-factory.js +2 -0
  109. package/.agents/scripts/lib/orchestration/review-providers/security-review.js +11 -3
  110. package/.agents/scripts/lib/orchestration/story-close/baseline-upward-writeback.js +2 -3
  111. package/.agents/scripts/lib/orchestration/story-close/format-autofix.js +41 -15
  112. package/.agents/scripts/lib/orchestration/story-deliver-terminal-schema.js +2 -4
  113. package/.agents/scripts/lib/orchestration/story-deliver-terminal.js +2 -13
  114. package/.agents/scripts/lib/orchestration/story-handoff.js +27 -6
  115. package/.agents/scripts/lib/orchestration/story-progress.js +3 -11
  116. package/.agents/scripts/lib/orchestration/ticketing/bulk.js +3 -5
  117. package/.agents/scripts/lib/orchestration/verify-credit.js +52 -28
  118. package/.agents/scripts/lib/single-story-sweep/protection-ctx.js +11 -11
  119. package/.agents/scripts/lib/single-story-sweep/protection.js +1 -9
  120. package/.agents/scripts/lib/single-story-sweep/sweep-lock.js +1 -5
  121. package/.agents/scripts/lib/source-extensions.js +30 -15
  122. package/.agents/scripts/lib/test-run-credit.js +1 -9
  123. package/.agents/scripts/lib/test-temp.js +22 -21
  124. package/.agents/scripts/lib/util/ajv.js +111 -0
  125. package/.agents/scripts/lib/util/atomic-write.js +30 -0
  126. package/.agents/scripts/lib/util/paths.js +51 -0
  127. package/.agents/scripts/lib/util/sleep.js +6 -0
  128. package/.agents/scripts/lib/util/slug.js +12 -0
  129. package/.agents/scripts/lib/validation-evidence.js +19 -40
  130. package/.agents/scripts/lib/worktree/lifecycle/force-drain.js +2 -1
  131. package/.agents/scripts/lib/worktree/lifecycle/pending-cleanup.js +10 -28
  132. package/.agents/scripts/lib/worktree/lifecycle/reap.js +2 -2
  133. package/.agents/scripts/lib/worktree/node-modules-strategy.js +21 -14
  134. package/.agents/scripts/lint-issue-body.js +2 -2
  135. package/.agents/scripts/plan-context.js +2 -7
  136. package/.agents/scripts/providers/github/auth.js +3 -3
  137. package/.agents/scripts/providers/github/board-add.js +18 -9
  138. package/.agents/scripts/providers/github/errors.js +3 -1
  139. package/.agents/scripts/providers/github/gh-token-diagnostics.js +10 -7
  140. package/.agents/scripts/providers/github/issues.js +6 -2
  141. package/.agents/scripts/providers/github/mappers.js +1 -5
  142. package/.agents/scripts/providers/github/projects-v2-graphql.js +26 -6
  143. package/.agents/scripts/providers/github/search-budget.js +3 -1
  144. package/.agents/scripts/resolve-doc-tiers.js +7 -20
  145. package/.agents/scripts/sync-agentrc.js +5 -14
  146. package/.agents/scripts/sync-claude-agents.js +38 -150
  147. package/.agents/scripts/sync-claude-commands.js +35 -218
  148. package/.agents/scripts/update-coverage-baseline.js +1 -1
  149. package/.agents/scripts/update-crap-baseline.js +1 -1
  150. package/.agents/scripts/update-duplication-baseline.js +2 -16
  151. package/.agents/scripts/validate-skills.js +6 -10
  152. package/.agents/skills/core/code-review-and-quality/SKILL.md +3 -18
  153. package/.agents/skills/core/documentation-and-adrs/SKILL.md +4 -14
  154. package/.agents/workflows/audit-exceptions.md +9 -0
  155. package/.agents/workflows/audit-lean.md +129 -0
  156. package/.agents/workflows/helpers/audit-lens-core.md +7 -0
  157. package/.agents/workflows/helpers/code-quality-guardrails.md +21 -0
  158. package/.agents/workflows/helpers/code-review.md +15 -1
  159. package/.agents/workflows/helpers/deliver-digest.md +1 -1
  160. package/.agents/workflows/helpers/deliver-reference.md +2 -2
  161. package/.agents/workflows/mandrel-plan.md +2 -2
  162. package/docs/CHANGELOG.md +48 -0
  163. package/lib/cli/doctor-checks/codex.js +6 -5
  164. package/lib/cli/doctor-checks/llm-review.js +102 -0
  165. package/lib/cli/doctor-checks/project-access.js +124 -0
  166. package/lib/cli/doctor-checks/sync-parity.js +65 -140
  167. package/lib/cli/doctor-checks/test-credit-path.js +69 -28
  168. package/lib/cli/doctor-checks/toolchain.js +5 -3
  169. package/lib/cli/registry.js +11 -0
  170. package/lib/migrations/helpers/retire-agentrc-key.js +3 -3
  171. package/lib/migrations/index.js +6 -0
  172. package/lib/migrations/steps/2.91.0-move-shared-crap-capture-script.js +84 -0
  173. package/lib/migrations/steps/2.91.0-retire-duplication-formats.js +23 -0
  174. package/lib/migrations/steps/2.91.0-unset-null-lint-command.js +54 -0
  175. package/package.json +1 -3
@@ -1,85 +1,35 @@
1
- /** Close-validation `project.commands.*` resolution and formatter file policy. */
1
+ /** Close-validation `project.commands.*` spawns and formatter file policy. */
2
2
 
3
- import { execFileSync } from 'node:child_process';
4
3
  import { diffNameOnly } from '../changed-files.js';
5
- import { getCommands } from '../config/commands.js';
6
-
7
- /** The typecheck and lint gates are mandatory, so they carry their own fallbacks. */
8
- const TYPECHECK_FALLBACK = 'npm run typecheck';
9
-
10
- /**
11
- * Must stay byte-identical: `commandConfigHash` covers it, and drift would
12
- * invalidate every recorded lint evidence record.
13
- */
14
- const LINT_FALLBACK = 'npm run lint';
15
-
16
- /**
17
- * Must stay byte-identical: it is the close `test` gate's argv and the credit
18
- * identity `test-run-credit` and `verify-credit` hash, so drift would
19
- * invalidate every recorded `test` evidence record.
20
- */
21
- const TEST_FALLBACK = 'npm test';
22
-
23
- export const FORMAT_CHECK_FALLBACK = 'npx biome format .';
24
-
25
- const FORMAT_WRITE_FALLBACK = 'npx biome format --write .';
4
+ import {
5
+ COMMANDS_DEFAULTS,
6
+ resolveProjectCommand,
7
+ } from '../config/commands.js';
26
8
 
27
9
  /** Derived from the write command so a Prettier repo is not told to run biome. */
28
10
  export function buildFormatHint(writeCmd) {
29
11
  const cmd =
30
- writeCmd && writeCmd.trim().length > 0 ? writeCmd : FORMAT_WRITE_FALLBACK;
12
+ writeCmd && writeCmd.trim().length > 0
13
+ ? writeCmd
14
+ : COMMANDS_DEFAULTS.formatWrite;
31
15
  return `Run \`${cmd}\` to auto-fix formatting drift.`;
32
16
  }
33
17
 
34
18
  /**
35
- * Falls back on a missing/empty value or malformed config.
19
+ * A disabled gate keeps the default argv as its (never-spawned) identity.
36
20
  *
37
- * @param {{ project?: { commands?: object } } | null | undefined} config
38
- * @param {string} key
39
- * @param {string} fallback
40
- * @returns {string}
21
+ * @param {object | null | undefined} config
22
+ * @param {keyof typeof COMMANDS_DEFAULTS} key
41
23
  */
42
- function resolveCommandWithFallback(config, key, fallback) {
43
- try {
44
- const cmds = getCommands(config);
45
- const value = cmds[key];
46
- if (typeof value === 'string' && value.trim().length > 0) {
47
- return value.trim();
48
- }
49
- } catch {
50
- // Malformed config — use the fallback.
51
- }
52
- return fallback;
24
+ export function resolveGateCommand(config, key) {
25
+ const { raw, disabled, argv } = resolveProjectCommand(config, key);
26
+ const [cmd, ...args] = disabled ? defaultArgv(key) : argv;
27
+ return { cmd, args, raw, disabled };
53
28
  }
54
29
 
55
- /**
56
- * @param {{ project?: { commands?: object } } | null | undefined} config
57
- * @returns {string}
58
- */
59
- export function resolveTypecheckCommand(config) {
60
- return resolveCommandWithFallback(config, 'typecheck', TYPECHECK_FALLBACK);
61
- }
62
-
63
- /**
64
- * Own-present explicit `null` only: `getCommands` collapses absent and `null`.
65
- *
66
- * @param {{ project?: { commands?: object } } | null | undefined} config
67
- * @returns {boolean}
68
- */
69
- export function isTypecheckDisabled(config) {
70
- const commands = config?.project?.commands;
71
- if (commands === null || typeof commands !== 'object') return false;
72
- return Object.hasOwn(commands, 'typecheck') && commands.typecheck === null;
73
- }
74
-
75
- /**
76
- * A consumer may point this at its hooks' scoped lint; CI keeps whole-repo drift.
77
- *
78
- * @param {{ project?: { commands?: object } } | null | undefined} config
79
- * @returns {string}
80
- */
81
- export function resolveLintCommand(config) {
82
- return resolveCommandWithFallback(config, 'lint', LINT_FALLBACK);
30
+ /** @param {keyof typeof COMMANDS_DEFAULTS} key */
31
+ function defaultArgv(key) {
32
+ return resolveProjectCommand(null, key).argv;
83
33
  }
84
34
 
85
35
  /**
@@ -90,46 +40,23 @@ export function resolveLintCommand(config) {
90
40
  * @returns {string}
91
41
  */
92
42
  export function resolveTestCommand(config) {
93
- return resolveCommandWithFallback(config, 'test', TEST_FALLBACK);
43
+ return resolveProjectCommand(config, 'test').raw;
94
44
  }
95
45
 
96
- /**
97
- * The argv close's `test` gate spawns — the one identity every `test`
98
- * credit (deposit, close probe, `verify[]` credit) hashes. Whitespace split,
99
- * as the gate builder splits every other `commands.*` key.
100
- *
101
- * @param {{ project?: { commands?: object } } | null | undefined} config
102
- * @returns {{ cmd: string, args: string[] }}
103
- */
46
+ /** The one identity every `test` credit hashes. @param {object|null|undefined} config */
104
47
  export function resolveTestGateArgv(config) {
105
- const [cmd, ...args] = resolveTestCommand(config)
106
- .split(/\s+/)
107
- .filter(Boolean);
48
+ const { cmd, args } = resolveGateCommand(config, 'test');
108
49
  return { cmd, args };
109
50
  }
110
51
 
111
- /**
112
- * @param {{ project?: { commands?: object } } | null | undefined} config
113
- * @returns {string}
114
- */
115
- export function resolveFormatCheckCommand(config) {
116
- return resolveCommandWithFallback(
117
- config,
118
- 'formatCheck',
119
- FORMAT_CHECK_FALLBACK,
120
- );
52
+ /** @param {object|null|undefined} config */
53
+ export function resolveFormatWriteCommand(config) {
54
+ return resolveProjectCommand(config, 'formatWrite').raw;
121
55
  }
122
56
 
123
- /**
124
- * @param {{ project?: { commands?: object } } | null | undefined} config
125
- * @returns {string}
126
- */
127
- export function resolveFormatWriteCommand(config) {
128
- return resolveCommandWithFallback(
129
- config,
130
- 'formatWrite',
131
- FORMAT_WRITE_FALLBACK,
132
- );
57
+ /** Only the default biome check gets a changed-file scope. */
58
+ export function isDefaultFormatCheck(formatCheckRaw) {
59
+ return formatCheckRaw === COMMANDS_DEFAULTS.formatCheck;
133
60
  }
134
61
 
135
62
  /**
@@ -143,23 +70,7 @@ export function listChangedFilesForFormatGate({ cwd, baseRef }) {
143
70
  if (!cwd) throw new Error('listChangedFilesForFormatGate: cwd is required');
144
71
  if (!baseRef)
145
72
  throw new Error('listChangedFilesForFormatGate: baseRef is required');
146
- const gitSpawn = (_cwd, ...args) => {
147
- try {
148
- const stdout = execFileSync('git', args, {
149
- cwd: _cwd,
150
- encoding: 'utf8',
151
- stdio: ['ignore', 'pipe', 'pipe'],
152
- });
153
- return { status: 0, stdout, stderr: '' };
154
- } catch (err) {
155
- return {
156
- status: err.status ?? 1,
157
- stdout: err.stdout ?? '',
158
- stderr: err.stderr ?? err.message,
159
- };
160
- }
161
- };
162
- return diffNameOnly({ baseRef, cwd, gitSpawn });
73
+ return diffNameOnly({ baseRef, cwd });
163
74
  }
164
75
 
165
76
  /**
@@ -6,22 +6,23 @@ import { _internals as baselineReaderInternals } from '../baselines/reader.js';
6
6
  import { getChangedFiles } from '../changed-files.js';
7
7
  import {
8
8
  COVERAGE_GATE_DEFAULTS,
9
- CRAP_GATE_DEFAULTS,
10
9
  getQuality,
10
+ resolveQuality,
11
11
  } from '../config/quality.js';
12
12
  import { filterFilesUnderTargets } from '../coverage-capture.js';
13
+ import {
14
+ isCaptureActive,
15
+ primaryCaptureSource,
16
+ } from '../coverage-capture-passes.js';
13
17
  import { hasNpmScript, readPackageScripts } from '../npm-scripts.js';
14
18
  import { KNOWN_KINDS } from '../orchestration/check-baselines/phases/parse-args.js';
15
19
  import { predictsTestEvidenceCredit } from '../test-run-credit.js';
16
20
  import {
17
21
  buildFormatHint,
18
- FORMAT_CHECK_FALLBACK,
19
- isTypecheckDisabled,
20
- resolveFormatCheckCommand,
22
+ isDefaultFormatCheck,
21
23
  resolveFormatWriteCommand,
22
- resolveLintCommand,
24
+ resolveGateCommand,
23
25
  resolveTestGateArgv,
24
- resolveTypecheckCommand,
25
26
  } from './commands.js';
26
27
 
27
28
  /**
@@ -74,33 +75,34 @@ export function isCrapGateEnabled(config) {
74
75
  }
75
76
 
76
77
  /**
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}.
78
+ * Resolves only the two gates capture reads, so a broken sibling gate block
79
+ * is left to the baselines partition's own fail-closed path.
80
80
  *
81
81
  * @param {object|undefined|null} config - Canonical resolved config.
82
- * @returns {string}
83
82
  */
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;
83
+ function captureQuality(config) {
84
+ const gates = config?.delivery?.quality?.gates ?? {};
85
+ const { crap, coverage } = gates;
86
+ return resolveQuality({ gates: { crap, coverage } });
89
87
  }
90
88
 
91
89
  /**
92
- * Coverage-capture registers when the CRAP gate is on AND the CRAP capture
93
- * script exists; {@link resolveCreditedDepositor} builds on it.
90
+ * Coverage-capture registers when the coverage or CRAP gate is on AND the
91
+ * primary capture script exists (the coverage gate's `captureScript`, or an
92
+ * own CRAP source's); {@link resolveCreditedDepositor} builds on it.
94
93
  *
95
94
  * @param {object|undefined|null} config - Canonical resolved config.
96
95
  * @param {Record<string, string>|null|undefined} scripts - `package.json` scripts.
97
96
  * @returns {boolean}
98
97
  */
99
98
  function isCoverageCaptureActive(config, scripts) {
100
- return (
101
- isCrapGateEnabled(config) &&
102
- hasNpmScript(scripts, crapCaptureScript(config))
103
- );
99
+ const { crap, coverage } = captureQuality(config);
100
+ return isCaptureActive({
101
+ crap,
102
+ coverage,
103
+ scripts,
104
+ hasNpmScriptImpl: hasNpmScript,
105
+ });
104
106
  }
105
107
 
106
108
  /**
@@ -260,14 +262,14 @@ function buildBaselinesGateEntries({ decision, kinds, env }) {
260
262
  }
261
263
 
262
264
  /**
263
- * Whitespace split; keeps an unconfigured consumer's `commandConfigHash` stable.
265
+ * The pre-decided skip an explicit `project.commands.<key>: null` registers.
264
266
  *
265
- * @param {string} commandString
266
- * @returns {{ cmd: string, args: string[] }}
267
+ * @param {{ disabled: boolean }} command
268
+ * @param {string} gateName
269
+ * @returns {{ skip?: { reason: string } }}
267
270
  */
268
- function splitCommand(commandString) {
269
- const [cmd, ...args] = commandString.split(/\s+/).filter(Boolean);
270
- return { cmd, args };
271
+ function disabledSkip(command, gateName) {
272
+ return command.disabled ? { skip: { reason: `${gateName}-disabled` } } : {};
271
273
  }
272
274
 
273
275
  /**
@@ -364,17 +366,19 @@ function coverageCaptureRunsSuite({
364
366
  /**
365
367
  * Names every suite the capture can run: under `captureScope: "affected"` a
366
368
  * 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`.
369
+ * an own CRAP source's script is named beside the coverage gate's.
368
370
  *
369
- * @param {string} captureScript The CRAP capture script ({@link crapCaptureScript}).
371
+ * @param {object|undefined|null} config - Canonical resolved config.
370
372
  * @returns {string}
371
373
  */
372
- function coverageCaptureHint(captureScript) {
374
+ function coverageCaptureHint(config) {
375
+ const { crap, coverage } = captureQuality(config);
376
+ const primary = primaryCaptureSource({ crap, coverage });
373
377
  const crapScript =
374
- captureScript === CRAP_GATE_DEFAULTS.captureScript
378
+ primary.captureScript === coverage.captureScript
375
379
  ? ''
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.`;
380
+ : `, the CRAP gate's own \`${primary.captureScript}\` (\`gates.crap.captureScript\`)`;
381
+ return `Coverage capture failed — its suite run (the \`${coverage.captureScript}\` script, \`gates.coverage.captureScript\`${crapScript}, or the affected capture script 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
382
  }
379
383
 
380
384
  const COVERAGE_CAPTURE_ARGS = Object.freeze([
@@ -438,8 +442,8 @@ export const GATE_TIMEOUT_HINT = `The gate outran the suite timeout (\`delivery.
438
442
  /**
439
443
  * Build the close-validation gate list, cheapest fast-fail first: typecheck →
440
444
  * lint → [test] → format → [quality-preview-mi] → [coverage-capture →
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
445
+ * quality-preview-crap] → check-baselines. Coverage-capture registers only when the coverage or CRAP gate is
446
+ * enabled AND its capture script (`gates.coverage.captureScript`) exists; it then carries test-failure signalling and
443
447
  * the plain `test` gate is dropped, so there is always exactly one test gate.
444
448
  *
445
449
  * @param {{ config?: object, baseBranch?: string, cwd?: string, packageScripts?: Record<string, string>, presentBaselines?: string[]|Set<string>, log?: (message: string) => void, getChangedFilesImpl?: typeof getChangedFiles }} [opts]
@@ -490,15 +494,13 @@ export function buildDefaultGates({
490
494
  '[close-validation] coverage-capture will take the incremental skip (no changed file under the CRAP target dirs) — registering the plain `test` gate so this close still runs the suite.',
491
495
  );
492
496
  }
493
- const typecheck = splitCommand(resolveTypecheckCommand(config));
494
- const lint = splitCommand(resolveLintCommand(config));
495
- const formatCheckString = resolveFormatCheckCommand(config);
496
- const format = splitCommand(formatCheckString);
497
+ const typecheck = resolveGateCommand(config, 'typecheck');
498
+ const lint = resolveGateCommand(config, 'lint');
499
+ const format = resolveGateCommand(config, 'formatCheck');
497
500
  const formatWriteString = resolveFormatWriteCommand(config);
498
- const formatChangedFileScope =
499
- formatCheckString === FORMAT_CHECK_FALLBACK
500
- ? buildChangedFileScope(baseBranch)
501
- : null;
501
+ const formatChangedFileScope = isDefaultFormatCheck(format.raw)
502
+ ? buildChangedFileScope(baseBranch)
503
+ : null;
502
504
  const baselinesGateEnv = buildBaselinesGateEnv(baseBranch);
503
505
  const baselineKinds = enabledBaselineKinds(config);
504
506
  const baselinesDecision = probeBaselinesGate({
@@ -520,13 +522,16 @@ export function buildDefaultGates({
520
522
  cmd: typecheck.cmd,
521
523
  args: typecheck.args,
522
524
  hint: TYPECHECK_HINT,
523
- ...(isTypecheckDisabled(config)
524
- ? { skip: { reason: 'typecheck-disabled' } }
525
- : {}),
525
+ ...disabledSkip(typecheck, 'typecheck'),
526
526
  },
527
527
  // Gate names stay generic though commands resolve from config, so the
528
528
  // log line, evidence keyspace and partition membership never shift.
529
- { name: 'lint', cmd: lint.cmd, args: lint.args },
529
+ {
530
+ name: 'lint',
531
+ cmd: lint.cmd,
532
+ args: lint.args,
533
+ ...disabledSkip(lint, 'lint'),
534
+ },
530
535
  ...buildTestGateEntry(
531
536
  coverageCaptureRunsSuite({
532
537
  coverageCaptureActive,
@@ -540,6 +545,7 @@ export function buildDefaultGates({
540
545
  cmd: format.cmd,
541
546
  args: format.args,
542
547
  hint: buildFormatHint(formatWriteString),
548
+ ...disabledSkip(format, 'format'),
543
549
  ...(formatChangedFileScope
544
550
  ? { changedFileScope: formatChangedFileScope }
545
551
  : {}),
@@ -551,7 +557,7 @@ export function buildDefaultGates({
551
557
  name: 'coverage-capture',
552
558
  cmd: 'node',
553
559
  args: [...COVERAGE_CAPTURE_ARGS],
554
- hint: coverageCaptureHint(crapCaptureScript(config)),
560
+ hint: coverageCaptureHint(config),
555
561
  lockEventChannel: true,
556
562
  ...(captureSkipPredicted
557
563
  ? { skip: { reason: 'incremental-no-crap-changes' } }
@@ -153,6 +153,10 @@ function spawnGate(cmd, args, opts, lock) {
153
153
  }
154
154
 
155
155
  /**
156
+ * The child always gets an env: `AP_AGENTRC_CWD` is pinned to `cwd` (layered
157
+ * last) so every gate and its `npm run` grandchildren resolve the worktree's
158
+ * `.agentrc.json`, not the config of the checkout holding the scripts.
159
+ *
156
160
  * @param {string} cmd
157
161
  * @param {string[]} args
158
162
  * @param {string} cwd
@@ -164,7 +168,7 @@ function spawnGateChild(cmd, args, cwd, env) {
164
168
  shell: process.platform === 'win32',
165
169
  stdio: ['ignore', 'pipe', 'pipe'],
166
170
  ...groupSpawnOptions(),
167
- ...(env ? { env: { ...process.env, ...env } } : {}),
171
+ env: { ...process.env, ...env, AP_AGENTRC_CWD: cwd },
168
172
  });
169
173
  }
170
174
 
@@ -15,6 +15,7 @@ import {
15
15
  } from '../../baselines/kinds/crap.js';
16
16
  import { loadFile as loadBaselineFile } from '../../baselines/reader.js';
17
17
  import { diffNameOnly } from '../../changed-files.js';
18
+ import { COVERAGE_CAPTURE_DEFAULTS } from '../../config/gates/coverage.schema.js';
18
19
  import { loadCoverage } from '../../coverage-utils.js';
19
20
  import { scanAndScore } from '../../crap-utils.js';
20
21
  import { cachedGitFetchSync } from '../../git/cached-fetch.js';
@@ -78,7 +79,7 @@ export function createCrapScorer({
78
79
  targetDirs = [],
79
80
  ignoreGlobs = [],
80
81
  requireCoverage = true,
81
- coveragePath = 'coverage/coverage-final.json',
82
+ coveragePath = COVERAGE_CAPTURE_DEFAULTS.coveragePath,
82
83
  } = {}) {
83
84
  return async (files) => {
84
85
  const abs = path.isAbsolute(coveragePath)
@@ -4,16 +4,37 @@
4
4
  * per-file baseline so a `baseline-refresh:` commit can ship with the PR.
5
5
  */
6
6
 
7
+ import path from 'node:path';
7
8
  import { getBaseline } from '../../baselines/maintainability-baseline-io.js';
8
9
  import { diffNameOnly } from '../../changed-files.js';
9
10
  import { cachedGitFetchSync } from '../../git/cached-fetch.js';
10
11
  import { gitSpawn as defaultGitSpawn } from '../../git-utils.js';
11
12
  import { calculateForSource } from '../../maintainability-engine.js';
13
+ import { reportUnscorable } from '../../maintainability-unscorable.js';
14
+ import { isScorableSourceFile } from '../../source-extensions.js';
15
+ import { transpileForReport } from '../../transpile.js';
12
16
  import { MISSING_ARG_REASONS, validateProjectionInputs } from './inputs.js';
13
17
 
14
18
  /** Absorbs floating-point noise. */
15
19
  export const DEFAULT_MI_TOLERANCE = 0.001;
16
20
 
21
+ const UNSCORABLE_TRANSPILE_REASON =
22
+ 'transpile failed; no projected MI (lint and typecheck own the syntax error)';
23
+
24
+ /**
25
+ * TS is transpiled first, as the baseline scanner does, so a `.tsx` projects
26
+ * the score its baseline row holds. `null` when the transpile fails: no
27
+ * projection beats a phantom 0-score regression.
28
+ *
29
+ * @param {string} source
30
+ * @param {string} absPath Used only to pick the transpile mode and compiler.
31
+ * @returns {number | null}
32
+ */
33
+ function scoreHeadSource(source, absPath) {
34
+ const prepared = transpileForReport(absPath, source);
35
+ return prepared === null ? null : calculateForSource(prepared);
36
+ }
37
+
17
38
  /**
18
39
  * Collapse `missing-*` to the public `missing-args` reason.
19
40
  *
@@ -73,9 +94,9 @@ function diffChangedFiles({ cwd, baseBranch, storyBranch, git }) {
73
94
  * baselineScore: number,
74
95
  * tolerance: number,
75
96
  * git: { gitSpawn: typeof defaultGitSpawn },
76
- * scoreSource: (source: string) => number,
97
+ * scoreSource: (source: string, absPath: string) => number | null,
77
98
  * }} opts
78
- * @returns {{ file: string, projected: number, baseline: number, drop: number } | null}
99
+ * @returns {{ file: string, projected?: number, reason?: string } | null}
79
100
  */
80
101
  function scoreFile({
81
102
  cwd,
@@ -88,7 +109,8 @@ function scoreFile({
88
109
  }) {
89
110
  const show = git.gitSpawn(cwd, 'show', `${storyBranch}:${file}`);
90
111
  if (show.status !== 0) return null; // deleted/renamed on the story branch
91
- const projected = scoreSource(show.stdout || '');
112
+ const projected = scoreSource(show.stdout || '', path.join(cwd, file));
113
+ if (projected === null) return { file, reason: UNSCORABLE_TRANSPILE_REASON };
92
114
  if (projected >= baselineScore - tolerance) return null;
93
115
  return {
94
116
  file,
@@ -98,6 +120,10 @@ function scoreFile({
98
120
  };
99
121
  }
100
122
 
123
+ function bucketOf(outcome) {
124
+ return outcome.reason ? 'unscorable' : 'regressions';
125
+ }
126
+
101
127
  /**
102
128
  * @param {{
103
129
  * cwd: string,
@@ -106,9 +132,9 @@ function scoreFile({
106
132
  * baseline: Record<string, number>,
107
133
  * tolerance: number,
108
134
  * git: { gitSpawn: typeof defaultGitSpawn },
109
- * scoreSource: (source: string) => number,
135
+ * scoreSource: (source: string, absPath: string) => number | null,
110
136
  * }} opts
111
- * @returns {Array<{ file: string, projected: number, baseline: number, drop: number }>}
137
+ * @returns {{ regressions: object[], unscorable: object[] }}
112
138
  */
113
139
  function collectRegressions({
114
140
  cwd,
@@ -119,12 +145,12 @@ function collectRegressions({
119
145
  git,
120
146
  scoreSource,
121
147
  }) {
122
- const regressions = [];
148
+ const found = { regressions: [], unscorable: [] };
123
149
  for (const file of files) {
124
- if (!file.endsWith('.js') && !file.endsWith('.mjs')) continue;
150
+ if (!isScorableSourceFile(file)) continue;
125
151
  const baselineScore = baseline[file];
126
152
  if (typeof baselineScore !== 'number') continue;
127
- const reg = scoreFile({
153
+ const outcome = scoreFile({
128
154
  cwd,
129
155
  storyBranch,
130
156
  file,
@@ -133,15 +159,20 @@ function collectRegressions({
133
159
  git,
134
160
  scoreSource,
135
161
  });
136
- if (reg) regressions.push(reg);
162
+ if (outcome) found[bucketOf(outcome)].push(outcome);
137
163
  }
138
- return regressions;
164
+ return found;
165
+ }
166
+
167
+ function toUnscorableEntry({ file, reason }) {
168
+ return { relPath: file, unscorable: true, reason };
139
169
  }
140
170
 
141
171
  /**
142
172
  * Scores each changed file's content at the Story branch tip (exact for a
143
173
  * clean merge). Never throws; failures resolve to
144
- * `{ ok: true, regressions: [], skipped }`.
174
+ * `{ ok: true, regressions: [], skipped }`. An unscorable file is reported,
175
+ * never a regression.
145
176
  *
146
177
  * @param {{
147
178
  * cwd: string,
@@ -150,12 +181,14 @@ function collectRegressions({
150
181
  * baselinePath: string,
151
182
  * tolerance?: number,
152
183
  * git?: { gitSpawn: typeof defaultGitSpawn },
153
- * scoreSource?: (source: string) => number,
184
+ * scoreSource?: (source: string, absPath: string) => number | null,
154
185
  * loadBaseline?: (path: string) => Record<string, number>,
186
+ * report?: typeof reportUnscorable,
155
187
  * }} opts
156
188
  * @returns {{
157
189
  * ok: boolean,
158
190
  * regressions: Array<{ file: string, projected: number, baseline: number, drop: number }>,
191
+ * unscorable?: object[],
159
192
  * skipped?: string,
160
193
  * detail?: string,
161
194
  * }}
@@ -167,8 +200,9 @@ export function projectMaintainabilityRegressions({
167
200
  baselinePath,
168
201
  tolerance = DEFAULT_MI_TOLERANCE,
169
202
  git = { gitSpawn: defaultGitSpawn },
170
- scoreSource = calculateForSource,
203
+ scoreSource = scoreHeadSource,
171
204
  loadBaseline = getBaseline,
205
+ report = reportUnscorable,
172
206
  } = {}) {
173
207
  const validation = validateProjectionInputs(
174
208
  { cwd, baseBranch, storyBranch, baselinePath },
@@ -202,7 +236,7 @@ export function projectMaintainabilityRegressions({
202
236
  };
203
237
  }
204
238
 
205
- const regressions = collectRegressions({
239
+ const { regressions, unscorable } = collectRegressions({
206
240
  cwd,
207
241
  storyBranch,
208
242
  files: diffOutcome.files,
@@ -212,7 +246,8 @@ export function projectMaintainabilityRegressions({
212
246
  scoreSource,
213
247
  });
214
248
 
215
- return { ok: regressions.length === 0, regressions };
249
+ report(unscorable.map(toUnscorableEntry));
250
+ return { ok: regressions.length === 0, regressions, unscorable };
216
251
  }
217
252
 
218
253
  /**
@@ -4,13 +4,10 @@
4
4
  */
5
5
 
6
6
  import path from 'node:path';
7
+ import { isObject } from '../json-utils.js';
7
8
 
8
9
  const LOCAL_AGENTRC = '.agentrc.local.json';
9
10
 
10
- function isPlainObject(value) {
11
- return value !== null && typeof value === 'object' && !Array.isArray(value);
12
- }
13
-
14
11
  /**
15
12
  * Deep-merge plain objects for the overlay. Arrays and scalars from
16
13
  * `override` replace the base value at that key.
@@ -20,8 +17,8 @@ function isPlainObject(value) {
20
17
  * @returns {unknown}
21
18
  */
22
19
  export function deepMergeObjects(base, override) {
23
- if (!isPlainObject(override)) return override;
24
- if (!isPlainObject(base)) return { ...override };
20
+ if (!isObject(override)) return override;
21
+ if (!isObject(base)) return { ...override };
25
22
  const out = { ...base };
26
23
  for (const key of Object.keys(override)) {
27
24
  out[key] = mergeValue(base[key], override[key]);
@@ -30,7 +27,7 @@ export function deepMergeObjects(base, override) {
30
27
  }
31
28
 
32
29
  function mergeValue(baseVal, overrideVal) {
33
- if (isPlainObject(overrideVal) && isPlainObject(baseVal)) {
30
+ if (isObject(overrideVal) && isObject(baseVal)) {
34
31
  return deepMergeObjects(baseVal, overrideVal);
35
32
  }
36
33
  return overrideVal;