@nuasite/checks 0.16.0

package/dist/types/types.d.ts

@@ -0,0 +1,220 @@
+import type { HTMLElement as ParsedHTMLElement } from 'node-html-parser';
+export type CheckSeverity = 'error' | 'warning' | 'info';
+export type CheckDomain = 'seo' | 'geo' | 'performance' | 'accessibility' | 'ai';
+export type CheckMode = 'auto' | 'full' | 'essential';
+/** 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;
+};
+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;
+}
+/** 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[]>;
+}
+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;
+}
+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;
+}
+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;
+}
+export interface CheckReport {
+    totalPages: number;
+    totalChecks: number;
+    results: CheckResult[];
+    errors: CheckResult[];
+    warnings: CheckResult[];
+    infos: CheckResult[];
+    passed: boolean;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@nuasite/checks",
+  "description": "SEO, GEO, performance, accessibility, and AI validation for Astro sites.",
+  "files": [
+    "dist/**",
+    "src/**",
+    "package.json"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nuasite/nuasite.git",
+    "directory": "packages/checks"
+  },
+  "license": "Apache-2.0",
+  "version": "0.16.0",
+  "module": "src/index.ts",
+  "types": "src/index.ts",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "import": "./src/index.ts",
+      "default": "./src/index.ts"
+    }
+  },
+  "dependencies": {
+    "astro": "^6.0.2",
+    "node-html-parser": "^7.1.0"
+  },
+  "devDependencies": {
+    "@types/bun": "1.3.10"
+  },
+  "peerDependencies": {
+    "typescript": "^5"
+  },
+  "scripts": {
+    "prepack": "bun run ../../scripts/workspace-deps/resolve-deps.ts"
+  },
+  "keywords": [
+    "devtools",
+    "nuasite",
+    "seo",
+    "geo",
+    "performance",
+    "accessibility",
+    "validation",
+    "withastro"
+  ]
+}

package/src/check-runner.ts

@@ -0,0 +1,92 @@
+import type { Check, CheckReport, CheckResult, CheckSeverity, PageCheckContext, ResolvedChecksOptions, SiteCheck, SiteCheckContext } from './types'
+
+export class CheckRunner {
+	private pageChecks: Check[] = []
+	private siteChecks: SiteCheck[] = []
+	private overrides: Record<string, CheckSeverity | false>
+	private isEssential: boolean
+
+	constructor(options: ResolvedChecksOptions, isCI: boolean) {
+		this.overrides = options.overrides
+		this.isEssential = options.mode === 'essential' || (options.mode === 'auto' && !isCI)
+	}
+
+	registerCheck(check: Check): void {
+		this.pageChecks.push(check)
+	}
+
+	registerSiteCheck(check: SiteCheck): void {
+		this.siteChecks.push(check)
+	}
+
+	async runPageChecks(context: PageCheckContext): Promise<CheckResult[]> {
+		const results: CheckResult[] = []
+		for (const check of this.pageChecks) {
+			if (this.isSkipped(check)) continue
+			const issues = await check.run(context)
+			const enriched: CheckResult[] = issues.map(issue => ({
+				checkId: check.id,
+				ruleName: check.name,
+				domain: check.domain,
+				severity: check.defaultSeverity,
+				pagePath: context.pagePath,
+				filePath: context.filePath,
+				...issue,
+			}))
+			results.push(...this.applyOverrides(check, enriched))
+		}
+		return results
+	}
+
+	async runSiteChecks(context: SiteCheckContext): Promise<CheckResult[]> {
+		const results: CheckResult[] = []
+		for (const check of this.siteChecks) {
+			if (this.isSkipped(check)) continue
+			const issues = await check.run(context)
+			const enriched: CheckResult[] = issues.map(issue => ({
+				checkId: check.id,
+				ruleName: check.name,
+				domain: check.domain,
+				severity: check.defaultSeverity,
+				...issue,
+			}))
+			results.push(...this.applyOverrides(check, enriched))
+		}
+		return results
+	}
+
+	generateReport(results: CheckResult[], totalPages: number): CheckReport {
+		const errors: CheckResult[] = []
+		const warnings: CheckResult[] = []
+		const infos: CheckResult[] = []
+		for (const r of results) {
+			if (r.severity === 'error') errors.push(r)
+			else if (r.severity === 'warning') warnings.push(r)
+			else infos.push(r)
+		}
+
+		return {
+			totalPages,
+			totalChecks: this.pageChecks.length + this.siteChecks.length,
+			results,
+			errors,
+			warnings,
+			infos,
+			passed: errors.length === 0,
+		}
+	}
+
+	private isSkipped(check: Check | SiteCheck): boolean {
+		if (this.overrides[check.id] === false) return true
+		if (this.isEssential && !check.essential) return true
+		return false
+	}
+
+	private applyOverrides(check: Check | SiteCheck, results: CheckResult[]): CheckResult[] {
+		const override = this.overrides[check.id]
+		if (override) {
+			return results.map(r => ({ ...r, severity: override }))
+		}
+		return results
+	}
+}

package/src/checks/accessibility/aria-landmarks-check.ts

@@ -0,0 +1,23 @@
+import type { Check, CheckIssue, PageCheckContext } from '../../types'
+
+export function createAriaLandmarksCheck(): Check {
+	return {
+		kind: 'page',
+		id: 'accessibility/aria-landmarks',
+		name: 'ARIA Landmarks',
+		domain: 'accessibility',
+		defaultSeverity: 'info',
+		description: 'Page should have a <main> landmark element',
+		essential: false,
+		run(ctx: PageCheckContext): CheckIssue[] {
+			const hasMain = ctx.root.querySelector('main') || ctx.root.querySelector('[role="main"]')
+			if (!hasMain) {
+				return [{
+					message: 'Page is missing a <main> landmark element',
+					suggestion: 'Wrap the primary content in a <main> element or add role="main" to the content container',
+				}]
+			}
+			return []
+		},
+	}
+}

package/src/checks/accessibility/form-label-check.ts

@@ -0,0 +1,29 @@
+import type { Check, CheckIssue, PageCheckContext } from '../../types'
+
+export function createFormLabelCheck(): Check {
+	return {
+		kind: 'page',
+		id: 'accessibility/form-label',
+		name: 'Form Labels',
+		domain: 'accessibility',
+		defaultSeverity: 'warning',
+		description: 'Form inputs must have associated labels',
+		essential: true,
+		run(ctx: PageCheckContext): CheckIssue[] {
+			const results: CheckIssue[] = []
+			for (const form of ctx.pageData.forms) {
+				for (const input of form.inputs) {
+					if (!input.hasLabel) {
+						const identifier = input.name ?? input.id ?? input.type
+						results.push({
+							message: `Input "${identifier}" is missing an associated label`,
+							suggestion: 'Add a <label> element with a matching "for" attribute, or wrap the input in a <label>',
+							line: input.line,
+						})
+					}
+				}
+			}
+			return results
+		},
+	}
+}

package/src/checks/accessibility/index.ts

@@ -0,0 +1,5 @@
+export { createAriaLandmarksCheck } from './aria-landmarks-check'
+export { createFormLabelCheck } from './form-label-check'
+export { createLangAttributeCheck } from './lang-attribute-check'
+export { createLinkTextCheck } from './link-text-check'
+export { createTabindexCheck } from './tabindex-check'

package/src/checks/accessibility/lang-attribute-check.ts

@@ -0,0 +1,22 @@
+import type { Check, CheckIssue, PageCheckContext } from '../../types'
+
+export function createLangAttributeCheck(): Check {
+	return {
+		kind: 'page',
+		id: 'accessibility/lang-attribute',
+		name: 'Lang Attribute',
+		domain: 'accessibility',
+		defaultSeverity: 'warning',
+		description: 'HTML element should have a lang attribute',
+		essential: true,
+		run(ctx: PageCheckContext): CheckIssue[] {
+			if (!ctx.pageData.htmlLang) {
+				return [{
+					message: 'Page is missing a lang attribute on the <html> element',
+					suggestion: 'Add lang="en" (or appropriate language code) to the <html> tag',
+				}]
+			}
+			return []
+		},
+	}
+}

package/src/checks/accessibility/link-text-check.ts

@@ -0,0 +1,30 @@
+import { buildPoorTextSet, poorLinkTexts } from '../../i18n/poor-texts'
+import type { Check, CheckIssue, PageCheckContext } from '../../types'
+
+export function createLinkTextCheck(): Check {
+	return {
+		kind: 'page',
+		id: 'accessibility/link-text',
+		name: 'Descriptive Link Text',
+		domain: 'accessibility',
+		defaultSeverity: 'info',
+		description: 'Links should have descriptive text instead of generic phrases',
+		essential: false,
+		run(ctx: PageCheckContext): CheckIssue[] {
+			const poorTexts = buildPoorTextSet(poorLinkTexts, ctx.pageData.htmlLang)
+			const results: CheckIssue[] = []
+			for (const link of ctx.pageData.links) {
+				const trimmed = link.text.trim()
+				if (poorTexts.has(trimmed.toLowerCase())) {
+					results.push({
+						message: `Link with text "${trimmed}" is not descriptive`,
+						suggestion: 'Use descriptive text that explains where the link goes, e.g. "View pricing details" instead of "click here"',
+						line: link.line,
+						actual: trimmed,
+					})
+				}
+			}
+			return results
+		},
+	}
+}

package/src/checks/accessibility/tabindex-check.ts

@@ -0,0 +1,28 @@
+import type { Check, CheckIssue, PageCheckContext } from '../../types'
+
+export function createTabindexCheck(): Check {
+	return {
+		kind: 'page',
+		id: 'accessibility/tabindex',
+		name: 'Positive Tabindex',
+		domain: 'accessibility',
+		defaultSeverity: 'warning',
+		description: 'Elements should not have a positive tabindex value',
+		essential: false,
+		run(ctx: PageCheckContext): CheckIssue[] {
+			const results: CheckIssue[] = []
+			const elements = ctx.root.querySelectorAll('[tabindex]')
+			for (const el of elements) {
+				const tabindex = parseInt(el.getAttribute('tabindex') ?? '0', 10)
+				if (tabindex > 0) {
+					const tag = el.tagName?.toLowerCase() ?? 'unknown'
+					results.push({
+						message: `<${tag}> element has tabindex="${tabindex}" which disrupts natural tab order`,
+						suggestion: 'Use tabindex="0" to make an element focusable in natural order, or tabindex="-1" for programmatic focus only',
+					})
+				}
+			}
+			return results
+		},
+	}
+}

package/src/checks/geo/content-quality-check.ts

@@ -0,0 +1,48 @@
+import type { Check, CheckIssue, PageCheckContext } from '../../types'
+
+export function createContentTooShortCheck(minLength: number): Check {
+	return {
+		kind: 'page',
+		id: 'geo/content-too-short',
+		name: 'Content Length',
+		domain: 'geo',
+		defaultSeverity: 'info',
+		description: `Page content should be at least ${minLength} characters`,
+		essential: false,
+		run(ctx: PageCheckContext): CheckIssue[] {
+			const length = ctx.pageData.bodyTextLength
+			if (length < minLength) {
+				return [{
+					message: `Page content is ${length} characters (min: ${minLength})`,
+					suggestion: `Add more meaningful content to reach at least ${minLength} characters`,
+					actual: `${length} characters`,
+					expected: `>= ${minLength} characters`,
+				}]
+			}
+			return []
+		},
+	}
+}
+
+export function createInsufficientHeadingsCheck(minHeadings: number): Check {
+	return {
+		kind: 'page',
+		id: 'geo/insufficient-headings',
+		name: 'Heading Count',
+		domain: 'geo',
+		defaultSeverity: 'info',
+		description: `Page should have at least ${minHeadings} headings for structure`,
+		essential: false,
+		run(ctx: PageCheckContext): CheckIssue[] {
+			if (ctx.pageData.headings.length < minHeadings) {
+				return [{
+					message: `Page has ${ctx.pageData.headings.length} heading(s) (min: ${minHeadings})`,
+					suggestion: `Add more headings to improve content structure and LLM comprehension`,
+					actual: `${ctx.pageData.headings.length} headings`,
+					expected: `>= ${minHeadings} headings`,
+				}]
+			}
+			return []
+		},
+	}
+}

package/src/checks/geo/index.ts

@@ -0,0 +1,2 @@
+export { createContentTooShortCheck, createInsufficientHeadingsCheck } from './content-quality-check'
+export { createLlmsTxtCheck } from './llms-txt-check'

package/src/checks/geo/llms-txt-check.ts

@@ -0,0 +1,37 @@
+import fs from 'node:fs/promises'
+import path from 'node:path'
+import type { SiteCheck, SiteCheckContext, SiteCheckIssue } from '../../types'
+
+export function createLlmsTxtCheck(): SiteCheck {
+	return {
+		kind: 'site',
+		id: 'geo/llms-txt',
+		name: 'llms.txt',
+		domain: 'geo',
+		defaultSeverity: 'warning',
+		description: 'Site should have a valid llms.txt file',
+		essential: true,
+		async run(ctx: SiteCheckContext): Promise<SiteCheckIssue[]> {
+			const llmsPath = path.join(ctx.distDir, 'llms.txt')
+			let content: string
+			try {
+				content = await fs.readFile(llmsPath, 'utf-8')
+			} catch {
+				return [{
+					message: 'Site is missing a llms.txt file',
+					suggestion: 'Add a llms.txt file to make your site discoverable by LLMs',
+					pagePath: '/llms.txt',
+				}]
+			}
+
+			if (content.trim().length === 0) {
+				return [{
+					message: 'llms.txt file is empty',
+					suggestion: 'Add content to llms.txt describing your site for LLM consumption',
+					pagePath: '/llms.txt',
+				}]
+			}
+			return []
+		},
+	}
+}

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

@@ -0,0 +1,26 @@
+import type { Check, CheckIssue, PageCheckContext } from '../../types'
+
+export function createHtmlSizeCheck(maxSize: number): Check {
+	return {
+		kind: 'page',
+		id: 'performance/html-size',
+		name: 'HTML Size',
+		domain: 'performance',
+		defaultSeverity: 'warning',
+		description: `HTML document should be under ${(maxSize / 1024).toFixed(0)} KB`,
+		essential: false,
+		run(ctx: PageCheckContext): CheckIssue[] {
+			if (ctx.pageData.htmlSize > maxSize) {
+				const actualKB = (ctx.pageData.htmlSize / 1024).toFixed(1)
+				const maxKB = (maxSize / 1024).toFixed(1)
+				return [{
+					message: `HTML document is ${actualKB} KB (max: ${maxKB} KB)`,
+					suggestion: 'Reduce HTML size by removing unnecessary markup, inlining less CSS, or splitting into multiple pages',
+					actual: `${actualKB} KB`,
+					expected: `<= ${maxKB} KB`,
+				}]
+			}
+			return []
+		},
+	}
+}