@codyswann/lisa 4.54.13 → 4.55.0

package/typescript/copy-overwrite/scripts/threshold-ratchet-compare.mjs

@@ -10,6 +10,9 @@
  * for the CLI.
  */
 import {
+  ALLOW_STATE,
+  classifyAllowEntry,
+  describeAllowScope,
   extractAllowEntries,
   extractK6Constraints,
   extractLighthouseAssertions,
@@ -224,7 +227,7 @@ function compareAllowList(relPath, base, current) {
         file: relPath,
         key: `thresholdRatchet.allow ${entry.file}#${entry.key}`,
         type: "allow-added",
-        message: `${relPath}: new threshold exception for ${entry.file} → ${entry.key}. Exceptions are a human decision: land this entry in its own human-approved change first, then make the threshold change.`,
+        message: `${relPath}: new threshold exception — ${describeAllowScope(entry)}. Exceptions are a human decision: land this entry in its own human-approved change first, then make the threshold change. It needs a reason saying what resolves it and an "until": "YYYY-MM-DD" naming the day it is reviewed, because an exemption that cannot end is a permanent reduction in what the ratchet covers.`,
       });
     }
   }
@@ -314,29 +317,106 @@ export function compareFile(relPath, baselineText, currentText) {
 }
 
 /**
- * Drop findings covered by baseline-side allow entries. `allow-added`
- * findings are never dropped — an exception cannot approve its own creation.
+ * Whether an allow entry's file and key cover a finding.
+ * @param {{ file: string, key: string }} entry An allow entry
+ * @param {Finding} finding A finding from the change
+ * @returns {boolean} True when the entry's scope reaches this finding
+ */
+function entryCovers(entry, finding) {
+  return (
+    (finding.file === entry.file || finding.file.endsWith(`/${entry.file}`)) &&
+    (entry.key === "*" || entry.key === finding.key)
+  );
+}
+
+/**
+ * Report the allow entries a human has to act on, whether or not this change
+ * touched anything they cover.
+ *
+ * Separate from {@link applyAllowList} because the two answer different
+ * questions and only one of them depends on the change under review. An
+ * exemption that has outlived its condition is dead weight the moment the
+ * condition passes — the way `_thresholdsDivergence` is stale the moment the
+ * two floors agree — and saying so is not conditional on anybody happening to
+ * touch the gate it covered.
+ * @param {Array<{ file: string, key: string, reason?: string, until?: unknown }>} allowEntries
+ *   The allow list being honoured
+ * @param {number} [now] Clock reading, injected so the check is deterministic
+ * @returns {string[]} One line per entry that is expired or unevaluable; empty
+ *   when every entry still names a condition that holds
+ */
+export function describeAllowList(allowEntries, now = Date.now()) {
+  const lines = [];
+  for (const entry of allowEntries) {
+    const { state, detail } = classifyAllowEntry(entry, now);
+    if (state !== ALLOW_STATE.LIVE) lines.push(detail);
+  }
+  return lines;
+}
+
+/**
+ * Drop findings covered by a LIVE baseline-side allow entry.
+ *
+ * Three ways a finding leaves here, and they are deliberately distinct:
+ *
+ *   allowed  a covering entry's condition still holds. Reported, not blocked —
+ *            a project mid-migration is not red-walled by expiry.
+ *   expired  every covering entry's condition has passed. The weakening the
+ *            entry used to permit is REFUSED again, and the refusal names the
+ *            entry, its scope, its reason and the remedy. An expiry that
+ *            lapsed into "allowed" would be worse than no expiry.
+ *   blocked  nothing covered it, or everything that covered it has expired.
+ *
+ * An entry whose condition nothing can evaluate counts as covering, so the
+ * allow list keeps working for entries written before `until` existed;
+ * `describeAllowList` reports those every run instead.
+ *
+ * `allow-added` findings are never dropped, by any entry in any state — an
+ * exception cannot approve its own creation, which is the baseline-side fence
+ * and is untouched here.
  * @param {Finding[]} findings All findings from the change
- * @param {Array<{ file: string, key: string }>} allowEntries Baseline
- *   (already-merged) allow list
- * @returns {{ blocked: Finding[], allowed: Finding[] }} Findings that still
- *   block vs. findings covered by a recorded exception
+ * @param {Array<{ file: string, key: string, reason?: string, until?: unknown }>} allowEntries
+ *   Baseline (already-merged) allow list
+ * @param {number} [now] Clock reading, injected so the check is deterministic
+ * @returns {{
+ *   blocked: Finding[],
+ *   allowed: Array<{ finding: Finding, entry: { file: string, key: string }, message: string }>,
+ *   expired: Array<{ finding: Finding, entry: { file: string, key: string }, message: string }>,
+ * }} Findings that still block, findings a live exemption covers, and the
+ *   refusals produced by exemptions that have ended
  */
-export function applyAllowList(findings, allowEntries) {
+export function applyAllowList(findings, allowEntries, now = Date.now()) {
+  const classified = allowEntries.map(entry => ({
+    entry,
+    ...classifyAllowEntry(entry, now),
+  }));
   const blocked = [];
   const allowed = [];
+  const expired = [];
   for (const finding of findings) {
-    const isAllowed =
-      finding.type !== "allow-added" &&
-      allowEntries.some(
-        e =>
-          (finding.file === e.file || finding.file.endsWith(`/${e.file}`)) &&
-          (e.key === "*" || e.key === finding.key)
-      );
-    if (isAllowed) allowed.push(finding);
-    else blocked.push(finding);
+    const covering =
+      finding.type === "allow-added"
+        ? []
+        : classified.filter(c => entryCovers(c.entry, finding));
+    const live = covering.find(c => c.state !== ALLOW_STATE.EXPIRED);
+    if (live) {
+      allowed.push({
+        finding,
+        entry: live.entry,
+        message: `allowed by ${live.scope}, which ${live.summary}. It covers: ${finding.message}`,
+      });
+      continue;
+    }
+    blocked.push(finding);
+    for (const dead of covering) {
+      expired.push({
+        finding,
+        entry: dead.entry,
+        message: `${dead.detail} It used to cover: ${finding.message}`,
+      });
+    }
   }
-  return { blocked, allowed };
+  return { blocked, allowed, expired };
 }
 
 /**
@@ -354,8 +434,9 @@ export function formatReport(findings) {
     "Quality thresholds are a one-way ratchet: they may tighten but never",
     "loosen. Fix the code so it meets the current gate instead of lowering the",
     "gate. If a human decides an exception is genuinely correct, they record it",
-    "in .lisa.config.json under thresholdRatchet.allow (with a reason) in a",
-    "separate human-approved change; this check honors exceptions only after",
-    "they are merged.",
+    "in .lisa.config.json under thresholdRatchet.allow — with a reason saying",
+    'what resolves it, and an "until": "YYYY-MM-DD" naming the day it is',
+    "reviewed — in a separate human-approved change; this check honors an",
+    "exception only after it is merged, and only until its until date passes.",
   ].join("\n");
 }

package/typescript/copy-overwrite/scripts/threshold-ratchet-families.mjs

@@ -382,8 +382,8 @@ export function extractK6Constraints(conf) {
 /**
  * Extract thresholdRatchet.allow entries from parsed .lisa.config.json.
  * @param {unknown} config Parsed config (may be undefined)
- * @returns {Array<{ file: string, key: string, reason?: string }>} The
- *   well-formed allow entries; malformed entries are dropped
+ * @returns {Array<{ file: string, key: string, reason?: string, until?: unknown }>}
+ *   The well-formed allow entries; malformed entries are dropped
  */
 export function extractAllowEntries(config) {
   const raw = config?.thresholdRatchet?.allow;
@@ -392,3 +392,131 @@ export function extractAllowEntries(config) {
     e => e && typeof e.file === "string" && typeof e.key === "string"
   );
 }
+
+/**
+ * The three states an allow entry's expiry condition can be in.
+ *
+ * THE DEFECT THESE EXIST FOR (#3856). An allow entry is the human-approved way
+ * for a weakening to pass the ratchet, and it had no expiry, no review and no
+ * removal path — nothing read the `reason`, so an exemption granted for a
+ * temporary condition (a migration in flight, a suite being rewritten, a
+ * dependency waiting upstream) outlived the condition and kept applying,
+ * silently, forever. The set of gates actually enforced therefore shrank
+ * monotonically while every individual decision that shrank it was correct at
+ * the time. A control whose exception list only grows converges on no control.
+ *
+ * The shape is taken from `_thresholdsDivergence` in `stryker.conf.json`,
+ * governed by `src/sync/stryker-thresholds-ownership.ts` — the one exemption
+ * surface in this repository that already stops exempting when it goes stale.
+ * Its three properties are reproduced here: the entry records its condition in
+ * a form something can evaluate, the reason says what resolves it, and once the
+ * condition passes the entry stops exempting AND says so, naming the remedy.
+ *
+ * `unchecked` is deliberately NOT `expired`. An entry written before `until`
+ * existed names a condition nothing can evaluate, which is the prose situation
+ * the ticket describes — it is reported every run, loudly, and it keeps
+ * exempting. Refusing it instead would red-wall every project mid-migration
+ * that carries a valid exception, which is the failure the ticket names as
+ * worse than the defect.
+ * @type {Readonly<Record<string, "live"|"expired"|"unchecked">>}
+ */
+export const ALLOW_STATE = Object.freeze({
+  LIVE: "live",
+  EXPIRED: "expired",
+  UNCHECKED: "unchecked",
+});
+
+/** A calendar condition, and the only shape `until` may take. */
+const ISO_DAY = /^(\d{4})-(\d{2})-(\d{2})$/u;
+
+/** An entry is live through the END of its named day, not up to its start. */
+const DAY_MS = 86_400_000;
+
+/**
+ * The instant an `until` condition stops holding.
+ *
+ * Round-tripped through `toISOString` on purpose: `Date.UTC` accepts
+ * out-of-range components and slides them, so `2026-02-31` would silently
+ * become March 3rd and `0099-01-01` would become 1999. An exemption dated a day
+ * that does not exist is a condition nobody can evaluate, and saying so is the
+ * honest answer — quietly moving it would hand the entry a different, longer
+ * life than the one written down.
+ * @param {unknown} until The entry's `until` field
+ * @returns {number | undefined} Epoch ms after which the entry has expired, or
+ *   undefined when `until` is not a calendar day anything can evaluate
+ */
+export function allowEntryExpiry(until) {
+  if (typeof until !== "string") return undefined;
+  const day = until.trim();
+  const match = ISO_DAY.exec(day);
+  if (!match) return undefined;
+  const midnight = Date.UTC(
+    Number(match[1]),
+    Number(match[2]) - 1,
+    Number(match[3])
+  );
+  if (new Date(midnight).toISOString().slice(0, 10) !== day) return undefined;
+  return midnight + DAY_MS;
+}
+
+/**
+ * Name an allow entry so a report says WHICH exemption it is talking about,
+ * and how much it covers.
+ *
+ * File-wide and key-scoped entries are spelled differently because they are
+ * different risks wearing the same shape: `key: "*"` turns off ratchet
+ * protection for every threshold in the file, and in a config diff that reads
+ * as one more approved exception.
+ * @param {{ file: string, key: string }} entry An allow entry, already
+ *   well-formed — `extractAllowEntries` is the only source of these
+ * @returns {string} Operator-readable identification of the entry
+ */
+export function describeAllowScope(entry) {
+  return entry.key === "*"
+    ? `thresholdRatchet.allow entry ${entry.file} → * (file-wide: every key in the file)`
+    : `thresholdRatchet.allow entry ${entry.file} → ${entry.key} (key-scoped)`;
+}
+
+/**
+ * Classify one allow entry's expiry condition, and say what to do about it.
+ * @param {{ file: string, key: string, reason?: unknown, until?: unknown }} entry
+ *   An allow entry
+ * @param {number} now Clock reading, injected so the check is deterministic
+ * @returns {{ state: "live"|"expired"|"unchecked", scope: string, summary: string, detail: string }}
+ *   The state, the entry's identification, a short phrase for a one-line
+ *   mention, and the full sentence naming the entry, its reason and the remedy
+ */
+export function classifyAllowEntry(entry, now) {
+  const scope = describeAllowScope(entry);
+  const because =
+    typeof entry.reason === "string" && entry.reason.trim() !== ""
+      ? ` Reason on record: ${entry.reason.trim()}`
+      : " No reason is recorded.";
+  const expiresAt = allowEntryExpiry(entry.until);
+  if (expiresAt === undefined) {
+    const summary = `names no condition anything can evaluate (until = ${JSON.stringify(entry.until ?? null)})`;
+    return {
+      state: ALLOW_STATE.UNCHECKED,
+      scope,
+      summary,
+      detail: `${scope} ${summary}, so nothing can ever end it. Give it "until": "YYYY-MM-DD" naming the day the exemption is reviewed, or delete it.${because}`,
+    };
+  }
+  const day = String(entry.until).trim();
+  if (now >= expiresAt) {
+    const summary = `expired after ${day}`;
+    return {
+      state: ALLOW_STATE.EXPIRED,
+      scope,
+      summary,
+      detail: `${scope} ${summary} and no longer exempts anything. Delete it, or record a fresh human-approved entry naming the new condition.${because}`,
+    };
+  }
+  const summary = `is live until ${day}`;
+  return {
+    state: ALLOW_STATE.LIVE,
+    scope,
+    summary,
+    detail: `${scope} ${summary}.`,
+  };
+}

package/typescript/create-only/.github/workflows/ci.yml

@@ -20,6 +20,13 @@ jobs:
       issues: read
     uses: CodySwannGT/lisa/.github/workflows/quality.yml@main
     with:
+      # Travels with the `uses:` line above — the two are one unit. Lisa's
+      # reusable workflows are tracked at `@main`, so that file changes under
+      # this repository with no pull request here. This is the contract major it
+      # spoke when Lisa seeded this file; the run fails loudly if it has since
+      # declared a break, and says NOT DETERMINED if this line goes missing
+      # (CodySwannGT/lisa#3698).
+      expected_workflow_contract_major: '1'
       node_version: '22.21.1'
       package_manager: 'bun'
       skip_jobs: ''