chaffjs 0.20.0 → 0.21.0

package/src/custom/checked.ts

@@ -0,0 +1,8 @@
+import type { CustomProblem } from "./parse.ts";
+
+/** One field of one rule, read: its value when it can be used, and what is wrong with it otherwise. */
+export type Checked<T> = { readonly value: T | undefined; readonly problems: readonly CustomProblem[] };
+
+export const ok = <T>(value: T): Checked<T> => ({ value, problems: [] });
+
+export const failed = <T>(...problems: CustomProblem[]): Checked<T> => ({ value: undefined, problems });

package/src/custom/dsl-fields.ts

@@ -0,0 +1,102 @@
+import type { LevelTable, Localized, Severity } from "../plugin.ts";
+import { RULE_GROUPS, ruleGuideOf, type RuleGroup, type RuleGuide } from "../rule-guide.ts";
+import { fieldProblems } from "../rule-fields.ts";
+import { failed, ok, type Checked } from "./checked.ts";
+
+// The fields a team's rule (custom_rules, or a plugin's rules) writes the way chaff's own rules/*.yaml do: levels,
+// use_for, group, summary, the example by language and rewrite. Each is optional; without it the rule reads as a team
+// rule always has. The shared fields are checked by rule-fields.ts, the one place chaff's own rules are checked too. Pure.
+
+const SEVERITIES: readonly Severity[] = ["info", "warning", "error"];
+const LEVEL_NAMES = ["strict", "normal", "relaxed"] as const;
+
+const isRecord = (value: unknown): value is Record<string, unknown> => typeof value === "object" && value !== null && !Array.isArray(value);
+
+const printed = (value: unknown): string => (typeof value === "string" ? value : (JSON.stringify(value) ?? typeof value));
+
+const rankOf = (severity: Severity): number => SEVERITIES.indexOf(severity) + 1;
+
+/** level: one severity; normal is the rule's own, relaxed one lower, strict one higher, where there is one. */
+const tableFor = (severity: Severity): LevelTable => {
+  const rank = rankOf(severity);
+  return { ...(rank < SEVERITIES.length ? { strict: rank + 1 } : {}), normal: rank, ...(rank > 1 ? { relaxed: rank - 1 } : {}) };
+};
+
+const severityAt = (value: unknown): Severity | undefined => SEVERITIES.find((entry) => entry === value);
+
+/**
+ * levels: a severity for each of strict, normal and relaxed, as chaff's rules with nothing to count write them. A
+ * team's detector reports places, not counts, so a number has nothing to be compared with and is refused.
+ */
+const tableOf = (written: unknown): { table: LevelTable; severity: Severity } | undefined => {
+  if (!isRecord(written) || Object.keys(written).some((key) => !LEVEL_NAMES.some((name) => name === key))) return undefined;
+  const ranks = LEVEL_NAMES.flatMap((name) => {
+    const severity = severityAt(written[name]);
+    return severity === undefined ? [] : [[name, rankOf(severity)] as const];
+  });
+  const normal = severityAt(written["normal"]);
+  if (normal === undefined || ranks.length !== Object.keys(written).length) return undefined;
+  return { table: Object.fromEntries(ranks), severity: normal };
+};
+
+export type RuleLevels = { readonly table: LevelTable; readonly severity: Severity };
+
+/** level (one severity, as before) or levels (a severity per level). Not both: they would disagree on normal. */
+export const levelsOf = (raw: Readonly<Record<string, unknown>>, at: string): Checked<RuleLevels> => {
+  const [level, levels] = [raw["level"], raw["levels"]];
+  if (level !== undefined && levels !== undefined) return failed({ kind: "level-and-levels", at });
+  if (levels !== undefined) {
+    const read = tableOf(levels);
+    return read === undefined ? failed({ kind: "bad-levels", at, written: printed(levels) }) : ok(read);
+  }
+  if (level === undefined) return ok({ table: tableFor("warning"), severity: "warning" });
+  const severity = severityAt(level);
+  return severity === undefined ? failed({ kind: "bad-level", at, written: printed(level) }) : ok({ table: tableFor(severity), severity });
+};
+
+/** An example written by language ({ ja: { before, after } }) rather than as { before, after }. */
+const isExampleByLanguage = (example: unknown): example is Record<string, unknown> =>
+  isRecord(example) && Object.keys(example).length > 0 && !("before" in example) && !("after" in example);
+
+/** example's before and after, each by language, whichever form it is written in. */
+export const exampleSides = (example: unknown): { readonly before: unknown; readonly after: unknown } => {
+  if (!isRecord(example)) return { before: undefined, after: undefined };
+  if (!isExampleByLanguage(example)) return { before: example["before"], after: example["after"] };
+  const pairs = Object.entries(example).flatMap(([language, pair]) => (isRecord(pair) ? [[language, pair] as const] : []));
+  return {
+    before: Object.fromEntries(pairs.map(([language, pair]) => [language, pair["before"]])),
+    after: Object.fromEntries(pairs.map(([language, pair]) => [language, pair["after"]])),
+  };
+};
+
+export type Described = Pick<RuleGuide, "rewrite" | "rewriteDepth"> & {
+  readonly group: RuleGroup;
+  /** undefined: the rule's name stands for its summary. */
+  readonly summary: Localized | undefined;
+  /** undefined: every genre, as a team's rule always has. */
+  readonly useFor: readonly string[] | undefined;
+};
+
+const textOf = (value: unknown): Localized | undefined => {
+  if (typeof value === "string") return value.trim() === "" ? undefined : { ja: value.trim(), en: value.trim() };
+  return isRecord(value) ? ruleGuideOf({ summary: value }).summary : undefined;
+};
+
+/**
+ * The fields a team's rule shares with chaff's own, checked in rule-fields.ts. An example written as { before, after }
+ * is left to the caller, which has always read and reported it.
+ */
+export const describedOf = (raw: Readonly<Record<string, unknown>>, at: string, genres: readonly string[]): Checked<Described> => {
+  const shared = { ...raw, example: isExampleByLanguage(raw["example"]) ? raw["example"] : undefined };
+  const problems = fieldProblems(shared, genres).map((problem) => ({ kind: problem.kind, at, written: problem.written }));
+  if (problems.length > 0) return failed(...problems);
+  const { rewrite, rewriteDepth } = ruleGuideOf({ rewrite: raw["rewrite"] });
+  const useFor = raw["use_for"];
+  return ok({
+    group: RULE_GROUPS.find((group) => group === raw["group"]) ?? "team",
+    summary: textOf(raw["summary"]),
+    useFor: Array.isArray(useFor) ? useFor.map((entry) => String(entry)) : undefined,
+    rewrite,
+    rewriteDepth,
+  });
+};

package/src/custom/load.ts

@@ -2,6 +2,7 @@ import type { Config } from "../config/load.ts";
 import type { RuleDefinition } from "../plugin.ts";
 import { loadRules } from "../rule-load.ts";
 import { loadGenres } from "../genre-load.ts";
+import { knownGenres } from "../known-genres.ts";
 import { parseCustomRules, type CustomRules } from "./parse.ts";
 
 /** The team's custom_rules as rules, with what could not be read. A team's rule applies to every genre, like the team's words. */
@@ -9,6 +10,7 @@ export const customRulesOf = (config: Pick<Config, "customRules" | "baseDir">):
   parseCustomRules(config.customRules, {
     builtIn: new Set(loadRules("en").map((rule) => rule.id)),
     useFor: loadGenres().groups.map((group) => group.id),
+    genres: knownGenres(),
     baseDir: config.baseDir,
   });
 

package/src/custom/parse.ts

@@ -1,7 +1,10 @@
-import type { CustomSpec, LevelTable, Localized, RuleDefinition, Severity, TokenCondition } from "../plugin.ts";
+import type { CustomSpec, Localized, RuleDefinition, TokenCondition } from "../plugin.ts";
 import { regexRefusal, type RegexRefusal } from "./regex-safety.ts";
 import { posTags } from "./token-pattern.ts";
 import { modulePathOf, type ModulePathRefusal } from "./module-path.ts";
+import type { FieldProblem } from "../rule-fields.ts";
+import { failed, ok, type Checked } from "./checked.ts";
+import { describedOf, exampleSides, levelsOf, type Described, type RuleLevels } from "./dsl-fields.ts";
 
 // custom_rules in chaff.yaml: a team's own deterministic rules, written without code. Each becomes a RuleDefinition like the
 // built-in ones, so findings, explain, rules --json, stet, the baseline and SARIF treat it the same. Pure: the YAML comes in parsed.
@@ -26,18 +29,25 @@ export type CustomProblem =
   | { readonly kind: "bad-pattern"; readonly at: string; readonly refusal: RegexRefusal }
   | { readonly kind: "no-tokens"; readonly at: string }
   | { readonly kind: "bad-token"; readonly at: string; readonly index: number }
-  | { readonly kind: "unknown-pos"; readonly at: string; readonly written: string };
+  | { readonly kind: "unknown-pos"; readonly at: string; readonly written: string }
+  | { readonly kind: "level-and-levels"; readonly at: string }
+  | { readonly kind: "bad-levels"; readonly at: string; readonly written: string }
+  | (FieldProblem & { readonly at: string });
 
 export type CustomRules = { readonly rules: readonly RuleDefinition[]; readonly problems: readonly CustomProblem[] };
 
 /**
- * What parsing needs to know: the built-in rule ids (a team's rule may not take one), the genres a rule applies to, and
- * the folder a module's path is relative to (where chaff.yaml is).
+ * What parsing needs to know: the built-in rule ids (a team's rule may not take one), the genres a rule applies to when
+ * it does not say (useFor), every genre a use_for may name, and the folder a module's path is relative to (where chaff.yaml is).
  */
-export type CustomContext = { readonly builtIn: ReadonlySet<string>; readonly useFor: readonly string[]; readonly baseDir: string };
+export type CustomContext = {
+  readonly builtIn: ReadonlySet<string>;
+  readonly useFor: readonly string[];
+  readonly genres: readonly string[];
+  readonly baseDir: string;
+};
 
 const RULE_ID = /^[a-z][a-z0-9-]*$/u;
-const SEVERITIES: readonly Severity[] = ["info", "warning", "error"];
 
 const isRecord = (value: unknown): value is Record<string, unknown> => typeof value === "object" && value !== null && !Array.isArray(value);
 
@@ -58,12 +68,6 @@ const EVERY_LANGUAGE = "*";
 
 const exampleSideOf = (value: unknown): Localized | undefined => (nonEmpty(value) ? { [EVERY_LANGUAGE]: value.trim() } : byLanguageOf(value));
 
-/** One rule's own problems, with the rule's id (or its place in the list) as where. */
-type Checked<T> = { readonly value: T | undefined; readonly problems: readonly CustomProblem[] };
-
-const ok = <T>(value: T): Checked<T> => ({ value, problems: [] });
-const failed = <T>(...problems: CustomProblem[]): Checked<T> => ({ value: undefined, problems });
-
 type Pair = { readonly avoid: string; readonly use: string };
 
 /** words as a map (avoid: use) or a list (words to point at, with nothing to use instead). */
@@ -125,7 +129,8 @@ const moduleOf = (raw: Record<string, unknown>, at: string, baseDir: string): Ch
 };
 
 const specOf = (raw: Record<string, unknown>, type: string, at: string, baseDir: string): Checked<CustomSpec> => {
-  if (type === "words") return wordsOf(raw["words"], at);
+  // A words rule may take its words from a word list instead, one per language (a rule pack's lexicons/<language>/).
+  if (type === "words") return takesWordList(raw, type) ? ok({ type: "words", words: [] }) : wordsOf(raw["words"], at);
   if (type === "pattern") return patternOf(raw, at);
   if (type === "module") return moduleOf(raw, at, baseDir);
   return tokensOf(raw["tokens"], at);
@@ -137,28 +142,16 @@ const typeOf = (raw: Record<string, unknown>, at: string): Checked<string> => {
   return CUSTOM_TYPES.some((known) => known === type) ? ok(type) : failed({ kind: "unknown-type", at, written: type });
 };
 
-const severityOf = (raw: unknown, at: string): Checked<Severity> => {
-  if (raw === undefined) return ok("warning");
-  const severity = SEVERITIES.find((entry) => entry === raw);
-  return severity === undefined ? failed({ kind: "bad-level", at, written: typeof raw === "string" ? raw : printed(raw) }) : ok(severity);
-};
-
-/** The four words as severities: normal is the rule's own level, relaxed one lower, strict one higher, where there is one. */
-const levelsFor = (severity: Severity): LevelTable => {
-  const rank = SEVERITIES.indexOf(severity) + 1;
-  return { ...(rank < SEVERITIES.length ? { strict: rank + 1 } : {}), normal: rank, ...(rank > 1 ? { relaxed: rank - 1 } : {}) };
-};
-
 type Texts = { readonly name: Localized; readonly why: Localized; readonly how_to_fix: Localized; readonly before: Localized; readonly after: Localized };
 
 const textsOf = (raw: Record<string, unknown>, at: string): Checked<Texts> => {
-  const example = isRecord(raw["example"]) ? raw["example"] : {};
+  const example = exampleSides(raw["example"]);
   const found = {
     name: localizedOf(raw["name"]),
     why: localizedOf(raw["why"]),
     how_to_fix: localizedOf(raw["how_to_fix"]),
-    before: exampleSideOf(example["before"]),
-    after: exampleSideOf(example["after"]),
+    before: exampleSideOf(example.before),
+    after: exampleSideOf(example.after),
   };
   const missing = Object.entries(found).flatMap(([field, text]) =>
     text === undefined ? [{ kind: "missing" as const, at, field: field === "before" || field === "after" ? `example.${field}` : field }] : [],
@@ -179,9 +172,13 @@ const requiresOf = (raw: unknown, type: string, at: string): Checked<readonly st
   return unknown === undefined ? ok([...new Set(written)]) : failed({ kind: "bad-requires", at, written: unknown });
 };
 
-/** A module's word list by name; its detector gets it as options.lexicon. The other types carry their words themselves. */
-const wordListOf = (raw: unknown, type: string, at: string): Checked<string | undefined> => {
-  if (raw === undefined || type !== "module") return ok(undefined);
+/** A module reads a word list; so does a words rule that writes word_list in place of words. The others carry their words. */
+const takesWordList = (raw: Record<string, unknown>, type: string): boolean =>
+  raw["word_list"] !== undefined && (type === "module" || (type === "words" && raw["words"] === undefined));
+
+/** The word list by name; the detector gets it, in the document's language, as options.lexicon. */
+const wordListOf = (raw: unknown, takesList: boolean, at: string): Checked<string | undefined> => {
+  if (raw === undefined || !takesList) return ok(undefined);
   return nonEmpty(raw) ? ok(raw.trim()) : failed({ kind: "bad-word-list", at, written: printed(raw) });
 };
 
@@ -190,7 +187,7 @@ type Needs = { readonly requires: readonly string[]; readonly wordList: string |
 
 const needsOf = (raw: Record<string, unknown>, type: string, at: string): Checked<Needs> => {
   const requires = requiresOf(raw["requires"], type, at);
-  const wordList = wordListOf(raw["word_list"], type, at);
+  const wordList = wordListOf(raw["word_list"], takesWordList(raw, type), at);
   if (requires.value === undefined || wordList.problems.length > 0) return failed(...requires.problems, ...wordList.problems);
   return ok({ requires: requires.value, wordList: wordList.value });
 };
@@ -226,10 +223,11 @@ type Example = { readonly before: string; readonly after: string };
 type Parts = {
   readonly spec: CustomSpec;
   readonly needs: Needs;
-  readonly severity: Severity;
+  readonly levels: RuleLevels;
   readonly texts: Texts;
   readonly languages: readonly string[] | undefined;
   readonly examples: Readonly<Record<string, Example>>;
+  readonly described: Described;
 };
 
 const READER_LANGUAGES: readonly string[] = ["ja", "en"];
@@ -253,7 +251,7 @@ const definitionOf = (id: string, raw: Record<string, unknown>, parts: Parts, us
   message: localizedOf(raw["message"]) ?? defaultMessage(parts.spec, parts.texts.name),
   messages: {},
   placeholders: PLACEHOLDERS,
-  levels: levelsFor(parts.severity),
+  levels: parts.levels.table,
   level_sets: "severity",
   by_genre: {},
   how_to_find: HOW_TO_FIND[parts.spec.type],
@@ -266,18 +264,19 @@ const definitionOf = (id: string, raw: Record<string, unknown>, parts: Parts, us
   uses: [],
   from: [],
   languages: parts.languages,
-  use_for: useFor,
-  severity: parts.severity,
+  use_for: parts.described.useFor ?? useFor,
+  severity: parts.levels.severity,
   custom: parts.spec,
   // The reference and explain read a rule's plain-language fields from guide; a team's rule is listed with the team's words.
   guide: {
-    group: "team",
-    summary: parts.texts.name,
+    group: parts.described.group,
+    summary: parts.described.summary ?? parts.texts.name,
     examples: parts.examples,
     notFlagged: {},
     levelMeaning: {},
     sources: [],
-    rewrite: {},
+    rewrite: parts.described.rewrite,
+    rewriteDepth: parts.described.rewriteDepth,
   },
 });
 
@@ -289,24 +288,47 @@ const idOf = (raw: Record<string, unknown>, index: number, seen: ReadonlySet<str
   return seen.has(id) ? failed({ kind: "duplicate-id", at }) : ok(id);
 };
 
+/** Each field of one rule, checked. */
+type Checks = {
+  readonly id: Checked<string>;
+  readonly spec: Checked<CustomSpec>;
+  readonly needs: Checked<Needs>;
+  readonly levels: Checked<RuleLevels>;
+  readonly texts: Checked<Texts>;
+  readonly languages: Checked<readonly string[] | undefined>;
+  readonly described: Checked<Described>;
+};
+
+/** The rule's parts once every check passed; undefined when one has no value. */
+const partsOf = (checks: Checks, examples: Readonly<Record<string, Example>>): { readonly id: string; readonly parts: Parts } | undefined => {
+  const { id, spec, needs, levels, texts, described } = checks;
+  if (id.value === undefined || spec.value === undefined || needs.value === undefined) return undefined;
+  if (levels.value === undefined || texts.value === undefined || described.value === undefined) return undefined;
+  const parts = { spec: spec.value, needs: needs.value, levels: levels.value, texts: texts.value, languages: checks.languages.value, examples };
+  return { id: id.value, parts: { ...parts, described: described.value } };
+};
+
 const ruleOf = (raw: unknown, index: number, seen: ReadonlySet<string>, context: CustomContext): Checked<RuleDefinition> => {
   if (!isRecord(raw)) return failed({ kind: "not-a-map", at: `#${String(index + 1)}` });
   const id = idOf(raw, index, seen, context.builtIn);
   const at = id.value ?? (nonEmpty(raw["id"]) ? raw["id"] : `#${String(index + 1)}`);
   const type = typeOf(raw, at);
-  const spec = type.value === undefined ? failed<CustomSpec>() : specOf(raw, type.value, at, context.baseDir);
-  const needs = needsOf(raw, type.value ?? "", at);
-  const severity = severityOf(raw["level"], at);
-  const texts = textsOf(raw, at);
-  const languages = languagesOf(raw["languages"], at);
+  const checks: Checks = {
+    id,
+    spec: type.value === undefined ? failed<CustomSpec>() : specOf(raw, type.value, at, context.baseDir),
+    needs: needsOf(raw, type.value ?? "", at),
+    levels: levelsOf(raw, at),
+    texts: textsOf(raw, at),
+    languages: languagesOf(raw["languages"], at),
+    described: describedOf(raw, at, context.genres),
+  };
+  const { texts, languages } = checks;
   const examples = texts.value === undefined ? {} : examplesOf(texts.value, languages.value);
   const unpaired: CustomProblem[] = texts.value !== undefined && Object.keys(examples).length === 0 ? [{ kind: "unpaired-example", at }] : [];
-  const problems = [...[id, type, spec, needs, severity, texts, languages].flatMap((checked) => checked.problems), ...unpaired];
-  if (problems.length > 0) return failed(...problems);
-  if (id.value === undefined || spec.value === undefined || needs.value === undefined || severity.value === undefined || texts.value === undefined)
-    return failed();
-  const parts = { spec: spec.value, needs: needs.value, severity: severity.value, texts: texts.value, languages: languages.value, examples };
-  return ok(definitionOf(id.value, raw, parts, context.useFor));
+  const ordered: Checked<unknown>[] = [id, type, checks.spec, checks.needs, checks.levels, texts, languages, checks.described];
+  const problems = [...ordered.flatMap((checked) => checked.problems), ...unpaired];
+  const ready = problems.length > 0 ? undefined : partsOf(checks, examples);
+  return ready === undefined ? failed(...problems) : ok(definitionOf(ready.id, raw, ready.parts, context.useFor));
 };
 
 /** custom_rules as written. Every problem is reported; a rule with a problem is left out, and the run is stopped by the caller. */

package/src/custom/problems.ts

@@ -5,10 +5,13 @@ import { customRulesOf } from "./load.ts";
 import { MAX_PATTERN_LENGTH, MAX_REPEATS, type RegexRefusal } from "./regex-safety.ts";
 import { POS_WRITTEN_NAMES } from "./token-pattern.ts";
 import type { ModulePathRefusal } from "./module-path.ts";
+import { fieldProblemSentence, type FieldKind, type FieldProblem } from "../rule-fields.ts";
 
 /** Each problem's sentence, with {at}, {written}, {field}, {index}, {refusal} and {names} filled in from the problem. */
 type Text = {
-  readonly problems: Readonly<Record<CustomProblem["kind"], string>>;
+  readonly problems: Readonly<Record<Exclude<CustomProblem["kind"], FieldKind>, string>>;
+  /** What comes before a shared field's own sentence (rule-fields.ts). */
+  readonly fieldAt: string;
   readonly refusal: Readonly<Record<RegexRefusal, string>>;
   readonly modulePath: Readonly<Record<ModulePathRefusal, string>>;
 };
@@ -45,7 +48,11 @@ const TEXT: Texts<Text> = {
       "bad-token": "{scope} の {at}: tokens の {index} 番目に pos・base・surface のどれもありません",
       "unknown-pos": "{scope} の {at}: 品詞 {written} は知りません（{names}）",
       "bad-pattern": "{scope} の {at}: pattern を使えません。{refusal}",
+      "level-and-levels": "{scope} の {at}: level と levels の両方があります。どちらか一つにしてください",
+      "bad-levels":
+        "{scope} の {at}: levels: {written} は読めません。strict・normal・relaxed に重さ（error / warning / info）を書き、normal は必ず書きます。チームのルールは箇所を出すので、数は書けません",
     },
+    fieldAt: "{scope} の {at}: ",
   },
   en: {
     modulePath: {
@@ -78,7 +85,11 @@ const TEXT: Texts<Text> = {
       "bad-token": "{scope} {at}: token {index} has none of pos, base and surface",
       "unknown-pos": "{scope} {at}: unknown part of speech {written} ({names})",
       "bad-pattern": "{scope} {at}: the pattern cannot be used: {refusal}",
+      "level-and-levels": "{scope} {at}: has both level and levels; keep one",
+      "bad-levels":
+        "{scope} {at}: cannot read levels: {written}. Give strict, normal and relaxed a severity (error / warning / info), normal always. A team's rule reports places, so a number has nothing to count",
     },
+    fieldAt: "{scope} {at}: ",
   },
 };
 
@@ -100,10 +111,15 @@ const valuesOf = (problem: CustomProblem, text: Text, scope: string): Readonly<R
   names: POS_WRITTEN_NAMES.join(" / "),
 });
 
+const FIELD_KINDS: ReadonlySet<string> = new Set<FieldKind>(["bad-depth", "bad-group", "bad-use-for", "bad-summary", "bad-example"]);
+
+const isFieldProblem = (problem: CustomProblem): problem is FieldProblem & { readonly at: string } => FIELD_KINDS.has(problem.kind);
+
 /** One problem as a sentence. scope names the list the rule is in: custom_rules, or a plugin's rules. */
 export const customProblemSentence = (problem: CustomProblem, ui: UiLanguage, scope = "custom_rules"): string => {
   const values = valuesOf(problem, TEXT[ui], scope);
-  return TEXT[ui].problems[problem.kind].replace(PLACEHOLDER, (_whole, key: string) => values[key] ?? "");
+  const fill = (template: string): string => template.replace(PLACEHOLDER, (_whole, key: string) => values[key] ?? "");
+  return isFieldProblem(problem) ? `${fill(TEXT[ui].fieldAt)}${fieldProblemSentence(problem, ui)}` : fill(TEXT[ui].problems[problem.kind]);
 };
 
 /** What in custom_rules cannot run. Each stops the run: a team's rule that silently does not run looks like a clean document. */

package/src/detectors/blank-structure.ts

@@ -3,7 +3,7 @@
 import type { Detector, Finding, ProseDocument, Span } from "../plugin.ts";
 import { readMarkdown } from "../markdown-read.ts";
 import { spanOf, type MarkdownNode } from "../markdown-node.ts";
-import { eachPreOrder } from "../tree-walk.ts";
+import { eachPreOrder, foldPostOrder } from "../tree-walk.ts";
 import { quoteAt } from "./structure-tree.ts";
 
 /** Fewer body rows than this, and one blank is as likely a choice as a gap. */
@@ -21,14 +21,22 @@ const EMPHASIS = /[*_]/gu;
 const COMMENT = /^<!--[\s\S]*-->$/u;
 const VISIBLE_LEAVES = new Set(["inlineCode", "image", "imageReference"]);
 
-/** Whether a node shows the reader anything: text that is not blank, code, an image, or HTML that is not a comment. */
-const shows = (node: MarkdownNode): boolean => {
+/** What a leaf shows on its own; undefined for a node whose children decide. */
+const leafShows = (node: MarkdownNode): boolean | undefined => {
   if (node.type === "text") return (node.value ?? "").replace(EMPHASIS, "").trim() !== "";
   if (node.type === "html") return !COMMENT.test((node.value ?? "").trim());
   if (VISIBLE_LEAVES.has(node.type)) return true;
-  return (node.children ?? []).some(shows);
+  return undefined;
 };
 
+/** Whether a node shows the reader anything: text that is not blank, code, an image, or HTML that is not a comment. */
+const shows = (node: MarkdownNode): boolean =>
+  foldPostOrder<MarkdownNode, boolean>(
+    node,
+    (each) => each.children ?? [],
+    (each, children) => leafShows(each) ?? children.some((child) => child),
+  );
+
 const sourceOf = (source: string, node: MarkdownNode | undefined): string => {
   const span = node === undefined ? undefined : spanOf(node);
   return span === undefined ? "" : source.slice(span.start, span.end).replace(/\|/gu, "").trim();

package/src/detectors/clause-shape.ts

@@ -0,0 +1,199 @@
+import type { Detector, DetectorOptions, Finding, Lexicon, ProseDocument, Sentence, Token } from "../plugin.ts";
+import { isWithinAny, quotedIn } from "../quoted-span.ts";
+
+// The shape of a clause read from its words: how it ends, a paired word left alone, an adverb that needs a
+// negation, a particle used where another one belongs. Every word comes from a lexicon; this file knows parts of speech.
+
+const findingAt = (sentence: Sentence, offset: number, values: Readonly<Record<string, string | number>>): Finding => ({
+  rule: "",
+  severity: "info",
+  line: 0,
+  column: 0,
+  quote: sentence.text.trim(),
+  values: { ...values, offset },
+});
+
+const patternsOf = (lexicon: Lexicon | undefined, group?: string): ReadonlySet<string> =>
+  new Set((lexicon ?? []).filter((entry) => group === undefined || entry.group === group).map((entry) => entry.pattern));
+
+const isSpace = (token: Token | undefined): boolean => token !== undefined && token.surface.trim() === "";
+
+/** The tokens of a sentence outside anything quoted in 「」『』, with their index in the sentence. */
+const ownTokens = (sentence: Sentence): { readonly token: Token; readonly at: number }[] => {
+  const quoted = quotedIn(sentence);
+  return (sentence.tokens ?? []).flatMap((token, at) => (isWithinAny(quoted, token.span) ? [] : [{ token, at }]));
+};
+
+const wordOf = (token: Token): string => token.lemma ?? token.surface;
+
+const isListed = (words: ReadonlySet<string>, token: Token | undefined): boolean =>
+  token !== undefined && (words.has(token.surface) || words.has(wordOf(token)));
+
+// --- ending-run: sentences in a row that end with the same words ---------------------------------------------
+
+const TRAILING_POS: ReadonlySet<string> = new Set(["PUNCT", "SYM"]);
+const TAIL_POS: ReadonlySet<string> = new Set(["AUX", "PART"]);
+const VERBAL_POS: ReadonlySet<string> = new Set(["VERB"]);
+
+/**
+ * How a sentence ends: its closing auxiliaries, and the verb before them as written (しました, あります, 思います).
+ * A noun before them is left out, so 必要です and 重要です end the same way. No auxiliary, no ending to compare.
+ */
+export const endingOf = (sentence: Sentence): string | undefined => {
+  const tokens = (sentence.tokens ?? []).filter((token) => !isSpace(token));
+  const last = tokens.findLastIndex((token) => !TRAILING_POS.has(token.pos));
+  const head = tokens.slice(0, last + 1).findLastIndex((token) => !TAIL_POS.has(token.pos));
+  if (head === last) return undefined;
+  const headToken = tokens[head];
+  const tail = tokens.slice(head + 1, last + 1).map((token) => token.surface);
+  return [headToken !== undefined && VERBAL_POS.has(headToken.pos) ? headToken.surface : "", ...tail].join("");
+};
+
+type Ended = { readonly sentence: Sentence; readonly ending: string | undefined };
+
+/** Runs of consecutive sentences with the same ending. A sentence with no ending to compare closes a run. */
+export const endingRuns = (sentences: readonly Sentence[]): Ended[][] =>
+  sentences
+    .map((sentence) => ({ sentence, ending: endingOf(sentence) }))
+    .reduce<Ended[][]>((runs, ended) => {
+      const last = runs.at(-1) ?? [];
+      const continues = ended.ending !== undefined && last[0]?.ending === ended.ending;
+      return continues ? [...runs.slice(0, -1), [...last, ended]] : [...runs, [ended]];
+    }, [])
+    .filter((run) => run[0]?.ending !== undefined);
+
+const runFinding = (run: readonly Ended[], limit: number): Finding => {
+  const first = run[0];
+  return {
+    rule: "",
+    severity: "info",
+    line: 0,
+    column: 0,
+    quote: run.map(({ sentence }) => sentence.text.trim()).join(""),
+    values: { word: first?.ending ?? "", count: run.length, limit, offset: first?.sentence.span.start ?? 0 },
+  };
+};
+
+/** More than limit sentences in a row within one paragraph that end with the same words. */
+export const endingRun: Detector = (doc, options): Finding[] =>
+  doc.paragraphs.flatMap((paragraph) =>
+    endingRuns(paragraph.sentences)
+      .filter((run) => run.length > options.limit)
+      .map((run) => runFinding(run, options.limit)),
+  );
+
+// --- unpaired-parallel: a word that lists by pairs (〜たり) used once, followed by another clause -----------------
+
+const CONTENT_POS: ReadonlySet<string> = new Set(["VERB", "ADJ", "NOUN", "PROPN"]);
+
+const nextWord = (tokens: readonly Token[], at: number): Token | undefined => tokens.slice(at + 1).find((token) => !isSpace(token));
+
+/**
+ * The marker is left alone when the sentence holds it once and what follows starts a new clause: a comma,
+ * or a content word other than the lexicon's closer (〜たり、映画を見る / 〜たり見る). 〜たりする and 〜たりもする are whole.
+ */
+const leftAlone = (tokens: readonly Token[], at: number, closers: ReadonlySet<string>, commas: ReadonlySet<string>): boolean => {
+  const next = nextWord(tokens, at);
+  if (next === undefined) return false;
+  if (commas.has(next.surface)) return true;
+  return CONTENT_POS.has(next.pos) && !isListed(closers, next);
+};
+
+const CONJUNCTION = "CCONJ";
+
+const markersIn = (sentence: Sentence, markers: ReadonlySet<string>): { readonly token: Token; readonly at: number }[] =>
+  ownTokens(sentence).filter(({ token }) => token.pos === CONJUNCTION && markers.has(token.surface));
+
+/** A sentence that uses the lexicon's paired marker once and goes on without its partner. */
+export const unpairedParallel: Detector = (doc, options): Finding[] => {
+  const markers = patternsOf(options.lexicon, "marker");
+  const closers = patternsOf(options.lexicon, "closer");
+  const commas = patternsOf(options.lexicon, "comma");
+  return doc.sentences.flatMap((sentence) => {
+    const found = markersIn(sentence, markers);
+    const only = found.length === 1 ? found[0] : undefined;
+    if (only === undefined || !leftAlone(sentence.tokens ?? [], only.at, closers, commas)) return [];
+    return [findingAt(sentence, only.token.span.start, { word: only.token.surface })];
+  });
+};
+
+// --- adverb-polarity: an adverb that wants a negation, in a sentence that has none ------------------------------
+
+type Negations = { readonly words: ReadonlySet<string>; readonly prefixes: readonly string[] };
+
+const negationsOf = (lexicon: Lexicon | undefined): Negations => ({
+  words: new Set((lexicon ?? []).filter((entry) => entry.group === undefined).map((entry) => entry.pattern)),
+  prefixes: [...patternsOf(lexicon, "prefix")],
+});
+
+/** A negating word (ない, 違う) or a word opening with a negating prefix (不十分, 無理). */
+const isNegation = (token: Token, negations: Negations): boolean =>
+  isListed(negations.words, token) || negations.prefixes.some((prefix) => token.surface.length > prefix.length && token.surface.startsWith(prefix));
+
+type Placed = { readonly token: Token; readonly at: number };
+
+/** A negation of the writer's own after the adverb; one inside a quotation does not answer it. */
+const hasNegation = (own: readonly Placed[], from: number, negations: Negations): boolean =>
+  own.some(({ token, at }) => at > from && isNegation(token, negations));
+
+/** Each of the lexicon's adverbs (全然, 決して) with no word of the negation list after it in its sentence. */
+export const adverbPolarity: Detector = (doc, options): Finding[] => {
+  const adverbs = patternsOf(options.lexicon);
+  const negations = negationsOf(doc.lexicons["negation-word"]);
+  return doc.sentences.flatMap((sentence) => {
+    const own = ownTokens(sentence);
+    return own
+      .filter(({ token, at }) => adverbs.has(token.surface) && !hasNegation(own, at, negations))
+      .map(({ token }) => findingAt(sentence, token.span.start, { word: token.surface }));
+  });
+};
+
+// --- origin-particle: a comparison particle (より) used for "from" -------------------------------------------------
+
+/** Adverbs (順次) and punctuation (本日より、発送) stand between the particle and its head. */
+const SKIPPED_POS: ReadonlySet<string> = new Set(["ADV", "PUNCT"]);
+const PARTICLE = "ADP";
+const NOMINAL_POS: ReadonlySet<string> = new Set(["NOUN", "PROPN"]);
+
+/** The first word after the particle, past adverbs (順次) and a bound honorific prefix (ご連絡). */
+const headAfter = (tokens: readonly Token[], at: number): number =>
+  tokens.findIndex((token, index) => index > at && !isSpace(token) && !SKIPPED_POS.has(token.pos) && token.features?.["Bound"] !== "Yes");
+
+/**
+ * The head names a start or a sending (開始, 参る, 連絡). A noun head must be the action itself: followed by an object
+ * marker or a light verb (受付を開始, 開始します), not a noun being compared (昨年より販売が増えた).
+ */
+const isOriginHead = (tokens: readonly Token[], head: number, heads: ReadonlySet<string>, objectMarkers: ReadonlySet<string>): boolean => {
+  const token = tokens[head];
+  if (token === undefined || !isListed(heads, token)) return false;
+  if (!NOMINAL_POS.has(token.pos)) return true;
+  const next = nextWord(tokens, head);
+  return next !== undefined && (objectMarkers.has(next.surface) || next.features?.["VerbType"] === "Light");
+};
+
+type ParticleWords = { readonly particles: ReadonlySet<string>; readonly heads: ReadonlySet<string>; readonly objectMarkers: ReadonlySet<string> };
+
+const originsIn = (sentence: Sentence, words: ParticleWords): Token[] => {
+  const tokens = sentence.tokens ?? [];
+  return ownTokens(sentence)
+    .filter(
+      ({ token, at }) =>
+        token.pos === PARTICLE && words.particles.has(token.surface) && isOriginHead(tokens, headAfter(tokens, at), words.heads, words.objectMarkers),
+    )
+    .map(({ token }) => token);
+};
+
+const particleWords = (doc: ProseDocument, options: DetectorOptions): ParticleWords => ({
+  particles: patternsOf(options.lexicon),
+  heads: patternsOf(doc.lexicons["origin-head"], "head"),
+  objectMarkers: patternsOf(doc.lexicons["origin-head"], "object"),
+});
+
+/** The lexicon's particle where it marks a starting point (4月1日より開始), which the lexicon's rewrite says instead. */
+export const originParticle: Detector = (doc, options): Finding[] => {
+  const words = particleWords(doc, options);
+  const rewrites = new Map((options.lexicon ?? []).map((entry) => [entry.pattern, entry.rewrite ?? ""]));
+  return doc.sentences.flatMap((sentence) =>
+    originsIn(sentence, words).map((token) => findingAt(sentence, token.span.start, { word: token.surface, suggestion: rewrites.get(token.surface) ?? "" })),
+  );
+};