@casomoltd/tooling 0.23.5 → 0.24.0

package/bin/check-private-refs.mjs

@@ -0,0 +1,175 @@
+#!/usr/bin/env node
+/**
+ * Fail a PUBLIC repo that names something only its authors can reach.
+ *
+ * A private tracker link, an internal hostname, the name of a repo
+ * nobody outside can clone — each is a disclosure, and none of them is
+ * a syntax error. Existing cover is guidance and a human reviewer, both
+ * fallible, for a mistake that is unrecoverable the moment it is
+ * pushed: the commit is public even if the file is deleted afterwards.
+ *
+ * The failure this exists for is not carelessness. It is a CORRECT rule
+ * followed into the wrong repo — "link the tracking task" is good
+ * advice, and doing it in a published package is how the reference gets
+ * out. So the check runs on the repo's visibility, not on the author's
+ * intent.
+ *
+ * VISIBILITY FIRST, always. A private repo SHOULD carry tracker links;
+ * flagging them there would train everyone to ignore this.
+ *
+ * Deliberately configurable rather than opinionated. This file ships in
+ * a public package, so it cannot itself name anybody's private repos,
+ * boards or hosts — that would be the disclosure it exists to prevent.
+ * The defaults cover hosted trackers that are private by default; a
+ * consuming repo adds its own names in `check-private-refs.config.mjs`:
+ *
+ *   export default {
+ *     visibility: 'public',        // optional; skips the gh lookup
+ *     forbidden: [                 // strings or RegExp
+ *       {pattern: /internal\.example\.net/, why: 'internal hostname'},
+ *     ],
+ *     allow: [/CHANGELOG\.md$/],   // paths exempted, with care
+ *   };
+ */
+
+import {execFileSync} from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import {loadConfig} from "./utils.mjs";
+
+/**
+ * Hosted trackers whose links are private by default.
+ *
+ * Generic on purpose: every one of these is a product many teams use,
+ * so naming them discloses nothing about who is running this check.
+ */
+const DEFAULT_FORBIDDEN = [
+  {pattern: /\bnotion\.so\//i, why: "Notion link"},
+  {pattern: /\bapp\.notion\.com\//i, why: "Notion link"},
+  {pattern: /\blinear\.app\/[\w-]+\/issue\//i, why: "Linear issue link"},
+  {pattern: /\b[\w-]+\.atlassian\.net\//i, why: "Jira/Confluence link"},
+  {pattern: /\bapp\.shortcut\.com\//i, why: "Shortcut story link"},
+  {pattern: /\bapp\.asana\.com\//i, why: "Asana task link"},
+  {pattern: /\btrello\.com\/c\//i, why: "Trello card link"},
+  {pattern: /\bheight\.app\//i, why: "Height task link"},
+];
+
+/** Text files only. A match inside a binary is noise, not a leak. */
+const SKIP_EXT = new Set([
+  ".png", ".jpg", ".jpeg", ".gif", ".webp", ".avif", ".ico", ".svg",
+  ".pdf", ".woff", ".woff2", ".ttf", ".otf", ".eot",
+  ".zip", ".gz", ".tgz", ".mp4", ".webm", ".lock",
+]);
+
+function repoVisibility(configured) {
+  if (configured) return configured;
+  try {
+    const out = execFileSync(
+      "gh", ["repo", "view", "--json", "visibility", "-q", ".visibility"],
+      {encoding: "utf-8", stdio: ["ignore", "pipe", "ignore"]},
+    );
+    return out.trim().toLowerCase();
+  } catch {
+    return null;
+  }
+}
+
+function trackedFiles() {
+  const out = execFileSync("git", ["ls-files"], {encoding: "utf-8"});
+  return out.split("\n").filter(Boolean);
+}
+
+function toMatchers(entries) {
+  return entries.map((e) => {
+    if (typeof e === "string") {
+      return {pattern: new RegExp(e), why: e};
+    }
+    if (e instanceof RegExp) return {pattern: e, why: String(e)};
+    return {
+      pattern: e.pattern instanceof RegExp
+        ? e.pattern
+        : new RegExp(e.pattern),
+      why: e.why ?? String(e.pattern),
+    };
+  });
+}
+
+async function main() {
+  const mod = await loadConfig("check-private-refs.config.mjs");
+  // `loadConfig` returns the MODULE, so the config is its default
+  // export. Reading the module object itself silently found no
+  // patterns and reported a clean repo.
+  const config = mod?.default ?? {};
+  const visibility = repoVisibility(config.visibility);
+
+  if (visibility === null) {
+    // Not fatal, but never silent. A repo whose visibility we cannot
+    // establish has not been checked, and saying "skipped" is the
+    // difference between a gap you know about and one you do not.
+    console.warn(
+      "check-private-refs: SKIPPED — could not determine repo "
+      + "visibility (is `gh` installed and authenticated?). Set "
+      + "`visibility` in check-private-refs.config.mjs to be explicit.",
+    );
+    return;
+  }
+  if (visibility !== "public") {
+    console.log(
+      `check-private-refs: repo is ${visibility} — private references `
+      + "are expected here, nothing to check",
+    );
+    return;
+  }
+
+  const matchers = toMatchers([
+    ...DEFAULT_FORBIDDEN,
+    ...(config.forbidden ?? []),
+  ]);
+  const allow = (config.allow ?? []).map((a) =>
+    a instanceof RegExp ? a : new RegExp(a));
+
+  const findings = [];
+  for (const file of trackedFiles()) {
+    if (SKIP_EXT.has(path.extname(file).toLowerCase())) continue;
+    if (allow.some((a) => a.test(file))) continue;
+    let lines;
+    try {
+      lines = fs.readFileSync(file, "utf-8").split("\n");
+    } catch {
+      continue;
+    }
+    lines.forEach((line, i) => {
+      for (const {pattern, why} of matchers) {
+        if (pattern.test(line)) {
+          findings.push({
+            file, line: i + 1, why, text: line.trim().slice(0, 120),
+          });
+        }
+      }
+    });
+  }
+
+  if (findings.length === 0) {
+    console.log(
+      `check-private-refs OK — public repo, ${matchers.length} patterns, `
+      + "0 private references",
+    );
+    return;
+  }
+
+  console.error(
+    `\ncheck-private-refs: ${findings.length} private reference(s) in a `
+    + "PUBLIC repo:\n",
+  );
+  for (const f of findings) {
+    console.error(`  ${f.file}:${f.line} — ${f.why}\n    ${f.text}`);
+  }
+  console.error(
+    "\nA public repo must name only what its readers can open. Where a "
+    + "tracker link is what you wanted, name the retirement CONDITION "
+    + "instead, or link an issue on this repo.",
+  );
+  process.exit(1);
+}
+
+main();

package/bin/readability.mjs

@@ -25,6 +25,7 @@ import {parseArgs} from "node:util";
 import path from "node:path";
 import {loadConfig} from "./utils.mjs";
 import {
+  MIN_SCORABLE_WORDS,
   discoverSlugs,
   extractText,
   scoreText,
@@ -74,26 +75,43 @@ async function main() {
         result.consensusGrade <= maxGrade;
       pages.push({slug: s, ...result, pass});
     } catch (err) {
+      // A page we could not read is a FAILURE, not a pass. Recording
+      // it as passing meant a broken path or an unreadable file
+      // reported green, which is the same shape of blind spot as
+      // treating an unscored page as a pass.
       pages.push({
         slug: s,
         wordCount: 0,
         scores: null,
         consensusGrade: null,
-        pass: true,
+        pass: false,
         error: err.message,
       });
     }
   }
 
   const allPassed = pages.every((p) => p.pass);
+  // Named separately from the pass/fail count. An unscored page is not
+  // evidence of anything, and it should not be able to hide inside a
+  // green run — the reader of this output has to be told how much of
+  // the site was actually measured.
+  const unscored = pages.filter((p) => p.unscored).map((p) => p.slug);
   const threshold = {maxGrade};
-  const results = {pages, threshold, allPassed};
+  const results = {pages, threshold, allPassed, unscored};
 
   if (values.pretty) {
     console.error(formatPretty(results, threshold));
   }
   console.log(JSON.stringify(results, null, 2));
 
+  if (unscored.length > 0) {
+    console.error(
+      `\nreadability: ${unscored.length} page(s) under `
+      + `${MIN_SCORABLE_WORDS} words were NOT scored — they are not `
+      + `passing, they are unmeasured:\n  ${unscored.join("\n  ")}`,
+    );
+  }
+
   process.exit(allPassed ? 0 : 1);
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@casomoltd/tooling",
-  "version": "0.23.5",
+  "version": "0.24.0",
   "description": "Casomo's shared dev config: ESLint, Prettier, commitlint, knip & jscpd presets and dev CLIs (git hooks, readability, screenshots)",
   "license": "MIT",
   "repository": {
@@ -20,12 +20,13 @@
     "!**/*.test.mjs"
   ],
   "scripts": {
-    "check": "node bin/check-gates.mjs && node bin/verify-pack.mjs && 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 typecheck && npm run test && npm run lint:md",
     "typecheck": "tsc --noEmit -p hooks/tsconfig.json",
     "test": "node hooks/test.mts && node bin/check-gates.test.mjs",
     "lint:md": "remark --frail --quiet --no-stdout --rc-path bin/skills-lint.config.mjs skills docs",
     "build": "echo 'no-op: source-only repo, nothing to build'",
-    "prepare": "husky || true"
+    "prepare": "husky || true",
+    "check:private-refs": "node bin/check-private-refs.mjs"
   },
   "casomo": {
     "gates": {
@@ -48,6 +49,7 @@
   "bin": {
     "build-report": "./bin/build-report.mjs",
     "check-gates": "./bin/check-gates.mjs",
+    "check-private-refs": "./bin/check-private-refs.mjs",
     "check-tags": "./bin/check-tags.sh",
     "check-version": "./bin/check-version.sh",
     "commit-msg": "./bin/commit-msg.sh",

package/readability/index.mjs

@@ -36,36 +36,138 @@ export function discoverSlugs(srcAppDir) {
 // Extract prose text from a page.tsx source file
 // -------------------------------------------------------------------
 
-export function extractText(filePath) {
-  const source = fs.readFileSync(filePath, "utf-8");
+/**
+ * Resolve a project-local import specifier to a file on disk.
+ *
+ * Relative (`./x`) and src-aliased (`@/x`) only. A bare specifier is a
+ * package and is deliberately not followed: node_modules prose is not
+ * this site's prose.
+ */
+function resolveLocalImport(spec, fromFile, srcDir) {
+  let base;
+  if (spec.startsWith(".")) {
+    base = path.resolve(path.dirname(fromFile), spec);
+  } else if (spec.startsWith("@/") && srcDir) {
+    base = path.join(srcDir, spec.slice(2));
+  } else {
+    return null;
+  }
+  const candidates = [
+    base,
+    `${base}.tsx`,
+    `${base}.ts`,
+    path.join(base, "index.tsx"),
+    path.join(base, "index.ts"),
+  ];
+  for (const c of candidates) {
+    if (fs.existsSync(c) && fs.statSync(c).isFile()) return c;
+  }
+  return null;
+}
 
+/** The `src` directory a file sits under, for resolving `@/` imports. */
+function srcDirOf(filePath) {
+  const marker = `${path.sep}src${path.sep}`;
+  const i = filePath.lastIndexOf(marker);
+  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. */
+function extractOwnText(source) {
   const jsxText = [];
-  const tagContentRe = />([^<>{]+)</g;
+
+  // 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].trim();
+    const text = match[1].replace(/\{[^}]*\}/g, " ").trim();
     if (text) jsxText.push(text);
   }
 
-  // String literals that look like readable prose
+  // 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) {
-    jsxText.push(match[1].trim());
+    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;
+}
+
+/**
+ * Whether a string is prose a reader would read, rather than data that
+ * happens to live in a string.
+ *
+ * Two tests, both cheap. It must be mostly letters — path data,
+ * class-name soup and number tables are not — and it must be more than
+ * a couple of words, which drops the fragments left behind when a JSX
+ * expression is stripped out of a short line.
+ */
+function isProse(text) {
+  const compact = text.replace(/\s+/g, "");
+  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));
+  return words.length >= 3;
+}
+
+/**
+ * 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.
+ *
+ * Depth-limited and cycle-safe. Only project-local imports are
+ * followed; a package's prose is not this site's prose.
+ */
+export function extractText(filePath, {maxDepth = 3} = {}) {
+  const srcDir = srcDirOf(filePath);
+  const seen = new Set();
+  const collected = [];
+
+  const walk = (file, depth) => {
+    const resolved = path.resolve(file);
+    if (seen.has(resolved) || depth > maxDepth) return;
+    seen.add(resolved);
+    const source = fs.readFileSync(resolved, "utf-8");
+    collected.push(...extractOwnText(source));
+    if (depth === maxDepth) return;
+    for (const m of source.matchAll(IMPORT_RE)) {
+      const target = resolveLocalImport(m[1], resolved, srcDir);
+      if (target) walk(target, depth + 1);
+    }
+  };
+  walk(filePath, 0);
 
   // Terminate fragments so formulas count separate sentences
   const SENT_END = /[.!?]$/;
-  const terminated = jsxText.map((t) =>
+  const terminated = collected.map((t) =>
     SENT_END.test(t) ? t : t + "."
   );
 
   let text = terminated.join(" ");
   text = text.replace(/\{[^}]*\}/g, " ");
-  text = text.replace(/&nbsp;/g, " ");
-  text = text.replace(/&amp;/g, "&");
-  text = text.replace(/&lt;/g, "<");
-  text = text.replace(/&gt;/g, ">");
-  text = text.replace(/&[a-z]+;/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(/\s+/g, " ").trim();
 
   return text;
@@ -90,10 +192,25 @@ function applyWordSubs(text, wordSubs) {
   return out;
 }
 
+/**
+ * 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.
+ */
+export const MIN_SCORABLE_WORDS = 100;
+
 export function scoreText(text, wordSubs = DEFAULT_WORD_SUBS) {
   const wordCount = text.split(/\s+/).filter(Boolean).length;
-  if (wordCount < 100) {
-    return {wordCount, scores: null, consensusGrade: null};
+  if (wordCount < MIN_SCORABLE_WORDS) {
+    return {
+      wordCount,
+      scores: null,
+      consensusGrade: null,
+      unscored: true,
+    };
   }
   const normalized = applyWordSubs(text, wordSubs);
   const scores = {