mandrel 1.57.0

package/.agents/scripts/update-coverage-baseline.js

@@ -0,0 +1,129 @@
+#!/usr/bin/env node
+// cli-opt-out: top-level main()-driven CLI invoked via npm run coverage:update; no runAsCli() wrapper required.
+/**
+ * Refresh `baselines/coverage.json` from the most recent
+ * `coverage/coverage-final.json`. Run this when you intentionally add,
+ * remove, or change scope of `.agents/scripts/**` files and the
+ * resulting per-file coverage shifts are expected.
+ *
+ * Story #3658 (Epic #2173): this CLI is now a thin wrapper around
+ * `refreshBaseline({ kind: 'coverage' })` from
+ * `.agents/scripts/lib/baselines/refresh-service.js`. All scoring, scope
+ * resolution, envelope assembly, and persistence flows through the unified
+ * service.
+ *
+ * The script does NOT run the test suite itself — invoke
+ * `npm run test:coverage` first (or rely on its prior run-on-disk
+ * artifact). This keeps the refresh idempotent and lets operators
+ * inspect coverage output before locking it in.
+ */
+
+import { createRequire } from 'node:module';
+import path from 'node:path';
+import { parseDiffScopeFlag } from './lib/baselines/diff-scope-cli.js';
+import { refreshBaseline } from './lib/baselines/refresh-service.js';
+import { getBaselineEpsilon } from './lib/config/quality.js';
+import {
+  buildScopePredicate,
+  COVERAGE_BASELINE_PATH,
+  readCoverageFinal,
+  scoreCoverageFinal,
+} from './lib/coverage-baseline.js';
+import { Logger } from './lib/Logger.js';
+
+const require = createRequire(import.meta.url);
+
+function loadC8Scope(cwd) {
+  return require(path.resolve(cwd, '.c8rc.cjs'));
+}
+
+function parseFullScopeFlag(argv = []) {
+  return argv.includes('--full-scope');
+}
+
+function main() {
+  const argv = process.argv.slice(2);
+  const diffScopeRef = parseDiffScopeFlag(argv);
+  const fullScope = parseFullScopeFlag(argv);
+  const cwd = process.cwd();
+  Logger.info('[Coverage] Updating baseline from coverage-final.json...');
+
+  if (fullScope && diffScopeRef !== null) {
+    throw new Error(
+      '[Coverage] --full-scope is incompatible with --diff-scope; pick one',
+    );
+  }
+
+  // Build the per-kind scorer the service will invoke. The scorer receives
+  // `(files, { fullScope })` and returns rows in the `{path, lines,
+  // branches, functions}` shape the writer expects.
+  const scorer = (files, opts) => {
+    const effectiveCwd = opts?.cwd ?? cwd;
+    let raw;
+    try {
+      raw = readCoverageFinal(effectiveCwd);
+    } catch (err) {
+      Logger.error(`[Coverage] ❌ ${err.message}`);
+      return [];
+    }
+
+    const c8Config = loadC8Scope(effectiveCwd);
+    const c8Scope = buildScopePredicate({
+      include: c8Config.include ?? [],
+      exclude: c8Config.exclude ?? [],
+    });
+    const scores = scoreCoverageFinal({
+      raw,
+      cwd: effectiveCwd,
+      scope: c8Scope,
+    });
+
+    // 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)
+        : null;
+
+    const rows = Object.entries(scores)
+      .filter(([relPath]) => inScope === null || inScope.has(relPath))
+      .map(([relPath, score]) => ({
+        path: relPath,
+        lines: score?.lines ?? 0,
+        branches: score?.branches ?? 0,
+        functions: score?.functions ?? 0,
+      }));
+
+    const fileCount = Object.keys(scores).length;
+    Logger.info(
+      `[Coverage] Scored ${fileCount} file(s)${inScope ? ` (${rows.length} in scope)` : ''}.`,
+    );
+    return rows;
+  };
+
+  const absBaselinePath = path.resolve(cwd, COVERAGE_BASELINE_PATH);
+  const epsilon = getBaselineEpsilon('coverage', null);
+  const refreshOpts = {
+    kind: 'coverage',
+    writePath: absBaselinePath,
+    epsilon,
+    scorer,
+  };
+  if (fullScope) {
+    refreshOpts.fullScope = true;
+  } else if (diffScopeRef) {
+    refreshOpts.baseRef = diffScopeRef;
+  }
+  // No flag → scopeFiles=null + fullScope=false → service derives the diff
+  // via `origin/main..HEAD` (its default baseRef/headRef).
+
+  return refreshBaseline(refreshOpts).then((result) => {
+    Logger.info(
+      `[Coverage] ✅ Baseline updated: ${result.envelope.rows.length} file(s) recorded at ${COVERAGE_BASELINE_PATH} (${absBaselinePath}). scope=${result.scope.mode}, wrote=${result.wrote}.`,
+    );
+  });
+}
+
+main().catch((err) => {
+  Logger.error(`[Coverage] ❌ Fatal error: ${err?.message ?? err}`);
+  process.exit(1);
+});

package/.agents/scripts/update-crap-baseline.js

@@ -0,0 +1,177 @@
+// Fail-fast if the framework's runtime deps are not installed — must be the
+// first import so the check runs before any third-party-importing sibling
+// module is evaluated (Story #3432).
+import './lib/runtime-deps/ensure-installed.js';
+import path from 'node:path';
+import { parseDiffScopeFlag } from './lib/baselines/diff-scope-cli.js';
+import { refreshBaseline } from './lib/baselines/refresh-service.js';
+import { getBaselineEpsilon } from './lib/config/quality.js';
+import {
+  getBaselines,
+  getQuality,
+  resolveConfig,
+} from './lib/config-resolver.js';
+import { loadCoverage } from './lib/coverage-utils.js';
+import {
+  resolveEscomplexVersion,
+  resolveTsTranspilerVersion,
+  scanAndScore,
+} from './lib/crap-utils.js';
+
+import { Logger } from './lib/Logger.js';
+
+/**
+ * CLI: scan → score → save the CRAP baseline.
+ *
+ * Story #3658 (Epic #2173): this CLI is now a thin wrapper around
+ * `refreshBaseline({ kind: 'crap' })` from
+ * `.agents/scripts/lib/baselines/refresh-service.js`. All scoring, scope
+ * resolution, envelope assembly, and persistence flows through the unified
+ * service.
+ *
+ * Writes the canonical CRAP baseline at the path resolved from
+ * `delivery.quality.baselines.crap.path` (default `baselines/crap.json`),
+ * or the path supplied via `--baseline <path>`. Output is a deterministic,
+ * kernel-stamped envelope. Files without coverage entries are skipped (not
+ * scored as 0%) when `requireCoverage: true` — their count and names are
+ * logged so the operator can tell the difference between "unscorable" and
+ * "safe zero".
+ *
+ * Exits non-zero only when the scanner itself crashes. An empty result (no
+ * coverage at all, no scored methods) still writes an envelope with `rows: []`
+ * so downstream `check-crap` can tell "intentional empty baseline" apart from
+ * "no baseline yet".
+ */
+
+function parseCliArgs(argv = process.argv.slice(2)) {
+  const out = {
+    baselinePath: undefined,
+    coveragePath: undefined,
+    fullScope: false,
+    diffScopeRef: null,
+  };
+  for (let i = 0; i < argv.length; i += 1) {
+    if (argv[i] === '--baseline' && argv[i + 1]) {
+      out.baselinePath = argv[i + 1];
+      i += 1;
+    } else if (argv[i] === '--coverage' && argv[i + 1]) {
+      out.coveragePath = argv[i + 1];
+      i += 1;
+    } else if (argv[i] === '--full-scope') {
+      out.fullScope = true;
+    }
+  }
+  out.diffScopeRef = parseDiffScopeFlag(argv);
+  return out;
+}
+
+async function main() {
+  const args = parseCliArgs();
+  const config = resolveConfig();
+  const crap = getQuality(config).crap;
+  const targetDirs = Array.isArray(crap.targetDirs) ? crap.targetDirs : [];
+  const requireCoverage = crap.requireCoverage !== false;
+  const coveragePath =
+    args.coveragePath ?? crap.coveragePath ?? 'coverage/coverage-final.json';
+  const baselinePath = args.baselinePath ?? getBaselines(config).crap.path;
+  const ignoreGlobs = Array.isArray(crap.ignoreGlobs) ? crap.ignoreGlobs : [];
+
+  Logger.info('[CRAP] Updating baseline...');
+  Logger.info(`[CRAP] Target dirs: ${targetDirs.join(', ')}`);
+  Logger.info(
+    `[CRAP] Coverage source: ${coveragePath}${requireCoverage ? ' (required)' : ' (optional)'}`,
+  );
+
+  const absBaselinePath = path.isAbsolute(baselinePath)
+    ? baselinePath
+    : path.resolve(process.cwd(), baselinePath);
+
+  if (args.fullScope && args.diffScopeRef !== null) {
+    throw new Error(
+      '[CRAP] --full-scope is incompatible with --diff-scope; pick one',
+    );
+  }
+
+  // Build the per-kind scorer the service will invoke. The scorer receives
+  // `(files, { fullScope, cwd })`:
+  //   - fullScope === true:  walk all target dirs; scopeFiles=null passed to scanAndScore.
+  //   - fullScope === false: score only the diff-derived in-scope files.
+  const scorer = async (files, opts) => {
+    const effectiveCwd = opts?.cwd ?? process.cwd();
+    const coverageAbs = path.isAbsolute(coveragePath)
+      ? coveragePath
+      : path.resolve(effectiveCwd, coveragePath);
+    const coverage = loadCoverage(coverageAbs);
+    if (!coverage && requireCoverage) {
+      Logger.warn(
+        `[CRAP] ⚠ No coverage artifact at ${coveragePath}. All files will be skipped under requireCoverage=true.`,
+      );
+      Logger.warn(
+        "[CRAP] ⚠ Run 'npm run test:coverage' before 'npm run crap:update'.",
+      );
+      return [];
+    }
+    const scopeFiles = opts?.fullScope ? null : (files ?? null);
+    const {
+      rows,
+      scannedFiles,
+      skippedFilesNoCoverage,
+      skippedMethodsNoCoverage,
+    } = await scanAndScore({
+      targetDirs,
+      coverage,
+      requireCoverage,
+      cwd: effectiveCwd,
+      ignoreGlobs,
+      scopeFiles,
+    });
+
+    Logger.info(`[CRAP] Scanned ${scannedFiles} file(s).`);
+    if (skippedFilesNoCoverage > 0) {
+      Logger.info(
+        `[CRAP] Skipped ${skippedFilesNoCoverage} file(s) without coverage entries.`,
+      );
+    }
+    if (skippedMethodsNoCoverage > 0) {
+      Logger.info(
+        `[CRAP] Skipped ${skippedMethodsNoCoverage} method(s) whose per-method coverage was unresolved.`,
+      );
+    }
+
+    return (rows ?? []).filter(
+      (r) => typeof r?.crap === 'number' && Number.isFinite(r.crap),
+    );
+  };
+
+  const epsilon = getBaselineEpsilon('crap', config);
+  const refreshOpts = {
+    kind: 'crap',
+    writePath: absBaselinePath,
+    epsilon,
+    scorer,
+  };
+  if (args.fullScope) {
+    refreshOpts.fullScope = true;
+  } else if (args.diffScopeRef) {
+    refreshOpts.baseRef = args.diffScopeRef;
+  }
+  // No flag → scopeFiles=null + fullScope=false → service derives the diff
+  // via `origin/main..HEAD` (its default baseRef/headRef).
+
+  const result = await refreshBaseline(refreshOpts);
+
+  const escomplexVersion = resolveEscomplexVersion();
+  const tsTranspilerVersion = resolveTsTranspilerVersion();
+  Logger.info(
+    `[CRAP] ✅ Baseline updated (kernelVersion=${result.envelope.kernelVersion}, escomplexVersion=${escomplexVersion}, tsTranspilerVersion=${tsTranspilerVersion}). Wrote to ${absBaselinePath}.`,
+  );
+  Logger.info(
+    `[CRAP] Wrote ${result.envelope.rows.length} row(s). scope=${result.scope.mode}, wrote=${result.wrote}.`,
+  );
+}
+
+// cli-opt-out: top-level main().catch predates runAsCli; never imported elsewhere so the auto-run risk is moot.
+main().catch((err) => {
+  Logger.error(`[CRAP] ❌ Fatal error: ${err?.stack ?? err?.message ?? err}`);
+  process.exit(1);
+});

package/.agents/scripts/update-duplication-baseline.js

@@ -0,0 +1,134 @@
+// Fail-fast if the framework's runtime deps are not installed — must be the
+// first import so the check runs before any third-party-importing sibling
+// module is evaluated (Story #3432).
+import './lib/runtime-deps/ensure-installed.js';
+import { createRequire } from 'node:module';
+import path from 'node:path';
+import { buildWriterScopeArgs } from './lib/baselines/diff-scope-cli.js';
+import { scanDuplication } from './lib/baselines/duplication-scanner.js';
+import { write, writeFile } from './lib/baselines/writer.js';
+import { getBaselineEpsilon } from './lib/config/quality.js';
+import { getQuality, resolveConfig } from './lib/config-resolver.js';
+import { Logger } from './lib/Logger.js';
+
+/**
+ * CLI: scan → score → save the code-duplication (DRY) baseline (Story #3664).
+ *
+ * Writes the canonical duplication baseline at the path resolved from
+ * `delivery.quality.gates.duplication.baselinePath` (default
+ * `baselines/duplication.json`), or the path supplied via `--baseline <path>`.
+ * Output is a deterministic, kernel-stamped envelope produced by the shared
+ * writer — every row path is canonicalised, the per-kind rollup math runs,
+ * and the envelope is schema-validated before persisting.
+ *
+ * Mirrors `update-crap-baseline.js`: thin CLI shell + shared writer funnel.
+ * The duplication scan delegates to jscpd's `detectClones` (a pure clone
+ * detector with no test coupling), wrapped by `scanDuplication` so the
+ * parse→envelope path is unit-testable with the scanner mocked.
+ *
+ * Exits non-zero only when the scanner itself crashes. An empty result (no
+ * detected clones) still writes an envelope with `rows: []` so downstream
+ * `check-baselines` can tell "intentional empty baseline" apart from "no
+ * baseline yet".
+ */
+
+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 here so
+ * the rest of the module stays import-pure and testable.
+ *
+ * @returns {(opts: object) => Promise<Array<object>>}
+ */
+function resolveDetectClones() {
+  const jscpd = require('jscpd');
+  if (typeof jscpd.detectClones !== 'function') {
+    throw new Error(
+      "[Duplication] jscpd.detectClones is not available — run 'npm install'",
+    );
+  }
+  return jscpd.detectClones;
+}
+
+function parseCliArgs(argv = process.argv.slice(2)) {
+  const out = { baselinePath: undefined };
+  for (let i = 0; i < argv.length; i += 1) {
+    if (argv[i] === '--baseline' && argv[i + 1]) {
+      out.baselinePath = argv[i + 1];
+      i += 1;
+    }
+  }
+  return out;
+}
+
+/**
+ * Resolve the duplication gate block from the merged quality config. The
+ * flattened legacy bag does not expose a `duplication` accessor (the kind
+ * post-dates the bag), so read it off the resolved `gates` map directly.
+ *
+ * @param {object} config resolved config
+ * @returns {object} the duplication gate block (possibly empty)
+ */
+function resolveDuplicationGate(config) {
+  const gates = getQuality(config).gates ?? {};
+  return gates.duplication ?? {};
+}
+
+async function main() {
+  const args = parseCliArgs();
+  const config = resolveConfig();
+  const gate = resolveDuplicationGate(config);
+  const targetDirs = Array.isArray(gate.targetDirs) ? gate.targetDirs : [];
+  const ignoreGlobs = Array.isArray(gate.ignoreGlobs) ? gate.ignoreGlobs : [];
+  const baselinePath =
+    args.baselinePath ?? gate.baselinePath ?? 'baselines/duplication.json';
+
+  Logger.info('[Duplication] Updating baseline...');
+  Logger.info(`[Duplication] Target dirs: ${targetDirs.join(', ')}`);
+
+  const rows = await scanDuplication({
+    targetDirs,
+    cwd: process.cwd(),
+    ignoreGlobs,
+    detect: resolveDetectClones(),
+  });
+
+  const absBaselinePath = path.isAbsolute(baselinePath)
+    ? baselinePath
+    : path.resolve(process.cwd(), baselinePath);
+
+  // Route through the shared writer: canonicalise paths, run the per-kind
+  // rollup, stamp `$schema` / `kernelVersion` / `generatedAt`, and validate
+  // against the duplication schema before persisting. Epsilon is applied by
+  // default so unchanged code with stale env produces a zero-row diff.
+  const scopeArgs = buildWriterScopeArgs({
+    kind: 'duplication',
+    absBaselinePath,
+    epsilon: getBaselineEpsilon('duplication', config),
+    logger: Logger,
+    logTag: '[Duplication]',
+  });
+  const envelope = write({
+    kind: 'duplication',
+    rows,
+    ...scopeArgs,
+  });
+  writeFile(absBaselinePath, envelope);
+
+  Logger.info(
+    `[Duplication] Scanned ${rows.length} file(s) with detected duplication; wrote ${envelope.rows.length} row(s).`,
+  );
+  Logger.info(
+    `[Duplication] ✅ Baseline updated (kernelVersion=${envelope.kernelVersion}). Wrote to ${absBaselinePath}.`,
+  );
+}
+
+// cli-opt-out: top-level main().catch predates runAsCli; never imported elsewhere so the auto-run risk is moot.
+main().catch((err) => {
+  Logger.error(
+    `[Duplication] ❌ Fatal error: ${err?.stack ?? err?.message ?? err}`,
+  );
+  process.exit(1);
+});

package/.agents/scripts/update-maintainability-baseline.js

@@ -0,0 +1,183 @@
+/**
+ * update-maintainability-baseline.js — manual refresh CLI for the
+ * maintainability baseline.
+ *
+ * Story #2202 / Task #2215 (Epic #2173): this CLI is now a thin wrapper
+ * around `refreshBaseline({ kind: 'maintainability' })` from
+ * `.agents/scripts/lib/baselines/refresh-service.js`. All scoring, scope
+ * resolution, envelope assembly, and persistence flows through the unified
+ * service.
+ *
+ * Surface:
+ *
+ *   - `--diff-scope <ref>` (or `--diff-scope=<ref>`): explicitly scope the
+ *     refresh to files changed between `<ref>` and HEAD. Out-of-scope rows
+ *     are preserved byte-for-byte from the prior on-disk baseline.
+ *   - With no flag: scope is derived from `git diff --name-only
+ *     origin/main..HEAD` (the service's default `baseRef..headRef`).
+ *     Operators wanting a full rewrite must pass `--full-scope` (added by
+ *     Task #2214; see that Task's notes for the cut-over).
+ *
+ * The scoring step (escomplex / typhonjs maintainability index) is
+ * injected as a scorer function via the service's `opts.scorer` seam.
+ * Full-scope refreshes (`scope.mode === 'full'`) walk every configured
+ * target directory; diff/explicit refreshes score only the files the
+ * service hands in. This keeps the manual CLI byte-identical (per
+ * AC-3 — see Task #2212's byte-identity test) to whatever code path
+ * story-close would have produced for the same scope.
+ */
+
+// Fail-fast if the framework's runtime deps are not installed — must be the
+// first import so the check runs before any third-party-importing sibling
+// module is evaluated (Story #3432).
+import './lib/runtime-deps/ensure-installed.js';
+import path from 'node:path';
+import { parseDiffScopeFlag } from './lib/baselines/diff-scope-cli.js';
+import { filterExcludedRows } from './lib/baselines/kinds/maintainability.js';
+import { refreshBaseline } from './lib/baselines/refresh-service.js';
+import { getBaselineEpsilon } from './lib/config/quality.js';
+import {
+  getBaselines,
+  getQuality,
+  resolveConfig,
+} from './lib/config-resolver.js';
+import { Logger } from './lib/Logger.js';
+import { calculateAll, scanDirectory } from './lib/maintainability-utils.js';
+
+/**
+ * Parse `--full-scope` (boolean opt-out flag).
+ *
+ * @param {string[]} argv
+ * @returns {boolean}
+ */
+function parseFullScopeFlag(argv = []) {
+  return argv.includes('--full-scope');
+}
+
+/**
+ * Build the per-kind scorer the service will invoke. The scorer receives
+ * `(files, { fullScope })`:
+ *
+ *   - `fullScope === true`: ignore `files`, walk every configured target
+ *     directory, score every supported source file, return rows.
+ *   - `fullScope === false`: `files` is the resolved (diff or explicit)
+ *     scope. Score only those that fall under a configured target
+ *     directory; rows outside that set are dropped (the service / writer
+ *     preserves their prior-on-disk entries verbatim).
+ *
+ * The scorer is `cwd`-aware: the service passes its `cwd` through so all
+ * path normalisation stays consistent with diff-scope derivation.
+ */
+function buildMaintainabilityScorer({ targetDirs, ignoreGlobs = [], logger }) {
+  return async function maintainabilityScorer(files, opts) {
+    const cwd = opts?.cwd ?? process.cwd();
+    let absPaths;
+    if (opts?.fullScope) {
+      absPaths = [];
+      for (const dir of targetDirs) {
+        const abs = path.isAbsolute(dir) ? dir : path.resolve(cwd, dir);
+        logger.info(`[Maintainability] Scanning ${dir}...`);
+        scanDirectory(abs, absPaths, { cwd, ignoreGlobs });
+      }
+    } else {
+      // Files come in as canonical POSIX repo-relative paths from the
+      // service. Resolve to absolute paths for the scorer, but only keep
+      // the ones that fall under a configured target dir — rows outside
+      // those roots are the gate's responsibility, not the baseline's.
+      const targetAbsDirs = targetDirs.map((dir) =>
+        path.isAbsolute(dir) ? dir : path.resolve(cwd, dir),
+      );
+      absPaths = [];
+      for (const rel of files ?? []) {
+        const abs = path.resolve(cwd, rel);
+        const underTarget = targetAbsDirs.some(
+          (root) => abs === root || abs.startsWith(`${root}${path.sep}`),
+        );
+        if (underTarget) absPaths.push(abs);
+      }
+    }
+
+    logger.info(
+      `[Maintainability] Calculating scores for ${absPaths.length} files...`,
+    );
+    const scores = await calculateAll(absPaths);
+    const rows = Object.entries(scores).map(([p, mi]) => ({ path: p, mi }));
+    // Story #2467 / Task #2494: drop files the escomplex kernel can't parse
+    // so they stop landing as `mi: 0` phantom entries in the baseline.
+    return filterExcludedRows(rows);
+  };
+}
+
+async function main() {
+  const argv = process.argv.slice(2);
+  const diffScopeRef = parseDiffScopeFlag(argv);
+  const fullScope = parseFullScopeFlag(argv);
+
+  if (fullScope && diffScopeRef !== null) {
+    throw new Error(
+      '[Maintainability] --full-scope is incompatible with --diff-scope; pick one',
+    );
+  }
+
+  const config = resolveConfig();
+  const miQuality = getQuality(config).maintainability;
+  const targetDirs = miQuality.targetDirs;
+  const ignoreGlobs = miQuality.ignoreGlobs ?? [];
+  const baselinePath = getBaselines(config).maintainability.path;
+  const absBaselinePath = path.isAbsolute(baselinePath)
+    ? baselinePath
+    : path.resolve(process.cwd(), baselinePath);
+  const epsilon = getBaselineEpsilon('maintainability', config);
+
+  Logger.info('[Maintainability] Updating baseline...');
+  if (fullScope) {
+    Logger.info(
+      '[Maintainability] --full-scope: regenerating every row (out-of-scope merge disabled).',
+    );
+  } else if (diffScopeRef) {
+    Logger.info(
+      `[Maintainability] --diff-scope ${diffScopeRef}: narrowing to changed files; out-of-scope rows preserved verbatim.`,
+    );
+  }
+
+  const scorer = buildMaintainabilityScorer({
+    targetDirs,
+    ignoreGlobs,
+    logger: Logger,
+  });
+
+  // Task #2214 (Epic #2173, AC-2): flag-omission now defaults to
+  // diff-scope. The pre-migration default was a full regenerate; operators
+  // wanting that behaviour must now pass `--full-scope` explicitly. This is
+  // a deliberate breaking CLI behaviour change — see docs/CHANGELOG.md.
+  const refreshOpts = {
+    kind: 'maintainability',
+    writePath: absBaselinePath,
+    epsilon,
+    scorer,
+  };
+  if (fullScope) {
+    refreshOpts.fullScope = true;
+  } else if (diffScopeRef) {
+    // The CLI's documented `--diff-scope <ref>` semantics are
+    // `<ref>...HEAD` (three-dot). The service derives via two-dot
+    // `baseRef..headRef`; pass the ref as `baseRef` so the service's
+    // diff-derivation does the heavy lifting through the same execFile
+    // seam that auto-refresh uses.
+    refreshOpts.baseRef = diffScopeRef;
+  }
+  // No flag → scopeFiles=null + fullScope=false → service derives the
+  // diff via `origin/main..HEAD` (its default baseRef/headRef).
+
+  const result = await refreshBaseline(refreshOpts);
+
+  Logger.info(
+    `[Maintainability] ✅ Baseline updated successfully at ${absBaselinePath} (kernelVersion=${result.envelope.kernelVersion}, wrote=${result.wrote}, scope=${result.scope.mode}).`,
+  );
+}
+
+// cli-opt-out: top-level main().catch predates runAsCli; never imported elsewhere so the auto-run risk is moot.
+main().catch((err) => {
+  Logger.error(`[Maintainability] ❌ Fatal error: ${err.message}`);
+  process.exit(1);
+});