mandrel 2.59.0 → 2.61.0

package/.agents/scripts/lib/baselines/kinds/_shared-metric.js

@@ -1,32 +1,11 @@
-/**
- * kinds/_shared-metric.js — shared metric helpers for per-kind baseline
- * modules (Story #3646).
- *
- * Both `crap.js` and `maintainability.js` duplicate the same
- * percentile/rollup/compare/epsilon algorithm verbatim. This module
- * extracts the parametrised core so each kind imports the factories
- * and passes only what differs (aggregate fields, identity key function,
- * better-is-higher polarity, metric field name).
- *
- * Exports (all pure, no I/O):
- *   - percentile(sortedValues, p)                     — verbatim shared
- *   - makeRollup({ aggregate })                       — rollup factory
- *   - makeAggregate({ fields })                       — aggregate factory
- *   - makeCompare({ identity, betterIsHigher })       — compare factory
- *   - makeEpsilon({ identity, metricField })          — epsilon factory
- */
+/** Pure metric factories shared by the per-kind baseline modules. */
 
 import { componentMatches } from '../component-matcher.js';
 
-// ---------------------------------------------------------------------------
-// percentile
-// ---------------------------------------------------------------------------
-
 /**
- * Nearest-rank percentile over a **pre-sorted** ascending numeric array.
- * Keeps rollup values integer-friendly without pulling in a stats dep.
+ * Nearest-rank percentile over a pre-sorted ascending array.
  *
- * @param {number[]} sortedValues - ascending-sorted array of numbers
+ * @param {number[]} sortedValues
  * @param {number} p - percentile in [0, 100]
  * @returns {number}
  */
@@ -39,12 +18,8 @@ export function percentile(sortedValues, p) {
   return sortedValues[idx];
 }
 
-// ---------------------------------------------------------------------------
-// makeAggregate
-// ---------------------------------------------------------------------------
-
 /**
- * Build an aggregate-stats function for a set of metric fields.
+ * Empty rows yield 0 for every percentile and extras key.
  *
  * @param {{
  *   fields: Array<{
@@ -55,16 +30,6 @@ export function percentile(sortedValues, p) {
  *   }>
  * }} opts
  * @returns {(rows: object[]) => Record<string, number>}
- *
- * Each `fields` entry describes one metric:
- *   - `name`        — key in the returned stats object (e.g. `'p50'`)
- *   - `rowKey`      — property name on each row (e.g. `'crap'`, `'mi'`)
- *   - `percentiles` — list of percentile values to compute (e.g. `[50, 95]`)
- *   - `extras`      — optional function over the sorted values that returns
- *                     extra keys (e.g. `{ max, methodsAbove20 }`)
- *
- * The return value when `rows` is empty is built from the field list:
- * every percentile resolves to 0 and every extras key resolves to 0.
  */
 export function makeAggregate({ fields }) {
   return function aggregate(rows) {
@@ -99,13 +64,7 @@ export function makeAggregate({ fields }) {
   };
 }
 
-// ---------------------------------------------------------------------------
-// makeRollup
-// ---------------------------------------------------------------------------
-
 /**
- * Build a rollup function that groups rows by component.
- *
  * @param {{ aggregate: (rows: object[]) => Record<string, number> }} opts
  * @returns {(rows: object[], components?: object[]) => Record<string, object>}
  */
@@ -120,12 +79,9 @@ export function makeRollup({ aggregate }) {
   };
 }
 
-// ---------------------------------------------------------------------------
-// makeCompare
-// ---------------------------------------------------------------------------
-
 /**
- * Build a compare(head, base) function for a per-kind baseline.
+ * A removed base row is an improvement only when `removedIsImprovement` says
+ * so; otherwise it is unchanged.
  *
  * @param {{
  *   identity: (row: object) => string,
@@ -133,13 +89,6 @@ export function makeRollup({ aggregate }) {
  *   metricField: string,
  *   removedIsImprovement?: (row: object) => boolean
  * }} opts
- *   - `identity`           — row → composite key string
- *   - `betterIsHigher`     — when true, delta > 0 is an improvement (MI);
- *                            when false, delta > 0 is a regression (CRAP)
- *   - `metricField`        — name of the numeric metric property on each row
- *   - `removedIsImprovement` — optional predicate deciding whether a removed
- *                              base row counts as an improvement; defaults to
- *                              `() => false` (no removal is auto-improvement)
  * @returns {(head: object, base: object) => {
  *   regressions: object[], improvements: object[],
  *   unchanged: object[], additions: object[]
@@ -189,12 +138,8 @@ export function makeCompare({
   };
 }
 
-// ---------------------------------------------------------------------------
-// makeEpsilon
-// ---------------------------------------------------------------------------
-
 /**
- * Build an applyEpsilon(prior, regenerated, epsilon) function.
+ * Within epsilon, the prior row object is returned so its bytes are kept.
  *
  * @param {{
  *   identity: (row: object) => string,

package/.agents/scripts/lib/baselines/kinds/bundle-size.js

@@ -1,8 +1,6 @@
 /**
- * kinds/bundle-size.js — per-kind module for the bundle-size baseline
- * (Story #1891). Row shape: `{ bundle, rawKb, gzippedKb }`. Bundle names
- * are opaque identifiers (`main`, `vendor`, etc.) rather than file paths,
- * so they bypass the canonicaliser.
+ * Per-kind module for the bundle-size baseline. Row shape:
+ * `{ bundle, rawKb, gzippedKb }`; bundle names are opaque, not paths.
  */
 
 import { mergeRowsByScope } from '../scope.js';
@@ -29,9 +27,7 @@ export function projectRow(row) {
 }
 
 /**
- * Canonical row identity (Story #5215). This kind does not use the shared
- * factory scaffold, so it declares the protocol member itself; `bundle` is
- * unique per row here, which a shipped-baseline injectivity test pins.
+ * `bundle` is unique per row.
  *
  * @param {{bundle: string, rawKb: number, gzippedKb: number}} row
  * @returns {string}
@@ -59,13 +55,8 @@ function aggregate(rows) {
 }
 
 /**
- * Pure compare(head, base) for the bundle-size kind. Diffs rows by
- * `bundle`. A row regresses when rawKb or gzippedKb increases; improves
- * when either decreases without the other increasing; otherwise
- * unchanged. New bundles count as regressions when they carry any size;
- * removed bundles count as improvements when they had any size.
- *
- * No I/O. No process exit. No friction emission.
+ * Any size increase regresses. Unlike the scaffold kinds, a new non-empty
+ * bundle is a regression, and a removed one an improvement.
  */
 export function compare(head, base) {
   const headRows = Array.isArray(head?.rows) ? head.rows : [];
@@ -116,10 +107,7 @@ export function rollup(rows, components = []) {
 }
 
 /**
- * Pure stabilizer for s-stability-epsilon (Story #1964). Bundle-size rows
- * match by `bundle`. The metric is the maximum absolute KB delta across
- * `rawKb` and `gzippedKb`. Sub-epsilon deltas resolve to the prior bytes;
- * missing-prior rows fall through.
+ * The delta is the larger of the raw and gzipped KB deltas.
  *
  * @param {Array<{bundle: string, rawKb: number, gzippedKb: number}>} prior
  * @param {Array<{bundle: string, rawKb: number, gzippedKb: number}>} regenerated
@@ -142,17 +130,8 @@ export function applyEpsilon(prior, regenerated, epsilon) {
 }
 
 /**
- * Pure scope-aware merge for s-diff-scoped-writes (Story #1974). Bundle
- * rows match by `bundle`. In diff mode, rows whose `bundle` name is
- * OUTSIDE `scope.files` are preserved from `prior` verbatim; in-scope
- * rows come from `regenerated`. In full mode (or no scope), regenerated
- * wins everywhere.
- *
- * Note: bundle names are not file paths. The scope filter only narrows
- * naturally when callers seed `scope.files` with bundle names. Auto-
- * refresh callers using a Story file diff will see no in-scope rows and
- * therefore preserve every prior row — the safe default for a baseline
- * whose identity is not file-derived.
+ * Bundle names are not paths, so a file-diff scope matches nothing and every
+ * prior row is preserved — the safe default.
  *
  * @param {Array<{bundle: string, rawKb: number, gzippedKb: number}>} prior
  * @param {Array<{bundle: string, rawKb: number, gzippedKb: number}>} regenerated

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

@@ -1,19 +1,7 @@
 /**
- * kinds/coverage.js — per-kind module for the coverage baseline (Story #1891).
- *
- * Row shape: `{ path, lines, branches, functions }` (percentages 0–100).
- * Rollup math: per-axis denominator-weighted average is overkill for the
- * foundation — we ship the arithmetic mean across rows for the whole-repo
- * `*` key and each component. Per-row denominators land later when the
- * components resolver and per-component weighting (Story #1902, #1919)
- * arrive; the rollup signature is stable so callers don't churn.
- *
- * Higher percentages are better. New paths land in the `additions` bucket
- * (Story #2012 — partial coverage on a new file must never flip to a
- * regression); removed paths inherit a perfect head row so any lower base
- * registers as an improvement. Scaffold (sortRows / rollup / compare /
- * applyEpsilon / mergeRows) is generated by `makeBaselineKind`
- * (Story #3983).
+ * Per-kind module for the coverage baseline. Row shape:
+ * `{ path, lines, branches, functions }` (0–100). The rollup is an
+ * unweighted mean across rows. A removed path compares against a perfect head.
  */
 
 import { canonicalise } from '../path-canon.js';