chaffjs 0.18.0 → 0.20.0

package/src/outline/shape.ts

@@ -0,0 +1,72 @@
+import { lengthOf } from "../measure.ts";
+import { lineStarts, placeOf } from "../position.ts";
+import type { LengthUnit, ProseDocument, Section, Sentence } from "../plugin.ts";
+import { coversOffset, spanIndex } from "../compare/spans.ts";
+
+/** One section: its heading's depth (0 for the text before the first heading), its words, its line, and its own length. */
+export type OutlineEntry = { readonly depth: number; readonly heading: string; readonly line: number; readonly length: number };
+
+/** The measures a restructure moves. Lengths are in the document's unit: characters for Japanese, words for English. */
+export type Shape = {
+  readonly headings: number;
+  /** The mean length of the sections that have text, rounded. */
+  readonly averageSectionLength: number;
+  /** The share of the body text inside list items, as a rounded percentage. */
+  readonly listPercent: number;
+  /** Bold spans (Markdown `**…**`). */
+  readonly bold: number;
+};
+
+export type Outline = { readonly unit: LengthUnit; readonly entries: readonly OutlineEntry[]; readonly shape: Shape };
+
+const PERCENT = 100;
+
+const lengthOfAll = (sentences: readonly Sentence[], unit: LengthUnit): number => sentences.reduce((sum, sentence) => sum + lengthOf(sentence, unit), 0);
+
+/** The text before the first heading is listed only when there is some: a title line alone has nothing above it. */
+const isListed = (entry: OutlineEntry): boolean => entry.depth > 0 || entry.length > 0;
+
+/** Where each heading starts, keyed by where it ends: a section begins after its heading, past a Setext underline. */
+type HeadingStarts = ReadonlyMap<number, number>;
+
+const headingStartsOf = (doc: ProseDocument): HeadingStarts => new Map((doc.markup?.headings ?? []).map((heading) => [heading.end, heading.start]));
+
+/** A heading's first line; for the text above the first heading, the line its text starts on, below any front matter. */
+const startOf = (section: Section, headingStarts: HeadingStarts): number =>
+  section.depth === 0 ? (section.sentences[0]?.span.start ?? section.span.start) : (headingStarts.get(section.span.start) ?? section.span.start);
+
+type Place = { readonly lineOf: (offset: number) => number; readonly headingStarts: HeadingStarts };
+
+const entryOf = (section: Section, unit: LengthUnit, place: Place): OutlineEntry => ({
+  depth: section.depth,
+  heading: section.heading,
+  line: place.lineOf(startOf(section, place.headingStarts)),
+  length: lengthOfAll(section.sentences, unit),
+});
+
+const averageOf = (lengths: readonly number[]): number =>
+  lengths.length === 0 ? 0 : Math.round(lengths.reduce((sum, length) => sum + length, 0) / lengths.length);
+
+const listPercentOf = (doc: ProseDocument): number => {
+  const lists = spanIndex(doc.listSpans);
+  const total = lengthOfAll(doc.sentences, doc.lengthUnit);
+  const inLists = lengthOfAll(
+    doc.sentences.filter((sentence) => coversOffset(lists, sentence.span.start)),
+    doc.lengthUnit,
+  );
+  return total === 0 ? 0 : Math.round((inLists / total) * PERCENT);
+};
+
+/** The document's outline and its shape, measured from the same reading lint uses. */
+export const outlineOf = (doc: ProseDocument): Outline => {
+  const starts = lineStarts(doc.source);
+  const place: Place = { lineOf: (offset) => placeOf(starts, offset).line, headingStarts: headingStartsOf(doc) };
+  const entries = doc.sections.map((section) => entryOf(section, doc.lengthUnit, place)).filter(isListed);
+  const shape: Shape = {
+    headings: entries.filter((entry) => entry.depth > 0).length,
+    averageSectionLength: averageOf(entries.map((entry) => entry.length).filter((length) => length > 0)),
+    listPercent: listPercentOf(doc),
+    bold: doc.sections.reduce((sum, section) => sum + section.strongCount, 0),
+  };
+  return { unit: doc.lengthUnit, entries, shape };
+};

package/src/outline/structure-render.ts

@@ -0,0 +1,101 @@
+import type { LengthUnit } from "../plugin.ts";
+import type { FeatureValue } from "../structure-shape/features.ts";
+import type { Placement, StructureScore } from "../structure-shape/score.ts";
+import type { StructureText } from "./structure-text.ts";
+
+const BEYOND_MARK = "✗";
+const WITHIN_MARK = "·";
+const NOT_MEASURED = "—";
+
+const valueText = (feature: FeatureValue, unit: LengthUnit, text: StructureText): string =>
+  feature.value === undefined ? NOT_MEASURED : text.features[feature.id].value(feature.value, feature.detail, unit);
+
+const whereText = (placement: Placement, text: StructureText): string => {
+  if (placement.pastShare === undefined) return "";
+  const low = placement.direction === "low";
+  const where = text.past(placement.pastShare, low);
+  if (!placement.beyond || placement.median === undefined || placement.limit === undefined) return `  ${where}`;
+  return `  ${text.aside(where, text.human(String(placement.median), String(placement.limit), low))}`;
+};
+
+const placementLine = (placement: Placement, unit: LengthUnit, text: StructureText): string => {
+  const mark = placement.beyond ? BEYOND_MARK : WITHIN_MARK;
+  return `  ${mark} ${text.features[placement.feature.id].name}: ${valueText(placement.feature, unit, text)}${whereText(placement, text)}`;
+};
+
+const unmeasuredLine = (placements: readonly Placement[], text: StructureText): string[] => {
+  const reasons = placements.flatMap((placement) => {
+    const why = placement.feature.notMeasured;
+    return why === undefined ? [] : [text.aside(text.features[placement.feature.id].name, text.notMeasured[why])];
+  });
+  return reasons.length === 0 ? [] : [`  ${text.unmeasured(reasons.join(text.listSeparator))}`];
+};
+
+const headerOf = (score: StructureScore, language: string, text: StructureText): string =>
+  score.articles === undefined ? text.noBaseline(language) : text.score(score.score, score.compared, score.articles);
+
+/** A value no higher (or, for a low measure, no more uniform) than any step of the human articles. */
+const isUsual = (placement: Placement): boolean => placement.feature.value !== undefined && placement.pastShare === 0;
+
+const usualLine = (placements: readonly Placement[], unit: LengthUnit, text: StructureText): string[] => {
+  const usual = placements.filter(isUsual).map((placement) => `${text.features[placement.feature.id].name} ${valueText(placement.feature, unit, text)}`);
+  return usual.length === 0 ? [] : [`  ${WITHIN_MARK} ${text.usualAmong(usual.join(text.listSeparator))}`];
+};
+
+/**
+ * One document's structure block: the score, each value that stands out placed against human articles, the usual ones
+ * on one line, then what was not measured and why.
+ */
+export const structureLines = (score: StructureScore, language: string, unit: LengthUnit, text: StructureText): string[] => [
+  headerOf(score, language, text),
+  ...score.placements
+    .filter((placement) => placement.feature.value !== undefined && !isUsual(placement))
+    .map((placement) => placementLine(placement, unit, text)),
+  ...usualLine(score.placements, unit, text),
+  ...unmeasuredLine(score.placements, text),
+];
+
+const changeLine = (before: Placement, after: Placement | undefined, units: readonly [LengthUnit, LengthUnit], text: StructureText): string => {
+  const name = text.features[before.feature.id].name;
+  const afterValue = after === undefined ? NOT_MEASURED : valueText(after.feature, units[1], text);
+  return `  ${name}: ${valueText(before.feature, units[0], text)} → ${afterValue}`;
+};
+
+/** The score before and after, then each measure that either file measured. */
+export const structureChangeLines = (
+  before: StructureScore,
+  after: StructureScore,
+  units: readonly [LengthUnit, LengthUnit],
+  text: StructureText,
+): string[] => [
+  `  ${text.scoreChange}: ${String(before.score)} → ${String(after.score)}`,
+  ...before.placements.flatMap((placement, index) => {
+    const other = after.placements[index];
+    const measured = placement.feature.value !== undefined || other?.feature.value !== undefined;
+    return measured ? [changeLine(placement, other, units, text)] : [];
+  }),
+];
+
+/** For grep: the score and the measures past the human limit, on one line. */
+export const structureCompact = (path: string, score: StructureScore): string => {
+  const beyond = score.placements.filter((placement) => placement.beyond).map((placement) => `${placement.feature.id}=${String(placement.feature.value)}`);
+  return [`${path}: structure ${String(score.score)}/${String(score.compared)}`, ...beyond].join(" ");
+};
+
+/** The structure block as data: the score, and each measure with its value, where it sits, and why it was not measured. */
+export const structureJson = (score: StructureScore): Readonly<Record<string, unknown>> => ({
+  score: score.score,
+  compared: score.compared,
+  baselineArticles: score.articles ?? null,
+  features: score.placements.map((placement) => ({
+    id: placement.feature.id,
+    value: placement.feature.value ?? null,
+    ...(placement.feature.detail === undefined ? {} : { detail: placement.feature.detail }),
+    ...(placement.feature.notMeasured === undefined ? {} : { notMeasured: placement.feature.notMeasured }),
+    direction: placement.direction,
+    pastShare: placement.pastShare ?? null,
+    humanMedian: placement.median ?? null,
+    limit: placement.limit ?? null,
+    beyond: placement.beyond,
+  })),
+});

package/src/outline/structure-text.ts

@@ -0,0 +1,124 @@
+import type { Texts } from "../ui.ts";
+import type { LengthUnit } from "../plugin.ts";
+import type { FeatureId, NotMeasured } from "../structure-shape/features.ts";
+
+/** How one measure is named and how its value reads. */
+export type FeatureText = {
+  readonly name: string;
+  /** The value with its unit and what was found (the form, the pair), from the measure's number and detail. */
+  readonly value: (value: number, detail: string | undefined, unit: LengthUnit) => string;
+};
+
+export type StructureText = {
+  readonly features: Readonly<Record<FeatureId, FeatureText>>;
+  readonly notMeasured: Readonly<Record<NotMeasured, string>>;
+  /** The block's first line: the score and what it counts. */
+  readonly score: (score: number, compared: number, articles: number) => string;
+  readonly noBaseline: (language: string) => string;
+  /** Where a value sits: past what share of human articles, in the measure's direction. */
+  readonly past: (share: number, low: boolean) => string;
+  /** The measures whose values are usual in human articles, on one line. */
+  readonly usualAmong: (measures: string) => string;
+  /** The human median and the limit past which the measure counts (p90, or p10 for a low measure). */
+  readonly human: (median: string, limit: string, low: boolean) => string;
+  readonly unmeasured: (reasons: string) => string;
+  readonly listSeparator: string;
+  /** A remark after a phrase: 本文（注） / text (note). */
+  readonly aside: (main: string, inner: string) => string;
+  /** The before/after line of the score. */
+  readonly scoreChange: string;
+};
+
+const BOOKEND_JA: Readonly<Record<string, string>> = { before: "前", after: "後" };
+const BOOKEND_EN: Readonly<Record<string, string>> = { before: "opening", after: "closing" };
+
+const sides = (detail: string | undefined, names: Readonly<Record<string, string>>, joiner: string): string =>
+  (detail ?? "")
+    .split(",")
+    .flatMap((side) => names[side] ?? [])
+    .join(joiner);
+
+const withDetail = (value: string, detail: string | undefined, wrap: (detail: string) => string): string =>
+  detail === undefined ? value : `${value}${wrap(detail)}`;
+
+export const STRUCTURE_TEXT: Texts<StructureText> = {
+  ja: {
+    features: {
+      "heading-density": { name: "見出しの多さ", value: (value, _detail, unit) => `${unit === "char" ? "1000 字" : "1000 語"}あたり ${String(value)}` },
+      "short-sections": { name: "1〜2 段落の節", value: (value, detail) => withDetail(`${String(value)}%`, detail, (mean) => `（平均 ${mean} 段落）`) },
+      "section-uniformity": { name: "節の長さのばらつき", value: (value) => `${String(value)}%` },
+      "heading-forms": { name: "決まった形の見出し", value: (value, detail) => withDetail(`${String(value)}%`, detail, (form) => `（多いのは「${form}」）`) },
+      "three-subsections": { name: "3 つの小見出しに分けた見出し", value: (value) => `${String(value)} か所` },
+      bookends: {
+        name: "はじめに・まとめの見出し",
+        value: (value, detail) => withDetail(String(value), detail, () => `（${sides(detail, BOOKEND_JA, "と")}）`),
+      },
+      "closing-restatement": {
+        name: "まとめが本文を言い直す割合",
+        value: (value, detail) => withDetail(`${String(value)}%`, detail, (heading) => `（「${heading}」）`),
+      },
+      "three-item-lists": { name: "3 項目の箇条書き", value: (value, detail) => withDetail(`${String(value)}%`, detail, (counts) => `（${counts}）`) },
+      "bold-labels": { name: "太字の見出しで始まる項目", value: (value) => `${String(value)} 項目` },
+      "emoji-headings": { name: "絵文字の付いた見出し", value: (value) => `${String(value)} 個` },
+      "pro-con": { name: "メリットとデメリットの対", value: (value, detail) => withDetail(`${String(value)} 組`, detail, (pairs) => `（${pairs}）`) },
+    },
+    notMeasured: {
+      "too-short": "文書が短い",
+      "too-few-sections": "中身のある節が少ない",
+      "too-few-headings": "見出しが少ない",
+      "no-closing": "まとめの節が無い",
+      "too-few-lists": "箇条書きが 3 つ未満",
+    },
+    score: (score, compared, articles) =>
+      `構成の AI らしさ: ${String(score)}（人の記事の 9 割を超えた項目の数。比べた ${String(compared)} 項目、人の記事 ${String(articles)} 本と比べて）`,
+    noBaseline: (language) => `構成の AI らしさ: 比べていません（${language} の人の記事の基準がありません）`,
+    past: (share, low) => `人の記事の ${String(share)}% より${low ? "揃っている" : "多い"}`,
+    usualAmong: (measures) => `人の記事でふつう: ${measures}`,
+    human: (median, limit, low) => `人の中央 ${median}、${low ? "下" : "上"}から 1 割の境 ${limit}`,
+    unmeasured: (reasons) => `測っていない: ${reasons}`,
+    listSeparator: "、",
+    aside: (main, inner) => `${main}（${inner}）`,
+    scoreChange: "構成の AI らしさ",
+  },
+  en: {
+    features: {
+      "heading-density": { name: "headings", value: (value, _detail, unit) => `${String(value)} per 1000 ${unit === "char" ? "characters" : "words"}` },
+      "short-sections": {
+        name: "sections of one or two paragraphs",
+        value: (value, detail) => withDetail(`${String(value)}%`, detail, (mean) => ` (mean ${mean} paragraphs)`),
+      },
+      "section-uniformity": { name: "section length variation", value: (value) => `${String(value)}%` },
+      "heading-forms": { name: "headings in a stock form", value: (value, detail) => withDetail(`${String(value)}%`, detail, (form) => ` (most: "${form}")`) },
+      "three-subsections": { name: "headings split into three", value: (value) => String(value) },
+      bookends: {
+        name: "introduction / conclusion headings",
+        value: (value, detail) => withDetail(String(value), detail, () => ` (${sides(detail, BOOKEND_EN, " and ")})`),
+      },
+      "closing-restatement": {
+        name: "closing that restates the body",
+        value: (value, detail) => withDetail(`${String(value)}%`, detail, (heading) => ` ("${heading}")`),
+      },
+      "three-item-lists": { name: "three-item lists", value: (value, detail) => withDetail(`${String(value)}%`, detail, (counts) => ` (${counts})`) },
+      "bold-labels": { name: "list items opening with a bold label", value: (value) => String(value) },
+      "emoji-headings": { name: "headings with an emoji", value: (value) => String(value) },
+      "pro-con": { name: "pros / cons pairs", value: (value, detail) => withDetail(String(value), detail, (pairs) => ` (${pairs})`) },
+    },
+    notMeasured: {
+      "too-short": "the document is short",
+      "too-few-sections": "few sections with text",
+      "too-few-headings": "few headings",
+      "no-closing": "no closing section",
+      "too-few-lists": "fewer than three lists",
+    },
+    score: (score, compared, articles) =>
+      `Structure score: ${String(score)} (measures past 90% of human articles, of ${String(compared)} compared against ${String(articles)} human articles)`,
+    noBaseline: (language) => `Structure score: not compared (no baseline of human articles in ${language})`,
+    past: (share, low) => `${low ? "more uniform" : "higher"} than ${String(share)}% of human articles`,
+    usualAmong: (measures) => `usual in human articles: ${measures}`,
+    human: (median, limit, low) => `human median ${median}, ${low ? "10th" : "90th"} percentile ${limit}`,
+    unmeasured: (reasons) => `not measured: ${reasons}`,
+    listSeparator: ", ",
+    aside: (main, inner) => `${main} (${inner})`,
+    scoreChange: "structure score",
+  },
+};

package/src/outline/text.ts

@@ -0,0 +1,55 @@
+import type { Texts } from "../ui.ts";
+import type { LengthUnit } from "../plugin.ts";
+import { counted } from "../render/plural.ts";
+import { STRUCTURE_TEXT, type StructureText } from "./structure-text.ts";
+
+export type OutlineText = {
+  readonly usage: string;
+  /** How a length is written: 120 字 / 120 words. */
+  readonly length: (count: number, unit: LengthUnit) => string;
+  /** The text before the first heading, in place of a heading. */
+  readonly lead: string;
+  readonly headings: string;
+  readonly averageSection: string;
+  readonly lists: string;
+  readonly bold: string;
+  readonly separator: string;
+  /** The line that names the file and gives its shape. */
+  readonly shapeOf: (path: string, measures: string) => string;
+  readonly measure: (name: string, value: string) => string;
+  /** The heading of the before/after block. */
+  readonly changed: (before: string, after: string) => string;
+  /** The structure block: the score and each measure against human articles. */
+  readonly structure: StructureText;
+};
+
+export const OUTLINE_TEXT: Texts<OutlineText> = {
+  ja: {
+    usage: "使い方: chaff outline <file> [<書き直した後>] [--compact | --json] [--language ja|en|…] [--genre <ジャンル>]",
+    length: (count, unit) => (unit === "char" ? `${String(count)} 字` : `${String(count)} 語`),
+    lead: "（最初の見出しの前）",
+    headings: "見出し",
+    averageSection: "節の平均",
+    lists: "箇条書き",
+    bold: "太字",
+    separator: "、",
+    shapeOf: (path, measures) => `${path} の構成: ${measures}`,
+    measure: (name, value) => `${name} ${value}`,
+    changed: (before, after) => `構成の変化（${before} → ${after}）`,
+    structure: STRUCTURE_TEXT.ja,
+  },
+  en: {
+    usage: "usage: chaff outline <file> [<rewritten>] [--compact | --json] [--language ja|en|…] [--genre <genre>]",
+    length: (count, unit) => (unit === "char" ? counted(count, "character") : counted(count, "word")),
+    lead: "(before the first heading)",
+    headings: "headings",
+    averageSection: "average section",
+    lists: "in lists",
+    bold: "bold",
+    separator: ", ",
+    shapeOf: (path, measures) => `${path} outline: ${measures}`,
+    measure: (name, value) => `${name} ${value}`,
+    changed: (before, after) => `How the shape changed (${before} → ${after})`,
+    structure: STRUCTURE_TEXT.en,
+  },
+};

package/src/paragraph-runs.ts

@@ -0,0 +1,30 @@
+// Runs of one-sentence paragraphs: paragraphs that follow one another with nothing but blank lines between them, each holding a
+// single sentence. Pure: paragraphs and the source they are cut from come in.
+import type { Paragraph } from "./plugin.ts";
+
+/** A line break, then nothing but spaces (an ideographic space too), then another line break. */
+const BLANK_LINE = /\n[^\S\n]*\n/u;
+
+/**
+ * Whether two paragraphs follow one another across a blank line and nothing else: no heading, list, table or code block between.
+ * Lines joined by a single line break are one paragraph to Markdown, however the document builder splits them.
+ */
+const isAdjacent = (source: string, before: Paragraph, after: Paragraph): boolean => {
+  const between = source.slice(before.span.end, after.span.start);
+  return between.trim() === "" && BLANK_LINE.test(between);
+};
+
+/**
+ * Each run of adjacent one-sentence paragraphs, in document order, as the paragraphs it holds. A paragraph of two sentences or
+ * more, or anything between two paragraphs, ends the run.
+ */
+export const oneSentenceRuns = (source: string, paragraphs: readonly Paragraph[]): Paragraph[][] =>
+  paragraphs.reduce<Paragraph[][]>((runs, paragraph, at) => {
+    if (paragraph.sentences.length !== 1) return runs;
+    const previous = paragraphs[at - 1];
+    const current = runs.at(-1);
+    const continues = previous !== undefined && current?.at(-1) === previous && isAdjacent(source, previous, paragraph);
+    if (continues) current.push(paragraph);
+    else runs.push([paragraph]);
+    return runs;
+  }, []);

package/src/person-forms.ts

@@ -0,0 +1,119 @@
+import type { Lexicon } from "./plugin.ts";
+import { isWithinAny, QUOTATION_MARKS, quotedSpans } from "./quoted-span.ts";
+
+// The party a document names (私たち / 弊社 for itself, you / one for its reader). Each place is read as a form that fills
+// a slot, so a document naming one slot two ways can be pointed at its minority. Which form is right is never decided.
+
+/** One place that names a party: where it is in the text, as written, the form it counts as and the slot it fills. */
+export type PersonMention = { readonly at: number; readonly written: string; readonly form: string; readonly slot: string };
+
+/** From the language package: person-word (surface → form), person-form (form → slot), person-not-after (a word before that makes a form another word; a package may have none). */
+export type PersonWords = { readonly words: Lexicon; readonly forms: Lexicon; readonly notAfter: Lexicon };
+
+/**
+ * A neighbour that makes the hit part of a longer word: a Latin letter or digit, a combining mark, a kanji, a katakana
+ * (東京本社, 当社比, yourselves). Hiragana is not one: 私は is 私 and a particle.
+ */
+const JOINING = /[\p{Script=Latin}\p{N}\p{M}\p{Script=Han}\p{Script=Katakana}ー]/u;
+
+const LATIN_WORD = /^[\p{Script=Latin}']+$/u;
+
+/** How far back the word before is looked for. A longer word than this is not one person-not-after lists. */
+const BEFORE_REACH = 24;
+
+/** Lower case for ASCII letters only, so every position in the text stays where it was (toLowerCase can change length: İ). */
+const asciiLower = (text: string): string => text.replace(/[A-Z]/gu, (letter) => letter.toLowerCase());
+
+type Pattern = { readonly text: string; readonly form: string; readonly slot: string };
+
+const builtPatterns = new WeakMap<PersonWords, readonly Pattern[]>();
+
+/** Longest first, so 私たち is read before 私. A surface whose form names no slot is not read. Built once per word set. */
+const patternsOf = (person: PersonWords): readonly Pattern[] => {
+  const built = builtPatterns.get(person);
+  if (built !== undefined) return built;
+  const slots = new Map(person.forms.map((entry) => [entry.pattern, entry.instead_of ?? entry.pattern]));
+  const patterns = person.words
+    .flatMap((entry) => {
+      const form = entry.instead_of ?? entry.pattern;
+      const slot = slots.get(form);
+      return slot === undefined ? [] : [{ text: asciiLower(entry.pattern), form, slot }];
+    })
+    .toSorted((left, right) => right.text.length - left.text.length);
+  builtPatterns.set(person, patterns);
+  return patterns;
+};
+
+/** The word right before a hit, with only spaces between: "for, one can" has none, "for one" has "for". */
+const wordBefore = (text: string, at: number): string => {
+  const reach = text.slice(Math.max(0, at - BEFORE_REACH), at);
+  const trimmed = reach.trimEnd();
+  const last = trimmed.split(/\s/u).at(-1) ?? "";
+  return trimmed.length === reach.length || !LATIN_WORD.test(last) ? "" : asciiLower(last);
+};
+
+/** Written in capitals (YOU in a shouted heading) it is not the running text's habit. */
+const isCapitals = (written: string): boolean => written.length > 1 && written === written.toUpperCase() && written !== written.toLowerCase();
+
+/** person-not-after's instead_of is the form an entry guards; without it, every form. */
+const guards = (entry: Lexicon[number], form: string, before: string): boolean =>
+  asciiLower(entry.pattern) === before && (entry.instead_of === undefined || entry.instead_of === form);
+
+const standsAlone = (text: string, start: number, end: number, form: string, person: PersonWords): boolean => {
+  if (JOINING.test(text.charAt(start - 1)) || JOINING.test(text.charAt(end))) return false;
+  if (isCapitals(text.slice(start, end))) return false;
+  const before = wordBefore(text, start);
+  return before === "" || !person.notAfter.some((entry) => guards(entry, form, before));
+};
+
+/** Every start of `needle` in `haystack`. A loop, so a text with thousands of hits does not grow the stack. */
+const startsOf = (haystack: string, needle: string): number[] => {
+  const found: number[] = [];
+  for (let at = haystack.indexOf(needle); at !== -1; at = haystack.indexOf(needle, at + 1)) found.push(at);
+  return found;
+};
+
+/** Pure: every place the text names a party, outside quotations (「」『』“”""), in order. Case is ignored. */
+export const personMentions = (text: string, person: PersonWords): PersonMention[] => {
+  const quoted = quotedSpans(text, QUOTATION_MARKS);
+  const lower = asciiLower(text);
+  const taken = new Uint8Array(text.length);
+  const found: PersonMention[] = [];
+  patternsOf(person).forEach((pattern) => {
+    startsOf(lower, pattern.text).forEach((start) => {
+      const end = start + pattern.text.length;
+      if (taken.subarray(start, end).some((mark) => mark === 1)) return;
+      if (isWithinAny(quoted, { start, end }) || !standsAlone(text, start, end, pattern.form, person)) return;
+      taken.fill(1, start, end);
+      found.push({ at: start, written: text.slice(start, end), form: pattern.form, slot: pattern.slot });
+    });
+  });
+  return found.toSorted((left, right) => left.at - right.at);
+};
+
+export type PersonMinority<T> = { readonly odd: readonly T[]; readonly usual: string; readonly of: number };
+
+/** Fewer than this many places name the slot the usual way, and there is no habit to go against. */
+const MIN_USUAL = 3;
+const PERCENT = 100;
+
+/** The most used form; on a tie, the one the document used first (a Map keeps first-use order). */
+const usualForm = (forms: readonly string[]): string | undefined => {
+  const counts = new Map<string, number>();
+  forms.forEach((form) => counts.set(form, (counts.get(form) ?? 0) + 1));
+  return [...counts.entries()].reduce<[string, number] | undefined>((best, next) => (best === undefined || next[1] > best[1] ? next : best), undefined)?.[0];
+};
+
+/**
+ * Pure: for each slot, the places that use another form than the document's usual one. Entries are in document order.
+ * Nothing when the slot has one form, when the usual form has fewer than MIN_USUAL places, or when the other forms pass
+ * limitPercent of the slot's places: then the document uses two forms on purpose, and pointing at either takes a side.
+ */
+export const personMinorities = <T extends { readonly mention: PersonMention }>(entries: readonly T[], limitPercent: number): PersonMinority<T>[] =>
+  [...new Set(entries.map((entry) => entry.mention.slot))].flatMap((slot) => {
+    const inSlot = entries.filter((entry) => entry.mention.slot === slot);
+    const usual = usualForm(inSlot.map((entry) => entry.mention.form));
+    const odd = inSlot.filter((entry) => entry.mention.form !== usual);
+    if (usual === undefined || odd.length === 0 || inSlot.length - odd.length < MIN_USUAL) return [];
+    return odd.length * PERCENT > limitPercent * inSlot.length ? [] : [{ odd, usual, of: inSlot.length }];
+  });

package/src/plugin.ts

@@ -62,6 +62,10 @@ export type LexiconEntry = {
   readonly instead_of?: string | undefined;
   /** 語が、かかる語のどちら側に立つか。語順が言語で違うものを語彙表が言う（範囲の「で」は前、"in" は後ろ）。 */
   readonly position?: "before" | "after" | undefined;
+  /** How to rewrite this one phrase, in the lexicon's language. chaff fix-plan prints it next to the rule's own direction. */
+  readonly rewrite?: string | undefined;
+  /** 語の組の名前。同じ組の語どうしだけを比べる rule が使う（対応する OS を言う語と、対応する言語を言う語を分ける）。 */
+  readonly group?: string | undefined;
   /** pattern を adapter が語に分けたもの。品詞が読めるときだけ core が入れる。語彙表を書く側は書かない。 */
   readonly tokens?: readonly Token[] | undefined;
 };
@@ -105,6 +109,8 @@ export type LanguageAdapter = {
   readonly lexicons: Readonly<Record<string, Lexicon>>;
   /** 文書の構造を読む型。無い言語では `chaff tree` がそう言って止まる。 */
   readonly structure?: StructurePatterns;
+  /** 綴りを確かめる辞書（小文字の語の集まり）。大きいので、rule が呼んだときに読む。持たない言語では綴りの rule が動かない。 */
+  readonly dictionary?: () => ReadonlySet<string>;
 };
 
 // ───────── 文書の構造 ─────────
@@ -188,8 +194,15 @@ export type StructurePatterns = {
   readonly continuesSentence?: (number: string, rest: string) => boolean;
   /** 数の書き方（「二十二」「3」）を数にする。相対の参照の「前二項」「前条第二項」が使う。 */
   readonly number?: (text: string) => number | undefined;
+  /** text の at のすぐ前に書いた文書の名前（「民法の」「…(平成二十年厚生労働省告示第五十九号)」「この規則の」）。名前が無ければ undefined。 */
+  readonly namedDocument?: DocumentNamer;
 };
 
+/** 位置のすぐ前に書いた文書の名前。self はこの文書を指す名前（「この規則」「本規約」）。 */
+export type NamedDocument = { readonly name: string; readonly self: boolean };
+
+export type DocumentNamer = (text: string, at: number) => NamedDocument | undefined;
+
 export type StructureKind = "doc" | "section" | "chapter" | "article" | "item" | "definition" | "reference" | "obligation" | "quantity" | "date";
 
 /** 番地の付いた木の節点。すべて元の文書の位置（UTF-16）と行を持つ。 */
@@ -231,8 +244,8 @@ export type Section = {
 
 export type Paragraph = { readonly span: Span; readonly sentences: readonly Sentence[] };
 
-/** 箇条書き 1 つ。項目は項目の文字数で持つ。長さのばらつきしか見ないため。 */
-export type BulletList = { readonly span: Span; readonly items: readonly number[] };
+/** 箇条書き 1 つ。items は項目の文字数（空白を除く）、itemSpans は同じ順の項目の範囲。 */
+export type BulletList = { readonly span: Span; readonly items: readonly number[]; readonly itemSpans: readonly Span[] };
 
 /**
  * detector に渡る唯一の入り口。core が I/O を済ませてから呼ぶ。
@@ -339,10 +352,14 @@ export type ProseDocument = {
   readonly profile?: DocumentProfile | undefined;
   /** 本文でないもの（コード・HTML・強調の印）を同じ長さの空白で覆った source。位置は source と同じ。 */
   readonly prose?: string | undefined;
+  /** 位置のすぐ前に書いた文書の名前を読む。言語パッケージが読めなければ無い。 */
+  readonly namedDocument?: DocumentNamer | undefined;
   /** メールの引用した返信（前置きの行と「> 」の行）。ほかの人の言葉なので、見出しにも木にも入れない。 */
   readonly replyQuotes?: readonly Span[] | undefined;
   /** 記法の手がかり（見出し・画像・リンク）。記法を読む rule だけが触れ、触れたときに作る。 */
   readonly markup?: Markup | undefined;
+  /** adapter の綴りの辞書。持たない言語では無い。 */
+  readonly dictionary?: (() => ReadonlySet<string>) | undefined;
 };
 
 /** 見出し 1 つ。text は属性（`{#id}`）を外した言葉。 */
@@ -420,6 +437,15 @@ export type RuleOption = {
 
 export type Detector = (doc: ProseDocument, options: DetectorOptions) => Finding[];
 
+/** A finding of a rule that reads several documents at once, and the document (its path) it is located in. */
+export type DocumentFinding = { readonly path: string; readonly finding: Finding };
+
+/**
+ * A rule that compares the documents of one run (several files, or a folder): a word spelled one way in one file and
+ * another way in the rest. Each finding is located in one of the documents, by the offset in its values, as for a Detector.
+ */
+export type CrossDetector = (docs: readonly ProseDocument[], options: DetectorOptions) => DocumentFinding[];
+
 export type Localized = Readonly<Record<string, string>>;
 
 export type Level = "strict" | "normal" | "relaxed" | "off";
@@ -474,8 +500,10 @@ export type RuleDefinition = {
   readonly severity: Severity;
   /** Options beyond the level (the direction and length for katakana-long-vowel). Most rules have none. */
   readonly options?: Readonly<Record<string, RuleOption>>;
-  /** A rule a team defined under custom_rules in chaff.yaml: what it looks for. Built-in rules have none. */
+  /** A rule a team defined under custom_rules in chaff.yaml, or a plugin ships: what it looks for. Built-in rules have none. */
   readonly custom?: CustomSpec;
+  /** The name of the plugin that ships the rule, which is also its id's prefix (foo in foo/rule-id). Only a plugin's rules have it. */
+  readonly plugin?: string;
   /** What the rule reference tells a reader who is not an engineer: its group, one line, a before and after. */
   readonly guide?: RuleGuide;
 };
@@ -490,8 +518,10 @@ export type TokenCondition = {
 /**
  * What a team's rule looks for. words: spellings to avoid, each with the one to use (or none, to only point at it).
  * pattern: a regular expression, checked before it runs. tokens: a run of tokens from the language adapter.
+ * module: a detector the team wrote in JavaScript; module as written in chaff.yaml, file where it resolved to.
  */
 export type CustomSpec =
   | { readonly type: "words"; readonly words: readonly { readonly avoid: string; readonly use: string }[] }
   | { readonly type: "pattern"; readonly pattern: string; readonly flags: string }
-  | { readonly type: "tokens"; readonly tokens: readonly TokenCondition[] };
+  | { readonly type: "tokens"; readonly tokens: readonly TokenCondition[] }
+  | { readonly type: "module"; readonly module: string; readonly file: string };

package/src/reasons.ts

@@ -6,6 +6,7 @@ export type Reasons = {
   readonly otherLanguage: (language: string) => string;
   readonly noCapability: (capability: string) => string;
   readonly noTags: string;
+  readonly unreadTags: string;
   readonly semantic: string;
   readonly experimental: string;
   readonly turnedOff: string;
@@ -17,6 +18,8 @@ export type Reasons = {
   readonly noHeadings: string;
   readonly patternTimeout: (budgetMs: number) => string;
   readonly notMarkdown: string;
+  /** A rule that compares documents, in a run of one: it runs when chaff is given two or more files, or a folder. */
+  readonly oneDocument: string;
 };
 
 const CAPABILITY_NAME: Texts<Readonly<Record<string, string>>> = {
@@ -29,6 +32,7 @@ export const REASONS: Texts<Reasons> = {
     otherLanguage: (language) => `${language} 向けの rule ではないため`,
     noCapability: (capability) => `この言語では${CAPABILITY_NAME.ja[capability] ?? capability}が使えないため`,
     noTags: "アダプタが品詞を返さなかったため",
+    unreadTags: "言語のパッケージがこの文書を読めなかったため（品詞の取れない段落があります）",
     semantic: "意味を読む検査のため（npx chaff test で動きます）",
     experimental: "まだ試験中のため",
     turnedOff: "設定で止めているため",
@@ -41,11 +45,13 @@ export const REASONS: Texts<Reasons> = {
     noHeadings: "表題より下の見出しが無いため",
     patternTimeout: (budgetMs) => `正規表現が ${String(budgetMs)} ms で終わらなかったため（chaff.yaml の pattern を単純にしてください）`,
     notMarkdown: "Markdown の文書ではないため",
+    oneDocument: "比べるほかの文書が無いため（ファイルを二つ以上かフォルダを渡すと動きます）",
   },
   en: {
     otherLanguage: (language) => `not a rule for ${language}`,
     noCapability: (capability) => `${CAPABILITY_NAME.en[capability] ?? capability} is not available for this language`,
     noTags: "the language package returned no parts of speech",
+    unreadTags: "the language package could not read this document (some paragraphs have no parts of speech)",
     semantic: "it reads meaning; npx chaff test runs it",
     experimental: "still experimental",
     turnedOff: "turned off in the settings",
@@ -58,5 +64,6 @@ export const REASONS: Texts<Reasons> = {
     noHeadings: "the document has no headings below its title",
     patternTimeout: (budgetMs) => `the pattern did not finish within ${String(budgetMs)} ms (simplify the pattern in chaff.yaml)`,
     notMarkdown: "the document is not Markdown",
+    oneDocument: "it compares documents, and there is only one to compare (it runs when chaff is given two or more files, or a folder)",
   },
 };