@plainconceptsplatform/workflows 1.10.0 → 1.11.0

package/loops/templates/quality-gates/scripts/check-coverage.mjs

@@ -0,0 +1,89 @@
+// Managed by @plainconceptsplatform/workflows. Source: loops/templates/quality-gates/scripts/check-coverage.mjs. Update with `workflows update --force`; consumer edits may be overwritten.
+// Enforces per-assembly line-coverage floors from a Cobertura XML report, and the web floor from
+// the vitest v8 report. Shape vendored from PlainConceptsPlatform/Atlas scripts/check-coverage.mjs.
+//
+// Why a floor map (not one global number): coverage is only honest where the test run actually
+// exercises the assembly. The CI report this runs against is the MERGED unit + acceptance +
+// integration coverage (the Application assembly is mostly exercised by the SQL-backed integration suite).
+//
+// The web floor gates the v8 Cobertura report from `vitest run --coverage`. It reads the report's
+// root line-rate: the web suite is one run, so there is nothing to merge.
+//
+// The floors are the app's, in quality.config.json (`coverage.api`, `coverage.reportOnly`,
+// `coverage.web`). They sit just under the measured baseline and only ever ratchet up; never
+// lower one to go green. The rule is in Foundations, ai/ENGINEERING.md, "Thresholds and ratchets".
+//
+// Usage: node scripts/check-coverage.mjs <coverage.cobertura.xml>
+//        node scripts/check-coverage.mjs --web <cobertura-coverage.xml>
+
+import { readFileSync } from 'node:fs';
+import { pathToFileURL } from 'node:url';
+import { coberturaRoot, packageRates } from './lib/engineering-excellence.mjs';
+import { loadQualityConfig } from './lib/quality-config.mjs';
+
+const pct = (r) => `${(r * 100).toFixed(2)}%`;
+
+function checkApi(file, { api: floors, reportOnly }) {
+  const rates = packageRates(readFileSync(file, 'utf8'));
+  let failed = false;
+  if (Object.keys(floors).length === 0) {
+    console.error('✗ quality.config.json sets no coverage.api floors: nothing would be gated');
+    return true;
+  }
+  for (const [pkg, floor] of Object.entries(floors)) {
+    const rate = rates[pkg];
+    if (rate === undefined) {
+      console.error(`✗ ${pkg}: no coverage data in ${file} (assembly not measured)`);
+      failed = true;
+      continue;
+    }
+    if (rate < floor) {
+      console.error(`✗ ${pkg}: ${pct(rate)} < floor ${pct(floor)}`);
+      failed = true;
+    } else {
+      console.log(`✓ ${pkg}: ${pct(rate)} (floor ${pct(floor)})`);
+    }
+  }
+  for (const pkg of reportOnly) {
+    if (rates[pkg] !== undefined) {
+      console.log(`· ${pkg}: ${pct(rates[pkg])} (report-only — not gated yet)`);
+    }
+  }
+  return failed;
+}
+
+function checkWeb(file, { web: floor }) {
+  if (floor === null) {
+    console.error('✗ web: quality.config.json sets no coverage.web floor');
+    return true;
+  }
+  const { lineRate } = coberturaRoot(readFileSync(file, 'utf8'));
+  if (Number.isNaN(lineRate)) {
+    console.error(`✗ web: no line-rate in ${file}`);
+    return true;
+  }
+  if (lineRate < floor) {
+    console.error(`✗ web: ${pct(lineRate)} < floor ${pct(floor)}`);
+    return true;
+  }
+  console.log(`✓ web: ${pct(lineRate)} (floor ${pct(floor)})`);
+  return false;
+}
+
+if (import.meta.url === pathToFileURL(process.argv[1]).href) {
+  const args = process.argv.slice(2);
+  const web = args[0] === '--web';
+  const file = web ? args[1] : args[0];
+  if (!file) {
+    console.error('usage: node scripts/check-coverage.mjs [--web] <coverage.cobertura.xml>');
+    process.exit(2);
+  }
+  let coverage;
+  try {
+    ({ coverage } = loadQualityConfig());
+  } catch (err) {
+    console.error(`✗ ${err.message}`);
+    process.exit(2);
+  }
+  process.exit((web ? checkWeb(file, coverage) : checkApi(file, coverage)) ? 1 : 0);
+}

package/loops/templates/quality-gates/scripts/check-duplication.mjs

@@ -0,0 +1,67 @@
+#!/usr/bin/env node
+// Managed by @plainconceptsplatform/workflows. Source: loops/templates/quality-gates/scripts/check-duplication.mjs. Update with `workflows update --force`; consumer edits may be overwritten.
+
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { buildBaseline, evaluate, pruneBaseline } from './lib/duplication-gate.mjs';
+import { duplicatedLinesByFile, lineCount, repoPath } from './lib/engineering-excellence.mjs';
+
+const args = process.argv.slice(2);
+const opt = (name) => {
+  const i = args.indexOf(`--${name}`);
+  return i === -1 ? undefined : args[i + 1];
+};
+const flag = (name) => args.includes(`--${name}`);
+
+const report = opt('report') ?? 'jscpd-report/jscpd-report.json';
+const baselineFile = opt('baseline') ?? fileURLToPath(new URL('./duplication-baseline.json', import.meta.url));
+if (!existsSync(report)) {
+  console.error(`✗ ${report} not found — run \`npx jscpd -c .jscpd.json\` first`);
+  process.exit(2);
+}
+
+const jscpd = JSON.parse(readFileSync(report, 'utf8'));
+const REPO_ROOT = fileURLToPath(new URL('..', import.meta.url));
+const lengthOf = (file) => (existsSync(`${REPO_ROOT}${file}`) ? lineCount(readFileSync(`${REPO_ROOT}${file}`, 'utf8')) : Infinity);
+const duplicated = duplicatedLinesByFile(jscpd, lengthOf);
+const clonesOf = (file) =>
+  (jscpd.duplicates ?? [])
+    .map((d) => [d.firstFile, d.secondFile].map((f) => ({ file: repoPath(f.name), start: f.start, end: f.end })))
+    .filter((pair) => pair.some((f) => f.file === file))
+    .map((pair) => pair.map((f) => `${f.file}:${f.start}-${f.end}`).join(' ↔ '));
+const writeJson = (file, obj) => writeFileSync(file, `${JSON.stringify(obj, null, 2)}\n`);
+const total = (b) => Object.values(b).reduce((n, v) => n + v, 0);
+
+if (flag('write-baseline')) {
+  const b = buildBaseline(duplicated);
+  writeJson(baselineFile, b);
+  console.log(`· wrote ${Object.keys(b).length} files (${total(b)} duplicated lines) to ${baselineFile}`);
+  process.exit(0);
+}
+
+const baseline = existsSync(baselineFile) ? JSON.parse(readFileSync(baselineFile, 'utf8')) : {};
+
+if (flag('prune')) {
+  const pruned = pruneBaseline(baseline, duplicated);
+  writeJson(baselineFile, pruned);
+  console.log(`· baseline ${Object.keys(baseline).length} -> ${Object.keys(pruned).length} files, ${total(baseline)} -> ${total(pruned)} lines`);
+  process.exit(0);
+}
+
+const { violations, baselined, fixed } = evaluate(duplicated, baseline);
+console.log('### Duplication gate (jscpd, no new clones)');
+console.log('');
+console.log(`${Object.keys(duplicated).length} files with clones · ${baselined} within their baseline · ${violations.length} violations`);
+if (fixed.length) {
+  console.log('', `${fixed.length} baseline entries improved — run \`node scripts/check-duplication.mjs --prune\` to ratchet the baseline down.`);
+}
+if (violations.length) {
+  console.log('', 'Violations — reuse the existing code instead of copying it:', '');
+  for (const v of violations) {
+    const why = v.why === 'new' ? 'not in the baseline' : `baseline ${v.baseline}`;
+    console.log(`- ✗ \`${v.file}\` — ${v.lines} duplicated lines (${why})`);
+    for (const c of clonesOf(v.file)) console.log(`  - ${c}`);
+  }
+  process.exit(1);
+}
+console.log('', '✓ no duplicated lines above the baseline');

package/loops/templates/quality-gates/scripts/check-mutation.mjs

@@ -0,0 +1,67 @@
+#!/usr/bin/env node
+// Managed by @plainconceptsplatform/workflows. Source: loops/templates/quality-gates/scripts/check-mutation.mjs. Update with `workflows update --force`; consumer edits may be overwritten.
+
+import { readFileSync } from 'node:fs';
+import { pathToFileURL } from 'node:url';
+import { mutationScores, tallyMutants } from './lib/engineering-excellence.mjs';
+import { loadQualityConfig } from './lib/quality-config.mjs';
+
+// The covered-code floor per scope is the app's: `mutation` in quality.config.json.
+
+// Mutant states and the score formula live in scripts/lib/engineering-excellence.mjs so the
+// Engineering Excellence facet reports exactly what this gate judged. `Killed`/`Timeout` are
+// detections; `CompileError`/`RuntimeError` are Stryker's problem rather than the
+// suite's, and `Ignored` was filtered deliberately, so all three are excluded.
+
+function main() {
+  const [scope, file] = process.argv.slice(2);
+  if (!scope || !file) {
+    console.error('usage: node scripts/check-mutation.mjs <scope> <mutation-report.json>');
+    process.exit(2);
+  }
+  let floors;
+  try {
+    floors = loadQualityConfig().mutation;
+  } catch (err) {
+    console.error(`✗ ${err.message}`);
+    process.exit(2);
+  }
+  if (!(scope in floors)) {
+    console.error(`✗ unknown scope '${scope}' — quality.config.json sets mutation floors for: ${Object.keys(floors).join(', ') || 'none'}`);
+    process.exit(2);
+  }
+
+  // The gate step runs with if: always(), so a Stryker run that died before writing
+  // its report lands here. Say that plainly instead of throwing an ENOENT stack.
+  let report;
+  try {
+    report = JSON.parse(readFileSync(file, 'utf8'));
+  } catch (err) {
+    console.error(`✗ ${scope}: cannot read ${file} — ${err.message}`);
+    process.exit(1);
+  }
+  const s = mutationScores(tallyMutants(report));
+  const { survived, noCoverage } = s;
+
+  if (s.valid === 0) {
+    console.error(`✗ ${scope}: no valid mutants in ${file} — the run produced nothing to score`);
+    process.exit(1);
+  }
+
+  const pct = (r) => `${(r * 100).toFixed(2)}%`;
+  const floor = floors[scope];
+  const { coveredScore, fullScore } = s;
+
+  // Printed on every run, pass or fail: the NoCoverage population is not a
+  // deficiency to gate on, it is the backlog of logic no unit test reaches.
+  console.log(`· ${scope}: full score ${pct(fullScore)} · ${noCoverage} mutants with no unit coverage · ${survived} survived`);
+
+  if (coveredScore < floor) {
+    console.error(`✗ ${scope}: covered-code ${pct(coveredScore)} < floor ${pct(floor)}`);
+    process.exit(1);
+  }
+
+  console.log(`✓ ${scope}: covered-code ${pct(coveredScore)} (floor ${pct(floor)})`);
+}
+
+if (import.meta.url === pathToFileURL(process.argv[1]).href) main();

package/loops/templates/quality-gates/scripts/dast-wait-stable.sh

@@ -0,0 +1,53 @@
+#!/usr/bin/env bash
+# Managed by @plainconceptsplatform/workflows. Source: loops/templates/quality-gates/scripts/dast-wait-stable.sh. Update with `workflows update --force`; consumer edits may be overwritten.
+# Wait until a deployed instance of the app is the NEW build and stays up, before (or between) DAST
+# scans. Used by .github/workflows/security-dast.yml; shape from
+# PlainConceptsPlatform/Atlas scripts/dast-wait-stable.sh.
+#
+#   dast-wait-stable.sh <host> <streak> [expected-sha]
+#
+# With an expected SHA, first poll /api/v1/health until it reports that commit (the deploy's own
+# build-identity gate). After a deploy the old process can keep answering 200 for about a minute
+# before the new one takes over, with 502s in between, and a streak of 200s from the OLD process
+# would start the scan on platform pages.
+#
+# Then require <streak> consecutive 200s on /login (the SPA shell) 10 s apart, within 6 minutes.
+# Not /: with Entra SSO on, an anonymous GET / is redirected to the sign-in (SignInRedirect).
+# Exits 0 when stable, 1 otherwise.
+set -uo pipefail
+
+host="$1"
+streak_needed="$2"
+sha="${3:-}"
+
+# wait_build <url> <sha> <attempts>: poll every 15 s until the body names the commit.
+wait_build() {
+  local url="$1" expected="$2" attempts="$3" body
+  for _ in $(seq 1 "$attempts"); do
+    body="$(curl -s --max-time 20 "$url" || true)"
+    case "$body" in *"$expected"*) return 0 ;; esac
+    sleep 15
+  done
+  return 1
+}
+
+if [ -n "$sha" ]; then
+  if ! wait_build "https://${host}/api/v1/health" "$sha" 24; then
+    echo "::error::${host} never reported build ${sha} on /api/v1/health in 6 minutes: the deploy did not land, or the old process is still serving"
+    exit 1
+  fi
+  echo "Build ${sha:0:7} is serving /api/v1/health"
+fi
+
+streak=0
+for attempt in $(seq 1 36); do
+  code=$(curl -s -o /dev/null -w '%{http_code}' --max-time 15 "https://${host}/login" || echo 000)
+  if [ "$code" = "200" ]; then streak=$((streak + 1)); else streak=0; fi
+  if [ "$streak" -ge "$streak_needed" ]; then
+    echo "SPA shell stable (${streak_needed} consecutive 200s by attempt ${attempt})"
+    exit 0
+  fi
+  sleep 10
+done
+echo "::error::${host}/login never answered 200 ${streak_needed} times in a row in 6 minutes: the scan would read platform errors, not the app"
+exit 1

package/loops/templates/quality-gates/scripts/engineering-excellence.mjs

@@ -0,0 +1,188 @@
+#!/usr/bin/env node
+// Managed by @plainconceptsplatform/workflows. Source: loops/templates/quality-gates/scripts/engineering-excellence.mjs. Update with `workflows update --force`; consumer edits may be overwritten.
+
+import { existsSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { CC_MAX, CRAP_MAX, evaluate } from './lib/complexity-gate.mjs';
+import { evaluate as evaluateDuplication } from './lib/duplication-gate.mjs';
+import { loadQualityConfig } from './lib/quality-config.mjs';
+import { scopedSources } from './lib/source-files.mjs';
+import {
+  apiMethods,
+  complexityFacetData,
+  coverageFacetData,
+  duplicatedLinesByFile,
+  envelope,
+  hygieneFacetData,
+  lineCount,
+  mutationFacetData,
+  scoreMethods,
+  sbomFacetData,
+  securityFacetData,
+  validateFacet,
+  webMethods,
+} from './lib/engineering-excellence.mjs';
+
+const BUILT = ['coverage', 'complexity', 'mutation', 'security', 'sbom', 'hygiene'];
+const SCHEMA = JSON.parse(readFileSync(new URL('./engineering-excellence.schema.json', import.meta.url), 'utf8'));
+
+function parseArgs(argv) {
+  const [facet, ...rest] = argv;
+  const opts = { job: [] };
+  for (let i = 0; i < rest.length; i += 2) {
+    const key = rest[i]?.replace(/^--/, '');
+    const value = rest[i + 1];
+    if (!key || value === undefined) usage(`missing value for ${rest[i]}`);
+    if (key === 'job') opts.job.push(value);
+    else opts[key] = value;
+  }
+  return { facet, opts };
+}
+
+function usage(msg) {
+  if (msg) console.error(`✗ ${msg}`);
+  console.error(`usage: node scripts/engineering-excellence.mjs <${BUILT.join('|')}> --out <file> [inputs] — see the header of this file`);
+  process.exit(2);
+}
+
+const read = (file) => readFileSync(file, 'utf8');
+const REPO_ROOT = fileURLToPath(new URL('..', import.meta.url));
+const sourceLines = (file) => (existsSync(`${REPO_ROOT}${file}`) ? read(`${REPO_ROOT}${file}`).split('\n') : null);
+const readOptional = (file) => {
+  if (!file) return null;
+  if (existsSync(file)) return read(file);
+  console.log(`· ${file} not found — recorded as null (the producing job did not write it)`);
+  return null;
+};
+const required = (opts, key) => opts[key] ?? usage(`--${key} is required`);
+
+function mutationReports(dir) {
+  const reports = {};
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const scope = entry.isDirectory() && entry.name.match(/^mutation-(.+)$/)?.[1];
+    if (!scope) continue;
+    const file = join(dir, entry.name, 'mutation-report.json');
+    // A scope whose Stryker run died has no report; the gate already failed it.
+    if (existsSync(file)) reports[scope] = JSON.parse(read(file));
+    else console.log(`· ${scope}: no mutation-report.json — scope omitted`);
+  }
+  return reports;
+}
+
+function build(facet, opts) {
+  switch (facet) {
+    case 'coverage': {
+      const { coverage } = loadQualityConfig();
+      return coverageFacetData({
+        apiXml: read(required(opts, 'api')),
+        webXml: read(required(opts, 'web')),
+        floors: { api: coverage.api, web: coverage.web },
+      });
+    }
+    case 'complexity': {
+      const methods = [
+        ...apiMethods(read(required(opts, 'api'))),
+        ...webMethods(JSON.parse(read(required(opts, 'eslint'))), JSON.parse(read(required(opts, 'web-final')))),
+      ];
+      const data = complexityFacetData(methods);
+      // The backlog size is the gate's ratchet: it should only ever go down.
+      if (opts.baseline && existsSync(opts.baseline)) {
+        const r = evaluate(scoreMethods(methods), JSON.parse(read(opts.baseline)), sourceLines);
+        data.gate = { ccMax: CC_MAX, crapMax: CRAP_MAX, baselined: r.baselined, violations: r.violations.length, justified: r.justified.length };
+      }
+      return data;
+    }
+    case 'mutation':
+      return mutationFacetData(mutationReports(required(opts, 'reports')), loadQualityConfig().mutation);
+    case 'security': {
+      const trivy = readOptional(opts.trivy);
+      const semgrep = readOptional(opts.semgrep);
+      const jobs = Object.fromEntries(opts.job.map((j) => j.split('=')));
+      return securityFacetData({
+        trivy: trivy && JSON.parse(trivy),
+        semgrep: semgrep && JSON.parse(semgrep),
+        jobs,
+      });
+    }
+    case 'sbom':
+      return sbomFacetData(read(required(opts, 'cyclonedx')));
+    case 'hygiene': {
+      const cfg = JSON.parse(read(join(REPO_ROOT, '.jscpd.json')));
+      const files = scopedSources(cfg, REPO_ROOT);
+      const lengths = new Map(files.map((f) => [f.file, lineCount(f.text)]));
+      const duplicated = duplicatedLinesByFile(JSON.parse(read(required(opts, 'jscpd'))), (f) => lengths.get(f));
+      const semgrep = readOptional(opts.semgrep);
+      let gate = null;
+      if (opts.baseline && existsSync(opts.baseline)) {
+        const baseline = JSON.parse(read(opts.baseline));
+        const r = evaluateDuplication(duplicated, baseline);
+        gate = {
+          baselinedFiles: Object.keys(baseline).length,
+          baselineLines: Object.values(baseline).reduce((n, v) => n + v, 0),
+          violations: r.violations.length,
+          fixed: r.fixed.length,
+        };
+      }
+      return hygieneFacetData({
+        files,
+        duplicated,
+        semgrep: semgrep && JSON.parse(semgrep),
+        thresholds: { minLines: cfg.minLines, minTokens: cfg.minTokens },
+        gate,
+      });
+    }
+    default:
+      return usage(`unknown facet '${facet}'`);
+  }
+}
+
+const pct = (r) => (r === null || r === undefined ? 'n/a' : `${(r * 100).toFixed(2)}%`);
+
+// A short Markdown digest for $GITHUB_STEP_SUMMARY, so the numbers are readable on
+// the run itself, not only in the dashboard.
+function summary(facet, d) {
+  const lines = [`### Engineering Excellence · ${facet}`, ''];
+  if (facet === 'coverage') {
+    lines.push('| Scope | Lines | Branches | Floor |', '|---|---|---|---|');
+    for (const [k, s] of Object.entries(d.scopes)) lines.push(`| ${k} | ${pct(s.lineRate)} | ${pct(s.branchRate)} | ${pct(s.floor)} |`);
+    lines.push('', `Global: ${pct(d.global.lineRate)}`);
+  } else if (facet === 'complexity') {
+    lines.push('| Scope | Methods | CC p90 | CC max | CC>10 | CRAP>30 |', '|---|---|---|---|---|---|');
+    for (const [k, s] of Object.entries(d.scopes)) lines.push(`| ${k} | ${s.methods} | ${s.ccP90} | ${s.ccMax} | ${s.over10} | ${s.crapOver30} |`);
+    if (d.gate) lines.push('', `Gate backlog: ${d.gate.baselined} baselined · ${d.gate.violations} violations · ${d.gate.justified} justified`);
+    lines.push('', 'Top CRAP hotspots:', '');
+    for (const h of d.hotspots.slice(0, 10)) lines.push(`- \`${h.file}:${h.line}\` ${h.method} — CC ${h.cc}, cov ${pct(h.coverage)}, CRAP ${h.crap}`);
+  } else if (facet === 'mutation') {
+    lines.push('| Scope | Covered-code | Full | Survived | NoCoverage | Floor |', '|---|---|---|---|---|---|');
+    for (const [k, s] of Object.entries(d.scopes)) lines.push(`| ${k} | ${pct(s.coveredScore)} | ${pct(s.fullScore)} | ${s.survived} | ${s.noCoverage} | ${pct(s.floor)} |`);
+    lines.push('', `Global covered-code: ${pct(d.global.coveredScore)}`);
+  } else if (facet === 'security') {
+    if (d.trivy) lines.push(`Trivy vulns: ${JSON.stringify(d.trivy.vuln)} · fixable ${d.trivy.fixableVulns}`);
+    if (d.semgrep) lines.push(`Semgrep: ${d.semgrep.ERROR} error · ${d.semgrep.WARNING} warning · ${d.semgrep.INFO} info`);
+    lines.push(`Jobs: ${Object.entries(d.jobs).map(([k, v]) => `${k}=${v}`).join(', ')}`);
+  } else if (facet === 'sbom') {
+    lines.push(`${d.components} components · ${JSON.stringify(d.byEcosystem)} · ${d.unlicensed} without a license`);
+  } else if (facet === 'hygiene') {
+    const n = (v) => (v === null ? 'n/a' : v);
+    lines.push('| Scope | Files | Duplication | Dup. lines | Swallowed | Justified | Dead code | Comment density |', '|---|---|---|---|---|---|---|---|');
+    for (const [k, s] of Object.entries(d.scopes)) {
+      lines.push(`| ${k} | ${s.files} | ${pct(s.duplicationRate)} | ${s.duplicatedLines} | ${n(s.swallowedExceptions)} | ${s.justifiedSwallows} | ${s.deadCodeWarnings} | ${n(s.commentDensity)} |`);
+    }
+    if (d.gate) lines.push('', `Duplication gate: ${d.gate.baselinedFiles} baselined files (${d.gate.baselineLines} lines) · ${d.gate.violations} violations · ${d.gate.fixed} improved`);
+  }
+  return lines.join('\n');
+}
+
+const { facet, opts } = parseArgs(process.argv.slice(2));
+if (!BUILT.includes(facet)) usage(`unknown facet '${facet}'`);
+const out = required(opts, 'out');
+const doc = envelope(facet, build(facet, opts));
+const errors = validateFacet(doc, SCHEMA);
+if (errors.length) {
+  console.error(`✗ ${facet}: facet violates scripts/engineering-excellence.schema.json`);
+  for (const e of errors.slice(0, 20)) console.error(`  ${e}`);
+  process.exit(1);
+}
+writeFileSync(out, `${JSON.stringify(doc, null, 2)}\n`);
+console.log(summary(facet, doc.data));