chaffjs 0.5.1 → 0.6.0

package/src/structure/cite.ts

@@ -0,0 +1,115 @@
+import type { StructureNode } from "../plugin.ts";
+import { lineStarts, placeOf } from "../position.ts";
+
+// 回答の引用が原文にあるか。番地が木にあり、引用した文がその番地の範囲に書かれていれば一致。
+// 意味が合っているかは見ない。書いてあるかどうかだけを、機械で決める。
+
+export type Citation = { readonly address: string; readonly quote: string };
+
+export type CitationStatus = "ok" | "missing-address" | "quote-elsewhere" | "quote-not-found";
+
+export type CitationResult = {
+  readonly citation: Citation;
+  readonly status: CitationStatus;
+  /** 引用文が原文で見つかった位置の、いちばん内側の番地。quote-elsewhere のとき、本当はどこに書いてあるか。 */
+  readonly foundAt?: string;
+  /** 引用文が見つかった行。引用文が空なら、番地の行。 */
+  readonly line?: number;
+};
+
+/** 比べる形。空白と改行を除き、全角と半角を NFKC で揃える。index は各文字の元の位置。 */
+type Normalized = { readonly text: string; readonly index: readonly number[] };
+
+const WHITESPACE = /^\s+$/u;
+const GRAPHEMES = new Intl.Segmenter("und", { granularity: "grapheme" });
+
+/**
+ * 書記素（見た目の一文字）ごとに NFKC をかける。1 符号単位ずつでは「ｶﾞ」と「ガ」、「ハ」＋濁点と「バ」が揃わない。
+ * NFKC は 1 文字を複数にすることがある（「㈱」→「(株)」）。どれも元の書記素の先頭を指す。
+ */
+const normalize = (source: string): Normalized => {
+  const text: string[] = [];
+  const index: number[] = [];
+  [...GRAPHEMES.segment(source)].forEach(({ segment, index: at }) => {
+    if (WHITESPACE.test(segment)) return;
+    // 位置の表は UTF-16 の単位で持つ。検索（indexOf）がその単位で数えるので、絵文字のような 2 単位の文字でもずれない。
+    const normalized = segment.normalize("NFKC");
+    text.push(normalized);
+    index.push(...Array.from({ length: normalized.length }, () => at));
+  });
+  return { text: text.join(""), index };
+};
+
+type Occurrence = { readonly start: number; readonly last: number };
+
+const within = (node: StructureNode, occurrence: Occurrence): boolean => node.span.start <= occurrence.start && occurrence.last < node.span.end;
+
+type Located = { readonly holding?: Occurrence; readonly earliest?: Occurrence };
+
+/**
+ * key が現れる位置を上から順に見て、候補の番地に収まるものが見つかった時点で止める。見つからなければ最初の位置を返す。
+ * 全部を配列に溜めない。「の」のような短い引用が長い原文に何百万回現れても、覚えるのは二つだけ。
+ * 次は 1 文字先から探す。重なって現れる引用（「ああ」の中の「ああ」）も、どの位置も見落とさない。
+ */
+const locate = (whole: Normalized, key: string, candidates: readonly StructureNode[]): Located => {
+  // 空の key は indexOf がどこまでも位置を返し、終わらなくなる。
+  if (key === "") return {};
+  let earliest: Occurrence | undefined;
+  for (let at = whole.text.indexOf(key); at !== -1; at = whole.text.indexOf(key, at + 1)) {
+    const occurrence = { start: whole.index[at] ?? 0, last: whole.index[at + key.length - 1] ?? 0 };
+    earliest ??= occurrence;
+    if (candidates.some((node) => within(node, occurrence))) return { holding: occurrence, earliest };
+  }
+  return earliest === undefined ? {} : { earliest };
+};
+
+type Addressed = { readonly node: StructureNode; readonly depth: number };
+
+/** 番地を持つ節点と、その深さ。深いほど内側。 */
+const addressedNodes = (tree: StructureNode): Addressed[] => {
+  const found: Addressed[] = [];
+  const pending: Addressed[] = [{ node: tree, depth: 0 }];
+  while (pending.length > 0) {
+    const current = pending.pop();
+    if (current === undefined) break;
+    if (current.node.address !== "") found.push(current);
+    [...current.node.children].reverse().forEach((child) => pending.push({ node: child, depth: current.depth + 1 }));
+  }
+  return found;
+};
+
+/** 引用の全体を含む、いちばん内側の番地。二つの項にまたがる引用なら、両方を含む条。どの番地にも入らなければ undefined。 */
+const innermostHolding = (nodes: readonly Addressed[], occurrence: Occurrence): string | undefined =>
+  nodes
+    .filter(({ node }) => within(node, occurrence))
+    .reduce<Addressed | undefined>((best, current) => (best === undefined || current.depth > best.depth ? current : best), undefined)?.node.address;
+
+/**
+ * 引用を一件ずつ確かめる。source は木を作った原文そのもの。
+ * 引用文が空（空白だけ）なら番地だけを確かめる。同じ番地が二つある（附則が第1条から振り直す）ときは、どちらかにあれば一致。
+ * 原文は一度だけ揃え、引用ごとには番地の範囲を揃え直さない。長い契約書に引用が何百とあっても、引用ごとの代金は原文の長さに比例するだけ。
+ */
+export const checkCitations = (source: string, tree: StructureNode, citations: readonly Citation[]): CitationResult[] => {
+  const nodes = addressedNodes(tree);
+  const byAddress = new Map<string, StructureNode[]>();
+  nodes.forEach(({ node }) => {
+    const same = byAddress.get(node.address) ?? [];
+    same.push(node);
+    byAddress.set(node.address, same);
+  });
+  const whole = normalize(source);
+  const starts = lineStarts(source);
+  return citations.map((citation): CitationResult => {
+    const candidates = byAddress.get(citation.address) ?? [];
+    const first = candidates[0];
+    if (first === undefined) return { citation, status: "missing-address" };
+    const key = normalize(citation.quote).text;
+    if (key === "") return { citation, status: "ok", line: first.line };
+    const { holding, earliest } = locate(whole, key, candidates);
+    if (holding !== undefined) return { citation, status: "ok", line: placeOf(starts, holding.start).line };
+    if (earliest === undefined) return { citation, status: "quote-not-found" };
+    const foundAt = innermostHolding(nodes, earliest);
+    const line = placeOf(starts, earliest.start).line;
+    return { citation, status: "quote-elsewhere", line, ...(foundAt === undefined ? {} : { foundAt }) };
+  });
+};

package/src/structure/issues.ts

@@ -0,0 +1,63 @@
+import type { StructureNode } from "../plugin.ts";
+
+// 木だけで決まる誤り。参照先が無い、番号が飛ぶ・重なる、同じ語を二度定義する。
+// 意味の食い違いは判定しない。書いてあることから機械で決まるものだけを出す。
+
+export type StructureIssue = { readonly offset: number; readonly values: Readonly<Record<string, string | number>> };
+
+const NUMBERED: readonly string[] = ["chapter", "article", "item"];
+
+/** 木を上から順に平らにする。文書の中での順番と同じになる。再帰にしないのは、深い木でスタックを使い切らないため。 */
+export const inDocumentOrder = (tree: StructureNode): StructureNode[] => {
+  const order: StructureNode[] = [];
+  const pending: StructureNode[] = [tree];
+  while (pending.length > 0) {
+    const node = pending.pop();
+    if (node === undefined) break;
+    order.push(node);
+    pending.push(...[...node.children].reverse());
+  }
+  return order;
+};
+
+const textOf = (node: StructureNode, key: string): string => {
+  const value = node.attrs[key];
+  return value === undefined ? "" : String(value);
+};
+
+/**
+ * 参照がこの文書のどこかを指しているか。fallback は言語パッケージが付ける別の行き先で、
+ * 日本語の「第4条第1項」は、番号の無い第 1 項を持つ第4条を指しうる。
+ */
+const resolves = (node: StructureNode, addresses: ReadonlySet<string>): boolean =>
+  addresses.has(textOf(node, "target")) || (node.attrs["fallback"] !== undefined && addresses.has(textOf(node, "fallback")));
+
+/**
+ * 参照の番地が木に無い。他の文書の名前が付いた参照（民法第709条、Section 9 of the Master Agreement）は引かない。
+ * 番号付きのまとまりを 1 つも持たない文書も見ない。他の文書を指しているだけかもしれない。
+ */
+export const danglingReferences = (tree: StructureNode): StructureIssue[] => {
+  const nodes = inDocumentOrder(tree);
+  const addresses = new Set(nodes.filter((node) => NUMBERED.includes(node.kind)).map((node) => node.address));
+  if (addresses.size === 0) return [];
+  return nodes
+    .filter((node) => node.kind === "reference" && node.attrs["document"] === undefined)
+    .filter((node) => !resolves(node, addresses))
+    .map((node) => ({ offset: node.span.start, values: { label: textOf(node, "label"), target: textOf(node, "target") } }));
+};
+
+/** 同じ語の二度目以降の定義。どちらが正しいかは決めず、両方の場所を示す。 */
+export const duplicateDefinitions = (tree: StructureNode): StructureIssue[] => {
+  const first = new Map<string, StructureNode>();
+  return inDocumentOrder(tree)
+    .filter((node) => node.kind === "definition")
+    .flatMap((node) => {
+      const term = textOf(node, "term");
+      const earlier = first.get(term);
+      if (earlier === undefined) {
+        first.set(term, node);
+        return [];
+      }
+      return [{ offset: node.span.start, values: { term, first: earlier.line } }];
+    });
+};

package/src/structure/lines.ts

@@ -0,0 +1,32 @@
+/** 1 行。text は改行を含まず、\r\n の \r も落としてある。start は元の文書での位置。 */
+export type Line = { readonly text: string; readonly start: number; readonly number: number };
+
+/**
+ * 行に分ける。位置は元の文字列のまま数える。
+ * Windows で書かれた契約書は \r\n で届くので、\r を本文に残すと行末の判定がずれる。
+ * 行ごとに配列を作り直さない。何万行もある契約書で二乗に遅くなるため。
+ */
+export const linesOf = (source: string): Line[] => {
+  const lines: Line[] = [];
+  let at = 0;
+  source.split("\n").forEach((raw, index) => {
+    lines.push({ text: raw.endsWith("\r") ? raw.slice(0, -1) : raw, start: at, number: index + 1 });
+    at += raw.length + 1;
+  });
+  return lines;
+};
+
+/** offset を含む行の番号（1 始まり）。lines は start の昇順。二分探索で、行数に対して対数で引く。 */
+export const lineNumberAt = (lines: readonly Line[], offset: number): number | undefined => {
+  let low = 0;
+  let high = lines.length - 1;
+  while (low <= high) {
+    const middle = (low + high) >> 1;
+    const line = lines[middle];
+    if (line === undefined) return undefined;
+    if (offset < line.start) high = middle - 1;
+    else if (offset > line.start + line.text.length) low = middle + 1;
+    else return line.number;
+  }
+  return undefined;
+};

package/src/structure/markdown-path.ts

@@ -0,0 +1,6 @@
+import { extname } from "node:path";
+
+const MARKDOWN = [".md", ".markdown", ".mdx"];
+
+/** 見出しとコードの範囲を Markdown として読むか。.txt の契約書は行頭の番号だけで木にする。 */
+export const isMarkdownPath = (path: string): boolean => MARKDOWN.includes(extname(path).toLowerCase());

package/src/structure/numbering.ts

@@ -0,0 +1,44 @@
+import type { StructureNode } from "../plugin.ts";
+import { inDocumentOrder, type StructureIssue } from "./issues.ts";
+
+const labelOf = (node: StructureNode): string => String(node.attrs["label"] ?? node.address);
+
+type Ordered = { readonly node: StructureNode; readonly ordinal: number };
+
+/** 同じ親の子のうち、番号の付いたものを種類ごとに分ける。条と項は別の並び。 */
+const sequencesOf = (parent: StructureNode): Ordered[][] => {
+  const groups = new Map<string, Ordered[]>();
+  parent.children.forEach((node) => {
+    if (node.ordinal === undefined) return;
+    // 配列を作り直さずに足す。条が何千もある法令で二乗にしない。
+    const group = groups.get(node.kind) ?? [];
+    group.push({ node, ordinal: node.ordinal });
+    groups.set(node.kind, group);
+  });
+  return [...groups.values()];
+};
+
+/** 隣り合う二つの番号が、1 つ進んでいなければ指摘する。同じ番号なら重なり、飛べば抜け。 */
+const breaksIn = (sequence: readonly Ordered[]): StructureIssue[] =>
+  sequence.flatMap((current, index) => {
+    const previous = sequence[index - 1];
+    // 1 に戻ったら新しい並び。一つの条に (a)(b) の箇条書きが二つある、附則が第1条から振り直す、のどちらも誤りではない。
+    if (previous === undefined || current.ordinal === previous.ordinal + 1 || current.ordinal === 1) return [];
+    return [
+      {
+        offset: current.node.span.start,
+        values: { previous: labelOf(previous.node), label: labelOf(current.node), expected: previous.ordinal + 1, found: current.ordinal },
+      },
+    ];
+  });
+
+/**
+ * 番号の抜けと重なり。比べるのは同じ親の子どうしだけ。英米の法令は章ごとに Section 101、201 と百の位を変えるので、
+ * 文書全体の通し番号として比べると抜けに見える。最初の番号は見ない。日本語の項は 2 から番号を振る。
+ * 1 に戻った番号は新しい並びの始まりとして扱うので、「(a) の後の (a)」の重なりは見逃す。
+ */
+export const numberingBreaks = (tree: StructureNode): StructureIssue[] =>
+  inDocumentOrder(tree)
+    .flatMap(sequencesOf)
+    .flatMap(breaksIn)
+    .sort((left, right) => left.offset - right.offset);

package/src/structure/of.ts

@@ -0,0 +1,15 @@
+import { markdownOutline } from "../document.ts";
+import type { StructureNode, StructurePatterns } from "../plugin.ts";
+import { buildTree, NO_OUTLINE } from "./build.ts";
+
+export type SourceInput = { readonly path: string; readonly source: string; readonly language: string; readonly markdown: boolean };
+
+/**
+ * 文字列から木を作る。Markdown なら見出しとコードの範囲を先に取る。
+ * lint は文書モデルを作るときの解析を使い回すので、ここを通らずに buildTree を呼ぶ。
+ */
+export const buildStructure = (input: SourceInput, patterns: StructurePatterns): StructureNode =>
+  buildTree(
+    { path: input.path, source: input.source, language: input.language, outline: input.markdown ? markdownOutline(input.source) : NO_OUTLINE },
+    patterns,
+  );

package/src/structure/sexp.ts

@@ -0,0 +1,28 @@
+import type { StructureNode } from "../plugin.ts";
+
+/** 文字列は二重引用符で囲み、中の \ と " だけを逃がす。改行は \n にして 1 行に保つ。 */
+const quote = (text: string): string => `"${text.replace(/\\/gu, "\\\\").replace(/"/gu, '\\"').replace(/\r?\n/gu, "\\n")}"`;
+
+const atom = (value: string | number): string => (typeof value === "number" ? String(value) : quote(value));
+
+/** 属性はキーの順に並べる。同じ木から毎回同じ文字列を出すため。 */
+const keywords = (node: StructureNode): string[] => [
+  ...Object.keys(node.attrs)
+    .sort((left, right) => left.localeCompare(right, "en"))
+    .flatMap((key) => {
+      const value = node.attrs[key];
+      return value === undefined ? [] : [`:${key} ${atom(value)}`];
+    }),
+  `:line ${String(node.line)}`,
+];
+
+/**
+ * 木を S 式にする。人と AI が読むための形で、JSON と同じ木から作る。
+ * `(kind "番地" :key value ... 子)`。番地を持たない葉は番地を書かない。
+ */
+export const toSexp = (node: StructureNode, indent = ""): string => {
+  const head = [node.kind, ...(node.address === "" ? [] : [quote(node.address)]), ...keywords(node)].join(" ");
+  if (node.children.length === 0) return `${indent}(${head})`;
+  const inner = node.children.map((child) => toSexp(child, `${indent}  `)).join("\n");
+  return `${indent}(${head}\n${inner})`;
+};

package/src/structure/universal.ts

@@ -0,0 +1,21 @@
+import type { NumberedLine, NumberingContext } from "../plugin.ts";
+
+/**
+ * 「4.2 設定」「3.1.4 Scope」のような通し番号。数字と点だけで書くので言語を問わない。
+ * 各部分を 3 桁・深さを 6 までに抑え、後戻りが爆発しない形にしてある。
+ */
+const DOTTED = /^[ \t]{0,3}(?<number>\d{1,3}(?:\.\d{1,3}){0,5})\.?[ \t\u3000]+(?<rest>\S.*)$/u;
+
+/**
+ * 本文の「1. 」は箇条書きで、見出しの「1. 」は章番号。点を含まない番号は、見出しの行でだけ読む。
+ * 「4.2 」のように点を含むものは、.txt の仕様書でも見出しとして書かれるので本文でも読む。
+ */
+export const dottedNumber = (line: string, context: NumberingContext): NumberedLine | undefined => {
+  const groups = DOTTED.exec(line)?.groups;
+  const number = groups?.["number"];
+  if (number === undefined) return undefined;
+  const depth = number.split(".").length;
+  if (depth < 2 && !context.isHeading) return undefined;
+  const rest = groups?.["rest"]?.trim() ?? "";
+  return { kind: "article", depth, number, absolute: true, label: number, heading: rest, rest, ordinal: Number(number.split(".").at(-1)) };
+};