chaffjs 0.19.0 → 0.21.0

package/src/outline/structure-render.ts

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

package/src/outline/structure-text.ts

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

package/src/outline/text.ts

@@ -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,14 @@ 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;
+};
+
+/** A plugin's word list is named <plugin>/<list> (@scope/foo/list too); a language package's has no slash. */
+const pluginListOf = (list: string): { readonly plugin: string; readonly name: string } | undefined => {
+  const slash = list.lastIndexOf("/");
+  return slash === -1 ? undefined : { plugin: list.slice(0, slash), name: list.slice(slash + 1) };
 };
 
 const CAPABILITY_NAME: Texts<Readonly<Record<string, string>>> = {
@@ -31,7 +39,7 @@ export const REASONS: Texts<Reasons> = {
     noCapability: (capability) => `この言語では${CAPABILITY_NAME.ja[capability] ?? capability}が使えないため`,
     noTags: "アダプタが品詞を返さなかったため",
     unreadTags: "言語のパッケージがこの文書を読めなかったため（品詞の取れない段落があります）",
-    semantic: "意味を読む検査のため（npx chaff test で動きます）",
+    semantic: "意味を読む検査のため（npx chaffjs test で動きます）",
     experimental: "まだ試験中のため",
     turnedOff: "設定で止めているため",
     presetOff: (genre) => `ジャンル ${genre} では見ないため`,
@@ -39,17 +47,21 @@ export const REASONS: Texts<Reasons> = {
     unreadStructure: (clauses, units) =>
       `条項の番号が本文に ${String(clauses)} 個あるのに、番号として読めたのは ${String(units)} 個のため（深い字下げや、行が本文につながった文書）`,
     noDetector: (name) => `検出器 ${name} がないため`,
-    noLexicon: (language, list) => `${language} の語彙表 ${list} が無いため`,
+    noLexicon: (language, list) => {
+      const owner = pluginListOf(list);
+      return owner === undefined ? `${language} の語彙表 ${list} が無いため` : `プラグイン ${owner.plugin} に ${language} の語彙表 ${owner.name} が無いため`;
+    },
     noHeadings: "表題より下の見出しが無いため",
     patternTimeout: (budgetMs) => `正規表現が ${String(budgetMs)} ms で終わらなかったため（chaff.yaml の pattern を単純にしてください）`,
     notMarkdown: "Markdown の文書ではないため",
+    oneDocument: "比べるほかの文書が無いため（ファイルを二つ以上かフォルダを渡すと動きます）",
   },
   en: {
     otherLanguage: (language) => `not a rule for ${language}`,
     noCapability: (capability) => `${CAPABILITY_NAME.en[capability] ?? capability} is not available for this language`,
     noTags: "the language package returned no parts of speech",
     unreadTags: "the language package could not read this document (some paragraphs have no parts of speech)",
-    semantic: "it reads meaning; npx chaff test runs it",
+    semantic: "it reads meaning; npx chaffjs test runs it",
     experimental: "still experimental",
     turnedOff: "turned off in the settings",
     presetOff: (genre) => `the ${genre} genre does not check it`,
@@ -57,9 +69,13 @@ export const REASONS: Texts<Reasons> = {
     unreadStructure: (clauses, units) =>
       `the text has ${String(clauses)} clause numbers but only ${String(units)} ${formFor(units, "was read as a numbered line", "were read as numbered lines")} (deep indents, or lines run into the text)`,
     noDetector: (name) => `no detector named ${name}`,
-    noLexicon: (language, list) => `the ${language} package has no word list ${list}`,
+    noLexicon: (language, list) => {
+      const owner = pluginListOf(list);
+      return owner === undefined ? `the ${language} package has no word list ${list}` : `the plugin ${owner.plugin} has no ${language} word list ${owner.name}`;
+    },
     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

@@ -5,13 +5,16 @@ 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";
+import { depthMeaning } from "../rewrite-depth.ts";
 
 const TEXT: Texts<{
   readonly off: string;
   readonly defaultGenre: string;
   readonly genreNote: (genre: string, others: string) => string;
   readonly experimental: string;
+  readonly alone: (id: string) => string;
   readonly howToFix: string;
+  readonly depth: (depth: string, meaning: string) => string;
   readonly example: string;
   readonly definedIn: (plugin: string | undefined) => string;
   readonly values: string;
@@ -27,7 +30,10 @@ const TEXT: Texts<{
     defaultGenre: "既定",
     genreNote: (genre, others) => `この数字は ${genre} のものです。ほかに ${others} で別の数字を持っています。`,
     experimental: "このルールはまだ試験中で、既定では動きません（--experimental で動きます）。",
+    alone: (id) => `このルールだけを動かす:  npx chaffjs enable ${id}（chaff.yaml の rules に ${id}: normal と書くのと同じです）`,
     howToFix: "直しかた",
+    depth: (depth, meaning) =>
+      `書き直しの深さ: ${depth}（${meaning}）。chaff fix-plan --depth でこれより浅い深さを選ぶと、計画はこのルールを直さず、名前だけを挙げます。`,
     example: "例",
     definedIn: (plugin) =>
       plugin === undefined ? "このルールはチームが chaff.yaml の custom_rules で決めたものです。" : `このルールはプラグイン ${plugin} のものです。`,
@@ -37,14 +43,16 @@ const TEXT: Texts<{
     now: (level) => `いまは ${level} です。`,
     nowNumber: (limit) => `いまは段階ではなく数です: ${limit}。`,
     from: (source) => `（${source} で決めています）`,
-    change: (id) => `変える:  npx chaff relax ${id} --why "理由"`,
+    change: (id) => `変える:  npx chaffjs relax ${id} --why "理由"`,
   },
   en: {
     off: "not checked",
     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",
+    depth: (depth, meaning) => `Rewrite depth: ${depth} (${meaning}). With a shallower chaff fix-plan --depth, the plan names this rule without fixing it.`,
     example: "Example",
     definedIn: (plugin) =>
       plugin === undefined ? "The team defined this rule under custom_rules in chaff.yaml." : `This rule comes from the plugin ${plugin}.`,
@@ -54,7 +62,7 @@ const TEXT: Texts<{
     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"`,
+    change: (id) => `Change it:  npx chaffjs relax ${id} --why "reason"`,
   },
 };
 
@@ -95,12 +103,20 @@ const exampleLines = (rule: RuleDefinition, language: string, text: (typeof TEXT
   return ["", `  ${text.example}:  ${example.before}`, `      →  ${example.after}`, "", `  ${text.definedIn(rule.plugin)}`];
 };
 
+/** How deep the rule's rewrite direction reaches, for a rule that has one: what chaff fix-plan --depth compares. */
+const depthLines = (rule: RuleDefinition, language: string, text: (typeof TEXT)["ja"]): string[] => {
+  const depth = rule.guide?.rewriteDepth;
+  return depth === undefined ? [] : ["", `  ${text.depth(depth, depthMeaning(depth, uiLanguageOf(language)))}`];
+};
+
 /** Where the rule's settings come from: the option layers, strongest first, and the source of its level when a style set it. */
 /** 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 の意図と根拠を読む。指摘に納得できないときの入口。 */
@@ -110,7 +126,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})`,
@@ -118,6 +135,7 @@ export const renderExplain = (rule: RuleDefinition, current: Level, language: st
     `  ${readableText(rule, rule.why, language)}`,
     "",
     `  ${text.howToFix}: ${readableText(rule, rule.how_to_fix, language)}`,
+    ...depthLines(rule, language, text),
     ...exampleLines(rule, language, text),
     "",
     `  ${rule.level_sets === "severity" ? text.severities : text.values}`,

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}`);
@@ -79,7 +90,7 @@ const block = (finding: Finding, rule: RuleDefinition, language: string, quoted:
   "",
   ...indent(`→ ${filledText(rule.how_to_fix, finding, language)}`, "     "),
   "",
-  `     ${TEXT[uiLanguageOf(language)].relax}:  npx chaff relax ${finding.rule}`,
+  `     ${TEXT[uiLanguageOf(language)].relax}:  npx chaffjs relax ${finding.rule}`,
   "",
 ];
 
@@ -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");