@nitpicker/core 0.4.1 → 0.4.3

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@nitpicker/core",
-	"version": "0.4.1",
+	"version": "0.4.3",
 	"description": "Plugin-based page analysis engine for Nitpicker",
 	"author": "D-ZERO",
 	"license": "Apache-2.0",
@@ -12,6 +12,9 @@
 	"publishConfig": {
 		"access": "public"
 	},
+	"files": [
+		"lib"
+	],
 	"type": "module",
 	"exports": {
 		".": {
@@ -26,11 +29,11 @@
 	"dependencies": {
 		"@d-zero/dealer": "1.6.3",
 		"@d-zero/shared": "0.20.0",
-		"@nitpicker/crawler": "0.4.1",
-		"@nitpicker/types": "0.4.1",
+		"@nitpicker/crawler": "0.4.3",
+		"@nitpicker/types": "0.4.3",
 		"ansi-colors": "4.1.3",
 		"cosmiconfig": "9.0.0",
 		"jsdom": "28.1.0"
 	},
-	"gitHead": "32b83ee38eba7dfd237adb1b41f69e049e8d4ceb"
+	"gitHead": "0f4ca55751be2f83dd5b6622c3502503fc7dfb41"
 }

package/CHANGELOG.md

@@ -1,8 +0,0 @@
-# Change Log
-
-All notable changes to this project will be documented in this file.
-See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
-
-## [0.4.1](https://github.com/d-zero-dev/nitpicker/compare/v0.4.0...v0.4.1) (2026-02-27)
-
-**Note:** Version bump only for package @nitpicker/core

package/src/discover-analyze-plugins.spec.ts

@@ -1,21 +0,0 @@
-import { describe, it, expect } from 'vitest';
-
-import { discoverAnalyzePlugins } from './discover-analyze-plugins.js';
-
-describe('discoverAnalyzePlugins', () => {
-	it('returns all standard analyze plugins', () => {
-		const plugins = discoverAnalyzePlugins();
-		expect(plugins.length).toBeGreaterThanOrEqual(6);
-		expect(plugins.map((p) => p.name)).toContain('@nitpicker/analyze-axe');
-		expect(plugins.map((p) => p.name)).toContain('@nitpicker/analyze-textlint');
-	});
-
-	it('returns plugins with empty default settings', () => {
-		const plugins = discoverAnalyzePlugins();
-		for (const plugin of plugins) {
-			expect(plugin.module).toBe(plugin.name);
-			expect(plugin.configFilePath).toBe('');
-			expect(plugin.settings).toEqual({});
-		}
-	});
-});

package/src/discover-analyze-plugins.ts

@@ -1,37 +0,0 @@
-import type { Plugin } from './types.js';
-
-/**
- * Standard analyze plugin module names bundled with the Nitpicker CLI.
- *
- * These are treated as built-in plugins and always available without
- * explicit configuration.
- */
-const STANDARD_ANALYZE_PLUGINS = [
-	'@nitpicker/analyze-axe',
-	'@nitpicker/analyze-lighthouse',
-	'@nitpicker/analyze-main-contents',
-	'@nitpicker/analyze-markuplint',
-	'@nitpicker/analyze-search',
-	'@nitpicker/analyze-textlint',
-] as const;
-
-/**
- * Returns the standard set of `@nitpicker/analyze-*` plugins
- * as {@link Plugin} entries with default (empty) settings.
- *
- * This is used as a fallback when no configuration file is found,
- * allowing `nitpicker analyze` to work out of the box without
- * requiring a `.nitpickerrc` file.
- *
- * All analyze plugins are treated as standard packages bundled
- * with the CLI, so no filesystem scanning is necessary.
- * @returns Array of standard analyze plugins with empty settings.
- */
-export function discoverAnalyzePlugins(): Plugin[] {
-	return STANDARD_ANALYZE_PLUGINS.map((moduleName) => ({
-		name: moduleName,
-		module: moduleName,
-		configFilePath: '',
-		settings: {},
-	}));
-}

package/src/hooks/define-plugin.spec.ts

@@ -1,38 +0,0 @@
-import type { PluginFactory } from '../types.js';
-
-import { describe, it, expect } from 'vitest';
-
-import { definePlugin } from './define-plugin.js';
-
-describe('definePlugin', () => {
-	it('returns the exact same function passed in', () => {
-		const factory: PluginFactory<{ lang: string }> = (options) => {
-			return {
-				headers: { score: `Score (${options.lang})` },
-			};
-		};
-
-		const result = definePlugin(factory);
-
-		expect(result).toBe(factory);
-	});
-
-	it('preserves type inference for sync factories', () => {
-		const factory = definePlugin((() => ({
-			headers: { found: 'Found' },
-		})) as PluginFactory<{ keywords: string[] }>);
-
-		expect(typeof factory).toBe('function');
-	});
-
-	it('preserves label in the returned AnalyzePlugin', () => {
-		const factory = definePlugin((() => ({
-			label: 'テスト用プラグイン',
-			headers: { score: 'Score' },
-		})) as PluginFactory<Record<string, never>>);
-
-		const plugin = factory({} as never, '');
-
-		expect(plugin).toHaveProperty('label', 'テスト用プラグイン');
-	});
-});

package/src/hooks/define-plugin.ts

@@ -1,73 +0,0 @@
-import type { PluginFactory } from '../types.js';
-
-/**
- * Identity function that provides full type inference for analyze plugin definitions.
- *
- * This function does **nothing at runtime** - it returns its argument unchanged.
- * Its sole purpose is to give TypeScript enough context to infer the generic
- * parameters `O` (options type) and `T` (column key union) from the plugin
- * implementation, without requiring explicit type annotations at the call site.
- *
- * ## Why an identity function?
- *
- * Without this wrapper, plugin authors would need to manually annotate the
- * `PluginFactory` type with both generic parameters:
- *
- * ```ts
- * // Without definePlugin - verbose and error-prone
- * const factory: PluginFactory<{ lang: string }, 'score' | 'details'> = (options) => { ... };
- * export default factory;
- * ```
- *
- * With `definePlugin`, TypeScript infers everything from the function body:
- *
- * ```ts
- * // With definePlugin - concise and type-safe
- * export default definePlugin(async (options: { lang: string }) => {
- *   return {
- *     label: 'Custom Analysis',
- *     headers: { score: 'Score', details: 'Details' },
- *     async eachPage({ window }) {
- *       return { page: { score: { value: 100 }, details: { value: 'OK' } } };
- *     },
- *   };
- * });
- * ```
- *
- * This pattern is sometimes called a "satisfies helper" or "builder pattern"
- * and is common in TypeScript libraries that need generic inference from
- * function arguments (cf. Zod's `z.object()`, tRPC's `router()`).
- * @template O - Shape of the plugin's settings/options from the config file.
- * @template T - String literal union of column keys contributed by this plugin.
- * @param factory - The plugin factory function to pass through.
- * @returns The same function, unchanged.
- * @example
- * ```ts
- * import { definePlugin } from '@nitpicker/core';
- *
- * type Options = { keywords: string[] };
- *
- * export default definePlugin(async (options: Options) => {
- *   return {
- *     label: 'キーワード検索',
- *     headers: { found: 'Keywords Found', count: 'Match Count' },
- *     async eachPage({ html }) {
- *       const matches = options.keywords.filter(k => html.includes(k));
- *       return {
- *         page: {
- *           found: { value: matches.join(', ') },
- *           count: { value: matches.length },
- *         },
- *       };
- *     },
- *   };
- * });
- * ```
- * @see {@link ../types.ts!PluginFactory} for the function signature being wrapped
- * @see {@link ../types.ts!AnalyzePlugin} for the returned plugin interface
- */
-export function definePlugin<O, T extends string = string>(
-	factory: PluginFactory<O, T>,
-): PluginFactory<O, T> {
-	return factory;
-}

package/src/hooks/index.ts

@@ -1 +0,0 @@
-export { definePlugin } from './define-plugin.js';

package/src/import-modules.spec.ts

@@ -1,150 +0,0 @@
-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

@@ -1,45 +0,0 @@
-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

@@ -1,5 +0,0 @@
-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

@@ -1,192 +0,0 @@
-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);
-	});
-});