@nitpicker/core 0.4.1

package/src/page-analysis-worker.ts

@@ -0,0 +1,131 @@
+/**
+ * Worker thread module for per-page single-plugin execution.
+ *
+ * This is the default export loaded by {@link ./worker/runner.ts!runner}
+ * when analyzing a single page with a single plugin. It:
+ *
+ * 1. Dynamically imports the configured plugin via {@link importModules}
+ * 2. If the plugin implements `eachPage`:
+ *    - Creates a JSDOM instance from the raw HTML
+ *    - Calls the plugin's `eachPage` hook with the DOM window
+ *    - Closes the JSDOM window to free memory
+ * 3. Returns the plugin result as {@link ReportPage} or `null`
+ *
+ * Each Worker invocation handles exactly one plugin, so the calling code
+ * can track per-plugin progress independently.
+ * @module
+ */
+
+import type { Plugin, ReportPage } from './types.js';
+import type { UrlEventBus } from './url-event-bus.js';
+import type { ExURL as URL } from '@d-zero/shared/parse-url';
+
+import { JSDOM } from 'jsdom';
+
+import { importModules } from './import-modules.js';
+
+/**
+ * Set of critical Node.js global properties that must never be overwritten
+ * by JSDOM window properties.
+ */
+const PROTECTED_GLOBALS = new Set([
+	'process',
+	'global',
+	'globalThis',
+	'console',
+	'Buffer',
+	'setTimeout',
+	'setInterval',
+	'clearTimeout',
+	'clearInterval',
+	'setImmediate',
+	'clearImmediate',
+	'queueMicrotask',
+]);
+
+/**
+ * Initial data payload for the page analysis worker.
+ * Passed via `workerData` and consumed by the default export.
+ *
+ * Uses `type` instead of `interface` because this type must satisfy the
+ * `Record<string, unknown>` constraint required by the Worker data serialization.
+ */
+export type PageAnalysisWorkerData = {
+	/** Single analyze plugin to execute against the page. */
+	plugin: Plugin;
+	/** Page data containing raw HTML and parsed URL. */
+	pages: { html: string; url: URL };
+};
+
+/**
+ * Executes a single plugin's `eachPage` hook against a single page.
+ * @template T - Column key union from the plugin's headers.
+ * @param data - Contains the single plugin and page data (HTML + URL).
+ * @param urlEventBus - Event bus for URL discovery events (forwarded to the main thread).
+ * @param num - Zero-based index of the current page in the batch.
+ * @param total - Total number of pages being processed.
+ * @returns Report data from the plugin, or `null` if skipped.
+ * @see {@link ./worker/runner.ts!runner} for how this function is called
+ * @see {@link ./nitpicker.ts!Nitpicker.analyze} for the orchestration context
+ */
+export default async function <T extends string>(
+	data: PageAnalysisWorkerData,
+	urlEventBus: UrlEventBus,
+	num: number,
+	total: number,
+): Promise<ReportPage<T> | null> {
+	const {
+		plugin,
+		pages: { html, url },
+	} = data;
+	const [analyzeMod] = await importModules([plugin]);
+
+	if (!analyzeMod?.eachPage) {
+		return null;
+	}
+
+	await urlEventBus.emit('url', url.href);
+
+	const dom = new JSDOM(html, {
+		url: url.href,
+		runScripts: 'outside-only',
+	});
+
+	// Expose JSDOM globals so that browser-oriented libraries
+	// (axe-core, @medv/finder, etc.) that inspect the global scope
+	// can find `window`, `document`, `Node`, and other DOM APIs.
+	const g = globalThis as Record<string, unknown>;
+	const domGlobalKeys: string[] = [];
+	for (const key of Object.getOwnPropertyNames(dom.window)) {
+		if (key in g || PROTECTED_GLOBALS.has(key)) {
+			continue;
+		}
+		try {
+			g[key] = dom.window[key as keyof typeof dom.window];
+			domGlobalKeys.push(key);
+		} catch {
+			// Some window properties throw on access — skip them
+		}
+	}
+
+	try {
+		const report = await analyzeMod.eachPage({
+			url,
+			html,
+			window: dom.window,
+			num,
+			total,
+		});
+
+		return report ?? null;
+	} catch (error) {
+		// eslint-disable-next-line no-console
+		console.error(`[${plugin.name}] ${error instanceof Error ? error.message : error}`);
+		return null;
+	} finally {
+		for (const key of domGlobalKeys) {
+			delete g[key];
+		}
+		dom.window.close();
+	}
+}

package/src/read-plugin-labels.spec.ts

@@ -0,0 +1,151 @@
+import type { Plugin } from './types.js';
+
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+
+describe('readPluginLabels', () => {
+	beforeEach(() => {
+		vi.resetModules();
+	});
+
+	it('reads labels from plugins', async () => {
+		vi.doMock('label-plugin-a', () => ({
+			default: () => ({ label: 'axe: アクセシビリティチェック' }),
+		}));
+
+		const { readPluginLabels } = await import('./read-plugin-labels.js');
+
+		const plugins: Plugin[] = [
+			{
+				name: '@nitpicker/analyze-axe',
+				module: 'label-plugin-a',
+				configFilePath: '/config',
+			},
+		];
+
+		const labels = await readPluginLabels(plugins);
+
+		expect(labels.get('@nitpicker/analyze-axe')).toBe('axe: アクセシビリティチェック');
+	});
+
+	it('reads labels from multiple plugins', async () => {
+		vi.doMock('label-plugin-b1', () => ({
+			default: () => ({ label: 'Plugin B1' }),
+		}));
+		vi.doMock('label-plugin-b2', () => ({
+			default: () => ({ label: 'Plugin B2' }),
+		}));
+
+		const { readPluginLabels } = await import('./read-plugin-labels.js');
+
+		const plugins: Plugin[] = [
+			{ name: 'b1', module: 'label-plugin-b1', configFilePath: '' },
+			{ name: 'b2', module: 'label-plugin-b2', configFilePath: '' },
+		];
+
+		const labels = await readPluginLabels(plugins);
+
+		expect(labels.size).toBe(2);
+		expect(labels.get('b1')).toBe('Plugin B1');
+		expect(labels.get('b2')).toBe('Plugin B2');
+	});
+
+	it('skips plugins that lack a label', async () => {
+		vi.doMock('label-plugin-c', () => ({
+			default: () => ({ headers: { col: 'Column' } }),
+		}));
+
+		const { readPluginLabels } = await import('./read-plugin-labels.js');
+
+		const plugins: Plugin[] = [
+			{ name: 'no-label', module: 'label-plugin-c', configFilePath: '' },
+		];
+
+		const labels = await readPluginLabels(plugins);
+
+		expect(labels.size).toBe(0);
+	});
+
+	it('skips plugins whose import fails', async () => {
+		vi.doMock('label-plugin-broken', () => {
+			throw new Error('module not found');
+		});
+
+		const { readPluginLabels } = await import('./read-plugin-labels.js');
+
+		const plugins: Plugin[] = [
+			{ name: 'broken', module: 'label-plugin-broken', configFilePath: '' },
+		];
+
+		const labels = await readPluginLabels(plugins);
+
+		expect(labels.size).toBe(0);
+	});
+
+	it('skips plugins whose factory throws', async () => {
+		vi.doMock('label-plugin-throw', () => ({
+			default: () => {
+				throw new Error('factory error');
+			},
+		}));
+
+		const { readPluginLabels } = await import('./read-plugin-labels.js');
+
+		const plugins: Plugin[] = [
+			{ name: 'throw', module: 'label-plugin-throw', configFilePath: '' },
+		];
+
+		const labels = await readPluginLabels(plugins);
+
+		expect(labels.size).toBe(0);
+	});
+
+	it('passes settings and configFilePath to factory', async () => {
+		const factory = vi.fn().mockReturnValue({ label: 'Configured' });
+		vi.doMock('label-plugin-d', () => ({ default: factory }));
+
+		const { readPluginLabels } = await import('./read-plugin-labels.js');
+
+		const plugins: Plugin[] = [
+			{
+				name: 'configured',
+				module: 'label-plugin-d',
+				configFilePath: '/path/to/.nitpickerrc',
+				settings: { lang: 'ja' },
+			},
+		];
+
+		await readPluginLabels(plugins);
+
+		expect(factory).toHaveBeenCalledWith({ lang: 'ja' }, '/path/to/.nitpickerrc');
+	});
+
+	it('returns empty map for empty plugin list', async () => {
+		const { readPluginLabels } = await import('./read-plugin-labels.js');
+		const labels = await readPluginLabels([]);
+
+		expect(labels.size).toBe(0);
+	});
+
+	it('collects labels from working plugins even when some fail', async () => {
+		vi.doMock('label-plugin-good', () => ({
+			default: () => ({ label: 'Good Plugin' }),
+		}));
+		vi.doMock('label-plugin-bad', () => ({
+			default: () => {
+				throw new Error('bad');
+			},
+		}));
+
+		const { readPluginLabels } = await import('./read-plugin-labels.js');
+
+		const plugins: Plugin[] = [
+			{ name: 'good', module: 'label-plugin-good', configFilePath: '' },
+			{ name: 'bad', module: 'label-plugin-bad', configFilePath: '' },
+		];
+
+		const labels = await readPluginLabels(plugins);
+
+		expect(labels.size).toBe(1);
+		expect(labels.get('good')).toBe('Good Plugin');
+	});
+});

package/src/read-plugin-labels.ts

@@ -0,0 +1,37 @@
+import type { Plugin } from './types.js';
+
+/**
+ * Reads the `label` property from each plugin by importing and
+ * initializing the plugin module.
+ *
+ * Each plugin module's default export (a `PluginFactory`) is called
+ * with the plugin's configured settings. The resulting `AnalyzePlugin`
+ * object's `label` field is collected into a Map keyed by plugin name.
+ *
+ * Plugins that fail to import or initialize, or that lack a `label`,
+ * are silently skipped.
+ * @param plugins - Array of plugin definitions from the resolved config.
+ * @returns Map from plugin name to its human-readable label.
+ */
+export async function readPluginLabels(
+	plugins: readonly Plugin[],
+): Promise<Map<string, string>> {
+	const labels = new Map<string, string>();
+
+	await Promise.all(
+		plugins.map(async (plugin) => {
+			try {
+				const mod = await import(plugin.module);
+				const factory = mod.default;
+				const instance = await factory(plugin.settings ?? {}, plugin.configFilePath);
+				if (instance && typeof instance.label === 'string') {
+					labels.set(plugin.name, instance.label);
+				}
+			} catch {
+				// Module not importable or factory failed — skip
+			}
+		}),
+	);
+
+	return labels;
+}

package/src/table.spec.ts

@@ -0,0 +1,83 @@
+import { describe, it, expect } from 'vitest';
+
+import { Table } from './table.js';
+
+describe('Table', () => {
+	it('starts with empty headers and data', () => {
+		const table = new Table<'a'>();
+		const json = table.toJSON();
+		expect(json.headers).toEqual({});
+		expect(json.data).toEqual({});
+	});
+
+	it('addHeaders registers column headers', () => {
+		const table = new Table<'title' | 'score'>();
+		table.addHeaders({ title: 'Page Title', score: 'Score' });
+		const json = table.toJSON();
+		expect(json.headers).toEqual({ title: 'Page Title', score: 'Score' });
+	});
+
+	it('addHeaders merges headers from multiple calls', () => {
+		const table = new Table<'a' | 'b'>();
+		table.addHeaders({ a: 'A' } as Record<'a' | 'b', string>);
+		table.addHeaders({ b: 'B' } as Record<'a' | 'b', string>);
+		const json = table.toJSON();
+		expect(json.headers).toEqual({ a: 'A', b: 'B' });
+	});
+
+	it('addHeaders overwrites duplicate keys with the later value', () => {
+		const table = new Table<'x'>();
+		table.addHeaders({ x: 'First' });
+		table.addHeaders({ x: 'Second' });
+		expect(table.toJSON().headers).toEqual({ x: 'Second' });
+	});
+
+	it('addDataToUrl stores data for a URL', () => {
+		const table = new Table<'col'>();
+		const url = { href: 'https://example.com/' } as { href: string };
+		table.addDataToUrl(url, { col: { value: 'hello' } });
+		const json = table.toJSON();
+		expect(json.data['https://example.com/']).toEqual({ col: { value: 'hello' } });
+	});
+
+	it('addDataToUrl merges data for the same URL', () => {
+		const table = new Table<'a' | 'b'>();
+		const url = { href: 'https://example.com/' } as { href: string };
+		table.addDataToUrl(url, { a: { value: 1 } } as Record<'a' | 'b', { value: unknown }>);
+		table.addDataToUrl(url, { b: { value: 2 } } as Record<'a' | 'b', { value: unknown }>);
+		const data = table.toJSON().data['https://example.com/'];
+		expect(data).toEqual({ a: { value: 1 }, b: { value: 2 } });
+	});
+
+	it('addData stores batch data', () => {
+		const table = new Table<'col'>();
+		table.addData({
+			'https://a.com/': { col: { value: 'A' } },
+			'https://b.com/': { col: { value: 'B' } },
+		});
+		const json = table.toJSON();
+		expect(Object.keys(json.data)).toHaveLength(2);
+		expect(json.data['https://a.com/']).toEqual({ col: { value: 'A' } });
+	});
+
+	it('getData returns data as a plain object', () => {
+		const table = new Table<'col'>();
+		const url = { href: 'https://example.com/' } as { href: string };
+		table.addDataToUrl(url, { col: { value: 42 } });
+		const data = table.getData();
+		expect(data['https://example.com/']).toEqual({ col: { value: 42 } });
+	});
+
+	it('getDataByUrl returns data for a known URL', () => {
+		const table = new Table<'col'>();
+		const url = { href: 'https://example.com/' } as { href: string };
+		table.addDataToUrl(url, { col: { value: 'x' } });
+		expect(table.getDataByUrl(url)).toEqual({ col: { value: 'x' } });
+	});
+
+	it('getDataByUrl returns undefined for unknown URL', () => {
+		const table = new Table<'col'>();
+		const url = { href: 'https://unknown.com/' } as { href: string };
+		expect(table.getDataByUrl(url)).toBeUndefined();
+	});
+});

package/src/table.ts

@@ -0,0 +1,149 @@
+import type {
+	TableData,
+	TableHeaderMap,
+	TableHeaders,
+	TablePages,
+	TableRow,
+} from './types.js';
+import type { ExURL as URL } from '@d-zero/shared/parse-url';
+
+/**
+ * In-memory accumulator for tabular report data.
+ *
+ * Table collects column headers from plugins and per-URL row data from
+ * analysis results. It uses `Map` internally for efficient merge operations
+ * (multiple plugins contribute columns to the same URL row), then serializes
+ * to plain objects for JSON storage in the archive.
+ *
+ * ## Merge semantics
+ *
+ * When data is added for a URL that already has entries, the new columns are
+ * shallow-merged with existing ones (later values overwrite earlier ones for
+ * the same key). This allows multiple plugins to contribute different columns
+ * to the same row without conflicts, as long as they use distinct column keys.
+ * @template T - String literal union of all column keys across plugins.
+ * @example
+ * ```ts
+ * const table = new Table<'title' | 'score'>();
+ * table.addHeaders({ title: 'Page Title', score: 'Score' });
+ * table.addDataToUrl(url, {
+ *   title: { value: 'Home' },
+ *   score: { value: 95 },
+ * });
+ * const json = table.toJSON();
+ * // { headers: { title: 'Page Title', score: 'Score' }, data: { 'https://...': { ... } } }
+ * ```
+ * @see {@link ./types.ts} for the underlying type aliases
+ */
+export class Table<T extends string> {
+	/** Per-URL row data. Key is the URL href string. */
+	#data: TableRow<T> = new Map();
+
+	/** Column header definitions accumulated from all plugins. */
+	#headers: TableHeaderMap<T> = new Map();
+
+	/**
+	 * Merges a batch of URL-keyed page data into the table.
+	 * Typically called with deserialized data from a Worker thread or cache.
+	 * @param data - Object where keys are URL strings and values are column data.
+	 */
+	addData(data: TablePages<T>) {
+		const entries = Object.entries(data);
+		for (const [k, v] of entries) {
+			this.#add(k, v);
+		}
+	}
+
+	/**
+	 * Adds or merges column data for a single URL.
+	 * @param url - The page URL to associate the data with.
+	 * @param data - Column values to store for this URL.
+	 */
+	addDataToUrl(url: URL, data: TableData<T>) {
+		this.#add(url.href, data);
+	}
+
+	/**
+	 * Registers column headers from a plugin.
+	 *
+	 * Multiple plugins can call this independently; headers are merged by key.
+	 * If two plugins declare the same key with different labels, the later
+	 * registration wins.
+	 * @param headers - Map of column keys to display labels.
+	 */
+	addHeaders(headers: TableHeaders<T>) {
+		const entries = Object.entries(headers);
+		for (const entry of entries) {
+			const [key, name] = entry as [T, string];
+			this.#headers.set(key, name);
+		}
+	}
+
+	/**
+	 * Returns all row data as a plain object (serializable to JSON).
+	 * @returns URL-keyed record of column data.
+	 */
+	getData(): TablePages<T> {
+		return mapToObject(this.#data);
+	}
+
+	/**
+	 * Retrieves column data for a specific URL, or `undefined` if not present.
+	 * @param url - The page URL to look up.
+	 * @returns Column data for the URL, or `undefined`.
+	 */
+	getDataByUrl(url: URL) {
+		return this.#data.get(url.href);
+	}
+
+	/**
+	 * Serializes the entire table (headers + data) to a JSON-compatible object.
+	 *
+	 * Used when storing the table in the archive via `archive.setData('analysis/table', ...)`.
+	 * @returns Plain object with `headers` and `data` properties.
+	 */
+	toJSON() {
+		return {
+			headers: mapToObject(this.#headers),
+			data: mapToObject(this.#data),
+		};
+	}
+
+	/**
+	 * Internal merge-or-insert for a single URL row.
+	 * If the URL already has data, the new values are shallow-merged.
+	 * @param k - URL href string used as the row key.
+	 * @param v - Column data to add or merge.
+	 */
+	#add(k: string, v: TableData<T>) {
+		const data = this.#data.get(k);
+		if (data) {
+			this.#data.set(k, {
+				...data,
+				...v,
+			});
+		} else {
+			this.#data.set(k, v);
+		}
+	}
+}
+
+/**
+ * Converts a `Map<K, V>` to a plain `Record<K, V>` object.
+ *
+ * Used internally to serialize Map-based storage into JSON-compatible
+ * objects for archive storage and Worker message passing.
+ * @template K - String key type.
+ * @template V - Value type.
+ * @param map - The Map to convert.
+ * @returns A plain object with the same key-value pairs.
+ */
+function mapToObject<K extends string, V>(map: Map<K, V>) {
+	const entries = map.entries();
+	const object = {} as Record<K, V>;
+	for (const entry of entries) {
+		const [k, v] = entry;
+		object[k] = v;
+	}
+	return object;
+}