mandrel 2.24.0 → 2.26.0

package/.agents/scripts/lib/baselines/preview-gates.js

@@ -30,10 +30,14 @@ import {
 import { calculateAll, scanDirectory } from '../maintainability-utils.js';
 import { resolveCrapEnvOverrides } from './env-overrides.js';
 import {
+  assertBaselineCompatible,
+  assessComparisonBasis,
   buildCrapReport,
   compareCrap,
   filterRowsByFileScope,
+  INCOMPATIBLE_BASELINE_DIAGNOSTIC,
   loadCrapBaseline,
+  suppressVerdicts,
 } from './kinds/crap.js';
 import {
   buildMaintainabilityReport,
@@ -131,6 +135,34 @@ function hasCrapRegressions(result) {
   return result.regressions > 0 || result.newViolations > 0;
 }
 
+/**
+ * Build the zero-row CRAP envelope the preview returns when it has nothing to
+ * compare against — no baseline, or the gate disabled.
+ *
+ * @param {{scope: string, diffRef: string|null}} scopeInfo
+ * @returns {object}
+ */
+function emptyCrapEnvelope({ scope, diffRef }) {
+  return {
+    kernelVersion: KERNEL_VERSION,
+    escomplexVersion: resolveEscomplexVersion(),
+    summary: {
+      total: 0,
+      regressions: 0,
+      newViolations: 0,
+      drifted: 0,
+      incomparable: 0,
+      provenanceMismatched: 0,
+      unscorable: 0,
+      removed: 0,
+      skippedNoCoverage: 0,
+      scope,
+      diffRef,
+    },
+    violations: [],
+  };
+}
+
 function applyDiffScopeMi({ files, baseline, scopeSet, cwd }) {
   if (!scopeSet) {
     return { scopedFiles: files, scopedBaseline: baseline ?? {} };
@@ -236,23 +268,24 @@ export async function runCrapPreview({
   const quality = getQuality(config);
   const crap = quality.crap;
   if (!baseline || crap.enabled === false) {
+    return { exitCode: 0, envelope: emptyCrapEnvelope({ scope, diffRef }) };
+  }
+
+  // Story #4866 (AC-6): judge the loaded envelope BEFORE comparing anything
+  // against it. A baseline whose scoring semantics or transpiler coordinates
+  // predate the running scorer cannot yield a meaningful per-method verdict,
+  // and emitting regressions from it asks the operator to fix code that is
+  // not broken. Fail open — the authoritative `check-baselines` gate still
+  // gates the merge, so a permissive pre-commit hook costs no real coverage
+  // while a blocking one costs a provably defect-free commit.
+  const incompatible = assertBaselineCompatible(baseline);
+  if (incompatible) {
     return {
       exitCode: 0,
-      envelope: {
-        kernelVersion: KERNEL_VERSION,
-        escomplexVersion: resolveEscomplexVersion(),
-        summary: {
-          total: 0,
-          regressions: 0,
-          newViolations: 0,
-          drifted: 0,
-          removed: 0,
-          skippedNoCoverage: 0,
-          scope,
-          diffRef,
-        },
-        violations: [],
-      },
+      envelope: suppressVerdicts(emptyCrapEnvelope({ scope, diffRef }), {
+        name: INCOMPATIBLE_BASELINE_DIAGNOSTIC,
+        message: incompatible,
+      }),
     };
   }
 
@@ -298,6 +331,16 @@ export async function runCrapPreview({
       diffRef,
     },
   });
+  // Story #4866 (AC-5): above the drifted-row ratio the basis is self-
+  // evidently unsound and every per-method verdict below it is an artefact of
+  // a mis-keyed join. Say so once, by name, and fail open.
+  const basis = assessComparisonBasis(result);
+  if (!basis.sound) {
+    return {
+      exitCode: 0,
+      envelope: suppressVerdicts(envelope, basis.diagnostic),
+    };
+  }
   const exitCode = hasCrapRegressions(result) ? 1 : 0;
   return { exitCode, envelope };
 }

package/.agents/scripts/lib/baselines/reader.js

@@ -221,6 +221,11 @@ function readAndShape(kind, absolutePath) {
     // dropping it here would make every baseline look unstamped and fail the
     // whole repo closed on a stamp that is actually present on disk.
     scoringSemantics: parsed.scoringSemantics,
+    // Story #4866 — same contract for the transpiler stamp. Dropping it here
+    // would leave the ts-transpiler compat axis reachable but blind: it would
+    // read `undefined` off every loaded envelope and pass vacuously, which is
+    // the exact deadness this Story exists to end.
+    tsTranspilerVersion: parsed.tsTranspilerVersion,
   };
 }
 
@@ -314,6 +319,11 @@ export function loadFile(absolutePath, opts = {}) {
     // dropping it here would make every baseline look unstamped and fail the
     // whole repo closed on a stamp that is actually present on disk.
     scoringSemantics: parsed.scoringSemantics,
+    // Story #4866 — same contract for the transpiler stamp. Dropping it here
+    // would leave the ts-transpiler compat axis reachable but blind: it would
+    // read `undefined` off every loaded envelope and pass vacuously, which is
+    // the exact deadness this Story exists to end.
+    tsTranspilerVersion: parsed.tsTranspilerVersion,
   };
 }
 

package/.agents/scripts/lib/baselines/refresh-service.js

@@ -3,14 +3,16 @@
  * (Story #2197, Epic #2173).
  *
  * `refreshBaseline()` is the single funnel through which every baseline
- * regeneration (maintainability, crap, coverage) must flow. Callers that
- * previously assembled their own envelopes and called `fs.writeFileSync`
- * MUST migrate to this entry point — Stories 3/4/5 of Epic #2173 do that
- * migration; Story #2197 only lands the service surface and tests.
+ * regeneration (maintainability, crap, coverage, duplication) must flow.
+ * Callers that previously assembled their own envelopes and called
+ * `fs.writeFileSync` MUST migrate to this entry point — Stories 3/4/5 of
+ * Epic #2173 do that migration; Story #2197 only lands the service surface
+ * and tests. Story #4944 migrated the last holdout, `duplication`.
  *
  * The service is **scoring-agnostic**: it does not itself walk the
- * filesystem to compute MI / CRAP / coverage scores. Scoring is provided
- * by the per-kind default scorers resolved lazily via `resolveDefaultScorer`
+ * filesystem to compute MI / CRAP / coverage / duplication scores. Scoring
+ * is provided by the per-kind default scorers resolved lazily via
+ * `resolveDefaultScorer`
  * (built with the project config resolved against `cwd`) and, in tests or
  * production wiring, injected via the `scorer` option for hermetic
  * determinism. The service is the policy layer:
@@ -29,7 +31,8 @@
  * Public API (Task #2203, AC-1 / AC-2 / AC-7):
  *
  *   refreshBaseline({
- *     kind,        // 'maintainability' | 'crap' | 'coverage'  REQUIRED
+ *     kind,        // 'maintainability' | 'crap' | 'coverage'
+ *                  //   | 'duplication'                       REQUIRED
  *     baseRef,     // git ref to diff against; default 'origin/main'
  *     headRef,     // git ref under inspection; default 'HEAD'
  *     scopeFiles,  // Array<string> | null
@@ -62,8 +65,9 @@
  *
  * Acceptance contract:
  *
- *   AC-1: All callers that produce a maintainability/crap/coverage baseline
- *         go through refreshBaseline(). Enforced by Task #2208 invariant.
+ *   AC-1: All callers that produce a maintainability/crap/coverage/
+ *         duplication baseline go through refreshBaseline(). Enforced by
+ *         the Task #2208 invariant.
  *   AC-2: scopeFiles=null && !fullScope -> diff-derived scope (Task #2207).
  *   AC-4: Out-of-scope rows + their updatedAt fields are preserved byte-
  *         for-byte (Task #2209).
@@ -93,6 +97,7 @@ import {
   isIgnoredByGlobs as isIgnoredByGlobsMi,
   scanDirectory as scanDirectoryMi,
 } from '../maintainability-utils.js';
+import { resolveDetectClones, scanDuplication } from './duplication-scanner.js';
 import { filterExcludedRows } from './kinds/maintainability.js';
 import { canonicalizeBaselinePath } from './path-canon.js';
 import {
@@ -108,7 +113,12 @@ const execFileAsync = promisify(nodeExecFile);
  * Kinds the refresh service knows how to dispatch. Stays in lockstep with
  * the per-kind modules under `.agents/scripts/lib/baselines/kinds/`.
  */
-const SUPPORTED_KINDS = Object.freeze(['maintainability', 'crap', 'coverage']);
+const SUPPORTED_KINDS = Object.freeze([
+  'maintainability',
+  'crap',
+  'coverage',
+  'duplication',
+]);
 
 /**
  * Per-kind file-extension predicate for diff-scope derivation (Task #2207).
@@ -125,6 +135,12 @@ const KIND_FILE_PREDICATES = Object.freeze({
   maintainability: (p) => /\.(?:m?[jt]sx?)$/i.test(p),
   crap: (p) => /\.(?:m?[jt]sx?)$/i.test(p),
   coverage: (p) => /\.(?:m?[jt]sx?)$/i.test(p),
+  // Duplication shares the source-extension filter deliberately. jscpd is
+  // configured for the `javascript` format only, so a changed `.ts` file
+  // admitted here simply yields no row on either side of the merge —
+  // over-inclusive is inert, under-inclusive would silently pin a changed
+  // file's prior row. Erring wide is the safe direction.
+  duplication: (p) => /\.(?:m?[jt]sx?)$/i.test(p),
 });
 
 /**
@@ -338,6 +354,7 @@ const KIND_SCORER_BUILDERS = Object.freeze({
   maintainability: buildDefaultMaintainabilityScorer,
   crap: buildDefaultCrapScorer,
   coverage: buildDefaultCoverageScorer,
+  duplication: buildDefaultDuplicationScorer,
 });
 
 /**
@@ -384,7 +401,7 @@ export function resolveDefaultScorer(kind, { cwd } = {}) {
  * so callers (and tests) can assert what actually got scored.
  *
  * @param {{
- *   kind: 'maintainability' | 'crap' | 'coverage',
+ *   kind: 'maintainability' | 'crap' | 'coverage' | 'duplication',
  *   baseRef?: string,
  *   headRef?: string,
  *   scopeFiles?: string[] | null,
@@ -745,3 +762,44 @@ function validateOptions({ kind, scopeFiles, fullScope, writePath }) {
     );
   }
 }
+
+/**
+ * Build the default duplication scorer.
+ *
+ * **This scorer always scans the whole target tree, in every scope mode.**
+ * That is not an oversight — duplication is the only kind here whose metric
+ * is *pairwise*: a clone is a relationship between two files, and jscpd can
+ * only report it if both sides are in the corpus it was handed. Narrowing the
+ * scan to the diff would drop every clone between a changed file and an
+ * unchanged one, i.e. exactly the duplication a refactor is most likely to
+ * introduce. So the `files` argument is intentionally unused: scope narrowing
+ * for this kind is a **write-side** concern, applied by the service handing
+ * `scope` to `writer.write()`, where `mergeRowsByScope` keeps the freshly
+ * scanned rows for in-scope files and preserves the prior rows verbatim for
+ * everything else.
+ *
+ * Reads `targetDirs` / `ignoreGlobs` off `gates.duplication`, not off a
+ * flattened accessor: `resolveQuality` never lifted duplication into the
+ * legacy bag (the kind post-dates it), so `quality.duplication` is always
+ * `undefined` and reading it would silently scan nothing.
+ *
+ * @param {{ cwd: string, config?: object, quality?: object, detect?: (opts: object) => Promise<object[]> }} opts
+ * @returns {(files: string[], opts: object) => Promise<object[]>}
+ */
+function buildDefaultDuplicationScorer({ cwd, config, quality, detect } = {}) {
+  const dupCfg =
+    resolveQualityBlock({ quality, config })?.gates?.duplication ?? {};
+  const targetDirs = Array.isArray(dupCfg.targetDirs) ? dupCfg.targetDirs : [];
+  const ignoreGlobs = Array.isArray(dupCfg.ignoreGlobs)
+    ? dupCfg.ignoreGlobs
+    : [];
+  return async (_files, opts) => {
+    const effectiveCwd = opts?.cwd ?? cwd ?? process.cwd();
+    return scanDuplication({
+      targetDirs,
+      cwd: effectiveCwd,
+      ignoreGlobs,
+      detect: detect ?? resolveDetectClones(),
+    });
+  };
+}

package/.agents/scripts/lib/baselines/scope.js

@@ -1,33 +1,44 @@
 // .agents/scripts/lib/baselines/scope.js
 //
-// Story #1962 / Task #1970 — One ScopeResolution helper that the
-// `check-baselines.js` dispatcher and the per-kind regression writers
-// (Epic #1943) both consume. Routing every scope decision through this
-// single function is what guarantees read/write parity: the dispatcher
-// can never decide "diff against epic/1943" while the writer assumes
-// "full repo", because both call `resolveScope()` with the same inputs.
+// Story #1962 / Task #1970 — the ScopeResolution helper behind the
+// `check-baselines.js` dispatcher: `resolveDispatchScope` in
+// `lib/orchestration/check-baselines/phases/compare.js` is its one
+// caller. Routing the read side's scope decision through a single pure
+// function keeps the precedence rules from being re-implemented per gate.
+//
+// It is NOT the writers' resolver. `lib/baselines/refresh-service.js`
+// defines its own private `resolveScope` (Story #3658) over a different
+// input set, and the header here used to claim otherwise — a claim that
+// made the read/write pair look coupled when it is not. Corrected in
+// Story #4922.
 //
 // The resolver is intentionally pure — it takes already-extracted
-// inputs and returns a frozen ScopeResolution. CLI parsing, env
-// reading, and config loading happen in the caller; that keeps this
-// module trivially testable and prevents the precedence rules from
-// being silently re-implemented at every call site.
+// inputs and returns a frozen ScopeResolution. Env reading and config
+// loading happen in the caller; that keeps this module trivially
+// testable.
 //
 // Precedence (highest → lowest):
 //
-//   1. CLI flags — `cliFlags.fullScope: true` or `cliFlags.changedSinceRef`.
-//      Operator-typed beats anything in env/config. A CLI override of
-//      `--full-scope` wins even if the config says `'diff'`.
-//   2. Environment — `BASELINE_SCOPE` ('full' | 'diff') and
+//   1. Environment — `BASELINE_SCOPE` ('full' | 'diff') and
 //      `BASELINE_REF` (any git ref). The dispatcher reads these from
-//      `process.env` and forwards via `cliFlags.envScope` /
-//      `cliFlags.envRef` so the resolver itself never touches process
-//      state. CI usually sets these.
-//   3. Config — `configScope` ('full' | 'diff') and `configRef` (any
+//      `process.env` and forwards via `envScope` / `envRef` so the
+//      resolver itself never touches process state. CI sets these.
+//   2. Config — `configScope` ('full' | 'diff') and `configRef` (any
 //      git ref) from `delivery.quality.gateScoping` in `.agentrc.json`.
-//   4. Default — `mode='diff'` against `ref='main'`. This is the
+//   3. Default — `mode='diff'` against `ref='main'`. This is the
 //      framework-wide fallback when nothing else is configured.
 //
+// Story #4922 removed a fourth, highest-precedence layer: a
+// `cliFlags.fullScope` / `cliFlags.changedSinceRef` operator override,
+// plus the `cliFlags.changedFiles` → `files` plumbing that fed it. No
+// production caller ever populated any of the three — only this module's
+// own unit tests did — so the layer's only effect was to advertise a
+// `--full-scope` / `--changed-since` contract that `check-baselines.js`
+// does not implement, and a `files` set that no consumer read. Operators
+// who need full scope set `BASELINE_SCOPE=full`, which is what CI does.
+// (`mergeRowsByScope` below still takes a `files`-bearing scope — that
+// one comes from the refresh service's own resolver, not from here.)
+//
 // Missing-ref fallback: when the resolved mode is `'diff'` but no ref
 // is supplied at any layer, the resolver falls back to `'main'` rather
 // than producing a half-resolved scope with `ref=null`. The dispatcher
@@ -45,17 +56,8 @@
 //     kind: string,        // echoed back for caller convenience
 //     mode: 'full' | 'diff',
 //     ref:  string | null, // null in full mode; ref string in diff mode
-//     files: Set<string>,  // empty Set in full mode (sentinel for "all")
 //     source: string,      // which layer won (debug / friction signal)
 //   }
-//
-// `files` is intentionally a Set rather than an Array — callers
-// repeatedly check membership during per-row filtering, and Set lookup
-// is O(1). An empty Set in `'full'` mode means "no filter applies".
-// A non-empty Set in `'diff'` mode means "only these paths are in
-// scope" (the dispatcher pre-computes them via `git diff --name-only`
-// and forwards via `cliFlags.changedFiles`); when omitted, the writer
-// is expected to compute the diff itself against `ref`.
 
 const VALID_MODES = new Set(['full', 'diff']);
 const DEFAULT_DIFF_REF = 'main';
@@ -84,45 +86,19 @@ function asMode(v) {
 }
 
 /**
- * Coerce a candidate set/array of files to a frozen Set. Returns an
- * empty Set when the input is missing or empty.
- *
- * @param {unknown} v
- * @returns {Set<string>}
- */
-function asFilesSet(v) {
-  if (v instanceof Set) {
-    return new Set(
-      Array.from(v).filter((f) => typeof f === 'string' && f.length > 0),
-    );
-  }
-  if (Array.isArray(v)) {
-    return new Set(v.filter((f) => typeof f === 'string' && f.length > 0));
-  }
-  return new Set();
-}
-
-/**
- * Resolve a scope against the layered precedence (CLI > env > config >
+ * Resolve a scope against the layered precedence (env > config >
  * default). Pure; no I/O.
  *
  * @param {object} input
- * @param {string} input.kind         - Baseline kind (e.g. `'lint'`).
+ * @param {string} input.kind          - Baseline kind (e.g. `'lint'`).
  * @param {string} [input.configScope] - `'full'` | `'diff'` from agentrc.
  * @param {string} [input.configRef]   - Diff ref from agentrc.
- * @param {object} [input.cliFlags]    - Pre-parsed CLI / env layer.
- * @param {boolean} [input.cliFlags.fullScope]      - `--full-scope`.
- * @param {string}  [input.cliFlags.changedSinceRef] - `--changed-since <ref>`.
- * @param {string}  [input.cliFlags.envScope]        - From `BASELINE_SCOPE`.
- * @param {string}  [input.cliFlags.envRef]          - From `BASELINE_REF`.
- * @param {Iterable<string>} [input.cliFlags.changedFiles]
- *        Pre-computed diff paths (when caller already ran `git diff
- *        --name-only`). Becomes `files`; only meaningful in `'diff'` mode.
+ * @param {string} [input.envScope]    - From `BASELINE_SCOPE`.
+ * @param {string} [input.envRef]      - From `BASELINE_REF`.
  * @returns {{
  *   kind: string,
  *   mode: 'full' | 'diff',
  *   ref: string | null,
- *   files: Set<string>,
  *   source: string,
  * }}
  */
@@ -131,59 +107,34 @@ export function resolveScope(input = {}) {
     typeof input.kind === 'string' && input.kind.length > 0
       ? input.kind
       : 'unknown';
-  const cli = input.cliFlags ?? {};
-
-  // ---- Layer 1: CLI flags (highest precedence) -------------------------
-  if (cli.fullScope === true) {
-    return Object.freeze({
-      kind,
-      mode: 'full',
-      ref: null,
-      files: new Set(),
-      source: 'cli:--full-scope',
-    });
-  }
-  const cliRef = asNonEmptyString(cli.changedSinceRef);
-  if (cliRef) {
-    return Object.freeze({
-      kind,
-      mode: 'diff',
-      ref: cliRef,
-      files: asFilesSet(cli.changedFiles),
-      source: 'cli:--changed-since',
-    });
-  }
 
-  // ---- Layer 2: Environment (extracted by caller into cliFlags.env*) ---
-  const envMode = asMode(cli.envScope);
+  // ---- Layer 1: Environment (extracted by the caller) ------------------
+  const envMode = asMode(input.envScope);
   if (envMode === 'full') {
     return Object.freeze({
       kind,
       mode: 'full',
       ref: null,
-      files: new Set(),
       source: 'env:BASELINE_SCOPE=full',
     });
   }
-  const envRef = asNonEmptyString(cli.envRef);
+  const envRef = asNonEmptyString(input.envRef);
   if (envMode === 'diff' || envRef) {
     return Object.freeze({
       kind,
       mode: 'diff',
       ref: envRef ?? DEFAULT_DIFF_REF,
-      files: asFilesSet(cli.changedFiles),
       source: envRef ? 'env:BASELINE_REF' : 'env:BASELINE_SCOPE=diff',
     });
   }
 
-  // ---- Layer 3: Config (delivery.quality.gateScoping) -----------------
+  // ---- Layer 2: Config (delivery.quality.gateScoping) ------------------
   const cfgMode = asMode(input.configScope);
   if (cfgMode === 'full') {
     return Object.freeze({
       kind,
       mode: 'full',
       ref: null,
-      files: new Set(),
       source: 'config:gateScoping.scope=full',
     });
   }
@@ -193,19 +144,17 @@ export function resolveScope(input = {}) {
       kind,
       mode: 'diff',
       ref: cfgRef ?? DEFAULT_DIFF_REF,
-      files: asFilesSet(cli.changedFiles),
       source: cfgRef
         ? 'config:gateScoping.diffRef'
         : 'config:gateScoping.scope=diff',
     });
   }
 
-  // ---- Layer 4: Default ------------------------------------------------
+  // ---- Layer 3: Default ------------------------------------------------
   return Object.freeze({
     kind,
     mode: 'diff',
     ref: DEFAULT_DIFF_REF,
-    files: asFilesSet(cli.changedFiles),
     source: 'default',
   });
 }

package/.agents/scripts/lib/baselines/writer.js

@@ -261,17 +261,26 @@ export function writeFile(absPath, envelope, opts = {}) {
   // across runs and platforms. Per-kind row keys retain their natural
   // declaration order; the row sort is done by `sortRows()`.
   //
-  // Story #4775: the projection is deliberately explicit, so any per-kind
-  // envelope stamp (`scoringSemantics`) must be carried through by name or it
-  // is silently dropped on the way to disk — the stamp would then be present
-  // in memory, validated, and absent from the file it exists to protect.
+  // The projection is deliberately explicit (Story #4775): a per-kind envelope
+  // stamp reaches disk only if it is named here, so an unlisted one is present
+  // in memory, passes validation, and is absent from the file it exists to
+  // protect. That is not hypothetical — Story #4901 added `provenanceStamped`
+  // to `envelopeExtras()` and not to this list, and every baseline written
+  // between then and Story #4969 lost it at this boundary, leaving the
+  // `provenance-unstamped` axis reading an absence its own writer had
+  // manufactured.
+  //
+  // A stamp a kind does not set is simply `undefined`, and `JSON.stringify`
+  // omits an undefined-valued key — so naming all three unconditionally emits
+  // exactly what the per-key `undefined` guards used to, with nothing to
+  // half-apply when the next stamp is added.
   const canonical = {
     $schema: envelope.$schema,
     kernelVersion: envelope.kernelVersion,
     generatedAt: envelope.generatedAt,
-    ...(envelope.scoringSemantics === undefined
-      ? {}
-      : { scoringSemantics: envelope.scoringSemantics }),
+    scoringSemantics: envelope.scoringSemantics,
+    tsTranspilerVersion: envelope.tsTranspilerVersion,
+    provenanceStamped: envelope.provenanceStamped,
     rollup: envelope.rollup,
     rows: envelope.rows,
   };

package/.agents/scripts/lib/changed-files.js

@@ -8,10 +8,17 @@ import { createGitInterface } from './git-utils.js';
  *
  * Pure; no I/O.
  *
+ * Module-private since Story #4944. It was exported for
+ * `diff-scope-cli.js#resolveDiffScopeFiles`, which the duplication-CLI
+ * migration deleted; the three remaining callers all live in this file, so
+ * exporting it now would ship a seam only the tests reach. Its behaviour is
+ * covered through `diffNameOnly`, which returns this function's output
+ * verbatim.
+ *
  * @param {string | null | undefined} stdout
  * @returns {string[]}
  */
-export function parseNameOnlyStdout(stdout) {
+function parseNameOnlyStdout(stdout) {
   if (!stdout) return [];
   return stdout
     .split('\n')