@growth-labs/cms 0.1.0

package/src/engine/validator/checks/html-comment-leak.ts

@@ -0,0 +1,58 @@
+/**
+ * `html-comment-leak`
+ *
+ * Detect raw HTML comments stored in the body. The renderer happily
+ * passes them through, so anything that leaks into the prose either:
+ *  - reveals editor intent ("<!-- TK: needs fact-check -->")
+ *  - is dead markup from a paste (Word `<!--StartFragment-->`)
+ *  - is a marker the system was supposed to consume already
+ *
+ * Whitelist (confirmed via grep on origin/main on 2026-05-21):
+ *   <!-- generated-faq -->
+ *   <!-- /generated-faq -->
+ *
+ * Anything else is treated as a leak.
+ */
+import type { ArticleBodyInput, ValidationError } from '../types.js'
+import { makeError } from '../types.js'
+
+const COMMENT_RE = /<!--([\s\S]*?)-->/g
+
+const WHITELIST: ReadonlyArray<string> = ['generated-faq', '/generated-faq']
+
+function isWhitelisted(body: string): boolean {
+	const trimmed = body.trim()
+	return WHITELIST.includes(trimmed)
+}
+
+export function check(input: ArticleBodyInput): ValidationError[] {
+	const errors: ValidationError[] = []
+
+	const checkField = (value: string | null, fieldName: string) => {
+		if (!value) return
+		for (const match of value.matchAll(COMMENT_RE)) {
+			const body = match[1] ?? ''
+			if (isWhitelisted(body)) continue
+			const start = match.index ?? 0
+			errors.push(
+				makeError(
+					'html-comment-leak',
+					`${fieldName} contains a non-whitelisted HTML comment '${match[0].slice(0, 60)}${match[0].length > 60 ? '…' : ''}'.`,
+					{ start, end: start + match[0].length },
+				),
+			)
+			break // one per field is enough for the surface alert
+		}
+	}
+
+	checkField(input.body_markdown, 'body_markdown')
+	checkField(input.body_html, 'body_html')
+	return errors
+}
+
+/** Strip non-whitelisted HTML comments from the body. */
+export function repair(value: string): string {
+	return value.replace(/<!--([\s\S]*?)-->/g, (match, body: string) =>
+		isWhitelisted(body) ? match : '',
+	)
+}

package/src/engine/validator/checks/iframe-missing-dims-and-wrapper.ts

@@ -0,0 +1,34 @@
+/**
+ * `iframe-missing-dims-and-wrapper`
+ *
+ * Detect `<iframe>` tags stored without width/height attributes. The
+ * Fronts prose stylesheet uses an aspect-ratio wrapper (see
+ * `src/styles/theme-bridge.css` `.fronts-prose iframe`) that handles
+ * the layout when the iframe sits inside that container, so this is
+ * informational unless the iframe is bare.
+ */
+import type { ArticleBodyInput, ValidationError } from '../types.js'
+import { makeError } from '../types.js'
+
+const IFRAME_RE = /<iframe(?![^>]*\s(?:width|height)=)[^>]*>/i
+
+export function check(input: ArticleBodyInput): ValidationError[] {
+	const errors: ValidationError[] = []
+
+	const checkField = (value: string | null, fieldName: string) => {
+		if (!value) return
+		const match = IFRAME_RE.exec(value)
+		if (!match) return
+		errors.push(
+			makeError(
+				'iframe-missing-dims-and-wrapper',
+				`${fieldName} contains an <iframe> with no width/height. Either add explicit dims or ensure it renders inside .fronts-prose for the aspect-ratio wrapper.`,
+				{ start: match.index, end: match.index + match[0].length },
+			),
+		)
+	}
+
+	checkField(input.body_markdown, 'body_markdown')
+	checkField(input.body_html, 'body_html')
+	return errors
+}

package/src/engine/validator/checks/invisible-control-chars.ts

@@ -0,0 +1,58 @@
+/**
+ * `invisible-control-chars`
+ *
+ * Detect zero-width and bidi control characters that paste from Word,
+ * Google Docs, or rich-text RTF often introduces. These don't render
+ * but they break selection, search, and TOC ID derivation downstream.
+ *
+ * Explicit list (Codex revision — do NOT include U+00A0 NBSP which is
+ * a legitimate non-breaking space):
+ *   U+200B  ZERO WIDTH SPACE
+ *   U+200C  ZERO WIDTH NON-JOINER
+ *   U+200D  ZERO WIDTH JOINER
+ *   U+200E  LEFT-TO-RIGHT MARK
+ *   U+200F  RIGHT-TO-LEFT MARK
+ *   U+2060  WORD JOINER
+ *   U+00AD  SOFT HYPHEN
+ *   U+FEFF  ZERO WIDTH NO-BREAK SPACE (BOM)
+ */
+import type { ArticleBodyInput, ValidationError } from '../types.js'
+import { makeError } from '../types.js'
+
+const INVISIBLE_CHARS = '​‌‍‎‏⁠­'
+// Explicit alternation rather than a character class — biome's
+// `noMisleadingCharacterClass` rule flags joined-emoji classes, and
+// these zero-width / bidi chars can compose into one emoji-like
+// sequence in some Unicode contexts. The alternation behaves the
+// same for our purposes.
+const PATTERN = /​|‌|‍|‎|‏|⁠|­|/g
+
+export function check(input: ArticleBodyInput): ValidationError[] {
+	const errors: ValidationError[] = []
+
+	const checkField = (value: string | null, fieldName: string) => {
+		if (!value) return
+		const match = PATTERN.exec(value)
+		PATTERN.lastIndex = 0
+		if (!match) return
+		const codepoint = match[0].charCodeAt(0).toString(16).toUpperCase().padStart(4, '0')
+		errors.push(
+			makeError(
+				'invisible-control-chars',
+				`${fieldName} contains an invisible control character at offset ${match.index} (U+${codepoint}). Strip before publishing — breaks selection and TOC anchors.`,
+				{ start: match.index, end: match.index + 1 },
+			),
+		)
+	}
+
+	checkField(input.body_markdown, 'body_markdown')
+	checkField(input.body_html, 'body_html')
+	return errors
+}
+
+/** Pure repair: strip every char in {@link INVISIBLE_CHARS}. */
+export function repair(value: string): string {
+	return value.replace(/​|‌|‍|‎|‏|⁠|­|/g, '')
+}
+
+export const INVISIBLE_CONTROL_CHARS = INVISIBLE_CHARS

package/src/engine/validator/checks/paywall-marker-leak.ts

@@ -0,0 +1,43 @@
+/**
+ * `paywall-marker-leak`
+ *
+ * Detect `<!-- paywall -->` / `<!-- paywall-cut -->` style markers
+ * that should have been consumed by an upstream splitter. If they
+ * reach the renderer they appear as visible HTML comments (or, worse,
+ * surface in the FAQ generator's input as junk anchors).
+ *
+ * Block-severity: leaked markers indicate a broken splitter and
+ * usually mean the article is also missing its premium content
+ * boundary.
+ */
+import type { ArticleBodyInput, ValidationError } from '../types.js'
+import { makeError } from '../types.js'
+
+const PATTERN = /<!--\s*paywall(?:-cut)?\s*-->/i
+const PATTERN_GLOBAL = /<!--\s*paywall(?:-cut)?\s*-->/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(
+				'paywall-marker-leak',
+				`${fieldName} contains a raw paywall marker '${match[0]}'. The splitter should consume this — investigate why it leaked through.`,
+				{ 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: drop the leaked marker entirely. */
+export function repair(value: string): string {
+	return value.replace(PATTERN_GLOBAL, '')
+}

package/src/engine/validator/checks/raw-block-html.ts

@@ -0,0 +1,65 @@
+/**
+ * `raw-block-html`
+ *
+ * Detect raw block-level HTML at the start of a line in markdown. The
+ * renderer treats raw HTML as opaque — `<p>` / `<div>` / `<span>` tags
+ * bypass the prose pipeline entirely (no paragraph wrapping, no inline
+ * link parsing). That has caused articles to render as one giant text
+ * blob with no formatting.
+ *
+ * Whitelisted (safe / intentional):
+ *   <details>, <summary>, <figure>, <iframe>, <img>
+ *
+ * Blocked (always a paste residue): `<p>`, `<div>`, `<span>` at the
+ * start of a line. Other raw tags get a `warn`.
+ *
+ * Note: inline `<i>` / `<b>` / `<em>` / `<strong>` are left alone — the
+ * markdown parser does handle them inside a paragraph.
+ */
+import type { ArticleBodyInput, ValidationError } from '../types.js'
+import { makeError } from '../types.js'
+
+const BLOCK_RE = /^<(br|p|div|span)(\s|>|\/)/gim
+
+// Fence detection so we don't flag block HTML inside ```html ... ```.
+const FENCE_RE = /^```/gm
+
+function inFenced(source: string, offset: number): boolean {
+	let count = 0
+	for (const m of source.matchAll(FENCE_RE)) {
+		if ((m.index ?? 0) >= offset) break
+		count += 1
+	}
+	return count % 2 === 1
+}
+
+export function check(input: ArticleBodyInput): ValidationError[] {
+	if (!input.body_markdown) return []
+	const source = input.body_markdown
+	const errors: ValidationError[] = []
+
+	for (const match of source.matchAll(BLOCK_RE)) {
+		const offset = match.index ?? 0
+		if (inFenced(source, offset)) continue
+		const tag = (match[1] ?? '').toLowerCase()
+		errors.push(
+			makeError(
+				'raw-block-html',
+				`body_markdown contains a raw block <${tag}> at the start of a line. The markdown parser will treat it as opaque and skip paragraph formatting around it.`,
+				{ start: offset, end: offset + match[0].length },
+			),
+		)
+		break
+	}
+	return errors
+}
+
+/**
+ * Pure repair: convert `<br>` / `<br/>` to a blank line so the
+ * paragraph break is preserved. Other tags (`<p>` / `<div>` / `<span>`)
+ * are left to the operator — silently unwrapping them can lose nesting
+ * intent.
+ */
+export function repair(value: string): string {
+	return value.replace(/^<br\s*\/?>\s*$/gim, '')
+}

package/src/engine/validator/checks/stale-body-html.ts

@@ -0,0 +1,39 @@
+/**
+ * `stale-body-html`
+ *
+ * Repair-pipeline-only check. The article renderer prefers
+ * `body_html` over `body_markdown` when both are present (see
+ * `content.ts:213` / `article/[slug].astro:245`). So whenever L3
+ * rewrites `body_markdown`, the stored `body_html` is now stale —
+ * subsequent renders will keep using the old HTML and the repair is
+ * invisible. The repair pipeline must null `body_html` whenever it
+ * changes `body_markdown`.
+ *
+ * This module surfaces the check code so the repair script can log
+ * "stale-body-html-resolved: N" in its summary. The detector here
+ * compares before/after markdown — if the markdown changed and the
+ * row also had a non-empty `body_html`, the staleness must be cleared.
+ */
+import type { ValidationError } from '../types.js'
+import { makeError } from '../types.js'
+
+export interface StaleHtmlContext {
+	originalMarkdown: string
+	repairedMarkdown: string
+	bodyHtml: string | null
+}
+
+/**
+ * Returns a single error iff the markdown changed during repair AND
+ * the row has a non-null body_html that would shadow the fix.
+ */
+export function check(ctx: StaleHtmlContext): ValidationError[] {
+	if (!ctx.bodyHtml?.trim()) return []
+	if (ctx.originalMarkdown === ctx.repairedMarkdown) return []
+	return [
+		makeError(
+			'stale-body-html',
+			'body_markdown was rewritten by repair but body_html still holds the old HTML; null body_html so the renderer re-derives from the cleaned markdown.',
+		),
+	]
+}

package/src/engine/validator/checks/unresolved-footnote-anchor.ts

@@ -0,0 +1,61 @@
+/**
+ * `unresolved-footnote-anchor`
+ *
+ * Detect footnote markers `[…](#anchor)` whose target anchor isn't
+ * defined elsewhere in the body. The renderer happily emits a broken
+ * link; the reader sees a footnote that goes nowhere. Flag-only —
+ * auto-stubbing creates fake citations, so we surface to the editor.
+ */
+import type { ArticleBodyInput, ValidationError } from '../types.js'
+import { makeError } from '../types.js'
+
+const LINK_RE = /\[[^\]]+\]\((#[^)\s]+)\)/g
+// Anchors defined inline either as `<a name="x">`, `<a id="x">`, or as
+// markdown reference-style anchors (rare but exist).
+const ANCHOR_DEFINE_RE = /<a\s[^>]*(?:name|id)\s*=\s*["']([^"']+)["']/gi
+const HEADING_RE = /^(#{1,6})\s+(.+)$/gm
+
+function slugify(text: string): string {
+	return text
+		.toLowerCase()
+		.replace(/[^\w\s-]/g, '')
+		.trim()
+		.replace(/\s+/g, '-')
+}
+
+export function check(input: ArticleBodyInput): ValidationError[] {
+	if (!input.body_markdown) return []
+	const source = input.body_markdown
+
+	// Build the set of anchors that DO exist in this document.
+	const defined = new Set<string>()
+	for (const m of source.matchAll(ANCHOR_DEFINE_RE)) {
+		if (m[1]) defined.add(m[1])
+	}
+	for (const m of source.matchAll(HEADING_RE)) {
+		if (m[2]) defined.add(slugify(m[2]))
+	}
+
+	const errors: ValidationError[] = []
+	for (const match of source.matchAll(LINK_RE)) {
+		const anchorWithHash = match[1] ?? ''
+		const anchor = anchorWithHash.slice(1) // drop leading #
+		if (!anchor) continue
+		if (defined.has(anchor)) continue
+		// Skip generic "back-to-top" hrefs that point at literal '#'
+		// (the LINK_RE already excluded them but be defensive).
+		if (anchor === '' || anchor === 'top') continue
+		const start = match.index ?? 0
+		errors.push(
+			makeError(
+				'unresolved-footnote-anchor',
+				`Footnote/anchor link '${match[0]}' points to '#${anchor}' which is not defined in the body.`,
+				{ start, end: start + match[0].length },
+			),
+		)
+		// Only surface the first occurrence per body — operators read
+		// the list once; the rest will be cleaned in the same pass.
+		break
+	}
+	return errors
+}

package/src/engine/validator/checks/word-gdocs-paste-artifacts.ts

@@ -0,0 +1,72 @@
+/**
+ * `word-gdocs-paste-artifacts`
+ *
+ * Detect Microsoft Word / Google Docs paste residue that the import
+ * pipeline failed to strip. These markers either render as visible junk
+ * (the comment markers) or burn unused class attributes into the DOM
+ * (Mso* class names, mso-* style properties).
+ *
+ * Block-severity: when these appear, the body is not safe to publish
+ * raw — they have triggered measurable layout regressions in the past
+ * (the `Mso*` classes inherit Word's default font stack, which leaks
+ * Times New Roman into the prose font).
+ */
+import type { ArticleBodyInput, ValidationError } from '../types.js'
+import { makeError } from '../types.js'
+
+const PATTERN =
+	/\sclass\s*=\s*"?Mso\w+|<!--\s*Start(?:Fragment|HTML|Selection)\s*-->|mso-(?:margin|para|list|ascii|fareast|hansi|bidi)-/i
+
+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(
+				'word-gdocs-paste-artifacts',
+				`${fieldName} contains Word/Google Docs paste residue (matched '${match[0]}'). Strip Mso* classes and mso-* styles before publishing.`,
+				{ 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: drop Mso* class attributes, Start* fragment comments,
+ * and mso-* CSS rules. The repair is conservative — we keep the
+ * surrounding element and strip the offending attribute / declaration
+ * rather than removing the whole node.
+ */
+export function repair(value: string): string {
+	return (
+		value
+			// Drop class attributes that contain Mso* tokens.
+			.replace(/\sclass\s*=\s*"([^"]*)"/gi, (_match, classes: string) => {
+				const filtered = classes
+					.split(/\s+/)
+					.filter((token) => !/^Mso\w+/i.test(token))
+					.join(' ')
+					.trim()
+				return filtered ? ` class="${filtered}"` : ''
+			})
+			.replace(/\sclass\s*=\s*'([^']*)'/gi, (_match, classes: string) => {
+				const filtered = classes
+					.split(/\s+/)
+					.filter((token) => !/^Mso\w+/i.test(token))
+					.join(' ')
+					.trim()
+				return filtered ? ` class='${filtered}'` : ''
+			})
+			// Drop Start*/End* fragment markers entirely.
+			.replace(/<!--\s*(?:Start|End)(?:Fragment|HTML|Selection)\s*-->/gi, '')
+			// Drop mso-* CSS declarations.
+			.replace(/mso-(?:margin|para|list|ascii|fareast|hansi|bidi)-[^;"'>]*;?/gi, '')
+	)
+}