npm - @nuasite/checks - Versions diffs - 0.16.0 - Mend

@nuasite/checks 0.16.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (124) hide show

package/src/checks/seo/open-graph-check.ts ADDED Viewed

@@ -0,0 +1,55 @@
+import type { Check, CheckIssue, PageCheckContext } from '../../types'
+export function createOgTitleCheck(): Check {
+	return {
+		kind: 'page',
+		id: 'seo/og-title',
+		name: 'Open Graph Title',
+		domain: 'seo',
+		defaultSeverity: 'warning',
+		description: 'Pages should have an og:title meta tag',
+		essential: false,
+		run(ctx: PageCheckContext): CheckIssue[] {
+			if (!ctx.pageData.openGraph.title) {
+				return [{ message: 'Page is missing og:title meta tag', suggestion: 'Add <meta property="og:title" content="..."> inside <head>' }]
+			}
+			return []
+		},
+	}
+}
+export function createOgDescriptionCheck(): Check {
+	return {
+		kind: 'page',
+		id: 'seo/og-description',
+		name: 'Open Graph Description',
+		domain: 'seo',
+		defaultSeverity: 'warning',
+		description: 'Pages should have an og:description meta tag',
+		essential: false,
+		run(ctx: PageCheckContext): CheckIssue[] {
+			if (!ctx.pageData.openGraph.description) {
+				return [{ message: 'Page is missing og:description meta tag', suggestion: 'Add <meta property="og:description" content="..."> inside <head>' }]
+			}
+			return []
+		},
+	}
+}
+export function createOgImageCheck(): Check {
+	return {
+		kind: 'page',
+		id: 'seo/og-image',
+		name: 'Open Graph Image',
+		domain: 'seo',
+		defaultSeverity: 'warning',
+		description: 'Pages should have an og:image meta tag',
+		essential: false,
+		run(ctx: PageCheckContext): CheckIssue[] {
+			if (!ctx.pageData.openGraph.image) {
+				return [{ message: 'Page is missing og:image meta tag', suggestion: 'Add <meta property="og:image" content="..."> inside <head>' }]
+			}
+			return []
+		},
+	}
+}

package/src/checks/seo/sitemap-robots-check.ts ADDED Viewed

@@ -0,0 +1,55 @@
+import fs from 'node:fs/promises'
+import path from 'node:path'
+import type { SiteCheck, SiteCheckContext, SiteCheckIssue } from '../../types'
+export function createRobotsTxtCheck(): SiteCheck {
+	return {
+		kind: 'site',
+		id: 'seo/robots-txt',
+		name: 'robots.txt Present',
+		domain: 'seo',
+		defaultSeverity: 'warning',
+		description: 'Site should have a robots.txt file',
+		essential: false,
+		async run(ctx: SiteCheckContext): Promise<SiteCheckIssue[]> {
+			try {
+				await fs.access(path.join(ctx.distDir, 'robots.txt'))
+				return []
+			} catch {
+				return [{
+					message: 'Site is missing a robots.txt file',
+					suggestion: 'Add a robots.txt file to the public directory or use an Astro integration to generate one',
+					pagePath: '/robots.txt',
+				}]
+			}
+		},
+	}
+}
+export function createSitemapXmlCheck(): SiteCheck {
+	return {
+		kind: 'site',
+		id: 'seo/sitemap-xml',
+		name: 'Sitemap Present',
+		domain: 'seo',
+		defaultSeverity: 'warning',
+		description: 'Site should have a sitemap',
+		essential: false,
+		async run(ctx: SiteCheckContext): Promise<SiteCheckIssue[]> {
+			const files = ['sitemap-index.xml', 'sitemap-0.xml', 'sitemap.xml']
+			for (const file of files) {
+				try {
+					await fs.access(path.join(ctx.distDir, file))
+					return []
+				} catch {
+					// continue checking next file
+				}
+			}
+			return [{
+				message: 'Site is missing a sitemap',
+				suggestion: 'Add @astrojs/sitemap to generate a sitemap automatically',
+				pagePath: '/sitemap-index.xml',
+			}]
+		},
+	}
+}

package/src/checks/seo/title-check.ts ADDED Viewed

@@ -0,0 +1,63 @@
+import type { Check, CheckIssue, PageCheckContext } from '../../types'
+export function createTitleMissingCheck(): Check {
+	return {
+		kind: 'page',
+		id: 'seo/title-missing',
+		name: 'Title Present',
+		domain: 'seo',
+		defaultSeverity: 'error',
+		description: 'Every page must have a <title> element',
+		essential: true,
+		run(ctx: PageCheckContext): CheckIssue[] {
+			if (!ctx.pageData.title) {
+				return [{ message: 'Page is missing a <title> element', suggestion: 'Add a <title> tag inside <head>' }]
+			}
+			return []
+		},
+	}
+}
+export function createTitleEmptyCheck(): Check {
+	return {
+		kind: 'page',
+		id: 'seo/title-empty',
+		name: 'Title Not Empty',
+		domain: 'seo',
+		defaultSeverity: 'error',
+		description: 'Page title must not be empty',
+		essential: true,
+		run(ctx: PageCheckContext): CheckIssue[] {
+			if (ctx.pageData.title && ctx.pageData.title.content.length === 0) {
+				return [{ message: 'Page title is empty', suggestion: 'Add meaningful text to the <title> element', line: ctx.pageData.title.line }]
+			}
+			return []
+		},
+	}
+}
+export function createTitleLengthCheck(maxLength: number): Check {
+	return {
+		kind: 'page',
+		id: 'seo/title-length',
+		name: 'Title Length',
+		domain: 'seo',
+		defaultSeverity: 'warning',
+		description: `Title should be under ${maxLength} characters`,
+		essential: true,
+		run(ctx: PageCheckContext): CheckIssue[] {
+			if (!ctx.pageData.title) return []
+			const { content, line } = ctx.pageData.title
+			if (content.length > maxLength) {
+				return [{
+					message: `Title is ${content.length} characters (max: ${maxLength})`,
+					suggestion: `Shorten the title to under ${maxLength} characters`,
+					line,
+					actual: content,
+					expected: `<= ${maxLength} characters`,
+				}]
+			}
+			return []
+		},
+	}
+}

package/src/checks/seo/twitter-card-check.ts ADDED Viewed

@@ -0,0 +1,22 @@
+import type { Check, CheckIssue, PageCheckContext } from '../../types'
+export function createTwitterCardCheck(): Check {
+	return {
+		kind: 'page',
+		id: 'seo/twitter-card',
+		name: 'Twitter Card',
+		domain: 'seo',
+		defaultSeverity: 'info',
+		description: 'Pages should have a twitter:card meta tag for rich social sharing',
+		essential: false,
+		run(ctx: PageCheckContext): CheckIssue[] {
+			if (!ctx.pageData.twitterCard.card) {
+				return [{
+					message: 'Page is missing twitter:card meta tag',
+					suggestion: 'Add <meta name="twitter:card" content="summary_large_image"> inside <head>',
+				}]
+			}
+			return []
+		},
+	}
+}

package/src/checks/seo/viewport-check.ts ADDED Viewed

@@ -0,0 +1,22 @@
+import type { Check, CheckIssue, PageCheckContext } from '../../types'
+export function createViewportMissingCheck(): Check {
+	return {
+		kind: 'page',
+		id: 'seo/viewport-missing',
+		name: 'Viewport Meta Tag',
+		domain: 'seo',
+		defaultSeverity: 'warning',
+		description: 'Pages should have a viewport meta tag for mobile responsiveness',
+		essential: true,
+		run(ctx: PageCheckContext): CheckIssue[] {
+			if (!ctx.pageData.hasViewport) {
+				return [{
+					message: 'Page is missing a viewport meta tag',
+					suggestion: 'Add <meta name="viewport" content="width=device-width, initial-scale=1"> inside <head>',
+				}]
+			}
+			return []
+		},
+	}
+}

package/src/checks-integration.ts ADDED Viewed

@@ -0,0 +1,126 @@
+import type { AstroIntegration } from 'astro'
+import fs from 'node:fs/promises'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { CheckRunner } from './check-runner'
+import { resolveChecksOptions } from './config'
+import { analyzeHtml } from './html-analyzer'
+import { registerAllChecks } from './register'
+import { logReport, writeJsonReport } from './report'
+import type { CheckResult, ChecksOptions, ExtractedPageData } from './types'
+/**
+ * Try to read an HTML file for a given page pathname in the dist directory.
+ * Returns the file content and path, or undefined if not found.
+ */
+async function readPageHtml(distDir: string, pathname: string): Promise<{ html: string; filePath: string } | undefined> {
+	const candidates = [
+		path.join(distDir, pathname, 'index.html'),
+		path.join(distDir, `${pathname.replace(/\/$/, '')}.html`),
+	]
+	for (const candidate of candidates) {
+		try {
+			const html = await fs.readFile(candidate, 'utf8')
+			return { html, filePath: candidate }
+		} catch {
+			// Not found, try next
+		}
+	}
+	return undefined
+}
+export const checks = (options: ChecksOptions = {}): AstroIntegration => {
+	const resolved = resolveChecksOptions(options)
+	const isCI = !!process.env.CI
+	let siteUrl: string | undefined
+	let projectRoot: string | undefined
+	return {
+		name: '@nuasite/checks',
+		hooks: {
+			'astro:config:done': ({ config }) => {
+				siteUrl = config.site
+				projectRoot = fileURLToPath(config.root)
+			},
+			'astro:build:done': async ({ dir, pages, logger }) => {
+				const distDir = fileURLToPath(dir)
+				const runner = new CheckRunner(resolved, isCI)
+				// Register all built-in checks based on config
+				registerAllChecks(runner, resolved)
+				// Register custom checks
+				for (const check of resolved.customChecks) {
+					if (check.kind === 'site') {
+						runner.registerSiteCheck(check)
+					} else {
+						runner.registerCheck(check)
+					}
+				}
+				const allResults: CheckResult[] = []
+				const pagesData = new Map<string, ExtractedPageData>()
+				// Run per-page checks in parallel
+				const pageResults = await Promise.all(
+					pages.map(async (page) => {
+						const pagePath = `/${page.pathname}`.replace(/\/+/g, '/')
+						const result = await readPageHtml(distDir, page.pathname)
+						if (!result) {
+							logger.warn(`Skipping ${page.pathname}; no HTML output found.`)
+							return null
+						}
+						const { root, pageData } = analyzeHtml(result.html)
+						const results = await runner.runPageChecks({
+							pagePath,
+							filePath: result.filePath,
+							distDir,
+							html: result.html,
+							root,
+							pageData,
+						})
+						return { pagePath, pageData, results }
+					}),
+				)
+				for (const entry of pageResults) {
+					if (!entry) continue
+					pagesData.set(entry.pagePath, entry.pageData)
+					allResults.push(...entry.results)
+				}
+				// Run site-level checks
+				const siteResults = await runner.runSiteChecks({
+					distDir,
+					projectRoot: projectRoot ?? process.cwd(),
+					pages: pagesData,
+					siteUrl,
+				})
+				allResults.push(...siteResults)
+				// Generate and log report
+				const report = runner.generateReport(allResults, pagesData.size)
+				logReport(report, logger)
+				// Write JSON report if configured
+				if (resolved.reportJson) {
+					const reportPath = await writeJsonReport(report, distDir, resolved.reportJson)
+					logger.info(`JSON report written to ${reportPath}`)
+				}
+				// Fail build if configured
+				if (resolved.failOnError && report.errors.length > 0) {
+					throw new Error(
+						`@nuasite/checks: ${report.errors.length} error(s) found. Set failOnError: false to continue.`,
+					)
+				}
+				if (resolved.failOnWarning && (report.errors.length > 0 || report.warnings.length > 0)) {
+					throw new Error(
+						`@nuasite/checks: ${report.errors.length} error(s) and ${report.warnings.length} warning(s) found.`,
+					)
+				}
+			},
+		},
+	}
+}

package/src/config.ts ADDED Viewed

@@ -0,0 +1,27 @@
+import type { ChecksOptions, ResolvedChecksOptions } from './types'
+function resolveOption<T extends object>(value: boolean | T | undefined, defaultOptions: T = {} as T): T | false {
+	if (value === false) return false
+	if (value === true || value === undefined) return defaultOptions
+	return value
+}
+export function resolveChecksOptions(options: ChecksOptions = {}): ResolvedChecksOptions {
+	return {
+		mode: options.mode ?? 'auto',
+		seo: resolveOption(options.seo),
+		geo: resolveOption(options.geo),
+		performance: resolveOption(options.performance),
+		accessibility: resolveOption(options.accessibility),
+		ai: options.ai || false,
+		failOnError: options.failOnError ?? true,
+		failOnWarning: options.failOnWarning ?? false,
+		overrides: options.overrides ?? {},
+		customChecks: options.customChecks ?? [],
+		reportJson: options.reportJson === true
+			? 'checks-report.json'
+			: typeof options.reportJson === 'string'
+			? options.reportJson
+			: false,
+	}
+}

package/src/html-analyzer.ts ADDED Viewed

@@ -0,0 +1,325 @@
+import { type HTMLElement as ParsedHTMLElement, parse } from 'node-html-parser'
+import type {
+	ExtractedFormData,
+	ExtractedPageData,
+	HeadingData,
+	ImageData,
+	JsonLdData,
+	LinkData,
+	MetaTagData,
+	ScriptData,
+	StylesheetData,
+} from './types'
+/**
+ * Parse HTML and extract all data needed by checks.
+ * Parses once per page — all checks receive the same ExtractedPageData.
+ */
+export function analyzeHtml(html: string): { root: ParsedHTMLElement; pageData: ExtractedPageData } {
+	const root = parse(html, {
+		lowerCaseTagName: false,
+		comment: true,
+		blockTextElements: {
+			script: true,
+			noscript: true,
+			style: true,
+			pre: true,
+		},
+	})
+	const head = root.querySelector('head')
+	const body = root.querySelector('body')
+	const htmlElement = root.querySelector('html')
+	const lineIndex = buildLineIndex(html)
+	// Extract body text length once for content quality checks
+	const bodyTextLength = (body?.querySelector('main')?.textContent ?? body?.textContent ?? '').trim().length
+	const pageData: ExtractedPageData = {
+		metaTags: [],
+		openGraph: {},
+		twitterCard: {},
+		jsonLd: [],
+		headings: [],
+		images: [],
+		links: [],
+		scripts: [],
+		stylesheets: [],
+		forms: [],
+		htmlLang: htmlElement?.getAttribute('lang') || undefined,
+		htmlSize: Buffer.byteLength(html, 'utf8'),
+		bodyTextLength,
+		hasViewport: false,
+		hasNoindex: false,
+		inlineScriptBytes: 0,
+		inlineStyleBytes: 0,
+	}
+	if (head) {
+		pageData.title = extractTitle(head, html, lineIndex)
+		pageData.metaTags = extractMetaTags(head, html, lineIndex)
+		categorizeMetaTags(pageData)
+		pageData.canonical = extractCanonical(head, html, lineIndex)
+		pageData.jsonLd = extractJsonLd(root, html, lineIndex)
+		pageData.scripts = extractScripts(root, html, lineIndex)
+		pageData.stylesheets = extractStylesheets(head, html, lineIndex)
+		// Compute inline sizes from extracted data
+		pageData.inlineScriptBytes = pageData.scripts
+			.filter(s => s.isInline)
+			.reduce((sum, s) => sum + s.size, 0)
+		for (const style of root.querySelectorAll('style')) {
+			const content = style.textContent ?? ''
+			if (content) pageData.inlineStyleBytes += Buffer.byteLength(content, 'utf8')
+		}
+	}
+	if (body) {
+		pageData.headings = extractHeadings(body, html, lineIndex)
+		pageData.images = extractImages(root, html, lineIndex)
+		pageData.links = extractLinks(body, html, lineIndex)
+		pageData.forms = extractForms(body, html, lineIndex)
+	}
+	return { root, pageData }
+}
+// ── Line index for efficient offset → line conversion ──────────────────────────
+/** Precompute newline offsets for O(log n) offset-to-line lookups */
+function buildLineIndex(html: string): number[] {
+	const offsets = [0]
+	for (let i = 0; i < html.length; i++) {
+		if (html[i] === '\n') offsets.push(i + 1)
+	}
+	return offsets
+}
+/** Binary search to convert a character offset to a 1-based line number */
+function offsetToLine(lineIndex: number[], offset: number): number {
+	let lo = 0
+	let hi = lineIndex.length - 1
+	while (lo <= hi) {
+		const mid = (lo + hi) >>> 1
+		if (lineIndex[mid]! <= offset) lo = mid + 1
+		else hi = mid - 1
+	}
+	return lo // 1-based since offsets[0] = 0 means line 1
+}
+/**
+ * Advancing line finder — tracks position to handle duplicate elements correctly.
+ * Each call advances the search start so identical markup gets distinct line numbers.
+ */
+function createLineFinder(html: string, lineIndex: number[]) {
+	let pos = 0
+	return (search: string): number => {
+		const idx = html.indexOf(search, pos)
+		if (idx !== -1) {
+			pos = idx + 1
+			return offsetToLine(lineIndex, idx)
+		}
+		// Fallback: search from beginning for edge cases
+		const fallback = html.indexOf(search)
+		if (fallback !== -1) return offsetToLine(lineIndex, fallback)
+		return 1
+	}
+}
+function extractTitle(head: ParsedHTMLElement, html: string, lineIndex: number[]): ExtractedPageData['title'] {
+	const titleEl = head.querySelector('title')
+	if (!titleEl) return undefined
+	const content = titleEl.textContent?.trim() || ''
+	const findLine = createLineFinder(html, lineIndex)
+	return { content, line: findLine('<title') }
+}
+function extractMetaTags(head: ParsedHTMLElement, html: string, lineIndex: number[]): MetaTagData[] {
+	const tags: MetaTagData[] = []
+	const findLine = createLineFinder(html, lineIndex)
+	for (const meta of head.querySelectorAll('meta')) {
+		const name = meta.getAttribute('name')
+		const property = meta.getAttribute('property')
+		const content = meta.getAttribute('content')
+		if (!content || (!name && !property)) continue
+		tags.push({
+			name: name || undefined,
+			property: property || undefined,
+			content,
+			line: findLine(meta.toString().substring(0, 60)),
+		})
+	}
+	return tags
+}
+function categorizeMetaTags(pageData: ExtractedPageData): void {
+	for (const meta of pageData.metaTags) {
+		if (meta.name === 'description') {
+			pageData.metaDescription = { content: meta.content, line: meta.line }
+		}
+		if (meta.name === 'viewport') {
+			pageData.hasViewport = true
+		}
+		if (meta.name === 'robots' && meta.content.toLowerCase().includes('noindex')) {
+			pageData.hasNoindex = true
+		}
+		if (meta.property?.startsWith('og:')) {
+			const key = meta.property.replace('og:', '')
+			pageData.openGraph[key] = { content: meta.content, line: meta.line }
+		}
+		if ((meta.name ?? meta.property ?? '').startsWith('twitter:')) {
+			const key = (meta.name ?? meta.property ?? '').replace('twitter:', '')
+			pageData.twitterCard[key] = { content: meta.content, line: meta.line }
+		}
+	}
+}
+function extractCanonical(head: ParsedHTMLElement, html: string, lineIndex: number[]): ExtractedPageData['canonical'] {
+	const link = head.querySelector('link[rel="canonical"]')
+	if (!link) return undefined
+	const href = link.getAttribute('href')
+	if (!href) return undefined
+	const findLine = createLineFinder(html, lineIndex)
+	return { href, line: findLine('rel="canonical"') }
+}
+function extractJsonLd(root: ParsedHTMLElement, html: string, lineIndex: number[]): JsonLdData[] {
+	const entries: JsonLdData[] = []
+	const findLine = createLineFinder(html, lineIndex)
+	for (const script of root.querySelectorAll('script[type="application/ld+json"]')) {
+		const raw = script.textContent?.trim() || ''
+		if (!raw) continue
+		const line = findLine('application/ld+json')
+		try {
+			const data = JSON.parse(raw)
+			entries.push({ type: data['@type'] || 'Unknown', raw, valid: true, line })
+		} catch (e) {
+			entries.push({
+				type: 'Unknown',
+				raw,
+				valid: false,
+				error: e instanceof Error ? e.message : String(e),
+				line,
+			})
+		}
+	}
+	return entries
+}
+function extractHeadings(body: ParsedHTMLElement, html: string, lineIndex: number[]): HeadingData[] {
+	const headings: HeadingData[] = []
+	const findLine = createLineFinder(html, lineIndex)
+	for (const el of body.querySelectorAll('h1, h2, h3, h4, h5, h6')) {
+		const tag = el.tagName?.toLowerCase() || ''
+		const level = parseInt(tag.replace('h', ''), 10)
+		if (Number.isNaN(level)) continue
+		headings.push({
+			level,
+			text: el.textContent?.trim() || '',
+			line: findLine(el.toString().substring(0, 40)),
+		})
+	}
+	return headings
+}
+function extractImages(root: ParsedHTMLElement, html: string, lineIndex: number[]): ImageData[] {
+	const images: ImageData[] = []
+	const findLine = createLineFinder(html, lineIndex)
+	for (const img of root.querySelectorAll('img')) {
+		images.push({
+			src: img.getAttribute('src') || '',
+			alt: img.getAttribute('alt') ?? undefined,
+			loading: img.getAttribute('loading') || undefined,
+			line: findLine(img.toString().substring(0, 60)),
+		})
+	}
+	return images
+}
+function extractLinks(body: ParsedHTMLElement, html: string, lineIndex: number[]): LinkData[] {
+	const links: LinkData[] = []
+	const findLine = createLineFinder(html, lineIndex)
+	for (const a of body.querySelectorAll('a')) {
+		links.push({
+			href: a.getAttribute('href') || '',
+			text: a.textContent?.trim() || '',
+			rel: a.getAttribute('rel') || undefined,
+			line: findLine(a.toString().substring(0, 60)),
+		})
+	}
+	return links
+}
+function extractScripts(root: ParsedHTMLElement, html: string, lineIndex: number[]): ScriptData[] {
+	const scripts: ScriptData[] = []
+	const findLine = createLineFinder(html, lineIndex)
+	for (const script of root.querySelectorAll('script')) {
+		const src = script.getAttribute('src') || undefined
+		const content = script.textContent ?? ''
+		const isInline = !src && content.trim().length > 0
+		scripts.push({
+			src,
+			type: script.getAttribute('type') || undefined,
+			isAsync: script.hasAttribute('async'),
+			isDefer: script.hasAttribute('defer'),
+			isInline,
+			size: isInline ? Buffer.byteLength(content, 'utf8') : 0,
+			line: findLine(script.toString().substring(0, 60)),
+		})
+	}
+	return scripts
+}
+function extractStylesheets(head: ParsedHTMLElement, html: string, lineIndex: number[]): StylesheetData[] {
+	const stylesheets: StylesheetData[] = []
+	const findLine = createLineFinder(html, lineIndex)
+	for (const link of head.querySelectorAll('link[rel="stylesheet"]')) {
+		const href = link.getAttribute('href')
+		if (!href) continue
+		stylesheets.push({
+			href,
+			media: link.getAttribute('media') || undefined,
+			line: findLine(link.toString().substring(0, 60)),
+		})
+	}
+	return stylesheets
+}
+function extractForms(body: ParsedHTMLElement, html: string, lineIndex: number[]): ExtractedFormData[] {
+	const forms: ExtractedFormData[] = []
+	const findLine = createLineFinder(html, lineIndex)
+	for (const form of body.querySelectorAll('form')) {
+		const inputs: ExtractedFormData['inputs'] = []
+		const inputFinder = createLineFinder(html, lineIndex)
+		for (const input of form.querySelectorAll('input, select, textarea')) {
+			const id = input.getAttribute('id')
+			const name = input.getAttribute('name')
+			const type = input.getAttribute('type') || input.tagName?.toLowerCase() || 'text'
+			// Skip hidden inputs (they don't need labels)
+			if (type === 'hidden' || type === 'submit' || type === 'button') continue
+			// Check for associated label
+			const hasLabel = !!(
+				(id && form.querySelector(`label[for="${id}"]`))
+				|| input.closest('label')
+				|| input.getAttribute('aria-label')
+				|| input.getAttribute('aria-labelledby')
+			)
+			inputs.push({
+				type,
+				name: name || undefined,
+				id: id || undefined,
+				hasLabel,
+				line: inputFinder(input.toString().substring(0, 60)),
+			})
+		}
+		forms.push({
+			inputs,
+			line: findLine(form.toString().substring(0, 40)),
+		})
+	}
+	return forms
+}