@nitpicker/core 0.24.0 → 0.25.0

package/lib/page-analysis-worker.js

@@ -1,68 +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 { JSDOM } from 'jsdom';
-import { importModules } from './import-modules.js';
-/**
- * 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 (data, urlEventBus, num, total) {
-    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',
-    });
-    try {
-        const report = await analyzeMod.eachPage({
-            url,
-            html,
-            window: dom.window,
-            num,
-            total,
-        });
-        return report ?? null;
-    }
-    catch (error) {
-        const message = error instanceof Error ? error.message : String(error);
-        throw new Error(`[${plugin.name}] ${message}`);
-    }
-    finally {
-        dom.window.close();
-    }
-}

package/lib/read-plugin-labels.d.ts

@@ -1,15 +0,0 @@
-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 declare function readPluginLabels(plugins: readonly Plugin[]): Promise<Map<string, string>>;

package/lib/read-plugin-labels.js

@@ -1,30 +0,0 @@
-/**
- * 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) {
-    const labels = new Map();
-    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/lib/table.d.ts

@@ -1,75 +0,0 @@
-import type { TableData, TableHeaders, TablePages } 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 declare class Table<T extends string> {
-    #private;
-    /**
-     * 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>): void;
-    /**
-     * 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>): void;
-    /**
-     * 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>): void;
-    /**
-     * Returns all row data as a plain object (serializable to JSON).
-     * @returns URL-keyed record of column data.
-     */
-    getData(): TablePages<T>;
-    /**
-     * 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): TableData<T> | undefined;
-    /**
-     * 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(): {
-        headers: Record<T, string>;
-        data: Record<string, TableData<T>>;
-    };
-}

package/lib/table.js

@@ -1,132 +0,0 @@
-/**
- * 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 {
-    /** Per-URL row data. Key is the URL href string. */
-    #data = new Map();
-    /** Column header definitions accumulated from all plugins. */
-    #headers = 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) {
-        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, data) {
-        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) {
-        const entries = Object.entries(headers);
-        for (const entry of entries) {
-            const [key, name] = entry;
-            this.#headers.set(key, name);
-        }
-    }
-    /**
-     * Returns all row data as a plain object (serializable to JSON).
-     * @returns URL-keyed record of column data.
-     */
-    getData() {
-        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) {
-        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, v) {
-        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(map) {
-    const entries = map.entries();
-    const object = {};
-    for (const entry of entries) {
-        const [k, v] = entry;
-        object[k] = v;
-    }
-    return object;
-}

package/lib/url-event-bus.d.ts

@@ -1,33 +0,0 @@
-import { TypedAwaitEventEmitter as EventEmitter } from '@d-zero/shared/typed-await-event-emitter';
-/**
- * Event map for {@link UrlEventBus}.
- *
- * Currently supports a single event type for URL discovery notifications.
- */
-export interface UrlEventBusEvent {
-    /**
-     * Emitted when a URL is discovered or being processed.
-     * The payload is the URL href string.
-     */
-    url: string;
-}
-/**
- * Typed event bus for URL discovery notifications.
- *
- * Used as a communication channel between Worker threads and the main thread:
- *
- * - **Inside Workers**: The each-page worker emits `'url'` events on a local
- *   UrlEventBus. The Worker thread entry point ({@link ./worker/worker.ts})
- *   listens for these and forwards them to the main thread via `parentPort.postMessage`.
- *
- * - **In the main thread**: {@link ./worker/worker-pool.ts!WorkerPool} routes
- *   `'url'` messages received from workers to the per-task UrlEventBus
- *   supplied by the caller.
- *
- * This indirection lets plugin code work the same way regardless of which
- * worker in the pool is currently processing a given page.
- * @see {@link ./worker/worker.ts} for worker-side forwarding
- * @see {@link ./worker/worker-pool.ts!WorkerPool} for main-thread routing
- */
-export declare class UrlEventBus extends EventEmitter<UrlEventBusEvent> {
-}

package/lib/url-event-bus.js

@@ -1,21 +0,0 @@
-import { TypedAwaitEventEmitter as EventEmitter } from '@d-zero/shared/typed-await-event-emitter';
-/**
- * Typed event bus for URL discovery notifications.
- *
- * Used as a communication channel between Worker threads and the main thread:
- *
- * - **Inside Workers**: The each-page worker emits `'url'` events on a local
- *   UrlEventBus. The Worker thread entry point ({@link ./worker/worker.ts})
- *   listens for these and forwards them to the main thread via `parentPort.postMessage`.
- *
- * - **In the main thread**: {@link ./worker/worker-pool.ts!WorkerPool} routes
- *   `'url'` messages received from workers to the per-task UrlEventBus
- *   supplied by the caller.
- *
- * This indirection lets plugin code work the same way regardless of which
- * worker in the pool is currently processing a given page.
- * @see {@link ./worker/worker.ts} for worker-side forwarding
- * @see {@link ./worker/worker-pool.ts!WorkerPool} for main-thread routing
- */
-export class UrlEventBus extends EventEmitter {
-}

package/lib/worker/runner.d.ts

@@ -1,25 +0,0 @@
-import type { WorkerData } from './types.js';
-import type { UrlEventBus } from '../url-event-bus.js';
-/**
- * Dynamically imports and executes a plugin worker module.
- *
- * This function is the final execution step in the worker pipeline:
- * 1. It `import()`s the module specified by `data.filePath`
- * 2. Calls the module's default export with the remaining data, emitter,
- *    and progress counters
- * 3. Returns the result
- *
- * The `filePath` field is deleted from `data` before passing it to the
- * module function, so the module only receives its own domain-specific data.
- *
- * This function is called from the Worker thread ({@link ./worker.ts}) for
- * every task delivered by the {@link ./worker-pool.ts!WorkerPool}.
- * @template I - Shape of the caller's initial data (minus the worker infrastructure fields).
- * @template R - Return type of the plugin module's default export.
- * @param data - Combined worker data containing the module path and plugin-specific payload.
- * @param emitter - Event emitter for URL discovery notifications (forwarded to the plugin).
- * @returns The result produced by the dynamically imported module.
- * @see {@link ./types.ts!WorkerData} for the data shape
- * @see {@link ../page-analysis-worker.ts} for a typical module loaded by this runner
- */
-export declare function runner<I extends Record<string, unknown>, R>(data: WorkerData<I>, emitter: UrlEventBus): Promise<R>;

package/lib/worker/runner.js

@@ -1,31 +0,0 @@
-/**
- * Dynamically imports and executes a plugin worker module.
- *
- * This function is the final execution step in the worker pipeline:
- * 1. It `import()`s the module specified by `data.filePath`
- * 2. Calls the module's default export with the remaining data, emitter,
- *    and progress counters
- * 3. Returns the result
- *
- * The `filePath` field is deleted from `data` before passing it to the
- * module function, so the module only receives its own domain-specific data.
- *
- * This function is called from the Worker thread ({@link ./worker.ts}) for
- * every task delivered by the {@link ./worker-pool.ts!WorkerPool}.
- * @template I - Shape of the caller's initial data (minus the worker infrastructure fields).
- * @template R - Return type of the plugin module's default export.
- * @param data - Combined worker data containing the module path and plugin-specific payload.
- * @param emitter - Event emitter for URL discovery notifications (forwarded to the plugin).
- * @returns The result produced by the dynamically imported module.
- * @see {@link ./types.ts!WorkerData} for the data shape
- * @see {@link ../page-analysis-worker.ts} for a typical module loaded by this runner
- */
-export async function runner(data, emitter) {
-    const { filePath, num, total } = data;
-    const mod = await import(filePath);
-    const fn = mod.default;
-    // @ts-expect-error
-    delete data.filePath;
-    const result = await fn(data, emitter, num, total);
-    return result;
-}

package/lib/worker/types.d.ts

@@ -1,23 +0,0 @@
-/**
- * Data payload sent inside a `task` message from {@link ./worker-pool.ts!WorkerPool} to a worker.
- *
- * This type merges the worker infrastructure fields (`filePath`, `num`, `total`)
- * with the caller-supplied initial data (`I`). The `filePath` points to the
- * module whose default export will be invoked by the {@link ../runner.ts!runner}.
- * @template I - Shape of the additional data the caller provides
- *   (e.g. {@link ../../page-analysis-worker.ts!PageAnalysisWorkerData}).
- * @see {@link ./worker-pool.ts!WorkerPool.run} for where this payload is constructed
- * @see {@link ./runner.ts!runner} for where it is consumed
- */
-export type WorkerData<I extends Record<string, unknown>> = {
-    /**
-     * Absolute path to the compiled JS module to `import()` and execute.
-     * The module must export a default function matching the
-     * `(data, emitter, num, total) => Promise<R>` signature.
-     */
-    filePath: string;
-    /** Zero-based index of the current item in the batch (for progress tracking). */
-    num: number;
-    /** Total number of items in the batch (for progress tracking). */
-    total: number;
-} & I;

package/lib/worker/types.js

@@ -1 +0,0 @@
-export {};

package/lib/worker/worker-pool.d.ts

@@ -1,82 +0,0 @@
-import type { UrlEventBus } from '../url-event-bus.js';
-/**
- * Per-task payload sent into the pool's `run()` method.
- * @template I - Shape of the per-task data merged into the worker message.
- */
-export interface PoolTaskParams<I extends Record<string, unknown>> {
-    /** Absolute path to the module to dynamically import inside the worker. */
-    readonly filePath: string;
-    /** Zero-based index of the current item (for progress display). */
-    readonly num: number;
-    /** Total number of items in the batch (for progress display). */
-    readonly total: number;
-    /** Event bus to receive `'url'` events forwarded from the worker. */
-    readonly emitter: UrlEventBus;
-    /** Plugin-specific data delivered to the dynamically imported module. */
-    readonly initialData: I;
-}
-/** Constructor options for {@link WorkerPool}. */
-export interface WorkerPoolOptions {
-    /** Number of long-lived worker threads to maintain. Must be >= 1. */
-    readonly size: number;
-    /** Absolute path to the worker entry script (compiled `worker.js`). */
-    readonly workerPath: string;
-}
-/**
- * Long-lived pool of Worker threads that share execution across many tasks.
- *
- * Replaces the previous "one worker per page" model where every analyzed page
- * paid the cost of spawning a new V8 isolate, importing JSDOM, importing the
- * plugin module, and tearing it all down. With the pool, each worker is
- * created once at the start of an analyze run and processes tasks via
- * message passing until the pool is terminated.
- *
- * ## Why this matters
- *
- * On a 750-page archive with `CONCURRENCY_LIMIT = 50`, the old model spawned
- * 50 workers nearly simultaneously and repeated this every time a worker
- * finished, producing recurring "boot waves" that drove peak memory above
- * 20GB. The pool model performs N initial boots and then reuses those V8
- * isolates for the rest of the run, eliminating the recurring cost entirely.
- *
- * ## Message protocol (Pool ↔ Worker)
- *
- * | Direction        | `type`        | Payload                          |
- * |------------------|---------------|----------------------------------|
- * | Pool → Worker    | `'task'`      | `{ taskId, data }`               |
- * | Pool → Worker    | `'shutdown'`  | (none)                           |
- * | Worker → Pool    | `'url'`       | `{ taskId, url }` (forwarded)    |
- * | Worker → Pool    | `'result'`    | `{ taskId, result, error? }`     |
- *
- * Each task carries a unique numeric `taskId` so that responses and URL
- * notifications from a worker can be routed back to the correct caller.
- */
-export declare class WorkerPool {
-    #private;
-    /**
-     * Constructs a pool with the given size and worker entry script.
-     * @param options - Pool size and worker entry script path.
-     */
-    constructor(options: WorkerPoolOptions);
-    /**
-     * Submits a task to the pool. Resolves with the worker's `result` payload
-     * once a worker has finished processing it. The task may be queued if all
-     * workers are currently busy.
-     * @template I - Shape of the per-task `initialData` payload.
-     * @template R - Expected result type returned by the worker module.
-     * @param params - Task payload (file path, batch indices, emitter, data).
-     * @returns The worker's result.
-     */
-    run<I extends Record<string, unknown>, R>(params: PoolTaskParams<I>): Promise<R>;
-    /**
-     * Rejects every queued or in-flight task, sends each worker a `shutdown`
-     * message, and awaits its exit. After this call returns, no further
-     * submissions are accepted.
-     *
-     * Pending tasks are rejected synchronously so callers waiting on
-     * `pool.run()` Promises do not hang. Workers handle the shutdown message
-     * by exiting cleanly; if that fails, {@link #shutdownSlot} forces
-     * termination after a 5 second timeout.
-     */
-    terminate(): Promise<void>;
-}