@nitpicker/core 0.4.4 → 0.5.0

package/lib/core.d.ts

@@ -0,0 +1,5 @@
+export { Nitpicker } from './nitpicker.js';
+export { definePlugin } from './hooks/define-plugin.js';
+export { readPluginLabels } from './read-plugin-labels.js';
+export { runInWorker } from './worker/run-in-worker.js';
+export * from './types.js';

package/lib/core.js

@@ -0,0 +1,5 @@
+export { Nitpicker } from './nitpicker.js';
+export { definePlugin } from './hooks/define-plugin.js';
+export { readPluginLabels } from './read-plugin-labels.js';
+export { runInWorker } from './worker/run-in-worker.js';
+export * from './types.js';

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

@@ -1,4 +1,4 @@
-import type { Config } from './types.js';
+import type { Config, PluginOverrides } from './types.js';
 /**
  * Loads the analyze plugin configuration from the user's config file.
  *
@@ -13,6 +13,9 @@ import type { Config } from './types.js';
  * - 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).
+ * @param pluginOverrides - CLI-specified plugin setting overrides.
+ *   Values are shallow-merged into the matching plugin's settings,
+ *   with CLI values taking precedence over config-file values.
  * @returns Fully resolved {@link Config} with the `analyze` plugin list.
  * @example
  * ```ts
@@ -36,5 +39,6 @@ import type { Config } from './types.js';
  * ```
  * @see {@link ./types.ts!Config} for the output type
  * @see {@link ./types.ts!Plugin} for individual plugin entries
+ * @see {@link ./types.ts!PluginOverrides} for CLI override support
  */
-export declare function loadPluginSettings(defaultConfig?: Partial<Config>): Promise<Config>;
+export declare function loadPluginSettings(defaultConfig?: Partial<Config>, pluginOverrides?: PluginOverrides): Promise<Config>;

package/lib/load-plugin-settings.js

@@ -21,6 +21,9 @@ const MODULE_NAME = 'nitpicker';
  * - 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).
+ * @param pluginOverrides - CLI-specified plugin setting overrides.
+ *   Values are shallow-merged into the matching plugin's settings,
+ *   with CLI values taking precedence over config-file values.
  * @returns Fully resolved {@link Config} with the `analyze` plugin list.
  * @example
  * ```ts
@@ -44,22 +47,25 @@ const MODULE_NAME = 'nitpicker';
  * ```
  * @see {@link ./types.ts!Config} for the output type
  * @see {@link ./types.ts!Plugin} for individual plugin entries
+ * @see {@link ./types.ts!PluginOverrides} for CLI override support
  */
-export async function loadPluginSettings(defaultConfig = {}) {
+export async function loadPluginSettings(defaultConfig = {}, pluginOverrides = {}) {
     const explorer = cosmiconfig(MODULE_NAME);
     const result = await explorer.search();
     if (!result) {
         const defaultPlugins = defaultConfig.analyze || [];
+        const plugins = defaultPlugins.length > 0 ? defaultPlugins : discoverAnalyzePlugins();
         return {
-            analyze: defaultPlugins.length > 0 ? defaultPlugins : discoverAnalyzePlugins(),
+            analyze: applyPluginOverrides(plugins, pluginOverrides),
         };
     }
     const config = result.config;
     const { isEmpty, filepath } = result;
     if (!config || isEmpty) {
         const defaultPlugins = defaultConfig.analyze || [];
+        const plugins = defaultPlugins.length > 0 ? defaultPlugins : discoverAnalyzePlugins();
         return {
-            analyze: defaultPlugins.length > 0 ? defaultPlugins : discoverAnalyzePlugins(),
+            analyze: applyPluginOverrides(plugins, pluginOverrides),
         };
     }
     const analyzePlugins = [];
@@ -79,7 +85,41 @@ export async function loadPluginSettings(defaultConfig = {}) {
         }
     }
     const mergedPlugins = [...(defaultConfig.analyze || []), ...analyzePlugins];
+    const finalPlugins = mergedPlugins.length > 0 ? mergedPlugins : discoverAnalyzePlugins();
     return {
-        analyze: mergedPlugins.length > 0 ? mergedPlugins : discoverAnalyzePlugins(),
+        analyze: applyPluginOverrides(finalPlugins, pluginOverrides),
     };
 }
+/**
+ * Applies CLI-specified overrides to plugin settings.
+ *
+ * For each plugin in the list, if there is a matching entry in
+ * `overrides`, the override values are shallow-merged into the
+ * plugin's existing settings. CLI values take precedence over
+ * config-file values.
+ *
+ * **Limitation**: Merging is shallow (one level). Nested objects in
+ * the override will replace the entire config-file value, not deep-merge.
+ * @param plugins - The plugin list to apply overrides to.
+ * @param overrides - CLI-specified plugin setting overrides.
+ * @returns A new plugin array with overrides applied.
+ */
+function applyPluginOverrides(plugins, overrides) {
+    const overrideKeys = Object.keys(overrides);
+    if (overrideKeys.length === 0) {
+        return plugins;
+    }
+    return plugins.map((plugin) => {
+        const override = overrides[plugin.module];
+        if (!override) {
+            return plugin;
+        }
+        return {
+            ...plugin,
+            settings: {
+                ...plugin.settings,
+                ...override,
+            },
+        };
+    });
+}

package/lib/nitpicker.d.ts

@@ -1,4 +1,4 @@
-import type { AnalyzeOptions, Config, NitpickerEvent } from './types.js';
+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';
@@ -101,6 +101,16 @@ export declare class Nitpicker extends EventEmitter<NitpickerEvent> {
      * @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.

package/lib/nitpicker.js

@@ -73,6 +73,11 @@ export class Nitpicker extends EventEmitter {
      * `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;
@@ -179,57 +184,77 @@ export class Nitpicker extends EventEmitter {
                 updateProgress();
                 // Bounded Promise pool (replaces deal())
                 const executing = new Set();
+                let pluginPageDataCount = 0;
+                let pluginErrorCount = 0;
                 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);
+                        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;
                             }
-                            if (violations) {
-                                allViolations.push(...violations);
-                                pluginViolationCount += violations.length;
+                            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);
+                                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();
-                            return;
                         }
-                        const html = await page.getHtml();
-                        if (!html) {
+                        catch (error) {
+                            pluginErrorCount++;
                             done++;
                             updateProgress();
-                            return;
+                            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,
+                            });
                         }
-                        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));
@@ -238,6 +263,14 @@ export class Nitpicker extends EventEmitter {
                     }
                 }
                 await Promise.all(executing);
+                // 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`
@@ -267,16 +300,27 @@ export class Nitpicker extends EventEmitter {
                     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);
+                    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);
+                            }
+                        }
                     }
-                    if (violations) {
-                        allViolations.push(...violations);
+                    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,
+                        });
                     }
                 }
             }
@@ -302,10 +346,23 @@ export class Nitpicker extends EventEmitter {
      */
     async getConfig() {
         if (!this.#config) {
-            this.#config = await loadPluginSettings();
+            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.

package/lib/page-analysis-worker.js

@@ -85,9 +85,8 @@ export default async function (data, urlEventBus, 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;
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`[${plugin.name}] ${message}`);
     }
     finally {
         for (const key of domGlobalKeys) {

package/lib/types.d.ts

@@ -45,6 +45,42 @@ export interface AnalyzeOptions {
     /** When `true`, outputs plain-text progress lines instead of animated Lanes. */
     readonly verbose?: boolean;
 }
+/**
+ * CLI-specified overrides for individual plugin settings.
+ *
+ * These values are provided via CLI flags (e.g. `--search-keywords`,
+ * `--axe-lang`) and take precedence over settings loaded from the
+ * configuration file. Each key maps to a known `@nitpicker/analyze-*`
+ * plugin module name, and the value is a partial settings object that
+ * will be shallow-merged into the plugin's config-file settings.
+ *
+ * ## Adding CLI overrides for a new plugin
+ *
+ * 1. Add a property to this interface with the plugin module name as key
+ * 2. Add corresponding CLI flag(s) to `commandDef.flags` in `@nitpicker/cli/src/commands/analyze.ts`
+ * 3. Add flag-to-override mapping in `@nitpicker/cli/src/analyze/build-plugin-overrides.ts`
+ * 4. Update `README.md` analyze options table
+ * @see {@link ./load-plugin-settings.ts!loadPluginSettings} for the merge logic
+ */
+export interface PluginOverrides {
+    /** Overrides for `@nitpicker/analyze-search` plugin settings. */
+    '@nitpicker/analyze-search'?: {
+        /** Keywords to search for in page content. */
+        keywords?: string[];
+        /** CSS selector to narrow the search scope. */
+        scope?: string;
+    };
+    /** Overrides for `@nitpicker/analyze-main-contents` plugin settings. */
+    '@nitpicker/analyze-main-contents'?: {
+        /** CSS selector for main content detection. */
+        mainContentSelector?: string;
+    };
+    /** Overrides for `@nitpicker/analyze-axe` plugin settings. */
+    '@nitpicker/analyze-axe'?: {
+        /** BCP 47 language tag for locale. */
+        lang?: string;
+    };
+}
 /**
  * Internal configuration model used by {@link ../nitpicker.ts!Nitpicker}.
  *

package/lib/worker/run-in-worker.js

@@ -106,7 +106,12 @@ export function runInWorker(params) {
                     process.removeListener('uncaughtException', killWorker);
                     process.removeListener('uncaughtExceptionMonitor', killWorker);
                     process.removeListener('unhandledRejection', killWorker);
-                    resolve(message.result);
+                    if (message.error) {
+                        reject(new Error(message.error));
+                    }
+                    else {
+                        resolve(message.result);
+                    }
                 }
             });
         });

package/lib/worker/worker.js

@@ -43,11 +43,26 @@ emitter.on('url', (url) => {
         url,
     });
 });
-const result = await runner(data, emitter);
-if (!parentPort) {
-    throw new Error('Use in worker thread');
+try {
+    const result = await runner(data, emitter);
+    if (!parentPort) {
+        throw new Error('Use in worker thread');
+    }
+    parentPort.postMessage({
+        type: 'finish',
+        result,
+    });
+}
+catch (error) {
+    if (!parentPort) {
+        throw new Error('Use in worker thread');
+    }
+    const message = error instanceof Error ? error.message : String(error);
+    // eslint-disable-next-line no-console
+    console.error(`[worker] Fatal error: ${message}`);
+    parentPort.postMessage({
+        type: 'finish',
+        result: null,
+        error: message,
+    });
 }
-parentPort.postMessage({
-    type: 'finish',
-    result,
-});

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@nitpicker/core",
-	"version": "0.4.4",
+	"version": "0.5.0",
 	"description": "Plugin-based page analysis engine for Nitpicker",
 	"author": "D-ZERO",
 	"license": "Apache-2.0",
@@ -18,8 +18,8 @@
 	"type": "module",
 	"exports": {
 		".": {
-			"import": "./lib/index.js",
-			"types": "./lib/index.d.ts"
+			"import": "./lib/core.js",
+			"types": "./lib/core.d.ts"
 		}
 	},
 	"scripts": {
@@ -27,13 +27,13 @@
 		"clean": "tsc --build --clean"
 	},
 	"dependencies": {
-		"@d-zero/dealer": "1.6.3",
-		"@d-zero/shared": "0.20.0",
-		"@nitpicker/crawler": "0.4.4",
-		"@nitpicker/types": "0.4.4",
+		"@d-zero/dealer": "1.7.0",
+		"@d-zero/shared": "0.20.1",
+		"@nitpicker/crawler": "0.5.0",
+		"@nitpicker/types": "0.5.0",
 		"ansi-colors": "4.1.3",
 		"cosmiconfig": "9.0.0",
 		"jsdom": "28.1.0"
 	},
-	"gitHead": "7c9bad351d1a3f4eb6ea7233f7143140d0989ef2"
+	"gitHead": "607d06bd596a0270d7088f32373d7367eb47ea94"
 }