@nuasite/checks 0.16.0

package/src/checks/performance/image-optimization-check.ts

@@ -0,0 +1,82 @@
+import { statSync } from 'node:fs'
+import path from 'node:path'
+import type { Check, CheckIssue, PageCheckContext } from '../../types'
+
+function isExternalOrDataUrl(src: string): boolean {
+	return src.startsWith('data:') || src.startsWith('http://') || src.startsWith('https://') || src.startsWith('//')
+}
+
+export function createImageFormatCheck(allowedFormats: string[]): Check {
+	return {
+		kind: 'page',
+		id: 'performance/image-format',
+		name: 'Image Format',
+		domain: 'performance',
+		defaultSeverity: 'info',
+		description: `Images should use modern formats: ${allowedFormats.join(', ')}`,
+		essential: false,
+		run(ctx: PageCheckContext): CheckIssue[] {
+			const results: CheckIssue[] = []
+			for (const img of ctx.pageData.images) {
+				if (isExternalOrDataUrl(img.src)) continue
+				const ext = path.extname(img.src).toLowerCase().replace('.', '')
+				if (ext && !allowedFormats.includes(ext)) {
+					results.push({
+						message: `Image "${img.src}" uses .${ext} format instead of a modern format`,
+						suggestion: `Convert to ${allowedFormats.join(' or ')} for better compression`,
+						line: img.line,
+						actual: ext,
+						expected: allowedFormats.join(', '),
+					})
+				}
+			}
+			return results
+		},
+	}
+}
+
+export function createImageSizeCheck(maxSize: number): Check {
+	const sizeCache = new Map<string, number | null>()
+	return {
+		kind: 'page',
+		id: 'performance/image-size',
+		name: 'Image File Size',
+		domain: 'performance',
+		defaultSeverity: 'warning',
+		description: `Image files should be under ${(maxSize / 1024).toFixed(0)} KB`,
+		essential: false,
+		run(ctx: PageCheckContext): CheckIssue[] {
+			const results: CheckIssue[] = []
+			for (const img of ctx.pageData.images) {
+				if (isExternalOrDataUrl(img.src)) continue
+				const imgPath = img.src.startsWith('/')
+					? path.join(ctx.distDir, img.src)
+					: path.resolve(path.dirname(ctx.filePath), img.src)
+				let size: number | null
+				if (sizeCache.has(imgPath)) {
+					size = sizeCache.get(imgPath)!
+				} else {
+					try {
+						size = statSync(imgPath).size
+					} catch {
+						size = null
+					}
+					sizeCache.set(imgPath, size)
+				}
+				if (size === null) continue
+				if (size > maxSize) {
+					const actualKB = (size / 1024).toFixed(1)
+					const maxKB = (maxSize / 1024).toFixed(1)
+					results.push({
+						message: `Image "${img.src}" is ${actualKB} KB (max: ${maxKB} KB)`,
+						suggestion: 'Compress the image or use a smaller resolution',
+						line: img.line,
+						actual: `${actualKB} KB`,
+						expected: `<= ${maxKB} KB`,
+					})
+				}
+			}
+			return results
+		},
+	}
+}

package/src/checks/performance/index.ts

@@ -0,0 +1,6 @@
+export { createHtmlSizeCheck } from './html-size-check'
+export { createImageFormatCheck, createImageSizeCheck } from './image-optimization-check'
+export { createInlineSizeCheck } from './inline-size-check'
+export { createLazyLoadingCheck } from './lazy-loading-check'
+export { createRenderBlockingScriptCheck } from './render-blocking-check'
+export { createTotalRequestsCheck } from './total-requests-check'

package/src/checks/performance/inline-size-check.ts

@@ -0,0 +1,29 @@
+import type { Check, CheckIssue, PageCheckContext } from '../../types'
+
+export function createInlineSizeCheck(maxSize: number): Check {
+	return {
+		kind: 'page',
+		id: 'performance/inline-size',
+		name: 'Inline Resource Size',
+		domain: 'performance',
+		defaultSeverity: 'warning',
+		description: `Inline scripts and styles should total under ${(maxSize / 1024).toFixed(0)} KB`,
+		essential: false,
+		run(ctx: PageCheckContext): CheckIssue[] {
+			const totalInline = ctx.pageData.inlineScriptBytes + ctx.pageData.inlineStyleBytes
+			if (totalInline > maxSize) {
+				const actualKB = (totalInline / 1024).toFixed(1)
+				const maxKB = (maxSize / 1024).toFixed(1)
+				const scriptKB = (ctx.pageData.inlineScriptBytes / 1024).toFixed(1)
+				const styleKB = (ctx.pageData.inlineStyleBytes / 1024).toFixed(1)
+				return [{
+					message: `Inline resources total ${actualKB} KB (scripts: ${scriptKB} KB, styles: ${styleKB} KB, max: ${maxKB} KB)`,
+					suggestion: 'Move large inline scripts and styles to external files for better caching',
+					actual: `${actualKB} KB`,
+					expected: `<= ${maxKB} KB`,
+				}]
+			}
+			return []
+		},
+	}
+}

package/src/checks/performance/lazy-loading-check.ts

@@ -0,0 +1,29 @@
+import type { Check, CheckIssue, PageCheckContext } from '../../types'
+
+export function createLazyLoadingCheck(): Check {
+	return {
+		kind: 'page',
+		id: 'performance/lazy-loading',
+		name: 'Lazy Loading',
+		domain: 'performance',
+		defaultSeverity: 'info',
+		description: 'Below-the-fold images should use loading="lazy"',
+		essential: false,
+		run(ctx: PageCheckContext): CheckIssue[] {
+			const results: CheckIssue[] = []
+			const images = ctx.pageData.images
+			for (let i = 2; i < images.length; i++) {
+				const img = images[i]!
+				if (img.loading === 'eager') continue
+				if (img.loading !== 'lazy') {
+					results.push({
+						message: `Image "${img.src}" (position ${i + 1}) is missing loading="lazy"`,
+						suggestion: 'Add loading="lazy" to below-the-fold images to improve initial page load',
+						line: img.line,
+					})
+				}
+			}
+			return results
+		},
+	}
+}

package/src/checks/performance/render-blocking-check.ts

@@ -0,0 +1,27 @@
+import type { Check, CheckIssue, PageCheckContext } from '../../types'
+
+export function createRenderBlockingScriptCheck(): Check {
+	return {
+		kind: 'page',
+		id: 'performance/render-blocking-script',
+		name: 'Render-Blocking Scripts',
+		domain: 'performance',
+		defaultSeverity: 'warning',
+		description: 'Scripts with src should use async, defer, or type="module" to avoid blocking rendering',
+		essential: false,
+		run(ctx: PageCheckContext): CheckIssue[] {
+			const results: CheckIssue[] = []
+			for (const script of ctx.pageData.scripts) {
+				if (!script.src) continue
+				if (script.isAsync || script.isDefer) continue
+				if (script.type === 'module') continue
+				results.push({
+					message: `Script "${script.src}" is render-blocking`,
+					suggestion: 'Add async, defer, or type="module" to the script tag',
+					line: script.line,
+				})
+			}
+			return results
+		},
+	}
+}

package/src/checks/performance/total-requests-check.ts

@@ -0,0 +1,27 @@
+import type { Check, CheckIssue, PageCheckContext } from '../../types'
+
+export function createTotalRequestsCheck(maxRequests: number): Check {
+	return {
+		kind: 'page',
+		id: 'performance/total-requests',
+		name: 'Total External Requests',
+		domain: 'performance',
+		defaultSeverity: 'info',
+		description: `Page should load fewer than ${maxRequests} external resources`,
+		essential: false,
+		run(ctx: PageCheckContext): CheckIssue[] {
+			const externalScripts = ctx.pageData.scripts.filter(s => s.src).length
+			const externalStyles = ctx.pageData.stylesheets.length
+			const total = externalScripts + externalStyles
+			if (total > maxRequests) {
+				return [{
+					message: `Page loads ${total} external resources (${externalScripts} scripts, ${externalStyles} stylesheets, max: ${maxRequests})`,
+					suggestion: 'Bundle scripts and stylesheets to reduce the number of HTTP requests',
+					actual: `${total} requests`,
+					expected: `<= ${maxRequests} requests`,
+				}]
+			}
+			return []
+		},
+	}
+}

package/src/checks/seo/broken-internal-links-check.ts

@@ -0,0 +1,49 @@
+import type { SiteCheck, SiteCheckContext, SiteCheckIssue } from '../../types'
+
+export function createBrokenInternalLinksCheck(): SiteCheck {
+	return {
+		kind: 'site',
+		id: 'seo/broken-internal-links',
+		name: 'Internal Links Valid',
+		domain: 'seo',
+		defaultSeverity: 'warning',
+		description: 'Internal links should point to existing pages',
+		essential: false,
+		run(ctx: SiteCheckContext): SiteCheckIssue[] {
+			const knownPaths = new Set<string>()
+			for (const p of ctx.pages.keys()) {
+				knownPaths.add(p)
+				const withSlash = p.endsWith('/') ? p : `${p}/`
+				const withoutSlash = p.endsWith('/') ? p.slice(0, -1) || '/' : p
+				knownPaths.add(withSlash)
+				knownPaths.add(withoutSlash)
+			}
+
+			const results: SiteCheckIssue[] = []
+			for (const [pagePath, pageData] of ctx.pages) {
+				for (const link of pageData.links) {
+					if (!link.href) continue
+					if (link.href.startsWith('http://') || link.href.startsWith('https://') || link.href.startsWith('//')) continue
+					if (link.href.startsWith('#') || link.href.startsWith('mailto:') || link.href.startsWith('tel:') || link.href.startsWith('javascript:')) continue
+
+					let targetPath = link.href.split('#')[0]!.split('?')[0]!
+					if (!targetPath.startsWith('/')) {
+						const base = pagePath.endsWith('/') ? pagePath : pagePath.substring(0, pagePath.lastIndexOf('/') + 1)
+						targetPath = base + targetPath
+					}
+					targetPath = targetPath.replace(/\/+/g, '/')
+
+					if (!knownPaths.has(targetPath)) {
+						results.push({
+							message: `Internal link to "${link.href}" does not match any known page`,
+							suggestion: 'Fix the link href or create the target page',
+							pagePath,
+							line: link.line,
+						})
+					}
+				}
+			}
+			return results
+		},
+	}
+}

package/src/checks/seo/canonical-check.ts

@@ -0,0 +1,77 @@
+import type { Check, CheckIssue, PageCheckContext } from '../../types'
+
+export function createCanonicalMissingCheck(): Check {
+	return {
+		kind: 'page',
+		id: 'seo/canonical-missing',
+		name: 'Canonical URL Present',
+		domain: 'seo',
+		defaultSeverity: 'warning',
+		description: 'Every page should have a canonical URL',
+		essential: true,
+		run(ctx: PageCheckContext): CheckIssue[] {
+			if (!ctx.pageData.canonical) {
+				return [{ message: 'Page is missing a canonical URL', suggestion: 'Add <link rel="canonical" href="..."> inside <head>' }]
+			}
+			return []
+		},
+	}
+}
+
+export function createCanonicalMismatchCheck(): Check {
+	return {
+		kind: 'page',
+		id: 'seo/canonical-mismatch',
+		name: 'Canonical URL Matches Page',
+		domain: 'seo',
+		defaultSeverity: 'warning',
+		description: 'Canonical URL should point to the current page',
+		essential: true,
+		run(ctx: PageCheckContext): CheckIssue[] {
+			if (!ctx.pageData.canonical) return []
+			const { href, line } = ctx.pageData.canonical
+			try {
+				const canonicalPath = new URL(href).pathname.replace(/\/+$/, '') || '/'
+				const pagePath = ctx.pagePath.replace(/\/+$/, '') || '/'
+				if (canonicalPath !== pagePath) {
+					return [{
+						message: 'Canonical URL does not match the page path',
+						suggestion: `Update the canonical URL to point to this page's own URL`,
+						line,
+						actual: href,
+						expected: ctx.pagePath,
+					}]
+				}
+			} catch {
+				// Invalid URL — handled by canonical-invalid check
+			}
+			return []
+		},
+	}
+}
+
+export function createCanonicalInvalidCheck(): Check {
+	return {
+		kind: 'page',
+		id: 'seo/canonical-invalid',
+		name: 'Canonical URL Valid',
+		domain: 'seo',
+		defaultSeverity: 'error',
+		description: 'Canonical URL must be a valid absolute URL',
+		essential: true,
+		run(ctx: PageCheckContext): CheckIssue[] {
+			if (!ctx.pageData.canonical) return []
+			const { href, line } = ctx.pageData.canonical
+			if (!href.startsWith('http://') && !href.startsWith('https://')) {
+				return [{
+					message: 'Canonical URL is not a valid absolute URL',
+					suggestion: 'Use an absolute URL starting with http:// or https://',
+					line,
+					actual: href,
+					expected: 'Absolute URL (http:// or https://)',
+				}]
+			}
+			return []
+		},
+	}
+}

package/src/checks/seo/description-check.ts

@@ -0,0 +1,55 @@
+import type { Check, CheckIssue, PageCheckContext } from '../../types'
+
+export function createDescriptionMissingCheck(): Check {
+	return {
+		kind: 'page',
+		id: 'seo/description-missing',
+		name: 'Meta Description Present',
+		domain: 'seo',
+		defaultSeverity: 'warning',
+		description: 'Every page should have a meta description',
+		essential: true,
+		run(ctx: PageCheckContext): CheckIssue[] {
+			if (!ctx.pageData.metaDescription) {
+				return [{ message: 'Page is missing a meta description', suggestion: 'Add <meta name="description" content="..."> inside <head>' }]
+			}
+			return []
+		},
+	}
+}
+
+export function createDescriptionLengthCheck(minLength: number, maxLength: number): Check {
+	return {
+		kind: 'page',
+		id: 'seo/description-length',
+		name: 'Meta Description Length',
+		domain: 'seo',
+		defaultSeverity: 'warning',
+		description: `Meta description should be ${minLength}-${maxLength} characters`,
+		essential: true,
+		run(ctx: PageCheckContext): CheckIssue[] {
+			if (!ctx.pageData.metaDescription) return []
+			const { content, line } = ctx.pageData.metaDescription
+			const results: CheckIssue[] = []
+
+			if (content.length > maxLength) {
+				results.push({
+					message: `Meta description is ${content.length} characters (max: ${maxLength})`,
+					suggestion: `Shorten to under ${maxLength} characters`,
+					line,
+					actual: `${content.length} characters`,
+					expected: `${minLength}-${maxLength} characters`,
+				})
+			} else if (content.length < minLength) {
+				results.push({
+					message: `Meta description is ${content.length} characters (min: ${minLength})`,
+					suggestion: `Expand to at least ${minLength} characters for better SEO`,
+					line,
+					actual: `${content.length} characters`,
+					expected: `${minLength}-${maxLength} characters`,
+				})
+			}
+			return results
+		},
+	}
+}

package/src/checks/seo/heading-hierarchy-check.ts

@@ -0,0 +1,76 @@
+import type { Check, CheckIssue, PageCheckContext } from '../../types'
+
+export function createMultipleH1Check(): Check {
+	return {
+		kind: 'page',
+		id: 'seo/multiple-h1',
+		name: 'Single H1',
+		domain: 'seo',
+		defaultSeverity: 'warning',
+		description: 'Each page should have only one <h1> element',
+		essential: true,
+		run(ctx: PageCheckContext): CheckIssue[] {
+			const h1s = ctx.pageData.headings.filter(h => h.level === 1)
+			if (h1s.length > 1) {
+				const second = h1s[1]!
+				return [{
+					message: `Page has ${h1s.length} <h1> elements (expected 1)`,
+					suggestion: 'Use only one <h1> per page; use <h2>-<h6> for sub-headings',
+					line: second.line,
+					actual: `${h1s.length} h1 elements`,
+					expected: '1 h1 element',
+				}]
+			}
+			return []
+		},
+	}
+}
+
+export function createNoH1Check(): Check {
+	return {
+		kind: 'page',
+		id: 'seo/no-h1',
+		name: 'H1 Present',
+		domain: 'seo',
+		defaultSeverity: 'warning',
+		description: 'Each page should have an <h1> element',
+		essential: true,
+		run(ctx: PageCheckContext): CheckIssue[] {
+			const h1s = ctx.pageData.headings.filter(h => h.level === 1)
+			if (h1s.length === 0) {
+				return [{ message: 'Page is missing an <h1> element', suggestion: 'Add an <h1> heading to identify the main topic of the page' }]
+			}
+			return []
+		},
+	}
+}
+
+export function createHeadingSkipCheck(): Check {
+	return {
+		kind: 'page',
+		id: 'seo/heading-skip',
+		name: 'Heading Hierarchy',
+		domain: 'seo',
+		defaultSeverity: 'info',
+		description: 'Heading levels should not be skipped (e.g. h1 followed by h3)',
+		essential: false,
+		run(ctx: PageCheckContext): CheckIssue[] {
+			const results: CheckIssue[] = []
+			const { headings } = ctx.pageData
+			for (let i = 1; i < headings.length; i++) {
+				const prev = headings[i - 1]!
+				const curr = headings[i]!
+				if (curr.level > prev.level + 1) {
+					results.push({
+						message: `Heading level skipped from <h${prev.level}> to <h${curr.level}>`,
+						suggestion: `Use <h${prev.level + 1}> instead of <h${curr.level}>, or add the missing intermediate heading`,
+						line: curr.line,
+						actual: `h${prev.level} → h${curr.level}`,
+						expected: `h${prev.level} → h${prev.level + 1}`,
+					})
+				}
+			}
+			return results
+		},
+	}
+}

package/src/checks/seo/image-alt-check.ts

@@ -0,0 +1,28 @@
+import type { Check, CheckIssue, PageCheckContext } from '../../types'
+
+export function createImageAltMissingCheck(): Check {
+	return {
+		kind: 'page',
+		id: 'seo/image-alt-missing',
+		name: 'Image Alt Text',
+		domain: 'seo',
+		defaultSeverity: 'warning',
+		description: 'Images should have an alt attribute',
+		essential: false,
+		run(ctx: PageCheckContext): CheckIssue[] {
+			const results: CheckIssue[] = []
+			for (const image of ctx.pageData.images) {
+				if (image.alt === undefined) {
+					results.push({
+						message: `Image is missing an alt attribute: ${image.src}`,
+						suggestion: 'Add an alt attribute describing the image, or alt="" if the image is decorative',
+						line: image.line,
+						actual: 'no alt attribute',
+						expected: 'alt="descriptive text" or alt=""',
+					})
+				}
+			}
+			return results
+		},
+	}
+}

package/src/checks/seo/image-alt-quality-check.ts

@@ -0,0 +1,31 @@
+import { buildPoorTextSet, poorImageAlts } from '../../i18n/poor-texts'
+import type { Check, CheckIssue, PageCheckContext } from '../../types'
+
+export function createImageAltQualityCheck(): Check {
+	return {
+		kind: 'page',
+		id: 'seo/image-alt-quality',
+		name: 'Image Alt Text Quality',
+		domain: 'seo',
+		defaultSeverity: 'info',
+		description: 'Image alt text should be descriptive, not generic',
+		essential: false,
+		run(ctx: PageCheckContext): CheckIssue[] {
+			const poorAlts = buildPoorTextSet(poorImageAlts, ctx.pageData.htmlLang)
+			const results: CheckIssue[] = []
+			for (const image of ctx.pageData.images) {
+				if (image.alt === undefined || image.alt === '') continue
+				const trimmed = image.alt.trim()
+				if (poorAlts.has(trimmed.toLowerCase())) {
+					results.push({
+						message: `Image has generic alt text "${trimmed}": ${image.src}`,
+						suggestion: 'Use descriptive alt text that explains the image content, e.g. "Team photo at annual retreat" instead of "photo"',
+						line: image.line,
+						actual: trimmed,
+					})
+				}
+			}
+			return results
+		},
+	}
+}

package/src/checks/seo/index.ts

@@ -0,0 +1,14 @@
+export { createBrokenInternalLinksCheck } from './broken-internal-links-check'
+export { createCanonicalInvalidCheck, createCanonicalMismatchCheck, createCanonicalMissingCheck } from './canonical-check'
+export { createDescriptionLengthCheck, createDescriptionMissingCheck } from './description-check'
+export { createHeadingSkipCheck, createMultipleH1Check, createNoH1Check } from './heading-hierarchy-check'
+export { createImageAltMissingCheck } from './image-alt-check'
+export { createImageAltQualityCheck } from './image-alt-quality-check'
+export { createJsonLdInvalidCheck } from './json-ld-check'
+export { createMetaDuplicateCheck } from './meta-duplicates-check'
+export { createNoindexDetectedCheck } from './noindex-check'
+export { createOgDescriptionCheck, createOgImageCheck, createOgTitleCheck } from './open-graph-check'
+export { createRobotsTxtCheck, createSitemapXmlCheck } from './sitemap-robots-check'
+export { createTitleEmptyCheck, createTitleLengthCheck, createTitleMissingCheck } from './title-check'
+export { createTwitterCardCheck } from './twitter-card-check'
+export { createViewportMissingCheck } from './viewport-check'

package/src/checks/seo/json-ld-check.ts

@@ -0,0 +1,26 @@
+import type { Check, CheckIssue, PageCheckContext } from '../../types'
+
+export function createJsonLdInvalidCheck(): Check {
+	return {
+		kind: 'page',
+		id: 'seo/json-ld-invalid',
+		name: 'JSON-LD Valid',
+		domain: 'seo',
+		defaultSeverity: 'error',
+		description: 'JSON-LD structured data must be valid',
+		essential: true,
+		run(ctx: PageCheckContext): CheckIssue[] {
+			const results: CheckIssue[] = []
+			for (const entry of ctx.pageData.jsonLd) {
+				if (!entry.valid) {
+					results.push({
+						message: entry.error ?? `Invalid JSON-LD for type "${entry.type}"`,
+						suggestion: 'Fix the JSON-LD structured data so it is valid JSON',
+						line: entry.line,
+					})
+				}
+			}
+			return results
+		},
+	}
+}

package/src/checks/seo/meta-duplicates-check.ts

@@ -0,0 +1,44 @@
+import type { Check, CheckIssue, PageCheckContext } from '../../types'
+
+const ALLOWED_DUPLICATES = new Set([
+	'property:og:image',
+	'property:og:image:width',
+	'property:og:image:height',
+	'property:og:image:alt',
+	'property:og:locale:alternate',
+])
+
+export function createMetaDuplicateCheck(): Check {
+	return {
+		kind: 'page',
+		id: 'seo/meta-duplicate',
+		name: 'No Duplicate Meta Tags',
+		domain: 'seo',
+		defaultSeverity: 'warning',
+		description: 'Meta tags should not have duplicate name or property attributes',
+		essential: false,
+		run(ctx: PageCheckContext): CheckIssue[] {
+			const results: CheckIssue[] = []
+			const seen = new Map<string, number>()
+
+			for (const tag of ctx.pageData.metaTags) {
+				const key = tag.name ? `name:${tag.name}` : tag.property ? `property:${tag.property}` : null
+				if (!key) continue
+				if (ALLOWED_DUPLICATES.has(key)) continue
+
+				const prevLine = seen.get(key)
+				if (prevLine !== undefined) {
+					const label = tag.name ? `name="${tag.name}"` : `property="${tag.property}"`
+					results.push({
+						message: `Duplicate meta tag with ${label}`,
+						suggestion: `Remove the duplicate <meta ${label}> tag (first seen at line ${prevLine})`,
+						line: tag.line,
+					})
+				} else {
+					seen.set(key, tag.line)
+				}
+			}
+			return results
+		},
+	}
+}

package/src/checks/seo/noindex-check.ts

@@ -0,0 +1,22 @@
+import type { Check, CheckIssue, PageCheckContext } from '../../types'
+
+export function createNoindexDetectedCheck(): Check {
+	return {
+		kind: 'page',
+		id: 'seo/noindex-detected',
+		name: 'Noindex Detection',
+		domain: 'seo',
+		defaultSeverity: 'info',
+		description: 'Detects pages with noindex meta tag that will be excluded from search engines',
+		essential: false,
+		run(ctx: PageCheckContext): CheckIssue[] {
+			if (ctx.pageData.hasNoindex) {
+				return [{
+					message: 'Page has a noindex directive and will not appear in search results',
+					suggestion: 'Remove the noindex directive if this page should be indexed by search engines',
+				}]
+			}
+			return []
+		},
+	}
+}