@getarbiter/cli 0.5.0

package/dist/templates/scripts/verify-i18n-parity.mjs.ejs

@@ -0,0 +1,114 @@
+#!/usr/bin/env node
+// SPDX-License-Identifier: Apache-2.0
+// CATALOG: INV-106 enforcement — i18n locale key-parity gate (#1127).
+// Verifies that all i18n locale files have the same set of translation keys.
+// Bidirectional diff: missing in any locale is a failure.
+// Exit 1 if key sets diverge across locales.
+
+import { existsSync, readdirSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+const ROOT = process.cwd()
+const LOCALES_DIRS = [
+  join(ROOT, 'src', 'i18n', 'locales'),
+  join(ROOT, 'src', 'locales'),
+  join(ROOT, 'public', 'locales'),
+  join(ROOT, 'locales'),
+]
+
+function flattenKeys(obj, prefix = '') {
+  const keys = []
+  for (const [k, v] of Object.entries(obj)) {
+    const full = prefix ? `${prefix}.${k}` : k
+    if (typeof v === 'object' && v !== null && !Array.isArray(v)) {
+      keys.push(...flattenKeys(v, full))
+    } else {
+      keys.push(full)
+    }
+  }
+  return keys
+}
+
+function findLocalesDir() {
+  for (const dir of LOCALES_DIRS) {
+    if (existsSync(dir)) return dir
+  }
+  return null
+}
+
+const localesDir = findLocalesDir()
+
+if (!localesDir) {
+  // No locales directory — project may not use i18n yet; skip gracefully
+  process.stdout.write('[verify-i18n-parity] no locales directory found — skip (INV-106)\n')
+  process.exit(0)
+}
+
+let files
+try {
+  files = readdirSync(localesDir).filter((f) => f.endsWith('.json'))
+} catch (err) {
+  process.stderr.write(`[INV-106] cannot read locales directory: ${err.message}\n`)
+  process.exit(1)
+}
+
+if (files.length < 2) {
+  // Only one locale — nothing to compare
+  process.stdout.write(
+    `[verify-i18n-parity] only ${files.length} locale file(s) — skip parity check (INV-106)\n`,
+  )
+  process.exit(0)
+}
+
+const keysByLocale = {}
+for (const file of files) {
+  const locale = file.replace(/\.json$/, '')
+  try {
+    const content = JSON.parse(readFileSync(join(localesDir, file), 'utf-8'))
+    keysByLocale[locale] = new Set(flattenKeys(content))
+  } catch (err) {
+    process.stderr.write(`[INV-106] failed to parse ${file}: ${err.message}\n`)
+    process.exit(1)
+  }
+}
+
+const locales = Object.keys(keysByLocale)
+const referenceLocale = locales[0]
+const referenceKeys = keysByLocale[referenceLocale]
+let violations = 0
+
+for (const locale of locales.slice(1)) {
+  const targetKeys = keysByLocale[locale]
+
+  // Keys in reference but missing from target
+  const missingInTarget = [...referenceKeys].filter((k) => !targetKeys.has(k))
+  for (const key of missingInTarget) {
+    process.stderr.write(
+      `[INV-106] key missing in ${locale}: "${key}" (present in ${referenceLocale})\n`,
+    )
+    violations++
+  }
+
+  // Keys in target but missing from reference
+  const missingInReference = [...targetKeys].filter((k) => !referenceKeys.has(k))
+  for (const key of missingInReference) {
+    process.stderr.write(
+      `[INV-106] key missing in ${referenceLocale}: "${key}" (present in ${locale})\n`,
+    )
+    violations++
+  }
+}
+
+if (violations > 0) {
+  process.stderr.write(
+    `\n[verify-i18n-parity] ${violations} parity violation(s) found.\n` +
+      `  INV-106: All locale files must have identical key sets.\n` +
+      `  Reference locale: ${referenceLocale} (${referenceKeys.size} keys)\n` +
+      `  Locales checked: ${locales.join(', ')}\n`,
+  )
+  process.exit(1)
+}
+
+process.stdout.write(
+  `[verify-i18n-parity] i18n key parity OK — ${locales.length} locales, ${referenceKeys.size} keys (INV-106)\n`,
+)

package/dist/templates/scripts/verify-module-coverage.mjs.ejs

@@ -0,0 +1,207 @@
+#!/usr/bin/env node
+// SPDX-License-Identifier: Apache-2.0
+// <%= projectName %> — per-MODULE coverage non-regression ratchet (#1457, INV-134).
+//
+// ADVISORY (L2, start-warn): complements — does NOT duplicate — the FE per-layer
+// coverage ratchet (verify-fe-coverage.mjs, FSD layers, frontend-only) and the
+// total-coverage greenfield gate (lib/coverage-gate.mjs). This gate is per-FILE /
+// per-package, all-languages, upward-only with a ±SLACK pp tolerance: a module whose
+// coverage drops more than SLACK below module-coverage-baseline.json is a regression.
+//
+// Greenfield-aware: a module with zero executable lines contributes nothing (a virgin
+// or generated-only file must never false-fail). First run with coverage present and
+// no baseline seeds the baseline and exits 0. No coverage artifact at all → SKIP
+// (exit 0) — non-coverage repos and pre-coverage CI stages never false-fail.
+//
+// Per-language dispatch: TypeScript/JavaScript (Istanbul/Vitest coverage-summary.json)
+// is implemented robustly. Java (JaCoCo), Python (coverage.py), Rust (tarpaulin) and
+// Go (go cover) are scaffolded to SKIP gracefully when their summary is absent or the
+// format is unsupported — NEVER a false-fail.
+//
+// The ratchet compare is factored into a PURE, exported `compareModuleCoverage` so the
+// decision logic is unit-testable in isolation (see __tests__/generators/module-coverage-ratchet.test.ts).
+
+import { existsSync, readFileSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+export const SLACK = 0.5 // tolerated per-module regression, in percentage points
+const ROOT = process.cwd()
+const BASELINE_FILE = join(ROOT, 'module-coverage-baseline.json')
+
+/**
+ * Pure ratchet compare. Both maps are { moduleKey: linePct } where linePct is a
+ * number 0..100. Greenfield modules (0 executable lines) MUST be excluded by the
+ * caller before reaching here. Upward-only:
+ *   - a module in `baseline` whose `current` pct dropped more than `slack`  → violation
+ *   - a module in `baseline` absent from `current` (rename/deletion)        → violation
+ *   - a module in `current` but not in `baseline` (new code)                → ignored
+ *   - empty baseline (first run)                                            → no violations
+ *
+ * @param {Record<string, number>} baseline  module → baselined line pct
+ * @param {Record<string, number>} current   module → current line pct
+ * @param {number} slack                      tolerated drop in pp (default SLACK)
+ * @returns {{ violations: Array<{ module: string, reason: string }> }}
+ */
+export function compareModuleCoverage(baseline, current, slack = SLACK) {
+  const violations = []
+  for (const [module, base] of Object.entries(baseline ?? {})) {
+    if (typeof base !== 'number') continue
+    const cur = current?.[module]
+    if (cur === undefined) {
+      violations.push({
+        module,
+        reason: `present in baseline but absent from current coverage (rename/deletion?)`,
+      })
+      continue
+    }
+    if (cur + 1e-9 < base - slack) {
+      violations.push({
+        module,
+        reason: `coverage dropped: ${cur.toFixed(1)}% < ${base}% (slack: ${slack}pp)`,
+      })
+    }
+  }
+  return { violations }
+}
+
+// ─── Per-language extraction ────────────────────────────────────────────────
+// Each extractor returns either:
+//   - { modules: Record<string, number> }  on success (may be {} = greenfield)
+//   - null                                 when this language's summary is absent
+//                                          /unsupported → caller SKIPs (no false-fail)
+// A module is included only when it has > 0 executable lines (greenfield-aware).
+
+function extractTsCoverage() {
+  const file = join(ROOT, 'coverage', 'coverage-summary.json')
+  if (!existsSync(file)) return null
+  let summary
+  try {
+    summary = JSON.parse(readFileSync(file, 'utf-8'))
+  } catch (err) {
+    process.stderr.write(`[verify-module-coverage] failed to parse coverage-summary.json: ${err.message}\n`)
+    return null
+  }
+  if (summary == null || typeof summary !== 'object') return null
+  const modules = {}
+  for (const [filePath, stats] of Object.entries(summary)) {
+    if (filePath === 'total') continue
+    const lines = stats?.lines
+    if (lines == null || typeof lines !== 'object') continue
+    const total = typeof lines.total === 'number' ? lines.total : 0
+    if (total <= 0) continue // greenfield module — no executable lines, skip
+    const pct =
+      typeof lines.pct === 'number'
+        ? lines.pct
+        : (Number(lines.covered ?? 0) / total) * 100
+    modules[filePath] = Math.round(pct * 100) / 100
+  }
+  return { modules }
+}
+
+// Scaffolds — graceful SKIP until each is implemented. They intentionally return null
+// (summary absent / format unsupported) so the gate NEVER false-fails on these stacks.
+function extractJavaCoverage() {
+  // JaCoCo emits target/site/jacoco/jacoco.csv (per-class) or jacoco.xml.
+  // TODO(#1457): parse per-package coverage from jacoco.csv/xml. Skip until implemented.
+  return null
+}
+function extractPythonCoverage() {
+  // coverage.py emits coverage.json (`coverage json`) with per-file `summary.percent_covered`.
+  // TODO(#1457): parse per-file pct from coverage.json. Skip until implemented.
+  return null
+}
+function extractRustCoverage() {
+  // cargo-tarpaulin emits cobertura.xml (per-file line-rate).
+  // TODO(#1457): parse per-file line-rate from cobertura.xml. Skip until implemented.
+  return null
+}
+function extractGoCoverage() {
+  // `go test -coverprofile` emits coverage.out (per-file mode:set blocks).
+  // TODO(#1457): aggregate per-file pct from coverage.out. Skip until implemented.
+  return null
+}
+
+const LANGUAGE = '<%= language %>'
+
+function extractCoverage() {
+  switch (LANGUAGE) {
+    case 'typescript':
+    case 'javascript':
+      return extractTsCoverage()
+    case 'java':
+    case 'kotlin':
+      return extractJavaCoverage()
+    case 'python':
+      return extractPythonCoverage()
+    case 'rust':
+      return extractRustCoverage()
+    case 'go':
+      return extractGoCoverage()
+    default:
+      // Unknown language — try the TS path opportunistically, else SKIP.
+      return extractTsCoverage()
+  }
+}
+
+// ─── Main (skipped under test import — only runs when executed directly) ─────
+function main() {
+  const UPDATE_BASELINE = process.argv.includes('--update-baseline')
+
+  const extracted = extractCoverage()
+  if (extracted == null) {
+    process.stdout.write(
+      `[verify-module-coverage] SKIP — no coverage summary for "${LANGUAGE}" (run coverage first, or stack not yet supported)\n`,
+    )
+    return 0
+  }
+  const current = extracted.modules
+
+  if (UPDATE_BASELINE) {
+    writeFileSync(BASELINE_FILE, JSON.stringify(current, null, 2) + '\n')
+    process.stdout.write(
+      `[verify-module-coverage] baseline updated (${Object.keys(current).length} modules)\n`,
+    )
+    return 0
+  }
+
+  if (!existsSync(BASELINE_FILE)) {
+    // First run with coverage present and no baseline → seed it and pass.
+    writeFileSync(BASELINE_FILE, JSON.stringify(current, null, 2) + '\n')
+    process.stdout.write(
+      `[verify-module-coverage] seeded module-coverage-baseline.json (${Object.keys(current).length} modules) — re-run to ratchet\n`,
+    )
+    return 0
+  }
+
+  let baseline
+  try {
+    baseline = JSON.parse(readFileSync(BASELINE_FILE, 'utf-8'))
+  } catch (err) {
+    process.stderr.write(`[verify-module-coverage] failed to parse module-coverage-baseline.json: ${err.message}\n`)
+    return 1
+  }
+
+  const { violations } = compareModuleCoverage(baseline, current, SLACK)
+  if (violations.length > 0) {
+    for (const v of violations) {
+      process.stderr.write(`[verify-module-coverage] ${v.module}: ${v.reason}\n`)
+    }
+    process.stderr.write(
+      `\n[verify-module-coverage] ${violations.length} per-module coverage regression(s).\n` +
+        `  Ratchet is upward-only — coverage must not drop > ${SLACK}pp below module-coverage-baseline.json.\n` +
+        `  To advance the baseline: node scripts/verify-module-coverage.mjs --update-baseline\n`,
+    )
+    return 1
+  }
+
+  process.stdout.write(
+    `[verify-module-coverage] OK — ${Object.keys(baseline).length} modules within baseline (slack: ${SLACK}pp)\n`,
+  )
+  return 0
+}
+
+// Only execute when run as a script — importing for unit tests must have no side effects.
+import { fileURLToPath } from 'node:url'
+if (process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1]) {
+  process.exit(main())
+}

package/dist/templates/scripts/verify-mutation-baseline.mjs.ejs

@@ -0,0 +1,209 @@
+#!/usr/bin/env node
+// SPDX-License-Identifier: Apache-2.0
+// <%= projectName %> — mutation-score non-regression ratchet (#1508).
+//
+// The absolute `mutationThreshold` (enforced by the mutator itself — stryker
+// `thresholds.break`, pitest `mutationThreshold`) catches a CATASTROPHIC drop, but
+// the killed-mutant ratio can still erode run-over-run toward that floor without ever
+// tripping. This ratchet backstops it: once a score is committed to
+// mutation-baseline.json, the score may only go UP (within a small ±SLACK tolerance
+// for mutator non-determinism). A real improvement advances the baseline; a regression
+// fails the gate and must be root-caused — not allowed to silently drift floor-ward.
+//
+// Greenfield-/SKIP-aware: no mutation report on disk → SKIP (exit 0); first run with a
+// report and no baseline → seed the baseline and pass. The ratchet only ever fails on a
+// genuine regression after a baseline is committed, so it is safe to wire blocking.
+//
+// Per-stack dispatch: TypeScript/JavaScript (Stryker `reports/mutation/mutation.json`)
+// is implemented; Java (pitest), Rust (cargo-mutants) and Python (mutmut) SKIP
+// gracefully until implemented — NEVER a false-fail.
+//
+// The compare is factored into a PURE, exported `compareMutationScore` so the decision
+// logic is unit-testable in isolation (see __tests__/generators/mutation-baseline-ratchet.test.ts).
+
+import { existsSync, readFileSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+export const SLACK = 0.5 // tolerated score wobble (pp) for mutator non-determinism
+const ROOT = process.cwd()
+const BASELINE_FILE = join(ROOT, 'mutation-baseline.json')
+
+/**
+ * Pure ratchet compare. Both are mutation scores in [0, 100].
+ *   - current dropped MORE than slack below baseline → violation
+ *   - current within slack (or higher)               → no violation
+ *   - baseline null/undefined (first run)            → no violation (seed elsewhere)
+ *
+ * @param {number|null|undefined} baselineScore  last committed mutation score
+ * @param {number} currentScore                   achieved mutation score this run
+ * @param {number} slack                          tolerated drop in pp (default SLACK)
+ * @returns {{ violations: Array<{ reason: string }> }}
+ */
+export function compareMutationScore(baselineScore, currentScore, slack = SLACK) {
+  const violations = []
+  if (typeof baselineScore !== 'number') return { violations }
+  if (typeof currentScore !== 'number' || Number.isNaN(currentScore)) {
+    violations.push({ reason: `current mutation score is not a number` })
+    return { violations }
+  }
+  if (currentScore + 1e-9 < baselineScore - slack) {
+    violations.push({
+      reason: `mutation score dropped: ${currentScore.toFixed(2)}% < ${baselineScore}% (slack: ${slack}pp)`,
+    })
+  }
+  return { violations }
+}
+
+// ─── Per-stack extraction ───────────────────────────────────────────────────
+// Each extractor returns either a number (achieved score 0..100) or null when this
+// stack's report is absent/unsupported → caller SKIPs (no false-fail).
+
+/**
+ * Compute the Stryker mutation score from reports/mutation/mutation.json.
+ * Score = detected / (detected + undetected) * 100, where
+ *   detected   = Killed + Timeout
+ *   undetected = Survived + NoCoverage
+ * (CompileError / RuntimeError / Ignored are excluded from the denominator, matching
+ * Stryker's own `mutationScore`.) Returns null on absent/unparseable report or when
+ * there are no covered mutants to score.
+ */
+export function strykerScoreFromReport(report) {
+  if (report == null || typeof report !== 'object' || report.files == null) return null
+  let detected = 0
+  let undetected = 0
+  for (const file of Object.values(report.files)) {
+    const mutants = file?.mutants
+    if (!Array.isArray(mutants)) continue
+    for (const m of mutants) {
+      switch (m?.status) {
+        case 'Killed':
+        case 'Timeout':
+          detected++
+          break
+        case 'Survived':
+        case 'NoCoverage':
+          undetected++
+          break
+        default:
+          break // CompileError / RuntimeError / Ignored — not scored
+      }
+    }
+  }
+  const total = detected + undetected
+  if (total <= 0) return null
+  return Math.round((detected / total) * 100 * 100) / 100
+}
+
+function extractStrykerScore() {
+  const file = join(ROOT, 'reports', 'mutation', 'mutation.json')
+  if (!existsSync(file)) return null
+  try {
+    return strykerScoreFromReport(JSON.parse(readFileSync(file, 'utf-8')))
+  } catch (err) {
+    process.stderr.write(`[verify-mutation-baseline] failed to parse mutation.json: ${err.message}\n`)
+    return null
+  }
+}
+
+// Scaffolds — graceful SKIP until each is implemented (never a false-fail).
+function extractPitestScore() {
+  // pitest emits target/pit-reports/mutations.xml (<mutation detected=.. status=..>).
+  // TODO(#1508): aggregate detected/total from mutations.xml. Skip until implemented.
+  return null
+}
+function extractCargoMutantsScore() {
+  // cargo-mutants emits mutants.out/outcomes.json (caught/missed/unviable/timeout).
+  // TODO(#1508): compute caught/(caught+missed) from outcomes.json. Skip until implemented.
+  return null
+}
+function extractMutmutScore() {
+  // mutmut tracks results in .mutmut-cache / `mutmut results`.
+  // TODO(#1508): parse killed/total from the mutmut cache. Skip until implemented.
+  return null
+}
+
+const LANGUAGE = '<%= language %>'
+
+function extractScore() {
+  switch (LANGUAGE) {
+    case 'typescript':
+    case 'javascript':
+      return extractStrykerScore()
+    case 'java':
+    case 'kotlin':
+      return extractPitestScore()
+    case 'rust':
+      return extractCargoMutantsScore()
+    case 'python':
+      return extractMutmutScore()
+    default:
+      return extractStrykerScore()
+  }
+}
+
+// ─── Main (skipped under test import — only runs when executed directly) ─────
+function main() {
+  const UPDATE_BASELINE = process.argv.includes('--update-baseline')
+
+  const current = extractScore()
+  if (current == null) {
+    process.stdout.write(
+      `[verify-mutation-baseline] SKIP — no mutation report for "${LANGUAGE}" (run mutation testing first, or stack not yet supported)\n`,
+    )
+    return 0
+  }
+
+  if (UPDATE_BASELINE) {
+    writeFileSync(BASELINE_FILE, JSON.stringify({ mutationScore: current }, null, 2) + '\n')
+    process.stdout.write(`[verify-mutation-baseline] baseline updated → ${current}%\n`)
+    return 0
+  }
+
+  if (!existsSync(BASELINE_FILE)) {
+    writeFileSync(BASELINE_FILE, JSON.stringify({ mutationScore: current }, null, 2) + '\n')
+    process.stdout.write(
+      `[verify-mutation-baseline] seeded mutation-baseline.json → ${current}% — re-run to ratchet\n`,
+    )
+    return 0
+  }
+
+  let baseline
+  try {
+    baseline = JSON.parse(readFileSync(BASELINE_FILE, 'utf-8'))
+  } catch (err) {
+    process.stderr.write(`[verify-mutation-baseline] failed to parse mutation-baseline.json: ${err.message}\n`)
+    return 1
+  }
+  const baselineScore = typeof baseline?.mutationScore === 'number' ? baseline.mutationScore : null
+
+  const { violations } = compareMutationScore(baselineScore, current, SLACK)
+  if (violations.length > 0) {
+    for (const v of violations) process.stderr.write(`[verify-mutation-baseline] ${v.reason}\n`)
+    process.stderr.write(
+      `\n[verify-mutation-baseline] mutation-score regression.\n` +
+        `  Ratchet is upward-only — the score must not drop > ${SLACK}pp below mutation-baseline.json.\n` +
+        `  To advance the baseline after a real improvement: node scripts/verify-mutation-baseline.mjs --update-baseline\n`,
+    )
+    return 1
+  }
+
+  // A real improvement silently advances the baseline so the floor only climbs.
+  if (baselineScore != null && current > baselineScore + SLACK) {
+    writeFileSync(BASELINE_FILE, JSON.stringify({ mutationScore: current }, null, 2) + '\n')
+    process.stdout.write(
+      `[verify-mutation-baseline] OK — score improved ${baselineScore}% → ${current}%, baseline ratcheted up\n`,
+    )
+    return 0
+  }
+
+  process.stdout.write(
+    `[verify-mutation-baseline] OK — ${current}% within baseline ${baselineScore}% (slack: ${SLACK}pp)\n`,
+  )
+  return 0
+}
+
+// Only execute when run as a script — importing for unit tests must have no side effects.
+import { fileURLToPath } from 'node:url'
+if (process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1]) {
+  process.exit(main())
+}