mandrel 1.57.0

package/.agents/scripts/lib/baselines/path-canon.js

@@ -0,0 +1,279 @@
+/**
+ * path-canon.js — single canonicalisation authority for every path written
+ * into (or compared against) a Mandrel baseline (Story #1891, Epic #1786).
+ *
+ * This module is the one place baseline path canonicalisation lives. It
+ * exposes three helpers tuned to two boundaries (Story #3345 folded the
+ * formerly separate `canonicalize-path.js` permissive coercer in here so
+ * there is a single import surface):
+ *
+ *   - `canonicalise(p)` — the **strict** repo-relative canonicaliser. It
+ *     rejects input it considers unsafe to key a baseline by, then
+ *     normalises what it accepts.
+ *   - `assertCanonical(p)` — the **throw-on-reject** writer-boundary check.
+ *     It runs the same rejection checks as `canonicalise` but never
+ *     transforms the input.
+ *   - `canonicalizeBaselinePath(p)` — the **permissive coercer** used by the
+ *     refresh service. It never throws on absolute / drive-letter / UNC
+ *     input; instead it transforms those shapes into a repo-relative key,
+ *     because its caller funnels raw `git diff` and tool output through a
+ *     single point that must always yield a canonical key.
+ *
+ * `canonicalise` enforces, in order:
+ *
+ *   1. Rejects absolute paths (Windows `C:\...` or POSIX `/...`) — baselines
+ *      that key by absolute paths break the moment they're checked out on a
+ *      different machine, in a worktree, or in CI.
+ *   2. Rejects `..` segments — baselines must not name files outside the
+ *      repo root, and the loader's signed-int comparison can otherwise be
+ *      fooled by a traversal-shaped key.
+ *   3. Strips a leading `.worktrees/<workspace>/` prefix so a refresh run
+ *      from inside `.worktrees/story-1891/...` produces the same key as a
+ *      refresh from the main checkout. This is the defensive policy that
+ *      stops a future worktree-based refresh from reintroducing the
+ *      maintainability worktree-prefix regression that prompted Story #1891.
+ *   4. Normalises Windows backslashes to forward slashes.
+ *   5. Strips a leading `./` for cosmetic stability — `./src/a.js` and
+ *      `src/a.js` are the same path and should serialise to the same key.
+ *
+ * Both `canonicalise` and `canonicalizeBaselinePath` are **idempotent**:
+ * feeding either function's output back in produces the same string. Tests
+ * pin this property explicitly.
+ *
+ * `assertCanonical` is the throw-on-reject variant. It runs the same checks
+ * but does not transform the input — used at the writer boundary to assert
+ * a row's `path` has already been canonicalised by the caller (so the writer
+ * never silently rewrites a row's identity).
+ *
+ * @module lib/baselines/path-canon
+ */
+
+const WORKTREE_PREFIX = /^\.worktrees\/[^/\\]+[/\\]/;
+
+/**
+ * Test whether `value` is a Windows or POSIX absolute path. Windows absolute
+ * paths have a drive letter (`C:`) or start with a backslash-separator
+ * (`\\server\share`). POSIX absolute paths start with a forward slash.
+ *
+ * @param {string} value
+ * @returns {boolean}
+ */
+function isAbsolute(value) {
+  if (value.startsWith('/')) return true;
+  if (value.startsWith('\\')) return true;
+  // Drive-letter form: `C:\...` or `C:/...` or even bare `C:foo` (rare but
+  // still absolute in Windows semantics — refuse it).
+  if (/^[A-Za-z]:[\\/]?/.test(value)) return true;
+  return false;
+}
+
+/**
+ * Test whether `value` contains a `..` segment. We tokenise on both `/` and
+ * `\` so a Windows-shaped path like `src\..\evil.js` is caught before
+ * normalisation rewrites the separators.
+ *
+ * @param {string} value
+ * @returns {boolean}
+ */
+function hasTraversal(value) {
+  const parts = value.split(/[/\\]/);
+  return parts.some((segment) => segment === '..');
+}
+
+/**
+ * Canonicalise a path for use as a baseline row key.
+ *
+ * @param {string} input  A repo-relative path. May use `\` or `/` separators
+ *                        and may carry a leading `./` or
+ *                        `.worktrees/<workspace>/` prefix.
+ * @returns {string}      The canonical, forward-slash, repo-relative form.
+ * @throws {TypeError}    When `input` is not a string.
+ * @throws {Error}        When `input` is absolute or contains a `..` segment.
+ */
+export function canonicalise(input) {
+  if (typeof input !== 'string') {
+    throw new TypeError(
+      `path-canon.canonicalise: expected string, got ${typeof input}`,
+    );
+  }
+  if (input.length === 0) {
+    throw new Error('path-canon.canonicalise: path must be non-empty');
+  }
+  if (isAbsolute(input)) {
+    throw new Error(
+      `path-canon.canonicalise: absolute paths are forbidden in baselines (got "${input}")`,
+    );
+  }
+  if (hasTraversal(input)) {
+    throw new Error(
+      `path-canon.canonicalise: ".." segments are forbidden in baselines (got "${input}")`,
+    );
+  }
+
+  // 1. Normalise separators first so the worktree-prefix regex sees a
+  //    forward-slash form regardless of platform.
+  let working = input.replace(/\\/g, '/');
+
+  // 2. Strip `.worktrees/<workspace>/` prefix (defensive policy — see
+  //    module preamble).
+  working = working.replace(WORKTREE_PREFIX, '');
+
+  // 3. Strip a leading `./` after worktree-prefix removal so
+  //    `./.worktrees/story-1/src/a.js` and `.worktrees/story-1/src/a.js`
+  //    converge.
+  if (working.startsWith('./')) working = working.slice(2);
+
+  // 4. Collapse any accidental double-slashes introduced by upstream
+  //    string concat — leaves leading `/` alone since we've already
+  //    rejected absolute paths.
+  working = working.replace(/\/{2,}/g, '/');
+
+  if (working.length === 0) {
+    throw new Error(
+      `path-canon.canonicalise: path collapsed to empty after canonicalisation (got "${input}")`,
+    );
+  }
+
+  return working;
+}
+
+/**
+ * Assert that `input` is already in canonical form. Throws on any deviation;
+ * never transforms the input. Used at the writer boundary as a defensive
+ * check that callers have funnelled their rows through `canonicalise` before
+ * handing them to `write()`.
+ *
+ * @param {string} input
+ * @returns {void}
+ * @throws {TypeError|Error}
+ */
+export function assertCanonical(input) {
+  if (typeof input !== 'string') {
+    throw new TypeError(
+      `path-canon.assertCanonical: expected string, got ${typeof input}`,
+    );
+  }
+  if (input.length === 0) {
+    throw new Error('path-canon.assertCanonical: path must be non-empty');
+  }
+  if (isAbsolute(input)) {
+    throw new Error(
+      `path-canon.assertCanonical: absolute paths are forbidden in baselines (got "${input}")`,
+    );
+  }
+  if (hasTraversal(input)) {
+    throw new Error(
+      `path-canon.assertCanonical: ".." segments are forbidden in baselines (got "${input}")`,
+    );
+  }
+  if (input.includes('\\')) {
+    throw new Error(
+      `path-canon.assertCanonical: backslash separators are forbidden in baselines (got "${input}")`,
+    );
+  }
+  if (WORKTREE_PREFIX.test(input)) {
+    throw new Error(
+      `path-canon.assertCanonical: .worktrees/<workspace>/ prefix is forbidden in baselines (got "${input}")`,
+    );
+  }
+  if (input.startsWith('./')) {
+    throw new Error(
+      `path-canon.assertCanonical: leading "./" is forbidden in baselines (got "${input}")`,
+    );
+  }
+  if (input.includes('//')) {
+    throw new Error(
+      `path-canon.assertCanonical: double-slash segments are forbidden in baselines (got "${input}")`,
+    );
+  }
+}
+
+/**
+ * Permissively coerce a raw filesystem path into the POSIX, repo-relative
+ * key shape used by the Unified Baseline Refresh Service (Story #2192,
+ * Epic #2173). Unlike `canonicalise`, this helper never throws on absolute,
+ * drive-letter, or UNC input — it transforms those shapes into a
+ * repo-relative key because its caller (the refresh service) receives raw
+ * paths from `git diff` and tool output and needs a single funnel that
+ * always produces a canonical key.
+ *
+ * Rules, in order:
+ *   1. Reject non-string input with `TypeError`.
+ *   2. Swap every `\` for `/` so the rest of the pipeline sees a single
+ *      separator style regardless of platform.
+ *   3. Strip a UNC prefix (`//server/share/`) so paths surfaced by tools
+ *      that resolved a network share collapse to a repo-relative key.
+ *   4. Strip a Windows drive-letter prefix (`C:` / `C:/`) so paths
+ *      surfaced by Windows tools collapse to the same key as the
+ *      equivalent Linux path.
+ *   5. Strip a single leading `/` so a path that was absolute after
+ *      drive-letter stripping becomes repo-relative.
+ *   6. Strip a leading `.worktrees/<workspace>/` prefix so a refresh run
+ *      from inside a worktree produces the same key as a refresh from the
+ *      main checkout. This MUST match the equivalent step in
+ *      `canonicalise()` (Story #3695): the strict canonicaliser used by the
+ *      per-kind `projectRow` strips this prefix, so the permissive coercer
+ *      that builds the diff-scope `scope.files` set MUST strip it too —
+ *      otherwise a scored row's path (`src/new.js`) never matches its
+ *      worktree-prefixed scope entry (`.worktrees/story-1/src/new.js`) and
+ *      a brand-new file's row is silently dropped from the scoped baseline.
+ *   7. Strip a leading `./` for cosmetic stability.
+ *   8. Collapse any `/{2,}` run to a single `/`.
+ *
+ * The function is **idempotent**: feeding its own output back in produces
+ * the same string. Downstream consumers (the refresh service and the gate
+ * reader) rely on this property so a row written on Windows compares equal
+ * to the same row written on Linux.
+ *
+ * @param {string} input  A raw filesystem path. May use `\` or `/`
+ *                        separators, may carry a Windows drive letter, may
+ *                        be absolute or relative.
+ * @returns {string}      The canonical, forward-slash, repo-relative key.
+ * @throws {TypeError}    When `input` is not a string.
+ */
+export function canonicalizeBaselinePath(input) {
+  if (typeof input !== 'string') {
+    throw new TypeError(
+      `canonicalizeBaselinePath: expected string, got ${input === null ? 'null' : typeof input}`,
+    );
+  }
+
+  // 1. Normalize separators first.
+  let working = input.replace(/\\/g, '/');
+
+  // 2. Strip UNC share prefix (`//server/share/...`) before generic
+  //    double-slash collapse so the share name is preserved as a regular
+  //    path segment, not eaten.
+  const uncMatch = working.match(/^\/\/([^/]+)\/([^/]+)(\/|$)/);
+  if (uncMatch) {
+    working = working.slice(uncMatch[0].length);
+  }
+
+  // 3. Strip Windows drive-letter prefix (`C:` or `C:/`).
+  working = working.replace(/^[A-Za-z]:\/?/, '');
+
+  // 4. Strip a single leading `/` so an absolute path becomes
+  //    repo-relative.
+  if (working.startsWith('/')) {
+    working = working.replace(/^\/+/, '');
+  }
+
+  // 5. Strip a leading `.worktrees/<workspace>/` prefix (Story #3695) so a
+  //    worktree-rooted path collapses to the same repo-relative key the
+  //    strict `canonicalise()` produces. Without this, a scored row path and
+  //    its diff-scope `scope.files` entry diverge inside a worktree and the
+  //    scope-aware merge drops brand-new files. Only a single leading
+  //    segment is stripped — a legitimate inner `.worktrees/` directory the
+  //    user named themselves is preserved (mirrors `canonicalise`).
+  working = working.replace(WORKTREE_PREFIX, '');
+
+  // 6. Strip a leading `./`.
+  if (working.startsWith('./')) {
+    working = working.slice(2);
+  }
+
+  // 7. Collapse redundant separators.
+  working = working.replace(/\/{2,}/g, '/');
+
+  return working;
+}

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

@@ -0,0 +1,298 @@
+/**
+ * preview-gates.js — `quality-preview` / `quality-watch` per-kind runners.
+ *
+ * Hoisted from the per-kind CLI shells (Story #1981, Task #2005) so the
+ * quality-preview surface no longer depends on the to-be-deleted
+ * `check-maintainability.js` and `check-crap.js` CLI scripts. Each
+ * exported runner takes a parsed scope ref + an optional `--staged`
+ * flag, runs the same scan → compare → report-builder pipeline the CLIs
+ * used internally, and returns:
+ *
+ *   {
+ *     exitCode,                 // 0 = pass, 1 = regression / floor break
+ *     envelope,                 // the same `--json` envelope the CLI emitted
+ *   }
+ *
+ * No I/O beyond the scan itself; no friction signals (preview is a
+ * developer-facing tool, not a gate); no `process.exit`.
+ */
+
+import path from 'node:path';
+
+import { resolvePreviewScope } from '../changed-files.js';
+import { getBaselines, getQuality, resolveConfig } from '../config-resolver.js';
+import { loadCoverage } from '../coverage-utils.js';
+import {
+  KERNEL_VERSION,
+  resolveEscomplexVersion,
+  scanAndScore,
+} from '../crap-utils.js';
+import { calculateAll, scanDirectory } from '../maintainability-utils.js';
+import { resolveCrapEnvOverrides } from './env-overrides.js';
+import {
+  buildCrapReport,
+  compareCrap,
+  filterRowsByFileScope,
+  loadCrapBaseline,
+} from './kinds/crap.js';
+import {
+  buildMaintainabilityReport,
+  loadMaintainabilityBaseline,
+  MAINTAINABILITY_EXCLUSIONS,
+} from './kinds/maintainability.js';
+
+/**
+ * Framework default MI preview tolerance, used only when neither an explicit
+ * override nor a configured `quality.maintainability.tolerance` is present.
+ * Mirrors the historical preview default.
+ */
+export const MI_PREVIEW_DEFAULT_TOLERANCE = 0.5;
+
+/**
+ * Resolve the effective maintainability tolerance for the preview gate so it
+ * agrees with the authoritative `check-baselines` gate. Precedence: an explicit
+ * caller override → the configured `quality.maintainability.tolerance` (already
+ * resolved to a scalar by `getQuality`) → the framework default. Previously the
+ * preview hardcoded the default and ignored the configured value, so a project
+ * that raised its tolerance (e.g. to 12) still saw the local pre-commit/pre-push
+ * gate flag sub-tolerance drops that `check-baselines` accepted.
+ *
+ * @param {{ explicit?: number | null, configured?: number, fallback?: number }} opts
+ * @returns {number}
+ */
+export function resolvePreviewTolerance({
+  explicit = null,
+  configured,
+  fallback = MI_PREVIEW_DEFAULT_TOLERANCE,
+} = {}) {
+  if (Number.isFinite(explicit)) return explicit;
+  if (Number.isFinite(configured)) return configured;
+  return fallback;
+}
+
+/**
+ * Pure: replicate the legacy `check-maintainability.js compareScores`
+ * behavior so the preview runner can build the stats block the report
+ * builder expects.
+ *
+ * @param {Record<string, number>} scores
+ * @param {Record<string, number>} baseline
+ * @param {number} tolerance
+ */
+function compareScores(scores, baseline, tolerance) {
+  let regressions = 0;
+  let newFiles = 0;
+  let improvements = 0;
+  const regressedFiles = [];
+  for (const [file, score] of Object.entries(scores ?? {})) {
+    const baselineScore = baseline?.[file];
+    if (baselineScore === undefined) {
+      newFiles += 1;
+      continue;
+    }
+    if (score < baselineScore - tolerance) {
+      const drop = baselineScore - score;
+      regressions += 1;
+      regressedFiles.push({
+        file,
+        current: score,
+        baseline: baselineScore,
+        drop,
+      });
+    } else if (score > baselineScore + tolerance) {
+      improvements += 1;
+    }
+  }
+  return { regressions, newFiles, improvements, regressedFiles };
+}
+
+/**
+ * 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[]}
+ */
+function resolveBaselineRows(baseline, scopeSet) {
+  return scopeSet
+    ? filterRowsByFileScope(baseline.rows, scopeSet)
+    : baseline.rows;
+}
+
+/**
+ * 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}
+ */
+function hasCrapRegressions(result) {
+  return result.regressions > 0 || result.newViolations > 0;
+}
+
+function applyDiffScopeMi({ files, baseline, scopeSet, cwd }) {
+  if (!scopeSet) {
+    return { scopedFiles: files, scopedBaseline: baseline ?? {} };
+  }
+  const scopedFiles = files.filter((abs) => {
+    const rel = path.relative(cwd, abs).replace(/\\/g, '/');
+    return scopeSet.has(rel);
+  });
+  const scopedBaseline = Object.fromEntries(
+    Object.entries(baseline ?? {}).filter(([file]) => scopeSet.has(file)),
+  );
+  return { scopedFiles, scopedBaseline };
+}
+
+/**
+ * Run the maintainability gate in preview mode.
+ *
+ * @param {{
+ *   cwd?: string,
+ *   changedSinceRef?: string | null,
+ *   staged?: boolean,
+ *   tolerance?: number,
+ * }} [opts]
+ */
+export async function runMaintainabilityPreview({
+  cwd = process.cwd(),
+  changedSinceRef = null,
+  staged = false,
+  tolerance = null,
+} = {}) {
+  const config = resolveConfig({ cwd });
+  const baselinePath = getBaselines(config).maintainability.path;
+  const baseline = loadMaintainabilityBaseline({
+    baselinePath: path.isAbsolute(baselinePath)
+      ? baselinePath
+      : path.resolve(cwd, baselinePath),
+    epicRef: null,
+  });
+
+  const miQuality = getQuality(config).maintainability;
+  const effectiveTolerance = resolvePreviewTolerance({
+    explicit: tolerance,
+    configured: miQuality.tolerance,
+  });
+  const targetDirs = miQuality.targetDirs;
+  const ignoreGlobs = miQuality.ignoreGlobs ?? [];
+  const files = [];
+  for (const dir of targetDirs) {
+    const abs = path.isAbsolute(dir) ? dir : path.resolve(cwd, dir);
+    scanDirectory(abs, files, { cwd, ignoreGlobs });
+  }
+  const { scopeSet, scope, diffRef } = resolvePreviewScope({
+    staged,
+    changedSinceRef,
+    cwd,
+  });
+  const { scopedFiles, scopedBaseline } = applyDiffScopeMi({
+    files,
+    baseline,
+    scopeSet,
+    cwd,
+  });
+
+  const rawScores = await calculateAll(scopedFiles);
+  // Story #2467 / Task #2494: drop parse-unscorable files so they cannot
+  // surface as phantom MI=0 regressions in the preview envelope.
+  const scores = {};
+  for (const [key, mi] of Object.entries(rawScores)) {
+    const rel = path.isAbsolute(key) ? path.relative(cwd, key) : key;
+    const posixRel = rel.split(path.sep).join('/');
+    if (!MAINTAINABILITY_EXCLUSIONS.has(posixRel)) scores[key] = mi;
+  }
+  const stats = compareScores(scores, scopedBaseline, effectiveTolerance);
+  const envelope = buildMaintainabilityReport(scores, stats, {
+    scope,
+    diffRef,
+  });
+  const exitCode = stats.regressions > 0 ? 1 : 0;
+  return { exitCode, envelope };
+}
+
+/**
+ * Run the CRAP gate in preview mode.
+ */
+export async function runCrapPreview({
+  cwd = process.cwd(),
+  changedSinceRef = null,
+  staged = false,
+} = {}) {
+  const { scopeSet, scope, diffRef } = resolvePreviewScope({
+    staged,
+    changedSinceRef,
+    cwd,
+  });
+  const config = resolveConfig({ cwd });
+  const baselinePath = getBaselines(config).crap.path;
+  const baseline = loadCrapBaseline({
+    baselinePath: path.isAbsolute(baselinePath)
+      ? baselinePath
+      : path.resolve(cwd, baselinePath),
+    epicRef: null,
+  });
+  const quality = getQuality(config);
+  const crap = quality.crap;
+  if (!baseline || crap.enabled === false) {
+    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: [],
+      },
+    };
+  }
+
+  const targetDirs = Array.isArray(crap.targetDirs) ? crap.targetDirs : [];
+  const crapIgnoreGlobs = Array.isArray(crap.ignoreGlobs)
+    ? crap.ignoreGlobs
+    : [];
+  const requireCoverage = crap.requireCoverage !== false;
+  const coveragePath = crap.coveragePath ?? 'coverage/coverage-final.json';
+  const coverage = loadCoverage(path.resolve(cwd, coveragePath));
+  const { newMethodCeiling, tolerance } = resolveCrapEnvOverrides(
+    crap,
+    process.env,
+  );
+  const scan = await scanAndScore({
+    targetDirs,
+    coverage,
+    requireCoverage,
+    cwd,
+    scopeFiles: scopeSet,
+    ignoreGlobs: crapIgnoreGlobs,
+  });
+  const baselineRows = resolveBaselineRows(baseline, scopeSet);
+  const result = compareCrap({
+    currentRows: scan.rows,
+    baselineRows,
+    newMethodCeiling,
+    tolerance,
+  });
+  const envelope = buildCrapReport({
+    compareResult: result,
+    scanSummary: scan,
+    kernelVersion: KERNEL_VERSION,
+    escomplexVersion: resolveEscomplexVersion(),
+    newMethodCeiling,
+    scopeInfo: {
+      scope,
+      diffRef,
+    },
+  });
+  const exitCode = hasCrapRegressions(result) ? 1 : 0;
+  return { exitCode, envelope };
+}