@codyswann/lisa 4.22.6 → 4.22.7

package/scripts/check-release-package-identity.mjs

@@ -0,0 +1,319 @@
+#!/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.
+
+/**
+ * Fail closed when a release checkout or packed npm candidate does not bind to
+ * one immutable version and commit.
+ *
+ * Release workflows have two separate state transitions: standard-version
+ * writes and pushes the release commit, then npm builds and publishes a tagged
+ * checkout. A tag aimed at the pre-release merge let the second transition
+ * compile stale generated source and only afterwards rewrite package.json. This
+ * checker makes both boundaries executable: `checkout` proves tag/HEAD/commit
+ * identity before build, and `pack` proves the exact tarball passed to
+ * `npm publish` contains matching package metadata and generated certificate.
+ *
+ * Projects without Lisa's nightly certificate still receive the generic
+ * version/commit/tarball checks. When the source certificate exists, its built
+ * and packed counterpart becomes mandatory.
+ * @module scripts/check-release-package-identity
+ */
+import { createHash } from "node:crypto";
+import {
+  appendFileSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  readdirSync,
+} from "node:fs";
+import path from "node:path";
+import process from "node:process";
+
+import { boundedExecFileSync } from "./lib/bounded-spawn.mjs";
+import { invokedAsScript } from "./lib/invoked-as-script.mjs";
+
+const RELEASE_COMMIT_PATTERN = /^[a-f0-9]{40}$/u;
+const SOURCE_CERTIFICATE = "src/core/nightly-e2e-guard-behavior-certificate.ts";
+const PACKED_CERTIFICATE =
+  "package/dist/core/nightly-e2e-guard-behavior-certificate.js";
+
+/** Raise one consistently named fail-closed identity error. */
+function mismatch(message) {
+  throw new Error(`Release package identity mismatch: ${message}`);
+}
+
+/** Return a required CLI option. */
+function requiredOption(argv, name) {
+  const index = argv.indexOf(name);
+  const value = index >= 0 ? argv[index + 1] : undefined;
+  if (!value || value.startsWith("--")) mismatch(`missing required ${name}`);
+  return value;
+}
+
+/** Resolve one git revision to its immutable commit. */
+function gitCommit(root, revision) {
+  try {
+    return String(
+      boundedExecFileSync("git", ["rev-parse", `${revision}^{commit}`], {
+        cwd: root,
+        encoding: "utf8",
+      })
+    ).trim();
+  } catch {
+    mismatch(`could not resolve git revision ${revision}`);
+  }
+}
+
+/** Parse one JSON file with a release-specific diagnostic. */
+function readJson(filePath, label) {
+  try {
+    return JSON.parse(readFileSync(filePath, "utf8"));
+  } catch {
+    mismatch(`${label} is missing or invalid JSON (${filePath})`);
+  }
+}
+
+/** SHA-256 for an immutable file or member. */
+function sha256(bytes) {
+  return createHash("sha256").update(bytes).digest("hex");
+}
+
+/** Read one tar member without extracting paths into the checkout. */
+function tarMember(tarballPath, member) {
+  try {
+    return Buffer.from(
+      boundedExecFileSync("tar", ["-xOf", tarballPath, member])
+    );
+  } catch {
+    mismatch(`packed candidate does not contain ${member}`);
+  }
+}
+
+/** Extract the one workspace package version certified by generated bytes. */
+function certificateVersion(bytes, label) {
+  const match = String(bytes).match(
+    /workspace package @codyswann\/lisa@([^\s"'()]+)\s*\(/u
+  );
+  if (!match?.[1]) mismatch(`${label} has no workspace package provenance`);
+  return match[1];
+}
+
+/** Require a valid immutable release commit spelling. */
+export function assertReleaseCommit(releaseCommit) {
+  if (!RELEASE_COMMIT_PATTERN.test(releaseCommit)) {
+    mismatch(
+      `release commit must be 40 lowercase hexadecimal characters; got ${JSON.stringify(releaseCommit)}`
+    );
+  }
+  return releaseCommit;
+}
+
+/**
+ * Prove that the checked-out tag and HEAD name the supplied release commit.
+ * @param {{root: string, releaseCommit: string, tag: string}} input Identity input
+ * @returns {{headCommit: string, tagCommit: string, releaseCommit: string}}
+ */
+export function assertCheckoutIdentity({ root, releaseCommit, tag }) {
+  assertReleaseCommit(releaseCommit);
+  const headCommit = gitCommit(root, "HEAD");
+  if (headCommit !== releaseCommit) {
+    mismatch(
+      `HEAD ${headCommit} does not match release commit ${releaseCommit}`
+    );
+  }
+  const tagCommit = gitCommit(root, tag);
+  if (tagCommit !== releaseCommit) {
+    mismatch(`tag ${tag} resolves ${tagCommit}, expected ${releaseCommit}`);
+  }
+  return Object.freeze({ headCommit, tagCommit, releaseCommit });
+}
+
+/**
+ * Pack and validate the exact candidate later passed to npm publish.
+ * @param {{root: string, version: string, releaseCommit: string, packDestination: string}} input Candidate input
+ * @returns {{version: string, releaseCommit: string, certificateVersion: string|null, tarballPath: string, tarballSha256: string, certificateMemberSha256: string|null}}
+ */
+export function packAndValidateReleaseCandidate({
+  root,
+  version,
+  releaseCommit,
+  packDestination,
+}) {
+  assertReleaseCommit(releaseCommit);
+  const packageJson = readJson(path.join(root, "package.json"), "package.json");
+  if (packageJson.version !== version) {
+    mismatch(
+      `package.json version ${JSON.stringify(packageJson.version)} expected ${version}`
+    );
+  }
+  if (packageJson.lisaReleaseCommit !== releaseCommit) {
+    mismatch(
+      `package.json lisaReleaseCommit ${JSON.stringify(packageJson.lisaReleaseCommit)} expected ${releaseCommit}`
+    );
+  }
+  if (packageJson.gitHead !== releaseCommit) {
+    mismatch(
+      `package.json gitHead ${JSON.stringify(packageJson.gitHead)} expected ${releaseCommit}`
+    );
+  }
+
+  const sourceCertificatePath = path.join(root, SOURCE_CERTIFICATE);
+  const hasCertificate = existsSync(sourceCertificatePath);
+  if (hasCertificate) {
+    const sourceVersion = certificateVersion(
+      readFileSync(sourceCertificatePath),
+      "source certificate"
+    );
+    if (sourceVersion !== version) {
+      mismatch(
+        `source certificate names ${sourceVersion}, expected ${version}`
+      );
+    }
+  }
+
+  mkdirSync(packDestination, { recursive: true });
+  if (readdirSync(packDestination).length !== 0) {
+    mismatch(`pack destination must be empty (${packDestination})`);
+  }
+  let packOutput;
+  try {
+    packOutput = String(
+      boundedExecFileSync(
+        "npm",
+        [
+          "pack",
+          "--ignore-scripts",
+          "--silent",
+          "--pack-destination",
+          packDestination,
+        ],
+        { cwd: root, encoding: "utf8", timeout: 120_000 }
+      )
+    );
+  } catch (error) {
+    mismatch(
+      `npm pack failed before publication (${error instanceof Error ? error.message : String(error)})`
+    );
+  }
+  const candidates = readdirSync(packDestination).filter(file =>
+    file.endsWith(".tgz")
+  );
+  if (candidates.length !== 1) {
+    mismatch("npm pack did not report exactly one candidate tarball");
+  }
+  const reportedCandidate = packOutput
+    .split(/\r?\n/u)
+    .map(line => line.trim())
+    .filter(Boolean)
+    .at(-1);
+  if (path.basename(reportedCandidate ?? "") !== candidates[0]) {
+    mismatch(
+      `npm pack reported ${JSON.stringify(reportedCandidate)}, wrote ${JSON.stringify(candidates[0])}`
+    );
+  }
+
+  const tarballPath = path.resolve(packDestination, candidates[0]);
+  const tarballBytes = readFileSync(tarballPath);
+  const packedPackage = JSON.parse(
+    String(tarMember(tarballPath, "package/package.json"))
+  );
+  if (packedPackage.version !== version) {
+    mismatch(
+      `packed package version ${JSON.stringify(packedPackage.version)} expected ${version}`
+    );
+  }
+  if (packedPackage.lisaReleaseCommit !== releaseCommit) {
+    mismatch(
+      `packed lisaReleaseCommit ${JSON.stringify(packedPackage.lisaReleaseCommit)} expected ${releaseCommit}`
+    );
+  }
+  if (packedPackage.gitHead !== releaseCommit) {
+    mismatch(
+      `packed gitHead ${JSON.stringify(packedPackage.gitHead)} expected ${releaseCommit}`
+    );
+  }
+
+  let packedCertificateVersion = null;
+  let certificateMemberSha256 = null;
+  if (hasCertificate) {
+    const member = tarMember(tarballPath, PACKED_CERTIFICATE);
+    packedCertificateVersion = certificateVersion(member, "packed certificate");
+    if (packedCertificateVersion !== version) {
+      mismatch(
+        `packed certificate names ${packedCertificateVersion}, expected ${version} at release commit ${releaseCommit} (${PACKED_CERTIFICATE})`
+      );
+    }
+    certificateMemberSha256 = sha256(member);
+  }
+
+  return Object.freeze({
+    version,
+    releaseCommit,
+    certificateVersion: packedCertificateVersion,
+    tarballPath,
+    tarballSha256: sha256(tarballBytes),
+    certificateMemberSha256,
+  });
+}
+
+/** Append validated tarball identity to a GitHub Actions step output. */
+function writeGithubOutput(result, outputPath) {
+  if (!outputPath) return;
+  if (result.tarballPath.includes("\n") || result.tarballPath.includes("\r")) {
+    mismatch("candidate tarball path contains a line break");
+  }
+  appendFileSync(
+    outputPath,
+    [
+      `tarball=${result.tarballPath}`,
+      `tarball_sha256=${result.tarballSha256}`,
+      `certificate_member_sha256=${result.certificateMemberSha256 ?? "not-applicable"}`,
+      "",
+    ].join("\n")
+  );
+}
+
+/** Execute the checkout or pack CLI boundary. */
+export function runReleasePackageIdentityCli(
+  argv,
+  { root = process.cwd(), githubOutput = process.env.GITHUB_OUTPUT } = {}
+) {
+  const [mode, ...options] = argv;
+  if (mode === "checkout") {
+    const result = assertCheckoutIdentity({
+      root,
+      releaseCommit: requiredOption(options, "--release-commit"),
+      tag: requiredOption(options, "--tag"),
+    });
+    process.stdout.write(
+      `RELEASE_CHECKOUT_IDENTITY_OK ${JSON.stringify(result)}\n`
+    );
+    return 0;
+  }
+  if (mode === "pack") {
+    const result = packAndValidateReleaseCandidate({
+      root,
+      version: requiredOption(options, "--version"),
+      releaseCommit: requiredOption(options, "--release-commit"),
+      packDestination: requiredOption(options, "--pack-destination"),
+    });
+    writeGithubOutput(result, githubOutput);
+    process.stdout.write(
+      `RELEASE_PACKAGE_IDENTITY_OK ${JSON.stringify(result)}\n`
+    );
+    return 0;
+  }
+  mismatch("expected mode checkout or pack");
+}
+
+if (invokedAsScript(import.meta.url)) {
+  try {
+    process.exitCode = runReleasePackageIdentityCli(process.argv.slice(2));
+  } catch (error) {
+    process.stderr.write(
+      `${error instanceof Error ? error.message : String(error)}\n`
+    );
+    process.exitCode = 1;
+  }
+}

package/scripts/two-channel-couplings.json

@@ -5,13 +5,13 @@
   },
   "inspected": {
     "workflows": 23,
-    "steps": 636,
-    "couplings": 26,
-    "inventory": 56
+    "steps": 639,
+    "couplings": 27,
+    "inventory": 57
   },
   "counts": {
     "package-backed": 10,
-    "apply-lagged": 14,
+    "apply-lagged": 15,
     "never-delivered": 0,
     "undelivered": 2
   },
@@ -68,6 +68,19 @@
       ],
       "detail": "`nightly-e2e-report.yml` is delivered at `@main`, so this step is live in every consumer on their next run. It reads `scripts/check-nightly-e2e-health.mjs` from the CALLER's tree with no package-relative candidate, and Lisa delivers that path on the `lisa apply` channel (typescript/copy-overwrite). The two halves land in the wrong order: this step is live everywhere immediately, the file it needs is live only where somebody applied. The read is unguarded, so an absent path fails the job loudly. Visible, which makes it the better of the two failures."
     },
+    {
+      "key": "publish-to-npm.yml::scripts/check-release-package-identity.mjs",
+      "workflow": "publish-to-npm.yml",
+      "path": "scripts/check-release-package-identity.mjs",
+      "channel": "apply",
+      "verdict": "apply-lagged",
+      "remedy": "run-lisa-apply",
+      "guarded": false,
+      "lanes": [
+        "all/copy-overwrite"
+      ],
+      "detail": "`publish-to-npm.yml` is delivered at `@main`, so this step is live in every consumer on their next run. It reads `scripts/check-release-package-identity.mjs` from the CALLER's tree with no package-relative candidate, and Lisa delivers that path on the `lisa apply` channel (all/copy-overwrite). The two halves land in the wrong order: this step is live everywhere immediately, the file it needs is live only where somebody applied. The read is unguarded, so an absent path fails the job loudly. Visible, which makes it the better of the two failures."
+    },
     {
       "key": "quality-rails.yml::scripts/check-threshold-ratchet.mjs",
       "workflow": "quality-rails.yml",

package/typescript/copy-overwrite/.prettierignore

@@ -68,6 +68,7 @@ scripts/check-conflict-markers.mjs
 scripts/check-e2e-coverage.mjs
 scripts/check-lighthouse-details.mjs
 scripts/check-nightly-e2e-health.mjs
+scripts/check-release-package-identity.mjs
 scripts/check-skipped-required-checks.mjs
 scripts/check-state-classification.mjs
 scripts/check-threshold-ratchet.mjs