hanlint 0.0.9 → 0.0.12

package/src/guard/contract.js

@@ -0,0 +1,174 @@
+// @ts-check
+/** Reader Contract 검사와 이유가 붙은 국소 Patch 검증. */
+import { sha256 } from "../digest.js";
+
+import { Patch } from "../config/patch.js";
+import { Contract, ContractV2, Outline, ProtectedSurface, parseContract } from "../config/readerContract.js";
+import { defaultConfig } from "../config/settings.js";
+import { headingsOf } from "../document/model.js";
+import { parseMarkdown } from "../document/parseMarkdown.js";
+import { buildFingerprint } from "../fingerprint/build.js";
+import { runAll } from "../rules/registry.js";
+import { editIssues } from "./editLocality.js";
+import { compareOutline, summarizeDocument } from "./outline.js";
+import { CheckResult, PatchResult } from "./receipt.js";
+import { compareText, factLines, protectedSurface, surfaceDiff, surfaceViolationCount } from "./surface.js";
+
+/** @param {string} text */
+function digest(text) {
+  return sha256(text);
+}
+
+/** 원문의 보호 표면을 모두 덮는 version 1 Contract 초안을 만든다. @param {string} text @param {string} reader @param {string} goal */
+export function contractFromText(text, reader, goal) {
+  const contract = new Contract(reader, goal, factLines(text));
+  const result = surfaceDiff(contract.text, text);
+  const missing = [];
+  for (const kind of ["missingNumbers", "missingUrls", "missingCode", "missingLinks"]) {
+    for (const value of result[/** @type {keyof typeof result} */ (kind)]) missing.push(`${kind}=${value}`);
+  }
+  if (missing.length) throw new Error(`reader 또는 goal이 원문에 없는 보호 원자를 넣었다: ${missing.join(", ")}`);
+  if (surfaceViolationCount(result)) {
+    const issues = Object.entries(result).flatMap(([kind, values]) => values.map((value) => `${kind}=${value}`));
+    throw new Error(`계약 초안이 원문의 보호 표면을 모두 담지 못했다: ${issues.join(", ")}`);
+  }
+  return contract;
+}
+
+/** 원문의 자동 표면과 한 수준의 제목을 분리한 version 2 Contract 초안을 만든다. @param {string} text @param {string} reader @param {string} goal @param {number} [outlineLevel] @param {string[]} [facts] */
+export function contractFromTextV2(text, reader, goal, outlineLevel = 2, facts = []) {
+  const doc = parseMarkdown(text);
+  const headings = headingsOf(doc, outlineLevel).map((heading) => heading.text);
+  const surface = protectedSurface(text);
+  const contract = new ContractV2(
+    reader,
+    goal,
+    facts,
+    new ProtectedSurface(surface.numbers, surface.urls, surface.code, surface.links),
+    new Outline(outlineLevel, headings),
+  );
+  const result = surfaceDiff(contract.text, text);
+  if (surfaceViolationCount(result)) {
+    const issues = Object.entries(result).flatMap(([kind, values]) => values.map((value) => `${kind}=${value}`));
+    throw new Error(`reader, goal 또는 facts가 원문에 없는 보호 원자를 넣었다: ${issues.join(", ")}`);
+  }
+  return contract;
+}
+
+/** @param {string} text @param {Contract | ContractV2 | Record<string, unknown>} rawContract @param {import("../config/settings.js").Config} [config] @param {string | null} [path] */
+export function check(text, rawContract, config = defaultConfig(), path = null) {
+  const contract = rawContract instanceof Contract || rawContract instanceof ContractV2 ? rawContract : parseContract(rawContract);
+  const doc = buildFingerprint(parseMarkdown(text, path), config);
+  const findings = runAll(doc, config);
+  const outline = contract instanceof ContractV2 ? compareOutline(contract.outline, doc) : null;
+  const document = contract instanceof ContractV2 ? summarizeDocument(doc) : null;
+  return new CheckResult(contract.digest, digest(text), surfaceDiff(contract.text, text), findings, contract.version, outline, document, contract instanceof ContractV2 ? contract.lockedFacts.filter((fact) => !text.includes(fact)) : []);
+}
+
+/** @param {CheckResult} result */
+function contractIssues(result) {
+  const found = new Set();
+  for (const [kind, values] of Object.entries(result.surface)) {
+    for (const value of values) found.add(`${kind}\u0000${value}`);
+  }
+  if (result.outline) {
+    for (const mismatch of result.outline.mismatches) {
+      found.add(`outline\u0000${mismatch.position}:${mismatch.expected ?? ""}:${mismatch.actual ?? ""}`);
+    }
+  }
+  for (const fact of result.missingFacts) found.add(`lockedFacts\u0000${fact}`);
+  return found;
+}
+
+/** @param {CheckResult} result @param {string} reason */
+function reasonCount(result, reason) {
+  if (reason === "lockedFacts") return result.missingFacts.length;
+  if (reason in result.surface) return result.surface[/** @type {keyof typeof result.surface} */ (reason)].length;
+  if (reason === "outline" && result.outline) return result.outline.mismatches.length;
+  return result.findings.filter((finding) => finding.rule === reason).length;
+}
+
+/** @param {import("../rules/finding.js").Finding} finding */
+function errorSignature(finding) {
+  return `${finding.rule}\u0000${finding.quote}`;
+}
+
+/** @param {CheckResult} before @param {CheckResult} after */
+function addedErrors(before, after) {
+  const remaining = new Map();
+  for (const finding of before.findings) {
+    if (finding.severity !== "error") continue;
+    const signature = errorSignature(finding);
+    remaining.set(signature, (remaining.get(signature) ?? 0) + 1);
+  }
+  return after.findings.filter((finding) => {
+    if (finding.severity !== "error") return false;
+    const signature = errorSignature(finding);
+    const count = remaining.get(signature) ?? 0;
+    if (!count) return true;
+    remaining.set(signature, count - 1);
+    return false;
+  });
+}
+
+/** 파이썬 str.count와 같은 겹치지 않는 정확 출현 수. @param {string} text @param {string} fragment */
+function exactCount(text, fragment) {
+  let count = 0;
+  let cursor = 0;
+  while (true) {
+    const at = text.indexOf(fragment, cursor);
+    if (at < 0) return count;
+    count += 1;
+    cursor = at + fragment.length;
+  }
+}
+
+/** @param {string} text @param {Patch | Record<string, unknown>} rawPatch @param {Contract | ContractV2 | Record<string, unknown>} rawContract @param {import("../config/settings.js").Config} [config] @param {string | null} [path] */
+export function verifyPatch(text, rawPatch, rawContract, config = defaultConfig(), path = null) {
+  const patch = rawPatch instanceof Patch ? rawPatch : Patch.fromMapping(rawPatch);
+  const contract = rawContract instanceof Contract || rawContract instanceof ContractV2 ? rawContract : parseContract(rawContract);
+  const beforeResult = check(text, contract, config, path);
+  const matchCount = exactCount(text, patch.before);
+  const reasonBefore = reasonCount(beforeResult, patch.reason);
+  if (matchCount !== 1) {
+    return new PatchResult({
+      contractSha256: contract.digest,
+      sourceSha256: beforeResult.draftSha256,
+      patchSha256: patch.digest,
+      resultSha256: null,
+      reason: patch.reason,
+      matchCount,
+      reasonBefore,
+      reasonAfter: null,
+      newContractIssues: [],
+      newErrors: [],
+      resultText: null,
+      contractVersion: contract.version,
+    });
+  }
+  const resultText = text.replace(patch.before, patch.after);
+  const afterResult = check(resultText, contract, config, path);
+  const beforeIssues = contractIssues(beforeResult);
+  const newContractIssues = [...contractIssues(afterResult)]
+    .filter((issue) => !beforeIssues.has(issue))
+    .map((issue) => /** @type {[string, string]} */ (issue.split("\u0000", 2)))
+    .sort((left, right) => compareText(left[0], right[0]) || compareText(left[1], right[1]));
+  if (contract instanceof ContractV2) {
+    newContractIssues.push(...editIssues(text, patch, beforeResult.findings, contract.editPolicy));
+    newContractIssues.sort((a, b) => compareText(a[0], b[0]) || compareText(a[1], b[1]));
+  }
+  return new PatchResult({
+    contractSha256: contract.digest,
+    sourceSha256: beforeResult.draftSha256,
+    patchSha256: patch.digest,
+    resultSha256: afterResult.draftSha256,
+    reason: patch.reason,
+    matchCount,
+    reasonBefore,
+    reasonAfter: reasonCount(afterResult, patch.reason),
+    newContractIssues,
+    newErrors: addedErrors(beforeResult, afterResult),
+    resultText,
+    contractVersion: contract.version,
+  });
+}

package/src/guard/editLocality.js

@@ -0,0 +1,27 @@
+// @ts-check
+/** 선택한 규칙의 Finding 줄과 원문 변경 창을 대조한다. */
+export function editIssues(text, patch, findings, policy) {
+  if (!Object.keys(policy).length) return [];
+  const limits = policy[patch.reason];
+  if (!limits) return [["editPolicy", "reason has no edit budget"]];
+  const before = [...patch.before], after = [...patch.after];
+  let prefix = 0, suffix = 0;
+  while (prefix < Math.min(before.length, after.length) && before[prefix] === after[prefix]) prefix++;
+  while (suffix < Math.min(before.length, after.length) - prefix && before.at(-1 - suffix) === after.at(-1 - suffix)) suffix++;
+  const changedBefore = before.slice(prefix, before.length - suffix).join("");
+  const changedAfter = after.slice(prefix, after.length - suffix).join("");
+  const start = text.indexOf(patch.before) + before.slice(0, prefix).join("").length;
+  const firstLine = text.slice(0, start).split("\n").length;
+  const lastLine = firstLine + changedBefore.split("\n").length - 1;
+  const issues = [];
+  if (!findings.some((f) => f.rule === patch.reason && firstLine <= f.line && f.line <= lastLine)) {
+    issues.push(["editPolicy", "changed range does not contain the Finding line"]);
+  }
+  if (Math.max([...changedBefore].length, [...changedAfter].length) > limits.maxChars) {
+    issues.push(["editPolicy", "changed range exceeds maxChars"]);
+  }
+  if (Math.max(changedBefore.split("\n").length, changedAfter.split("\n").length) > limits.maxLines) {
+    issues.push(["editPolicy", "changed range exceeds maxLines"]);
+  }
+  return issues;
+}

package/src/guard/outline.js

@@ -0,0 +1,46 @@
+// @ts-check
+/** Reader Contract가 잠근 제목 순서와 글 지문의 구조 요약. */
+
+/** @typedef {{position: number, expected: string | null, actual: string | null}} OutlineMismatch */
+/** @typedef {{matches: boolean, level: number, expected: string[], actual: string[], mismatches: OutlineMismatch[]}} OutlineDiff */
+/** @typedef {{heading: string, line: number, paragraphCount: number, codeBlockCount: number}} SectionSummary */
+/** @typedef {{sentenceCount: number, paragraphCount: number, sectionCount: number, wordCount: number, questionCount: number, readerCallCount: number, sections: SectionSummary[]}} DocumentSummary */
+
+/** @param {Pick<import("../config/readerContract.js").Outline, "level" | "headings">} outline @param {import("../fingerprint/build.js").DocumentPrint} doc @returns {OutlineDiff} */
+export function compareOutline(outline, doc) {
+  const actual = doc.headings.filter(([level]) => level === outline.level).map(([, title]) => title);
+  const mismatches = [];
+  const count = Math.max(outline.headings.length, actual.length);
+  for (let index = 0; index < count; index += 1) {
+    const expected = outline.headings[index] ?? null;
+    const found = actual[index] ?? null;
+    if (expected !== found) {
+      mismatches.push({ position: index + 1, expected, actual: found });
+    }
+  }
+  return {
+    matches: mismatches.length === 0,
+    level: outline.level,
+    expected: [...outline.headings],
+    actual,
+    mismatches,
+  };
+}
+
+/** @param {import("../fingerprint/build.js").DocumentPrint} doc @returns {DocumentSummary} */
+export function summarizeDocument(doc) {
+  return {
+    sentenceCount: doc.sentences.length,
+    paragraphCount: doc.paragraphs.length,
+    sectionCount: doc.bodySections.length,
+    wordCount: doc.wordCount,
+    questionCount: doc.questionCount,
+    readerCallCount: doc.readerCallCount,
+    sections: doc.bodySections.map((section) => ({
+      heading: section.title,
+      line: section.startLine,
+      paragraphCount: section.paragraphs.length,
+      codeBlockCount: section.blockKinds.filter((kind) => kind === "code").length,
+    })),
+  };
+}

package/src/guard/receipt.js

@@ -0,0 +1,180 @@
+// @ts-check
+/** Reader Contract 검사와 Patch 검증의 결정적 영수증. */
+
+import { findingAsDict } from "../rules/finding.js";
+import { readerDebts } from "../rules/readerDebt.js";
+import { compareText, surfaceViolationCount } from "./surface.js";
+
+export const CHECK_MEANING = "violationCount는 선언한 보호 원자와 hanlint error의 수다. facts의 관계와 진실, 빠진 의미, 독자 효용과 자연스러움은 검증하지 않는다";
+export const CHECK_MEANING_V2 = "violationCount는 선언한 보호 원자, 제목 구조, 잠금 문구 누락과 hanlint error의 수다. facts의 관계와 진실, 빠진 의미, 독자 효용과 자연스러움은 검증하지 않는다";
+export const PATCH_MEANING = "verified는 정확히 한 자리를 바꾸고 명시한 기존 위반을 줄이며 새 보호 원자 위반과 새 error를 만들지 않았다는 뜻뿐이다. 수정문의 의미와 진실, 자연스러움은 승인하지 않는다";
+export const PATCH_MEANING_V2 = "verified는 정확히 한 자리를 바꾸고 명시한 기존 위반을 줄이며 새 계약 위반과 새 error를 만들지 않고 선택한 수정 예산을 지켰다는 뜻뿐이다. 수정문의 의미와 진실, 자연스러움은 승인하지 않는다";
+
+/** @param {import("../rules/finding.js").Finding[]} findings */
+function errorRules(findings) {
+  /** @type {Record<string, number>} */
+  const counted = {};
+  for (const finding of findings) {
+    if (finding.severity === "error") counted[finding.rule] = (counted[finding.rule] ?? 0) + 1;
+  }
+  return Object.fromEntries(Object.entries(counted).sort(([left], [right]) => compareText(left, right)));
+}
+
+export class CheckResult {
+  /** @param {string} contractSha256 @param {string} draftSha256 @param {import("./surface.js").SurfaceDiff} surface @param {import("../rules/finding.js").Finding[]} findings @param {number} [contractVersion] @param {import("./outline.js").OutlineDiff | null} [outline] @param {import("./outline.js").DocumentSummary | null} [document] */
+  constructor(contractSha256, draftSha256, surface, findings, contractVersion = 1, outline = null, document = null, missingFacts = []) {
+    this.contractSha256 = contractSha256;
+    this.draftSha256 = draftSha256;
+    this.surface = surface;
+    this.findings = findings;
+    this.contractVersion = contractVersion;
+    this.outline = outline;
+    this.document = document;
+    this.missingFacts = missingFacts;
+    if (![1, 2].includes(contractVersion)) {
+      throw new Error(`check result contractVersion 은 1 또는 2다: ${contractVersion}`);
+    }
+    const hasStructure = outline !== null && document !== null;
+    if (hasStructure !== (contractVersion === 2)) {
+      throw new Error("version 2 check result만 outline과 document를 함께 가진다");
+    }
+  }
+
+  get errorCount() {
+    return this.findings.filter((finding) => finding.severity === "error").length;
+  }
+
+  get noticeCount() {
+    return this.findings.length - this.errorCount;
+  }
+
+  get violationCount() {
+    return surfaceViolationCount(this.surface) + (this.outline?.mismatches.length ?? 0) + this.errorCount + this.missingFacts.length;
+  }
+
+  asDict() {
+    const result = {
+      version: this.contractVersion,
+      kind: "hanlint.checkResult",
+      violationCount: this.violationCount,
+      contractSha256: this.contractSha256,
+      draftSha256: this.draftSha256,
+      surface: this.surface,
+      lint: {
+        errorCount: this.errorCount,
+        noticeCount: this.noticeCount,
+        errorRules: errorRules(this.findings),
+        items: this.findings.map(findingAsDict),
+      },
+      meaning: this.contractVersion === 1 ? CHECK_MEANING : CHECK_MEANING_V2,
+    };
+    if (this.contractVersion === 2) return { ...result, outline: this.outline, document: this.document, missingFacts: this.missingFacts };
+    return result;
+  }
+}
+
+export class PatchResult {
+  /** @param {{contractSha256: string, sourceSha256: string, patchSha256: string, resultSha256: string | null, reason: string, matchCount: number, reasonBefore: number, reasonAfter: number | null, newContractIssues: [string, string][], newErrors: import("../rules/finding.js").Finding[], resultText: string | null, contractVersion: number}} values */
+  constructor(values) {
+    this.contractSha256 = values.contractSha256;
+    this.sourceSha256 = values.sourceSha256;
+    this.patchSha256 = values.patchSha256;
+    this.resultSha256 = values.resultSha256;
+    this.reason = values.reason;
+    this.matchCount = values.matchCount;
+    this.reasonBefore = values.reasonBefore;
+    this.reasonAfter = values.reasonAfter;
+    this.newContractIssues = values.newContractIssues;
+    this.newErrors = values.newErrors;
+    this.resultText = values.resultText;
+    this.contractVersion = values.contractVersion;
+    if (![1, 2].includes(values.contractVersion)) {
+      throw new Error(`patch result contractVersion 은 1 또는 2다: ${values.contractVersion}`);
+    }
+  }
+
+  get newSurfaceIssues() {
+    return this.newContractIssues.filter(([kind]) => kind !== "outline");
+  }
+
+  get reasonReduced() {
+    return this.reasonBefore > 0 && this.reasonAfter !== null && this.reasonAfter < this.reasonBefore;
+  }
+
+  get violationCount() {
+    return Number(this.matchCount !== 1) + Number(!this.reasonReduced) + this.newContractIssues.length + this.newErrors.length;
+  }
+
+  get verified() {
+    return this.violationCount === 0;
+  }
+
+  asDict() {
+    const base = {
+      version: this.contractVersion,
+      kind: "hanlint.patchResult",
+      verified: this.verified,
+      violationCount: this.violationCount,
+      contractSha256: this.contractSha256,
+      sourceSha256: this.sourceSha256,
+      patchSha256: this.patchSha256,
+      resultSha256: this.resultSha256,
+      matchCount: this.matchCount,
+      reason: {
+        name: this.reason,
+        before: this.reasonBefore,
+        after: this.reasonAfter,
+        reduced: this.reasonReduced,
+      },
+    };
+    const issues = this.newContractIssues.map(([kind, value]) => ({ kind, value }));
+    const tail = {
+      newErrors: this.newErrors.map(findingAsDict),
+      meaning: this.contractVersion === 1 ? PATCH_MEANING : PATCH_MEANING_V2,
+    };
+    if (this.contractVersion === 1) return { ...base, newSurfaceIssues: issues, ...tail };
+    return { ...base, newContractIssues: issues, ...tail };
+  }
+}
+
+/** 사람이 결론, 근거, 다음 행동 순서로 읽는 검사 영수증. @param {CheckResult} result */
+export function renderCheck(result) {
+  const lines = [result.violationCount === 0 ? "계약 위반 없음" : `계약 위반 ${result.violationCount}건`];
+  const labels = [
+    ["빠진 숫자", result.surface.missingNumbers],
+    ["계약 밖 숫자", result.surface.unexpectedNumbers],
+    ["빠진 URL", result.surface.missingUrls],
+    ["계약 밖 URL", result.surface.unexpectedUrls],
+    ["빠진 코드", result.surface.missingCode],
+    ["계약 밖 코드", result.surface.unexpectedCode],
+    ["빠진 링크 목적지", result.surface.missingLinks],
+    ["계약 밖 링크 목적지", result.surface.unexpectedLinks],
+  ];
+  for (const [label, values] of labels) if (values.length) lines.push(`- ${label}: ${values.join(", ")}`);
+  for (const fact of result.missingFacts) lines.push(`- lockedFacts: ${fact}`);
+  if (result.outline) {
+    const state = result.outline.matches ? "일치" : `어긋남 ${result.outline.mismatches.length}곳`;
+    lines.push(`- 구조: H${result.outline.level} ${result.outline.actual.length}개, ${state}`);
+    for (const mismatch of result.outline.mismatches) {
+      lines.push(`  ${mismatch.position}. 기대 \`${mismatch.expected ?? "없음"}\`, 실제 \`${mismatch.actual ?? "없음"}\``);
+    }
+  }
+  if (result.document) {
+    lines.push(`- 글: 문장 ${result.document.sentenceCount}, 문단 ${result.document.paragraphCount}, 절 ${result.document.sectionCount}`);
+    result.document.sections.forEach((section, index) => {
+      lines.push(`  ${index + 1}. ${section.heading} (${section.line}행, 문단 ${section.paragraphCount}, 코드 ${section.codeBlockCount})`);
+    });
+  }
+  lines.push(`- lint: error ${result.errorCount}, notice ${result.noticeCount}`);
+  if (result.errorCount) {
+    lines.push(`  ${Object.entries(errorRules(result.findings)).map(([rule, count]) => `${rule} ${count}`).join(", ")}`);
+  }
+  const debts = readerDebts(result.findings);
+  lines.push(debts.length ? `- 독자 부채: ${debts.length}건` : "- 독자 부채: 없음");
+  for (const debt of debts) lines.push(`  ${debt.line}행 [${debt.rule}] ${debt.why}`);
+  if (result.violationCount) lines.push("\n다음: 계약과 글 가운데 틀린 쪽을 바로잡고 같은 check를 다시 실행한다");
+  else if (result.noticeCount) lines.push("\n다음: notice를 읽고 고칠지 유지할지 판단한 뒤 사람과 LLM 평가로 넘어간다");
+  else lines.push("\n다음: 세어서 잡히는 계약 위반이 없다. 사람과 LLM 평가로 넘어간다");
+  lines.push("", result.contractVersion === 1 ? CHECK_MEANING : CHECK_MEANING_V2);
+  return lines.join("\n");
+}

package/src/guard/surface.js

@@ -0,0 +1,184 @@
+// @ts-check
+/** 계약 본문과 결과 글 사이의 보호 원자 차이. */
+
+/**
+ * @typedef {object} SurfaceDiff
+ * @property {string[]} missingNumbers
+ * @property {string[]} unexpectedNumbers
+ * @property {string[]} missingUrls
+ * @property {string[]} unexpectedUrls
+ * @property {string[]} missingCode
+ * @property {string[]} unexpectedCode
+ * @property {string[]} missingLinks
+ * @property {string[]} unexpectedLinks
+ */
+
+const NUMBER_ATOM = /(?<!\p{Nd})(?:\p{Nd}{1,3}(?:,\p{Nd}{3})+|\p{Nd}+)(?:\.\p{Nd}+)*(?!\p{Nd})/gu;
+const URL = /https?:\/\/[^\s)>\]]*[\p{L}\p{N}_\/#=%&+~-]/gu;
+const INLINE_CODE = /`([^`\n]+)`/gu;
+const LINK_DESTINATION = /\[[^\u005D]*\]\(([^)]+)\)/gu;
+const FACT_FIELDS = [
+  ["unexpectedNumbers", "{}"],
+  ["unexpectedUrls", "{}"],
+  ["unexpectedCode", "`{}`"],
+  ["unexpectedLinks", "[]({})"],
+];
+const UNEXPECTED_FIELDS = FACT_FIELDS.map(([field]) => field);
+const DECIMAL_ZEROS = [
+  0x0030, 0x0660, 0x06f0, 0x07c0, 0x0966, 0x09e6, 0x0a66, 0x0ae6, 0x0b66, 0x0be6,
+  0x0c66, 0x0ce6, 0x0d66, 0x0de6, 0x0e50, 0x0ed0, 0x0f20, 0x1040, 0x1090, 0x17e0,
+  0x1810, 0x1946, 0x19d0, 0x1a80, 0x1a90, 0x1b50, 0x1bb0, 0x1c40, 0x1c50, 0xa620,
+  0xa8d0, 0xa900, 0xa9d0, 0xa9f0, 0xaa50, 0xabf0, 0xff10, 0x104a0, 0x10d30, 0x11066,
+  0x110f0, 0x11136, 0x111d0, 0x112f0, 0x11450, 0x114d0, 0x11650, 0x116c0, 0x11730, 0x118e0,
+  0x11950, 0x11c50, 0x11d50, 0x11da0, 0x16a60, 0x16ac0, 0x16b50, 0x1d7ce, 0x1e140, 0x1e2f0,
+  0x1e4f0, 0x1e950,
+];
+
+/** 파이썬 문자열 순서와 같은 코드 포인트 순서. @param {string} left @param {string} right */
+export function compareText(left, right) {
+  const leftPoints = [...left].map((value) => /** @type {number} */ (value.codePointAt(0)));
+  const rightPoints = [...right].map((value) => /** @type {number} */ (value.codePointAt(0)));
+  const limit = Math.min(leftPoints.length, rightPoints.length);
+  for (let index = 0; index < limit; index += 1) {
+    if (leftPoints[index] !== rightPoints[index]) return leftPoints[index] - rightPoints[index];
+  }
+  return leftPoints.length - rightPoints.length;
+}
+
+/** @param {string} character */
+function decimalValue(character) {
+  const point = /** @type {number} */ (character.codePointAt(0));
+  const zero = DECIMAL_ZEROS.find((start) => start <= point && point < start + 10);
+  if (zero === undefined) throw new Error(`지원하지 않는 유니코드 십진 숫자다: ${character}`);
+  return String(point - zero);
+}
+
+/** @param {string} value */
+function canonicalNumber(value) {
+  return [...value]
+    .filter((character) => character !== ",")
+    .map((character) => (/\p{Nd}/u.test(character) ? decimalValue(character) : character))
+    .join("");
+}
+
+/** @param {string} text */
+export function numberValues(text) {
+  return [...new Set([...text.matchAll(NUMBER_ATOM)].map((match) => canonicalNumber(match[0])))].sort(compareText);
+}
+
+/** @param {RegExp} pattern @param {string} text */
+function valuesOf(pattern, text) {
+  return [...new Set([...text.matchAll(pattern)].map((match) => (match.length > 1 ? match[1] : match[0])))].sort(compareText);
+}
+
+/** @param {string[]} expected @param {string[]} actual */
+function difference(expected, actual) {
+  const other = new Set(actual);
+  return expected.filter((value) => !other.has(value)).sort(compareText);
+}
+
+/** @param {string} contractText @param {string} text @param {string[] | null} [numbers] @returns {SurfaceDiff} */
+export function surfaceDiff(contractText, text, numbers = null) {
+  const surfaceText = text.normalize("NFC");
+  const expectedNumbers = numbers === null ? numberValues(contractText) : [...new Set(numbers)].sort(compareText);
+  const actualNumbers = numberValues(surfaceText);
+  const expectedUrls = valuesOf(URL, contractText);
+  const actualUrls = valuesOf(URL, surfaceText);
+  const expectedCode = valuesOf(INLINE_CODE, contractText);
+  const actualCode = valuesOf(INLINE_CODE, surfaceText);
+  const expectedLinks = valuesOf(LINK_DESTINATION, contractText);
+  const actualLinks = valuesOf(LINK_DESTINATION, surfaceText);
+  const allowedCode = [...new Set([...expectedCode, ...actualCode.filter((value) => contractText.includes(value))])];
+  const allowedLinks = [...new Set([...expectedLinks, ...actualLinks.filter((value) => contractText.includes(value))])];
+  return {
+    missingNumbers: difference(expectedNumbers, actualNumbers),
+    unexpectedNumbers: difference(actualNumbers, expectedNumbers),
+    missingUrls: difference(expectedUrls, actualUrls),
+    unexpectedUrls: difference(actualUrls, expectedUrls),
+    missingCode: difference(expectedCode, actualCode),
+    unexpectedCode: difference(actualCode, allowedCode),
+    missingLinks: difference(expectedLinks, actualLinks),
+    unexpectedLinks: difference(actualLinks, allowedLinks),
+  };
+}
+
+/** @param {ReturnType<typeof surfaceDiff>} diff */
+export function surfaceViolationCount(diff) {
+  return Object.values(diff).reduce((total, values) => total + values.length, 0);
+}
+
+/** 원문의 보호 원자를 뜻 없는 정렬 집합으로 분리한다. @param {string} text */
+export function protectedSurface(text) {
+  const surfaceText = text.normalize("NFC");
+  return {
+    numbers: numberValues(surfaceText),
+    urls: valuesOf(URL, surfaceText),
+    code: valuesOf(INLINE_CODE, surfaceText),
+    links: valuesOf(LINK_DESTINATION, surfaceText),
+  };
+}
+
+/** 원문의 보호 표면을 모두 덮는 Contract 사실 후보 줄. @param {string} text */
+export function factLines(text) {
+  const surfaceText = text.normalize("NFC");
+  const seen = new Set();
+  /** @type {{ text: string, atoms: Set<string> }[]} */
+  const candidates = [];
+  for (const line of surfaceText.split(/\r\n|[\n\v\f\r\x1c-\x1e\x85\u2028\u2029]/u)) {
+    const candidate = line.trim();
+    if (!candidate || seen.has(candidate)) continue;
+    seen.add(candidate);
+    const diff = surfaceDiff("", candidate);
+    const atoms = new Set(
+      UNEXPECTED_FIELDS.flatMap((field) =>
+        diff[/** @type {keyof typeof diff} */ (field)].map((value) => `${field}\u0000${value}`),
+      ),
+    );
+    if (atoms.size) candidates.push({ text: candidate, atoms });
+  }
+
+  const fullDiff = surfaceDiff("", surfaceText);
+  const uncovered = new Set(
+    UNEXPECTED_FIELDS.flatMap((field) =>
+      fullDiff[/** @type {keyof typeof fullDiff} */ (field)].map((value) => `${field}\u0000${value}`),
+    ),
+  );
+  if (!uncovered.size) {
+    throw new Error("원문에 자동으로 보호할 숫자, URL, 인라인 코드, 링크 목적지가 없다. facts를 직접 작성한다");
+  }
+
+  const selected = new Set();
+  while (uncovered.size) {
+    let best = -1;
+    let bestGain = 0;
+    for (let index = 0; index < candidates.length; index += 1) {
+      if (selected.has(index)) continue;
+      const gain = [...candidates[index].atoms].filter((atom) => uncovered.has(atom)).length;
+      if (gain > bestGain) {
+        best = index;
+        bestGain = gain;
+      }
+    }
+    if (!bestGain) break;
+    selected.add(best);
+    for (const atom of candidates[best].atoms) uncovered.delete(atom);
+  }
+
+  const facts = candidates.filter((_, index) => selected.has(index)).map((candidate) => candidate.text);
+  const factSet = new Set(facts);
+  for (const [field, template] of FACT_FIELDS) {
+    const prefix = `${field}\u0000`;
+    const values = [...uncovered]
+      .filter((atom) => atom.startsWith(prefix))
+      .map((atom) => atom.slice(prefix.length))
+      .sort(compareText);
+    for (const value of values) {
+      const candidate = template.replace("{}", value);
+      if (!factSet.has(candidate)) {
+        facts.push(candidate);
+        factSet.add(candidate);
+      }
+    }
+  }
+  return facts;
+}