@nitpicker/core 0.23.1 → 0.25.0

package/lib/nitpicker.d.ts

@@ -1,150 +0,0 @@
-import type { AnalyzeOptions, Config, NitpickerEvent, PluginOverrides } 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 SQL-backed analysis violation
- * tables via the archive facade.
- *
- * ## Architecture decisions
- *
- * - **Worker pool per plugin**: Each plugin gets its own long-lived
- *   {@link ./worker/worker-pool.ts!WorkerPool}, sized by either the plugin's
- *   declared `concurrency` or {@link DEFAULT_CONCURRENCY} (CPU core count).
- *   Workers are spawned once and reused across every page, so the V8 isolate
- *   / JSDOM module / plugin module boot cost is paid only `concurrency`
- *   times per plugin instead of once per page.
- *
- * - **Plugin-outer, page-inner loop**: Plugins are processed sequentially.
- *   For each plugin, pages are submitted to that plugin's pool, which queues
- *   them and dispatches to idle workers. 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 — `Symbol.asyncDispose` closes it on scope exit
- * await using 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);
-    /**
-     * Enables `await using nitpicker = ...`. Delegates to the wrapped
-     * archive's `Symbol.asyncDispose` (i.e. {@link Archive.close}).
-     */
-    [Symbol.asyncDispose](): Promise<void>;
-    /**
-     * Runs all configured analyze plugins (or a filtered subset) against
-     * every page in the archive.
-     *
-     * Plugins are processed **sequentially** (one at a time). For each plugin,
-     * pages are processed in **parallel** through a dedicated long-lived
-     * {@link ./worker/worker-pool.ts!WorkerPool} sized either by the plugin's
-     * declared concurrency or by {@link DEFAULT_CONCURRENCY}. This architecture
-     * enables per-plugin progress tracking via Lanes.
-     *
-     * The analysis proceeds in up to two phases:
-     *
-     * 1. **`eachPage` phase** - For each plugin with `eachPage`, dispatches
-     *    page analysis tasks to the plugin's worker pool. 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, data entries are stored in the archive:
-     * - `analysis/report` - Full {@link Report} with headers and data
-     * - `analysis/table` - The raw {@link Table} instance (serialized)
-     * - SQL-backed analysis violation tables - Flat {@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>;
-    /**
-     * Sets CLI-specified plugin overrides that take precedence over
-     * config-file settings.
-     *
-     * Must be called before {@link getConfig} to take effect. If config
-     * has already been loaded, calling this method clears the cache so
-     * that the next `getConfig()` call re-loads with the new overrides.
-     * @param overrides - Plugin setting overrides from CLI flags.
-     */
-    setPluginOverrides(overrides: PluginOverrides): void;
-    /**
-     * 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.
-     * @param onExtractProgress - Forwarded to `Archive.open` — called during
-     *   the untar step with bytes read so far and the archive's total size
-     *   (issue #294: a large archive's extraction can take tens of seconds
-     *   with no other signal it isn't hung).
-     * @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, onExtractProgress?: (readBytes: number, totalBytes: number) => void): Promise<Nitpicker>;
-}

package/lib/nitpicker.js

@@ -1,437 +0,0 @@
-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 { getTableCacheRoot } from './get-table-cache-root.js';
-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 { WorkerPool } from './worker/worker-pool.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 per-page analysis module.
- * Each task posted to the pool carries this path so the worker can
- * dynamically import it (cached after first import).
- * @see {@link ./page-analysis-worker.ts} for the source
- */
-const pageAnalysisWorkerPath = path.resolve(__dirname, 'page-analysis-worker.js');
-/**
- * Resolved path to the compiled long-lived worker thread script.
- * Used as the `workerPath` when constructing {@link WorkerPool} instances.
- */
-const workerPath = path.resolve(__dirname, 'worker/worker.js');
-/**
- * Default concurrency used when a plugin does not declare its own value.
- * Tracks the number of CPU cores so that worker pools scale with the host.
- */
-const DEFAULT_CONCURRENCY = Math.max(1, os.cpus().length);
-/**
- * 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 SQL-backed analysis violation
- * tables via the archive facade.
- *
- * ## Architecture decisions
- *
- * - **Worker pool per plugin**: Each plugin gets its own long-lived
- *   {@link ./worker/worker-pool.ts!WorkerPool}, sized by either the plugin's
- *   declared `concurrency` or {@link DEFAULT_CONCURRENCY} (CPU core count).
- *   Workers are spawned once and reused across every page, so the V8 isolate
- *   / JSDOM module / plugin module boot cost is paid only `concurrency`
- *   times per plugin instead of once per page.
- *
- * - **Plugin-outer, page-inner loop**: Plugins are processed sequentially.
- *   For each plugin, pages are submitted to that plugin's pool, which queues
- *   them and dispatches to idle workers. 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 — `Symbol.asyncDispose` closes it on scope exit
- * await using 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;
-    /**
-     * CLI-specified plugin setting overrides.
-     * Passed to `loadPluginSettings()` to merge with config-file settings.
-     */
-    #pluginOverrides = {};
-    /** 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;
-    }
-    /**
-     * Enables `await using nitpicker = ...`. Delegates to the wrapped
-     * archive's `Symbol.asyncDispose` (i.e. {@link Archive.close}).
-     */
-    async [Symbol.asyncDispose]() {
-        await this.#archive.close();
-    }
-    /**
-     * Runs all configured analyze plugins (or a filtered subset) against
-     * every page in the archive.
-     *
-     * Plugins are processed **sequentially** (one at a time). For each plugin,
-     * pages are processed in **parallel** through a dedicated long-lived
-     * {@link ./worker/worker-pool.ts!WorkerPool} sized either by the plugin's
-     * declared concurrency or by {@link DEFAULT_CONCURRENCY}. This architecture
-     * enables per-plugin progress tracking via Lanes.
-     *
-     * The analysis proceeds in up to two phases:
-     *
-     * 1. **`eachPage` phase** - For each plugin with `eachPage`, dispatches
-     *    page analysis tasks to the plugin's worker pool. 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, data entries are stored in the archive:
-     * - `analysis/report` - Full {@link Report} with headers and data
-     * - `analysis/table` - The raw {@link Table} instance (serialized)
-     * - SQL-backed analysis violation tables - Flat {@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', getTableCacheRoot());
-        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, modIndex }] 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();
-                const pluginConcurrency = Math.max(1, analyzeMods[modIndex]?.concurrency ?? DEFAULT_CONCURRENCY);
-                const pool = new WorkerPool({
-                    size: pluginConcurrency,
-                    workerPath,
-                });
-                let pluginPageDataCount = 0;
-                let pluginErrorCount = 0;
-                try {
-                    // Bound the number of in-flight IIFEs so HTML strings loaded
-                    // via page.getHtml() do not pile up on the main thread while
-                    // they wait for a worker. A small buffer above pool size keeps
-                    // the pool continuously fed without staging too much HTML.
-                    const inFlight = new Set();
-                    const highWater = pluginConcurrency * 2;
-                    for (const [pageIndex, page] of pages.entries()) {
-                        const task = (async () => {
-                            try {
-                                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);
-                                        pluginPageDataCount += Object.keys(cachedPages).length;
-                                    }
-                                    if (violations) {
-                                        for (const v of violations) {
-                                            allViolations.push(v);
-                                        }
-                                        pluginViolationCount += violations.length;
-                                    }
-                                    done++;
-                                    updateProgress();
-                                    return;
-                                }
-                                const html = await page.getHtml();
-                                if (!html) {
-                                    done++;
-                                    updateProgress();
-                                    return;
-                                }
-                                const report = await pool.run({
-                                    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);
-                                    pluginPageDataCount++;
-                                }
-                                await cache.store(cacheKey, {
-                                    pages: Object.keys(tablePages).length > 0 ? tablePages : undefined,
-                                    violations: report?.violations,
-                                });
-                                if (report?.violations) {
-                                    for (const v of report.violations) {
-                                        allViolations.push(v);
-                                    }
-                                    pluginViolationCount += report.violations.length;
-                                }
-                                done++;
-                                updateProgress();
-                            }
-                            catch (error) {
-                                pluginErrorCount++;
-                                done++;
-                                updateProgress();
-                                const message = error instanceof Error ? error.message : String(error);
-                                await this.emit('error', {
-                                    message: `[${plugin.name}] Failed to analyze ${page.url.href}: ${message}`,
-                                    error: error instanceof Error ? error : null,
-                                });
-                            }
-                        })();
-                        inFlight.add(task);
-                        task.then(() => inFlight.delete(task), () => inFlight.delete(task));
-                        if (inFlight.size >= highWater) {
-                            await Promise.race(inFlight);
-                        }
-                    }
-                    await Promise.all(inFlight);
-                }
-                finally {
-                    await pool.terminate();
-                }
-                // Warn when plugin produced no page data at all
-                if (pluginPageDataCount === 0 && pages.length > 0) {
-                    const errorDetail = pluginErrorCount > 0 ? ` (${pluginErrorCount} errors occurred)` : '';
-                    await this.emit('error', {
-                        message: `[${plugin.name}] Produced no data for ${pages.length} pages${errorDetail}. Check plugin configuration and HTML snapshots.`,
-                        error: null,
-                    });
-                }
-                // 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;
-                    }
-                    try {
-                        const report = await mod.eachUrl({ url, isExternal });
-                        if (!report) {
-                            continue;
-                        }
-                        const { page: reportPage, violations } = report;
-                        if (reportPage) {
-                            table.addDataToUrl(url, reportPage);
-                        }
-                        if (violations) {
-                            for (const v of violations) {
-                                allViolations.push(v);
-                            }
-                        }
-                    }
-                    catch (error) {
-                        const message = error instanceof Error ? error.message : String(error);
-                        await this.emit('error', {
-                            message: `[eachUrl] Failed to analyze ${url.href}: ${message}`,
-                            error: error instanceof Error ? error : null,
-                        });
-                    }
-                }
-            }
-        }, {
-            withRefs: false,
-        });
-        const report = {
-            name: 'general',
-            pageData: table.toJSON(),
-        };
-        await this.archive.setData('analysis/report', report);
-        await this.archive.setData('analysis/table', table);
-        await this.archive.replaceAnalysisViolations(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({}, this.#pluginOverrides);
-        }
-        return this.#config;
-    }
-    /**
-     * Sets CLI-specified plugin overrides that take precedence over
-     * config-file settings.
-     *
-     * Must be called before {@link getConfig} to take effect. If config
-     * has already been loaded, calling this method clears the cache so
-     * that the next `getConfig()` call re-loads with the new overrides.
-     * @param overrides - Plugin setting overrides from CLI flags.
-     */
-    setPluginOverrides(overrides) {
-        this.#pluginOverrides = overrides;
-        this.#config = null;
-    }
-    /**
-     * 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.
-     * @param onExtractProgress - Forwarded to `Archive.open` — called during
-     *   the untar step with bytes read so far and the archive's total size
-     *   (issue #294: a large archive's extraction can take tens of seconds
-     *   with no other signal it isn't hung).
-     * @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, onExtractProgress) {
-        const archive = await Archive.open({
-            filePath,
-            openPluginData: true,
-            onExtractProgress,
-        });
-        return new Nitpicker(archive);
-    }
-}

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

@@ -1,58 +0,0 @@
-/**
- * Worker thread module for per-page single-plugin execution.
- *
- * This is the default export loaded by {@link ./worker/runner.ts!runner}
- * for each task dispatched by the {@link ./worker/worker-pool.ts!WorkerPool}. It:
- *
- * 1. Dynamically imports the configured plugin via {@link importModules}
- *    (cached after the first task on the same worker)
- * 2. If the plugin implements `eachPage`:
- *    - Creates a JSDOM instance from the raw HTML, with `runScripts:
- *      'outside-only'` so that plugins can use `window.eval` to run
- *      DOM-scoped scripts (e.g. injecting a browser-oriented library that
- *      needs to bind to that specific window — see
- *      `@nitpicker/analyze-axe`'s `injectAxe`)
- *    - 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`
- *
- * One invocation processes exactly one plugin × one page, even though
- * the worker hosting this module handles many tasks over its lifetime.
- * `eachPage` plugins must not rely on `dom.window` being reachable from
- * `globalThis` — nothing exposes it there — and must not cache state that
- * outlives a single call, since the window backing it is closed once the
- * call returns.
- * @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.
- * Wrapped inside the `task` message dispatched by the {@link ./worker/worker-pool.ts!WorkerPool}
- * and consumed by this module's default export.
- *
- * Uses `type` instead of `interface` because this type must satisfy the
- * `Record<string, unknown>` constraint required by the Worker message 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>;