@casomoltd/tooling 0.35.0 → 0.36.1

package/bin/buttondown.mjs

@@ -12,19 +12,25 @@
  *   buttondown emit <dir>          write each long field out as rendered
  *   buttondown draft <file.md>     create or replace a draft
  *   buttondown upload <image>      upload an image, print its URL
- *   buttondown api <METHOD> <path> [json]
- *                                  any call, for setting up a manual test
+ *   buttondown api <METHOD> <path> [json] [--send]
+ *                                  any call, for setting up a manual test;
+ *                                  one that sends or schedules an email
+ *                                  is refused without --send
  *
  * `diff`, `apply` and `check` exit 1 on drift, a refusal or a problem, so a
  * script can gate on them.
  */
 import {
-  apply, assertApiPath, client, draft, drift, emit, loadSettings, readKey,
-  runCheck, upload, writeTokens,
+  apply, assertApiPath, assertNotSending, client, draft, drift, emit,
+  loadSettings, readKey, runCheck, upload, writeTokens,
 } from "../buttondown/engine.mjs";
 
+/** The one flag: without it, `api` refuses any call that could send an
+ *  email, and no other command takes it. */
+const SEND_FLAG = "--send";
+
 const USAGE = "usage: buttondown [diff|apply|check|tokens|emit <dir>|"
-  + "draft <file.md>|upload <image>|api <METHOD> <path> [json]]";
+  + `draft <file.md>|upload <image>|api <METHOD> <path> [json] [${SEND_FLAG}]]`;
 
 /** Each command with the fewest and most arguments it takes. */
 const ARGS = {
@@ -32,9 +38,13 @@ const ARGS = {
   emit: [1, 1], draft: [1, 1], upload: [1, 1], api: [2, 3],
 };
 
-const [command = "diff", ...args] = process.argv.slice(2);
+const argv = process.argv.slice(2);
+const send = argv.includes(SEND_FLAG);
+const [command = "diff", ...args] = argv.filter((a) => a !== SEND_FLAG);
 const [fewest, most] = ARGS[command] ?? [];
-if (fewest === undefined || args.length < fewest || args.length > most) {
+const badUsage = fewest === undefined || args.length < fewest
+  || args.length > most || (send && command !== "api");
+if (badUsage) {
   console.error(USAGE);
   process.exit(2);
 }
@@ -85,9 +95,16 @@ switch (command) {
   case "api": {
     const [method, url, body] = args;
     assertApiPath(settings, method, url);
-    const res = await (await api()).call(
-      method.toUpperCase(), url, body && JSON.parse(body),
-    );
+    const payload = body && JSON.parse(body);
+    if (!send) {
+      try {
+        assertNotSending(method, url, payload);
+      } catch (e) {
+        console.error(`buttondown: ${e.message}; add ${SEND_FLAG} to send it`);
+        process.exit(1);
+      }
+    }
+    const res = await (await api()).call(method.toUpperCase(), url, payload);
     console.log(res.status, res.data ? JSON.stringify(res.data, null, 2) : "");
     process.exit(res.ok ? 0 : 1);
   }

package/buttondown/engine.mjs

@@ -87,6 +87,19 @@ const API_PATH = new URL(API).pathname;
 /** The status of an email not yet sent. */
 const DRAFT = "draft";
 
+/**
+ * The api routes that can mail someone, judged on a `requestPath`. A write
+ * to the emails collection or to one email may carry a status that sends
+ * it, so it passes only as a draft; any action on an email (publish,
+ * send-draft and whatever Buttondown adds) or on a subscriber (a reminder,
+ * an email to one reader) is refused outright, so a new route fails closed.
+ * Creating an unactivated subscriber also mails a confirmation, and stays
+ * allowed: it is how a manual test stands in for a reader signing up, to an
+ * address the tester owns.
+ */
+const EMAIL_WRITE = new RegExp(`^${API_PATH}/emails(/[^/]+)?/?$`);
+const SENDING_ACTION = new RegExp(`^${API_PATH}/(emails|subscribers)/[^/]+/.`);
+
 const FRONT_MATTER = /^---\n([\s\S]*?)\n---\n/;
 
 /** The Buttondown fields holding the two skins. */
@@ -387,7 +400,7 @@ export async function readKey(env = process.env) {
 export function client(settings, key) {
   const {newsletter} = settings;
   async function call(method, url, body, {form} = {}) {
-    const res = await fetch(new URL(API + url), {
+    const res = await fetch(requestUrl(url), {
       method,
       headers: {
         Authorization: `Token ${key}`,
@@ -445,25 +458,37 @@ export function client(settings, key) {
 
 /**
  * Refuses an `api` call that writes newsletter settings anywhere but this
- * newsletter. Judged on the path the server routes: percent-decoded, then
- * normalised, so `/%6eewsletters/<other>`, `/./newsletters/<other>` and
- * `<own>/../<other>` are seen for what they are. A path still encoded after
- * one decoding is refused outright rather than guessed at.
+ * newsletter, judged on the path the server routes (`requestPath`).
  */
 export function assertApiPath(settings, method, url) {
   if (method.toUpperCase() === "GET") return;
-  const decoded = decodeURIComponent(new URL(API + url).pathname);
-  if (decoded.includes("%")) {
-    throw new Error(`api refuses an encoded path: ${url}`);
-  }
-  const {pathname} = new URL(decoded, API);
-  const own = API_PATH + newsletterPath(settings.newsletter);
+  const pathname = requestPath(url);
+  const own = (API_PATH + newsletterPath(settings.newsletter)).toLowerCase();
   if (pathname.startsWith(`${API_PATH}/newsletters`)
     && pathname !== own && !pathname.startsWith(`${own}/`)) {
     throw new Error(`api writes under /newsletters only to ${own}`);
   }
 }
 
+/**
+ * Throws if an api call could send or schedule an email (`EMAIL_WRITE`,
+ * `SENDING_ACTION`). Sending reaches real inboxes and cannot be recalled, so
+ * the caller lets a call through only on a person's explicit say-so.
+ */
+export function assertNotSending(method, url, body) {
+  const cannotSend = ["GET", "DELETE"].includes(method.toUpperCase());
+  if (cannotSend) return;
+  const pathname = requestPath(url);
+  const status = body && typeof body === "object" ? body.status : undefined;
+  const creates = pathname.replace(/\/$/, "") === `${API_PATH}/emails`;
+  const draftOnly = status === DRAFT || (status === undefined && !creates);
+  if (SENDING_ACTION.test(pathname)
+    || (EMAIL_WRITE.test(pathname) && !draftOnly)) {
+    throw new Error(`api refuses a call that could send an email: `
+      + `${method.toUpperCase()} ${url}`);
+  }
+}
+
 /** Whether a live value already says what the repo wants. */
 export function same(field, got, want) {
   if (IMAGE_FIELDS.has(field)) {
@@ -693,6 +718,26 @@ export function stripComments(text) {
   }
 }
 
+/** The URL `call` fetches for an api path, and the one the guards judge. */
+function requestUrl(url) {
+  return new URL(API + url);
+}
+
+/**
+ * The path the server routes for an `api` url, from `requestUrl`,
+ * then percent-decoded, slash-collapsed and normalised, so
+ * `/%6eewsletters/<other>`, `//emails/<id>/publish`, `/./newsletters/<other>`
+ * and `<own>/../<other>` are seen for what they are. A path still encoded
+ * after one decoding is refused outright rather than guessed at.
+ */
+function requestPath(url) {
+  const decoded = decodeURIComponent(requestUrl(url).pathname);
+  if (decoded.includes("%")) {
+    throw new Error(`api refuses an encoded path: ${url}`);
+  }
+  return new URL(decoded.replace(/\/{2,}/g, "/"), API).pathname.toLowerCase();
+}
+
 /** Throws unless an image field holds an absolute URL, since Buttondown
  *  stores a relative one as given and the image then never loads. */
 function assertAbsoluteUrl(field, value) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@casomoltd/tooling",
-  "version": "0.35.0",
+  "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)",
   "license": "MIT",
   "repository": {
@@ -24,7 +24,7 @@
   "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",
+    "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",
     "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",
@@ -84,7 +84,8 @@
     "eslint-config-next": ">=16",
     "eslint-plugin-sonarjs": ">=3",
     "jscpd": ">=4",
-    "knip": ">=5"
+    "knip": ">=5",
+    "typescript": ">=5"
   },
   "devDependencies": {
     "@types/node": "^26.0.0",

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;