@casomoltd/tooling 0.27.0 → 0.29.0

package/README.md

@@ -21,12 +21,17 @@ Shared linting, formatting, commit config, and CLI tools for Casomo Ltd's repos.
 | Command | Description |
 |---|---|
 | `check-version` | Pre-push guard — rejects push if `package.json` version hasn't changed vs `origin/main` |
-| `pre-push` | Husky pre-push hook — runs check, build, then version/tag guards |
+| `check-linear` | Pre-push guard — rejects a push that would put a merge commit on the remote. History is linear; a branch catches up by rebasing. Only what the push adds is judged, so merges already on the remote stay |
+| `pre-push` | Husky pre-push hook — runs check, then the version, tag and linear-history guards |
 | `pre-commit` | Husky pre-commit hook — runs `npm run check` |
 | `commit-msg` | Husky commit-msg hook — runs commitlint |
 | `readability` | Measure reading difficulty of page content |
 | `screenshot` | Capture a dev server page via Playwright — an agent's visual feedback loop |
 | `build-report` | Compile a Typst client report to PDF with the house template |
+| `render-figures` | Pre-render a design spec's mermaid figures to static SVG |
+| `spec-check` | Check a design spec's anchors, contents, figures and numbering |
+| `check-private-refs` | In a public repo, refuse a private tracker link or a name listed in `check-private-refs.config.mjs` |
+| `check-personal-data` | Refuse an email, National Insurance number, UK mobile number, date of birth or locally denylisted name; per-repo allowances in `check-personal-data.config.mjs` |
 
 ## Install
 
@@ -38,7 +43,7 @@ npm i -D @casomoltd/tooling
 ```
 
 ```json
-"@casomoltd/tooling": "^0.20.0"
+"@casomoltd/tooling": "^0.28.0"
 ```
 
 The package is public, so installs need no token or `.npmrc`. The `files`
@@ -51,10 +56,10 @@ declared here — see [External prerequisites](#external-prerequisites).
 
 ## External prerequisites
 
-Two bins need something npm cannot sensibly deliver: `screenshot` needs
-a Chromium build, `build-report` needs the `typst` CLI and the IBM Plex
-fonts. **Neither is declared — not as a dependency, and not as an
-optional peer.** Both load their prerequisite lazily and fail with an
+Three bins need something npm cannot sensibly deliver: `screenshot` and
+`render-figures` need a Chromium build through Playwright, and
+`build-report` needs the `typst` CLI and the IBM Plex fonts. **None is
+declared — not as a dependency, and not as an optional peer.** Each loads its prerequisite lazily and fails with an
 install instruction when it is missing, so a consumer that never runs
 those bins carries nothing for them.
 
@@ -97,6 +102,44 @@ repo needs (lint, typecheck, spell, etc.).
 hooks (e.g. `./bin/check-version.sh`) because it can't resolve
 its own bin commands via `node_modules/.bin`.
 
+### A repo whose toolchain is not npm
+
+A Python, Go or C++ repo still gets the commit rules. It carries a **dev-only
+npm layer** that exists to host the hook and nothing else:
+
+```json
+{
+  "name": "<repo>-hooks",
+  "private": true,
+  "description": "Dev-only npm layer: wires the shared commit-msg gate into this repo. Not the project toolchain.",
+  "scripts": { "prepare": "husky" },
+  "devDependencies": {
+    "@casomoltd/tooling": "^0.28.0",
+    "@commitlint/cli": "^20.0.0",
+    "husky": "^9.1.7"
+  }
+}
+```
+
+Plus `commitlint.config.cjs` re-exporting the rules, and `.husky/commit-msg`.
+No `version`, because the repo versions itself with its own tool. Live
+examples: `kallim`, `paperpi`.
+
+**Do not wire `pre-commit` or `pre-push` from this package in such a repo.**
+Both run `npm run check`, and `check-gates` reads `package.json` and requires
+eight named npm scripts — a gate a non-npm repo cannot satisfy and should not
+fake. Write a `.husky/pre-push` that calls the real toolchain instead:
+
+```sh
+uv run ruff check && uv run ruff format --check && uv run pyright && uv run pytest
+```
+
+**Why this is documented here.** Undocumented, each non-npm repo solves it
+alone and writes its own shell or Python copy of `no-ai-attribution`, and the
+copies drift — the length limits are what they lose first. One rule, one home.
+If a house gate will not run in your repo, wire the shared one or fix this
+package. Do not write a local equivalent.
+
 ## Markdown / skills lint
 
 `bin/skills-lint.config.mjs` is a stock remark config (`remark-frontmatter` +
@@ -167,6 +210,21 @@ Add these scripts to your `package.json`:
 Screenshots are saved to `.claude/screenshots/`. Set
 `SCREENSHOT_URL` to override the default `http://localhost:3000`.
 
+## Design specs
+
+`spec-check` reads one HTML design spec and reports its mechanical
+faults: an anchor resolving to nothing, a contents entry disagreeing
+with its heading, a figure without a number, an anchor or a caption, a
+figure wider than the card it sits in, a section number typed where the
+stylesheet generates one, and markup the artifact host refuses.
+
+`render-figures` rewrites a spec's mermaid figures as static SVG, so the
+page carries no runtime. Each figure keeps its source in an HTML comment
+above it, and a run reads those back, renders them and freezes the
+computed paint inline. It resolves Playwright from the working directory;
+set `RENDER_FIGURES_RESOLVE_FROM` to a project that has it when running
+from somewhere else.
+
 ## Client reports (Typst)
 
 `report/` ships the Casomo house style for client-facing PDF reports —
@@ -181,13 +239,13 @@ npx build-report report.typ --watch                # recompile on save
 npx build-report report.typ --open                 # open the PDF when done
 ```
 
-The compiled PDF is a build artefact, so it defaults to the same scratch
-resolution as the agent reports (see *Report output & `SCRATCH_DIR`*
-under Agents): `$SCRATCH_DIR/reports/<name>.pdf`, or
-`<repo-root>/scratch/reports/` when `SCRATCH_DIR` is unset — add
-`scratch/` to the consumer repo's `.gitignore` (this repo does). Pass
-`--out` only when the PDF is a deliverable the repo actually keeps
-(e.g. a site's `public/`).
+The compiled PDF is a build artefact and goes to
+`$SCRATCH_DIR/reports/<name>.pdf`, or `<repo-root>/scratch/reports/` when
+**`SCRATCH_DIR`** is unset — add `scratch/` to the consumer repo's
+`.gitignore` (this repo does). A PDF is a file to open rather than a page
+to publish, so it keeps a scratch location where the x-ray reports need
+none. Pass `--out` only when the PDF is a deliverable the repo actually
+keeps (e.g. a site's `public/`).
 
 A report imports the template and applies it as a show rule; everything
 after is the body. From a consumer repo the import goes through
@@ -322,7 +380,7 @@ decision table) that keeps these units composing without overlap.
 | `/casomoltd:typescript` | TypeScript data modelling and type design |
 | `/casomoltd:screenshot` | Capture and analyse a dev server page |
 | `/casomoltd:design-pass` | Map → review → refactor a package (drives `design-xray` + `code-review`) |
-| `/casomoltd:draft-design-spec` | Author a browser-reviewable HTML design spec from a brief and iterate on it before writing code (drives `design-xray`) |
+| `/casomoltd:draft-design-spec` | Author a reviewable HTML design spec from a brief, publish it as an Artifact, and iterate on it there before writing code (drives `design-xray`) |
 | `/casomoltd:page-design` | Structure a content/explainer page for trust — above-the-fold answer, disclosure, palette-only colour (rubric a page-design reviewer preloads) |
 | `/casomoltd:generate-report` | Scaffold a Typst client report from the house template, compile via `build-report`, verify the PDF |
 
@@ -408,14 +466,16 @@ where a justification would and otherwise survives an ordinary read-through. The
 `agents/*.md` changes to it. Not link validity (a markdown link linter), not the
 corpus reference graph (`docs-xray`), not prose voice (a content reviewer).
 
-**Report output & `SCRATCH_DIR`.** `design-xray` and `docs-xray` persist their
-report — the `.md` plus an `.html` rendered by `bin/render-report.mjs` — so it
-outlives the run and opens in a browser. Each writes to a gitignored
-`<repo-root>/scratch/<agent>/` by default. Set the optional **`SCRATCH_DIR`** env
-var to pool every report under one shared location instead (`$SCRATCH_DIR/<agent>/`)
-— e.g. a multi-repo workspace collecting reports in one place rather than scattering
-them per-repo. Publishing a report to a hosted claude.ai artifact is orchestrator-
-only and on explicit request; the agents never do it.
+**Report output.** `design-xray` and `docs-xray` write their report — the `.md`
+plus an `.html` rendered by `bin/render-report.mjs` — into a working directory
+and return both paths, and the caller publishes the `.html`. Each agent's
+*Persist the report* section is the spec for that hand-off.
+
+The rendered `.html` is built for that destination: `render-report.mjs` converts
+the markdown in node and ships **no mermaid runtime**, because the artifact host
+renders every `pre.mermaid` itself and a second runtime races it into black
+boxes. A page that builds its own body at load time has no diagram blocks in it
+when the host looks.
 
 ## Package distribution
 

package/bin/check-hooks.sh

@@ -0,0 +1,84 @@
+#!/bin/sh
+# Is the house commit gate actually active in this repo?
+#
+# Answers one question, and answers it by *behaviour* rather than by presence.
+# A repo can have a commit-msg hook that enforces some of the rules, or an
+# older copy of them, and look wired while letting real violations through —
+# that is exactly what happened: three repos each grew a hand-written copy of
+# `no-ai-attribution`, two of them missing the length limits, and nothing
+# noticed for months because every one of them *had* a hook.
+#
+# So this feeds the hook messages that must fail and checks that they do.
+#
+#   check-hooks            # this repo
+#   check-hooks ~/dev/*    # every repo under a directory
+#
+# Exit 0 if every repo checked is gated, 1 otherwise. Language-neutral: sh and
+# git only, like check-linear and check-tags.
+set -e
+
+status=0
+
+check_one() {
+  repo=$1
+  name=$(basename "$repo")
+
+  if [ ! -d "$repo/.git" ]; then
+    return 0  # not a repo; silently skip so globs can be sloppy
+  fi
+
+  hooks=$(git -C "$repo" config --get core.hooksPath || echo ".git/hooks")
+  case "$hooks" in
+    /*) hook="$hooks/commit-msg" ;;
+    *)  hook="$repo/$hooks/commit-msg" ;;
+  esac
+
+  if [ ! -f "$hook" ]; then
+    printf '%-24s NOT GATED  (no commit-msg hook)\n' "$name"
+    status=1
+    return 0
+  fi
+
+  msg=$(mktemp)
+  failures=""
+
+  # Each probe is a message the house rules must reject. Keep the bodies
+  # single-line so a copy that only checks the header still fails the first.
+  probe() {
+    printf '%s' "$2" > "$msg"
+    if git -C "$repo" hook run --ignore-missing commit-msg -- "$msg" \
+        >/dev/null 2>&1; then
+      failures="$failures $1"
+    fi
+  }
+
+  probe attribution "Add a thing
+
+Co-authored-by: Claude <noreply@anthropic.com>
+"
+  probe header-length "Add a thing with a subject line that runs past the fifty character limit
+"
+  probe body-length "Add a thing
+
+This body line is deliberately longer than the seventy-two character limit.
+"
+
+  rm -f "$msg"
+
+  if [ -n "$failures" ]; then
+    printf '%-24s PARTIAL    (accepts:%s)\n' "$name" "$failures"
+    status=1
+  else
+    printf '%-24s gated\n' "$name"
+  fi
+}
+
+if [ $# -eq 0 ]; then
+  check_one "$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
+else
+  for arg in "$@"; do
+    check_one "$arg"
+  done
+fi
+
+exit $status

package/bin/check-linear.sh

@@ -0,0 +1,47 @@
+#!/bin/sh
+# Refuse a push that would put a merge commit on the remote.
+#
+# History is linear here: a branch catches up by rebasing, never by merging.
+# A merge commit costs the thing a linear history is kept for — `git log` on a
+# file stops being the list of changes to it, `git bisect` has two parents to
+# choose between, and a revert has to name which side it means.
+#
+# The forge refuses merges made through its own UI; this refuses the other
+# route, which is a local `git merge` followed by an ordinary push. Both are
+# needed: neither covers the other.
+#
+# Only what the push would ADD is judged. A merge already on the remote stays
+# where it is, because rewriting shared history to satisfy a new rule costs
+# more than the rule is worth.
+
+STATUS=0
+
+while read -r _ LOCAL_SHA REMOTE_REF REMOTE_SHA; do
+  # A deletion pushes the zero sha and adds nothing.
+  case "$LOCAL_SHA" in
+    *[!0]*) ;;
+    *) continue ;;
+  esac
+
+  case "$REMOTE_SHA" in
+    # A new branch: everything on it that no remote already has.
+    *[!0]*) RANGE="$REMOTE_SHA..$LOCAL_SHA" ;;
+    *) RANGE="$LOCAL_SHA --not --remotes" ;;
+  esac
+
+  # shellcheck disable=SC2086  # RANGE carries its own arguments.
+  MERGES=$(git rev-list --merges $RANGE 2>/dev/null)
+
+  if [ -n "$MERGES" ]; then
+    COUNT=$(printf '%s\n' "$MERGES" | wc -l | tr -d ' ')
+    echo "$REMOTE_REF would gain $COUNT merge commit(s):"
+    printf '%s\n' "$MERGES" | while read -r SHA; do
+      echo "  $(git log --format='%h %s' -1 "$SHA")"
+    done
+    echo "History is linear here. Rebase instead:"
+    echo "  git rebase main"
+    STATUS=1
+  fi
+done
+
+exit $STATUS

package/bin/check-personal-data.mjs

@@ -0,0 +1,270 @@
+#!/usr/bin/env node
+/**
+ * Refuse to let a person's details reach a commit.
+ *
+ * A repo that works from real people's records keeps them in a working
+ * directory outside it, and they reach it the moment someone pastes a
+ * statement into a fixture or reuses a real figure as a "specimen". This
+ * finds what has a shape:
+ *
+ * - **Emails, National Insurance numbers, UK mobile numbers and dates of
+ *   birth** are detectable by shape, and these rules find them.
+ * - **Names are not.** No pattern separates a person from a cited author, so
+ *   names come from a local denylist that is itself never committed: a file
+ *   listing the people would be the leak it exists to prevent. Without the
+ *   file the other rules still run, and the summary says name checking is off.
+ *
+ * Deliberately configurable, because this file ships in a public package and
+ * cannot name anybody's domains or reference formats. A consuming repo adds
+ * its own in `check-personal-data.config.mjs`:
+ *
+ *   export default {
+ *     allowEmail: [/@example-org\.com$/i],   // addresses that are not people
+ *     rules: [                               // repo-specific identifiers
+ *       {name: "case reference", re: /\bCASE-\d{4,}\b/g,
+ *        allow: (m) => m === "CASE-0000"},
+ *     ],
+ *     denylist: ".personal-data-denylist",   // the default; gitignore it
+ *     allow: [/\.test\.mjs$/],               // paths exempted, with care
+ *   };
+ *
+ * Usage:
+ *   check-personal-data            # tracked and untracked-but-not-ignored
+ *   check-personal-data --staged   # staged only
+ */
+import {execFileSync} from "node:child_process";
+import {existsSync, readFileSync, realpathSync, statSync} from "node:fs";
+import {pathToFileURL} from "node:url";
+import {loadConfig} from "./utils.mjs";
+
+/** Addresses in every repo's own tooling that name no person. */
+const ALLOWED_EMAIL = [
+  /@example\.(com|org|net)$/i,
+  /@users\.noreply\.github\.com$/i,
+];
+
+/* Files whose content looks like data but never describes a person:
+ * lockfiles, generated bundles, fonts, images. */
+const SKIP_DIRS = new Set(["node_modules", ".next", "dist", "coverage", "out"]);
+const SKIP_EXTS = new Set([
+  "lock", "woff", "woff2", "ttf", "otf", "png", "jpg", "jpeg", "gif", "webp",
+  "ico", "pdf", "zip", "map",
+]);
+
+function skip(file) {
+  if (file.split("/").some((part) => SKIP_DIRS.has(part))) return true;
+  if (file.endsWith("package-lock.json")) return true;
+  const ext = file.slice(file.lastIndexOf(".") + 1).toLowerCase();
+  return SKIP_EXTS.has(ext);
+}
+
+/** The field names a data shape puts between a label and its value. */
+const FIELD_SUFFIX = /(?:value|val|text|node|display|content)$/;
+
+/** A key that names a birth. */
+const BIRTH_KEY = /(?:dob|dateofbirth|birthdate|born)$/;
+
+/** The constructor a source file writes a date with. `new Date(1983, 6, 14)`
+ *  matches neither the printed nor the ISO rule, and the words before it end
+ *  `newdate` rather than a field name, so both halves would be blind at once
+ *  without this. */
+const DATE_CALL = /(?:new\s*)?date\($/;
+
+/**
+ * Whether the words before a date name a birth.
+ *
+ * A rendered page puts label and value side by side, so the key is last. A
+ * data file nests: `{label: "Date of birth", value: {value: "..."}}` gives a
+ * lead-in ending `dateofbirthvaluevalue`. The suffixes come off one at a time
+ * rather than as a starred alternation, which backtracks super-linearly
+ * because `val` is a prefix of `value`; a bounded loop is linear.
+ */
+function namesABirth(lead) {
+  let rest = lead;
+  for (let depth = 0; depth < 4; depth += 1) {
+    if (BIRTH_KEY.test(rest)) return true;
+    const trimmed = rest.replace(FIELD_SUFFIX, "");
+    if (trimmed === rest) return false;
+    rest = trimmed;
+  }
+  return BIRTH_KEY.test(rest);
+}
+
+const NON_WORD = /[^a-z0-9]/gi;
+
+/** What precedes a date, as a reader sees it: tags dropped, a generous
+ *  window, because a label and its value are separated by a cell boundary
+ *  and whatever styling that cell carries. */
+const leadIn = (before) =>
+  before.replace(/<[^<>]*>/g, " ").slice(-120).replace(NON_WORD, "")
+    .toLowerCase();
+
+/** A real address ends in a letters-only top-level domain; without this a
+ *  package spec such as `postcss@8.4.31` reads as one. */
+const TLD = /\.[A-Za-z]{2,}$/;
+
+/** The identity rules every repo gets. */
+export function identityRules(allowEmail = []) {
+  const allowed = [...ALLOWED_EMAIL, ...allowEmail];
+  return [
+    {
+      name: "email address",
+      // Labels joined by dots, not one class containing the dot: letting `.`
+      // sit in the class too makes the parts overlap and backtrack.
+      re: /\b[A-Za-z0-9._%+-]+@[A-Za-z0-9-]+(?:\.[A-Za-z0-9-]+)+\b/g,
+      allow: (m) => allowed.some((a) => a.test(m)) || !TLD.test(m),
+    },
+    {
+      name: "National Insurance number",
+      re: /\b[A-CEGHJ-PR-TW-Z]{2}\s?\d{2}\s?\d{2}\s?\d{2}\s?[A-D]\b/g,
+    },
+    {
+      name: "UK mobile number",
+      re: /\b(?:\+44\s?7\d{3}|\(?07\d{3}\)?)\s?\d{3}\s?\d{3}\b/g,
+    },
+    {
+      name: "date of birth",
+      // Every ISO date, then the words before it decide: a bare date is a
+      // rule's date far more often than a person's.
+      re: /\b\d{4}[-/]\d{1,2}[-/]\d{1,2}\b/g,
+      // 1 January is the placeholder a redacted fixture writes; flagging it
+      // trains everyone to ignore the check.
+      allow: (m) => /[-/]0?1[-/]0?1$/.test(m),
+      context: (before) => namesABirth(leadIn(before)),
+    },
+    {
+      name: "date of birth",
+      // The printed form, "DD Month YYYY", which the ISO rule cannot see.
+      re: /\b\d{1,2}\s+(?:January|February|March|April|May|June|July|August|September|October|November|December)\s+(?:19|20)\d{2}\b/g,
+      allow: (m) => /^0?1\s+January\s/.test(m),
+      context: (before) => namesABirth(leadIn(before)),
+    },
+    {
+      name: "date of birth",
+      // The constructed form. Month is zero-based, so the placeholder is
+      // month 0, day 1. The key is whatever the constant is called.
+      re: /\bnew\s+Date\(\s*(?:19|20)\d{2}\s*,\s*\d{1,2}\s*,\s*\d{1,2}\s*\)/g,
+      allow: (m) => /,\s*0\s*,\s*0?1\s*\)$/.test(m),
+      context: (before) => namesABirth(leadIn(before))
+        || BIRTH_KEY.test(leadIn(before).replace(DATE_CALL, "")),
+    },
+  ];
+}
+
+/** Every finding in one file's text, against the rules and the names. */
+export function findPersonalData(text, rules, names = []) {
+  const hits = [];
+  const lines = text.split("\n");
+  for (const rule of rules) {
+    for (const [i, line] of lines.entries()) {
+      for (const m of line.matchAll(rule.re)) {
+        if (rule.allow?.(m[0])) continue;
+        if (rule.context && !rule.context(line.slice(0, m.index))) continue;
+        hits.push({line: i + 1, rule: rule.name, text: m[0]});
+      }
+    }
+  }
+  for (const name of names) {
+    // No `g`: `.test()` on a global regex advances `lastIndex`, and a name
+    // on consecutive lines would be reported on every other one.
+    const re = new RegExp(
+      `\\b${name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\b`, "i");
+    for (const [i, line] of lines.entries()) {
+      if (re.test(line)) {
+        hits.push({line: i + 1, rule: "name on the local denylist", text: name});
+      }
+    }
+  }
+  return hits;
+}
+
+/* Tracked AND untracked-but-not-ignored: the moment this exists for is the
+ * first commit of a new directory, and a tracked-only listing is blind to
+ * exactly that. Ignored files are left out on purpose; they are the working
+ * directory, where a person's data is supposed to live. */
+function files(stagedOnly) {
+  const args = stagedOnly
+    ? ["diff", "--cached", "--name-only", "--diff-filter=ACMR"]
+    : ["ls-files", "--cached", "--others", "--exclude-standard"];
+  return execFileSync("git", args, {encoding: "utf8"})
+    .split("\n").filter((f) => f && !skip(f) && existsSync(f)
+      && statSync(f).isFile());
+}
+
+function denied(path) {
+  if (!existsSync(path)) return [];
+  return readFileSync(path, "utf8").split("\n")
+    .map((l) => l.trim()).filter((l) => l && !l.startsWith("#"));
+}
+
+/** Every finding across the files, and every file that could not be read,
+ *  with the reason. `read` is the reader, so an unreadable file can be
+ *  tested without making one. */
+export function scan(fileList, read, rules, names) {
+  const hits = [];
+  const unread = [];
+  for (const file of fileList) {
+    let text;
+    try {
+      text = read(file);
+    } catch (error) {
+      unread.push({file, code: error?.code ?? String(error)});
+      continue;
+    }
+    for (const h of findPersonalData(text, rules, names)) hits.push({file, ...h});
+  }
+  return {hits, unread};
+}
+
+async function main() {
+  const mod = await loadConfig("check-personal-data.config.mjs");
+  // `loadConfig` returns the module, so the config is its default export.
+  const config = mod?.default ?? {};
+  const denylist = config.denylist ?? ".personal-data-denylist";
+  const rules = [...identityRules(config.allowEmail), ...(config.rules ?? [])];
+  const names = denied(denylist);
+  const allow = (config.allow ?? []).map((a) =>
+    a instanceof RegExp ? a : new RegExp(a));
+
+  const {hits, unread} = scan(
+    files(process.argv.includes("--staged"))
+      .filter((file) => !allow.some((a) => a.test(file))),
+    (file) => readFileSync(file, "utf8"), rules, names);
+
+  // A file this could not read is a file it did not check, so the run is
+  // incomplete rather than clean, whatever else it found.
+  for (const u of unread) console.error(`  ${u.file}: could not be read (${u.code})`);
+  if (unread.length && !hits.length) {
+    console.error(`\ncheck-personal-data: INCOMPLETE — ${unread.length} file(s) `
+      + "were not checked.\n");
+    process.exit(1);
+  }
+
+  if (hits.length) {
+    console.error("\nPersonal data must not be committed.\n");
+    for (const h of hits) console.error(`  ${h.file}:${h.line}  ${h.rule}: ${h.text}`);
+    console.error(
+      `\n${hits.length} finding(s). Move the data to a working directory `
+      + "outside every repository, or replace it with values that could not "
+      + "be anyone's.\n");
+    process.exit(1);
+  }
+
+  console.log(
+    "check-personal-data: clean"
+    + (names.length ? ` (${names.length} name(s) on the local denylist)`
+      : ` (no ${denylist}; name checking off)`)
+  );
+}
+
+/** True only when this file is the entry point. npm installs a bin as a
+ *  symlink, so compare the resolved path, or `main` never runs in a consumer. */
+const isEntryPoint = () => {
+  try {
+    return import.meta.url === pathToFileURL(realpathSync(process.argv[1])).href;
+  } catch {
+    return false;
+  }
+};
+
+if (isEntryPoint()) main();

package/bin/pre-push.sh

@@ -16,4 +16,5 @@ export PRE_PUSH_REFS
 # simply doesn't.
 npm run check \
   && echo "$PRE_PUSH_REFS" | check-version \
-  && echo "$PRE_PUSH_REFS" | check-tags
+  && echo "$PRE_PUSH_REFS" | check-tags \
+  && echo "$PRE_PUSH_REFS" | check-linear