chaffjs 0.6.0 → 0.8.0

package/rules/latin-spacing.yaml

@@ -0,0 +1,27 @@
+id: latin-spacing
+layer: L3
+status: experimental
+how_to_find: latin-spacing
+languages: [ja]
+severity: warning
+
+name:
+  ja: 英数字の前後の空白がそろっていない
+  en: Spacing around Latin text is inconsistent
+
+why:
+  ja: 日本語と英字・数字のあいだを空けるか詰めるかは、どちらでも読めます。困るのは一つの文書の中で混ざることで、読み手には違いに意味があるように見えます。chaff はどちらが正しいかを決めず、文書の中で少ないほうを指摘します。英字と、数字の前、数字の後ろは別々に数えます。「を 3回」のように、数字の前は空けて助数詞とは詰める書き方がふつうにあるからです。「3GBの」のように数字に続く単位は、英字ではなく数字の側として数えます。
+  en: Whether to put a space between Japanese and Latin letters or digits is a choice either way. What reads badly is mixing both in one document, which suggests the difference means something. chaff does not decide which is right; it points at whichever the document uses less. Letters, the space before a digit and the space after one are counted separately, since spacing before a number but not before its counter is common.
+
+message:
+  ja: "日本語と{kind}のあいだを{style}（この文書はふつう{usual}。{of} 箇所のうち {count} 箇所が違う）"
+  en: "Spacing between Japanese and {kind} differs here ({count} of {of})"
+
+how_to_fix:
+  ja: 文書の多いほうの書き方に合わせてください。チームで決めているなら、STYLE.md に書いておくと迷いません。
+  en: Match the way the rest of the document does it. If the team has decided, write it in the style guide.
+
+# 何箇所違えば指摘するか。1 は「1 箇所でも混ざっていれば」。
+levels: { strict: 1, normal: 1, relaxed: 3 }
+
+use_for: [business, blog, technical]

package/rules/preferred-term.yaml

@@ -0,0 +1,27 @@
+id: preferred-term
+layer: L2
+status: experimental
+how_to_find: preferred-term
+word_list: preferred-term
+severity: warning
+
+name:
+  ja: チームの表記と違う
+  en: Not the team's spelling
+
+why:
+  ja: 同じものを「サーバー」とも「サーバ」とも書くと、読み手は別のものかと迷い、検索でも片方を取りこぼします。どちらに寄せるかはチームごとに違うので、chaff.yaml の prefer に「使わない書き方」と「使う書き方」の組を自分で並べてください。並べていなければ何も言いません。
+  en: Writing the same thing two ways ("e-mail" and "email") makes a reader wonder whether they differ, and a search misses one of them. Which way wins is the team's choice, so list pairs (the spelling to avoid, then the one to use) under `prefer` in chaff.yaml. With nothing listed, this rule says nothing.
+
+message:
+  ja: 「{matched}」は「{preferred}」と書きます
+  en: 'Write "{preferred}", not "{matched}"'
+
+how_to_fix:
+  ja: 「{preferred}」に直してください。固有名詞など、そのままにすべき箇所なら stet で理由を添えて黙らせます。
+  en: Change it to "{preferred}". Where it must stay (a product's own name, a quotation), silence it with stet and the reason.
+
+# チームが並べた書き方なので、1 つでも指摘する。並べた時点で「使わない」と決めている。
+levels: { strict: 1, normal: 1, relaxed: 3 }
+
+use_for: [business, blog, technical]

package/skills/chaff/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: chaff
+description: "Check prose with chaff (npx chaffjs): run it on Markdown or text, read each finding, fix the text or record why not, and tune chaff.yaml with rules --json and relax --why. Use when asked to lint, proofread or tighten documents, or to set up a team's writing rules."
+---
+
+# Checking writing with chaff
+
+chaff finds what makes writing hard to read — long sentences, padding, mixed styles, broken references in a
+contract — and never rewrites anything. Reading the findings and changing the text is your part. Japanese and
+English documents both work; the language is detected per file.
+
+## Run it
+
+```sh
+npx chaffjs <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
+```
+
+A run exits 1 when a finding is an `error`, and also when it could not check anything (no file to check, an
+unknown `--genre`, no package for the language) — so a clean exit means the files were checked. After the findings comes the list of rules that did not run, and why (the default output only; `--compact`
+gives just their number): read it before saying a document is clean. A run over several files prints only the files that have findings, so to call one file clean,
+run chaff on that file alone and read its list.
+
+## For each finding, choose one of three
+
+| | When | How |
+| --- | --- | --- |
+| Fix the text | The finding is right | Edit the sentence. Keep the meaning, the facts and the numbers; change only how it is said. |
+| Silence that spot | Right in general, wrong here (a quotation, a term that must repeat) | `<!-- stet: rule-id — reason -->` before it; `stet-section` / `stet-file` for wider scope. Always give the reason. |
+| Change the rule | Wrong for this team or genre | `npx chaffjs relax <rule-id> --why "reason"` (or `strict` / `off`). The reason and date are written into `chaff.yaml`. |
+
+`npx chaffjs explain <rule-id>` shows why a rule exists, its levels and the current one. Read it before
+relaxing a rule.
+
+## Tune chaff.yaml
+
+- `npx chaffjs init` writes a commented `chaff.yaml` when there is none (an existing one is left as it is), and
+  adds `.chaff-cache/` and `.env*` to `.gitignore`.
+- `npx chaffjs rules --json` prints every rule with its levels, the setting in effect (`now`) and why a rule is
+  off. Read it instead of guessing rule names or limits.
+- A level is `strict` / `normal` / `relaxed` / `off`; when even `relaxed` is too tight, a positive number is the
+  limit itself (`max-sentence-length: 260`).
+- `prefer:` maps spellings to the team's (`e-mail: email`); `preferred-term: normal` turns the rule on.
+- Unknown rule names and unreadable values are reported on stderr — read stderr after editing `chaff.yaml`.
+- `genre:` sets the kind of document (`npx chaffjs genres` lists them); `--genre` overrides it for one run.
+
+## 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,
+  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.
+
+## Do not
+
+- Do not change what a document says to satisfy a rule. If a finding cannot be fixed without changing the
+  meaning, leave it and say so.
+- Do not turn a rule off to make a run pass; relax it with a reason the team would accept.
+- Do not report "no findings" without reading the not-run list.

package/src/adapter-load.ts

@@ -59,13 +59,41 @@ const LANGUAGE_ID = /^[a-z]{2,3}$/u;
 export const packageFor = (language: string): string | undefined =>
   ADAPTER_PACKAGE[language] ?? (LANGUAGE_ID.test(language) ? `@chaffjs/lang-${language}` : undefined);
 
-const importAdapter = async (specifier: string, language: string): Promise<unknown> => {
+/**
+ * 探す順。公式（`@chaffjs/lang-<言語>`）が先で、無ければ第三者の `chaff-lang-<言語>`。
+ * `@typescript-eslint/*` と `eslint-plugin-*` の分け方と同じで、README にもそう書いてある。同梱の言語は表のものだけ。
+ */
+export const packagesFor = (language: string): readonly string[] => {
+  if (ADAPTER_PACKAGE[language] !== undefined) return [ADAPTER_PACKAGE[language]];
+  return LANGUAGE_ID.test(language) ? [`@chaffjs/lang-${language}`, `chaff-lang-${language}`] : [];
+};
+
+export type Importer = (specifier: string) => Promise<unknown>;
+
+/**
+ * そのパッケージ自体が入っていないときだけ真。入っているパッケージが自分の依存を見つけられないときも同じ
+ * ERR_MODULE_NOT_FOUND になるので、Node の文言が探した名前を挙げているかで分ける。
+ */
+export const isAbsent = (err: unknown, specifier: string): boolean =>
+  err instanceof Error && "code" in err && err.code === "ERR_MODULE_NOT_FOUND" && err.message.includes(`'${specifier}'`);
+
+/** 入っている最初のものを読む。入っていないのは次へ。入っていて壊れているものは、次へ行かずにそのまま投げる。 */
+const importFirst = async (specifiers: readonly string[], language: string, importer: Importer): Promise<{ specifier: string; module: unknown }> => {
+  const [first, ...rest] = specifiers;
+  if (first === undefined) throw new Error(`no adapter for language "${language}"`);
   try {
-    return await import(specifier);
+    return { specifier: first, module: await importer(first) };
   } catch (err) {
-    const missing = err instanceof Error && "code" in err && err.code === "ERR_MODULE_NOT_FOUND";
-    if (missing) throw new Error(`言語 ${language} のパッケージ ${specifier} が入っていません（npm i -D ${specifier}）`, { cause: err });
-    throw err;
+    if (!isAbsent(err, first)) throw err;
+    if (rest.length > 0) return importFirst(rest, language, importer);
+    const all = packagesFor(language);
+    const install = `npm i -D ${all[0] ?? first}`;
+    // Only the requested language is known here; a Japanese message for Japanese, English for any other.
+    const message =
+      language === "ja"
+        ? `言語 ${language} のパッケージが入っていません（${all.join(" か ")}。${install}）`
+        : `No package for language ${language} is installed (${all.join(" or ")}; ${install})`;
+    throw new Error(message, { cause: err });
   }
 };
 
@@ -74,13 +102,16 @@ const importAdapter = async (specifier: string, language: string): Promise<unkno
  * core だけで起動し、文字種で言語を当ててから、その言語のアダプタを読む。
  * 全言語を静的に import すると、使わない言語のぶんまで npx の初回取得が膨らむ。
  */
-export const loadAdapter = async (language: string): Promise<LanguageAdapter> => {
-  const specifier = packageFor(language);
-  if (specifier === undefined) throw new Error(`no adapter for language "${language}"`);
-  const module = await importAdapter(specifier, language);
+export const loadAdapter = async (language: string, importer: Importer = (specifier) => import(specifier)): Promise<LanguageAdapter> => {
+  const { specifier, module } = await importFirst(packagesFor(language), language, importer);
   if (typeof module !== "object" || module === null) throw new Error(`${specifier} did not export a module`);
   const candidate = pickExport(module);
   const broken = checkAdapter(candidate);
-  if (broken !== undefined || !isAdapter(candidate)) throw new Error(`${specifier} が LanguageAdapter を export していません: ${broken ?? ""}`);
+  if (broken !== undefined || !isAdapter(candidate)) {
+    const why = broken ?? "";
+    throw new Error(
+      language === "ja" ? `${specifier} が LanguageAdapter を export していません: ${why}` : `${specifier} does not export a LanguageAdapter: ${why}`,
+    );
+  }
   return candidate;
 };

package/src/cli-args.ts

@@ -0,0 +1,9 @@
+/**
+ * Options of the commands that take files to check, whose value is the next argument. That value is not a file.
+ * `--why` (relax), `--format` and `--language` (tree) belong to commands that read their own arguments.
+ */
+export const VALUE_FLAGS: readonly string[] = ["--sarif", "--genre", "--rule"];
+
+/** The arguments that name what to check: everything that is neither an option nor an option's value. */
+export const targetsOf = (args: readonly string[]): string[] =>
+  args.filter((arg, index) => !arg.startsWith("--") && !(index > 0 && VALUE_FLAGS.includes(args[index - 1] ?? "")));

package/src/cli-text.ts

@@ -0,0 +1,182 @@
+// What the command line says, in Japanese and English. Per-file text follows the file's language; the rest
+// follows hostLanguage (chaff.yaml's language, else the terminal's locale).
+import type { Texts } from "./ui.ts";
+
+/** Where a file's genre came from, as the header names it. */
+export type GenreSource = "--genre" | "by_path" | "config" | "default" | "front-matter" | "path" | "content";
+
+const USAGE_JA = `chaff — 文章の読みにくいところを見つけます。文章は書き換えません。
+
+  chaff <file|dir|glob>...       検査する（設定も API key も要りません）
+  chaff .                        この場所の Markdown を全部
+  chaff test <file|dir>...       意味を読む検査も動かす（API key が要ります）
+                                 判定役は chaff.yaml の ai_backend で選びます
+  chaff init                     chaff.yaml を作る
+  chaff eval <dir>               手元の文書で閾値を測り直す
+  chaff explain <rule>           そのルールの意図と根拠を読む
+  chaff genres                   ジャンルの一覧
+  chaff tree <file> [--format sexp|json]  文書を番地の付いた木にする（条・項・定義・参照）
+  chaff cite <原文> <引用.json>           回答の引用（番地と引用文）が原文にあるかを確かめる
+  chaff rules --json             いまの設定を JSON で出す（AI に渡す用）
+  chaff baseline <dir>           いまある指摘を棚上げする（既存の repo に入れるとき）
+  chaff suppressions <dir>       stet で黙らせている指摘を数える
+  chaff relax|strict|off <rule> [--why "理由"]
+  chaff skill [--global]         Claude Code の skill を入れる（.claude/skills/chaff/、--global で ~/.claude/）
+
+  --compact         エンジニア向けの 1 行形式
+  --experimental    試験中の rule も動かす
+  --genre <ジャンル>  この実行だけジャンルを決める（chaff.yaml より優先）
+  --show-baseline   棚上げした分も含めて全部見る
+  --watch           保存のたびに見直し、変わったところだけ出す
+  --dry-run         test で、何を AI に送るかだけを見る（API を呼びません）
+  --sarif <path>    指摘を SARIF で書き出す（GitHub の PR の行に出すため）
+
+この箇所だけ黙らせる:  <!-- stet: rule-id — 理由 -->
+
+値は strict / normal / relaxed / off の 4 つから選びます。
+`;
+
+const USAGE_EN = `chaff — finds what makes writing hard to read. It never rewrites the text.
+
+  chaff <file|dir|glob>...       check (no config or API key needed)
+  chaff .                        every Markdown file here
+  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
+  chaff eval <dir>               re-measure the limits on your own documents
+  chaff explain <rule>           read what a rule is for and why
+  chaff genres                   list the genres
+  chaff tree <file> [--format sexp|json]  the document as a tree of addresses (sections, clauses, definitions, references)
+  chaff cite <source> <quotes.json>       check that quoted passages (address and text) are in the source
+  chaff rules --json             the current settings as JSON (to give to an AI)
+  chaff baseline <dir>           shelve today's findings (when adding chaff to an existing repository)
+  chaff suppressions <dir>       count the findings silenced with stet
+  chaff relax|strict|off <rule> [--why "reason"]
+  chaff skill [--global]         install the Claude Code skill (.claude/skills/chaff/; --global for ~/.claude/)
+
+  --compact         one line per finding, for engineers
+  --experimental    run the experimental rules too
+  --genre <genre>   the genre for this run only (wins over chaff.yaml)
+  --show-baseline   show the shelved findings too
+  --watch           re-check on every save and print only what changed
+  --dry-run         with test, show what would be sent to the AI (no API call)
+  --sarif <path>    write the findings as SARIF (for comments on a GitHub PR)
+
+Silence one spot:  <!-- stet: rule-id — reason -->
+
+A rule's level is one of strict / normal / relaxed / off.
+`;
+
+export type CliText = {
+  readonly usage: 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;
+  readonly noMarkdown: (targets: string) => string;
+  readonly noMarkdownHere: string;
+  readonly noAdapter: (language: string) => string;
+  readonly unknownGenre: (genre: string) => string;
+  readonly unknownRule: (id: string) => string;
+  readonly unknownRuleWithList: (id: string, list: string) => string;
+  readonly unnamed: string;
+  readonly sarifWritten: (path: string, count: number) => string;
+  readonly unchanged: string;
+  readonly findingsUnit: string;
+  readonly watching: (files: number, findings: number) => string;
+  readonly watchHint: string;
+  readonly baselineDone: (files: number, entries: number, file: string) => readonly string[];
+  readonly genres: (list: readonly string[]) => string;
+  readonly unit: (ruleId: string, language: string) => string;
+};
+
+export const CLI_TEXT: Texts<CliText> = {
+  ja: {
+    usage: USAGE_JA,
+    languageName: (language) => (language === "ja" ? "日本語" : "英語"),
+    genreSource: {
+      "--genre": "--genre",
+      by_path: "chaff.yaml の by_path",
+      config: "chaff.yaml",
+      default: "既定",
+      "front-matter": "front matter",
+      path: "パス",
+      content: "内容",
+    },
+    header: (path, genre, language, from, shelved, hushed) =>
+      [`${path}   ${genre} · ${language}   ジャンルは${from}から`, shelved > 0 ? `   棚上げ ${shelved} 件` : "", hushed > 0 ? `   stet ${hushed} 件` : ""].join(
+        "",
+      ),
+    noMarkdown: (targets) => `Markdown が 1 つも見つかりませんでした: ${targets}`,
+    noMarkdownHere: "Markdown が 1 つも見つかりませんでした。",
+    noAdapter: (language) => `言語 "${language}" のアダプタがありません。`,
+    unknownGenre: (genre) => `ジャンル "${genre}" はありません。npx chaff genres で一覧が出ます。`,
+    unknownRule: (id) => `${id} というルールはありません。npx chaff rules --json で一覧が出ます。`,
+    unknownRuleWithList: (id, list) => `${id} というルールはありません。\n一覧:\n${list}`,
+    unnamed: "(名前なし)",
+    sarifWritten: (path, count) => `\n  SARIF を書きました: ${path}（${count} 件）`,
+    unchanged: "変わりませんでした",
+    findingsUnit: " 件",
+    watching: (files, findings) => `\n  ${files} ファイルを見ています。いまの指摘は ${findings} 件です。`,
+    watchHint: "  保存するたびに、変わったところだけ出します。止めるには Ctrl-C。\n",
+    baselineDone: (files, entries, file) => [
+      "",
+      `  ${files} ファイルを走査しました。`,
+      "",
+      `  ${entries} 件の指摘を ${file} に記録しました。`,
+      "  以後、これらは報告されません。新しく増えたものだけが出ます。",
+      "",
+      `  ${file} を commit してください。`,
+      "",
+    ],
+    genres: (list) =>
+      ["", "  使えるジャンル:", ...list.map((genre) => `    ${genre}`), "", "  chaff.yaml の genre に書くか、--genre で指定します。", ""].join("\n"),
+    unit: (ruleId, language) => {
+      if (ruleId === "bold-density") return "1000 字あたりの箇所数";
+      if (ruleId !== "max-sentence-length") return "回";
+      return language === "ja" ? "文字" : "語";
+    },
+  },
+  en: {
+    usage: USAGE_EN,
+    languageName: (language) => (language === "ja" ? "Japanese" : "English"),
+    genreSource: {
+      "--genre": "--genre",
+      by_path: "by_path in chaff.yaml",
+      config: "chaff.yaml",
+      default: "the default",
+      "front-matter": "front matter",
+      path: "the path",
+      content: "the content",
+    },
+    header: (path, genre, language, from, shelved, hushed) =>
+      [`${path}   ${genre} · ${language}   genre from ${from}`, shelved > 0 ? `   ${shelved} shelved` : "", hushed > 0 ? `   ${hushed} stet` : ""].join(""),
+    noMarkdown: (targets) => `No Markdown files found: ${targets}`,
+    noMarkdownHere: "No Markdown files found.",
+    noAdapter: (language) => `No language package for "${language}".`,
+    unknownGenre: (genre) => `There is no genre "${genre}". npx chaff genres lists them.`,
+    unknownRule: (id) => `There is no rule named ${id}. npx chaff rules --json lists them.`,
+    unknownRuleWithList: (id, list) => `There is no rule named ${id}.\nRules:\n${list}`,
+    unnamed: "(no name)",
+    sarifWritten: (path, count) => `\n  Wrote SARIF: ${path} (${count} finding${count === 1 ? "" : "s"})`,
+    unchanged: "no change",
+    findingsUnit: " findings",
+    watching: (files, findings) => `\n  Watching ${files} file${files === 1 ? "" : "s"}. ${findings} finding${findings === 1 ? "" : "s"} now.`,
+    watchHint: "  Each save prints only what changed. Ctrl-C to stop.\n",
+    baselineDone: (files, entries, file) => [
+      "",
+      `  Checked ${files} file${files === 1 ? "" : "s"}.`,
+      "",
+      `  Recorded ${entries} finding${entries === 1 ? "" : "s"} in ${file}.`,
+      "  They will not be reported again; only new ones will.",
+      "",
+      `  Commit ${file}.`,
+      "",
+    ],
+    genres: (list) => ["", "  Genres:", ...list.map((genre) => `    ${genre}`), "", "  Set one with genre in chaff.yaml, or with --genre.", ""].join("\n"),
+    unit: (ruleId, language) => {
+      if (ruleId === "bold-density") return "places per 1000 characters";
+      if (ruleId !== "max-sentence-length") return "times";
+      return language === "ja" ? "characters" : "words";
+    },
+  },
+};