mandrel 2.59.0 → 2.61.0

package/.agents/scripts/lib/baselines/kinds/duplication.js

@@ -1,28 +1,7 @@
 /**
- * kinds/duplication.js — per-kind module for the code-duplication (DRY)
- * baseline (Story #3664).
- *
- * Row shape: `{ path, duplicatedLines, totalLines, percentage }`. Each row
- * records how much of a single source file is copy-paste duplication, as
- * reported by a clone detector (jscpd). `percentage` is the per-file
- * duplication ratio in [0, 100]; `duplicatedLines` / `totalLines` are the
- * raw line counts the percentage derives from, kept so the whole-repo
- * rollup can recompute an exact aggregate ratio rather than averaging
- * per-file percentages (which would over-weight small files).
- *
- * Lower duplication is better, so the gate's floor direction is `lte`
- * (see `check-baselines/phases/floors.js#axisDirection`). New paths land
- * in the `additions` bucket (Story #2012); removed paths count as
- * improvements when they carried any duplication — the file is gone, so
- * its prior debt is gone too.
- *
- * `kernelVersion()` returns a static in-repo semver — the duplication
- * scorer is the in-repo scan + rollup contract (the jscpd output is
- * normalised before it reaches this module), so there is no upstream
- * library version to track the way CRAP/MI track `typhonjs-escomplex`.
- * Bump the version passed to `makeBaselineKind` whenever the row shape or
- * rollup math changes. Scaffold is generated by `makeBaselineKind`
- * (Story #3983).
+ * Per-kind module for the duplication baseline (jscpd). Row shape:
+ * `{ path, duplicatedLines, totalLines, percentage }`; lower is better. Bump
+ * the static kernel version when the row shape or rollup math changes.
  */
 
 import { canonicalise } from '../path-canon.js';
@@ -46,12 +25,7 @@ export function projectRow(row) {
   };
 }
 
-/**
- * Exact aggregate duplication ratio: total duplicated lines / total lines
- * across the row set, expressed as a percentage. Averaging per-file
- * percentages would over-weight small files, so the rollup recomputes from
- * the raw line counts each row carries.
- */
+/** Recomputed from line counts; averaging percentages over-weights small files. */
 function aggregate(rows) {
   if (!rows || rows.length === 0) {
     return {

package/.agents/scripts/lib/baselines/kinds/kind-factory.js

@@ -1,30 +1,13 @@
-/**
- * kinds/kind-factory.js — shared scaffold factory for per-kind baseline
- * modules (Story #3983).
- *
- * The five row-metric kinds (coverage, mutation, maintainability,
- * lighthouse, duplication) used to hand-roll the same scaffold each:
- * `kernelVersion`, `sortRows`, a component-aware `rollup`, a
- * `compare(head, base)` that diffs rows by key into
- * `{regressions, improvements, unchanged, additions}`, an
- * `applyEpsilon` stabilizer (Story #1964), and a scope-aware
- * `mergeRows` (Story #1974). Only the axis list, direction-of-better,
- * aggregate math, and the missing/removed-row policies differ per kind.
- *
- * `makeBaselineKind` generates the scaffold once; each kind module stays
- * a thin parameterization with a byte-identical exported surface. The
- * Story #2012 class of fix ("new paths must land in `additions`, never
- * the regression arm") lives here exactly once.
- *
- * All generated functions are pure: no I/O, no process exit, no
- * friction emission.
- */
+/** Pure scaffold factory for the row-metric baseline kinds. */
 
 import { componentMatches } from '../component-matcher.js';
 import { mergeRowsByScope } from '../scope.js';
 
 /**
- * Build the shared scaffold for a per-kind baseline module.
+ * `missingBasePolicy`: a head row with no base row is an `'addition'`
+ * (default; never a regression) or is classified against a `'perfect'` base.
+ * `removedRowPolicy`: a base row with no head row is classified against a
+ * perfect head, or is an improvement when `when(baseRow)` holds.
  *
  * @param {{
  *   keyField: string,
@@ -38,26 +21,6 @@ import { mergeRowsByScope } from '../scope.js';
  *     | { kind: 'improvement-when', when: (row: object) => boolean },
  *   perfectRow?: (key: string) => object,
  * }} opts
- *   - `keyField`          — row grouping property (`'path'` or `'route'`):
- *                           the rollup/scope key. The generated
- *                           `rowIdentity` derives from it, but the two are
- *                           distinct concepts — see `rowIdentity` below.
- *   - `kernelVersion`     — static semver, or a thunk for kinds that pin
- *                           to another kind's kernel (MI → CRAP)
- *   - `axes`              — metric property names compared per row
- *   - `betterWhen`        — `'higher'` (coverage, MI, …) or `'lower'`
- *                           (duplication): decides which delta sign is a
- *                           regression
- *   - `aggregate`         — per-kind rollup math over a row set
- *   - `missingBasePolicy` — head row with no base row: `'addition'`
- *                           (default; Story #2012 bucket) or `'perfect'`
- *                           (classify against a perfect base — lighthouse,
- *                           where a new route must meet the bar)
- *   - `removedRowPolicy`  — base row with no head row: `'perfect-head'`
- *                           classifies against a perfect head row;
- *                           `'improvement-when'` pushes an improvement
- *                           when `when(baseRow)` holds, else unchanged
- *   - `perfectRow`        — builds the perfect row for the policies above
  * @returns {{
  *   kernelVersion: () => string,
  *   rowIdentity: (row: object) => string,
@@ -83,17 +46,8 @@ export function makeBaselineKind({
     typeof kernelVersion === 'function' ? kernelVersion : () => kernelVersion;
 
   /**
-   * Canonical row identity (Story #5215) — the string a 3-way merge keys a
-   * row on, and the contract every kind module must satisfy.
-   *
-   * Deliberately a separate concept from `keyField`, even though the five
-   * scaffold kinds derive one from the other. `keyField` answers "which
-   * component does this row roll up into", so a kind is free to declare a
-   * grouping key coarser than a row (CRAP declares `'path'` while shipping
-   * one row per method). Identity answers "is this the same row", and a
-   * merge that confuses the two silently drops every sibling sharing a key.
-   * Callers therefore read `rowIdentity` off the kind module and never
-   * rebuild a key from `keyField` themselves.
+   * "Is this the same row" — distinct from `keyField` ("which component"),
+   * though derived from it here. Callers must never rebuild it from `keyField`.
    *
    * @param {object} row
    * @returns {string}

package/.agents/scripts/lib/baselines/kinds/maintainability.js

@@ -1,21 +1,7 @@
 /**
- * kinds/maintainability.js — per-kind module for the Maintainability Index
- * (MI) baseline (Story #1891).
- *
- * Row shape: `{ path, mi }`. The legacy baseline shipped a flat `{ path: mi }`
- * map; the v2 envelope arrays each row explicitly so per-row metadata can
- * grow without churning the schema.
- *
- * MI is computed by the in-repo `escomplex-engine` kernel — same upstream
- * dependency family as CRAP — so the kernel version tracks
- * `typhonjs-escomplex` too.
- *
- * Higher MI = better. New paths land in the `additions` bucket
- * (Story #2012 — new files MUST NOT register as regressions); removed
- * paths count as improvements when their MI was non-perfect — the file is
- * gone, so its prior debt is gone too. Scaffold (sortRows / rollup /
- * compare / applyEpsilon / mergeRows) is generated by `makeBaselineKind`
- * (Story #3983).
+ * Per-kind module for the Maintainability Index baseline. Row shape:
+ * `{ path, mi }`; higher is better. New files are additions, never
+ * regressions; a removed file with MI < 100 counts as an improvement.
  */
 
 import { readBaselineAtRef } from '../../baseline-loader.js';
@@ -30,54 +16,15 @@ export const name = 'maintainability';
 export const keyField = 'path';
 
 /**
- * Files the maintainability scorer cannot measure because the upstream kernel
- * throws on them. Each entry must carry a one-line reason so a future engine
- * bump can audit the list and drop the exclusion.
- *
- * **This list is empty, and the goal is to keep it that way.** It previously
- * held seven paths, all attributed to escomplex "choking on modern
- * destructuring / regex-property patterns". That diagnosis was wrong. The real
- * defect is that `typhonjs-escomplex`'s code generator is written against
- * ESTree while its own parser emits Babel, so a regex literal in a loop head,
- * an `await` in a loop head, a `?.`, a dynamic `import()`, or an object spread
- * in a default parameter aborted the whole file's analysis. That is now
- * repaired at the kernel boundary by `lib/escomplex-ast-compat.js`, which makes
- * all four surviving entries scorable — and the audit incidentally showed the
- * other three had been pointing at deleted files, because nothing audits an
- * allowlist whose only effect is to suppress output.
- *
- * Before adding a path here, check whether `escomplex-ast-compat.js` can handle
- * the construct instead. An entry here is a file nobody measures; a handler
- * there gets it measured for every consumer.
- *
- * Story #2467 / Task #2494 — the prior behaviour stored these files with
- * `mi: 0` in `baselines/maintainability.json`, which corrupted the global
- * `min`/p50 rollup and let real regressions hide behind a phantom floor.
- * Excluding them at the scorer makes the absence explicit; the comparator
- * already treats missing-in-baseline new files as `additions` (Story #2012)
- * so re-inclusion is non-breaking once the kernel can score them.
- *
- * Canonicalised POSIX repo-relative paths.
+ * Canonical paths the kernel cannot score; each entry needs a one-line
+ * reason. Keep it empty: prefer a handler in `escomplex-ast-compat.js`, which
+ * gets the file measured for every consumer.
  */
 export const MAINTAINABILITY_EXCLUSIONS = Object.freeze(new Set());
 
 /**
- * Filter parse-unscorable files out of a rows array. Used by the scorer
- * before envelope assembly so MI=0 phantoms never reach the on-disk
- * baseline. Pure — does not mutate the input.
- *
- * Two layers:
- *   1. Drop rows whose `path` appears in the explicit
- *      `MAINTAINABILITY_EXCLUSIONS` allowlist (documented escomplex
- *      parse-fail families).
- *   2. Defensive backstop — drop any remaining `mi === 0` rows. A real
- *      MI score never reaches 0 for valid code (the escomplex floor for
- *      runnable JS is ~10–20), so `mi === 0` is a reliable signal that
- *      the scorer hit a parse failure the allowlist hasn't caught yet.
- *      Without this backstop, a newly-added file that escomplex can't
- *      parse silently poisons the global min/p50 rollup (Story #2467
- *      precedent). The audit lens flags any allowlist entries it can
- *      now score so the list stays auditable.
+ * Drop excluded paths and any `mi === 0` row: real code never scores 0, so
+ * 0 means a parse failure that would poison the min/p50 rollup.
  *
  * @template {{path: string, mi?: number}} R
  * @param {R[]} rows
@@ -117,8 +64,7 @@ export const {
   mergeRows,
 } = makeBaselineKind({
   keyField,
-  // MI and CRAP share the escomplex kernel — pin them together so a drift
-  // in either always invalidates both baselines.
+  // Shared escomplex kernel: drift invalidates both baselines.
   kernelVersion: crapKernelVersion,
   axes: ['mi'],
   betterWhen: 'higher',
@@ -130,22 +76,15 @@ export const {
   },
 });
 
-// ---------------------------------------------------------------------------
-// CLI-facing pure helpers (Story #1981, Task #1989).
-// Hoisted from `.agents/scripts/check-maintainability.js`.
-// ---------------------------------------------------------------------------
+// CLI-facing pure helpers for `check-maintainability.js`.
 
-// Envelope version for the --json parity output. Bump when the report
-// shape changes so downstream agent workflows can detect breaks without
-// guessing. 1.1.0 — TypeScript support landed in 5.29.0.
+// `--json` report version; bump when the report shape changes.
 export const MI_REPORT_KERNEL_VERSION = '1.1.0';
 
 /**
- * Pure: build the MI parity envelope. Shape matches the CRAP `--json`
- * output: `{ kernelVersion, summary, violations }` sans `fixGuidance`
- * (MI scores don't decompose along the two CRAP axes).
+ * Same shape as the CRAP `--json` report, minus `fixGuidance`.
  *
- * @param {Record<string, number>} scores current MI scores keyed by file
+ * @param {Record<string, number>} scores
  * @param {{
  *   regressions?: number,
  *   newFiles?: number,
@@ -179,7 +118,7 @@ export function buildMaintainabilityReport(scores, stats, scopeInfo) {
   };
 }
 
-/** Thin wrapper: delegate to baseline-store with MI-specific defaults. */
+/** Returns the flat `{ path: mi }` map the comparators expect. */
 export function loadMaintainabilityBaseline({
   baselinePath,
   epicRef,
@@ -195,12 +134,8 @@ export function loadMaintainabilityBaseline({
     logger,
     label: 'Maintainability',
   });
-  // Epic-ref read may return a non-object — coerce to {} so downstream
-  // `Object.entries` / `Object.keys` never throws.
+  // An epic-ref read may return a non-object.
   if (epicRef && (parsed === null || typeof parsed !== 'object')) return {};
-  // Story #1895: the on-disk baseline switched from the flat
-  // `{ path: mi }` map to the canonical envelope shape. Project envelope
-  // back to the legacy flat shape so downstream comparators keep working.
   if (
     parsed &&
     typeof parsed === 'object' &&

package/.agents/scripts/lib/baselines/kinds/mutation.js

@@ -1,44 +1,11 @@
 /**
- * kinds/mutation.js — per-kind module for the mutation-testing baseline
- * (Story #1891). Row shape: `{ path, score, killed, survived }`. Rollup
- * carries score/killed/survived/noCoverage. Stryker is the upstream
- * kernel; we pin a static version until a Mandrel-side retrofit story
- * wires the running Stryker version through (#1908).
+ * Per-kind module for the mutation baseline (Stryker upstream, static kernel
+ * version). Row shape: `{ path, score, killed, survived }`; higher is better.
  *
- * Higher score = better. New paths land in the `additions` bucket
- * (Story #2012 — any real-world score under 100 must never flip to a
- * regression); removed paths count as improvements when their score was
- * non-perfect. Scaffold is generated by `makeBaselineKind` (Story #3983).
- *
- * ## Rollup weighting (Story #5058)
- *
- * The rollup score is a **mutant-weighted** mean —
- * `sum(score_i * mutants_i) / sum(mutants_i)`, where
- * `mutants_i = killed_i + survived_i`. It used to be `scoreSum / rows.length`,
- * an unweighted mean over files, under which a 3-mutant file carried the same
- * weight as a 300-mutant one: adding a handful of thinly-mutated new files
- * dragged the whole-repo number down far enough to breach the floor arm while
- * the compare arm reported no regression at all (a newly-scanned file has no
- * baseline row, so it can only move the aggregate `applyFloors` scores).
- *
- * Both weights are already summed in the same loop and are already required
- * by the row schema, which is `additionalProperties: false` — so the weighted
- * score is computable from the existing row shape with no producer change and
- * no schema change.
- *
- * **Limit of the approximation.** Rows carry no timeout or no-coverage counts
- * (`noCoverage` in the rollup is hardcoded `0`), so `killed + survived` is not
- * Stryker's full mutant population wherever timed-out or uncovered mutants
- * exist. The weighted score therefore *approximates* Stryker's published
- * overall score — it does not reproduce it. Closing that gap needs a producer
- * change and its own Story.
- *
- * Because this changes what the stored number MEANS, it is a semantics
- * migration: a baseline measured at 88.51 unweighted is 85.18 weighted over
- * the same rows, so every floor calibrated on the old mean breaches on
- * upgrade. `assertBaselineCompatible` below fails such a baseline closed —
- * a bare `kernelVersion` bump would not, because `kernelMatch` feeds only the
- * reporting-side drift count and reaches no exit code.
+ * The rollup score is mutant-weighted (`sum(score * mutants) / sum(mutants)`),
+ * so thinly-mutated files cannot drag the aggregate past the floor. Rows carry
+ * no timeout/no-coverage counts, so it only approximates Stryker's overall
+ * score.
  */
 
 import { canonicalise } from '../path-canon.js';
@@ -47,15 +14,9 @@ import { makeBaselineKind } from './kind-factory.js';
 export const name = 'mutation';
 export const keyField = 'path';
 
-/**
- * Kernel version of the mutation scorer. Bumped off the original `1.0.0` by
- * Story #5058: the rollup score changed from an unweighted file mean to a
- * mutant-weighted mean, so rows stamped below this version were aggregated
- * under superseded semantics.
- */
+/** Major 2 marks the weighted rollup; older stamps used an unweighted mean. */
 const KERNEL_VERSION = '2.0.0';
 
-/** Major of {@link KERNEL_VERSION} — the weighted-rollup boundary. */
 const WEIGHTED_ROLLUP_MAJOR = 2;
 
 const RESEED_REMEDY =
@@ -75,8 +36,6 @@ export function projectRow(row) {
 }
 
 /**
- * Parse the major component of a semver-ish stamp.
- *
  * @param {unknown} version
  * @returns {number|null} The major, or null when unparseable/absent.
  */
@@ -86,16 +45,10 @@ function majorOf(version) {
 }
 
 /**
- * Kind-module hook (Story #4775) — refuse a loaded baseline whose rollup was
- * aggregated by the superseded unweighted mean. `checkBaselineSemantics`
- * dispatches here and `check-baselines`' evaluate phase turns a non-null
- * return into a fail-closed `semantics` schema error, so a pre-weighting
- * baseline can never be silently scored against floors calibrated on a
- * different definition of the number. Follows the `kinds/crap.js` precedent.
- *
- * An absent or unparseable stamp is rejected too: `kernelVersion` is required
- * by the shared envelope schema, so its absence is not evidence of a newer
- * writer.
+ * Kind-module hook: fail closed on a baseline aggregated by the unweighted
+ * mean, whose floors meant a different number. A plain `kernelVersion` drift
+ * reaches no exit code, so this hook is the real guard. A missing stamp is
+ * rejected too.
  *
  * @param {object|null} baseline A loaded v2 baseline envelope.
  * @returns {string|null} Operator-facing message, or null when compatible.
@@ -115,8 +68,6 @@ export function assertBaselineCompatible(baseline) {
 }
 
 /**
- * A row's mutant count — the weight it carries in the rollup score.
- *
  * @param {object} row
  * @returns {number}
  */
@@ -125,8 +76,6 @@ function mutantsOf(row) {
 }
 
 /**
- * Sum one numeric row field across a row set.
- *
  * @param {object[]} rows
  * @param {string} field
  * @returns {number}
@@ -138,12 +87,7 @@ function sumOf(rows, field) {
 }
 
 /**
- * The mutant-weighted mean score: `sum(score * mutants) / sum(mutants)`.
- *
- * Zero-mutant guard: an empty row set, or one whose rows carry only zeroes,
- * has no weight to divide by. Returning 0 rather than dividing keeps `NaN` and
- * `Infinity` out of the envelope, where they would fail the schema's numeric
- * bounds downstream.
+ * Zero mutants yields 0, keeping `NaN` out of the schema-validated envelope.
  *
  * @param {object[]} rows
  * @param {number} mutants Total mutant count across `rows`.
@@ -157,10 +101,6 @@ function weightedScore(rows, mutants) {
 }
 
 /**
- * Aggregate rows into the rollup shape. `killed` and `survived` stay plain
- * sums and `noCoverage` stays hardcoded 0 — the weighting changes `score`
- * alone.
- *
  * @param {object[]} rows
  * @returns {{score: number, killed: number, survived: number, noCoverage: number}}
  */

package/.agents/scripts/lib/baselines/maintainability-baseline-io.js

@@ -3,11 +3,8 @@ import path from 'node:path';
 import { Logger } from '../Logger.js';
 
 /**
- * Story #1895: project the canonical maintainability envelope back to the
- * legacy flat `{ path: mi }` map so existing gate consumers keep working
- * without churn — Story #1912 will replace this shim with the shared
- * reader. Returns the parsed input unchanged when it doesn't look like an
- * envelope (legacy flat shape stays flat).
+ * Project an envelope to the flat `{ path: mi }` map the gate consumers read;
+ * a non-envelope passes through unchanged.
  */
 function projectMaintainabilityEnvelopeToFlat(parsed) {
   if (
@@ -29,13 +26,9 @@ function projectMaintainabilityEnvelopeToFlat(parsed) {
 }
 
 /**
- * Loads the current maintainability baseline from disk. The on-disk path is
- * resolved by the caller via {@link getBaselines}; passing it explicitly
- * removes the silent-default behaviour the framework dropped in Epic #730
- * Story 5.5.
+ * No default path: the caller resolves it via {@link getBaselines}.
  *
- * @param {string} baselinePath  Repo-relative or absolute path to the baseline
- *   JSON. Required.
+ * @param {string} baselinePath  Repo-relative or absolute.
  * @returns {Record<string, number>}
  */
 export function getBaseline(baselinePath) {