@codyswann/lisa 4.45.14 → 4.45.15

package/scripts/run-artifact-checks.mjs

@@ -0,0 +1,215 @@
+#!/usr/bin/env node
+/**
+ * Run the generated-artifact sub-checks and end with the FAILING one's words.
+ *
+ * `check:artifacts` runs six sub-checks in sequence and keeps going after one
+ * fails, which is correct — an operator wants every problem in one attempt, not
+ * one per attempt. The cost was that the failing sub-check's own diagnostic was
+ * then buried under the output of every sub-check that passed AFTER it, and the
+ * last thing printed before the summary belonged to an unrelated check that had
+ * nothing wrong with it.
+ *
+ * Measured on `origin/main` at 4.45.10 (CodySwannGT/lisa#3876). A commit whose
+ * staged bytes `lint-staged` reformatted was refused, and this is what the
+ * operator saw at the bottom of the transcript:
+ *
+ * ```
+ * $ node scripts/check-generated-artifact-merge-coverage.mjs
+ * generated-artifact merge coverage: 4 artifact(s) declared, 2 merge-driver …
+ * check:artifacts FAILED, and these are the checks that failed: upstream-evidence-manifest
+ * ```
+ *
+ * Forty lines above it, unread, the failing check had already said the whole
+ * answer — the file whose bytes moved, the cause, and both commands:
+ *
+ * ```
+ * Error: src/core/upstream-evidence-manifest.ts is stale.
+ *   Its inputs moved after it was generated. …
+ *   At commit time lint-staged reformats every staged file BEFORE this
+ *   check runs, so a manifest generated first is stale by the time it is
+ *   checked. Regenerate now, after the reformat.
+ * ```
+ *
+ * The diagnosis was never the problem. Its POSITION was. The ticket's own note
+ * records the consequence: identifying the failing sub-check by exit code
+ * before reading anything had become "the reliable habit", which is a habit an
+ * operator should not need.
+ *
+ * So the ordering is inverted here: every passing sub-check's output first, the
+ * failing ones last, then the summary. Nothing is dropped and nothing is
+ * printed twice — the same bytes, in the order that puts the answer where a
+ * reader looks.
+ *
+ * ## Why the check names stay in `package.json`
+ *
+ * They are passed in as arguments rather than listed in this file, and that is
+ * load-bearing rather than stylistic. `undeclaredChecks` in
+ * `check-generated-artifact-merge-coverage.mjs` reads the `check:artifacts`
+ * SCRIPT BODY with `/\bcheck:[a-z0-9-]+/gu` and fails when a name appears there
+ * that no artifact declares. Moving the list in here would leave that regex
+ * matching nothing at all: the guard would pass, having examined an empty set,
+ * and a seventh sub-check could join `check:artifacts` unannounced. A guard
+ * that reports success by looking at nothing is the exact defect this
+ * repository keeps finding, so the list stays where its guard can see it.
+ * @module scripts/run-artifact-checks
+ */
+
+import process from "node:process";
+
+import { boundedSpawnSync, isChildTimeout } from "./lib/bounded-spawn.mjs";
+import { invokedAsScript } from "./lib/invoked-as-script.mjs";
+
+/**
+ * How long one sub-check may run before the result is a timeout, not a verdict.
+ *
+ * Far above the work rather than near it. The whole aggregate completes in
+ * seconds on an idle box; this budget exists so that a sub-check killed on a
+ * saturated host is reported as KILLED rather than as a check that failed — a
+ * killed `spawnSync` child returns EMPTY streams, so without this the failure
+ * arrives looking exactly like a content problem and never mentions time.
+ */
+export const CHECK_BUDGET_MS = 900_000;
+
+/** Printed immediately before the failing sub-checks' own output. */
+export const FAILURE_HEADER =
+  "── below: what the check that FAILED actually said ──";
+
+/** Said instead of an empty block when a failing sub-check printed nothing. */
+export const NO_OUTPUT_NOTE =
+  "  (this check produced no output at all — it did not merely fail its " +
+  "content check. A killed child returns empty streams, so treat an empty " +
+  "block as a possible kill rather than as a silent refusal.)";
+
+/** Said when a sub-check exceeded its budget rather than reaching a verdict. */
+export const TIMEOUT_NOTE =
+  "  (this check exceeded its time budget and was killed. It reached no " +
+  "verdict, so nothing above is evidence about the artifacts.)";
+
+/**
+ * Run one sub-check and capture everything it said.
+ * @param {string} name - Package script name, e.g. `check:lisa-owned-hash-ledger`
+ * @returns {{name: string, ok: boolean, timedOut: boolean, output: string}} What it did and said.
+ */
+export function runCheck(name) {
+  try {
+    // `--silent` because bun otherwise echoes `$ <command>` to STDERR while
+    // the check writes its findings to STDOUT. Capturing both and printing
+    // them in stream order puts every banner after the output it introduces,
+    // which reads as though each check were labelled with its neighbour's
+    // name. The label this file prints is accurate by construction instead.
+    const result = boundedSpawnSync("bun", ["run", "--silent", name], {
+      encoding: "utf8",
+      timeout: CHECK_BUDGET_MS,
+    });
+    const output = `${result.stdout ?? ""}${result.stderr ?? ""}`;
+    return { name, ok: result.status === 0, timedOut: false, output };
+  } catch (error) {
+    if (isChildTimeout(error)) {
+      return { name, ok: false, timedOut: true, output: "" };
+    }
+    throw error;
+  }
+}
+
+/**
+ * The transcript, in the order that puts the answer where a reader looks.
+ *
+ * Passing sub-checks first, failing ones last, summary at the very end. A
+ * reader who scrolls to the bottom — which is every reader of a refused commit
+ * — lands on the check that has something to say rather than on one that does
+ * not.
+ * @param {Array<{name: string, ok: boolean, timedOut: boolean, output: string}>} results - One record per sub-check, in the order they ran
+ * @returns {{lines: string[], exitCode: number}} What to print, and what to exit with.
+ */
+export function renderReport(results) {
+  const failures = results.filter(result => !result.ok);
+  const passed = results.filter(result => result.ok);
+  const passedLines = passed.flatMap(result => [
+    `▸ ${result.name}`,
+    ...trimmedLines(result.output),
+  ]);
+
+  if (failures.length === 0) {
+    return {
+      lines: [
+        ...passedLines,
+        `check:artifacts OK - all ${String(results.length)} generated-artifact checks passed.`,
+      ],
+      exitCode: 0,
+    };
+  }
+
+  const failureLines = failures.flatMap(result => [
+    "",
+    `▸ ${result.name}`,
+    ...describeFailure(result),
+  ]);
+
+  return {
+    lines: [
+      ...passedLines,
+      "",
+      FAILURE_HEADER,
+      ...failureLines,
+      "",
+      `check:artifacts FAILED, and these are the checks that failed: ${failures
+        .map(result => result.name.replace(/^check:/u, ""))
+        .join(" ")}`,
+    ],
+    exitCode: 1,
+  };
+}
+
+/**
+ * What one failing sub-check contributes to the report.
+ *
+ * An empty capture is NEVER rendered as an empty block. Two different events
+ * produce one — a check that printed nothing, and a child killed before it
+ * could print — and a blank gap reads as neither.
+ * @param {{timedOut: boolean, output: string}} result - One failing sub-check's record
+ * @returns {string[]} Its output, or the note that explains the absence of any.
+ */
+function describeFailure(result) {
+  if (result.timedOut) return [TIMEOUT_NOTE];
+  const lines = trimmedLines(result.output);
+  return lines.length === 0 ? [NO_OUTPUT_NOTE] : lines;
+}
+
+/**
+ * One captured stream as lines, without the trailing blank a final newline adds.
+ * @param {string} output - Captured combined output
+ * @returns {string[]} Its lines, empty when it said nothing.
+ */
+function trimmedLines(output) {
+  const trimmed = output.replace(/\n+$/u, "");
+  return trimmed === "" ? [] : trimmed.split("\n");
+}
+
+/**
+ * Run every named sub-check and report.
+ * @param {string[]} names - Package script names to run, in order
+ * @param {(name: string) => {name: string, ok: boolean, timedOut: boolean, output: string}} [run] - Injected runner, for tests
+ * @returns {{lines: string[], exitCode: number}} What to print, and what to exit with.
+ */
+export function runArtifactChecks(names, run = runCheck) {
+  return renderReport(names.map(name => run(name)));
+}
+
+if (invokedAsScript(import.meta.url)) {
+  const names = process.argv.slice(2);
+  if (names.length === 0) {
+    // Refused rather than reported OK. An aggregate handed nothing to run
+    // would otherwise print "all 0 generated-artifact checks passed", which is
+    // the shape of every control in this repository that reported success
+    // having examined nothing.
+    console.error(
+      "run-artifact-checks.mjs: no checks were named, so nothing was run.\n" +
+        "  This cannot pass by inspecting nothing. Pass the package script\n" +
+        "  names to run, as `check:artifacts` in package.json does."
+    );
+    process.exit(1);
+  }
+  const { lines, exitCode } = runArtifactChecks(names);
+  console.log(lines.join("\n"));
+  process.exit(exitCode);
+}

package/typescript/copy-contents/.husky/post-merge

@@ -0,0 +1,114 @@
+# Report generated-artifact staleness the moment a MERGE creates it.
+#
+# WHY THIS HOOK EXISTS AT ALL
+#
+# `git merge` does not run `pre-commit`. Measured against a throwaway
+# repository with all five hooks installed and echoing their own name
+# (CodySwannGT/lisa#3876):
+#
+#   plain commit  → pre-commit, prepare-commit-msg, commit-msg, post-commit
+#   git merge     → prepare-commit-msg, commit-msg, post-merge
+#
+# `pre-commit` is absent from the merge line, and it is the hook that runs the
+# gate registry at the `commit` moment. So a project declaring
+# `artifact-freshness` at `commit` has that gate skipped by exactly the event
+# most likely to stale a generated artifact: a merge that moves the tracked
+# files the artifact derives from.
+#
+# The staleness was still caught — by the pre-push suite, roughly ten minutes
+# later, after the branch had been worked on further. The ticket measured three
+# such stalls on one branch in one session, about thirty minutes of gate time
+# for a change whose own tests were green throughout. The regeneration takes
+# seconds. The cost is entirely in the finding out.
+#
+# `post-merge` is the one hook git DOES run there, and nothing in Lisa had ever
+# used it.
+#
+# WHY IT REPORTS AND NEVER BLOCKS
+#
+# There is nothing left to block. The merge commit already exists by the time
+# this runs, and git ignores this hook's exit code entirely — so a non-zero exit
+# would buy no enforcement and would only look like one. This hook exists to
+# move a discovery earlier, not to add a gate. The gates at commit, push and
+# pull-request are unchanged and still refuse.
+#
+# WHY IT ASKS THE REGISTRY RATHER THAN NAMING A COMMAND
+#
+# Which files are generated is project-specific, which is why
+# `artifact-freshness` ships `declareOnly`. Hard-coding `check:artifacts` here
+# would name a script most projects do not have and would run one project's
+# prover in every project. Instead this asks the gate registry what THIS
+# project declared, and stands down in silence when the answer is nothing —
+# which is the correct answer for a project that has no generated artifacts.
+#
+# A `post-merge` MOMENT in the registry proper was considered and is the purer
+# shape: a gate would then declare that it runs here, the way it declares
+# `commit`. It is not done in this change because a new moment touches the
+# moment vocabulary, validation, the runner, doctor, and their suites — a
+# larger change than the discovery-timing defect being fixed. This hook reuses
+# the declaration a project already made instead of inventing a second place to
+# declare it.
+
+# CI merges through the forge, not through a working copy, and the gates run
+# there in their own right. Running this there would add seconds to every job
+# to re-report something a required check already refuses.
+if [ -n "${CI:-}" ]; then
+  exit 0
+fi
+
+LISA_GATES="node_modules/@codyswann/lisa/all/copy-overwrite/scripts/lisa-gates.mjs"
+if [ ! -f "$LISA_GATES" ]; then
+  LISA_GATES="scripts/lisa-gates.mjs"
+fi
+if [ ! -f "$LISA_GATES" ]; then
+  LISA_GATES="all/copy-overwrite/scripts/lisa-gates.mjs"
+fi
+
+if [ ! -f "$LISA_GATES" ] || ! command -v node >/dev/null 2>&1; then
+  exit 0
+fi
+
+# The earliest moment the project declares this gate at, because the property
+# is one property and its prover does not change with the moment. A project
+# that declares it only at `pull-request` still wants to know now.
+LISA_ARTIFACT_CHECK=""
+for LISA_MOMENT in commit push pull-request; do
+  LISA_ARTIFACT_CHECK="$(
+    node "$LISA_GATES" list --moment="$LISA_MOMENT" 2>/dev/null |
+      awk '$2 == "artifact-freshness" { $1 = ""; $2 = ""; sub(/^[[:space:]]+/, ""); print; exit }'
+  )"
+  if [ -n "$LISA_ARTIFACT_CHECK" ]; then
+    break
+  fi
+done
+
+if [ -z "$LISA_ARTIFACT_CHECK" ]; then
+  exit 0
+fi
+
+if sh -c "$LISA_ARTIFACT_CHECK" >/dev/null 2>&1; then
+  exit 0
+fi
+
+echo ""
+echo "⚠️  This merge left a generated artifact stale."
+echo ""
+echo "   The merge moved tracked files that a generated artifact derives from,"
+echo "   so the artifact now describes bytes that are no longer there. Nothing"
+echo "   is blocked yet — but the commit, push and pull-request gates will all"
+echo "   refuse until it is regenerated, and the push gate is the expensive"
+echo "   place to find out."
+echo ""
+echo "   Not every merge does this. This one did."
+echo ""
+echo "   See what is stale:"
+echo "     $LISA_ARTIFACT_CHECK"
+echo ""
+echo "   Then regenerate, in that order, AFTER 'git add' of the real changes —"
+echo "   the generators read TRACKED files, so regenerating first silently"
+echo "   omits whatever the commit is about to add."
+echo ""
+
+# Deliberately zero. See "WHY IT REPORTS AND NEVER BLOCKS" above: git ignores
+# this exit code, so a non-zero one would be a refusal that refuses nothing.
+exit 0

package/typescript/copy-overwrite/scripts/lisa-mutation.mjs

@@ -1341,14 +1341,67 @@ const dryRunTimeoutVerdict = budgets => ({
     "   needs longer on this machine; investigate a hang if it does not.",
 });
 
+/**
+ * How many scored ranges the verdict lists before it stops naming them.
+ *
+ * The list is what makes the verdict self-identifying, so it has to be long
+ * enough to recognise the change by and short enough that nobody scrolls past
+ * the verdict to reach it.
+ * @type {number}
+ */
+const SCORED_RANGES_LISTED = 10;
+
+/**
+ * What this run scored, in the run's own terms.
+ *
+ * ## Why a verdict has to name its subject
+ *
+ * CodySwannGT/lisa#3878. The parser tests feed this module Stryker's exact
+ * wording, and when the unit suite runs inside a push the vendor's line reaches
+ * the same transcript a real gate writes to. Three readers in a row read a
+ * FIXTURE line as a real verdict about their branch and went off to strengthen
+ * tests for a score nothing had measured. Nothing in the vendor's wording says
+ * which run produced it, and no amount of care fixes that from the reading end.
+ *
+ * The discriminator that survives a wording edit is not a marker anyone has to
+ * spot: it is that a real verdict can name the ranges it scored and a stand-in
+ * transcript cannot, because a stand-in never scoped a change. So the verdict
+ * carries its own subject, and a reader's test becomes "does this name MY
+ * files?" rather than "does this look real?".
+ * @param {readonly string[]|null|undefined} scored - Scored `path:start-end`
+ *   ranges, `null` for a whole-list run that scoped no diff, or `undefined`
+ *   from a caller that is not the gate and therefore knows of no subject.
+ * @returns {string} The block naming the subject, or "" when it is unknown.
+ */
+const scoredSubjectNote = scored => {
+  if (scored === null) {
+    return (
+      `\n   Scored: every pattern in the project's mutate list ` +
+      `(${WHOLE_LIST_FLAG}), not a diff.`
+    );
+  }
+  // Not reachable from the gate, which always knows its scope. It IS reachable
+  // from a direct call to the exported classifier, and inventing a subject
+  // there would be the same lie in the other direction.
+  if (!Array.isArray(scored) || scored.length === 0) return "";
+  const listed = scored.slice(0, SCORED_RANGES_LISTED);
+  const rest =
+    scored.length > listed.length
+      ? `\n     …and ${scored.length - listed.length} more`
+      : "";
+  const lines = listed.map(range => `     • ${range}`).join("\n");
+  return `\n   Scored ${scored.length} changed line range(s) from THIS change:\n${lines}${rest}`;
+};
+
 /**
  * The block printed when a completed run scored under `thresholds.break`.
  * @param {readonly string[]} broke - `[, score, threshold]` from Stryker.
  * @param {string} output - Stryker's combined output.
  * @param {{timeoutMS: number, inherited: string[]}} budgets - Budgets in force.
+ * @param {readonly string[]|null|undefined} scored - What the run scored.
  * @returns {{outcome: string, message: string}} The marker and the block.
  */
-const scoreBelowBreakVerdict = (broke, output, budgets) => {
+const scoreBelowBreakVerdict = (broke, output, budgets, scored) => {
   const timedOut = timedOutMutants(output);
   const clockNote =
     timedOut > 0
@@ -1363,7 +1416,7 @@ const scoreBelowBreakVerdict = (broke, output, budgets) => {
     `   threshold of ${broke[2]}. This one IS a verdict about your tests.`;
   return {
     outcome: OUTCOMES.scoreBelowBreak,
-    message: `${verdict}${clockNote}`,
+    message: `${verdict}${clockNote}${scoredSubjectNote(scored)}`,
   };
 };
 
@@ -1417,9 +1470,12 @@ const runFailedVerdict = (output, budgets) => {
  *   when this machine could not capture it.
  * @param {{timeoutMS: number, dryRunTimeoutMinutes: number,
  *   inherited: string[]}} budgets - From `resolveTimeoutBudgets`.
+ * @param {readonly string[]|null} [scored] - What the run scored: the
+ *   `path:start-end` ranges, or `null` for a whole-list run. Passed by the gate
+ *   so the verdict names its own subject; see {@link scoredSubjectNote}.
  * @returns {{outcome: string, message: string}} The marker and the block.
  */
-export const classifyStrykerFailure = (output, budgets) => {
+export const classifyStrykerFailure = (output, budgets, scored) => {
   if (typeof output !== "string" || output.length === 0) {
     return runFailedVerdict(null, budgets);
   }
@@ -1427,7 +1483,7 @@ export const classifyStrykerFailure = (output, budgets) => {
     return dryRunTimeoutVerdict(budgets);
   }
   const broke = BREAK_THRESHOLD_PATTERN.exec(output);
-  if (broke) return scoreBelowBreakVerdict(broke, output, budgets);
+  if (broke) return scoreBelowBreakVerdict(broke, output, budgets, scored);
   return runFailedVerdict(output, budgets);
 };
 
@@ -2311,9 +2367,11 @@ export const WHOLE_LIST_FLAG = "--all";
  * failed on. See {@link timeoutAccounting}.
  * @param {string} cwd - Project root.
  * @param {{code: number, output: string|null, killedBy?: string}} result - From `runStryker`.
+ * @param {readonly string[]|null} [scored] - What the run scored, forwarded to
+ *   the failure classification so the verdict names its own subject.
  * @returns {{code: number, measured: boolean}} The exit code and whether a score was produced.
  */
-export const reportRun = (cwd, result) => {
+export const reportRun = (cwd, result, scored) => {
   const accounting = accountForTimeouts(result.output, cwd);
   if (result.killedBy === CHILD_DEADLINE) {
     // A gate that ran and failed measured something; a gate that was KILLED
@@ -2330,7 +2388,8 @@ export const reportRun = (cwd, result) => {
     // guess — which it did, out loud, as "mutation score below threshold", for
     // dry runs that never computed a score at all.
     console.error(
-      classifyStrykerFailure(result.output, resolveTimeoutBudgets(cwd)).message
+      classifyStrykerFailure(result.output, resolveTimeoutBudgets(cwd), scored)
+        .message
     );
     // A failure that produced no table produced no score either — a dry run
     // killed by the clock is the common case — so the unmeasured warning would
@@ -2424,7 +2483,7 @@ export const runGate = (cwd = process.cwd(), argv = []) => {
       `🧬 ${OUTCOMES.wholeList} — Stryker over every pattern in ` +
         `${declaration.source}, with no diff scoping.`
     );
-    const reported = reportRun(cwd, runStryker(cwd, []));
+    const reported = reportRun(cwd, runStryker(cwd, []), null);
     return finish(OUTCOMES.wholeList, reported.code, reported.measured);
   }
 
@@ -2537,7 +2596,11 @@ export const runGate = (cwd = process.cwd(), argv = []) => {
   );
   for (const file of scope.selected) console.log(`   • ${file}`);
 
-  const reported = reportRun(cwd, runStryker(cwd, scope.selected));
+  const reported = reportRun(
+    cwd,
+    runStryker(cwd, scope.selected),
+    scope.selected
+  );
   return finish(OUTCOMES.scoped, reported.code, reported.measured);
 };