@casomoltd/tooling 0.36.0 → 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.0",
+  "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",
+    "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,20 +81,24 @@
   },
   "peerDependencies": {
     "@commitlint/cli": ">=20",
-    "eslint": ">=9",
+    "eslint": ">=9.24",
     "eslint-config-next": ">=16",
     "eslint-plugin-sonarjs": ">=3",
     "jscpd": ">=4",
-    "knip": ">=5"
+    "knip": ">=5",
+    "typescript": ">=5"
   },
   "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": {

package/readability/index.mjs

@@ -7,6 +7,7 @@
  */
 
 import rs from "text-readability";
+import ts from "typescript";
 import fs from "node:fs";
 import path from "node:path";
 
@@ -17,6 +18,34 @@ export const DEFAULT_WORD_SUBS = {
   calculator: "tool",
 };
 
+const IMPORT_RE = /import\s+(?:type\s+)?(?:[\w*{},\s]+from\s+)?["']([^"']+)["']/g;
+
+/** Elements that sit inside a sentence rather than starting one: their
+ *  text joins the block around them. Everything else is a block, whose
+ *  text is a sentence or more of its own. Matched on the tag's own text,
+ *  so a member tag (`<Foo.Link>`) counts as a block. */
+const INLINE_TAGS = new Set([
+  "a", "Link", "strong", "em", "b", "i", "u", "span", "code", "abbr",
+  "sup", "sub", "small", "mark", "time", "br", "wbr",
+]);
+
+/** What an interpolated value reads as inside a sentence: a figure. */
+const FIGURE = "1";
+
+/** The shortest string literal read as prose: shorter ones are labels. */
+const MIN_PROSE_CHARS = 20;
+
+/** A run of at least two letters: the least that reads as a word. */
+const HAS_WORD = /[A-Za-z]{2,}/;
+
+/** Typographic entities, read as the characters they stand for. */
+const ENTITIES = {
+  "&nbsp;": " ", "&amp;": "&", "&lt;": "<", "&gt;": ">",
+  "&rsquo;": "\u2019", "&lsquo;": "\u2018", "&rdquo;": "\u201d",
+  "&ldquo;": "\u201c", "&ndash;": "\u2013", "&mdash;": "\u2014",
+  "&hellip;": "\u2026", "&#39;": "'", "&quot;": "\"",
+};
+
 // -------------------------------------------------------------------
 // Discover page slugs from an app-router directory
 // -------------------------------------------------------------------
@@ -72,37 +101,121 @@ function srcDirOf(filePath) {
   return i === -1 ? null : filePath.slice(0, i + marker.length - 1);
 }
 
-const IMPORT_RE = /import\s+(?:type\s+)?(?:[\w*{},\s]+from\s+)?["']([^"']+)["']/g;
+/**
+ * Prose lifted from ONE file's JSX, without following its imports.
+ *
+ * Parsed, because a JSX file is mostly code and code is full of `<` and
+ * `>` (generics, arrow functions, comparisons): only a parser can tell
+ * JSX text from it. What comes back is each block's text, with its links
+ * and emphasis folded into the sentence they sit in and each
+ * interpolated value read as a figure, plus string literals that read as
+ * prose. Those include attribute values, because a component's
+ * `description="…"` is copy on the page, and they also include strings a
+ * reader never sees (a metadata title, an error message): an
+ * approximation of what the page shows, close enough to grade it.
+ */
+function extractOwnText(source, fileName) {
+  const sf = ts.createSourceFile(
+    fileName, source, ts.ScriptTarget.Latest, true, ts.ScriptKind.TSX,
+  );
+  const out = [];
 
-/** Prose lifted from ONE file's JSX, without following its imports. */
-function extractOwnText(source) {
-  const jsxText = [];
-
-  // Tag content. `{` is ALLOWED inside the match and the expressions
-  // are stripped further down. Excluding it dropped the whole sentence
-  // rather than the interpolation, so any served line carrying a
-  // figure — most of the prose on a pay page — was invisible here.
-  const tagContentRe = /&gt;([^&lt;&gt;]+)&lt;/g;
-  let match;
-  while ((match = tagContentRe.exec(source)) !== null) {
-    const text = match[1].replace(/\{[^}]*\}/g, " ").trim();
-    if (text) jsxText.push(text);
-  }
+  const tagOf = (el) => {
+    const opening = ts.isJsxElement(el) ? el.openingElement : el;
+    return opening.tagName.getText(sf);
+  };
+  const isInline = (el) =>
+    (ts.isJsxElement(el) || ts.isJsxSelfClosingElement(el))
+    && INLINE_TAGS.has(tagOf(el));
 
-  // String literals that look like readable prose. "Look like" is
-  // doing real work: an SVG `d` attribute begins with a capital M and
-  // runs for thousands of characters, and counting one as a sentence
-  // put a whole article three grades above its true score.
-  const stringRe = /['"`]([A-Z][^'"`]{20,})['"`]/g;
-  while ((match = stringRe.exec(source)) !== null) {
-    const candidate = match[1].trim();
-    if (isProse(candidate)) jsxText.push(candidate);
-  }
-  // NOT filtered as a whole: tag content is legitimately fragmentary,
-  // because a formatter wraps one served sentence across several
-  // lines. Only string literals need the prose test, and only they can
-  // contain an SVG path.
-  return jsxText;
+  // The text a block reads as: its own text, its inline children's,
+  // and a figure for each interpolation. Block children are left out:
+  // the walk below scores each as its own block.
+  const inlineText = (children) => children.map((child) => {
+    if (ts.isJsxText(child)) return child.text;
+    if (ts.isJsxExpression(child)) {
+      return child.expression ? expressionText(child.expression) : "";
+    }
+    if (isInline(child)) {
+      return ts.isJsxElement(child) ? inlineText(child.children) : " ";
+    }
+    return "";
+  }).join("");
+
+  // What an interpolation reads as. A string is its text; a conditional
+  // reads as its first branch, the one a reader sees by default; inline
+  // JSX joins the sentence; block JSX is scored on its own by the walk
+  // below; anything else is a value, read as a figure.
+  const expressionText = (e) => {
+    if (ts.isParenthesizedExpression(e)) return expressionText(e.expression);
+    if (ts.isStringLiteral(e) || ts.isNoSubstitutionTemplateLiteral(e)) {
+      return e.text;
+    }
+    if (ts.isConditionalExpression(e)) return expressionText(e.whenTrue);
+    if (ts.isBinaryExpression(e)
+      && e.operatorToken.kind === ts.SyntaxKind.AmpersandAmpersandToken) {
+      return expressionText(e.right);
+    }
+    if (isInline(e)) {
+      return ts.isJsxElement(e) ? inlineText(e.children) : " ";
+    }
+    return containsJsx(e) ? "" : ` ${FIGURE} `;
+  };
+
+  const containsJsx = (node) => {
+    let found = false;
+    const look = (n) => {
+      if (found) return;
+      if (ts.isJsxElement(n) || ts.isJsxSelfClosingElement(n)
+        || ts.isJsxFragment(n)) {
+        found = true;
+        return;
+      }
+      ts.forEachChild(n, look);
+    };
+    look(node);
+    return found;
+  };
+
+  // A run of strings joined with `+`, read as the one sentence it is.
+  const stringOf = (node) => {
+    if (ts.isStringLiteral(node) || ts.isNoSubstitutionTemplateLiteral(node)) {
+      return node.text;
+    }
+    if (ts.isTemplateExpression(node)) {
+      return node.head.text + node.templateSpans
+        .map((span) => ` ${FIGURE} ${span.literal.text}`).join("");
+    }
+    if (ts.isParenthesizedExpression(node)) return stringOf(node.expression);
+    if (ts.isBinaryExpression(node)
+      && node.operatorToken.kind === ts.SyntaxKind.PlusToken) {
+      const left = stringOf(node.left);
+      const right = stringOf(node.right);
+      return left === null || right === null ? null : left + right;
+    }
+    return null;
+  };
+
+  const visit = (node) => {
+    const isBlock = (ts.isJsxElement(node) && !isInline(node))
+      || ts.isJsxFragment(node);
+    if (isBlock) {
+      const text = inlineText(node.children).replace(/\s+/g, " ").trim();
+      if (HAS_WORD.test(text)) out.push(text);
+    } else {
+      const text = stringOf(node);
+      if (text !== null) {
+        const prose = text.replace(/\s+/g, " ").trim();
+        const readsAsProse = /^[A-Z]/.test(prose)
+          && prose.length > MIN_PROSE_CHARS && isProse(prose);
+        if (readsAsProse) out.push(prose);
+        return;
+      }
+    }
+    ts.forEachChild(node, visit);
+  };
+  visit(sf);
+  return out;
 }
 
 /**
@@ -119,7 +232,7 @@ function isProse(text) {
   if (compact.length === 0) return false;
   const letters = (compact.match(/[A-Za-z]/g) ?? []).length;
   if (letters / compact.length < 0.6) return false;
-  const words = text.split(/\s+/).filter((w) => /[A-Za-z]{2,}/.test(w));
+  const words = text.split(/\s+/).filter((w) => HAS_WORD.test(w));
   return words.length >= 3;
 }
 
@@ -127,11 +240,8 @@ function isProse(text) {
  * Prose a reader actually sees on a page, following the components it
  * imports.
  *
- * Import-following is the point. Until 3 Sep 2026 this read one file
- * and stopped, so every shared prose component was unmeasured — a
- * notice component scoring grade 12.6 while all five pages rendering
- * it reported PASS. A page's score has to cover what it renders, not
- * what happens to be written in its own file.
+ * Import-following is the point: a page's score has to cover the
+ * components it renders, not only what is written in its own file.
  *
  * Depth-limited and cycle-safe. Only project-local imports are
  * followed; a package's prose is not this site's prose.
@@ -144,9 +254,16 @@ export function extractText(filePath, {maxDepth = 3} = {}) {
   const walk = (file, depth) => {
     const resolved = path.resolve(file);
     if (seen.has(resolved) || depth > maxDepth) return;
+    // Components only. A `.ts` module's strings are mostly data (role
+    // lists, labels, the company statement) that the page shows only in
+    // part or elsewhere, and scoring them graded every page on the same
+    // shared lists. The cost: prose a page renders from a `.ts` module
+    // goes unread.
+    const importedNonComponent = depth > 0 && !resolved.endsWith(".tsx");
+    if (importedNonComponent) return;
     seen.add(resolved);
     const source = fs.readFileSync(resolved, "utf-8");
-    collected.push(...extractOwnText(source));
+    collected.push(...extractOwnText(source, resolved));
     if (depth === maxDepth) return;
     for (const m of source.matchAll(IMPORT_RE)) {
       const target = resolveLocalImport(m[1], resolved, srcDir);
@@ -162,12 +279,7 @@ export function extractText(filePath, {maxDepth = 3} = {}) {
   );
 
   let text = terminated.join(" ");
-  text = text.replace(/\{[^}]*\}/g, " ");
-  text = text.replace(/&amp;nbsp;/g, " ");
-  text = text.replace(/&amp;amp;/g, "&amp;");
-  text = text.replace(/&amp;lt;/g, "&lt;");
-  text = text.replace(/&amp;gt;/g, "&gt;");
-  text = text.replace(/&amp;[a-z]+;/g, " ");
+  text = text.replace(/&#?\w+;/g, (entity) => ENTITIES[entity] ?? " ");
   text = text.replace(/\s+/g, " ").trim();
 
   return text;
@@ -195,10 +307,8 @@ function applyWordSubs(text, wordSubs) {
 /**
  * The floor below which the formulas are not meaningful.
  *
- * A page under it is UNSCORED, not passing. The two used to be
- * indistinguishable — the CLI read a null grade as a pass — so eight
- * of forty-five pages were reported green on the strength of no
- * measurement at all.
+ * A page under it is UNSCORED, not passing: a score that measured
+ * nothing is not evidence the page reads well.
  */
 export const MIN_SCORABLE_WORDS = 100;