chaffjs 0.19.0 → 0.20.0

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

@@ -1,6 +1,7 @@
 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;
@@ -18,6 +19,8 @@ export type OutlineText = {
   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> = {
@@ -33,6 +36,7 @@ export const OUTLINE_TEXT: Texts<OutlineText> = {
     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>]",
@@ -46,5 +50,6 @@ export const OUTLINE_TEXT: Texts<OutlineText> = {
     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

@@ -109,6 +109,8 @@ export type LanguageAdapter = {
   readonly lexicons: Readonly<Record<string, Lexicon>>;
   /** 文書の構造を読む型。無い言語では `chaff tree` がそう言って止まる。 */
   readonly structure?: StructurePatterns;
+  /** 綴りを確かめる辞書（小文字の語の集まり）。大きいので、rule が呼んだときに読む。持たない言語では綴りの rule が動かない。 */
+  readonly dictionary?: () => ReadonlySet<string>;
 };
 
 // ───────── 文書の構造 ─────────
@@ -356,6 +358,8 @@ export type ProseDocument = {
   readonly replyQuotes?: readonly Span[] | undefined;
   /** 記法の手がかり（見出し・画像・リンク）。記法を読む rule だけが触れ、触れたときに作る。 */
   readonly markup?: Markup | undefined;
+  /** adapter の綴りの辞書。持たない言語では無い。 */
+  readonly dictionary?: (() => ReadonlySet<string>) | undefined;
 };
 
 /** 見出し 1 つ。text は属性（`{#id}`）を外した言葉。 */
@@ -433,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";

package/src/reasons.ts

@@ -18,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>>> = {
@@ -43,6 +45,7 @@ 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}`,
@@ -61,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)",
   },
 };

package/src/render/explain.ts

@@ -11,6 +11,7 @@ const TEXT: Texts<{
   readonly defaultGenre: string;
   readonly genreNote: (genre: string, others: string) => string;
   readonly experimental: string;
+  readonly alone: (id: string) => string;
   readonly howToFix: string;
   readonly example: string;
   readonly definedIn: (plugin: string | undefined) => string;
@@ -27,6 +28,7 @@ const TEXT: Texts<{
     defaultGenre: "既定",
     genreNote: (genre, others) => `この数字は ${genre} のものです。ほかに ${others} で別の数字を持っています。`,
     experimental: "このルールはまだ試験中で、既定では動きません（--experimental で動きます）。",
+    alone: (id) => `このルールだけを動かす:  npx chaffjs enable ${id}（chaff.yaml の rules に ${id}: normal と書くのと同じです）`,
     howToFix: "直しかた",
     example: "例",
     definedIn: (plugin) =>
@@ -44,6 +46,7 @@ const TEXT: Texts<{
     defaultGenre: "the default genre",
     genreNote: (genre, others) => `These numbers are for ${genre}. ${others} have numbers of their own.`,
     experimental: "This rule is still experimental and does not run by default (--experimental runs it).",
+    alone: (id) => `Turn on this rule alone:  npx chaffjs enable ${id}  (the same as rules: { ${id}: normal } in chaff.yaml)`,
     howToFix: "How to fix",
     example: "Example",
     definedIn: (plugin) =>
@@ -101,6 +104,8 @@ export type ExplainSettings = {
   readonly optionLayers?: readonly OptionLayer[];
   readonly levelFrom?: string | undefined;
   readonly limit?: number | undefined;
+  /** The rule is off only because it is experimental, so naming it would run it: say how. */
+  readonly offOnlyAsExperimental?: boolean;
 };
 
 /** rule の意図と根拠を読む。指摘に納得できないときの入口。 */
@@ -110,7 +115,8 @@ export const renderExplain = (rule: RuleDefinition, current: Level, language: st
   const limit = rule.level_sets === "severity" ? undefined : settings.limit;
   const marked = limit === undefined ? current : undefined;
   const text = TEXT[uiLanguageOf(language)];
-  const experimental = rule.status === "experimental" ? [`  ${text.experimental}`] : [];
+  const experimental =
+    rule.status === "experimental" ? [`  ${text.experimental}`, ...(settings.offOnlyAsExperimental === true ? [`  ${text.alone(rule.id)}`] : [])] : [];
   return [
     "",
     `  ${readableText(rule, rule.name, language)}   (${rule.id})`,

package/src/render/friendly.ts

@@ -17,6 +17,7 @@ const TEXT: Texts<{
   readonly presetOn: (n: number, ids: string) => string;
   readonly notRun: (n: number) => string;
   readonly because: (why: string) => string;
+  readonly alone: (id: string) => string;
 }> = {
   ja: {
     line: (n) => `${n} 行目`,
@@ -28,6 +29,8 @@ const TEXT: Texts<{
     presetOn: (n, ids) => `試験中の rule を ${n} 件、ジャンルの既定で有効にしています: ${ids}`,
     notRun: (n) => `${n} 件の rule は動いていません:`,
     because: (why) => `（${why}）`,
+    alone: (id) =>
+      `試験中のルールを 1 つだけ動かすには、npx chaffjs enable ${id} のように名指しします（chaff.yaml の rules に ${id}: normal と書くのと同じです）。--experimental はすべてを動かします。`,
   },
   en: {
     line: (n) => `line ${n}`,
@@ -39,8 +42,16 @@ const TEXT: Texts<{
     presetOn: (n, ids) => `${counted(n, "experimental rule")} turned on by the genre: ${ids}`,
     notRun: (n) => `${counted(n, "rule")} did not run:`,
     because: (why) => ` (${why})`,
+    alone: (id) =>
+      `Turn on one experimental rule alone by naming it: npx chaffjs enable ${id} (the same as rules: { ${id}: normal } in chaff.yaml). --experimental turns on all of them.`,
   },
 };
+/** Said once under the list, naming the first rule that is off only because it is experimental: not once per line. */
+const aloneHint = (skipped: RunResult["skipped"], alone: (id: string) => string): string[] => {
+  const example = skipped.find((entry) => entry.offUntilExperimental === true);
+  return example === undefined ? [] : ["", `  ${alone(example.rule)}`];
+};
+
 const QUOTE_LIMIT = 120;
 
 const indent = (text: string, pad: string): string[] => text.split("\n").map((line) => `${pad}${line}`);
@@ -113,7 +124,12 @@ export const renderFriendly = (
   ];
   const skipped =
     result.skipped.length > 0
-      ? ["", `  ${text.notRun(result.skipped.length)}`, ...result.skipped.map((entry) => `      ${entry.rule}${text.because(entry.why)}`)]
+      ? [
+          "",
+          `  ${text.notRun(result.skipped.length)}`,
+          ...result.skipped.map((entry) => `      ${entry.rule}${text.because(entry.why)}`),
+          ...aloneHint(result.skipped, text.alone),
+        ]
       : [];
   const after = notes.flatMap((note) => ["", note]);
   return ["", header, ...blocks, ...closing, ...forced, ...skipped, ...after, ""].join("\n");

package/src/render/rules-json.ts

@@ -7,6 +7,7 @@ import { loadGenres, presetLevels } from "../genre-load.ts";
 import { presetLevelsOf, type PresetLevels } from "../genre-parse.ts";
 import { RULE_GROUPS, groupTextOf } from "../rule-guide.ts";
 import { standingIn } from "../rule-genres.ts";
+import { offOnlyAsExperimental } from "../experimental-alone.ts";
 import { optionsJson } from "./options.ts";
 import { limitsFor, styleLevelSource } from "../config/style.ts";
 import { loadStyles } from "../style-load.ts";
@@ -62,7 +63,9 @@ const TEXT: Texts<{
 
 type Limits = Readonly<Record<string, number>>;
 
-const now = (rule: RuleDefinition, config: Config, limits: Limits, genre: string, text: (typeof TEXT)["ja"], preset: PresetLevels): Record<string, unknown> => {
+/** language: the documents', for a rule that reads only some languages. */
+const now = (rule: RuleDefinition, config: Config, limits: Limits, genre: string, preset: PresetLevels, language: string): Record<string, unknown> => {
+  const text = TEXT[uiLanguageOf(language)];
   // A run leaves out a rule whose use_for does not cover the genre before it reads any level.
   if (standingIn(rule, genre, {}).kind === "unsuited") return { level: "off", why_off: text.offUnsuited(genre) };
   const explicit = config.rules[rule.id] ?? preset[rule.id];
@@ -72,14 +75,15 @@ const now = (rule: RuleDefinition, config: Config, limits: Limits, genre: string
   if (limit !== undefined) return { level: "normal", limit, set_as: "number" };
   if (explicit !== undefined) return { level: explicit, ...effectAt(rule, explicit, genre) };
   if (rule.status === "experimental" && !config.experimental) {
-    return { level: "off", why_off: text.offExperimental, turn_on_with: `npx chaff lint --experimental` };
+    const alone = offOnlyAsExperimental(rule, config, genre, preset, language);
+    return { level: "off", why_off: text.offExperimental, ...(alone ? { turn_on_with: `npx chaffjs enable ${rule.id}` } : {}) };
   }
   return { level: "normal", ...effectAt(rule, "normal", genre) };
 };
 
 /** The level a rule runs at now, and why it is off when it is: what `chaff rules` shows in its table. */
 export const nowFor = (rule: RuleDefinition, config: Config, language: string, genre: string): Record<string, unknown> =>
-  now(rule, config, limitsFor(config, language), genre, TEXT[uiLanguageOf(language)], presetLevels(genre));
+  now(rule, config, limitsFor(config, language), genre, presetLevels(genre), language);
 
 /** What a level does to a rule: the limit it counts to, or, with nothing to count, the severity of its findings. */
 const effectAt = (rule: RuleDefinition, level: Exclude<Level, "off">, genre: string): Record<string, unknown> =>
@@ -199,7 +203,7 @@ export const rulesJson = (
         ...levelsOf(rule, genre),
         levels_you_can_set: definedLevels(rule),
         your_setting: yourSetting(rule, config, limits),
-        now: now(rule, config, limits, genre, text, preset),
+        now: now(rule, config, limits, genre, preset, language),
         ...(rule.options === undefined ? {} : { options: optionsJson(rule, optionLayers) }),
         ...(rule.custom === undefined
           ? {}

package/src/render/rules-table.ts

@@ -48,7 +48,7 @@ const runsWhenOf = (rule: RuleDefinition): RunsWhen => {
 };
 
 /** Columns line up in a terminal only if a wide (CJK) character counts as two. */
-const widthOf = (text: string): number => Array.from(text).reduce((sum, char) => sum + ((char.codePointAt(0) ?? 0) >= 0x2e80 ? 2 : 1), 0);
+export const widthOf = (text: string): number => Array.from(text).reduce((sum, char) => sum + ((char.codePointAt(0) ?? 0) >= 0x2e80 ? 2 : 1), 0);
 
 const pad = (text: string, width: number): string => `${text}${" ".repeat(Math.max(0, width - widthOf(text)))}`;
 

package/src/render/sarif.ts

@@ -37,6 +37,16 @@ type SarifResult = {
   }[];
 };
 
+/** A rule that did not run on one file, and why, in that file's language. */
+export type NotRunOnFile = { readonly path: string; readonly rule: string; readonly why: string };
+
+type SarifNotification = {
+  readonly level: "note";
+  readonly message: { readonly text: string };
+  readonly associatedRule: { readonly id: string };
+  readonly locations: readonly { readonly physicalLocation: { readonly artifactLocation: { readonly uri: string } } }[];
+};
+
 /** `chaff/<rule>` と名前空間を切る。同じ PR に上がる他のツールの rule id と衝突させない。 */
 const ruleIdOf = (rule: string): string => `chaff/${rule}`;
 
@@ -85,7 +95,26 @@ const usedRules = (located: readonly Located[]): SarifRule[] => {
   });
 };
 
-export const renderSarif = (located: readonly Located[], version: string): string => {
+/**
+ * The rules that did not run, one notification per rule and reason, with the files it holds for. Without them an upload
+ * with no results reads as "checked and fine" for rules that never looked.
+ */
+const notRunNotifications = (notRun: readonly NotRunOnFile[]): SarifNotification[] => {
+  const groups = new Map<string, { readonly rule: string; readonly why: string; readonly paths: readonly string[] }>();
+  notRun.forEach((entry) => {
+    const key = JSON.stringify([entry.rule, entry.why]);
+    const group = groups.get(key) ?? { rule: entry.rule, why: entry.why, paths: [] };
+    groups.set(key, { ...group, paths: [...group.paths, entry.path] });
+  });
+  return [...groups.values()].map((group) => ({
+    level: "note",
+    message: { text: `${group.rule}: ${group.why}` },
+    associatedRule: { id: ruleIdOf(group.rule) },
+    locations: group.paths.map((uri) => ({ physicalLocation: { artifactLocation: { uri } } })),
+  }));
+};
+
+export const renderSarif = (located: readonly Located[], version: string, notRun: readonly NotRunOnFile[] = []): string => {
   return `${JSON.stringify(
     {
       $schema: SCHEMA,
@@ -93,6 +122,7 @@ export const renderSarif = (located: readonly Located[], version: string): strin
       runs: [
         {
           tool: { driver: { name: "chaff", version, informationUri: INFORMATION_URI, rules: usedRules(located) } },
+          invocations: [{ executionSuccessful: true, toolConfigurationNotifications: notRunNotifications(notRun) }],
           results: located.map(resultOf),
         },
       ],

package/src/resolve-genre.ts

@@ -6,7 +6,7 @@ import { unknownFrontMatterGenre } from "./genre-check.ts";
 import { plainSource } from "./plain-source.ts";
 
 /** unread: a genre the front matter wrote that chaff does not know, when the front matter was looked at. */
-type ResolvedGenre = { readonly genre: string; readonly from: GenreSource; readonly unread?: string | undefined };
+export type ResolvedGenre = { readonly genre: string; readonly from: GenreSource; readonly unread?: string | undefined };
 
 export const resolveGenre = (path: string, text: string, config: Config, cliGenre?: string): ResolvedGenre => {
   // コマンドで指定したものが最優先。その実行だけの指定だから、設定より強い。

package/src/rule-guide.ts

@@ -61,12 +61,14 @@ export const groupTextOf = (language: string, group: RuleGroup): GroupText => GR
 /**
  * A short text the rule flags and the same text fixed, with the chaff.yaml it needs (jargon, prefer, a level).
  * pad: the rule measures a whole document of some length (per 1000 words), so the example is tried after an ordinary passage.
+ * other: a rule that compares documents (requires: [documents]) is tried with this third file in the same run.
  */
 export type RuleExample = {
   readonly before: string;
   readonly after: string;
   readonly config?: Readonly<Record<string, unknown>>;
   readonly pad?: boolean;
+  readonly other?: string;
 };
 
 /** One finding of the rule itself on its example, as the command line reported it. */
@@ -126,6 +128,7 @@ const exampleOf = (value: unknown): RuleExample | undefined => {
     after: value["after"],
     ...(isRecord(config) ? { config } : {}),
     ...(value["pad"] === true ? { pad: true } : {}),
+    ...(isText(value["other"]) ? { other: value["other"] } : {}),
   };
 };