@blamejs/exceptd-skills 0.19.33 → 0.19.34

package/lib/validate-package.js

@@ -1,20 +1,9 @@
 "use strict";
 /**
- * lib/validate-package.js
- *
- * Predeploy + prepublishOnly gate. Runs `npm pack --dry-run --json` and
- * asserts the publish tarball is what we expect:
- *
- *   - includes every required file from package.json `files`
- *   - excludes every forbidden file (secrets, tests, caches, dev artifacts)
- *   - is under the size budget (SIZE_BUDGET_BYTES below — do not restate the
- *     figure here; this line said 7 MB through three raises of it)
- *   - `bin/exceptd.js` has the expected shebang
- *   - the bin target listed in package.json exists on disk
- *
- * Exit 0 on success, 1 on any violation.
- *
- * Zero npm deps. Node 24 stdlib.
+ * Predeploy + prepublishOnly gate: runs `npm pack --dry-run --json` and asserts
+ * the publish tarball holds every required file, no forbidden one, a bin target
+ * that exists and carries a shebang, and a size under SIZE_BUDGET_BYTES — never
+ * restated in prose, which goes stale at every raise of it.
  */
 
 const fs = require("fs");
@@ -24,22 +13,8 @@ const { safeExit } = require("./exit-codes");
 
 const ROOT = path.join(__dirname, "..");
 const ABS = (p) => path.join(ROOT, p);
-// Published-tarball cap. Guards against accidental bloat (a vendored
-// node_modules, a committed binary — tens of MB), not the curated data that
-// legitimately grows each release: the CVE catalog gains entries and the RFC
-// index spans the full series. Packed size crossed 5 MB through that gradual
-// growth; 7 MB restored headroom. Completing five-jurisdiction framework-gap
-// coverage across the whole catalog added ~1,100 curated statements plus their
-// reverse-reference index, crossing 7 MB; 8 MB restored headroom. Curating a
-// further hundred KEV CVEs — each with its indicators, five framework-gap
-// statements and a paired zero-day lesson — crossed 8 MB; 9 MB restored
-// headroom. Recording the controls each CVE requires, across most of the
-// catalog, adds several hundred words per entry and crossed 9 MB; 11 MB
-// restores headroom through the remainder of that work while still catching a
-// gross-bloat accident. Two further hundred-CVE curation passes took the
-// catalog past 1,300 entries and crossed 11 MB; 13 MB restores headroom for
-// roughly two more passes at the current per-entry size, which is where the
-// next deliberate look at what ships in the tarball belongs.
+// Sized to catch a gross-bloat accident — a vendored node_modules, a committed
+// binary — not the curated data that legitimately grows each release.
 const SIZE_BUDGET_BYTES = 13 * 1024 * 1024;
 
 const REQUIRED_PATHS = [
@@ -52,10 +27,7 @@ const REQUIRED_PATHS = [
   "manifest-snapshot.json",
   "sbom.cdx.json",
   "bin/exceptd.js",
-  // Modules require()d at the top of bin/exceptd.js on every invocation —
-  // dropping any of these from the tarball bricks the CLI at launch with a
-  // module-not-found, so they are pinned explicitly rather than relied on via
-  // the directory-level files[] entries.
+  // require()d at the top of bin/exceptd.js: dropping one bricks the CLI at launch.
   "lib/exit-codes.js",
   "lib/id-validation.js",
   "lib/flag-suggest.js",
@@ -91,8 +63,7 @@ const FORBIDDEN_PATTERNS = [
 const PEM_ALLOWLIST = new Set(["keys/public.pem"]);
 
 function runNpmPack() {
-  // `npm pack --dry-run --json` writes a JSON array to stdout describing
-  // what would be in the tarball without actually creating it.
+  // --dry-run --json describes the tarball on stdout without creating it.
   const res = spawnSync("npm", ["pack", "--dry-run", "--json"], { cwd: ROOT, encoding: "utf8", shell: process.platform === "win32" });
   if (res.status !== 0) {
     process.stderr.write(`[validate-package] npm pack failed (exit ${res.status}): ${res.stderr || res.stdout}\n`);
@@ -113,20 +84,12 @@ function runNpmPack() {
   return first;
 }
 
-/* SBOM coverage of the ACTUAL tarball.
- *
- * The SBOM's own completeness gate expands package.json `files`, but npm ships
- * more than `files` names — package.json unconditionally, plus README files it
- * collects itself. Those extras shipped unhashed and nothing noticed, because
- * the generator and its checker both asked `files`: two sides agreeing on the
- * same incomplete question. `npm pack` is the only authority on what actually
- * ships, and this is the one gate holding its output, so the comparison belongs
- * here.
- *
- * Exclusions are read from the SBOM's own declared properties instead of a
- * second copy of the list, so a file can only be uncovered when the published
- * artifact says out loud that it is. The single structural exception is the
- * SBOM itself, which cannot contain its own hash.
+/* SBOM coverage of the ACTUAL tarball. The SBOM's own completeness gate expands
+ * package.json `files`, but npm ships more than that, so a generator and its
+ * checker can agree on the same incomplete question; `npm pack` is the only
+ * authority on what ships. Exclusions come from the SBOM's own declared
+ * properties rather than a second copy of the list; the structural exception is
+ * the SBOM, which cannot hash itself.
  */
 function sbomCoverageIssues(filePaths, sbom) {
   const props = (sbom && sbom.metadata && sbom.metadata.properties) || [];
@@ -159,7 +122,6 @@ function main() {
 
   const pkg = JSON.parse(fs.readFileSync(ABS("package.json"), "utf8"));
 
-  // package.json sanity
   if (pkg.private === true) issues.push(`package.json "private" is true — npm publish will fail`);
   if (!pkg.bin || !pkg.bin.exceptd) issues.push(`package.json missing bin.exceptd`);
   if (!Array.isArray(pkg.files) || pkg.files.length === 0) issues.push(`package.json missing files[] whitelist`);
@@ -167,7 +129,6 @@ function main() {
     issues.push(`package.json missing publishConfig.access: public (scoped package needs explicit access)`);
   }
 
-  // bin target exists + has a shebang
   if (pkg.bin && pkg.bin.exceptd) {
     const binPath = ABS(pkg.bin.exceptd);
     if (!fs.existsSync(binPath)) {
@@ -180,19 +141,16 @@ function main() {
     }
   }
 
-  // npm pack dry-run
   const packInfo = runNpmPack();
   const filePaths = packInfo.files.map((f) => f.path.replace(/\\/g, "/"));
   const fileSet = new Set(filePaths);
 
-  // Required files present
   for (const r of REQUIRED_PATHS) {
     if (!fileSet.has(r)) {
       issues.push(`required file missing from publish tarball: ${r}`);
     }
   }
 
-  // Forbidden files absent
   for (const p of filePaths) {
     if (PEM_ALLOWLIST.has(p)) continue;
     for (const re of FORBIDDEN_PATTERNS) {
@@ -210,12 +168,8 @@ function main() {
     issues.push(`could not read sbom.cdx.json to check tarball coverage: ${err.message}`);
   }
 
-  // Size budget. An absent/non-numeric `size` field is NOT a pass — it means
-  // the gate cannot evaluate the budget at all. Fail loudly instead of
-  // silently skipping (the absent-field-fails-open class, symmetric with the
-  // license_sha256 / vendored_sha256 guards in validate-vendor.js): a future
-  // npm-pack output shape change that drops or renames `size` must not turn the
-  // size budget into a no-op.
+  // An absent or non-numeric `size` is a failure, not a pass: a change in npm
+  // pack's output shape must not turn the budget into a silent no-op.
   if (typeof packInfo.size !== "number") {
     issues.push(`npm pack output missing numeric size — cannot enforce size budget`);
   } else if (packInfo.size > SIZE_BUDGET_BYTES) {