mandrel 2.82.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.
- package/.agents/docs/configuration.md +4 -3
- package/.agents/schemas/agentrc.schema.json +1 -1
- package/.agents/scripts/coverage-capture.js +55 -24
- package/.agents/scripts/evidence-gate.js +7 -1
- package/.agents/scripts/lib/baselines/duplication-scanner.js +26 -2
- package/.agents/scripts/lib/close-lock-events.js +109 -0
- package/.agents/scripts/lib/close-validation/commands.js +12 -0
- package/.agents/scripts/lib/close-validation/gates.js +6 -0
- package/.agents/scripts/lib/close-validation/process.js +5 -2
- package/.agents/scripts/lib/close-validation/runner.js +14 -4
- package/.agents/scripts/lib/config-settings-schema.js +1 -1
- package/.agents/scripts/lib/full-suite-lock.js +20 -0
- package/.agents/scripts/lib/full-suite-queue.js +24 -56
- package/.agents/scripts/lib/generated/agentrc-validator.js +1 -1
- package/.agents/scripts/lib/orchestration/single-story-close/phases/close-validation.js +73 -63
- package/.agents/scripts/lib/orchestration/single-story-close/phases/reconcile-done.js +63 -0
- package/.agents/scripts/lib/orchestration/single-story-close/runner.js +3 -0
- package/.agents/scripts/lib/supervised-suite.js +8 -28
- package/README.md +167 -216
- package/docs/CHANGELOG.md +10 -0
- package/package.json +1 -1
|
@@ -86,7 +86,7 @@ Project identity, filesystem roots, planner docs context, and the commands the c
|
|
|
86
86
|
| `docsContextFiles` | No | `array<string>` | `["architecture.md","data-dictionary.md","decisions.md","patterns.md"]` | Files under `paths.docsRoot` the planner treats as standing context. Read digest-first — the docs digest names the file and the line range, and only the named section is pulled. |
|
|
87
87
|
| `commands` | No | `object` | — | Shell commands the close-validation chain spawns. Each is run from the repo root. |
|
|
88
88
|
| `commands.test` | No | `string` | `"npm test"` | Full test-suite command close's `test` gate spawns, and the identity its `test` credit is hashed under — the deposit `run-tests.js` makes, close's credit probe and `verify[]` credit all key on it, as does `mandrel doctor`'s `test-credit-path` check. Set it for a non-npm project (e.g. `python3 scripts/validation.py`); unset, it is `npm test`. Like every command here it must be a single argv (no `;`, `&&`, pipes or substitution). |
|
|
89
|
-
| `commands.typecheck` | No | `string` \| `null` | `null` | Static type-check command. `null` disables the gate for projects with no type layer
|
|
89
|
+
| `commands.typecheck` | No | `string` \| `null` | `null` | 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. |
|
|
90
90
|
| `commands.lint` | No | `string` \| `null` | `null` | Lint command run as a close-validation gate. `null` (the default) uses `npm run lint`; the gate is mandatory, so unlike `typecheck` this key cannot disable it. Point it at the scoped command your hooks already run to stop paying for a third whole-repo lint at close — the gate still lints the diff, and CI still owns whole-repo drift. Like every command here it must be a single argv (no `;`, `&&`, pipes or substitution), so wrap a multi-linter pair in one npm script and name that. |
|
|
91
91
|
| `commands.formatCheck` | No | `string` | `"npx biome format ."` | Non-mutating format verification run as a close-validation gate. |
|
|
92
92
|
| `commands.formatWrite` | No | `string` | `"npx biome format --write ."` | Mutating format command the close-time format-autofix step spawns. |
|
|
@@ -294,8 +294,9 @@ names or defaults.
|
|
|
294
294
|
and the audit-suite prompt artifacts). Override `tempRoot` to relocate it.
|
|
295
295
|
- **`commands`.** Each string must be non-empty and pass the shell-injection
|
|
296
296
|
guard (`safeString` — disallows `;`, `&`, `|`, backtick, `$`, `<`, `>`).
|
|
297
|
-
`typecheck` is nullable; `null` is the canonical "not
|
|
298
|
-
repo" value
|
|
297
|
+
`typecheck` is nullable; an explicit `null` is the canonical "not
|
|
298
|
+
applicable for this repo" value and makes close report the gate as skipped,
|
|
299
|
+
while leaving the key unset keeps the `npm run typecheck` fallback. Read the block via `getCommands(config)`
|
|
299
300
|
([`config-resolver.js`](../scripts/lib/config-resolver.js)).
|
|
300
301
|
- **`docsContextFiles`.** Entries are **plain filenames, not globs** — each
|
|
301
302
|
resolves to a single file under `paths.docsRoot`. For the decisions log this
|
|
@@ -91,7 +91,7 @@
|
|
|
91
91
|
"type": "string",
|
|
92
92
|
"pattern": "([;&|`]|\\$\\()"
|
|
93
93
|
},
|
|
94
|
-
"description": "Static type-check command. `null` disables the gate for projects with no type layer
|
|
94
|
+
"description": "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.",
|
|
95
95
|
"default": null
|
|
96
96
|
},
|
|
97
97
|
"lint": {
|
|
@@ -14,6 +14,7 @@
|
|
|
14
14
|
*/
|
|
15
15
|
import { getChangedFiles } from './lib/changed-files.js';
|
|
16
16
|
import { isDirectInvocation } from './lib/cli-utils.js';
|
|
17
|
+
import { claimLockEventSink, lockEventHooks } from './lib/close-lock-events.js';
|
|
17
18
|
import { getQuality, resolveConfig } from './lib/config-resolver.js';
|
|
18
19
|
import {
|
|
19
20
|
computeContentDigest,
|
|
@@ -68,6 +69,7 @@ export function parseArgs(argv) {
|
|
|
68
69
|
* filterFilesUnderTargetsImpl?: typeof filterFilesUnderTargets,
|
|
69
70
|
* logger?: { info: Function, warn: Function, error: Function },
|
|
70
71
|
* lockOptions?: object,
|
|
72
|
+
* env?: Record<string, string|undefined>,
|
|
71
73
|
* }} [deps]
|
|
72
74
|
* @returns {Promise<number>}
|
|
73
75
|
*/
|
|
@@ -85,30 +87,26 @@ export async function runCoverageCapture(argv = process.argv, deps = {}) {
|
|
|
85
87
|
filterFilesUnderTargetsImpl = filterFilesUnderTargets,
|
|
86
88
|
logger = Logger,
|
|
87
89
|
lockOptions = {},
|
|
90
|
+
env = process.env,
|
|
88
91
|
} = deps;
|
|
92
|
+
const lockHooks = lockEventHooks(claimLockEventSink(env));
|
|
89
93
|
const args = parseArgs(argv);
|
|
90
94
|
const config = resolveConfigImpl({ cwd: args.cwd });
|
|
91
95
|
const { crap, coverage } = getQualityImpl(config);
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
if (
|
|
100
|
-
logger.error(
|
|
101
|
-
'[coverage-capture] ✖ No "test:coverage" script in package.json. ' +
|
|
102
|
-
'Add one (e.g. "test:coverage": "node --test --experimental-test-coverage") ' +
|
|
103
|
-
'or disable the CRAP gate via delivery.quality.gates.crap.enabled=false.',
|
|
104
|
-
);
|
|
105
|
-
return 1;
|
|
106
|
-
}
|
|
96
|
+
const refused = refusal({
|
|
97
|
+
crap,
|
|
98
|
+
cwd: args.cwd,
|
|
99
|
+
readPackageScriptsImpl,
|
|
100
|
+
hasNpmScriptImpl,
|
|
101
|
+
logger,
|
|
102
|
+
});
|
|
103
|
+
if (refused !== null) return refused;
|
|
107
104
|
|
|
108
105
|
// Outermost first: the credit probe announces or refuses the run, and only
|
|
109
106
|
// a surviving run reaches the host-level full-suite lock.
|
|
110
|
-
const locked = lockedCapture(runCaptureImpl, config,
|
|
107
|
+
const locked = lockedCapture(runCaptureImpl, config, env, {
|
|
111
108
|
rerunCommand: rerunCommandFor(argv),
|
|
109
|
+
onLockOutcome: lockHooks.onLockOutcome,
|
|
112
110
|
...lockOptions,
|
|
113
111
|
});
|
|
114
112
|
const credited = creditedCapture(locked, {
|
|
@@ -139,10 +137,39 @@ export async function runCoverageCapture(argv = process.argv, deps = {}) {
|
|
|
139
137
|
logger,
|
|
140
138
|
},
|
|
141
139
|
});
|
|
142
|
-
if (timings)
|
|
140
|
+
if (timings) reportTimings(timings, logger, lockHooks);
|
|
143
141
|
return code;
|
|
144
142
|
}
|
|
145
143
|
|
|
144
|
+
/** @returns {number|null} The exit code when no capture may run. */
|
|
145
|
+
function refusal({
|
|
146
|
+
crap,
|
|
147
|
+
cwd,
|
|
148
|
+
readPackageScriptsImpl,
|
|
149
|
+
hasNpmScriptImpl,
|
|
150
|
+
logger,
|
|
151
|
+
}) {
|
|
152
|
+
if (crap.enabled === false) {
|
|
153
|
+
logger.info('[coverage-capture] CRAP gate disabled — skipping capture.');
|
|
154
|
+
return 0;
|
|
155
|
+
}
|
|
156
|
+
if (hasNpmScriptImpl(readPackageScriptsImpl(cwd), 'test:coverage')) {
|
|
157
|
+
return null;
|
|
158
|
+
}
|
|
159
|
+
// Name the fix rather than propagate npm's opaque "Missing script" exit.
|
|
160
|
+
logger.error(
|
|
161
|
+
'[coverage-capture] ✖ No "test:coverage" script in package.json. ' +
|
|
162
|
+
'Add one (e.g. "test:coverage": "node --test --experimental-test-coverage") ' +
|
|
163
|
+
'or disable the CRAP gate via delivery.quality.gates.crap.enabled=false.',
|
|
164
|
+
);
|
|
165
|
+
return 1;
|
|
166
|
+
}
|
|
167
|
+
|
|
168
|
+
function reportTimings(timings, logger, lockHooks) {
|
|
169
|
+
logger.info(`[coverage-capture] ${formatSuiteTimings(timings)}`);
|
|
170
|
+
lockHooks.onTimings(timings);
|
|
171
|
+
}
|
|
172
|
+
|
|
146
173
|
/** @param {string[]} argv */
|
|
147
174
|
function rerunCommandFor(argv) {
|
|
148
175
|
return ['node', ...argv.slice(1)].join(' ');
|
|
@@ -189,17 +216,21 @@ async function runCaptureScopes({ crap, coverage, args, capture, deps }) {
|
|
|
189
216
|
return await runFullScopeCapture(shared);
|
|
190
217
|
}
|
|
191
218
|
|
|
219
|
+
// Module-level so coverage sees them even when no test spawns the CLI.
|
|
220
|
+
function exitWith(code) {
|
|
221
|
+
process.exit(code);
|
|
222
|
+
}
|
|
223
|
+
|
|
224
|
+
function exitOnUnexpectedError(err) {
|
|
225
|
+
Logger.error('[coverage-capture] unexpected error:', err);
|
|
226
|
+
process.exit(1);
|
|
227
|
+
}
|
|
228
|
+
|
|
192
229
|
// cli-opt-out: main resolves an exit code that is forwarded via process.exit(code); runAsCli's async-main signature does not preserve the result code.
|
|
193
230
|
if (isDirectInvocation(import.meta.url)) {
|
|
194
231
|
// `--help` must not reach the core, which would spawn the whole suite.
|
|
195
232
|
(handleCoverageCaptureHelp(process.argv)
|
|
196
233
|
? Promise.resolve(0)
|
|
197
234
|
: runCoverageCapture()
|
|
198
|
-
).then(
|
|
199
|
-
(code) => process.exit(code),
|
|
200
|
-
(err) => {
|
|
201
|
-
Logger.error('[coverage-capture] unexpected error:', err);
|
|
202
|
-
process.exit(1);
|
|
203
|
-
},
|
|
204
|
-
);
|
|
235
|
+
).then(exitWith, exitOnUnexpectedError);
|
|
205
236
|
}
|
|
@@ -11,6 +11,7 @@
|
|
|
11
11
|
import { spawnSync } from 'node:child_process';
|
|
12
12
|
import { parseArgs } from 'node:util';
|
|
13
13
|
import { runAsCli } from './lib/cli-utils.js';
|
|
14
|
+
import { claimLockEventSink, lockEventHooks } from './lib/close-lock-events.js';
|
|
14
15
|
import { getQuality, resolveConfig } from './lib/config-resolver.js';
|
|
15
16
|
import {
|
|
16
17
|
fullSuiteLockPolicy,
|
|
@@ -228,12 +229,14 @@ export function runLockedSuite(
|
|
|
228
229
|
} = {},
|
|
229
230
|
) {
|
|
230
231
|
const timeoutMs = getQuality(config).coverage?.timeoutMs;
|
|
232
|
+
const lockHooks = lockEventHooks(claimLockEventSink(env));
|
|
231
233
|
return withFullSuiteLockAsync(
|
|
232
234
|
{
|
|
233
235
|
...fullSuiteLockPolicy(config, env),
|
|
234
236
|
cwd,
|
|
235
237
|
log,
|
|
236
238
|
rerunCommand: ['node', ...process.argv.slice(1)].join(' '),
|
|
239
|
+
onLockOutcome: lockHooks.onLockOutcome,
|
|
237
240
|
...lockOptions,
|
|
238
241
|
},
|
|
239
242
|
({ lockWaitMs }) =>
|
|
@@ -243,7 +246,10 @@ export function runLockedSuite(
|
|
|
243
246
|
cwd,
|
|
244
247
|
timeoutMs,
|
|
245
248
|
lockWaitMs,
|
|
246
|
-
onTimings: (t) =>
|
|
249
|
+
onTimings: (t) => {
|
|
250
|
+
log(`[evidence-gate] ${formatSuiteTimings(t)}`);
|
|
251
|
+
lockHooks.onTimings(t);
|
|
252
|
+
},
|
|
247
253
|
onTimeout: () =>
|
|
248
254
|
log(
|
|
249
255
|
`[evidence-gate] ⏱ ${cmd} ${args.join(' ')} exceeded ${timeoutMs}ms — killed its process group.`,
|
|
@@ -148,6 +148,30 @@ export function readLineCount(absPath) {
|
|
|
148
148
|
return lines.length;
|
|
149
149
|
}
|
|
150
150
|
|
|
151
|
+
/** fast-glob reads a backslash as an escape. */
|
|
152
|
+
function toGlobPath(p) {
|
|
153
|
+
return p.split(path.sep).join('/');
|
|
154
|
+
}
|
|
155
|
+
|
|
156
|
+
/**
|
|
157
|
+
* jscpd 4's finder globs with `cwd: process.cwd()` and ignores its `cwd`
|
|
158
|
+
* option, so a repo-relative ignore glob only ever matches the process tree.
|
|
159
|
+
* Anchor each one at `cwd`; absolute and `**\/`-prefixed globs pass through,
|
|
160
|
+
* as jscpd itself treats them.
|
|
161
|
+
*
|
|
162
|
+
* @param {unknown} ignoreGlobs
|
|
163
|
+
* @param {string} cwd
|
|
164
|
+
* @returns {string[]}
|
|
165
|
+
*/
|
|
166
|
+
function anchorIgnoreGlobs(ignoreGlobs, cwd) {
|
|
167
|
+
if (!Array.isArray(ignoreGlobs)) return [];
|
|
168
|
+
return ignoreGlobs.map((glob) =>
|
|
169
|
+
path.isAbsolute(glob) || glob.startsWith('**/')
|
|
170
|
+
? glob
|
|
171
|
+
: toGlobPath(path.resolve(cwd, glob)),
|
|
172
|
+
);
|
|
173
|
+
}
|
|
174
|
+
|
|
151
175
|
/**
|
|
152
176
|
* @param {{
|
|
153
177
|
* targetDirs: string[],
|
|
@@ -174,14 +198,14 @@ export async function scanDuplication({
|
|
|
174
198
|
}
|
|
175
199
|
const dirs = Array.isArray(targetDirs) ? targetDirs : [];
|
|
176
200
|
const clones = await detect({
|
|
177
|
-
path: dirs,
|
|
201
|
+
path: dirs.map((dir) => toGlobPath(path.resolve(cwd, dir))),
|
|
178
202
|
cwd,
|
|
179
203
|
silent: true,
|
|
180
204
|
gitignore: false,
|
|
181
205
|
reporters: [],
|
|
182
206
|
format: formats,
|
|
183
207
|
minTokens,
|
|
184
|
-
ignore:
|
|
208
|
+
ignore: anchorIgnoreGlobs(ignoreGlobs, cwd),
|
|
185
209
|
});
|
|
186
210
|
const visited = collectVisitedFiles(clones, cwd);
|
|
187
211
|
const fileLineCounts = new Map();
|
|
@@ -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
|
-
...(
|
|
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
|
|
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,
|
|
229
|
-
const
|
|
230
|
-
|
|
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: ${
|
|
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,
|