@growth-labs/cms 0.1.0

package/src/engine/slug.ts

@@ -0,0 +1,33 @@
+// Slug helpers ported verbatim from fulcrum-labs/fronts src/lib/slug.ts
+// (inventory §1: `slug.ts` — extract, pure). No Fronts coupling.
+
+export function slugify(input: string): string {
+	return input
+		.toLowerCase()
+		.replace(/['"`]/g, '')
+		.replace(/[^a-z0-9]+/g, '-')
+		.replace(/^-+|-+$/g, '')
+		.replace(/--+/g, '-')
+		.trim()
+}
+
+export function normalizeSlug(input: string | null | undefined): string {
+	return slugify(input ?? '')
+}
+
+export function ensureTrailingSlash(pathname: string): string {
+	if (!pathname) return '/'
+	return pathname.endsWith('/') ? pathname : `${pathname}/`
+}
+
+export function stripTrailingSlash(pathname: string): string {
+	if (!pathname || pathname === '/') return '/'
+	return pathname.replace(/\/+$/, '')
+}
+
+export function buildContentPath(
+	type: 'article' | 'video' | 'podcast' | 'authors' | 'regions',
+	slug: string,
+): string {
+	return ensureTrailingSlash(`/${type}/${normalizeSlug(slug)}`)
+}

package/src/engine/soft-delete.ts

@@ -0,0 +1,42 @@
+import type { D1Database } from './d1.js'
+
+export async function softDeleteContent(
+	db: D1Database,
+	id: string,
+	now?: number,
+): Promise<boolean> {
+	const ts = now ?? Math.floor(Date.now() / 1000)
+	const res = await db
+		.prepare(
+			'UPDATE content_items SET deleted_at = ?, updated_at = unixepoch() WHERE id = ? AND deleted_at IS NULL',
+		)
+		.bind(ts, id)
+		.run()
+	return Boolean(res.meta && (res.meta as { changes?: number }).changes)
+}
+
+export async function restoreContent(db: D1Database, id: string): Promise<boolean> {
+	const res = await db
+		.prepare(
+			'UPDATE content_items SET deleted_at = NULL, updated_at = unixepoch() WHERE id = ? AND deleted_at IS NOT NULL',
+		)
+		.bind(id)
+		.run()
+	return Boolean(res.meta && (res.meta as { changes?: number }).changes)
+}
+
+/** Hard delete. content_* child tables cascade via the 0001 FKs. */
+export async function purgeContent(db: D1Database, id: string): Promise<boolean> {
+	const res = await db.prepare('DELETE FROM content_items WHERE id = ?').bind(id).run()
+	return Boolean(res.meta && (res.meta as { changes?: number }).changes)
+}
+
+/** Ids of non-trashed content (list/board exclude deleted_at IS NOT NULL). */
+export async function listActiveIds(db: D1Database): Promise<string[]> {
+	const result = await db
+		.prepare(
+			'SELECT id FROM content_items WHERE deleted_at IS NULL ORDER BY updated_at DESC, id DESC',
+		)
+		.all<{ id: string }>()
+	return (result.results || []).map((r) => r.id)
+}

package/src/engine/tags.ts

@@ -0,0 +1,95 @@
+// Tag CRUD engine — backs the Organize-tab tag management.
+// setContentTags / ensureTags (auto-create on assign) stay in publisher.ts;
+// this module adds management over content_tags + content_tag_links.
+
+import type { D1Database } from './d1.js'
+import { slugify } from './slug.js'
+
+export interface TagSummary {
+	id: string
+	slug: string
+	label: string
+	count: number
+}
+
+export async function getTag(db: D1Database, tagId: string): Promise<TagSummary | null> {
+	const row = await db
+		.prepare(
+			`SELECT t.id, t.slug, t.label, COUNT(l.content_id) AS count
+			 FROM content_tags t
+			 LEFT JOIN content_tag_links l ON l.tag_id = t.id
+			 WHERE t.id = ?
+			 GROUP BY t.id LIMIT 1`,
+		)
+		.bind(tagId)
+		.first<TagSummary>()
+	return row ?? null
+}
+
+export async function createTag(db: D1Database, label: string): Promise<TagSummary | null> {
+	const slug = slugify(label)
+	const trimmed = label.trim()
+	if (!slug || !trimmed) return null
+	const existing = await db
+		.prepare('SELECT id FROM content_tags WHERE slug = ? LIMIT 1')
+		.bind(slug)
+		.first<{ id: string }>()
+	if (existing) return null
+	const id = crypto.randomUUID()
+	await db
+		.prepare('INSERT INTO content_tags (id, slug, label) VALUES (?, ?, ?)')
+		.bind(id, slug, trimmed)
+		.run()
+	return { id, slug, label: trimmed, count: 0 }
+}
+
+export async function listTags(db: D1Database): Promise<TagSummary[]> {
+	const result = await db
+		.prepare(
+			`SELECT t.id, t.slug, t.label, COUNT(l.content_id) AS count
+			 FROM content_tags t
+			 LEFT JOIN content_tag_links l ON l.tag_id = t.id
+			 GROUP BY t.id ORDER BY count DESC, t.label ASC`,
+		)
+		.all<{ id: string; slug: string; label: string; count: number }>()
+	return result.results || []
+}
+
+export async function searchTags(db: D1Database, q: string): Promise<TagSummary[]> {
+	const needle = `${slugify(q)}%`
+	const result = await db
+		.prepare(
+			`SELECT t.id, t.slug, t.label, COUNT(l.content_id) AS count
+			 FROM content_tags t
+			 LEFT JOIN content_tag_links l ON l.tag_id = t.id
+			 WHERE t.slug LIKE ? GROUP BY t.id ORDER BY t.label ASC LIMIT 50`,
+		)
+		.bind(needle)
+		.all<{ id: string; slug: string; label: string; count: number }>()
+	return result.results || []
+}
+
+export async function renameTag(db: D1Database, tagId: string, label: string): Promise<boolean> {
+	const slug = slugify(label)
+	const trimmed = label.trim()
+	if (!slug || !trimmed) return false
+	// content_tags.slug is UNIQUE — a rename whose target slug is already taken by
+	// a DIFFERENT tag would throw a constraint error. Fail gracefully (the
+	// Promise<boolean> contract) instead, matching the empty-slug early return.
+	const clash = await db
+		.prepare('SELECT id FROM content_tags WHERE slug = ? AND id != ? LIMIT 1')
+		.bind(slug, tagId)
+		.first<{ id: string }>()
+	if (clash) return false
+	const res = await db
+		.prepare('UPDATE content_tags SET label = ?, slug = ? WHERE id = ?')
+		.bind(trimmed, slug, tagId)
+		.run()
+	return Boolean(res.meta && (res.meta as { changes?: number }).changes)
+}
+
+export async function deleteTag(db: D1Database, tagId: string): Promise<boolean> {
+	// content_tag_links has ON DELETE CASCADE on tag_id (0001), so links go too.
+	const res = await db.prepare('DELETE FROM content_tags WHERE id = ?').bind(tagId).run()
+	return Boolean(res.meta && (res.meta as { changes?: number }).changes)
+}

package/src/engine/topics.ts

@@ -0,0 +1,158 @@
+import type { D1Database } from './d1.js'
+import { slugify } from './slug.js'
+
+export interface TopicSummary {
+	slug: string
+	label: string
+	count: number
+}
+
+function isMissingTopicsTable(error: unknown): boolean {
+	return error instanceof Error && /no such table: cms_topics/i.test(error.message)
+}
+
+async function listStoredTopics(db: D1Database): Promise<Array<{ slug: string; label: string }>> {
+	try {
+		const result = await db
+			.prepare('SELECT slug, label FROM cms_topics ORDER BY label ASC')
+			.all<{ slug: string; label: string }>()
+		return result.results || []
+	} catch (error) {
+		if (isMissingTopicsTable(error)) return []
+		throw error
+	}
+}
+
+async function hasStoredTopicsTable(db: D1Database): Promise<boolean> {
+	try {
+		await db.prepare('SELECT 1 FROM cms_topics LIMIT 1').first()
+		return true
+	} catch (error) {
+		if (isMissingTopicsTable(error)) return false
+		throw error
+	}
+}
+
+export async function listTopics(db: D1Database): Promise<TopicSummary[]> {
+	const result = await db
+		.prepare(
+			`SELECT primary_topic AS slug, primary_topic AS label, COUNT(*) AS count
+			 FROM content_items
+			 WHERE deleted_at IS NULL
+				AND primary_topic IS NOT NULL
+				AND TRIM(primary_topic) != ''
+			 GROUP BY primary_topic
+			 ORDER BY count DESC, primary_topic ASC`,
+		)
+		.all<TopicSummary>()
+	const merged = new Map<string, TopicSummary>()
+	for (const row of result.results || []) {
+		merged.set(row.slug, { slug: row.slug, label: row.label, count: Number(row.count) || 0 })
+	}
+	for (const topic of await listStoredTopics(db)) {
+		const existing = merged.get(topic.slug)
+		merged.set(topic.slug, {
+			slug: topic.slug,
+			label: topic.label,
+			count: existing?.count ?? 0,
+		})
+	}
+	return Array.from(merged.values()).sort(
+		(a, b) => b.count - a.count || a.label.localeCompare(b.label),
+	)
+}
+
+export async function createTopic(db: D1Database, label: string): Promise<TopicSummary | null> {
+	const slug = slugify(label)
+	if (!slug) return null
+	if (!(await hasStoredTopicsTable(db))) return null
+
+	const assigned = await db
+		.prepare('SELECT 1 FROM content_items WHERE primary_topic = ? LIMIT 1')
+		.bind(slug)
+		.first()
+	if (assigned) return null
+
+	try {
+		await db
+			.prepare(
+				`INSERT INTO cms_topics (slug, label, created_at, updated_at)
+				 VALUES (?, ?, unixepoch(), unixepoch())`,
+			)
+			.bind(slug, label.trim())
+			.run()
+	} catch {
+		return null
+	}
+	return { slug, label: label.trim(), count: 0 }
+}
+
+export async function renameTopic(
+	db: D1Database,
+	currentSlug: string,
+	label: string,
+): Promise<TopicSummary | null> {
+	const nextSlug = slugify(label)
+	if (!currentSlug || !nextSlug) return null
+	const nextLabel = label.trim()
+	if (nextSlug !== currentSlug) {
+		const contentClash = await db
+			.prepare('SELECT 1 FROM content_items WHERE primary_topic = ? LIMIT 1')
+			.bind(nextSlug)
+			.first()
+		if (contentClash) return null
+		try {
+			const storedClash = await db
+				.prepare('SELECT 1 FROM cms_topics WHERE slug = ? AND slug != ? LIMIT 1')
+				.bind(nextSlug, currentSlug)
+				.first()
+			if (storedClash) return null
+		} catch (error) {
+			if (!isMissingTopicsTable(error)) throw error
+		}
+	}
+
+	let hadStoredTopic = false
+	const storedTopicsAvailable = await hasStoredTopicsTable(db)
+	if (storedTopicsAvailable) {
+		const stored = await db
+			.prepare('SELECT 1 FROM cms_topics WHERE slug = ? LIMIT 1')
+			.bind(currentSlug)
+			.first()
+		hadStoredTopic = Boolean(stored)
+		if (hadStoredTopic) {
+			await db
+				.prepare(
+					'UPDATE cms_topics SET slug = ?, label = ?, updated_at = unixepoch() WHERE slug = ?',
+				)
+				.bind(nextSlug, nextLabel, currentSlug)
+				.run()
+		}
+	}
+
+	const res = await db
+		.prepare(
+			`UPDATE content_items
+			 SET primary_topic = ?, updated_at = unixepoch()
+			 WHERE deleted_at IS NULL AND primary_topic = ?`,
+		)
+		.bind(nextSlug, currentSlug)
+		.run()
+	const changes = (res.meta as { changes?: number } | undefined)?.changes ?? 0
+	if (changes === 0 && !hadStoredTopic) return null
+	if (storedTopicsAvailable && !hadStoredTopic) {
+		await db
+			.prepare(
+				`INSERT OR REPLACE INTO cms_topics (slug, label, created_at, updated_at)
+				 VALUES (
+				   ?,
+				   ?,
+				   COALESCE((SELECT created_at FROM cms_topics WHERE slug = ?), unixepoch()),
+				   unixepoch()
+				 )`,
+			)
+			.bind(nextSlug, nextLabel, nextSlug)
+			.run()
+	}
+	return { slug: nextSlug, label: nextLabel, count: changes }
+}

package/src/engine/url-guard.ts

@@ -0,0 +1,136 @@
+// url-guard.ts — SSRF guard for outbound webhook URLs.
+//
+// The webhook `url` registered by a workspace is later fetched by
+// buildDefaultDispatchWebhook (POST with the signed envelope). Without
+// validation that is an arbitrary-outbound-POST / SSRF primitive — a member
+// could point a hook at an internal service, the cloud metadata endpoint, or a
+// loopback admin port and have the Worker make the request from inside the
+// trust boundary.
+//
+// This module is the single source of truth for "is this URL safe to register
+// and POST to". It is enforced in TWO places:
+//   1. the create/update route — reject with 400 so a bad URL never persists.
+//   2. fire time (buildDefaultDispatchWebhook) — defense in depth, in case a
+//      row predates the guard or was written out-of-band.
+//
+// Policy: require `https:`, reject credentials-in-URL, reject hosts that resolve
+// to (or are written as) loopback / link-local / cloud-metadata / RFC-1918
+// private space, and reject internal-only hostname suffixes (`.internal`,
+// `.local`) plus bare single-label hostnames (intranet-style).
+//
+// NOTE: this is a host-literal + name-suffix check, not a DNS resolution check.
+// workerd has no synchronous DNS and the fetch egress is the real boundary; this
+// blocks the obvious literal-IP and well-known-name SSRF classes. DNS-rebinding
+// to a private IP is out of scope for a package-level guard (it requires a
+// pinned-IP fetch the host owns).
+
+export interface UrlGuardResult {
+	ok: boolean
+	reason?: string
+}
+
+function fail(reason: string): UrlGuardResult {
+	return { ok: false, reason }
+}
+
+/** Internal-only hostname suffixes that must never receive a webhook POST. */
+const BLOCKED_HOST_SUFFIXES = ['.internal', '.local']
+
+/** Decimal-octet test for an IPv4 literal. */
+function parseIpv4(host: string): [number, number, number, number] | null {
+	const parts = host.split('.')
+	if (parts.length !== 4) return null
+	const octets: number[] = []
+	for (const part of parts) {
+		if (!/^\d{1,3}$/.test(part)) return null
+		const n = Number(part)
+		if (n > 255) return null
+		octets.push(n)
+	}
+	return octets as [number, number, number, number]
+}
+
+/** True if the IPv4 literal is in a loopback / link-local / private / unspecified range. */
+function isBlockedIpv4(octets: [number, number, number, number]): boolean {
+	const [a, b] = octets
+	// 0.0.0.0/8 — "this host" / unspecified.
+	if (a === 0) return true
+	// 127.0.0.0/8 — loopback.
+	if (a === 127) return true
+	// 10.0.0.0/8 — private.
+	if (a === 10) return true
+	// 172.16.0.0/12 — private (172.16 – 172.31).
+	if (a === 172 && b >= 16 && b <= 31) return true
+	// 192.168.0.0/16 — private.
+	if (a === 192 && b === 168) return true
+	// 169.254.0.0/16 — link-local (incl. 169.254.169.254 cloud metadata).
+	if (a === 169 && b === 254) return true
+	return false
+}
+
+/**
+ * Validate a webhook URL against the SSRF policy.
+ *
+ * Returns `{ ok: true }` only for a public `https:` URL with no credentials
+ * whose host is not a loopback/link-local/private/internal target.
+ */
+export function validateWebhookUrl(raw: string): UrlGuardResult {
+	if (!raw || typeof raw !== 'string') return fail('url is required')
+
+	let url: URL
+	try {
+		url = new URL(raw)
+	} catch {
+		return fail('url is not a valid absolute URL')
+	}
+
+	// 1. Scheme — https only (rejects http, file, gopher, ftp, data, ...).
+	if (url.protocol !== 'https:') {
+		return fail('url must use the https scheme')
+	}
+
+	// 2. No credentials in the URL (user:pass@host).
+	if (url.username || url.password) {
+		return fail('url must not contain credentials')
+	}
+
+	// Normalize the host: strip IPv6 brackets, lowercase, drop a trailing dot.
+	let host = url.hostname.toLowerCase()
+	if (host.endsWith('.')) host = host.slice(0, -1)
+
+	if (!host) return fail('url host is empty')
+
+	// 3. IPv6 loopback / unspecified (URL.hostname strips the brackets).
+	if (host === '::1' || host === '::' || host === '0:0:0:0:0:0:0:1') {
+		return fail('url host is a loopback address')
+	}
+
+	// 4. localhost (by name).
+	if (host === 'localhost' || host.endsWith('.localhost')) {
+		return fail('url host is localhost')
+	}
+
+	// 5. IPv4 literal in a blocked range.
+	const ipv4 = parseIpv4(host)
+	if (ipv4) {
+		if (isBlockedIpv4(ipv4)) {
+			return fail('url host is a private, loopback, or link-local address')
+		}
+		// A public IPv4 literal is allowed.
+		return { ok: true }
+	}
+
+	// 6. Internal-only name suffixes (.internal, .local).
+	for (const suffix of BLOCKED_HOST_SUFFIXES) {
+		if (host.endsWith(suffix)) {
+			return fail(`url host suffix '${suffix}' is internal-only`)
+		}
+	}
+
+	// 7. Bare single-label hostname (no dot) — intranet-style, not public DNS.
+	if (!host.includes('.')) {
+		return fail('url host must be a fully-qualified public hostname')
+	}
+
+	return { ok: true }
+}

package/src/engine/validator/checks/bare-url-not-autolinked.ts

@@ -0,0 +1,78 @@
+import { buildProtectedMask, isProtectedSpan } from '../scan.js'
+/**
+ * `bare-url-not-autolinked`
+ *
+ * Detect bare `https://…` URLs in prose that aren't wrapped in a
+ * markdown link, autolink, fenced code, inline code, or HTML
+ * attribute. The renderer auto-links them in newer markdown variants,
+ * but Fronts' renderer doesn't — so bare URLs ship as plain text.
+ *
+ * AST-aware via the shared {@link buildProtectedMask} helper so we
+ * don't flag URLs that live inside the protected regions.
+ */
+import type { ArticleBodyInput, ValidationError } from '../types.js'
+import { makeError } from '../types.js'
+
+// Greedy URL match — everything that isn't whitespace or a clearly
+// terminal character. Trailing punctuation is trimmed in a second pass.
+const BARE_URL_RE = /\bhttps?:\/\/[^\s<>"'`)\]]+/g
+
+const TRAILING_PUNCT_RE = /[.,;:!?]+$/
+
+interface UrlMatch {
+	start: number
+	end: number
+	url: string
+}
+
+function findBareUrls(value: string): UrlMatch[] {
+	const out: UrlMatch[] = []
+	for (const match of value.matchAll(BARE_URL_RE)) {
+		const start = match.index ?? 0
+		let url = match[0]
+		// Trim trailing punctuation that isn't part of the URL — `.com).` etc.
+		const trimMatch = TRAILING_PUNCT_RE.exec(url)
+		if (trimMatch) {
+			url = url.slice(0, trimMatch.index)
+		}
+		out.push({ start, end: start + url.length, url })
+	}
+	return out
+}
+
+export function check(input: ArticleBodyInput): ValidationError[] {
+	if (!input.body_markdown) return []
+	const source = input.body_markdown
+	const mask = buildProtectedMask(source)
+
+	for (const m of findBareUrls(source)) {
+		if (isProtectedSpan(mask, m.start, m.end)) continue
+		return [
+			makeError(
+				'bare-url-not-autolinked',
+				`Bare URL '${m.url}' is not wrapped in a markdown link. Wrap as '[label](${m.url})' or '<${m.url}>'.`,
+				{ start: m.start, end: m.end },
+			),
+		]
+	}
+	return []
+}
+
+/**
+ * Pure repair: wrap bare URLs in `<url>` autolinks. Only used when the
+ * operator opts in (some bodies intentionally print URLs as text in
+ * citation footnotes — the wrap changes how they render).
+ */
+export function repair(value: string): string {
+	const mask = buildProtectedMask(value)
+	let out = ''
+	let cursor = 0
+	for (const m of findBareUrls(value)) {
+		if (isProtectedSpan(mask, m.start, m.end)) continue
+		out += value.slice(cursor, m.start)
+		out += `<${m.url}>`
+		cursor = m.end
+	}
+	out += value.slice(cursor)
+	return out
+}

package/src/engine/validator/checks/broken-footnote-label.ts

@@ -0,0 +1,33 @@
+/**
+ * `broken-footnote-label`
+ *
+ * After Phase 1's `stripOverEscapes()` pass, legacy imports leave
+ * footnote labels as literal `[[1]](#_ftnref1)` — a double-bracketed
+ * link whose label is also bracketed. The markdown parser sees an
+ * empty alt-text "image" or simply leaks the literal brackets.
+ *
+ * Repair: collapse `[[N]](#anchor)` → `[N](#anchor)` so the label
+ * renders as the numeric footnote marker `[1]`, styled as a real link.
+ */
+import type { ArticleBodyInput, ValidationError } from '../types.js'
+import { makeError } from '../types.js'
+
+const PATTERN = /\[\[(\d+)\]\]\((#[^)\s]+)\)/
+
+export function check(input: ArticleBodyInput): ValidationError[] {
+	if (!input.body_markdown) return []
+	const match = PATTERN.exec(input.body_markdown)
+	if (!match) return []
+	return [
+		makeError(
+			'broken-footnote-label',
+			`body_markdown contains a broken footnote label '${match[0]}' — collapse '[[N]](#…)' to '[N](#…)' so the link renders correctly.`,
+			{ start: match.index, end: match.index + match[0].length },
+		),
+	]
+}
+
+/** Pure repair: collapse `[[N]](#anchor)` → `[N](#anchor)`. */
+export function repair(value: string): string {
+	return value.replace(/\[\[(\d+)\]\]\((#[^)\s]+)\)/g, '[$1]($2)')
+}

package/src/engine/validator/checks/double-encoded-entities.ts

@@ -0,0 +1,46 @@
+/**
+ * `double-encoded-entities`
+ *
+ * Detect `"` `'` `&` `’` — the
+ * result of HTML-encoding an already-encoded string. The renderer
+ * decodes one level, so the reader sees `"` `'` etc. in the
+ * prose.
+ *
+ * Repair: decode one level (`"` → `"`) so the next
+ * render pass produces the correct character. We do NOT decode all the
+ * way to a raw character — that would change semantics inside HTML
+ * attributes where the encoded form is still required.
+ */
+import type { ArticleBodyInput, ValidationError } from '../types.js'
+import { makeError } from '../types.js'
+
+// Cover named entities and both decimal and hex numeric references.
+const PATTERN = /&(quot|amp|lt|gt|apos|nbsp|#\d+|#x[0-9a-fA-F]+);/i
+
+const PATTERN_GLOBAL = /&(quot|amp|lt|gt|apos|nbsp|#\d+|#x[0-9a-fA-F]+);/gi
+
+export function check(input: ArticleBodyInput): ValidationError[] {
+	const errors: ValidationError[] = []
+
+	const checkField = (value: string | null, fieldName: string) => {
+		if (!value) return
+		const match = PATTERN.exec(value)
+		if (!match) return
+		errors.push(
+			makeError(
+				'double-encoded-entities',
+				`${fieldName} contains a double-encoded entity '${match[0]}'. Decode one level so it renders as the intended character.`,
+				{ start: match.index, end: match.index + match[0].length },
+			),
+		)
+	}
+
+	checkField(input.body_markdown, 'body_markdown')
+	checkField(input.body_html, 'body_html')
+	return errors
+}
+
+/** Pure repair: decode the `&` prefix one level. */
+export function repair(value: string): string {
+	return value.replace(PATTERN_GLOBAL, (_match, inner: string) => `&${inner};`)
+}

package/src/engine/validator/checks/empty-alt-text.ts

@@ -0,0 +1,35 @@
+/**
+ * `empty-alt-text`
+ *
+ * Detect markdown images stored with empty alt text: `![](https://…)`.
+ * This is an accessibility regression — screen readers announce the
+ * filename or "image" — and it usually means the import dropped the
+ * caption rather than the editor making a deliberate decorative
+ * choice. Flag-only; auto-fix would require fabricating alt text.
+ */
+import type { ArticleBodyInput, ValidationError } from '../types.js'
+import { makeError } from '../types.js'
+
+const PATTERN = /!\[\]\((https?:\/\/[^)\s]+)\)/
+const PATTERN_GLOBAL = /!\[\]\((https?:\/\/[^)\s]+)\)/g
+
+export function check(input: ArticleBodyInput): ValidationError[] {
+	if (!input.body_markdown) return []
+	const match = PATTERN.exec(input.body_markdown)
+	if (!match) return []
+	return [
+		makeError(
+			'empty-alt-text',
+			`Image '${match[1]}' has empty alt text. Add descriptive alt, or wrap as a decorative image deliberately.`,
+			{ start: match.index, end: match.index + match[0].length },
+		),
+	]
+}
+
+/** Count occurrences — used by sweep reporting. */
+export function count(value: string | null): number {
+	if (!value) return 0
+	let n = 0
+	for (const _ of value.matchAll(PATTERN_GLOBAL)) n += 1
+	return n
+}

package/src/engine/validator/checks/heading-hierarchy-skip.ts

@@ -0,0 +1,33 @@
+/**
+ * `heading-hierarchy-skip`
+ *
+ * Detect headings that skip levels — e.g. an `<h1>` followed directly
+ * by an `<h3>` with no `<h2>` between them. This breaks the TOC tree
+ * and screen-reader navigation. Skip auto-fix — promoting an `h3` to
+ * `h2` is semantic, not mechanical.
+ */
+import type { ArticleBodyInput, ValidationError } from '../types.js'
+import { makeError } from '../types.js'
+
+const HEADING_RE = /^(#{1,6})\s+\S/gm
+
+export function check(input: ArticleBodyInput): ValidationError[] {
+	if (!input.body_markdown) return []
+	const source = input.body_markdown
+	let lastLevel = 0
+	for (const match of source.matchAll(HEADING_RE)) {
+		const level = (match[1] ?? '').length
+		if (lastLevel > 0 && level > lastLevel + 1) {
+			const start = match.index ?? 0
+			return [
+				makeError(
+					'heading-hierarchy-skip',
+					`Heading '${match[0].trim()}' skips from h${lastLevel} to h${level}. Insert intermediate level(s) to keep the TOC tree intact.`,
+					{ start, end: start + match[0].length },
+				),
+			]
+		}
+		lastLevel = level
+	}
+	return []
+}