@casomoltd/tooling 0.23.1 → 0.23.3

package/README.md

@@ -104,7 +104,7 @@ its own bin commands via `node_modules/.bin`.
 Claude Code skills/agents/docs tree: every `SKILL.md` / `agents/*.md` has
 parseable YAML frontmatter with `name` + `description`, and every relative link
 and `#anchor` resolves. tooling runs it over its own `skills/` in `npm run
-check` (`lint:skills`) — catching the breakage a rename or hand-edit leaves that
+check` (`lint:md`) — catching the breakage a rename or hand-edit leaves that
 Claude Code's loader silently swallows.
 
 To gate a consumer repo's docs (link/anchor integrity) at its own pre-commit,
@@ -218,15 +218,46 @@ fails loud on the former and warns on the latter.
 
 ## Quality gates
 
-There is no CI — all quality gates run locally via git hooks.
-Code should be deployment-ready by the time it's pushed to
-the remote.
+Quality gates run locally via git hooks, so code is
+deployment-ready by the time it reaches the remote. GitHub
+Actions re-runs `check` on push and publishes on a version tag;
+the local hooks are the gate, CI is the backstop.
 
-- **pre-commit**: Runs commitlint only (fast).
-- **pre-push**: Runs the full suite — `npm run check`,
-  `npm run build`, then version and tag guards. This ensures
-  lint, typecheck, spelling, and version bumps are all verified
-  before code reaches the remote.
+- **pre-commit**: `npm run check` — the repo's full health gate.
+- **commit-msg**: commitlint (house rules + the AI-attribution ban).
+- **pre-push**: `npm run check`, then the version and tag guards.
+
+**`check` owns the build.** A repo whose build fails is not
+healthy, and any assertion that reads build output has to run
+after the build in the same script — so `build` belongs in
+`check`, and appears nowhere else. Declaring it in the pre-push
+gate as well would give it two owners and build twice.
+
+### What every repo's `check` must contain
+
+`check` is a hand-written, ordered chain — the repos are
+heterogeneous and some orderings are load-bearing — but its
+**composition is enforced**, not remembered. Run `check-gates`
+as its first step:
+
+```json
+"check": "check-gates && npm run lint && npm run typecheck && ..."
+```
+
+It fails if a required gate is missing, if one is defined but
+never run (a dead gate), or if an exception outlives the problem
+it was written for. Required: `lint`, `typecheck`, `test`,
+`knip`, `jscpd`, `lint:md`, `spell`, `build`.
+
+A repo opts out by declaring a **reason** — a blank one fails, so
+an opt-out is never silent, and every exception is printed on
+each run:
+
+```json
+"casomo": {
+  "gates": { "test": "content site — no suite yet" }
+}
+```
 
 ## Usage
 

package/bin/check-gates.mjs

@@ -0,0 +1,132 @@
+#!/usr/bin/env node
+// Assert that a repo's `check` script is COMPOSED correctly, before it runs.
+//
+// Each repo hand-writes `check` as an ordered `&&` chain, which is worth
+// keeping: the repos are heterogeneous and some chains carry a real ordering
+// constraint (build must precede any assertion that reads build output). What
+// is not worth keeping is that chain being unverified — a gate can be dropped,
+// or defined and never wired in, and nothing says a word.
+//
+// So this does not orchestrate the gates; it checks the composition:
+//   1. every REQUIRED gate is defined and actually run by `check`
+//   2. no gate-shaped script is defined but left unreferenced (a dead gate)
+//   3. no exception outlives the problem it was written for
+//
+// A repo opts out by declaring a reason in its own package.json. A blank
+// reason fails, so an opt-out can never be silent:
+//
+//   "casomo": { "gates": { "test": "content site — no suite yet" } }
+//
+// Declared exceptions are printed on every run: excusing a gap must not be the
+// same thing as hiding it.
+import {readFileSync} from "node:fs";
+import {join} from "node:path";
+
+/** Gates every repo must define and run, absent a declared exception. */
+export const REQUIRED = [
+  "lint",
+  "typecheck",
+  "test",
+  "knip",
+  "jscpd",
+  "lint:md",
+  "spell",
+  "build",
+];
+
+/** Gate-shaped but not mandatory: still dead if defined and never run. */
+export const OPTIONAL = ["check:readability"];
+
+/** A script is a gate only by exact membership or the `check:` prefix — never
+ * by heuristic, so `dev`, `start`, `clean`, `lint:fix`, `test:watch`,
+ * `build:clean` and `indexnow` need no denylist to be ignored. */
+export const isGate = (name) =>
+  REQUIRED.includes(name) || OPTIONAL.includes(name) || name.startsWith("check:");
+
+/** Gates `check` actually invokes. Segments are matched whole so that a repo
+ * running only `lint:md` never reads as also running `lint`. */
+export const referencedGates = (check) =>
+  new Set(
+    String(check ?? "")
+      .split("&&")
+      .map((segment) => segment.trim().match(/^npm run ([\w:.-]+)/)?.[1])
+      .filter(Boolean),
+  );
+
+export const evaluate = (pkg) => {
+  const scripts = pkg.scripts ?? {};
+  const exceptions = pkg.casomo?.gates ?? {};
+  const run = referencedGates(scripts.check);
+
+  // `check` itself is the chain, not a step within it.
+  const defined = Object.keys(scripts).filter((n) => isGate(n) && n !== "check");
+
+  const failures = [];
+  for (const gate of REQUIRED) {
+    if (!(gate in scripts)) failures.push([gate, `required gate is not defined`]);
+    else if (!run.has(gate))
+      failures.push([gate, `required gate is defined but \`check\` never runs it`]);
+  }
+  for (const gate of defined) {
+    if (run.has(gate)) continue;
+    if (failures.some(([g]) => g === gate)) continue; // already reported above
+    failures.push([gate, `defined but \`check\` never runs it — a dead gate`]);
+  }
+
+  const excused = [];
+  const unreasoned = [];
+  const live = [];
+  for (const [gate, reason] of failures) {
+    if (!(gate in exceptions)) {
+      live.push([gate, reason]);
+    } else if (!String(exceptions[gate] ?? "").trim()) {
+      unreasoned.push(gate);
+    } else {
+      excused.push([gate, exceptions[gate]]);
+    }
+  }
+
+  // An exception whose failure has gone away is the same rot in reverse.
+  const stale = Object.keys(exceptions).filter(
+    (gate) => !failures.some(([g]) => g === gate),
+  );
+
+  return {live, excused, unreasoned, stale};
+};
+
+const main = () => {
+  const dir = process.cwd();
+  const pkg = JSON.parse(readFileSync(join(dir, "package.json"), "utf8"));
+  const {live, excused, unreasoned, stale} = evaluate(pkg);
+
+  for (const [gate, reason] of excused) {
+    console.log(`check-gates: skipping \`${gate}\` — ${reason}`);
+  }
+
+  const problems = [
+    ...live.map(([gate, reason]) => `${gate}: ${reason}`),
+    ...unreasoned.map(
+      (gate) => `${gate}: exception declared with no reason — say why, or fix it`,
+    ),
+    ...stale.map(
+      (gate) => `${gate}: exception is no longer needed — the gate passes, drop it`,
+    ),
+  ];
+
+  if (problems.length) {
+    console.error(
+      `✖ check-gates: ${problems.length} problem(s)\n  ` +
+        problems.join("\n  ") +
+        `\n\nDeclare an exception in package.json to opt out, with a reason:\n` +
+        `  "casomo": { "gates": { "<gate>": "why this repo does not run it" } }`,
+    );
+    process.exit(1);
+  }
+
+  console.log(
+    `check-gates OK — ${REQUIRED.length} required gates` +
+      (excused.length ? `, ${excused.length} excused` : ""),
+  );
+};
+
+if (import.meta.url === `file://${process.argv[1]}`) main();

package/bin/pre-push.sh

@@ -4,14 +4,16 @@
 PRE_PUSH_REFS=$(cat)
 export PRE_PUSH_REFS
 
-# Uniform pre-push for every repo: check, build, then the version/tag gates.
-# `npm run build` must exist in EVERY repo so this line never has to special-case
-# one. Where a repo produces no build output (a source-only repo like tooling,
-# consumed as a git-dep), define build as a no-op (`"build": "echo ..."`) rather
-# than omitting it — a missing script would abort the push with "Missing script:
-# build", which once made it ambiguous whether a source-only repo was even
-# pushable. No-op keeps the step honest and uniform.
+# Uniform pre-push for every repo: the repo's own health gate, then the
+# release-protocol gates.
+#
+# Building belongs to `check`, not here. A repo whose build fails is not
+# healthy, and any assertion that reads build output (SSR, page meta, sitemap)
+# has to run after the build inside that same script — so `check` is where the
+# step already has to live. Declaring it here as well would give the build two
+# owners and run it twice wherever `check` builds. A repo that needs a build
+# gate adds `npm run build` to its own `check`; one that produces no artifact
+# simply doesn't.
 npm run check \
-  && npm run build \
   && echo "$PRE_PUSH_REFS" | check-version \
   && echo "$PRE_PUSH_REFS" | check-tags

package/bin/verify-pack.mjs

@@ -25,6 +25,11 @@ const ALLOWED_FILES = ["README.md", "package.json", "LICENSE", "LICENSE.md"];
 const SECRET_PATTERN =
   /(^|\/)(\.env(\..*)?|.*settings\.local\.json|.*\.pem|id_[rd]sa|.*\.key|\.npmrc)$/i;
 
+// Tests live beside what they test, which puts them inside an allowed dir —
+// so the allowlist alone would ship them. Consumers get the tool, not its
+// test suite.
+const TEST_PATTERN = /\.test\.[cm]?[jt]s$/i;
+
 const raw = execSync("npm pack --dry-run --json", {encoding: "utf8"});
 const files = JSON.parse(raw)[0].files.map((entry) => entry.path);
 
@@ -34,14 +39,18 @@ const escaped = files.filter(
     !ALLOWED_PREFIXES.some((prefix) => f.startsWith(prefix)),
 );
 const secrets = files.filter((f) => SECRET_PATTERN.test(f));
+const tests = files.filter((f) => TEST_PATTERN.test(f));
 
-if (escaped.length || secrets.length) {
+if (escaped.length || secrets.length || tests.length) {
   if (escaped.length) {
     console.error("✖ files outside the allowlist:\n  " + escaped.join("\n  "));
   }
   if (secrets.length) {
     console.error("✖ secret-like files in package:\n  " + secrets.join("\n  "));
   }
+  if (tests.length) {
+    console.error("✖ test files in package:\n  " + tests.join("\n  "));
+  }
   process.exit(1);
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@casomoltd/tooling",
-  "version": "0.23.1",
+  "version": "0.23.3",
   "description": "Casomo's shared dev config: ESLint, Prettier, commitlint, knip & jscpd presets and dev CLIs (git hooks, readability, screenshots)",
   "license": "MIT",
   "repository": {
@@ -16,14 +16,26 @@
     "jscpd/",
     "readability/",
     "report/",
-    "README.md"
+    "README.md",
+    "!**/*.test.mjs"
   ],
   "scripts": {
-    "check": "node bin/verify-pack.mjs && tsc --noEmit -p hooks/tsconfig.json && node hooks/test.mts && npm run lint:skills",
-    "lint:skills": "remark --frail --quiet --no-stdout --rc-path bin/skills-lint.config.mjs skills docs",
-    "build": "echo 'no-op: source-only repo (consumed as a git-dep), nothing to build'",
+    "check": "node bin/check-gates.mjs && node bin/verify-pack.mjs && npm run typecheck && npm run test && npm run lint:md",
+    "typecheck": "tsc --noEmit -p hooks/tsconfig.json",
+    "test": "node hooks/test.mts && node bin/check-gates.test.mjs",
+    "lint:md": "remark --frail --quiet --no-stdout --rc-path bin/skills-lint.config.mjs skills docs",
+    "build": "echo 'no-op: source-only repo, nothing to build'",
     "prepare": "husky || true"
   },
+  "casomo": {
+    "gates": {
+      "lint": "publishes the shared eslint config but has none of its own yet",
+      "knip": "no knip config for this repo's mixed .mts/.mjs layout yet",
+      "jscpd": "no jscpd config for this repo yet",
+      "spell": "no shared cspell config exists yet",
+      "build": "source-only repo — build is a deliberate no-op, nothing to verify"
+    }
+  },
   "exports": {
     "./eslint": "./eslint/index.mjs",
     "./eslint-lib": "./eslint/lib.mjs",
@@ -35,6 +47,7 @@
   },
   "bin": {
     "build-report": "./bin/build-report.mjs",
+    "check-gates": "./bin/check-gates.mjs",
     "check-tags": "./bin/check-tags.sh",
     "check-version": "./bin/check-version.sh",
     "commit-msg": "./bin/commit-msg.sh",