@plainconceptsplatform/workflows 1.10.1 → 1.12.0

package/loops/templates/quality-gates/scripts/engineering-excellence.schema.json.md

@@ -0,0 +1,5 @@
+# Ownership: scripts/engineering-excellence.schema.json
+
+Managed by @plainconceptsplatform/workflows. Source: loops/templates/quality-gates/scripts/engineering-excellence.schema.json. Update with `workflows update --force`; consumer edits may be overwritten.
+
+JSON (RFC 8259) does not permit comments, so the ownership header of `engineering-excellence.schema.json` is documented here. The schema is the facet contract the Project-Health collector reads, vendored verbatim from PlainConceptsPlatform/Atlas. `scripts/engineering-excellence.mjs` validates every facet against it before writing, so an app never uploads a facet the collector would reject.

package/loops/templates/quality-gates/scripts/lib/complexity-gate.mjs

@@ -0,0 +1,80 @@
+// Managed by @plainconceptsplatform/workflows. Source: loops/templates/quality-gates/scripts/lib/complexity-gate.mjs. Update with `workflows update --force`; consumer edits may be overwritten.
+export const CC_MAX = 15;
+export const CRAP_MAX = 30;
+// CRAP moves with coverage; a fraction of a point on an untouched method is
+// measurement noise between runs, not a regression worth a red build.
+export const CRAP_TOLERANCE = 1;
+const JUSTIFY_WINDOW = 5;
+
+export const methodKey = (m) => `${m.file}::${m.method}`;
+export const violates = (m) => m.cc > CC_MAX || m.crap > CRAP_MAX;
+
+// Overloads share a key; the baseline keeps the worst of them.
+function worstByKey(methods) {
+  const out = new Map();
+  for (const m of methods) {
+    const k = methodKey(m);
+    const prev = out.get(k);
+    if (!prev || m.cc > prev.cc || (m.cc === prev.cc && m.crap > prev.crap)) out.set(k, m);
+  }
+  return out;
+}
+
+export function buildBaseline(methods) {
+  const entries = [...worstByKey(methods.filter(violates))]
+    .sort(([a], [b]) => a.localeCompare(b))
+    .map(([k, m]) => [k, { cc: m.cc, crap: Math.round(m.crap * 100) / 100 }]);
+  return Object.fromEntries(entries);
+}
+
+// An escape hatch a reviewer can see: `complexity-justified: <reason> (#<issue>)`
+// in a comment within the few lines above the method's first line.
+const JUSTIFIED = /complexity-justified:\s*(\S.*?)\s*\(#(\d+)\)/;
+export function justification(sourceLines, line) {
+  if (!sourceLines || !line) return null;
+  for (let n = line - 1; n >= Math.max(1, line - JUSTIFY_WINDOW); n--) {
+    const m = sourceLines[n - 1]?.match(JUSTIFIED);
+    if (m) return { reason: m[1], issue: Number(m[2]) };
+  }
+  return null;
+}
+
+// `readSource(file)` returns the file's lines (or null); injected so this stays pure.
+export function evaluate(methods, baseline, readSource = () => null) {
+  const violations = [];
+  const justified = [];
+  let baselined = 0;
+  const current = worstByKey(methods);
+  for (const [k, m] of current) {
+    if (!violates(m)) continue;
+    const base = baseline[k];
+    if (base && m.cc <= base.cc && m.crap <= base.crap + CRAP_TOLERANCE) {
+      baselined++;
+      continue;
+    }
+    const j = justification(readSource(m.file), m.line);
+    if (j) {
+      justified.push({ ...m, ...j });
+      continue;
+    }
+    const why = !base ? 'new' : m.cc > base.cc ? 'cc-increased' : 'crap-increased';
+    violations.push({ ...m, why, baseline: base ?? null });
+  }
+  // Entries that no longer violate (refactored, tested, deleted) can leave the
+  // baseline; --prune does that and only ever shrinks it.
+  const fixed = Object.keys(baseline).filter((k) => !current.has(k) || !violates(current.get(k))).sort();
+  return { violations, justified, baselined, fixed };
+}
+
+// Rewrite the baseline only downwards: drop fixed entries and lower values that
+// improved. Never adds a key and never raises a value.
+export function pruneBaseline(baseline, methods) {
+  const current = worstByKey(methods);
+  const out = {};
+  for (const [k, base] of Object.entries(baseline)) {
+    const m = current.get(k);
+    if (!m || !violates(m)) continue;
+    out[k] = { cc: Math.min(base.cc, m.cc), crap: Math.min(base.crap, Math.round(m.crap * 100) / 100) };
+  }
+  return out;
+}

package/loops/templates/quality-gates/scripts/lib/complexity-gate.test.mjs

@@ -0,0 +1,105 @@
+// Managed by @plainconceptsplatform/workflows. Source: loops/templates/quality-gates/scripts/lib/complexity-gate.test.mjs. Update with `workflows update --force`; consumer edits may be overwritten.
+// Run: node --test scripts/lib/complexity-gate.test.mjs
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import { buildBaseline, evaluate, justification, pruneBaseline } from './complexity-gate.mjs';
+import { scoreMethods } from './engineering-excellence.mjs';
+
+const m = (method, cc, coverage, file = 'apps/api/src/App.Domain/Renting/Contract.cs', line = 10) =>
+  scoreMethods([{ scope: 'App.Domain', module: 'Renting', file, method, line, cc, coverage }])[0];
+
+test('evaluate_newMethodAboveCcCap_isViolationEvenWhenFullyCovered', () => {
+  const { violations } = evaluate([m('Contract.Price', 16, 1)], {});
+
+  assert.equal(violations.length, 1);
+  assert.equal(violations[0].why, 'new');
+  assert.equal(violations[0].crap, 16);
+});
+
+test('evaluate_newMethodUnderCcCapButUntested_isViolationOnCrap', () => {
+  // CC 12 at 0% coverage: 144 + 12 = 156 > 30.
+  const { violations } = evaluate([m('Contract.Renew', 12, 0)], {});
+
+  assert.deepEqual(violations.map((v) => [v.method, v.crap]), [['Contract.Renew', 156]]);
+});
+
+test('evaluate_complexMethodTestedInProportion_passes', () => {
+  // CC 12 at 60% coverage: 144 * 0.064 + 12 = 21.2 <= 30.
+  const r = evaluate([m('Contract.Renew', 12, 0.6), m('Contract.Id', 1, 0)], {});
+
+  assert.deepEqual(r.violations, []);
+});
+
+test('evaluate_baselinedMethodUnchanged_passesAndCountsAsBacklog', () => {
+  const method = m('Contract.Parse', 40, 0.5);
+  const r = evaluate([method], { [`${method.file}::Contract.Parse`]: { cc: 40, crap: method.crap } });
+
+  assert.deepEqual(r.violations, []);
+  assert.equal(r.baselined, 1);
+});
+
+test('evaluate_baselinedMethodMoreComplex_isViolation', () => {
+  const method = m('Contract.Parse', 41, 0.5);
+  const { violations } = evaluate([method], { [`${method.file}::Contract.Parse`]: { cc: 40, crap: 9999 } });
+
+  assert.equal(violations[0].why, 'cc-increased');
+  assert.deepEqual(violations[0].baseline, { cc: 40, crap: 9999 });
+});
+
+test('evaluate_baselinedMethodLostCoverageBeyondTolerance_isViolation', () => {
+  const method = m('Contract.Parse', 20, 0.4); // CRAP 106.4
+  const key = `${method.file}::Contract.Parse`;
+
+  assert.equal(evaluate([method], { [key]: { cc: 20, crap: 105.5 } }).violations.length, 0, 'within the 1-point tolerance');
+  assert.equal(evaluate([method], { [key]: { cc: 20, crap: 100 } }).violations[0].why, 'crap-increased');
+});
+
+test('evaluate_justifiedMethod_isExemptAndReported', () => {
+  const method = m('Contract.Route', 18, 1, 'apps/web/src/lib/route.ts', 4);
+  const source = ['', '// complexity-justified: exhaustive status table, splitting hides it (#1941)', '', 'export function route() {'];
+
+  const r = evaluate([method], {}, () => source);
+
+  assert.deepEqual(r.violations, []);
+  assert.deepEqual(r.justified.map((j) => [j.method, j.issue]), [['Contract.Route', 1941]]);
+});
+
+test('justification_commentWithoutIssueOrTooFarAbove_isIgnored', () => {
+  const lines = ['// complexity-justified: trust me', 'a', 'b', 'c', 'd', 'e', 'f', 'fn()'];
+  assert.equal(justification(lines, 8), null, 'no (#issue)');
+  const far = ['// complexity-justified: ok (#1)', 'a', 'b', 'c', 'd', 'e', 'fn()'];
+  assert.equal(justification(far, 7), null, 'more than 5 lines above');
+  assert.deepEqual(justification(far, 6), { reason: 'ok', issue: 1 });
+});
+
+test('evaluate_baselineEntriesNoLongerViolating_areReportedFixed', () => {
+  const tested = m('Contract.Parse', 12, 1);
+  const r = evaluate([tested], {
+    [`${tested.file}::Contract.Parse`]: { cc: 12, crap: 156 },
+    'apps/web/src/gone.ts::removed': { cc: 30, crap: 900 },
+  });
+
+  assert.deepEqual(r.fixed, ['apps/api/src/App.Domain/Renting/Contract.cs::Contract.Parse', 'apps/web/src/gone.ts::removed']);
+});
+
+test('buildBaseline_overloads_keepsOnlyViolatorsAtTheirWorst', () => {
+  const b = buildBaseline([m('Contract.Parse', 20, 0), m('Contract.Parse', 25, 0), m('Contract.Id', 1, 0)]);
+
+  assert.deepEqual(b, { 'apps/api/src/App.Domain/Renting/Contract.cs::Contract.Parse': { cc: 25, crap: 650 } });
+});
+
+test('pruneBaseline_improvementsAndRegressions_onlyEverShrinks', () => {
+  const key = (name) => `apps/api/src/App.Domain/Renting/Contract.cs::${name}`;
+  const baseline = {
+    [key('Improved')]: { cc: 30, crap: 900 },
+    [key('Worse')]: { cc: 20, crap: 100 },
+    [key('Fixed')]: { cc: 16, crap: 16 },
+  };
+
+  const pruned = pruneBaseline(baseline, [m('Improved', 25, 1), m('Worse', 22, 0), m('Fixed', 10, 1), m('Brand', 50, 0)]);
+
+  assert.deepEqual(pruned, {
+    [key('Improved')]: { cc: 25, crap: 25 },
+    [key('Worse')]: { cc: 20, crap: 100 },
+  });
+});

package/loops/templates/quality-gates/scripts/lib/duplication-gate.mjs

@@ -0,0 +1,50 @@
+// Managed by @plainconceptsplatform/workflows. Source: loops/templates/quality-gates/scripts/lib/duplication-gate.mjs. Update with `workflows update --force`; consumer edits may be overwritten.
+// Rules for the blocking duplication gate (practice 11, vendored from PlainConceptsPlatform/Atlas, Atlas#1942). Pure functions; the CLI is
+// scripts/check-duplication.mjs, and the per-file numbers come from
+// duplicatedLinesByFile in engineering-excellence.mjs, so the gate and the hygiene facet count the
+// same lines.
+//
+// Same model as the complexity gate (complexity-gate.mjs): a baseline, not a diff.
+// scripts/duplication-baseline.json records, per file, how many of its lines sit
+// inside a jscpd clone today. A file may keep that many but never more, and a file
+// outside the baseline may have none. Any clone at or above jscpd's minimum (.jscpd.json)
+// that a PR adds therefore fails, in every file it touches, while the existing
+// backlog stays green. The ratchet is the file only ever shrinking.
+
+export function buildBaseline(duplicated) {
+  return Object.fromEntries(
+    Object.entries(duplicated)
+      .filter(([, lines]) => lines > 0)
+      .sort(([a], [b]) => a.localeCompare(b)),
+  );
+}
+
+export function evaluate(duplicated, baseline) {
+  const violations = [];
+  let baselined = 0;
+  for (const [file, lines] of Object.entries(duplicated).sort(([a], [b]) => a.localeCompare(b))) {
+    if (lines === 0) continue;
+    const base = baseline[file];
+    if (base !== undefined && lines <= base) {
+      baselined++;
+      continue;
+    }
+    violations.push({ file, lines, baseline: base ?? null, why: base === undefined ? 'new' : 'increased' });
+  }
+  // Entries whose file improved or lost its clones; --prune lowers or drops them.
+  const fixed = Object.keys(baseline)
+    .filter((file) => (duplicated[file] ?? 0) < baseline[file])
+    .sort();
+  return { violations, baselined, fixed };
+}
+
+// Only ever downwards: lowers improved entries, drops files with no clone left (or
+// gone), never adds a file and never raises a count.
+export function pruneBaseline(baseline, duplicated) {
+  const out = {};
+  for (const [file, base] of Object.entries(baseline)) {
+    const lines = Math.min(base, duplicated[file] ?? 0);
+    if (lines > 0) out[file] = lines;
+  }
+  return out;
+}

package/loops/templates/quality-gates/scripts/lib/duplication-gate.test.mjs

@@ -0,0 +1,47 @@
+// Managed by @plainconceptsplatform/workflows. Source: loops/templates/quality-gates/scripts/lib/duplication-gate.test.mjs. Update with `workflows update --force`; consumer edits may be overwritten.
+// Run: node --test scripts/lib/duplication-gate.test.mjs
+// Vendored from PlainConceptsPlatform/Atlas scripts/lib/duplication-gate.test.mjs (Atlas#1942).
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import { buildBaseline, evaluate, pruneBaseline } from './duplication-gate.mjs';
+
+const A = 'apps/api/src/App.Api/Audit/AuditEndpoints.cs';
+const B = 'apps/web/src/pages/Settings.tsx';
+const C = 'apps/web/src/lib/api.ts';
+
+test('evaluate_cloneInFileOutsideBaseline_isNewViolation', () => {
+  const r = evaluate({ [A]: 30, [C]: 12 }, { [A]: 30 });
+
+  assert.deepEqual(r.violations, [{ file: C, lines: 12, baseline: null, why: 'new' }]);
+  assert.equal(r.baselined, 1);
+});
+
+test('evaluate_baselinedFileGainsDuplicatedLines_isIncreasedViolation', () => {
+  const r = evaluate({ [A]: 41 }, { [A]: 30 });
+
+  assert.deepEqual(r.violations, [{ file: A, lines: 41, baseline: 30, why: 'increased' }]);
+});
+
+test('evaluate_baselinedFilesAtOrUnderBaseline_passAndReportImprovements', () => {
+  const r = evaluate({ [A]: 30, [B]: 5 }, { [A]: 30, [B]: 20, [C]: 12 });
+
+  assert.deepEqual(r.violations, []);
+  assert.equal(r.baselined, 2);
+  assert.deepEqual(r.fixed, [C, B], 'C lost its clones and B shrank, sorted by path');
+});
+
+test('evaluate_noClonesAndEmptyBaseline_passes', () => {
+  assert.deepEqual(evaluate({}, {}), { violations: [], baselined: 0, fixed: [] });
+});
+
+test('buildBaseline_duplicatedLines_keepsOnlyFilesWithClonesSorted', () => {
+  const b = buildBaseline({ [C]: 12, [A]: 30, [B]: 0 });
+
+  assert.deepEqual(Object.entries(b), [[A, 30], [C, 12]]);
+});
+
+test('pruneBaseline_improvementsAndRegressions_onlyEverShrinks', () => {
+  const pruned = pruneBaseline({ [A]: 30, [B]: 20, [C]: 12 }, { [A]: 45, [B]: 8, 'apps/web/src/new.ts': 50 });
+
+  assert.deepEqual(pruned, { [A]: 30, [B]: 8 }, 'A is not raised, B is lowered, C is dropped, the new file is not added');
+});