@softure-ai/blog 0.0.0-stage → 0.1.5

package/src/quality/catalog.ts

@@ -0,0 +1,86 @@
+// The rule catalog: every rule the gate can report for an app's settings, with its effective
+// severity. The writing skill (BL-7) is checked against it, so a rule the gate enforces is named in
+// the skill and the skill names no rule the gate lacks.
+import type { QualitySeverity } from "./finding.js";
+import type { QualityRuleInfo } from "./plugin.js";
+import { getEffectiveSeverity, type QualitySettings } from "./settings.js";
+
+export const QUALITY_RULE_GROUPS = ["file", "structure", "links", "images", "ymyl", "style", "voice", "plugin"] as const;
+export type QualityRuleGroup = (typeof QUALITY_RULE_GROUPS)[number];
+
+export interface QualityCatalogRule extends QualityRuleInfo {
+  readonly group: QualityRuleGroup;
+}
+
+const rule = (group: QualityRuleGroup, id: string, severity: QualitySeverity, description: string): QualityCatalogRule => ({ group, id, severity, description });
+
+/** Rules that do not depend on the ruleset, the voice or plugins. */
+const CORE_RULES: readonly QualityCatalogRule[] = [
+  rule("file", "file", "error", "the file parses: frontmatter keys and values, slug equal to the file name"),
+  rule("structure", "title-length", "warning", "the title fits in search results (limits.titleChars)"),
+  rule("structure", "description-length", "warning", "the description is between limits.descriptionChars.min and max characters"),
+  rule("structure", "as-of-future", "error", "current_as_of is not in the future"),
+  rule("structure", "stale", "warning", "current_as_of is not older than limits.staleAfterDays"),
+  rule("structure", "summary-missing", "error", "an article has a summary"),
+  rule("structure", "lead", "error", "the text opens with a paragraph that answers"),
+  rule("structure", "lead-length", "warning", "the first paragraph fits in limits.leadWords"),
+  rule("structure", "lead-number", "error", "an article has a concrete number in its first two paragraphs"),
+  rule("structure", "heading-h1", "error", "no # heading in the body"),
+  rule("structure", "heading-order", "error", "headings do not skip a level"),
+  rule("structure", "sections", "error", "an article has at least two ## sections"),
+  rule("structure", "section-question", "error", "at least one ## heading of an article is a question"),
+  rule("structure", "section-answer", "error", "a question heading is followed by a paragraph"),
+  rule("structure", "section-answer-length", "warning", "the answer under a question fits in limits.answerWords"),
+  rule("structure", "length", "error", "the word count is within limits.words (a warning above the maximum)"),
+  rule("structure", "footnote-undefined", "error", "every footnote reference has a definition"),
+  rule("structure", "footnote-unused", "warning", "every footnote definition is referenced"),
+  rule("links", "internal-links", "error", "at least limits.internalLinks internal links (a warning for a term)"),
+  rule("links", "internal-link-target", "error", "every internal link leads to a page, article or glossary term"),
+  rule("links", "external-link-https", "warning", "external links use https"),
+  rule("links", "external-link-dead", "error", "external links answer 2xx (only with --external)"),
+  rule("links", "term-form-conflict", "error", "a glossary form belongs to one published term (only in check; publish refuses it always)"),
+  rule("images", "image-source", "error", "an image comes from the site or a host of blog({ images: { hosts } })"),
+  rule("images", "image-alt", "error", "an image has alt text"),
+  rule("images", "image-dimensions", "error", "the app knows an image's width and height (blog({ images: { dimensions } }))"),
+  rule("style", "dashes", "error", "at most one dash per limits.wordsPerDash words"),
+  rule("style", "dashes-paragraph", "warning", "at most one dash per paragraph"),
+  rule("style", "bold-density", "warning", "at most one bold phrase per limits.wordsPerBold words"),
+  rule("style", "bold-labels", "warning", "fewer than three list items start with a bold label"),
+  rule("style", "triads", "warning", "at most three lists of three"),
+  rule("style", "long-sentences", "warning", "sentences fit in limits.sentenceWords"),
+  rule("style", "monotone-rhythm", "warning", "sentence lengths vary"),
+  rule("style", "repeated-openings", "warning", "no three sentences in a row start with the same word"),
+];
+
+const YMYL_RULES: readonly QualityCatalogRule[] = [
+  rule("ymyl", "sources-missing", "error", "an article lists its sources"),
+  rule("ymyl", "source-https", "error", "every source address uses https"),
+  rule("ymyl", "number-source", "error", "every significant number (amount, percentage, 1000 or more) carries a footnote"),
+  rule("ymyl", "footnote-source", "error", "every footnote has a source address or the app's own calculation mark"),
+  rule("ymyl", "footnote-not-in-sources", "error", "every address in a footnote is a listed source"),
+  rule("ymyl", "profit-promise", "error", "no promise of profit and no order to buy"),
+];
+
+const PLUGIN_RULES: readonly QualityCatalogRule[] = [
+  rule("plugin", "plugin-failed", "error", "a rule plugin ran without throwing"),
+  rule("plugin", "plugin-rule-undeclared", "error", "a rule plugin reports only the rules it declares"),
+];
+
+/** Every rule the gate can report with these settings, with the effective severity; rules switched off are left out. */
+export function listQualityRules(settings: QualitySettings): QualityCatalogRule[] {
+  const { ruleset, options } = settings;
+  const rules: QualityCatalogRule[] = [
+    ...CORE_RULES,
+    ...(ruleset.flagsTitleCaseHeadings ? [rule("style", "title-case-heading", "warning", "headings use sentence case")] : []),
+    ...ruleset.patterns.map((pattern) => rule("style", pattern.id, pattern.severity, pattern.message)),
+    ...settings.voicePatterns.map((pattern) => rule("voice", pattern.id, pattern.severity, pattern.message)),
+    ...(options.ymyl === null ? [] : YMYL_RULES),
+    ...(options.blocks.length === 0 ? [] : [rule("structure", "block-requires", "error", "a block plugin's fenced block has the frontmatter keys it requires")]),
+    ...(options.plugins.length === 0 ? [] : PLUGIN_RULES),
+    ...options.plugins.flatMap((plugin) => plugin.rules.map((info) => rule("plugin", info.id, info.severity, info.description))),
+  ];
+  return rules.flatMap((entry) => {
+    const severity = getEffectiveSeverity(settings, entry.id, entry.severity);
+    return severity === null ? [] : [{ ...entry, severity }];
+  });
+}

package/src/quality/check-article.ts

@@ -0,0 +1,112 @@
+// The gate over one article (FIRE_TRACKER `src/lib/blog/quality/check-article.ts`): one entry for
+// `softure-blog check`, the publish gate and the tests. Pure: the parsed article, today and the link
+// resolver come in; the network check of external links is separate.
+import type { BlogArticleInput } from "../contract.js";
+import { findArticleImages } from "../render/images.js";
+import { findArticleBlocks, type FoundBlock } from "../render/render-article.js";
+import { parseArticleFile, type ParseArticleFileOptions } from "../content/article-file.js";
+import { splitArticleBody, splitBlocks } from "./blocks.js";
+import { sortFindings, type QualityFinding } from "./finding.js";
+import type { QualityPlugin } from "./plugin.js";
+import { checkBlockRequires } from "./rules/blocks.js";
+import { checkImages } from "./rules/images.js";
+import type { RuleInput } from "./rules/input.js";
+import { checkLinks, collectLinks, type InternalLinkResolver } from "./rules/links.js";
+import { checkFootnotes, checkLead, checkLength, checkMetadata, checkSections } from "./rules/structure.js";
+import { checkMetadataStyle, checkRhythm, checkStyle } from "./rules/style.js";
+import { checkNumberSources, checkSources } from "./rules/ymyl.js";
+import { getEffectiveSeverity, type QualitySettings } from "./settings.js";
+
+export interface QualityCheckResult {
+  readonly findings: readonly QualityFinding[];
+  /** External addresses for the network check (`--external`). */
+  readonly externalLinks: readonly { readonly url: string; readonly line: number }[];
+}
+
+export interface CheckArticleInput {
+  /** The parsed file. */
+  readonly article: BlogArticleInput;
+  /** The whole file text, for the body's line numbers. */
+  readonly text: string;
+  readonly settings: QualitySettings;
+  /** `YYYY-MM-DD` in the app's time zone. */
+  readonly today: string;
+  /** Default: every internal link exists (the publish gate; `check` resolves them). */
+  readonly resolveInternalLink?: InternalLinkResolver;
+}
+
+export function checkArticle(input: CheckArticleInput): QualityCheckResult {
+  const { article, settings, today } = input;
+  const split = splitArticleBody(input.text);
+  const blocks = split === null ? splitBlocks(article.bodyMarkdown) : splitBlocks(split.body, split.bodyStartLine);
+  const body = split?.body ?? article.bodyMarkdown;
+  const bodyStartLine = split?.bodyStartLine ?? 1;
+  const pluginBlocks = findPluginBlocks(body, bodyStartLine, settings);
+  const images = findArticleImages(body).map((image) => ({ ...image, line: image.line + bodyStartLine - 1 }));
+  const ruleInput: RuleInput = { article, blocks, settings, today };
+  const links = collectLinks(ruleInput);
+
+  const builtIn = [
+    ...checkMetadata(ruleInput),
+    ...checkMetadataStyle(ruleInput),
+    ...checkLead(ruleInput),
+    ...checkSections(ruleInput),
+    ...checkLength(ruleInput),
+    ...checkFootnotes(ruleInput),
+    ...(settings.options.ymyl === null ? [] : [...checkSources(ruleInput), ...checkNumberSources(ruleInput)]),
+    ...checkLinks(ruleInput, links, input.resolveInternalLink ?? (() => true)),
+    ...checkStyle(ruleInput),
+    ...checkRhythm(ruleInput),
+    ...checkBlockRequires(article, pluginBlocks),
+    ...checkImages(images, settings.images),
+  ];
+  const fromPlugins = settings.options.plugins.flatMap((plugin) => runPlugin(plugin, { article, blocks, pluginBlocks, today, ruleset: settings.ruleset }));
+  return { findings: applySeverity(settings, [...builtIn, ...fromPlugins]), externalLinks: links.external };
+}
+
+export interface CheckArticleTextInput extends Omit<CheckArticleInput, "article"> {
+  /** A path or a bare name; it must read `<slug>.md`. */
+  readonly fileName: string;
+  /** The app's `fields` and reserved slugs, as the publish run applies them. */
+  readonly parse?: ParseArticleFileOptions;
+}
+
+/** Parses the file first; parse errors are `file` findings and stop the check. */
+export function checkArticleText(input: CheckArticleTextInput): QualityCheckResult {
+  const parsed = parseArticleFile(input.text, input.fileName, input.parse);
+  if (!parsed.ok) {
+    return { findings: applySeverity(input.settings, parsed.errors.map((message) => ({ rule: "file", severity: "error", message }))), externalLinks: [] };
+  }
+  return checkArticle({ ...input, article: parsed.article });
+}
+
+/** The app's plugin blocks with file lines; none without `quality.blocks`. */
+function findPluginBlocks(body: string, bodyStartLine: number, settings: QualitySettings): FoundBlock[] {
+  if (settings.options.blocks.length === 0) return [];
+  return findArticleBlocks(body, settings.options.blocks).map((block) => ({ ...block, line: block.line + bodyStartLine - 1 }));
+}
+
+function runPlugin(plugin: QualityPlugin, context: Parameters<QualityPlugin["check"]>[0]): QualityFinding[] {
+  let findings: readonly QualityFinding[];
+  try {
+    findings = plugin.check(context);
+  } catch (error) {
+    // A plugin bug must not crash a publish with a stack trace; it refuses the file instead.
+    return [{ rule: "plugin-failed", severity: "error", message: `plugin ${plugin.name} failed: ${error instanceof Error ? error.message : String(error)}` }];
+  }
+  const declared = new Set(plugin.rules.map((info) => info.id));
+  return findings.map((finding) =>
+    declared.has(finding.rule)
+      ? finding
+      : { rule: "plugin-rule-undeclared", severity: "error", message: `plugin ${plugin.name} reported rule ${finding.rule}, which it does not declare`, ...(finding.line === undefined ? {} : { line: finding.line }) },
+  );
+}
+
+function applySeverity(settings: QualitySettings, findings: readonly QualityFinding[]): QualityFinding[] {
+  return sortFindings(
+    findings.flatMap((finding) => {
+      const severity = getEffectiveSeverity(settings, finding.rule, finding.severity);
+      return severity === null ? [] : [{ ...finding, severity }];
+    }),
+  );
+}

package/src/quality/check-files.ts

@@ -0,0 +1,63 @@
+// The gate over article files for `softure-blog check` (FIRE_TRACKER `check-file.ts`): parse, rules,
+// internal links resolved against the app and its content, external links when a fetch is given, and
+// the glossary forms of the whole content folder (a form belongs to one term).
+import type { ArticleFile } from "../db/publish-run.js";
+import { parseArticleFile, type ParseArticleFileOptions } from "../content/article-file.js";
+import { findTermFormConflicts, type GlossaryTerm, type TermFormConflict } from "../render/glossary.js";
+import { checkArticleText } from "./check-article.js";
+import { checkExternalLinks, type FetchLike } from "./external-links.js";
+import { sortFindings, type QualityFinding } from "./finding.js";
+import type { InternalLinkResolver } from "./rules/links.js";
+import { getEffectiveSeverity, type QualitySettings } from "./settings.js";
+
+export interface CheckArticleFilesOptions {
+  readonly settings: QualitySettings;
+  readonly today: string;
+  readonly resolveInternalLink: InternalLinkResolver;
+  readonly parse?: ParseArticleFileOptions;
+  /** When given, external links are requested over the network. */
+  readonly fetch?: FetchLike;
+  /** The site's published terms (`readGlossaryTerms`); a checked term that shares a form with another is reported. */
+  readonly glossary?: readonly GlossaryTerm[];
+}
+
+export interface FileCheckResult {
+  readonly file: string;
+  readonly findings: readonly QualityFinding[];
+}
+
+export async function checkArticleFiles(files: readonly ArticleFile[], options: CheckArticleFilesOptions): Promise<FileCheckResult[]> {
+  const results: FileCheckResult[] = [];
+  const conflicts = findTermFormConflicts(options.glossary ?? []);
+  for (const file of files) {
+    const result = checkArticleText({
+      text: file.text,
+      fileName: file.name,
+      settings: options.settings,
+      today: options.today,
+      resolveInternalLink: options.resolveInternalLink,
+      ...(options.parse === undefined ? {} : { parse: options.parse }),
+    });
+    const external = options.fetch === undefined ? [] : await checkExternalLinks(result.externalLinks, options.fetch);
+    const forms = checkTermForms(file, conflicts, options);
+    results.push({ file: file.name, findings: sortFindings([...result.findings, ...external, ...forms]) });
+  }
+  return results;
+}
+
+/** `term-form-conflict` for a published term file whose forms another term claims too. */
+function checkTermForms(file: ArticleFile, conflicts: readonly TermFormConflict[], options: CheckArticleFilesOptions): QualityFinding[] {
+  if (conflicts.length === 0) return [];
+  const parsed = parseArticleFile(file.text, file.name, options.parse);
+  if (!parsed.ok || parsed.article.kind !== "term" || parsed.article.status !== "published") return [];
+  const { slug } = parsed.article;
+  const severity = getEffectiveSeverity(options.settings, "term-form-conflict", "error");
+  if (severity === null) return [];
+  return conflicts
+    .filter((conflict) => conflict.slugs.includes(slug))
+    .map((conflict) => ({
+      rule: "term-form-conflict",
+      severity,
+      message: `form "${conflict.form}" is also a form of term ${conflict.slugs.filter((other) => other !== slug).join(", ")}; a form belongs to one term, so remove it from all but one`,
+    }));
+}

package/src/quality/external-links.ts

@@ -0,0 +1,37 @@
+// External links answer 2xx (FIRE_TRACKER `src/lib/blog/quality/external-links.ts`). Over the network
+// only on request (`softure-blog check --external`, the weekly workflow): tests and publishing never
+// depend on other people's servers. `fetch` is injected so tests stay offline.
+import type { QualityFinding } from "./finding.js";
+
+export type FetchLike = (
+  url: string,
+  init: { readonly method: string; readonly redirect: "follow"; readonly signal: AbortSignal; readonly headers: Record<string, string> },
+) => Promise<{ readonly status: number }>;
+
+/** Some public-sector servers refuse requests that do not introduce themselves. */
+const USER_AGENT = "softure-blog-link-check/1.0";
+/** Servers without HEAD support answer with these; then the check asks with GET. */
+const RETRY_WITH_GET = new Set([400, 403, 404, 405, 501]);
+const TIMEOUT_MS = 15_000;
+
+export async function checkExternalUrl(url: string, fetchImpl: FetchLike): Promise<{ ok: boolean; detail: string }> {
+  const request = (method: string) => fetchImpl(url, { method, redirect: "follow", signal: AbortSignal.timeout(TIMEOUT_MS), headers: { "user-agent": USER_AGENT } });
+  try {
+    let response = await request("HEAD");
+    if (RETRY_WITH_GET.has(response.status)) response = await request("GET");
+    return { ok: response.status >= 200 && response.status < 300, detail: `HTTP ${String(response.status)}` };
+  } catch (error) {
+    // A network failure is the finding itself: its message tells the editor what happened.
+    return { ok: false, detail: error instanceof Error ? error.message : String(error) };
+  }
+}
+
+/** Each address once, at its first line. */
+export async function checkExternalLinks(links: readonly { readonly url: string; readonly line: number }[], fetchImpl: FetchLike): Promise<QualityFinding[]> {
+  const unique = new Map<string, number>();
+  for (const link of links) if (!unique.has(link.url)) unique.set(link.url, link.line);
+  const results = await Promise.all([...unique].map(async ([url, line]) => ({ url, line, ...(await checkExternalUrl(url, fetchImpl)) })));
+  return results
+    .filter((result) => !result.ok)
+    .map((result) => ({ rule: "external-link-dead", severity: "error", message: `an external link does not answer 2xx (${result.detail}): ${result.url}`, line: result.line }));
+}

package/src/quality/finding.ts

@@ -0,0 +1,29 @@
+// A finding of the quality gate (FIRE_TRACKER `src/lib/blog/quality/finding.ts`). An error refuses a
+// publish and fails `softure-blog check`; a warning only informs.
+
+export const QUALITY_SEVERITIES = ["error", "warning"] as const;
+export type QualitySeverity = (typeof QUALITY_SEVERITIES)[number];
+
+export interface QualityFinding {
+  /** The stable id of the rule, used for severity overrides and by the writing skill. */
+  readonly rule: string;
+  readonly severity: QualitySeverity;
+  /** What is wrong and what to do instead, in English. */
+  readonly message: string;
+  /** The line of the file, from 1, when the rule points at one. */
+  readonly line?: number;
+}
+
+export function hasQualityErrors(findings: readonly QualityFinding[]): boolean {
+  return findings.some((finding) => finding.severity === "error");
+}
+
+/** Errors first, then by line; findings without a line go first within their severity. */
+export function sortFindings(findings: readonly QualityFinding[]): QualityFinding[] {
+  return [...findings].sort((a, b) => (a.severity === b.severity ? (a.line ?? 0) - (b.line ?? 0) : a.severity === "error" ? -1 : 1));
+}
+
+/** `[rule] line N: message`, the form the publish command prints. */
+export function formatFinding(finding: QualityFinding): string {
+  return `[${finding.rule}]${finding.line === undefined ? "" : ` line ${String(finding.line)}`}: ${finding.message}`;
+}

package/src/quality/gate.ts

@@ -0,0 +1,15 @@
+// The quality gate for `softure-blog publish` (FIRE_TRACKER `src/lib/blog/quality/publish-gate.ts`):
+// the errors of a file going public, one line each. Internal links are not resolved here, since a
+// container that publishes may hold no app folder; `softure-blog check` in CI resolves them.
+import type { Clock } from "@softure-ai/core";
+import type { PublishGate } from "../db/publish-run.js";
+import { checkArticle } from "./check-article.js";
+import { formatFinding } from "./finding.js";
+import { getLocalDate, type QualitySettings } from "./settings.js";
+
+export function createQualityGate(settings: QualitySettings, clock: Clock): PublishGate {
+  return (file, article) => {
+    const { findings } = checkArticle({ article, text: file.text, settings, today: getLocalDate(clock.now(), settings.timeZone) });
+    return findings.filter((finding) => finding.severity === "error").map(formatFinding);
+  };
+}

package/src/quality/index.ts

@@ -0,0 +1,28 @@
+// The quality gate's public surface, re-exported from `@softure-ai/blog/server`.
+export { listQualityRules, QUALITY_RULE_GROUPS, type QualityCatalogRule, type QualityRuleGroup } from "./catalog.js";
+export { checkArticle, checkArticleText, type CheckArticleInput, type CheckArticleTextInput, type QualityCheckResult } from "./check-article.js";
+export { checkArticleFiles, type CheckArticleFilesOptions, type FileCheckResult } from "./check-files.js";
+export { getProseBlocks, splitArticleBody, splitBlocks, type Block, type BlockKind } from "./blocks.js";
+export { checkExternalLinks, checkExternalUrl, type FetchLike } from "./external-links.js";
+export { formatFinding, hasQualityErrors, QUALITY_SEVERITIES, sortFindings, type QualityFinding, type QualitySeverity } from "./finding.js";
+export { createQualityGate } from "./gate.js";
+export { collectAppRoutes, createInternalLinkResolver, findAppDir, readContentFolder, readPublishedContent, type AppRoute, type InternalLinkResolverOptions } from "./link-targets.js";
+export { qualityOptionsSchema, type QualityLimits, type QualityOptions, type QualityOptionsInput } from "./options.js";
+export { isQualityPlugin, type QualityPlugin, type QualityPluginContext, type QualityRuleInfo } from "./plugin.js";
+export { collectLinks, type InternalLinkResolver, type LinkSummary } from "./rules/links.js";
+export { enRuleset, plRuleset, QUALITY_LANGUAGES, QUALITY_RULESETS, type LanguageRuleset, type QualityLanguage, type StylePattern } from "./rulesets/index.js";
+export { getLocalDate, resolveQualitySettings, type QualitySettings } from "./settings.js";
+export {
+  countWords,
+  findBareUrls,
+  findFootnoteRefs,
+  findLinks,
+  findSignificantNumbers,
+  normalizeNumber,
+  parseNumber,
+  splitSentences,
+  toProse,
+  wordPattern,
+  type MarkdownLink,
+  type NumberNotation,
+} from "./text.js";

package/src/quality/link-targets.ts

@@ -0,0 +1,107 @@
+// Internal link targets from the file system (FIRE_TRACKER `src/lib/blog/quality/link-targets.ts`),
+// for `softure-blog check`. A route exists when the Next.js app folder has a `page.*` or `route.*` for
+// it (route groups vanish from the path; private segments and `_folders` are skipped). An article or
+// a glossary term exists when the content folder has its published file of that kind, under
+// `quality.paths`; a static page under the same path wins over the dynamic article route.
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { parseArticleFile, type ParseArticleFileOptions } from "../content/article-file.js";
+import type { BlogArticleKind } from "../contract.js";
+import type { GlossaryTerm } from "../render/glossary.js";
+import type { InternalLinkResolver } from "./rules/links.js";
+
+const ROUTE_FILES = /^(?:page|route)\.(?:tsx?|jsx?|mdx?)$/;
+
+export interface AppRoute {
+  readonly pattern: RegExp;
+  /** Has a `[param]` segment. */
+  readonly isDynamic: boolean;
+}
+
+export interface InternalLinkResolverOptions {
+  /** The Next.js app folder, or `null` when the app has none (only content links resolve). */
+  readonly appDir: string | null;
+  readonly privateRouteSegments: readonly string[];
+  readonly paths: { readonly articles: string; readonly terms: string };
+  /** Published texts by slug. */
+  readonly content: ReadonlyMap<string, BlogArticleKind>;
+}
+
+/** The app folder to read: the given one, else `src/app`, else `app`, else none. */
+export function findAppDir(cwd: string, appDir: string | undefined): string | null {
+  if (appDir !== undefined) return join(cwd, appDir);
+  return [join(cwd, "src/app"), join(cwd, "app")].find((dir) => existsSync(dir)) ?? null;
+}
+
+export function collectAppRoutes(appDir: string, privateSegments: readonly string[]): AppRoute[] {
+  const routes: AppRoute[] = [];
+  const walk = (dir: string, segments: readonly string[]): void => {
+    const entries = readdirSync(dir, { withFileTypes: true });
+    if (entries.some((entry) => entry.isFile() && ROUTE_FILES.test(entry.name))) {
+      const visible = segments.filter((segment) => !/^\(.*\)$/.test(segment));
+      const pattern = visible.map((segment) => (/^\[.*\]$/.test(segment) ? "[^/]+" : escapeRegExp(segment))).join("/");
+      routes.push({ pattern: new RegExp(`^/${pattern}$`), isDynamic: visible.some((segment) => /^\[.*\]$/.test(segment)) });
+    }
+    for (const entry of entries) {
+      if (entry.isDirectory() && !privateSegments.includes(entry.name) && !entry.name.startsWith("_")) walk(join(dir, entry.name), [...segments, entry.name]);
+    }
+  };
+  walk(appDir, []);
+  return routes;
+}
+
+/** Published texts in the content folders by slug: the file name is the slug (BL-2), the kind and status come from the frontmatter. */
+export function readPublishedContent(files: readonly { readonly name: string; readonly text: string }[]): Map<string, BlogArticleKind> {
+  const content = new Map<string, BlogArticleKind>();
+  for (const file of files) {
+    const frontmatter = /^---\r?\n([\s\S]*?)\r?\n---/.exec(file.text)?.[1] ?? "";
+    if (!/^status:\s*(["']?)published\1\s*(?:#.*)?$/m.test(frontmatter)) continue;
+    content.set(file.name.replace(/\.md$/, ""), /^kind:\s*(["']?)term\1\s*(?:#.*)?$/m.test(frontmatter) ? "term" : "article");
+  }
+  return content;
+}
+
+/**
+ * The published glossary terms of the content folders, for the form conflict check: a later file
+ * with the same slug replaces an earlier one (a checked file over its copy in the folder). A file that
+ * does not parse is skipped; its own check reports it.
+ */
+export function readGlossaryTerms(files: readonly { readonly name: string; readonly text: string }[], parse: ParseArticleFileOptions = {}): GlossaryTerm[] {
+  const terms = new Map<string, GlossaryTerm>();
+  for (const file of files) {
+    const parsed = parseArticleFile(file.text, file.name, parse);
+    if (!parsed.ok) continue;
+    const { slug, kind, status, termForms } = parsed.article;
+    if (kind === "term" && status === "published") terms.set(slug, { slug, forms: termForms });
+    else terms.delete(slug);
+  }
+  return [...terms.values()];
+}
+
+export function createInternalLinkResolver(options: InternalLinkResolverOptions): InternalLinkResolver {
+  const routes = options.appDir === null || !existsSync(options.appDir) ? [] : collectAppRoutes(options.appDir, options.privateRouteSegments);
+  const term = new RegExp(`^${escapeRegExp(options.paths.terms)}/([^/]+)$`);
+  const article = new RegExp(`^${escapeRegExp(options.paths.articles === "/" ? "" : options.paths.articles)}/([^/]+)$`);
+  const isStaticRoute = (pathname: string) => routes.some((route) => !route.isDynamic && route.pattern.test(pathname));
+  return (rawPathname) => {
+    const pathname = rawPathname.length > 1 ? rawPathname.replace(/\/$/, "") : rawPathname;
+    const termSlug = term.exec(pathname)?.[1];
+    if (termSlug !== undefined) return options.content.get(termSlug) === "term" || isStaticRoute(pathname);
+    const articleSlug = article.exec(pathname)?.[1];
+    if (articleSlug !== undefined) return options.content.get(articleSlug) === "article" || isStaticRoute(pathname);
+    return routes.some((route) => route.pattern.test(pathname));
+  };
+}
+
+/** Reads `*.md` files of a folder except README.md. */
+export function readContentFolder(dir: string): { name: string; text: string }[] {
+  if (!existsSync(dir)) return [];
+  return readdirSync(dir)
+    .filter((name) => name.endsWith(".md") && name !== "README.md")
+    .sort()
+    .map((name) => ({ name, text: readFileSync(join(dir, name), "utf8") }));
+}
+
+function escapeRegExp(text: string): string {
+  return text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}

package/src/quality/options.ts

@@ -0,0 +1,105 @@
+// `blog({ quality })`: the gate's options, parsed at startup with the rest of the blog's options.
+import { z } from "zod";
+import type { BlockPlugin } from "../render/render-article.js";
+import { QUALITY_SEVERITIES } from "./finding.js";
+import { isQualityPlugin, type QualityPlugin } from "./plugin.js";
+import { QUALITY_LANGUAGES } from "./rulesets/types.js";
+
+const KEBAB = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+
+function isBlockPlugin(value: unknown): value is BlockPlugin {
+  if (typeof value !== "object" || value === null) return false;
+  const candidate = value as { type?: unknown; render?: unknown };
+  return typeof candidate.type === "string" && typeof candidate.render === "function";
+}
+
+const range = (min: number, max: number) =>
+  z
+    .strictObject({ min: z.number().int().min(0).default(min), max: z.number().int().positive().default(max) })
+    .prefault({})
+    .refine((value) => value.min <= value.max, "min must not exceed max");
+
+const byKind = (article: number, term: number) =>
+  z.strictObject({ article: z.number().int().min(0).default(article), term: z.number().int().min(0).default(term) }).prefault({});
+
+/** Thresholds; the defaults are FIRE's, chosen for answer-first texts that AI assistants quote. */
+export const qualityLimitsSchema = z
+  .strictObject({
+    words: z.strictObject({ article: range(600, 4000), term: range(60, 700) }).prefault({}),
+    leadWords: byKind(90, 60),
+    answerWords: z.number().int().positive().default(70),
+    internalLinks: byKind(2, 1),
+    staleAfterDays: z.number().int().positive().default(365),
+    titleChars: z.number().int().positive().default(70),
+    descriptionChars: range(50, 160),
+    wordsPerDash: z.number().int().positive().default(150),
+    wordsPerBold: z.number().int().positive().default(200),
+    sentenceWords: z.number().int().positive().default(35),
+  })
+  .prefault({});
+
+const sitePath = z.string().regex(/^\/[a-z0-9/_-]*$/, "must be a path from the site root, e.g. /blog").transform((path) => (path.length > 1 ? path.replace(/\/$/, "") : path));
+
+export const qualityOptionsSchema = z.strictObject({
+  /** The ruleset of the blog's language. */
+  language: z.enum(QUALITY_LANGUAGES).default("en"),
+  /** Your money or your life: sources required, every significant number footnoted, no profit promises. */
+  ymyl: z
+    .union([z.boolean(), z.strictObject({ ownCalculationMark: z.string().trim().min(1).optional() })])
+    .default(false)
+    .transform((value) => (value === false ? null : { ownCalculationMark: value === true ? null : (value.ownCalculationMark ?? null) })),
+  voice: z
+    .strictObject({
+      /** Texts signed by an editorial team: no "I", "my", "in my opinion". */
+      forbidFirstPersonSingular: z.boolean().default(false),
+      /**
+       * The brand's banned phrases: a global regular expression, matched as given. `wordPattern("...")`
+       * builds one that is case-insensitive and knows word edges in any alphabet.
+       */
+      phrases: z
+        .array(
+          z.strictObject({
+            id: z.string().max(60).regex(KEBAB, "kebab-case, e.g. finance-cliche"),
+            pattern: z.instanceof(RegExp, { error: "must be a regular expression" }).refine((pattern) => pattern.global, "must be global (flag g), so every hit counts"),
+            message: z.string().trim().min(1),
+            severity: z.enum(QUALITY_SEVERITIES).default("error"),
+          }),
+        )
+        .default([]),
+    })
+    .prefault({}),
+  limits: qualityLimitsSchema,
+  /** Per rule: another severity, or "off". */
+  severity: z.record(z.string().regex(KEBAB), z.enum(["error", "warning", "off"])).default({}),
+  /** Where the pages live; BL-4 serves them there. */
+  paths: z.strictObject({ articles: sitePath.default("/blog"), terms: sitePath.default("/blog/glossary") }).prefault({}),
+  /** Absolute origins whose links count as internal, besides the config's `appOrigin` and the canonical site origin (`getSiteUrls`). */
+  ownOrigins: z.array(z.url({ protocol: /^https?$/ })).default([]),
+  /** The Next.js app folder `softure-blog check` reads routes from. Default: `src/app`, else `app`. */
+  appDir: z.string().trim().min(1).optional(),
+  /** Route folders that are no link target (API, pages behind a login). Route groups count too, e.g. "(app)". */
+  privateRouteSegments: z.array(z.string().min(1)).default(["api"]),
+  plugins: z.array(z.custom<QualityPlugin>(isQualityPlugin, "must be a plugin: { name, rules, check }")).default([]),
+  /** The block plugins the app renders with (`renderArticle({ blocks })`): their `requires` keys must be in the frontmatter. */
+  blocks: z.array(z.custom<BlockPlugin>(isBlockPlugin, "must be a block plugin: { type, render }")).default([]),
+});
+
+export type QualityOptionsInput = z.input<typeof qualityOptionsSchema>;
+export type QualityOptions = z.output<typeof qualityOptionsSchema>;
+export type QualityLimits = QualityOptions["limits"];
+
+/**
+ * `blog({ quality })`: the options, or `false` to turn the gate off. Not a zod union, whose error
+ * would read "Invalid input" and hide which option is wrong: the options' own issues are reported.
+ * The cast gives it the types of a defaulted option: optional in, never undefined out.
+ */
+export const qualitySettingSchema = z
+  .unknown()
+  .optional()
+  .transform((value, ctx): QualityOptions | false => {
+    if (value === false) return false;
+    const parsed = qualityOptionsSchema.safeParse(value ?? {});
+    if (parsed.success) return parsed.data;
+    for (const issue of parsed.error.issues) ctx.addIssue({ code: "custom", message: issue.message, path: issue.path });
+    return z.NEVER;
+  }) as unknown as z.ZodDefault<z.ZodType<QualityOptions | false, QualityOptionsInput | false>>;

package/src/quality/plugin.ts

@@ -0,0 +1,43 @@
+// The rule plugin API: an app adds its domain rules (FIRE: legal figures equal the engine's, numbers
+// next to a chart stand in its table) to `blog({ quality: { plugins } })`.
+import type { BlogArticleInput } from "../contract.js";
+import type { FoundBlock } from "../render/render-article.js";
+import type { Block } from "./blocks.js";
+import type { QualityFinding, QualitySeverity } from "./finding.js";
+import type { LanguageRuleset } from "./rulesets/types.js";
+
+/** A rule as the catalog lists it: what the writing skill names and the gate enforces. */
+export interface QualityRuleInfo {
+  readonly id: string;
+  /** The default severity; `quality.severity` overrides it. */
+  readonly severity: QualitySeverity;
+  readonly description: string;
+}
+
+export interface QualityPluginContext {
+  /** The parsed file: frontmatter values, the app's `fields` and the Markdown body. */
+  readonly article: BlogArticleInput;
+  /** The body cut into blocks with file lines; fenced code is skipped, `::name{…}` directives are blocks of their own. */
+  readonly blocks: readonly Block[];
+  /** The fenced blocks of the app's block plugins (`quality.blocks`), with the file line of the opening fence. */
+  readonly pluginBlocks: readonly FoundBlock[];
+  /** `YYYY-MM-DD` in the app's time zone. */
+  readonly today: string;
+  /** The app's language ruleset, for its number notation. */
+  readonly ruleset: LanguageRuleset;
+}
+
+export interface QualityPlugin {
+  /** Names the plugin in a failure message. */
+  readonly name: string;
+  /** Every rule id the plugin may report. A finding with another id is refused as `plugin-rule-undeclared`. */
+  readonly rules: readonly QualityRuleInfo[];
+  /** Pure: no network, no file system. A throw becomes a `plugin-failed` error. */
+  readonly check: (context: QualityPluginContext) => readonly QualityFinding[];
+}
+
+export function isQualityPlugin(value: unknown): value is QualityPlugin {
+  if (typeof value !== "object" || value === null) return false;
+  const candidate = value as { name?: unknown; rules?: unknown; check?: unknown };
+  return typeof candidate.name === "string" && Array.isArray(candidate.rules) && typeof candidate.check === "function";
+}