chaffjs 0.18.0 → 0.19.0

package/src/name-variants.ts

@@ -0,0 +1,217 @@
+import type { Token } from "./plugin.ts";
+
+// 同じ名前（人・会社・製品）を、文書の中で少しだけ違う形に書いた所。どの形が正しいかは決めず、少ないほうを指す。
+// 三通りで同じ名前と見る。書き方の違いだけ（GitHub と Github、Mac OS と macOS）、読みが同じ（山田太郎 と 山田太朗）、
+// 英字の一字違い（Microsoft と Microsft）。一字違いは別の名前でもありうるので、多いほうが二度以上、少ないほうが一度だけのときに限る。
+
+/** words は名前の語（記号を除く）。読みが同じ二つの名前が、どの語で違うかを見るため。 */
+export type NameMention = { readonly surface: string; readonly offset: number; readonly reading: string | undefined; readonly words: readonly string[] };
+
+export type NameVariant = { readonly mention: NameMention; readonly usual: string; readonly kind: "spelling" | "reading" | "near" };
+
+const NAME = "PROPN";
+/**
+ * 名前の語のあいだに挟まってよい記号（AT&T、Rolls-Royce、ジョン・スミス）。読点は挟まない。
+ * 並べた名前（Zeebrugge, Kerk、Cook, Lisa）を一つの名前にしてしまう。
+ */
+const JOINERS: ReadonlySet<string> = new Set(["&", "-", "・"]);
+const LETTER = /\p{L}/u;
+
+/** 名前の語。字を含むもの。記号だけの語（wiki の '' ）を固有名詞と読む解析器がある。 */
+const isName = (token: Token | undefined): boolean => token?.pos === NAME && LETTER.test(token.surface);
+
+/** 固有名詞の続き。記号一つを挟んで固有名詞が続けば、一つの名前。 */
+const runsOf = (tokens: readonly Token[]): Token[][] => {
+  const runs: Token[][] = [];
+  const current: Token[] = [];
+  const close = (): void => {
+    if (current.length > 0) runs.push(current.splice(0));
+  };
+  tokens.forEach((token, index) => {
+    const bridges = JOINERS.has(token.surface) && current.length > 0 && isName(tokens[index + 1]);
+    if (isName(token) || bridges) current.push(token);
+    else close();
+  });
+  close();
+  return runs;
+};
+
+const LOWER = /\p{Ll}/u;
+const UPPER = /\p{Lu}/u;
+const isUpperOnly = (text: string): boolean => UPPER.test(text) && !LOWER.test(text);
+/** 小文字の英字だけの語（the、issue）。日本語の解析器は英単語を固有名詞と読むので、ふつうの語と名前の区別がつかない。 */
+const LOWER_LATIN_ONLY = /^[a-z\s-]+$/u;
+/** 行末で切った語のハイフン（Internet-⏎Drafts）。空白をまとめると "Internet- Drafts" になる。 */
+const WRAPPED_HYPHEN = /-\s+/gu;
+/** 名前の前後に付いた引用の印（wiki の斜体 ''、Hbase'）。名前の一部ではない。 */
+const QUOTE_MARKS: ReadonlySet<string> = new Set(["'", "’", '"', "“", "”"]);
+
+const withoutEdgeQuotes = (text: string): string => {
+  const chars = [...text];
+  const start = chars.findIndex((char) => !QUOTE_MARKS.has(char));
+  const end = chars.findLastIndex((char) => !QUOTE_MARKS.has(char));
+  return start < 0 ? "" : chars.slice(start, end + 1).join("");
+};
+/**
+ * 名前として比べないもの。@ で始まる SNS のアカウント（@SpaceX は SpaceX の別の書き方ではない）と、一字の語を含むもの
+ * （Attachment S、Appendix B は札で、空白を詰めると Attachments と同じ形になる）。
+ */
+const NOT_COMPARED = /@|(?:^|\s)\p{L}(?:\s|$)/u;
+
+/**
+ * 文の語から、名前の現れ。surface は source の上の書いたまま（折り返しの空白は一つにまとめる）。
+ * 大文字だけの名前（ACME INC、NASA）は外す。契約書の署名欄や略語で、ふつうの書き方の別の形ではない。小文字の英字だけの語も外す。
+ */
+export const mentionsIn = (tokens: readonly Token[], source: string): NameMention[] =>
+  runsOf(tokens).flatMap((run) => {
+    const first = run[0];
+    const last = run.at(-1);
+    if (first === undefined || last === undefined) return [];
+    const written = source.slice(first.span.start, last.span.end).replaceAll(WRAPPED_HYPHEN, "-").replaceAll(/\s+/gu, " ");
+    const surface = withoutEdgeQuotes(written);
+    if (surface === "" || isUpperOnly(surface) || LOWER_LATIN_ONLY.test(surface) || NOT_COMPARED.test(surface)) return [];
+    const words = run.filter((token) => !JOINERS.has(token.surface));
+    const readings = words.map((token) => token.reading);
+    const reading = readings.every((value) => value !== undefined && value !== "") ? readings.join("") : undefined;
+    return [{ surface, offset: first.span.start, reading, words: words.map((token) => token.surface) }];
+  });
+
+/** 比べる形。幅（ＡＷＳ と AWS）、大文字小文字、空白と記号は名前を変えない。 */
+export const nameKey = (surface: string): string =>
+  surface
+    .normalize("NFKC")
+    .toLowerCase()
+    .replaceAll(/[\s\p{P}\p{S}]/gu, "");
+
+type Tally = { readonly surface: string; readonly first: NameMention; readonly count: number };
+
+const talliesOf = (mentions: readonly NameMention[]): Tally[] => {
+  const tallies = new Map<string, { surface: string; first: NameMention; count: number }>();
+  mentions.forEach((mention) => {
+    const tally = tallies.get(mention.surface);
+    if (tally === undefined) tallies.set(mention.surface, { surface: mention.surface, first: mention, count: 1 });
+    else tally.count += 1;
+  });
+  return [...tallies.values()];
+};
+
+/** 多いほう。同数なら先に書いたほう。 */
+const usualOf = (group: readonly Tally[]): Tally | undefined =>
+  group.toSorted((left, right) => right.count - left.count || left.first.offset - right.first.offset)[0];
+
+const groupBy = (tallies: readonly Tally[], keysOf: (tally: Tally) => readonly string[]): Tally[][] => {
+  const groups = new Map<string, Tally[]>();
+  tallies.forEach((tally) =>
+    keysOf(tally).forEach((key) => {
+      const group = groups.get(key);
+      if (group === undefined) groups.set(key, [tally]);
+      else group.push(tally);
+    }),
+  );
+  return [...groups.values()].filter((group) => group.length > 1);
+};
+
+/**
+ * 組の中で、それぞれの書き方を、同じ名前と言える相手（alike）のうち多いほうと比べる。組全体で一番多いものとだけ比べると、
+ * 同じ読みの別の名前（山田太郎 と 矢間田多労）が多ければ、本当の書き分け（山田太朗）が隠れる。
+ */
+const variantsIn = (groups: readonly Tally[][], kind: NameVariant["kind"], alike: (tally: Tally, other: Tally) => boolean = () => true): NameVariant[] =>
+  groups.flatMap((group) =>
+    group.flatMap((tally) => {
+      const usual = usualOf([tally, ...group.filter((other) => other !== tally && alike(tally, other))]);
+      return usual === undefined || usual === tally ? [] : [{ mention: tally.first, usual: usual.surface, kind }];
+    }),
+  );
+
+/**
+ * 読みが同じでも、別の名前のことが多い（毅 と 敦士、札幌 と サッポロ）。語が二つ以上あり、違うのが一語だけのとき
+ * （山田太郎 と 山田太朗）に限る。
+ */
+const oneWordApart = (tally: Tally, usual: Tally): boolean => {
+  const words = tally.first.words;
+  const others = usual.first.words;
+  return words.length >= 2 && words.length === others.length && words.filter((word, index) => word !== others[index]).length === 1;
+};
+
+/** 一字違いを比べる語の長さ。短い語（Iran と Iraq、RET と REU、II と VI）は一字違いでも別の語。 */
+const MIN_NEAR_LENGTH = 5;
+const LATIN_WORD = /^[a-z]+$/u;
+
+const wordsOf = (surface: string): string[] => surface.toLowerCase().split(/[\s-]+/u);
+
+/** 一字の置き換えか、隣どうしの入れ替え（Microsfot）。 */
+const isSwapOrReplace = (left: string, right: string): boolean => {
+  const differ = [...left].flatMap((char, index) => (char === right.charAt(index) ? [] : [index]));
+  const [first, second] = differ;
+  if (differ.length === 1) return true;
+  return (
+    differ.length === 2 &&
+    first !== undefined &&
+    second === first + 1 &&
+    left.charAt(first) === right.charAt(second) &&
+    left.charAt(second) === right.charAt(first)
+  );
+};
+
+/**
+ * 語の中の一字の抜け。語の終わりの抜け（Service と Services、America と American）は語の形の違い、頭の抜け（State と XState）は
+ * 別の名前で、書き損じではない。
+ */
+const isInnerDrop = (longer: string, shorter: string): boolean =>
+  [...longer].some((_char, index) => index > 0 && index < longer.length - 1 && longer.slice(0, index) + longer.slice(index + 1) === shorter);
+
+/** 二つの語が一字違いか。英字だけの、長さ 5 以上の語で。 */
+export const isNearWord = (left: string, right: string): boolean => {
+  if (left === right || !LATIN_WORD.test(left) || !LATIN_WORD.test(right) || Math.min(left.length, right.length) < MIN_NEAR_LENGTH) return false;
+  if (left.length === right.length) return isSwapOrReplace(left, right);
+  if (left.length === right.length + 1) return isInnerDrop(left, right);
+  return right.length === left.length + 1 && isInnerDrop(right, left);
+};
+
+/** 語の一つを伏せた形。ほかの語が同じ二つの名前は、同じ形を一つ持つ。 */
+const maskedKeys = (tally: Tally): string[] => {
+  const words = wordsOf(tally.surface);
+  return words.map((_word, index) => words.map((word, at) => (at === index ? "*" : word)).join(" "));
+};
+
+const differingWords = (left: Tally, right: Tally): readonly [string, string] | undefined => {
+  const leftWords = wordsOf(left.surface);
+  const rightWords = wordsOf(right.surface);
+  const at = leftWords.findIndex((word, index) => word !== rightWords[index]);
+  const [leftWord, rightWord] = [leftWords[at], rightWords[at]];
+  return leftWords.length === rightWords.length && leftWord !== undefined && rightWord !== undefined ? [leftWord, rightWord] : undefined;
+};
+
+/** 一語だけが一字違いで、相手が二度以上、こちらが一度だけ。 */
+const isSlipOf = (tally: Tally, other: Tally): boolean => {
+  if (tally.count !== 1 || other.count < 2) return false;
+  const words = differingWords(tally, other);
+  return words !== undefined && isNearWord(...words);
+};
+
+const nearVariants = (tallies: readonly Tally[]): NameVariant[] => variantsIn(groupBy(tallies, maskedKeys), "near", isSlipOf);
+
+/** 同じ名前の、少ないほうの書き方。書き方ごとに最初の現れを一つ。同じ現れを二つの見方が言えば、先の見方だけ。 */
+export const nameVariants = (mentions: readonly NameMention[]): NameVariant[] => {
+  const tallies = talliesOf(mentions);
+  const found = [
+    ...variantsIn(
+      groupBy(tallies, (tally) => [nameKey(tally.surface)]),
+      "spelling",
+    ),
+    ...variantsIn(
+      groupBy(tallies, (tally) => (tally.first.reading === undefined ? [] : [tally.first.reading])),
+      "reading",
+      oneWordApart,
+    ),
+    ...nearVariants(tallies),
+  ];
+  const reported = new Set<string>();
+  return found
+    .filter((variant) => {
+      if (reported.has(variant.mention.surface)) return false;
+      reported.add(variant.mention.surface);
+      return true;
+    })
+    .toSorted((left, right) => left.mention.offset - right.mention.offset);
+};

package/src/node-version.ts

@@ -0,0 +1,22 @@
+// bin/chaff.js loads this before the CLI, on whatever Node.js the person has. Keep it free of imports and of syntax
+// that old releases cannot parse (`??`, `?.`): running there is its whole job.
+
+type Env = Readonly<Record<string, string | undefined>>;
+
+/** The lowest major version an engines range such as ">=24" names, or undefined for a range of another shape. */
+export const requiredMajorOf = (range: unknown): number | undefined => {
+  const match = /^\s*>=\s*v?(\d+)/u.exec(String(range));
+  return match === null ? undefined : Number(match[1]);
+};
+
+const isJapaneseLocale = (env: Env): boolean => /^ja/iu.test(env["LC_ALL"] || env["LC_MESSAGES"] || env["LANG"] || "");
+
+/** What to print before stopping when this Node.js is older than the engines range; undefined when it is new enough. */
+export const tooOldMessage = (version: string, range: unknown, env: Env): string | undefined => {
+  const required = requiredMajorOf(range);
+  const major = Number(version.split(".")[0]);
+  if (required === undefined || Number.isNaN(major) || major >= required) return undefined;
+  return isJapaneseLocale(env)
+    ? `chaff は Node.js ${String(required)} 以上で動きます。いまは v${version} です。https://nodejs.org/ja から LTS を入れてください。`
+    : `chaff needs Node.js ${String(required)} or later. This is v${version}. Install the LTS from https://nodejs.org/en`;
+};

package/src/not-run.ts

@@ -0,0 +1,16 @@
+import type { Skipped } from "./run.ts";
+
+/** A rule someone asked about that did not run in this check, with why, and whether --experimental would run it. */
+export type NotRun = { readonly rule: string; readonly why: string; readonly needsExperimental: boolean };
+
+/**
+ * Pure: of the rules named in `ruleIds`, those this check skipped. A command that looks a rule's findings up (feedback,
+ * suppressions) says this instead of "none": no findings from a rule that did not run is not "checked and fine".
+ * --experimental is suggested only where it is the reason, not for a rule chaff.yaml or the genre turned off.
+ */
+export const notRunAmong = (ruleIds: readonly string[], skipped: readonly Skipped[]): NotRun[] => {
+  const asked = new Set(ruleIds);
+  return skipped
+    .filter((entry) => asked.has(entry.rule))
+    .map((entry) => ({ rule: entry.rule, why: entry.why, needsExperimental: entry.offUntilExperimental === true }));
+};

package/src/orthography.ts

@@ -152,13 +152,25 @@ export const hyphenGroups = (text: string): string[] => text.split(HYPHEN).filte
 
 const isCodeChar = (char: string | undefined): boolean => DIGIT.test(char ?? "") || isHyphen(char);
 
-const isCode = (chars: readonly string[], digit: number): boolean => {
+/** digit を含む、isPart の字の並び。 */
+const runAround = (chars: readonly string[], digit: number, isPart: (char: string | undefined) => boolean): string => {
   let [first, last] = [digit, digit];
-  while (first > 0 && isCodeChar(chars[first - 1])) first -= 1;
-  while (last < chars.length - 1 && isCodeChar(chars[last + 1])) last += 1;
-  return hyphenGroups(chars.slice(first, last + 1).join("")).length >= MIN_CODE_GROUPS;
+  while (first > 0 && isPart(chars[first - 1])) first -= 1;
+  while (last < chars.length - 1 && isPart(chars[last + 1])) last += 1;
+  return chars.slice(first, last + 1).join("");
 };
 
+const isDottedChar = (char: string | undefined): boolean => DIGIT.test(char ?? "") || char === ".";
+
+/** 「1.0.0」「3.1.2」のように . でつないだ 3 組以上の数字は、版や項目の番号で数量ではない。2 組（「1.5 倍」）は小数なので数える。 */
+const isDottedCode = (chars: readonly string[], digit: number): boolean =>
+  runAround(chars, digit, isDottedChar)
+    .split(".")
+    .filter((group) => group !== "").length >= MIN_CODE_GROUPS;
+
+const isCode = (chars: readonly string[], digit: number): boolean =>
+  hyphenGroups(runAround(chars, digit, isCodeChar)).length >= MIN_CODE_GROUPS || isDottedCode(chars, digit);
+
 /** 日本語との境目にある数字が、数えない書き方（「第3条」の番地、「073-489-5909」の符号）か。 */
 const isUncountedNumber = (chars: readonly string[], index: number): boolean => {
   const [left, right] = [chars[index], chars[index + 1]];
@@ -201,13 +213,30 @@ export const latinBoundaries = (text: string, written: string = text): Boundary[
 };
 
 /**
- * 混ざっているとき、そろえるべき少数派。種類（英字・数字の前・数字の後ろ）ごとに数える。
+ * 二通りの書き方（true と false）が混ざっているとき、そろえるべき少数派。どちらか一方しか無ければ undefined。
  * 同数なら、文書が先に使った書き方をその文書の書き方とみなし、後から出た書き方を少数派にする。
  */
-export const minorityStyle = (boundaries: readonly { readonly spaced: boolean }[]): boolean | undefined => {
-  const spaced = boundaries.filter((boundary) => boundary.spaced).length;
-  const touching = boundaries.length - spaced;
-  if (spaced === 0 || touching === 0) return undefined;
-  if (spaced !== touching) return spaced < touching;
-  return !(boundaries[0]?.spaced ?? false);
+export const minorityOf = (written: readonly boolean[]): boolean | undefined => {
+  const yes = written.filter(Boolean).length;
+  const no = written.length - yes;
+  if (yes === 0 || no === 0) return undefined;
+  if (yes !== no) return yes < no;
+  return !(written[0] ?? false);
 };
+
+const PERCENT = 100;
+
+/**
+ * 二通りに書き分けたもの（side が true か false）のうち、少ないほうのもの。少ないほうが全体の limitPercent パーセントを超えるなら、
+ * 文書が使い分けていると見て空。どちらか一方しか無くても空。
+ */
+export const minorityWithin = <T>(items: readonly T[], side: (item: T) => boolean, limitPercent: number): T[] => {
+  const minority = minorityOf(items.map(side));
+  if (minority === undefined) return [];
+  const odd = items.filter((item) => side(item) === minority);
+  return odd.length * PERCENT > limitPercent * items.length ? [] : odd;
+};
+
+/** 空けるか詰めるかの少数派。種類（英字・数字の前・数字の後ろ）ごとに数える。 */
+export const minorityStyle = (boundaries: readonly { readonly spaced: boolean }[]): boolean | undefined =>
+  minorityOf(boundaries.map((boundary) => boundary.spaced));

package/src/outline/render.ts

@@ -0,0 +1,85 @@
+import type { LengthUnit } from "../plugin.ts";
+import type { Outline, OutlineEntry, Shape } from "./shape.ts";
+import type { OutlineText } from "./text.ts";
+
+/** One file's outline as `chaff outline` shows it. */
+export type DocumentOutline = { readonly path: string; readonly language: string; readonly outline: Outline };
+
+type Measure = { readonly name: string; readonly value: (shape: Shape, unit: LengthUnit) => string };
+
+/** The shape's measures in the order they are shown. */
+const measuresOf = (text: OutlineText): readonly Measure[] => [
+  { name: text.headings, value: (shape) => String(shape.headings) },
+  { name: text.averageSection, value: (shape, unit) => text.length(shape.averageSectionLength, unit) },
+  { name: text.lists, value: (shape) => `${String(shape.listPercent)}%` },
+  { name: text.bold, value: (shape) => String(shape.bold) },
+];
+
+/** The shape's measures on one line: 見出し 6、節の平均 120 字、… / headings 6, average section 80 words, … */
+export const shapeMeasures = (shape: Shape, unit: LengthUnit, text: OutlineText): string =>
+  measuresOf(text)
+    .map((measure) => text.measure(measure.name, measure.value(shape, unit)))
+    .join(text.separator);
+
+const shapeLine = (document: DocumentOutline, text: OutlineText): string =>
+  text.shapeOf(document.path, shapeMeasures(document.outline.shape, document.outline.unit, text));
+
+const headingOf = (entry: OutlineEntry, text: OutlineText): string => (entry.depth === 0 ? text.lead : `${"#".repeat(entry.depth)} ${entry.heading}`);
+
+/** A heading indented by its depth, where it is, and how long its own text is. */
+const entryLine = (entry: OutlineEntry, document: DocumentOutline, text: OutlineText): string => {
+  const indent = "  ".repeat(Math.max(entry.depth - 1, 0));
+  const length = text.length(entry.length, document.outline.unit);
+  return `  ${indent}${headingOf(entry, text)}  (${document.path}:${String(entry.line)})  ${length}`;
+};
+
+const outlineBlock = (document: DocumentOutline, text: OutlineText): string[] => [
+  shapeLine(document, text),
+  "",
+  ...document.outline.entries.map((entry) => entryLine(entry, document, text)),
+];
+
+/** Each measure before and after, so a restructure shows as numbers that moved. */
+const changeBlock = (before: DocumentOutline, after: DocumentOutline, text: OutlineText): string[] => [
+  "",
+  text.changed(before.path, after.path),
+  ...measuresOf(text).map(
+    (measure) => `  ${measure.name}: ${measure.value(before.outline.shape, before.outline.unit)} → ${measure.value(after.outline.shape, after.outline.unit)}`,
+  ),
+];
+
+/** For a person: each file's shape and outline, then, for two files, how each measure moved. */
+export const renderOutlineFriendly = (documents: readonly DocumentOutline[], text: OutlineText): string => {
+  const [before, after] = documents;
+  const outlines = documents.flatMap((document, index) => [...(index > 0 ? [""] : []), ...outlineBlock(document, text)]);
+  return [...outlines, ...(before !== undefined && after !== undefined ? changeBlock(before, after, text) : [])].join("\n");
+};
+
+const COMPACT_UNIT: Readonly<Record<LengthUnit, string>> = { char: "chars", word: "words" };
+
+const compactEntry = (entry: OutlineEntry, document: DocumentOutline): string => {
+  const heading = entry.depth === 0 ? "lead" : `h${String(entry.depth)} ${entry.heading}`;
+  return `${document.path}:${String(entry.line)}: ${heading} (${String(entry.length)} ${COMPACT_UNIT[document.outline.unit]})`;
+};
+
+/** For grep: one section per line, then each file's shape. */
+export const renderOutlineCompact = (documents: readonly DocumentOutline[], text: OutlineText): string =>
+  [
+    ...documents.flatMap((document) => document.outline.entries.map((entry) => compactEntry(entry, document))),
+    ...documents.map((document) => shapeLine(document, text)),
+  ].join("\n");
+
+const outlineJson = (document: DocumentOutline): Readonly<Record<string, unknown>> => ({
+  path: document.path,
+  language: document.language,
+  unit: document.outline.unit,
+  shape: document.outline.shape,
+  outline: document.outline.entries,
+});
+
+/** For an AI: one file's outline and shape, or `before` and `after` for two. */
+export const renderOutlineJson = (documents: readonly DocumentOutline[]): string => {
+  const [before, after] = documents;
+  const body = before !== undefined && after !== undefined ? { before: outlineJson(before), after: outlineJson(after) } : documents.map(outlineJson)[0];
+  return JSON.stringify(body, null, 2);
+};

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/text.ts

@@ -0,0 +1,50 @@
+import type { Texts } from "../ui.ts";
+import type { LengthUnit } from "../plugin.ts";
+import { counted } from "../render/plural.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;
+};
+
+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}）`,
+  },
+  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})`,
+  },
+};

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;
 };
@@ -188,8 +192,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 +242,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,6 +350,8 @@ export type ProseDocument = {
   readonly profile?: DocumentProfile | undefined;
   /** 本文でないもの（コード・HTML・強調の印）を同じ長さの空白で覆った source。位置は source と同じ。 */
   readonly prose?: string | undefined;
+  /** 位置のすぐ前に書いた文書の名前を読む。言語パッケージが読めなければ無い。 */
+  readonly namedDocument?: DocumentNamer | undefined;
   /** メールの引用した返信（前置きの行と「> 」の行）。ほかの人の言葉なので、見出しにも木にも入れない。 */
   readonly replyQuotes?: readonly Span[] | undefined;
   /** 記法の手がかり（見出し・画像・リンク）。記法を読む rule だけが触れ、触れたときに作る。 */
@@ -474,8 +487,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 +505,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;
@@ -29,6 +30,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: "設定で止めているため",
@@ -46,6 +48,7 @@ export const REASONS: Texts<Reasons> = {
     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",