mandrel 2.112.0 → 2.114.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.
@@ -212,6 +212,7 @@
212
212
  },
213
213
  "targetDirs": ["src"],
214
214
  "additionalFormats": [],
215
+ "scanHeapMb": 4096,
215
216
  "ignoreGlobs": []
216
217
  }
217
218
  },
@@ -244,6 +244,7 @@ Everything `/mandrel-deliver` and `single-story-close` consume: worktree isolati
244
244
  | `quality.gates.duplication.components` | No | `object<map>` | — | Component-keyed membership map — the membership half of the component mapping whose threshold half is `floors`: component name to the glob list whose rows roll up under it (matched against the row key: the file path, or the bundle name for bundle-size). `check-baselines` reports one rollup per component that matches a row and holds it to `floors.<component>`, falling back to `floors["*"]`. Defaults to `{ "*": ["**"] }` at the resolver layer. |
245
245
  | `quality.gates.duplication.targetDirs` | No | `string[]` or `{ append?, prepend? }` | `["src"]` | Directories whose scorable sources (`.js`, `.mjs`, `.cjs`, `.jsx`, `.ts`, `.tsx`, `.mts`, `.cts`), plus the files of any `additionalFormats`, the duplication (DRY) gate scans for copy-paste clones. Mandrel ships a `src/`-centric default; projects whose executable code lives elsewhere (e.g. this repo's `.agents/scripts/`) override here. The framework default is intentionally not auto-discovered, so an override is the explicit, auditable signal (Story #3664). |
246
246
  | `quality.gates.duplication.additionalFormats` | No | `array<string>` | `[]` | Extra jscpd format names (e.g. `python`, `go`) the duplication gate scans on top of the scorable formats it always reads. Extend-only: the scorable formats cannot be removed, and naming one here is a no-op. An unknown format name fails the scan rather than measuring nothing. The CRAP, MI, coverage and native-review gates still score only the scorable list (Story #5849). |
247
+ | `quality.gates.duplication.scanHeapMb` | No | `integer` | `4096` | V8 old-space limit, in MB, of the child process that runs the whole-tree duplication scan. The need grows with the scanned tree. It is a ceiling, not an allocation, and it reaches only that child. |
247
248
  | `quality.gates.duplication.ignoreGlobs` | No | `array<string>` | `[]` | Minimatch glob patterns matched against the canonicalised repo-relative path of each discovered file. Files matching any pattern are excluded from duplication discovery before scanning. Orthogonal to `components` (grouping). Absent or empty preserves the existing behaviour (Story #3664). This is the lever for scanning fewer files. |
248
249
  | `quality.autoRefresh` | No | `object` | — | Baseline-attribution auto-refresh: when a gate can prove a regression is a legitimate consequence of the diff, it rewrites the baseline instead of blocking. The single-row CRAP jump cap (5) and the rescore scope (`diff`) are fixed. |
249
250
  | `quality.autoRefresh.enabled` | No | `boolean` | `true` | Master switch for the auto-refresh path. When false, every baseline refresh is a deliberate operator action. |
@@ -780,6 +781,22 @@ runs `lint` without depositing close's credit and records the one `lint` pass
780
781
  only after every post-seat check passed at that HEAD; under a coverage
781
782
  deferral the checks are skipped and close runs lint itself.
782
783
 
784
+ When preflight's `lint` fails and the change set
785
+ (`origin/<baseBranch>...HEAD`) adds at least one file, the finding appends a
786
+ hint naming this contract: a check that refuses a missing coverage or CRAP
787
+ row for a change-set file must downgrade under
788
+ `MANDREL_HANDOFF_STEP=preflight` and be declared here. A lint failure on a
789
+ change set that adds nothing carries no hint.
790
+
791
+ The base merge never drops a seated row. When the only conflicts are in
792
+ `baselines/*.json` files the merge driver owns, the handoff (and close)
793
+ re-merges each one from its three index stages by row identity: every
794
+ conflicted row or envelope key (a stamp such as `kernelVersion`) takes
795
+ `origin/<baseBranch>`'s side, and a row only the Story carries survives. The
796
+ sync log names how many Story-only rows were kept. A side that does not
797
+ decode, or a kind the driver does not know, still takes the whole
798
+ `origin/<baseBranch>` file.
799
+
783
800
  #### `delivery.quality.ratchets.coveredByLint` — ratchets your lint already runs
784
801
 
785
802
  The handoff preflight runs each standalone ratchet whose baseline is committed
@@ -1335,6 +1335,12 @@
1335
1335
  "description": "Extra jscpd format names (e.g. `python`, `go`) the duplication gate scans on top of the scorable formats it always reads. Extend-only: the scorable formats cannot be removed, and naming one here is a no-op. An unknown format name fails the scan rather than measuring nothing. The CRAP, MI, coverage and native-review gates still score only the scorable list (Story #5849).",
1336
1336
  "default": []
1337
1337
  },
1338
+ "scanHeapMb": {
1339
+ "type": "integer",
1340
+ "minimum": 256,
1341
+ "description": "V8 old-space limit, in MB, of the child process that runs the whole-tree duplication scan. The need grows with the scanned tree. It is a ceiling, not an allocation, and it reaches only that child.",
1342
+ "default": 4096
1343
+ },
1338
1344
  "ignoreGlobs": {
1339
1345
  "type": "array",
1340
1346
  "items": {
@@ -0,0 +1,19 @@
1
+ /**
2
+ * Forked entry for the whole-tree duplication scan. Disconnecting after the
3
+ * reply lets the process end by itself, so a coverage run still flushes.
4
+ */
5
+
6
+ import { resolveDetectClones, scanDuplication } from './duplication-scanner.js';
7
+
8
+ process.once('message', async (params) => {
9
+ let reply;
10
+ try {
11
+ const detect = resolveDetectClones();
12
+ reply = { rows: await scanDuplication({ ...params, detect }) };
13
+ } catch (err) {
14
+ reply = {
15
+ error: { message: err?.message ?? String(err), code: err?.code },
16
+ };
17
+ }
18
+ process.send(reply, () => process.disconnect());
19
+ });
@@ -0,0 +1,76 @@
1
+ /**
2
+ * Runs the duplication scan in a child with its own heap: the scan needs
3
+ * gigabytes on a large tree, and a flag on the fork reaches nobody else.
4
+ */
5
+
6
+ import { fork } from 'node:child_process';
7
+ import { fileURLToPath } from 'node:url';
8
+ import { scanDuplication } from './duplication-scanner.js';
9
+
10
+ const DEFAULT_SCAN_HEAP_MB = 4096;
11
+ const STDERR_TAIL_CHARS = 2000;
12
+ const HEAP_FLAG = /^--max[-_]old[-_]space[-_]size=/;
13
+ const CHILD_ENTRY = fileURLToPath(
14
+ new URL('./duplication-scan-child.js', import.meta.url),
15
+ );
16
+
17
+ function isHeapDeath(code, signal, stderr) {
18
+ return (
19
+ signal === 'SIGABRT' || code === 134 || /heap out of memory/i.test(stderr)
20
+ );
21
+ }
22
+
23
+ function childDeathError(code, signal, stderr, scanHeapMb) {
24
+ const how = signal ? `signal ${signal}` : `exit code ${code}`;
25
+ const hint = isHeapDeath(code, signal, stderr)
26
+ ? ` It ran out of heap at ${scanHeapMb} MB; raise delivery.quality.gates.duplication.scanHeapMb.`
27
+ : '';
28
+ return new Error(
29
+ `[Duplication] scan child died with ${how} before reporting.${hint} ${stderr.trim()}`.trim(),
30
+ );
31
+ }
32
+
33
+ function replyError({ message, code }) {
34
+ const err = new Error(message);
35
+ if (code !== undefined) err.code = code;
36
+ return err;
37
+ }
38
+
39
+ /**
40
+ * @param {{ targetDirs: string[], cwd: string, ignoreGlobs?: string[], additionalFormats?: string[] }} scan
41
+ * @param {{ detect?: (opts: object) => Promise<object[]>, scanHeapMb?: number, forkImpl?: typeof fork }} [opts]
42
+ * an injected `detect` scans in-process and forks nothing
43
+ * @returns {Promise<object[]>} the scan's rows
44
+ */
45
+ export function runDuplicationScan(
46
+ scan,
47
+ { detect, scanHeapMb = DEFAULT_SCAN_HEAP_MB, forkImpl = fork } = {},
48
+ ) {
49
+ if (detect) return scanDuplication({ ...scan, detect });
50
+ return new Promise((resolve, reject) => {
51
+ const child = forkImpl(CHILD_ENTRY, [], {
52
+ execArgv: [
53
+ ...process.execArgv.filter((arg) => !HEAP_FLAG.test(arg)),
54
+ `--max-old-space-size=${scanHeapMb}`,
55
+ ],
56
+ silent: true,
57
+ });
58
+ let reply;
59
+ let stderr = '';
60
+ child.stdout?.resume();
61
+ child.stderr?.on('data', (chunk) => {
62
+ stderr = (stderr + chunk).slice(-STDERR_TAIL_CHARS);
63
+ });
64
+ child.on('message', (message) => {
65
+ reply = message;
66
+ });
67
+ child.once('error', reject);
68
+ child.once('close', (code, signal) => {
69
+ if (reply?.error) reject(replyError(reply.error));
70
+ else if (reply) resolve(reply.rows);
71
+ else reject(childDeathError(code, signal, stderr, scanHeapMb));
72
+ });
73
+ // A failed send surfaces as the child's `close`.
74
+ child.send(scan, () => {});
75
+ });
76
+ }
@@ -10,7 +10,7 @@
10
10
  * @module lib/baselines/merge-envelopes
11
11
  */
12
12
 
13
- import { deepEqual } from '../json-utils.js';
13
+ import { deepEqual, isObject } from '../json-utils.js';
14
14
  import { KNOWN_KINDS } from './envelope.js';
15
15
  import { getKindModule } from './kernel.js';
16
16
 
@@ -310,6 +310,51 @@ export function mergePlainBaseline({ base, ours, theirs, kind } = {}) {
310
310
  };
311
311
  }
312
312
 
313
+ /**
314
+ * Three-way merge where every row and stamp conflict takes theirs, so a row
315
+ * only ours carries survives a conflicted file. `null` for an unknown kind or
316
+ * a missing side.
317
+ *
318
+ * @param {{ base: object|null, ours: object, theirs: object }} params
319
+ * @returns {{ kind: string, envelopeKind: boolean, envelope: object, storyOnlyRows: number }|null}
320
+ */
321
+ export function mergeBaselineTheirsWins({ base, ours, theirs } = {}) {
322
+ const envelopeKind = kindFromEnvelope(ours) ?? kindFromEnvelope(theirs);
323
+ const kind =
324
+ envelopeKind ??
325
+ plainKindFromEnvelope(ours) ??
326
+ plainKindFromEnvelope(theirs);
327
+ if (!kind || !isObject(ours) || !isObject(theirs)) return null;
328
+ const merge = envelopeKind ? mergeEnvelopes : mergePlainBaseline;
329
+ const { conflicts } = merge({ base, ours, theirs, kind });
330
+ const rowConflicts = conflicts.filter((c) => c.scope === 'row');
331
+ const replaced = new Set(rowConflicts.map((c) => c.ours));
332
+ const resolved = {
333
+ ...ours,
334
+ rows: [
335
+ ...(ours.rows ?? []).filter((row) => !replaced.has(row)),
336
+ ...rowConflicts.flatMap((c) =>
337
+ c.theirs === undefined ? [] : [c.theirs],
338
+ ),
339
+ ],
340
+ };
341
+ for (const c of conflicts.filter((c) => c.scope === 'envelope')) {
342
+ if (c.theirs === undefined) delete resolved[c.identity];
343
+ else resolved[c.identity] = c.theirs;
344
+ }
345
+ const { envelope } = merge({ base, ours: resolved, theirs, kind });
346
+ const rowIdentity = envelopeKind
347
+ ? getKindModule(kind).rowIdentity
348
+ : plainSpec(kind).rowIdentity;
349
+ const elsewhere = new Set(
350
+ [...(base?.rows ?? []), ...(theirs.rows ?? [])].map(rowIdentity),
351
+ );
352
+ const storyOnlyRows = (ours.rows ?? []).filter(
353
+ (row) => !elsewhere.has(rowIdentity(row)),
354
+ ).length;
355
+ return { kind, envelopeKind: Boolean(envelopeKind), envelope, storyOnlyRows };
356
+ }
357
+
313
358
  const REGENERATE_COMMANDS = Object.freeze({
314
359
  'dead-exports': 'npm run dead-exports:update',
315
360
  'dead-exports-production': 'npm run dead-exports:update',
@@ -35,11 +35,8 @@ import { isScorableSourceFile } from '../source-extensions.js';
35
35
  import { toPosix } from '../util/paths.js';
36
36
  import { buildBundleSizeScorer } from './bundle-size-scorer.js';
37
37
  import { decodeEnvelope } from './codec.js';
38
- import {
39
- resolveDetectClones,
40
- resolveFormatExtensions,
41
- scanDuplication,
42
- } from './duplication-scanner.js';
38
+ import { runDuplicationScan } from './duplication-scan-fork.js';
39
+ import { resolveFormatExtensions } from './duplication-scanner.js';
43
40
  import { checkBaselineAhead, getKindModule } from './kernel.js';
44
41
  import { filterExcludedRows } from './kinds/maintainability.js';
45
42
  import { canonicalizeBaselinePath } from './path-canon.js';
@@ -260,10 +257,10 @@ const KIND_SCORER_BUILDERS = Object.freeze({
260
257
  * parallel implementation would report its own disagreement as drift.
261
258
  *
262
259
  * @param {string} kind
263
- * @param {{ cwd: string }} opts
260
+ * @param {{ cwd: string, detect?: (opts: object) => Promise<object[]> }} opts
264
261
  * @returns {((files: string[], opts: object) => Promise<object[]> | object[]) | undefined}
265
262
  */
266
- export function resolveDefaultScorer(kind, { cwd } = {}) {
263
+ export function resolveDefaultScorer(kind, { cwd, detect } = {}) {
267
264
  const builder = KIND_SCORER_BUILDERS[kind];
268
265
  if (typeof builder !== 'function') return undefined;
269
266
  const effectiveCwd = cwd ?? process.cwd();
@@ -273,7 +270,7 @@ export function resolveDefaultScorer(kind, { cwd } = {}) {
273
270
  } catch {
274
271
  quality = undefined;
275
272
  }
276
- return builder({ cwd: effectiveCwd, quality });
273
+ return builder({ cwd: effectiveCwd, quality, detect });
277
274
  }
278
275
 
279
276
  /** The CRAP stamp anchors where check-baselines does: target dirs + root. */
@@ -318,7 +315,8 @@ function requireScorer(kind, scorer, cwd) {
318
315
  * Refresh the on-disk baseline for `kind`. `scopeFiles: null` without
319
316
  * `fullScope` derives scope from `git diff baseRef..headRef`; `fullScope`
320
317
  * requires `scopeFiles: null`. `requireRowsForScopeFiles` fails loud when a
321
- * scoped file produced no row.
318
+ * scoped file produced no row. A scoped refresh never rewrites an
319
+ * `excludeWriteFiles` row.
322
320
  *
323
321
  * @param {{
324
322
  * kind: 'maintainability' | 'crap' | 'coverage' | 'duplication' | 'bundle-size',
@@ -335,6 +333,7 @@ function requireScorer(kind, scorer, cwd) {
335
333
  * requireRowsForScopeFiles?: boolean,
336
334
  * requiredScopeFilePredicate?: (file: string) => boolean,
337
335
  * extrasContext?: { cwd?: string, targetDirs?: string[] },
336
+ * excludeWriteFiles?: string[],
338
337
  * }} opts
339
338
  * @returns {Promise<{
340
339
  * kind: string,
@@ -363,6 +362,7 @@ export async function refreshBaseline(opts = {}) {
363
362
  requireRowsForScopeFiles = false,
364
363
  requiredScopeFilePredicate,
365
364
  extrasContext,
365
+ excludeWriteFiles = [],
366
366
  } = opts;
367
367
 
368
368
  validateOptions({ kind, scopeFiles, fullScope, writePath });
@@ -419,6 +419,7 @@ export async function refreshBaseline(opts = {}) {
419
419
  scope,
420
420
  rows: canonicalRows,
421
421
  priorRows: priorEnvelope?.rows,
422
+ exclude: excludeWriteFiles,
422
423
  });
423
424
 
424
425
  const envelope = writeEnvelope({
@@ -475,10 +476,17 @@ function partnersOf(rows, files) {
475
476
  * removed clone's partner appears in no head pair). A rise in an unrelated
476
477
  * file stays out of scope, so a branch never owns drift it did not cause.
477
478
  *
478
- * @param {{ kind: string, scope: { mode: string, files: string[] }, rows: object[], priorRows?: object[] }} args
479
+ * `exclude` is subtracted last.
480
+ *
481
+ * @param {{ kind: string, scope: { mode: string, files: string[] }, rows: object[], priorRows?: object[], exclude?: string[] }} args
479
482
  * @returns {string[]}
480
483
  */
481
- function resolveWriteScopeFiles({ kind, scope, rows, priorRows }) {
484
+ function resolveWriteScopeFiles({ exclude = [], ...args }) {
485
+ const excluded = new Set(exclude.map(canonicalizeBaselinePath));
486
+ return widenWriteScope(args).filter((file) => !excluded.has(file));
487
+ }
488
+
489
+ function widenWriteScope({ kind, scope, rows, priorRows }) {
482
490
  if (kind !== 'duplication' || scope.mode === 'full') return [...scope.files];
483
491
  const headByPath = new Map(rows.map((row) => [row.path, row]));
484
492
  const partners = scope.files.flatMap(
@@ -750,12 +758,14 @@ function buildDefaultDuplicationScorer({ cwd, config, quality, detect } = {}) {
750
758
  : [];
751
759
  return async (_files, opts) => {
752
760
  const effectiveCwd = opts?.cwd ?? cwd ?? process.cwd();
753
- return scanDuplication({
754
- targetDirs,
755
- cwd: effectiveCwd,
756
- ignoreGlobs,
757
- additionalFormats: dupCfg.additionalFormats,
758
- detect: detect ?? resolveDetectClones(),
759
- });
761
+ return runDuplicationScan(
762
+ {
763
+ targetDirs,
764
+ cwd: effectiveCwd,
765
+ ignoreGlobs,
766
+ additionalFormats: dupCfg.additionalFormats,
767
+ },
768
+ { detect, scanHeapMb: dupCfg.scanHeapMb },
769
+ );
760
770
  };
761
771
  }
@@ -29,6 +29,13 @@ export const DUPLICATION_GATE = {
29
29
  'Extra jscpd format names (e.g. `python`, `go`) the duplication gate scans on top of the scorable formats it always reads. Extend-only: the scorable formats cannot be removed, and naming one here is a no-op. An unknown format name fails the scan rather than measuring nothing. The CRAP, MI, coverage and native-review gates still score only the scorable list (Story #5849).',
30
30
  default: [],
31
31
  },
32
+ scanHeapMb: {
33
+ type: 'integer',
34
+ minimum: 256,
35
+ description:
36
+ 'V8 old-space limit, in MB, of the child process that runs the whole-tree duplication scan. The need grows with the scanned tree. It is a ceiling, not an allocation, and it reaches only that child.',
37
+ default: 4096,
38
+ },
32
39
  ignoreGlobs: {
33
40
  type: 'array',
34
41
  items: { type: 'string', minLength: 1 },
@@ -59,6 +59,26 @@ export function redactErrorMessage(message, options = {}) {
59
59
  return out.replace(TOKEN_SHAPED, '[REDACTED]');
60
60
  }
61
61
 
62
+ const JSON_STRING_VALUE = /:\s*"(?:[^"\\]|\\.)*(?:"|$)/g;
63
+ const EMAIL = /[\w.+-]+@[\w-]+(?:\.[\w-]+)+/g;
64
+ const UUID = /\b[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}\b/gi;
65
+
66
+ /**
67
+ * `redactErrorMessage`, after blanking JSON string values and email- and
68
+ * UUID-shaped tokens — for raw output that may carry account PII.
69
+ *
70
+ * @param {string|undefined} text
71
+ * @returns {string}
72
+ */
73
+ export function redactPii(text) {
74
+ return redactErrorMessage(
75
+ String(text ?? '')
76
+ .replace(JSON_STRING_VALUE, ': "<redacted>"')
77
+ .replace(EMAIL, '<email>')
78
+ .replace(UUID, '<uuid>'),
79
+ );
80
+ }
81
+
62
82
  function pathVariants(p) {
63
83
  if (!p) return [];
64
84
  const back = p.replace(/\//g, '\\');