chaffjs 0.20.0 → 0.21.0

package/rules/undefined-acronym.yaml

@@ -1,6 +1,6 @@
 id: undefined-acronym
 layer: L1
-status: experimental
+status: stable
 how_to_find: undefined-acronym
 word_list: common-acronym
 extra_word_lists:
@@ -40,7 +40,14 @@ how_to_fix:
 
 levels: { strict: 1, normal: 3, relaxed: 6 }
 
+# 技術文書の読み手は、分野の略語を知っている。既定の数では group の文書の過半に出たので、測って上げた（spec §21.1）。
+by_genre:
+  technical: { strict: 3, normal: 5, relaxed: 8 }
+
 use_for: [business, technical, 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/transcript: "A transcript records what was said: its sentences, repeats and register are the speaker's, not the writer's to fix."
 sources: [plain-2011, jis-z8301-2019]
 
 group: readability

package/rules/unfilled-placeholder.yaml

@@ -1,6 +1,6 @@
 id: unfilled-placeholder
 layer: L2
-status: experimental
+status: stable
 how_to_find: unfilled-placeholder
 word_list: placeholder-word
 severity: warning

package/rules/unit-mismatch.yaml

@@ -1,6 +1,6 @@
 id: unit-mismatch
 layer: L3
-status: experimental
+status: stable
 how_to_find: unit-mismatch
 requires: [quantities]
 uses: [pos]
@@ -58,6 +58,7 @@ not_flagged:
   ja: 単位が同じ量（食い違いは fact-conflict が見ます）、種類の違う量（長さと重さ）、違う見出しや違う親の項目の下の量、2% までの差は見ません。GB や MB は 1000 倍でも 1024 倍でも合えば合うとみなします。
   en: Values in the same unit (fact-conflict looks at those), of different kinds (a length and a mass), under different headings or parent items, and differences within 2% are left alone. GB and MB agree when they match at either 1000 or 1024.
 rewrite:
+  depth: light
   ja:
     direction: 二つの量のどちらが正しいかを書き手に確かめ、もう一方を換算して直してください。どちらが正しいか文書から決まらないときは、推測で選ばずに書き手に聞いてください。
     pairs:

package/rules/unknown-word.yaml

@@ -1,6 +1,6 @@
 id: unknown-word
 layer: L2
-status: experimental
+status: stable
 how_to_find: unknown-word
 languages: [en]
 severity: info
@@ -32,6 +32,8 @@ placeholders:
 levels: { strict: warning, normal: info, relaxed: info }
 
 use_for: [business, technical, blog, legal, docs, academic, literature, speech]
+off_for:
+  literature: "A narrator may hedge, speak with ら dropped, and spell as the work's time and place did."
 
 group: slips
 summary:
@@ -48,6 +50,7 @@ not_flagged:
   ja: 大文字を含む語、四字より短い語、コード・URL・メールアドレスの中の語、文書で二度以上使う語、一字違いの辞書の語が無い語、chaff.yaml の names に並べた語、語彙表 known-misspelling が別に言う語は指しません。
   en: Words with a capital letter, words shorter than four letters, words in code, URLs and email addresses, words used twice or more in the document, words with no dictionary word one letter away, words listed under names in chaff.yaml, and the misspellings known-misspelling reports are not reported.
 rewrite:
+  depth: light
   en:
     direction: If the flagged word is a typo, replace it with the suggested dictionary word, or another word the sentence means. If it is a real word or a name, leave it and add it to names in chaff.yaml.
     pairs:

package/rules/unqualified-superlative.yaml

@@ -1,6 +1,6 @@
 id: unqualified-superlative
 layer: L2
-status: experimental
+status: stable
 how_to_find: unqualified-superlative
 word_list: superlative
 extra_word_lists: [comparison-marker, superlative-scope, quantity-noun]
@@ -26,6 +26,11 @@ how_to_fix:
 levels: { strict: 1, normal: 2, relaxed: 4 }
 
 use_for: [business, 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."
+  docs: "A help page repeats its heading in its first line (To upload a file, ...) and states no claims to back up."
+  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/transcript: "A transcript records what was said: its sentences, repeats and register are the speaker's, not the writer's to fix."
 sources: [femmer-2017]
 
 group: wording

package/rules/unused-definition.yaml

@@ -1,9 +1,9 @@
 id: unused-definition
 layer: L3
-status: experimental
+status: stable
 how_to_find: unused-definition
 requires: [structure]
-severity: warning
+severity: info
 
 name:
   ja: 定義したのに使っていない語
@@ -27,7 +27,7 @@ placeholders:
     ja: 〇〇
     en: the term
 
-levels: { strict: error, normal: warning, relaxed: info }
+levels: { strict: warning, normal: info, relaxed: info }
 
 use_for: [business, technical, blog, legal, docs, academic, literature, speech]
 
@@ -51,6 +51,7 @@ not_flagged:
   ja: 定義の書き方（「X」とは、以下「X」という）で書いた語だけを見ます。複数形と所有の形（Services、Seller's）は使用に数えます。同じ語の二つ目の定義は duplicate-definition が言います。
   en: Only terms defined in a recognised form ("X" means, (the "X")) are checked. Plurals and possessives (Services, Seller's) count as uses. A second definition of the same term is duplicate-definition's to report.
 rewrite:
+  depth: light
   ja:
     direction: 本文で使っていない定義を消してください。本文が同じものを別の語で呼んでいるなら、その語を定義した語に替えます。どちらかは書き手に聞きます。
     pairs:

package/rules/url-run-on.yaml

@@ -1,6 +1,6 @@
 id: url-run-on
 layer: L1
-status: experimental
+status: stable
 how_to_find: url-run-on
 severity: warning
 

package/rules/use-before-definition.yaml

@@ -1,9 +1,9 @@
 id: use-before-definition
 layer: L3
-status: experimental
+status: stable
 how_to_find: use-before-definition
 requires: [structure]
-severity: warning
+severity: info
 
 name:
   ja: 定義より前で使っている語
@@ -29,7 +29,7 @@ placeholders:
     ja: 〇
     en: N
 
-levels: { strict: error, normal: warning, relaxed: info }
+levels: { strict: warning, normal: info, relaxed: info }
 
 use_for: [business, technical, blog, legal, docs, academic, literature, speech]
 
@@ -53,6 +53,7 @@ not_flagged:
   ja: 定義の条（「X」とは…をいう）で定義した語は、前で使っても言いません。定義の条は文書の頭にも終わりにも置く書き方があるためです。最初の一か所だけを指します。
   en: Terms defined in a definitions clause ("X" means ...) are not checked, since a definitions clause may come first or last. Only the first early use is pointed at.
 rewrite:
+  depth: structure
   ja:
     direction: 定義を、その語を最初に使う文へ移してください。移せないなら、前の文を定義した語を使わない書き方にします。
     pairs:

package/rules/vague-figure-reference.yaml

@@ -1,6 +1,6 @@
 id: vague-figure-reference
 layer: L2
-status: experimental
+status: stable
 how_to_find: vague-figure-pointer
 # 置き場所で指す言い方と、その言い方が指す種類（図・表）。図・表に名前を付ける語は dangling-figure-reference と同じ figure-label。
 # 箇条を置き場所で指す言い方は vague-clause-pointer。文書の構造の木に番号付きの条か章があるときだけ見る。
@@ -35,6 +35,8 @@ placeholders:
 levels: { strict: error, normal: warning, relaxed: info }
 
 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."
 sources: [jis-z8301-2019]
 
 group: structure

package/rules/vague-link-text.yaml

@@ -1,6 +1,6 @@
 id: vague-link-text
 layer: L1
-status: experimental
+status: stable
 how_to_find: vague-link-text
 word_list: vague-link-text
 requires: [markdown]
@@ -51,6 +51,7 @@ not_flagged:
   ja: 言葉の一部に「こちら」を含むだけのリンク（「料金表はこちら」）、URL をそのまま書いたリンク、参照の形のリンク（[こちら][1]）は指しません。Markdown でない文書と、引用（>）とコードの中のリンクも見ません。
   en: Link text that only contains such a word ("pricing here"), a bare or angle-bracket URL, and reference-style links ([here][1]) are not reported, nor are links in a quotation (>), in code, or in a document that is not Markdown.
 rewrite:
+  depth: light
   ja:
     direction: リンクの言葉を、行き先の名前（ページの題、資料の名前）に変えてください。「こちら」「ここ」は文から外し、文は行き先の名前を言う形に組み直します。行き先の URL は変えません。
     pairs:

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/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/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(" ")}` : "";
@@ -107,6 +112,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 +142,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 +154,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 +166,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 +176,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 +197,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 +216,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 +226,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

@@ -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";
@@ -338,6 +340,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/config/load.ts

@@ -52,6 +52,8 @@ export type Config = {
   readonly customRules?: unknown;
   /** grade as written: the rubric `chaff grade` reads (grade/rubric.ts). */
   readonly grade?: unknown;
+  /** fix_plan as written: the depth chaff fix-plan rewrites to (fix-plan/chosen-depth.ts reads and checks it). */
+  readonly fixPlan?: unknown;
   /** plugins as written: package names and paths. extension/plugin-load.ts reads and checks them. */
   readonly plugins?: unknown;
   /** The code chaff.yaml names, once loaded (extension/load.ts). Reading chaff.yaml does not load it. */
@@ -197,6 +199,7 @@ export const loadConfig = (path: string): Config => {
     style: raw["style"] === undefined || raw["style"] === null ? undefined : (str(raw["style"]) ?? printed(raw["style"])),
     customRules: raw["custom_rules"],
     grade: raw["grade"],
+    fixPlan: raw["fix_plan"],
     plugins: raw["plugins"],
   };
 };

package/src/config/option-problems.ts

@@ -36,7 +36,7 @@ const TEXT: Texts<ProblemText> = {
   ja: {
     notAMap: (where, value) => `${where}: options の ${value} は読めません。ルールの名前の下に、オプションの名前と値を並べてください`,
     problem: (where, problem) => {
-      if (problem.kind === "unknown-rule") return `${where}: options の ${problem.rule} というルールはありません（npx chaff rules --json で一覧が出ます）`;
+      if (problem.kind === "unknown-rule") return `${where}: options の ${problem.rule} というルールはありません（npx chaffjs rules --json で一覧が出ます）`;
       if (problem.kind === "no-options") return `${where}: ${problem.rule} にはオプションがありません。options に書いても何も変わりません`;
       if (problem.kind === "not-a-map") return `${where}: options の ${problem.rule} の下には、オプションの名前と値を並べてください`;
       if (problem.kind === "unknown-option")
@@ -47,7 +47,7 @@ const TEXT: Texts<ProblemText> = {
   en: {
     notAMap: (where, value) => `${where}: cannot read ${value} under options. Under each rule's name, list option names and values`,
     problem: (where, problem) => {
-      if (problem.kind === "unknown-rule") return `${where}: there is no rule named ${problem.rule} under options (npx chaff rules --json lists them)`;
+      if (problem.kind === "unknown-rule") return `${where}: there is no rule named ${problem.rule} under options (npx chaffjs rules --json lists them)`;
       if (problem.kind === "no-options") return `${where}: ${problem.rule} takes no options, so writing some changes nothing`;
       if (problem.kind === "not-a-map") return `${where}: under options, ${problem.rule} needs option names and values`;
       if (problem.kind === "unknown-option") return `${where}: ${problem.rule} has no option ${problem.option} (it takes ${problem.known.join(" / ")})`;

package/src/config/rule-problems.ts

@@ -9,7 +9,7 @@ const TEXT: Texts<{
   readonly numberOnSeverity: (where: string, id: string) => string;
 }> = {
   ja: {
-    unknown: (where, id) => `${where}: ${id} というルールはありません（npx chaff rules --json で一覧が出ます）`,
+    unknown: (where, id) => `${where}: ${id} というルールはありません（npx chaffjs rules --json で一覧が出ます）`,
     unreadable: (where, id, value) => `${where}: ${id} の値 ${value} は読めません（strict / normal / relaxed / off か、正の数）`,
     numberOnSemantic: (where, id) =>
       `${where}: ${id} は意味を読む検査なので数値の上限はありません。normal として動きます（strict / normal / relaxed / off で書いてください）`,
@@ -17,7 +17,7 @@ const TEXT: Texts<{
       `${where}: ${id} には数の上限がありません。normal として動きます（段階は指摘の重さを変えます。relaxed で一段軽く、off で止まります）`,
   },
   en: {
-    unknown: (where, id) => `${where}: there is no rule named ${id} (npx chaff rules --json lists them)`,
+    unknown: (where, id) => `${where}: there is no rule named ${id} (npx chaffjs rules --json lists them)`,
     unreadable: (where, id, value) => `${where}: cannot read ${value} as the level of ${id} (strict / normal / relaxed / off, or a positive number)`,
     numberOnSemantic: (where, id) => `${where}: ${id} reads meaning and has no numeric limit; it runs as normal (write strict / normal / relaxed / off)`,
     numberOnSeverity: (where, id) =>