mandrel 2.88.0 → 2.90.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 (40) hide show
  1. package/.agents/docs/agentrc-reference.json +3 -1
  2. package/.agents/docs/configuration.md +9 -0
  3. package/.agents/schemas/agentrc.schema.json +13 -0
  4. package/.agents/scripts/board-backfill.js +253 -0
  5. package/.agents/scripts/coverage-capture.js +32 -49
  6. package/.agents/scripts/lib/audit-baselines/gate-surface.js +24 -11
  7. package/.agents/scripts/lib/audit-baselines/read.js +4 -2
  8. package/.agents/scripts/lib/audit-baselines/surface-entry.js +95 -11
  9. package/.agents/scripts/lib/baselines/crap-preview-scan.js +3 -1
  10. package/.agents/scripts/lib/baselines/crap-updater-cli.js +2 -0
  11. package/.agents/scripts/lib/baselines/kinds/crap.js +37 -16
  12. package/.agents/scripts/lib/baselines/preview-gates.js +1 -0
  13. package/.agents/scripts/lib/close-validation/gates.js +40 -9
  14. package/.agents/scripts/lib/close-validation/process.js +5 -1
  15. package/.agents/scripts/lib/config/gates/crap.schema.js +15 -0
  16. package/.agents/scripts/lib/config/quality.js +49 -1
  17. package/.agents/scripts/lib/coverage-capture-affected.js +2 -1
  18. package/.agents/scripts/lib/coverage-capture-fullscope.js +2 -2
  19. package/.agents/scripts/lib/coverage-capture-incremental.js +1 -1
  20. package/.agents/scripts/lib/coverage-capture-passes.js +143 -0
  21. package/.agents/scripts/lib/coverage-capture-usage.js +1 -1
  22. package/.agents/scripts/lib/coverage-capture.js +79 -38
  23. package/.agents/scripts/lib/crap-utils.js +6 -2
  24. package/.agents/scripts/lib/generated/agentrc-validator.js +1 -1
  25. package/.agents/scripts/lib/maintainability-utils.js +6 -1
  26. package/.agents/scripts/lib/observability/source-classifier.js +1 -0
  27. package/.agents/scripts/lib/orchestration/board-access-latch.js +101 -0
  28. package/.agents/scripts/lib/orchestration/check-baselines/phases/evaluate.js +1 -1
  29. package/.agents/scripts/lib/orchestration/column-sync.js +107 -52
  30. package/.agents/scripts/lib/orchestration/project-meta-resolver.js +44 -17
  31. package/.agents/scripts/lib/orchestration/story-handoff.js +14 -1
  32. package/.agents/scripts/lib/orchestration/verify-credit.js +4 -1
  33. package/.agents/scripts/providers/github/board-add.js +18 -9
  34. package/.agents/scripts/providers/github/projects-v2-graphql.js +15 -3
  35. package/.agents/scripts/update-crap-baseline.js +2 -2
  36. package/.agents/workflows/audit-baselines.md +7 -2
  37. package/docs/CHANGELOG.md +26 -0
  38. package/lib/cli/doctor-checks/project-access.js +114 -0
  39. package/lib/cli/registry.js +6 -0
  40. package/package.json +1 -1
@@ -3,11 +3,12 @@
3
3
  * reads it: the scorer skips uncovered methods, so a stale artifact silently
4
4
  * weakens the gate.
5
5
  */
6
- import { spawnSync } from 'node:child_process';
7
6
  import crypto from 'node:crypto';
8
7
  import fs from 'node:fs';
9
8
  import path from 'node:path';
9
+ import { spawnChild } from './child-exec.js';
10
10
  import { LOCK_WAIT_EXPIRED_EXIT_CODE } from './full-suite-lock.js';
11
+ import { Logger } from './Logger.js';
11
12
  import { TIMEOUT_EXIT_CODE } from './process-group.js';
12
13
  import {
13
14
  isScorableSourceFile,
@@ -114,6 +115,45 @@ function foldDirtySources({
114
115
  return count;
115
116
  }
116
117
 
118
+ /**
119
+ * A digest's git runner, through `spawnChild` so a repo whose index listing
120
+ * outgrows Node's 1 MiB default buffer still digests (no ENOBUFS). A failure
121
+ * throws an error tagged with the subcommand, for the warning.
122
+ *
123
+ * @param {string} cwd
124
+ * @param {{ spawnSync?: Function }} io `io.spawnSync` is the test seam.
125
+ * @returns {(...args: string[]) => string}
126
+ */
127
+ function digestGit(cwd, io) {
128
+ return (...args) => {
129
+ const res = spawnChild('git', args, { cwd, run: io.spawnSync });
130
+ if (res?.error || res?.status !== 0) {
131
+ const err =
132
+ res?.error ?? new Error(res?.stderr || `git ${args[0]} failed`);
133
+ err.gitSubcommand = args[0];
134
+ if (err.code === undefined) err.code = `exit ${res?.status}`;
135
+ throw err;
136
+ }
137
+ return res.stdout ?? '';
138
+ };
139
+ }
140
+
141
+ /**
142
+ * No digest never matches, so an unfreshable stamp is announced, not silent.
143
+ *
144
+ * @param {Error & { gitSubcommand?: string, code?: string }} err
145
+ * @param {{ logger?: { warn: Function } }} io
146
+ * @returns {null}
147
+ */
148
+ function warnDigestUnavailable(err, io) {
149
+ const logger = io.logger ?? Logger;
150
+ const subcommand = err?.gitSubcommand ?? 'digest';
151
+ logger.warn(
152
+ `[coverage-capture] ⚠ git ${subcommand} failed (${err?.code ?? 'unknown'}); digest unavailable, stamp cannot read fresh.`,
153
+ );
154
+ return null;
155
+ }
156
+
117
157
  /**
118
158
  * Digest of the scorable sources under `targetDirs`: `git ls-files -s` of
119
159
  * tracked content plus dirty files' bytes, so it moves only on content change.
@@ -122,24 +162,17 @@ function foldDirtySources({
122
162
  *
123
163
  * @param {string} cwd Absolute repo root.
124
164
  * @param {string[]} targetDirs Repo-relative directories to digest.
125
- * @param {{ spawnSync?: typeof spawnSync, readFileSync?: typeof fs.readFileSync }} [io]
165
+ * @param {{ spawnSync?: Function, readFileSync?: typeof fs.readFileSync, logger?: { warn: Function } }} [io]
126
166
  * @returns {string | null} Hex SHA-256 digest, or null when unavailable.
127
167
  */
128
168
  export function computeContentDigest(cwd, targetDirs, io = {}) {
129
- const spawn = io.spawnSync ?? spawnSync;
130
169
  const readFileSync = io.readFileSync ?? fs.readFileSync;
131
170
  const dirs = (targetDirs ?? []).filter(
132
171
  (d) => typeof d === 'string' && d.length > 0,
133
172
  );
134
173
  if (dirs.length === 0) return null;
135
174
 
136
- const git = (...args) => {
137
- const res = spawn('git', args, { cwd, encoding: 'utf8' });
138
- if (res?.error || res?.status !== 0) {
139
- throw res?.error ?? new Error(res?.stderr || `git ${args[0]} failed`);
140
- }
141
- return res.stdout ?? '';
142
- };
175
+ const git = digestGit(cwd, io);
143
176
 
144
177
  try {
145
178
  const hash = crypto.createHash('sha256');
@@ -156,8 +189,8 @@ export function computeContentDigest(cwd, targetDirs, io = {}) {
156
189
  });
157
190
  if (tracked.length + scorableDirty === 0) return null;
158
191
  return hash.digest('hex');
159
- } catch {
160
- return null;
192
+ } catch (err) {
193
+ return warnDigestUnavailable(err, io);
161
194
  }
162
195
  }
163
196
 
@@ -197,24 +230,17 @@ export function filterSuiteInputPaths(files, coveragePath = null) {
197
230
  *
198
231
  * @param {string} cwd
199
232
  * @param {string} coveragePath
200
- * @param {{ spawnSync?: typeof spawnSync, readFileSync?: typeof fs.readFileSync }} [io]
233
+ * @param {{ spawnSync?: Function, readFileSync?: typeof fs.readFileSync, logger?: { warn: Function } }} [io]
201
234
  * @returns {string | null}
202
235
  */
203
236
  export function computeTreeDigest(cwd, coveragePath, io = {}) {
204
- const spawn = io.spawnSync ?? spawnSync;
205
237
  const readFileSync = io.readFileSync ?? fs.readFileSync;
206
238
  const pathspec = [
207
239
  '--',
208
240
  '.',
209
241
  ...suiteDigestExcludedDirs(coveragePath).map((dir) => `:(exclude)${dir}`),
210
242
  ];
211
- const git = (...args) => {
212
- const res = spawn('git', args, { cwd, encoding: 'utf8' });
213
- if (res?.error || res?.status !== 0) {
214
- throw res?.error ?? new Error(res?.stderr || `git ${args[0]} failed`);
215
- }
216
- return res.stdout ?? '';
217
- };
243
+ const git = digestGit(cwd, io);
218
244
  try {
219
245
  const hash = crypto.createHash('sha256');
220
246
  hash.update(git('ls-files', '-s', ...pathspec));
@@ -231,8 +257,8 @@ export function computeTreeDigest(cwd, coveragePath, io = {}) {
231
257
  select: () => true,
232
258
  });
233
259
  return hash.digest('hex');
234
- } catch {
235
- return null;
260
+ } catch (err) {
261
+ return warnDigestUnavailable(err, io);
236
262
  }
237
263
  }
238
264
 
@@ -486,11 +512,15 @@ export function creditedCapture(runCaptureFn, { requireCredited, logger }) {
486
512
  * @param {string} abs Absolute artifact path that was looked for.
487
513
  * @returns {string}
488
514
  */
489
- function missingCoverageArtifactMessage(abs) {
515
+ function missingCoverageArtifactMessage(
516
+ abs,
517
+ script = 'test:coverage',
518
+ configKey = 'delivery.quality.gates.coverage.coveragePath',
519
+ ) {
490
520
  return (
491
- `coverage artifact not found at ${abs}. \`npm run test:coverage\` must ` +
521
+ `coverage artifact not found at ${abs}. \`npm run ${script}\` must ` +
492
522
  'write Istanbul per-file JSON (the `json` reporter → coverage-final.json) ' +
493
- 'at delivery.quality.gates.coverage.coveragePath; a `json-summary` ' +
523
+ `at ${configKey}; a \`json-summary\` ` +
494
524
  '(coverage-summary.json) alone cannot feed the coverage or CRAP baselines.'
495
525
  );
496
526
  }
@@ -513,17 +543,20 @@ export class MissingCoverageArtifactError extends Error {
513
543
  /**
514
544
  * Wrap a capture runner so a green run that left no artifact at
515
545
  * `coveragePath` exits 1: a broken capture contract, not a capture. Every
516
- * capture path already returns before stamping on a non-zero code.
546
+ * capture path already returns before stamping on a non-zero code. `script`
547
+ * and `configKey` name the capture source in the refusal (an
548
+ * own CRAP source runs `crap.captureScript` into `crap.coveragePath`).
517
549
  *
518
550
  * @param {(opts: object) => Promise<number>} run
519
551
  * @param {{ cwd: string, coveragePath: string,
520
552
  * existsSync?: (p: string) => boolean,
553
+ * script?: string, configKey?: string,
521
554
  * logger: { error: Function } }} opts
522
555
  * @returns {(opts: object) => Promise<number>}
523
556
  */
524
557
  export function requireCaptureArtifact(
525
558
  run,
526
- { cwd, coveragePath, existsSync = fs.existsSync, logger },
559
+ { cwd, coveragePath, existsSync = fs.existsSync, script, configKey, logger },
527
560
  ) {
528
561
  return async (captureOpts) => {
529
562
  const code = await run(captureOpts);
@@ -531,7 +564,7 @@ export function requireCaptureArtifact(
531
564
  const abs = path.resolve(cwd, coveragePath);
532
565
  if (existsSync(abs)) return 0;
533
566
  logger.error(
534
- `[coverage-capture] ✖ test:coverage passed but ${missingCoverageArtifactMessage(abs)}`,
567
+ `[coverage-capture] ✖ ${script ?? 'test:coverage'} passed but ${missingCoverageArtifactMessage(abs, script, configKey)}`,
535
568
  );
536
569
  return 1;
537
570
  };
@@ -687,14 +720,20 @@ function lockWaitExpiredMessage(code) {
687
720
  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.`;
688
721
  }
689
722
 
690
- /** @param {number} code */
691
- function timeoutMessage(code) {
692
- 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.`;
723
+ /**
724
+ * @param {number} code
725
+ * @param {string} script
726
+ */
727
+ function timeoutMessage(code, script) {
728
+ 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.`;
693
729
  }
694
730
 
695
- /** @param {number} code */
696
- function failingSuiteMessage(code) {
697
- return `[coverage-capture] ✖ npm run test:coverage exited ${code}. Fix failing tests or coverage-threshold breaches before re-running the CRAP gate.`;
731
+ /**
732
+ * @param {number} code
733
+ * @param {string} script
734
+ */
735
+ function failingSuiteMessage(code, script) {
736
+ return `[coverage-capture] ✖ npm run ${script} exited ${code}. Fix failing tests or coverage-threshold breaches before re-running the CRAP gate.`;
698
737
  }
699
738
 
700
739
  /**
@@ -712,15 +751,17 @@ const FAILING_SUITE_REPORT = Object.freeze(['error', failingSuiteMessage]);
712
751
 
713
752
  /**
714
753
  * Report a non-zero capture; an expired lock wait or a timeout is not a
715
- * failing suite, so neither prints the failing-tests line.
754
+ * failing suite, so neither prints the failing-tests line. `script` is the
755
+ * one the pass ran (an own CRAP source runs `crap.captureScript`).
716
756
  *
717
757
  * @param {number} code
718
758
  * @param {{ info: Function, error: Function }} logger
759
+ * @param {string} [script]
719
760
  * @returns {number}
720
761
  */
721
- export function reportCaptureFailure(code, logger) {
762
+ export function reportCaptureFailure(code, logger, script = 'test:coverage') {
722
763
  const [level, message] =
723
764
  NON_FAILURE_CAPTURE_EXITS[code] ?? FAILING_SUITE_REPORT;
724
- logger[level](message(code));
765
+ logger[level](message(code, script));
725
766
  return code;
726
767
  }
@@ -164,7 +164,11 @@ const MIN_RESOLUTION_SAMPLE = 25;
164
164
  * @param {number} floor
165
165
  * @returns {string|null}
166
166
  */
167
- export function checkResolutionFloor(resolution, floor) {
167
+ export function checkResolutionFloor(
168
+ resolution,
169
+ floor,
170
+ captureScript = 'test:coverage',
171
+ ) {
168
172
  if (!resolution) return null;
169
173
  const { joinableMethods = 0, resolvedMethods = 0, rate = 1 } = resolution;
170
174
  if (joinableMethods < MIN_RESOLUTION_SAMPLE) return null;
@@ -181,7 +185,7 @@ export function checkResolutionFloor(resolution, floor) {
181
185
  'unresolved methods are absent and coincidental line collisions are ' +
182
186
  'mis-attributed.\n' +
183
187
  (worst ? ` Worst unresolved files:\n${worst}\n` : '') +
184
- " Regenerate coverage ('npm run test:coverage') and re-run; if the " +
188
+ ` Regenerate coverage ('npm run ${captureScript}') and re-run; if the ` +
185
189
  'rate stays low the coverage artifact and the scanned tree disagree.'
186
190
  );
187
191
  }