@ticket-gate/engine 0.0.0 → 0.1.0-rc.1

package/score/cli.mjs

@@ -0,0 +1,182 @@
+// The command line of the mutation score gate.
+//
+//   <score command> --base=<ref> [--root=<dir>]
+//        [--report=<path> --base-report=<path>] [--files=<p,...>]
+//
+// Exit 0: pass (or nothing to mutate). 1: a file failed the rule. 2: the
+// mutation tool, the report, the worktree or the install failed.
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+
+import { GateError, baseWorktree, git, gitOk, readReport } from './base.mjs';
+import { baseToHeadLines, parseChangedLines } from './lines.mjs';
+import {
+  judge,
+  needsForcedRerun,
+  regressedMutants,
+  scoreFile,
+  summaryLine,
+  warnings,
+} from './judge.mjs';
+import { renderSurvivors, reportFiles } from './survivors.mjs';
+import { mutationTargets } from './targets.mjs';
+
+/** Runs the gate; returns the exit code. `cfg` is the project config, `root` the default repo root. */
+export function runScore(argv, cfg, root0) {
+  const opt = (name) =>
+    argv.find((a) => a.startsWith(`--${name}=`))?.slice(name.length + 3);
+  const root = resolve(opt('root') ?? root0);
+  const baseArg = opt('base');
+  const adapter = cfg.adapter;
+  if (!baseArg) {
+    console.error(
+      `mutation: FAIL --base=<ref> is required. Run: ${cfg.commands.score} --base=<BASE sha>`,
+    );
+    return 2;
+  }
+  try {
+    const sha = git(root, [
+      'rev-parse',
+      '--verify',
+      `${baseArg}^{commit}`,
+    ]).trim();
+    const sha7 = sha.slice(0, 7);
+    const paths = opt('files')
+      ? opt('files').split(',')
+      : [
+          ...git(root, ['diff', '--name-only', '--no-renames', sha]).split(
+            '\n',
+          ),
+          ...git(root, ['ls-files', '--others', '--exclude-standard']).split(
+            '\n',
+          ),
+        ].filter(Boolean);
+    const targets = mutationTargets(
+      paths,
+      (p) => existsSync(join(root, p)),
+      cfg,
+    );
+    if (!targets.length) {
+      console.log(`mutation: ${cfg.noTargets} vs ${sha7}`);
+      return 0;
+    }
+
+    let bad = 0;
+    for (const t of targets)
+      for (const d of adapter.disablesWithoutReason(
+        readFileSync(join(root, t), 'utf8'),
+      )) {
+        console.log(
+          `mutation: FAIL ${t}:${d.line}: Stryker disable without a reason`,
+        );
+        bad++;
+      }
+
+    const isNew = Object.fromEntries(
+      targets.map((t) => [t, !gitOk(root, ['cat-file', '-e', `${sha}:${t}`])]),
+    );
+    const existing = targets.filter((t) => !isNew[t]);
+
+    // `force`: the confirming run, which ignores the incremental file and re-tests every mutant.
+    const reportPath = opt('report') ?? join(root, adapter.reportPath);
+    const branchReport = (force) => {
+      if (!opt('report')) adapter.runBranch({ root, files: targets, force });
+      return readReport(reportPath, 'branch');
+    };
+    const baseReportOf = (force) => {
+      if (opt('base-report')) return readReport(opt('base-report'), 'base');
+      if (!existing.length) return null;
+      const dir = baseWorktree(root, sha, cfg);
+      const out = adapter.runBase({ root, dir, files: existing, force });
+      return readReport(out, 'base');
+    };
+
+    const diffOf = (path) =>
+      git(root, ['diff', '-U0', '--no-renames', '--no-color', sha, '--', path]);
+    const verdictsOf = (report, baseReport) => {
+      const branchFiles = reportFiles(report, cfg.packageDir);
+      const baseFiles = reportFiles(baseReport, cfg.packageDir);
+      return targets.map((path) => {
+        const mutants = branchFiles[path]?.mutants ?? [];
+        const s = scoreFile(mutants);
+        const baseScore = baseFiles[path]
+          ? scoreFile(baseFiles[path].mutants).score
+          : 100;
+        const diff = isNew[path] ? null : diffOf(path);
+        const changed = diff === null ? null : parseChangedLines(diff);
+        const onChanged = (status) =>
+          mutants.filter(
+            (m) =>
+              m.status === status &&
+              (changed === null || changed.has(m.location.start.line)),
+          ).length;
+        const v = {
+          path,
+          isNew: isNew[path],
+          score: s.score,
+          baseScore,
+          changed,
+          noCoverageOnChanged: onChanged('NoCoverage'),
+          survivedOnChanged: onChanged('Survived'),
+          survivorsOnChanged: onChanged('Survived') + onChanged('NoCoverage'),
+          regressed:
+            diff === null
+              ? []
+              : regressedMutants(
+                  baseFiles[path]?.mutants ?? [],
+                  mutants,
+                  baseToHeadLines(diff),
+                ),
+        };
+        return { ...v, reasons: judge(v, cfg), warnings: warnings(v) };
+      });
+    };
+
+    let report = branchReport(false);
+    let verdicts = verdictsOf(report, baseReportOf(false));
+    // A regressed mutant can be a stale incremental result (a static mutant credited
+    // to whichever test imported the module): confirm it on fresh runs before failing.
+    if (needsForcedRerun(verdicts, !opt('report'))) {
+      const n = verdicts.reduce((a, v) => a + v.regressed.length, 0);
+      console.log(
+        `mutation: ${n} mutant(s) killed on base survive on unchanged lines; confirming with --force (no incremental cache)`,
+      );
+      report = branchReport(true);
+      verdicts = verdictsOf(report, baseReportOf(true));
+    }
+
+    for (const v of verdicts)
+      for (const r of v.reasons) {
+        console.log(`mutation: FAIL ${v.path}: ${r}`);
+        bad++;
+      }
+
+    const newDisables = targets.flatMap((t) =>
+      adapter.addedDisables(root, sha, t, isNew[t]),
+    );
+    const md = renderSurvivors({
+      base: sha,
+      verdicts,
+      report,
+      newDisables,
+      packageDir: cfg.packageDir,
+    });
+    const survivorsFile = join(root, cfg.survivors);
+    mkdirSync(dirname(survivorsFile), { recursive: true });
+    writeFileSync(survivorsFile, md);
+    process.stdout.write(md);
+    if (bad)
+      console.log(
+        `mutation: survivors are in ${cfg.survivors}; ${cfg.handoff}, then rerun: ${cfg.commands.score} --base=${sha7}`,
+      );
+    console.log(summaryLine(verdicts));
+    return bad ? 1 : 0;
+  } catch (e) {
+    if (e instanceof GateError) {
+      console.log(e.message);
+      return 2;
+    }
+    console.log(`mutation: FAIL ${e.stderr ?? e.message}`);
+    return 2;
+  }
+}

package/score/judge.mjs

@@ -0,0 +1,107 @@
+// Scores and verdicts of the mutation score gate. Pure: the rule thresholds
+// arrive in `cfg`.
+
+const KILLED = new Set(['Killed', 'Timeout']);
+const OPEN = new Set(['Survived', 'NoCoverage']);
+
+/**
+ * Head mutants on unchanged lines that the base killed and the branch does not: a
+ * test was removed or weakened. A mutant is matched by its location (mapped from
+ * base to head), mutator and replacement; counts are compared per key, so a key the
+ * base already left open is not a regression. A changed line never matches: `toHead`
+ * maps untouched base lines only onto untouched head lines.
+ */
+export function regressedMutants(baseMutants, headMutants, toHead) {
+  const keyOf = (m, start, end) =>
+    `${start}:${m.location.start.column}-${end}:${m.location.end.column}/${m.mutatorName}/${m.replacement}`;
+  const base = new Map();
+  for (const m of baseMutants) {
+    const start = toHead(m.location.start.line);
+    const end = toHead(m.location.end.line);
+    if (start === null || end === null) continue;
+    const k = keyOf(m, start, end);
+    const c = base.get(k) ?? { killed: 0, open: 0 };
+    if (KILLED.has(m.status)) c.killed++;
+    else if (OPEN.has(m.status)) c.open++;
+    base.set(k, c);
+  }
+  const headOpen = new Map();
+  for (const m of headMutants) {
+    if (!OPEN.has(m.status)) continue;
+    const k = keyOf(m, m.location.start.line, m.location.end.line);
+    headOpen.set(k, [...(headOpen.get(k) ?? []), m]);
+  }
+  const out = [];
+  for (const [k, list] of headOpen) {
+    const c = base.get(k);
+    if (!c) continue;
+    const n = Math.min(c.killed, Math.max(0, list.length - c.open));
+    out.push(...list.slice(0, n));
+  }
+  return out;
+}
+
+/** Killed + Timeout over Killed + Timeout + Survived + NoCoverage. */
+export function scoreFile(mutants) {
+  const c = { Killed: 0, Timeout: 0, Survived: 0, NoCoverage: 0 };
+  for (const m of mutants) if (m.status in c) c[m.status]++;
+  const killed = c.Killed + c.Timeout;
+  const valid = killed + c.Survived + c.NoCoverage;
+  const score = valid === 0 ? 100 : Math.round((10000 * killed) / valid) / 100;
+  return {
+    killed,
+    survived: c.Survived,
+    noCoverage: c.NoCoverage,
+    valid,
+    score,
+  };
+}
+
+/** Failure reasons for one file; empty means pass. `cfg.newFileMin` is the floor for a new file. */
+export function judge(v, cfg) {
+  const reasons = [];
+  if (v.isNew && v.score < cfg.newFileMin)
+    reasons.push(`new file score ${v.score.toFixed(2)} < ${cfg.newFileMin}`);
+  // An existing file fails only on a mutant that survives on a line this branch
+  // changed. A whole-file score below base is a warning (see `warnings`): it can
+  // come from lines nobody touched, and the nightly rotation re-checks them.
+  if (!v.isNew && (v.survivedOnChanged ?? 0) > 0)
+    reasons.push(`${v.survivedOnChanged} surviving mutant(s) on changed lines`);
+  if (!v.isNew && v.noCoverageOnChanged > 0)
+    reasons.push(
+      `${v.noCoverageOnChanged} no-coverage mutant(s) on changed lines`,
+    );
+  if (!v.isNew && (v.regressed?.length ?? 0) > 0)
+    reasons.push(
+      `${v.regressed.length} mutant(s) killed on base now survive on unchanged lines (a test was removed or weakened)`,
+    );
+  return reasons;
+}
+
+/**
+ * Non-failing notes for one file: the whole-file score fell below base with no
+ * regressed mutant (a killed base mutant on a line the branch removed, say).
+ */
+export function warnings(v) {
+  const out = [];
+  if (!v.isNew && v.score < v.baseScore && !(v.regressed?.length ?? 0))
+    out.push(
+      `score ${v.score.toFixed(2)} dropped below base ${v.baseScore} (whole file; not a failure, no mutant killed on base survives)`,
+    );
+  return out;
+}
+
+/** True when a regressed mutant should be confirmed by a run without the incremental cache. */
+export function needsForcedRerun(verdicts, ranStryker) {
+  return ranStryker && verdicts.some((v) => (v.regressed?.length ?? 0) > 0);
+}
+
+export function summaryLine(verdicts) {
+  const scores = verdicts.map((v) => v.score);
+  const min = scores.length ? Math.min(...scores) : 100;
+  const max = scores.length ? Math.max(...scores) : 100;
+  const n = verdicts.reduce((a, v) => a + v.survivorsOnChanged, 0);
+  const g = verdicts.reduce((a, v) => a + (v.regressed?.length ?? 0), 0);
+  const w = verdicts.reduce((a, v) => a + (v.warnings?.length ?? 0), 0);
+  return `mutation: ${verdicts.length} files, score ${min.toFixed(1)}..${max.toFixed(1)}, ${n} survivors on changed lines${g ? `, ${g} regressed on unchanged lines` : ''}${w ? `, ${w} warning(s): whole-file score below base` : ''}`;
+}

package/score/lines.mjs

@@ -0,0 +1,40 @@
+// Line arithmetic over a `git diff -U0` text. Pure.
+
+/** New-side line numbers of a `git diff -U0` text. */
+export function parseChangedLines(diffU0) {
+  const lines = new Set();
+  for (const m of diffU0.matchAll(
+    /^@@ -\d+(?:,\d+)? \+(\d+)(?:,(\d+))? @@/gm,
+  )) {
+    const start = Number(m[1]);
+    const count = m[2] === undefined ? 1 : Number(m[2]);
+    for (let i = 0; i < count; i++) lines.add(start + i);
+  }
+  return lines;
+}
+
+/**
+ * Base line -> head line for the lines a `git diff -U0` left untouched; null for a
+ * base line the diff removed or rewrote.
+ */
+export function baseToHeadLines(diffU0) {
+  const hunks = [];
+  for (const m of diffU0.matchAll(
+    /^@@ -(\d+)(?:,(\d+))? \+(\d+)(?:,(\d+))? @@/gm,
+  ))
+    hunks.push({
+      oldStart: Number(m[1]),
+      oldCount: m[2] === undefined ? 1 : Number(m[2]),
+      newCount: m[4] === undefined ? 1 : Number(m[4]),
+    });
+  return (line) => {
+    let delta = 0;
+    for (const h of hunks) {
+      // `-a,0` inserts after base line a; `-a,b` rewrites base lines a..a+b-1.
+      const last = h.oldCount === 0 ? h.oldStart : h.oldStart + h.oldCount - 1;
+      if (h.oldCount > 0 && line >= h.oldStart && line <= last) return null;
+      if (line > last) delta += h.newCount - h.oldCount;
+    }
+    return line + delta;
+  };
+}

package/score/schema.mjs

@@ -0,0 +1,68 @@
+// Shape check of a mutation-testing-report-schema report (majors 1 and 2).
+// Only the fields the score rules read are checked; the first problem wins.
+export const SCHEMA_VERSION = /^[12](?:\.(?:0|[1-9]\d*)){0,2}$/;
+
+export const STATUSES = new Set([
+  'Killed',
+  'Survived',
+  'NoCoverage',
+  'CompileError',
+  'RuntimeError',
+  'Timeout',
+  'Ignored',
+  'Pending',
+]);
+
+const isLine = (n) => Number.isInteger(n) && n >= 1;
+const isObject = (v) =>
+  typeof v === 'object' && v !== null && !Array.isArray(v);
+const isStringArray = (v) =>
+  Array.isArray(v) && v.every((s) => typeof s === 'string');
+
+function mutantProblem(m) {
+  if (!STATUSES.has(m?.status))
+    return `status ${JSON.stringify(m?.status)} is not a schema status`;
+  if (typeof m.mutatorName !== 'string') return 'mutatorName is not a string';
+  if (m.replacement !== undefined && typeof m.replacement !== 'string')
+    return 'replacement is not a string';
+  for (const end of ['start', 'end'])
+    for (const axis of ['line', 'column'])
+      if (!isLine(m.location?.[end]?.[axis]))
+        return `location.${end}.${axis} is not a positive integer`;
+  if (m.coveredBy !== undefined && !isStringArray(m.coveredBy))
+    return 'coveredBy is not an array of strings';
+  return null;
+}
+
+/** The first way `report` departs from the schema, or null. */
+export function schemaProblem(report) {
+  if (!isObject(report)) return 'is not a JSON object';
+  if (
+    typeof report.schemaVersion !== 'string' ||
+    !SCHEMA_VERSION.test(report.schemaVersion)
+  )
+    return `schemaVersion ${JSON.stringify(report.schemaVersion)} is not a supported mutation-testing-report-schema version (1.x or 2.x)`;
+  if (!isObject(report.files)) return 'files is missing';
+  for (const [path, file] of Object.entries(report.files)) {
+    const where = `files[${JSON.stringify(path)}]`;
+    if (!Array.isArray(file?.mutants))
+      return `${where}.mutants is not an array`;
+    for (const [i, m] of file.mutants.entries()) {
+      const p = mutantProblem(m);
+      if (p) return `${where}.mutants[${i}]: ${p}`;
+    }
+  }
+  if (report.testFiles !== undefined) {
+    if (!isObject(report.testFiles)) return 'testFiles is not an object';
+    for (const [path, tf] of Object.entries(report.testFiles)) {
+      const ok =
+        Array.isArray(tf?.tests) &&
+        tf.tests.every(
+          (t) => typeof t?.id === 'string' && typeof t?.name === 'string',
+        );
+      if (!ok)
+        return `testFiles[${JSON.stringify(path)}].tests is not an array of { id, name }`;
+    }
+  }
+  return null;
+}

package/score/survivors.mjs

@@ -0,0 +1,103 @@
+// The survivors Markdown of the mutation score gate. Pure: the package directory
+// the report keys are relative to arrives as `packageDir`.
+import { isAbsolute } from 'node:path';
+
+import { summaryLine } from './judge.mjs';
+
+/** Report keys are relative to `packageDir` or absolute; make them repo paths. */
+export function repoKey(key, packageDir) {
+  if (packageDir === '.') return key;
+  if (isAbsolute(key)) {
+    const i = key.indexOf(`${packageDir}/`);
+    return i === -1 ? key : key.slice(i);
+  }
+  return key.startsWith(`${packageDir}/`) ? key : `${packageDir}/${key}`;
+}
+
+/** Report files by repo path. */
+export function reportFiles(report, packageDir) {
+  const out = {};
+  for (const [k, f] of Object.entries(report?.files ?? {}))
+    out[repoKey(k, packageDir)] = f;
+  return out;
+}
+
+function slice(source, loc) {
+  const lines = source.split('\n');
+  const first = lines[loc.start.line - 1] ?? '';
+  if (loc.end.line === loc.start.line)
+    return first.slice(loc.start.column - 1, loc.end.column - 1);
+  return `${first.slice(loc.start.column - 1)} ...`;
+}
+
+/**
+ * The Markdown of the survivors file. `verdicts` carry `path`,
+ * `isNew`, `score`, `baseScore`, `reasons`, `changed` (Set of lines, or null
+ * for every line); `report` is the branch Stryker report; `sources` optionally
+ * overrides a file's source text by repo path; `newDisables` is
+ * `[{ path, line, text }]`.
+ */
+export function renderSurvivors({
+  base,
+  verdicts,
+  report,
+  sources = {},
+  newDisables = [],
+  packageDir,
+}) {
+  const files = reportFiles(report, packageDir);
+  const names = new Map();
+  for (const [file, t] of Object.entries(report?.testFiles ?? {}))
+    for (const test of t.tests ?? [])
+      names.set(test.id, `${file} > ${test.name}`);
+
+  const out = [`# Mutation survivors (base ${base.slice(0, 7)})`, ''];
+  out.push(summaryLine(verdicts));
+  for (const v of verdicts)
+    for (const r of v.reasons) out.push(`mutation: FAIL ${v.path}: ${r}`);
+  for (const v of verdicts)
+    for (const w of v.warnings ?? [])
+      out.push(`mutation: WARN ${v.path}: ${w}`);
+  for (const v of verdicts) {
+    out.push(
+      '',
+      `## ${v.path}  score ${v.score} (${v.isNew ? 'new' : `base ${v.baseScore}`})`,
+      '',
+    );
+    const file = files[v.path];
+    const source = sources[v.path] ?? file?.source ?? '';
+    const open = (file?.mutants ?? [])
+      .filter((m) => m.status === 'Survived' || m.status === 'NoCoverage')
+      .sort(
+        (a, b) =>
+          a.location.start.line - b.location.start.line ||
+          a.location.start.column - b.location.start.column,
+      );
+    if (!open.length) out.push('- none');
+    const regressed = new Set(v.regressed ?? []);
+    for (const m of open) {
+      const { line, column } = m.location.start;
+      const changed = v.changed === null || v.changed?.has(line);
+      const tag = changed
+        ? ' [changed]'
+        : regressed.has(m)
+          ? ' [regressed]'
+          : '';
+      const tests = (m.coveredBy ?? [])
+        .map((id) => names.get(id))
+        .filter(Boolean);
+      const base_ = v.path.split('/').pop();
+      out.push(
+        `- \`${base_}:${line}:${column}/${m.mutatorName}\` ${m.status}${tag}`,
+        `  - original: \`${slice(source, m.location)}\``,
+        `  - mutated: \`${m.replacement}\``,
+        `  - covered by: ${tests.length ? tests.map((t) => `\`${t}\``).join('; ') : 'none (no coverage)'}`,
+      );
+    }
+  }
+  out.push('', '## New disable comments', '');
+  if (!newDisables.length) out.push('- none');
+  for (const d of newDisables)
+    out.push(`- \`${d.path}:${d.line}\` ${d.text.trim()}`);
+  return `${out.join('\n')}\n`;
+}

package/score/targets.mjs

@@ -0,0 +1,34 @@
+// Which changed paths the score gate mutates. Pure: the project's scope, extra
+// and excluded patterns arrive in `cfg`.
+
+/**
+ * The module a test file stands for: `foo.test.ts` or `foo.<case>.test.ts` -> the
+ * longest existing `foo[.<case>].ts` beside it; null for anything else.
+ */
+export function testedModule(path, exists) {
+  const m = /^(.*\/)([^/]+?)\.test\.ts$/.exec(path);
+  if (!m) return null;
+  const parts = m[2].split('.');
+  for (let n = parts.length; n >= 1; n--) {
+    const p = `${m[1]}${parts.slice(0, n).join('.')}.ts`;
+    if (exists(p)) return p;
+  }
+  return null;
+}
+
+/**
+ * Changed paths that the gate mutates, sorted; deleted files drop out. A changed
+ * (or deleted) test file selects the module beside it, so a weakened test is judged
+ * by the regressed-mutant rule even when the module itself did not change.
+ * `cfg` carries `scope` (RegExp), `extra` (paths) and `excluded` (RegExp).
+ */
+export function mutationTargets(paths, exists, cfg) {
+  return [...new Set(paths)]
+    .map((p) => testedModule(p, exists) ?? p)
+    .filter((p) => p.endsWith('.ts'))
+    .filter((p) => cfg.scope.test(p) || cfg.extra.includes(p))
+    .filter((p) => !cfg.excluded.test(p))
+    .filter((p) => exists(p))
+    .filter((p, i, all) => all.indexOf(p) === i)
+    .sort();
+}

package/score-config.mjs

@@ -0,0 +1,120 @@
+// The `score` key of gate.config.mjs: the project values the mutation score gate (./score) reads.
+// Validated at load time; a bad value throws Error('gate.config: score.<key>: <what>').
+
+export const SCORE_KEYS = Object.freeze([
+  'scope',
+  'extra',
+  'excluded',
+  'newFileMin',
+  'packageDir',
+  'adapter',
+  'baseInstall',
+  'survivors',
+  'worktreeDir',
+  'handoff',
+  'commands',
+  'noTargets',
+]);
+
+/** The minimum score of a file that is new on the branch, unless `score.newFileMin` says otherwise. */
+export const NEW_FILE_MIN = 80;
+
+export const SCORE_DEFAULTS = Object.freeze({
+  extra: [],
+  excluded: /(?!)/,
+  newFileMin: NEW_FILE_MIN,
+  survivors: '.turbo/mutation-survivors.md',
+  worktreeDir: 'ticket-gate-score-base',
+  handoff: 'add or fix the tests that should kill them',
+  commands: { score: 'ticket-gate score' },
+  noTargets: 'no file in the score scope changed',
+});
+
+const isObject = (v) => v && typeof v === 'object' && !Array.isArray(v);
+const isStr = (v) => typeof v === 'string' && v !== '';
+const isLine = (v) => isStr(v) && !/[\r\n]/.test(v);
+const isStrList = (v) => Array.isArray(v) && v.every((s) => typeof s === 'string');
+const segments = (p) => p.split(/[\\/]/);
+const isRel = (p) =>
+  isStr(p) &&
+  !p.startsWith('/') &&
+  !/^[A-Za-z]:/.test(p) &&
+  !segments(p).includes('..');
+const isSubDir = (p) =>
+  isRel(p) && p !== '.' && !segments(p).some((s) => s === '' || s === '.');
+const isOneSegment = (p) => isStr(p) && p !== '.' && p !== '..' && !/[\\/]/.test(p);
+
+/** Validates `score`; `fail(where, what)` throws. A key left out keeps its default (see `scoreOf`). */
+export function validateScore(score, fail) {
+  if (!isObject(score)) fail('score', 'must be an object');
+  for (const k of Object.keys(score)) {
+    if (!SCORE_KEYS.includes(k))
+      fail(`score.${k}`, `unknown key (known: ${SCORE_KEYS.join(', ')})`);
+  }
+  for (const k of ['scope', 'excluded']) {
+    if (k === 'excluded' && score[k] === undefined) continue;
+    const re = score[k];
+    if (!(re instanceof RegExp) || re.global || re.sticky)
+      fail(`score.${k}`, 'must be a RegExp without the g or y flag');
+  }
+  if (score.extra !== undefined && !isStrList(score.extra))
+    fail('score.extra', 'must be an array of repo paths');
+  const min = score.newFileMin;
+  if (min !== undefined && !(typeof min === 'number' && min >= 0 && min <= 100))
+    fail('score.newFileMin', 'must be a number from 0 to 100');
+  if (!isSubDir(score.packageDir) && score.packageDir !== '.')
+    fail(
+      'score.packageDir',
+      'must be a relative sub-directory of the repo, or "." for a package at the repo root',
+    );
+  const a = score.adapter;
+  if (
+    !isObject(a) ||
+    !isStr(a.name) ||
+    !isStr(a.reportPath) ||
+    !['runBranch', 'runBase', 'disablesWithoutReason', 'addedDisables'].every(
+      (f) => typeof a[f] === 'function',
+    )
+  )
+    fail(
+      'score.adapter',
+      'needs a string name, a string reportPath and the functions runBranch, runBase, disablesWithoutReason, addedDisables',
+    );
+  const b = score.baseInstall;
+  if (
+    !isObject(b) ||
+    !isStr(b.cmd) ||
+    !isStrList(b.args) ||
+    !isStr(b.label) ||
+    !isStr(b.hint) ||
+    !isOneSegment(b.marker)
+  )
+    fail(
+      'score.baseInstall',
+      'needs a string cmd, a string-array args, strings label and hint, and a marker that is one file name',
+    );
+  if (score.survivors !== undefined && !(isRel(score.survivors) && score.survivors !== '.'))
+    fail('score.survivors', 'must be a relative file path');
+  if (score.worktreeDir !== undefined && !isOneSegment(score.worktreeDir))
+    fail('score.worktreeDir', 'must be a single directory name');
+  for (const k of ['handoff', 'noTargets']) {
+    if (score[k] !== undefined && !isLine(score[k]))
+      fail(`score.${k}`, 'must be a non-empty single-line string');
+  }
+  const c = score.commands;
+  if (c !== undefined) {
+    if (!isObject(c)) fail('score.commands', 'must be { score: string }');
+    for (const k of Object.keys(c)) {
+      if (k !== 'score') fail(`score.commands.${k}`, 'unknown key (known: score)');
+    }
+    if (c.score !== undefined && !isLine(c.score))
+      fail('score.commands.score', 'must be a non-empty single-line command string');
+  }
+}
+
+/** The effective score config: defaults filled in, given values kept. */
+export const scoreOf = (score) => ({
+  ...SCORE_DEFAULTS,
+  ...score,
+  commands: { ...SCORE_DEFAULTS.commands, ...score.commands },
+});