@codyswann/lisa 4.45.2 → 4.45.4

package/scripts/check-typecheck-tests.mjs

@@ -27,6 +27,33 @@
  * threshold-ratchet as an `allow-list` family, so *adding* an entry is flagged
  * by a gate somebody already reads.
  *
+ * IT REFUSES TO ANSWER FROM AN UNRESOLVABLE TREE (CodySwannGT/lisa#3913). The
+ * second of those ratchet directions is the destructive one: it names files and
+ * tells a reader to delete their quarantine entries. With an empty
+ * `node_modules` the compiler cannot start, nothing is compiled, no diagnostic
+ * is parsed — and "no diagnostic for this file" is exactly the shape of "this
+ * file was fixed". The gate reported all 370 quarantined files as cleared and
+ * instructed their removal, which is a destructive edit ordered on the strength
+ * of a comparison whose inputs never resolved.
+ *
+ * So there are two ways this refuses instead of reporting, and the second is
+ * the general one:
+ *
+ *   - the compiler is not present at the path this spawns it from; and
+ *   - the compiler signalled failure and produced NOT ONE parseable
+ *     diagnostic, which also covers a broken tsconfig, an OOM and a crash.
+ *
+ * Both exit non-zero with the denial first and NO file list, because a gate
+ * whose only surface is an exit code cannot invent a third one — see
+ * `scripts/lib/dependency-tree.mjs` for why the wording is a contract rather
+ * than a string.
+ *
+ * `--root` EXISTS SO THIS CAN BE POINTED AT A FIXTURE. Deriving the root solely
+ * from `import.meta.url` made the failure above reproducible only by copying
+ * this file somewhere else, and `check-empty-subject-guards.mjs` reads that
+ * token out of this header to decide the gate is probeable at all — without it
+ * this sits in that sweep's declared blind spot.
+ *
  * WHAT IS DELIBERATELY NOT DONE HERE: the declared `lib` is not widened. tsc
  * emits "Try changing the 'lib' compiler option to 'es2023' or later" on the
  * ES2023 array APIs, and taking that suggestion would have erased the
@@ -38,110 +65,240 @@
 import { spawnSync } from "node:child_process";
 import { readFileSync } from "node:fs";
 import * as path from "node:path";
+import process from "node:process";
 import { fileURLToPath } from "node:url";
 
-const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
-const QUARANTINE = path.join(ROOT, "typecheck-quarantine.json");
-const PROJECT = path.join(ROOT, "tsconfig.tests.json");
+import {
+  cannotMeasure,
+  INSTALL_COMMAND,
+  missingDependencies,
+  ranVacuously,
+} from "./lib/dependency-tree.mjs";
+import { invokedAsScript } from "./lib/invoked-as-script.mjs";
+
+const DEFAULT_ROOT = path.resolve(
+  path.dirname(fileURLToPath(import.meta.url)),
+  ".."
+);
+
+/** The gate's name, as it prints in both the report and the refusal. */
+const GATE = "type-correctness (tests)";
+
+/** Where the compiler is spawned from, relative to the root. */
+const TSC = path.join("node_modules", "typescript", "bin", "tsc");
 
 /** Matches `path/to/file.ts(12,34): error TS1234: message`. */
 const ERROR_LINE = /^(?<file>[^(]+)\((?<line>\d+),\d+\): error (?<code>TS\d+):/;
 
 /**
  * Read the quarantined paths.
- * @returns {{files: string[], reason: string}} The parsed quarantine.
+ * @param {string} root - The directory holding the quarantine.
+ * @returns {{files: string[], reason: string} | null} The parsed quarantine, or
+ *   `null` when it could not be read — an unreadable list is a refusal, not a
+ *   pass, because that file is what makes this gate green.
  */
-function readQuarantine() {
+function readQuarantine(root) {
+  const quarantine = path.join(root, "typecheck-quarantine.json");
   try {
-    const parsed = JSON.parse(readFileSync(QUARANTINE, "utf-8"));
+    const parsed = JSON.parse(readFileSync(quarantine, "utf-8"));
     return { files: parsed.files ?? [], reason: parsed.reason ?? "" };
   } catch (error) {
     console.error(
-      `check-typecheck-tests: cannot read ${path.relative(ROOT, QUARANTINE)} — ${error.message}`
+      `check-typecheck-tests: cannot read ${path.relative(root, quarantine)} — ${error.message}`
     );
     console.error(
       "That file is what makes this gate green, so an unreadable one is a refusal, not a pass."
     );
-    process.exit(1);
+    return null;
   }
 }
 
-const { files: quarantined } = readQuarantine();
-const exempt = new Set(quarantined);
-
-const tsc = spawnSync(
-  process.execPath,
-  [
-    path.join(ROOT, "node_modules", "typescript", "bin", "tsc"),
-    "--noEmit",
-    "-p",
-    PROJECT,
-  ],
-  { cwd: ROOT, encoding: "utf-8", maxBuffer: 64 * 1024 * 1024 }
-);
-
-if (tsc.error) {
-  console.error(
-    `check-typecheck-tests: could not run tsc — ${tsc.error.message}`
-  );
-  process.exit(1);
+/**
+ * Parse tsc's output into a per-file error count.
+ * @param {string} output - Combined stdout and stderr.
+ * @returns {Map<string, number>} Errors keyed by forward-slashed path.
+ */
+function parseDiagnostics(output) {
+  /** @type {Map<string, number>} */
+  const errorsByFile = new Map();
+  for (const line of output.split("\n")) {
+    const match = ERROR_LINE.exec(line.trim());
+    if (!match?.groups) continue;
+    const file = match.groups.file.replace(/\\/g, "/");
+    errorsByFile.set(file, (errorsByFile.get(file) ?? 0) + 1);
+  }
+  return errorsByFile;
 }
 
-const lines = `${tsc.stdout ?? ""}\n${tsc.stderr ?? ""}`.split("\n");
-/** @type {Map<string, number>} */
-const errorsByFile = new Map();
-for (const line of lines) {
-  const match = ERROR_LINE.exec(line.trim());
-  if (!match?.groups) continue;
-  const file = match.groups.file.replace(/\\/g, "/");
-  errorsByFile.set(file, (errorsByFile.get(file) ?? 0) + 1);
+/**
+ * The refusal issued when nothing was compiled.
+ *
+ * The denial names the destructive remedy explicitly. "Nothing type-checked" is
+ * the inference a reader draws from an empty diagnostic set, and the gate's own
+ * cleared-entry message is what turns that inference into a deletion — so this
+ * has to deny both, not just the first.
+ *
+ * NO FILE IS NAMED HERE, deliberately. A list of paths is what makes the
+ * destructive message actionable, and a refusal that still printed 370 paths
+ * would be followed exactly as often as the finding it replaces.
+ *
+ * @param {string} because - Why the measurement could not happen.
+ * @param {number} quarantined - How many entries went unexamined.
+ * @param {string} fix - The action that repairs THIS cause. Named per call
+ *   site rather than fixed, because telling someone to install dependencies
+ *   they already have is how a refusal gets dismissed as noise.
+ * @returns {string} The refusal block.
+ */
+function refuseUnmeasurable(because, quarantined, fix) {
+  return cannotMeasure({
+    gate: GATE,
+    denial: `that any of the ${quarantined} quarantined file(s) now type-check`,
+    because,
+    remedy:
+      `${fix} Do NOT edit typecheck-quarantine.json on the strength of ` +
+      `this — no file was compiled, so nothing was established about any ` +
+      `entry in it.`,
+  });
 }
 
-const offenders = [...errorsByFile.keys()]
-  .filter(file => !exempt.has(file))
-  .sort();
-const cleared = quarantined.filter(file => !errorsByFile.has(file)).sort();
+/**
+ * Run the gate.
+ * @param {string} root - Directory to resolve the project and quarantine under.
+ * @returns {number} The process exit code.
+ */
+export function main(root) {
+  const quarantine = readQuarantine(root);
+  if (quarantine === null) return 1;
+  const quarantined = quarantine.files;
+  const exempt = new Set(quarantined);
 
-const totalErrors = [...errorsByFile.values()].reduce((sum, n) => sum + n, 0);
-console.log(
-  `type-correctness (tests): ${errorsByFile.size} file(s) with ${totalErrors} error(s); ` +
-    `${quarantined.length} quarantined.`
-);
+  // PRECONDITION. Checked before the spawn rather than inferred from it: the
+  // spawn SUCCEEDS with an empty `node_modules` — node starts, and it is node
+  // that cannot find the module — so `tsc.error` never fires and the failure
+  // arrives as an empty diagnostic set indistinguishable from a clean run.
+  const missing = missingDependencies(root, [TSC]);
+  if (missing.length > 0) {
+    console.error(
+      refuseUnmeasurable(
+        `the TypeScript compiler is not installed — no file at ${missing[0]}.`,
+        quarantined.length,
+        `Run \`${INSTALL_COMMAND}\`, then re-run this gate.`
+      )
+    );
+    return 1;
+  }
 
-if (offenders.length > 0) {
-  console.error("");
-  console.error(
-    `❌ ${offenders.length} file(s) outside the quarantine have type errors:`
+  const tsc = spawnSync(
+    process.execPath,
+    [
+      path.join(root, TSC),
+      "--noEmit",
+      "-p",
+      path.join(root, "tsconfig.tests.json"),
+    ],
+    { cwd: root, encoding: "utf-8", maxBuffer: 64 * 1024 * 1024 }
   );
-  for (const file of offenders) {
-    console.error(`   ${file} (${errorsByFile.get(file)})`);
+
+  if (tsc.error) {
+    console.error(
+      `check-typecheck-tests: could not run tsc — ${tsc.error.message}`
+    );
+    return 1;
   }
-  console.error("");
-  console.error(
-    "Fix them. Do NOT add them to typecheck-quarantine.json — that list"
-  );
-  console.error(
-    "only shrinks, and the threshold-ratchet flags additions to it."
-  );
-}
 
-if (cleared.length > 0) {
-  console.error("");
-  console.error(
-    `❌ ${cleared.length} quarantined file(s) now type-check and must leave the list:`
+  const errorsByFile = parseDiagnostics(
+    `${tsc.stdout ?? ""}\n${tsc.stderr ?? ""}`
   );
-  for (const file of cleared) console.error(`   ${file}`);
-  console.error("");
-  console.error(
-    "Remove them from typecheck-quarantine.json. A list that keeps entries"
+
+  // POSTCONDITION, and the general form of the same defect. The compiler
+  // signalled failure and produced nothing this gate can read, so the
+  // comparison below would run against an empty set — the exact shape of "every
+  // quarantined file is fixed". A ZERO exit with no diagnostics is not this: it
+  // is a clean run, and it reports normally.
+  if (ranVacuously(tsc.status, errorsByFile.size)) {
+    const firstLine = `${tsc.stderr ?? ""}${tsc.stdout ?? ""}`
+      .split("\n")
+      .map(line => line.trim())
+      .find(Boolean);
+    console.error(
+      refuseUnmeasurable(
+        `tsc exited ${tsc.status} without emitting one diagnostic this gate ` +
+          `could parse, so the comparison had no subject.` +
+          `${firstLine ? ` First output line: ${firstLine}` : ""}`,
+        quarantined.length,
+        "Fix the cause named above, then re-run this gate."
+      )
+    );
+    return 1;
+  }
+
+  const offenders = [...errorsByFile.keys()]
+    .filter(file => !exempt.has(file))
+    .sort();
+  const cleared = quarantined.filter(file => !errorsByFile.has(file)).sort();
+
+  const totalErrors = [...errorsByFile.values()].reduce((sum, n) => sum + n, 0);
+  console.log(
+    `${GATE}: ${errorsByFile.size} file(s) with ${totalErrors} error(s); ` +
+      `${quarantined.length} quarantined.`
   );
-  console.error(
-    "after they are fixed would re-authorise them if they ever regressed."
+
+  if (offenders.length > 0) {
+    console.error("");
+    console.error(
+      `❌ ${offenders.length} file(s) outside the quarantine have type errors:`
+    );
+    for (const file of offenders) {
+      console.error(`   ${file} (${errorsByFile.get(file)})`);
+    }
+    console.error("");
+    console.error(
+      "Fix them. Do NOT add them to typecheck-quarantine.json — that list"
+    );
+    console.error(
+      "only shrinks, and the threshold-ratchet flags additions to it."
+    );
+  }
+
+  if (cleared.length > 0) {
+    console.error("");
+    console.error(
+      `❌ ${cleared.length} quarantined file(s) now type-check and must leave the list:`
+    );
+    for (const file of cleared) console.error(`   ${file}`);
+    console.error("");
+    console.error(
+      "Remove them from typecheck-quarantine.json. A list that keeps entries"
+    );
+    console.error(
+      "after they are fixed would re-authorise them if they ever regressed."
+    );
+  }
+
+  if (offenders.length > 0 || cleared.length > 0) return 1;
+
+  console.log(
+    "✅ No type errors outside the quarantine, and no stale quarantine entries."
   );
+  return 0;
 }
 
-if (offenders.length > 0 || cleared.length > 0) process.exit(1);
+/**
+ * Resolve the root from `--root <dir>`, defaulting to the repository.
+ * @param {ReadonlyArray<string>} argv - Arguments after the script name.
+ * @returns {string} The absolute root.
+ */
+export function rootFrom(argv) {
+  const flag = argv.indexOf("--root");
+  if (flag === -1) return DEFAULT_ROOT;
+  const value = argv[flag + 1];
+  if (value === undefined) {
+    console.error("check-typecheck-tests: --root requires a value");
+    process.exit(2);
+  }
+  return path.resolve(value);
+}
 
-console.log(
-  "✅ No type errors outside the quarantine, and no stale quarantine entries."
-);
+if (invokedAsScript(import.meta.url)) {
+  process.exit(main(rootFrom(process.argv.slice(2))));
+}

package/scripts/lib/dependency-tree.mjs

@@ -0,0 +1,136 @@
+/**
+ * dependency-tree — decide whether a gate's dependency tree is resolvable, and
+ * say "cannot measure" in one voice when it is not (CodySwannGT/lisa#3913).
+ *
+ * @remarks
+ * ## The defect this exists for
+ *
+ * The `type-correctness` gate spawns the compiler by PATH:
+ * `node node_modules/typescript/bin/tsc`. With an empty `node_modules` the
+ * SPAWN still succeeds — node starts, and it is node that then cannot find the
+ * module — so the gate's `if (tsc.error)` guard does not fire. node's
+ * "Cannot find module" goes to stderr and does not match the gate's
+ * `file(line,col): error TSxxxx:` pattern, so the parsed-diagnostics map comes
+ * back EMPTY. Every quarantined file then satisfies "has no errors", and the
+ * gate reports:
+ *
+ * ```
+ * ❌ 370 quarantined file(s) now type-check and must leave the list:
+ * Remove them from typecheck-quarantine.json.
+ * ```
+ *
+ * Following that deletes 370 live quarantine entries on the word of a checker
+ * that compiled nothing. The comparison was not wrong — it was correct about an
+ * input it was never entitled to accept.
+ *
+ * ## Why "cannot measure" is a THIRD outcome, not a failure message
+ *
+ * This is the #3888 family: a control that could not establish its subject must
+ * not render identically to one that established it and found nothing. The
+ * sibling exemplar is the review gate's `UNDETERMINED` verdict in
+ * `check-skipped-required-checks.mjs`, whose own comment states the rule this
+ * module follows — resolving an unestablished subject to `success` "would be a
+ * new instance of exactly that".
+ *
+ * A gate whose only surface is an exit code cannot emit a third code that
+ * anything reads, so the fallback is fixed: **fail closed, with the denial as
+ * the first clause.** Never pass. A reader who skims one line must come away
+ * knowing the finding was NOT made, because the natural inference from silence
+ * about errors is that there were none.
+ *
+ * ## The message contract
+ *
+ * {@link cannotMeasure} takes the clauses rather than a finished string so that
+ * no call site can ship three of the four. Every message names:
+ *
+ *  1. the outcome, in a distinct word (`CANNOT MEASURE`);
+ *  2. the inference a reader would otherwise draw, DENIED in words;
+ *  3. why the measurement could not happen;
+ *  4. what to do — including, where one exists, the destructive remedy that
+ *     must NOT be followed.
+ *
+ * Clause 2 is the one that is easy to drop and the only one that stops a
+ * destructive edit, so it is a required parameter.
+ *
+ * @module scripts/lib/dependency-tree
+ */
+import { existsSync } from "node:fs";
+import path from "node:path";
+
+/** The install command that repairs an unresolvable tree. */
+export const INSTALL_COMMAND = "bun install --frozen-lockfile";
+
+/**
+ * The distinct outcome word. Deliberately not "ERROR" or "FAILED": those are
+ * what the gate prints when it DID measure and found something, which is the
+ * confusion this whole module exists to prevent.
+ */
+export const CANNOT_MEASURE = "CANNOT MEASURE";
+
+/**
+ * Names the dependencies a gate needs that are not present under `root`.
+ *
+ * Presence is tested at the exact path the gate will spawn or import, not by
+ * asking whether `node_modules` exists. A partially installed tree — the case
+ * that produced the `knip` sibling of this defect, where `node_modules` was
+ * present but two binaries were not — has a `node_modules` directory and still
+ * cannot answer the question.
+ *
+ * @param {string} root - Directory the gate resolves dependencies against.
+ * @param {ReadonlyArray<string>} relativePaths - Paths under `root` to require,
+ *   each already spelled the way the gate will use it.
+ * @returns {string[]} The missing paths, in the order given.
+ */
+export function missingDependencies(root, relativePaths) {
+  return relativePaths.filter(
+    relative => !existsSync(path.join(root, relative))
+  );
+}
+
+/**
+ * True when a child process signalled failure without producing anything the
+ * caller could read as a finding.
+ *
+ * This is the general form of the defect, and it catches more than an empty
+ * `node_modules`: a broken `tsconfig`, an out-of-memory compiler, a crash. The
+ * three cases are distinguishable in principle and identical in what they
+ * license — nothing.
+ *
+ * The one ambiguous input resolves the safe way. If a compiler ever emitted
+ * real diagnostics in a format the caller's pattern did not match, this reports
+ * "could not measure" rather than "no errors" — and "I could not read the
+ * output" is the honest account of that too.
+ *
+ * A zero exit with no diagnostics is NOT this: that is a clean run, and the
+ * caller is entitled to report it.
+ *
+ * @param {number | null} status - The child's exit status.
+ * @param {number} findingCount - How many findings the caller parsed out.
+ * @returns {boolean} Whether the run was vacuous.
+ */
+export function ranVacuously(status, findingCount) {
+  return status !== 0 && findingCount === 0;
+}
+
+/**
+ * Builds the operator-readable `CANNOT MEASURE` block.
+ *
+ * Returned rather than printed so callers can route it to stderr, a report, or
+ * a test assertion without this module deciding.
+ *
+ * @param {object} clauses - The four required clauses.
+ * @param {string} clauses.gate - The gate's own name, as it prints elsewhere.
+ * @param {string} clauses.denial - What this is NOT reporting, phrased as the
+ *   inference a reader would otherwise draw. Required: it is the clause that
+ *   stops a destructive edit.
+ * @param {string} clauses.because - Why the measurement could not happen.
+ * @param {string} clauses.remedy - What the reader should do instead.
+ * @returns {string} The block, newline-separated, no trailing newline.
+ */
+export function cannotMeasure({ gate, denial, because, remedy }) {
+  return [
+    `${CANNOT_MEASURE} — ${gate} did not run, and is NOT reporting ${denial}.`,
+    `Why: ${because}`,
+    `Do this: ${remedy}`,
+  ].join("\n");
+}

package/typescript/copy-contents/.husky/pre-push

@@ -126,6 +126,51 @@ if ! command -v jq >/dev/null 2>&1; then
   exit 1
 fi
 
+# The DEPENDENCY TREE is proved here too, for the same reason and one worse
+# consequence (CodySwannGT/lisa#3913).
+#
+# Every gate below resolves its tool out of `node_modules` — knip, vitest, tsc.
+# An empty tree does not stop those gates; it makes them answer from nothing,
+# and an empty answer is not silent. Upstream, the `type-correctness` gate is
+# what showed this belongs here rather than inside each gate: with no compiler
+# to run it parsed zero diagnostics, concluded from that emptiness that every
+# quarantined file now compiles, and instructed a reader to delete the
+# quarantine entries protecting them — a destructive edit ordered by a control
+# whose inputs never resolved. Its sibling `knip:check` reports unlisted
+# binaries from the identical cause. That one merely LOOKS odd and nobody acts
+# on it, which is exactly why it went unfixed while the dangerous one hid
+# behind it.
+#
+# So this is not a convenience check for a missing install. Absence of the
+# dependencies and absence of findings must not produce the same observable. A
+# check that cannot RUN is not a skip and not a pass — it blocks.
+if [ -f package.json ]; then
+  LISA_DECLARED_DEPS="$(jq -r '((.dependencies // {}) + (.devDependencies // {})) | length' package.json 2>/dev/null)"
+  # A non-numeric or absent answer counts as zero: this guard may not be the
+  # thing that blocks a push over an unreadable package.json.
+  case "$LISA_DECLARED_DEPS" in
+    "" | *[!0-9]*) LISA_DECLARED_DEPS=0 ;;
+  esac
+  # `ls -A` covers absent and present-but-empty in one test, which is the
+  # distinction the gates themselves cannot make.
+  if [ "$LISA_DECLARED_DEPS" -gt 0 ] && [ -z "$(ls -A node_modules 2>/dev/null)" ]; then
+    echo "❌ Push blocked: CANNOT MEASURE — dependencies are not installed."
+    echo ""
+    echo "   package.json declares $LISA_DECLARED_DEPS dependencies and node_modules is"
+    echo "   absent or empty, so the gates below cannot resolve the tools they"
+    echo "   run: tsc, knip and vitest."
+    echo ""
+    echo "   This is NOT a finding about your code, and nothing below it is"
+    echo "   either."
+    echo ""
+    echo "To fix:"
+    echo "  bun install --frozen-lockfile   # or your package manager's equivalent"
+    echo ""
+    exit 1
+  fi
+  unset LISA_DECLARED_DEPS
+fi
+
 # BEGIN: push destination guard
 # ---------------------------------------------------------------------------
 # Refuse a push whose RESOLVED destination is a deploy branch it was not aimed