@yuu1111/quality-check 0.0.0

package/README.ja.md

@@ -0,0 +1,87 @@
+[English](README.md)
+
+# @yuu1111/quality-check
+
+Projectごとのscriptから個別に呼んでいたBiome、Knip、comment-check、TSDoc checkerを1つのCLIへまとめる baselineの差分判定もここで行う
+
+## Install
+
+```bash
+bun add -D @yuu1111/quality-check
+```
+
+## Usage
+
+`quality.config.ts` でengineと除外pathを指定し、scriptから起動する
+
+```json
+{
+  "scripts": {
+    "check:quality": "quality-check"
+  }
+}
+```
+
+```ts
+import { defineConfig } from "@yuu1111/quality-check";
+
+export default defineConfig({
+  engines: {
+    biome: true,
+    knip: true,
+    "comment-check": true,
+    "tsdoc-check": { args: ["--error", "missing-doc"] },
+  },
+  ignore: ["FFXIVReplayAnalyzer"],
+});
+```
+
+engineごとの出力と集約summaryを並べて出し、どのengineが失敗したかを1回の実行で示す
+
+```text
+== biome ==
+Checked 128 files in 260ms. No fixes applied.
+biome: passed (exit 0)
+
+== comment-check ==
+src/queue.ts:18:2 placeholder-comment placeholder comment should be resolved or tracked
+comment-check: failed (1 new, 0 resolved, 0 warnings)
+
+quality-check: 1 of 3 engines failed
+  failed: comment-check
+  passed: biome, tsdoc-check
+```
+
+## Config
+
+| Field | Description |
+|-------|-------------|
+| `engines` | 起動するengine 値は `true` または `{ args }` |
+| `ignore` | file走査engineが検査から外すpath |
+| `baseline` | baseline fileのpath `false` なら差分判定を行わない |
+| `targets` | file走査engineへ渡す対象path |
+
+engineは `biome` → `knip` → `comment-check` → `tsdoc-check` の順に実行する
+`args` はengineの既定引数の後ろへ足すため、`tsdoc-check` の `--error` のようなengine固有の指定はここへ置く
+
+## Options
+
+| Option | Description |
+|--------|-------------|
+| `--config <path>` | 読み込むconfig file（既定は `quality.config.ts`） |
+| `--baseline <path>` | baseline fileを上書きする |
+| `--ignore <path>` | 除外pathを追加する 複数指定できる |
+| `--update-baseline` | 現在の検出でbaselineを置き換える |
+| `--json` | engineごとの結果をJSONで出力する |
+
+## Notes
+
+終了codeは0が全engine成功、1が失敗したengineあり、2が設定またはengine起動の失敗
+
+BiomeとKnipは除外pathを自分のconfig（`biome.json`、`knip.ts`）で持つ `ignore` はfile走査engineへ `--ignore` として渡し、BiomeとKnipには渡さない
+
+`comment-check` はbaseline差分を無効化する未作成のpathを渡して起動する 新規と解消済みの判定はengineごとではなく統合CLIが1つのbaseline fileで行うため、既存の `comment-baseline.json` がある場合は `--update-baseline` で移す
+
+## License
+
+MIT

package/README.md

@@ -0,0 +1,97 @@
+[日本語](README.ja.md)
+
+# @yuu1111/quality-check
+
+Runs Biome, Knip, comment-check, and the TSDoc checker from one CLI instead of
+one script per project. The baseline diff lives here too.
+
+## Install
+
+```bash
+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:
+
+```json
+{
+  "scripts": {
+    "check:quality": "quality-check"
+  }
+}
+```
+
+```ts
+import { defineConfig } from "@yuu1111/quality-check";
+
+export default defineConfig({
+  engines: {
+    biome: true,
+    knip: true,
+    "comment-check": true,
+    "tsdoc-check": { args: ["--error", "missing-doc"] },
+  },
+  ignore: ["FFXIVReplayAnalyzer"],
+});
+```
+
+Each engine prints its own section, and the summary names the engines that
+failed:
+
+```text
+== biome ==
+Checked 128 files in 260ms. No fixes applied.
+biome: passed (exit 0)
+
+== comment-check ==
+src/queue.ts:18:2 placeholder-comment placeholder comment should be resolved or tracked
+comment-check: failed (1 new, 0 resolved, 0 warnings)
+
+quality-check: 1 of 3 engines failed
+  failed: comment-check
+  passed: biome, tsdoc-check
+```
+
+## Config
+
+| Field | Description |
+|-------|-------------|
+| `engines` | Engines to run, as `true` or `{ args }` |
+| `ignore` | Paths that the file-scanning engines leave out |
+| `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`, `tsdoc-check`.
+`args` is appended after the engine defaults, so engine-specific flags such as
+`--error` for `tsdoc-check` belong there.
+
+## Options
+
+| Option | Description |
+|--------|-------------|
+| `--config <path>` | Config file to load (default `quality.config.ts`) |
+| `--baseline <path>` | Override the baseline file |
+| `--ignore <path>` | Add an excluded path, repeatable |
+| `--update-baseline` | Replace the baseline with the current findings |
+| `--json` | Print the per-engine results as JSON |
+
+## 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.
+
+`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
+file, so an existing `comment-baseline.json` is moved over with
+`--update-baseline`.
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,27 @@
+{
+	"name": "@yuu1111/quality-check",
+	"version": "0.0.0",
+	"description": "Integrated quality check runner",
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/yuu1111/configs.git",
+		"directory": "packages/quality-check"
+	},
+	"type": "module",
+	"bin": {
+		"quality-check": "src/cli.ts"
+	},
+	"exports": {
+		".": "./src/config.ts",
+		"./engines": "./src/engines.ts"
+	},
+	"files": [
+		"README.ja.md",
+		"src"
+	],
+	"keywords": [
+		"quality",
+		"lint"
+	]
+}

package/src/baseline.ts

@@ -0,0 +1,147 @@
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import type { NormalizedFinding } from "./findings";
+
+/**
+ * baselineへ記録する検出1件の識別情報と件数
+ */
+export interface BaselineEntry {
+	count: number;
+	engine: string;
+	file: string;
+	rule: string;
+	text: string;
+}
+
+/**
+ * baseline fileの形式
+ */
+export interface BaselineFile {
+	entries: BaselineEntry[];
+	version: 1;
+}
+
+/**
+ * baselineと現在の検出を比較した結果
+ */
+export interface BaselineComparison {
+	added: NormalizedFinding[];
+	resolved: BaselineEntry[];
+}
+
+type JsonObject = Record<string, unknown>;
+
+/**
+ * 検出をbaseline上で一意に識別するkeyに使う項目
+ */
+export interface BaselineKey {
+	engine: string;
+	file: string;
+	rule: string;
+	text: string;
+}
+
+function isJsonObject(value: unknown): value is JsonObject {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function isBaselineEntry(value: unknown): value is BaselineEntry {
+	if (!isJsonObject(value)) {
+		return false;
+	}
+	return (
+		typeof value.engine === "string" &&
+		typeof value.rule === "string" &&
+		typeof value.file === "string" &&
+		typeof value.text === "string" &&
+		typeof value.count === "number"
+	);
+}
+
+function entryKey(entry: BaselineKey): string {
+	return [entry.engine, entry.rule, entry.file, entry.text].join("\u0000");
+}
+
+function compareEntries(left: BaselineEntry, right: BaselineEntry): number {
+	const leftKey = entryKey(left);
+	const rightKey = entryKey(right);
+	if (leftKey === rightKey) {
+		return 0;
+	}
+	return leftKey < rightKey ? -1 : 1;
+}
+
+/**
+ * 検出をengineとruleとfileと本文で集計してbaselineを作る
+ */
+export function createBaseline(findings: NormalizedFinding[]): BaselineFile {
+	const entries = new Map<string, BaselineEntry>();
+	for (const finding of findings) {
+		const key = entryKey(finding);
+		const existing = entries.get(key);
+		if (existing) {
+			existing.count += 1;
+			continue;
+		}
+		entries.set(key, {
+			count: 1,
+			engine: finding.engine,
+			file: finding.file,
+			rule: finding.rule,
+			text: finding.text,
+		});
+	}
+	return { entries: [...entries.values()].sort(compareEntries), version: 1 };
+}
+
+/**
+ * 現在の検出からbaseline済みを除き、解消済みentryを求める
+ */
+export function compareWithBaseline(
+	findings: NormalizedFinding[],
+	baseline: BaselineFile,
+): BaselineComparison {
+	const remaining = new Map<string, number>();
+	for (const entry of baseline.entries) {
+		const key = entryKey(entry);
+		remaining.set(key, (remaining.get(key) ?? 0) + entry.count);
+	}
+	const added: NormalizedFinding[] = [];
+	for (const finding of findings) {
+		const key = entryKey(finding);
+		const count = remaining.get(key) ?? 0;
+		if (count > 0) {
+			remaining.set(key, count - 1);
+			continue;
+		}
+		added.push(finding);
+	}
+	const resolved = baseline.entries.filter(
+		(entry) => (remaining.get(entryKey(entry)) ?? 0) > 0,
+	);
+	return { added, resolved };
+}
+
+/**
+ * baseline fileを読み込む 存在しない場合は空のbaselineを返す
+ */
+export function readBaseline(path: string): BaselineFile {
+	if (!existsSync(path)) {
+		return { entries: [], version: 1 };
+	}
+	const value: unknown = JSON.parse(readFileSync(path, "utf8"));
+	if (
+		!isJsonObject(value) ||
+		!Array.isArray(value.entries) ||
+		!value.entries.every(isBaselineEntry)
+	) {
+		throw new Error(`${path} is not a quality baseline`);
+	}
+	return { entries: value.entries, version: 1 };
+}
+
+/**
+ * baseline fileをタブ区切りのJSONで書き込む
+ */
+export function writeBaseline(path: string, baseline: BaselineFile): void {
+	writeFileSync(path, `${JSON.stringify(baseline, null, "\t")}\n`);
+}

package/src/cli.ts

@@ -0,0 +1,184 @@
+#!/usr/bin/env bun
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import { createBaseline, readBaseline, writeBaseline } from "./baseline";
+import {
+	DEFAULT_BASELINE_FILE,
+	findConfigFile,
+	loadConfig,
+	type QualityConfig,
+} from "./config";
+import { formatEngineSection, formatSummary, toJsonReport } from "./report";
+import { runEngines } from "./run";
+
+const USAGE =
+	"Usage: quality-check [--config <path>] [--baseline <path>] [--ignore <path>] [--update-baseline] [--json] [path...]";
+
+interface Options {
+	baselinePath: string | undefined;
+	configPath: string | undefined;
+	ignores: string[];
+	json: boolean;
+	targets: string[];
+	update: boolean;
+}
+
+function applyFlagOption(options: Options, argument: string): boolean {
+	if (argument === "--json") {
+		options.json = true;
+		return true;
+	}
+	if (argument === "--update-baseline") {
+		options.update = true;
+		return true;
+	}
+	return false;
+}
+
+function applyValueOption(
+	options: Options,
+	argument: string,
+	argv: string[],
+	index: number,
+): number | null {
+	if (argument === "--config") {
+		options.configPath = argv[index + 1];
+		return 1;
+	}
+	if (argument.startsWith("--config=")) {
+		options.configPath = argument.slice("--config=".length);
+		return 0;
+	}
+	if (argument === "--baseline") {
+		options.baselinePath = argv[index + 1];
+		return 1;
+	}
+	if (argument.startsWith("--baseline=")) {
+		options.baselinePath = argument.slice("--baseline=".length);
+		return 0;
+	}
+	if (argument === "--ignore") {
+		const value = argv[index + 1];
+		if (value !== undefined) {
+			options.ignores.push(value);
+		}
+		return 1;
+	}
+	if (argument.startsWith("--ignore=")) {
+		options.ignores.push(argument.slice("--ignore=".length));
+		return 0;
+	}
+	return null;
+}
+
+function parseArguments(argv: string[]): Options {
+	const options: Options = {
+		baselinePath: undefined,
+		configPath: undefined,
+		ignores: [],
+		json: false,
+		targets: [],
+		update: false,
+	};
+	for (let index = 0; index < argv.length; index += 1) {
+		const argument = argv[index] ?? "";
+		const consumed = applyValueOption(options, argument, argv, index);
+		if (consumed !== null) {
+			index += consumed;
+			continue;
+		}
+		if (applyFlagOption(options, argument)) {
+			continue;
+		}
+		if (argument.startsWith("-")) {
+			throw new Error(`unknown option: ${argument}`);
+		}
+		options.targets.push(argument);
+	}
+	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,
+	cwd: string,
+): string | null {
+	if (options.baselinePath !== undefined) {
+		return resolve(cwd, options.baselinePath);
+	}
+	if (config.baseline === false) {
+		return null;
+	}
+	return resolve(cwd, config.baseline ?? DEFAULT_BASELINE_FILE);
+}
+
+function resolveConfigPath(options: Options, cwd: string): string | null {
+	if (options.configPath !== undefined) {
+		return resolve(cwd, options.configPath);
+	}
+	return findConfigFile(cwd);
+}
+
+async function main(argv: string[]): Promise<number> {
+	if (argv.includes("--help") || argv.includes("-h")) {
+		console.log(USAGE);
+		return 0;
+	}
+	const options = parseArguments(argv);
+	const cwd = process.cwd();
+	const configPath = resolveConfigPath(options, cwd);
+	if (configPath === null) {
+		console.error(`quality.config.ts not found in ${cwd}`);
+		return 2;
+	}
+	const config = mergeIgnores(await loadConfig(configPath), options.ignores);
+	const baselinePath = resolveBaselinePath(options, config, cwd);
+	const results = await runEngines({
+		baseline:
+			options.update || baselinePath === null
+				? null
+				: readBaseline(baselinePath),
+		config,
+		cwd,
+		rawBaseline: join(tmpdir(), `quality-check-raw-${process.pid}.json`),
+		targets:
+			options.targets.length > 0 ? options.targets : (config.targets ?? ["."]),
+	});
+	if (options.update) {
+		if (baselinePath === null) {
+			console.error("baseline is disabled by the configuration");
+			return 2;
+		}
+		const baseline = createBaseline(
+			results.flatMap((result) => result.detected),
+		);
+		writeBaseline(baselinePath, baseline);
+		console.log(
+			`Recorded ${baseline.entries.length} entries in ${baselinePath}`,
+		);
+		return 0;
+	}
+	if (options.json) {
+		console.log(JSON.stringify(toJsonReport(results), null, "\t"));
+	} else {
+		for (const result of results) {
+			console.log(formatEngineSection(result));
+		}
+		console.log(formatSummary(results));
+	}
+	return results.some((result) => result.status !== "passed") ? 1 : 0;
+}
+
+try {
+	process.exit(await main(process.argv.slice(2)));
+} catch (error) {
+	console.error(error instanceof Error ? error.message : String(error));
+	process.exit(2);
+}

package/src/config.ts

@@ -0,0 +1,201 @@
+import { existsSync } from "node:fs";
+import { resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+
+/**
+ * 統合CLIが起動できるengineの名前 並び順が実行順になる
+ */
+export const ENGINE_NAMES = [
+	"biome",
+	"knip",
+	"comment-check",
+	"tsdoc-check",
+] as const;
+
+/**
+ * engine名のunion型
+ */
+export type EngineName = (typeof ENGINE_NAMES)[number];
+
+/**
+ * engineのbinへ追加で渡す起動設定
+ */
+export interface EngineOptions {
+	/** engineの既定引数の後ろへ足す引数 */
+	args?: string[];
+}
+
+/**
+ * quality.config.tsが受け付ける統合検査の設定
+ */
+export interface QualityConfig {
+	/** 起動するengine 値がfalseまたは未指定のengineは起動しない */
+	engines: Partial<Record<EngineName, boolean | EngineOptions>>;
+	/** file走査engineが検査から外すpath */
+	ignore?: string[];
+	/** baseline fileのpath falseなら差分判定を行わない */
+	baseline?: string | false;
+	/** file走査engineへ渡す対象path */
+	targets?: string[];
+}
+
+/**
+ * 設定fileを型付けするための恒等関数
+ */
+export function defineConfig(config: QualityConfig): QualityConfig {
+	return config;
+}
+
+/**
+ * config fileを探索する既定のfile名
+ */
+export const DEFAULT_CONFIG_FILES = [
+	"quality.config.ts",
+	"quality.config.mts",
+	"quality.config.js",
+	"quality.config.mjs",
+] as const;
+
+/**
+ * baseline fileの既定名
+ */
+export const DEFAULT_BASELINE_FILE = "quality-baseline.json";
+
+type JsonObject = Record<string, unknown>;
+
+function isJsonObject(value: unknown): value is JsonObject {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function isEngineName(value: string): value is EngineName {
+	return (ENGINE_NAMES as readonly string[]).includes(value);
+}
+
+function readStringArray(value: unknown, field: string): string[] | undefined {
+	if (value === undefined) {
+		return undefined;
+	}
+	if (
+		!Array.isArray(value) ||
+		value.some((entry) => typeof entry !== "string" || entry === "")
+	) {
+		throw new Error(`${field} must be an array of non-empty strings`);
+	}
+	return [...value] as string[];
+}
+
+function readBaseline(
+	value: unknown,
+	source: string,
+): string | false | undefined {
+	if (value === undefined || value === false) {
+		return value;
+	}
+	if (typeof value === "string" && value !== "") {
+		return value;
+	}
+	throw new Error(`${source}: baseline must be a path string or false`);
+}
+
+function parseEngineOptions(
+	value: unknown,
+	source: string,
+	name: EngineName,
+): boolean | EngineOptions {
+	if (typeof value === "boolean") {
+		return value;
+	}
+	if (!isJsonObject(value)) {
+		throw new Error(
+			`${source}: engines.${name} must be a boolean or an object`,
+		);
+	}
+	const unknown = Object.keys(value).filter((key) => key !== "args");
+	if (unknown.length > 0) {
+		throw new Error(
+			`${source}: engines.${name} has an unknown option: ${unknown[0]}`,
+		);
+	}
+	const args = readStringArray(value.args, `${source}: engines.${name}.args`);
+	return args === undefined ? {} : { args };
+}
+
+/**
+ * 読み込んだ設定を検証して不足分を補う
+ */
+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);
+	}
+	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;
+}
+
+/**
+ * 有効なengineを実行順で返す
+ */
+export function enabledEngines(config: QualityConfig): EngineName[] {
+	return ENGINE_NAMES.filter((name) => Boolean(config.engines[name]));
+}
+
+/**
+ * engineの起動設定を返す 無効なengineにはnullを返す
+ */
+export function engineOptions(
+	config: QualityConfig,
+	name: EngineName,
+): EngineOptions | null {
+	const value = config.engines[name];
+	if (!value) {
+		return null;
+	}
+	return value === true ? {} : value;
+}
+
+/**
+ * 作業ディレクトリからconfig fileを探す
+ */
+export function findConfigFile(cwd: string): string | null {
+	for (const name of DEFAULT_CONFIG_FILES) {
+		const candidate = resolve(cwd, name);
+		if (existsSync(candidate)) {
+			return candidate;
+		}
+	}
+	return null;
+}
+
+/**
+ * config fileを読み込んで検証する
+ */
+export async function loadConfig(path: string): Promise<QualityConfig> {
+	const module: unknown = await import(pathToFileURL(path).href);
+	const value =
+		isJsonObject(module) && "default" in module ? module.default : module;
+	return parseConfig(value, path);
+}

package/src/engines.ts

@@ -0,0 +1,143 @@
+import { existsSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { type EngineName, engineOptions, type QualityConfig } from "./config";
+
+/**
+ * 子プロセスとして起動したengineの生の結果
+ */
+export interface EngineProcessResult {
+	exitCode: number | null;
+	stderr: string;
+	stdout: string;
+}
+
+/**
+ * engineを起動して出力を返す関数 テストでは差し替える
+ */
+export type EngineRunner = (
+	command: string[],
+	options: { cwd: string },
+) => Promise<EngineProcessResult>;
+
+/**
+ * engineごとの実行file名
+ */
+export const ENGINE_BINS: Record<EngineName, string> = {
+	biome: "biome",
+	"comment-check": "comment-check",
+	knip: "knip",
+	"tsdoc-check": "tsdoc-check",
+};
+
+const WINDOWS_SHIMS = [".exe", ".cmd", ".bat", ""];
+const POSIX_SHIMS = [""];
+
+/**
+ * engineのコマンドを組み立てるための実行条件
+ */
+export interface EngineCommandContext {
+	config: QualityConfig;
+	ignores: string[];
+	/** comment-checkのbaseline差分を無効化するために渡す未作成のpath */
+	rawBaseline: string;
+	targets: string[];
+}
+
+/**
+ * 検出をJSONで返すengineか
+ */
+export function isFindingEngine(name: EngineName): boolean {
+	return name === "comment-check" || name === "tsdoc-check";
+}
+
+/**
+ * node_modules/.binとPATHからengineの実行fileを探す
+ */
+export function resolveExecutable(
+	name: EngineName,
+	cwd: string,
+): string | null {
+	const shims = process.platform === "win32" ? WINDOWS_SHIMS : POSIX_SHIMS;
+	const bin = ENGINE_BINS[name];
+	let directory = cwd;
+	for (;;) {
+		for (const shim of shims) {
+			const candidate = join(
+				directory,
+				"node_modules",
+				".bin",
+				`${bin}${shim}`,
+			);
+			if (existsSync(candidate)) {
+				return candidate;
+			}
+		}
+		const parent = dirname(directory);
+		if (parent === directory) {
+			break;
+		}
+		directory = parent;
+	}
+	const onPath = Bun.which(bin);
+	return onPath ?? null;
+}
+
+/**
+ * engineへ渡すコマンドを組み立てる
+ */
+export function buildEngineCommand(
+	name: EngineName,
+	executable: string,
+	context: EngineCommandContext,
+): string[] {
+	const extra = engineOptions(context.config, name)?.args ?? [];
+	if (name === "biome") {
+		return [executable, "check", ...context.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,
+			...ignoreArguments,
+			...extra,
+		];
+	}
+	return [
+		executable,
+		"--json",
+		...context.targets,
+		...ignoreArguments,
+		...extra,
+	];
+}
+
+/**
+ * Bun.spawnでengineを起動する既定のrunner
+ */
+export async function runEngineProcess(
+	command: string[],
+	options: { cwd: string },
+): Promise<EngineProcessResult> {
+	const child = Bun.spawn({
+		cmd: command,
+		cwd: options.cwd,
+		stderr: "pipe",
+		stdout: "pipe",
+	});
+	const [stdout, stderr, exitCode] = await Promise.all([
+		new Response(child.stdout).text(),
+		new Response(child.stderr).text(),
+		child.exited,
+	]);
+	return { exitCode, stderr, stdout };
+}

package/src/findings.ts

@@ -0,0 +1,106 @@
+import type { EngineName } from "./config";
+
+/**
+ * 検出の重大度
+ */
+export type FindingSeverity = "error" | "warning";
+
+/**
+ * engine間の差を吸収した検出1件
+ */
+export interface NormalizedFinding {
+	column: number;
+	engine: EngineName;
+	file: string;
+	line: number;
+	rule: string;
+	severity: FindingSeverity;
+	text: string;
+}
+
+/**
+ * engineが--jsonで返した検出の分類
+ */
+export interface ParsedFindings {
+	errors: NormalizedFinding[];
+	warnings: NormalizedFinding[];
+}
+
+type JsonObject = Record<string, unknown>;
+
+function isJsonObject(value: unknown): value is JsonObject {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function readFinding(
+	engine: EngineName,
+	value: unknown,
+	severity: FindingSeverity,
+	textField: "message" | "text",
+): NormalizedFinding {
+	if (!isJsonObject(value)) {
+		throw new Error(`${engine} printed an unexpected finding`);
+	}
+	const { column, file, line, rule } = value;
+	const text = value[textField];
+	if (
+		typeof rule !== "string" ||
+		typeof file !== "string" ||
+		typeof line !== "number" ||
+		typeof column !== "number" ||
+		typeof text !== "string"
+	) {
+		throw new Error(`${engine} printed an unexpected finding`);
+	}
+	return { column, engine, file, line, rule, severity, text };
+}
+
+function readEntries(
+	engine: EngineName,
+	value: unknown,
+	field: string,
+): unknown[] {
+	if (!Array.isArray(value)) {
+		throw new Error(`${engine} printed JSON without a ${field} array`);
+	}
+	return value;
+}
+
+function parseJson(engine: EngineName, stdout: string): JsonObject {
+	let value: unknown;
+	try {
+		value = JSON.parse(stdout);
+	} catch {
+		throw new Error(`${engine} did not print JSON`);
+	}
+	if (!isJsonObject(value)) {
+		throw new Error(`${engine} printed an unexpected JSON value`);
+	}
+	return value;
+}
+
+/**
+ * engineの--json出力を検出へ変換する 解析できない出力は例外にする
+ */
+export function parseFindings(
+	engine: EngineName,
+	stdout: string,
+): ParsedFindings {
+	const value = parseJson(engine, stdout);
+	if (engine === "comment-check") {
+		return {
+			errors: readEntries(engine, value.added, "added").map((entry) =>
+				readFinding(engine, entry, "error", "text"),
+			),
+			warnings: [],
+		};
+	}
+	return {
+		errors: readEntries(engine, value.errors, "errors").map((entry) =>
+			readFinding(engine, entry, "error", "message"),
+		),
+		warnings: readEntries(engine, value.warnings, "warnings").map((entry) =>
+			readFinding(engine, entry, "warning", "message"),
+		),
+	};
+}

package/src/report.ts

@@ -0,0 +1,83 @@
+import { isFindingEngine } from "./engines";
+import type { NormalizedFinding } from "./findings";
+import type { EngineResult } from "./run";
+
+function describeFinding(finding: NormalizedFinding): string {
+	return `${finding.file}:${finding.line}:${finding.column} ${finding.rule} ${finding.severity} ${finding.text}`;
+}
+
+function describeCounts(result: EngineResult): string {
+	if (!isFindingEngine(result.name)) {
+		return `exit ${result.exitCode}`;
+	}
+	return `${result.reported.length} new, ${result.resolved} resolved, ${result.warnings.length} warnings`;
+}
+
+function describeStatus(result: EngineResult): string {
+	if (result.status === "error") {
+		return "error";
+	}
+	return `${result.status} (${describeCounts(result)})`;
+}
+
+/**
+ * engine1つ分の出力sectionを組み立てる
+ */
+export function formatEngineSection(result: EngineResult): string {
+	const lines = [`== ${result.name} ==`];
+	if (result.output !== "" && !isFindingEngine(result.name)) {
+		lines.push(result.output);
+	}
+	for (const finding of [...result.reported, ...result.warnings]) {
+		lines.push(describeFinding(finding));
+	}
+	if (result.message !== undefined) {
+		lines.push(result.message);
+	}
+	lines.push(`${result.name}: ${describeStatus(result)}`);
+	return lines.join("\n");
+}
+
+/**
+ * 失敗したengineを列挙した集約summaryを組み立てる
+ */
+export function formatSummary(results: EngineResult[]): string {
+	const failed = results
+		.filter((result) => result.status !== "passed")
+		.map((result) => result.name);
+	const passed = results
+		.filter((result) => result.status === "passed")
+		.map((result) => result.name);
+	if (failed.length === 0) {
+		return `quality-check: ${results.length} engines passed`;
+	}
+	const lines = [
+		`quality-check: ${failed.length} of ${results.length} engines failed`,
+		`  failed: ${failed.join(", ")}`,
+	];
+	if (passed.length > 0) {
+		lines.push(`  passed: ${passed.join(", ")}`);
+	}
+	return lines.join("\n");
+}
+
+/**
+ * engineの結果をJSONへ変換する
+ */
+export function toJsonReport(results: EngineResult[]): unknown {
+	return {
+		engines: results.map((result) => ({
+			detected: result.detected.length,
+			exitCode: result.exitCode,
+			message: result.message ?? null,
+			name: result.name,
+			reported: result.reported,
+			resolved: result.resolved,
+			status: result.status,
+			warnings: result.warnings,
+		})),
+		failed: results
+			.filter((result) => result.status !== "passed")
+			.map((result) => result.name),
+	};
+}

package/src/run.ts

@@ -0,0 +1,183 @@
+import { type BaselineFile, compareWithBaseline } from "./baseline";
+import { type EngineName, enabledEngines, type QualityConfig } from "./config";
+import {
+	buildEngineCommand,
+	ENGINE_BINS,
+	type EngineCommandContext,
+	type EngineProcessResult,
+	type EngineRunner,
+	isFindingEngine,
+	resolveExecutable,
+	runEngineProcess,
+} from "./engines";
+import { type NormalizedFinding, parseFindings } from "./findings";
+
+/**
+ * engine1つ分の実行状態
+ */
+export type EngineStatus = "error" | "failed" | "passed";
+
+/**
+ * engine1つ分の実行結果
+ */
+export interface EngineResult {
+	/** baseline適用前の阻害する検出 */
+	detected: NormalizedFinding[];
+	exitCode: number | null;
+	message?: string;
+	name: EngineName;
+	output: string;
+	/** baseline適用後に残った阻害する検出 */
+	reported: NormalizedFinding[];
+	resolved: number;
+	status: EngineStatus;
+	warnings: NormalizedFinding[];
+}
+
+/**
+ * engineをまとめて起動するための実行条件
+ */
+export interface RunOptions {
+	/** 適用するbaseline nullなら差分判定を行わない */
+	baseline: BaselineFile | null;
+	config: QualityConfig;
+	cwd: string;
+	/** file走査engineへ渡す対象path */
+	targets: string[];
+	/** comment-checkのbaseline差分を無効化する未作成のpath */
+	rawBaseline: string;
+	/** engineの実行fileを解決する関数 テストでは差し替える */
+	resolve?: (name: EngineName, cwd: string) => string | null;
+	runner?: EngineRunner;
+}
+
+function baseResult(
+	name: EngineName,
+	exitCode: number | null,
+	output: string,
+): Omit<EngineResult, "status"> {
+	return {
+		detected: [],
+		exitCode,
+		name,
+		output,
+		reported: [],
+		resolved: 0,
+		warnings: [],
+	};
+}
+
+function joinOutput(result: EngineProcessResult): string {
+	return [result.stdout, result.stderr]
+		.map((part) => part.trimEnd())
+		.filter((part) => part !== "")
+		.join("\n");
+}
+
+function describeError(error: unknown): string {
+	return error instanceof Error ? error.message : String(error);
+}
+
+async function runFindingEngine(
+	name: EngineName,
+	options: RunOptions,
+	executable: string,
+	context: EngineCommandContext,
+	runner: EngineRunner,
+): Promise<EngineResult> {
+	const result = await runner(buildEngineCommand(name, executable, context), {
+		cwd: options.cwd,
+	});
+	const output = joinOutput(result);
+	if (result.exitCode === 2) {
+		return {
+			...baseResult(name, 2, output),
+			message: `${name} could not finish`,
+			status: "error",
+		};
+	}
+	let parsed: ReturnType<typeof parseFindings>;
+	try {
+		parsed = parseFindings(name, result.stdout);
+	} catch (error) {
+		return {
+			...baseResult(name, result.exitCode, output),
+			message: describeError(error),
+			status: "error",
+		};
+	}
+	const comparison =
+		options.baseline === null
+			? { added: parsed.errors, resolved: [] }
+			: compareWithBaseline(parsed.errors, options.baseline);
+	return {
+		...baseResult(name, result.exitCode, output),
+		detected: parsed.errors,
+		reported: comparison.added,
+		resolved: comparison.resolved.length,
+		status: comparison.added.length > 0 ? "failed" : "passed",
+		warnings: parsed.warnings,
+	};
+}
+
+async function runProcessEngine(
+	name: EngineName,
+	options: RunOptions,
+	executable: string,
+	context: EngineCommandContext,
+	runner: EngineRunner,
+): Promise<EngineResult> {
+	const result = await runner(buildEngineCommand(name, executable, context), {
+		cwd: options.cwd,
+	});
+	const output = joinOutput(result);
+	if (result.exitCode === 2) {
+		return {
+			...baseResult(name, 2, output),
+			message: `${name} could not finish`,
+			status: "error",
+		};
+	}
+	return {
+		...baseResult(name, result.exitCode, output),
+		status: result.exitCode === 0 ? "passed" : "failed",
+	};
+}
+
+async function runEngine(
+	name: EngineName,
+	options: RunOptions,
+	context: EngineCommandContext,
+	runner: EngineRunner,
+): Promise<EngineResult> {
+	const executable = (options.resolve ?? resolveExecutable)(name, options.cwd);
+	if (executable === null) {
+		return {
+			...baseResult(name, null, ""),
+			message: `${ENGINE_BINS[name]} is not installed`,
+			status: "error",
+		};
+	}
+	if (isFindingEngine(name)) {
+		return await runFindingEngine(name, options, executable, context, runner);
+	}
+	return await runProcessEngine(name, options, executable, context, runner);
+}
+
+/**
+ * 設定で有効なengineを順に起動する
+ */
+export async function runEngines(options: RunOptions): Promise<EngineResult[]> {
+	const runner = options.runner ?? runEngineProcess;
+	const context: EngineCommandContext = {
+		config: options.config,
+		ignores: options.config.ignore ?? [],
+		rawBaseline: options.rawBaseline,
+		targets: options.targets,
+	};
+	const results: EngineResult[] = [];
+	for (const name of enabledEngines(options.config)) {
+		results.push(await runEngine(name, options, context, runner));
+	}
+	return results;
+}