@growth-labs/seo 0.4.0 → 0.4.2

package/src/utils/validation.ts

@@ -0,0 +1,308 @@
+export interface ValidationResult {
+	errors: string[]
+	warnings: string[]
+}
+
+export interface PageValidationOptions {
+	titleMaxLength: number
+	descriptionMaxLength: number
+	heroMinWidth?: number
+}
+
+/**
+ * Validate a JSON-LD object for common SEO issues.
+ */
+export function validateJsonLd(jsonLd: Record<string, unknown>): ValidationResult {
+	const errors: string[] = []
+	const warnings: string[] = []
+
+	// Must have @context
+	if (!jsonLd['@context']) {
+		errors.push('JSON-LD missing @context')
+	}
+
+	// Must have @type
+	const type = jsonLd['@type']
+	if (!type) {
+		errors.push('JSON-LD missing @type')
+	}
+
+	const typeStr = Array.isArray(type) ? type[0] : String(type ?? '')
+
+	// Article checks
+	if (typeStr === 'Article' || typeStr === 'NewsArticle' || typeStr === 'BlogPosting') {
+		if (!jsonLd.image) {
+			warnings.push(`${typeStr} JSON-LD missing recommended "image" property`)
+		}
+		if (!jsonLd.author) {
+			warnings.push(`${typeStr} JSON-LD missing recommended "author" property`)
+		}
+		const headline = jsonLd.headline
+		if (headline && typeof headline === 'string' && headline.length > 110) {
+			warnings.push(`${typeStr} JSON-LD "headline" exceeds 110 characters (${headline.length})`)
+		}
+	}
+
+	// Product checks
+	if (typeStr === 'Product') {
+		const offers = jsonLd.offers
+		if (!offers) {
+			warnings.push('Product JSON-LD missing recommended "offers" property')
+		} else {
+			const offersObj = Array.isArray(offers) ? offers[0] : offers
+			if (offersObj && typeof offersObj === 'object') {
+				const o = offersObj as Record<string, unknown>
+				if (!o.price && o.price !== 0) {
+					warnings.push('Product JSON-LD offers missing "price"')
+				}
+				if (!o.availability) {
+					warnings.push('Product JSON-LD offers missing "availability"')
+				}
+			}
+		}
+	}
+
+	// BreadcrumbList position ordering
+	if (typeStr === 'BreadcrumbList') {
+		const itemListElement = jsonLd.itemListElement
+		if (Array.isArray(itemListElement)) {
+			let lastPosition = 0
+			for (let i = 0; i < itemListElement.length; i++) {
+				const item = itemListElement[i] as Record<string, unknown>
+				const position = Number(item.position)
+				if (position <= lastPosition) {
+					errors.push(
+						`BreadcrumbList itemListElement[${i}] position ${position} is not in ascending order`,
+					)
+				}
+				lastPosition = position
+			}
+		}
+	}
+
+	return { errors, warnings }
+}
+
+/**
+ * Validate an HTML string for common on-page SEO issues.
+ */
+export function validatePage(html: string, options: PageValidationOptions): ValidationResult {
+	const errors: string[] = []
+	const warnings: string[] = []
+
+	if (isNoindexMetaRefreshRedirect(html)) {
+		return { errors, warnings }
+	}
+
+	const { titleMaxLength, descriptionMaxLength } = options
+
+	// Title checks
+	const titleMatch = html.match(/<title[^>]*>([\s\S]*?)<\/title>/i)
+	if (!titleMatch) {
+		errors.push('Missing <title> tag')
+	} else {
+		const title = titleMatch[1].trim()
+		if (title.length > titleMaxLength) {
+			warnings.push(`<title> exceeds ${titleMaxLength} characters (${title.length})`)
+		}
+	}
+
+	// Meta description checks
+	const descMatch =
+		html.match(/<meta\s[^>]*name=["']description["'][^>]*>/i) ??
+		html.match(/<meta\s[^>]*name=description[^>]*>/i)
+	if (!descMatch) {
+		warnings.push('Missing meta description')
+	} else {
+		const contentMatch =
+			descMatch[0].match(/content=["']([^"']*)["']/i) ?? descMatch[0].match(/content=([^\s>]+)/i)
+		if (contentMatch) {
+			const desc = contentMatch[1].trim()
+			if (desc.length > descriptionMaxLength) {
+				warnings.push(
+					`Meta description exceeds ${descriptionMaxLength} characters (${desc.length})`,
+				)
+			}
+		}
+	}
+
+	// Canonical check
+	const canonicalMatch =
+		html.match(/<link\s[^>]*rel=["']canonical["'][^>]*>/i) ??
+		html.match(/<link\s[^>]*rel=canonical[^>]*>/i)
+	if (!canonicalMatch) {
+		warnings.push('Missing canonical link')
+	}
+
+	// og:image check
+	const ogImageMatch =
+		html.match(/<meta\s[^>]*property=["']og:image["'][^>]*>/i) ??
+		html.match(/<meta\s[^>]*property=og:image[^>]*>/i)
+	if (!ogImageMatch) {
+		warnings.push('Missing og:image meta tag')
+	}
+
+	// og:image:width check against heroMinWidth
+	if (options.heroMinWidth) {
+		const ogWidthMatch =
+			html.match(/<meta\s[^>]*property=["']og:image:width["'][^>]*>/i) ??
+			html.match(/<meta\s[^>]*property=og:image:width[^>]*>/i)
+		if (ogWidthMatch) {
+			const widthContentMatch =
+				ogWidthMatch[0].match(/content=["']([^"']*)["']/i) ??
+				ogWidthMatch[0].match(/content=([^\s>]+)/i)
+			if (widthContentMatch) {
+				const width = Number(widthContentMatch[1])
+				if (!Number.isNaN(width) && width < options.heroMinWidth) {
+					warnings.push(`Hero image width ${width}px is below minimum ${options.heroMinWidth}px`)
+				}
+			}
+		}
+	}
+
+	// H1 checks
+	const h1Matches = html.match(/<h1[\s>]/gi) ?? []
+	if (h1Matches.length === 0) {
+		warnings.push('Missing H1 tag')
+	} else if (h1Matches.length > 1) {
+		warnings.push(`Multiple H1 tags found (${h1Matches.length})`)
+	}
+
+	// JSON-LD presence check
+	const jsonLdMatch = html.match(/<script\s[^>]*type=["']application\/ld\+json["'][^>]*>/i)
+	if (!jsonLdMatch) {
+		warnings.push('Missing JSON-LD structured data')
+	}
+
+	return { errors, warnings }
+}
+
+function isNoindexMetaRefreshRedirect(html: string): boolean {
+	const metaTags = html.match(/<meta\s+[^>]*>/gi) ?? []
+	const hasRefresh = metaTags.some(
+		(tag) => getHtmlAttr(tag, 'http-equiv')?.toLowerCase() === 'refresh',
+	)
+	const hasNoindex = metaTags.some((tag) => {
+		if (getHtmlAttr(tag, 'name')?.toLowerCase() !== 'robots') return false
+		const content = getHtmlAttr(tag, 'content')?.toLowerCase() ?? ''
+		return content
+			.split(',')
+			.map((part) => part.trim())
+			.includes('noindex')
+	})
+	return hasRefresh && hasNoindex
+}
+
+function getHtmlAttr(tag: string, name: string): string | undefined {
+	const escapedName = name.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+	const match = tag.match(
+		new RegExp(`\\b${escapedName}\\s*=\\s*(?:"([^"]*)"|'([^']*)'|([^\\s>]+))`, 'i'),
+	)
+	return match?.[1] ?? match?.[2] ?? match?.[3]
+}
+
+// ─── Hreflang reciprocity ───
+
+import type { ContentItem } from '../types.js'
+
+export interface HreflangReciprocityIssue {
+	url: string
+	missingReciprocal: {
+		from: string
+		lang: string
+		expectedBackReference: string
+	}
+}
+
+/**
+ * Verify that every `alternateLocales` entry has a reciprocal entry on the
+ * target side. For search engines, missing reciprocals are a hard error — Google
+ * will ignore the hreflang annotations altogether.
+ *
+ * Runs in O(N^2) worst-case but N is bounded by the number of translated articles,
+ * not the entire catalog, so this is fine at build time.
+ *
+ * Returns the list of reciprocity violations. Callers log these as errors in the
+ * build-time validation hook.
+ */
+export function validateHreflangReciprocity(items: ContentItem[]): HreflangReciprocityIssue[] {
+	const byUrl = new Map<string, ContentItem>()
+	for (const item of items) byUrl.set(item.url, item)
+
+	const issues: HreflangReciprocityIssue[] = []
+	for (const item of items) {
+		if (!item.alternateLocales || item.alternateLocales.length === 0) continue
+		for (const alt of item.alternateLocales) {
+			const altItem = byUrl.get(alt.url)
+			if (!altItem) {
+				issues.push({
+					url: item.url,
+					missingReciprocal: {
+						from: alt.url,
+						lang: alt.lang,
+						expectedBackReference: item.url,
+					},
+				})
+				continue
+			}
+			const hasBackRef = altItem.alternateLocales?.some((a) => a.url === item.url)
+			if (!hasBackRef) {
+				issues.push({
+					url: item.url,
+					missingReciprocal: {
+						from: alt.url,
+						lang: alt.lang,
+						expectedBackReference: item.url,
+					},
+				})
+			}
+		}
+	}
+	return issues
+}
+
+// ─── Prerender-gated-content guard ───
+
+export interface PrerenderGuardIssue {
+	route: string
+	access: 'members'
+	message: string
+}
+
+/**
+ * Fails the build when a route whose ContentItem has `access: 'members'` is
+ * configured as `prerender: true`. This is the load-bearing check that makes
+ * Flexible Sampling + static mode the only known-bad combo. The consumer's
+ * Astro integration iterates the build manifest and calls this with the
+ * prerendered-route URL set crossed against contentProvider output.
+ *
+ * Spec lines 1389-1405.
+ *
+ * Returns an empty array on success; non-empty means the build MUST fail.
+ */
+export function validatePrerenderedGatedRoutes({
+	prerenderedUrls,
+	items,
+}: {
+	prerenderedUrls: Set<string>
+	items: ContentItem[]
+}): PrerenderGuardIssue[] {
+	const issues: PrerenderGuardIssue[] = []
+	for (const item of items) {
+		if (item.access !== 'members') continue
+		const path = new URL(item.url).pathname
+		if (prerenderedUrls.has(path) || prerenderedUrls.has(`${path}/`)) {
+			issues.push({
+				route: path,
+				access: 'members',
+				message:
+					`Route ${path} is prerendered but serves a members-gated item. ` +
+					`Prerendered HTML is the same bytes for every requester — there is no ` +
+					`way to serve a teaser to anonymous users and the full body to verified ` +
+					`Googlebot from the same static file. Set export const prerender = false ` +
+					`on this route, or mark this item access: 'public'.`,
+			})
+		}
+	}
+	return issues
+}

package/src/virtual.d.ts

@@ -0,0 +1,8 @@
+declare module 'virtual:growth-labs/seo/config' {
+	import type { ResolvedSeoOptions } from '@growth-labs/seo'
+	import type { ContentProvider } from '@growth-labs/seo'
+
+	export const config: ResolvedSeoOptions
+	export function getConfig(): ResolvedSeoOptions
+	export function getContentProvider(): ContentProvider | undefined
+}

package/src/vite-plugin.ts

@@ -0,0 +1,66 @@
+import type { Plugin } from 'vite'
+import type { ResolvedSeoOptions } from './options.js'
+
+const VIRTUAL_MODULE_ID = 'virtual:growth-labs/seo/config'
+const RESOLVED_VIRTUAL_MODULE_ID = `\0${VIRTUAL_MODULE_ID}`
+
+export interface SeoVitePluginOptions {
+	config: ResolvedSeoOptions
+	/**
+	 * Optional module specifier whose default export is the ContentProvider.
+	 * When set, the generated virtual module imports it and registers the
+	 * provider via `_setContentProvider` at load time. This is how state
+	 * gets seeded in Cloudflare's prerender-worker context, where
+	 * `seo(userOptions)` from astro.config.mjs never runs.
+	 *
+	 * The specifier is passed directly to Vite's resolver. Project-root-relative
+	 * paths (e.g. '/src/lib/content-provider.ts') are the usual form.
+	 */
+	contentProviderModule?: string
+}
+
+export function growthLabsSeoPlugin(opts: SeoVitePluginOptions | ResolvedSeoOptions): Plugin {
+	// Back-compat: callers from 0.2.x passed ResolvedSeoOptions directly.
+	const normalized: SeoVitePluginOptions =
+		'config' in opts && 'site' in (opts as SeoVitePluginOptions).config
+			? (opts as SeoVitePluginOptions)
+			: { config: opts as ResolvedSeoOptions }
+
+	const { config, contentProviderModule } = normalized
+	// contentProvider is a function — not JSON-serializable. Strip it; the
+	// module-path form seeds state separately.
+	const { contentProvider: _, ...staticConfig } = config as Record<string, unknown>
+
+	return {
+		name: 'growth-labs-seo-config',
+		resolveId(id) {
+			if (id === VIRTUAL_MODULE_ID) {
+				return RESOLVED_VIRTUAL_MODULE_ID
+			}
+		},
+		load(id) {
+			if (id !== RESOLVED_VIRTUAL_MODULE_ID) return
+
+			// The generated module seeds state via side-effect at import time.
+			// Routes/middleware that `import 'virtual:growth-labs/seo/config'` before
+			// calling getConfig() populate state in whatever environment they run —
+			// the main Worker AND the Cloudflare prerender worker.
+			const lines: string[] = [
+				`import { _setConfig, _setContentProvider } from '@growth-labs/seo/_internal/state';`,
+			]
+			if (contentProviderModule) {
+				lines.push(`import _cp from ${JSON.stringify(contentProviderModule)};`)
+			}
+			lines.push(`const config = ${JSON.stringify(staticConfig)};`)
+			lines.push(`_setConfig(config);`)
+			if (contentProviderModule) {
+				lines.push(`_setContentProvider(_cp);`)
+			}
+			lines.push(`export { config };`)
+			lines.push(
+				`export { getConfig, getContentProvider } from '@growth-labs/seo/_internal/state';`,
+			)
+			return lines.join('\n')
+		},
+	}
+}