chaffjs 0.5.1 → 0.6.0

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/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/structure/build.ts

@@ -0,0 +1,203 @@
+import type { Heading } from "../document.ts";
+import { maskSpans } from "../mask.ts";
+import type { Mention, NumberedLine, NumberingContext, Span, StructureKind, StructureNode, StructurePatterns } from "../plugin.ts";
+import { lineNumberAt, linesOf, type Line } from "./lines.ts";
+import { dottedNumber } from "./universal.ts";
+
+/** 組み立て中の節点。できあがったら StructureNode に固める。 */
+type Draft = {
+  readonly kind: StructureKind;
+  readonly address: string;
+  readonly start: number;
+  end: number;
+  readonly line: number;
+  readonly attrs: Readonly<Record<string, string | number>>;
+  readonly children: Draft[];
+  readonly ordinal?: number | undefined;
+};
+
+/** 開いている節点。rank の大きいものほど内側。 */
+type Frame = { readonly draft: Draft; readonly rank: number; readonly numbered?: NumberedLine | undefined };
+
+/**
+ * 見出しは深さ 1〜6 を rank にする。番号のまとまりは必ず見出しの内側に入るので、
+ * それより大きい rank から数える。「## 第3条」の下の番号だけの項は、見出しに閉じられずに条の中へ入る。
+ */
+const NUMBERED_RANK = 10;
+
+type State = {
+  readonly stack: Frame[];
+  /** 見出しの深さごとの通し番号。番号の無い見出しの番地 h2.1 を作る。 */
+  readonly headingCounts: number[];
+};
+
+const draftOf = (kind: StructureKind, address: string, line: Line, attrs: Readonly<Record<string, string | number>>): Draft => ({
+  kind,
+  address,
+  start: line.start,
+  end: line.start + line.text.length,
+  line: line.number,
+  attrs,
+  children: [],
+});
+
+const top = (state: State): Frame => {
+  const frame = state.stack.at(-1);
+  if (frame === undefined) throw new Error("the document frame was closed");
+  return frame;
+};
+
+/** 自分と同じか内側の rank を閉じてから、親の子として開く。 */
+const open = (state: State, frame: Frame): void => {
+  while (state.stack.length > 1 && top(state).rank >= frame.rank) state.stack.pop();
+  top(state).draft.children.push(frame.draft);
+  state.stack.push(frame);
+};
+
+const nearestNumbered = (state: State): Frame | undefined => [...state.stack].reverse().find((frame) => frame.numbered !== undefined);
+
+const nearestSection = (state: State): Frame | undefined => [...state.stack].reverse().find((frame) => frame.draft.kind === "section");
+
+/**
+ * 条番号や 4.2 はそれだけで番地になる。項・号・(a) は親の番地に続ける。親が無ければ節の中の番号とする。
+ * 呼ぶ前に自分と同じか内側の rank は閉じてあるので、残っている番号付きの節点が親。
+ */
+const addressOf = (state: State, numbered: NumberedLine): string => {
+  if (numbered.absolute) return numbered.number;
+  const parent = nearestNumbered(state);
+  if (parent !== undefined) return `${parent.draft.address}.${numbered.number}`;
+  const section = nearestSection(state);
+  return section === undefined ? numbered.number : `${section.draft.address}/${numbered.number}`;
+};
+
+/** 飛ばした深さは 0 と数える。「# A」の直後の「### C」は h1.0.1。番地に空の部品を作らない。 */
+const headingAddress = (state: State, depth: number): string => {
+  state.headingCounts[depth - 1] = (state.headingCounts[depth - 1] ?? 0) + 1;
+  state.headingCounts.fill(0, depth);
+  const counts = Array.from({ length: depth }, (_, index) => state.headingCounts[index] ?? 0);
+  return `h${counts.map((count) => String(count)).join(".")}`;
+};
+
+/**
+ * 見出しに書いた番号（「## 第3条」）は、見出しの深さで入れ子にする。本文の番号は見出しの内側に入る。
+ * 見出しの深さを捨てると、「## 第3条」の下の「### 詳細」が条の外に出てしまう。
+ */
+const openNumbered = (state: State, line: Line, numbered: NumberedLine, headingDepth: number | undefined): void => {
+  const attrs = { label: numbered.label, ...(numbered.heading === "" ? {} : { heading: numbered.heading }) };
+  const rank = headingDepth ?? NUMBERED_RANK + numbered.depth;
+  // 番地は、自分と同じか内側を閉じてから決める。閉じる前だと、同じ深さの前の条を親と取り違える。
+  while (state.stack.length > 1 && top(state).rank >= rank) state.stack.pop();
+  const draft = { ...draftOf(numbered.kind, addressOf(state, numbered), line, attrs), ordinal: numbered.ordinal };
+  open(state, { draft, rank, numbered });
+};
+
+const openSection = (state: State, line: Line, heading: Heading): void => {
+  while (state.stack.length > 1 && top(state).rank >= heading.depth) state.stack.pop();
+  open(state, { draft: draftOf("section", headingAddress(state, heading.depth), line, { heading: heading.text }), rank: heading.depth });
+};
+
+const LEAVES: readonly { readonly kind: StructureKind; readonly find: (patterns: StructurePatterns, text: string) => readonly Mention[] }[] = [
+  { kind: "definition", find: (patterns, text) => patterns.definitions(text) },
+  { kind: "reference", find: (patterns, text) => patterns.references(text) },
+  { kind: "obligation", find: (patterns, text) => patterns.obligations(text) },
+  { kind: "quantity", find: (patterns, text) => patterns.quantities(text) },
+  { kind: "date", find: (patterns, text) => patterns.dates?.(text) ?? [] },
+];
+
+/** 言語を問わない通し番号。後ろが単位なら数量なので番号にしない。 */
+const universalNumber = (patterns: StructurePatterns, text: string, context: NumberingContext): NumberedLine | undefined => {
+  const dotted = dottedNumber(text, context);
+  return dotted !== undefined && patterns.countedAfter?.(dotted.number, dotted.rest) === true ? undefined : dotted;
+};
+
+/** 行の中の定義・参照・義務・数量を、いま開いている最も内側の節点の子にする。 */
+const addLeaves = (state: State, patterns: StructurePatterns, line: Line, text: string, offset: number): void => {
+  const parent = top(state).draft;
+  const leaves = LEAVES.flatMap(({ kind, find }) =>
+    find(patterns, text).map((mention) => ({ kind, start: line.start + offset + mention.start, end: line.start + offset + mention.end, attrs: mention.attrs })),
+  ).sort((left, right) => left.start - right.start);
+  leaves.forEach((leaf) =>
+    parent.children.push({ kind: leaf.kind, address: "", start: leaf.start, end: leaf.end, line: line.number, attrs: leaf.attrs, children: [] }),
+  );
+};
+
+const extend = (state: State, end: number): void => {
+  state.stack.forEach((frame) => {
+    frame.draft.end = Math.max(frame.draft.end, end);
+  });
+};
+
+const freeze = (draft: Draft): StructureNode => ({
+  kind: draft.kind,
+  address: draft.address,
+  span: { start: draft.start, end: draft.end },
+  line: draft.line,
+  attrs: draft.attrs,
+  children: draft.children.map(freeze),
+  ...(draft.ordinal === undefined ? {} : { ordinal: draft.ordinal }),
+});
+
+/** Markdown から取った手がかり。見出しと、中を読まない範囲（コード）。.txt はどちらも空。 */
+export type Outline = { readonly headings: readonly Heading[]; readonly opaque: readonly Span[] };
+
+export const NO_OUTLINE: Outline = { headings: [], opaque: [] };
+
+export type StructureInput = { readonly path: string; readonly source: string; readonly language: string; readonly outline: Outline };
+
+/** 見出しのある行を、行番号から引けるようにする。見出しごとに全行を探し直さない。 */
+const headingsByLine = (lines: readonly Line[], headings: readonly Heading[]): Map<number, Heading> =>
+  new Map(
+    headings.flatMap((heading) => {
+      const number = lineNumberAt(lines, heading.start);
+      if (number === undefined) return [];
+      const entry: [number, Heading] = [number, heading];
+      return [entry];
+    }),
+  );
+
+/** 見出しの行から「#」の印を外した文字列。コードを覆った後の行から取るので、見出しの中のコードも読まない。 */
+const atxText = (text: string): string => {
+  const body = text
+    .trim()
+    .replace(/^#{1,6}(?=[ \t]|$)/u, "")
+    .trim();
+  const closing = body.search(/[ \t]#+$/u);
+  return (closing === -1 ? body : body.slice(0, closing)).trim();
+};
+
+const readLine = (state: State, patterns: StructurePatterns, line: Line, heading: Heading | undefined): void => {
+  const text = heading === undefined ? line.text : atxText(line.text);
+  const openNumbers = state.stack.flatMap((frame) => (frame.numbered === undefined ? [] : [frame.numbered]));
+  const context = { open: openNumbers, isHeading: heading !== undefined };
+  const numbered = patterns.numbered(text, context) ?? universalNumber(patterns, text, context);
+  // 番号付きの見出しも見出しの通し番号を進める。進めないと、その下の「### 詳細」が前の見出しの番地を名乗る。
+  if (numbered !== undefined && heading !== undefined) headingAddress(state, heading.depth);
+  if (numbered !== undefined) openNumbered(state, line, numbered, heading?.depth);
+  else if (heading !== undefined) openSection(state, line, heading);
+  extend(state, line.start + line.text.length);
+  // 番号付きの行は番号の後ろだけを読む。「第3条（支払）」の「第3条」を自分への参照として拾わない。
+  const scanned = numbered === undefined ? text : numbered.rest;
+  const offset = Math.max(0, line.text.lastIndexOf(scanned));
+  if (scanned !== "") addLeaves(state, patterns, line, scanned, offset);
+};
+
+/**
+ * 文書を番地の付いた木にする。番号の書き方は言語パッケージが読み、ここは入れ子と番地だけを決める。
+ * Markdown では見出しとコードの範囲を使い、.txt は行頭の番号だけで組む。
+ */
+export const buildTree = (input: StructureInput, patterns: StructurePatterns): StructureNode => {
+  const outline = input.outline;
+  // コードは同じ長さの空白で覆ってから読む。コードブロックの行は空になって飛ばされ、
+  // 文中の `第99条` は参照として拾われない。位置は元の文書のまま。
+  const lines = linesOf(maskSpans(input.source, outline.opaque));
+  const headings = headingsByLine(lines, outline.headings);
+  const doc = draftOf("doc", "", { text: "", start: 0, number: 1 }, { path: input.path, language: input.language });
+  doc.end = input.source.length;
+  const state: State = { stack: [{ draft: doc, rank: 0 }], headingCounts: [] };
+  lines.forEach((line) => {
+    if (line.text.trim() !== "") readLine(state, patterns, line, headings.get(line.number));
+    // コードの行は覆って読まないが、開いている節の中身ではある。節の最後にコードブロックがあっても、範囲をそこまで伸ばす。
+    else if (input.source.slice(line.start, line.start + line.text.length).trim() !== "") extend(state, line.start + line.text.length);
+  });
+  return freeze(doc);
+};