@codyswann/lisa 3.14.1 → 3.14.3

package/scripts/build-plugins.sh

@@ -12,6 +12,20 @@ SRC_DIR="$PLUGINS_DIR/src"
 # Read version from package.json so plugins stay in sync with Lisa releases
 VERSION=$(node -e "console.log(require('$ROOT_DIR/package.json').version)")
 
+# Materialize a Lisa-owned source file into a copy-overwrite/ template tree.
+#
+# Never a plain `cp`. These destinations are `copy-overwrite` assets, and a
+# `copy-overwrite` asset that reads as editable silently loses downstream
+# hardening on the next sync — already observed on block-no-verify.sh. They are
+# also the only assets that cannot carry a hand-typed ownership header, because
+# this script would erase it on the next build (#2547). So the header is stamped
+# here, as the file is generated: the authored source stays honest about being
+# editable, the shipped copy states that it is replaced, and the two cannot
+# disagree because one produces the other.
+materialize() {
+  node "$ROOT_DIR/scripts/materialize-copy-overwrite.mjs" "$1" "$2"
+}
+
 inject_version() {
   local manifest="$1"
   if [ -f "$manifest" ]; then
@@ -82,11 +96,12 @@ if [ -f "$SRC_DIR/base/hooks/threshold-ratchet.mjs" ]; then
     mkdir -p "$ratchet_scripts_dir"
     # The entry point takes the template check-* naming; its relative imports
     # (threshold-ratchet-*.mjs) keep their canonical names in both trees.
-    cp "$SRC_DIR/base/hooks/threshold-ratchet.mjs" \
+    materialize "$SRC_DIR/base/hooks/threshold-ratchet.mjs" \
       "$ratchet_scripts_dir/check-threshold-ratchet.mjs"
-    cp "$SRC_DIR/base/hooks/threshold-ratchet-families.mjs" \
-      "$SRC_DIR/base/hooks/threshold-ratchet-compare.mjs" \
-      "$ratchet_scripts_dir/"
+    for ratchet_module in threshold-ratchet-families threshold-ratchet-compare; do
+      materialize "$SRC_DIR/base/hooks/$ratchet_module.mjs" \
+        "$ratchet_scripts_dir/$ratchet_module.mjs"
+    done
   done
 fi
 
@@ -108,7 +123,7 @@ fi
 for guard in block-no-verify parity-safety-net block-shell-json-parsing \
   block-instruction-file-edits block-direct-issue-create; do
   if [ -f "$SRC_DIR/base/hooks/$guard.sh" ]; then
-    cp "$SRC_DIR/base/hooks/$guard.sh" "$HOST_GUARD_DIR/$guard.sh"
+    materialize "$SRC_DIR/base/hooks/$guard.sh" "$HOST_GUARD_DIR/$guard.sh"
     chmod +x "$HOST_GUARD_DIR/$guard.sh"
   fi
 done
@@ -122,7 +137,8 @@ done
 # guards are, not because it is dispatched the same way.
 if [ -f "$SRC_DIR/base/hooks/sonar-secrets.sh" ]; then
   mkdir -p "$HOST_GUARD_DIR"
-  cp "$SRC_DIR/base/hooks/sonar-secrets.sh" "$HOST_GUARD_DIR/sonar-secrets.sh"
+  materialize "$SRC_DIR/base/hooks/sonar-secrets.sh" \
+    "$HOST_GUARD_DIR/sonar-secrets.sh"
   chmod +x "$HOST_GUARD_DIR/sonar-secrets.sh"
 fi
 
@@ -132,7 +148,7 @@ fi
 # and an unconditional copy fails the whole build there.
 if [ -f "$ROOT_DIR/scripts/lisa-enforcement-fallback.sh" ]; then
   mkdir -p "$ROOT_DIR/all/copy-overwrite/scripts"
-  cp "$ROOT_DIR/scripts/lisa-enforcement-fallback.sh" \
+  materialize "$ROOT_DIR/scripts/lisa-enforcement-fallback.sh" \
     "$ROOT_DIR/all/copy-overwrite/scripts/lisa-enforcement-fallback.sh"
   chmod +x "$ROOT_DIR/all/copy-overwrite/scripts/lisa-enforcement-fallback.sh"
 fi

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/scripts/materialize-copy-overwrite.mjs

@@ -0,0 +1,163 @@
+#!/usr/bin/env node
+/**
+ * Copy a Lisa-owned file into a `copy-overwrite/` template tree, stamping the
+ * ownership header on the way in.
+ *
+ * Thirteen `copy-overwrite` assets are not authored where they ship. The build
+ * materializes them from `plugins/src/base/hooks/` (the five PreToolUse guards,
+ * the Sonar wrapper, the three threshold-ratchet modules into two stack lanes)
+ * and from `scripts/lisa-enforcement-fallback.sh` (the dispatcher). A header
+ * typed into the shipped copy is erased by the next `bun run build`, which is
+ * why those thirteen were the only files #2545 could not correct.
+ *
+ * The header cannot move upstream to the source either. `plugins/src/base/hooks/
+ * block-no-verify.sh` is precisely the file maintainers edit, so telling it that
+ * it will be overwritten would be a fresh instance of the false statement #2538
+ * exists to remove. So the header becomes a property of the *generation step*:
+ * the source stays honest, the shipped copy states its real contract, and the
+ * two can never disagree because one produces the other.
+ *
+ * This matters most on exactly these files. A `copy-overwrite` asset that reads
+ * as editable silently loses downstream hardening — a consumer repo hardened its
+ * `block-no-verify.sh` and the next sync reverted it, noticed only because two
+ * of its own tests started failing.
+ * @module scripts/materialize-copy-overwrite
+ */
+import { readFileSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+/**
+ * The `copy-overwrite` ownership contract, verbatim from the header #2545
+ * established. Duplicated nowhere: `tests/unit/templates/
+ * template-ownership-header.test.ts` asserts the same two sentences over every
+ * template in the lane, and this generator writes them into the thirteen that
+ * cannot hold a hand-typed copy.
+ */
+export const OWNERSHIP_HEADER = [
+  "This file is managed by Lisa and IS replaced on each `lisa` run.",
+  "Do not edit directly — durable changes belong upstream in Lisa.",
+];
+
+/**
+ * Line comment syntax per extension, for the formats this generator emits.
+ *
+ * Deliberately a closed map rather than a default. A file type that is not
+ * listed makes `materialize` throw, so wiring a new generated asset through
+ * here is a decision someone has to make — the alternative is a silent
+ * pass-through that reintroduces the headerless copy this module exists to end.
+ */
+const COMMENT_PREFIX = new Map([
+  [".sh", "#"],
+  [".bash", "#"],
+  [".mjs", "//"],
+  [".cjs", "//"],
+  [".js", "//"],
+]);
+
+/**
+ * The comment prefix a generated file's format uses.
+ * @param {string} filePath - Path whose extension selects the syntax.
+ * @returns {string | undefined} Prefix, or undefined when unsupported.
+ */
+export const commentPrefixFor = filePath =>
+  COMMENT_PREFIX.get(path.extname(filePath));
+
+/**
+ * The header block as it appears in a file of the given comment syntax.
+ * @param {string} prefix - Line comment prefix, e.g. `#` or `//`.
+ * @returns {string[]} The header lines, ready to splice in.
+ */
+const headerLines = prefix => OWNERSHIP_HEADER.map(line => `${prefix} ${line}`);
+
+/**
+ * Whether contents already state the ownership contract.
+ * @param {string} contents - File contents.
+ * @returns {boolean} True when every header sentence is present.
+ */
+export const hasOwnershipHeader = contents =>
+  OWNERSHIP_HEADER.every(line => contents.includes(line));
+
+/**
+ * Contents with the ownership header stamped in.
+ *
+ * Placement is not cosmetic: a `#!` line that stops being line 1 stops being a
+ * shebang, so the header lands *below* it when one is present. Idempotent, so
+ * re-running the build over an already-stamped tree is a no-op rather than a
+ * pile of headers.
+ * @param {string} contents - Source file contents.
+ * @param {string} filePath - Destination path, for its extension.
+ * @returns {string} Contents carrying the header.
+ * @throws {Error} When the destination's format has no known comment syntax.
+ */
+export const withOwnershipHeader = (contents, filePath) => {
+  const prefix = commentPrefixFor(filePath);
+  if (prefix === undefined) {
+    throw new Error(
+      `No comment syntax known for ${path.basename(filePath)} — a generated ` +
+        `copy-overwrite asset must be able to state its ownership contract.`
+    );
+  }
+  if (hasOwnershipHeader(contents)) return contents;
+
+  const lines = contents.split("\n");
+  const insertAt = lines[0]?.startsWith("#!") ? 1 : 0;
+  return [
+    ...lines.slice(0, insertAt),
+    ...headerLines(prefix),
+    "",
+    ...lines.slice(insertAt),
+  ].join("\n");
+};
+
+/**
+ * Contents with the ownership header removed, leaving the authored source.
+ *
+ * The byte-equality tests that pin a shipped copy to its reviewed original run
+ * through here, so "generated file minus its stamp" has exactly one definition
+ * and cannot drift from what the stamp step actually writes.
+ * @param {string} contents - Generated file contents.
+ * @param {string} filePath - Path, for its comment syntax.
+ * @returns {string} Contents without the header block.
+ */
+export const withoutOwnershipHeader = (contents, filePath) => {
+  const prefix = commentPrefixFor(filePath);
+  if (prefix === undefined) return contents;
+
+  const block = headerLines(prefix);
+  const lines = contents.split("\n");
+  const at = lines.findIndex(
+    (line, index) => line === block[0] && lines[index + 1] === block[1]
+  );
+  if (at === -1) return contents;
+
+  // The blank separator belongs to the stamp, not to the source, so it comes
+  // out with it — otherwise round-tripping would grow a line each build.
+  const end =
+    lines[at + block.length] === "" ? at + block.length + 1 : at + block.length;
+  return [...lines.slice(0, at), ...lines.slice(end)].join("\n");
+};
+
+/**
+ * Read a source file and write it to a destination carrying the header.
+ * @param {string} source - Authored file to materialize.
+ * @param {string} destination - Path inside a `copy-overwrite/` tree.
+ * @returns {void}
+ */
+export const materialize = (source, destination) => {
+  writeFileSync(
+    destination,
+    withOwnershipHeader(readFileSync(source, "utf8"), destination)
+  );
+};
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+  const [source, destination] = process.argv.slice(2);
+  if (!source || !destination) {
+    console.error(
+      "usage: materialize-copy-overwrite.mjs <source> <destination>"
+    );
+    process.exit(1);
+  }
+  materialize(source, destination);
+}

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

package/typescript/copy-overwrite/.github/GITHUB_ACTIONS.md

@@ -1,3 +1,6 @@
+<!-- This file is managed by Lisa and IS replaced on each `lisa` run. -->
+<!-- Do not edit directly — durable changes belong upstream in Lisa. -->
+
 # GitHub Actions Configuration
 
 This directory contains the CI/CD workflows and automation for the project. This document explains how to configure and use the GitHub Actions workflows.

package/typescript/copy-overwrite/ast-grep/rules/no-inline-component-in-container.yml

@@ -1,3 +1,6 @@
+# This file is managed by Lisa and IS replaced on each `lisa` run.
+# Do not edit directly — durable changes belong upstream in Lisa.
+
 id: no-inline-component-in-container
 language: tsx
 severity: error

package/typescript/copy-overwrite/ast-grep/rules/no-inline-component-in-view.yml

@@ -1,3 +1,6 @@
+# This file is managed by Lisa and IS replaced on each `lisa` run.
+# Do not edit directly — durable changes belong upstream in Lisa.
+
 id: no-inline-component-in-view
 language: tsx
 severity: error

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

@@ -1,4 +1,7 @@
 #!/usr/bin/env node
+// This file is managed by Lisa and IS replaced on each `lisa` run.
+// Do not edit directly — durable changes belong upstream in Lisa.
+
 /**
  * Threshold ratchet gate — quality thresholds may tighten, never weaken.
  *

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

@@ -1,3 +1,6 @@
+// This file is managed by Lisa and IS replaced on each `lisa` run.
+// Do not edit directly — durable changes belong upstream in Lisa.
+
 /**
  * Threshold ratchet — comparison rules and reporting.
  *

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

@@ -1,3 +1,6 @@
+// This file is managed by Lisa and IS replaced on each `lisa` run.
+// Do not edit directly — durable changes belong upstream in Lisa.
+
 /**
  * Threshold ratchet — watched file families and value extractors.
  *