mandrel 2.97.0 → 2.100.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/audit-checklists/quality.md +1 -0
- package/.agents/rules/api-conventions.md +4 -0
- package/.agents/rules/testing-standards.md +19 -1
- package/.agents/scripts/lib/orchestration/single-story-close/phases/pre-gate-steps.js +3 -1
- package/.agents/scripts/lib/orchestration/story-close/baseline-upward-writeback.js +1 -1
- package/.agents/scripts/lib/orchestration/story-close/commit-body.js +100 -0
- package/.agents/scripts/lib/orchestration/story-close/context-budget-writeback.js +1 -1
- package/.agents/scripts/lib/orchestration/story-close/duplication-close-rescore.js +1 -1
- package/.agents/scripts/lib/orchestration/story-close/ratchet-shrink-writeback.js +1 -1
- package/.agents/scripts/lib/test-tiers.js +14 -10
- package/.agents/scripts/run-tests.js +162 -92
- package/.agents/skills/core/code-review-and-quality/SKILL.md +1 -1
- package/.agents/workflows/audit-quality.md +7 -0
- package/.agents/workflows/helpers/code-review.md +10 -0
- package/docs/CHANGELOG.md +22 -0
- package/package.json +1 -1
|
@@ -23,4 +23,5 @@ Self-check your change against this lens's concerns before you ship:
|
|
|
23
23
|
- [ ] An optional field nothing populates
|
|
24
24
|
- [ ] Property-Based Coverage — Invariants Tested Only by Examples.
|
|
25
25
|
- [ ] Toolchain by ecosystem, never one library.
|
|
26
|
+
- [ ] Vacuous property tests.
|
|
26
27
|
- [ ] Name the property.
|
|
@@ -108,4 +108,8 @@ Before opening a PR that adds or edits an API surface:
|
|
|
108
108
|
removal is unavoidable, use expand–contract: ship the replacement,
|
|
109
109
|
migrate consumers, then delete the old surface in a later release.
|
|
110
110
|
- [ ] Naming follows [§ Payload Formatting](#payload-formatting).
|
|
111
|
+
- [ ] Every public function or endpoint states its caller obligations
|
|
112
|
+
(input preconditions, required call ordering, ownership) in its
|
|
113
|
+
JSDoc/TSDoc or schema, and the contract tier carries a negative test
|
|
114
|
+
for each obligation the surface rejects.
|
|
111
115
|
- [ ] API documentation or types are committed alongside the implementation.
|
|
@@ -33,6 +33,18 @@ never read a skipped test as coverage for its tier.
|
|
|
33
33
|
`.spec.` suffix.
|
|
34
34
|
- **Coverage.** Unit tests are where line and branch coverage targets are
|
|
35
35
|
met. Mutation testing, when configured, runs at this tier.
|
|
36
|
+
- **Property tests.** A unit whose correctness rests on an invariant — a
|
|
37
|
+
round-trip (`decode(encode(x)) === x`), idempotency, an ordering, a state
|
|
38
|
+
machine, or a documented "always"/"never" claim — states that invariant as a
|
|
39
|
+
property test with the stack's property-based library (`fast-check` for
|
|
40
|
+
JS/TS, `hypothesis` for Python, `proptest` for Rust). Keep a few example
|
|
41
|
+
tests beside it as readable witnesses; examples alone cannot reach the
|
|
42
|
+
inputs nobody thought to pick. Pin or print the seed so a red reproduces.
|
|
43
|
+
- **Failure witness.** A new property test counts only after it was seen to
|
|
44
|
+
fail against a deliberately broken implementation (a mutant: an off-by-one,
|
|
45
|
+
a dropped branch, a swapped comparison). Record the mutation in one
|
|
46
|
+
commit-body line beginning `Failure witness:`. A property no mutant can
|
|
47
|
+
fail constrains nothing.
|
|
36
48
|
|
|
37
49
|
### Contract — data crossing a boundary
|
|
38
50
|
|
|
@@ -146,7 +158,13 @@ first, then the minimum code that makes it pass, then refactoring with the
|
|
|
146
158
|
suite green; skip it only for configuration, documentation, or static-content
|
|
147
159
|
changes. For a bug fix the **Prove-It Pattern** binds — write the reproduction
|
|
148
160
|
test and watch it fail *before* implementing the fix; a fix without a
|
|
149
|
-
failing-then-passing reproduction is not done.
|
|
161
|
+
failing-then-passing reproduction is not done. The fix also states its
|
|
162
|
+
**behaviour delta** — which inputs now behave differently, and how — in one
|
|
163
|
+
commit-body line beginning `Behaviour delta:` (wrap it under commitlint's
|
|
164
|
+
100-character body-line limit). The regression test covers exactly that
|
|
165
|
+
delta: inputs inside it fail before the fix and pass after, and at least one
|
|
166
|
+
input just outside it is asserted unchanged. A fix that changes behaviour
|
|
167
|
+
beyond its stated delta reached green by being broader than the bug. Assert on outcomes rather than
|
|
150
168
|
on which internal methods were called, prefer real implementations **> fakes >
|
|
151
169
|
stubs > mocks** within [§ Mocking & Isolation](#mocking--isolation), and favour
|
|
152
170
|
DAMP over DRY so each test reads as a self-contained story named after the
|
|
@@ -10,6 +10,7 @@
|
|
|
10
10
|
|
|
11
11
|
import { Logger } from '../../../Logger.js';
|
|
12
12
|
import { runBaselineUpwardWriteback as defaultRunBaselineUpwardWriteback } from '../../story-close/baseline-upward-writeback.js';
|
|
13
|
+
import { refusalMark } from '../../story-close/commit-body.js';
|
|
13
14
|
import { runContextBudgetWriteback as defaultRunContextBudgetWriteback } from '../../story-close/context-budget-writeback.js';
|
|
14
15
|
import { runDuplicationCloseRescore as defaultRunDuplicationCloseRescore } from '../../story-close/duplication-close-rescore.js';
|
|
15
16
|
import { runScopedFormatAutofix as defaultRunScopedFormatAutofix } from '../../story-close/format-autofix.js';
|
|
@@ -74,7 +75,7 @@ async function writebackStep(
|
|
|
74
75
|
tag,
|
|
75
76
|
writeback?.committed
|
|
76
77
|
? `✅ ${describe(writeback)} as ${writeback.sha} on ${storyBranch}.`
|
|
77
|
-
:
|
|
78
|
+
: `${refusalMark(tag, writeback?.reason)} No ${noun} (${writeback?.reason ?? 'nothing to write'}).`,
|
|
78
79
|
);
|
|
79
80
|
}
|
|
80
81
|
|
|
@@ -88,6 +89,7 @@ async function bestEffort({ tag, label, progress, run }) {
|
|
|
88
89
|
try {
|
|
89
90
|
await run();
|
|
90
91
|
} catch (err) {
|
|
92
|
+
refusalMark(tag, err?.message);
|
|
91
93
|
progress(
|
|
92
94
|
tag,
|
|
93
95
|
`⚠️ ${label} failed (close continues; the gate chain is authoritative): ${err?.message ?? err}`,
|
|
@@ -28,10 +28,10 @@ import {
|
|
|
28
28
|
resolveDefaultScorer,
|
|
29
29
|
} from '../../baselines/refresh-service.js';
|
|
30
30
|
import { getQuality } from '../../config-resolver.js';
|
|
31
|
-
import { gitSync as defaultGitSync } from '../../git-utils.js';
|
|
32
31
|
import { Logger as DefaultLogger } from '../../Logger.js';
|
|
33
32
|
import { isScorableSourceFile } from '../../source-extensions.js';
|
|
34
33
|
import { toPosix } from '../../util/paths.js';
|
|
34
|
+
import { closeGitSync as defaultGitSync } from './commit-body.js';
|
|
35
35
|
import {
|
|
36
36
|
currentBranch,
|
|
37
37
|
listChangedFiles,
|
|
@@ -0,0 +1,100 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* commit-body.js — the git close-time baseline write-backs commit with: each
|
|
3
|
+
* body line bounded to commitlint's `body-max-line-length` (100), never by
|
|
4
|
+
* bypassing the consumer's hook; a refusal names the rule and warns.
|
|
5
|
+
*/
|
|
6
|
+
|
|
7
|
+
import { gitSync } from '../../git-utils.js';
|
|
8
|
+
import { Logger } from '../../Logger.js';
|
|
9
|
+
|
|
10
|
+
const BODY_LINE_MAX = 100;
|
|
11
|
+
|
|
12
|
+
/** Survives each writer's own `<label>: <message>` skip reason. */
|
|
13
|
+
const COMMIT_REFUSED = 'commit-refused:';
|
|
14
|
+
|
|
15
|
+
const ROW_PREFIX = '- ';
|
|
16
|
+
const CONTINUATION = ' ';
|
|
17
|
+
const LEFT_ELLIPSIS = '…/';
|
|
18
|
+
|
|
19
|
+
/** Keep the path's tail, cut at a segment boundary. */
|
|
20
|
+
function truncatePathLeft(rowPath, max) {
|
|
21
|
+
if (rowPath.length <= max) return rowPath;
|
|
22
|
+
const tail = rowPath.slice(rowPath.length - (max - LEFT_ELLIPSIS.length));
|
|
23
|
+
const cut = tail.indexOf('/');
|
|
24
|
+
const kept = cut >= 0 && cut < tail.length - 1 ? tail.slice(cut + 1) : tail;
|
|
25
|
+
return `${LEFT_ELLIPSIS}${kept}`;
|
|
26
|
+
}
|
|
27
|
+
|
|
28
|
+
function truncateRight(text, max) {
|
|
29
|
+
return text.length <= max ? text : `${text.slice(0, max - 1)}…`;
|
|
30
|
+
}
|
|
31
|
+
|
|
32
|
+
/** `- <path>: <detail>`, or the path then an indented detail line. */
|
|
33
|
+
function formatBodyRow(rowPath, detail) {
|
|
34
|
+
const oneLine = `${ROW_PREFIX}${rowPath}: ${detail}`;
|
|
35
|
+
if (oneLine.length <= BODY_LINE_MAX) return [oneLine];
|
|
36
|
+
return [
|
|
37
|
+
`${ROW_PREFIX}${truncatePathLeft(rowPath, BODY_LINE_MAX - ROW_PREFIX.length)}`,
|
|
38
|
+
`${CONTINUATION}${truncateRight(detail, BODY_LINE_MAX - CONTINUATION.length)}`,
|
|
39
|
+
];
|
|
40
|
+
}
|
|
41
|
+
|
|
42
|
+
/** Re-flow over-long rows (split at the last `: `); cut other long lines. */
|
|
43
|
+
function boundBody(body) {
|
|
44
|
+
return body
|
|
45
|
+
.split('\n')
|
|
46
|
+
.flatMap((line) => {
|
|
47
|
+
if (line.length <= BODY_LINE_MAX) return [line];
|
|
48
|
+
const split = line.lastIndexOf(': ');
|
|
49
|
+
if (!line.startsWith(ROW_PREFIX) || split < 0) {
|
|
50
|
+
return [truncateRight(line, BODY_LINE_MAX)];
|
|
51
|
+
}
|
|
52
|
+
return formatBodyRow(
|
|
53
|
+
line.slice(ROW_PREFIX.length, split),
|
|
54
|
+
line.slice(split + 2),
|
|
55
|
+
);
|
|
56
|
+
})
|
|
57
|
+
.join('\n');
|
|
58
|
+
}
|
|
59
|
+
|
|
60
|
+
/** The commitlint rule(s) from hook stderr — not the message, which echoes argv. */
|
|
61
|
+
function describeCommitRefusal(err) {
|
|
62
|
+
const text = String(err?.stderr || err?.message || err || '');
|
|
63
|
+
const rules = [
|
|
64
|
+
...new Set([...text.matchAll(/\[([a-z][a-z0-9-]*)\]/g)].map((m) => m[1])),
|
|
65
|
+
];
|
|
66
|
+
if (rules.length > 0)
|
|
67
|
+
return `commit-msg hook refused it [${rules.join(', ')}]`;
|
|
68
|
+
const lines = text.split('\n').map((l) => l.trim());
|
|
69
|
+
return truncateRight(lines.filter(Boolean).at(-1) ?? 'unknown', 200);
|
|
70
|
+
}
|
|
71
|
+
|
|
72
|
+
/** `git commit` itself failed (a hook refused it), not a write or `git add`. */
|
|
73
|
+
class CommitRefusedError extends Error {
|
|
74
|
+
constructor(cause) {
|
|
75
|
+
super(`${COMMIT_REFUSED} ${describeCommitRefusal(cause)}`, { cause });
|
|
76
|
+
this.name = 'CommitRefusedError';
|
|
77
|
+
}
|
|
78
|
+
}
|
|
79
|
+
|
|
80
|
+
/** Drop-in `gitSync`: a `git commit` gets bounded `-m` paragraphs. */
|
|
81
|
+
export function closeGitSync(cwd, ...args) {
|
|
82
|
+
if (args[0] !== 'commit') return gitSync(cwd, ...args);
|
|
83
|
+
const bounded = args.map((arg, i) =>
|
|
84
|
+
args[i - 1] === '-m' ? boundBody(arg) : arg,
|
|
85
|
+
);
|
|
86
|
+
try {
|
|
87
|
+
return gitSync(cwd, ...bounded);
|
|
88
|
+
} catch (err) {
|
|
89
|
+
throw new CommitRefusedError(err);
|
|
90
|
+
}
|
|
91
|
+
}
|
|
92
|
+
|
|
93
|
+
/** `⚠️` plus a warn-level log for a refused commit, else `⏭`. */
|
|
94
|
+
export function refusalMark(tag, reason) {
|
|
95
|
+
if (!String(reason ?? '').includes(COMMIT_REFUSED)) return '⏭';
|
|
96
|
+
Logger.warn(
|
|
97
|
+
`[${tag}] baseline commit refused; its rows stay stale: ${reason}`,
|
|
98
|
+
);
|
|
99
|
+
return '⚠️';
|
|
100
|
+
}
|
|
@@ -22,8 +22,8 @@ import {
|
|
|
22
22
|
loadBaseline as defaultLoadBaseline,
|
|
23
23
|
} from '../../../check-context-budget.js';
|
|
24
24
|
import { resolveDocTiers as defaultResolveDocTiers } from '../../doc-tiers.js';
|
|
25
|
-
import { gitSync as defaultGitSync } from '../../git-utils.js';
|
|
26
25
|
import { Logger as DefaultLogger } from '../../Logger.js';
|
|
26
|
+
import { closeGitSync as defaultGitSync } from './commit-body.js';
|
|
27
27
|
|
|
28
28
|
const TAG = '[context-budget-writeback]';
|
|
29
29
|
|
|
@@ -19,8 +19,8 @@ import {
|
|
|
19
19
|
} from '../../baselines/refresh-service.js';
|
|
20
20
|
import { getBaselineEpsilon } from '../../config/quality.js';
|
|
21
21
|
import { getQuality } from '../../config-resolver.js';
|
|
22
|
-
import { gitSync as defaultGitSync } from '../../git-utils.js';
|
|
23
22
|
import { Logger as DefaultLogger } from '../../Logger.js';
|
|
23
|
+
import { closeGitSync as defaultGitSync } from './commit-body.js';
|
|
24
24
|
import {
|
|
25
25
|
currentBranch,
|
|
26
26
|
listChangedFiles,
|
|
@@ -28,9 +28,9 @@ import {
|
|
|
28
28
|
extractRowsFromKnip,
|
|
29
29
|
} from '../../dead-exports-knip.js';
|
|
30
30
|
import { resolveDeadExportsMode } from '../../dead-exports-mode.js';
|
|
31
|
-
import { gitSync as defaultGitSync } from '../../git-utils.js';
|
|
32
31
|
import { Logger as DefaultLogger } from '../../Logger.js';
|
|
33
32
|
import { toPosix } from '../../util/paths.js';
|
|
33
|
+
import { closeGitSync as defaultGitSync } from './commit-body.js';
|
|
34
34
|
import { currentBranch, listDirtyPaths } from './format-autofix.js';
|
|
35
35
|
|
|
36
36
|
const TAG = '[ratchet-shrink]';
|
|
@@ -28,10 +28,10 @@ const matchesE2E = picomatch(E2E_INCLUDE, { dot: true });
|
|
|
28
28
|
const TIERS = ['full', 'quick', 'integration', 'e2e'];
|
|
29
29
|
|
|
30
30
|
/**
|
|
31
|
-
* The only
|
|
32
|
-
*
|
|
31
|
+
* The only `node --test` flags passed through; any other `--flag` is rejected,
|
|
32
|
+
* so a typo can never run nothing and exit 0.
|
|
33
33
|
*/
|
|
34
|
-
const PASSTHROUGH_FLAGS = ['--test-name-pattern', '--test-only'];
|
|
34
|
+
export const PASSTHROUGH_FLAGS = ['--test-name-pattern', '--test-only'];
|
|
35
35
|
|
|
36
36
|
/** Roots scanned for `*.test.js`, including colocated `__tests__` trees. */
|
|
37
37
|
const TEST_WALK_ROOTS = ['tests', 'lib', '.agents/scripts'];
|
|
@@ -115,6 +115,16 @@ export function listTestFilesForTier(tier, repoRoot, fsLike = fs) {
|
|
|
115
115
|
return splitBySpeed(rest, tier);
|
|
116
116
|
}
|
|
117
117
|
|
|
118
|
+
/** The one unrecognized-argument error every run-tests flag check throws. */
|
|
119
|
+
export function unrecognizedArgument(args) {
|
|
120
|
+
return new Error(
|
|
121
|
+
`[run-tests] unrecognized argument(s): ${args.join(', ')}. ` +
|
|
122
|
+
`Accepted: --tier <${TIERS.join('|')}>, ${PASSTHROUGH_FLAGS.join(', ')}, --shard <i>/<n>, --help. ` +
|
|
123
|
+
'Unrecognized flags are not forwarded: `node --test` would read them as ' +
|
|
124
|
+
'file patterns and exit 0 having run nothing.',
|
|
125
|
+
);
|
|
126
|
+
}
|
|
127
|
+
|
|
118
128
|
/**
|
|
119
129
|
* @param {string[]} rest
|
|
120
130
|
* @throws {Error} naming both the accepted tiers and the accepted flags.
|
|
@@ -126,13 +136,7 @@ function assertKnownFlags(rest) {
|
|
|
126
136
|
!PASSTHROUGH_FLAGS.includes(arg) &&
|
|
127
137
|
!PASSTHROUGH_FLAGS.some((flag) => arg.startsWith(`${flag}=`)),
|
|
128
138
|
);
|
|
129
|
-
if (unknown.length
|
|
130
|
-
throw new Error(
|
|
131
|
-
`[run-tests] unrecognized argument(s): ${unknown.join(', ')}. ` +
|
|
132
|
-
`Accepted: --tier <${TIERS.join('|')}>, ${PASSTHROUGH_FLAGS.join(', ')}, --help. ` +
|
|
133
|
-
'Unrecognized flags are not forwarded: `node --test` would read them as ' +
|
|
134
|
-
'file patterns and exit 0 having run nothing.',
|
|
135
|
-
);
|
|
139
|
+
if (unknown.length > 0) throw unrecognizedArgument(unknown);
|
|
136
140
|
}
|
|
137
141
|
|
|
138
142
|
/**
|
|
@@ -5,19 +5,20 @@
|
|
|
5
5
|
* Cross-platform driver for `npm test`. Cleanup runs in-process so reserved
|
|
6
6
|
* temp artefacts are removed even when tests fail (`posttest` would not run).
|
|
7
7
|
*
|
|
8
|
-
* The
|
|
8
|
+
* The tier runs through one in-process `node:test` `run()` call with process
|
|
9
|
+
* isolation: files reach each child one path at a time, so no command line
|
|
10
|
+
* ever carries the whole tier. Children inherit this process's env and cwd
|
|
11
|
+
* (Node 22's `run()` takes neither option), so both are swapped for the run.
|
|
12
|
+
* The env unsets `NOTIFICATION_WEBHOOK_URL` so no test POSTs to a live
|
|
9
13
|
* webhook from `.env` (`MANDREL_ALLOW_TEST_WEBHOOKS=1` opts back in).
|
|
10
14
|
*
|
|
11
|
-
* Every tier enumerates explicit file targets (`node --test` has no negative
|
|
12
|
-
* pattern), which overflows the Windows ~32 767-char command line, so targets
|
|
13
|
-
* are chunked into one spawn per chunk.
|
|
14
|
-
*
|
|
15
15
|
* A green full-tier run in a `story-<id>` checkout deposits close's `test`
|
|
16
16
|
* gate evidence.
|
|
17
17
|
*/
|
|
18
18
|
|
|
19
|
-
import { spawnSync } from 'node:child_process';
|
|
20
19
|
import path from 'node:path';
|
|
20
|
+
import { run } from 'node:test';
|
|
21
|
+
import { spec, tap } from 'node:test/reporters';
|
|
21
22
|
import { fileURLToPath } from 'node:url';
|
|
22
23
|
import { assertNoReservedIdStreams } from './check-test-temp-hygiene.js';
|
|
23
24
|
import { cleanupRepoTestTempArtifacts } from './cleanup-repo-test-temp.js';
|
|
@@ -31,11 +32,21 @@ import {
|
|
|
31
32
|
TEST_CONCURRENCY_MIN,
|
|
32
33
|
TEST_RUNNER_FLAGS,
|
|
33
34
|
} from './lib/test-runner-contract.js';
|
|
34
|
-
import {
|
|
35
|
+
import {
|
|
36
|
+
listTestFilesForTier,
|
|
37
|
+
PASSTHROUGH_FLAGS,
|
|
38
|
+
parseTierArgv,
|
|
39
|
+
unrecognizedArgument,
|
|
40
|
+
} from './lib/test-tiers.js';
|
|
35
41
|
|
|
36
42
|
const __dirname = path.dirname(fileURLToPath(import.meta.url));
|
|
37
43
|
const ROOT = path.resolve(__dirname, '..', '..');
|
|
38
44
|
|
|
45
|
+
/** Child node flags, derived from the shared declaration (module mocks). */
|
|
46
|
+
const CHILD_EXEC_ARGV = TEST_RUNNER_FLAGS.filter((f) =>
|
|
47
|
+
f.startsWith('--experimental-'),
|
|
48
|
+
);
|
|
49
|
+
|
|
39
50
|
export {
|
|
40
51
|
resolveTestConcurrency,
|
|
41
52
|
TEST_CONCURRENCY_MAX,
|
|
@@ -43,52 +54,6 @@ export {
|
|
|
43
54
|
TEST_RUNNER_FLAGS,
|
|
44
55
|
};
|
|
45
56
|
|
|
46
|
-
/**
|
|
47
|
-
* Per-spawn budget for the joined targets. Windows: ~a quarter of the
|
|
48
|
-
* 32 767-char ceiling, leaving room for exe path and flags. POSIX `ARG_MAX` is
|
|
49
|
-
* far larger, so its budget keeps a tier in one spawn (each extra chunk pays a
|
|
50
|
-
* runner start-up and idles cores at its tail).
|
|
51
|
-
*/
|
|
52
|
-
export const MAX_TARGET_CHARS = 8000;
|
|
53
|
-
export const POSIX_MAX_TARGET_CHARS = 100_000;
|
|
54
|
-
|
|
55
|
-
/**
|
|
56
|
-
* @param {NodeJS.Platform} [platform]
|
|
57
|
-
* @returns {number}
|
|
58
|
-
*/
|
|
59
|
-
export function resolveMaxTargetChars(platform = process.platform) {
|
|
60
|
-
return platform === 'win32' ? MAX_TARGET_CHARS : POSIX_MAX_TARGET_CHARS;
|
|
61
|
-
}
|
|
62
|
-
|
|
63
|
-
/**
|
|
64
|
-
* Order-preserving chunks with joined length ≤ `maxChars`. An oversized
|
|
65
|
-
* target gets its own chunk; an empty list yields one empty chunk so the
|
|
66
|
-
* caller still spawns once.
|
|
67
|
-
*
|
|
68
|
-
* @param {string[]} targets
|
|
69
|
-
* @param {number} [maxChars]
|
|
70
|
-
* @returns {string[][]}
|
|
71
|
-
*/
|
|
72
|
-
export function chunkTestTargets(targets, maxChars = MAX_TARGET_CHARS) {
|
|
73
|
-
const chunks = [];
|
|
74
|
-
let current = [];
|
|
75
|
-
let currentLen = 0;
|
|
76
|
-
|
|
77
|
-
for (const target of targets) {
|
|
78
|
-
const addition = target.length + (current.length > 0 ? 1 : 0);
|
|
79
|
-
if (current.length > 0 && currentLen + addition > maxChars) {
|
|
80
|
-
chunks.push(current);
|
|
81
|
-
current = [];
|
|
82
|
-
currentLen = 0;
|
|
83
|
-
}
|
|
84
|
-
current.push(target);
|
|
85
|
-
currentLen += target.length + (current.length > 1 ? 1 : 0);
|
|
86
|
-
}
|
|
87
|
-
|
|
88
|
-
if (current.length > 0) chunks.push(current);
|
|
89
|
-
return chunks.length > 0 ? chunks : [[]];
|
|
90
|
-
}
|
|
91
|
-
|
|
92
57
|
/**
|
|
93
58
|
* Every flag must precede the targets: Node stops parsing options at the
|
|
94
59
|
* first positional and reads a later flag as a file pattern. Hence
|
|
@@ -116,61 +81,166 @@ export function buildNodeTestArgs({
|
|
|
116
81
|
];
|
|
117
82
|
}
|
|
118
83
|
|
|
119
|
-
|
|
84
|
+
const SHARD_RE = /^(\d+)\/(\d+)$/;
|
|
85
|
+
|
|
86
|
+
/** `i/n` with 1 ≤ i ≤ n, else null. */
|
|
87
|
+
function parseShardValue(raw) {
|
|
88
|
+
const match = SHARD_RE.exec(raw ?? '');
|
|
89
|
+
const index = Number(match?.[1]);
|
|
90
|
+
const total = Number(match?.[2]);
|
|
91
|
+
return index >= 1 && index <= total ? { index, total } : null;
|
|
92
|
+
}
|
|
93
|
+
|
|
94
|
+
/**
|
|
95
|
+
* Pull `--shard <i>/<n>` or `--shard=<i>/<n>` out of argv; a malformed or
|
|
96
|
+
* out-of-range value throws the unrecognized-argument error.
|
|
97
|
+
*/
|
|
98
|
+
export function extractShard(argv) {
|
|
99
|
+
const at = argv.findIndex((a) => a === '--shard' || a.startsWith('--shard='));
|
|
100
|
+
if (at === -1) return { shard: null, argv };
|
|
101
|
+
const span = argv[at] === '--shard' ? 2 : 1;
|
|
102
|
+
const flag = argv.slice(at, at + span).join(' ');
|
|
103
|
+
const shard = parseShardValue(flag.slice('--shard '.length));
|
|
104
|
+
if (!shard) throw unrecognizedArgument([flag]);
|
|
105
|
+
return { shard, argv: argv.filter((_, i) => i < at || i >= at + span) };
|
|
106
|
+
}
|
|
107
|
+
|
|
108
|
+
/**
|
|
109
|
+
* Shard `i` of `n` keeps every file whose index ≡ i-1 (mod n) — the rule
|
|
110
|
+
* `node --test --test-shard` applies — so shards partition the list.
|
|
111
|
+
*/
|
|
112
|
+
export function shardTestFiles(files, shard) {
|
|
113
|
+
if (!shard) return files;
|
|
114
|
+
return files.filter((_, i) => i % shard.total === shard.index - 1);
|
|
115
|
+
}
|
|
116
|
+
|
|
117
|
+
/**
|
|
118
|
+
* Map the pass-through argv onto `run()` options. A bare positional is an
|
|
119
|
+
* extra file, as it was on the old `node --test` command line.
|
|
120
|
+
*
|
|
121
|
+
* @param {string[]} rest
|
|
122
|
+
* @returns {{ testNamePatterns?: string[], only: boolean, files: string[] }}
|
|
123
|
+
*/
|
|
124
|
+
export function toRunOptions(rest) {
|
|
125
|
+
const [namePattern, onlyFlag] = PASSTHROUGH_FLAGS;
|
|
126
|
+
const patterns = [];
|
|
127
|
+
const files = [];
|
|
128
|
+
let only = false;
|
|
129
|
+
for (let i = 0; i < rest.length; i += 1) {
|
|
130
|
+
const arg = rest[i];
|
|
131
|
+
if (arg === namePattern) {
|
|
132
|
+
i += 1;
|
|
133
|
+
patterns.push(rest[i]);
|
|
134
|
+
} else if (arg.startsWith(`${namePattern}=`)) {
|
|
135
|
+
patterns.push(arg.slice(namePattern.length + 1));
|
|
136
|
+
} else if (arg === onlyFlag) {
|
|
137
|
+
only = true;
|
|
138
|
+
} else {
|
|
139
|
+
files.push(arg);
|
|
140
|
+
}
|
|
141
|
+
}
|
|
142
|
+
return {
|
|
143
|
+
...(patterns.length > 0 ? { testNamePatterns: patterns } : {}),
|
|
144
|
+
only,
|
|
145
|
+
files,
|
|
146
|
+
};
|
|
147
|
+
}
|
|
148
|
+
|
|
149
|
+
function replaceProcessEnv(next) {
|
|
150
|
+
for (const key of Object.keys(process.env)) {
|
|
151
|
+
if (!Object.hasOwn(next, key)) delete process.env[key];
|
|
152
|
+
}
|
|
153
|
+
Object.assign(process.env, next);
|
|
154
|
+
}
|
|
155
|
+
|
|
156
|
+
/**
|
|
157
|
+
* The default runner: one `run()` over `files`, reported as TAP off a TTY
|
|
158
|
+
* (CI logs, `test-output.txt`) and spec on one. Resolves 1 when any non-todo
|
|
159
|
+
* test fails — a crashing file reports as a failed file-level test.
|
|
160
|
+
*/
|
|
161
|
+
export async function runNodeTests({
|
|
162
|
+
files,
|
|
163
|
+
cwd,
|
|
164
|
+
env,
|
|
165
|
+
testNamePatterns,
|
|
166
|
+
only = false,
|
|
167
|
+
stdout = process.stdout,
|
|
168
|
+
}) {
|
|
169
|
+
const savedEnv = { ...process.env };
|
|
170
|
+
const savedCwd = process.cwd();
|
|
171
|
+
replaceProcessEnv(env);
|
|
172
|
+
process.chdir(cwd);
|
|
173
|
+
let failed = false;
|
|
174
|
+
try {
|
|
175
|
+
const stream = run({
|
|
176
|
+
files,
|
|
177
|
+
isolation: 'process',
|
|
178
|
+
concurrency: resolveTestConcurrency(),
|
|
179
|
+
execArgv: CHILD_EXEC_ARGV,
|
|
180
|
+
testNamePatterns,
|
|
181
|
+
only,
|
|
182
|
+
});
|
|
183
|
+
stream.on('test:fail', (data) => {
|
|
184
|
+
if (!data.todo) failed = true;
|
|
185
|
+
});
|
|
186
|
+
for await (const chunk of stream.compose(stdout.isTTY ? new spec() : tap)) {
|
|
187
|
+
stdout.write(chunk);
|
|
188
|
+
}
|
|
189
|
+
} finally {
|
|
190
|
+
process.chdir(savedCwd);
|
|
191
|
+
replaceProcessEnv(savedEnv);
|
|
192
|
+
}
|
|
193
|
+
return failed ? 1 : 0;
|
|
194
|
+
}
|
|
195
|
+
|
|
196
|
+
export async function runTestSuite({
|
|
120
197
|
argv = process.argv.slice(2),
|
|
121
198
|
cwd = ROOT,
|
|
122
|
-
|
|
199
|
+
runTests = runNodeTests,
|
|
123
200
|
cleanup = cleanupRepoTestTempArtifacts,
|
|
124
201
|
listTargets = listTestFilesForTier,
|
|
125
|
-
maxTargetChars = resolveMaxTargetChars(),
|
|
126
202
|
fixtureStreamGuard = assertNoReservedIdStreams,
|
|
127
203
|
preflight = runTierPreflight,
|
|
128
204
|
depositCredit = reportTestRunCredit,
|
|
205
|
+
stdout = process.stdout,
|
|
129
206
|
} = {}) {
|
|
130
|
-
const {
|
|
207
|
+
const { shard, argv: unsharded } = extractShard(argv);
|
|
208
|
+
const { tier, rest } = parseTierArgv(unsharded);
|
|
131
209
|
|
|
132
210
|
// Nothing has been created yet, so a refusal needs no cleanup.
|
|
133
211
|
const preflightStatus = preflight({ tier, repoRoot: cwd });
|
|
134
212
|
if (preflightStatus !== 0) return preflightStatus;
|
|
135
213
|
|
|
136
|
-
const
|
|
137
|
-
const
|
|
214
|
+
const { files: extraFiles, ...options } = toRunOptions(rest);
|
|
215
|
+
const files = shardTestFiles(
|
|
216
|
+
[...new Set([...listTargets(tier, cwd), ...extraFiles])],
|
|
217
|
+
shard,
|
|
218
|
+
);
|
|
138
219
|
|
|
139
|
-
const env = buildWebhookSafeTestEnv(process.env);
|
|
140
220
|
const startedAt = Date.now();
|
|
141
|
-
let status =
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
spawnError = testRun.error;
|
|
153
|
-
break;
|
|
154
|
-
}
|
|
155
|
-
const chunkStatus = testRun.status ?? 1;
|
|
156
|
-
// First non-zero wins; later chunks still run to report every failure.
|
|
157
|
-
if (chunkStatus !== 0 && status === 0) status = chunkStatus;
|
|
221
|
+
let status = 1;
|
|
222
|
+
try {
|
|
223
|
+
status = await runTests({
|
|
224
|
+
...options,
|
|
225
|
+
files,
|
|
226
|
+
cwd,
|
|
227
|
+
env: buildWebhookSafeTestEnv(process.env),
|
|
228
|
+
stdout,
|
|
229
|
+
});
|
|
230
|
+
} finally {
|
|
231
|
+
cleanup({ repoRoot: cwd });
|
|
158
232
|
}
|
|
159
233
|
|
|
160
|
-
cleanup({ repoRoot: cwd });
|
|
161
|
-
|
|
162
234
|
// Fail a run whose fixture telemetry leaked into the live signals tree,
|
|
163
235
|
// where the retro graduator would count it as real evidence.
|
|
164
236
|
const polluted = fixtureStreamGuard({ cwd });
|
|
165
237
|
if (polluted !== 0 && status === 0) status = polluted;
|
|
166
238
|
|
|
167
|
-
|
|
168
|
-
|
|
239
|
+
// Best-effort; never affects the exit code. A shard is not a full run.
|
|
240
|
+
if (!shard) {
|
|
241
|
+
depositCredit({ cwd, tier, status, durationMs: Date.now() - startedAt });
|
|
169
242
|
}
|
|
170
243
|
|
|
171
|
-
// Best-effort; never affects the exit code.
|
|
172
|
-
depositCredit({ cwd, tier, status, durationMs: Date.now() - startedAt });
|
|
173
|
-
|
|
174
244
|
return status;
|
|
175
245
|
}
|
|
176
246
|
|
|
@@ -188,16 +258,16 @@ Flags:
|
|
|
188
258
|
Tier to run. Default: full — every test file except
|
|
189
259
|
\`tests/e2e/**\`, which only \`--tier e2e\` runs.
|
|
190
260
|
--test-name-pattern <re>, --test-only
|
|
191
|
-
The documented \`node --test\` pass-throughs,
|
|
192
|
-
|
|
193
|
-
Any other \`--flag\` is rejected rather than forwarded
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
261
|
+
The documented \`node --test\` pass-throughs, mapped
|
|
262
|
+
onto the \`run()\` options \`testNamePatterns\` / \`only\`.
|
|
263
|
+
Any other \`--flag\` is rejected rather than forwarded,
|
|
264
|
+
so a typo never runs nothing and still exits 0.
|
|
265
|
+
--shard <i>/<n> Run shard i of n (1 ≤ i ≤ n) of the tier's sorted
|
|
266
|
+
file list; the n shards partition it.
|
|
197
267
|
--help Show this message.
|
|
198
268
|
|
|
199
|
-
Exits
|
|
200
|
-
|
|
269
|
+
Exits 1 when any non-todo test fails, or 2 when the tier preflight refuses
|
|
270
|
+
to start the suite.
|
|
201
271
|
`;
|
|
202
272
|
|
|
203
273
|
runAsCli(import.meta.url, async () => runTestSuite(), {
|
|
@@ -16,7 +16,7 @@ description:
|
|
|
16
16
|
- Apply the **five-axis review** to every change: **Correctness, Readability & Simplicity, Architecture, Security, Performance**.
|
|
17
17
|
- Flag dead code artifacts (`_unused` vars, backwards-compat shims, `// removed` comments) and require their removal before merge.
|
|
18
18
|
- Defer to `.agents/rules/security-baseline.md` and the `security-and-hardening` skill for security review; explicit checks include input validation, no hardcoded secrets, parameterized queries, encoded output, authn+authz, and treating external data as untrusted.
|
|
19
|
-
- Bug-fix reviews cover **both** the fix and the regression test; a fix without a failing-then-passing test is not approvable.
|
|
19
|
+
- Bug-fix reviews cover **both** the fix and the regression test; a fix without a failing-then-passing test is not approvable, and neither is one whose commit body states no `Behaviour delta:` or whose diff changes behaviour outside it (`rules/testing-standards.md` § Applying the Standards).
|
|
20
20
|
- **Refactoring is post-green and behaviour-preserving.** Run the refactor pass only when the suite is already green and gates pass; inputs, outputs, side effects, error semantics, and ordering MUST be identical before and after, and existing tests MUST keep passing **without modification** (if a test had to change, behaviour changed — revert).
|
|
21
21
|
- **Lower CRAP by lowering complexity, and remove duplication at the root.** Target the highest-CRAP well-covered functions and the largest verbatim duplications by measurement (`check-baselines.js`), not by smell; extract one well-named helper rather than leaving near-copies. CRAP must not rise and maintainability must not fall on any touched file, and no gate, floor, or threshold may be retuned to make the pass "succeed".
|
|
22
22
|
|
|
@@ -187,6 +187,13 @@ Evaluate the gathered context against the following test quality dimensions:
|
|
|
187
187
|
- Category: file under `Coverage`. A property test whose seed is
|
|
188
188
|
neither pinned nor printed on failure goes under `Flakiness`: a red that
|
|
189
189
|
cannot be reproduced breaks the reproducibility the rubric demands.
|
|
190
|
+
- **Vacuous property tests.** An existing property test is itself a
|
|
191
|
+
finding when its generator cannot reach the inputs the stated
|
|
192
|
+
invariant constrains (a domain that excludes the edge, a filter that
|
|
193
|
+
discards it), or when its assertion would hold for any implementation.
|
|
194
|
+
File it under `Coverage` at **Medium**, or **High** under the High
|
|
195
|
+
conditions above. Name the unreachable input or the trivially true
|
|
196
|
+
assertion.
|
|
190
197
|
- **Name the property.** Each finding states the invariant as a testable
|
|
191
198
|
property (e.g. `decode(encode(x)) === x`; "no transition leaves a
|
|
192
199
|
terminal state") plus its generator shape (the input domain to draw
|
|
@@ -229,6 +229,16 @@ spec decision, a swallowed error on a real failure path) is a 🔴.
|
|
|
229
229
|
disabled-code block removed to make a diff look clean, or a lint-suppression
|
|
230
230
|
comment (`biome-ignore`, `eslint-disable`, `@ts-expect-error`) added to mute
|
|
231
231
|
a real diagnostic instead of fixing it.
|
|
232
|
+
- **Over-broad fixes** — a bug fix that reaches green by changing more than
|
|
233
|
+
the bug: the fix commit's body carries no `Behaviour delta:` line, or the
|
|
234
|
+
diff changes behaviour for inputs outside the stated delta (a widened
|
|
235
|
+
guard, a new early return, a catch-all branch, a default that now applies
|
|
236
|
+
everywhere), or the regression test asserts no input just outside the
|
|
237
|
+
delta unchanged.
|
|
238
|
+
- **Vacuous properties** — a new property test that constrains nothing: no
|
|
239
|
+
`Failure witness:` line records a mutant it was seen to fail against, its
|
|
240
|
+
generator cannot reach the inputs the stated invariant constrains, or its
|
|
241
|
+
assertion would hold for any implementation.
|
|
232
242
|
|
|
233
243
|
For every hit, name the file and line, the taxonomy category, and *why the
|
|
234
244
|
code — not the check — should have changed*. A finding here is legitimate only
|
package/docs/CHANGELOG.md
CHANGED
|
@@ -15,6 +15,28 @@ All notable changes to this project will be documented in this file.
|
|
|
15
15
|
-->
|
|
16
16
|
<!-- markdownlint-disable-file MD004 MD012 MD037 -->
|
|
17
17
|
|
|
18
|
+
## [2.100.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.99.0...mandrel-v2.100.0) (2026-10-23)
|
|
19
|
+
|
|
20
|
+
|
|
21
|
+
### Fixed
|
|
22
|
+
|
|
23
|
+
* **ci:** guard fromJSON on the release PR output so a release merge can publish (refs [#5872](https://github.com/dsj1984/mandrel/issues/5872)) ([#5873](https://github.com/dsj1984/mandrel/issues/5873)) ([bcf11b9](https://github.com/dsj1984/mandrel/commit/bcf11b9722fe47f42a832218909bdb3cc5495a45))
|
|
24
|
+
|
|
25
|
+
## [2.99.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.98.0...mandrel-v2.99.0) (2026-10-23)
|
|
26
|
+
|
|
27
|
+
|
|
28
|
+
### Added
|
|
29
|
+
|
|
30
|
+
* adopt verification-discipline rules: bug-fix behaviour delta, write-time property tests with failure witnesses, caller obligations ([#5863](https://github.com/dsj1984/mandrel/issues/5863)) ([#5864](https://github.com/dsj1984/mandrel/issues/5864)) ([d746c14](https://github.com/dsj1984/mandrel/commit/d746c1442808f3c4d7f39996027e0d57df500b94))
|
|
31
|
+
* cut the required-CI critical path: one-pass node:test orchestrator, sharded Windows Smoke, leaner validate job, ruleset drift guard ([#5866](https://github.com/dsj1984/mandrel/issues/5866)) ([#5871](https://github.com/dsj1984/mandrel/issues/5871)) ([64f01a1](https://github.com/dsj1984/mandrel/commit/64f01a1c6b730c22e48a8fc004490dd613c700e2))
|
|
32
|
+
|
|
33
|
+
## [2.98.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.97.0...mandrel-v2.98.0) (2026-10-22)
|
|
34
|
+
|
|
35
|
+
|
|
36
|
+
### Fixed
|
|
37
|
+
|
|
38
|
+
* close-time baseline commits stay under commitlint's 100-char body line limit, so a deep file path no longer silently drops the re-score ([#5859](https://github.com/dsj1984/mandrel/issues/5859)) ([#5860](https://github.com/dsj1984/mandrel/issues/5860)) ([3f85ed8](https://github.com/dsj1984/mandrel/commit/3f85ed88a0f6a0f8eafbb3d328f0353e1f4f00ed))
|
|
39
|
+
|
|
18
40
|
## [2.97.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.96.0...mandrel-v2.97.0) (2026-10-22)
|
|
19
41
|
|
|
20
42
|
|
package/package.json
CHANGED