chaffjs 0.1.0 → 0.3.0

package/rules/no-doubled-joshi.yaml

@@ -0,0 +1,28 @@
+id: no-doubled-joshi
+layer: L3
+status: experimental
+how_to_find: doubled-particle
+word_list: nesting-particle
+requires: [pos]
+languages: [ja]
+severity: warning
+
+name:
+  ja: 同じ助詞が入れ子で続いている
+  en: Nested repeated particle
+
+why:
+  ja: 「弊社の新製品の販売の計画」のように同じ助詞が読点を挟まずに続くと、どれがどれに係るのか読み手が追えなくなります。読点で区切られた並列は数えていません。
+  en: When the same particle repeats without a break, the reader cannot tell which phrase attaches to which. Items separated by punctuation are not counted.
+
+message:
+  ja: 「{word}」が読点を挟まずに {count} 回続いています（{limit} 回まで）
+  en: '"{word}" repeats {count} times with no break (limit {limit})'
+
+how_to_fix:
+  ja: 文を割るか、係り先を言い換えてください。「弊社の新製品の販売の計画」を「弊社が新製品を販売する計画」に。
+  en: Split the sentence, or rephrase so the attachment is explicit.
+
+levels: { strict: 1, normal: 2, relaxed: 3 }
+
+use_for: [blog, business, technical]

package/rules/no-mixed-desumasu.yaml

@@ -0,0 +1,29 @@
+id: no-mixed-desumasu
+layer: L3
+status: experimental
+how_to_find: sentence-ending
+word_list: polite-ending
+requires: [pos]
+languages: [ja]
+severity: warning
+
+name:
+  ja: 文末の調子が混ざっている
+  en: Mixed sentence-ending register
+
+why:
+  ja: ですます調とである調が混ざると、読み手は「誰に向けた文書か」を掴み損ねます。どちらが正しいかではなく、1 つの文書で揃っているかの問題です。
+  en: Mixing polite and plain endings leaves the reader unsure who the document addresses. Neither register is wrong; consistency within one document is the point.
+
+message:
+  ja: この文だけ他と文末の調子が違います（文書の中で {count} 文）
+  en: "This sentence's ending register differs from the rest ({count} in this document)"
+
+how_to_fix:
+  ja: 多いほうに揃えてください。少数派のほうを直すのが、いちばん手数が少なくて済みます。
+  en: Match the majority. Rewriting the minority is the smallest change.
+
+# 少数派が何文までなら「混在」と見るか。これを超えたら、混在ではなく別の文体と判断して黙る。
+levels: { strict: 5, normal: 3, relaxed: 1 }
+
+use_for: [blog, business, technical]

package/rules/no-nakaguro-parallel.yaml

@@ -0,0 +1,27 @@
+id: no-nakaguro-parallel
+layer: L3
+status: experimental
+how_to_find: middle-dot
+languages: [ja]
+severity: info
+
+name:
+  ja: 中黒で並べすぎている
+  en: Too many items joined by middle dots
+
+why:
+  ja: 中黒の並列は 1 組なら読めますが、1 文に何組も入ると、どの項目がどの組に属するのか追えなくなります。実文書では 1 文 4 個までは普通に読めていました。
+  en: One run of middle dots reads fine. Several runs in one sentence make it impossible to tell which item belongs to which group.
+
+message:
+  ja: この文に中黒が {count} 個あります（{limit} 個まで）
+  en: "{count} middle dots in this sentence (limit {limit})"
+
+how_to_fix:
+  ja: 文を割るか、箇条書きにしてください。組の切れ目がはっきりします。
+  en: Use commas, or turn it into a bullet list.
+
+# 実文書の分布から。1 文 4 個までは読める。
+levels: { strict: 3, normal: 5, relaxed: 8 }
+
+use_for: [blog, business, technical]

package/rules/oxford-comma-consistency.yaml

@@ -0,0 +1,26 @@
+id: oxford-comma-consistency
+layer: L3
+status: experimental
+how_to_find: oxford-comma
+languages: [en]
+severity: info
+
+name:
+  ja: 並列の読点が揃っていない
+  en: Oxford comma use is inconsistent
+
+why:
+  ja: 最後の and の前に読点を打つかは、スタイルガイドで割れます。どちらが正しいかは決めません。1 つの文書で混ざっていると、読み手は項目の切れ目を毎回読み直すことになります。
+  en: Whether to put a comma before the final "and" is a style-guide split. Neither is wrong. Mixed within one document, the reader re-parses every list.
+
+message:
+  ja: この文だけ並列の読点の打ちかたが他と違います（文書の中で {count} 文）
+  en: "This list punctuates differently from the rest ({count} in this document)"
+
+how_to_fix:
+  ja: 多いほうに揃えてください。
+  en: Match the majority.
+
+levels: { strict: 3, normal: 2, relaxed: 1 }
+
+use_for: [blog, business, technical]

package/rules/paragraph-length-variance.yaml

@@ -0,0 +1,25 @@
+id: paragraph-length-variance
+layer: L1
+status: experimental
+how_to_find: paragraph-variance
+severity: info
+
+name:
+  ja: 段落の長さが揃いすぎている
+  en: Paragraph lengths are too uniform
+
+why:
+  ja: 人が書くと、言いたいことの重さで段落の長さは揺れます。揃いすぎは、埋めるために長さを合わせた跡です。
+  en: When a person writes, paragraph length follows what matters. Uniform length is the mark of filling a shape.
+
+message:
+  ja: 段落の長さのばらつきが {variance}% しかありません（{limit}% 以上ほしい）
+  en: Paragraph length varies by only {variance}% (want at least {limit}%)
+
+how_to_fix:
+  ja: 短くできる段落を短くしてください。全部を同じ長さにしないこと。
+  en: Let the short ones be short.
+
+levels: { strict: 40, normal: 30, relaxed: 20 }
+
+use_for: [blog]

package/rules/preamble-length.yaml

@@ -0,0 +1,25 @@
+id: preamble-length
+layer: L1
+status: experimental
+how_to_find: preamble-length
+severity: info
+
+name:
+  ja: 本題に入るまでが長い
+  en: Too long before the point
+
+why:
+  ja: 業務文書の読み手は結論を探しに来ています。最初の見出しまでに段落が重なると、探す手間だけが増えます。
+  en: A reader of a business document is looking for the decision. Paragraphs before the first heading only delay it.
+
+message:
+  ja: 最初の見出しまでに {count} 段落あります（{limit} 段落まで）
+  en: "{count} paragraphs before the first heading (limit {limit})"
+
+how_to_fix:
+  ja: 結論を先に書くか、前置きを見出しの下へ移してください。
+  en: Put the conclusion first, or move the preamble under a heading.
+
+levels: { strict: 1, normal: 2, relaxed: 4 }
+
+use_for: [business]

package/rules/repeated-conjunction.yaml

@@ -0,0 +1,26 @@
+id: repeated-conjunction
+layer: L2
+status: experimental
+how_to_find: repeated-conjunction
+word_list: paragraph-opener
+severity: warning
+
+name:
+  ja: 段落が同じ調子で始まり続ける
+  en: Paragraphs keep opening the same way
+
+why:
+  ja: 接続詞で始まる段落は 1 つなら流れを作りますが、続くとどの段落も前の付け足しに見えて、話がどこへ向かっているのか分からなくなります。
+  en: One paragraph opening with a conjunction carries the flow. A run of them makes every paragraph an afterthought.
+
+message:
+  ja: 接続詞で始まる段落が {count} 続いています（{limit} まで）
+  en: "{count} paragraphs in a row open with a conjunction (limit {limit})"
+
+how_to_fix:
+  ja: どれか 1 つを残して、他は言いたいことから始めてください。
+  en: Keep one. Start the others with what you want to say.
+
+levels: { strict: 1, normal: 2, relaxed: 4 }
+
+use_for: [business, blog, technical]

package/rules/repeated-sentence-head.yaml

@@ -25,4 +25,4 @@ levels:
   normal: 3
   relaxed: 4
 
-use_for: [blog, business]
+use_for: [blog, business, technical]

package/rules/rule-of-three.yaml

@@ -0,0 +1,25 @@
+id: rule-of-three
+layer: L1
+status: experimental
+how_to_find: rule-of-three
+severity: info
+
+name:
+  ja: 3 項目の箇条書きばかり
+  en: Everything comes in threes
+
+why:
+  ja: 3 つ並べると収まりがよいので、言いたいことが 2 つでも 4 つでも 3 つにされます。
+  en: Three items feel complete, so two become three and four become three.
+
+message:
+  ja: 箇条書き {total} 個のうち {count} 個が 3 項目です（{limit}% まで）
+  en: "{count} of {total} lists have exactly three items ({limit}% allowed)"
+
+how_to_fix:
+  ja: 数を合わせるために足した項目を消してください。2 つで足りるなら 2 つで。
+  en: Drop the item you added to reach three.
+
+levels: { strict: 50, normal: 70, relaxed: 90 }
+
+use_for: [blog]

package/rules/sasete-itadaku.yaml

@@ -0,0 +1,27 @@
+id: sasete-itadaku
+layer: L3
+status: experimental
+how_to_find: phrase-match
+word_list: sasete-itadaku
+languages: [ja]
+severity: info
+
+name:
+  ja: 「させていただく」が多い
+  en: Overused humble form
+
+why:
+  ja: 1 度なら丁寧ですが、重なると誰の判断で何をするのかが消えます。「検討させていただきます」は、検討するのかしないのかを言っていません。
+  en: Once it is polite. Repeated, it hides whose decision it is and what will actually happen.
+
+message:
+  ja: 「{matched}」が文書内に {count} 回あります（{limit} 回まで）
+  en: '"{matched}" appears {count} times in this document (limit {limit})'
+
+how_to_fix:
+  ja: 主語を立てて言い切ってください。「検討させていただきます」を「来週までに結論を出します」に。
+  en: Name the actor and commit. "We will look into it" becomes "we will decide by Friday".
+
+levels: { strict: 1, normal: 3, relaxed: 6 }
+
+use_for: [business, blog]

package/rules/section-length-uniformity.yaml

@@ -0,0 +1,25 @@
+id: section-length-uniformity
+layer: L1
+status: experimental
+how_to_find: section-uniformity
+severity: info
+
+name:
+  ja: 節の長さが揃いすぎている
+  en: Section lengths are too uniform
+
+why:
+  ja: 見出しごとに機械的に埋めると、節の長さが揃います。書くことの量は節ごとに違うはずです。
+  en: Filling every heading to the same size is what a template does, not what a writer does.
+
+message:
+  ja: 節の長さのばらつきが {variance}% しかありません（{limit}% 以上ほしい）
+  en: Section length varies by only {variance}% (want at least {limit}%)
+
+how_to_fix:
+  ja: 書くことの少ない節は短いままにしてください。
+  en: Let the thin sections stay thin.
+
+levels: { strict: 45, normal: 35, relaxed: 25 }
+
+use_for: [blog]

package/rules/sentence-initial-conjunction-run.yaml

@@ -0,0 +1,27 @@
+id: sentence-initial-conjunction-run
+layer: L3
+status: experimental
+how_to_find: conjunction-run
+word_list: sentence-opener
+languages: [en]
+severity: info
+
+name:
+  ja: 接続詞で始まる文が続いている
+  en: Run of sentences opening with a conjunction
+
+why:
+  ja: 接続詞で始まる文は 1 つなら効きますが、続くとどの文も前の文の付け足しに見えて、何が主張なのかが分からなくなります。
+  en: One sentence opening with "And" or "But" lands. A run of them makes every sentence read as an afterthought.
+
+message:
+  ja: 接続詞で始まる文が {count} 文続いています（{limit} 文まで）
+  en: "{count} sentences in a row open with a conjunction (limit {limit})"
+
+how_to_fix:
+  ja: どれか 1 つを残して、他は前の文に繋ぐか独立させてください。
+  en: Keep one. Join the others to the previous sentence, or let them stand alone.
+
+levels: { strict: 1, normal: 2, relaxed: 4 }
+
+use_for: [blog, business]

package/rules/taigen-dome-in-prose.yaml

@@ -0,0 +1,27 @@
+id: taigen-dome-in-prose
+layer: L3
+status: experimental
+how_to_find: noun-ending
+requires: [pos]
+languages: [ja]
+severity: info
+
+name:
+  ja: 体言止めが続いている
+  en: Too many noun-ending sentences
+
+why:
+  ja: 体言止めは 1 つなら効きますが、続くと文が途中で切れたように読めます。箇条書きでは普通の書きかたなので、本文だけを見ています。
+  en: One noun-ending sentence lands. Several in a row read as unfinished. Bullet lists are excluded, where the form is normal.
+
+message:
+  ja: 本文に体言止めが {count} 文あります（{limit} 文まで）
+  en: "{count} sentences end on a noun in the body text (limit {limit})"
+
+how_to_fix:
+  ja: 述語を足してください。「〜が課題。」を「〜が課題です。」に。
+  en: Add the predicate.
+
+levels: { strict: 2, normal: 4, relaxed: 8 }
+
+use_for: [blog, business, technical]

package/rules/title-case-consistency.yaml

@@ -0,0 +1,26 @@
+id: title-case-consistency
+layer: L3
+status: experimental
+how_to_find: title-case-mix
+languages: [en]
+severity: info
+
+name:
+  ja: 見出しの大文字化が揃っていない
+  en: Heading capitalisation is inconsistent
+
+why:
+  ja: Title Case と sentence case のどちらが正しいかは決めません。1 つの文書で混ざっていると、見出しの階層が変わったように見えます。
+  en: Neither Title Case nor sentence case is wrong. Mixed within one document, the headings look like they change level.
+
+message:
+  ja: この見出しだけ他と大文字化の流儀が違います（文書の中で {count} 個）
+  en: "This heading's capitalisation differs from the rest ({count} in this document)"
+
+how_to_fix:
+  ja: 多いほうに揃えてください。
+  en: Match the majority.
+
+levels: { strict: 3, normal: 2, relaxed: 1 }
+
+use_for: [blog, business, technical]

package/rules/undefined-acronym.yaml

@@ -0,0 +1,25 @@
+id: undefined-acronym
+layer: L1
+status: experimental
+how_to_find: undefined-acronym
+severity: info
+
+name:
+  ja: 略語が説明なしで出てくる
+  en: Acronym never expanded
+
+why:
+  ja: 略語は読む人によって指すものが違います。社内で通じても、半年後の自分や別の部署には通じません。
+  en: An acronym means different things to different readers. What is obvious inside one team is not obvious outside it.
+
+message:
+  ja: 「{word}」が説明なしで使われています（説明のない略語 {count} 個）
+  en: '"{word}" is used without an expansion ({count} such acronyms)'
+
+how_to_fix:
+  ja: 初出のところで括弧に入れて展開してください。「CI（継続的インテグレーション）」のように。
+  en: Expand it in brackets at first use.
+
+levels: { strict: 1, normal: 3, relaxed: 6 }
+
+use_for: [business, technical]

package/rules/unqualified-superlative.yaml

@@ -0,0 +1,26 @@
+id: unqualified-superlative
+layer: L2
+status: experimental
+how_to_find: unqualified-superlative
+word_list: superlative
+severity: warning
+
+name:
+  ja: 比べる相手のない最上級
+  en: Superlative with nothing to compare
+
+why:
+  ja: 「最も速い」だけでは、何と比べて最もなのかがありません。比較対象も条件も無い最上級は、読み手に確かめようがありません。
+  en: '"The fastest" without saying than what leaves the reader nothing to check.'
+
+message:
+  ja: 「{matched}」に比べる相手がありません（そういう言い方が {count} 箇所）
+  en: '"{matched}" has nothing to compare against ({count} such claims)'
+
+how_to_fix:
+  ja: 比較対象か条件を添えてください。「社内の 3 案のうち最も速い」のように。
+  en: Name the comparison. "The fastest of the three options we tried."
+
+levels: { strict: 1, normal: 2, relaxed: 4 }
+
+use_for: [business, blog]

package/src/backends/anthropic.ts

@@ -0,0 +1,61 @@
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import Anthropic from "@anthropic-ai/sdk";
+import { toFailure } from "./types.ts";
+import type { Failure, Judge, Prompt } from "./types.ts";
+
+export type AnthropicResponse = { readonly content: readonly { readonly type: string; readonly text?: string | undefined }[] };
+
+/** judge が使うのは messages.create だけ。最小の面だけを要求する。テストで差し替えられる。 */
+export type AnthropicClient = { readonly messages: { readonly create: (params: Anthropic.MessageCreateParamsNonStreaming) => Promise<AnthropicResponse> } };
+
+const isTextBlock = (block: unknown): block is { readonly text: string } =>
+  typeof block === "object" && block !== null && "text" in block && typeof block.text === "string";
+
+export const DEFAULT_MODEL = "claude-opus-5";
+
+/**
+ * 認証情報があるか。
+ *
+ * env var を見るだけでは足りない。SDK は ANTHROPIC_API_KEY / ANTHROPIC_AUTH_TOKEN /
+ * `ant auth login` のプロファイル / Workload Identity の順に解決するので、env が
+ * 無くても通ることがある。逆に、無いまま呼ぶと SDK は型の無い素の Error を投げる
+ * （AnthropicError でも APIError でもない）ので、あとから種類で判別できない。
+ * だから先に確かめる。
+ */
+const ENV_KEYS = ["ANTHROPIC_API_KEY", "ANTHROPIC_AUTH_TOKEN", "ANTHROPIC_IDENTITY_TOKEN", "ANTHROPIC_IDENTITY_TOKEN_FILE"];
+
+export const configDir = (): string => process.env["ANTHROPIC_CONFIG_DIR"] ?? join(homedir(), ".config", "anthropic");
+
+export const hasCredentials = (profileDir: string = configDir()): boolean =>
+  ENV_KEYS.some((name) => (process.env[name] ?? "").length > 0) || existsSync(profileDir);
+
+export const isAuthFailure = (error: unknown): boolean =>
+  error instanceof Anthropic.AuthenticationError || (error instanceof Anthropic.APIError && error.status === 401);
+
+/** API が返した失敗だけを拾う。ネットワーク断やコードの誤りは、握りつぶさずそのまま投げる。 */
+export const describeFailure = (error: unknown): Failure | undefined => {
+  if (!(error instanceof Anthropic.APIError)) return undefined;
+  const raw: { status: unknown; message: unknown } = error;
+  return toFailure(raw);
+};
+
+export const judge =
+  (client?: AnthropicClient): Judge =>
+  async (prompt: Prompt): Promise<string> => {
+    const anthropic: AnthropicClient = client ?? new Anthropic();
+    const response = await anthropic.messages.create({
+      model: prompt.model,
+      max_tokens: 1024,
+      system: prompt.system,
+      output_config: { format: { type: "json_schema", schema: prompt.schema } },
+      messages: [{ role: "user", content: prompt.user }],
+    });
+    const body = response.content.map((block) => (isTextBlock(block) ? block.text : undefined)).find((text) => text !== undefined);
+    if (body === undefined) throw new Error("判定が返りませんでした");
+    return body;
+  };
+
+/** 認証が無いときに人へ見せる案内。 */
+export const SETUP_HINT = "ANTHROPIC_API_KEY を設定するか、ant auth login を実行してください。";

package/src/backends/openai.ts

@@ -0,0 +1,46 @@
+import OpenAI from "openai";
+import { toFailure } from "./types.ts";
+import type { Failure, Judge, Prompt } from "./types.ts";
+
+export type OpenAIResponse = { readonly choices: readonly { readonly message: { readonly content: string | null } }[] };
+
+/** judge が使うのは chat.completions.create だけ。最小の面だけを要求する。 */
+export type OpenAIClient = {
+  readonly chat: { readonly completions: { readonly create: (params: OpenAI.ChatCompletionCreateParamsNonStreaming) => Promise<OpenAIResponse> } };
+};
+
+export const DEFAULT_MODEL = "gpt-5";
+
+export const hasCredentials = (): boolean => (process.env["OPENAI_API_KEY"] ?? "").length > 0;
+
+export const isAuthFailure = (error: unknown): boolean => error instanceof OpenAI.APIError && error.status === 401;
+
+/** API が返した失敗だけを拾う。ネットワーク断やコードの誤りは、握りつぶさずそのまま投げる。 */
+export const describeFailure = (error: unknown): Failure | undefined => {
+  if (!(error instanceof OpenAI.APIError)) return undefined;
+  const raw: { status: unknown; message: unknown } = error;
+  return toFailure(raw);
+};
+
+/**
+ * 同じ JSON schema をそのまま使う。包みかたが違うだけで、返させる形は provider で変えない。
+ * 変えると、provider を替えたときに判定の意味まで変わる。
+ */
+export const judge =
+  (client?: OpenAIClient): Judge =>
+  async (prompt: Prompt): Promise<string> => {
+    const openai: OpenAIClient = client ?? new OpenAI();
+    const response = await openai.chat.completions.create({
+      model: prompt.model,
+      messages: [
+        { role: "system", content: prompt.system },
+        { role: "user", content: prompt.user },
+      ],
+      response_format: { type: "json_schema", json_schema: { name: "verdict", schema: prompt.schema, strict: true } },
+    });
+    const body = response.choices[0]?.message.content;
+    if (body === null || body === undefined) throw new Error("判定が返りませんでした");
+    return body;
+  };
+
+export const SETUP_HINT = "OPENAI_API_KEY を設定してください。";

package/src/backends/types.ts

@@ -0,0 +1,38 @@
+/**
+ * 判定役の面。ここまでが provider ごとに違い、ここから先は共通。
+ *
+ * 返すのは JSON の文字列で、Verdict への変換と検証は judge.ts が 1 箇所で行う。
+ * provider が増えても「返ってきた形の確かめかた」は増やさない。
+ */
+export type JsonSchema = Readonly<Record<string, unknown>>;
+
+export type Prompt = { readonly system: string; readonly user: string; readonly schema: JsonSchema; readonly model: string };
+
+export type Judge = (prompt: Prompt) => Promise<string>;
+
+export type BackendName = "anthropic" | "openai";
+
+export const BACKENDS: readonly BackendName[] = ["anthropic", "openai"];
+
+export const isBackend = (value: unknown): value is BackendName => BACKENDS.some((name) => name === value);
+
+/** API が返した失敗。生のスタックトレースを人に見せないための、最小の分類。 */
+export type Failure = { readonly kind: "auth" | "quota" | "api"; readonly status: number | undefined; readonly message: string };
+
+const statusOf = (value: unknown): number | undefined => (typeof value === "number" ? value : undefined);
+
+const messageOf = (value: unknown): string => (typeof value === "string" && value.length > 0 ? value : "原因は返ってきませんでした");
+
+const kindOf = (status: number | undefined): Failure["kind"] => {
+  if (status === 401 || status === 403) return "auth";
+  return status === 429 ? "quota" : "api";
+};
+
+/**
+ * SDK の APIError から Failure を作る。分類は provider で変えない。
+ * status と message は SDK 上 any なので、ここで 1 度だけ形を確かめる。
+ */
+export const toFailure = (error: { readonly status: unknown; readonly message: unknown }): Failure => {
+  const status = statusOf(error.status);
+  return { kind: kindOf(status), status, message: messageOf(error.message) };
+};