@nitpicker/core 0.4.1

package/src/import-modules.spec.ts

@@ -0,0 +1,150 @@
+import type { AnalyzePlugin, Plugin } from './types.js';
+
+import { describe, it, expect, vi } from 'vitest';
+
+vi.mock('./import-modules.js', async (importOriginal) => {
+	const original = await importOriginal<typeof import('./import-modules.js')>(); // eslint-disable-line @typescript-eslint/consistent-type-imports
+	return { importModules: original.importModules };
+});
+
+describe('importModules', () => {
+	it('imports and initializes a single plugin', async () => {
+		const mockPlugin: AnalyzePlugin = {
+			label: 'Test Plugin',
+			headers: { col: 'Column' },
+		};
+		const factory = vi.fn().mockReturnValue(mockPlugin);
+
+		vi.doMock('@nitpicker/analyze-fake-a', () => ({ default: factory }));
+
+		const { importModules } = await import('./import-modules.js');
+
+		const plugins: Plugin[] = [
+			{
+				name: '@nitpicker/analyze-fake-a',
+				module: '@nitpicker/analyze-fake-a',
+				configFilePath: '/path/to/config',
+				settings: { lang: 'ja' },
+			},
+		];
+
+		const result = await importModules(plugins);
+
+		expect(result).toHaveLength(1);
+		expect(result[0]).toBe(mockPlugin);
+		expect(factory).toHaveBeenCalledWith({ lang: 'ja' });
+	});
+
+	it('imports multiple plugins in parallel', async () => {
+		const pluginA: AnalyzePlugin = { label: 'A' };
+		const pluginB: AnalyzePlugin = { label: 'B' };
+		const factoryA = vi.fn().mockReturnValue(pluginA);
+		const factoryB = vi.fn().mockReturnValue(pluginB);
+
+		vi.doMock('@nitpicker/analyze-fake-b1', () => ({ default: factoryA }));
+		vi.doMock('@nitpicker/analyze-fake-b2', () => ({ default: factoryB }));
+
+		const { importModules } = await import('./import-modules.js');
+
+		const plugins: Plugin[] = [
+			{
+				name: '@nitpicker/analyze-fake-b1',
+				module: '@nitpicker/analyze-fake-b1',
+				configFilePath: '',
+			},
+			{
+				name: '@nitpicker/analyze-fake-b2',
+				module: '@nitpicker/analyze-fake-b2',
+				configFilePath: '',
+			},
+		];
+
+		const result = await importModules(plugins);
+
+		expect(result).toHaveLength(2);
+		expect(result[0]).toBe(pluginA);
+		expect(result[1]).toBe(pluginB);
+	});
+
+	it('passes undefined settings when not configured', async () => {
+		const factory = vi.fn().mockReturnValue({});
+
+		vi.doMock('@nitpicker/analyze-fake-c', () => ({ default: factory }));
+
+		const { importModules } = await import('./import-modules.js');
+
+		const plugins: Plugin[] = [
+			{
+				name: '@nitpicker/analyze-fake-c',
+				module: '@nitpicker/analyze-fake-c',
+				configFilePath: '',
+			},
+		];
+
+		await importModules(plugins);
+
+		expect(factory).toHaveBeenCalledWith(undefined);
+	});
+
+	it('handles async factory functions', async () => {
+		const pluginResult: AnalyzePlugin = {
+			label: 'Async Plugin',
+			headers: { score: 'Score' },
+		};
+		const factory = vi.fn().mockResolvedValue(pluginResult);
+
+		vi.doMock('@nitpicker/analyze-fake-d', () => ({ default: factory }));
+
+		const { importModules } = await import('./import-modules.js');
+
+		const plugins: Plugin[] = [
+			{
+				name: '@nitpicker/analyze-fake-d',
+				module: '@nitpicker/analyze-fake-d',
+				configFilePath: '',
+				settings: {},
+			},
+		];
+
+		const result = await importModules(plugins);
+
+		expect(result[0]).toBe(pluginResult);
+	});
+
+	it('returns empty array for empty plugin list', async () => {
+		const { importModules } = await import('./import-modules.js');
+		const result = await importModules([]);
+
+		expect(result).toEqual([]);
+	});
+
+	it('rejects plugin modules without the @nitpicker/analyze- prefix', async () => {
+		const { importModules } = await import('./import-modules.js');
+
+		const plugins: Plugin[] = [
+			{
+				name: 'malicious-plugin',
+				module: 'malicious-plugin',
+				configFilePath: '',
+			},
+		];
+
+		await expect(importModules(plugins)).rejects.toThrow(
+			'Unauthorized plugin module: "malicious-plugin". Plugin modules must start with "@nitpicker/analyze-".',
+		);
+	});
+
+	it('rejects plugin modules with a similar but incorrect prefix', async () => {
+		const { importModules } = await import('./import-modules.js');
+
+		const plugins: Plugin[] = [
+			{
+				name: 'tricky-plugin',
+				module: '@nitpicker/analyze',
+				configFilePath: '',
+			},
+		];
+
+		await expect(importModules(plugins)).rejects.toThrow('Unauthorized plugin module');
+	});
+});

package/src/import-modules.ts

@@ -0,0 +1,45 @@
+import type { AnalyzePlugin, Plugin } from './types.js';
+
+/**
+ * Allowed prefix for analyze plugin module names.
+ * Only modules starting with this prefix are permitted to be dynamically imported.
+ */
+const ALLOWED_PREFIX = '@nitpicker/analyze-';
+
+/**
+ * Dynamically imports and initializes all analyze plugin modules.
+ *
+ * For each plugin in the list:
+ * 1. Validates that `plugin.module` starts with `@nitpicker/analyze-`
+ * 2. Calls `import(plugin.module)` to load the npm package
+ * 3. Invokes the module's default export (a `PluginFactory` factory)
+ *    with the plugin's `settings`
+ * 4. Returns the resulting `AnalyzePlugin` instance
+ *
+ * All plugins are loaded in parallel via `Promise.all` for performance.
+ *
+ * This function is called both in the main thread (for `headers` and `eachUrl`)
+ * and inside each Worker thread (for `eachPage`). The Worker-side call is
+ * necessary because plugin modules may not be transferable across threads.
+ * @param plugins - Array of plugin definitions from the resolved config.
+ * @returns Array of initialized `AnalyzePlugin` instances, in the same order.
+ * @throws {Error} If any plugin module name does not start with `@nitpicker/analyze-`.
+ * @see {@link ./types.ts} for the `PluginFactory` factory function signature
+ * @see {@link ./page-analysis-worker.ts} for Worker-side usage
+ * @see {@link ./nitpicker.ts!Nitpicker.analyze} for main-thread usage
+ */
+export async function importModules(plugins: Plugin[]) {
+	const analyzeMods = await Promise.all(
+		plugins.map(async (plugin) => {
+			if (!plugin.module.startsWith(ALLOWED_PREFIX)) {
+				throw new Error(
+					`Unauthorized plugin module: "${plugin.module}". Plugin modules must start with "${ALLOWED_PREFIX}".`,
+				);
+			}
+			const mod = await import(plugin.module);
+			const factory = mod.default;
+			return factory(plugin.settings) as AnalyzePlugin;
+		}),
+	);
+	return analyzeMods;
+}

package/src/index.ts

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

package/src/load-plugin-settings.spec.ts

@@ -0,0 +1,192 @@
+import { cosmiconfig } from 'cosmiconfig';
+import { afterEach, describe, it, expect, vi } from 'vitest';
+
+vi.mock('cosmiconfig', () => ({
+	cosmiconfig: vi.fn(),
+}));
+
+vi.mock('./discover-analyze-plugins.js', () => ({
+	discoverAnalyzePlugins: vi.fn(() => []),
+}));
+
+import { discoverAnalyzePlugins } from './discover-analyze-plugins.js';
+import { loadPluginSettings } from './load-plugin-settings.js';
+
+afterEach(() => {
+	vi.mocked(discoverAnalyzePlugins).mockClear();
+});
+
+/**
+ * Set up the cosmiconfig mock to return a specific search result.
+ * @param result - The mock cosmiconfig search result, or null for no config found.
+ */
+function mockCosmiconfig(
+	result: { config: unknown; filepath: string; isEmpty?: boolean } | null,
+) {
+	vi.mocked(cosmiconfig).mockReturnValue({
+		search: vi.fn().mockResolvedValue(result),
+	} as never);
+}
+
+describe('loadPluginSettings', () => {
+	it('returns empty analyze array when no config found', async () => {
+		mockCosmiconfig(null);
+		const config = await loadPluginSettings();
+		expect(config.analyze).toEqual([]);
+	});
+
+	it('returns empty analyze array when config is empty', async () => {
+		mockCosmiconfig({ config: null, filepath: '/path/.nitpickerrc.json', isEmpty: true });
+		const config = await loadPluginSettings();
+		expect(config.analyze).toEqual([]);
+	});
+
+	it('returns empty analyze array when config has no plugins', async () => {
+		mockCosmiconfig({ config: {}, filepath: '/path/.nitpickerrc.json' });
+		const config = await loadPluginSettings();
+		expect(config.analyze).toEqual([]);
+	});
+
+	it('converts plugins.analyze object to Plugin array', async () => {
+		mockCosmiconfig({
+			config: {
+				plugins: {
+					analyze: {
+						'@nitpicker/analyze-axe': { lang: 'ja' },
+					},
+				},
+			},
+			filepath: '/path/.nitpickerrc.json',
+		});
+		const config = await loadPluginSettings();
+		expect(config.analyze).toHaveLength(1);
+		expect(config.analyze[0]).toEqual({
+			name: '@nitpicker/analyze-axe',
+			module: '@nitpicker/analyze-axe',
+			configFilePath: '/path/.nitpickerrc.json',
+			settings: { lang: 'ja' },
+		});
+	});
+
+	it('normalizes boolean true settings to empty object', async () => {
+		mockCosmiconfig({
+			config: {
+				plugins: {
+					analyze: {
+						'@nitpicker/analyze-markuplint': true,
+					},
+				},
+			},
+			filepath: '/path/.nitpickerrc.json',
+		});
+		const config = await loadPluginSettings();
+		expect(config.analyze[0].settings).toEqual({});
+	});
+
+	it('skips falsy plugin entries', async () => {
+		mockCosmiconfig({
+			config: {
+				plugins: {
+					analyze: {
+						'@nitpicker/analyze-axe': { lang: 'ja' },
+						'@nitpicker/analyze-disabled': false,
+					},
+				},
+			},
+			filepath: '/path/.nitpickerrc.json',
+		});
+		const config = await loadPluginSettings();
+		expect(config.analyze).toHaveLength(1);
+		expect(config.analyze[0].name).toBe('@nitpicker/analyze-axe');
+	});
+
+	it('merges defaultConfig analyze plugins before discovered plugins', async () => {
+		mockCosmiconfig({
+			config: {
+				plugins: {
+					analyze: {
+						'@nitpicker/analyze-axe': true,
+					},
+				},
+			},
+			filepath: '/path/.nitpickerrc.json',
+		});
+		const defaultPlugin = {
+			name: 'default-plugin',
+			module: 'default-plugin',
+			configFilePath: '/default',
+			settings: {},
+		};
+		const config = await loadPluginSettings({ analyze: [defaultPlugin] });
+		expect(config.analyze).toHaveLength(2);
+		expect(config.analyze[0].name).toBe('default-plugin');
+		expect(config.analyze[1].name).toBe('@nitpicker/analyze-axe');
+	});
+
+	it('spreads defaultConfig keys when no config found', async () => {
+		mockCosmiconfig(null);
+		const config = await loadPluginSettings({ analyze: [] });
+		expect(config.analyze).toEqual([]);
+	});
+
+	it('falls back to discoverAnalyzePlugins when no config found and no defaults', async () => {
+		const discovered = [
+			{
+				name: '@nitpicker/analyze-axe',
+				module: '@nitpicker/analyze-axe',
+				configFilePath: '',
+				settings: {},
+			},
+		];
+		vi.mocked(discoverAnalyzePlugins).mockReturnValue(discovered);
+		mockCosmiconfig(null);
+		const config = await loadPluginSettings();
+		expect(config.analyze).toEqual(discovered);
+	});
+
+	it('falls back to discoverAnalyzePlugins when config is empty', async () => {
+		const discovered = [
+			{
+				name: '@nitpicker/analyze-markuplint',
+				module: '@nitpicker/analyze-markuplint',
+				configFilePath: '',
+				settings: {},
+			},
+		];
+		vi.mocked(discoverAnalyzePlugins).mockReturnValue(discovered);
+		mockCosmiconfig({ config: null, filepath: '/path/.nitpickerrc.json', isEmpty: true });
+		const config = await loadPluginSettings();
+		expect(config.analyze).toEqual(discovered);
+	});
+
+	it('falls back to discoverAnalyzePlugins when config has no plugins section', async () => {
+		const discovered = [
+			{
+				name: '@nitpicker/analyze-axe',
+				module: '@nitpicker/analyze-axe',
+				configFilePath: '',
+				settings: {},
+			},
+		];
+		vi.mocked(discoverAnalyzePlugins).mockReturnValue(discovered);
+		mockCosmiconfig({ config: {}, filepath: '/path/.nitpickerrc.json' });
+		const config = await loadPluginSettings();
+		expect(config.analyze).toEqual(discovered);
+	});
+
+	it('does not fall back when config has plugins', async () => {
+		mockCosmiconfig({
+			config: {
+				plugins: {
+					analyze: {
+						'@nitpicker/analyze-axe': { lang: 'ja' },
+					},
+				},
+			},
+			filepath: '/path/.nitpickerrc.json',
+		});
+		const config = await loadPluginSettings();
+		expect(discoverAnalyzePlugins).not.toHaveBeenCalled();
+		expect(config.analyze).toHaveLength(1);
+	});
+});

package/src/load-plugin-settings.ts

@@ -0,0 +1,99 @@
+import type { Config, Plugin } from './types.js';
+import type { ConfigJSON } from '@nitpicker/types';
+
+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: Partial<Config> = {},
+): Promise<Config> {
+	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 as ConfigJSON;
+	const { isEmpty, filepath } = result;
+	if (!config || isEmpty) {
+		const defaultPlugins = defaultConfig.analyze || [];
+		return {
+			analyze: defaultPlugins.length > 0 ? defaultPlugins : discoverAnalyzePlugins(),
+		};
+	}
+
+	const analyzePlugins: Plugin[] = [];
+
+	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(),
+	};
+}