chaffjs 0.5.0 → 0.6.0

package/src/adapter-load.ts

@@ -50,7 +50,24 @@ const pickExport = (module: object): unknown => {
   return isAdapter(record["adapter"]) ? record["adapter"] : record["default"];
 };
 
-export const packageFor = (language: string): string | undefined => ADAPTER_PACKAGE[language];
+/**
+ * 同梱の言語は表から、それ以外は `@chaffjs/lang-<言語>` を探す。
+ * 利用者が lang-zh のようなパッケージを書いて入れれば、core を変えずにその言語で動く。
+ */
+const LANGUAGE_ID = /^[a-z]{2,3}$/u;
+
+export const packageFor = (language: string): string | undefined =>
+  ADAPTER_PACKAGE[language] ?? (LANGUAGE_ID.test(language) ? `@chaffjs/lang-${language}` : undefined);
+
+const importAdapter = async (specifier: string, language: string): Promise<unknown> => {
+  try {
+    return await import(specifier);
+  } catch (err) {
+    const missing = err instanceof Error && "code" in err && err.code === "ERR_MODULE_NOT_FOUND";
+    if (missing) throw new Error(`言語 ${language} のパッケージ ${specifier} が入っていません（npm i -D ${specifier}）`, { cause: err });
+    throw err;
+  }
+};
 
 /**
  * アダプタは「必要になったものだけ」を実行時に解決する。spec §17.2。
@@ -60,7 +77,7 @@ export const packageFor = (language: string): string | undefined => ADAPTER_PACK
 export const loadAdapter = async (language: string): Promise<LanguageAdapter> => {
   const specifier = packageFor(language);
   if (specifier === undefined) throw new Error(`no adapter for language "${language}"`);
-  const module: unknown = await import(specifier);
+  const module = await importAdapter(specifier, language);
   if (typeof module !== "object" || module === null) throw new Error(`${specifier} did not export a module`);
   const candidate = pickExport(module);
   const broken = checkAdapter(candidate);

package/src/cli.ts

@@ -23,6 +23,8 @@ import { renderFriendly } from "./render/friendly.ts";
 import { rulesJson } from "./render/rules-json.ts";
 import { renderSarif } from "./render/sarif.ts";
 import { VERSION } from "./version.ts";
+import { runTree, treeTargets } from "./commands/tree.ts";
+import { citeTargets, runCite } from "./commands/cite.ts";
 import { renderSummary, type FileOutcome } from "./render/summary.ts";
 import { neededBy, runRules } from "./run.ts";
 import type { Level, RuleDefinition } from "./plugin.ts";
@@ -37,6 +39,8 @@ const USAGE = `chaff — 文章の読みにくいところを見つけます。
   chaff eval <dir>               手元の文書で閾値を測り直す
   chaff explain <rule>           そのルールの意図と根拠を読む
   chaff genres                   ジャンルの一覧
+  chaff tree <file> [--format sexp|json]  文書を番地の付いた木にする（条・項・定義・参照）
+  chaff cite <原文> <引用.json>           回答の引用（番地と引用文）が原文にあるかを確かめる
   chaff rules --json             いまの設定を JSON で出す（AI に渡す用）
   chaff baseline <dir>           いまある指摘を棚上げする（既存の repo に入れるとき）
   chaff suppressions <dir>       stet で黙らせている指摘を数える
@@ -283,6 +287,8 @@ const HANDLERS: Readonly<Record<string, Handler>> = {
   rules: showRules,
   explain: (argv) => explain(argv[1]),
   eval: (argv) => runEval(positional(argv), argv, { config: readConfig(), resolveGenre, flag }),
+  tree: (argv) => runTree(treeTargets(argv), argv, { config: readConfig(), flag }),
+  cite: (argv) => runCite(citeTargets(argv), argv, { config: readConfig(), flag }),
   test: (argv) => runTest(positional(argv), argv, { config: readConfig(), resolveGenre, inspect }),
   baseline: (argv) => runBaseline(positional(argv), argv),
   suppressions: (argv) => runSuppressions(positional(argv), argv),

package/src/commands/cite.ts

@@ -0,0 +1,74 @@
+import { checkCitations, type Citation, type CitationResult } from "../structure/cite.ts";
+import { readSource, readTree, type TreeContext } from "./tree.ts";
+
+const USAGE = "使い方: chaff cite <原文> <引用.json> [--format text|json] [--language ja|en|…]";
+const FORMATS = ["text", "json"];
+const QUOTE_WIDTH = 40;
+const VALUED = ["--format", "--language"];
+
+export const citeTargets = (argv: readonly string[]): string[] =>
+  argv.slice(1).filter((arg, index, all) => !arg.startsWith("--") && !VALUED.includes(all[index - 1] ?? ""));
+
+const isRecord = (value: unknown): value is Record<string, unknown> => typeof value === "object" && value !== null && !Array.isArray(value);
+
+const isCitation = (value: unknown): value is Citation => isRecord(value) && typeof value["address"] === "string" && typeof value["quote"] === "string";
+
+export type ParsedCitations = { readonly citations: readonly Citation[] } | { readonly error: string };
+
+const parseJson = (text: string): { readonly value: unknown } | { readonly error: string } => {
+  try {
+    return { value: JSON.parse(text) };
+  } catch (err) {
+    return { error: `JSON として読めません: ${err instanceof Error ? err.message : String(err)}` };
+  }
+};
+
+/** 引用の一覧。[{ address, quote }] の配列だけを受け取る。形が違えば理由を返す。 */
+export const parseCitations = (text: string): ParsedCitations => {
+  const parsed = parseJson(text);
+  if ("error" in parsed) return parsed;
+  if (!Array.isArray(parsed.value)) return { error: '引用は配列で渡してください: [{ "address": "3.2", "quote": "…" }]' };
+  const entries: readonly unknown[] = parsed.value;
+  const bad = entries.findIndex((entry) => !isCitation(entry));
+  if (bad !== -1) return { error: `${String(bad + 1)} 件目に address（文字列）と quote（文字列）がありません` };
+  return { citations: entries.filter(isCitation).map((entry) => ({ address: entry.address, quote: entry.quote })) };
+};
+
+const MESSAGES: Readonly<Record<CitationResult["status"], (result: CitationResult) => string>> = {
+  ok: () => "一致",
+  "missing-address": (result) => `番地 ${result.citation.address} は原文にありません`,
+  "quote-elsewhere": (result) => `引用文は ${result.citation.address} ではなく ${result.foundAt ?? "番地の外"}（${String(result.line ?? "?")} 行目）にあります`,
+  "quote-not-found": () => "引用文が原文のどこにもありません",
+};
+
+const describe = (result: CitationResult): string => {
+  const mark = result.status === "ok" ? "✓" : "✗";
+  const oneLine = result.citation.quote.replace(/\s+/gu, " ").trim();
+  const quote = oneLine.length > QUOTE_WIDTH ? `${oneLine.slice(0, QUOTE_WIDTH)}…` : oneLine;
+  return `${mark} ${result.citation.address}「${quote}」: ${MESSAGES[result.status](result)}`;
+};
+
+/**
+ * 回答の引用が原文にあるかを確かめる。書き換えはしない。
+ * 一つでも外れていれば 1 で終わるので、AI の回答を単体試験のように検査できる。
+ */
+export const runCite = async (targets: readonly string[], argv: readonly string[], context: TreeContext): Promise<number> => {
+  const [sourcePath, citationsPath] = targets;
+  const format = context.flag(argv, "--format") ?? "text";
+  if (sourcePath === undefined || citationsPath === undefined || targets.length !== 2 || !FORMATS.includes(format)) {
+    console.error(USAGE);
+    return 1;
+  }
+  const citationsText = await readSource(citationsPath);
+  if (citationsText === undefined) return 1;
+  const parsed = parseCitations(citationsText);
+  if ("error" in parsed) {
+    console.error(`${citationsPath}: ${parsed.error}`);
+    return 1;
+  }
+  const read = await readTree(sourcePath, argv, context);
+  if (read === undefined) return 1;
+  const results = checkCitations(read.source, read.tree, parsed.citations);
+  console.log(format === "json" ? JSON.stringify(results, null, 2) : results.map(describe).join("\n"));
+  return results.every((result) => result.status === "ok") ? 0 : 1;
+};

package/src/commands/tree.ts

@@ -0,0 +1,94 @@
+import { readFile } from "node:fs/promises";
+import { loadAdapter } from "../adapter-load.ts";
+import { applyByPath } from "../config/by-path.ts";
+import { guessLanguage } from "../detect.ts";
+import { isMarkdownPath } from "../structure/markdown-path.ts";
+import { buildStructure } from "../structure/of.ts";
+import { toSexp } from "../structure/sexp.ts";
+import type { Config } from "../config/load.ts";
+import type { StructureNode } from "../plugin.ts";
+
+export type TreeContext = {
+  readonly config: Config;
+  readonly flag: (argv: readonly string[], name: string) => string | undefined;
+};
+
+const FORMATS = ["sexp", "json"];
+
+const USAGE = "使い方: chaff tree <file>... [--format sexp|json] [--language ja|en|…]";
+
+/** 値を取るフラグ。その次の引数は値で、対象のファイルではない。 */
+const VALUED = ["--format", "--language"];
+
+export const treeTargets = (argv: readonly string[]): string[] =>
+  argv.slice(1).filter((arg, index, all) => !arg.startsWith("--") && !VALUED.includes(all[index - 1] ?? ""));
+
+export const readSource = async (path: string): Promise<string | undefined> => {
+  try {
+    return await readFile(path, "utf8");
+  } catch (err) {
+    console.error(`${path} を読めませんでした: ${err instanceof Error ? err.message : String(err)}`);
+    return undefined;
+  }
+};
+
+/**
+ * 言語の決め方は lint / test / eval と同じ。そのファイルの by_path、全体の language、中身からの推定の順で、
+ * その前に --language を置く。混在するリポジトリで、英語の契約書を日本語として読まないため。
+ */
+export const treeLanguage = (path: string, source: string, argv: readonly string[], context: TreeContext): string =>
+  context.flag(argv, "--language") ??
+  applyByPath(context.config.byPath, context.config.baseDir, path).language ??
+  context.config.language ??
+  guessLanguage(source).language;
+
+export type SourceTree = { readonly source: string; readonly tree: StructureNode };
+
+/**
+ * 1 ファイルを読んで木にする。読めない・言語パッケージが構造を読めないときは、黙らずに言って undefined を返す。
+ * chaff tree と chaff cite が同じ木を見るように、ここを一つにしておく。
+ */
+export const readTree = async (path: string, argv: readonly string[], context: TreeContext): Promise<SourceTree | undefined> => {
+  const source = await readSource(path);
+  if (source === undefined) return undefined;
+  const language = treeLanguage(path, source, argv, context);
+  const adapter = await loadAdapter(language);
+  if (adapter.structure === undefined) {
+    console.error(`${path}: 言語 ${language} のパッケージは文書の構造を読めません（structure がありません）`);
+    return undefined;
+  }
+  // 日本語は形態素で数量と日付を読む。解析器が無ければ単位の表で読むので、木は作れる。
+  await adapter.prepare?.({ pos: true });
+  return { source, tree: buildStructure({ path, source, language, markdown: isMarkdownPath(path) }, adapter.structure) };
+};
+
+const printTree = async (path: string, argv: readonly string[], context: TreeContext): Promise<boolean> => {
+  const read = await readTree(path, argv, context);
+  if (read === undefined) return false;
+  console.log(context.flag(argv, "--format") === "json" ? JSON.stringify(read.tree, null, 2) : toSexp(read.tree));
+  return true;
+};
+
+/**
+ * 1 つずつ、渡された順に処理する。前のファイルが終わってから次を始めるので、出力の順が入れ替わらない。
+ * 失敗したファイルがあっても残りは処理し、1 つでも失敗していれば false を返す。
+ */
+export const inOrder = async (paths: readonly string[], each: (path: string) => Promise<boolean>): Promise<boolean> =>
+  paths.reduce<Promise<boolean>>(async (previous, path) => {
+    const earlier = await previous;
+    return (await each(path)) && earlier;
+  }, Promise.resolve(true));
+
+/**
+ * 文書を番地の付いた木にして出す。S 式は人と AI が読むため、JSON は機械が読むため。
+ * 書き換えはしない。Markdown でない .txt（見出しの無い契約書）も、行頭の番号で木にする。
+ */
+export const runTree = async (paths: readonly string[], argv: readonly string[], context: TreeContext): Promise<number> => {
+  const format = context.flag(argv, "--format") ?? "sexp";
+  if (paths.length === 0 || !FORMATS.includes(format)) {
+    console.error(USAGE);
+    return 1;
+  }
+  const printed = await inOrder(paths, (path) => printTree(path, argv, context));
+  return printed ? 0 : 1;
+};

package/src/detectors/index.ts

@@ -14,6 +14,7 @@ import { paragraphLength, paragraphVariance, preambleLength, ruleOfThree, sectio
 import { concreteEvidence, dashDensity, emojiDensity, ngramRepetition, undefinedAcronym } from "./signals.ts";
 import { aiTell, contractionMix, cushionDensity, hedgingDensity, repeatedConjunction, unqualifiedSuperlative } from "./lexicon.ts";
 import { internalJargon, properNounDensity, requiredSections } from "./team.ts";
+import { danglingReference, duplicateDefinition, numberingGap } from "./structure-tree.ts";
 
 /** rule 定義の how_to_find がここを引く。rule 側は実装を知らない。 */
 export const DETECTORS: Readonly<Record<string, Detector>> = {
@@ -53,4 +54,7 @@ export const DETECTORS: Readonly<Record<string, Detector>> = {
   "internal-jargon": internalJargon,
   "required-sections": requiredSections,
   "proper-noun-density": properNounDensity,
+  "dangling-reference": danglingReference,
+  "numbering-gap": numberingGap,
+  "duplicate-definition": duplicateDefinition,
 };

package/src/detectors/signals.ts

@@ -72,7 +72,12 @@ const countGrams = (text: string, width: number): Map<string, number> => {
  * どちらを見るかは adapter が宣言する単位で決める。ひらがなを持たない char 単位の言語が
  * 来たら、この見分けは効かなくなる（そのときは adapter 側に判定を移す）。
  */
-const CONNECTIVE = { char: /[ぁ-ゖ]/u, word: /\S \S.*\S \S/u };
+/**
+ * つなぎが 1 つでは足りない。「detectorは」は用語に助詞が 1 つ付いただけで、
+ * 繰り返して当たり前の**用語**であって言い回しではない。
+ * 実文書で測ると、本物の言い回しはひらがなを 7 つ前後含み、用語＋助詞は 1〜2 だった。
+ */
+const CONNECTIVE = { char: /[ぁ-ゖ].*[ぁ-ゖ].*[ぁ-ゖ]/u, word: /\S \S.*\S \S/u };
 
 const isPhrasing = (gram: string, unit: ProseDocument["lengthUnit"]): boolean => CONNECTIVE[unit].test(gram);
 

package/src/detectors/structure-tree.ts

@@ -0,0 +1,32 @@
+import type { Detector, Finding, ProseDocument } from "../plugin.ts";
+import { danglingReferences, duplicateDefinitions, type StructureIssue } from "../structure/issues.ts";
+import { numberingBreaks } from "../structure/numbering.ts";
+
+const QUOTE_LENGTH = 80;
+
+/** 指摘の位置から行末までを引用する。条の見出しや参照を含む一行が、読み手の探す手がかりになる。 */
+const quoteAt = (source: string, offset: number): string => {
+  const end = source.indexOf("\n", offset);
+  return source
+    .slice(offset, end === -1 ? source.length : end)
+    .slice(0, QUOTE_LENGTH)
+    .trim();
+};
+
+const findingsOf =
+  (rule: string, issuesOf: (tree: NonNullable<ProseDocument["structure"]>) => StructureIssue[]): Detector =>
+  (doc): Finding[] =>
+    doc.structure === undefined
+      ? []
+      : issuesOf(doc.structure).map((issue) => ({
+          rule,
+          severity: "error",
+          line: 0,
+          column: 0,
+          quote: quoteAt(doc.source, issue.offset),
+          values: { ...issue.values, offset: issue.offset },
+        }));
+
+export const danglingReference: Detector = findingsOf("dangling-reference", danglingReferences);
+export const numberingGap: Detector = findingsOf("numbering-gap", numberingBreaks);
+export const duplicateDefinition: Detector = findingsOf("duplicate-definition", duplicateDefinitions);

package/src/document.ts

@@ -4,7 +4,9 @@ import { gfmTableFromMarkdown } from "mdast-util-gfm-table";
 import { frontmatter } from "micromark-extension-frontmatter";
 import { frontmatterFromMarkdown } from "mdast-util-frontmatter";
 import { maskSpans } from "./mask.ts";
-import type { BulletList, LanguageAdapter, Paragraph, ProseDocument, Section, Sentence, Span } from "./plugin.ts";
+import { buildTree, NO_OUTLINE, type Outline } from "./structure/build.ts";
+import { isMarkdownPath } from "./structure/markdown-path.ts";
+import type { BulletList, LanguageAdapter, Paragraph, ProseDocument, Section, Sentence, Span, StructureNode } from "./plugin.ts";
 
 type Place = { readonly offset?: number | undefined };
 type Node = {
@@ -120,7 +122,7 @@ const textOf = (node: Node, source: string): string => {
   return parts.join("");
 };
 
-type Heading = { readonly depth: number; readonly text: string; readonly start: number; readonly end: number };
+export type Heading = { readonly depth: number; readonly text: string; readonly start: number; readonly end: number };
 
 const headingsOf = (root: Node, source: string): Heading[] => {
   const found: Heading[] = [];
@@ -247,6 +249,9 @@ export const buildDocument = (path: string, source: string, adapter: LanguageAda
   const paragraphSpans = spansOfType(root, "paragraph");
   const listItems = spansOfType(root, "listItem");
   const sentences = sentencesOf(prose, paragraphSpans, adapter);
+  const patterns = adapter.structure;
+  // null は「作ったが構造を読めない言語だった」、undefined は「まだ作っていない」。
+  const tree: { value: StructureNode | null | undefined } = { value: undefined };
   return {
     path,
     source,
@@ -260,5 +265,24 @@ export const buildDocument = (path: string, source: string, adapter: LanguageAda
     lists: listsOf(root, source),
     lexicons: { ...adapter.lexicons, "internal-jargon": team.jargon.map((pattern) => ({ pattern })) },
     requiredSections: team.requiredSections,
+    // 構造の rule（参照先が無い・番号の抜け）が読む木。どの rule も読まなければ作らない。何万行の契約書で、他の rule の lint に代金を払わせない。
+    get structure(): StructureNode | undefined {
+      tree.value ??=
+        patterns === undefined
+          ? null
+          : buildTree({ path, source, language: adapter.id, outline: isMarkdownPath(path) ? outlineOf(root, source) : NO_OUTLINE }, patterns);
+      return tree.value ?? undefined;
+    },
   };
 };
+
+/** 番号を探してはいけない範囲。コードの中の「第3条」は条ではなく、参照でもない。 */
+const OPAQUE = ["code", "inlineCode", "html", "yaml", "toml"];
+
+const outlineOf = (root: Node, source: string): Outline => ({
+  headings: headingsOf(root, source),
+  opaque: OPAQUE.flatMap((type) => spansOfType(root, type)),
+});
+
+/** 構造を読むための Markdown の手がかり。見出しと、中を読まない範囲。 */
+export const markdownOutline = (source: string): Outline => outlineOf(parse(source), source);

package/src/eval.ts

@@ -63,6 +63,16 @@ const recommend = (rule: RuleDefinition, sweep: readonly Point[], total: number)
   return strictest;
 };
 
+/** lint と同じ要求の読み方。知らない要求は満たさないものとする。pos に読み替えると、動かない rule を測ってしまう。 */
+const meets = (need: string, docs: readonly ProseDocument[]): boolean => {
+  const capabilities = docs[0]?.capabilities;
+  if (need === "pos") return capabilities?.pos === true;
+  if (need === "lemma") return capabilities?.lemma === true;
+  // 木は adapter が structure を持つときだけ作れる。無いまま測ると、どの閾値でも 0 件になる。
+  if (need === "structure") return docs.length > 0 && docs.every((doc) => doc.structure !== undefined);
+  return false;
+};
+
 /**
  * lint で動かない rule は掃引しない。
  * 動かないものの閾値を測ると、「どの閾値でも 0 件」が「よく校正されている」に見える。
@@ -71,8 +81,7 @@ const measurable = (rule: RuleDefinition, docs: readonly ProseDocument[], genre:
   if (rule.layer === "L4" || !rule.use_for.some((target) => genre.startsWith(target))) return false;
   if (rule.languages !== undefined && !rule.languages.includes(language)) return false;
   if (rule.from.length > 0) return false;
-  const capabilities = docs[0]?.capabilities;
-  return !rule.requires.some((need) => (need === "lemma" ? capabilities?.lemma : capabilities?.pos) !== true);
+  return rule.requires.every((need) => meets(need, docs));
 };
 
 export const evaluate = (docs: readonly ProseDocument[], rules: readonly RuleDefinition[], genre: string, language: string): RuleReport[] =>

package/src/plugin.ts

@@ -71,6 +71,79 @@ export type LanguageAdapter = {
   readonly segment: (text: string) => Segmentation;
   /** L2 rule が word_list で引く。アダプタが自分の言語のぶんだけを持つ。 */
   readonly lexicons: Readonly<Record<string, Lexicon>>;
+  /** 文書の構造を読む型。無い言語では `chaff tree` がそう言って止まる。 */
+  readonly structure?: StructurePatterns;
+};
+
+// ───────── 文書の構造 ─────────
+
+/**
+ * 行頭の番号 1 つ。「第3条」「２」「(a)」を読むのは言語パッケージで、
+ * 入れ子と番地を決めるのは core。core は番号の書き方を知らない。
+ */
+export type NumberedLine = {
+  readonly kind: "chapter" | "article" | "item";
+  /** 入れ子の深さ。条が 1、項が 2、号が 3 のように、言語パッケージが決める。条より外の編・章・節は 0 以下。 */
+  readonly depth: number;
+  /** 番地の部品。"3"、"4.2"、"a"。 */
+  readonly number: string;
+  /** true なら number だけで番地が決まる（条番号、4.2 のような通し番号）。false なら親の番地に続ける。 */
+  readonly absolute: boolean;
+  /** 書かれたままの番号。「第3条」「Section 4.2」。 */
+  readonly label: string;
+  /** 番号に続く見出し。「第3条（支払）」の「支払」。本文しか無ければ空。 */
+  readonly heading: string;
+  /** 番号の後ろの文字列全部。定義や参照はここから探す。 */
+  readonly rest: string;
+  /**
+   * 並びの中の位置。第三条は 3、(ii) は 2、(b) は 2、4.2 は 2。番号の抜けを見る rule が比べる。
+   * 枝番号（第3条の2）は並びの外なので付けない。読み方を知っているのは言語パッケージだけなので、core は計算しない。
+   */
+  readonly ordinal?: number | undefined;
+};
+
+/** 番号を読むときに見える周り。「(i)」がローマ数字か英字かは、開いている番号で決まる。 */
+export type NumberingContext = {
+  readonly open: readonly NumberedLine[];
+  /** Markdown の見出しの行か。本文の「1. 」は箇条書きで、見出しの「1. 」は章番号。 */
+  readonly isHeading: boolean;
+};
+
+/** 行の中で見つけたもの。start / end は渡した文字列の中の位置。 */
+export type Mention = { readonly start: number; readonly end: number; readonly attrs: Readonly<Record<string, string | number>> };
+
+export type StructurePatterns = {
+  readonly numbered: (line: string, context: NumberingContext) => NumberedLine | undefined;
+  /** 定義。attrs.term に定義された語。 */
+  readonly definitions: (text: string) => readonly Mention[];
+  /** 参照。attrs.target に正規化した番地（"12.1"）、attrs.label に書かれたまま。 */
+  readonly references: (text: string) => readonly Mention[];
+  /** 義務・禁止・許可。attrs.marker に語、attrs.type に must / must-not / may。 */
+  readonly obligations: (text: string) => readonly Mention[];
+  /** 数量。attrs.value に数、attrs.unit に単位。 */
+  readonly quantities: (text: string) => readonly Mention[];
+  /** 日付。attrs.value に "2024-04-01"・"2024-04"・"04-01"・"2024" のどれか。無い言語は日付を読まない。 */
+  readonly dates?: (text: string) => readonly Mention[];
+  /**
+   * 「1.5 倍」「2.5 days」の 1.5 は通し番号ではない。番号と後ろの文字列を渡し、後ろが単位なら true。
+   * 数字と点だけの通し番号は core が言語を問わず読むので、それを数量と見分けられるのは言語パッケージだけ。
+   */
+  readonly countedAfter?: (number: string, rest: string) => boolean;
+};
+
+export type StructureKind = "doc" | "section" | "chapter" | "article" | "item" | "definition" | "reference" | "obligation" | "quantity" | "date";
+
+/** 番地の付いた木の節点。すべて元の文書の位置（UTF-16）と行を持つ。 */
+export type StructureNode = {
+  readonly kind: StructureKind;
+  /** 節・条・項の番地。"3.2"、見出しは "h2.1"。定義や参照のような葉は空。 */
+  readonly address: string;
+  readonly span: Span;
+  readonly line: number;
+  readonly attrs: Readonly<Record<string, string | number>>;
+  readonly children: readonly StructureNode[];
+  /** 番号付きのまとまりの、並びの中の位置（NumberedLine.ordinal）。S 式には出さない。 */
+  readonly ordinal?: number;
 };
 
 // ───────── 文書モデルと rule ─────────
@@ -115,6 +188,8 @@ export type ProseDocument = {
   readonly lexicons: Readonly<Record<string, Lexicon>>;
   /** この種類の文書に無いと困る見出し。チームが chaff.yaml で決める。 */
   readonly requiredSections: readonly string[];
+  /** 番地の付いた木（§27）。adapter が structure を持たない言語では無い。 */
+  readonly structure: StructureNode | undefined;
 };
 
 export type Severity = "error" | "warning" | "info";

package/src/position.ts

@@ -12,7 +12,27 @@ export const lineStarts = (source: string): number[] => {
   return starts;
 };
 
+/**
+ * offset を含む行。starts は昇順なので二分探索で引く。指摘が何千もある長い文書で、指摘ごとに全行をなめない。
+ * offset より前に行頭が無ければ（負の値、NaN）先頭の行とする。
+ */
+const lineIndexOf = (starts: readonly number[], offset: number): number => {
+  let low = 0;
+  let high = starts.length - 1;
+  let found = 0;
+  while (low <= high) {
+    const middle = (low + high) >> 1;
+    if ((starts[middle] ?? Number.POSITIVE_INFINITY) <= offset) {
+      found = middle;
+      low = middle + 1;
+    } else {
+      high = middle - 1;
+    }
+  }
+  return found;
+};
+
 export const placeOf = (starts: readonly number[], offset: number): Place => {
-  const index = starts.reduce((best, start, at) => (start <= offset ? at : best), 0);
+  const index = lineIndexOf(starts, offset);
   return { line: index + 1, column: offset - (starts[index] ?? 0) + 1 };
 };

package/src/run.ts

@@ -43,9 +43,9 @@ const hasTokens = (doc: ProseDocument): boolean => doc.sentences.length === 0 ||
 /** 要求を満たさない rule は動かせない。満たさないまま動かすと「指摘 0 件」が保証に見える。 */
 const unmet = (rule: RuleDefinition, doc: ProseDocument): string | undefined => {
   if (rule.languages !== undefined && !rule.languages.includes(doc.language)) return `${doc.language} 向けの rule ではないため`;
-  const missing = rule.requires.find((need) => !has(doc.capabilities, need));
+  const missing = rule.requires.filter((need) => need !== "structure").find((need) => !has(doc.capabilities, need));
   if (missing !== undefined) return `この言語では${CAPABILITY_NAME[missing] ?? missing}が使えないため`;
-  if (rule.requires.length > 0 && !hasTokens(doc)) return "アダプタが品詞を返さなかったため";
+  if (rule.requires.some((need) => need === "pos" || need === "lemma") && !hasTokens(doc)) return "アダプタが品詞を返さなかったため";
   return undefined;
 };
 
@@ -111,6 +111,11 @@ export const runRules = (doc: ProseDocument, rules: readonly RuleDefinition[], s
         const why = rule.status === "experimental" && settings[rule.id] === undefined ? "まだ試験中のため" : "設定で止めているため";
         return { findings: acc.findings, skipped: [...acc.skipped, { rule: rule.id, why }] };
       }
+      // 木は capability ではなく、adapter が structure を持つかで決まる。持たない言語で動かすと「参照先が無い」が 0 件に見える。
+      // 段階を見た後で聞く。doc.structure は触れたときに木を作るので、止めている rule のために作らない。
+      if (rule.requires.includes("structure") && doc.structure === undefined) {
+        return { findings: acc.findings, skipped: [...acc.skipped, { rule: rule.id, why: `${doc.language} のパッケージは文書の構造を読めないため` }] };
+      }
       // 複合シグナルは二段目で扱う。一段目では「検出器が無い」と言わせない。
       if (rule.from.length > 0) return acc;
       const detector = DETECTORS[rule.how_to_find];

package/src/sentence-shape.ts

@@ -19,4 +19,22 @@ export const hasParticle = (sentence: Sentence): boolean => (sentence.tokens ??
 
 const SKIP = new Set(["PUNCT", "PART", "SYM"]);
 
-export const lastContent = (sentence: Sentence): Token | undefined => [...(sentence.tokens ?? [])].reverse().find((token) => !SKIP.has(token.pos));
+/**
+ * 文末の括弧は、文の終わりではなく添え物。
+ *
+ * 「これを最優先制約とする（§17）。」の述語は「とする」であって「17」ではない。
+ * 仕様書は相互参照を括弧で添えるので、これを数えると文末が全部そこになる。
+ */
+const TRAILING = /[(（][^(（]*[)）][\s。．！？!?]*$/u;
+
+const beforeTrailing = (sentence: Sentence): readonly Token[] => {
+  const tokens = sentence.tokens ?? [];
+  const match = TRAILING.exec(sentence.text);
+  if (match?.index === undefined) return tokens;
+  const cut = sentence.span.start + match.index;
+  const kept = tokens.filter((token) => token.span.end <= cut);
+  // 括弧を外したら何も残らない文は、括弧そのものが中身。そのまま見る。
+  return kept.length === 0 ? tokens : kept;
+};
+
+export const lastContent = (sentence: Sentence): Token | undefined => [...beforeTrailing(sentence)].reverse().find((token) => !SKIP.has(token.pos));