mandrel 2.59.0 → 2.61.0

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

@@ -1,47 +1,20 @@
-// .agents/scripts/lib/baselines/components.js
-//
-// Story #1892 / Task #1902 — shared component resolver and row grouper.
-//
-// The "components" model lets a gate slice a baseline into named buckets
-// (e.g. `app`, `worker`, `infra`) so per-component floors and tolerances
-// can be evaluated independently. The shape is:
-//
-//   components: { [name: string]: string[] }   // map of name → glob list
-//
-// The canonical default — used when a gate omits `components` from its
-// agentrc config — is `{ '*': ['**'] }`, meaning "one bucket called `*`
-// matching every row". This keeps backwards compatibility with the
-// pre-components rollup contract: a baseline that ships only `rollup['*']`
-// continues to work without operator intervention.
-//
-// Globs are matched with minimatch. Overlap is allowed by design — a row
-// matched by two components is reported under both. Components keyed by
-// the literal `*` are treated as the whole-repo rollup and always match
-// every row regardless of declared globs.
+// Component resolver and row grouper: slice a baseline into named glob
+// buckets for per-component floors. The `*` component is the whole-repo
+// rollup and matches every row; overlap between components is allowed.
 
 import { Minimatch } from 'minimatch';
 
-/** The default components map, used when a gate omits `components`. */
 const DEFAULT_COMPONENTS = Object.freeze({ '*': Object.freeze(['**']) });
 
 /**
- * Compiled-matcher cache for `groupRows`, keyed on the glob string.
- *
- * `groupRows` is called once per gate over the whole baseline row set — tens
- * of thousands of rows for `crap.json` — and the functional `minimatch()` it
- * used re-parsed each component glob for every single row. The component
- * globs come from config, so the distinct set is small and immutable; caching
- * the compiled matcher turns an O(rows × globs) parse into an O(globs) one
- * (Story #5109). Matching semantics are unchanged: same patterns, same
- * `{ dot: true }`.
+ * Compiled matchers keyed by glob: `groupRows` runs over tens of thousands of
+ * rows, and re-parsing each glob per row dominated its cost.
  *
  * @type {Map<string, import('minimatch').Minimatch>}
  */
 const GLOB_MATCHER_CACHE = new Map();
 
 /**
- * Compile (once) the `Minimatch` for one glob.
- *
  * @param {string} glob
  * @returns {import('minimatch').Minimatch}
  */
@@ -55,21 +28,10 @@ function matcherFor(glob) {
 }
 
 /**
- * Resolve the components map for a single gate config.
+ * Absent or empty `components` → `{ '*': ['**'] }`; non-array glob lists
+ * coerce to `[]`.
  *
- * Behaviour:
- *   - If the gate config has no `components` key (or it's not a plain
- *     object), return the default `{ '*': ['**'] }`.
- *   - If `components` is present but contains no entries, also return the
- *     default — a writer that emitted an empty `components: {}` is
- *     functionally equivalent to "no components declared".
- *   - Otherwise pass the operator-declared map through unchanged. Each
- *     value MUST be an array of glob strings; non-array values are
- *     coerced to an empty array so the grouper's caller can't crash on
- *     malformed input.
- *
- * @param {object} [gateConfig]  A single gate config slice, e.g.
- *   `delivery.quality.gates.coverage`.
+ * @param {object} [gateConfig]
  * @returns {Record<string, string[]>} Components map, never null.
  */
 export function resolveComponents(gateConfig) {
@@ -96,25 +58,12 @@ function cloneDefault() {
 }
 
 /**
- * Group rows by component using the resolved components map.
- *
- * Matching rules:
- *   - The component literally named `*` is the whole-repo bucket and
- *     captures every row regardless of declared globs.
- *   - For every other component, the row's `keyField` value is matched
- *     against each declared glob with minimatch (using `dot: true` so
- *     leading-dot paths participate). A row joins the bucket on first
- *     match — but a row CAN appear in multiple buckets because we evaluate
- *     every component (overlap is allowed).
- *   - Rows whose `keyField` is not a non-empty string never match
- *     any non-`*` bucket; they still land in `*`.
+ * A row without a string `keyField` lands only in `*`.
  *
  * @param {Array<Record<string, unknown>>} rows
  * @param {Record<string, string[]>}       components
  * @param {string}                         [keyField='path']
- *   The row field to feed into the matcher. Defaults to `path` (used by
- *   lint / coverage / crap / maintainability / mutation). Use `'route'`
- *   for lighthouse and `'bundle'` for bundle-size.
+ *   `route` for lighthouse, `bundle` for bundle-size.
  * @returns {Record<string, Array<Record<string, unknown>>>}
  *   Map of component name → matching rows, in input order.
  */

package/.agents/scripts/lib/baselines/coverage-updater-cli.js

@@ -1,33 +1,15 @@
 /**
- * lib/baselines/coverage-updater-cli.js — the `update-coverage-baseline` CLI's
- * scope-flag reconciliation and its bespoke scorer.
- *
- * Story #5316: both lived inside `update-coverage-baseline.js#main`, which no
- * test imports, so `main` scored CRAP 30 and the inlined scorer another 30 —
- * two of the ten methods Story #5311's honest re-anchor made visible, both at
- * 0% coverage.
- *
- * **Why this is NOT the `refresh-service.js` default scorer.** Story #4293's
- * idiom — drop the bespoke scorer, let `refreshBaseline` resolve the canonical
- * default — was the obvious move here, and `buildDefaultCoverageScorer` is
- * behaviour-equivalent line for line. It was rejected for one reason: the
- * default is silent where this one speaks. A missing or unreadable coverage
- * artifact makes any scorer return `[]`, and `refresh-service.js` has no
- * empty-rows guard, so a full-scope refresh then writes an emptied baseline at
- * exit 0. This scorer's `[Coverage] ❌` line is currently the only signal an
- * operator gets that it happened. Converging would have traded a CRAP row for
- * a quieter failure. (The fail-open itself is real and wants its own Story —
- * it changes `refreshBaseline` semantics for every caller.)
+ * The `update-coverage-baseline` CLI's testable logic. The scorer stays
+ * bespoke (not the refresh-service default) because it logs when the coverage
+ * artifact is missing: `refreshBaseline` has no empty-rows guard, so that line
+ * is the only signal a full-scope refresh just wrote an empty baseline.
  */
 
 import { Logger } from '../Logger.js';
 import { parseDiffScopeFlag } from './diff-scope-cli.js';
 
 /**
- * Reconcile the two scope flags.
- *
- * Throws when both are present: they describe incompatible scopes, and
- * silently preferring one would write a baseline the operator did not ask for.
+ * Throws when both scope flags are present.
  *
  * @param {string[]} [argv]
  * @returns {{fullScope: boolean, diffScopeRef: string|null}}
@@ -44,16 +26,8 @@ export function resolveCoverageUpdaterScope(argv = []) {
 }
 
 /**
- * Build the scorer `refreshBaseline` invokes.
- *
- * Reads `coverage-final.json`, narrows to the c8 include/exclude scope so the
- * baseline records exactly the files coverage is measured over, and — in diff
- * mode — narrows again to the service-resolved in-scope list so untouched rows
- * are preserved rather than re-scored.
- *
- * The three collaborators are named seams (`rules/test-seams.md`) so a test
- * drives the whole scorer with no coverage artifact and no `.c8rc.cjs` on
- * disk.
+ * Narrows to the c8 include/exclude scope, and in diff mode to the in-scope
+ * files so untouched rows are preserved rather than re-scored.
  *
  * @param {string} cwd
  * @param {{readCoverage: Function, loadScope: Function, buildScope: Function,
@@ -70,8 +44,6 @@ export function buildCoverageUpdaterScorer(
     try {
       raw = readCoverage(effectiveCwd);
     } catch (err) {
-      // The only operator-facing signal that the refresh is about to record
-      // nothing — see this module's header.
       logger.error(`[Coverage] ❌ ${err.message}`);
       return [];
     }
@@ -86,7 +58,6 @@ export function buildCoverageUpdaterScorer(
       }),
     });
 
-    // In diff mode, further narrow to the service-resolved in-scope file list.
     const inScope =
       !opts?.fullScope && Array.isArray(files) && files.length > 0
         ? new Set(files)

package/.agents/scripts/lib/baselines/crap-preview-incremental.js

@@ -1,23 +1,11 @@
-/**
- * crap-preview-incremental.js — resolve `runCrapPreview`'s incremental-join
- * `scanAndScore` input (Story #4981).
- *
- * Split into its own file (rather than added inline to `preview-gates.js`)
- * so the Story's opt-in wiring lands as new code, not a same-file expansion
- * of the pre-existing preview runner.
- */
-import { getChangedFiles } from '../changed-files.js';
+import { getChangedFiles, resolveChangedFilesRef } from '../changed-files.js';
 
 /**
- * Resolve the `incremental` option `scanAndScore` (`crap-utils.js`) expects,
- * or `null` when incremental mode is disabled or the changed-files ref could
- * not be resolved — a resolution failure falls back to full-scope rather
- * than silently relaxing the gate.
- *
- * Gated by `incrementalCoverage.baselineJoin` alone (Story #5173). It MUST
- * NOT consult `skipWhenUnchanged`: the join loosens what the gate demands,
- * while the skip only decides whether a capture runs, so a consumer that took
- * the saving has not thereby asked for the loosening.
+ * The `incremental` option for `scanAndScore`, or `null` (full scope) when
+ * disabled or the changed-files ref fails — never a silently relaxed gate.
+ * The preview's `--changed-since` ref wins over configured `baseRef`, so one
+ * hook invocation resolves one ref. Gated by `baselineJoin` alone, never
+ * `skipWhenUnchanged`: skipping a capture is not consent to loosen the gate.
  *
  * @param {{
  *   crap: { incrementalCoverage?: { baselineJoin?: boolean, baseRef?: string } },
@@ -36,7 +24,7 @@ export function resolveCrapPreviewIncremental({
   getChangedFilesImpl = getChangedFiles,
 }) {
   if (crap.incrementalCoverage?.baselineJoin !== true) return null;
-  const baseRef = crap.incrementalCoverage.baseRef || diffRef || 'main';
+  const baseRef = resolveChangedFilesRef({ crap, ref: diffRef });
   try {
     const touchedFiles = new Set(getChangedFilesImpl({ ref: baseRef, cwd }));
     return { touchedFiles, baselineRows };

package/.agents/scripts/lib/baselines/crap-preview-scan.js

@@ -1,13 +1,6 @@
 /**
- * crap-preview-scan.js — the scan → compare → report tail of
- * `preview-gates.js#runCrapPreview`, once its baseline is loaded and judged
- * compatible.
- *
- * Hoisted out of `runCrapPreview` verbatim (Story #4981) so that function's
- * cyclomatic complexity does not grow with the incremental-mode wiring
- * alongside it — this is a relocation of pre-existing logic, not new
- * behaviour; the incremental resolution itself is the only Story #4981
- * addition (see `resolveCrapPreviewIncremental`).
+ * The scan → compare → report tail of `preview-gates.js#runCrapPreview`, once
+ * its baseline is loaded and judged compatible.
  */
 import path from 'node:path';
 import { loadCoverage } from '../coverage-utils.js';
@@ -28,9 +21,6 @@ import {
 } from './kinds/crap.js';
 
 /**
- * Narrow a CRAP baseline to the rows whose file path is in `scopeSet`,
- * or return all rows when no diff-scope filter is active.
- *
  * @param {{ rows: object[] }} baseline
  * @param {Set<string>|null|undefined} scopeSet
  * @returns {object[]}
@@ -42,9 +32,6 @@ function resolveBaselineRows(baseline, scopeSet) {
 }
 
 /**
- * Return true when the CRAP compare result contains regressions or new
- * violations — i.e. when the preview gate should exit non-zero.
- *
  * @param {{ regressions: number, newViolations: number }} result
  * @returns {boolean}
  */
@@ -53,25 +40,8 @@ function hasCrapRegressions(result) {
 }
 
 /**
- * Scan `crap.targetDirs`, compare against the (already compatibility-judged)
- * baseline, and build the `--json` envelope — the exact pre-#4981 tail of
- * `runCrapPreview`, now including the Story #4981 incremental-join opt-in.
- *
- * @param {{
- *   crap: object,
- *   cwd: string,
- *   scopeSet: Set<string>|null,
- *   scope: string,
- *   diffRef: string|null,
- *   baseline: { rows: object[] },
- * }} opts
- * @returns {Promise<{ exitCode: number, envelope: object }>}
- */
-/**
- * The scanned methods at or over the fixed cyclomatic ceiling (Story #5313),
- * as advisories: `quality-preview.js` lists them and exits 0 on them, so the
- * reading reaches the author without the preview ever refusing a commit on
- * complexity alone. Pure.
+ * Methods at or over the cyclomatic ceiling, as advisories only: the preview
+ * never refuses a commit on complexity; `check-cyclomatic.js` enforces. Pure.
  *
  * @param {Array<{ file: string, method: string, startLine: number, cyclomatic: number }>} rows
  * @returns {Array<{ file: string, method: string, startLine: number, cyclomatic: number }>}
@@ -87,6 +57,17 @@ export function listCyclomaticAdvisories(rows) {
     }));
 }
 
+/**
+ * @param {{
+ *   crap: object,
+ *   cwd: string,
+ *   scopeSet: Set<string>|null,
+ *   scope: string,
+ *   diffRef: string|null,
+ *   baseline: { rows: object[] },
+ * }} opts
+ * @returns {Promise<{ exitCode: number, envelope: object }>}
+ */
 export async function computeCrapPreviewScan({
   crap,
   cwd,
@@ -102,11 +83,8 @@ export async function computeCrapPreviewScan({
   const requireCoverage = crap.requireCoverage !== false;
   const coveragePath = crap.coveragePath ?? 'coverage/coverage-final.json';
   const coverage = loadCoverage(path.resolve(cwd, coveragePath));
-  // Story #4731 (AC-3) — feed the CRAP regression compare the *configured*
-  // crap tolerance (env override → `gates.crap.tolerance` → framework default)
-  // so `compareCrap` demotes positive deltas at or under tolerance rather than
-  // failing on any positive delta; over-tolerance deltas still fail. This keeps
-  // the pre-commit/pre-push preview aligned with the authoritative gate.
+  // The configured tolerance keeps the preview aligned with the authoritative
+  // gate: deltas at or under it are demoted, not failed.
   const { newMethodCeiling, tolerance } = resolveCrapEnvOverrides(
     crap,
     process.env,
@@ -141,13 +119,9 @@ export async function computeCrapPreviewScan({
     newMethodCeiling,
     scopeInfo: { scope, diffRef },
   });
-  // Story #5313: a method at or over the cyclomatic ceiling is an ADVISORY
-  // on the preview — reported, never a verdict. The ratchet in
-  // `check-cyclomatic.js` owns enforcement.
   envelope.cyclomaticAdvisories = listCyclomaticAdvisories(scan.rows);
-  // 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.
+  // Above the drifted-row ratio every verdict is an artefact of a mis-keyed
+  // join: say so once and fail open.
   const basis = assessComparisonBasis(result);
   if (!basis.sound) {
     return {

package/.agents/scripts/lib/baselines/crap-updater-cli.js

@@ -1,26 +1,8 @@
 /**
- * lib/baselines/crap-updater-cli.js — the `update-crap-baseline` CLI's own
- * logic: flag parsing, option defaulting, and the bespoke scorer it hands
- * `refreshBaseline`.
- *
- * Story #5316: all three lived inside `update-crap-baseline.js#main`, which no
- * test imports. `parseCliArgs` scored CRAP 56, the inlined scorer 72, and
- * `main` itself 90 — three of the ten methods Story #5311's honest re-anchor
- * made visible, every one at 0% coverage. They sit here for the same reason
- * `diff-scope-cli.js` does: a CLI shell is unreachable from a test, and the
- * import from the CLI is what keeps these off the `dead-exports:production`
- * ratchet.
- *
- * **Why this is NOT the `refresh-service.js` default scorer.** The service
- * already resolves a `buildDefaultCrapScorer`, and Story #4293 made
- * `update-maintainability-baseline.js` drop its bespoke scorer in favour of
- * exactly that. This one cannot follow: it carries `checkResolutionFloor`, a
- * fail-closed refusal that throws before anything is written when too few
- * methods resolved a coverage entry — the guard that stops a broken join being
- * persisted as a sparse baseline (Story #4775). Moving that into the shared
- * default would change behaviour for `refresh-commit.js` and close-validation,
- * which resolve the same default. So the scorer stays bespoke, and is tested
- * here instead.
+ * The `update-crap-baseline` CLI's testable logic: flags, options and its
+ * scorer. The scorer stays bespoke (not the refresh-service default) because
+ * its fail-closed resolution floor must not change behaviour for the other
+ * callers of that default.
  */
 
 import path from 'node:path';
@@ -28,18 +10,13 @@ import { checkResolutionFloor, scanAndScore } from '../crap-utils.js';
 import { Logger } from '../Logger.js';
 import { parseDiffScopeFlag } from './diff-scope-cli.js';
 
-/** Coverage artifact read when neither the flag nor config names one. */
 const DEFAULT_COVERAGE_PATH = 'coverage/coverage-final.json';
 
-/** Resolution-rate floor applied when config does not set one. */
 const DEFAULT_MIN_RESOLUTION_RATE = 0.75;
 
 /**
- * Parse the updater's argv.
- *
- * `--full-scope` and `--diff-scope <ref>` are read here but deliberately NOT
- * reconciled — {@link resolveCrapUpdaterOptions} owns the refusal, so a caller
- * cannot get a half-validated shape by calling only this.
+ * Scope flags are not reconciled here; {@link resolveCrapUpdaterOptions} owns
+ * that refusal.
  *
  * @param {string[]} [argv]
  * @returns {{baselinePath: string|undefined, coveragePath: string|undefined,
@@ -67,22 +44,13 @@ export function parseCrapUpdaterArgs(argv = []) {
 }
 
 /**
- * Fold parsed args over the project's quality config into the one shape the
- * CLI and the scorer both read.
- *
- * Every flag wins over config, and config over the built-in default — the
- * precedence that used to be a chain of `??` inside `main`, which is most of
- * why `main` was cyclomatic 9.
- *
- * Throws on `--full-scope` together with `--diff-scope`: the two describe
- * incompatible scopes and silently preferring one would write a baseline the
- * operator did not ask for.
+ * Flag → config → default. Throws on `--full-scope` with `--diff-scope`:
+ * silently preferring one would write a baseline nobody asked for.
  *
  * @param {{baselinePath?: string, coveragePath?: string, fullScope?: boolean,
- *   diffScopeRef?: string|null}} args From {@link parseCrapUpdaterArgs}.
- * @param {{crap?: object, baselines?: object}} sources Resolved config slices:
- *   `crap` is the quality block, `baselines` the baselines block.
- * @param {string} [cwd] Root the baseline path is resolved against.
+ *   diffScopeRef?: string|null}} args
+ * @param {{crap?: object, baselines?: object}} sources
+ * @param {string} [cwd]
  * @returns {{targetDirs: string[], ignoreGlobs: string[],
  *   requireCoverage: boolean, minMethodResolutionRate: number,
  *   coveragePath: string, baselinePath: string, absBaselinePath: string,
@@ -118,13 +86,8 @@ export function resolveCrapUpdaterOptions(
 }
 
 /**
- * Report a scan's drop counters. Each earns a line only when it moved, so a
- * clean scan stays quiet.
- *
- * `unscorableFiles` (Story #5311) is the one that must never be silent: a file
- * the scan could not read, transpile or parse contributes no rows, so without
- * a line of its own the run reads as a clean scan of a tree with fewer methods
- * than it has.
+ * Non-zero drop counters only. `unscorableFiles` must be reported, or the run
+ * reads as a clean scan of a smaller tree.
  *
  * @param {{skippedFilesNoCoverage?: number, skippedMethodsNoCoverage?: number,
  *   unscorableFiles?: number, resolution?: object}} summary
@@ -158,19 +121,9 @@ function reportScanSummary(summary, logger = Logger) {
 }
 
 /**
- * Build the scorer `refreshBaseline` invokes.
- *
- * Fails closed twice, and both refusals are the point of keeping this bespoke:
- *
- *   - **No coverage artifact under `requireCoverage`** — every file would be
- *     skipped, so the scan is abandoned with an operator-facing warning rather
- *     than returning a confidently empty row set.
- *   - **Resolution rate below the floor** — `checkResolutionFloor` throws
- *     BEFORE the service writes anything. A baseline built from a broken join
- *     is not sparse, it is wrong.
- *
- * `loadCoverage` and the logger are named seams so a test drives the whole
- * scorer without a coverage artifact on disk (`rules/test-seams.md`).
+ * Fails closed on a missing coverage artifact under `requireCoverage` (warn,
+ * no rows) and on a resolution rate below the floor (throws before anything is
+ * written: a broken join is wrong, not sparse).
  *
  * @param {ReturnType<typeof resolveCrapUpdaterOptions>} options
  * @param {{loadCoverage: Function, scan?: Function, logger?: object}} deps
@@ -208,8 +161,6 @@ export function buildCrapUpdaterScorer(
     logger.info(`[CRAP] Scanned ${summary.scannedFiles} file(s).`);
     reportScanSummary(summary, logger);
 
-    // Fail closed BEFORE the service persists anything — a thin baseline is
-    // never written and then apologised for.
     const refusal = checkResolutionFloor(
       summary.resolution,
       options.minMethodResolutionRate,

package/.agents/scripts/lib/baselines/diff-scope-cli.js

@@ -1,40 +1,12 @@
 /**
- * lib/baselines/diff-scope-cli.js — shared `--diff-scope <ref>` parser for
- * the manual baseline-update CLIs (Story #1974 / Task #1986, Epic #1943).
- *
- * `update-coverage-baseline.js`, `update-crap-baseline.js`,
- * `update-maintainability-baseline.js`, and
- * `update-duplication-baseline.js` all accept an opt-in `--diff-scope <ref>`
- * flag. When supplied, the baseline write narrows to files changed since
- * `<ref>`; out-of-scope rows are preserved verbatim from the prior on-disk
- * baseline.
- *
- * The helper is shared to keep the flag's contract identical across the four
- * scripts: one argv parser, one spelling, one error message.
- *
- * **Scope of this module, post-Story #4944.** It parses the flag and nothing
- * else. Everything downstream of the parse — resolving the changed-file set,
- * reading the prior envelope, and assembling the writer call — used to live
- * here too, in `buildWriterScopeArgs` and its helpers. Those were the
- * pre-service path; `lib/baselines/refresh-service.js` owns all of it now
- * (`resolveScope`, `readPriorEnvelope`, and the `writer.write()` handoff),
- * and `refreshBaseline()` derives its own diff via `execFile` rather than
- * `spawnSync`. `update-duplication-baseline.js` was the last caller of the
- * legacy path; when it migrated, the whole write-side half of this module
- * became unreachable and was removed rather than left shipped-but-uncalled.
- *
- * Note for anyone tracing the per-kind prior-row reader that used to live
- * here: it is gone, not relocated. The service reads the prior envelope
- * kind-agnostically (any `{ rows: [], rollup: {} }` document), so the
- * per-kind row-shape filter it needed no longer has a job to do.
+ * The shared `--diff-scope <ref>` flag parser for the baseline-update CLIs:
+ * one spelling, one error message. Scope resolution lives in
+ * `refresh-service.js`.
  */
 
 /**
- * Parse `--diff-scope <ref>` (and the legacy `--diff-scope=<ref>` form)
- * from an argv slice. Returns `null` when the flag is absent. Throws a
- * TypeError when the flag is supplied without a value.
- *
- * Pure; no I/O.
+ * Accepts `--diff-scope <ref>` and `--diff-scope=<ref>`; `null` when absent.
+ * Throws a TypeError when the value is missing. Pure.
  *
  * @param {string[]} argv
  * @returns {string | null}

package/.agents/scripts/lib/baselines/duplication-scanner.js

@@ -1,28 +1,5 @@
 /**
- * duplication-scanner.js — code-duplication (DRY) scanner for the
- * duplication baseline (Story #3664).
- *
- * Wraps the jscpd clone detector behind two pure-ish seams so the
- * refresh script and its unit tests can exercise the parse→envelope path
- * without spawning a real scan:
- *
- *   - `buildDuplicationRows(clones, fileLineCounts, cwd)` — PURE. Folds
- *     jscpd's clone-pair output into per-file `{ path, duplicatedLines,
- *     totalLines, percentage }` rows. Overlapping clones on the same file
- *     are unioned (line-set), so a line duplicated by two different clones
- *     counts once. Every file the scan visited gets a row — files with no
- *     clones land at `duplicatedLines: 0` so the baseline records the full
- *     denominator and a later regression on a previously-clean file is
- *     visible.
- *
- *   - `scanDuplication({ targetDirs, cwd, minTokens, detect, readLineCount })`
- *     — the I/O wrapper. Walks `targetDirs`, runs the injected `detect`
- *     (jscpd's `detectClones` by default), reads per-file line counts, and
- *     returns the projected rows. The `detect` and `readLineCount` seams
- *     are injectable so tests run fully offline.
- *
- * Lower duplication is better — see `kinds/duplication.js` and the gate's
- * `lte` floor direction in `check-baselines/phases/floors.js`.
+ * jscpd-backed scanner for the duplication baseline (lower is better).
  */
 
 import { readFileSync } from 'node:fs';
@@ -35,16 +12,9 @@ const DEFAULT_FORMATS = Object.freeze(['javascript']);
 const require = createRequire(import.meta.url);
 
 /**
- * Resolve jscpd's `detectClones` lazily. The jscpd ESM entrypoint has a
- * broken transitive `colors/safe` specifier under Node's strict ESM
- * resolver, so we load the CJS build via `createRequire`. Isolated behind a
- * function so the rest of the module stays import-pure and testable — no
- * importer of this file pays the jscpd load unless it actually scans.
- *
- * Lives here rather than in `update-duplication-baseline.js` since Story
- * #4944: the refresh service's default duplication scorer needs the same
- * seam, and a second copy in the CLI would be the classic "two
- * implementations of one probe" divergence.
+ * Lazy CJS load: jscpd's ESM entry has a broken transitive `colors/safe`
+ * specifier under strict ESM resolution, and importers that never scan should
+ * not pay the load.
  *
  * @returns {(opts: object) => Promise<Array<object>>}
  */
@@ -59,9 +29,7 @@ export function resolveDetectClones() {
 }
 
 /**
- * Normalise a jscpd `sourceId` (or any path) to a canonical POSIX
- * repo-relative path. jscpd already emits cwd-relative paths, but a future
- * jscpd bump (or an absolute `sourceId`) is defended against here.
+ * POSIX repo-relative path, defending against an absolute `sourceId`.
  *
  * @param {string} sourceId
  * @param {string} cwd
@@ -76,9 +44,6 @@ export function relativisePath(sourceId, cwd) {
 }
 
 /**
- * Count the inclusive line span a clone covers: `end.line - start.line + 1`.
- * jscpd reports 1-based line numbers; a single-line clone spans one line.
- *
  * @param {{ start?: { line?: number }, end?: { line?: number } }} dup
  * @returns {Array<number>} the 1-based line numbers the clone covers
  */
@@ -94,16 +59,12 @@ function cloneLineNumbers(dup) {
 }
 
 /**
- * PURE: fold jscpd clone pairs + per-file line counts into canonical
- * duplication rows. Both sides of every clone pair (`duplicationA` and
- * `duplicationB`) contribute their covered lines to their respective
- * file's duplicated-line set, so a file that is only ever the "B" side of
- * a clone still accrues duplication.
+ * Pure. Both sides of each clone pair accrue lines; overlapping clones are
+ * unioned per file so a line counts once. Every counted file gets a row.
  *
  * @param {Array<{duplicationA?: object, duplicationB?: object}>} clones
  * @param {Map<string, number>|Record<string, number>} fileLineCounts
- *   per-file total line counts keyed by canonical POSIX repo-relative path
- * @param {string} [cwd] used to relativise absolute sourceIds
+ * @param {string} [cwd]
  * @returns {Array<{path: string, duplicatedLines: number, totalLines: number, percentage: number}>}
  */
 export function buildDuplicationRows(
@@ -155,10 +116,6 @@ function toLineCountMap(fileLineCounts) {
 }
 
 /**
- * Default per-file line counter — reads the file off disk and counts
- * newline-delimited lines. Injectable via `scanDuplication`'s
- * `readLineCount` seam so tests never touch the filesystem.
- *
  * @param {string} absPath
  * @returns {number}
  */
@@ -166,15 +123,12 @@ export function readLineCount(absPath) {
   const text = readFileSync(absPath, 'utf8');
   if (text.length === 0) return 0;
   const lines = text.split(/\r\n|\r|\n/);
-  // A trailing newline produces a final empty element — drop it so the
-  // count matches the editor's line count.
+  // Drop the empty element after a trailing newline.
   if (lines.length > 0 && lines[lines.length - 1] === '') lines.pop();
   return lines.length;
 }
 
 /**
- * Run a duplication scan over `targetDirs` and return canonical rows.
- *
  * @param {{
  *   targetDirs: string[],
  *   cwd?: string,
@@ -224,11 +178,8 @@ export async function scanDuplication({
 }
 
 /**
- * Collect the set of files that appear on either side of any clone pair.
- * jscpd's `detectClones` only reports files that participate in at least
- * one clone, so the scanned-but-clean files are not enumerable from the
- * clone list alone — the baseline therefore records exactly the files
- * with detected duplication. Pure helper, exported for tests.
+ * Files on either side of any clone. jscpd reports only participating files,
+ * so the baseline records exactly the files with detected duplication.
  *
  * @param {Array<object>} clones
  * @param {string} cwd