chaffjs 0.20.0 → 0.22.0

package/rules/vague-word-density.yaml

@@ -1,6 +1,6 @@
 id: vague-word-density
 layer: L2
-status: experimental
+status: stable
 how_to_find: vague-density
 word_list: vague-word
 uses: [pos]
@@ -59,6 +59,7 @@ level_meaning:
   ja: 1000 字あたりあいまいな語 {limit} 個まで
   en: up to {limit} vague words per 1000 words
 rewrite:
+  depth: light
   ja:
     direction: あいまいな語を、何を・どこまで・いつまでに置き換えてください。決まっていないなら、決まっていないことと、誰が決めるのかを書きます。
     pairs:

package/rules/very-adjective.yaml

@@ -1,6 +1,6 @@
 id: very-adjective
 layer: L2
-status: experimental
+status: stable
 how_to_find: intensified-adjective
 word_list: very-intensifier
 extra_word_lists: [very-exception]
@@ -27,6 +27,9 @@ how_to_fix:
 levels: { strict: 1, normal: 2, relaxed: 4 }
 
 use_for: [business, technical, blog, legal, docs, academic, literature, speech]
+off_for:
+  literature: 'Dialect and old usage ("an hospital") are the work''s voice, and dialogue leans on "very".'
+  speech: "A transcript keeps the speaker's words: hedges and ら dropped as spoken."
 
 group: wording
 summary:
@@ -47,6 +50,7 @@ level_meaning:
   ja: very + 形容詞が 1000 語あたり {limit} 個まで
   en: up to {limit} "very" + adjective per 1000 words
 rewrite:
+  depth: light
   en:
     direction: Replace "very" + adjective with a stronger single word, or with what the text says about how much. If the text says nothing more, a plain adjective without "very" will do.
     pairs:

package/rules/weasel-word.yaml

@@ -1,6 +1,6 @@
 id: weasel-word
 layer: L2
-status: experimental
+status: stable
 how_to_find: phrase-match
 word_list: weasel-word
 requires: [pos]
@@ -26,6 +26,10 @@ how_to_fix:
 levels: { strict: 1, normal: 1, relaxed: 2 }
 
 use_for: [business, technical, blog, legal, docs, academic, literature, speech]
+off_for:
+  legal: "Legal drafting repeats its terms and its sentence heads on purpose, puts the actor in the passive (shall be deemed), and joins long noun compounds (個人情報取扱事業者). This rule would only flag the form."
+  literature: 'A narrator and a character speak as they speak: dialect ("would of"), "So," and hearsay are the voice.'
+  speech: "A transcript keeps the speaker's words: hedges and ら dropped as spoken."
 
 group: wording
 summary:
@@ -45,6 +49,7 @@ level_meaning:
   ja: 当てはまる言い回しが {limit} 箇所あれば指摘
   en: reported once there are {limit}
 rewrite:
+  depth: light
   en:
     direction: Replace the unnamed crowd ("many experts", "studies") with the person or study the text or its sources name. If they name none, do not invent one; ask the writer, or state the claim as the writer's own.
     pairs:

package/rules/which-that-consistency.yaml

@@ -0,0 +1,64 @@
+id: which-that-consistency
+layer: L3
+status: stable
+how_to_find: relative-pronoun-mix
+requires: [pos]
+languages: [en]
+severity: info
+
+name:
+  ja: 限定の関係節の which と that が揃っていない
+  en: Restrictive "which" and "that" mixed
+
+why:
+  ja: 英語の限定の関係節（the file that contains the keys）は、that で書く人と which で書く人がいます。米国の手引きは that を勧め、英国の手引きはどちらも認めます。どちらが正しいかは決めません。一つの文書で混ざっていると、読み手は which の節が補足（読点のある非限定の節）なのかと迷います。読点を挟まない「名詞 + which / that + 動詞」だけを数え、少ないほうを指します。
+  en: 'A restrictive relative clause ("the file that contains the keys") opens with "that" for some writers and "which" for others. American guides prefer "that"; British ones accept both. chaff does not pick a side. Mixed in one document, a reader wonders whether a "which" clause is meant as an aside (the non-restrictive kind, set off by a comma). Only "noun + which/that + verb" with no comma between is counted, and the fewer form is pointed at.'
+
+message:
+  ja: 限定の関係節を「{word}」で書いています（この文書はふつう「{usual}」）
+  en: 'This restrictive clause opens with "{word}"; the document mostly uses "{usual}"'
+
+how_to_fix:
+  ja: 文書の多いほうに揃えてください。補足の節にするなら、前に読点を置いて which で書きます。
+  en: Match the rest of the document. If the clause is meant as an aside, set it off with a comma and use "which".
+
+# 少ないほうが何箇所までなら「混在」と見るか。これを超えたら、文書が使い分けている。
+levels: { strict: 4, normal: 2, relaxed: 1 }
+
+use_for: [business, technical, blog, legal, docs, academic, literature, speech]
+off_for:
+  literature: "Length, rhythm, repetition and register are the author's choices in literature, and dialogue mixes styles. Only what one work can hold itself to runs: consistent spacing and commas, and numbering without gaps."
+  speech: "A transcript keeps the speaker's words."
+
+group: consistency
+summary:
+  ja: 英語で、限定の関係節を which で書く所と that で書く所が混ざっている所
+  en: Restrictive clauses opened with "which" in some places and "that" in others
+
+example:
+  en:
+    before: |
+      The job that builds the site runs nightly. The script that checks links runs hourly. The task that sends mail runs daily. The file which stores the keys is encrypted.
+    after: |
+      The job that builds the site runs nightly. The script that checks links runs hourly. The task that sends mail runs daily. The file that stores the keys is encrypted.
+
+not_flagged:
+  ja: 読点のある非限定の節（the rule, which we added,）、前置詞の後ろの which（in which）、that の後ろに主語が来る節（the report that we wrote、the fact that it works）、多いほうが 3 箇所に満たない文書、少ないほうが水準の数を超える文書（使い分けている）は指しません。
+  en: 'A non-restrictive clause set off by a comma ("the rule, which we added,"), "which" after a preposition ("in which"), a "that" followed by its own subject ("the report that we wrote", "the fact that it works"), a document where the usual form appears fewer than 3 times, and one where the fewer form passes the level (used on purpose) are not reported.'
+level_meaning:
+  ja: 少ないほうの書き方が {limit} 箇所以下のとき指摘
+  en: reported when the fewer form appears {limit} times or fewer
+
+rewrite:
+  depth: light
+  en:
+    direction: Change the flagged "which" or "that" to the form the rest of the document uses. If the clause is an aside, add a comma before it and keep "which".
+    pairs:
+      - before: The file which stores the keys is encrypted.
+        after: The file that stores the keys is encrypted.
+      - before: The step which signs the build runs last.
+        after: The step that signs the build runs last.
+    keep:
+      - the clause itself and the rest of the sentence
+    avoid:
+      - changing a "which" clause set off by commas, which is an aside

package/rules/wordy-phrase.yaml

@@ -1,6 +1,6 @@
 id: wordy-phrase
 layer: L2
-status: experimental
+status: stable
 how_to_find: phrase-match
 word_list: wordy-phrase
 requires: [pos]
@@ -27,6 +27,10 @@ how_to_fix:
 levels: { strict: 1, normal: 2, relaxed: 4 }
 
 use_for: [business, technical, blog, legal, docs, academic, literature, speech]
+off_for:
+  legal: 'Drafting writes "in the event that" and "for the purpose of" on purpose.'
+  literature: 'A narrator and a character speak as they speak: dialect ("would of"), "So," and hearsay are the voice.'
+  speech: "A transcript keeps the speaker's words: hedges and ら dropped as spoken."
 
 group: wording
 summary:
@@ -46,6 +50,7 @@ level_meaning:
   ja: 回りくどい言い回しを含む文が {limit} 文あれば指摘
   en: reported once {limit} sentences hold one
 rewrite:
+  depth: light
   en:
     direction: Replace the wordy phrase with its short form from the lexicon. Leave the rest of the sentence alone.
     pairs:

package/rules/yori-as-from.yaml

@@ -0,0 +1,61 @@
+id: yori-as-from
+layer: L3
+status: stable
+how_to_find: origin-particle
+word_list: origin-particle
+extra_word_lists: [origin-head]
+requires: [pos]
+languages: [ja]
+severity: info
+
+name:
+  ja: 起点を言う「より」
+  en: より used for "from"
+
+why:
+  ja: 公用文では、「より」は比べるときだけに使い、時や所の起点は「から」で書きます。「4月1日より開始」「担当者よりご連絡します」の「より」は起点です。比べる「より」（昨年より増えた）と同じ字なので、読み手は一瞬どちらかを考えます。「より」の後に始まり・送り・来ることを言う語（開始、連絡、参る）が続くときだけ指します。
+  en: Japanese official style uses より only for comparison ("more than") and から for a starting point ("from"). In 4月1日より開始 ("starting from 1 April") より marks a start, and the reader has to work out which より it is. chaff reports より only when a word for starting, sending or coming (開始, 連絡, 参る) follows it.
+
+message:
+  ja: 起点の「{word}」は「{suggestion}」と書けます
+  en: '"{word}" marks a starting point here; write "{suggestion}"'
+
+how_to_fix:
+  ja: 起点なら「から」にしてください（4月1日より開始 → 4月1日から開始）。
+  en: For a starting point, write から (4月1日より開始 → 4月1日から開始).
+
+levels: { strict: warning, normal: info, relaxed: info }
+
+use_for: [business, technical, legal, docs, academic, literature, speech]
+off_for:
+  literature: "Spoken 全然大丈夫, なので and より in a character's voice; classical verse has a たり that does not list."
+  speech: "Spoken Japanese says 全然大丈夫, opens with なので and greets with より参りました."
+sources: [koyobun-2022]
+
+group: wording
+summary:
+  ja: 「4月1日より開始」のように、起点を「から」でなく「より」で書いた所
+  en: より written for a starting point (4月1日より開始) where Japanese official style writes から
+example:
+  ja:
+    before: |
+      新しい窓口は4月1日より受付を開始します。
+    after: |
+      新しい窓口は4月1日から受付を開始します。
+
+not_flagged:
+  ja: 比べる「より」（昨年より増えた、これより大きい）と「により」「より一層」は指しません。名詞が続くときは、それが「を」か「する」「いたす」を伴う動作のときだけ指します（昨年より販売が増えた、は指しません）。鉤括弧で引いた中は見ません。
+  en: Comparison (昨年より増えた, "more than last year"), により ("by") and より一層 are not reported. A following noun counts only when it is an action taking を or a light verb, so 昨年より販売が増えた is not reported. Nothing quoted in 「」 is checked.
+rewrite:
+  depth: light
+  ja:
+    direction: 起点を言う「より」を「から」に替えてください。替えるのはその一語だけです。
+    pairs:
+      - before: 新しい窓口は4月1日より受付を開始します。
+        after: 新しい窓口は4月1日から受付を開始します。
+      - before: 詳細は担当者よりご連絡いたします。
+        after: 詳細は担当者からご連絡いたします。
+    keep:
+      - 日付、名前、敬語の形
+    avoid:
+      - 比べる「より」まで替える

package/skills/chaff/SKILL.md

@@ -32,7 +32,7 @@ choice, not a gap; turn it back on (`rules:` in `chaff.yaml`) only when the pers
 ```sh
 npx chaffjs --genre <genre> <file|dir|glob>...   # human-readable, one block per finding (a folder or glob picks up .md / .markdown / .mdx; name a .txt file directly)
 npx chaffjs . --compact                          # two lines per finding: line:col severity message, then the rule id
-npx chaffjs <file> --experimental                # also the experimental rules
+npx chaffjs <file> --experimental                # also the experimental rules (new ones, not yet measured)
 ```
 
 A run exits 1 when a finding is an `error`. It also exits 1 when it could not check anything: no file to
@@ -106,10 +106,10 @@ Use this section when asked to make a text sound less generated: 「AIっぽさ
 
 chaff marks the shapes common in generated text (group "Signs of generated text" in `npx chaffjs rules`: `ai-tell`,
 `contrast-framing`, `stock-transition`, `announcing-opener`, `colon-lead-in` (Japanese only), `assistant-residue`, and the signals
-`ai-generated-composite` reads). Most are experimental: run with `--experimental`. None of them says the text was
+`ai-generated-composite` reads). They run by default outside legal, manual, literary and spoken genres. None of them says the text was
 generated. chaff never rewrites; the rewriting is yours.
 
-**Start with the plan.** Run `npx chaffjs fix-plan <file> --experimental` (with the genre's `--genre`; `--json` to
+**Start with the plan.** Run `npx chaffjs fix-plan <file>` (with the genre's `--genre`; `--json` to
 read it as data). It prints, in the document's language:
 
 - the constraints: keep facts, numbers, conditions and names; add no fact; ask the writer instead of inventing a
@@ -140,7 +140,7 @@ repeats the body. The writer usually wants the structure changed, not only the s
 
 **Light** (only the flagged spots):
 
-1. `npx chaffjs fix-plan <file> --experimental` (or with the genre's `--genre`).
+1. `npx chaffjs fix-plan <file>` (or with the genre's `--genre`).
 2. Rewrite only the flagged spots, each by its rule's direction in the plan. Keep the meaning, numbers, conditions and
    technical constraints.
 3. Run chaff again. At most two rewrite passes.
@@ -148,7 +148,7 @@ repeats the body. The writer usually wants the structure changed, not only the s
 
 **Bold** (section by section, outline kept):
 
-1. Run chaff with `--experimental` and note the document-level signals: the `ai-generated-composite` inputs,
+1. Run chaff and note the document-level signals: the `ai-generated-composite` inputs,
    `bold-density`, `contrast-framing`, `stock-transition`, `sentence-rhythm`.
 2. Rewrite each section toward a human voice: less bold; one-line paragraphs and punchlines folded back into
    paragraphs; no "X ではありません。Y です" / "It's not X. It's Y" frames; lists turned back into sentences where the
@@ -204,7 +204,7 @@ repeats the body. The writer usually wants the structure changed, not only the s
      `chaff compare` catches an added number or name, but not added wording such as 「朝会で冗談が出るようになり」, so
      this one is yours to keep.
 5. **Check.**
-   - `npx chaffjs <old> --experimental` and `npx chaffjs <new> --experimental`: the AI signals before and after.
+   - `npx chaffjs <old>` and `npx chaffjs <new>`: the AI signals before and after.
    - `npx chaffjs outline <old> <new>`: headings, average section length, text in lists, bold, and the structure score
      and each structure measure, before and after. A restructure shows up here, not only in rule counts.
    - `npx chaffjs compare <old> <new> --distinct --allow-dropped heading --allow-added heading`: the headings are the
@@ -249,7 +249,7 @@ output before and after.
 ## Structured documents
 
 - `npx chaffjs tree <file>` shows a contract or specification as a tree of addresses (`3.2` for 第3条第2項 or
-  Section 3.2). `--experimental` adds the structure rules: references to missing provisions, numbering gaps,
+  Section 3.2). A check reads the same tree to find references to missing provisions, numbering gaps and
   terms defined twice.
 - `npx chaffjs cite <source> <quotes.json>` checks that quotations (`[{ "address", "quote" }]`) are really in
   the source; exit 1 if any is not. Use it to back every quotation you put in an answer or a summary.

package/src/api.ts

@@ -107,9 +107,21 @@ export type RuleSpec = {
   readonly name?: Text;
   readonly why?: Text;
   readonly how_to_fix?: Text;
-  readonly example?: { readonly before: Text; readonly after: Text };
+  /** { before, after }, or one pair per language as chaff's own rules write it: { ja: { before, after }, en: … }. */
+  readonly example?: { readonly before: Text; readonly after: Text } | Readonly<Record<string, { readonly before: string; readonly after: string }>>;
   readonly message?: Text;
+  /** One severity for normal; strict is one heavier and relaxed one lighter. Or levels, not both. */
   readonly level?: Severity;
+  /** A severity for each level, as chaff's rules with nothing to count write them. normal is required. */
+  readonly levels?: Readonly<Partial<Record<"strict" | "normal" | "relaxed", Severity>>>;
+  /** The genres the rule is for, or their first part (business, business/report). Without it, every genre. */
+  readonly use_for?: readonly string[];
+  /** Where the rule reference lists it (readability, wording, …). Without it, team. */
+  readonly group?: string;
+  /** What the rule finds, in one line. Without it, the name. */
+  readonly summary?: Text;
+  /** How chaff fix-plan rewrites what the rule flags: depth (light / structure / register) and, by language, direction, pairs, keep and avoid. */
+  readonly rewrite?: Readonly<Record<string, unknown>>;
   /** The languages the rule checks. Without it, every language. */
   readonly languages?: readonly string[];
   /** A word list by name; the detector gets it as options.lexicon. A plugin's own lists are named without the plugin's prefix. */

package/src/cli-text.ts

@@ -5,6 +5,11 @@ import { counted, formFor } from "./render/plural.ts";
 import type { GenreSetting } from "./genre-check.ts";
 import type { ProfileSetting } from "./profile/check.ts";
 
+const ASCII_AT = /[\x21-\x7e]/u;
+
+/** A word set in Japanese text with a space on each side where it starts or ends with Latin text, as the guide writes it. */
+const spacedInJapanese = (word: string): string => `${ASCII_AT.test(word.at(0) ?? "") ? " " : ""}${word}${ASCII_AT.test(word.at(-1) ?? "") ? " " : ""}`;
+
 /** What a folder walk looked for, and how to look for more. Markdown always; include adds file-name globs. */
 const lookedForJa = (include: readonly string[]): string => {
   const also = include.length > 0 ? `と ${include.join(" ")}` : "";
@@ -26,6 +31,8 @@ const USAGE_JA = `chaff — 文章の読みにくいところを見つけます
   chaff test <file|dir>...       意味を読む検査も動かす（API key が要ります）
                                  判定役は chaff.yaml の ai_backend で選びます
   chaff init                     chaff.yaml を作る（端末ならジャンルを尋ねる。--genre <ジャンル> でも選べる）
+  chaff init --plugin <名前>     YAML だけのルールの束（chaff-plugin-<名前>/）を作る
+  chaff plugin-test [フォルダ]   プラグインの各ルールを、そのルールの例にかけて確かめる
   chaff --version                chaffjs と言語パッケージの版
   chaff eval <dir>               手元の文書で閾値を測り直す
   chaff explain <rule>           そのルールの意図と根拠を読む
@@ -69,6 +76,8 @@ const USAGE_EN = `chaff — finds what makes writing hard to read. It never rewr
   chaff test <file|dir>...       also run the checks that read meaning (needs an API key)
                                  the judge is chosen by ai_backend in chaff.yaml
   chaff init                     create chaff.yaml (asks for the genre at a terminal; --genre <genre> chooses it)
+  chaff init --plugin <name>     create a YAML rule pack, chaff-plugin-<name>/
+  chaff plugin-test [folder]     run each rule of a plugin on the rule's own example
   chaff --version                the version of chaffjs and its language packages
   chaff eval <dir>               re-measure the limits on your own documents
   chaff explain <rule>           read what a rule is for and why
@@ -107,6 +116,8 @@ A rule's level is one of strict / normal / relaxed / off.
 
 export type CliText = {
   readonly usage: string;
+  /** Under one command's lines of the usage, for `chaff <command> --help`. */
+  readonly moreHelp: string;
   readonly languageName: (language: string) => string;
   readonly genreSource: Readonly<Record<GenreSource, string>>;
   readonly header: (path: string, genre: string, language: string, from: string, shelved: number, hushed: number) => string;
@@ -135,6 +146,7 @@ export type CliText = {
 export const CLI_TEXT: Texts<CliText> = {
   ja: {
     usage: USAGE_JA,
+    moreHelp: "すべてのコマンドと共通の指定は npx chaffjs --help で出ます。",
     languageName: (language) => (language === "ja" ? "日本語" : "英語"),
     genreSource: {
       "--genre": "--genre",
@@ -146,9 +158,11 @@ export const CLI_TEXT: Texts<CliText> = {
       content: "内容",
     },
     header: (path, genre, language, from, shelved, hushed) =>
-      [`${path}   ${genre} · ${language}   ジャンルは${from}から`, shelved > 0 ? `   棚上げ ${shelved} 件` : "", hushed > 0 ? `   stet ${hushed} 件` : ""].join(
-        "",
-      ),
+      [
+        `${path}   ${genre} · ${language}   ジャンルは${spacedInJapanese(from)}から`,
+        shelved > 0 ? `   棚上げ ${shelved} 件` : "",
+        hushed > 0 ? `   stet ${hushed} 件` : "",
+      ].join(""),
     suggested: (name, genre) => `   ${name}のようです。--genre ${genre} を試せます`,
     suggestedNote: (name, genre, used) =>
       `  ジャンルを決めていないので、${used} として見ました。${name}なら、--genre ${genre} でその種類の書き方に合わせて見ます（npx chaffjs genres で一覧）。`,
@@ -156,7 +170,7 @@ export const CLI_TEXT: Texts<CliText> = {
     noMarkdownHere: (include) => `検査するファイルが 1 つも見つかりませんでした。\n${lookedForJa(include)}`,
     noAdapter: (language) => `言語 "${language}" のアダプタがありません。`,
     unknownGenre: (genre, where, known) =>
-      `ジャンル "${genre}" はありません（${where}）。使えるのは ${known.join("、")} です。npx chaff genres で一覧が出ます。`,
+      `ジャンル "${genre}" はありません（${where}）。使えるのは ${known.join("、")} です。npx chaffjs genres で一覧が出ます。`,
     genreWhere: (where, files) => {
       if (where === "config") return "chaff.yaml の genre";
       return where === "by_path" ? `chaff.yaml の by_path、files: ${files.join(", ")}` : "--genre";
@@ -166,7 +180,7 @@ export const CLI_TEXT: Texts<CliText> = {
     unknownProfile: (profile, where, known) =>
       `文書の種類 "${profile}" はありません（${where}）。使えるのは ${known.join("、")} と、種類を使わない none です。`,
     profileWhere: (where, files) => (where === "config" ? "chaff.yaml の profile" : `chaff.yaml の by_path、files: ${files.join(", ")}`),
-    unknownRule: (id) => `${id} というルールはありません。npx chaff rules で一覧が出ます。`,
+    unknownRule: (id) => `${id} というルールはありません。npx chaffjs rules で一覧が出ます。`,
     unknownRuleWithList: (id, list) => `${id} というルールはありません。\n一覧:\n${list}`,
     unnamed: "(名前なし)",
     sarifWritten: (path, count) => `\n  SARIF を書きました: ${path}（${count} 件）`,
@@ -187,6 +201,7 @@ export const CLI_TEXT: Texts<CliText> = {
   },
   en: {
     usage: USAGE_EN,
+    moreHelp: "npx chaffjs --help lists every command and the options they share.",
     languageName: (language) => (language === "ja" ? "Japanese" : "English"),
     genreSource: {
       "--genre": "--genre",
@@ -205,7 +220,7 @@ export const CLI_TEXT: Texts<CliText> = {
     noMarkdown: (targets, include) => `No files to check found: ${targets}\n${lookedForEn(include)}`,
     noMarkdownHere: (include) => `No files to check found.\n${lookedForEn(include)}`,
     noAdapter: (language) => `No language package for "${language}".`,
-    unknownGenre: (genre, where, known) => `There is no genre "${genre}" (${where}). The genres are ${known.join(", ")}. npx chaff genres lists them.`,
+    unknownGenre: (genre, where, known) => `There is no genre "${genre}" (${where}). The genres are ${known.join(", ")}. npx chaffjs genres lists them.`,
     genreWhere: (where, files) => {
       if (where === "config") return "genre in chaff.yaml";
       return where === "by_path" ? `by_path in chaff.yaml, files: ${files.join(", ")}` : "--genre";
@@ -215,7 +230,7 @@ export const CLI_TEXT: Texts<CliText> = {
     unknownProfile: (profile, where, known) =>
       `There is no document profile "${profile}" (${where}). The profiles are ${known.join(", ")}; none uses no profile.`,
     profileWhere: (where, files) => (where === "config" ? "profile in chaff.yaml" : `by_path in chaff.yaml, files: ${files.join(", ")}`),
-    unknownRule: (id) => `There is no rule named ${id}. npx chaff rules lists them.`,
+    unknownRule: (id) => `There is no rule named ${id}. npx chaffjs rules lists them.`,
     unknownRuleWithList: (id, list) => `There is no rule named ${id}.\nRules:\n${list}`,
     unnamed: "(no name)",
     sarifWritten: (path, count) => `\n  Wrote SARIF: ${path} (${counted(count, "finding")})`,

package/src/cli.ts

@@ -13,8 +13,8 @@ import { runEval } from "./commands/eval.ts";
 import { runTest } from "./commands/test.ts";
 import { GENRES } from "./genre.ts";
 import { resolveGenre } from "./resolve-genre.ts";
-import { runInit } from "./init.ts";
-import { initGenre } from "./commands/init-ask.ts";
+import { runInitCommand } from "./commands/init-command.ts";
+import { runPluginTest } from "./commands/plugin-test.ts";
 import { targetsOf, withExperimental, withIncludes } from "./cli-args.ts";
 import { rulesOf } from "./custom/load.ts";
 import { renderCompact } from "./render/compact.ts";
@@ -29,6 +29,8 @@ import { renderSarif } from "./render/sarif.ts";
 import { VERSION, VERSION_LINES } from "./version.ts";
 import type { TreeContext } from "./commands/tree.ts";
 import { DOCUMENT_COMMANDS } from "./commands/document-commands.ts";
+import { asksForHelp } from "./command-help.ts";
+import { printCommandHelp } from "./commands/help.ts";
 import { runSkill } from "./commands/skill.ts";
 import { GRADE_EXIT, runGrade } from "./commands/grade.ts";
 import { fixPlanTargets, runFixPlan } from "./commands/fix-plan.ts";
@@ -280,19 +282,15 @@ const measureContext = (argv: readonly string[], config: Config): { config: Conf
 
 /** 分岐を数珠つなぎにせず表にする。足すときに main を太らせない。 */
 const HANDLERS: Readonly<Record<string, Handler>> = {
-  init: async (argv, config) => {
-    const ui = hostLanguage(config.language, process.env);
-    const chosen = await initGenre(flag(argv, "--genre"), ui, process.cwd());
-    if ("error" in chosen) console.error(chosen.error);
-    else runInit(process.cwd(), chosen.genre, ui).forEach((line) => console.log(line));
-    return "error" in chosen ? 1 : 0;
-  },
+  init: (argv, config) => runInitCommand((name) => flag(argv, name), argv.includes("--plugin"), hostLanguage(config.language, process.env), process.cwd()),
   genres: (_argv, config) => showGenres(config),
   rules: showRules,
   explain: (argv, config) => explain(config, argv[1], flag(argv, "--genre")),
   eval: (argv, config) => runEval(positional(argv), argv, { ...measureContext(argv, config), flag }),
   ...Object.fromEntries(Object.entries(DOCUMENT_COMMANDS).map(([name, run]): [string, Handler] => [name, (argv, config) => run(argv, treeContext(config))])),
   test: (argv, config) => runTest(positional(argv), argv, { ...measureContext(argv, config), inspect }),
+  "plugin-test": (argv, config) =>
+    runPluginTest(positional(argv)[0], { ui: hostLanguage(config.language, process.env), check: async (...args) => (await inspect(...args)).checked }),
   "fix-plan": (argv, config) =>
     runFixPlan(fixPlanTargets(argv), argv, { ...treeContext(config), check: async (path) => (await inspectAll(config, argv)(path)).checked }),
   baseline: (argv, config) => runBaseline(positional(argv), argv, config),
@@ -338,6 +336,7 @@ const dispatch = async (argv: readonly string[]): Promise<number> => {
     console.log(VERSION_LINES.join("\n"));
     return 0;
   }
+  if ((first === "lint" || HANDLERS[first] !== undefined) && asksForHelp(argv)) return printCommandHelp(hostText(readConfig()), first);
   // 知らないジャンルではどの rule も当たらず、知らない文書の種類では種類の知識が外れる。どちらも素通りに見えるので、何かする前に止める。
   const config = withIncludes(await withExtensions(readConfig()), argv);
   const problems = settingProblems(first, flag(argv, "--genre"), config, hostText(config), hostLanguage(config.language, process.env));

package/src/command-help.ts

@@ -0,0 +1,26 @@
+// Pure: what `chaff <command> --help` prints, taken from the usage that `chaff --help` prints, so the two cannot drift.
+
+const ENTRY = /^ {2}chaff (\S+)/u;
+const CONTINUATION = /^ {3,}\S/u;
+const HELP_FLAGS: ReadonlySet<string> = new Set(["--help", "-h"]);
+
+/** Whether the arguments after the command ask for its help. */
+export const asksForHelp = (argv: readonly string[]): boolean => argv.slice(1).some((arg) => HELP_FLAGS.has(arg));
+
+const namesOf = (line: string): readonly string[] => ENTRY.exec(line)?.[1]?.split("|") ?? [];
+
+/** The usage's lines for one command: each line naming it ("  chaff relax|strict|off …"), with the lines indented under it. */
+export const commandUsage = (usage: string, command: string): string[] =>
+  usage.split("\n").reduce<{ owned: boolean; lines: string[] }>(
+    (state, line) => {
+      const owned = ENTRY.test(line) ? namesOf(line).includes(command) : state.owned && CONTINUATION.test(line);
+      return { owned, lines: owned ? [...state.lines, line] : state.lines };
+    },
+    { owned: false, lines: [] },
+  ).lines;
+
+/** `chaff <command> --help`: the command's lines of the usage and where the rest is, or the whole usage when it has none. */
+export const commandHelp = (usage: string, command: string, moreHelp: string): string => {
+  const lines = commandUsage(usage, command);
+  return lines.length === 0 ? usage : [...lines, "", moreHelp].join("\n");
+};

package/src/commands/eval.ts

@@ -20,11 +20,11 @@ const TEXT: Texts<{
   readonly unknownRule: (id: string) => string;
 }> = {
   ja: {
-    mixed: (mixes) => `言語かジャンルが混ざっています: ${mixes}\n1 つに絞って測ってください（例: npx chaff eval examples/blog-ja/）。`,
+    mixed: (mixes) => `言語かジャンルが混ざっています: ${mixes}\n1 つに絞って測ってください（例: npx chaffjs eval examples/blog-ja/）。`,
     unknownRule: (id) => `${id} という rule はありません。`,
   },
   en: {
-    mixed: (mixes) => `Languages or genres are mixed: ${mixes}\nMeasure one at a time (for example npx chaff eval examples/blog-en/).`,
+    mixed: (mixes) => `Languages or genres are mixed: ${mixes}\nMeasure one at a time (for example npx chaffjs eval examples/blog-en/).`,
     unknownRule: (id) => `There is no rule named ${id}.`,
   },
 };

package/src/commands/fix-plan.ts

@@ -4,12 +4,17 @@ import { structureOf } from "../structure-shape/of-document.ts";
 import { buildFixPlan } from "../fix-plan/plan.ts";
 import { renderFixPlanJson, renderFixPlanMarkdown } from "../fix-plan/render.ts";
 import { FIX_PLAN_TEXT } from "../fix-plan/text.ts";
+import { chosenDepthOf } from "../fix-plan/chosen-depth.ts";
 import type { Checked } from "./feedback.ts";
 import { readDocument } from "./read-document.ts";
 import type { TreeContext } from "./tree.ts";
 
 /** Options whose value is the next argument. That value is not a file. */
-const VALUED: ReadonlySet<string> = new Set(["--language", "--genre"]);
+const VALUED: ReadonlySet<string> = new Set(["--language", "--genre", "--depth"]);
+
+/** --depth's value: undefined when not given, empty when given with nothing after it (which is then reported). */
+const depthFlag = (argv: readonly string[], context: FixPlanContext): string | undefined =>
+  argv.includes("--depth") ? (context.flag(argv, "--depth") ?? "") : undefined;
 
 export const fixPlanTargets = (argv: readonly string[]): string[] =>
   argv.slice(1).filter((arg, index, all) => !arg.startsWith("--") && !VALUED.has(all[index - 1] ?? ""));
@@ -24,6 +29,12 @@ export type FixPlanContext = TreeContext & {
  * the document-level signals, the structure targets from human articles, a recommended mode and the checks to run after. Deterministic; sends nothing anywhere.
  */
 export const runFixPlan = async (targets: readonly string[], argv: readonly string[], context: FixPlanContext): Promise<number> => {
+  // Checked first: a file name written after --depth by mistake is reported as the depth it was read as.
+  const depth = chosenDepthOf(depthFlag(argv, context), context.config.fixPlan, context.ui ?? "ja");
+  if ("problem" in depth) {
+    console.error(`chaff: ${depth.problem}`);
+    return 1;
+  }
   const [path] = targets;
   if (path === undefined || targets.length > 1) {
     console.error(FIX_PLAN_TEXT[context.ui ?? "ja"].usage);
@@ -49,6 +60,7 @@ export const runFixPlan = async (targets: readonly string[], argv: readonly stri
     outline: outlineOf(prose.doc),
     structure: structureOf(prose.doc),
     phrases: prose.doc.lexicons["ai-tell"] ?? [],
+    chosenDepth: depth.chosen,
   });
   console.log(argv.includes("--json") ? renderFixPlanJson(plan) : renderFixPlanMarkdown(plan));
   return 0;

package/src/commands/help.ts

@@ -0,0 +1,8 @@
+import { commandHelp } from "../command-help.ts";
+import type { CliText } from "../cli-text.ts";
+
+/** `chaff <command> --help` prints the command's usage and runs nothing: `init --help` must not write chaff.yaml. */
+export const printCommandHelp = (text: CliText, command: string): number => {
+  console.log(commandHelp(text.usage, command, text.moreHelp));
+  return 0;
+};

package/src/commands/init-command.ts

@@ -0,0 +1,13 @@
+import { runInit } from "../init.ts";
+import type { UiLanguage } from "../ui.ts";
+import { initGenre } from "./init-ask.ts";
+import { runInitPlugin } from "./plugin-init.ts";
+
+/** chaff init: chaff.yaml for a project, or with --plugin, a rule pack to start from. flag reads an option's value. */
+export const runInitCommand = async (flag: (name: string) => string | undefined, plugin: boolean, ui: UiLanguage, dir: string): Promise<number> => {
+  if (plugin) return runInitPlugin(dir, flag("--plugin"), ui);
+  const chosen = await initGenre(flag("--genre"), ui, dir);
+  if ("error" in chosen) console.error(chosen.error);
+  else runInit(dir, chosen.genre, ui).forEach((line) => console.log(line));
+  return "error" in chosen ? 1 : 0;
+};