@nitpicker/core 0.4.1

package/lib/load-plugin-settings.d.ts

@@ -0,0 +1,40 @@
+import type { Config } from './types.js';
+/**
+ * Loads the analyze plugin configuration from the user's config file.
+ *
+ * Uses cosmiconfig to search the filesystem from `process.cwd()` upward
+ * for a Nitpicker configuration file. The external config format
+ * (`ConfigJSON` from `@nitpicker/types`) is normalized into the internal
+ * {@link Config} model:
+ *
+ * - `config.plugins.analyze` (object keyed by module name with settings)
+ *   is converted to an ordered `Plugin[]` array
+ * - Boolean `true` settings are normalized to empty objects `{}`
+ * - The config file path is attached to each plugin for relative path resolution
+ * @param defaultConfig - Optional partial config to merge as defaults.
+ *   Plugin lists are concatenated (defaults first, then discovered plugins).
+ * @returns Fully resolved {@link Config} with the `analyze` plugin list.
+ * @example
+ * ```ts
+ * // .nitpickerrc.json
+ * // {
+ * //   "plugins": {
+ * //     "analyze": {
+ * //       "@nitpicker/analyze-axe": { "lang": "ja" },
+ * //       "@nitpicker/analyze-markuplint": true
+ * //     }
+ * //   }
+ * // }
+ *
+ * const config = await loadPluginSettings();
+ * // config.analyze = [
+ * //   { name: '@nitpicker/analyze-axe', module: '@nitpicker/analyze-axe',
+ * //     configFilePath: '/path/to/.nitpickerrc.json', settings: { lang: 'ja' } },
+ * //   { name: '@nitpicker/analyze-markuplint', module: '@nitpicker/analyze-markuplint',
+ * //     configFilePath: '/path/to/.nitpickerrc.json', settings: {} },
+ * // ]
+ * ```
+ * @see {@link ./types.ts!Config} for the output type
+ * @see {@link ./types.ts!Plugin} for individual plugin entries
+ */
+export declare function loadPluginSettings(defaultConfig?: Partial<Config>): Promise<Config>;

package/lib/load-plugin-settings.js

@@ -0,0 +1,85 @@
+import { cosmiconfig } from 'cosmiconfig';
+import { discoverAnalyzePlugins } from './discover-analyze-plugins.js';
+/**
+ * The cosmiconfig module name used for config file discovery.
+ * Searches for: `.nitpickerrc`, `.nitpickerrc.json`, `.nitpickerrc.yaml`,
+ * `nitpicker.config.js`, `nitpicker.config.cjs`, or a `"nitpicker"` key
+ * in `package.json`.
+ */
+const MODULE_NAME = 'nitpicker';
+/**
+ * Loads the analyze plugin configuration from the user's config file.
+ *
+ * Uses cosmiconfig to search the filesystem from `process.cwd()` upward
+ * for a Nitpicker configuration file. The external config format
+ * (`ConfigJSON` from `@nitpicker/types`) is normalized into the internal
+ * {@link Config} model:
+ *
+ * - `config.plugins.analyze` (object keyed by module name with settings)
+ *   is converted to an ordered `Plugin[]` array
+ * - Boolean `true` settings are normalized to empty objects `{}`
+ * - The config file path is attached to each plugin for relative path resolution
+ * @param defaultConfig - Optional partial config to merge as defaults.
+ *   Plugin lists are concatenated (defaults first, then discovered plugins).
+ * @returns Fully resolved {@link Config} with the `analyze` plugin list.
+ * @example
+ * ```ts
+ * // .nitpickerrc.json
+ * // {
+ * //   "plugins": {
+ * //     "analyze": {
+ * //       "@nitpicker/analyze-axe": { "lang": "ja" },
+ * //       "@nitpicker/analyze-markuplint": true
+ * //     }
+ * //   }
+ * // }
+ *
+ * const config = await loadPluginSettings();
+ * // config.analyze = [
+ * //   { name: '@nitpicker/analyze-axe', module: '@nitpicker/analyze-axe',
+ * //     configFilePath: '/path/to/.nitpickerrc.json', settings: { lang: 'ja' } },
+ * //   { name: '@nitpicker/analyze-markuplint', module: '@nitpicker/analyze-markuplint',
+ * //     configFilePath: '/path/to/.nitpickerrc.json', settings: {} },
+ * // ]
+ * ```
+ * @see {@link ./types.ts!Config} for the output type
+ * @see {@link ./types.ts!Plugin} for individual plugin entries
+ */
+export async function loadPluginSettings(defaultConfig = {}) {
+    const explorer = cosmiconfig(MODULE_NAME);
+    const result = await explorer.search();
+    if (!result) {
+        const defaultPlugins = defaultConfig.analyze || [];
+        return {
+            analyze: defaultPlugins.length > 0 ? defaultPlugins : discoverAnalyzePlugins(),
+        };
+    }
+    const config = result.config;
+    const { isEmpty, filepath } = result;
+    if (!config || isEmpty) {
+        const defaultPlugins = defaultConfig.analyze || [];
+        return {
+            analyze: defaultPlugins.length > 0 ? defaultPlugins : discoverAnalyzePlugins(),
+        };
+    }
+    const analyzePlugins = [];
+    if (config.plugins && config.plugins.analyze) {
+        const moduleNames = Object.keys(config.plugins.analyze);
+        for (const name of moduleNames) {
+            if (!config.plugins.analyze[name]) {
+                continue;
+            }
+            const settings = config.plugins.analyze[name] === true ? {} : config.plugins.analyze[name];
+            analyzePlugins.push({
+                name,
+                module: name,
+                configFilePath: filepath,
+                settings,
+            });
+        }
+    }
+    const mergedPlugins = [...(defaultConfig.analyze || []), ...analyzePlugins];
+    return {
+        analyze: mergedPlugins.length > 0 ? mergedPlugins : discoverAnalyzePlugins(),
+    };
+}

package/lib/nitpicker.d.ts

@@ -0,0 +1,127 @@
+import type { AnalyzeOptions, Config, NitpickerEvent } from './types.js';
+import { TypedAwaitEventEmitter as EventEmitter } from '@d-zero/shared/typed-await-event-emitter';
+import { Archive } from '@nitpicker/crawler';
+export { definePlugin } from './hooks/define-plugin.js';
+/**
+ * Core orchestrator for running analyze plugins against a `.nitpicker` archive.
+ *
+ * Nitpicker opens an existing archive (produced by the crawler), loads the
+ * user's plugin configuration via cosmiconfig, then runs each plugin against
+ * every page in the archive. Results are stored back into the archive as
+ * `analysis/report`, `analysis/table`, and `analysis/violations`.
+ *
+ * ## Architecture decisions
+ *
+ * - **Worker threads for `eachPage`**: DOM-heavy analysis (JSDOM + axe-core,
+ *   markuplint, etc.) runs in isolated Worker threads so that a crashing plugin
+ *   cannot take down the main process and memory from JSDOM windows is reclaimed
+ *   when the Worker exits. See {@link ./worker/run-in-worker.ts!runInWorker}.
+ *
+ * - **Plugin-outer, page-inner loop**: Plugins are processed sequentially,
+ *   and for each plugin, pages are processed in parallel (limit: 50) using
+ *   a bounded Promise pool. This enables per-plugin progress tracking via
+ *   {@link https://www.npmjs.com/package/@d-zero/dealer | Lanes}.
+ *
+ * - **Cache layer**: Results are cached per `pluginName:url` using
+ *   `@d-zero/shared/cache` so that re-running analysis after a partial failure
+ *   skips already-processed pages. The cache is cleared at the start of each run.
+ * @example
+ * ```ts
+ * import { Nitpicker } from '@nitpicker/core';
+ *
+ * // Open an existing archive
+ * const nitpicker = await Nitpicker.open('./example.nitpicker');
+ *
+ * // Run all configured analyze plugins
+ * await nitpicker.analyze();
+ *
+ * // Or run only specific plugins by name
+ * await nitpicker.analyze(['@nitpicker/analyze-axe']);
+ *
+ * // Write updated archive back to disk
+ * await nitpicker.write();
+ * ```
+ * @see {@link ./types.ts!NitpickerEvent} for emitted events
+ * @see {@link ./types.ts!Config} for the resolved configuration model
+ */
+export declare class Nitpicker extends EventEmitter<NitpickerEvent> {
+    #private;
+    /** The underlying archive instance. */
+    get archive(): Archive;
+    /**
+     * @param archive - An opened {@link Archive} instance to analyze.
+     *   Use {@link Nitpicker.open} for a convenient static factory.
+     */
+    constructor(archive: Archive);
+    /**
+     * Runs all configured analyze plugins (or a filtered subset) against
+     * every page in the archive.
+     *
+     * Plugins are processed **sequentially** (one at a time), while pages
+     * within each plugin are processed in **parallel** (bounded to
+     * {@link CONCURRENCY_LIMIT}). This architecture enables per-plugin
+     * progress tracking via Lanes.
+     *
+     * The analysis proceeds in two phases:
+     *
+     * 1. **`eachPage` phase** - For each plugin with `eachPage`, spawns
+     *    Worker threads via a bounded Promise pool to analyze all pages.
+     *    Progress is displayed via Lanes if provided in options.
+     *
+     * 2. **`eachUrl` phase** - For all plugins with `eachUrl`, runs
+     *    sequentially in the main thread. These are lightweight checks
+     *    that don't need DOM access.
+     *
+     * On completion, three data entries are stored in the archive:
+     * - `analysis/report` - Full {@link Report} with headers, data, and violations
+     * - `analysis/table` - The raw {@link Table} instance (serialized)
+     * - `analysis/violations` - Flat array of all {@link Violation} records
+     * @param filter - Optional list of plugin module names to run.
+     *   If omitted, all configured plugins are executed.
+     * @param options - Optional settings for progress display.
+     * @example
+     * ```ts
+     * // Run all plugins
+     * await nitpicker.analyze();
+     *
+     * // Run only axe and markuplint with Lanes progress
+     * await nitpicker.analyze(
+     *   ['@nitpicker/analyze-axe', '@nitpicker/analyze-markuplint'],
+     *   { lanes },
+     * );
+     * ```
+     */
+    analyze(filter?: string[], options?: AnalyzeOptions): Promise<void>;
+    /**
+     * Loads and caches the plugin configuration from the user's config file.
+     *
+     * Uses cosmiconfig to search for `.nitpickerrc`, `.nitpickerrc.json`,
+     * `nitpicker.config.js`, or a `nitpicker` key in `package.json`.
+     * The result is cached after the first call.
+     * @returns Resolved {@link Config} with the `analyze` plugin list.
+     */
+    getConfig(): Promise<Config>;
+    /**
+     * Writes the archive (including any new analysis results) to disk
+     * as a `.nitpicker` tar file, then emits a `writeFile` event.
+     * @fires NitpickerEvent#writeFile
+     */
+    write(): Promise<void>;
+    /**
+     * Opens an existing `.nitpicker` archive file and returns a ready-to-use
+     * Nitpicker instance.
+     *
+     * This is the recommended way to create a Nitpicker instance. It extracts
+     * the archive to a temporary directory, opens the SQLite database, and
+     * enables plugin data access.
+     * @param filePath - Path to the `.nitpicker` archive file.
+     * @returns A new Nitpicker instance backed by the opened archive.
+     * @example
+     * ```ts
+     * const nitpicker = await Nitpicker.open('./site.nitpicker');
+     * await nitpicker.analyze();
+     * await nitpicker.write();
+     * ```
+     */
+    static open(filePath: string): Promise<Nitpicker>;
+}

package/lib/nitpicker.js

@@ -0,0 +1,338 @@
+import os from 'node:os';
+import path from 'node:path';
+import { Cache } from '@d-zero/shared/cache';
+import { TypedAwaitEventEmitter as EventEmitter } from '@d-zero/shared/typed-await-event-emitter';
+import { Archive } from '@nitpicker/crawler';
+import c from 'ansi-colors';
+import { importModules } from './import-modules.js';
+import { loadPluginSettings } from './load-plugin-settings.js';
+import { Table } from './table.js';
+import { UrlEventBus } from './url-event-bus.js';
+import { runInWorker } from './worker/run-in-worker.js';
+export { definePlugin } from './hooks/define-plugin.js';
+const __filename = new URL(import.meta.url).pathname;
+const __dirname = path.dirname(__filename);
+/**
+ * Resolved path to the compiled Worker entry point.
+ * This file is loaded by `runInWorker()` in a `new Worker(...)` call.
+ * @see {@link ./page-analysis-worker.ts} for the source
+ */
+const pageAnalysisWorkerPath = path.resolve(__dirname, 'page-analysis-worker.js');
+/** Maximum number of concurrent Worker threads per plugin. */
+const CONCURRENCY_LIMIT = 50;
+/**
+ * Core orchestrator for running analyze plugins against a `.nitpicker` archive.
+ *
+ * Nitpicker opens an existing archive (produced by the crawler), loads the
+ * user's plugin configuration via cosmiconfig, then runs each plugin against
+ * every page in the archive. Results are stored back into the archive as
+ * `analysis/report`, `analysis/table`, and `analysis/violations`.
+ *
+ * ## Architecture decisions
+ *
+ * - **Worker threads for `eachPage`**: DOM-heavy analysis (JSDOM + axe-core,
+ *   markuplint, etc.) runs in isolated Worker threads so that a crashing plugin
+ *   cannot take down the main process and memory from JSDOM windows is reclaimed
+ *   when the Worker exits. See {@link ./worker/run-in-worker.ts!runInWorker}.
+ *
+ * - **Plugin-outer, page-inner loop**: Plugins are processed sequentially,
+ *   and for each plugin, pages are processed in parallel (limit: 50) using
+ *   a bounded Promise pool. This enables per-plugin progress tracking via
+ *   {@link https://www.npmjs.com/package/@d-zero/dealer | Lanes}.
+ *
+ * - **Cache layer**: Results are cached per `pluginName:url` using
+ *   `@d-zero/shared/cache` so that re-running analysis after a partial failure
+ *   skips already-processed pages. The cache is cleared at the start of each run.
+ * @example
+ * ```ts
+ * import { Nitpicker } from '@nitpicker/core';
+ *
+ * // Open an existing archive
+ * const nitpicker = await Nitpicker.open('./example.nitpicker');
+ *
+ * // Run all configured analyze plugins
+ * await nitpicker.analyze();
+ *
+ * // Or run only specific plugins by name
+ * await nitpicker.analyze(['@nitpicker/analyze-axe']);
+ *
+ * // Write updated archive back to disk
+ * await nitpicker.write();
+ * ```
+ * @see {@link ./types.ts!NitpickerEvent} for emitted events
+ * @see {@link ./types.ts!Config} for the resolved configuration model
+ */
+export class Nitpicker extends EventEmitter {
+    /**
+     * The underlying archive instance providing access to the SQLite database
+     * and file storage. Injected via constructor or created by `Nitpicker.open()`.
+     */
+    #archive;
+    /**
+     * Lazily loaded and cached plugin configuration.
+     * `null` until `getConfig()` is first called.
+     */
+    #config = null;
+    /** The underlying archive instance. */
+    get archive() {
+        return this.#archive;
+    }
+    /**
+     * @param archive - An opened {@link Archive} instance to analyze.
+     *   Use {@link Nitpicker.open} for a convenient static factory.
+     */
+    constructor(archive) {
+        super();
+        this.#archive = archive;
+    }
+    /**
+     * Runs all configured analyze plugins (or a filtered subset) against
+     * every page in the archive.
+     *
+     * Plugins are processed **sequentially** (one at a time), while pages
+     * within each plugin are processed in **parallel** (bounded to
+     * {@link CONCURRENCY_LIMIT}). This architecture enables per-plugin
+     * progress tracking via Lanes.
+     *
+     * The analysis proceeds in two phases:
+     *
+     * 1. **`eachPage` phase** - For each plugin with `eachPage`, spawns
+     *    Worker threads via a bounded Promise pool to analyze all pages.
+     *    Progress is displayed via Lanes if provided in options.
+     *
+     * 2. **`eachUrl` phase** - For all plugins with `eachUrl`, runs
+     *    sequentially in the main thread. These are lightweight checks
+     *    that don't need DOM access.
+     *
+     * On completion, three data entries are stored in the archive:
+     * - `analysis/report` - Full {@link Report} with headers, data, and violations
+     * - `analysis/table` - The raw {@link Table} instance (serialized)
+     * - `analysis/violations` - Flat array of all {@link Violation} records
+     * @param filter - Optional list of plugin module names to run.
+     *   If omitted, all configured plugins are executed.
+     * @param options - Optional settings for progress display.
+     * @example
+     * ```ts
+     * // Run all plugins
+     * await nitpicker.analyze();
+     *
+     * // Run only axe and markuplint with Lanes progress
+     * await nitpicker.analyze(
+     *   ['@nitpicker/analyze-axe', '@nitpicker/analyze-markuplint'],
+     *   { lanes },
+     * );
+     * ```
+     */
+    async analyze(filter, options) {
+        const config = await this.getConfig();
+        const plugins = filter
+            ? config.analyze.filter((plugin) => filter?.includes(plugin.name))
+            : config.analyze;
+        const analyzeMods = await importModules(plugins);
+        const lanes = options?.lanes;
+        const table = new Table();
+        for (const mod of analyzeMods) {
+            if (!mod.headers) {
+                continue;
+            }
+            if (!mod.eachPage) {
+                continue;
+            }
+            table.addHeaders(mod.headers);
+        }
+        const allViolations = [];
+        const cache = new Cache('nitpicker-axe', path.join(os.tmpdir(), 'nitpicker/cache/table'));
+        await cache.clear();
+        // Build plugin metadata: lane IDs and display labels
+        const eachPagePlugins = [];
+        for (const [i, plugin] of plugins.entries()) {
+            if (analyzeMods[i]?.eachPage) {
+                eachPagePlugins.push({ plugin, modIndex: i });
+            }
+        }
+        const pluginLaneIds = new Map();
+        const pluginLabels = new Map();
+        const pluginCompletionDetails = new Map();
+        for (const [laneId, { plugin, modIndex }] of eachPagePlugins.entries()) {
+            pluginLaneIds.set(plugin.name, laneId);
+            pluginLabels.set(plugin.name, analyzeMods[modIndex]?.label ?? plugin.name);
+        }
+        // Initialize all lanes as Waiting
+        for (const [name, id] of pluginLaneIds) {
+            const label = pluginLabels.get(name) ?? name;
+            lanes?.update(id, c.dim(`${label}: Waiting...`));
+        }
+        await this.archive.getPagesWithRefs(100_000, async (pages) => {
+            const urlEmitter = new UrlEventBus();
+            // Phase 1: eachPage plugins (sequentially, pages in parallel)
+            for (const [pluginSeqIndex, { plugin }] of eachPagePlugins.entries()) {
+                const laneId = pluginLaneIds.get(plugin.name);
+                const label = pluginLabels.get(plugin.name) ?? plugin.name;
+                let done = 0;
+                let pluginViolationCount = 0;
+                const updateProgress = () => {
+                    const pluginPercent = Math.round((done / pages.length) * 100);
+                    const overallPercent = Math.round(((pluginSeqIndex + done / pages.length) / eachPagePlugins.length) * 100);
+                    lanes?.header(`[${pluginSeqIndex + 1}/${eachPagePlugins.length}] Analyzing (${overallPercent}%)`);
+                    lanes?.update(laneId, `${label}: ${done}/${pages.length} (${pluginPercent}%)%braille%`);
+                };
+                updateProgress();
+                // Bounded Promise pool (replaces deal())
+                const executing = new Set();
+                for (const [pageIndex, page] of pages.entries()) {
+                    const task = (async () => {
+                        const cacheKey = `${plugin.name}:${page.url.href}`;
+                        const cached = await cache.load(cacheKey);
+                        if (cached) {
+                            const { pages: cachedPages, violations } = cached;
+                            if (cachedPages) {
+                                table.addData(cachedPages);
+                            }
+                            if (violations) {
+                                allViolations.push(...violations);
+                                pluginViolationCount += violations.length;
+                            }
+                            done++;
+                            updateProgress();
+                            return;
+                        }
+                        const html = await page.getHtml();
+                        if (!html) {
+                            done++;
+                            updateProgress();
+                            return;
+                        }
+                        const report = await runInWorker({
+                            filePath: pageAnalysisWorkerPath,
+                            num: pageIndex,
+                            total: pages.length,
+                            emitter: urlEmitter,
+                            initialData: {
+                                plugin,
+                                pages: {
+                                    html,
+                                    url: page.url,
+                                },
+                            },
+                        });
+                        const tablePages = {};
+                        if (report?.page) {
+                            tablePages[page.url.href] = report.page;
+                            table.addDataToUrl(page.url, report.page);
+                        }
+                        await cache.store(cacheKey, {
+                            pages: Object.keys(tablePages).length > 0 ? tablePages : undefined,
+                            violations: report?.violations,
+                        });
+                        if (report?.violations) {
+                            allViolations.push(...report.violations);
+                            pluginViolationCount += report.violations.length;
+                        }
+                        done++;
+                        updateProgress();
+                    })();
+                    executing.add(task);
+                    task.then(() => executing.delete(task), () => executing.delete(task));
+                    if (executing.size >= CONCURRENCY_LIMIT) {
+                        await Promise.race(executing);
+                    }
+                }
+                await Promise.all(executing);
+                // Mark this plugin as Done
+                const detail = pluginViolationCount > 0
+                    ? `${pluginViolationCount} violations`
+                    : `${done} pages`;
+                pluginCompletionDetails.set(plugin.name, detail);
+                lanes?.update(laneId, c.green(`${label}: Done (${detail})`));
+                // Dim inactive lanes
+                for (const [name, id] of pluginLaneIds) {
+                    if (name === plugin.name) {
+                        continue;
+                    }
+                    const otherLabel = pluginLabels.get(name) ?? name;
+                    const completionDetail = pluginCompletionDetails.get(name);
+                    if (completionDetail) {
+                        lanes?.update(id, c.dim(`${otherLabel}: Done (${completionDetail})`));
+                    }
+                    else {
+                        lanes?.update(id, c.dim(`${otherLabel}: Waiting...`));
+                    }
+                }
+            }
+            // Phase 2: eachUrl plugins (main thread, sequential)
+            for (const page of pages) {
+                const url = page.url;
+                const isExternal = page.isExternal;
+                for (const mod of analyzeMods) {
+                    if (!mod.eachUrl) {
+                        continue;
+                    }
+                    const report = await mod.eachUrl({ url, isExternal });
+                    if (!report) {
+                        continue;
+                    }
+                    const { page: reportPage, violations } = report;
+                    if (reportPage) {
+                        table.addDataToUrl(url, reportPage);
+                    }
+                    if (violations) {
+                        allViolations.push(...violations);
+                    }
+                }
+            }
+        }, {
+            withRefs: false,
+        });
+        const report = {
+            name: 'general',
+            pageData: table.toJSON(),
+            violations: allViolations,
+        };
+        await this.archive.setData('analysis/report', report);
+        await this.archive.setData('analysis/table', table);
+        await this.archive.setData('analysis/violations', allViolations);
+    }
+    /**
+     * Loads and caches the plugin configuration from the user's config file.
+     *
+     * Uses cosmiconfig to search for `.nitpickerrc`, `.nitpickerrc.json`,
+     * `nitpicker.config.js`, or a `nitpicker` key in `package.json`.
+     * The result is cached after the first call.
+     * @returns Resolved {@link Config} with the `analyze` plugin list.
+     */
+    async getConfig() {
+        if (!this.#config) {
+            this.#config = await loadPluginSettings();
+        }
+        return this.#config;
+    }
+    /**
+     * Writes the archive (including any new analysis results) to disk
+     * as a `.nitpicker` tar file, then emits a `writeFile` event.
+     * @fires NitpickerEvent#writeFile
+     */
+    async write() {
+        await this.#archive.write();
+        await this.emit('writeFile', { filePath: this.#archive.filePath });
+    }
+    /**
+     * Opens an existing `.nitpicker` archive file and returns a ready-to-use
+     * Nitpicker instance.
+     *
+     * This is the recommended way to create a Nitpicker instance. It extracts
+     * the archive to a temporary directory, opens the SQLite database, and
+     * enables plugin data access.
+     * @param filePath - Path to the `.nitpicker` archive file.
+     * @returns A new Nitpicker instance backed by the opened archive.
+     * @example
+     * ```ts
+     * const nitpicker = await Nitpicker.open('./site.nitpicker');
+     * await nitpicker.analyze();
+     * await nitpicker.write();
+     * ```
+     */
+    static async open(filePath) {
+        const archive = await Archive.open({ filePath, openPluginData: true });
+        return new Nitpicker(archive);
+    }
+}

package/lib/page-analysis-worker.d.ts

@@ -0,0 +1,48 @@
+/**
+ * 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';
+/**
+ * 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 function <T extends string>(data: PageAnalysisWorkerData, urlEventBus: UrlEventBus, num: number, total: number): Promise<ReportPage<T> | null>;