mandrel 2.81.0 → 2.83.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 (33) hide show
  1. package/.agents/docs/configuration.md +4 -3
  2. package/.agents/schemas/agentrc.schema.json +1 -1
  3. package/.agents/scripts/coverage-capture.js +55 -24
  4. package/.agents/scripts/evidence-gate.js +7 -1
  5. package/.agents/scripts/lib/audit-to-stories/parse-audit-md.js +49 -24
  6. package/.agents/scripts/lib/baselines/duplication-scanner.js +35 -7
  7. package/.agents/scripts/lib/bootstrap/manifest.js +128 -159
  8. package/.agents/scripts/lib/close-lock-events.js +109 -0
  9. package/.agents/scripts/lib/close-validation/commands.js +12 -0
  10. package/.agents/scripts/lib/close-validation/gates.js +6 -0
  11. package/.agents/scripts/lib/close-validation/process.js +5 -2
  12. package/.agents/scripts/lib/close-validation/runner.js +14 -4
  13. package/.agents/scripts/lib/config-settings-schema.js +1 -1
  14. package/.agents/scripts/lib/full-suite-lock.js +20 -0
  15. package/.agents/scripts/lib/full-suite-queue.js +24 -56
  16. package/.agents/scripts/lib/generated/agentrc-validator.js +1 -1
  17. package/.agents/scripts/lib/orchestration/git-cleanup/phases/cli.js +31 -27
  18. package/.agents/scripts/lib/orchestration/git-cleanup/phases/render.js +25 -21
  19. package/.agents/scripts/lib/orchestration/pr-watch-poll.js +107 -0
  20. package/.agents/scripts/lib/orchestration/pr-watch.js +168 -235
  21. package/.agents/scripts/lib/orchestration/reassert-status-column.js +102 -72
  22. package/.agents/scripts/lib/orchestration/single-story-close/phases/close-validation.js +73 -63
  23. package/.agents/scripts/lib/orchestration/single-story-close/phases/post-land.js +21 -3
  24. package/.agents/scripts/lib/orchestration/single-story-close/phases/pre-gate-steps.js +44 -2
  25. package/.agents/scripts/lib/orchestration/single-story-close/phases/reconcile-done.js +63 -0
  26. package/.agents/scripts/lib/orchestration/single-story-close/runner.js +3 -0
  27. package/.agents/scripts/lib/orchestration/story-close/duplication-close-rescore.js +257 -0
  28. package/.agents/scripts/lib/orchestration/story-close/ratchet-shrink-writeback.js +341 -0
  29. package/.agents/scripts/lib/orchestration/ticketing.js +0 -9
  30. package/.agents/scripts/lib/supervised-suite.js +8 -28
  31. package/README.md +167 -216
  32. package/docs/CHANGELOG.md +29 -0
  33. package/package.json +1 -1
@@ -0,0 +1,109 @@
1
+ /**
2
+ * Close's lock-wait and suite-timing figures, as NDJSON in a per-close file
3
+ * (never gate output, which tests can forge). A child claims the env var
4
+ * before spawning, so no suite process can write to it.
5
+ */
6
+ import crypto from 'node:crypto';
7
+ import fs from 'node:fs';
8
+ import os from 'node:os';
9
+ import path from 'node:path';
10
+
11
+ const CLOSE_LOCK_EVENTS_FILE_ENV = 'MANDREL_CLOSE_LOCK_EVENTS_FILE';
12
+
13
+ const EVENT_KINDS = new Set(['lock-wait', 'suite-timings']);
14
+
15
+ function appendEvent(file, event, fsImpl) {
16
+ try {
17
+ fsImpl.appendFileSync(file, `${JSON.stringify(event)}\n`);
18
+ } catch {}
19
+ }
20
+
21
+ function parseEventLine(line) {
22
+ try {
23
+ const event = JSON.parse(line);
24
+ return EVENT_KINDS.has(event?.kind) ? event : null;
25
+ } catch {
26
+ return null;
27
+ }
28
+ }
29
+
30
+ /** @param {{ dir?: string, fsImpl?: object }} [opts] */
31
+ export function createLockEventChannel({
32
+ dir = os.tmpdir(),
33
+ fsImpl = fs,
34
+ } = {}) {
35
+ const name = `mandrel-lock-events-${process.pid}-${crypto.randomBytes(6).toString('hex')}.ndjson`;
36
+ const file = path.join(dir, name);
37
+ return {
38
+ file,
39
+ env: { [CLOSE_LOCK_EVENTS_FILE_ENV]: file },
40
+ emit: (event) => appendEvent(file, event, fsImpl),
41
+ read: () => readEvents(file, fsImpl),
42
+ dispose() {
43
+ try {
44
+ fsImpl.rmSync(file, { force: true });
45
+ } catch {}
46
+ },
47
+ };
48
+ }
49
+
50
+ function readEvents(file, fsImpl) {
51
+ let text;
52
+ try {
53
+ text = fsImpl.readFileSync(file, 'utf8');
54
+ } catch {
55
+ return [];
56
+ }
57
+ return text.split('\n').filter(Boolean).map(parseEventLine).filter(Boolean);
58
+ }
59
+
60
+ /**
61
+ * Remove the channel from `env` and return its emitter (a no-op without one).
62
+ *
63
+ * @param {Record<string, string|undefined>} [env]
64
+ * @param {{ fsImpl?: object }} [opts]
65
+ * @returns {(event: object) => void}
66
+ */
67
+ export function claimLockEventSink(env = process.env, { fsImpl = fs } = {}) {
68
+ const file = env[CLOSE_LOCK_EVENTS_FILE_ENV];
69
+ delete env[CLOSE_LOCK_EVENTS_FILE_ENV];
70
+ if (!file) return () => {};
71
+ return (event) => appendEvent(file, event, fsImpl);
72
+ }
73
+
74
+ /**
75
+ * Waits sum, an expiry sticks, the last holder wins; timings are the last.
76
+ *
77
+ * @param {object[]} events
78
+ * @returns {{ lockWait: object|null, suiteTimings: object|null }}
79
+ */
80
+ export function summarizeLockEvents(events) {
81
+ let lockWait = null;
82
+ let suiteTimings = null;
83
+ for (const event of events) {
84
+ if (event.kind === 'lock-wait') lockWait = mergeLockWait(lockWait, event);
85
+ else suiteTimings = timingsOf(event);
86
+ }
87
+ return { lockWait, suiteTimings };
88
+ }
89
+
90
+ function mergeLockWait(tally, event) {
91
+ const holder = event.holder ?? tally?.holder;
92
+ return {
93
+ waitedSeconds: (tally?.waitedSeconds ?? 0) + Number(event.waitedSeconds),
94
+ expired: Boolean(tally?.expired) || event.expired === true,
95
+ ...(holder ? { holder } : {}),
96
+ };
97
+ }
98
+
99
+ function timingsOf({ lockWaitMs, hostWaitMs, testRunMs }) {
100
+ return { lockWaitMs, hostWaitMs: hostWaitMs ?? null, testRunMs };
101
+ }
102
+
103
+ /** @param {(event: object) => void} emit */
104
+ export function lockEventHooks(emit) {
105
+ return {
106
+ onLockOutcome: (outcome) => emit({ kind: 'lock-wait', ...outcome }),
107
+ onTimings: (timings) => emit({ kind: 'suite-timings', ...timings }),
108
+ };
109
+ }
@@ -60,6 +60,18 @@ export function resolveTypecheckCommand(config) {
60
60
  return resolveCommandWithFallback(config, 'typecheck', TYPECHECK_FALLBACK);
61
61
  }
62
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
+
63
75
  /**
64
76
  * A consumer may point this at its hooks' scoped lint; CI keeps whole-repo drift.
65
77
  *
@@ -12,6 +12,7 @@ import { predictsTestEvidenceCredit } from '../test-run-credit.js';
12
12
  import {
13
13
  buildFormatHint,
14
14
  FORMAT_CHECK_FALLBACK,
15
+ isTypecheckDisabled,
15
16
  resolveFormatCheckCommand,
16
17
  resolveFormatWriteCommand,
17
18
  resolveLintCommand,
@@ -28,6 +29,7 @@ import {
28
29
  * @property {{ baseRef: string }} [changedFileScope]
29
30
  * @property {{ reason: string }} [skip] - Pre-decided skip: recorded, never spawned.
30
31
  * @property {Record<string, string>} [env] - Overlay merged over `process.env` for this gate's child only.
32
+ * @property {boolean} [lockEventChannel] - The child reports on close's lock-event channel.
31
33
  * @property {(cmd: string, args: string[], opts: { cwd: string, gateName?: string, log?: (m: string) => void, signal?: AbortSignal, env?: Record<string, string> }) => Promise<{ status: number }> | { status: number }} [run]
32
34
  * - In-process runner used instead of spawning `cmd`/`args`.
33
35
  */
@@ -487,6 +489,9 @@ export function buildDefaultGates({
487
489
  cmd: typecheck.cmd,
488
490
  args: typecheck.args,
489
491
  hint: TYPECHECK_HINT,
492
+ ...(isTypecheckDisabled(config)
493
+ ? { skip: { reason: 'typecheck-disabled' } }
494
+ : {}),
490
495
  },
491
496
  // Gate names stay generic though commands resolve from config, so the
492
497
  // log line, evidence keyspace and partition membership never shift.
@@ -516,6 +521,7 @@ export function buildDefaultGates({
516
521
  cmd: 'node',
517
522
  args: [...COVERAGE_CAPTURE_ARGS],
518
523
  hint: COVERAGE_CAPTURE_HINT,
524
+ lockEventChannel: true,
519
525
  ...(captureSkipPredicted
520
526
  ? { skip: { reason: 'incremental-no-crap-changes' } }
521
527
  : {}),
@@ -81,12 +81,12 @@ function isBiomeNoFilesProcessed(output) {
81
81
  * nothing and returns `LOCK_WAIT_EXPIRED_EXIT_CODE`, so close ends
82
82
  * `pending`. A full-suite gate's timeout is armed at spawn, re-armed on the
83
83
  * suite-ready handshake, and its lock wait, host wait and test run are logged
84
- * as three figures. Each child leads its own process group so a timeout,
84
+ * as three figures, and both reach `onLockEvent` as structured events. Each child leads its own process group so a timeout,
85
85
  * abort or parent signal kills its workers too.
86
86
  *
87
87
  * @param {string} cmd
88
88
  * @param {string[]} args
89
- * @param {{ cwd: string, signal?: AbortSignal, gateName?: string, log?: (m: string) => void, env?: Record<string, string>, tolerateNoFilesProcessed?: boolean, fullSuiteLock?: boolean, timeoutMs?: number, lockOptions?: object, skipIfSatisfied?: () => {status: number}|undefined }} opts
89
+ * @param {{ cwd: string, signal?: AbortSignal, gateName?: string, log?: (m: string) => void, env?: Record<string, string>, tolerateNoFilesProcessed?: boolean, fullSuiteLock?: boolean, timeoutMs?: number, lockOptions?: object, onLockEvent?: (event: object) => void, skipIfSatisfied?: () => {status: number}|undefined }} opts
90
90
  * @returns {Promise<{ status: number }>}
91
91
  */
92
92
  export function defaultGateRunner(cmd, args, opts = {}) {
@@ -106,6 +106,9 @@ function gateLockOptions(opts) {
106
106
  log: opts.log,
107
107
  skipIfSatisfied: opts.skipIfSatisfied,
108
108
  onWaitExpired: deferredGateStatus,
109
+ onLockOutcome: opts.onLockEvent
110
+ ? (outcome) => opts.onLockEvent({ kind: 'lock-wait', ...outcome })
111
+ : undefined,
109
112
  ...opts.lockOptions, // `rerunCommand`, plus test seams
110
113
  };
111
114
  }
@@ -123,6 +123,7 @@ function applyChangedFileScope({ gate, spawnCwd, log }) {
123
123
  * runProjections?: typeof defaultRunProjections,
124
124
  * runner?: (cmd: string, args: string[], opts: { cwd: string, signal?: AbortSignal, gateName?: string, log?: (m: string) => void }) => Promise<{ status: number }> | { status: number },
125
125
  * log?: (m: string) => void,
126
+ * lockEvents?: object|null,
126
127
  * onGateStart?: (gate: Gate) => void,
127
128
  * storyId?: number|null,
128
129
  * standalone?: boolean,
@@ -143,6 +144,7 @@ export async function runCloseValidation({
143
144
  gates = DEFAULT_GATES,
144
145
  runner = defaultGateRunner,
145
146
  log = () => {},
147
+ lockEvents = null,
146
148
  onGateStart,
147
149
  baseBranch = null,
148
150
  storyBranch = null,
@@ -159,7 +161,7 @@ export async function runCloseValidation({
159
161
  shouldSkip = defaultShouldSkip,
160
162
  } = {}) {
161
163
  const failed = [];
162
- const lockOpts = fullSuiteLockOptions({ config });
164
+ const lockOpts = fullSuiteLockOptions({ config, lockEvents });
163
165
  const skipped = [];
164
166
  const evidenceActive = useEvidence && storyId != null && standalone;
165
167
  const evidenceStoreOpts = { cwd, standalone };
@@ -359,21 +361,29 @@ export async function runCloseValidation({
359
361
  * (`coverage.timeoutMs`) so a hung suite fails instead of holding the host
360
362
  * lock; the same figure bounds its lock wait (`resolveFullSuiteLockBudget`).
361
363
  *
362
- * @param {{ config: object|null }} args
364
+ * @param {{ config: object|null, lockEvents: object|null }} args
363
365
  * @returns {{ forGate: (gate: object) => object }}
364
366
  */
365
- function fullSuiteLockOptions({ config }) {
367
+ function fullSuiteLockOptions({ config, lockEvents }) {
366
368
  const timeoutMs = getQuality(config).coverage?.timeoutMs;
367
369
  return {
368
370
  forGate(gate) {
371
+ const env = gateEnv(gate, lockEvents);
369
372
  return {
370
- ...(gate.env ? { env: gate.env } : {}),
373
+ ...(env ? { env } : {}),
374
+ ...(lockEvents ? { onLockEvent: lockEvents.emit } : {}),
371
375
  ...(gate.fullSuiteLock ? fullSuiteGateOptions(gate, timeoutMs) : {}),
372
376
  };
373
377
  },
374
378
  };
375
379
  }
376
380
 
381
+ /** Any child but a `lockEventChannel` one would leak the channel to tests. */
382
+ function gateEnv(gate, lockEvents) {
383
+ if (!(gate.lockEventChannel && lockEvents)) return gate.env;
384
+ return { ...lockEvents.env, ...gate.env };
385
+ }
386
+
377
387
  /**
378
388
  * A full-suite gate's kill bound, and the command its lock-expiry line names.
379
389
  *
@@ -92,7 +92,7 @@ const COMMANDS_SCHEMA = {
92
92
  typecheck: {
93
93
  ...NULLABLE_NONEMPTY_SAFE_STRING,
94
94
  description:
95
- 'Static type-check command. `null` disables the gate for projects with no type layer; the empty string is rejected so a typo cannot silently disable it.',
95
+ 'Static type-check command run as a close-validation gate. Left unset (the `null` default), it falls back to `npm run typecheck`. An explicit `null` disables the gate for projects with no type layer: close reports it as skipped (`typecheck-disabled`) and runs nothing. The empty string is rejected so a typo cannot silently disable it.',
96
96
  default: COMMANDS_DEFAULTS.typecheck,
97
97
  },
98
98
  lint: {
@@ -49,6 +49,7 @@ const LOCK_DEFAULTS = Object.freeze({
49
49
  sleepFn: (ms) => defaultSleep(ms),
50
50
  acquireOnceFn: (opts) => acquireSweepLock(opts),
51
51
  onWaitExpired: () => LOCK_WAIT_EXPIRED_EXIT_CODE,
52
+ onLockOutcome: () => {},
52
53
  rerunCommand: 'the same command',
53
54
  });
54
55
 
@@ -168,6 +169,7 @@ function consult(probe, applies) {
168
169
  * lockPath?: string,
169
170
  * skipIfSatisfied?: () => T|undefined,
170
171
  * onWaitExpired?: (holder: import('./full-suite-queue.js').LockHolder) => T,
172
+ * onLockOutcome?: (outcome: object) => void,
171
173
  * rerunCommand?: string,
172
174
  * }} opts A non-`undefined` `skipIfSatisfied` return stands in for the spawn.
173
175
  * @param {(timing: { lockWaitMs: number }) => Promise<T>} spawn
@@ -180,6 +182,7 @@ export async function withFullSuiteLockAsync(options, spawn) {
180
182
  lock === null && lockPath !== null
181
183
  ? await waitInLine({ ...opts, lockPath })
182
184
  : { held: lock, expired: false, waited: false, waitedMs: 0 };
185
+ reportOutcome(opts.onLockOutcome, wait);
183
186
  try {
184
187
  return await spawnOrStandIn(opts, wait, spawn);
185
188
  } finally {
@@ -187,6 +190,23 @@ export async function withFullSuiteLockAsync(options, spawn) {
187
190
  }
188
191
  }
189
192
 
193
+ /** An I/O-error wait is no outcome; a throwing callback never costs the spawn. */
194
+ function reportOutcome(onLockOutcome, wait) {
195
+ if (!isFinishedWait(wait)) return;
196
+ try {
197
+ onLockOutcome(lockOutcome(wait));
198
+ } catch {}
199
+ }
200
+
201
+ function isFinishedWait(wait) {
202
+ return wait.waited && (wait.expired || Boolean(wait.held?.acquired));
203
+ }
204
+
205
+ function lockOutcome({ waitedMs, expired, holder }) {
206
+ const outcome = { waitedSeconds: Math.round(waitedMs / 1000), expired };
207
+ return expired && holder ? { ...outcome, holder } : outcome;
208
+ }
209
+
190
210
  function withDefaults(options) {
191
211
  const opts = { ...LOCK_DEFAULTS };
192
212
  for (const [key, value] of Object.entries(options)) {
@@ -167,50 +167,6 @@ function describeHolder({ ownerId, pid, ageSeconds }) {
167
167
  return `holder ${ownerId ?? 'unknown'}, pid ${pid ?? 'unknown'}, lock age ${ageSeconds ?? 'unknown'}s`;
168
168
  }
169
169
 
170
- const HOLDER_RE =
171
- /holder ([^,\s]+), pid (\d+|unknown), lock age (\d+|unknown)s/u;
172
-
173
- /**
174
- * Log lines are the one channel that reaches close from a child capture.
175
- *
176
- * @param {string} line
177
- * @returns {{ waitedSeconds: number, expired: boolean, holder?: LockHolder }|null}
178
- */
179
- export function parseLockWaitOutcome(line) {
180
- const text = String(line ?? '');
181
- const match = /\[full-suite-lock\] (✅|⌛) [^\n]*\(waited (\d+)s[,)]/u.exec(
182
- text,
183
- );
184
- if (!match) return null;
185
- return withHolder(
186
- { waitedSeconds: Number(match[2]), expired: match[1] === '⌛' },
187
- text,
188
- );
189
- }
190
-
191
- /** An expiry line also names the holder it gave up on. */
192
- function withHolder(outcome, text) {
193
- const holder = outcome.expired ? HOLDER_RE.exec(text) : null;
194
- if (!holder) return outcome;
195
- const [, ownerId, pid, ageSeconds] = holder.map(unknownAsNull);
196
- return {
197
- ...outcome,
198
- holder: {
199
- ownerId,
200
- pid: numberOrNull(pid),
201
- ageSeconds: numberOrNull(ageSeconds),
202
- },
203
- };
204
- }
205
-
206
- function unknownAsNull(raw) {
207
- return raw === 'unknown' ? null : raw;
208
- }
209
-
210
- function numberOrNull(raw) {
211
- return raw === null ? null : Number(raw);
212
- }
213
-
214
170
  function holderLabel(lockPath, fsImpl) {
215
171
  return `holding pid ${readLockHolderPid(lockPath, fsImpl) ?? 'unknown'}`;
216
172
  }
@@ -225,17 +181,9 @@ function holderLabel(lockPath, fsImpl) {
225
181
  * @returns {Promise<{ held: object|null, expired: boolean, waited: true, waitedMs: number, holder?: LockHolder }>}
226
182
  */
227
183
  export async function waitInLine(opts) {
228
- const { lockPath, waitMs, fsImpl, nowFn, log } = opts;
229
- const startedAt = nowFn();
230
- const clock = {
231
- deadline: startedAt + Math.max(0, waitMs),
232
- nextReport: startedAt + opts.reportMs,
233
- waitedMs: () => Math.max(0, nowFn() - startedAt),
234
- waited: () => Math.round((nowFn() - startedAt) / 1000),
235
- };
236
- log(
237
- `${LOCK_TAG} ⏳ another full suite is already running on this host (${holderLabel(lockPath, fsImpl)}) — waiting up to ${Math.round(waitMs / 1000)}s for it to finish before spawning.`,
238
- );
184
+ const { lockPath, fsImpl, nowFn } = opts;
185
+ const clock = waitClock(opts);
186
+ announceWait(opts);
239
187
  const ticket = enqueueWaiter({ lockPath, nowFn, fsImpl });
240
188
  try {
241
189
  const outcome = await pollForTurn(opts, ticket, clock);
@@ -244,9 +192,29 @@ export async function waitInLine(opts) {
244
192
  } finally {
245
193
  dequeueWaiter(ticket, { fsImpl });
246
194
  }
195
+ return giveUp(opts, clock);
196
+ }
197
+
198
+ function waitClock({ waitMs, reportMs, nowFn }) {
199
+ const startedAt = nowFn();
200
+ return {
201
+ deadline: startedAt + Math.max(0, waitMs),
202
+ nextReport: startedAt + reportMs,
203
+ waitedMs: () => Math.max(0, nowFn() - startedAt),
204
+ waited: () => Math.round((nowFn() - startedAt) / 1000),
205
+ };
206
+ }
207
+
208
+ function announceWait({ lockPath, waitMs, fsImpl, log }) {
209
+ log(
210
+ `${LOCK_TAG} ⏳ another full suite is already running on this host (${holderLabel(lockPath, fsImpl)}) — waiting up to ${Math.round(waitMs / 1000)}s for it to finish before spawning.`,
211
+ );
212
+ }
213
+
214
+ function giveUp({ lockPath, fsImpl, nowFn, log, rerunCommand }, clock) {
247
215
  const holder = readLockHolder(lockPath, { fsImpl, nowFn });
248
216
  log(
249
- `${LOCK_TAG} ⌛ gave up waiting for the full-suite lock (waited ${clock.waited()}s, ${describeHolder(holder)}) — not spawning, so two full suites never overlap. Re-run once it finishes: ${opts.rerunCommand}`,
217
+ `${LOCK_TAG} ⌛ gave up waiting for the full-suite lock (waited ${clock.waited()}s, ${describeHolder(holder)}) — not spawning, so two full suites never overlap. Re-run once it finishes: ${rerunCommand}`,
250
218
  );
251
219
  return {
252
220
  held: null,