@softure-ai/blog 0.0.0-stage → 0.1.5

package/src/quality/rules/blocks.ts

@@ -0,0 +1,43 @@
+// Block plugin needs (BL-3): a fenced block of a block plugin reads frontmatter keys (`requires`), and
+// an article that lacks one would render the block without its data.
+import type { BlogArticleInput } from "../../contract.js";
+import type { FoundBlock } from "../../render/render-article.js";
+import type { QualityFinding } from "../finding.js";
+
+export function checkBlockRequires(article: BlogArticleInput, pluginBlocks: readonly FoundBlock[]): QualityFinding[] {
+  return pluginBlocks.flatMap((block) =>
+    block.requires
+      .filter((key) => !hasFrontmatterKey(article, key))
+      .map((key) => ({ rule: "block-requires", severity: "error" as const, message: `the ${block.type} block needs ${key} in the frontmatter`, line: block.line })),
+  );
+}
+
+/** Whether the file set a frontmatter key: a module key with a value, or a key of the app's fields. */
+function hasFrontmatterKey(article: BlogArticleInput, key: string): boolean {
+  switch (key) {
+    case "id":
+    case "slug":
+    case "kind":
+    case "title":
+    case "description":
+    case "status":
+    case "current_as_of":
+      return true;
+    case "cluster":
+      return article.cluster !== null;
+    case "pillar":
+      return article.isPillar;
+    case "summary":
+      return article.summary !== null;
+    case "published_at":
+      return article.publishedAt !== null;
+    case "sources":
+      return article.sources.length > 0;
+    case "faq":
+      return article.faq.length > 0;
+    case "forms":
+      return article.termForms.length > 0;
+    default:
+      return article.fields[key] !== undefined;
+  }
+}

package/src/quality/rules/images.ts

@@ -0,0 +1,34 @@
+// Image rules (BF-3): every image in a body follows the app's image policy (`blog({ images })`), the
+// same check the renderer applies, so a text whose image the page would drop never goes public.
+import { checkArticleImage, type ArticleImagePolicy, type FoundImage, type ImageProblem, type ImageVerdict } from "../../render/images.js";
+import type { QualityFinding } from "../finding.js";
+
+const RULE_BY_PROBLEM: Record<ImageProblem, string> = { source: "image-source", alt: "image-alt", dimensions: "image-dimensions" };
+
+function describeProblem(problem: ImageProblem, src: string, policy: ArticleImagePolicy | null): string {
+  switch (problem) {
+    case "source":
+      return policy === null
+        ? `images are off until the app sets blog({ images }): ${src}`
+        : `an image from outside the site and the allowed hosts (blog({ images: { hosts } })): ${src}`;
+    case "alt":
+      return `an image without alt text; describe what it shows: ${src}`;
+    case "dimensions":
+      return `the app does not know the width and height of an image (blog({ images: { dimensions } })): ${src}`;
+  }
+}
+
+export function checkImages(images: readonly FoundImage[], policy: ArticleImagePolicy | null): QualityFinding[] {
+  return images.flatMap((image) => {
+    let verdict: ImageVerdict;
+    try {
+      verdict = checkArticleImage(image, policy ?? undefined);
+    } catch (error) {
+      // The resolver is the app's code; its bug refuses the file instead of crashing a publish.
+      const detail = error instanceof Error ? error.message : String(error);
+      return [{ rule: "image-dimensions", severity: "error" as const, message: `the image dimensions resolver failed (${detail}): ${image.src}`, line: image.line }];
+    }
+    if (verdict.ok) return [];
+    return verdict.problems.map((problem) => ({ rule: RULE_BY_PROBLEM[problem], severity: "error" as const, message: describeProblem(problem, image.src, policy), line: image.line }));
+  });
+}

package/src/quality/rules/input.ts

@@ -0,0 +1,12 @@
+// What every built-in rule reads.
+import type { BlogArticleInput } from "../../contract.js";
+import type { Block } from "../blocks.js";
+import type { QualitySettings } from "../settings.js";
+
+export interface RuleInput {
+  readonly article: BlogArticleInput;
+  readonly blocks: readonly Block[];
+  readonly settings: QualitySettings;
+  /** `YYYY-MM-DD` in the app's time zone. */
+  readonly today: string;
+}

package/src/quality/rules/links.ts

@@ -0,0 +1,56 @@
+// Link rules (FIRE_TRACKER `rules-structure.ts`, `collectLinks`, `checkLinks`): enough internal links,
+// each one to a page that exists, external links over https. Absolute links to the app's own origins
+// count as internal. The network check of external links is `external-links.ts`.
+import type { QualityFinding } from "../finding.js";
+import { findBareUrls, findLinks } from "../text.js";
+import type { RuleInput } from "./input.js";
+
+export interface LinkSummary {
+  readonly internal: readonly { readonly pathname: string; readonly line: number }[];
+  readonly external: readonly { readonly url: string; readonly line: number }[];
+}
+
+/** Whether a site path (`/blog/x`, `/calculator`) leads to a page. */
+export type InternalLinkResolver = (pathname: string) => boolean;
+
+export function collectLinks({ blocks, settings }: Pick<RuleInput, "blocks" | "settings">): LinkSummary {
+  const internal: { pathname: string; line: number }[] = [];
+  const external: { url: string; line: number }[] = [];
+  for (const block of blocks) {
+    if (block.kind === "directive") continue;
+    const urls = findLinks(block.text).map((link) => link.url);
+    if (block.kind === "footnote") urls.push(...findBareUrls(block.text));
+    for (const url of new Set(urls)) {
+      const own = settings.ownOrigins.find((origin) => url === origin || url.startsWith(`${origin}/`) || url.startsWith(`${origin}?`) || url.startsWith(`${origin}#`));
+      if (url.startsWith("/") || own !== undefined) {
+        const rest = own === undefined ? url : url.slice(own.length);
+        internal.push({ pathname: rest.split(/[?#]/)[0] || "/", line: block.line });
+      } else if (/^https?:\/\//.test(url)) {
+        external.push({ url, line: block.line });
+      }
+    }
+  }
+  return { internal, external };
+}
+
+export function checkLinks(input: RuleInput, links: LinkSummary, resolveInternalLink: InternalLinkResolver): QualityFinding[] {
+  const findings: QualityFinding[] = [];
+  const { kind } = input.article;
+  const minimum = input.settings.options.limits.internalLinks[kind];
+  if (links.internal.length < minimum) {
+    findings.push({
+      rule: "internal-links",
+      severity: kind === "article" ? "error" : "warning",
+      message: `${String(links.internal.length)} internal links; at least ${String(minimum)} needed (other texts, the glossary, the app's tools)`,
+    });
+  }
+  for (const link of links.internal) {
+    if (!resolveInternalLink(link.pathname)) {
+      findings.push({ rule: "internal-link-target", severity: "error", message: `an internal link leads nowhere: ${link.pathname}`, line: link.line });
+    }
+  }
+  for (const link of links.external) {
+    if (link.url.startsWith("http://")) findings.push({ rule: "external-link-https", severity: "warning", message: `a link without https: ${link.url}`, line: link.line });
+  }
+  return findings;
+}

package/src/quality/rules/structure.ts

@@ -0,0 +1,137 @@
+// Structure rules (FIRE_TRACKER `src/lib/blog/quality/rules-structure.ts`): metadata lengths and
+// freshness, a summary, the answer first, heading order, question sections, length and footnotes.
+// Required keys, kinds, slug shape and slug = file name are BL-2's parser's, not repeated here.
+import { getProseBlocks, type Block } from "../blocks.js";
+import type { QualityFinding } from "../finding.js";
+import { countWords, findFootnoteRefs, findSignificantNumbers, toProse } from "../text.js";
+import type { RuleInput } from "./input.js";
+
+export function checkMetadata({ article, settings, today }: RuleInput): QualityFinding[] {
+  const findings: QualityFinding[] = [];
+  const { limits } = settings.options;
+  if (article.title.length > limits.titleChars) {
+    findings.push({ rule: "title-length", severity: "warning", message: `the title has ${String(article.title.length)} characters; search engines cut it after about ${String(limits.titleChars)}` });
+  }
+  const { min, max } = limits.descriptionChars;
+  if (article.description.length < min || article.description.length > max) {
+    findings.push({ rule: "description-length", severity: "warning", message: `the description has ${String(article.description.length)} characters; aim for ${String(min)}–${String(max)}` });
+  }
+  if (article.currentAsOf > today) {
+    findings.push({ rule: "as-of-future", severity: "error", message: `current_as_of ${article.currentAsOf} is in the future (today is ${today})` });
+  } else if (daysBetween(article.currentAsOf, today) > limits.staleAfterDays) {
+    findings.push({ rule: "stale", severity: "warning", message: `current_as_of ${article.currentAsOf} is older than ${String(limits.staleAfterDays)} days; the text waits for fresh numbers` });
+  }
+  if (article.kind === "article" && article.summary === null) {
+    findings.push({ rule: "summary-missing", severity: "error", message: "the article has no summary: a few sentences with the answer for the \"in short\" box" });
+  }
+  return findings;
+}
+
+/** The text opens with a paragraph that answers; an article puts a concrete number in its first two paragraphs. */
+export function checkLead({ article, blocks, settings }: RuleInput): QualityFinding[] {
+  const first = blocks[0];
+  if (first === undefined) return [{ rule: "lead", severity: "error", message: "the text is empty" }];
+  if (first.kind !== "paragraph") {
+    return [{ rule: "lead", severity: "error", message: "the text starts with a heading or a list; the first block is a paragraph with the answer", line: first.line }];
+  }
+  const findings: QualityFinding[] = [];
+  const limit = settings.options.limits.leadWords[article.kind];
+  const words = countWords(toProse(first.text));
+  if (words > limit) {
+    findings.push({ rule: "lead-length", severity: "warning", message: `the first paragraph has ${String(words)} words; the answer fits in ${String(limit)}`, line: first.line });
+  }
+  if (article.kind === "article") {
+    const opening = blocks.slice(0, 4).filter((block) => block.kind === "paragraph").slice(0, 2);
+    const hasNumber = opening.some((block) => findSignificantNumbers(toProse(block.text), settings.ruleset.notation).length > 0);
+    if (!hasNumber) {
+      findings.push({
+        rule: "lead-number",
+        severity: "error",
+        message: "the first two paragraphs hold no concrete number (an amount or a percentage); the claim with its number goes first",
+        line: first.line,
+      });
+    }
+  }
+  return findings;
+}
+
+/** No H1 (the page title is `title`), no skipped heading level; an article has question sections with short answers. */
+export function checkSections({ article, blocks, settings }: RuleInput): QualityFinding[] {
+  const findings: QualityFinding[] = [];
+  let previousLevel = 1;
+  for (const block of blocks) {
+    if (block.kind !== "heading" || block.level === undefined) continue;
+    if (block.level === 1) {
+      findings.push({ rule: "heading-h1", severity: "error", message: "a # heading in the body; the page title comes from title, sections start at ##", line: block.line });
+    } else if (block.level > previousLevel + 1) {
+      findings.push({ rule: "heading-order", severity: "error", message: `heading level ${String(block.level)} follows level ${String(previousLevel)}; do not skip a level`, line: block.line });
+    }
+    previousLevel = block.level;
+  }
+  if (article.kind !== "article") return findings;
+
+  const sections = blocks.filter((block) => block.kind === "heading" && block.level === 2);
+  if (sections.length < 2) {
+    findings.push({ rule: "sections", severity: "error", message: `the article has ${String(sections.length)} ## sections; it needs at least 2` });
+  }
+  const questions = sections.filter((block) => block.text.trim().endsWith("?"));
+  if (questions.length === 0) {
+    findings.push({ rule: "section-question", severity: "error", message: "no ## heading is a question; answer sections are what AI assistants quote" });
+  }
+  const limit = settings.options.limits.answerWords;
+  for (const question of questions) {
+    const answer = blocks[blocks.indexOf(question) + 1];
+    if (answer?.kind !== "paragraph") {
+      findings.push({ rule: "section-answer", severity: "error", message: `no paragraph with the answer under "${question.text}"`, line: question.line });
+      continue;
+    }
+    const words = countWords(toProse(answer.text));
+    if (words > limit) {
+      findings.push({
+        rule: "section-answer-length",
+        severity: "warning",
+        message: `the answer under "${question.text}" has ${String(words)} words; the first sentences answer directly (at most ${String(limit)})`,
+        line: answer.line,
+      });
+    }
+  }
+  return findings;
+}
+
+export function checkLength({ article, blocks, settings }: RuleInput): QualityFinding[] {
+  const words = getProseBlocks(blocks).reduce((sum, block) => sum + countWords(toProse(block.text)), 0);
+  const { min, max } = settings.options.limits.words[article.kind];
+  if (words < min) return [{ rule: "length", severity: "error", message: `the text has ${String(words)} words; ${article.kind === "article" ? "an article" : "a term"} needs at least ${String(min)}` }];
+  if (words > max) return [{ rule: "length", severity: "warning", message: `the text has ${String(words)} words; above ${String(max)} readers and assistants lose the answer` }];
+  return [];
+}
+
+/** Every footnote reference has a definition, and every definition is used. */
+export function checkFootnotes({ blocks }: RuleInput): QualityFinding[] {
+  const findings: QualityFinding[] = [];
+  const definitions = getFootnoteDefinitions(blocks);
+  const used = new Set<string>();
+  for (const block of blocks) {
+    if (block.kind === "footnote" || block.kind === "directive") continue;
+    for (const ref of findFootnoteRefs(block.text)) {
+      used.add(ref);
+      if (!definitions.has(ref)) findings.push({ rule: "footnote-undefined", severity: "error", message: `footnote [^${ref}] has no definition`, line: block.line });
+    }
+  }
+  for (const [id, block] of definitions) {
+    if (!used.has(id)) findings.push({ rule: "footnote-unused", severity: "warning", message: `footnote [^${id}] is not used in the text`, line: block.line });
+  }
+  return findings;
+}
+
+export function getFootnoteDefinitions(blocks: readonly Block[]): Map<string, Block> {
+  const definitions = new Map<string, Block>();
+  for (const block of blocks) {
+    if (block.kind === "footnote" && block.footnoteId !== undefined) definitions.set(block.footnoteId, block);
+  }
+  return definitions;
+}
+
+function daysBetween(fromIso: string, toIso: string): number {
+  return Math.round((Date.parse(`${toIso}T00:00:00Z`) - Date.parse(`${fromIso}T00:00:00Z`)) / 86_400_000);
+}

package/src/quality/rules/style.ts

@@ -0,0 +1,137 @@
+// Style rules (FIRE_TRACKER `src/lib/blog/quality/rules-style.ts`): the ruleset's patterns, the app's
+// voice and the YMYL profit promises over prose, then rhythm and formatting measures.
+import { getProseBlocks, type Block } from "../blocks.js";
+import type { QualityFinding } from "../finding.js";
+import type { StylePattern } from "../rulesets/types.js";
+import { countWords, splitSentences, toProse } from "../text.js";
+import type { RuleInput } from "./input.js";
+
+const PROFIT_PROMISE_MESSAGE = "a promise of profit or an order to buy; not acceptable in a your-money-or-your-life text";
+
+/** The patterns the prose is matched against: ruleset style, app voice, and profit promises when YMYL is on. */
+export function getActivePatterns({ settings }: Pick<RuleInput, "settings">): StylePattern[] {
+  const patterns = [...settings.ruleset.patterns, ...settings.voicePatterns];
+  if (settings.options.ymyl !== null) {
+    patterns.push({ id: "profit-promise", severity: "error", pattern: settings.ruleset.profitPromises, message: PROFIT_PROMISE_MESSAGE });
+  }
+  return patterns;
+}
+
+/** Title, description and summary show in search results and above the text: the error patterns apply to them too. */
+export function checkMetadataStyle(input: RuleInput): QualityFinding[] {
+  const { title, description, summary } = input.article;
+  const blocks: Block[] = [title, description, ...(summary === null ? [] : [summary])].map((text) => ({ kind: "paragraph", text, line: 1 }));
+  return matchPatterns(blocks, getActivePatterns(input).filter((pattern) => pattern.severity === "error")).map((finding) => ({
+    rule: finding.rule,
+    severity: finding.severity,
+    message: `title, description or summary: ${finding.message}`,
+  }));
+}
+
+export function checkStyle(input: RuleInput): QualityFinding[] {
+  return matchPatterns(getProseBlocks(input.blocks), getActivePatterns(input));
+}
+
+/** One error per pattern and block; warnings aggregated to one finding per pattern with a count. */
+function matchPatterns(blocks: readonly Block[], patterns: readonly StylePattern[]): QualityFinding[] {
+  const findings: QualityFinding[] = [];
+  const warningHits = new Map<string, { count: number; line: number; sample: string }>();
+  for (const block of blocks) {
+    const prose = toProse(block.text);
+    for (const style of patterns) {
+      const matches = [...prose.matchAll(style.pattern)];
+      const first = matches[0]?.[0];
+      if (first === undefined) continue;
+      if (style.severity === "error") {
+        findings.push({ rule: style.id, severity: "error", message: `"${first}": ${style.message}`, line: block.line });
+      } else {
+        const hit = warningHits.get(style.id) ?? { count: 0, line: block.line, sample: first };
+        hit.count += matches.length;
+        warningHits.set(style.id, hit);
+      }
+    }
+  }
+  for (const style of patterns) {
+    const hit = warningHits.get(style.id);
+    if (hit !== undefined) {
+      findings.push({ rule: style.id, severity: "warning", message: `${String(hit.count)}x (e.g. "${hit.sample}"): ${style.message}`, line: hit.line });
+    }
+  }
+  return findings;
+}
+
+const DASH = /\s[—–-]\s|—/g;
+
+/** Rhythm and formatting: dashes (an error over the limit), bold, bold labels, triads, sentence length and variety, openings, headings. */
+export function checkRhythm({ blocks, settings }: RuleInput): QualityFinding[] {
+  const findings: QualityFinding[] = [];
+  const { limits } = settings.options;
+  const prose = getProseBlocks(blocks).filter((block) => block.kind !== "heading" && block.kind !== "table");
+  const proseText = prose.map((block) => toProse(block.text));
+  const totalWords = proseText.reduce((sum, text) => sum + countWords(text), 0);
+
+  const dashes = proseText.reduce((sum, text) => sum + (text.match(DASH)?.length ?? 0), 0);
+  if (dashes >= 3 && dashes > totalWords / limits.wordsPerDash) {
+    findings.push({
+      rule: "dashes",
+      severity: "error",
+      message: `${String(dashes)} dashes in ${String(totalWords)} words; at most one per ${String(limits.wordsPerDash)}: use a full stop, a comma or a colon`,
+    });
+  }
+  for (const [index, block] of prose.entries()) {
+    if ((proseText[index]?.match(DASH)?.length ?? 0) >= 2) findings.push({ rule: "dashes-paragraph", severity: "warning", message: "two dashes in one paragraph", line: block.line });
+  }
+
+  const bold = blocks.reduce((sum, block) => sum + (block.text.match(/\*\*[^*]+\*\*/g)?.length ?? 0), 0);
+  if (bold > 0 && bold > totalWords / limits.wordsPerBold) {
+    findings.push({ rule: "bold-density", severity: "warning", message: `${String(bold)} bold phrases in ${String(totalWords)} words; bold stops standing out` });
+  }
+  const boldLabels = blocks.filter((block) => block.kind === "listItem" && /^\*\*[^*]+:\*\*|^\*\*[^*]+\*\*:/.test(block.text));
+  const firstLabel = boldLabels[0];
+  if (firstLabel !== undefined && boldLabels.length >= 3) {
+    findings.push({
+      rule: "bold-labels",
+      severity: "warning",
+      message: `${String(boldLabels.length)} list items start with a bold label; the "**Label:** text" template`,
+      line: firstLabel.line,
+    });
+  }
+
+  const triads = proseText.reduce((sum, text) => sum + (text.match(settings.ruleset.triad)?.length ?? 0), 0);
+  if (triads > 3) findings.push({ rule: "triads", severity: "warning", message: `${String(triads)} lists of three; two items sound less like a template than three` });
+
+  const sentences = proseText.flatMap((text) => splitSentences(text));
+  const lengths = sentences.map((sentence) => countWords(sentence));
+  const long = lengths.filter((length) => length > limits.sentenceWords).length;
+  if (long > 0) findings.push({ rule: "long-sentences", severity: "warning", message: `${String(long)} sentences longer than ${String(limits.sentenceWords)} words` });
+  if (lengths.length >= 12) {
+    const mean = lengths.reduce((sum, length) => sum + length, 0) / lengths.length;
+    const deviation = Math.sqrt(lengths.reduce((sum, length) => sum + (length - mean) ** 2, 0) / lengths.length);
+    if (deviation < 4) {
+      findings.push({
+        rule: "monotone-rhythm",
+        severity: "warning",
+        message: `the sentences have similar lengths (mean ${mean.toFixed(0)} words, deviation ${deviation.toFixed(1)}); mix short ones with long ones`,
+      });
+    }
+  }
+  for (let index = 2; index < sentences.length; index += 1) {
+    const openings = sentences.slice(index - 2, index + 1).map((sentence) => sentence.split(" ")[0]?.toLowerCase());
+    const opening = openings[0];
+    if (opening !== undefined && openings.every((other) => other === opening)) {
+      findings.push({ rule: "repeated-openings", severity: "warning", message: `three sentences in a row start with "${opening}"` });
+      break;
+    }
+  }
+
+  if (settings.ruleset.flagsTitleCaseHeadings) {
+    for (const block of blocks) {
+      if (block.kind !== "heading") continue;
+      const words = block.text.split(/\s+/).filter((word) => /^\p{L}/u.test(word));
+      if (words.length >= 3 && words.every((word) => /^\p{Lu}/u.test(word))) {
+        findings.push({ rule: "title-case-heading", severity: "warning", message: `heading "${block.text}": only the first word starts with a capital letter`, line: block.line });
+      }
+    }
+  }
+  return findings;
+}

package/src/quality/rules/ymyl.ts

@@ -0,0 +1,57 @@
+// YMYL rules (FIRE_TRACKER `rules-structure.ts`, sources and `checkNumberSources`): an article lists
+// its sources over https, and every significant number carries a footnote whose address is a listed
+// source, or which names the app's own calculation (`ymyl.ownCalculationMark`).
+import type { Block } from "../blocks.js";
+import type { QualityFinding } from "../finding.js";
+import { findBareUrls, findFootnoteRefs, findSignificantNumbers, toProse } from "../text.js";
+import type { RuleInput } from "./input.js";
+import { getFootnoteDefinitions } from "./structure.js";
+
+export function checkSources({ article }: RuleInput): QualityFinding[] {
+  const findings: QualityFinding[] = [];
+  if (article.kind === "article" && article.sources.length === 0) {
+    findings.push({ rule: "sources-missing", severity: "error", message: "the article lists no sources (name and address of each)" });
+  }
+  for (const source of article.sources) {
+    if (!source.url.startsWith("https://")) {
+      findings.push({ rule: "source-https", severity: "error", message: `source "${source.name}" has an address without https: ${source.url}` });
+    }
+  }
+  return findings;
+}
+
+export function checkNumberSources({ article, blocks, settings }: RuleInput): QualityFinding[] {
+  const findings: QualityFinding[] = [];
+  const { notation } = settings.ruleset;
+  const mark = settings.options.ymyl?.ownCalculationMark ?? null;
+  for (const block of blocks) {
+    if (block.kind === "footnote" || block.kind === "directive" || block.kind === "heading") continue;
+    const numbers = findSignificantNumbers(toProse(block.text), notation);
+    if (numbers.length > 0 && findFootnoteRefs(block.text).length === 0 && !isTableSourcedNearby(blocks, block)) {
+      const remedy = mark === null ? "add a footnote with the source's address" : `add a footnote with the source's address or "${mark}"`;
+      findings.push({ rule: "number-source", severity: "error", message: `a number without a source: ${numbers.slice(0, 3).join(", ")}; ${remedy}`, line: block.line });
+    }
+  }
+  const sourceUrls = new Set(article.sources.map((source) => source.url));
+  for (const [id, block] of getFootnoteDefinitions(blocks)) {
+    const urls = findBareUrls(block.text);
+    const isOwnCalculation = mark !== null && block.text.toLowerCase().includes(mark.toLowerCase());
+    if (urls.length === 0 && !isOwnCalculation) {
+      const message = mark === null ? `footnote [^${id}] has no source address` : `footnote [^${id}] has neither a source address nor "${mark}"`;
+      findings.push({ rule: "footnote-source", severity: "error", message, line: block.line });
+    }
+    for (const url of urls) {
+      if (!sourceUrls.has(url)) {
+        findings.push({ rule: "footnote-not-in-sources", severity: "error", message: `the address in footnote [^${id}] is not in sources: ${url}`, line: block.line });
+      }
+    }
+  }
+  return findings;
+}
+
+/** A table has no room for a footnote per cell, so the paragraph right above or below may carry it. */
+function isTableSourcedNearby(blocks: readonly Block[], table: Block): boolean {
+  if (table.kind !== "table") return false;
+  const index = blocks.indexOf(table);
+  return [blocks[index - 1], blocks[index + 1]].some((neighbour) => neighbour?.kind === "paragraph" && findFootnoteRefs(neighbour.text).length > 0);
+}

package/src/quality/rulesets/en/ruleset.ts

@@ -0,0 +1,117 @@
+// The English ruleset: the same habits as the Polish one, in English, after `blader/humanizer` and
+// `hardikpandya/stop-slop`. Errors are habits a careful author uses rarely and on purpose; warnings
+// are words that say nothing alone but betray a template in a cluster.
+import { wordPattern } from "../../text.js";
+import type { LanguageRuleset } from "../types.js";
+
+export const enRuleset: LanguageRuleset = {
+  language: "en",
+  patterns: [
+    {
+      id: "announcement",
+      severity: "error",
+      pattern: wordPattern("it(?:'s| is) (?:worth|important to) (?:noting|note|mentioning|mention|pointing out|highlighting|emphasizing)|it should be noted|needless to say"),
+      message: "an announcement instead of a fact; write the fact",
+    },
+    {
+      id: "these-days",
+      severity: "error",
+      pattern: wordPattern("in today's (?:fast-paced |ever-changing |digital |modern )?(?:world|age|era|landscape)|in this day and age|in the modern era|now more than ever"),
+      message: "an empty opener about \"these times\"; start with a number or the answer",
+    },
+    {
+      id: "not-only-but-also",
+      severity: "error",
+      pattern: wordPattern("not only[^.!?]{1,120}? but also"),
+      message: "\"not only…, but also\"; name both things plainly",
+    },
+    {
+      id: "not-x-but-y",
+      severity: "error",
+      pattern: wordPattern("it(?:'s| is) not (?:just |only |about )?[^.!?,;]{1,60}[,;] it(?:'s| is)|this isn't (?:just )?[^.!?,;]{1,60}[,;] it's"),
+      message: "the \"it is not X, it is Y\" contrast; say Y right away",
+    },
+    {
+      id: "meta-commentary",
+      severity: "error",
+      pattern: wordPattern(
+        "in this (?:article|post|guide|piece|blog post)|let's (?:dive|delve|take a (?:closer )?look|explore|break (?:it|this) down)|without further ado|as (?:we )?(?:mentioned|discussed) (?:earlier|above|before)|as you'll see|you'll learn|read on to",
+      ),
+      message: "the text talks about itself instead of the topic; remove the announcement",
+    },
+    {
+      id: "throat-clearing",
+      severity: "error",
+      pattern: wordPattern(
+        "the truth is|here's (?:why|how|what|the thing)|here's where|interestingly|importantly|undoubtedly|without a doubt|it goes without saying|make no mistake|the reality is",
+      ),
+      message: "a run-up before the point; cut it and start with the point",
+    },
+    {
+      id: "empty-conclusion",
+      severity: "error",
+      pattern: wordPattern("in conclusion|to sum up|to summarize|in summary|all in all|at the end of the day|the bottom line is"),
+      message: "an empty conclusion; end with the last concrete fact",
+    },
+    {
+      id: "crucial",
+      severity: "error",
+      pattern: wordPattern("crucial|pivotal|delve|delves|delving|tapestry|testament to"),
+      message: "a favourite word of language models; name what depends on the thing",
+    },
+    {
+      id: "plays-a-role",
+      severity: "error",
+      pattern: wordPattern("plays? an? (?:\\p{L}+ )?role|playing an? (?:\\p{L}+ )?role"),
+      message: "\"plays a role\"; write what the thing does",
+    },
+    {
+      id: "puffery",
+      severity: "error",
+      pattern: wordPattern(
+        "game[- ]changer|groundbreaking|revolutionary|cutting-edge|unparalleled|invaluable|holistic|comprehensive guide|ultimate guide|a wide (?:range|array|variety) of|navigat(?:e|ing) the (?:complex |ever-changing )?(?:world|landscape|maze) of|ever-evolving|ever-changing landscape|seamless(?:ly)?|there(?:'s| is) no one-size-fits-all|depends on many factors",
+      ),
+      message: "an inflated or empty phrase; replace it with a fact",
+    },
+    {
+      id: "chatbot-phrases",
+      severity: "error",
+      pattern: wordPattern("I hope this helps|let me know if|feel free to|great question|as an AI(?: language model)?|as of my (?:last|knowledge) (?:update|cutoff)|happy to help|I'd be happy to"),
+      message: "a leftover of a chat with an assistant; remove it",
+    },
+    {
+      id: "emoji",
+      severity: "error",
+      pattern: /\p{Extended_Pictographic}/gu,
+      message: "an emoji in the text; remove it",
+    },
+    {
+      id: "filler-words",
+      severity: "warning",
+      pattern: wordPattern(
+        "moreover|furthermore|additionally|in addition|in other words|simply put|very|really|truly|absolutely|definitely|literally|basically|essentially|actually|just|optimal|leverage|robust|remember that",
+      ),
+      message: "a filler word; check whether the sentence says the same without it",
+    },
+    {
+      id: "exclamation",
+      severity: "warning",
+      pattern: /!/g,
+      message: "an exclamation mark; a guide speaks calmly",
+    },
+  ],
+  firstPersonSingular: wordPattern("I|I'm|I've|I'd|I'll|me|my|mine|myself|in my (?:opinion|view|experience)|personally"),
+  profitPromises: wordPattern(
+    "guaranteed (?:returns?|profits?|income|gains?)|(?:a )?sure (?:profit|bet|thing)|(?<!not |never |isn't |aren't )risk[- ]free|zero risk|no risk|(?:you )?can(?:'t|not) lose|you will (?:definitely |surely )?(?:profit|earn|get rich)|buy (?:now|today)|you (?:must|need to|have to) (?:buy|invest)|get rich quick|quick (?:profits?|riches)|easy money|effortless (?:income|returns?|wealth)",
+  ),
+  notation: {
+    number: /\d{1,3}(?:,\d{3})+(?:\.\d+)?|\d+(?:\.\d+)?/g,
+    unitAfter: /^\s?(?:%|percent\b|per cent\b|USD\b|EUR\b|GBP\b|dollars?\b|euros?\b|pounds?\b|k\b|thousand\b|million\b|billion\b|bn\b)/iu,
+    unitBefore: /(?:[$€£]|USD ?|EUR ?|GBP ?)$/u,
+    referenceBefore: /(?:§|section|sec\.|art\.|article|no\.|chapter|clause|rule|part)\s*$/iu,
+    thousandsSeparator: /,/,
+    decimalSeparator: ".",
+  },
+  triad: /(?<![\p{L}])\p{L}+, \p{L}+,? (?:and|or) \p{L}+(?![\p{L}])/gu,
+  flagsTitleCaseHeadings: false,
+};

package/src/quality/rulesets/index.ts

@@ -0,0 +1,9 @@
+// The language rulesets an app chooses from with `blog({ quality: { language } })`.
+import { enRuleset } from "./en/ruleset.js";
+import { plRuleset } from "./pl/ruleset.js";
+import type { LanguageRuleset, QualityLanguage } from "./types.js";
+
+export const QUALITY_RULESETS: Readonly<Record<QualityLanguage, LanguageRuleset>> = { en: enRuleset, pl: plRuleset };
+
+export { enRuleset, plRuleset };
+export { QUALITY_LANGUAGES, type LanguageRuleset, type QualityLanguage, type StylePattern } from "./types.js";