mandrel 2.87.0 → 2.89.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (170) hide show
  1. package/.agents/README.md +29 -0
  2. package/.agents/agents/auditor.md +4 -3
  3. package/.agents/docs/agentrc-reference.json +5 -2
  4. package/.agents/docs/configuration.md +14 -8
  5. package/.agents/docs/workflows.md +1 -1
  6. package/.agents/schemas/agentrc.schema.json +24 -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/coverage-capture.js +32 -49
  17. package/.agents/scripts/deliver-run.js +11 -0
  18. package/.agents/scripts/diagnose-friction.js +3 -3
  19. package/.agents/scripts/lib/audit-baselines/gate-surface.js +24 -11
  20. package/.agents/scripts/lib/audit-baselines/read.js +4 -2
  21. package/.agents/scripts/lib/audit-baselines/surface-entry.js +95 -11
  22. package/.agents/scripts/lib/baselines/coverage-updater-cli.js +6 -14
  23. package/.agents/scripts/lib/baselines/crap-preview-scan.js +3 -1
  24. package/.agents/scripts/lib/baselines/crap-updater-cli.js +38 -26
  25. package/.agents/scripts/lib/baselines/duplication-scanner.js +20 -1
  26. package/.agents/scripts/lib/baselines/env-overrides.js +39 -34
  27. package/.agents/scripts/lib/baselines/kernel.js +3 -2
  28. package/.agents/scripts/lib/baselines/kinds/crap.js +50 -53
  29. package/.agents/scripts/lib/baselines/preview-gates.js +5 -1
  30. package/.agents/scripts/lib/baselines/refresh-service.js +65 -22
  31. package/.agents/scripts/lib/baselines/writer.js +5 -1
  32. package/.agents/scripts/lib/bdd-runner-detect.js +7 -10
  33. package/.agents/scripts/lib/child-exec.js +14 -1
  34. package/.agents/scripts/lib/child-stream.js +122 -0
  35. package/.agents/scripts/lib/clean-temp.js +19 -13
  36. package/.agents/scripts/lib/cli-args.js +49 -0
  37. package/.agents/scripts/lib/close-validation/gates.js +40 -9
  38. package/.agents/scripts/lib/codex/skills-projection.js +1 -12
  39. package/.agents/scripts/lib/config/gates/crap.schema.js +15 -0
  40. package/.agents/scripts/lib/config/gates/mutation.schema.js +2 -2
  41. package/.agents/scripts/lib/config/gh-config-dir.js +63 -0
  42. package/.agents/scripts/lib/config/github.js +2 -0
  43. package/.agents/scripts/lib/config/paths.js +14 -3
  44. package/.agents/scripts/lib/config/quality.js +49 -1
  45. package/.agents/scripts/lib/config-resolver.js +78 -64
  46. package/.agents/scripts/lib/config-settings-schema-delivery.js +4 -3
  47. package/.agents/scripts/lib/config-settings-schema.js +7 -0
  48. package/.agents/scripts/lib/coverage-baseline.js +2 -2
  49. package/.agents/scripts/lib/coverage-capture-affected.js +2 -1
  50. package/.agents/scripts/lib/coverage-capture-fullscope.js +2 -2
  51. package/.agents/scripts/lib/coverage-capture-incremental.js +1 -1
  52. package/.agents/scripts/lib/coverage-capture-passes.js +143 -0
  53. package/.agents/scripts/lib/coverage-capture-usage.js +1 -1
  54. package/.agents/scripts/lib/coverage-capture.js +45 -15
  55. package/.agents/scripts/lib/crap-utils.js +65 -49
  56. package/.agents/scripts/lib/full-suite-lock.js +1 -10
  57. package/.agents/scripts/lib/gates/baseline-store.js +10 -0
  58. package/.agents/scripts/lib/generated/agentrc-validator.js +1 -1
  59. package/.agents/scripts/lib/gh-exec.js +45 -2
  60. package/.agents/scripts/lib/gh-transport.js +27 -0
  61. package/.agents/scripts/lib/git-utils.js +16 -9
  62. package/.agents/scripts/lib/maintainability-engine.js +27 -6
  63. package/.agents/scripts/lib/maintainability-utils.js +20 -2
  64. package/.agents/scripts/lib/orchestration/check-baselines/phases/evaluate.js +4 -1
  65. package/.agents/scripts/lib/orchestration/evidence-stream.js +186 -0
  66. package/.agents/scripts/lib/orchestration/file-assumptions.js +2 -19
  67. package/.agents/scripts/lib/orchestration/git-cleanup/phases/branches-reap.js +3 -7
  68. package/.agents/scripts/lib/orchestration/git-cleanup/phases/git-probes-ff.js +34 -40
  69. package/.agents/scripts/lib/orchestration/git-cleanup/phases/git-probes.js +4 -3
  70. package/.agents/scripts/lib/orchestration/plan-persist/persist-helpers.js +2 -19
  71. package/.agents/scripts/lib/orchestration/pr-watch.js +1 -5
  72. package/.agents/scripts/lib/orchestration/project-meta-cache.js +17 -4
  73. package/.agents/scripts/lib/orchestration/reassert-status-column.js +1 -8
  74. package/.agents/scripts/lib/orchestration/resolve-stories.js +1 -0
  75. package/.agents/scripts/lib/orchestration/review-providers/native.js +2 -2
  76. package/.agents/scripts/lib/orchestration/single-story-close/phase-timer.js +43 -0
  77. package/.agents/scripts/lib/orchestration/single-story-close/phases/confirm-merge.js +37 -13
  78. package/.agents/scripts/lib/orchestration/single-story-close/phases/finish.js +264 -0
  79. package/.agents/scripts/lib/orchestration/single-story-close/phases/open-pr.js +68 -0
  80. package/.agents/scripts/lib/orchestration/single-story-close/phases/pre-push.js +106 -0
  81. package/.agents/scripts/lib/orchestration/single-story-close/phases/reconcile-done.js +43 -35
  82. package/.agents/scripts/lib/orchestration/single-story-close/phases/review-halt.js +52 -0
  83. package/.agents/scripts/lib/orchestration/single-story-close/result.js +273 -0
  84. package/.agents/scripts/lib/orchestration/single-story-close/runner.js +68 -776
  85. package/.agents/scripts/lib/orchestration/story-close/context-budget-writeback.js +20 -9
  86. package/.agents/scripts/lib/orchestration/story-close/duplication-close-rescore.js +2 -2
  87. package/.agents/scripts/lib/orchestration/story-close/ratchet-shrink-writeback.js +20 -12
  88. package/.agents/scripts/lib/orchestration/story-handoff.js +50 -21
  89. package/.agents/scripts/lib/orchestration/story-progress.js +32 -12
  90. package/.agents/scripts/lib/orchestration/ticket-validator.js +3 -13
  91. package/.agents/scripts/lib/orchestration/verify-credit.js +4 -1
  92. package/.agents/scripts/lib/qa/resolve-selection.js +1 -8
  93. package/.agents/scripts/lib/single-story/confirm-and-land.js +33 -0
  94. package/.agents/scripts/lib/single-story-sweep/reconcile-closing.js +43 -11
  95. package/.agents/scripts/lib/single-story-sweep/sweep-lock.js +130 -30
  96. package/.agents/scripts/lib/skills/parse-skill.js +1 -4
  97. package/.agents/scripts/lib/story-body/story-body.js +12 -1
  98. package/.agents/scripts/lib/suite-admission.js +3 -11
  99. package/.agents/scripts/lib/temp-retention.js +25 -11
  100. package/.agents/scripts/lib/test-run-credit.js +2 -5
  101. package/.agents/scripts/lib/transpile.js +193 -31
  102. package/.agents/scripts/lib/util/paths.js +31 -0
  103. package/.agents/scripts/lib/util/sleep.js +15 -0
  104. package/.agents/scripts/lib/validation-evidence.js +29 -3
  105. package/.agents/scripts/lib/wave-runner/live-probe.js +24 -0
  106. package/.agents/scripts/lib/workers/crap-worker.js +23 -12
  107. package/.agents/scripts/lib/workers/maintainability-report-worker.js +18 -12
  108. package/.agents/scripts/lib/workflow-closure.js +1 -8
  109. package/.agents/scripts/notify.js +83 -90
  110. package/.agents/scripts/plan-context.js +8 -4
  111. package/.agents/scripts/providers/github/auth.js +14 -30
  112. package/.agents/scripts/providers/github/blocked-by-add.js +11 -27
  113. package/.agents/scripts/providers/github/compose.js +1 -0
  114. package/.agents/scripts/providers/github/gh-token-diagnostics.js +130 -0
  115. package/.agents/scripts/providers/github/identity.js +158 -0
  116. package/.agents/scripts/providers/github/issues.js +2 -2
  117. package/.agents/scripts/providers/github/mappers.js +16 -19
  118. package/.agents/scripts/providers/github/projects-v2-graphql.js +4 -36
  119. package/.agents/scripts/providers/github/request-helpers.js +44 -0
  120. package/.agents/scripts/providers/github/sub-issue-add.js +11 -28
  121. package/.agents/scripts/providers/github.js +10 -2
  122. package/.agents/scripts/quality-preview.js +6 -19
  123. package/.agents/scripts/single-story-confirm-merge.js +8 -20
  124. package/.agents/scripts/single-story-init.js +0 -1
  125. package/.agents/scripts/stories-wave-tick.js +60 -46
  126. package/.agents/scripts/story-handoff.js +2 -23
  127. package/.agents/scripts/story-review-compute.js +3 -22
  128. package/.agents/scripts/sync-claude-agents.js +1 -12
  129. package/.agents/scripts/sync-claude-commands.js +1 -12
  130. package/.agents/scripts/update-crap-baseline.js +11 -20
  131. package/.agents/scripts/update-ticket-state.js +44 -45
  132. package/.agents/templates/docs/audit-sweep-runbook.md +1 -1
  133. package/.agents/workflows/audit-accessibility.md +1 -1
  134. package/.agents/workflows/audit-adrs.md +1 -1
  135. package/.agents/workflows/audit-architecture.md +1 -1
  136. package/.agents/workflows/audit-baselines.md +9 -4
  137. package/.agents/workflows/audit-clean-code.md +1 -1
  138. package/.agents/workflows/audit-data-model.md +1 -1
  139. package/.agents/workflows/audit-dependencies.md +1 -1
  140. package/.agents/workflows/audit-devops.md +1 -1
  141. package/.agents/workflows/audit-documentation.md +1 -1
  142. package/.agents/workflows/audit-exceptions.md +2 -2
  143. package/.agents/workflows/audit-mobile.md +1 -1
  144. package/.agents/workflows/audit-navigability.md +1 -1
  145. package/.agents/workflows/audit-performance.md +1 -1
  146. package/.agents/workflows/audit-privacy.md +1 -1
  147. package/.agents/workflows/audit-quality.md +1 -1
  148. package/.agents/workflows/audit-security.md +1 -1
  149. package/.agents/workflows/audit-seo.md +1 -1
  150. package/.agents/workflows/audit-sre.md +1 -1
  151. package/.agents/workflows/audit-to-stories.md +9 -7
  152. package/.agents/workflows/audit-ux-ui.md +1 -1
  153. package/.agents/workflows/helpers/audit-lens-core.md +8 -5
  154. package/.agents/workflows/helpers/deliver-digest.md +4 -5
  155. package/.agents/workflows/helpers/deliver-story-reference.md +4 -4
  156. package/.agents/workflows/mandrel-deliver.md +3 -1
  157. package/README.md +6 -3
  158. package/docs/CHANGELOG.md +42 -0
  159. package/lib/cli/doctor-checks/codex.js +240 -0
  160. package/lib/cli/doctor-checks/merge-driver.js +79 -0
  161. package/lib/cli/doctor-checks/payload.js +201 -0
  162. package/lib/cli/doctor-checks/read-json.js +16 -0
  163. package/lib/cli/doctor-checks/runtime-deps.js +146 -0
  164. package/lib/cli/doctor-checks/spawn.js +18 -0
  165. package/lib/cli/doctor-checks/sync-parity.js +205 -0
  166. package/lib/cli/doctor-checks/test-credit-path.js +270 -0
  167. package/lib/cli/doctor-checks/toolchain.js +137 -0
  168. package/lib/cli/doctor-checks/version-current.js +82 -0
  169. package/lib/cli/registry.js +40 -1330
  170. package/package.json +1 -1
@@ -486,29 +486,51 @@ export function creditedCapture(runCaptureFn, { requireCredited, logger }) {
486
486
  * @param {string} abs Absolute artifact path that was looked for.
487
487
  * @returns {string}
488
488
  */
489
- export function missingCoverageArtifactMessage(abs) {
489
+ function missingCoverageArtifactMessage(
490
+ abs,
491
+ script = 'test:coverage',
492
+ configKey = 'delivery.quality.gates.coverage.coveragePath',
493
+ ) {
490
494
  return (
491
- `coverage artifact not found at ${abs}. \`npm run test:coverage\` must ` +
495
+ `coverage artifact not found at ${abs}. \`npm run ${script}\` must ` +
492
496
  'write Istanbul per-file JSON (the `json` reporter → coverage-final.json) ' +
493
- 'at delivery.quality.gates.coverage.coveragePath; a `json-summary` ' +
497
+ `at ${configKey}; a \`json-summary\` ` +
494
498
  '(coverage-summary.json) alone cannot feed the coverage or CRAP baselines.'
495
499
  );
496
500
  }
497
501
 
502
+ /**
503
+ * Fatal on every scope: zero scored rows would let the scope merge delete the
504
+ * in-scope rows.
505
+ */
506
+ export class MissingCoverageArtifactError extends Error {
507
+ constructor(abs, { prefix = '', cause } = {}) {
508
+ super(
509
+ `${prefix}${missingCoverageArtifactMessage(abs)}`,
510
+ cause === undefined ? undefined : { cause },
511
+ );
512
+ this.name = 'MissingCoverageArtifactError';
513
+ this.artifactPath = abs;
514
+ }
515
+ }
516
+
498
517
  /**
499
518
  * Wrap a capture runner so a green run that left no artifact at
500
519
  * `coveragePath` exits 1: a broken capture contract, not a capture. Every
501
- * capture path already returns before stamping on a non-zero code.
520
+ * capture path already returns before stamping on a non-zero code. `script`
521
+ * and `configKey` name the capture source in the refusal (an
522
+ * own CRAP source runs `crap.captureScript` into `crap.coveragePath`).
502
523
  *
503
524
  * @param {(opts: object) => Promise<number>} run
504
525
  * @param {{ cwd: string, coveragePath: string,
505
526
  * existsSync?: (p: string) => boolean,
527
+ * script?: string, configKey?: string,
506
528
  * logger: { error: Function } }} opts
507
529
  * @returns {(opts: object) => Promise<number>}
508
530
  */
509
531
  export function requireCaptureArtifact(
510
532
  run,
511
- { cwd, coveragePath, existsSync = fs.existsSync, logger },
533
+ { cwd, coveragePath, existsSync = fs.existsSync, script, configKey, logger },
512
534
  ) {
513
535
  return async (captureOpts) => {
514
536
  const code = await run(captureOpts);
@@ -516,7 +538,7 @@ export function requireCaptureArtifact(
516
538
  const abs = path.resolve(cwd, coveragePath);
517
539
  if (existsSync(abs)) return 0;
518
540
  logger.error(
519
- `[coverage-capture] ✖ test:coverage passed but ${missingCoverageArtifactMessage(abs)}`,
541
+ `[coverage-capture] ✖ ${script ?? 'test:coverage'} passed but ${missingCoverageArtifactMessage(abs, script, configKey)}`,
520
542
  );
521
543
  return 1;
522
544
  };
@@ -672,14 +694,20 @@ function lockWaitExpiredMessage(code) {
672
694
  return `[coverage-capture] ⏸ the full-suite lock wait expired with another suite still running, so this capture was deferred — no suite ran. Exiting ${code}; re-run it once that suite finishes.`;
673
695
  }
674
696
 
675
- /** @param {number} code */
676
- function timeoutMessage(code) {
677
- return `[coverage-capture] ⏱ npm run test:coverage timed out and was killed (exit ${code}) — no test verdict exists. This is usually host contention, not a failing test; re-run once the host is quieter.`;
697
+ /**
698
+ * @param {number} code
699
+ * @param {string} script
700
+ */
701
+ function timeoutMessage(code, script) {
702
+ return `[coverage-capture] ⏱ npm run ${script} timed out and was killed (exit ${code}) — no test verdict exists. This is usually host contention, not a failing test; re-run once the host is quieter.`;
678
703
  }
679
704
 
680
- /** @param {number} code */
681
- function failingSuiteMessage(code) {
682
- return `[coverage-capture] ✖ npm run test:coverage exited ${code}. Fix failing tests or coverage-threshold breaches before re-running the CRAP gate.`;
705
+ /**
706
+ * @param {number} code
707
+ * @param {string} script
708
+ */
709
+ function failingSuiteMessage(code, script) {
710
+ return `[coverage-capture] ✖ npm run ${script} exited ${code}. Fix failing tests or coverage-threshold breaches before re-running the CRAP gate.`;
683
711
  }
684
712
 
685
713
  /**
@@ -697,15 +725,17 @@ const FAILING_SUITE_REPORT = Object.freeze(['error', failingSuiteMessage]);
697
725
 
698
726
  /**
699
727
  * Report a non-zero capture; an expired lock wait or a timeout is not a
700
- * failing suite, so neither prints the failing-tests line.
728
+ * failing suite, so neither prints the failing-tests line. `script` is the
729
+ * one the pass ran (an own CRAP source runs `crap.captureScript`).
701
730
  *
702
731
  * @param {number} code
703
732
  * @param {{ info: Function, error: Function }} logger
733
+ * @param {string} [script]
704
734
  * @returns {number}
705
735
  */
706
- export function reportCaptureFailure(code, logger) {
736
+ export function reportCaptureFailure(code, logger, script = 'test:coverage') {
707
737
  const [level, message] =
708
738
  NON_FAILURE_CAPTURE_EXITS[code] ?? FAILING_SUITE_REPORT;
709
- logger[level](message(code));
739
+ logger[level](message(code, script));
710
740
  return code;
711
741
  }
@@ -14,6 +14,8 @@ import { analyzeModule } from './escomplex-kernel.js';
14
14
  import { Logger } from './Logger.js';
15
15
  import { scanDirectory } from './maintainability-utils.js';
16
16
  import {
17
+ CompilerMissingError,
18
+ preparedFailureFields,
17
19
  prepareSourceForScoring,
18
20
  resolveTsTranspilerVersion,
19
21
  } from './transpile.js';
@@ -162,7 +164,11 @@ const MIN_RESOLUTION_SAMPLE = 25;
162
164
  * @param {number} floor
163
165
  * @returns {string|null}
164
166
  */
165
- export function checkResolutionFloor(resolution, floor) {
167
+ export function checkResolutionFloor(
168
+ resolution,
169
+ floor,
170
+ captureScript = 'test:coverage',
171
+ ) {
166
172
  if (!resolution) return null;
167
173
  const { joinableMethods = 0, resolvedMethods = 0, rate = 1 } = resolution;
168
174
  if (joinableMethods < MIN_RESOLUTION_SAMPLE) return null;
@@ -179,7 +185,7 @@ export function checkResolutionFloor(resolution, floor) {
179
185
  'unresolved methods are absent and coincidental line collisions are ' +
180
186
  'mis-attributed.\n' +
181
187
  (worst ? ` Worst unresolved files:\n${worst}\n` : '') +
182
- " Regenerate coverage ('npm run test:coverage') and re-run; if the " +
188
+ ` Regenerate coverage ('npm run ${captureScript}') and re-run; if the ` +
183
189
  'rate stays low the coverage artifact and the scanned tree disagree.'
184
190
  );
185
191
  }
@@ -272,12 +278,58 @@ function projectScanRow(relPath, mr) {
272
278
  };
273
279
  }
274
280
 
281
+ /** Fold per-file results; missing compilers throw one CompilerMissingError. */
282
+ function tallyScanResults(perFile, cwd) {
283
+ const rows = [];
284
+ let skippedFilesNoCoverage = 0;
285
+ let skippedMethodsNoCoverage = 0;
286
+ let unscorableFiles = 0;
287
+ const missingCompilerDirs = [];
288
+ const resolution = newResolutionAccumulator();
289
+ for (const { item, result } of perFile) {
290
+ if (result?.compilerMissing) {
291
+ missingCompilerDirs.push(result.packageDir);
292
+ continue;
293
+ }
294
+ if (result?.skippedFileNoCoverage) {
295
+ skippedFilesNoCoverage += 1;
296
+ continue;
297
+ }
298
+ // `!result` is a pool-level error the worker never answered.
299
+ if (!result || result.rows === null) {
300
+ unscorableFiles += 1;
301
+ if (result?.error) {
302
+ Logger.warn(
303
+ `[crap-utils] failed to score ${item.relPath}: ${result.error}`,
304
+ );
305
+ }
306
+ continue;
307
+ }
308
+ skippedMethodsNoCoverage += result.skippedMethodsNoCoverage ?? 0;
309
+ accumulateResolution(resolution, item.relPath, result);
310
+ for (const mr of result.rows) {
311
+ rows.push(projectScanRow(item.relPath, mr));
312
+ }
313
+ }
314
+ if (missingCompilerDirs.length > 0) {
315
+ throw new CompilerMissingError(missingCompilerDirs, { cwd });
316
+ }
317
+ return {
318
+ rows,
319
+ skippedFilesNoCoverage,
320
+ skippedMethodsNoCoverage,
321
+ unscorableFiles,
322
+ resolution: summarizeResolution(resolution),
323
+ };
324
+ }
325
+
275
326
  /**
276
327
  * Score every method under `targetDirs` (no disk writes). Files without
277
328
  * coverage are skipped under `requireCoverage`; methods without resolvable
278
329
  * coverage are always dropped, so baselines never hold partial rows. A file
279
330
  * that cannot be read, transpiled or parsed is counted in `unscorableFiles`
280
- * so no drop is silent. `scopeFiles` filters before any I/O;
331
+ * so no drop is silent; a TypeScript file with no resolvable compiler throws
332
+ * `CompilerMissingError` instead. `scopeFiles` filters before any I/O;
281
333
  * `preScannedFiles` skips the walk; `incremental` resolves untouched files
282
334
  * from the baseline instead of fresh coverage.
283
335
  *
@@ -351,52 +403,16 @@ export async function scanAndScore({
351
403
  ? queue.map((item) => ({ item, result: scoreFileSerial(item, coverage) }))
352
404
  : await scoreFilesViaPool(queue, coverage);
353
405
 
354
- const rows = [];
355
- let skippedFilesNoCoverage = 0;
356
- let skippedMethodsNoCoverage = 0;
357
- let unscorableFiles = 0;
358
- const resolution = newResolutionAccumulator();
359
- for (const { item, result } of perFile) {
360
- if (!result) {
361
- // Pool-level error the worker never answered.
362
- unscorableFiles += 1;
363
- continue;
364
- }
365
- if (result.skippedFileNoCoverage) {
366
- skippedFilesNoCoverage += 1;
367
- continue;
368
- }
369
- if (result.rows === null) {
370
- unscorableFiles += 1;
371
- if (result.error) {
372
- Logger.warn(
373
- `[crap-utils] failed to score ${item.relPath}: ${result.error}`,
374
- );
375
- }
376
- continue;
377
- }
378
- skippedMethodsNoCoverage += result.skippedMethodsNoCoverage ?? 0;
379
- accumulateResolution(resolution, item.relPath, result);
380
- for (const mr of result.rows) {
381
- rows.push(projectScanRow(item.relPath, mr));
382
- }
383
- }
384
-
385
- rows.sort((a, b) => {
386
- if (a.file !== b.file) return a.file < b.file ? -1 : 1;
387
- if (a.startLine !== b.startLine) return a.startLine - b.startLine;
388
- if (a.method !== b.method) return a.method < b.method ? -1 : 1;
389
- return 0;
390
- });
406
+ const tally = tallyScanResults(perFile, cwd);
407
+ tally.rows.sort(compareScanRows);
408
+ return { ...tally, scannedFiles };
409
+ }
391
410
 
392
- return {
393
- rows,
394
- scannedFiles,
395
- skippedFilesNoCoverage,
396
- skippedMethodsNoCoverage,
397
- unscorableFiles,
398
- resolution: summarizeResolution(resolution),
399
- };
411
+ function compareScanRows(a, b) {
412
+ if (a.file !== b.file) return a.file < b.file ? -1 : 1;
413
+ if (a.startLine !== b.startLine) return a.startLine - b.startLine;
414
+ if (a.method !== b.method) return a.method < b.method ? -1 : 1;
415
+ return 0;
400
416
  }
401
417
 
402
418
  /** In-process scorer; the reference the worker output must match exactly. */
@@ -433,7 +449,7 @@ function scoreFileSerial(
433
449
  totalMethods: 0,
434
450
  };
435
451
  const prepared = prepareSourceForScoring(abs);
436
- if (prepared.error) return dropped;
452
+ if (prepared.error) return { ...dropped, ...preparedFailureFields(prepared) };
437
453
  const { crapRows, parseError } = analyzeOnce(
438
454
  prepared.code,
439
455
  entry,
@@ -26,6 +26,7 @@ import {
26
26
  resolveAdmission,
27
27
  resolveSuiteCapacity,
28
28
  } from './suite-admission.js';
29
+ import { defaultSleep } from './util/sleep.js';
29
30
 
30
31
  export { ADMISSION_REFUSED_EXIT_CODE };
31
32
 
@@ -281,16 +282,6 @@ function reportCompleted(opts, wait, ranMs) {
281
282
  } catch {}
282
283
  }
283
284
 
284
- /**
285
- * @param {number} ms
286
- * @returns {Promise<void>}
287
- */
288
- function defaultSleep(ms) {
289
- return new Promise((resolve) => {
290
- setTimeout(resolve, ms);
291
- });
292
- }
293
-
294
285
  /**
295
286
  * The one admission policy every caller resolves: enablement, budget,
296
287
  * capacity, and the workload `argv` classifies to.
@@ -48,6 +48,16 @@ function defaultReadFromTree({ baselinePath, projectRoot } = {}) {
48
48
  return JSON.parse(fs.readFileSync(abs, 'utf8'));
49
49
  }
50
50
 
51
+ /** Ratchet-gate read: `null` when missing, unparseable or not an object. */
52
+ export function readJsonBaseline(baselinePath) {
53
+ try {
54
+ const parsed = defaultReadFromTree({ baselinePath });
55
+ return parsed && typeof parsed === 'object' ? parsed : null;
56
+ } catch {
57
+ return null;
58
+ }
59
+ }
60
+
51
61
  /**
52
62
  * A gate may supply `readFromTree` for a "missing → empty" bootstrap (MI
53
63
  * returns `{}`); the default throws `BaselineNotFoundError`.