@yuu1111/quality-check 1.0.0 → 4.0.0

package/README.ja.md

@@ -2,7 +2,7 @@
 
 # @yuu1111/quality-check
 
-Projectごとのscriptから個別に呼んでいたBiome、型検査、Knip、code-style-check、comment-check、document-style-check、TSDoc checkerを1つのCLIへまとめる baselineの差分判定もここで行う
+設定したengineを1つのCLIで実行し baselineの差分判定も持つ統合runner
 
 ## Install
 
@@ -10,14 +10,13 @@ Projectごとのscriptから個別に呼んでいたBiome、型検査、Knip、c
 bun add -D @yuu1111/quality-check
 ```
 
-このCLIは `comment-check`、`document-style-check`、`tsdoc-check` を、configの型がengineの公開するrule名を取り込むためpeer dependencyとして持つ
-package managerはこのCLIと一緒に導入し、engineのbinaryは利用Projectの `node_modules/.bin` から実行時に解決する
-
-`@yuu1111/code-style-check` を宣言するProjectではKnipが未使用依存として報告するため `knip.ts` の `ignoreDependencies` で理由付きに宣言する
+4つの検出engine `code-style-check`、`comment-check`、`document-style-check`、`tsdoc-check` はこのpackageへ同梱する
+`bun build` がprivateなworkspace packageを `dist/cli.js` へbundleするため、このpackageを導入すればengine packageの追加導入も実行時の解決も要らない
+Biome、`tsc`、Knipは子プロセスのままで、利用Projectの `node_modules/.bin` から解決する
 
 ## Usage
 
-`quality.config.ts` で起動するengineとengineごとの起動条件を指定し、scriptから起動する
+`quality.json` で起動するengineを指定し、scriptから起動する
 
 ```json
 {
@@ -28,27 +27,35 @@ package managerはこのCLIと一緒に導入し、engineのbinaryは利用Proje
 ```
 
 ```ts
-import { defineConfig } from "@yuu1111/quality-check";
-
-export default defineConfig({
-	engines: {
-		biome: true,
-		typecheck: true,
-		knip: true,
-		"code-style-check": true,
-		"comment-check": true,
-		"document-style-check": true,
-		"tsdoc-check": true,
-	},
-	config: {
-		"comment-check": {
-			ignore: ["another-project"],
-			rules: { "japanese-period": "on" },
-		},
-		"document-style-check": { enable: true },
-		"tsdoc-check": { error: true },
-	},
-});
+{
+  "$schema": "./node_modules/@yuu1111/quality-check/schema.json",
+  "biome": {
+    "enabled": true
+  },
+  "comment-check": {
+    "enabled": true,
+    "ignore": ["another-project"],
+    "rules": {
+      "preset": "recommended",
+      "content": {
+        "japanese-period": "on"
+      }
+    }
+  },
+  "document-style-check": {
+    "enabled": true,
+    "rules": {
+      "preset": "all"
+    }
+  },
+  "tsdoc-check": {
+    "enabled": true,
+    "rules": {
+      "preset": "all"
+    }
+  },
+  "failOnWarnings": true
+}
 ```
 
 engineごとの出力と所要時間、集約summaryを並べて出し、どのengineが失敗したかと実行にかかった合計時間を1回の実行で示す
@@ -73,25 +80,26 @@ quality-check: 1 of 3 engines failed (1250ms)
 
 | Field | 説明 |
 |-------|-------------|
-| `engines` | 起動するengine、値は `true` または `false` |
-| `config` | engineごとの起動条件 |
+| `<engine>` | engineごとのsectionで `enabled` が起動を決める |
+| `<engine>.rules` | 同梱する4つの検出engineのrule選択 |
+| `failOnWarnings` | warningを阻害する検出として扱う |
 | `baseline` | baseline fileのpath `false` なら差分判定を行わない |
 
 engineは `biome` → `typecheck` → `knip` → `code-style-check` → `comment-check` → `document-style-check` → `tsdoc-check` の順に実行する
 
-`engines` は起動の委任だけを表し、起動条件は `config` のengineの下へ置く engineごとの条件は複数行のobjectとして書き、ruleやoptionを足しても他のengineの行が動かないようにする engineが受け取る条件は次のとおり
+engineごとのsectionが `enabled` とそのengineが受け取る条件を持つ engineが受け取らない条件は設定errorにし、打ち間違いが黙って無視されないようにする `biome`、`typecheck`、`knip` は子プロセスで起動し、4つの検出engineはin-processで起動する
 
 | Engine | Command | 条件 |
-|--------|-----------------|--------------|
+|--------|---------|--------------|
 | `biome` | `biome check` | `targets`、`args` 除外pathは `biome.json` が持つ |
 | `typecheck` | `tsc --noEmit` | `args`、`projects` 設定は `tsconfig.json` が持つ |
 | `knip` | `knip` | `args` 設定は `knip.ts` が持つ |
-| `code-style-check` | `code-style-check --json` | `ignore`、`targets`、`args` |
-| `comment-check` | `comment-check --json` | `ignore`、`targets`、`args`、`enable`、`rules` |
-| `document-style-check` | `document-style-check lint --json` | `ignore`、`targets`、`args`、`enable`、`rules` |
-| `tsdoc-check` | `tsdoc-check --json` | `ignore`、`targets`、`args`、`enable`、`error`、`rules` |
+| `code-style-check` | in-process | `ignore`、`targets`、`rules` |
+| `comment-check` | in-process | `ignore`、`targets`、`rules` |
+| `document-style-check` | in-process | `ignore`、`targets`、`rules` |
+| `tsdoc-check` | in-process | `ignore`、`targets`、`rules` |
 
-`args` はengineの既定引数の後ろへ足す
+`args` は子プロセスengineだけが受け取り、engineの既定引数の後ろへ足す
 設定fileで表せない起動条件や、engineの引数が変わったときの逃げ道として使う
 
 engineが受け取らない条件は渡さず、その旨をそのengineのsectionへ出す
@@ -101,30 +109,78 @@ engineが受け取らない条件は渡さず、その旨をそのengineのsecti
 biome: ignore skipped (biome.json holds its settings)
 ```
 
-`enable` と `error` はruleをまとめて選び、`rules` はruleを1つずつ選ぶ
-`enable: true` はengineが既定で無効にしているruleを全て有効にする
-`error: true` は `tsdoc-check` の全ruleを違反として扱い、opt-inのruleは先に有効にする 違反へ上げられるのはこのengineだけ
-`rules` はrule名をkeyにして `off`、`on`、`error` のいずれかを渡す `on` はengineの既定のまま、`error` はそのruleだけpresetと同じ扱いにする
-keyがrule名そのものなので導入済みengineのunionで型付けし、engineが知らない名前は起動時の失敗ではなく型errorになる
-`error` を取れるのは `tsdoc-check` だけ、`off` を取れるのは既定で無効のruleだけで、既定で有効なruleを無効にする引数をengineは持たない
-選んだruleは `--enable <rule>` になり、`tsdoc-check` では `--error <rule>` にもなる 他のengineはこれらのoptionを拒否する
+`rules` は同梱するengineのどのruleを実行してどう報告するかを選ぶ
+`rules.preset` は一括で選び `recommended` はengineの既定 `all` は全て有効 `none` は全て無効にする
+group名のkeyはengineが公開するruleのまとまりで、そのgroupの全ruleへ `off`、`on`、`error` を渡す
+group名の下のobjectはruleを1つずつ選ぶ
+具体的な指定が勝つため preset、group、rule の順に書ける
+`off` は既定で有効なruleにも渡せ、`on` はengineの既定severityのままにする
+`error` を取れるのは `tsdoc-check` だけで、そのruleを違反へ上げ opt-inのruleは先に有効にする
+engineが知らないgroup名やrule名は設定errorになり、配布する `schema.json` がeditorへ同じ語彙を教える
+選んだruleは同梱するengineへ直接渡すため、CLIは `--enable`、`--disable`、`--error` へは変換しない
 
-`comment-check` はbaseline差分を無効化する未作成のpathを渡して起動する
-新規と解消済みの判定はengineごとではなく統合CLIが1つのbaseline fileで行うため、既存の `comment-baseline.json` がある場合は `--update-baseline` で移す
+検出engineはbaselineを持たないため、新規と解消済みの判定はengineごとではなく統合CLIが1つのbaseline fileで行う
 
 `typecheck` は `projects` に並べたtsconfigごとに `tsc --noEmit -p <path>` を起動する
 省略時はカレントの `tsconfig.json` を1回だけ読む
 
+## Baseline
+
+既存のtreeへ検査を導入するProjectは、その時点の検出を `quality-baseline.json` へ記録し、後から増えた検出だけを失敗にする
+`--update-baseline` はそのfileを現在の検出で置き換える
+
+```bash
+quality-check --update-baseline
+```
+
+実行のたびに新規の検出を報告し、現れなくなったbaselineのentryを `resolved` として数える
+新規の検出は直し、意図して受け入れるときだけ `--update-baseline` を実行する
+entryの同一性はengineとruleとfileと検出messageで決まるため、messageが変わるとそのruleは再登録が必要になる
+`quality.json` の `baseline` を `false` にすると差分判定を行わず、全ての検出を報告する
+
+## Commands
+
+`quality-check document-style` は同梱する `document-style-check` の検証記録を実行する
+
+```bash
+quality-check document-style lint .
+quality-check document-style lint --write .
+quality-check document-style lint --enable japanese-period .
+quality-check document-style scan doc.md --rules SKILL.md --review review.json
+quality-check document-style check doc.md --rules SKILL.md --review review.json
+```
+
+| Command | 説明 |
+|---------|-------------|
+| `scan` | 対象文書の未確認の検証記録を書き出す |
+| `check` | 埋めた検証記録を現在の本文と基準に対して確認する |
+| `lint` | 機械的な違反を報告し、`--write`で整形する |
+
+記録は本文と基準のhashを固定するため、どちらかを編集すると無効になる `check`が保証するのは全項目に判断と根拠があることだけで、文体判断の正しさは別に確認する
+
 ## Options
 
 | Option | 説明 |
 |--------|-------------|
-| `--config <path>` | 読み込むconfig file（既定は `quality.config.ts`） |
+| `--config <path>` | 読み込むconfig file（既定は `quality.json`） |
 | `--baseline <path>` | baseline fileを上書きする |
 | `--ignore <path>` | 除外pathを追加する、複数指定できる |
 | `--update-baseline` | 現在の検出でbaselineを置き換える |
 | `--json` | engineごとの結果をJSONで出力する |
+| `document-style <command>` | 検証記録を実行する（`scan`、`check`、`lint`） |
 
 `--ignore` と位置引数の対象pathは、その条件を受け取るengineへだけ渡す
 
+### document-style
+
+| Option | 説明 |
+|--------|-------------|
+| `--rules <path>` | `## 判断基準`を持つ基準fileで、`scan`と`check`では必須 |
+| `--review <path>` | 読み書きする検証記録file |
+| `--enable <rule>` | opt-in ruleを実行する、複数指定できる |
+| `--disable <rule>` | 既定で有効なruleも含めて無効にする、複数指定できる |
+| `--ignore <path>` | 検査から外すpath、複数指定できる |
+| `--write` | 報告の代わりに整形を適用する |
+| `--json` | 検出をJSONで出力する |
+
 色は標準出力が端末のときだけ付ける `NO_COLOR` で無効にし、`FORCE_COLOR` で強制できる `--json` の出力には付けない

package/README.md

@@ -2,8 +2,7 @@
 
 # @yuu1111/quality-check
 
-Runs Biome, the type checker, Knip, code-style-check, comment-check, document-style-check, and the TSDoc checker from one CLI instead of one script per project.
-The baseline diff lives here too.
+Integrated CLI that runs the configured engines and owns the baseline diff.
 
 ## Install
 
@@ -11,14 +10,13 @@ The baseline diff lives here too.
 bun add -D @yuu1111/quality-check
 ```
 
-`comment-check`, `document-style-check`, and `tsdoc-check` are peer dependencies of this CLI, because the config types embed the rule names those engines publish.
-A package manager installs them with this CLI, and each engine binary is resolved at run time from the project's `node_modules/.bin`.
-
-A project that declares `@yuu1111/code-style-check` sees Knip report it as an unused dependency, so it names it in `ignoreDependencies` with the reason.
+The four finding engines `code-style-check`, `comment-check`, `document-style-check`, and `tsdoc-check` are built into this package.
+`bun build` bundles those private workspace packages into `dist/cli.js`, so installing this package is enough and no engine package has to be installed or resolved at run time.
+Biome, `tsc`, and Knip stay child processes and resolve from the project's `node_modules/.bin`.
 
 ## Usage
 
-Declare the engines to run and the conditions of each engine in `quality.config.ts`, then call the CLI from a script:
+Declare the engines to run in `quality.json`, then call the CLI from a script:
 
 ```json
 {
@@ -29,27 +27,35 @@ Declare the engines to run and the conditions of each engine in `quality.config.
 ```
 
 ```ts
-import { defineConfig } from "@yuu1111/quality-check";
-
-export default defineConfig({
-	engines: {
-		biome: true,
-		typecheck: true,
-		knip: true,
-		"code-style-check": true,
-		"comment-check": true,
-		"document-style-check": true,
-		"tsdoc-check": true,
-	},
-	config: {
-		"comment-check": {
-			ignore: ["another-project"],
-			rules: { "japanese-period": "on" },
-		},
-		"document-style-check": { enable: true },
-		"tsdoc-check": { error: true },
-	},
-});
+{
+  "$schema": "./node_modules/@yuu1111/quality-check/schema.json",
+  "biome": {
+    "enabled": true
+  },
+  "comment-check": {
+    "enabled": true,
+    "ignore": ["another-project"],
+    "rules": {
+      "preset": "recommended",
+      "content": {
+        "japanese-period": "on"
+      }
+    }
+  },
+  "document-style-check": {
+    "enabled": true,
+    "rules": {
+      "preset": "all"
+    }
+  },
+  "tsdoc-check": {
+    "enabled": true,
+    "rules": {
+      "preset": "all"
+    }
+  },
+  "failOnWarnings": true
+}
 ```
 
 Each engine prints its own section with its own time, and the summary names the engines that failed and the total time the run took:
@@ -74,59 +80,109 @@ Exit code 0 means every engine passed, 1 that at least one failed, and 2 that th
 
 | Field | Description |
 |-------|-------------|
-| `engines` | Engines to run, as `true` or `false` |
-| `config` | Conditions of each engine |
+| `<engine>` | One section per engine; `enabled` starts it |
+| `<engine>.rules` | Rule selection of the four built-in finding engines |
+| `failOnWarnings` | Treat every warning as a blocking finding |
 | `baseline` | Baseline file path; `false` disables the diff |
 
 Engines run in the order `biome`, `typecheck`, `knip`, `code-style-check`, `comment-check`, `document-style-check`, `tsdoc-check`.
 
-`engines` only delegates the start-up, and the conditions belong under the engine in `config`.
-Write an engine's conditions as a multi-line object, so a new rule or option changes one engine's block alone.
-Each engine runs:
+Each engine owns a top-level section that holds `enabled` and the conditions that engine takes.
+A condition an engine does not take is rejected, so a typo fails at start-up instead of being ignored.
+`biome`, `typecheck`, and `knip` run as child processes, and the four finding engines run in-process.
 
 | Engine | Command | Conditions |
 |--------|---------|------------|
 | `biome` | `biome check` | `targets`, `args`; `biome.json` holds the excluded paths |
 | `typecheck` | `tsc --noEmit` | `args`, `projects`; `tsconfig.json` holds the settings |
 | `knip` | `knip` | `args`; `knip.ts` holds the settings |
-| `code-style-check` | `code-style-check --json` | `ignore`, `targets`, `args` |
-| `comment-check` | `comment-check --json` | `ignore`, `targets`, `args`, `enable`, `rules` |
-| `document-style-check` | `document-style-check lint --json` | `ignore`, `targets`, `args`, `enable`, `rules` |
-| `tsdoc-check` | `tsdoc-check --json` | `ignore`, `targets`, `args`, `enable`, `error`, `rules` |
+| `code-style-check` | in-process | `ignore`, `targets`, `rules` |
+| `comment-check` | in-process | `ignore`, `targets`, `rules` |
+| `document-style-check` | in-process | `ignore`, `targets`, `rules` |
+| `tsdoc-check` | in-process | `ignore`, `targets`, `rules` |
 
-`args` is appended after the engine defaults, for conditions the config cannot express and for the case where an engine changes its arguments.
+`args` applies only to the child-process engines and is appended after the engine defaults, for conditions the config cannot express and for the case where an engine changes its arguments.
 
-A condition that an engine does not take is not passed on, and the section says so:
+A command line override an engine does not take is not passed on, and the section says so:
 
 ```text
 == biome ==
 biome: ignore skipped (biome.json holds its settings)
 ```
 
-`enable` and `error` pick rules in bulk, and `rules` picks one rule at a time.
-`enable: true` turns on every rule the engine keeps off by default.
-`error: true` turns every rule of `tsdoc-check` into an error, enabling the opt-in ones first; it is the only condition that raises a rule.
-A `rules` entry names one rule and gives it `off`, `on`, or `error`, where `on` keeps the engine default and `error` means the same as the `error` preset for that rule.
-The `rules` key is the rule name itself, so the installed engine's union types it and a name that engine does not know is a type error rather than a start-up failure.
-Only `tsdoc-check` takes `error` in `rules`, and only rules that are off by default take `off`, because no engine can turn off a rule that is on by default.
-Each selected rule becomes `--enable <rule>` and, on `tsdoc-check`, `--error <rule>`; the other engines reject the fields.
+`rules` selects which rules of the built-in engines run and how they are reported.
+`rules.preset` selects in bulk: `recommended` is the engine default, `all` turns every rule on, and `none` turns every rule off.
+A group key names one of the rule groups the engine publishes and takes `off`, `on`, or `error` for every rule in that group.
+An object under a group key names single rules.
+The most specific setting wins, so a preset, a group, and a rule may be written in that order.
+`off` also works for a rule that is on by default, and `on` keeps the engine default severity.
+Only `tsdoc-check` takes `error`, which raises the rule and turns an opt-in rule on first.
+A group or rule name that the engine does not know is a configuration error, and the published `schema.json` teaches an editor the same names.
+The selection is handed to the built-in engines directly, so the CLI no longer turns it into `--enable`, `--disable`, or `--error` arguments.
 
-`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`.
+No check engine keeps a baseline of its own, so the new-and-resolved diff is done by this CLI from a single baseline file.
 
 `typecheck` starts `tsc --noEmit -p <path>` once per path in `projects`, and falls back to the current `tsconfig.json`.
 
+## Baseline
+
+A project that adopts the checks on an existing tree records the findings it has today in `quality-baseline.json`, so only the findings it adds later fail.
+`--update-baseline` replaces that file with the current findings:
+
+```bash
+quality-check --update-baseline
+```
+
+Every run reports the new findings and counts the baseline entries that no longer appear as `resolved`.
+Fix the new findings, and run `--update-baseline` only when the team accepts one on purpose.
+An entry is identified by its engine, rule, file, and message, so a change to a message re-baselines that rule.
+Set `baseline` to `false` in `quality.json` to diff nothing and report every finding.
+
+## Commands
+
+`quality-check document-style` runs the review ledger of the built-in `document-style-check` engine:
+
+```bash
+quality-check document-style lint .
+quality-check document-style lint --write .
+quality-check document-style lint --enable japanese-period .
+quality-check document-style scan doc.md --rules SKILL.md --review review.json
+quality-check document-style check doc.md --rules SKILL.md --review review.json
+```
+
+| Command | Description |
+|---------|-------------|
+| `scan` | Write an unconfirmed review record for the given documents |
+| `check` | Verify a filled review record against the current documents and rules |
+| `lint` | Report mechanical violations, or fix them with `--write` |
+
+The review file pins the document bytes and the rules bytes by hash, so editing either one invalidates the record.
+`check` only confirms that every candidate carries a decision and a reason; it does not judge the writing.
+
 ## Options
 
 | Option | Description |
 |--------|-------------|
-| `--config <path>` | Config file to load (default `quality.config.ts`) |
+| `--config <path>` | Config file to load (default `quality.json`) |
 | `--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 |
+| `document-style <command>` | Run the review ledger (`scan`, `check`, or `lint`) |
 
 `--ignore` and the positional targets reach only the engines that take them.
 
+### document-style
+
+| Option | Description |
+|--------|-------------|
+| `--rules <path>` | Rules file that holds the criteria, required by `scan` and `check` |
+| `--review <path>` | Review file to write or read |
+| `--enable <rule>` | Run an opt-in rule, repeatable |
+| `--disable <rule>` | Turn a rule off, repeatable |
+| `--ignore <path>` | Path to leave out, repeatable |
+| `--write` | Apply `lint` fixes instead of reporting them |
+| `--json` | Print findings as JSON |
+
 Color is added only when stdout is a terminal.
 `NO_COLOR` turns it off and `FORCE_COLOR` turns it on; the `--json` output stays plain.