@softure-ai/blog 0.0.0-stage → 0.1.6

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

@@ -0,0 +1,126 @@
+// The Polish ruleset (FIRE_TRACKER `src/lib/blog/quality/rules-style.ts`, `text.ts`). A translation and
+// extension of `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.
+// FIRE's voice (no first person singular) and finance phrases are app config, not Polish.
+import { wordPattern } from "../../text.js";
+import type { LanguageRuleset } from "../types.js";
+
+const L = "\\p{L}*";
+
+export const plRuleset: LanguageRuleset = {
+  language: "pl",
+  patterns: [
+    {
+      id: "announcement",
+      severity: "error",
+      pattern: wordPattern("(?:warto|należy) (?:zauważyć|podkreślić|wspomnieć|nadmienić|dodać|zaznaczyć)"),
+      message: "an announcement instead of a fact; write the fact",
+    },
+    {
+      id: "these-days",
+      severity: "error",
+      pattern: wordPattern(`w dzisiejszych czasach|w dzisiejszym (?:świecie|dynamicznym${L})|w dobie|w obecnych czasach`),
+      message: "an empty opener about \"these times\"; start with a number or the answer",
+    },
+    {
+      id: "not-only-but-also",
+      severity: "error",
+      pattern: wordPattern("nie tylko[^.!?]{1,120}?,? (?:ale|lecz) (?:także|również|też|i)"),
+      message: "\"not only…, but also\"; name both things plainly",
+    },
+    {
+      id: "not-x-but-y",
+      severity: "error",
+      pattern: wordPattern("(?:to nie (?:jest )?[^.!?,]{1,60}, (?:to|tylko|lecz)|nie chodzi o [^.!?]{1,80}[.,] (?:chodzi o|tylko o|lecz o))"),
+      message: "the \"it is not X, it is Y\" contrast; say Y right away",
+    },
+    {
+      id: "meta-commentary",
+      severity: "error",
+      pattern: wordPattern(
+        "w (?:tym|niniejszym) (?:artykule|tekście|wpisie|poradniku)|przyjrzyjmy się|zanurzmy się|przejdźmy (?:teraz )?do|jak (?:już )?wspomniano|jak zaraz zobaczysz|jak zobaczymy|dowiesz się (?:z tego|w tym)",
+      ),
+      message: "the text talks about itself instead of the topic; remove the announcement",
+    },
+    {
+      id: "throat-clearing",
+      severity: "error",
+      pattern: wordPattern(
+        "prawda jest taka|oto (?:dlaczego|jak|co|czemu)|i tu pojawia się|co ciekawe|co ważne|co istotne|nie da się ukryć|nie ulega wątpliwości|bez wątpienia|niewątpliwie|bezsprzecznie",
+      ),
+      message: "a run-up before the point; cut it and start with the point",
+    },
+    {
+      id: "empty-conclusion",
+      severity: "error",
+      pattern: wordPattern("podsumowując|reasumując|w podsumowaniu|na zakończenie|konkludując|krótko podsumowując"),
+      message: "an empty conclusion; end with the last concrete fact",
+    },
+    {
+      id: "crucial",
+      severity: "error",
+      pattern: wordPattern(`kluczow${L}`),
+      message: "\"crucial\", the most common Polish tic of language models; name what depends on the thing",
+    },
+    {
+      id: "plays-a-role",
+      severity: "error",
+      pattern: wordPattern(`odgryw${L} (?:\\p{L}+ )?rolę`),
+      message: "\"plays a role\"; write what the thing does",
+    },
+    {
+      id: "puffery",
+      severity: "error",
+      pattern: wordPattern(
+        `kamień milowy|przełomow${L}|rewolucyjn${L}|game[- ]changer${L}|klucz do sukcesu|nieocenion${L}|holistyczn${L}|kompleksow${L}|szerok${L} (?:wachlarz${L}|gam${L}|spektrum)|w gąszczu|dynamicznie zmieniając${L}|nie ma jednej (?:dobrej |właściwej |uniwersalnej |prostej )?odpowiedzi|zależy od wielu czynników`,
+      ),
+      message: "an inflated or empty phrase; replace it with a fact",
+    },
+    {
+      id: "chatbot-phrases",
+      severity: "error",
+      pattern: wordPattern("mam nadzieję, że|daj (?:mi )?znać|chętnie pomogę|świetne pytanie|jako model językowy|według mojej wiedzy|na dzień mojej wiedzy|w razie pytań"),
+      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(
+        `ponadto|dodatkowo|co więcej|istotn${L}|fundamentaln${L}|innymi słowy|krótko mówiąc|w rezultacie|niezwykle|niezmiernie|naprawdę|absolutnie|zdecydowanie|dosłownie|po prostu|optymaln${L}|efektywn${L}|pamiętaj, że|warto`,
+      ),
+      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",
+    },
+    {
+      id: "straight-quotes",
+      severity: "warning",
+      pattern: /[“"]/g,
+      message: "an English quotation mark; Polish uses „…”",
+    },
+  ],
+  firstPersonSingular: wordPattern("ja|mnie|mój|moja|moje|mojego|mojej|moim|moich|moją|mi|uważam|sądzę|myślę|moim zdaniem|osobiście"),
+  profitPromises: wordPattern(
+    `gwarantowan${L} (?:zysk${L}|zwrot${L}|dochód${L}|zarobek${L})|pewn${L} zysk${L}|(?<!nie (?:jest|są|ma|będzie) )bez (?:żadnego )?ryzyka|zero ryzyka|nie (?:możesz|można) (?:nic )?stracić|na pewno zarobisz|zarobisz na pewno|kup(?:uj)? (?:teraz|już dziś)|musisz (?:kupić|zainwestować)|szybk${L} (?:zysk${L}|wzbogacen${L})|łatw${L} pieniądz${L}|bez wysiłku`,
+  ),
+  notation: {
+    number: /\d{1,3}(?:[ \u00a0\u202f]\d{3})+(?:,\d+)?|\d+(?:,\d+)?/g,
+    unitAfter: /^\s?(?:%|proc|zł|złotych|zl\b|PLN|tys|mln|mld|groszy|gr\b)/iu,
+    unitBefore: null,
+    referenceBefore: /(?:art\.|ust\.|poz\.|pkt|§|nr|Dz\.\s?U\.?|M\.P\.)\s*$/iu,
+    thousandsSeparator: /[ \u00a0\u202f]/,
+    decimalSeparator: ",",
+  },
+  triad: /(?<![\p{L}])\p{L}+, \p{L}+,? (?:i|oraz) \p{L}+(?![\p{L}])/gu,
+  flagsTitleCaseHeadings: true,
+};

package/src/quality/rulesets/types.ts

@@ -0,0 +1,31 @@
+// The shape of a language ruleset: the language data the style, voice and YMYL rules match against.
+import type { QualitySeverity } from "../finding.js";
+import type { NumberNotation } from "../text.js";
+
+export const QUALITY_LANGUAGES = ["en", "pl"] as const;
+export type QualityLanguage = (typeof QUALITY_LANGUAGES)[number];
+
+export interface StylePattern {
+  /** The rule id; the same id in two rulesets names the same habit. */
+  readonly id: string;
+  readonly severity: QualitySeverity;
+  /** Global, so every hit counts. */
+  readonly pattern: RegExp;
+  /** What is wrong and what to write instead. */
+  readonly message: string;
+}
+
+export interface LanguageRuleset {
+  readonly language: QualityLanguage;
+  /** AI-writing and generic style patterns. Errors: one hit is enough. Warnings: reported once per rule with a count. */
+  readonly patterns: readonly StylePattern[];
+  /** First person singular, for apps whose texts are signed by an editorial team (`voice.forbidFirstPersonSingular`). */
+  readonly firstPersonSingular: RegExp;
+  /** Promises of profit and orders to buy (YMYL). */
+  readonly profitPromises: RegExp;
+  readonly notation: NumberNotation;
+  /** An enumeration of three ("a, b and c"); more than three in a text reads as a template. */
+  readonly triad: RegExp;
+  /** Whether Title Case Headings are a mistake in this language. */
+  readonly flagsTitleCaseHeadings: boolean;
+}

package/src/quality/settings.ts

@@ -0,0 +1,60 @@
+// The gate's resolved settings: the parsed options plus what the app config adds (its origins and time
+// zone) and the blog's image policy, with the ruleset and voice patterns compiled once.
+import type { SoftureConfig } from "@softure-ai/core";
+import type { ArticleImagePolicy } from "../render/images.js";
+import type { QualitySeverity } from "./finding.js";
+import type { QualityOptions } from "./options.js";
+import { QUALITY_RULESETS } from "./rulesets/index.js";
+import type { LanguageRuleset, StylePattern } from "./rulesets/types.js";
+
+export interface QualitySettings {
+  readonly options: QualityOptions;
+  readonly ruleset: LanguageRuleset;
+  /** The app's voice phrases plus, when switched on, the ruleset's first person singular. */
+  readonly voicePatterns: readonly StylePattern[];
+  /** Origins whose absolute links are internal: the app's `appOrigin`, the site origin and `ownOrigins`. */
+  readonly ownOrigins: readonly string[];
+  /** IANA time zone of "today". */
+  readonly timeZone: string;
+  /** The app's image policy (`blog({ images })`); `null` when bodies may show no image. */
+  readonly images: ArticleImagePolicy | null;
+}
+
+export function resolveQualitySettings(
+  options: QualityOptions,
+  config: Pick<SoftureConfig, "appOrigin" | "timezone"> & {
+    /** The canonical site origin (core's `getSiteUrls(config).origin`) when it is not `appOrigin`. */
+    readonly siteOrigin?: string;
+  },
+  images: ArticleImagePolicy | null = null,
+): QualitySettings {
+  const ruleset = QUALITY_RULESETS[options.language];
+  const voicePatterns: StylePattern[] = options.voice.phrases.map((phrase) => ({
+    id: phrase.id,
+    severity: phrase.severity,
+    pattern: phrase.pattern,
+    message: phrase.message,
+  }));
+  if (options.voice.forbidFirstPersonSingular) {
+    voicePatterns.push({
+      id: "first-person-singular",
+      severity: "error",
+      pattern: ruleset.firstPersonSingular,
+      message: "first person singular; the texts are signed by the editors (\"we\", \"you\"), never \"I\"",
+    });
+  }
+  const origins = [config.appOrigin, ...(config.siteOrigin === undefined ? [] : [config.siteOrigin]), ...options.ownOrigins].map((origin) => new URL(origin).origin);
+  return { options, ruleset, voicePatterns, ownOrigins: [...new Set(origins)], timeZone: config.timezone, images };
+}
+
+/** `YYYY-MM-DD` of a moment in a time zone. */
+export function getLocalDate(moment: Date, timeZone: string): string {
+  return new Intl.DateTimeFormat("en-CA", { timeZone, year: "numeric", month: "2-digit", day: "2-digit" }).format(moment);
+}
+
+/** The severity a finding of `rule` gets: the override, else its own; `null` for "off". */
+export function getEffectiveSeverity(settings: QualitySettings, rule: string, severity: QualitySeverity): QualitySeverity | null {
+  const override = settings.options.severity[rule];
+  if (override === undefined) return severity;
+  return override === "off" ? null : override;
+}

package/src/quality/text.ts

@@ -0,0 +1,113 @@
+// Text helpers of the gate (FIRE_TRACKER `src/lib/blog/quality/text.ts`): prose without markup, words,
+// sentences, links, footnote references and the numbers that need a source. Number notation comes
+// from the language ruleset, so "28 260,50" and "28,260.50" both read as one number.
+
+export interface MarkdownLink {
+  readonly text: string;
+  readonly url: string;
+}
+
+/** How a language writes numbers, and which numbers count as facts that need a source. */
+export interface NumberNotation {
+  /** A number token; global. */
+  readonly number: RegExp;
+  /** A unit right after the number (`%`, a currency, "million"); tested on the text that follows. */
+  readonly unitAfter: RegExp;
+  /** A unit right before the number (`$`); tested on the text before. `null`: none. */
+  readonly unitBefore: RegExp | null;
+  /** A legal or list reference before the number ("art.", "§", "no."), which needs no source. */
+  readonly referenceBefore: RegExp;
+  /** The digits to remove before reading the number (thousands separators). */
+  readonly thousandsSeparator: RegExp;
+  readonly decimalSeparator: "," | ".";
+}
+
+// No `[` inside link text, link target or footnote id: each match attempt ends at the next `[`, so a
+// long run of unclosed brackets stays linear instead of rescanning the rest of the text per bracket.
+// An image (`![alt](src)`) is not a link: the lookbehind skips it, and `IMAGE` removes it from prose.
+const LINK = /(?<!!)\[([^[\]]*)\]\(([^)\s[]+)(?:\s+"[^"]*")?\)/g;
+const IMAGE = /!\[[^[\]]*\]\([^)\s[]+(?:\s+"[^"]*")?\)/g;
+const FOOTNOTE_REF = /\[\^([^[\]]+)\]/g;
+const URL_IN_TEXT = /https?:\/\/[^\s)>\]]+/g;
+
+export function findLinks(text: string): MarkdownLink[] {
+  return [...text.matchAll(LINK)].map((match) => ({ text: match[1] ?? "", url: match[2] ?? "" }));
+}
+
+export function findFootnoteRefs(text: string): string[] {
+  return [...text.matchAll(FOOTNOTE_REF)].map((match) => match[1] ?? "");
+}
+
+/** Bare URLs in a text (a footnote definition), without trailing punctuation. */
+export function findBareUrls(text: string): string[] {
+  return [...text.matchAll(URL_IN_TEXT)].map((match) => match[0].replace(/[.,;]$/, ""));
+}
+
+/** The prose a reader sees: no code, images, link targets, footnote refs, URLs or emphasis markers. */
+export function toProse(text: string): string {
+  return text
+    .replace(/`[^`]*`/g, " ")
+    .replace(IMAGE, " ")
+    .replace(LINK, "$1")
+    .replace(FOOTNOTE_REF, "")
+    .replace(/<https?:\/\/[^>]+>/g, " ")
+    .replace(/https?:\/\/\S+/g, " ")
+    .replace(/\*\*|__/g, "")
+    .replace(/(?<![\p{L}\d])[*_](?=\S)|(?<=\S)[*_](?![\p{L}\d])/gu, "")
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+export function countWords(prose: string): number {
+  return prose.match(/[\p{L}\d][\p{L}\d'’-]*/gu)?.length ?? 0;
+}
+
+/**
+ * Sentences of prose. A boundary is `.`, `!`, `?` or `…` before an upper-case letter, a quote or a
+ * bracket, never before a digit, so "art. 27" and "approx. 300" do not cut a sentence.
+ */
+export function splitSentences(prose: string): string[] {
+  return prose
+    .split(/(?<=[.!?…])\s+(?=[\p{Lu}„“"(])/u)
+    .map((sentence) => sentence.trim())
+    .filter((sentence) => sentence.length > 0);
+}
+
+/**
+ * The numbers that need a source: amounts, percentages and numbers from 1000 up. Ages, years
+ * (1900–2100), small counts and legal references ("art. 27") need none, or every text about law
+ * would fail.
+ */
+export function findSignificantNumbers(prose: string, notation: NumberNotation): string[] {
+  const found: string[] = [];
+  for (const match of prose.matchAll(new RegExp(notation.number.source, "g"))) {
+    const raw = match[0];
+    const before = prose.slice(Math.max(0, match.index - 12), match.index);
+    const after = prose.slice(match.index + raw.length, match.index + raw.length + 12);
+    if (/[\p{L}\d]$/u.test(before) || notation.referenceBefore.test(before)) continue;
+    if (notation.unitAfter.test(after) || (notation.unitBefore?.test(before) ?? false)) {
+      found.push(raw);
+      continue;
+    }
+    const value = parseNumber(raw, notation);
+    const looksLikeYear = /^\d{4}$/.test(raw) && value >= 1900 && value <= 2100;
+    if (value >= 1000 && !looksLikeYear) found.push(raw);
+  }
+  return found;
+}
+
+/** "28 260,50" (pl) or "28,260.50" (en) → 28260.5. */
+export function parseNumber(raw: string, notation: NumberNotation): number {
+  const digits = raw.replace(new RegExp(notation.thousandsSeparator.source, "g"), "");
+  return Number(notation.decimalSeparator === "," ? digits.replace(",", ".") : digits);
+}
+
+/** A number without thousands separators, to compare a text with a table. */
+export function normalizeNumber(raw: string, notation: NumberNotation): string {
+  return raw.replace(new RegExp(notation.thousandsSeparator.source, "g"), "");
+}
+
+/** A case-insensitive pattern with word edges that know non-ASCII letters (`\b` knows only ASCII). */
+export function wordPattern(source: string): RegExp {
+  return new RegExp(`(?<![\\p{L}\\d])(?:${source})(?![\\p{L}\\d])`, "giu");
+}

package/src/render/glossary.ts

@@ -0,0 +1,103 @@
+// Matching glossary term forms in plain text: no Markdown and no database. The renderer
+// (`render-article.ts`) calls the matcher on the text of paragraphs, lists and tables.
+//
+// - A form is a phrase from the term's file (`forms`), not a word cut out of an inflection: an editor
+//   picks "bridge to retirement", not "bridge", so a plain sentence about a bridge gets no link.
+// - Word bounds are Unicode-aware. `\b` in JS knows only ASCII, so "IKE" would hit "IKEA" without
+//   lookarounds on `\p{L}`.
+// - Case as written in the form, plus a variant with a capital first letter (start of a sentence).
+//   "IKE" does not hit "ike": an acronym in lower case is another word or a typo.
+// - The longest form wins at the same position: "IKZE relief" before "IKZE" when both are terms.
+import type { BlogArticle } from "../contract.js";
+
+export interface GlossaryTerm {
+  readonly slug: string;
+  readonly forms: readonly string[];
+}
+
+export interface TermMatch {
+  readonly index: number;
+  readonly text: string;
+  readonly slug: string;
+}
+
+/** Every occurrence of a form in the text, left to right, without overlaps. */
+export type TermMatcher = (text: string) => TermMatch[];
+
+function escapeRegExp(text: string): string {
+  return text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+function capitalize(text: string): string {
+  return text.charAt(0).toUpperCase() + text.slice(1);
+}
+
+export function createTermMatcher(terms: readonly GlossaryTerm[]): TermMatcher {
+  const slugByForm = new Map<string, string>();
+  for (const term of terms) {
+    for (const form of term.forms) {
+      const trimmed = form.trim();
+      if (trimmed === "") continue;
+      // The first term with a given form wins: two terms with the same phrase are an editorial
+      // mistake (`findTermFormConflicts`: the publish run refuses it and `check` reports it), and the
+      // link has to be deterministic for rows stored before that check.
+      for (const variant of [trimmed, capitalize(trimmed)]) {
+        if (!slugByForm.has(variant)) slugByForm.set(variant, term.slug);
+      }
+    }
+  }
+  if (slugByForm.size === 0) return () => [];
+  const alternatives = [...slugByForm.keys()]
+    .sort((a, b) => b.length - a.length || a.localeCompare(b))
+    .map(escapeRegExp)
+    .join("|");
+  const pattern = new RegExp(`(?<![\\p{L}\\p{N}])(?:${alternatives})(?![\\p{L}\\p{N}])`, "gu");
+
+  return (text) =>
+    [...text.matchAll(pattern)].map((match) => ({
+      index: match.index,
+      text: match[0],
+      // Every alternative of the pattern is a key of the map.
+      slug: slugByForm.get(match[0]) ?? "",
+    }));
+}
+
+/** A form that two or more terms claim; `slugs` sorted, the form as the first of them writes it. */
+export interface TermFormConflict {
+  readonly form: string;
+  readonly slugs: readonly string[];
+}
+
+/**
+ * Forms claimed by more than one term. Two forms collide for the matcher exactly when they are equal
+ * after a capital first letter ("ike" and "Ike" do; "IKE" and "Ike" do not), so that is the key. A term
+ * that lists one form twice is no conflict. Sorted by form, for stable messages.
+ */
+export function findTermFormConflicts(terms: readonly GlossaryTerm[]): TermFormConflict[] {
+  const claims = new Map<string, Map<string, string>>();
+  for (const term of terms) {
+    for (const form of term.forms) {
+      const trimmed = form.trim();
+      if (trimmed === "") continue;
+      const key = capitalize(trimmed);
+      const bySlug = claims.get(key) ?? new Map<string, string>();
+      if (!bySlug.has(term.slug)) bySlug.set(term.slug, trimmed);
+      claims.set(key, bySlug);
+    }
+  }
+  return [...claims.values()]
+    .filter((bySlug) => bySlug.size > 1)
+    .map((bySlug) => {
+      const slugs = [...bySlug.keys()].sort();
+      // `slugs` holds the keys of the map, so the first one is there.
+      return { form: bySlug.get(slugs[0] ?? "") ?? "", slugs };
+    })
+    .sort((a, b) => a.form.localeCompare(b.form));
+}
+
+/** The glossary of a site from its stored rows: every `kind = "term"` row with its forms. */
+export function toGlossary(articles: readonly Pick<BlogArticle, "kind" | "slug" | "termForms">[]): GlossaryTerm[] {
+  return articles
+    .filter((article) => article.kind === "term" && article.termForms.length > 0)
+    .map((article) => ({ slug: article.slug, forms: article.termForms }));
+}

package/src/render/images.ts

@@ -0,0 +1,110 @@
+// Images in article bodies under the app's image policy: one check for the renderer (emit or not) and
+// the quality gate (report why not). An image follows the policy when its source stays on the site (a
+// root-relative path) or comes over https from a host the app allows, its alt text is not empty and the
+// app knows its width and height, so the page reserves its box before it loads.
+import MarkdownIt from "markdown-it";
+import footnote from "markdown-it-footnote";
+
+export interface ImageDimensions {
+  readonly width: number;
+  readonly height: number;
+}
+
+export interface ArticleImagePolicy {
+  /** Hosts whose https images are allowed besides the site's own paths (`cdn.example.com` covers its subdomains). */
+  readonly hosts?: readonly string[];
+  /**
+   * Width and height in pixels of an allowed source, or `null` when the app does not know them. The
+   * source is the normalised URL the page requests (percent-encoded: a space is `%20`).
+   */
+  readonly dimensions: (src: string) => ImageDimensions | null;
+}
+
+export type ImageProblem = "source" | "alt" | "dimensions";
+
+export type ImageVerdict =
+  | { readonly ok: true; readonly width: number; readonly height: number }
+  | { readonly ok: false; readonly problems: readonly ImageProblem[] };
+
+export interface ArticleImage {
+  readonly src: string;
+  readonly alt: string;
+}
+
+export interface FoundImage extends ArticleImage {
+  /** 1-based line of the block that holds the image. */
+  readonly line: number;
+}
+
+// A placeholder origin: a root-relative source must resolve to it, or it leaves the site.
+const SITE_BASE = "https://site.invalid";
+
+function isOnSite(src: string): boolean {
+  if (!src.startsWith("/")) return false;
+  try {
+    return new URL(src, SITE_BASE).origin === SITE_BASE;
+  } catch {
+    return false;
+  }
+}
+
+function isOnAllowedHost(src: string, hosts: readonly string[]): boolean {
+  let url: URL;
+  try {
+    url = new URL(src);
+  } catch {
+    return false;
+  }
+  if (url.protocol !== "https:" || url.username !== "" || url.password !== "") return false;
+  const host = url.hostname.toLowerCase();
+  return hosts.some((allowed) => {
+    const own = allowed.toLowerCase();
+    return host === own || host.endsWith(`.${own}`);
+  });
+}
+
+function isAllowedSource(src: string, policy: ArticleImagePolicy | undefined): boolean {
+  if (policy === undefined) return false;
+  return isOnSite(src) || isOnAllowedHost(src, policy.hosts ?? []);
+}
+
+function isPixelCount(value: unknown): value is number {
+  return typeof value === "number" && Number.isInteger(value) && value > 0;
+}
+
+/**
+ * Whether an image follows the policy, and why not. Without a policy no image does. `dimensions` is
+ * asked only for an allowed source; a throw there is the app's bug and propagates.
+ */
+export function checkArticleImage(image: ArticleImage, policy: ArticleImagePolicy | undefined): ImageVerdict {
+  const problems: ImageProblem[] = [];
+  const isAllowed = isAllowedSource(image.src, policy);
+  if (!isAllowed) problems.push("source");
+  if (image.alt.trim() === "") problems.push("alt");
+  const size = isAllowed && policy !== undefined ? policy.dimensions(image.src) : null;
+  const hasSize = size !== null && isPixelCount(size.width) && isPixelCount(size.height);
+  if (isAllowed && !hasSize) problems.push("dimensions");
+  if (problems.length > 0 || size === null) return { ok: false, problems };
+  return { ok: true, width: size.width, height: size.height };
+}
+
+/**
+ * The images of a text with their lines, for the quality gate. It parses like the renderer, but lets
+ * every link scheme through, so an image the renderer would drop as text (`javascript:`) is listed and
+ * reported too.
+ */
+export function findArticleImages(markdown: string): FoundImage[] {
+  const md = new MarkdownIt({ html: false, linkify: false, typographer: false });
+  md.use(footnote);
+  md.validateLink = () => true;
+  const images: FoundImage[] = [];
+  for (const token of md.parse(markdown, {})) {
+    if (token.type !== "inline" || token.children === null) continue;
+    const line = (token.map?.[0] ?? 0) + 1;
+    for (const child of token.children) {
+      if (child.type !== "image") continue;
+      images.push({ src: String(child.attrGet("src") ?? ""), alt: md.renderer.renderInlineAsText(child.children ?? [], md.options, {}), line });
+    }
+  }
+  return images;
+}

package/src/render/index.ts

@@ -0,0 +1,29 @@
+// Server-side article rendering: Markdown to safe HTML, images under a policy, glossary links, block
+// plugins, reading time.
+export { createTermMatcher, findTermFormConflicts, toGlossary, type GlossaryTerm, type TermFormConflict, type TermMatch, type TermMatcher } from "./glossary.js";
+export {
+  checkArticleImage,
+  findArticleImages,
+  type ArticleImage,
+  type ArticleImagePolicy,
+  type FoundImage,
+  type ImageDimensions,
+  type ImageProblem,
+  type ImageVerdict,
+} from "./images.js";
+export { DEFAULT_WORDS_PER_MINUTE, getReadingMinutes } from "./reading-time.js";
+export {
+  findArticleBlocks,
+  renderArticle,
+  type ArticleBlock,
+  type ArticleHeading,
+  type ArticleSegment,
+  type BlockArticle,
+  type BlockOutput,
+  type BlockPlugin,
+  type BlogRenderMessages,
+  type FoundBlock,
+  type RenderArticleOptions,
+  type RenderedArticle,
+} from "./render-article.js";
+export { slugifyHeading } from "./slugify-heading.js";

package/src/render/reading-time.ts

@@ -0,0 +1,18 @@
+// Reading time of an article body.
+
+/** Words per minute assumed for prose of an article. */
+export const DEFAULT_WORDS_PER_MINUTE = 200;
+
+/**
+ * Minutes needed to read the text: words of prose (footnote definitions, URLs and Markdown syntax
+ * removed), rounded up, at least 1.
+ */
+export function getReadingMinutes(markdown: string, wordsPerMinute: number = DEFAULT_WORDS_PER_MINUTE): number {
+  const prose = markdown
+    .replace(/^\[\^[^\]]+\]:.*$/gm, "")
+    .replace(/https?:\/\/\S+/g, "")
+    .replace(/\[\^[^\]]+\]/g, "")
+    .replace(/[#>*_|`[\]()-]/g, " ");
+  const words = prose.split(/\s+/).filter((word) => /\p{L}|\d/u.test(word)).length;
+  return Math.max(1, Math.ceil(words / wordsPerMinute));
+}