chaffjs 0.18.0 → 0.20.0

package/src/render/compact.ts

@@ -1,4 +1,4 @@
-import type { RuleDefinition } from "../plugin.ts";
+import type { Finding, RuleDefinition } from "../plugin.ts";
 import type { RunResult } from "../run.ts";
 import { messageOf } from "./text.ts";
 import { counted } from "./plural.ts";
@@ -12,14 +12,24 @@ const TALLY: Texts<{ readonly findings: (n: number) => string; readonly notRun:
   en: { findings: (n) => counted(n, "finding"), notRun: (n) => `${counted(n, "rule")} not run`, separator: ", " },
 };
 
+const POSITION_MIN_WIDTH = 8;
+const SEVERITY_WIDTH = 8;
+
+const positionOf = (finding: Finding): string => `${String(finding.line)}:${String(finding.column)}`;
+
+/** 「行:桁」の列の幅。一番長い位置の後ろにも空白を 1 つ残す。grep や awk が重さの語と区切れるように。 */
+export const positionWidthOf = (findings: readonly Finding[]): number =>
+  findings.reduce((width, finding) => Math.max(width, positionOf(finding).length + 1), POSITION_MIN_WIDTH);
+
 /** エンジニア向け。1 件 2 行。 */
 export const renderCompact = (header: string, result: RunResult, rules: readonly RuleDefinition[], language: string): string => {
   const byId = new Map(rules.map((rule) => [rule.id, rule]));
+  const width = positionWidthOf(result.findings);
   const lines = result.findings.flatMap((finding) => {
     const rule = byId.get(finding.rule);
     if (rule === undefined) return [];
-    const at = `${finding.line}:${finding.column}`.padEnd(8);
-    return [`  ${at}${finding.severity.padEnd(8)}${messageOf(rule, finding, language)}`, `          ${" ".repeat(8)}${finding.rule}`];
+    const message = `  ${positionOf(finding).padEnd(width)}${finding.severity.padEnd(SEVERITY_WIDTH)}${messageOf(rule, finding, language)}`;
+    return [message, `  ${" ".repeat(width + SEVERITY_WIDTH)}${finding.rule}`];
   });
   const text = TALLY[uiLanguageOf(language)];
   const tail = [text.findings(result.findings.length), result.skipped.length > 0 ? text.notRun(result.skipped.length) : undefined].filter(

package/src/render/explain.ts

@@ -1,7 +1,7 @@
 import { definedLevels, resolve, severityAt } from "../levels.ts";
-import { readableText } from "./text.ts";
+import { fill, localized, readableText } from "./text.ts";
 import { SEVERITY_NAME } from "./severity-name.ts";
-import { uiLanguageOf, type Texts, type UiLanguage } from "../ui.ts";
+import { uiLanguageOf, type Texts } from "../ui.ts";
 import type { Level, RuleDefinition } from "../plugin.ts";
 import { optionLines } from "./options.ts";
 import type { OptionLayer } from "../rule-options.ts";
@@ -11,12 +11,15 @@ 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: string;
-  readonly values: (unit: string) => string;
+  readonly definedIn: (plugin: string | undefined) => string;
+  readonly values: string;
+  readonly times: string;
   readonly severities: string;
   readonly now: (level: string) => string;
+  readonly nowNumber: (limit: string) => string;
   readonly from: (source: string) => string;
   readonly change: (id: string) => string;
 }> = {
@@ -25,12 +28,16 @@ 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: "このルールはチームが chaff.yaml の custom_rules で決めたものです。",
-    values: (unit) => `設定できる値（単位: ${unit}）:`,
+    definedIn: (plugin) =>
+      plugin === undefined ? "このルールはチームが chaff.yaml の custom_rules で決めたものです。" : `このルールはプラグイン ${plugin} のものです。`,
+    values: "設定できる値:",
+    times: "回",
     severities: "設定できる値（数える上限は無く、指摘の重さが変わります）:",
     now: (level) => `いまは ${level} です。`,
+    nowNumber: (limit) => `いまは段階ではなく数です: ${limit}。`,
     from: (source) => `（${source} で決めています）`,
     change: (id) => `変える:  npx chaff relax ${id} --why "理由"`,
   },
@@ -39,25 +46,41 @@ 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: "The team defined this rule under custom_rules in chaff.yaml.",
-    values: (unit) => `Levels (unit: ${unit}):`,
+    definedIn: (plugin) =>
+      plugin === undefined ? "The team defined this rule under custom_rules in chaff.yaml." : `This rule comes from the plugin ${plugin}.`,
+    values: "Levels:",
+    times: "times",
     severities: "Levels (there is no limit to count to; a level sets how a finding is marked):",
     now: (level) => `Now: ${level}.`,
+    nowNumber: (limit) => `Now: ${limit}, set as a number rather than a level.`,
     from: (source) => ` (set by ${source})`,
     change: (id) => `Change it:  npx chaff relax ${id} --why "reason"`,
   },
 };
 
+/**
+ * A limit in the rule's words for what it counts ("up to 8 emoji per 1000 words"), as the rule reference shows it.
+ * A rule that says nothing (a team's custom rule) counts matches, so its limit is a number of times.
+ */
+const limitText = (rule: RuleDefinition, limit: number, language: string): string => {
+  const meaning = localized(rule.guide?.levelMeaning ?? {}, language);
+  return meaning === "" ? `${String(limit)} ${TEXT[uiLanguageOf(language)].times}` : fill(meaning, { limit });
+};
+
 /** What a level holds: the limit a detector counts to, or the severity a rule with nothing to count gives. */
-const valueAt = (rule: RuleDefinition, level: Exclude<Level, "off">, genre: string | undefined, ui: UiLanguage): string =>
-  rule.level_sets === "severity" ? SEVERITY_NAME[ui][severityAt(rule, level, genre)] : String(resolve(rule, level, genre).limit);
+const valueAt = (rule: RuleDefinition, level: Exclude<Level, "off">, genre: string | undefined, language: string): string =>
+  rule.level_sets === "severity"
+    ? SEVERITY_NAME[uiLanguageOf(language)][severityAt(rule, level, genre)]
+    : limitText(rule, resolve(rule, level, genre).limit, language);
 
-const levelLine = (rule: RuleDefinition, level: Level, current: Level, genre: string | undefined, ui: UiLanguage): string => {
+/** current is undefined when a number, not a level, sets the limit: no level is marked. */
+const levelLine = (rule: RuleDefinition, level: Level, current: Level | undefined, genre: string | undefined, language: string): string => {
   const mark = level === current ? "→" : " ";
   const name = level.padEnd(9);
-  return level === "off" ? `  ${mark} ${name}${TEXT[ui].off}` : `  ${mark} ${name}${valueAt(rule, level, genre, ui)}`;
+  return level === "off" ? `  ${mark} ${name}${TEXT[uiLanguageOf(language)].off}` : `  ${mark} ${name}${valueAt(rule, level, genre, language)}`;
 };
 
 /** ジャンルで数字が変わる rule は、それを言わないと「設定したのに効かない」に見える。 */
@@ -72,18 +95,28 @@ const exampleLines = (rule: RuleDefinition, language: string, text: (typeof TEXT
   const examples = rule.guide?.examples ?? {};
   const example = examples[language] ?? examples["en"] ?? Object.values(examples)[0];
   if (rule.custom === undefined || example === undefined) return [];
-  return ["", `  ${text.example}:  ${example.before}`, `      →  ${example.after}`, "", `  ${text.definedIn}`];
+  return ["", `  ${text.example}:  ${example.before}`, `      →  ${example.after}`, "", `  ${text.definedIn(rule.plugin)}`];
 };
 
 /** Where the rule's settings come from: the option layers, strongest first, and the source of its level when a style set it. */
-export type ExplainSettings = { readonly optionLayers?: readonly OptionLayer[]; readonly levelFrom?: string | undefined };
+/** limit: a number chaff.yaml or its style set for the rule (rules: { id: 80 }, a style's limits), which a level does not show. */
+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 の意図と根拠を読む。指摘に納得できないときの入口。 */
-export const renderExplain = (rule: RuleDefinition, current: Level, language: string, unit: string, genre?: string, settings: ExplainSettings = {}): string => {
+export const renderExplain = (rule: RuleDefinition, current: Level, language: string, genre?: string, settings: ExplainSettings = {}): string => {
   const { optionLayers = [], levelFrom } = settings;
-  const ui = uiLanguageOf(language);
-  const text = TEXT[ui];
-  const experimental = rule.status === "experimental" ? [`  ${text.experimental}`] : [];
+  // A rule with nothing to count has no number to set; chaff.yaml's number on it is reported as a problem and ignored.
+  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}`, ...(settings.offOnlyAsExperimental === true ? [`  ${text.alone(rule.id)}`] : [])] : [];
   return [
     "",
     `  ${readableText(rule, rule.name, language)}   (${rule.id})`,
@@ -93,12 +126,12 @@ export const renderExplain = (rule: RuleDefinition, current: Level, language: st
     `  ${text.howToFix}: ${readableText(rule, rule.how_to_fix, language)}`,
     ...exampleLines(rule, language, text),
     "",
-    `  ${rule.level_sets === "severity" ? text.severities : text.values(unit)}`,
-    ...definedLevels(rule).map((level) => levelLine(rule, level, current, genre, ui)),
+    `  ${rule.level_sets === "severity" ? text.severities : text.values}`,
+    ...definedLevels(rule).map((level) => levelLine(rule, level, marked, genre, language)),
     ...genreNote(rule, genre, text),
     ...optionLines(rule, optionLayers, language),
     "",
-    `  ${text.now(current)}${levelFrom === undefined ? "" : text.from(levelFrom)}`,
+    `  ${limit === undefined ? text.now(current) : text.nowNumber(limitText(rule, limit, language))}${levelFrom === undefined ? "" : text.from(levelFrom)}`,
     ...experimental,
     "",
     `  ${text.change(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,10 +7,12 @@ 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 { styleLevelSource } from "../config/style.ts";
+import { limitsFor, styleLevelSource } from "../config/style.ts";
 import { loadStyles } from "../style-load.ts";
 import type { OptionLayer } from "../rule-options.ts";
+import { CUSTOM_TYPES } from "../custom/parse.ts";
 
 const TEXT: Texts<{
   readonly offBySetting: string;
@@ -59,40 +61,45 @@ const TEXT: Texts<{
   },
 };
 
-const now = (rule: RuleDefinition, config: Config, genre: string, text: (typeof TEXT)["ja"], preset: PresetLevels): Record<string, unknown> => {
+type Limits = Readonly<Record<string, number>>;
+
+/** 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];
   if (explicit === "off" && config.rules[rule.id] === undefined) return { level: "off", why_off: text.offByGenre(genre) };
   if (explicit === "off") return { level: "off", why_off: text.offBySetting };
-  const limit = rule.level_sets === "severity" ? undefined : config.limits[rule.id];
+  const limit = rule.level_sets === "severity" ? undefined : limits[rule.id];
   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, 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> =>
   rule.level_sets === "severity" ? { severity: severityAt(rule, level, genre) } : { limit: resolve(rule, level, genre).limit };
 
-const yourSetting = (rule: RuleDefinition, config: Config): Record<string, unknown> | null => {
+const yourSetting = (rule: RuleDefinition, config: Config, limits: Limits): Record<string, unknown> | null => {
   const level = config.rules[rule.id];
   if (level === undefined) return null;
   const from = styleLevelSource(config, rule.id) ?? config.path;
-  const limit = rule.level_sets === "severity" ? undefined : config.limits[rule.id];
+  const limit = rule.level_sets === "severity" ? undefined : limits[rule.id];
   return limit === undefined ? { level, from } : { level, limit, from };
 };
 
 /** The house style chaff.yaml names: what it decides and the guideline it follows, so an AI can say where a setting came from. */
 const styleOf = (config: Config): Record<string, unknown> | null => {
-  const style = loadStyles().find((entry) => entry.id === config.applied?.style);
+  const style = [...loadStyles(), ...(config.extensions?.styles ?? [])].find((entry) => entry.id === config.applied?.style);
   return style === undefined ? null : { id: style.id, name: style.name, summary: style.summary, source: style.source };
 };
 
@@ -153,11 +160,11 @@ const groupsOf = (): Record<string, unknown>[] =>
 
 /**
  * What the local-rules release adds. Named now so an AI reading the JSON knows they are coming and does not invent them.
- * Filled in when they ship: the style presets under style:, the custom_rules types, and each rule's options.
+ * Filled in as they ship: the style presets under style:, each rule's options. The custom_rules types have shipped.
  */
 const COMING = {
   style_presets: { status: "coming", presets: [] },
-  custom_rule_types: { status: "coming", planned: ["words", "pattern", "tokens", "module"] },
+  custom_rule_types: { status: "available", types: CUSTOM_TYPES },
   rule_options: { status: "coming", note: "Each rule's options (with their types and allowed values) will be listed under options." },
 };
 
@@ -171,6 +178,7 @@ export const rulesJson = (
 ): string => {
   const text = TEXT[uiLanguageOf(language)];
   const preset = presetLevels(genre);
+  const limits = limitsFor(config, language);
   return JSON.stringify(
     {
       // 2: rules gained group, summary, example, not_flagged, level_meaning, languages, requires and genres,
@@ -194,10 +202,12 @@ export const rulesJson = (
         level_sets: rule.level_sets,
         ...levelsOf(rule, genre),
         levels_you_can_set: definedLevels(rule),
-        your_setting: yourSetting(rule, config),
-        now: now(rule, config, genre, text, preset),
+        your_setting: yourSetting(rule, config, limits),
+        now: now(rule, config, limits, genre, preset, language),
         ...(rule.options === undefined ? {} : { options: optionsJson(rule, optionLayers) }),
-        ...(rule.custom === undefined ? {} : { defined_in: "chaff.yaml custom_rules", custom: rule.custom }),
+        ...(rule.custom === undefined
+          ? {}
+          : { defined_in: rule.plugin === undefined ? "chaff.yaml custom_rules" : `plugin ${rule.plugin}`, custom: rule.custom }),
         ...guideOf(rule),
       })),
       how_to_write_settings_from_a_style_note: text.fromStyleNote,

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/render/suppressions.ts

@@ -1,4 +1,5 @@
 import type { Suppressed, Suppression } from "../stet.ts";
+import type { NotRun } from "../not-run.ts";
 import type { Texts, UiLanguage } from "../ui.ts";
 import { counted } from "./plural.ts";
 
@@ -11,6 +12,8 @@ const TEXT: Texts<{
   readonly none: string;
   readonly total: (n: number) => string;
   readonly reasonless: (n: number) => string;
+  readonly notRun: string;
+  readonly runExperimental: string;
 }> = {
   ja: {
     nudge: "  ← 設定の見直しを検討してください",
@@ -21,6 +24,8 @@ const TEXT: Texts<{
     none: "\n  抑制されている指摘はありません。\n",
     total: (n) => `抑制されている指摘: ${n} 件`,
     reasonless: (n) => `理由が書かれていない抑制: ${n} 件`,
+    notRun: "stet はあるが、今回動いていない rule（数えていません）:",
+    runExperimental: "試験中の rule は --experimental を付けると数えます。",
   },
   en: {
     nudge: "  <- consider changing the setting instead",
@@ -31,10 +36,18 @@ const TEXT: Texts<{
     none: "\n  No findings are silenced.\n",
     total: (n) => `Silenced findings: ${n}`,
     reasonless: (n) => `Silenced without a reason: ${n}`,
+    notRun: "Rules with a stet that did not run in this check (not counted):",
+    runExperimental: "Experimental rules are counted with --experimental.",
   },
 };
 
-export type PerFile = { readonly path: string; readonly suppressed: readonly Suppressed[]; readonly reasonless: readonly Suppression[] };
+export type PerFile = {
+  readonly path: string;
+  readonly suppressed: readonly Suppressed[];
+  readonly reasonless: readonly Suppression[];
+  /** Rules a stet in the file names that did not run, so their silenced findings could not be counted. */
+  readonly notRun: readonly NotRun[];
+};
 
 /** これを超えたら、その rule は (b) ではなく (c) にすべきというサイン。 */
 const NUDGE_AT = 5;
@@ -72,6 +85,19 @@ const groupLines = (group: Group, ui: UiLanguage): string[] => {
   ];
 };
 
+/** The rules whose stets were not counted because the rule did not run, one line each, with why and where. */
+const notRunLines = (files: readonly PerFile[], ui: UiLanguage): string[] => {
+  const text = TEXT[ui];
+  const rows = files.flatMap((file) => file.notRun.map((entry) => ({ ...entry, path: file.path })));
+  if (rows.length === 0) return [];
+  const rules = [...new Set(rows.map((row) => row.rule))];
+  const lines = rules.map((rule) => {
+    const mine = rows.filter((row) => row.rule === rule);
+    return `      ${rule.padEnd(26)}${mine[0]?.why ?? ""}   ${[...new Set(mine.map((row) => row.path))].join(", ")}`;
+  });
+  return ["", `  ${text.notRun}`, ...lines, ...(rows.some((row) => row.needsExperimental) ? [`  ${text.runExperimental}`] : [])];
+};
+
 /**
  * 抑制が溜まったことに気づけないと、規範と現実の乖離が静かに進む。
  * 同じ rule を何度も黙らせているなら、それは (b) ではなく (c) のサイン。
@@ -81,13 +107,15 @@ export const renderSuppressions = (files: readonly PerFile[], ui: UiLanguage = "
   const text = TEXT[ui];
   const groups = groupByRule(files);
   const total = groups.reduce((sum, group) => sum + group.count, 0);
-  if (total === 0) return text.none;
+  const notRun = notRunLines(files, ui);
+  if (total === 0) return notRun.length === 0 ? text.none : [text.none.trimEnd(), ...notRun, ""].join("\n");
   const reasonless = files.flatMap((file) => file.reasonless.map(() => file.path));
   return [
     "",
     `  ${text.total(total)}`,
     ...groups.flatMap((group) => groupLines(group, ui)),
     ...(reasonless.length > 0 ? ["", `  ${text.reasonless(reasonless.length)}`, `      ${[...new Set(reasonless)].join(", ")}`] : []),
+    ...notRun,
     "",
   ].join("\n");
 };

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. */
@@ -80,6 +82,20 @@ export type ExampleOutcome = {
   readonly after: readonly ExampleFinding[];
 };
 
+/** One spot written the way the rule flags it, and the same spot rewritten without adding a fact. */
+export type RewritePair = { readonly before: string; readonly after: string };
+
+/**
+ * How to rewrite a spot the rule flags, for an AI or a person doing the fix (chaff fix-plan prints it).
+ * direction: what to do; keep: what must not change; avoid: the mistakes a rewriter makes here.
+ */
+export type RuleRewrite = {
+  readonly direction: string;
+  readonly pairs: readonly RewritePair[];
+  readonly keep: readonly string[];
+  readonly avoid: readonly string[];
+};
+
 /** The plain-language part of a rule file: what the reference tells a reader, apart from the texts chaff prints. */
 export type RuleGuide = {
   readonly group: RuleGroup | undefined;
@@ -91,6 +107,10 @@ export type RuleGuide = {
   readonly notFlagged: Localized;
   /** What a level's number means, with {limit} for the number ("一文 {limit} 字まで"). None when every level is the same. */
   readonly levelMeaning: Localized;
+  /** The bibliography entries the rule rests on: the anchors of site/src/content/guide/{ja,en}/bibliography.md. */
+  readonly sources: readonly string[];
+  /** By language, optional per rule. */
+  readonly rewrite: Readonly<Record<string, RuleRewrite>>;
 };
 
 const isRecord = (value: unknown): value is Record<string, unknown> => typeof value === "object" && value !== null && !Array.isArray(value);
@@ -108,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"] } : {}),
   };
 };
 
@@ -121,6 +142,24 @@ const examplesOf = (value: unknown): Readonly<Record<string, RuleExample>> =>
       )
     : {};
 
+const textsOf = (value: unknown): string[] => (Array.isArray(value) ? value.filter(isText) : []);
+
+const pairOf = (value: unknown): RewritePair[] =>
+  isRecord(value) && isText(value["before"]) && isText(value["after"]) ? [{ before: value["before"], after: value["after"] }] : [];
+
+/** A block that is written reads field by field; what is missing reads as empty, and the test on rule files names it. */
+const rewriteOf = (value: Readonly<Record<string, unknown>>): RuleRewrite => ({
+  direction: isText(value["direction"]) ? value["direction"] : "",
+  pairs: Array.isArray(value["pairs"]) ? value["pairs"].flatMap(pairOf) : [],
+  keep: textsOf(value["keep"]),
+  avoid: textsOf(value["avoid"]),
+});
+
+const rewritesOf = (value: unknown): Readonly<Record<string, RuleRewrite>> =>
+  isRecord(value)
+    ? Object.fromEntries(Object.entries(value).flatMap(([language, entry]) => (isRecord(entry) ? [[language, rewriteOf(entry)] as const] : [])))
+    : {};
+
 /** A field that is missing or malformed reads as empty; the test on rule files names what a rule lacks. */
 export const ruleGuideOf = (raw: Readonly<Record<string, unknown>>): RuleGuide => ({
   group: RULE_GROUPS.find((group) => group === raw["group"]),
@@ -128,6 +167,8 @@ export const ruleGuideOf = (raw: Readonly<Record<string, unknown>>): RuleGuide =
   examples: examplesOf(raw["example"]),
   notFlagged: localizedOf(raw["not_flagged"]),
   levelMeaning: localizedOf(raw["level_meaning"]),
+  sources: textsOf(raw["sources"]),
+  rewrite: rewritesOf(raw["rewrite"]),
 });
 
 /** The rules in each group, in the order the reference lists them. A rule with no group is in none, which the test on rule files reports. */

package/src/run-semantic.ts

@@ -6,6 +6,7 @@ import { localized } from "./render/text.ts";
 import type { AdapterNeeds, Finding, Level, ProseDocument, RuleDefinition, Severity } from "./plugin.ts";
 import { lineStarts, placeOf } from "./position.ts";
 import { wantsTags } from "./run.ts";
+import { byPosition } from "./finding-order.ts";
 
 export type SemanticResult = {
   readonly findings: readonly Finding[];
@@ -137,7 +138,7 @@ export const runSemantic = async (
     ),
   );
   return {
-    findings: answers.filter((finding) => finding !== undefined).toSorted((left, right) => left.line - right.line),
+    findings: answers.filter((finding) => finding !== undefined).toSorted(byPosition),
     skipped,
     asked: live.reduce((sum, job) => sum + job.candidates.length, 0),
     sentencesSeen: doc.sentences.length,