@codyswann/lisa 4.27.4 → 4.27.6

package/scripts/lisa-enforcement-census.mjs

@@ -0,0 +1,168 @@
+#!/usr/bin/env node
+/**
+ * Fleet enforcement census — re-measures how many host checkouts resolve a
+ * Lisa enforcement guard, and reports it.
+ *
+ * The per-session staleness notice in `scripts/lisa-enforcement-fallback.sh`
+ * tells THIS session about THIS checkout, which is right and is not the gap.
+ * The gap is that nobody was looking at the fleet, so the only fleet-wide
+ * number that ever existed was taken by hand and frozen in a comment
+ * (CodySwannGT/lisa#3490). This runs the measurement again, every time.
+ *
+ * Two properties it must keep:
+ *
+ *   - It REPORTS. Its exit status is 0 for every finding about the fleet,
+ *     including a fleet where every checkout is stale. A census that could
+ *     redden someone's build would be routed around.
+ *   - It keeps "resolves nothing" apart from "resolves something old". They are
+ *     different failures with different remedies, and folding them loses the
+ *     serious half.
+ *
+ * Usage:
+ *   node scripts/lisa-enforcement-census.mjs [options]
+ *
+ * Options:
+ *   --roster <path>    Roster file (default: .lisa.workspaces.json beside this repo)
+ *   --scan <dir>       Also discover checkouts under <dir>. Repeatable.
+ *   --depth <n>        How deep --scan descends (default 2)
+ *   --reference <ver>  Compare against this version instead of the newest found
+ *   --redact           Replace real paths with stable anonymous labels
+ *   --json             Emit the measured fleet as JSON
+ *
+ * Exit status: 0 for every fleet finding. 1 only when an explicitly named
+ * roster cannot be read, and 2 for a usage error — both are failures of the
+ * census's own inputs, never findings about the fleet.
+ */
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const repoRoot = path.resolve(here, "..");
+
+const census = await import(
+  path.join(repoRoot, "dist", "core", "enforcement-census.js")
+).catch(error => {
+  process.stderr.write(
+    `Could not load the census from dist/. Run \`bun run build:dist\` first.\n${error.message}\n`
+  );
+  process.exit(2);
+});
+const report = await import(
+  path.join(repoRoot, "dist", "core", "enforcement-census-report.js")
+);
+
+const options = {
+  roster: null,
+  scans: [],
+  depth: 2,
+  reference: null,
+  redact: false,
+  json: false,
+};
+
+const argv = process.argv.slice(2);
+for (let index = 0; index < argv.length; index += 1) {
+  const flag = argv[index];
+  const value = argv[index + 1];
+  // A value-taking flag left at the end of the line has no value. Assigning
+  // `undefined` there silently falls back to the default roster or drops the
+  // requested setting, so the run measures something other than what was
+  // asked for and says nothing about it — a census reporting the wrong fleet
+  // is worse than one that refuses. This is the census's own input being
+  // wrong, so it exits 2 like any other usage error and never as a finding.
+  const VALUE_FLAGS = ["--roster", "--scan", "--depth", "--reference"];
+  if (VALUE_FLAGS.includes(flag) && value === undefined) {
+    process.stderr.write(`${flag} requires a value\n`);
+    process.exit(2);
+  }
+  if (flag === "--roster") {
+    options.roster = value;
+    index += 1;
+  } else if (flag === "--scan") {
+    options.scans.push(value);
+    index += 1;
+  } else if (flag === "--depth") {
+    options.depth = Number.parseInt(value ?? "", 10);
+    index += 1;
+  } else if (flag === "--reference") {
+    options.reference = value;
+    index += 1;
+  } else if (flag === "--redact") {
+    options.redact = true;
+  } else if (flag === "--json") {
+    options.json = true;
+  } else if (flag === "--help" || flag === "-h") {
+    process.stdout.write(
+      "Usage: node scripts/lisa-enforcement-census.mjs [--roster <path>] [--scan <dir>] [--depth <n>] [--reference <ver>] [--redact] [--json]\n"
+    );
+    process.exit(0);
+  } else {
+    process.stderr.write(`Unknown option: ${flag}\n`);
+    process.exit(2);
+  }
+}
+
+if (!Number.isInteger(options.depth) || options.depth < 0) {
+  process.stderr.write("--depth must be a non-negative integer\n");
+  process.exit(2);
+}
+
+const rosterPath =
+  options.roster ?? path.join(repoRoot, census.DEFAULT_ROSTER_FILE);
+const rosterEntries = await census.readFleetRoster(rosterPath);
+
+// An explicitly named roster that cannot be read is an input error, not a
+// finding: the operator asked for a specific file and did not get it. A missing
+// DEFAULT roster is neither — this repository is simply not a fleet hub — so it
+// reports an empty fleet and still exits 0.
+if (rosterEntries === null && options.roster !== null) {
+  process.stderr.write(`Could not read the roster: ${rosterPath}\n`);
+  process.exit(1);
+}
+
+const scanned = (
+  await Promise.all(
+    options.scans.map(directory =>
+      census.scanForCheckouts(directory, options.depth)
+    )
+  )
+).flat();
+
+const roster = await census.dedupeRoster([
+  ...(rosterEntries ?? []),
+  ...scanned,
+]);
+
+const origins = [
+  rosterEntries === null ? null : rosterPath,
+  ...options.scans.map(directory => `scan of ${directory}`),
+].filter(Boolean);
+
+const seedVersion = await import(path.join(repoRoot, "package.json"), {
+  with: { type: "json" },
+})
+  .then(module => module.default.version ?? null)
+  .catch(() => null);
+
+const measured = await census.runFleetCensus({
+  roster,
+  rosterOrigin: origins.length === 0 ? "no roster found" : origins.join(" + "),
+  seedVersion,
+  reference: options.reference,
+});
+
+const output = options.redact ? report.redactCensus(measured) : measured;
+
+process.stdout.write(
+  options.json
+    ? `${JSON.stringify(output, null, 2)}\n`
+    : report.renderFleetCensusReport(output)
+);
+
+// Unconditional. Nothing above may change it.
+//
+// Set rather than called: `process.exit()` tears the process down synchronously
+// and can drop a pending `process.stdout.write` when stdout is a pipe, which is
+// exactly how this is read — piped to a pager, a file, or a scheduled loop's
+// log. A truncated census reports a smaller fleet than it measured, silently.
+process.exitCode = 0;

package/scripts/lisa-enforcement-fallback.sh

@@ -404,10 +404,33 @@ fi
 #   - `main` cut 80 releases in 24 hours, median gap 10 minutes. "Behind the
 #     newest Lisa on this disk" is the DEFAULT state of a checkout within
 #     minutes of being cut, through nothing anyone did wrong.
-#   - Across the 27 host checkouts in this fleet, 12 resolve guards at all, and
-#     ALL TWELVE are behind or undateable. None is current. Eight carry no
-#     apply receipt; four are behind by a whole MAJOR (3.23.0, 3.23.1, 3.46.3,
-#     3.54.4 against 4.17.2).
+#   - Measured once across the host checkouts on one fleet: of those that
+#     resolved guards at all, every one was behind or undateable and none was
+#     current, several by a whole MAJOR — while a larger number resolved NO
+#     guard at all.
+#
+# That second reading used to be written here as a set of counts, and that was
+# the wrong place for it. A number in a comment is a measurement, not a monitor:
+# it was true on the day it was taken and nothing re-took it, so the drift after
+# that date was unobserved — which is the same defect the number documents. The
+# counts are therefore not restated here. Re-derive them:
+#
+# Run these FROM A LISA MONOREPO CHECKOUT — the census and the fleet roster are
+# Lisa-monorepo artifacts, and this comment travels into host projects where
+# neither exists. The script wrapper builds `dist/` first, which a fresh clone
+# does not have:
+#
+#   bun run lisa:enforcement-census              # roster on this machine
+#   bun run lisa:enforcement-census -- --redact  # safe to quote publicly
+#
+# In a host project the local half of the same question is `lisa doctor`, which
+# reports what THIS checkout resolves and needs no roster.
+#
+# The census reports and never gates, and it keeps "resolves NO guard" apart
+# from "resolves something old" — different failures, different remedies, and
+# folding them is what made the unenforced checkouts easy to miss
+# (CodySwannGT/lisa#3490). `lisa doctor` carries the same finding for the single
+# checkout it is run in.
 #
 # So no distance threshold rescues it — even the strictest version predicate is
 # permanently true across the fleet. The noise is the REPETITION, not the

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

@@ -87,6 +87,76 @@ if ! command -v node >/dev/null 2>&1; then
   echo "❌ Push blocked: Node.js is required to validate tracker work items."
   exit 1
 fi
+
+# BEGIN: push destination guard
+# ---------------------------------------------------------------------------
+# Refuse a push whose RESOLVED destination is a deploy branch it was not aimed
+# at.
+#
+# `push.default=upstream` (and its deprecated spelling `tracking`) resolves a
+# push's destination from the branch's UPSTREAM rather than from the branch
+# named on the command line. A working branch created the ordinary way —
+# `git checkout -b <branch> origin/main` — has `main` as its upstream, so the
+# ordinary `git push -u origin <branch>` resolves to `refs/heads/main` and lands
+# there. The push reports success. Branch protection and every required check
+# are bypassed, and the operator is told only afterwards, if at all
+# (CodySwannGT/lisa#3495).
+#
+# Measured in Lisa's own repository: two commits reached the default branch this
+# way. Every detection control afterwards fired correctly — the bypass was
+# reported, an agent force-push was refused, the release run was caught and
+# cancelled — and the commits shipped in a published release regardless, because
+# an ordinary unrelated merge cut a release before anyone could rewind. Nothing
+# had prevented the original push. That is why this is a refusal and not a
+# warning.
+#
+# WHY HERE, and not folded into a check that already exists.
+#
+# It reads the RESOLVED DESTINATION, in the third field of the stdin lines. That
+# is the only place in the system where the destination git actually chose is
+# observable; `push.default`, the branch's upstream and the command line are all
+# proxies for it, and the accident is precisely a disagreement between the
+# proxies and the answer. So the check has to live at the push moment, on this
+# stream.
+#
+# It is UNCONDITIONAL. The traceability step below stands down when a project
+# declares `gates.traceability`, and a guard a declaration can switch off is not
+# a guard against an accident. It also runs BELOW the deletion-only guard, which
+# exits first, so deleting a branch still needs no node.
+#
+# WHAT IT ALLOWS, deliberately: `main -> main`, so a merge landed locally still
+# pushes; a `HEAD` local ref, which is how git spells a destination the pusher
+# wrote out in full and how release automation pushes from a detached checkout;
+# and every push whose destination is not a deploy branch at all.
+#
+# READING THE STREAM SPENDS IT — the same constraint the deletion guard above
+# documents, and the same remedy: capture, use, replay with `exec <`. If no
+# scratch file can be created this stands down without reading a byte, leaving
+# the hook exactly as it was; a guard that cannot read the stream must not also
+# starve the checks that can.
+# ---------------------------------------------------------------------------
+#
+# The `-f` test is not belt and braces. This is now the FIRST thing in the file
+# to invoke the validator, so a checkout where no candidate path exists would
+# fail every push with a Node module-resolution error instead of the hook's own
+# message. Standing down leaves that diagnosis to the traceability step below,
+# which owns it and words it properly.
+LISA_DEST_REFS="$(mktemp "${TMPDIR:-/tmp}/lisa-dest-refs.XXXXXXXX")" || LISA_DEST_REFS=""
+if [ -n "$LISA_DEST_REFS" ] && [ -f "$WORK_ITEM_SCRIPT" ]; then
+  cat > "$LISA_DEST_REFS"
+  if ! node "$WORK_ITEM_SCRIPT" validate-push-destination "${1:-origin}" --refs "$LISA_DEST_REFS"; then
+    rm -f "$LISA_DEST_REFS"
+    exit 1
+  fi
+  # Put the stream back, byte for byte, for the validator and every gate below.
+  exec < "$LISA_DEST_REFS"
+  # Unlinked while the descriptor above is still open, so nothing is left in
+  # TMPDIR and no later `trap ... EXIT` in this file can drop the cleanup.
+  rm -f "$LISA_DEST_REFS"
+fi
+unset LISA_DEST_REFS
+# END: push destination guard
+
 # ---------------------------------------------------------------------------
 # Work-item traceability, at the push moment.
 #