@nuasite/checks 0.16.0

package/src/i18n/poor-texts.ts

@@ -0,0 +1,66 @@
+/**
+ * Locale-keyed collections of generic/non-descriptive text patterns.
+ * Used by accessibility and SEO checks to detect poor link text and image alt text.
+ */
+
+export const poorLinkTexts: Record<string, string[]> = {
+	en: ['click here', 'read more', 'here', 'link', 'more', 'learn more'],
+	es: ['haz clic aquí', 'clic aquí', 'leer más', 'aquí', 'enlace', 'más', 'más información'],
+	fr: ['cliquez ici', 'lire la suite', 'en savoir plus', 'ici', 'lien', 'plus'],
+	de: ['hier klicken', 'klicken sie hier', 'mehr lesen', 'weiterlesen', 'hier', 'mehr', 'mehr erfahren'],
+	it: ['clicca qui', 'leggi di più', 'continua a leggere', 'qui', 'collegamento', 'più'],
+	pt: ['clique aqui', 'leia mais', 'saiba mais', 'aqui', 'mais'],
+	nl: ['klik hier', 'lees meer', 'meer'],
+	cs: ['klikněte zde', 'klikni zde', 'čtěte dále', 'více', 'zde', 'odkaz', 'zjistit více'],
+	ko: ['여기를 클릭', '더 보기', '자세히 보기', '여기', '링크', '더보기', '클릭'],
+}
+
+export const poorImageAlts: Record<string, string[]> = {
+	en: ['image', 'photo', 'picture', 'img', 'untitled', 'screenshot', 'banner', 'logo', 'icon', 'graphic', 'thumbnail'],
+	es: ['imagen', 'foto', 'fotografía', 'captura de pantalla', 'logotipo', 'ícono'],
+	fr: ['image', 'photo', "capture d'écran", 'logo', 'icône', 'graphique', 'vignette'],
+	de: ['bild', 'foto', 'grafik', 'bildschirmfoto', 'logo', 'symbol'],
+	it: ['immagine', 'foto', 'fotografia', 'schermata', 'logo', 'icona'],
+	pt: ['imagem', 'foto', 'fotografia', 'captura de tela', 'logotipo', 'ícone'],
+	nl: ['afbeelding', 'foto', 'schermafbeelding', 'logo', 'icoon'],
+	cs: ['obrázek', 'foto', 'fotografie', 'snímek obrazovky', 'logo', 'ikona'],
+	ko: ['이미지', '사진', '스크린샷', '로고', '아이콘', '그래픽', '썸네일'],
+}
+
+const cache = new WeakMap<Record<string, string[]>, Map<string, Set<string>>>()
+
+/**
+ * Build a Set of poor texts, optionally filtered by page locale.
+ * When a locale is provided, returns texts for that language + English as fallback.
+ * When no locale is provided or locale is unrecognized, returns English texts only.
+ * Results are cached by dictionary + locale.
+ */
+export function buildPoorTextSet(texts: Record<string, string[]>, locale?: string): Set<string> {
+	const key = locale?.toLowerCase().split('-')[0] ?? '*'
+
+	let localeMap = cache.get(texts)
+	if (!localeMap) {
+		localeMap = new Map()
+		cache.set(texts, localeMap)
+	}
+
+	const cached = localeMap.get(key)
+	if (cached) return cached
+
+	const en = texts.en ?? []
+	let result: Set<string>
+
+	if (key === '*') {
+		const set = new Set<string>()
+		for (const arr of Object.values(texts)) {
+			for (const s of arr) set.add(s)
+		}
+		result = set
+	} else {
+		const matched = texts[key]
+		result = matched ? new Set([...matched, ...en]) : new Set(en)
+	}
+
+	localeMap.set(key, result)
+	return result
+}

package/src/index.ts

@@ -0,0 +1,22 @@
+export { checks } from './checks-integration'
+export { checks as default } from './checks-integration'
+export type {
+	AccessibilityChecksConfig,
+	AiChecksConfig,
+	Check,
+	CheckDomain,
+	CheckIssue,
+	CheckMode,
+	CheckReport,
+	CheckResult,
+	CheckSeverity,
+	ChecksOptions,
+	ExtractedPageData,
+	GeoChecksConfig,
+	PageCheckContext,
+	PerformanceChecksConfig,
+	SeoChecksConfig,
+	SiteCheck,
+	SiteCheckContext,
+	SiteCheckIssue,
+} from './types'

package/src/register.ts

@@ -0,0 +1,110 @@
+import type { CheckRunner } from './check-runner'
+import type { ResolvedChecksOptions } from './types'
+
+// SEO checks
+import { createBrokenInternalLinksCheck } from './checks/seo/broken-internal-links-check'
+import { createCanonicalInvalidCheck, createCanonicalMismatchCheck, createCanonicalMissingCheck } from './checks/seo/canonical-check'
+import { createDescriptionLengthCheck, createDescriptionMissingCheck } from './checks/seo/description-check'
+import { createHeadingSkipCheck, createMultipleH1Check, createNoH1Check } from './checks/seo/heading-hierarchy-check'
+import { createImageAltMissingCheck } from './checks/seo/image-alt-check'
+import { createImageAltQualityCheck } from './checks/seo/image-alt-quality-check'
+import { createJsonLdInvalidCheck } from './checks/seo/json-ld-check'
+import { createMetaDuplicateCheck } from './checks/seo/meta-duplicates-check'
+import { createNoindexDetectedCheck } from './checks/seo/noindex-check'
+import { createOgDescriptionCheck, createOgImageCheck, createOgTitleCheck } from './checks/seo/open-graph-check'
+import { createRobotsTxtCheck, createSitemapXmlCheck } from './checks/seo/sitemap-robots-check'
+import { createTitleEmptyCheck, createTitleLengthCheck, createTitleMissingCheck } from './checks/seo/title-check'
+import { createTwitterCardCheck } from './checks/seo/twitter-card-check'
+import { createViewportMissingCheck } from './checks/seo/viewport-check'
+
+// GEO checks
+import { createContentTooShortCheck, createInsufficientHeadingsCheck } from './checks/geo/content-quality-check'
+import { createLlmsTxtCheck } from './checks/geo/llms-txt-check'
+
+// Performance checks
+import { createHtmlSizeCheck } from './checks/performance/html-size-check'
+import { createImageFormatCheck, createImageSizeCheck } from './checks/performance/image-optimization-check'
+import { createInlineSizeCheck } from './checks/performance/inline-size-check'
+import { createLazyLoadingCheck } from './checks/performance/lazy-loading-check'
+import { createRenderBlockingScriptCheck } from './checks/performance/render-blocking-check'
+import { createTotalRequestsCheck } from './checks/performance/total-requests-check'
+
+// Accessibility checks
+import { createAriaLandmarksCheck } from './checks/accessibility/aria-landmarks-check'
+import { createFormLabelCheck } from './checks/accessibility/form-label-check'
+import { createLangAttributeCheck } from './checks/accessibility/lang-attribute-check'
+import { createLinkTextCheck } from './checks/accessibility/link-text-check'
+import { createTabindexCheck } from './checks/accessibility/tabindex-check'
+
+export function registerAllChecks(runner: CheckRunner, options: ResolvedChecksOptions): void {
+	// SEO checks
+	if (options.seo !== false) {
+		const seo = options.seo
+		const titleMax = seo.titleMaxLength ?? 60
+		const descMax = seo.descriptionMaxLength ?? 160
+		const descMin = seo.descriptionMinLength ?? 50
+
+		runner.registerCheck(createTitleMissingCheck())
+		runner.registerCheck(createTitleEmptyCheck())
+		runner.registerCheck(createTitleLengthCheck(titleMax))
+		runner.registerCheck(createDescriptionMissingCheck())
+		runner.registerCheck(createDescriptionLengthCheck(descMin, descMax))
+		runner.registerCheck(createCanonicalMissingCheck())
+		runner.registerCheck(createCanonicalInvalidCheck())
+		runner.registerCheck(createCanonicalMismatchCheck())
+		runner.registerCheck(createJsonLdInvalidCheck())
+		runner.registerCheck(createMultipleH1Check())
+		runner.registerCheck(createNoH1Check())
+		runner.registerCheck(createHeadingSkipCheck())
+		runner.registerCheck(createOgTitleCheck())
+		runner.registerCheck(createOgDescriptionCheck())
+		runner.registerCheck(createOgImageCheck())
+		runner.registerCheck(createImageAltMissingCheck())
+		runner.registerCheck(createImageAltQualityCheck())
+		runner.registerCheck(createMetaDuplicateCheck())
+		runner.registerCheck(createViewportMissingCheck())
+		runner.registerCheck(createNoindexDetectedCheck())
+		runner.registerCheck(createTwitterCardCheck())
+		runner.registerSiteCheck(createRobotsTxtCheck())
+		runner.registerSiteCheck(createSitemapXmlCheck())
+		runner.registerSiteCheck(createBrokenInternalLinksCheck())
+	}
+
+	// GEO checks
+	if (options.geo !== false) {
+		const geo = options.geo
+		const minContent = geo.minContentLength ?? 300
+		const minHeadings = geo.minHeadings ?? 2
+
+		runner.registerSiteCheck(createLlmsTxtCheck())
+		runner.registerCheck(createContentTooShortCheck(minContent))
+		runner.registerCheck(createInsufficientHeadingsCheck(minHeadings))
+	}
+
+	// Performance checks
+	if (options.performance !== false) {
+		const perf = options.performance
+		const maxHtml = perf.maxHtmlSize ?? 100_000
+		const maxImg = perf.maxImageSize ?? 500_000
+		const formats = perf.allowedImageFormats ?? ['webp', 'avif', 'svg']
+		const maxInline = perf.maxInlineSize ?? 50_000
+		const maxRequests = perf.maxExternalRequests ?? 20
+
+		runner.registerCheck(createHtmlSizeCheck(maxHtml))
+		runner.registerCheck(createImageFormatCheck(formats))
+		runner.registerCheck(createImageSizeCheck(maxImg))
+		runner.registerCheck(createLazyLoadingCheck())
+		runner.registerCheck(createRenderBlockingScriptCheck())
+		runner.registerCheck(createInlineSizeCheck(maxInline))
+		runner.registerCheck(createTotalRequestsCheck(maxRequests))
+	}
+
+	// Accessibility checks
+	if (options.accessibility !== false) {
+		runner.registerCheck(createLangAttributeCheck())
+		runner.registerCheck(createFormLabelCheck())
+		runner.registerCheck(createAriaLandmarksCheck())
+		runner.registerCheck(createLinkTextCheck())
+		runner.registerCheck(createTabindexCheck())
+	}
+}

package/src/report.ts

@@ -0,0 +1,78 @@
+import type { AstroIntegrationLogger } from 'astro'
+import fs from 'node:fs/promises'
+import path from 'node:path'
+import type { CheckReport, CheckResult } from './types'
+
+export function logReport(report: CheckReport, logger: AstroIntegrationLogger): void {
+	const { totalPages, totalChecks, errors, warnings, infos } = report
+
+	if (errors.length === 0 && warnings.length === 0 && infos.length === 0) {
+		logger.info(`Checked ${totalPages} pages (${totalChecks} rules) — all passed`)
+		return
+	}
+
+	logger.info(`Checked ${totalPages} pages (${totalChecks} rules)`)
+
+	if (errors.length > 0) {
+		logger.error(`${errors.length} error(s):`)
+		for (const r of errors) {
+			logger.error(formatResult(r))
+		}
+	}
+
+	if (warnings.length > 0) {
+		logger.warn(`${warnings.length} warning(s):`)
+		for (const r of warnings) {
+			logger.warn(formatResult(r))
+		}
+	}
+
+	if (infos.length > 0) {
+		logger.info(`${infos.length} info(s):`)
+		for (const r of infos) {
+			logger.info(formatResult(r))
+		}
+	}
+
+	const parts = [
+		errors.length > 0 ? `${errors.length} error(s)` : null,
+		warnings.length > 0 ? `${warnings.length} warning(s)` : null,
+		infos.length > 0 ? `${infos.length} info(s)` : null,
+	].filter(Boolean)
+
+	logger.info(`Summary: ${parts.join(', ')}`)
+}
+
+export async function writeJsonReport(report: CheckReport, distDir: string, filename: string): Promise<string> {
+	const filePath = path.join(distDir, filename)
+	const json = {
+		timestamp: new Date().toISOString(),
+		totalPages: report.totalPages,
+		totalChecks: report.totalChecks,
+		passed: report.passed,
+		summary: {
+			errors: report.errors.length,
+			warnings: report.warnings.length,
+			infos: report.infos.length,
+		},
+		results: report.results.map(r => ({
+			checkId: r.checkId,
+			severity: r.severity,
+			domain: r.domain,
+			message: r.message,
+			suggestion: r.suggestion,
+			pagePath: r.pagePath,
+			line: r.line,
+			actual: r.actual,
+			expected: r.expected,
+		})),
+	}
+	await fs.writeFile(filePath, JSON.stringify(json, null, '\t'), 'utf8')
+	return filePath
+}
+
+function formatResult(r: CheckResult): string {
+	const location = r.line ? `${r.pagePath}:${r.line}` : r.pagePath
+	const suggestion = r.suggestion ? ` → ${r.suggestion}` : ''
+	return `  ${r.checkId.padEnd(30)} ${location.padEnd(30)} ${r.message}${suggestion}`
+}

package/src/tsconfig.json

@@ -0,0 +1,6 @@
+{
+	"extends": "../tsconfig.settings.json",
+	"compilerOptions": {
+		"outDir": "../dist/types"
+	}
+}

package/src/types.ts

@@ -0,0 +1,244 @@
+import type { HTMLElement as ParsedHTMLElement } from 'node-html-parser'
+
+// ── Severity & Domain ──────────────────────────────────────────────────────────
+
+export type CheckSeverity = 'error' | 'warning' | 'info'
+export type CheckDomain = 'seo' | 'geo' | 'performance' | 'accessibility' | 'ai'
+export type CheckMode = 'auto' | 'full' | 'essential'
+
+// ── Check Issue (returned by checks) ────────────────────────────────────────────
+
+/** Lightweight result returned by a check's run() method. The runner enriches it into a full CheckResult. */
+export interface CheckIssue {
+	message: string
+	suggestion?: string
+	pagePath?: string
+	filePath?: string
+	line?: number
+	actual?: string
+	expected?: string
+}
+
+/** Issue returned by a site-level check — pagePath is required since there's no single page context. */
+export type SiteCheckIssue = CheckIssue & { pagePath: string }
+
+// ── Check Result (enriched by runner) ───────────────────────────────────────────
+
+export interface CheckResult {
+	checkId: string
+	ruleName: string
+	domain: CheckDomain
+	severity: CheckSeverity
+	message: string
+	suggestion?: string
+	pagePath: string
+	filePath?: string
+	line?: number
+	actual?: string
+	expected?: string
+}
+
+// ── Check Interfaces ───────────────────────────────────────────────────────────
+
+/** Per-page check — runs once for each HTML page */
+export interface Check {
+	kind: 'page'
+	id: string
+	name: string
+	domain: CheckDomain
+	defaultSeverity: CheckSeverity
+	description: string
+	/** Whether this check runs in essential mode (true) or only in full mode (false) */
+	essential: boolean
+	run(context: PageCheckContext): CheckIssue[] | Promise<CheckIssue[]>
+}
+
+/** Site-level check — runs once after all pages are processed */
+export interface SiteCheck {
+	kind: 'site'
+	id: string
+	name: string
+	domain: CheckDomain
+	defaultSeverity: CheckSeverity
+	description: string
+	essential: boolean
+	run(context: SiteCheckContext): SiteCheckIssue[] | Promise<SiteCheckIssue[]>
+}
+
+// ── Check Contexts ─────────────────────────────────────────────────────────────
+
+export interface PageCheckContext {
+	pagePath: string
+	filePath: string
+	distDir: string
+	html: string
+	root: ParsedHTMLElement
+	pageData: ExtractedPageData
+}
+
+export interface SiteCheckContext {
+	distDir: string
+	projectRoot: string
+	pages: Map<string, ExtractedPageData>
+	siteUrl?: string
+}
+
+// ── Extracted Page Data ────────────────────────────────────────────────────────
+
+export interface ExtractedPageData {
+	title?: { content: string; line: number }
+	metaDescription?: { content: string; line: number }
+	metaTags: MetaTagData[]
+	openGraph: Record<string, { content: string; line: number }>
+	twitterCard: Record<string, { content: string; line: number }>
+	canonical?: { href: string; line: number }
+	jsonLd: JsonLdData[]
+	headings: HeadingData[]
+	images: ImageData[]
+	links: LinkData[]
+	scripts: ScriptData[]
+	stylesheets: StylesheetData[]
+	forms: ExtractedFormData[]
+	htmlLang?: string
+	htmlSize: number
+	bodyTextLength: number
+	hasViewport: boolean
+	hasNoindex: boolean
+	inlineScriptBytes: number
+	inlineStyleBytes: number
+}
+
+export interface MetaTagData {
+	name?: string
+	property?: string
+	content: string
+	line: number
+}
+
+export interface JsonLdData {
+	type: string
+	raw: string
+	valid: boolean
+	error?: string
+	line: number
+}
+
+export interface HeadingData {
+	level: number
+	text: string
+	line: number
+}
+
+export interface ImageData {
+	src: string
+	alt?: string
+	loading?: string
+	line: number
+}
+
+export interface LinkData {
+	href: string
+	text: string
+	rel?: string
+	line: number
+}
+
+export interface ScriptData {
+	src?: string
+	type?: string
+	isAsync: boolean
+	isDefer: boolean
+	isInline: boolean
+	size: number
+	line: number
+}
+
+export interface StylesheetData {
+	href: string
+	media?: string
+	line: number
+}
+
+export interface ExtractedFormData {
+	inputs: FormInputData[]
+	line: number
+}
+
+export interface FormInputData {
+	type: string
+	name?: string
+	id?: string
+	hasLabel: boolean
+	line: number
+}
+
+// ── Configuration ──────────────────────────────────────────────────────────────
+
+export interface ChecksOptions {
+	mode?: CheckMode
+	seo?: boolean | SeoChecksConfig
+	geo?: boolean | GeoChecksConfig
+	performance?: boolean | PerformanceChecksConfig
+	accessibility?: boolean | AccessibilityChecksConfig
+	ai?: AiChecksConfig | false
+	failOnError?: boolean
+	failOnWarning?: boolean
+	overrides?: Record<string, CheckSeverity | false>
+	customChecks?: (Check | SiteCheck)[]
+	/** Write a JSON report to the dist dir. `true` writes `checks-report.json`, a string sets a custom filename. */
+	reportJson?: boolean | string
+}
+
+export interface SeoChecksConfig {
+	titleMaxLength?: number
+	descriptionMaxLength?: number
+	descriptionMinLength?: number
+}
+
+export interface GeoChecksConfig {
+	minContentLength?: number
+	minHeadings?: number
+}
+
+export interface PerformanceChecksConfig {
+	maxHtmlSize?: number
+	maxImageSize?: number
+	allowedImageFormats?: string[]
+	maxInlineSize?: number
+	maxExternalRequests?: number
+}
+
+export type AccessibilityChecksConfig = {}
+
+export interface AiChecksConfig {
+	apiKey?: string
+	checks?: string[]
+	maxPages?: number
+	cache?: boolean
+}
+
+export interface ResolvedChecksOptions {
+	mode: CheckMode
+	seo: SeoChecksConfig | false
+	geo: GeoChecksConfig | false
+	performance: PerformanceChecksConfig | false
+	accessibility: AccessibilityChecksConfig | false
+	ai: AiChecksConfig | false
+	failOnError: boolean
+	failOnWarning: boolean
+	overrides: Record<string, CheckSeverity | false>
+	customChecks: (Check | SiteCheck)[]
+	reportJson: string | false
+}
+
+// ── Report ─────────────────────────────────────────────────────────────────────
+
+export interface CheckReport {
+	totalPages: number
+	totalChecks: number
+	results: CheckResult[]
+	errors: CheckResult[]
+	warnings: CheckResult[]
+	infos: CheckResult[]
+	passed: boolean
+}