@yuu1111/quality-check 0.2.0 → 0.3.0

package/README.ja.md

@@ -12,7 +12,7 @@ bun add -D @yuu1111/quality-check
 
 ## Usage
 
-`quality.config.ts` でengineと除外pathを指定し、scriptから起動する
+`quality.config.ts` で起動するengineとengineごとの起動条件を指定し、scriptから起動する
 
 ```json
 {
@@ -26,14 +26,17 @@ bun add -D @yuu1111/quality-check
 import { defineConfig } from "@yuu1111/quality-check";
 
 export default defineConfig({
-  engines: {
-    biome: true,
-    knip: true,
-    "comment-check": true,
-    "document-style-check": true,
-    "tsdoc-check": { args: ["--error", "missing-doc"] },
-  },
-  ignore: ["FFXIVReplayAnalyzer"],
+	engines: {
+		biome: true,
+		knip: true,
+		"comment-check": true,
+		"document-style-check": true,
+		"tsdoc-check": true,
+	},
+	config: {
+		"comment-check": { ignore: ["FFXIVReplayAnalyzer"] },
+		"tsdoc-check": { error: ["missing-doc"] },
+	},
 });
 ```
 
@@ -57,13 +60,23 @@ quality-check: 1 of 3 engines failed
 
 | Field | Description |
 |-------|-------------|
-| `engines` | 起動するengine 値は `true` または `{ args }` |
-| `ignore` | file走査engineが検査から外すpath |
+| `engines` | 起動するengine 値は `true` または `false` |
+| `config` | engineごとの起動条件 |
 | `baseline` | baseline fileのpath `false` なら差分判定を行わない |
-| `targets` | file走査engineへ渡す対象path |
 
 engineは `biome` → `knip` → `comment-check` → `document-style-check` → `tsdoc-check` の順に実行する
-`args` はengineの既定引数の後ろへ足すため、`tsdoc-check` の `--error` のようなengine固有の指定はここへ置く
+
+`engines` は起動の委任だけを表し、起動条件は `config` のengineの下へ置く engineが受け取る条件は次のとおり
+
+| engine | 受け取る条件 |
+|--------|--------------|
+| `biome` | `targets`、`args` 除外pathは `biome.json` が持つ |
+| `knip` | `args` 設定は `knip.ts` が持つ |
+| `comment-check` | `ignore`、`targets`、`args` |
+| `document-style-check` | `ignore`、`targets`、`args` |
+| `tsdoc-check` | `ignore`、`targets`、`args`、`error`（違反として扱うrule名） |
+
+`args` はengineの既定引数の後ろへ足す 設定fileで表せない起動条件や、engineの引数が変わったときの逃げ道として使う
 
 ## Options
 
@@ -75,11 +88,20 @@ engineは `biome` → `knip` → `comment-check` → `document-style-check` →
 | `--update-baseline` | 現在の検出でbaselineを置き換える |
 | `--json` | engineごとの結果をJSONで出力する |
 
+`--ignore` と位置引数の対象pathは、その条件を受け取るengineへだけ渡す
+
 ## Notes
 
 終了codeは0が全engine成功、1が失敗したengineあり、2が設定またはengine起動の失敗
 
-BiomeとKnipは除外pathを自分のconfig（`biome.json`、`knip.ts`）で持つ `ignore` はfile走査engineへ `--ignore` として渡し、BiomeとKnipには渡さない
+engineが受け取らない条件を書いた場合は渡さず、その旨をそのengineのsectionへ出す
+
+```text
+== biome ==
+biome: ignore skipped (biome.json holds its settings)
+```
+
+BiomeとKnipの除外pathは `biome.json` と `knip.ts` が持つ このCLIは同じfileからengineの起動と結果の集約だけを行う
 
 `comment-check` はbaseline差分を無効化する未作成のpathを渡して起動する 新規と解消済みの判定はengineごとではなく統合CLIが1つのbaseline fileで行うため、既存の `comment-baseline.json` がある場合は `--update-baseline` で移す
 

package/README.md

@@ -13,8 +13,8 @@ bun add -D @yuu1111/quality-check
 
 ## Usage
 
-Declare the engines and the excluded paths in `quality.config.ts`, then call the
-CLI from a script:
+Declare the engines to run and the conditions of each engine in
+`quality.config.ts`, then call the CLI from a script:
 
 ```json
 {
@@ -28,14 +28,17 @@ CLI from a script:
 import { defineConfig } from "@yuu1111/quality-check";
 
 export default defineConfig({
-  engines: {
-    biome: true,
-    knip: true,
-    "comment-check": true,
-    "document-style-check": true,
-    "tsdoc-check": { args: ["--error", "missing-doc"] },
-  },
-  ignore: ["FFXIVReplayAnalyzer"],
+	engines: {
+		biome: true,
+		knip: true,
+		"comment-check": true,
+		"document-style-check": true,
+		"tsdoc-check": true,
+	},
+	config: {
+		"comment-check": { ignore: ["FFXIVReplayAnalyzer"] },
+		"tsdoc-check": { error: ["missing-doc"] },
+	},
 });
 ```
 
@@ -60,14 +63,26 @@ quality-check: 1 of 3 engines failed
 
 | Field | Description |
 |-------|-------------|
-| `engines` | Engines to run, as `true` or `{ args }` |
-| `ignore` | Paths that the file-scanning engines leave out |
+| `engines` | Engines to run, as `true` or `false` |
+| `config` | Conditions of each engine |
 | `baseline` | Baseline file path; `false` disables the diff |
-| `targets` | Targets passed to the file-scanning engines |
 
-Engines run in the order `biome`, `knip`, `comment-check`, `document-style-check`, `tsdoc-check`.
-`args` is appended after the engine defaults, so engine-specific flags such as
-`--error` for `tsdoc-check` belong there.
+Engines run in the order `biome`, `knip`, `comment-check`,
+`document-style-check`, `tsdoc-check`.
+
+`engines` only delegates the start-up, and the conditions belong under the
+engine in `config`. Each engine takes:
+
+| Engine | Conditions |
+|--------|------------|
+| `biome` | `targets`, `args`; `biome.json` holds the excluded paths |
+| `knip` | `args`; `knip.ts` holds the settings |
+| `comment-check` | `ignore`, `targets`, `args` |
+| `document-style-check` | `ignore`, `targets`, `args` |
+| `tsdoc-check` | `ignore`, `targets`, `args`, `error` (rule names to fail on) |
+
+`args` is appended after the engine defaults, for conditions the config cannot
+express and for the case where an engine changes its arguments.
 
 ## Options
 
@@ -79,14 +94,23 @@ Engines run in the order `biome`, `knip`, `comment-check`, `document-style-check
 | `--update-baseline` | Replace the baseline with the current findings |
 | `--json` | Print the per-engine results as JSON |
 
+`--ignore` and the positional targets reach only the engines that take them.
+
 ## Notes
 
 Exit code 0 means every engine passed, 1 that at least one failed, and 2 that the
 configuration or an engine could not start.
 
-Biome and Knip keep their excluded paths in their own config (`biome.json`,
-`knip.ts`). `ignore` reaches the file-scanning engines as `--ignore` and is not
-passed to Biome or Knip.
+A condition that an engine does not take is not passed on, and the section says
+so:
+
+```text
+== biome ==
+biome: ignore skipped (biome.json holds its settings)
+```
+
+Biome and Knip keep their excluded paths in `biome.json` and `knip.ts`. This
+CLI starts the engines from one file and aggregates the results.
 
 `comment-check` runs with an unwritten baseline path so that it reports every
 finding. The new-and-resolved diff is done by this CLI from a single baseline

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@yuu1111/quality-check",
-	"version": "0.2.0",
+	"version": "0.3.0",
 	"description": "Integrated quality check runner",
 	"license": "MIT",
 	"repository": {

package/src/cli.ts

@@ -98,13 +98,6 @@ function parseArguments(argv: string[]): Options {
 	return options;
 }
 
-function mergeIgnores(config: QualityConfig, ignores: string[]): QualityConfig {
-	if (ignores.length === 0) {
-		return config;
-	}
-	return { ...config, ignore: [...(config.ignore ?? []), ...ignores] };
-}
-
 function resolveBaselinePath(
 	options: Options,
 	config: QualityConfig,
@@ -138,7 +131,7 @@ async function main(argv: string[]): Promise<number> {
 		console.error(`quality.config.ts not found in ${cwd}`);
 		return 2;
 	}
-	const config = mergeIgnores(await loadConfig(configPath), options.ignores);
+	const config = await loadConfig(configPath);
 	const baselinePath = resolveBaselinePath(options, config, cwd);
 	const results = await runEngines({
 		baseline:
@@ -147,9 +140,8 @@ async function main(argv: string[]): Promise<number> {
 				: readBaseline(baselinePath),
 		config,
 		cwd,
+		overrides: { ignore: options.ignores, targets: options.targets },
 		rawBaseline: join(tmpdir(), `quality-check-raw-${process.pid}.json`),
-		targets:
-			options.targets.length > 0 ? options.targets : (config.targets ?? ["."]),
 	});
 	if (options.update) {
 		if (baselinePath === null) {

package/src/config.ts

@@ -19,25 +19,46 @@ export const ENGINE_NAMES = [
 export type EngineName = (typeof ENGINE_NAMES)[number];
 
 /**
- * engineのbinへ追加で渡す起動設定
+ * engineへ渡す起動条件
  */
 export interface EngineOptions {
+	/** 検査から外すpath engineが受け取れないときはreportへ出す */
+	ignore?: string[];
+	/** 検査する対象path engineが受け取れないときはreportへ出す */
+	targets?: string[];
 	/** engineの既定引数の後ろへ足す引数 */
 	args?: string[];
 }
 
+/**
+ * TSDoc検査へ渡す起動条件
+ */
+export interface TsdocCheckOptions extends EngineOptions {
+	/** 違反として扱うrule名 */
+	error?: string[];
+}
+
+/**
+ * engine名ごとの起動条件
+ */
+export interface EngineConfigMap {
+	biome: EngineOptions;
+	knip: EngineOptions;
+	"comment-check": EngineOptions;
+	"document-style-check": EngineOptions;
+	"tsdoc-check": TsdocCheckOptions;
+}
+
 /**
  * quality.config.tsが受け付ける統合検査の設定
  */
 export interface QualityConfig {
 	/** 起動するengine 値がfalseまたは未指定のengineは起動しない */
-	engines: Partial<Record<EngineName, boolean | EngineOptions>>;
-	/** file走査engineが検査から外すpath */
-	ignore?: string[];
+	engines: Partial<Record<EngineName, boolean>>;
+	/** engineごとの起動条件 省略したengineは既定値で起動する */
+	config?: Partial<EngineConfigMap>;
 	/** baseline fileのpath falseなら差分判定を行わない */
 	baseline?: string | false;
-	/** file走査engineへ渡す対象path */
-	targets?: string[];
 }
 
 /**
@@ -72,6 +93,14 @@ function isEngineName(value: string): value is EngineName {
 	return (ENGINE_NAMES as readonly string[]).includes(value);
 }
 
+const ENGINE_OPTION_KEYS: Record<EngineName, readonly string[]> = {
+	biome: ["args", "ignore", "targets"],
+	knip: ["args", "ignore", "targets"],
+	"comment-check": ["args", "ignore", "targets"],
+	"document-style-check": ["args", "ignore", "targets"],
+	"tsdoc-check": ["args", "error", "ignore", "targets"],
+};
+
 function readStringArray(value: unknown, field: string): string[] | undefined {
 	if (value === undefined) {
 		return undefined;
@@ -98,27 +127,96 @@ function readBaseline(
 	throw new Error(`${source}: baseline must be a path string or false`);
 }
 
-function parseEngineOptions(
+function parseEngines(
 	value: unknown,
 	source: string,
-	name: EngineName,
-): boolean | EngineOptions {
-	if (typeof value === "boolean") {
-		return value;
-	}
+): Partial<Record<EngineName, boolean>> {
 	if (!isJsonObject(value)) {
-		throw new Error(
-			`${source}: engines.${name} must be a boolean or an object`,
-		);
+		throw new Error(`${source} must export an engines object`);
 	}
-	const unknown = Object.keys(value).filter((key) => key !== "args");
+	const engines: Partial<Record<EngineName, boolean>> = {};
+	for (const [name, enabled] of Object.entries(value)) {
+		if (!isEngineName(name)) {
+			throw new Error(`${source}: unknown engine: ${name}`);
+		}
+		if (typeof enabled !== "boolean") {
+			throw new Error(
+				`${source}: engines.${name} must be a boolean 起動条件はconfigへ置く`,
+			);
+		}
+		engines[name] = enabled;
+	}
+	if (ENGINE_NAMES.every((name) => !engines[name])) {
+		throw new Error(`${source} must enable at least one engine`);
+	}
+	return engines;
+}
+
+function parseEngineOptions(
+	value: JsonObject,
+	source: string,
+	name: EngineName,
+): TsdocCheckOptions {
+	const unknown = Object.keys(value).filter(
+		(key) => !ENGINE_OPTION_KEYS[name].includes(key),
+	);
 	if (unknown.length > 0) {
 		throw new Error(
-			`${source}: engines.${name} has an unknown option: ${unknown[0]}`,
+			`${source}: config.${name} has an unknown option: ${unknown[0]}`,
+		);
+	}
+	const options: TsdocCheckOptions = {};
+	const ignore = readStringArray(
+		value.ignore,
+		`${source}: config.${name}.ignore`,
+	);
+	if (ignore !== undefined) {
+		options.ignore = ignore;
+	}
+	const targets = readStringArray(
+		value.targets,
+		`${source}: config.${name}.targets`,
+	);
+	if (targets !== undefined) {
+		options.targets = targets;
+	}
+	const args = readStringArray(value.args, `${source}: config.${name}.args`);
+	if (args !== undefined) {
+		options.args = args;
+	}
+	if (name === "tsdoc-check") {
+		const error = readStringArray(
+			value.error,
+			`${source}: config.${name}.error`,
 		);
+		if (error !== undefined) {
+			options.error = error;
+		}
+	}
+	return options;
+}
+
+function parseEngineConfig(
+	value: unknown,
+	source: string,
+): Partial<EngineConfigMap> | undefined {
+	if (value === undefined) {
+		return undefined;
+	}
+	if (!isJsonObject(value)) {
+		throw new Error(`${source}: config must be an object`);
+	}
+	const config: Partial<EngineConfigMap> = {};
+	for (const [name, options] of Object.entries(value)) {
+		if (!isEngineName(name)) {
+			throw new Error(`${source}: unknown engine in config: ${name}`);
+		}
+		if (!isJsonObject(options)) {
+			throw new Error(`${source}: config.${name} must be an object`);
+		}
+		config[name] = parseEngineOptions(options, source, name);
 	}
-	const args = readStringArray(value.args, `${source}: engines.${name}.args`);
-	return args === undefined ? {} : { args };
+	return config;
 }
 
 /**
@@ -128,32 +226,17 @@ export function parseConfig(value: unknown, source: string): QualityConfig {
 	if (!isJsonObject(value)) {
 		throw new Error(`${source} must export a config object`);
 	}
-	if (!isJsonObject(value.engines)) {
-		throw new Error(`${source} must export an engines object`);
-	}
-	const engines: Partial<Record<EngineName, boolean | EngineOptions>> = {};
-	for (const [name, options] of Object.entries(value.engines)) {
-		if (!isEngineName(name)) {
-			throw new Error(`${source}: unknown engine: ${name}`);
-		}
-		engines[name] = parseEngineOptions(options, source, name);
+	const config: QualityConfig = {
+		engines: parseEngines(value.engines, source),
+	};
+	const engineConfig = parseEngineConfig(value.config, source);
+	if (engineConfig !== undefined) {
+		config.config = engineConfig;
 	}
-	if (ENGINE_NAMES.every((name) => !engines[name])) {
-		throw new Error(`${source} must enable at least one engine`);
-	}
-	const config: QualityConfig = { engines };
 	const baseline = readBaseline(value.baseline, source);
 	if (baseline !== undefined) {
 		config.baseline = baseline;
 	}
-	const ignore = readStringArray(value.ignore, `${source}: ignore`);
-	if (ignore !== undefined) {
-		config.ignore = ignore;
-	}
-	const targets = readStringArray(value.targets, `${source}: targets`);
-	if (targets !== undefined) {
-		config.targets = targets;
-	}
 	return config;
 }
 
@@ -165,17 +248,16 @@ export function enabledEngines(config: QualityConfig): EngineName[] {
 }
 
 /**
- * engineの起動設定を返す 無効なengineにはnullを返す
+ * engineの起動条件を返す 無効なengineにはnullを返す
  */
-export function engineOptions(
+export function engineConfig<K extends EngineName>(
 	config: QualityConfig,
-	name: EngineName,
-): EngineOptions | null {
-	const value = config.engines[name];
-	if (!value) {
+	name: K,
+): EngineConfigMap[K] | null {
+	if (!config.engines[name]) {
 		return null;
 	}
-	return value === true ? {} : value;
+	return config.config?.[name] ?? ({} as EngineConfigMap[K]);
 }
 
 /**

package/src/engines.ts

@@ -1,6 +1,11 @@
 import { existsSync } from "node:fs";
 import { dirname, join } from "node:path";
-import { type EngineName, engineOptions, type QualityConfig } from "./config";
+import {
+	type EngineName,
+	type EngineOptions,
+	engineConfig,
+	type QualityConfig,
+} from "./config";
 
 /**
  * 子プロセスとして起動したengineの生の結果
@@ -33,15 +38,61 @@ export const ENGINE_BINS: Record<EngineName, string> = {
 const WINDOWS_SHIMS = [".exe", ".cmd", ".bat", ""];
 const POSIX_SHIMS = [""];
 
+/**
+ * コマンドラインから渡された起動条件の上書き
+ */
+export interface RunOverrides {
+	ignore: string[];
+	targets: string[];
+}
+
 /**
  * engineのコマンドを組み立てるための実行条件
  */
 export interface EngineCommandContext {
 	config: QualityConfig;
-	ignores: string[];
+	/** 対応するengineへだけ足す上書き */
+	overrides: RunOverrides;
 	/** comment-checkのbaseline差分を無効化するために渡す未作成のpath */
 	rawBaseline: string;
-	targets: string[];
+}
+
+/**
+ * engineが受け取らない起動条件と、その設定の持ち主
+ */
+export const ENGINE_LIMITS: Record<
+	EngineName,
+	Partial<Record<"ignore" | "targets", string>>
+> = {
+	biome: { ignore: "biome.json holds its settings" },
+	knip: {
+		ignore: "knip.ts holds its settings",
+		targets: "knip analyzes the whole project",
+	},
+	"comment-check": {},
+	"document-style-check": {},
+	"tsdoc-check": {},
+};
+
+/**
+ * engineが受け取らないため渡さなかった起動条件を返す
+ */
+export function skippedEngineOptions(
+	name: EngineName,
+	options: EngineOptions | undefined,
+): string[] {
+	if (options === undefined) {
+		return [];
+	}
+	const limits = ENGINE_LIMITS[name];
+	const skipped: string[] = [];
+	for (const key of ["ignore", "targets"] as const) {
+		const reason = limits[key];
+		if (reason !== undefined && options[key] !== undefined) {
+			skipped.push(`${key} skipped (${reason})`);
+		}
+	}
+	return skipped;
 }
 
 /**
@@ -95,24 +146,34 @@ export function buildEngineCommand(
 	executable: string,
 	context: EngineCommandContext,
 ): string[] {
-	const extra = engineOptions(context.config, name)?.args ?? [];
+	const options: EngineOptions = engineConfig(context.config, name) ?? {};
+	const limits = ENGINE_LIMITS[name];
+	const extra = options.args ?? [];
+	const ignores =
+		limits.ignore === undefined
+			? [...(options.ignore ?? []), ...context.overrides.ignore]
+			: [];
+	const requested =
+		context.overrides.targets.length > 0
+			? context.overrides.targets
+			: (options.targets ?? ["."]);
+	const targets = limits.targets === undefined ? requested : [];
+	const ignoreArguments = ignores.flatMap((ignore) => ["--ignore", ignore]);
+	const rules = engineConfig(context.config, "tsdoc-check")?.error ?? [];
+	const errorArguments = rules.flatMap((rule) => ["--error", rule]);
 	if (name === "biome") {
-		return [executable, "check", ...context.targets, ...extra];
+		return [executable, "check", ...targets, ...extra];
 	}
 	if (name === "knip") {
 		return [executable, ...extra];
 	}
-	const ignoreArguments = context.ignores.flatMap((ignore) => [
-		"--ignore",
-		ignore,
-	]);
 	if (name === "comment-check") {
 		return [
 			executable,
 			"--json",
 			"--baseline",
 			context.rawBaseline,
-			...context.targets,
+			...targets,
 			...ignoreArguments,
 			...extra,
 		];
@@ -122,7 +183,7 @@ export function buildEngineCommand(
 			executable,
 			"lint",
 			"--json",
-			...context.targets,
+			...targets,
 			...ignoreArguments,
 			...extra,
 		];
@@ -130,7 +191,8 @@ export function buildEngineCommand(
 	return [
 		executable,
 		"--json",
-		...context.targets,
+		...errorArguments,
+		...targets,
 		...ignoreArguments,
 		...extra,
 	];

package/src/report.ts

@@ -25,6 +25,9 @@ function describeStatus(result: EngineResult): string {
  */
 export function formatEngineSection(result: EngineResult): string {
 	const lines = [`== ${result.name} ==`];
+	for (const skipped of result.skipped) {
+		lines.push(`${result.name}: ${skipped}`);
+	}
 	if (result.output !== "" && !isFindingEngine(result.name)) {
 		lines.push(result.output);
 	}
@@ -73,6 +76,7 @@ export function toJsonReport(results: EngineResult[]): unknown {
 			name: result.name,
 			reported: result.reported,
 			resolved: result.resolved,
+			skipped: result.skipped,
 			status: result.status,
 			warnings: result.warnings,
 		})),

package/src/run.ts

@@ -7,8 +7,10 @@ import {
 	type EngineProcessResult,
 	type EngineRunner,
 	isFindingEngine,
+	type RunOverrides,
 	resolveExecutable,
 	runEngineProcess,
+	skippedEngineOptions,
 } from "./engines";
 import { type NormalizedFinding, parseFindings } from "./findings";
 
@@ -30,6 +32,8 @@ export interface EngineResult {
 	/** baseline適用後に残った阻害する検出 */
 	reported: NormalizedFinding[];
 	resolved: number;
+	/** engineが受け取らなかった起動条件 */
+	skipped: string[];
 	status: EngineStatus;
 	warnings: NormalizedFinding[];
 }
@@ -42,8 +46,8 @@ export interface RunOptions {
 	baseline: BaselineFile | null;
 	config: QualityConfig;
 	cwd: string;
-	/** file走査engineへ渡す対象path */
-	targets: string[];
+	/** コマンドラインから渡された起動条件の上書き */
+	overrides: RunOverrides;
 	/** comment-checkのbaseline差分を無効化する未作成のpath */
 	rawBaseline: string;
 	/** engineの実行fileを解決する関数 テストでは差し替える */
@@ -63,6 +67,7 @@ function baseResult(
 		output,
 		reported: [],
 		resolved: 0,
+		skipped: [],
 		warnings: [],
 	};
 }
@@ -144,7 +149,7 @@ async function runProcessEngine(
 	};
 }
 
-async function runEngine(
+async function executeEngine(
 	name: EngineName,
 	options: RunOptions,
 	context: EngineCommandContext,
@@ -164,6 +169,19 @@ async function runEngine(
 	return await runProcessEngine(name, options, executable, context, runner);
 }
 
+async function runEngine(
+	name: EngineName,
+	options: RunOptions,
+	context: EngineCommandContext,
+	runner: EngineRunner,
+): Promise<EngineResult> {
+	const result = await executeEngine(name, options, context, runner);
+	return {
+		...result,
+		skipped: skippedEngineOptions(name, options.config.config?.[name]),
+	};
+}
+
 /**
  * 設定で有効なengineを順に起動する
  */
@@ -171,9 +189,8 @@ export async function runEngines(options: RunOptions): Promise<EngineResult[]> {
 	const runner = options.runner ?? runEngineProcess;
 	const context: EngineCommandContext = {
 		config: options.config,
-		ignores: options.config.ignore ?? [],
+		overrides: options.overrides,
 		rawBaseline: options.rawBaseline,
-		targets: options.targets,
 	};
 	const results: EngineResult[] = [];
 	for (const name of enabledEngines(options.config)) {