@nitpicker/analyze-lighthouse 0.4.1

package/src/index.ts

@@ -0,0 +1,228 @@
+import type { LHReport } from './types.js';
+import type { TableValue, Violation } from '@nitpicker/types';
+import type { Config } from 'lighthouse';
+
+import { definePlugin } from '@nitpicker/core';
+import * as chromeLauncher from 'chrome-launcher';
+import lighthouse from 'lighthouse';
+import { ReportUtils } from 'lighthouse/report/renderer/report-utils.js';
+
+/**
+ * Plugin options for the Lighthouse analysis.
+ */
+type Options = {
+	/**
+	 * Custom Lighthouse configuration object.
+	 * Passed directly to `lighthouse()` as the third argument,
+	 * allowing callers to override categories, throttling, etc.
+	 * @see https://github.com/GoogleChrome/lighthouse/blob/master/docs/configuration.md
+	 */
+	config?: unknown;
+};
+
+/**
+ * Per-URL index that accumulates Lighthouse scores and individual audit results.
+ * Keyed by URL string so that the final report can iterate over all analyzed pages.
+ */
+type IndexData = Record<
+	string,
+	{
+		/** Reserved for future structured detail strings. */
+		details: string[];
+		/** Category-level scores (0-100) keyed by category id. */
+		scores: Record<string, number>;
+		/** Individual audit results that did not pass. */
+		results: Result[];
+	}
+>;
+
+/**
+ * A single non-passing audit result extracted from the Lighthouse report.
+ */
+type Result = {
+	/** Rating level: `"fail"`, `"average"`, or `"error"`. */
+	severity: string;
+	/** Category title with optional group suffix (e.g. `"Performance(metrics)"`). */
+	rule: string;
+	/** Formatted score string (e.g. `"(Score: 45)"`). */
+	code: string;
+	/** Audit title, display value, and description concatenated. */
+	message: string;
+};
+
+/**
+ * Analyze plugin that runs Google Lighthouse against each page.
+ *
+ * A fresh Chrome instance is launched via `chrome-launcher` for every page
+ * because Lighthouse requires exclusive control of the browser's DevTools
+ * protocol. Sharing a browser across pages would cause protocol conflicts.
+ *
+ * The plugin evaluates the four standard Lighthouse categories:
+ * Performance, Accessibility, Best Practices, and SEO.
+ * Each category score (0-100) is reported as a separate column, and
+ * individual non-passing audits are collected as violations.
+ *
+ * When Lighthouse throws (e.g. navigation timeout), the plugin returns
+ * zero scores with an "Error" note rather than failing the entire analysis,
+ * so that partial results from other pages are preserved.
+ * @example
+ * ```jsonc
+ * // nitpicker.config.json
+ * {
+ *   "plugins": {
+ *     "analyze": {
+ *       "@nitpicker/analyze-lighthouse": {}
+ *     }
+ *   }
+ * }
+ * ```
+ */
+export default definePlugin((options: Options) => {
+	return {
+		label: 'Lighthouse: パフォーマンス監査',
+		headers: {
+			performance: 'Performance',
+			accessibility: 'Accessibility',
+			'best-practices': 'Best Practices',
+			seo: 'SEO',
+		},
+
+		async eachPage({ url }) {
+			const chrome = await chromeLauncher.launch({ chromeFlags: ['--headless'] });
+			const config = options.config as Config;
+			const reports: IndexData = {};
+
+			const result = await lighthouse(url.href, { port: chrome.port }, config).catch(
+				(error: unknown) => {
+					if (error instanceof Error) {
+						return error;
+					}
+					throw error;
+				},
+			);
+
+			if (!result || result instanceof Error) {
+				return {
+					page: {
+						performance: { value: 0, note: 'Error' },
+						accessibility: { value: 0, note: 'Error' },
+						'best-practices': { value: 0, note: 'Error' },
+						seo: { value: 0, note: 'Error' },
+					},
+				};
+			}
+
+			const report: LHReport = ReportUtils.prepareReportResult(result.lhr);
+
+			const scores: Record<string, number> = {};
+			for (const cat of Object.values(report.categories)) {
+				scores[cat.id] = Math.round(cat.score * 100);
+			}
+
+			const results: Result[] = [];
+			for (const cat of Object.values(report.categories)) {
+				for (const audit of cat.auditRefs) {
+					const result = audit.result;
+					if (
+						result.scoreDisplayMode === 'notApplicable' ||
+						result.scoreDisplayMode === 'error'
+					) {
+						continue;
+					}
+					const rating = ReportUtils.calculateRating(
+						result.score,
+						result.scoreDisplayMode,
+					) as 'pass' | 'average' | 'fail' | 'error';
+					if (rating === 'pass') {
+						continue;
+					}
+					const label = cat.title + (audit.group ? `(${audit.group})` : '');
+					const score = `(Score: ${Math.round(result.score * 100)})`;
+					const value = result.displayValue ? ` (${result.displayValue})` : '';
+					results.push({
+						severity: rating,
+						rule: label,
+						code: score,
+						message: `${result.title}:${value} ${result.description}`,
+					});
+				}
+			}
+
+			reports[url.href] = {
+				details: [],
+				scores,
+				results,
+			};
+
+			await chrome.kill();
+			type Header = {
+				performance: string;
+				accessibility: string;
+				'best-practices': string;
+				seo: string;
+			};
+
+			const data: Record<string, Record<keyof Header, TableValue>> = {};
+			const totalPoints: Record<keyof Header, number> = {
+				performance: 0,
+				accessibility: 0,
+				'best-practices': 0,
+				seo: 0,
+			};
+			const violations: Violation[] = [];
+			const pageList = Object.keys(reports);
+			for (const url of pageList) {
+				const scores = reports[url]?.scores ?? {};
+				data[url] = {
+					performance: { value: scores.performance ?? 0 },
+					accessibility: { value: scores.accessibility ?? 0 },
+					['best-practices']: { value: scores['best-practices'] ?? 0 },
+					seo: { value: scores.seo ?? 0 },
+				};
+				totalPoints.performance += scores.performance ?? 0;
+				totalPoints.accessibility += scores.accessibility ?? 0;
+				totalPoints['best-practices'] += scores['best-practices'] ?? 0;
+				totalPoints.seo += scores.seo ?? 0;
+				const results = reports[url]?.results ?? [];
+				violations.push(
+					...results.map((result) => ({
+						validator: 'lighthouse',
+						severity: result.severity,
+						rule: result.rule,
+						code: result.code,
+						message: result.message,
+						url,
+					})),
+				);
+			}
+			return {
+				page: {
+					performance: {
+						value: Math.round(report.categories.performance.score * 100),
+						note: report.categories.performance.auditRefs
+							.map((a) => `${a.result.title}: ${a.result.description}`)
+							.join('\n'),
+					},
+					accessibility: {
+						value: Math.round(report.categories.accessibility.score * 100),
+						note: report.categories.accessibility.auditRefs
+							.map((a) => `${a.result.title}: ${a.result.description}`)
+							.join('\n'),
+					},
+					'best-practices': {
+						value: Math.round(report.categories['best-practices'].score * 100),
+						note: report.categories['best-practices'].auditRefs
+							.map((a) => `${a.result.title}: ${a.result.description}`)
+							.join('\n'),
+					},
+					seo: {
+						value: Math.round(report.categories.seo.score * 100),
+						note: report.categories.seo.auditRefs
+							.map((a) => `${a.result.title}: ${a.result.description}`)
+							.join('\n'),
+					},
+				},
+			};
+		},
+	};
+});

package/src/types.ts

@@ -0,0 +1,189 @@
+/**
+ * Typed subset of a Lighthouse report produced by `Util.prepareReportResult()`.
+ *
+ * Only the five standard Lighthouse categories are included because
+ * the plugin creates dedicated score columns for each one.
+ * The `auditRefs` array carries the resolved `result` inline so that
+ * consumers can iterate category -> audit without an extra lookup.
+ */
+export type LHReport = {
+	categories: Record<
+		'performance' | 'accessibility' | 'best-practices' | 'seo' | 'pwa',
+		{
+			/** Machine-readable category identifier matching the record key. */
+			id: string;
+			/** Human-readable category title (e.g. "Performance"). */
+			title: string;
+			/** Markdown description of the category. */
+			description: string;
+			/** Description for audits that require manual verification. */
+			manualDescription: string;
+			/** Aggregate score for the category in the 0-1 range. */
+			score: number;
+			/** Ordered list of audits that contribute to this category. */
+			auditRefs: {
+				/** Audit identifier (e.g. `"first-contentful-paint"`). */
+				id: string;
+				/** Relative weight of this audit within the category score. */
+				weight: number;
+				/** Audit group label (e.g. `"metrics"`, `"opportunities"`). */
+				group?: string;
+				/** The resolved audit result, inlined by `prepareReportResult()`. */
+				result: ApplicableAuditResult | NotApplicableAuditResult | ErrorAuditResult;
+			}[];
+		}
+	>;
+};
+
+/**
+ * Base shape shared by all audit result variants.
+ */
+type AuditResult = {
+	/** Audit identifier. */
+	id: string;
+	/** Short human-readable title describing what the audit checks. */
+	title: string;
+	/** Markdown description with remediation guidance. */
+	description: string;
+};
+
+/**
+ * An audit that ran successfully and produced a numeric or binary score.
+ */
+type ApplicableAuditResult = AuditResult & {
+	/** Score in the 0-1 range. */
+	score: number;
+	/**
+	 * How the score should be displayed.
+	 * - `numeric` / `binary` produce pass/fail ratings.
+	 * - `manual` requires human verification.
+	 * - `informative` is shown for context only (no pass/fail).
+	 */
+	scoreDisplayMode: 'numeric' | 'binary' | 'manual' | 'informative';
+	/** Raw metric value in the audit's native unit (ms, bytes, etc.). */
+	numericValue: number;
+	/** Formatted display string (e.g. "1.2 s", "350 KiB"). */
+	displayValue: string;
+	/** Non-fatal warnings raised during the audit. */
+	warnings?: unknown[];
+	/** Detailed data table or opportunity breakdown. */
+	details?: OpportunityDetails | TableDetails;
+};
+
+/**
+ * An audit that was skipped because it does not apply to the page
+ * (e.g. no `<video>` elements for a video-related audit).
+ */
+type NotApplicableAuditResult = AuditResult & {
+	score: null;
+	scoreDisplayMode: 'notApplicable';
+};
+
+/**
+ * An audit that failed with an internal error.
+ */
+type ErrorAuditResult = AuditResult & {
+	score: null;
+	scoreDisplayMode: 'error';
+	/** Human-readable error message explaining why the audit failed. */
+	errorMessage: string;
+};
+
+/**
+ * Discriminant base for Lighthouse detail types.
+ */
+type Details = {
+	type: string;
+};
+
+/**
+ * A detail type that contains a table of items with column headings.
+ * Used as a base for both `opportunity` and `table` detail types.
+ */
+type HeadnessDetails = Details & {
+	headings: {
+		/** Key into each item record. */
+		key: string;
+		/** Display type (e.g. `"url"`, `"bytes"`, `"ms"`). */
+		valueType: string;
+		/** Column header label. */
+		label: string;
+	}[];
+	/** Row data; each record maps heading keys to cell values. */
+	items: Record<string, string | number | Code | Node>[];
+};
+
+/**
+ * An opportunity detail highlighting potential savings.
+ * The `overallSavingsMs` value drives the opportunity's display in the report.
+ */
+type OpportunityDetails = HeadnessDetails & {
+	type: 'opportunity';
+	/** Total estimated time savings in milliseconds. */
+	overallSavingsMs: number;
+	/** Total estimated transfer-size savings in bytes, if applicable. */
+	overallSavingsBytes?: number;
+};
+
+/**
+ * A simple tabular detail without savings metadata.
+ */
+type TableDetails = HeadnessDetails & {
+	type: 'table';
+};
+
+// type CriticalRequestChainDetails = Details & {
+// 	type: 'criticalrequestchain';
+// 	chains: Record<
+// 		string,
+// 		{
+// 			request: CriticalRequestChainRequest;
+// 			children: Record<
+// 				string,
+// 				{
+// 					request: CriticalRequestChainRequest;
+// 				}
+// 			>;
+// 		}
+// 	>;
+// 	longestChain: {
+// 		duration: number;
+// 		length: number;
+// 		transferSize: number;
+// 	};
+// };
+
+// type CriticalRequestChainRequest = {
+// 	url: string;
+// 	startTime: number;
+// 	endTime: number;
+// 	responseReceivedTime: number;
+// 	transferSize: number;
+// };
+
+/**
+ * An inline code snippet cell value within a Lighthouse detail table.
+ */
+type Code = {
+	type: 'code';
+	/** The raw code string (e.g. a CSS selector or JS expression). */
+	value: string;
+};
+
+/**
+ * A DOM node reference within a Lighthouse detail table.
+ * Provides enough context to locate and identify the element in DevTools.
+ */
+type Node = {
+	type: 'node';
+	/** CSS selector that uniquely identifies the element. */
+	selector: string;
+	/** DevTools-style DOM tree path (e.g. `"1,HTML,1,BODY,3,DIV"`). */
+	path: string;
+	/** Truncated outer HTML of the element. */
+	snippet: string;
+	/** Why this node was flagged by the audit. */
+	explanation: string;
+	/** Accessible label or text content of the node. */
+	nodeLabel: string;
+};

package/tsconfig.json

@@ -0,0 +1,11 @@
+{
+	"extends": "../../../tsconfig.json",
+	"compilerOptions": {
+		"composite": true,
+		"outDir": "./lib",
+		"rootDir": "./src"
+	},
+	"references": [{ "path": "../core" }],
+	"include": ["./src/**/*"],
+	"exclude": ["node_modules", "lib", "./src/**/*.spec.ts"]
+}