@blamejs/exceptd-skills 0.18.18 → 0.18.20

package/scripts/check-agents-md-collectors.js

@@ -27,7 +27,65 @@ const path = require("node:path");
 
 const ROOT = path.join(__dirname, "..");
 const AGENTS = path.join(ROOT, "AGENTS.md");
-const COLLECTOR_DIR = path.join(ROOT, "lib", "collectors");
+const REAL_COLLECTOR_DIR = path.join(ROOT, "lib", "collectors");
+// EXCEPTD_COLLECTOR_DIR lets the test suite drive the gate against a throwaway
+// tempdir (so the require-throw / leaked-fixture behaviours are exercised
+// without writing into the real lib/collectors/). It is honored ONLY when the
+// explicit test-only switch EXCEPTD_COLLECTOR_DIR_TESTONLY=1 is also set, so a
+// stray env var in CI or a developer shell can never point the release gate at
+// an alternate directory and let missing/broken real collectors pass.
+const COLLECTOR_DIR =
+  process.env.EXCEPTD_COLLECTOR_DIR_TESTONLY === "1" && process.env.EXCEPTD_COLLECTOR_DIR
+    ? path.resolve(process.env.EXCEPTD_COLLECTOR_DIR)
+    : REAL_COLLECTOR_DIR;
+
+// A real shipped collector is named [a-z0-9-]+.js — the AGENTS.md enumeration
+// regex (`lib/collectors/([a-z0-9-]+\.js)`) cannot even reference an
+// underscore-prefixed file. So a `__`-prefixed file is never a collector:
+// it is test scaffolding or a stray artifact. classifyCollectors SKIPS it so a
+// leaked fixture cannot poison the count/enumeration/load-error scan; the gate
+// separately FORBIDS it (see findReservedFixtures) so a leaked fixture cannot
+// silently ship in the wholesale-published lib/ tree either.
+function isReservedFixture(f) {
+  return f.startsWith("__");
+}
+
+// Reserved-prefix .js files present in `dir`. These are test scaffolding and
+// must never ship; the gate fails hard if any are found in the directory it
+// validates.
+function findReservedFixtures(dir) {
+  try {
+    return fs.readdirSync(dir).filter((f) => f.endsWith(".js") && isReservedFixture(f));
+  } catch {
+    return [];
+  }
+}
+
+// Classify every <dir>/*.js into collectors (require succeeds + exports
+// collect()), helpers (require succeeds, no collect() — silently excluded),
+// and load-errors (require throws — surfaced, never silently dropped).
+// Exported so the test suite can drive it against a tempdir.
+function classifyCollectors(dir) {
+  const jsFiles = fs.readdirSync(dir)
+    .filter((f) => f.endsWith(".js") && !isReservedFixture(f))
+    .sort();
+  const collectorFiles = [];
+  const loadErrors = [];
+  for (const f of jsFiles) {
+    let mod;
+    try {
+      mod = require(path.join(dir, f));
+    } catch (e) {
+      loadErrors.push(`lib/collectors/${f}: ${e.message.split("\n")[0]}`);
+      continue;
+    }
+    if (typeof mod.collect === "function") {
+      collectorFiles.push(`lib/collectors/${f}`);
+    }
+  }
+  collectorFiles.sort();
+  return { collectorFiles, loadErrors };
+}
 
 const WORD_TO_NUMBER = {
   one: 1, two: 2, three: 3, four: 4, five: 5, six: 6, seven: 7,
@@ -46,19 +104,24 @@ function ok(msg) {
 }
 
 function main() {
-  let agents;
-  try { agents = fs.readFileSync(AGENTS, "utf8"); }
-  catch (e) {
-    console.error(`[check-agents-md-collectors] cannot read AGENTS.md: ${e.message}`);
+  // Leak-guard (P2: forbid leaked reserved fixtures before packing). A
+  // `__`-prefixed file in the collectors dir is stray test scaffolding;
+  // because lib/ is published wholesale, a leaked one would otherwise ship.
+  // Fail hard, naming the file, so the release path deletes it.
+  const stray = findReservedFixtures(COLLECTOR_DIR);
+  if (stray.length > 0) {
+    console.error(
+      `[check-agents-md-collectors] reserved-prefix file(s) must not ship from lib/collectors/ ` +
+      `- delete the stray test scaffolding: ${stray.join(", ")}`
+    );
     process.exitCode = 2;
     return;
   }
 
-  let jsFiles;
-  try {
-    jsFiles = fs.readdirSync(COLLECTOR_DIR).filter(f => f.endsWith(".js")).sort();
-  } catch (e) {
-    console.error(`[check-agents-md-collectors] cannot read ${COLLECTOR_DIR}: ${e.message}`);
+  let agents;
+  try { agents = fs.readFileSync(AGENTS, "utf8"); }
+  catch (e) {
+    console.error(`[check-agents-md-collectors] cannot read AGENTS.md: ${e.message}`);
     process.exitCode = 2;
     return;
   }
@@ -75,21 +138,14 @@ function main() {
   //                 count and the enumeration cross-check, so a file that
   //                 still ships in the tarball passes the gate undetected.
   //                 Surface it as a parse error (exit 2) naming the file.
-  const collectorFiles = [];
-  const loadErrors = [];
-  for (const f of jsFiles) {
-    let mod;
-    try {
-      mod = require(path.join(COLLECTOR_DIR, f));
-    } catch (e) {
-      loadErrors.push(`lib/collectors/${f}: ${e.message.split("\n")[0]}`);
-      continue;
-    }
-    if (typeof mod.collect === "function") {
-      collectorFiles.push(`lib/collectors/${f}`);
-    }
+  let collectorFiles, loadErrors;
+  try {
+    ({ collectorFiles, loadErrors } = classifyCollectors(COLLECTOR_DIR));
+  } catch (e) {
+    console.error(`[check-agents-md-collectors] cannot read ${COLLECTOR_DIR}: ${e.message}`);
+    process.exitCode = 2;
+    return;
   }
-  collectorFiles.sort();
 
   if (loadErrors.length > 0) {
     console.error(
@@ -146,4 +202,8 @@ function main() {
   }
 }
 
-main();
+if (require.main === module) {
+  main();
+}
+
+module.exports = { classifyCollectors };