hanlint 0.0.9 → 0.0.10

package/src/config/settings.js

@@ -38,6 +38,27 @@ PRESETS.guide = [...PRESETS.blog, ...REFERENCE];
 PRESETS.essay = [...PRESETS.report, ...NARRATIVE];
 PRESETS.fiction = [...PRESETS.report, ...NARRATIVE];
 PRESETS.encyclopedia = [...PRESETS.docs, ...ENCYCLOPEDIC];
+// 대화 답변에서 끄는 것. 글의 짜임을 재는 규칙은 글 한 편을 전제한다. 파이썬 settings.py 의 CONVERSATION 과 같다.
+const CONVERSATION = [
+  "countMismatch",
+  "duplicateBlock",
+  "factListParagraph",
+  "firstResultDistance",
+  "headingSentence",
+  "headingSkip",
+  "headingUniform",
+  "inputFileSource",
+  "installImport",
+  "introLong",
+  "keywordMissing",
+  "noQuestion",
+  "outsideProfile",
+  "paraFragment",
+  "platformApi",
+  "promiseRecall",
+  "sectionNoProse",
+];
+PRESETS.chat = CONVERSATION;
 
 /** 프리셋 → 견줄 프로파일의 종류. 정본은 파이썬 config/settings.py 의 PROFILE_OF 다. @type {Record<string, string>} */
 export const PROFILE_OF = {
@@ -48,6 +69,7 @@ export const PROFILE_OF = {
   essay: "essay",
   fiction: "fiction",
   encyclopedia: "encyclopedia",
+  chat: null,
 };
 
 export const PRESET_NAMES = Object.keys(PRESETS);
@@ -57,6 +79,7 @@ export const DEFAULT_PRESET = PRESET_NAMES[0];
 /**
  * @typedef {object} Config
  * @property {string} preset 글의 종류. PRESETS 가 정한 규칙을 처음부터 끈다
+ * @property {string[]} enforceStyle
  * @property {Set<string>} disable 끌 규칙 이름
  * @property {string | null} keywordField
  * @property {string[]} introFields
@@ -96,6 +119,7 @@ export function defaultConfig() {
   return {
     preset: DEFAULT_PRESET,
     disable: new Set(),
+    enforceStyle: [],
     keywordField: null,
     introFields: [],
     endingFields: [],
@@ -133,12 +157,12 @@ export function defaultConfig() {
 
 /** @param {Config} config @param {string} ruleName */
 export function enabled(config, ruleName) {
-  return !config.disable.has(ruleName) && !PRESETS[config.preset].includes(ruleName);
+  return !config.disable.has(ruleName) && (!PRESETS[config.preset].includes(ruleName) || config.enforceStyle.includes(ruleName));
 }
 
 /** 지금 꺼져 있는 규칙 이름. 프리셋이 끈 것과 disable 이 끈 것을 합친다. @param {Config} config */
 export function offRules(config) {
-  return [...new Set([...PRESETS[config.preset], ...config.disable])].sort();
+  return [...new Set([...PRESETS[config.preset].filter((name) => !config.enforceStyle.includes(name)), ...config.disable])].sort();
 }
 
 /** @param {Record<string, unknown>} data @returns {Config} */
@@ -155,6 +179,11 @@ export function configFromMapping(data) {
         throw new Error(`preset 은 ${PRESET_NAMES.join(", ")} 가운데 하나다: ${JSON.stringify(value)}`);
       }
       config.preset = /** @type {string} */ (value);
+    } else if (key === "enforceStyle") {
+      if (!Array.isArray(value) || value.some((name) => !["noQuestion", "nounPile"].includes(name))) {
+        throw new Error("enforceStyle 은 noQuestion, nounPile의 배열이다");
+      }
+      config.enforceStyle = [...value];
     } else if (key === "dictionary") {
       config.dictionary = { .../** @type {Record<string, unknown[]>} */ (value) };
     } else if (key === "exemplars") {

package/src/data/profiles.js

@@ -36,6 +36,10 @@ export const TYPE_LABELS = {
  * @property {number} sentences
  * @property {number} paragraphs
  * @property {Map<string, Histogram>} sentence
+ * @property {Map<string, Histogram>} paragraph
+ * @property {Histogram | null} endingRuns
+ * @property {Record<string, number>} endingTransitions
+ * @property {Record<string, Record<string, number>>} rates
  * @property {string} label
  */
 
@@ -62,6 +66,10 @@ function profileFromDict(kind, data) {
   for (const [name, value] of Object.entries(/** @type {Record<string, Record<string, unknown>>} */ (data.sentence))) {
     sentence.set(name, histogramFromDict(value));
   }
+  const paragraph = new Map();
+  for (const [name, value] of Object.entries(/** @type {Record<string, Record<string, unknown>>} */ (data.paragraph))) {
+    paragraph.set(name, histogramFromDict(value));
+  }
   const documents = Number(data.documents);
   return {
     kind,
@@ -69,6 +77,10 @@ function profileFromDict(kind, data) {
     sentences: Number(data.sentences),
     paragraphs: Number(data.paragraphs),
     sentence,
+    paragraph,
+    endingRuns: data.endingRuns ? histogramFromDict(/** @type {Record<string, unknown>} */ (data.endingRuns)) : null,
+    endingTransitions: { .../** @type {Record<string, number>} */ (data.endingTransitions ?? {}) },
+    rates: { .../** @type {Record<string, Record<string, number>>} */ (data.rates ?? {}) },
     label: TYPE_LABELS[kind] ?? `참조 글 ${documents}편`,
   };
 }

package/src/fingerprint/codeMarkers.js

@@ -13,7 +13,7 @@ const READS = new RegExp(
 const OPENS = new RegExp("\\bopen" + QUOTED + "\\s*(?:,\\s*(?:mode\\s*=\\s*)?[\"']([^\"']*)[\"'])?", "g");
 const WRITES = new RegExp(
   "\\b(?:to_csv|to_excel|to_parquet|to_json|to_sql|write_csv|write_parquet|write_json|write_ndjson|sink_parquet|sink_csv|" +
-    "write_text|write_bytes|savefig|save|imwrite|savetxt|dump)" + QUOTED,
+    "write_text|write_bytes|savefig|save|imwrite|savetxt|dump|ExcelWriter)" + QUOTED,
   "g",
 );
 const SHELL_WRITES = /(?:>>?|-o|-O|--output|Out-File)\s*["']?([\w./\\-]+\.[A-Za-z0-9]+)/g;

package/src/guard/contract.js

@@ -0,0 +1,174 @@
+// @ts-check
+/** Reader Contract 검사와 이유가 붙은 국소 Patch 검증. */
+import { createHash } from "node:crypto";
+
+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 createHash("sha256").update(text, "utf8").digest("hex");
+}
+
+/** 원문의 보호 표면을 모두 덮는 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 {import("../config/readerContract.js").Outline} 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");
+}