chaffjs 0.0.1

package/src/plugin.ts

@@ -0,0 +1,124 @@
+// 言語アダプタと genre pack が依存してよい唯一の面。spec §6。
+// ここに実装を置かない。型だけを置く。
+
+export type Span = { readonly start: number; readonly end: number };
+
+export type Sentence = { readonly span: Span; readonly text: string };
+
+/** 品詞は Universal Dependencies の UPOS に統一する。アダプタ独自の体系を露出させない。 */
+export type Token = { readonly span: Span; readonly surface: string; readonly pos: string; readonly lemma?: string };
+
+export type Segmentation = {
+  readonly sentences: readonly Sentence[];
+  readonly words?: readonly Span[];
+  readonly tokens?: readonly Token[];
+};
+
+export type LengthUnit = "char" | "word";
+
+/** L2 の語彙表。detector は共通で、これだけが言語別。spec §11。 */
+export type LexiconEntry = { readonly pattern: string; readonly weight?: number | undefined };
+
+export type Lexicon = readonly LexiconEntry[];
+
+/**
+ * rule は required な capability を宣言し、満たされなければ skip される。
+ * 日本語の品詞解析が 18MB の辞書を要することを、この一枚で吸収する。spec §16。
+ */
+export type AdapterCapabilities = {
+  readonly sentenceSplit: true;
+  readonly wordSplit: boolean;
+  readonly pos: boolean;
+  readonly lemma: boolean;
+  readonly lengthUnit: LengthUnit;
+};
+
+export type LanguageAdapter = {
+  readonly kind: "language";
+  /** BCP 47 の primary subtag。"ja" / "en"。 */
+  readonly id: string;
+  readonly apiVersion: 1;
+  readonly capabilities: AdapterCapabilities;
+  /** この言語である確からしさ。0..1。 */
+  readonly detect: (source: string) => number;
+  readonly segment: (text: string) => Segmentation;
+  /** L2 rule が word_list で引く。アダプタが自分の言語のぶんだけを持つ。 */
+  readonly lexicons: Readonly<Record<string, Lexicon>>;
+};
+
+// ───────── 文書モデルと rule ─────────
+
+export type Section = {
+  /** 見出しの深さ。見出しより前の導入部は 0。 */
+  readonly depth: number;
+  readonly heading: string;
+  readonly span: Span;
+  readonly sentences: readonly Sentence[];
+  /** この節に含まれる強調（Markdown の ** **）の数。 */
+  readonly strongCount: number;
+  /** 見出し直後の最初の文。heading-echo が見る。 */
+  readonly firstSentence: Sentence | undefined;
+};
+
+/**
+ * detector に渡る唯一の入り口。core が I/O を済ませてから呼ぶ。
+ * detector は純関数で、fs / network / clock に触れない。spec §6。
+ */
+export type ProseDocument = {
+  readonly path: string;
+  readonly source: string;
+  readonly language: string;
+  readonly lengthUnit: LengthUnit;
+  readonly sections: readonly Section[];
+  readonly sentences: readonly Sentence[];
+  /** アダプタが持つ語彙表。detector は言語を知らずにこれを引く。 */
+  readonly lexicons: Readonly<Record<string, Lexicon>>;
+};
+
+export type Severity = "error" | "warning" | "info";
+
+export type Finding = {
+  readonly rule: string;
+  readonly severity: Severity;
+  readonly line: number;
+  readonly column: number;
+  /** 引用して見せる範囲。非エンジニア向け出力が使う。 */
+  readonly quote: string;
+  /** message のプレースホルダに入れる値。 */
+  readonly values: Readonly<Record<string, string | number>>;
+};
+
+/** rule 定義が threshold を渡す。数値は 4 語から解決済み。 */
+export type DetectorOptions = {
+  readonly limit: number;
+  /** L2 のみ。rule 定義の word_list から解決した語彙表。 */
+  readonly lexicon?: Lexicon | undefined;
+  /** 見る範囲。opening は冒頭 2 段落、closing は最後の節、whole は全体。 */
+  readonly where?: string | undefined;
+};
+
+export type Detector = (doc: ProseDocument, options: DetectorOptions) => Finding[];
+
+export type Localized = Readonly<Record<string, string>>;
+
+export type Level = "strict" | "normal" | "relaxed" | "off";
+
+export type LevelTable = Readonly<Partial<Record<Exclude<Level, "off">, number>>>;
+
+export type RuleDefinition = {
+  readonly id: string;
+  readonly layer: "L1" | "L2" | "L3" | "L4";
+  readonly status: "experimental" | "stable" | "deprecated";
+  readonly name: Localized;
+  readonly why: Localized;
+  readonly how_to_fix: Localized;
+  readonly message: Localized;
+  /** 4 語と数値の対応。2 つ以上。未定義の段は normal に落ちる。spec §18.1。
+   *  言語別の閾値を持つ rule（max-sentence-length）は、読み込み時に言語で平坦化済み。 */
+  readonly levels: LevelTable;
+  readonly how_to_find: string;
+  readonly word_list: string | undefined;
+  readonly where: string | undefined;
+  readonly use_for: readonly string[];
+  readonly severity: Severity;
+};

package/src/position.ts

@@ -0,0 +1,9 @@
+export type Place = { readonly line: number; readonly column: number };
+
+/** 行頭のオフセット表。1 文書につき 1 度だけ作る。 */
+export const lineStarts = (source: string): number[] => [...source].reduce<number[]>((acc, char, index) => (char === "\n" ? [...acc, index + 1] : acc), [0]);
+
+export const placeOf = (starts: readonly number[], offset: number): Place => {
+  const index = starts.reduce((best, start, at) => (start <= offset ? at : best), 0);
+  return { line: index + 1, column: offset - (starts[index] ?? 0) + 1 };
+};

package/src/render/compact.ts

@@ -0,0 +1,18 @@
+import type { RuleDefinition } from "../plugin.ts";
+import type { RunResult } from "../run.ts";
+import { messageOf } from "./text.ts";
+
+/** エンジニア向け。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 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 tail = [`${result.findings.length} findings`, result.skipped.length > 0 ? `${result.skipped.length} rules not run` : undefined].filter(
+    (part) => part !== undefined,
+  );
+  return ["", header, "", ...lines, "", tail.join(", "), ""].join("\n");
+};

package/src/render/explain.ts

@@ -0,0 +1,31 @@
+import { definedLevels, resolve } from "../levels.ts";
+import { localized } from "./text.ts";
+import type { Level, RuleDefinition } from "../plugin.ts";
+
+const levelLine = (rule: RuleDefinition, level: Level, current: Level): string => {
+  const mark = level === current ? "\u2192" : " ";
+  const name = level.padEnd(9);
+  return level === "off" ? `  ${mark} ${name}見ない` : `  ${mark} ${name}${resolve(rule, level).limit}`;
+};
+
+/** rule の意図と根拠を読む。指摘に納得できないときの入口。 */
+export const renderExplain = (rule: RuleDefinition, current: Level, language: string, unit: string): string => {
+  const experimental = rule.status === "experimental" ? ["  このルールはまだ試験中で、既定では動きません（--experimental で動きます）。"] : [];
+  return [
+    "",
+    `  ${localized(rule.name, language)}   (${rule.id})`,
+    "",
+    `  ${localized(rule.why, language)}`,
+    "",
+    `  直しかた: ${localized(rule.how_to_fix, language)}`,
+    "",
+    `  設定できる値（単位: ${unit}）:`,
+    ...definedLevels(rule).map((level) => levelLine(rule, level, current)),
+    "",
+    `  いまは ${current} です。`,
+    ...experimental,
+    "",
+    `  変える:  npx chaff relax ${rule.id} --why "理由"`,
+    "",
+  ].join("\n");
+};

package/src/render/friendly.ts

@@ -0,0 +1,62 @@
+import type { Finding, RuleDefinition } from "../plugin.ts";
+import type { RunResult } from "../run.ts";
+import { MARK, localized, messageOf } from "./text.ts";
+import { tally } from "./summary.ts";
+
+const RULE = 60;
+const QUOTE_LIMIT = 120;
+
+const indent = (text: string, pad: string): string[] => text.split("\n").map((line) => `${pad}${line}`);
+
+const quoteOf = (finding: Finding): string[] => {
+  const text = finding.quote.replace(/\s+/gu, " ").trim();
+  if (text.length === 0) return [];
+  return ["", ...indent(text.length > QUOTE_LIMIT ? `${text.slice(0, QUOTE_LIMIT)}…` : text, "    ")];
+};
+
+/**
+ * 1 件につき 4 つを出す。どれが欠けても、書いた人は動けない。
+ *   引用 / 何が起きているか / なぜ問題か / どう直すか
+ * rule の id は「ゆるめる」コマンドの中にだけ出す。最初に読むのは name。
+ */
+const block = (finding: Finding, rule: RuleDefinition, language: string): string[] => [
+  "",
+  `─── ${finding.line} 行目 ${"─".repeat(Math.max(0, RULE - String(finding.line).length - 8))}`,
+  ...quoteOf(finding),
+  "",
+  `  ${MARK[finding.severity] ?? "·"}  ${localized(rule.name, language)}`,
+  "",
+  ...indent(messageOf(rule, finding, language), "     "),
+  ...indent(localized(rule.why, language), "     "),
+  "",
+  ...indent(`→ ${localized(rule.how_to_fix, language)}`, "     "),
+  "",
+  `     このルールをゆるめる:  npx chaff relax ${finding.rule}`,
+  "",
+];
+
+export const renderFriendly = (header: string, result: RunResult, rules: readonly RuleDefinition[], language: string): string => {
+  const byId = new Map(rules.map((rule) => [rule.id, rule]));
+  const blocks = result.findings.flatMap((finding) => {
+    const rule = byId.get(finding.rule);
+    return rule === undefined ? [] : block(finding, rule, language);
+  });
+  const notes = [
+    "",
+    "─".repeat(RULE),
+    "",
+    `  ${tally(result.findings)}   すべて機械による判定です`,
+    "              （同じ文章なら何度実行しても同じ結果になります）",
+    "",
+    "  文章は書き換えていません。直すのは書いた人です。",
+  ];
+  const forced =
+    result.forcedExperimental.length > 0
+      ? ["", `  試験中の rule を ${result.forcedExperimental.length} 件、設定により有効にしています: ${result.forcedExperimental.join(", ")}`]
+      : [];
+  const skipped =
+    result.skipped.length > 0
+      ? ["", `  ${result.skipped.length} 件の rule は動いていません:`, ...result.skipped.map((entry) => `      ${entry.rule}（${entry.why}）`)]
+      : [];
+  return ["", header, ...blocks, ...notes, ...forced, ...skipped, ""].join("\n");
+};

package/src/render/rules-json.ts

@@ -0,0 +1,46 @@
+import { definedLevels, resolve } from "../levels.ts";
+import type { Config } from "../config/load.ts";
+import type { Level, RuleDefinition } from "../plugin.ts";
+
+const now = (rule: RuleDefinition, config: Config): Record<string, unknown> => {
+  const explicit = config.rules[rule.id];
+  if (explicit === "off") return { level: "off", why_off: "設定で止めている" };
+  if (explicit !== undefined) return { level: explicit, limit: resolve(rule, explicit).limit };
+  if (rule.status === "experimental" && !config.experimental) {
+    return { level: "off", why_off: "experimental な rule は既定で動かさない", turn_on_with: `npx chaff lint --experimental` };
+  }
+  return { level: "normal", limit: resolve(rule, "normal").limit };
+};
+
+/** AI に設定を書かせるときの入口。推測せずに書けるだけの情報を 1 つに入れる。spec §19.3。 */
+export const rulesJson = (rules: readonly RuleDefinition[], config: Config, language: string, genre: string): string =>
+  JSON.stringify(
+    {
+      schema_version: 1,
+      config_file: "chaff.yaml",
+      detected: { genre, language },
+      values_you_can_use: ["strict", "normal", "relaxed", "off"],
+      values_note: "この 4 語のかわりに数字を直接書いてもよい。4 語のほうを勧める。",
+      rules: rules.map((rule) => ({
+        id: rule.id,
+        layer: rule.layer,
+        status: rule.status,
+        name: rule.name,
+        why: rule.why,
+        how_to_fix: rule.how_to_fix,
+        use_for: rule.use_for,
+        levels: rule.levels,
+        levels_you_can_set: definedLevels(rule),
+        your_setting: config.rules[rule.id] === undefined ? null : { level: config.rules[rule.id], from: config.path },
+        now: now(rule, config),
+      })),
+      how_to_change: {
+        by_command: ['npx chaff relax <rule-id> --why "<理由>"', 'npx chaff strict <rule-id> --why "<理由>"', 'npx chaff off <rule-id> --why "<理由>"'],
+        by_file: "chaff.yaml の rules に <rule-id>: <level> を足す。既定のままのものは書かない。",
+      },
+    },
+    null,
+    2,
+  );
+
+export const levelsForCli = (): readonly Level[] => ["strict", "normal", "relaxed", "off"];

package/src/render/summary.ts

@@ -0,0 +1,22 @@
+import type { Finding } from "../plugin.ts";
+
+export type FileOutcome = { readonly path: string; readonly findings: readonly Finding[]; readonly notRun: number };
+
+const count = (findings: readonly Finding[], severity: string): number => findings.filter((finding) => finding.severity === severity).length;
+
+export const tally = (findings: readonly Finding[]): string => {
+  const parts = [
+    count(findings, "error") > 0 ? `エラー ${count(findings, "error")} 件` : undefined,
+    count(findings, "warning") > 0 ? `注意 ${count(findings, "warning")} 件` : undefined,
+    count(findings, "info") > 0 ? `参考 ${count(findings, "info")} 件` : undefined,
+  ].filter((part) => part !== undefined);
+  return parts.length === 0 ? "指摘はありません" : parts.join("、");
+};
+
+/** 複数ファイルを見たときの締め。1 ファイルのときは出さない。 */
+export const renderSummary = (outcomes: readonly FileOutcome[]): string[] => {
+  if (outcomes.length < 2) return [];
+  const all = outcomes.flatMap((outcome) => outcome.findings);
+  const touched = outcomes.filter((outcome) => outcome.findings.length > 0).length;
+  return ["", "═".repeat(60), "", `  ${outcomes.length} ファイルを見て、${touched} ファイルに指摘がありました`, `  ${tally(all)}`, ""];
+};

package/src/render/suppressions.ts

@@ -0,0 +1,57 @@
+import type { Suppressed, Suppression } from "../stet.ts";
+
+export type PerFile = { readonly path: string; readonly suppressed: readonly Suppressed[]; readonly reasonless: readonly Suppression[] };
+
+/** これを超えたら、その rule は (b) ではなく (c) にすべきというサイン。 */
+const NUDGE_AT = 5;
+
+type Group = { readonly rule: string; readonly count: number; readonly files: readonly string[]; readonly reasons: readonly string[] };
+
+const groupByRule = (files: readonly PerFile[]): Group[] => {
+  const rows = files.flatMap((file) => file.suppressed.map((entry) => ({ path: file.path, rule: entry.finding.rule, reason: entry.suppression.reason })));
+  const ids = [...new Set(rows.map((row) => row.rule))];
+  return ids
+    .map((rule) => {
+      const mine = rows.filter((row) => row.rule === rule);
+      return {
+        rule,
+        count: mine.length,
+        files: [...new Set(mine.map((row) => row.path))],
+        reasons: [...new Set(mine.flatMap((row) => (row.reason === undefined ? [] : [row.reason])))],
+      };
+    })
+    .sort((left, right) => right.count - left.count);
+};
+
+const groupLines = (group: Group): string[] => {
+  const nudge = group.count >= NUDGE_AT ? "  ← 設定の見直しを検討してください" : "";
+  const shown = group.files.slice(0, 3).join(", ");
+  const rest = group.files.length > 3 ? ` ほか ${group.files.length - 3} ファイル` : "";
+  return [
+    "",
+    `  ${group.rule.padEnd(26)}${String(group.count).padStart(3)} 件${nudge}`,
+    `      ${shown}${rest}`,
+    ...(group.count >= NUDGE_AT && group.reasons.length > 0
+      ? [`      理由: ${group.reasons.slice(0, 2).join(" / ")}`, `      ルールごとゆるめる: npx chaff relax ${group.rule} --why "..."`]
+      : []),
+  ];
+};
+
+/**
+ * 抑制が溜まったことに気づけないと、規範と現実の乖離が静かに進む。
+ * 同じ rule を何度も黙らせているなら、それは (b) ではなく (c) のサイン。
+ * workflow spec §7.3。
+ */
+export const renderSuppressions = (files: readonly PerFile[]): string => {
+  const groups = groupByRule(files);
+  const total = groups.reduce((sum, group) => sum + group.count, 0);
+  if (total === 0) return "\n  抑制されている指摘はありません。\n";
+  const reasonless = files.flatMap((file) => file.reasonless.map(() => file.path));
+  return [
+    "",
+    `  抑制されている指摘: ${total} 件`,
+    ...groups.flatMap(groupLines),
+    ...(reasonless.length > 0 ? ["", `  理由が書かれていない抑制: ${reasonless.length} 件`, `      ${[...new Set(reasonless)].join(", ")}`] : []),
+    "",
+  ].join("\n");
+};

package/src/render/text.ts

@@ -0,0 +1,13 @@
+import type { Finding, Localized, RuleDefinition } from "../plugin.ts";
+
+export const localized = (field: Localized, language: string): string => field[language] ?? field["en"] ?? Object.values(field)[0] ?? "";
+
+export const fill = (template: string, values: Readonly<Record<string, string | number>>): string =>
+  template.replace(/\{(\w+)\}/gu, (whole, key: string) => {
+    const value = values[key];
+    return value === undefined ? whole : String(value);
+  });
+
+export const messageOf = (rule: RuleDefinition, finding: Finding, language: string): string => fill(localized(rule.message, language), finding.values);
+
+export const MARK: Readonly<Record<string, string>> = { error: "✖", warning: "⚠", info: "·" };

package/src/rule-load.ts

@@ -0,0 +1,78 @@
+import { readFileSync, readdirSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+import { parse } from "yaml";
+import type { LevelTable, RuleDefinition, Severity } from "./plugin.ts";
+
+const RULES_DIR = join(dirname(fileURLToPath(import.meta.url)), "..", "rules");
+
+const isRecord = (value: unknown): value is Record<string, unknown> => typeof value === "object" && value !== null && !Array.isArray(value);
+
+const isLocalized = (value: unknown): value is Record<string, string> => isRecord(value) && Object.values(value).every((entry) => typeof entry === "string");
+
+const isLevelTable = (value: unknown): value is LevelTable =>
+  isRecord(value) && Object.entries(value).every(([key, entry]) => ["strict", "normal", "relaxed"].includes(key) && typeof entry === "number");
+
+/** 言語別の levels を、その言語のぶんだけに平坦化する。単位が言語で違う rule のため。 */
+const flattenLevels = (raw: unknown, language: string): LevelTable | undefined => {
+  if (isLevelTable(raw)) return raw;
+  if (!isRecord(raw)) return undefined;
+  const forLanguage = raw[language] ?? raw["default"];
+  return isLevelTable(forLanguage) ? forLanguage : undefined;
+};
+
+const SEVERITIES: readonly Severity[] = ["error", "warning", "info"];
+const isSeverity = (value: unknown): value is Severity => SEVERITIES.some((entry) => entry === value);
+
+const LAYERS = ["L1", "L2", "L3", "L4"] as const;
+const STATUSES = ["experimental", "stable", "deprecated"] as const;
+
+const pick = <T>(value: unknown, allowed: readonly T[]): T | undefined => allowed.find((entry) => entry === value);
+
+/**
+ * 必須フィールドが欠けた rule は読み込まない。spec §18.2。
+ * message だけでは、非エンジニアは何が悪いのか分からない。why と how_to_fix を必須にする。
+ */
+const REQUIRED_TEXT = ["name", "why", "how_to_fix", "message"] as const;
+
+const missingFields = (raw: Record<string, unknown>, levels: LevelTable | undefined): string[] => [
+  ...(typeof raw["id"] === "string" ? [] : ["id"]),
+  ...(pick(raw["layer"], LAYERS) === undefined ? ["layer"] : []),
+  ...(pick(raw["status"], STATUSES) === undefined ? ["status"] : []),
+  ...REQUIRED_TEXT.filter((field) => !isLocalized(raw[field])),
+  ...(levels?.normal === undefined ? ["levels.normal"] : []),
+  ...(typeof raw["how_to_find"] === "string" ? [] : ["how_to_find"]),
+  ...(Array.isArray(raw["use_for"]) ? [] : ["use_for"]),
+  ...(isSeverity(raw["severity"]) ? [] : ["severity"]),
+];
+
+const localizedOf = (value: unknown): Record<string, string> => (isLocalized(value) ? value : {});
+
+const toRule = (raw: unknown, language: string, file: string): RuleDefinition => {
+  if (!isRecord(raw)) throw new Error(`${file}: rule は object であること`);
+  const levels = flattenLevels(raw["levels"], language);
+  const missing = missingFields(raw, levels);
+  if (missing.length > 0) throw new Error(`${file}: 必須フィールドがありません: ${missing.join(", ")}`);
+  if (levels === undefined) throw new Error(`${file}: levels を解決できません`);
+  return {
+    id: String(raw["id"]),
+    layer: pick(raw["layer"], LAYERS) ?? "L1",
+    status: pick(raw["status"], STATUSES) ?? "experimental",
+    name: localizedOf(raw["name"]),
+    why: localizedOf(raw["why"]),
+    how_to_fix: localizedOf(raw["how_to_fix"]),
+    message: localizedOf(raw["message"]),
+    levels,
+    how_to_find: String(raw["how_to_find"]),
+    word_list: typeof raw["word_list"] === "string" ? raw["word_list"] : undefined,
+    where: typeof raw["where"] === "string" ? raw["where"] : undefined,
+    use_for: Array.isArray(raw["use_for"]) ? raw["use_for"].map((entry) => String(entry)) : [],
+    severity: isSeverity(raw["severity"]) ? raw["severity"] : "warning",
+  };
+};
+
+export const loadRules = (language: string, dir: string = RULES_DIR): RuleDefinition[] =>
+  readdirSync(dir)
+    .filter((file) => file.endsWith(".yaml"))
+    .sort((left, right) => left.localeCompare(right, "en"))
+    .map((file) => toRule(parse(readFileSync(join(dir, file), "utf8")), language, file));

package/src/run.ts

@@ -0,0 +1,61 @@
+import { DETECTORS } from "./detectors/index.ts";
+import { resolve } from "./levels.ts";
+import type { Finding, Level, ProseDocument, RuleDefinition } from "./plugin.ts";
+import { lineStarts, placeOf } from "./position.ts";
+
+export type Skipped = { readonly rule: string; readonly why: string };
+
+export type RunResult = {
+  readonly findings: readonly Finding[];
+  readonly skipped: readonly Skipped[];
+  /** 設定で明示的に有効にした experimental な rule。実行ごとに一度報告する。spec §18.4。 */
+  readonly forcedExperimental: readonly string[];
+};
+
+export type Settings = Readonly<Record<string, Level>>;
+
+const levelFor = (rule: RuleDefinition, settings: Settings, experimental: boolean): Level => {
+  const explicit = settings[rule.id];
+  // 明示設定は status の既定に勝つ。名指しで有効にしたものを黙って無効にしない。
+  if (explicit !== undefined) return explicit;
+  if (rule.status === "experimental" && !experimental) return "off";
+  return "normal";
+};
+
+const place = (starts: readonly number[], finding: Finding): Finding => {
+  const offset = finding.values["offset"];
+  const at = placeOf(starts, typeof offset === "number" ? offset : 0);
+  return { ...finding, line: at.line, column: at.column };
+};
+
+export const runRules = (doc: ProseDocument, rules: readonly RuleDefinition[], settings: Settings, experimental: boolean, genre: string): RunResult => {
+  const starts = lineStarts(doc.source);
+  const applicable = rules.filter((rule) => rule.use_for.some((target) => genre.startsWith(target)));
+  const forced = applicable
+    .filter((rule) => rule.status === "experimental" && settings[rule.id] !== undefined && settings[rule.id] !== "off")
+    .map((rule) => rule.id);
+  const outcome = applicable.reduce<{ findings: Finding[]; skipped: Skipped[] }>(
+    (acc, rule) => {
+      const level = levelFor(rule, settings, experimental);
+      if (level === "off") {
+        const why = rule.status === "experimental" && settings[rule.id] === undefined ? "まだ試験中のため" : "設定で止めているため";
+        return { findings: acc.findings, skipped: [...acc.skipped, { rule: rule.id, why }] };
+      }
+      const detector = DETECTORS[rule.how_to_find];
+      if (detector === undefined) return { findings: acc.findings, skipped: [...acc.skipped, { rule: rule.id, why: `検出器 ${rule.how_to_find} がないため` }] };
+      const options = {
+        limit: resolve(rule, level).limit,
+        lexicon: rule.word_list === undefined ? undefined : doc.lexicons[rule.word_list],
+        where: rule.where,
+      };
+      // 語彙表を要求する rule で、その言語に語彙表が無ければ動かせない。黙って通さない。
+      if (rule.word_list !== undefined && options.lexicon === undefined) {
+        return { findings: acc.findings, skipped: [...acc.skipped, { rule: rule.id, why: `${doc.language} の語彙表 ${rule.word_list} が無いため` }] };
+      }
+      const found = detector(doc, options).map((finding) => place(starts, { ...finding, rule: rule.id, severity: rule.severity }));
+      return { findings: [...acc.findings, ...found], skipped: acc.skipped };
+    },
+    { findings: [], skipped: [] },
+  );
+  return { ...outcome, findings: [...outcome.findings].sort((left, right) => left.line - right.line), forcedExperimental: forced };
+};

package/src/stet.ts

@@ -0,0 +1,79 @@
+import type { Finding, Span } from "./plugin.ts";
+
+export type Suppression = {
+  readonly rules: readonly string[];
+  readonly reason: string | undefined;
+  readonly line: number;
+  readonly scope: "next" | "section" | "file";
+};
+
+/**
+ * 校正記号 stet（ラテン語で「そのままにせよ」）。
+ * 指摘は一般には正しいが、この箇所は意図的だ、と書く手段。
+ * これが無いと、残された手は「ルールごと切る」しかなくなる。workflow spec §7.1。
+ *
+ * 中身の切り分けは正規表現でやらない。入れ子の量指定子はバックトラックが超線形になり、
+ * 長い HTML コメントを 1 つ置かれるだけで検査が止まる。ここは ">" を含まない塊として
+ * 取り出し、あとはコードで割る。
+ */
+const PATTERN = /<!--\s*(stet|stet-section|stet-file)\s*:([^>]*)-->/gu;
+
+const SCOPE: Readonly<Record<string, Suppression["scope"]>> = { stet: "next", "stet-section": "section", "stet-file": "file" };
+
+/** 理由は em dash のあと。書かなくてもよいが、書かないと chaff suppressions に並ぶ。 */
+const REASON_MARK = "\u2014";
+
+const RULE_ID = /^[a-z][a-z0-9-]*$/u;
+
+const lineOf = (source: string, offset: number): number => source.slice(0, offset).split("\n").length;
+
+const splitBody = (body: string): { rules: string[]; reason: string | undefined } => {
+  const at = body.indexOf(REASON_MARK);
+  const head = at === -1 ? body : body.slice(0, at);
+  // 残っているのはコメント終端の "--" だけ。正規表現で任意個の "-" を剥がすと、
+  // 長いダッシュ列でバックトラックする（そして著者が書いたダッシュまで消す）。
+  const raw = at === -1 ? "" : body.slice(at + REASON_MARK.length);
+  const tail = (raw.endsWith("--") ? raw.slice(0, -2) : raw).trim();
+  return {
+    rules: head
+      .split(",")
+      .map((rule) => rule.trim())
+      .filter((rule) => RULE_ID.test(rule)),
+    reason: tail.length === 0 ? undefined : tail,
+  };
+};
+
+export const parseSuppressions = (source: string): Suppression[] =>
+  [...source.matchAll(PATTERN)].map((match) => ({
+    ...splitBody(match[2] ?? ""),
+    line: lineOf(source, match.index),
+    scope: SCOPE[match[1] ?? "stet"] ?? "next",
+  }));
+
+/** stet が効く範囲。next は直後の塊、section は次の見出しまで、file は全体。 */
+const NEXT_LINES = 6;
+
+const covers = (suppression: Suppression, finding: Finding, sectionEnds: readonly number[], lastLine: number): boolean => {
+  if (!suppression.rules.includes(finding.rule)) return false;
+  if (suppression.scope === "file") return true;
+  // 抑制は「この先の箇所」に対して書く。遡って効くと、意図せず黙る範囲が広がる。
+  if (finding.line < suppression.line) return false;
+  if (suppression.scope === "next") return finding.line - suppression.line <= NEXT_LINES;
+  return finding.line <= (sectionEnds.find((line) => line > suppression.line) ?? lastLine);
+};
+
+export type Suppressed = { readonly finding: Finding; readonly suppression: Suppression };
+
+export type Applied = { readonly kept: readonly Finding[]; readonly suppressed: readonly Suppressed[]; readonly unusedReasonless: readonly Suppression[] };
+
+export const applySuppressions = (source: string, findings: readonly Finding[], sections: readonly Span[]): Applied => {
+  const suppressions = parseSuppressions(source);
+  const sectionEnds = sections.map((span) => lineOf(source, span.end));
+  const lastLine = source.split("\n").length;
+  const matched = findings.map((finding) => ({ finding, suppression: suppressions.find((entry) => covers(entry, finding, sectionEnds, lastLine)) }));
+  return {
+    kept: matched.filter((entry) => entry.suppression === undefined).map((entry) => entry.finding),
+    suppressed: matched.flatMap((entry) => (entry.suppression === undefined ? [] : [{ finding: entry.finding, suppression: entry.suppression }])),
+    unusedReasonless: suppressions.filter((entry) => entry.reason === undefined),
+  };
+};