@casomoltd/tooling 0.36.1 → 0.38.0

package/README.md

@@ -8,13 +8,14 @@ Shared linting, formatting, commit config, and CLI tools for Casomo Ltd's repos.
 
 | Export | Description |
 |---|---|
-| `@casomoltd/tooling/eslint` | `createBaseConfig()` — ESLint flat config with Next.js, TypeScript, and SonarJS |
-| `@casomoltd/tooling/eslint-lib` | ESLint config variant for library packages |
+| `@casomoltd/tooling/eslint` | `createBaseConfig()` — ESLint flat config with Next.js, TypeScript, SonarJS and the house rules ([docs/lint.md](docs/lint.md)) |
+| `@casomoltd/tooling/eslint-lib` | `createLibConfig()` — the same house rules for a TypeScript library ([docs/lint.md](docs/lint.md)) |
 | `@casomoltd/tooling/prettier` | Prettier config object |
 | `@casomoltd/tooling/commitlint` | commitlint config with `no-ai-attribution` plugin |
 | `@casomoltd/tooling/knip` | Knip config for unused exports/dependencies |
 | `@casomoltd/tooling/jscpd` | Copy-paste detection config |
 | `@casomoltd/tooling/readability` | `scoreText()` — readability scoring for page content |
+| `@casomoltd/tooling/identity` | `CASOMO_ORGANIZATION`, the schema.org `Organization` every Casomo site names as publisher in its JSON-LD. App code imports it at build time, so a site that installs only production dependencies at runtime lists the package under `dependencies` |
 | `@casomoltd/tooling/buttondown` | For a repo using the `buttondown` command: the shared email blocks and skins (`createEmailBlocks`, `emailBaseCss`, `composeWebSkin`), `tokenReader()`, `loadSettings()` and `buildPayload()`, and `EMAIL_CHROME_HIDES` and `WEB_CHROME_HIDES` ([docs/buttondown.md](docs/buttondown.md)) |
 
 ### Bin commands
@@ -23,9 +24,11 @@ Shared linting, formatting, commit config, and CLI tools for Casomo Ltd's repos.
 |---|---|
 | `check-version` | Pre-push guard — rejects push if `package.json` version hasn't changed vs `origin/main` |
 | `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-push` | Husky pre-push hook — runs check, then `check:routes` where a repo defines it, then the version, tag and linear-history guards |
+| `check-routes` | Pre-push gate for a Next.js site — starts `next start` against the build `check` made, requests every page in `/sitemap.xml`, and fails if any is not a 200. Run it as `"check:routes": "check-routes"`; [why it runs on push](#quality-gates) |
 | `pre-commit` | Husky pre-commit hook — runs `npm run check` |
-| `commit-msg` | Husky commit-msg hook — runs commitlint |
+| `commit-msg` | Husky commit-msg hook — runs commitlint, then `check-listed-files` |
+| `check-listed-files` | Refuse a commit that changes a file still listed in `eslint-suppressions.json`, unless a `Lint-deferred:` trailer says why ([docs/lint.md](docs/lint.md)) |
 | `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 |
@@ -285,13 +288,17 @@ the local hooks are the gate, CI is the backstop.
 
 - **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.
+- **pre-push**: `npm run check`, then `check:routes` where the repo
+  defines it, then the version, tag and linear-history 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.
+Exception: `check:routes` reads the build outside `check`. It
+starts a server, which belongs to a push rather than to every
+commit, so the pre-push hook runs it after `check`.
 
 ### What every repo's `check` must contain
 

package/bin/check-gates.mjs

@@ -9,8 +9,10 @@
 //
 // 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)
+//   2. no gate-shaped script is defined but left unreferenced (a dead gate),
+//      other than a pre-push gate, which the hook runs instead
 //   3. no exception outlives the problem it was written for
+//   4. no pre-push gate is run by `check`, which every commit pays 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:
@@ -38,6 +40,11 @@ export const REQUIRED = [
 /** Gate-shaped but not mandatory: still dead if defined and never run. */
 export const OPTIONAL = ["check:readability"];
 
+/** Gates the pre-push hook runs after `check`, never `check` itself: they
+ * start a server against the build, which a commit should not pay for.
+ * bin/pre-push.sh runs each by name, so the two lists must match. */
+export const PRE_PUSH = ["check:routes"];
+
 /** 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. */
@@ -54,45 +61,57 @@ export const referencedGates = (check) =>
       .filter(Boolean),
   );
 
+/** Each required gate that is not defined, or defined but never run. */
+const requiredFailures = (scripts, run) =>
+  REQUIRED.flatMap((gate) => {
+    if (!(gate in scripts)) return [[gate, `required gate is not defined`]];
+    if (!run.has(gate)) {
+      return [[gate, `required gate is defined but \`check\` never runs it`]];
+    }
+    return [];
+  });
+
+/** Each other gate-shaped script that `check` never runs. `check` itself is
+ * the chain, not a step within it, and the hook runs a pre-push gate. */
+const deadGates = (scripts, run) =>
+  Object.keys(scripts)
+    .filter((n) => isGate(n) && n !== "check" && !REQUIRED.includes(n))
+    .filter((gate) => !PRE_PUSH.includes(gate))
+    .filter((gate) => !run.has(gate))
+    .map((gate) => [gate, `defined but \`check\` never runs it — a dead gate`]);
+
+/** Each pre-push gate that `check` runs, so every commit starts a server. */
+const prePushInCheck = (run) =>
+  PRE_PUSH.filter((gate) => run.has(gate)).map((gate) => [
+    gate,
+    `a pre-push gate: \`check\` runs on every commit`,
+  ]);
+
+/** Sort the failures by their exception: none, a blank reason, or a reason. */
+const byException = (failures, exceptions) => {
+  const sorted = {live: [], excused: [], unreasoned: []};
+  for (const [gate, reason] of failures) {
+    if (!(gate in exceptions)) sorted.live.push([gate, reason]);
+    else if (!String(exceptions[gate] ?? "").trim()) sorted.unreasoned.push(gate);
+    else sorted.excused.push([gate, exceptions[gate]]);
+  }
+  return sorted;
+};
+
 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]]);
-    }
-  }
-
+  const failures = [
+    ...requiredFailures(scripts, run),
+    ...deadGates(scripts, run),
+    ...prePushInCheck(run),
+  ];
   // 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};
+  return {...byException(failures, exceptions), stale};
 };
 
 const main = () => {

package/bin/check-listed-files.mjs

@@ -0,0 +1,127 @@
+#!/usr/bin/env node
+/**
+ * Refuse a commit that changes a file still listed in the repo's
+ * `eslint-suppressions.json`, unless the message says why it is deferred.
+ *
+ * The house size limits are lint errors, and a file that already broke one
+ * when the limit was switched on is listed there instead of failing. The
+ * list only shrinks if touching a file is the moment it is tidied: tidy it
+ * in its own commit (fix it, then `eslint --prune-suppressions`), and the
+ * change that needed it follows. ESLint itself fails while a fixed file
+ * keeps its entry, so a tidied file always comes off the list. A commit that
+ * has to change a listed file anyway carries a trailer naming why, so the
+ * deferral shows in `git log`:
+ *
+ *   Lint-deferred: a one-line hotfix; the tidy follows in its own commit
+ *
+ * What it reads, and what it assumes:
+ *
+ * - **The list as staged**, so the commit that tidies a file and drops its
+ *   entry passes.
+ * - **The files staged now**, renames counted under their old path too. An
+ *   amend is checked on what it newly stages, not on the whole commit.
+ * - **One list, at the repo root**, keyed by root-relative path, which is
+ *   where ESLint writes it when run from the root. A list anywhere else
+ *   fails the check rather than being silently missed.
+ * - **No merge commits:** a merge carries changes each branch already
+ *   committed and was checked for.
+ *
+ * Runs from the shared commit-msg hook, the first point the message exists.
+ *
+ * Usage:
+ *   check-listed-files <commit-message-file>
+ */
+import {execFileSync} from "node:child_process";
+import {readFileSync, realpathSync} from "node:fs";
+import {pathToFileURL} from "node:url";
+
+/** ESLint's default suppressions file, at the repo root. */
+export const SUPPRESSIONS_FILE = "eslint-suppressions.json";
+/** The trailer that lets a listed file through, with a reason on the same
+ *  line. Git reads trailer keys without regard to case. */
+export const DEFERRED_TRAILER = /^Lint-deferred:[ \t]*\S/im;
+
+/**
+ * The staged files that are listed, each with the rules it is listed for.
+ *
+ * @param {readonly string[]} staged - repo-relative paths in the commit
+ * @param {Record<string, Record<string, {count: number}>>} listed - the
+ *   staged suppressions file, keyed by repo-relative path
+ * @returns {{file: string, rules: string[]}[]}
+ */
+export function listedInCommit(staged, listed) {
+  return staged
+    .filter((file) => Object.hasOwn(listed, file))
+    .map((file) => ({file, rules: Object.keys(listed[file])}));
+}
+
+/** Whether the message defers the tidy with a reason. */
+export function defers(message) {
+  return DEFERRED_TRAILER.test(message);
+}
+
+const git = (...args) => execFileSync("git", args,
+  {encoding: "utf8", stdio: ["ignore", "pipe", "pipe"]});
+
+/** Whether git can resolve a ref or object, without throwing. */
+function resolves(ref) {
+  try {
+    git("rev-parse", "-q", "--verify", ref);
+    return true;
+  } catch {
+    // Not resolvable is the answer asked for, not a failure.
+    return false;
+  }
+}
+
+/** The repo's suppressions as staged; none where the repo stages no list.
+ *  A list that is staged but unreadable throws: it is not an empty list. */
+function stagedSuppressions() {
+  if (!resolves(`:${SUPPRESSIONS_FILE}`)) return {};
+  return JSON.parse(git("show", `:${SUPPRESSIONS_FILE}`));
+}
+
+/** Suppressions files tracked anywhere but the repo root. */
+function listsBelowRoot() {
+  return git("ls-files", `*${SUPPRESSIONS_FILE}`).split("\n")
+    .filter((path) => path && path !== SUPPRESSIONS_FILE);
+}
+
+/** The paths the commit touches, a rename under both its old and new path
+ *  and a deletion under its own. */
+function stagedPaths() {
+  return git("diff", "--cached", "--name-only", "--no-renames",
+    "--diff-filter=ACMRD").split("\n").filter(Boolean);
+}
+
+function main(messageFile) {
+  if (resolves("MERGE_HEAD")) return;
+  const elsewhere = listsBelowRoot();
+  if (elsewhere.length > 0) {
+    console.error("check-listed-files: suppressions lists below the repo "
+      + `root are not read, so this check cannot hold: ${elsewhere.join(", ")}`);
+    process.exit(1);
+  }
+  const hits = listedInCommit(stagedPaths(), stagedSuppressions());
+  if (hits.length === 0) return;
+  if (defers(readFileSync(messageFile, "utf8"))) {
+    for (const {file} of hits) {
+      console.warn(`check-listed-files: ${file} is listed; tidy deferred`);
+    }
+    return;
+  }
+  console.error("check-listed-files: this commit changes files listed in "
+    + `${SUPPRESSIONS_FILE}. Tidy each in its own commit first (fix it, `
+    + "then eslint --prune-suppressions), or add a 'Lint-deferred: <why>' "
+    + "trailer:");
+  for (const {file, rules} of hits) {
+    console.error(`  ${file}: ${rules.join(", ")}`);
+  }
+  process.exit(1);
+}
+
+// Run through npm's bin symlink, argv[1] is the link and import.meta.url
+// the real file, so compare real paths.
+if (import.meta.url === pathToFileURL(realpathSync(process.argv[1])).href) {
+  main(process.argv[2]);
+}

package/bin/check-routes.mjs

@@ -0,0 +1,218 @@
+#!/usr/bin/env node
+/**
+ * Request every page a built Next.js site lists in its sitemap from
+ * `next start` on a local port, and fail if any answers anything but 200.
+ *
+ * A build can pass while a page still fails at request time: a server
+ * component that throws, or a fetch that breaks only when the page renders.
+ * The pre-push hook runs this after `npm run check`, against the build
+ * `check` has just made; it makes no build of its own. It stays out of
+ * `check` because the pre-commit hook runs `check`, and starting a server
+ * belongs to a push, not to every commit.
+ *
+ * It reads the sitemap Next emits: plain `<loc>` elements, in a urlset or a
+ * sitemap index one level deep, with `&amp;` the only entity in a URL.
+ *
+ * Usage, in the site's root after `next build`:
+ *   check-routes
+ *
+ * Exit codes:
+ *   0  every listed page answered 200
+ *   1  a page did not, the sitemap failed or listed none, or the server
+ *      never started
+ */
+
+import {spawn} from "node:child_process";
+import {existsSync, realpathSync} from "node:fs";
+import {createServer} from "node:net";
+import {setTimeout as sleep} from "node:timers/promises";
+import {pathToFileURL} from "node:url";
+
+const HOST = "127.0.0.1";
+const SITEMAP = "/sitemap.xml";
+// The default distDir; a site that moves it is not supported.
+const BUILD_ID = ".next/BUILD_ID";
+// The site's own `next`, never one `npx` would offer to download.
+const NEXT_BIN = "node_modules/.bin/next";
+const HTTP_OK = 200;
+const READY_POLL_MS = 250;
+const READY_TIMEOUT_MS = 60_000;
+// A page waiting on a dead upstream must fail the push, not hang it.
+const REQUEST_TIMEOUT_MS = 30_000;
+// Enough to keep a few hundred pages quick without starving the server.
+const CONCURRENCY = 8;
+
+/** Probe every path, CONCURRENCY at a time; return the ones not 200. */
+export const failingPages = async (base, paths) => {
+  const queue = [...paths];
+  const failures = [];
+  const worker = async () => {
+    for (let path = queue.shift(); path !== undefined; path = queue.shift()) {
+      const result = await probe(base, path);
+      if (result.status !== HTTP_OK) failures.push(result);
+    }
+  };
+  await Promise.all(Array.from({length: CONCURRENCY}, worker));
+  return failures;
+};
+
+/** The path and query of every `<loc>` in a sitemap or sitemap index. The
+ * sitemap names the production host; the check asks the local server. */
+const sitemapPaths = (xml) =>
+  [...xml.matchAll(/<loc>([^<]+)<\/loc>/g)].map(([, loc]) => {
+    const url = new URL(loc.trim().replaceAll("&amp;", "&"));
+    return url.pathname + url.search;
+  });
+
+/** A sitemap index lists other sitemaps, not pages. */
+const isSitemapIndex = (xml) => /<sitemapindex[\s>]/.test(xml);
+
+const message = (err) => (err instanceof Error ? err.message : String(err));
+
+const get = (url, init = {}) =>
+  fetch(url, {...init, signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS)});
+
+/** A sitemap's text; any answer but 200 is the failure, not a retry. */
+const readSitemap = async (base, path) => {
+  const res = await get(base + path);
+  if (res.status !== HTTP_OK) throw new Error(`${path} answered ${res.status}`);
+  return res.text();
+};
+
+/** Every page path, once each, following a sitemap index one level down. */
+const collectPaths = async (base, rootXml) => {
+  if (!isSitemapIndex(rootXml)) return [...new Set(sitemapPaths(rootXml))];
+  const children = await Promise.all(
+    sitemapPaths(rootXml).map((path) => readSitemap(base, path)),
+  );
+  return [...new Set(children.flatMap(sitemapPaths))];
+};
+
+/** One page's status, or the error that stopped the request. A redirect
+ * counts as a failure: a sitemap should list where a page lives. */
+const probe = async (base, path) => {
+  try {
+    const res = await get(base + path, {redirect: "manual"});
+    await res.arrayBuffer();
+    return {path, status: res.status};
+  } catch (err) {
+    return {path, error: message(err)};
+  }
+};
+
+/** A free local port, so a dev server already on 3000 is never in the way. */
+const freePort = () =>
+  new Promise((resolve, reject) => {
+    const listener = createServer();
+    listener.on("error", reject);
+    listener.listen(0, HOST, () => {
+      const {port} = listener.address();
+      listener.close(() => resolve(port));
+    });
+  });
+
+/** `next start` in its own process group, so the stop reaches `next-server`
+ * and not only its launcher. `died` rejects the moment the server fails to
+ * spawn or exits, so a dead server fails the check now, not at the timeout. */
+const startServer = (port) => {
+  const server = spawn(NEXT_BIN, ["start", "-p", String(port), "-H", HOST], {
+    stdio: ["ignore", "pipe", "pipe"],
+    detached: true,
+  });
+  const output = [];
+  server.stdout.on("data", (d) => output.push(String(d)));
+  server.stderr.on("data", (d) => output.push(String(d)));
+  const died = new Promise((_, reject) => {
+    server.on("error", (err) => reject(new Error(`could not start next: ${err}`)));
+    server.on("exit", (code) =>
+      reject(new Error(`next start exited (${code})\n${output.join("")}`)),
+    );
+  });
+  // The exit the stop itself causes is expected, so nothing awaits it then.
+  died.catch(() => {});
+  return {server, output, died};
+};
+
+/** Stop the server's process group; one that has already exited is fine. */
+const stopServer = (server) => {
+  if (server.pid === undefined) return;
+  try {
+    process.kill(-server.pid, "SIGTERM");
+  } catch (err) {
+    if (err?.code !== "ESRCH") throw err;
+  }
+};
+
+/** The root sitemap once the server answers; keep polling only while the
+ * connection is refused. */
+const waitForSitemap = async (base, output) => {
+  const deadline = Date.now() + READY_TIMEOUT_MS;
+  while (Date.now() < deadline) {
+    try {
+      return await readSitemap(base, SITEMAP);
+    } catch (err) {
+      if (!(err instanceof TypeError)) throw err;
+    }
+    await sleep(READY_POLL_MS);
+  }
+  throw new Error(`the server never answered ${SITEMAP}\n${output.join("")}`);
+};
+
+const report = (count, failures) => {
+  if (count === 0) {
+    console.error(`✗ check-routes: ${SITEMAP} lists no pages`);
+    return 1;
+  }
+  if (failures.length > 0) {
+    console.error(`✗ check-routes: ${failures.length} of ${count} pages failed`);
+    for (const {path, status, error} of failures) {
+      console.error(`  ${status ?? error}  ${path}`);
+    }
+    return 1;
+  }
+  console.log(`✓ check-routes: ${count} pages answered 200`);
+  return 0;
+};
+
+/** Start the server, check every page, stop it; the exit code. */
+const run = async () => {
+  const port = await freePort();
+  const base = `http://${HOST}:${port}`;
+  const {server, output, died} = startServer(port);
+  try {
+    const rootXml = await Promise.race([waitForSitemap(base, output), died]);
+    const paths = await collectPaths(base, rootXml);
+    return report(paths.length, await failingPages(base, paths));
+  } catch (err) {
+    console.error(`✗ check-routes: ${message(err)}`);
+    return 1;
+  } finally {
+    stopServer(server);
+  }
+};
+
+const main = async () => {
+  if (!existsSync(BUILD_ID)) {
+    console.error(
+      `✗ check-routes: no ${BUILD_ID}; run \`next build\` first`
+        + " (a custom distDir is not supported)",
+    );
+    process.exit(1);
+  }
+  const code = await run();
+  // The server's pipes can keep node alive past the stop; the check is done.
+  process.exit(code);
+};
+
+/** True only when this file is the entry point. npm installs a bin as a
+ * symlink, so `process.argv[1]` is the link while `import.meta.url` is the
+ * target it resolves to: resolve before comparing, or `main` never runs. */
+const isEntryPoint = () => {
+  try {
+    return import.meta.url === pathToFileURL(realpathSync(process.argv[1])).href;
+  } catch {
+    return false;
+  }
+};
+
+if (isEntryPoint()) await main();

package/bin/commit-msg.sh

@@ -1,2 +1,6 @@
 #!/bin/sh
+# Stop at the first check that fails, so a later one cannot mask it.
+set -e
 npx --no -- commitlint --edit "$1"
+# Resolve the npm bin symlink so the check is found beside this script.
+node "$(dirname "$(realpath "$0")")/check-listed-files.mjs" "$1"

package/bin/pre-push.sh

@@ -14,7 +14,12 @@ export PRE_PUSH_REFS
 # 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.
+#
+# `check:routes` runs after `check`, not in it: see the README, "Quality
+# gates". Repos without it skip it. Every gate in PRE_PUSH
+# (bin/check-gates.mjs) must be run here.
 npm run check \
+  && npm run --if-present check:routes \
   && echo "$PRE_PUSH_REFS" | check-version \
   && echo "$PRE_PUSH_REFS" | check-tags \
   && echo "$PRE_PUSH_REFS" | check-linear

package/bin/verify-pack.mjs

@@ -4,7 +4,8 @@
 // the allowlist and never look like a secret. Defence-in-depth on top of
 // package.json "files" — this fails CI if that allowlist is ever loosened
 // or a secret-bearing file sneaks in. The tooling repo is public, so the
-// published/installed surface must stay configs + CLI only.
+// published/installed surface must stay configs, CLIs and the build-time
+// data sites import, and nothing private.
 import {execSync} from "node:child_process";
 
 // Dirs/files a consumer is allowed to receive. npm always adds
@@ -20,12 +21,21 @@ const ALLOWED_PREFIXES = [
   "report/",
   "styles/",
   "buttondown/",
+  "identity/",
 ];
 const ALLOWED_FILES = ["README.md", "package.json", "LICENSE", "LICENSE.md"];
 
-// Anything matching these must never ship, even from an allowed dir.
-const SECRET_PATTERN =
-  /(^|\/)(\.env(\..*)?|.*settings\.local\.json|.*\.pem|id_[rd]sa|.*\.key|\.npmrc)$/i;
+// A file whose name alone marks it as a secret must never ship, even from an
+// allowed dir: an env file, local settings, a key, or an npm token file.
+const SECRET_NAMES = new Set([".env", ".npmrc", "id_rsa", "id_dsa"]);
+const SECRET_ENDINGS = [".pem", ".key", "settings.local.json"];
+
+function looksSecret(path) {
+  const name = path.slice(path.lastIndexOf("/") + 1).toLowerCase();
+  return SECRET_NAMES.has(name)
+    || name.startsWith(".env.")
+    || SECRET_ENDINGS.some((ending) => name.endsWith(ending));
+}
 
 // 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
@@ -40,7 +50,7 @@ const escaped = files.filter(
     !ALLOWED_FILES.includes(f) &&
     !ALLOWED_PREFIXES.some((prefix) => f.startsWith(prefix)),
 );
-const secrets = files.filter((f) => SECRET_PATTERN.test(f));
+const secrets = files.filter(looksSecret);
 const tests = files.filter((f) => TEST_PATTERN.test(f));
 
 if (escaped.length || secrets.length || tests.length) {

package/eslint/house-rules.mjs

@@ -0,0 +1,102 @@
+/**
+ * The house rules every repo's ESLint config shares: line length; the size
+ * of a function, its parameter list, a file, its branching and nesting;
+ * named numbers; no non-null assertions; and exhaustive switches. Both the
+ * Next config (`index.mjs`) and the library config (`lib.mjs`) spread these
+ * in, so each rule is stated once. Every rule is on unless a reason is
+ * written beside the exception.
+ *
+ * They are errors, never warnings: a warning nobody has to act on is how a
+ * module grows past what anyone can read. A file that already breaks one is
+ * recorded in the repo's `eslint-suppressions.json` (`eslint
+ * --suppress-all`), and `check-listed-files` fails a commit that touches it
+ * until it is tidied, unless the message carries a `Lint-deferred:` reason.
+ * A repo whose files are transcribed reference data (published tables,
+ * cited at the data) exempts those paths from
+ * `@typescript-eslint/no-magic-numbers` in its own config, saying why.
+ * What each rule is for, and every exemption, is in `docs/lint.md`.
+ */
+
+/** Lines a function may run to, blank lines and comments not counted:
+ *  ESLint's default. */
+const FUNCTION_LINES = 50;
+/** Parameters a function may take; past this, pass a value object.
+ *  Proposed here; no external source (ESLint's default is 3). */
+const PARAMS = 4;
+/** Lines a file may run to, blank lines and comments not counted.
+ *  Proposed here; no external source (ESLint's default is 300). */
+const FILE_LINES = 400;
+/** Cyclomatic complexity a function may reach. Proposed here; no external
+ *  source (ESLint's default is 20). */
+const COMPLEXITY = 10;
+
+/** How deep blocks may nest before the code should be flattened.
+ *  Proposed here; no external source (ESLint's default is 4). */
+const DEPTH = 3;
+
+const SKIP_BLANKS_AND_COMMENTS = { skipBlankLines: true, skipComments: true };
+
+/** The rules, as one flat-config block for every file. */
+export const HOUSE_RULES = {
+  rules: {
+    // URLs and regex literals are the deviations from 88: neither can be
+    // broken without changing it. No other long line is allowed, so strings
+    // and template literals are not exempt.
+    'max-len': [
+      'error',
+      { code: 88, ignoreUrls: true, ignoreRegExpLiterals: true },
+    ],
+    'max-lines-per-function': [
+      'error', { max: FUNCTION_LINES, ...SKIP_BLANKS_AND_COMMENTS },
+    ],
+    // The TypeScript version does not count a `this:` type annotation.
+    'max-params': 'off',
+    '@typescript-eslint/max-params': ['error', { max: PARAMS }],
+    'max-lines': ['error', { max: FILE_LINES, ...SKIP_BLANKS_AND_COMMENTS }],
+    complexity: ['error', COMPLEXITY],
+    'max-depth': ['error', DEPTH],
+    // A number in code is named, so the reader sees what it is. Counting
+    // and indexing numbers, enums and type positions are not magic, nor a
+    // parameter's default or a readonly class property, which already name
+    // the number they hold. The TypeScript version replaces the base rule.
+    'no-magic-numbers': 'off',
+    '@typescript-eslint/no-magic-numbers': ['error', {
+      ignore: [-1, 0, 1],
+      ignoreArrayIndexes: true,
+      ignoreDefaultValues: true,
+      ignoreEnums: true,
+      ignoreNumericLiteralTypes: true,
+      ignoreReadonlyClassProperties: true,
+      ignoreTypeIndexes: true,
+    }],
+    // A `!` tells the compiler a value exists without checking that it does.
+    '@typescript-eslint/no-non-null-assertion': 'error',
+  },
+};
+
+/** Rules that need the type checker, for TypeScript files only. A switch
+ *  over a union names every member, so a new member is a lint error at each
+ *  switch rather than a silent fall-through. Type information also brings on the
+ *  type-aware rules in sonarjs's recommended set, which are silent
+ *  without it. */
+export const TYPED_RULES = {
+  files: ['**/*.ts', '**/*.tsx', '**/*.mts'],
+  // A declaration file holds no code to switch on.
+  ignores: ['**/*.d.ts', '**/*.d.mts'],
+  languageOptions: { parserOptions: { projectService: true } },
+  rules: { '@typescript-eslint/switch-exhaustiveness-check': 'error' },
+};
+
+/** A test file's cases often sit in one top-level function by design (a
+ *  `describe` block, an assert script), and its expected figures are
+ *  literals by design, so function length and magic numbers are not held
+ *  against test files; every other limit is. */
+export const TEST_FILES_EXEMPT = {
+  files: [
+    '**/*.test.*', '**/*.spec.*', '**/tests/**', '**/test/**', '**/__tests__/**',
+  ],
+  rules: {
+    'max-lines-per-function': 'off',
+    '@typescript-eslint/no-magic-numbers': 'off',
+  },
+};

package/eslint/index.mjs

@@ -1,3 +1,5 @@
+import {HOUSE_RULES, TEST_FILES_EXEMPT, TYPED_RULES} from "./house-rules.mjs";
+
 /**
  * Creates the shared ESLint base config.
  *
@@ -33,19 +35,8 @@ export function createBaseConfig({
         "@typescript-eslint/no-require-imports": "off",
       },
     },
-    {
-      rules: {
-        "max-len": [
-          "error",
-          {
-            code: 88,
-            ignoreUrls: true,
-            ignoreStrings: true,
-            ignoreTemplateLiterals: true,
-            ignoreRegExpLiterals: true,
-          },
-        ],
-      },
-    },
+    HOUSE_RULES,
+    TYPED_RULES,
+    TEST_FILES_EXEMPT,
   ]);
 }

package/eslint/lib.mjs

@@ -1,3 +1,5 @@
+import {HOUSE_RULES, TEST_FILES_EXEMPT, TYPED_RULES} from './house-rules.mjs';
+
 /**
  * Creates a shared ESLint config for TypeScript libraries
  * (non-Next.js projects).
@@ -22,19 +24,19 @@ export function createLibConfig({tseslint, sonarjs}) {
         '@typescript-eslint/no-require-imports': 'off',
       },
     },
+    HOUSE_RULES,
+    TYPED_RULES,
     {
-      rules: {
-        'max-len': [
-          'error',
-          {
-            code: 88,
-            ignoreUrls: true,
-            ignoreStrings: true,
-            ignoreTemplateLiterals: true,
-            ignoreRegExpLiterals: true,
-          },
-        ],
+      // A library's tsconfig includes only its sources and tests, so a root
+      // config file (vitest.config.ts) sits outside every project.
+      files: TYPED_RULES.files,
+      ignores: TYPED_RULES.ignores,
+      languageOptions: {
+        parserOptions: {
+          projectService: {allowDefaultProject: ['*.config.ts', '*.config.mts']},
+        },
       },
     },
+    TEST_FILES_EXEMPT,
   );
 }

package/identity/index.d.mts

@@ -0,0 +1,14 @@
+/** Casomo Ltd as a schema.org `Organization`, for a page's JSON-LD.
+ *
+ *  Every field is read-only because the value is frozen: spread it into an
+ *  untyped object literal, or type a JSON-LD field that holds it as
+ *  `readonly string[]`, never as `string[]`. */
+export interface CasomoOrganization {
+  readonly "@type": "Organization";
+  readonly "@id": string;
+  readonly name: string;
+  readonly url: string;
+  readonly sameAs: readonly string[];
+}
+
+export declare const CASOMO_ORGANIZATION: CasomoOrganization;

package/identity/index.mjs

@@ -0,0 +1,6 @@
+/**
+ * The public face of the identity entry: what a site imports. The value
+ * lives in organization.mjs, where the typecheck can read it against the
+ * declaration here; beside a .d.mts, TypeScript would skip it.
+ */
+export {CASOMO_ORGANIZATION} from "./organization.mjs";

package/identity/organization.mjs

@@ -0,0 +1,24 @@
+/**
+ * Casomo Ltd as search engines should see it: the one schema.org
+ * `Organization` every Casomo site names in its JSON-LD. Each site imports
+ * this rather than typing its own, so no two sites can disagree about who
+ * publishes them, and `sameAs` ties them all to the same profiles.
+ *
+ * Public facts only: the company's name and the addresses its pages already
+ * print. A person, such as an article's author, stays with the site.
+ */
+const SITE = "https://casomoltd.com";
+
+/** @type {import("./index.d.mts").CasomoOrganization} */
+export const CASOMO_ORGANIZATION = Object.freeze({
+  "@type": "Organization",
+  // One id across every site, so a crawler merges them into one entity.
+  "@id": `${SITE}/#organization`,
+  name: "Casomo Ltd",
+  url: SITE,
+  sameAs: Object.freeze([
+    "https://casomo.co.uk",
+    "https://www.facebook.com/casomouk",
+    "https://www.linkedin.com/company/111967567/",
+  ]),
+});

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@casomoltd/tooling",
-  "version": "0.36.1",
-  "description": "Casomo's shared dev config: ESLint, Prettier, commitlint, knip & jscpd presets and dev CLIs (git hooks, readability, screenshots, design specs)",
+  "version": "0.38.0",
+  "description": "Casomo's shared dev config: ESLint, Prettier, commitlint, knip & jscpd presets, dev CLIs (git hooks, readability, screenshots, design specs), and the build-time data and helpers sites import (the Buttondown engine, the shared Organization)",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -18,13 +18,16 @@
     "report/",
     "styles/",
     "buttondown/",
+    "identity/",
     "README.md",
-    "!**/*.test.mjs"
+    "!**/*.test.mjs",
+    "!identity/tsconfig.json"
   ],
   "scripts": {
-    "check": "node bin/check-gates.mjs && node bin/verify-pack.mjs && npm run check:private-refs && npm run check:personal-data && 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 && node bin/check-personal-data.test.mjs && node bin/casomo-config.test.mjs && node bin/buttondown.test.mjs && node commitlint/index.test.mjs && node readability/index.test.mjs",
+    "check": "node bin/check-gates.mjs && node bin/verify-pack.mjs && npm run check:private-refs && npm run check:personal-data && npm run lint && npm run typecheck && npm run test && npm run lint:md",
+    "lint": "eslint .",
+    "typecheck": "tsc --noEmit -p hooks/tsconfig.json && tsc --noEmit -p identity/tsconfig.json",
+    "test": "node hooks/test.mts && node bin/check-gates.test.mjs && node bin/check-listed-files.test.mjs && node bin/check-personal-data.test.mjs && node bin/check-routes.test.mjs && node bin/casomo-config.test.mjs && node bin/buttondown.test.mjs && node commitlint/index.test.mjs && node readability/index.test.mjs && node identity/index.test.mjs",
     "lint:md": "remark --frail --quiet --no-stdout --rc-path bin/skills-lint.config.mjs skills agents docs",
     "build": "echo 'no-op: source-only repo, nothing to build'",
     "prepare": "husky || true",
@@ -33,7 +36,6 @@
   },
   "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",
@@ -51,6 +53,10 @@
     "./buttondown": {
       "types": "./buttondown/index.d.mts",
       "default": "./buttondown/index.mjs"
+    },
+    "./identity": {
+      "types": "./identity/index.d.mts",
+      "default": "./identity/index.mjs"
     }
   },
   "bin": {
@@ -58,9 +64,11 @@
     "buttondown": "./bin/buttondown.mjs",
     "check-gates": "./bin/check-gates.mjs",
     "check-hooks": "./bin/check-hooks.sh",
+    "check-listed-files": "./bin/check-listed-files.mjs",
     "check-linear": "./bin/check-linear.sh",
     "check-personal-data": "./bin/check-personal-data.mjs",
     "check-private-refs": "./bin/check-private-refs.mjs",
+    "check-routes": "./bin/check-routes.mjs",
     "check-tags": "./bin/check-tags.sh",
     "check-version": "./bin/check-version.sh",
     "commit-msg": "./bin/commit-msg.sh",
@@ -80,7 +88,7 @@
   },
   "peerDependencies": {
     "@commitlint/cli": ">=20",
-    "eslint": ">=9",
+    "eslint": ">=9.24",
     "eslint-config-next": ">=16",
     "eslint-plugin-sonarjs": ">=3",
     "jscpd": ">=4",
@@ -89,12 +97,15 @@
   },
   "devDependencies": {
     "@types/node": "^26.0.0",
+    "eslint": "^9.39.5",
+    "eslint-plugin-sonarjs": "^4.2.2",
     "husky": "^9.1.7",
     "remark-cli": "^12.0.1",
     "remark-frontmatter": "^5.0.0",
     "remark-lint-frontmatter-schema": "^3.15.4",
     "remark-validate-links": "^13.1.0",
-    "typescript": "^6.0.3"
+    "typescript": "^6.0.3",
+    "typescript-eslint": "^8.72.0"
   },
   "overrides": {
     "remark-lint-frontmatter-schema": {