@codyswann/lisa 3.14.2 → 3.14.3

package/scripts/check-derived-artifacts.mjs

@@ -0,0 +1,237 @@
+#!/usr/bin/env node
+/**
+ * Fail a commit whose generated artifacts no longer vouch for the bytes beside
+ * them.
+ *
+ * Lisa has two artifacts derived from tracked sources:
+ *
+ * - `src/core/upstream-evidence-manifest.ts`, regenerated by
+ *   `bun run build:upstream-evidence-manifest`
+ * - `src/core/lisa-owned-hash-ledger.ts`, regenerated by
+ *   `bun run build:lisa-owned-hash-ledger`
+ *
+ * Each already has a suite-level guard, but the suite is the slow and late place
+ * to learn it. CodySwannGT/lisa#2557 is what that costs: three branches, each
+ * green on its own, combined into a red `main` that only failed in a post-merge
+ * Release run. The second obligation was days old and in nobody's checklist, and
+ * the measured pattern in this repository is that executable controls hold where
+ * prose does not — so this is the control, at the earliest point that can name
+ * the command to run.
+ *
+ * **This script verifies nothing itself.** It delegates to each generator's own
+ * `--check`, which is the point: a second implementation of "is the artifact
+ * current" would be a second thing to keep in step. The two checks deliberately
+ * assert different properties, and both are correct for their artifact:
+ *
+ * - The manifest hashes tracked files with no history walk, so a fresh
+ *   regeneration is byte-reproducible anywhere and byte-identity is a fair test.
+ * - The ledger walks history, whose result depends on clone depth and merge
+ *   topology. It therefore asserts only that the bytes shipped *right now* are
+ *   recorded — the property that actually protects refresh. Asserting
+ *   byte-identity there made a correct ledger fail once `autoupdate` merged
+ *   `main` in (CodySwannGT/lisa#2556), and at this repository's concurrency that
+ *   would mean every merge reddens every open PR. Do not tighten it back.
+ *
+ * Both triggers below are deliberate **supersets** of what each artifact covers.
+ * Re-deriving exact membership here would create a second copy of the rule that
+ * could drift and silently stop firing; over-triggering only costs a few seconds
+ * on a commit that owed nothing, which is the safe direction to be wrong in.
+ * @module scripts/check-derived-artifacts
+ */
+import { execFileSync } from "node:child_process";
+import path from "node:path";
+import process from "node:process";
+import { fileURLToPath } from "node:url";
+
+const repoRoot = path.resolve(import.meta.dirname, "..");
+
+/**
+ * Path prefixes whose contents the upstream evidence manifest hash-pins.
+ *
+ * Mirrors `packagedEvidencePrefixes` in
+ * `scripts/generate-upstream-evidence-manifest.mjs`. The duplication is
+ * deliberate: that script runs top-level code which refuses to load outside the
+ * canonical repository, so it cannot be imported for its constant. A test
+ * asserts the two lists agree, the same arrangement `isLisaOwned` already uses
+ * in the ledger generator.
+ * @type {readonly string[]}
+ */
+export const PACKAGED_EVIDENCE_PREFIXES = Object.freeze([
+  "plugins/src/",
+  "all/",
+  "cdk/",
+  "expo/",
+  "eslint-plugin-code-organization/",
+  "eslint-plugin-component-structure/",
+  "eslint-plugin-phaser/",
+  "eslint-plugin-ui-standards/",
+  "harper-fabric/",
+  "nestjs/",
+  "npm-package/",
+  "oxlint/",
+  "phaser/",
+  "rails/",
+  "scripts/",
+  "tsconfig/",
+  "typescript/",
+  "ui/",
+]);
+
+/** Marker separating a template's source location from its installed path. */
+const COPY_OVERWRITE = "/copy-overwrite/";
+
+/**
+ * Whether this change can move the bytes of a template the ledger vouches for.
+ *
+ * Every ledger source lives under a `copy-overwrite` directory, so the marker is
+ * a superset of the `lisa-` namespace the ledger actually records. Matching the
+ * broader set means a template that is renamed *into* the namespace, or added to
+ * it later, still trips the gate.
+ * @param {readonly string[]} stagedPaths - Repo-relative staged paths
+ * @returns {boolean} True when the ledger check is owed
+ */
+export function requiresLedgerCheck(stagedPaths) {
+  return stagedPaths.some(staged => staged.includes(COPY_OVERWRITE));
+}
+
+/**
+ * Whether this change touches a path the evidence manifest hash-pins.
+ * @param {readonly string[]} stagedPaths - Repo-relative staged paths
+ * @returns {boolean} True when the manifest check is owed
+ */
+export function requiresManifestCheck(stagedPaths) {
+  return stagedPaths.some(staged =>
+    PACKAGED_EVIDENCE_PREFIXES.some(prefix => staged.startsWith(prefix))
+  );
+}
+
+/**
+ * Repo-relative paths staged for the pending commit.
+ *
+ * Renames report their destination (`-M` plus `--diff-filter=R`), and deletions
+ * are included because removing a template is also a way to move what the
+ * artifacts describe.
+ * @returns {string[]} Staged paths, empty when git cannot be consulted
+ */
+export function stagedPaths() {
+  try {
+    return execFileSync(
+      "git",
+      ["diff", "--cached", "--name-only", "--diff-filter=ACMRD"],
+      { cwd: repoRoot, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }
+    )
+      .split("\n")
+      .filter(Boolean);
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * The human-readable half of a generator's failure output.
+ *
+ * A generator that reports by throwing prints a Node stack trace around its
+ * message. The frames are noise to the person being blocked — and this gate is
+ * read by operators who did not write either generator — so keep the lines that
+ * say what is wrong and drop the ones that say where the throw was.
+ * @param {string} raw - Combined stdout and stderr from the generator
+ * @returns {string} Message lines, stack frames removed
+ */
+export function readableFailure(raw) {
+  const lines = raw.split("\n");
+  // Node prints `<file>:<line>`, the offending source line, then a caret, before
+  // the message itself. Everything through the caret is the code frame.
+  const caret = lines.findIndex(line => /^\s*\^+\s*$/u.test(line));
+  return lines
+    .slice(caret + 1)
+    .filter(line => !/^\s+at\s/u.test(line))
+    .filter(line => !line.startsWith("Node.js v"))
+    .map(line => line.replace(/^Error:\s*/u, "").trimEnd())
+    .filter(Boolean)
+    .join("\n")
+    .trim();
+}
+
+/**
+ * Run one generator's `--check` and report whether it passed.
+ * @param {string} script - Repo-relative generator path
+ * @returns {{ok: boolean, output: string}} Result and any diagnostic output
+ */
+function runCheck(script) {
+  try {
+    execFileSync(process.execPath, [script, "--check"], {
+      cwd: repoRoot,
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+    return { ok: true, output: "" };
+  } catch (error) {
+    const stderr = error?.stderr ?? "";
+    const stdout = error?.stdout ?? "";
+    return { ok: false, output: readableFailure(`${stdout}${stderr}`) };
+  }
+}
+
+/**
+ * The artifacts this gate knows how to check, in the order they are reported.
+ * @type {readonly {name: string, script: string, command: string, trigger: (paths: readonly string[]) => boolean}[]}
+ */
+const ARTIFACTS = Object.freeze([
+  Object.freeze({
+    name: "upstream evidence manifest",
+    script: "scripts/generate-upstream-evidence-manifest.mjs",
+    command: "bun run build:upstream-evidence-manifest",
+    trigger: requiresManifestCheck,
+  }),
+  Object.freeze({
+    name: "Lisa-owned hash ledger",
+    script: "scripts/generate-lisa-owned-hash-ledger.mjs",
+    command: "bun run build:lisa-owned-hash-ledger",
+    trigger: requiresLedgerCheck,
+  }),
+]);
+
+/**
+ * Check every artifact this commit owes and describe any that are stale.
+ * @param {readonly string[]} staged - Repo-relative staged paths
+ * @returns {string[]} One remediation block per stale artifact
+ */
+export function staleArtifacts(staged) {
+  const failures = [];
+  for (const artifact of ARTIFACTS) {
+    if (!artifact.trigger(staged)) continue;
+    const result = runCheck(artifact.script);
+    if (result.ok) continue;
+    failures.push(
+      `${artifact.name} is stale.\n` +
+        `${result.output ? `${result.output}\n` : ""}` +
+        `  Fix: ${artifact.command}\n` +
+        `  Then: git add the regenerated file and commit again.`
+    );
+  }
+  return failures;
+}
+
+/** Run the gate over the staged change and exit non-zero when anything is stale. */
+function main() {
+  const staged = stagedPaths();
+  const failures = staleArtifacts(staged);
+  if (failures.length === 0) {
+    process.stdout.write("Generated artifacts are current.\n");
+    return;
+  }
+  process.stderr.write(
+    `\nA generated artifact no longer matches the sources in this commit:\n\n${failures.join(
+      "\n\n"
+    )}\n\n` +
+      `Both artifacts are regenerated from the working tree, so run the command\n` +
+      `above AFTER staging, and again after any reformat, then amend.\n` +
+      `If the stale file is one you did not touch, an unstaged local edit to a\n` +
+      `tracked file can also trip this — commit or revert it first.\n`
+  );
+  process.exit(1);
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+  main();
+}

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

@@ -129,4 +129,20 @@ fi
 # Run lint-staged for incremental lint and format checks
 echo "🚀 Running lint-staged..."
 $EXECUTOR lint-staged --config .lintstagedrc.json
+LINT_STAGED_STATUS=$?
+if [ $LINT_STAGED_STATUS -ne 0 ]; then
+  exit $LINT_STAGED_STATUS
+fi
+
+# Generated artifacts must vouch for the bytes committed beside them. Runs AFTER
+# lint-staged on purpose: reformatting a staged template moves its bytes, so a
+# check placed above would sign off on bytes that no longer exist. Absent in host
+# projects, which have the hook but none of Lisa's generators.
+if [ -f "scripts/check-derived-artifacts.mjs" ] && command -v node >/dev/null 2>&1; then
+  echo "🧾 Checking generated artifacts..."
+  node scripts/check-derived-artifacts.mjs --staged
+  if [ $? -ne 0 ]; then
+    exit 1
+  fi
+fi
 # END: AI GUARDRAILS