chaffjs 0.18.0 → 0.19.0

package/skills/chaff/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: chaff
-description: "Check prose with chaff (npx chaffjs): pick the genre preset for the kind of document (contract, statute, manual, FAQ, paper, fiction, transcript…), 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."
+description: "Check prose with chaff (npx chaffjs): pick the genre preset for the kind of document (contract, statute, manual, FAQ, paper, fiction, transcript…), 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. Also use when asked to make text sound less AI-generated (「AIっぽさをなくして」「AI臭さを消して」「人間らしく書き直して」, 'make this sound human'): Light, Bold or Full mode, with Full (全面書き直し) when the request says 「全面的に」 or 'from scratch'."
 ---
 
 # Checking writing with chaff
@@ -101,19 +101,50 @@ committing `chaff.yaml`. The guide page "Adding a rule" covers each way and how
 
 ## Making AI-sounding text sound human
 
+Use this section when asked to make a text sound less generated: 「AIっぽさをなくして」「AI臭さを消して」「人間らしく
+書き直して」, "make this sound human", "this reads like AI wrote it".
+
 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
-generated. When asked to make a text sound less generated, pick one of two modes and say which.
+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
+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
+  specific; two passes at most;
+- the recommended mode and why, and the document-level signals with the outline's numbers;
+- for each rule that fired: its rewrite direction, what to keep, what to avoid, one before/after pair, hints for the
+  `ai-tell` phrases found, and the spots (line and sentence);
+- the check commands to run on the rewrite.
+
+Follow it. Rewrite in the mode it recommends; a request that says 「全面的に」 or "from scratch" means Full whatever it
+says. Apply each rule's direction at its spots. Where a fix needs a specific the text does not give, leave ［ ］ and
+ask. Save the result under the name the plan gives, run its check commands, and report the mode and the checks'
+output. The mode steps below say the rest.
+
+Pick one of three modes and say which.
+
+| Mode | Changes | Pick it when |
+| --- | --- | --- |
+| **Light** | only the flagged spots | the content and the structure are fine and only some phrasing is off |
+| **Bold** | each section's prose, keeping the outline | the outline is fixed (a report template, a manual, required sections) |
+| **Full** | the whole document, from scratch | the request says 「全面的に」「一から」「全部書き直して」 / "from scratch" / "rewrite the whole thing"; or the genre is `blog/*` or an essay (`literature/essay`); or `ai-generated-composite` fires |
+
+For a blog or an essay, and whenever `ai-generated-composite` fires, recommend Full. A Light or Bold pass leaves the
+skeleton of generated text: a heading every few paragraphs, bold lead-ins, symmetric sections, a closing まとめ that
+repeats the body. The writer usually wants the structure changed, not only the sentences.
 
-**Light** (only the flagged spots), when the content and structure are fine:
+**Light** (only the flagged spots):
 
-1. `npx chaffjs <file> --experimental` (or with the genre's `--genre`); collect the AI-shape findings.
-2. Rewrite only those spots. Keep the meaning, numbers, conditions and technical constraints.
+1. `npx chaffjs fix-plan <file> --experimental` (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.
 4. Show the rewritten text and a short list of what changed and why.
 
-**Bold** (section by section), when a light pass still leaves it reading as generated:
+**Bold** (section by section, outline kept):
 
 1. Run chaff with `--experimental` and note the document-level signals: the `ai-generated-composite` inputs,
    `bold-density`, `contrast-framing`, `stock-transition`, `sentence-rhythm`.
@@ -126,7 +157,75 @@ generated. When asked to make a text sound less generated, pick one of two modes
    dropped fact; for one that is not a fact (a number inside a metaphor, the heading of a section you cut), say why it
    stays out. `--allow-dropped <kind>` excludes a kind you cut on purpose. Never leave an added fact.
 
-In both modes:
+**Full** (全面書き直し, from scratch):
+
+1. **Take inventory before writing.** `npx chaffjs facts <file> --json` lists every fact `compare` will hold you to
+   (numbers, dates, times, URLs, code, names, quotations, headings, references, footnotes). `npx chaffjs outline <file>`
+   gives the old outline and its shape. Then write down, one line each, the writer's actual claims and every concrete
+   experience, example and opinion in the original. This inventory is what you write from; the old sentences are not.
+2. **Throw away the structure.** Decide what the piece is for and who reads it. Choose one angle or story for the
+   whole piece, and outline it the way a person would. Do these before writing:
+   - reorder: put the conclusion, or the most interesting episode, first;
+   - merge thin sections and split overloaded ones, so a section is a real unit, not one heading per paragraph;
+   - cut sections that only restate, the closing まとめ / "Conclusion" included;
+   - drop a heading that wraps a single paragraph;
+   - turn a list-of-points section into a narrative with one through-line;
+   - no symmetric three-point sections unless the content really has three parts;
+   - move the writer's concrete experience to where it carries the argument;
+   - open with the point or a concrete scene, not a generic opener.
+3. **Show the new outline first.** Put the old outline (headings from `chaff outline`) next to the proposed one:
+   headings, and one line per section on what it says. The writer then sees the structural change at a glance. Wait
+   for a yes, unless the person asked for it to be done without asking; then go straight on.
+4. **Write it fresh**, in the writer's voice, from the inventory:
+   - paragraphs that argue, joined by connectives; sentence lengths that vary;
+   - plain verbs instead of metaphors ("静かに壊れる", "silently fails" → what actually happens);
+   - the writer's own episodes and numbers kept; generic filler cut;
+   - bold only where a reader truly must not miss something; lists only for real enumerations, steps or commands;
+   - no hedges stacked on a claim, no announcing what you are about to say, no "it's not X, it's Y", no em dashes;
+   - the register of the writer's other paragraphs (です/ます or だ/である) and of the platform (Zenn, a company
+     report, an email);
+   - nothing the inventory does not have: no new facts, people, numbers, causes or consequences.
+
+   Three principles while writing:
+   - **Undo personification.** A thing or an idea as the subject of a verb of will (秩序が壊れる, 文化が醸成される,
+     アーキテクチャが要求する) becomes what a person or the system does. 「チームにレビューの文化が醸成された」 →
+     「チームで互いにレビューをするようになった」. If the original does not say who, ask the writer.
+   - **Turn noun endings and noun chains back into sentences with a verb.** 「キュー滞留によるメッセージ処理遅延の発生。」 →
+     「キューにメッセージが溜まり、処理が遅れた。」 A noun ending hides who did what and when.
+   - **Never invent specifics.** A vague sentence may read better with a concrete example. If the writer did not give
+     one, ask for it, or mark your guess for them to confirm. Never write it as fact.
+     「チームの雰囲気が良くなった」 stays as it is, with a question: 「雰囲気が良くなったと感じたのは、どんな場面でしたか」.
+     `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 outline <old> <new>`: headings, average section length, text in lists, bold, 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
+     structure you rebuilt on purpose; every other dropped fact is restored and no other fact is added. A cut まとめ
+     restates facts the body still holds, so `--distinct` counts a fact as kept when the new text states it at least
+     once.
+6. **Stop** when all of these hold, or after two full passes, whichever comes first:
+   - `ai-generated-composite` does not fire;
+   - the density rules (`bold-density`, `contrast-framing`, `stock-transition`, `colon-lead-in`) are under their limits;
+   - `compare` is clean, or every exclusion has a stated reason.
+7. **Show** the new text, a short "what changed and why" list, then a table of the signals and the shape before and
+   after, taken from chaff's output.
+
+**Read for these too.** chaff cannot detect them mechanically, so check them by reading, in every mode:
+
+- a generic opener or closer ("本記事では〜解説します", "いかがでしたでしょうか", "In today's fast-paced world");
+- explaining what every reader already knows;
+- every section the same length and the same shape;
+- a list of benefits with no cost or trade-off;
+- no first-hand detail: nothing the writer saw, measured or did;
+- the same enthusiasm everywhere, so nothing stands out;
+- politeness piled on politeness;
+- a definition nobody asked for;
+- headings that are full sentences or slogans;
+- a まとめ / "Conclusion" that repeats the body.
+
+In every mode:
 
 - Never add facts, people, numbers or causes the original does not have.
 - Keep a domain term a word rule trips when it is right in context.
@@ -136,7 +235,8 @@ In both modes:
   and commands as lists; in a business document, put the conclusion and who does what first and keep tables and
   figures; in an essay, fold punchlines back in and replace big words ("真理", "new possibilities") with the scene.
 
-The guide page "Making AI-sounding text sound human" has a worked example with chaff's output before and after.
+The guide page "Making AI-sounding text sound human" has worked examples of a Bold and a Full rewrite, with chaff's
+output before and after.
 
 ## Structured documents
 

package/src/acronym-expansions.ts

@@ -0,0 +1,106 @@
+import { namesAcronym } from "./detectors/acronym-expansion.ts";
+
+// 略語とその展開を、文書が書いたとおりに読む。同じ略語を二通りに展開していないかを比べるため。
+
+/** 本文の一続き（文）。start は文書の中の位置。 */
+export type ExpansionText = { readonly start: number; readonly text: string };
+
+export type Expansion = { readonly acronym: string; readonly name: string; readonly offset: number };
+
+const ACRONYM = String.raw`[A-Z][A-Z0-9&]*[A-Z]`;
+const QUOTE = String.raw`["“”'‘’「」]?`;
+
+/** 名前のあとに括弧で略語（Service Level Agreement (SLA)、(the "SLA")）。 */
+const NAME_FIRST = new RegExp(String.raw`[(（]\s*(?:the\s+)?${QUOTE}(?<acronym>${ACRONYM})${QUOTE}\s*[)）]`, "gu");
+/** 略語のあとに括弧で名前（SLA (Service Level Agreement)、CI（継続的インテグレーション））。 */
+const ACRONYM_FIRST = new RegExp(String.raw`(?<![\p{Script=Latin}\p{N}])(?<acronym>${ACRONYM})\s?[(（](?<name>[^()（）\n]{2,60})[)）]`, "gu");
+
+/** 頭文字に数えない短い語（Department of Defense の of）。 */
+const SMALL_WORDS: ReadonlySet<string> = new Set(["of", "and", "the", "for", "to", "in", "on", "a", "an", "&", "de", "by", "with"]);
+
+const wordsBefore = (text: string): string[] =>
+  text
+    .replaceAll(/["“”'‘’]/gu, "")
+    .trim()
+    .split(/\s+/u)
+    .filter((word) => word !== "");
+
+const initialsOf = (words: readonly string[]): string =>
+  words
+    .filter((word) => !SMALL_WORDS.has(word.toLowerCase()))
+    .flatMap((word) => word.split("-"))
+    .map((word) => word.charAt(0))
+    .join("")
+    .toUpperCase();
+
+/**
+ * 括弧の前の語のうち、頭文字がちょうど略語になる最も短い並び（the Federal Open Market Committee (FOMC) なら
+ * Federal Open Market Committee）。頭文字の揃う並びが無ければ、展開ではない（(see Table 2) や (FOMC) の前の文）。
+ */
+export const nameBefore = (text: string, acronym: string): string | undefined => {
+  const words = wordsBefore(text).slice(-acronym.length * 2 - 2);
+  const letters = acronym.replaceAll("&", "");
+  const width = words.findIndex((_word, index) => initialsOf(words.slice(-(index + 1))) === letters);
+  if (width < 0) return undefined;
+  const name = words.slice(-(width + 1));
+  const start = name.findIndex((word) => !SMALL_WORDS.has(word.toLowerCase()));
+  return name
+    .slice(start)
+    .join(" ")
+    .replace(/[,;:]$/u, "");
+};
+
+const NON_LATIN_NAME = /^[\p{Script=Han}\p{Script=Hiragana}\p{Script=Katakana}ー・\s\p{L}\p{N}-]+$/u;
+const HAS_KANA_OR_KANJI = /[\p{Script=Han}\p{Script=Hiragana}\p{Script=Katakana}]/u;
+/** 括弧の中の定義の語や文（以下「CI」という。、読点のある説明）は、名前ではない。 */
+const NOT_A_NAME = /以下|という|[、。,;:]/u;
+
+/** 略語のあとの括弧の中が、その略語の名前か。英字の名前は頭文字が揃うとき、日本語の名前は語だけのとき。 */
+const isNameAfter = (name: string, acronym: string): boolean => {
+  if (NOT_A_NAME.test(name)) return false;
+  if (HAS_KANA_OR_KANJI.test(name)) return NON_LATIN_NAME.test(name);
+  return namesAcronym(name, acronym);
+};
+
+/** 文の中の略語の展開。両方の形を、文書の中の位置の順に。 */
+export const expansionsIn = (body: ExpansionText): Expansion[] => {
+  const nameFirst = [...body.text.matchAll(NAME_FIRST)].flatMap((match) => {
+    const acronym = match.groups?.["acronym"] ?? "";
+    const name = nameBefore(body.text.slice(0, match.index), acronym);
+    return name === undefined ? [] : [{ acronym, name, offset: body.start + match.index }];
+  });
+  const acronymFirst = [...body.text.matchAll(ACRONYM_FIRST)].flatMap((match) => {
+    const acronym = match.groups?.["acronym"] ?? "";
+    const name = (match.groups?.["name"] ?? "").trim();
+    return isNameAfter(name, acronym) ? [{ acronym, name, offset: body.start + match.index }] : [];
+  });
+  return [...nameFirst, ...acronymFirst].toSorted((left, right) => left.offset - right.offset);
+};
+
+/** 比べる形。大文字小文字、ハイフンと空白、& と and、語の終わりの複数の s は名前を変えない。 */
+export const comparableName = (name: string): string =>
+  name
+    .toLowerCase()
+    .replaceAll("&", " and ")
+    .replaceAll(/[-‐‑\s]+/gu, " ")
+    .trim()
+    .replaceAll(/(?<=\p{Script=Latin}{3})s\b/gu, "");
+
+export type ExpansionConflict = { readonly expansion: Expansion; readonly first: Expansion };
+
+/** 同じ略語の、最初の展開と違う展開。違う書き方ごとに最初の一つだけ。 */
+export const expansionConflicts = (expansions: readonly Expansion[]): ExpansionConflict[] => {
+  const firsts = new Map<string, Expansion>();
+  const reported = new Set<string>();
+  return expansions.flatMap((expansion) => {
+    const first = firsts.get(expansion.acronym);
+    if (first === undefined) {
+      firsts.set(expansion.acronym, expansion);
+      return [];
+    }
+    const variant = `${expansion.acronym}\u0000${comparableName(expansion.name)}`;
+    if (comparableName(first.name) === comparableName(expansion.name) || reported.has(variant)) return [];
+    reported.add(variant);
+    return [{ expansion, first }];
+  });
+};

package/src/announced-count.ts

@@ -86,17 +86,34 @@ const isHedged = (sentence: string, phrase: Phrase, words: CountWords): boolean
 
 const COLON_END = /[:：][ \t]*$/u;
 
-/** 数える語の無い数は、先を指す語のすぐ後ろでだけ（the following two:）。「under $75:」の金額を数に読まない。 */
-const pointsAhead = (sentence: string, phrase: Phrase, anchors: readonly string[]): boolean => {
+/**
+ * 数字か、語の切れ目で区切った英語の数の語（two）。英字や点に続く数字は版や名前の一部（v2、1.2）なので数えない。
+ * 漢数字は「一緒」「一般」の中にもあるので数えない。
+ */
+const numberPattern = (words: CountWords): RegExp => {
+  const latin = words.numbers.filter((number) => isLatin(number[0]));
+  const digits = String.raw`(?<![A-Za-z.])\p{Nd}`;
+  return new RegExp(latin.length === 0 ? digits : `${digits}|(?<![A-Za-z])(?:${alternation(latin)})(?![A-Za-z])`, "iu");
+};
+
+type Patterns = { readonly phrase: RegExp; readonly number: RegExp };
+
+/**
+ * 数える語の無い数は、先を指す語のすぐ後ろでだけ（the following two:）。「under $75:」の金額を数に読まない。
+ * 先を指す語が無く、終わりのコロンだけが予告なら、コロンが渡すのはその手前のいちばん近い数。数の後ろにまだ数があれば
+ * （「1 つのページにまとめていましたが、2 ページに分けました:」）、その数は予告の数ではない。
+ */
+const pointsAhead = (sentence: string, phrase: Phrase, anchors: readonly string[], number: RegExp): boolean => {
   const before = sentence.slice(0, phrase.start).toLowerCase();
   const lowered = anchors.map((anchor) => anchor.toLowerCase());
   if (!phrase.counted) return lowered.some((anchor) => endsWithWord(before.trimEnd(), anchor));
-  return COLON_END.test(sentence.trimEnd()) || lowered.some((anchor) => before.includes(anchor));
+  if (lowered.some((anchor) => before.includes(anchor))) return true;
+  return COLON_END.test(sentence.trimEnd()) && !number.test(sentence.slice(phrase.end));
 };
 
 /** 最後の一文の予告。数がちょうど一つで、目安や順番でなく、先を指しているときだけ。 */
-const announcedIn = (sentence: string, words: CountWords, pattern: RegExp): Phrase | undefined => {
-  const phrases = [...sentence.matchAll(pattern)].map((match) => ({
+const announcedIn = (sentence: string, words: CountWords, patterns: Patterns): Phrase | undefined => {
+  const phrases = [...sentence.matchAll(patterns.phrase)].map((match) => ({
     start: match.index,
     numberEnd: match.index + (match[1] ?? "").length,
     end: match.index + match[0].length,
@@ -105,7 +122,7 @@ const announcedIn = (sentence: string, words: CountWords, pattern: RegExp): Phra
   }));
   const only = phrases.length === 1 ? phrases[0] : undefined;
   if (only === undefined || only.announced < 1 || isHedged(sentence, only, words)) return undefined;
-  return pointsAhead(sentence, only, words.anchors) ? only : undefined;
+  return pointsAhead(sentence, only, words.anchors, patterns.number) ? only : undefined;
 };
 
 /** 位置から空白と改行を読み飛ばした先。 */
@@ -127,22 +144,47 @@ const neighboursOf = (source: string, lists: readonly BulletList[]): Neighbours
 const hasNeighbour = (source: string, list: Span, neighbours: Neighbours): boolean =>
   neighbours.ends.has(list.start) || neighbours.starts.has(pastSpace(source, list.end));
 
-type Context = { readonly source: string; readonly words: CountWords; readonly pattern: RegExp; readonly neighbours: Neighbours };
+/**
+ * 分類した箇条書き（「- **実運用**: CLI / Telegram」）の行は、ラベルの後ろに項目を区切って並べる。予告の数は区切った項目の数かもしれない。
+ * 区切りは斜線だけ。読点とコンマは項目の説明の文の中にも書くので（「UI: rename the button to Save, continue」）区切りに数えない。
+ * 行内のコードの中の斜線（`a/b`）も数えない。
+ */
+const CATEGORY_ITEM = /^[ \t]*(?:[-*+]|\d{1,9}[.)])[ \t]+[^:：\n]{1,40}[:：][ \t]*(?<members>\S[^\n]*)/u;
+const MEMBER_SEPARATOR = /[/／]/u;
+const INLINE_CODE = /`[^`\n]*`/gu;
+
+const membersOf = (item: string): number | undefined =>
+  CATEGORY_ITEM.exec(item)
+    ?.groups?.["members"]?.replace(INLINE_CODE, "code")
+    .split(MEMBER_SEPARATOR)
+    .filter((member) => member.trim() !== "").length;
+
+/** どの行も分類の形なら、区切って並べた項目の数の和。一行でも違えば undefined。 */
+const categorisedCount = (source: string, list: BulletList): number | undefined => {
+  const counts = list.itemSpans.map((item) => membersOf(source.slice(item.start, item.end)));
+  return counts.every((count) => count !== undefined) ? counts.reduce<number>((sum, count) => sum + (count ?? 0), 0) : undefined;
+};
+
+/** 予告の数が、行の数か、分類した行に並べた項目の数に合う。 */
+const matchesList = (announced: number, source: string, list: BulletList): boolean =>
+  announced === list.items.length || announced === categorisedCount(source, list);
+
+type Context = { readonly source: string; readonly words: CountWords; readonly patterns: Patterns; readonly neighbours: Neighbours };
 
-const mismatchOf = ({ source, words, pattern, neighbours }: Context, list: BulletList): CountMismatch[] => {
+const mismatchOf = ({ source, words, patterns, neighbours }: Context, list: BulletList): CountMismatch[] => {
   if (hasNeighbour(source, list.span, neighbours)) return [];
   const lead = leadBefore(source, list.span.start);
   if (lead === undefined) return [];
   const sentenceStart = lastSentenceStart(lead.text);
   const sentence = lead.text.slice(sentenceStart);
-  const phrase = announcedIn(sentence, words, pattern);
-  if (phrase === undefined || phrase.announced === list.items.length) return [];
+  const phrase = announcedIn(sentence, words, patterns);
+  if (phrase === undefined || matchesList(phrase.announced, source, list)) return [];
   const offset = lead.start + sentenceStart + phrase.start;
   return [{ offset, phrase: sentence.slice(phrase.start, phrase.end).trim(), announced: phrase.announced, listed: list.items.length }];
 };
 
 export const announcedCountMismatches = (source: string, lists: readonly BulletList[], words: CountWords): CountMismatch[] => {
   if (words.counters.length === 0) return [];
-  const context = { source, words, pattern: phrasePattern(words), neighbours: neighboursOf(source, lists) };
+  const context = { source, words, patterns: { phrase: phrasePattern(words), number: numberPattern(words) }, neighbours: neighboursOf(source, lists) };
   return lists.flatMap((list) => mismatchOf(context, list));
 };

package/src/announced-list.ts

@@ -0,0 +1,120 @@
+import type { Lexicon, LexiconEntry, Sentence, Token } from "./plugin.ts";
+import { entryRanges } from "./detectors/lexicon-match.ts";
+
+// 一覧を言う語（supported on、に対応）の隣に並べた名前を読み、後の文が、最初に挙げた一覧に無い名前を同じ語で言っていないかを見る。
+// 「対応 OS は Windows と macOS」と書いたあとの「Linux にも対応」。どちらが正しいかは決めず、一覧の外の名前を指す。
+
+export type ListMember = { readonly name: string; readonly offset: number };
+
+export type ListStatement = { readonly group: string; readonly offset: number; readonly members: readonly ListMember[] };
+
+export type OutsideMember = { readonly member: ListMember; readonly announced: ListStatement };
+
+const UPPER = /\p{Lu}/u;
+
+/**
+ * 名前の語。固有名詞のほか、大文字を含む名詞（macOS、Linux）。日本語の解析器は英字の名前を名詞とも固有名詞とも読むので、
+ * 品詞だけでは同じ一覧の名前が揃わない。
+ */
+const isNameToken = (token: Token): boolean => token.pos === "PROPN" || (token.pos === "NOUN" && UPPER.test(token.surface));
+
+const isJoiner = (token: Token, joiners: ReadonlySet<string>): boolean => joiners.has(token.surface.toLowerCase());
+
+/** 名前の語の並び（前へ読んだときは逆順）から、source の上の名前。 */
+const memberOf = (run: readonly Token[], source: string): ListMember | undefined => {
+  if (run.length === 0) return undefined;
+  const start = Math.min(...run.map((token) => token.span.start));
+  const end = Math.max(...run.map((token) => token.span.end));
+  return { name: source.slice(start, end).replaceAll(/\s+/gu, " "), offset: start };
+};
+
+/**
+ * 並んだ名前を、語の並びの順に読む。固有名詞が続けば一つの名前、つなぐ語（and、と、、）は名前の区切り。ほかの語に当たったら止まる。
+ * 名前で始まらなければ一覧ではない（supported on the web）。
+ */
+export const namesInOrder = (tokens: readonly Token[], joiners: ReadonlySet<string>, source: string): ListMember[] => {
+  const runs: Token[][] = [[]];
+  tokens.every((token) => {
+    const current = runs.at(-1) ?? [];
+    if (isNameToken(token)) current.push(token);
+    else if (isJoiner(token, joiners) && current.length > 0) runs.push([]);
+    else return false;
+    return true;
+  });
+  return runs.flatMap((run) => memberOf(run, source) ?? []);
+};
+
+/** 一覧の語の、一つの現れから読んだ名前。before の語は後ろの名前を、after の語は前の名前を読む。 */
+const membersAt = (
+  tokens: readonly Token[],
+  entry: LexiconEntry,
+  range: { start: number; end: number },
+  joiners: ReadonlySet<string>,
+  source: string,
+): ListMember[] =>
+  entry.position === "after"
+    ? namesInOrder(tokens.slice(0, range.start).toReversed(), joiners, source).toReversed()
+    : namesInOrder(tokens.slice(range.end), joiners, source);
+
+/** 一覧を読む言葉。frames は一覧を言う語、joiners は名前をつなぐ語、negations は打ち消しの語（小文字）。 */
+export type ListWords = { readonly frames: Lexicon; readonly joiners: ReadonlySet<string>; readonly negations: ReadonlySet<string> };
+
+/** 打ち消した文（neither is available on Docker Hub、Linux には対応していません）は、一覧に足す名前ではなく、外す名前を言う。 */
+const isNegated = (tokens: readonly Token[], negations: ReadonlySet<string>): boolean =>
+  tokens.some((token) => negations.has(token.surface.toLowerCase()) || negations.has((token.lemma ?? "").toLowerCase()));
+
+/** 文の中の、一覧を言う語と、その隣の名前。group の無い語は比べる相手が決まらないので読まない。打ち消した文も読まない。 */
+export const listStatementsIn = (sentence: Sentence, words: ListWords, source: string): ListStatement[] => {
+  const tokens = sentence.tokens ?? [];
+  const { frames, joiners } = words;
+  if (isNegated(tokens, words.negations)) return [];
+  return frames.flatMap((entry) => {
+    const group = entry.group;
+    if (group === undefined) return [];
+    return entryRanges(sentence, entry).flatMap((range) => {
+      const members = membersAt(tokens, entry, range, joiners, source);
+      const offset = tokens[range.start]?.span.start ?? sentence.span.start;
+      return members.length === 0 ? [] : [{ group, offset, members }];
+    });
+  });
+};
+
+/** 比べる形。大文字小文字・幅・空白は名前を変えない。 */
+const comparable = (name: string): string => name.normalize("NFKC").toLowerCase().replaceAll(/\s+/gu, "");
+
+/** 二つ以上の名前を挙げた最初の文。組ごとに一つ。 */
+const announcements = (statements: readonly ListStatement[]): ReadonlyMap<string, ListStatement> =>
+  statements.reduce((found, statement) => {
+    if (statement.members.length >= 2 && !found.has(statement.group)) found.set(statement.group, statement);
+    return found;
+  }, new Map<string, ListStatement>());
+
+/**
+ * 後の文が、一覧と一つも重ならない二つ以上の名前を挙げていれば、別のものの一覧（RIS は EndNote と RefWorks、BibTeX は BibDesk と LaTeX）。
+ * そこから先は、一つだけ名前を言う文がどちらの一覧の続きか決まらないので、その組は比べない。
+ */
+const isAnotherList = (statement: ListStatement, known: ReadonlySet<string>): boolean =>
+  statement.members.length >= 2 && !statement.members.some((member) => known.has(comparable(member.name)));
+
+/** 最初に挙げた一覧より後の文で、同じ組の語が言う、一覧に無い名前。名前ごとに最初の一つ。 */
+export const outsideMembers = (statements: readonly ListStatement[]): OutsideMember[] => {
+  const ordered = statements.toSorted((left, right) => left.offset - right.offset);
+  const announced = announcements(ordered);
+  const reported = new Set<string>();
+  const ambiguous = new Set<string>();
+  return ordered.flatMap((statement) => {
+    const list = announced.get(statement.group);
+    if (list === undefined || statement.offset <= list.offset || ambiguous.has(statement.group)) return [];
+    const known = new Set(list.members.map((member) => comparable(member.name)));
+    if (isAnotherList(statement, known)) {
+      ambiguous.add(statement.group);
+      return [];
+    }
+    return statement.members.flatMap((member) => {
+      const key = `${statement.group}\u0000${comparable(member.name)}`;
+      if (known.has(comparable(member.name)) || reported.has(key)) return [];
+      reported.add(key);
+      return [{ member, announced: list }];
+    });
+  });
+};

package/src/api.ts

@@ -0,0 +1,154 @@
+// The plugin API: everything a team's rule or a plugin package may rely on, and nothing else. A detector sees the
+// document only through these shapes, so chaff can change how it reads a document without breaking a plugin. Raise
+// API_VERSION when a change here would break a plugin written against the current one.
+
+/** The plugin API this chaff implements. A plugin says which one it was written for; chaff refuses any other. */
+export const API_VERSION = 1;
+
+/** A place in doc.source: UTF-16 offsets, end exclusive. */
+export type Span = { readonly start: number; readonly end: number };
+
+/** One word as the language adapter read it. pos is a Universal Dependencies UPOS tag (NOUN, VERB, ADP…). */
+export type Token = {
+  readonly span: Span;
+  readonly surface: string;
+  readonly pos: string;
+  readonly lemma?: string;
+  /** How the word is read (katakana for Japanese). Only adapters that can read it give it. */
+  readonly reading?: string;
+  /** Universal Dependencies FEATS the adapter folded in (Voice=Pass). */
+  readonly features?: Readonly<Record<string, string>>;
+};
+
+/** tokens is there only when the rule asked for parts of speech (requires: [pos]) and the adapter could give them. */
+export type Sentence = { readonly span: Span; readonly text: string; readonly tokens?: readonly Token[] };
+
+export type Paragraph = { readonly span: Span; readonly sentences: readonly Sentence[] };
+
+/** A heading and what follows it, up to the next heading. The text before the first heading is a section of depth 0. */
+export type Section = { readonly depth: number; readonly heading: string; readonly span: Span; readonly sentences: readonly Sentence[] };
+
+/** One bulleted or numbered list, with the length of each item in characters. */
+export type List = { readonly span: Span; readonly itemLengths: readonly number[] };
+
+/** One entry of a word list. instead_of is another way to write the same thing, for rules that check a document is consistent. */
+export type LexiconEntry = { readonly pattern: string; readonly instead_of?: string };
+
+export type Lexicon = readonly LexiconEntry[];
+
+export type MarkupHeading = { readonly depth: number; readonly text: string; readonly span: Span };
+
+/** alt is undefined for an HTML <img> with no alt attribute. */
+export type MarkupImage = { readonly alt: string | undefined; readonly span: Span };
+
+export type MarkupLink = { readonly destination: string; readonly span: Span };
+
+/** The document's markup. A plain-text document has markdown: false and no headings, images or links. */
+export type Markup = {
+  readonly markdown: boolean;
+  readonly headings: readonly MarkupHeading[];
+  readonly images: readonly MarkupImage[];
+  readonly links: readonly MarkupLink[];
+  /** The in-page names the writer gave ({#id} on a heading, HTML id and name), sorted. */
+  readonly ids: readonly string[];
+  /** What the reader sees as text: everything outside links. */
+  readonly texts: readonly Span[];
+};
+
+/** What a detector reads. Every span is a place in source. It is frozen: a detector cannot change what other rules see. */
+export type RuleDocument = {
+  readonly path: string;
+  readonly source: string;
+  /** The language the document is checked as: "ja", "en". */
+  readonly language: string;
+  /** What a length counts: characters (ja) or words (en). */
+  readonly lengthUnit: "char" | "word";
+  readonly sentences: readonly Sentence[];
+  readonly paragraphs: readonly Paragraph[];
+  readonly sections: readonly Section[];
+  readonly lists: readonly List[];
+  /** Each list item, wherever it is. */
+  readonly listItems: readonly Span[];
+  /** Each link, as written (`[text](url)`, `<https://…>`). */
+  readonly links: readonly Span[];
+  /** The word lists for the document's language: the adapter's, the team's and the plugins'. */
+  readonly lexicons: Readonly<Record<string, Lexicon>>;
+  readonly markup: Markup;
+};
+
+/** What a detector is given besides the document. lexicon is the rule's word_list for the document's language. */
+export type DetectorOptions = { readonly lexicon: Lexicon | undefined };
+
+/**
+ * One place a rule found. start (and end) are offsets in doc.source. values fill the rule's message: {matched} is
+ * source from start to end unless values gives it.
+ */
+export type Finding = {
+  readonly start: number;
+  readonly end?: number;
+  readonly values?: Readonly<Record<string, string | number>>;
+};
+
+/** A rule's check. It must be pure and deterministic: no files, network, clock or randomness, the same findings every time. */
+export type Detector = (doc: RuleDocument, options: DetectorOptions) => readonly Finding[];
+
+/** Words a reader sees: one string for every language, or one per language ({ ja, en }). */
+export type Text = string | Readonly<Record<string, string>>;
+
+export type Severity = "error" | "warning" | "info";
+
+/**
+ * A rule. In a type: module file only detect is read, and chaff.yaml gives the rest. In a plugin, id, name, why,
+ * how_to_fix and example are required, as they are for a rule in custom_rules.
+ */
+export type RuleSpec = {
+  readonly detect: Detector;
+  readonly id?: string;
+  readonly name?: Text;
+  readonly why?: Text;
+  readonly how_to_fix?: Text;
+  readonly example?: { readonly before: Text; readonly after: Text };
+  readonly message?: Text;
+  readonly level?: Severity;
+  /** 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. */
+  readonly word_list?: string;
+  /** "pos" when the detector reads tokens. Without it, sentences have no tokens. */
+  readonly requires?: readonly "pos"[];
+};
+
+export type Rule = RuleSpec & { readonly apiVersion: number };
+
+/** A rule, stamped with the API version it was written for. */
+export const defineRule = (spec: RuleSpec): Rule => ({ ...spec, apiVersion: API_VERSION });
+
+/** A word list in each language it has words for: { ja: [...], en: [...] }. A string is an entry with only a pattern. */
+export type LexiconSpec = Readonly<Record<string, readonly (string | LexiconEntry)[]>>;
+
+/** A house style a plugin ships: rule levels and options, and the guideline it follows. */
+export type StyleSpec = {
+  readonly id: string;
+  readonly name: Text;
+  readonly summary: Text;
+  readonly source: { readonly title: Text; readonly url: string };
+  readonly rules?: Readonly<Record<string, "strict" | "normal" | "relaxed" | "off">>;
+  readonly options?: Readonly<Record<string, Readonly<Record<string, unknown>>>>;
+};
+
+/**
+ * A plugin package. name is the prefix of every id it ships (name/rule-id); for chaff-plugin-foo it is foo, for
+ * @scope/chaff-plugin-foo it is @scope/foo. A rule is a RuleSpec, or a custom_rules entry without code (type: words,
+ * pattern or tokens).
+ */
+export type PluginSpec = {
+  readonly name: string;
+  readonly rules?: readonly (Rule | RuleSpec | Readonly<Record<string, unknown>>)[];
+  readonly lexicons?: Readonly<Record<string, LexiconSpec>>;
+  readonly styles?: readonly StyleSpec[];
+};
+
+export type Plugin = PluginSpec & { readonly apiVersion: number };
+
+/** A plugin, stamped with the API version it was written for. */
+export const definePlugin = (spec: PluginSpec): Plugin => ({ ...spec, apiVersion: API_VERSION });