chaffjs 0.28.0 → 0.30.0

package/src/commands/cite.ts

@@ -1,55 +1,39 @@
-import { checkCitations, type Citation, type CitationResult } from "../structure/cite.ts";
+import { dirname, isAbsolute, join } from "node:path";
+import { checkCitations, isAnywhere, type CitationResult } from "../structure/cite.ts";
+import { bySource, parseCitations, sourceOf, sourceProblem, type Claim } from "./cite-claims.ts";
+import { runScaffold } from "./cite-scaffold.ts";
+import { isWebSource, readPageTree, type CiteContext } from "./cite-page.ts";
 import { readSource, readTree, type TreeContext } from "./tree.ts";
-import type { Texts, UiLanguage } from "../ui.ts";
+import type { Texts } from "../ui.ts";
 
 const FORMATS: ReadonlySet<string> = new Set(["text", "json"]);
 const QUOTE_WIDTH = 40;
-const VALUED: ReadonlySet<string> = new Set(["--format", "--language", "--genre"]);
+const VALUED: ReadonlySet<string> = new Set(["--format", "--language", "--genre", "--url"]);
 
 export const citeTargets = (argv: readonly string[]): string[] =>
   argv.slice(1).filter((arg, index, all) => !arg.startsWith("--") && !VALUED.has(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, ui: UiLanguage): { readonly value: unknown } | { readonly error: string } => {
-  try {
-    return { value: JSON.parse(text) };
-  } catch (err) {
-    return { error: TEXT[ui].notJson(err instanceof Error ? err.message : String(err)) };
-  }
-};
-
-/** 引用の一覧。[{ address, quote }] の配列だけを受け取る。形が違えば理由を返す。 */
-export const parseCitations = (text: string, ui: UiLanguage = "ja"): ParsedCitations => {
-  const parsed = parseJson(text, ui);
-  if ("error" in parsed) return parsed;
-  if (!Array.isArray(parsed.value)) return { error: TEXT[ui].notArray };
-  const entries: readonly unknown[] = parsed.value;
-  const bad = entries.findIndex((entry) => !isCitation(entry));
-  if (bad !== -1) return { error: TEXT[ui].badEntry(bad + 1) };
-  return { citations: entries.filter(isCitation).map((entry) => ({ address: entry.address, quote: entry.quote })) };
-};
-
 type CiteText = {
   readonly usage: string;
   readonly quoted: (text: string) => string;
-  readonly notJson: (why: string) => string;
-  readonly notArray: string;
-  readonly badEntry: (n: number) => string;
+  readonly anywhere: string;
+  readonly foundAt: (parts: readonly string[]) => string;
+  readonly line: (line: number) => string;
   readonly results: Readonly<Record<CitationResult["status"], (result: CitationResult) => string>>;
 };
 
 const TEXT: Texts<CiteText> = {
   ja: {
     quoted: (text) => `「${text}」`,
-    usage: "使い方: chaff cite <原文> <引用.json> [--format text|json] [--language ja|en|…]",
-    notJson: (why) => `JSON として読めません: ${why}`,
-    notArray: '引用は配列で渡してください: [{ "address": "3.2", "quote": "…" }]',
-    badEntry: (n) => `${String(n)} 件目に address（文字列）と quote（文字列）がありません`,
+    usage: [
+      "使い方: chaff cite <原文> <引用.json> [--format text|json] [--language ja|en|…]",
+      "        chaff cite --url <URL> <引用.json> （原文が Web のページのとき）",
+      "        chaff cite <引用.json>            （引用ごとに source で原文のファイルか URL を書いたとき）",
+      "        chaff cite --scaffold <文書>      （出典の無い引用から引用.json のひな形を作る）",
+    ].join("\n"),
+    anywhere: "（番地なし）",
+    foundAt: (parts) => `（${parts.join("、")}）`,
+    line: (line) => `${String(line)} 行目`,
     results: {
       ok: () => "一致",
       "missing-address": (result) => `番地 ${result.citation.address} は原文にありません`,
@@ -60,10 +44,15 @@ const TEXT: Texts<CiteText> = {
   },
   en: {
     quoted: (text) => ` "${text}"`,
-    usage: "usage: chaff cite <source> <quotes.json> [--format text|json] [--language ja|en|…]",
-    notJson: (why) => `Not valid JSON: ${why}`,
-    notArray: 'Give the quotations as an array: [{ "address": "3.2", "quote": "…" }]',
-    badEntry: (n) => `Entry ${String(n)} needs address (a string) and quote (a string)`,
+    usage: [
+      "usage: chaff cite <source> <quotes.json> [--format text|json] [--language ja|en|…]",
+      "       chaff cite --url <URL> <quotes.json> (the source is a web page)",
+      "       chaff cite <quotes.json>             (each quotation names its source, a file or a URL)",
+      "       chaff cite --scaffold <document>     (a quotes.json to fill in, from the quotations with no source)",
+    ].join("\n"),
+    anywhere: "(anywhere)",
+    foundAt: (parts) => ` (${parts.join(", ")})`,
+    line: (line) => `line ${String(line)}`,
     results: {
       ok: () => "matches",
       "missing-address": (result) => `address ${result.citation.address} is not in the source`,
@@ -74,34 +63,114 @@ const TEXT: Texts<CiteText> = {
   },
 };
 
+/** Where a quote given no address was found, so the reader can write the address in. */
+const whereFound = (result: CitationResult, text: CiteText): string => {
+  if (result.status !== "ok" || !isAnywhere(result.citation) || result.line === undefined) return "";
+  return text.foundAt([...(result.foundAt === undefined ? [] : [result.foundAt]), text.line(result.line)]);
+};
+
+/** A claim that names its own source says which, before its address. */
+const sourcePrefix = (result: CitationResult): string => {
+  const source = sourceOf(result.citation);
+  return source === undefined ? "" : `${source} `;
+};
+
 const describe = (result: CitationResult, text: CiteText): 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}${text.quoted(quote)}: ${text.results[result.status](result)}`;
+  const address = isAnywhere(result.citation) ? text.anywhere : result.citation.address;
+  return `${mark} ${sourcePrefix(result)}${address}${text.quoted(quote)}: ${text.results[result.status](result)}${whereFound(result, text)}`;
+};
+
+/** Each claim checked against one source, a file or a web page. undefined when it cannot be read as a tree (already said why). */
+const checkAgainst = async (
+  location: string,
+  claims: readonly Claim[],
+  argv: readonly string[],
+  context: CiteContext,
+): Promise<CitationResult[] | undefined> => {
+  const read = isWebSource(location) ? await readPageTree(location, argv, context) : await readTree(location, argv, context);
+  return read === undefined ? undefined : checkCitations(read.source, read.tree, claims);
+};
+
+/** A claim's source, read from where the claims file is: a scaffold sits next to the document that quotes. A URL is a URL. */
+const sourcePath = (claimsPath: string, source: string): string => {
+  if (isWebSource(source)) return source;
+  // A claims file written on Windows says sources\talk.md; it names the same file everywhere.
+  const portable = source.replaceAll("\\", "/");
+  return isAbsolute(portable) ? portable : join(dirname(claimsPath), portable);
+};
+
+/**
+ * Each claim checked against the source it names, in the claims file's order. Sources are read one at a time, so what
+ * an unreadable one prints comes in the same order every run; any unreadable source fails the run.
+ */
+const checkEachSource = async (
+  claimsPath: string,
+  claims: readonly Claim[],
+  argv: readonly string[],
+  context: CiteContext,
+): Promise<CitationResult[] | undefined> => {
+  const groups = bySource(claims);
+  const checked = await groups.reduce<Promise<(CitationResult[] | undefined)[]>>(async (previous, group) => {
+    const done = await previous;
+    return [...done, await checkAgainst(sourcePath(claimsPath, group.source), group.claims, argv, context)];
+  }, Promise.resolve([]));
+  const byClaim = new Map<Claim, CitationResult>();
+  const unread = groups.some((group, index) => {
+    const results = checked[index];
+    results?.forEach((result, at) => byClaim.set(group.claims[at] ?? result.citation, result));
+    return results === undefined;
+  });
+  return unread ? undefined : claims.flatMap((claim) => byClaim.get(claim) ?? []);
+};
+
+const readClaims = async (claimsPath: string, sourceGiven: boolean, context: TreeContext): Promise<readonly Claim[] | undefined> => {
+  const text = await readSource(claimsPath, context);
+  if (text === undefined) return undefined;
+  const ui = context.ui ?? "ja";
+  const parsed = parseCitations(text, ui);
+  const problem = "error" in parsed ? parsed.error : sourceProblem(parsed.citations, sourceGiven, ui);
+  if (problem === undefined && "citations" in parsed) return parsed.citations;
+  console.error(`${claimsPath}: ${problem ?? ""}`);
+  return undefined;
+};
+
+const usageError = (text: CiteText): number => {
+  console.error(text.usage);
+  return 1;
+};
+
+/** The claims file, and the one source the command line gives (a file, or a page after --url), if any. */
+type Run = { readonly claimsPath: string; readonly sourceGiven: string | undefined };
+
+/** What the arguments ask to check, or undefined when they do not fit any usage. */
+const runOf = (targets: readonly string[], argv: readonly string[], context: CiteContext): Run | undefined => {
+  const url = context.flag(argv, "--url");
+  if (argv.includes("--url") && (url === undefined || !isWebSource(url))) return undefined;
+  const claimsPath = targets.at(-1);
+  if (claimsPath === undefined || targets.length > (url === undefined ? 2 : 1)) return undefined;
+  return { claimsPath, sourceGiven: url ?? (targets.length === 2 ? targets[0] : undefined) };
 };
 
 /**
- * 回答の引用が原文にあるかを確かめる。書き換えはしない。
+ * 回答の引用が原文にあるかを確かめる。書き換えはしない。原文は引数で一つ渡すか、引用ごとに source で書く。
  * 一つでも外れていれば 1 で終わるので、AI の回答を単体試験のように検査できる。
  */
-export const runCite = async (targets: readonly string[], argv: readonly string[], context: TreeContext): Promise<number> => {
-  const [sourcePath, citationsPath] = targets;
+export const runCite = async (targets: readonly string[], argv: readonly string[], context: CiteContext): Promise<number> => {
+  const text = TEXT[context.ui ?? "ja"];
   const format = context.flag(argv, "--format") ?? "text";
-  if (sourcePath === undefined || citationsPath === undefined || targets.length !== 2 || !FORMATS.has(format)) {
-    console.error(TEXT[context.ui ?? "ja"].usage);
-    return 1;
-  }
-  const citationsText = await readSource(citationsPath, context);
-  if (citationsText === undefined) return 1;
-  const parsed = parseCitations(citationsText, context.ui ?? "ja");
-  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((result) => describe(result, TEXT[context.ui ?? "ja"])).join("\n"));
+  if (!FORMATS.has(format)) return usageError(text);
+  // The scaffold is always JSON: it is a file to fill in.
+  if (argv.includes("--scaffold")) return argv.includes("--url") ? usageError(text) : runScaffold(targets, argv, context, text.usage);
+  const run = runOf(targets, argv, context);
+  if (run === undefined) return usageError(text);
+  const { claimsPath, sourceGiven } = run;
+  const claims = await readClaims(claimsPath, sourceGiven !== undefined, context);
+  if (claims === undefined) return 1;
+  const results = sourceGiven === undefined ? await checkEachSource(claimsPath, claims, argv, context) : await checkAgainst(sourceGiven, claims, argv, context);
+  if (results === undefined) return 1;
+  console.log(format === "json" ? JSON.stringify(results, null, 2) : results.map((result) => describe(result, text)).join("\n"));
   return results.every((result) => result.status === "ok") ? 0 : 1;
 };

package/src/company-names.ts

@@ -0,0 +1,202 @@
+import { nameKey } from "./name-variants.ts";
+import { escapeRegExp } from "./orthography.ts";
+
+// 会社の名前を、文書の中で二通りに書いた所（株式会社アオバシステム と アオバシステム株式会社、Aoba Systems Inc. と Aoba Systems Ltd.）。
+// 会社の形の語（株式会社、Inc）は語彙表 company-form が言う。group が同じ語は同じ形（Inc と Incorporated、株式会社 と (株)）、
+// position は名前のどちら側に立つか（無ければどちらにも立つ）。名前の部分は、形の語のすぐ隣の、名前に使う字の連なり。
+
+export type CompanyForm = { readonly pattern: string; readonly group: string; readonly position?: "before" | "after" | undefined };
+
+/** surface は形の語も含めた書いたまま。base は名前の部分、form は形の組、position は形の語が名前のどちら側にあるか。 */
+export type CompanyMention = {
+  readonly surface: string;
+  readonly offset: number;
+  readonly base: string;
+  readonly form: string;
+  readonly position: "before" | "after";
+};
+
+/** 二つの書き方の違い。spelling は記号・幅・大小だけ、form は会社の形、position は形の語の側、near は名前の一字違い。 */
+type CompanyRelation = "spelling" | "form" | "position" | "near";
+
+type CompanyVariant = { readonly mention: CompanyMention; readonly usual: string; readonly kind: CompanyRelation };
+
+/** 名前の部分が、品詞解析が固有名詞と読んだ語に掛かるか。漢字だけの名前（清算、当該）は、ふつうの語と区別がつかない。 */
+export type IsProper = (start: number, end: number) => boolean;
+
+const LATIN = /\p{Script=Latin}/u;
+const LETTER = /\p{L}/u;
+/** 漢字・かなの名前に使う字。ひらがなは名前の外（の、は、まで）。 */
+const CJK_NAME = /[\p{Script=Katakana}\p{Script=Han}\p{Script=Latin}\p{N}ー・&＆]/u;
+const NOT_HAN_LETTER = /(?!\p{Script=Han})\p{L}/u;
+/** 英字の名前の一語。大文字か数字で始まる。 */
+const LATIN_WORD = /^[\p{Lu}\p{N}][\p{L}\p{N}&'’.-]*$/u;
+const AMPERSAND = "&";
+/** 形の語のすぐあとに空白一つで大文字の語が続けば、形の語は長い名前の一部（Limited Partnership、Corporation Tax）。Inc. のあとの文や行は続きでない。 */
+const CONTINUED = /^ \p{Lu}/u;
+
+const occurrencesOf = (source: string, pattern: string): number[] => [...source.matchAll(new RegExp(escapeRegExp(pattern), "gu"))].map((match) => match.index);
+
+/** 英字の語の続き。ハイフンでつないだ語（Limited-time）も一つの語。 */
+const WORD_CONTINUES = /[\p{L}\p{N}-]/u;
+
+/** 英字の形の語は、語の続き（Including の Inc、Limited-time の Limited）では形の語と読まない。 */
+const standsAsWord = (source: string, pattern: string, at: number): boolean =>
+  !LATIN.test(pattern) || (!LETTER.test(source.charAt(at - 1)) && !WORD_CONTINUES.test(source.charAt(at + pattern.length)));
+
+type Span = { readonly start: number; readonly end: number };
+
+/** 英字の名前: 形の語の前の、大文字で始まる語の続き。頭の、固有名詞と読めない語（文頭の Contact）は外す。 */
+const latinBaseBefore = (source: string, end: number, isProper: IsProper): Span | undefined => {
+  const before = source.slice(0, end).replace(/,?\s$/u, "");
+  const words = [...before.matchAll(/\S+/gu)].map((match): Span => ({ start: match.index, end: match.index + match[0].length }));
+  const isNameWord = (span: Span): boolean => {
+    const word = source.slice(span.start, span.end);
+    return LATIN_WORD.test(word) || word === AMPERSAND;
+  };
+  const run = words.slice(
+    words.findLastIndex((span, index) => !isNameWord(span) || before.slice(span.end, words[index + 1]?.start ?? before.length).includes("\n")) + 1,
+  );
+  const first = run.find((span) => isProper(span.start, span.end));
+  return first === undefined ? undefined : { start: first.start, end: before.length };
+};
+
+const CJK_BEFORE = new RegExp(`${CJK_NAME.source}+$`, "u");
+const CJK_AFTER = new RegExp(`^${CJK_NAME.source}+`, "u");
+const SPACES: ReadonlySet<string> = new Set([" ", "\u3000"]);
+
+/** 漢字・かなの名前: 形の語の隣の、名前に使う字の続き。形の語との間の空白一つは名前の外。 */
+const cjkBaseBefore = (source: string, end: number): Span | undefined => {
+  const stop = SPACES.has(source.charAt(end - 1)) ? end - 1 : end;
+  const match = CJK_BEFORE.exec(source.slice(0, stop));
+  return match === null ? undefined : { start: match.index, end: stop };
+};
+
+const cjkBaseAfter = (source: string, start: number): Span | undefined => {
+  const from = SPACES.has(source.charAt(start)) ? start + 1 : start;
+  const match = CJK_AFTER.exec(source.slice(from));
+  return match === null ? undefined : { start: from, end: from + match[0].length };
+};
+
+/** 名前の部分の字数。一字（法令の項目の印 イ、ロ）は名前と読まない。 */
+const MIN_BASE_LENGTH = 2;
+
+/** 名前と読めるか。二字以上で、記号で始まり終わらず、漢字だけなら固有名詞と読めるもの。 */
+const isNameBase = (source: string, span: Span, isProper: IsProper): boolean => {
+  const base = source.slice(span.start, span.end);
+  if ([...base].length < MIN_BASE_LENGTH || /^[・&＆]|[・&＆]$/u.test(base)) return false;
+  return NOT_HAN_LETTER.test(base) || isProper(span.start, span.end);
+};
+
+const mentionOf = (source: string, base: Span, form: Span, group: string): CompanyMention => {
+  const position = form.start < base.start ? "before" : "after";
+  const [start, end] = [Math.min(base.start, form.start), Math.max(base.end, form.end)];
+  return { surface: source.slice(start, end), offset: start, base: source.slice(base.start, base.end), form: group, position };
+};
+
+const baseBefore = (source: string, at: number, latin: boolean, isProper: IsProper): Span | undefined =>
+  latin ? latinBaseBefore(source, at, isProper) : cjkBaseBefore(source, at);
+
+/** 形の語の一つの現れから、会社の名前の現れ。名前が前にあればそれを、無ければ後ろを取る。 */
+const mentionAt = (source: string, form: CompanyForm, at: number, isProper: IsProper): CompanyMention | undefined => {
+  const formSpan = { start: at, end: at + form.pattern.length };
+  const latin = LATIN.test(form.pattern);
+  if (latin && CONTINUED.test(source.slice(formSpan.end))) return undefined;
+  const before = form.position === "before" ? undefined : baseBefore(source, at, latin, isProper);
+  if (before !== undefined && isNameBase(source, before, isProper)) return mentionOf(source, before, formSpan, form.group);
+  const after = form.position === "after" || latin ? undefined : cjkBaseAfter(source, formSpan.end);
+  return after !== undefined && isNameBase(source, after, isProper) ? mentionOf(source, after, formSpan, form.group) : undefined;
+};
+
+/** 文書の中の会社の名前の現れ。長い形の語（Co., Ltd）を先に取り、その中の短い語（Ltd）は数えない。 */
+export const companyMentionsIn = (source: string, forms: readonly CompanyForm[], isProper: IsProper): CompanyMention[] => {
+  const taken: Span[] = [];
+  return forms
+    .toSorted((left, right) => right.pattern.length - left.pattern.length)
+    .flatMap((form) =>
+      occurrencesOf(source, form.pattern).flatMap((at) => {
+        const end = at + form.pattern.length;
+        if (!standsAsWord(source, form.pattern, at) || taken.some((span) => span.start < end && at < span.end)) return [];
+        taken.push({ start: at, end });
+        const mention = mentionAt(source, form, at, isProper);
+        return mention === undefined ? [] : [mention];
+      }),
+    )
+    .toSorted((left, right) => left.offset - right.offset);
+};
+
+const MIN_SLIP_LENGTH = 7;
+
+const spliced = (chars: readonly string[], at: number, count: number): string => chars.toSpliced(at, count).join("");
+const firstDifference = (left: readonly string[], right: readonly string[]): number => left.findIndex((char, index) => char !== right[index]);
+
+/** 一字の抜けなら、その字。 */
+const droppedChars = (longer: readonly string[], shorter: readonly string[]): string[] | undefined => {
+  if (longer.length !== shorter.length + 1) return undefined;
+  const at = firstDifference(longer, shorter);
+  return spliced(longer, at, 1) === shorter.join("") ? [longer[at] ?? ""] : undefined;
+};
+
+/** 一字の置き換えか、隣どうしの入れ替えなら、その字。 */
+const replacedChars = (left: readonly string[], right: readonly string[]): string[] | undefined => {
+  const at = firstDifference(left, right);
+  const changed = [left[at] ?? "", right[at] ?? ""];
+  if (left.length !== right.length || at < 0) return undefined;
+  if (spliced(left, at, 1) === spliced(right, at, 1)) return changed;
+  const swapped = left[at] === right[at + 1] && left[at + 1] === right[at] && spliced(left, at, 2) === spliced(right, at, 2);
+  return swapped ? changed : undefined;
+};
+
+/**
+ * 名前の部分が一字違いか（置き換え・抜け・隣どうしの入れ替え）。違う字が漢字なら見ない。漢字の一字違い（日本電気 と 日本電機）
+ * は別の会社のことがある。短い名前（Alpha と Alpho）も別の会社のことが多い。
+ */
+const isSlip = (left: string, right: string): boolean => {
+  const [leftChars, rightChars] = [[...left], [...right]];
+  if (Math.min(leftChars.length, rightChars.length) < MIN_SLIP_LENGTH) return false;
+  const changed = replacedChars(leftChars, rightChars) ?? droppedChars(leftChars, rightChars) ?? droppedChars(rightChars, leftChars);
+  return changed !== undefined && changed.every((char) => NOT_HAN_LETTER.test(char));
+};
+
+/** 名前の部分が同じ二つ。同じ形の短い書き方と長い書き方（株式会社 と (株)、Inc と Incorporated）は書き分けと見ない。 */
+const sameNameRelation = (left: CompanyMention, right: CompanyMention): CompanyRelation | undefined => {
+  if (left.form !== right.form) return "form";
+  if (left.position !== right.position) return "position";
+  return nameKey(left.surface) === nameKey(right.surface) ? "spelling" : undefined;
+};
+
+/**
+ * 二つの書き方が、同じ会社を二通りに書いたものか。名前の部分が同じ（記号・幅・大小を除いて）なら、形の組か形の語の側の違い、
+ * どちらも同じなら記号・幅・大小だけの違い。名前の部分が違うのは、形も側も同じで、漢字でない字の一字違いのときだけ（Aoba Systems と
+ * Aoba System）。名前の違う会社（親会社と子会社、別の取引先）は、名前の部分が一字より多く違うので同じと見ない。
+ */
+export const companyRelation = (left: CompanyMention, right: CompanyMention): CompanyRelation | undefined => {
+  if (left.surface === right.surface) return undefined;
+  const [leftKey, rightKey] = [nameKey(left.base), nameKey(right.base)];
+  if (leftKey === rightKey) return sameNameRelation(left, right);
+  return left.form === right.form && left.position === right.position && isSlip(leftKey, rightKey) ? "near" : undefined;
+};
+
+type Tally = { readonly first: CompanyMention; readonly count: number };
+
+const talliesOf = (mentions: readonly CompanyMention[]): Tally[] => {
+  const tallies = new Map<string, Tally>();
+  mentions.forEach((mention) => {
+    const tally = tallies.get(mention.surface);
+    tallies.set(mention.surface, { first: tally?.first ?? mention, count: (tally?.count ?? 0) + 1 });
+  });
+  return [...tallies.values()];
+};
+
+/** 多いほうが先。同数なら先に書いたほう。 */
+const byUsage = (left: Tally, right: Tally): number => right.count - left.count || left.first.offset - right.first.offset;
+
+/** 同じ会社の、少ないほうの書き方。同じ会社と言える相手のうち一番多いものと比べる。書き方ごとに最初の現れを一つ。 */
+export const companyVariants = (mentions: readonly CompanyMention[]): CompanyVariant[] => {
+  const tallies = talliesOf(mentions);
+  return tallies.flatMap((tally) => {
+    const [usual] = tallies.filter((other) => other === tally || companyRelation(tally.first, other.first) !== undefined).toSorted(byUsage);
+    const kind = usual === undefined || usual === tally ? undefined : companyRelation(tally.first, usual.first);
+    return usual === undefined || kind === undefined ? [] : [{ mention: tally.first, usual: usual.first.surface, kind }];
+  });
+};

package/src/default-values.ts

@@ -0,0 +1,158 @@
+// One parameter's default stated two ways on a page: the signature says `width = 72`, the options table says 72, and the
+// prose says "`width` defaults to 80". Pure; reads the Markdown source. The words of a default column (Default, 既定値)
+// and of a default in prose (defaults to, の既定値は) come from the language's lexicons.
+import { codeFences } from "./detectors/code-fences.ts";
+
+/** Where a default is stated, from the most to the least authoritative: the code, a table, a sentence. */
+type Source = "code" | "table" | "prose";
+type Stated = { readonly name: string; readonly value: string; readonly offset: number; readonly source: Source };
+
+/** A default that disagrees with the one the code (or else a table) states. */
+export type DefaultSlip = { readonly name: string; readonly value: string; readonly offset: number; readonly expected: string };
+
+export type DefaultWords = { readonly headers: readonly string[]; readonly phrases: readonly string[] };
+
+type Line = { readonly text: string; readonly start: number };
+
+const RANK: Readonly<Record<Source, number>> = { code: 0, table: 1, prose: 2 };
+/** The values read: a code span, a quoted string, or a literal (a number, true, false, null). */
+const QUOTED: readonly RegExp[] = [/^`([^`]+)`/u, /^"([^"]*)"/u, /^'([^']*)'/u];
+const LITERAL = /^(?:-?\d+(?:\.\d+)?|true|false|True|False|null|none|None|undefined)(?!\w|\.\d)/u;
+const NAME_SPAN = /`([A-Za-z_$][\w$]*)`/gu;
+const IDENTIFIER = /^[A-Za-z_$][\w$]*/u;
+const SPREAD = /^(?:\.\.\.|\*{1,2})/u;
+/** How far after the name a default phrase may start: "`width` defaults to", "`width` の既定値は". */
+const PHRASE_REACH = 4;
+/** A declaration, not a call: a keyword first, or a return type after the list. A call's width=40 is an argument. */
+const KEYWORD_FIRST = /^[ \t]*(?:(?:export|async)[ \t]+)*(?:def|function\*?|fn|func)[ \t]/u;
+const RETURN_TYPE = /\)[ \t]*(?::|->)/u;
+const DELIMITER_ROW = /^[ \t|:-]+$/u;
+
+const linesOf = (source: string): Line[] => {
+  const starts = [0, ...[...source.matchAll(/\n/gu)].map((match) => match.index + 1)];
+  return starts.map((start, index) => ({ text: source.slice(start, (starts[index + 1] ?? source.length + 1) - 1), start }));
+};
+
+const valueAt = (text: string): string | undefined => {
+  const trimmed = text.trimStart();
+  const quoted = QUOTED.map((pattern) => pattern.exec(trimmed)?.[1]).find((value) => value !== undefined);
+  return quoted ?? LITERAL.exec(trimmed)?.[0];
+};
+
+/** The text between a line's first ( and the ) that closes it. */
+const parameterList = (text: string): { readonly list: string; readonly from: number } | undefined => {
+  const open = text.indexOf("(");
+  const state = { depth: 0, close: -1 };
+  Array.from(text.slice(open)).some((char, index) => {
+    if (char === "(") state.depth += 1;
+    if (char === ")") state.depth -= 1;
+    if (state.depth === 0) state.close = open + index;
+    return state.depth === 0;
+  });
+  return open === -1 || state.close === -1 ? undefined : { list: text.slice(open + 1, state.close), from: open + 1 };
+};
+
+/** width = 72, width: int = 72, *args: a parameter's name and its default value, if it has one. */
+const parameterDefault = (part: string): { readonly name: string; readonly value: string } | undefined => {
+  const trimmed = part.trim().replace(SPREAD, "");
+  const name = IDENTIFIER.exec(trimmed)?.[0];
+  const equals = trimmed.search(/=(?!=)/u);
+  const value = equals === -1 ? undefined : valueAt(trimmed.slice(equals + 1));
+  return name === undefined || value === undefined ? undefined : { name, value };
+};
+
+const QUOTES = "\"'`";
+
+/** A parameter list split at its commas, leaving a comma inside quotes or brackets (sep = ", ") in its parameter. */
+const splitParameters = (list: string): string[] => {
+  const state = { quote: "", depth: 0, from: 0 };
+  const parts: string[] = [];
+  [...list].forEach((char, index) => {
+    if (state.quote !== "") {
+      if (char === state.quote) state.quote = "";
+      return;
+    }
+    if (QUOTES.includes(char)) state.quote = char;
+    if ("([{".includes(char)) state.depth += 1;
+    if (")]}".includes(char)) state.depth -= 1;
+    if (char !== "," || state.depth !== 0) return;
+    parts.push(list.slice(state.from, index));
+    state.from = index + 1;
+  });
+  return [...parts, list.slice(state.from)];
+};
+
+const isDeclaration = (text: string): boolean => KEYWORD_FIRST.test(text) || RETURN_TYPE.test(text);
+
+const inCodeLine = (line: Line, base: number): Stated[] => {
+  const params = isDeclaration(line.text) ? parameterList(line.text) : undefined;
+  if (params === undefined) return [];
+  return splitParameters(params.list).flatMap((part, index, parts) => {
+    const found = parameterDefault(part);
+    const from = params.from + parts.slice(0, index).reduce((length, earlier) => length + earlier.length + 1, 0);
+    return found === undefined ? [] : [{ ...found, offset: base + line.start + line.text.indexOf(found.name, from), source: "code" as const }];
+  });
+};
+
+const inCode = (source: string): Stated[] =>
+  codeFences(source).flatMap((fence) => linesOf(source.slice(fence.start, fence.end)).flatMap((line) => inCodeLine(line, fence.start)));
+
+const cellsOf = (text: string): string[] =>
+  text
+    .split("|")
+    .slice(1, -1)
+    .map((cell) => cell.trim());
+
+/** The rows of every table with a default column, as (first cell name, default cell). */
+const inTables = (lines: readonly Line[], headers: ReadonlySet<string>): Stated[] =>
+  lines.flatMap((line, index) => {
+    const column = cellsOf(line.text).findIndex((cell) => headers.has(cell.replace(/[*`]/gu, "").toLowerCase()));
+    const delimiter = lines[index + 1]?.text ?? "";
+    if (column <= 0 || !delimiter.includes("---") || !DELIMITER_ROW.test(delimiter)) return [];
+    const end = lines.findIndex((row, at) => at > index + 1 && !row.text.trimStart().startsWith("|"));
+    return lines.slice(index + 2, end === -1 ? lines.length : end).flatMap((row) => {
+      const cells = cellsOf(row.text);
+      const name = /^`?([A-Za-z_$][\w$]*)`?$/u.exec(cells[0] ?? "")?.[1];
+      const value = valueAt(cells[column] ?? "");
+      return name === undefined || value === undefined ? [] : [{ name, value, offset: row.start + row.text.indexOf(name), source: "table" as const }];
+    });
+  });
+
+/** "`width` defaults to 80", "`width` の既定値は 80 文字": a code name, a default phrase right after it, then the value. */
+const inProse = (lines: readonly Line[], phrases: readonly string[]): Stated[] =>
+  lines.flatMap((line) =>
+    [...line.text.matchAll(NAME_SPAN)].flatMap((match) => {
+      const after = line.text.slice(match.index + match[0].length);
+      const phrase = phrases.map((candidate) => ({ candidate, at: after.toLowerCase().indexOf(candidate) })).find(({ at }) => at !== -1 && at <= PHRASE_REACH);
+      const value = phrase === undefined ? undefined : valueAt(after.slice(phrase.at + phrase.candidate.length));
+      return value === undefined ? [] : [{ name: match[1] ?? "", value, offset: line.start + match.index + 1, source: "prose" as const }];
+    }),
+  );
+
+/** Python writes the same literals capitalised: True is true, None is null. */
+const LITERAL_SPELLINGS: Readonly<Record<string, string>> = { True: "true", False: "false", None: "null", none: "null" };
+
+const normalized = (value: string): string => LITERAL_SPELLINGS[value] ?? value;
+
+const sameValue = (left: string, right: string): boolean =>
+  normalized(left) === normalized(right) || (Number.isFinite(Number(left)) && Number(left) === Number(right) && left !== "" && right !== "");
+
+/**
+ * Every stated default that differs from the name's most authoritative statement (the code, else a table). Two
+ * sentences that disagree with no code or table to settle it are left alone.
+ */
+export const defaultSlips = (source: string, words: DefaultWords): DefaultSlip[] => {
+  const fences = codeFences(source);
+  const lines = linesOf(source).filter((line) => !fences.some((fence) => line.start >= fence.start && line.start < fence.end));
+  const stated = [...inCode(source), ...inTables(lines, new Set(words.headers)), ...inProse(lines, words.phrases)];
+  return stated.flatMap((statement) => {
+    const above = stated.filter((other) => other.name === statement.name && RANK[other.source] < RANK[statement.source]);
+    const top = Math.min(...above.map((other) => RANK[other.source]));
+    const authorities = above.filter((other) => RANK[other.source] === top);
+    // Two functions on one page may give one parameter name two defaults; then no statement settles the others.
+    const authority = authorities.every((other) => sameValue(other.value, authorities[0]?.value ?? "")) ? authorities[0] : undefined;
+    return authority === undefined || sameValue(authority.value, statement.value)
+      ? []
+      : [{ name: statement.name, value: statement.value, offset: statement.offset, expected: authority.value }];
+  });
+};