@casomoltd/tooling 0.36.1 → 0.37.0

package/README.md

@@ -8,8 +8,8 @@ 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 |
@@ -25,7 +25,8 @@ Shared linting, formatting, commit config, and CLI tools for Casomo Ltd's repos.
 | `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 |
+| `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 |

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/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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@casomoltd/tooling",
-  "version": "0.36.1",
+  "version": "0.37.0",
   "description": "Casomo's shared dev config: ESLint, Prettier, commitlint, knip & jscpd presets and dev CLIs (git hooks, readability, screenshots, design specs)",
   "license": "MIT",
   "repository": {
@@ -22,9 +22,10 @@
     "!**/*.test.mjs"
   ],
   "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",
+    "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",
-    "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",
+    "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/casomo-config.test.mjs && node bin/buttondown.test.mjs && node commitlint/index.test.mjs && node readability/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 +34,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",
@@ -58,6 +58,7 @@
     "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",
@@ -80,7 +81,7 @@
   },
   "peerDependencies": {
     "@commitlint/cli": ">=20",
-    "eslint": ">=9",
+    "eslint": ">=9.24",
     "eslint-config-next": ">=16",
     "eslint-plugin-sonarjs": ">=3",
     "jscpd": ">=4",
@@ -89,12 +90,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": {