hanlint 0.0.8 → 0.0.10

package/src/config/readerContract.js

@@ -0,0 +1,245 @@
+// @ts-check
+/** 모델과 실행 환경에 독립적인 최소 Reader Contract와 정확 Patch. */
+import { createHash } from "node:crypto";
+
+export const CONTRACT_VERSION = 1;
+export const LATEST_CONTRACT_VERSION = 2;
+export const CONTRACT_VERSIONS = Object.freeze([CONTRACT_VERSION, LATEST_CONTRACT_VERSION]);
+
+/** @param {unknown} value @param {string} where */
+function checkedString(value, where) {
+  if (typeof value !== "string" || !value || value !== value.trim()) {
+    throw new Error(`${where} 는 양끝 공백 없는 문자열이다`);
+  }
+  if (value !== value.normalize("NFC")) throw new Error(`${where} 는 NFC 문자열이어야 한다`);
+  return value;
+}
+
+/** @param {unknown} value @param {string} where @param {boolean} [allowEmpty] */
+function checkedStrings(value, where, allowEmpty = false) {
+  if (!Array.isArray(value) || (!allowEmpty && !value.length)) {
+    throw new Error(`${where} 는 ${allowEmpty ? "문자열 배열" : "비지 않은 문자열 배열"}이다`);
+  }
+  const found = value.map((item, index) => checkedString(item, `${where} ${index + 1}번째`));
+  if (new Set(found).size !== found.length) throw new Error(`${where} 에 같은 값이 두 번 있다`);
+  return found;
+}
+
+/** 파이썬 문자열 순서와 같은 코드 포인트 순서. @param {string} left @param {string} right */
+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} text */
+function digest(text) {
+  return createHash("sha256").update(text, "utf8").digest("hex");
+}
+
+export class Contract {
+  /** @param {string} reader @param {string} goal @param {string[]} facts @param {number} [version] */
+  constructor(reader, goal, facts, version = CONTRACT_VERSION) {
+    if (!Number.isInteger(version) || version !== CONTRACT_VERSION) {
+      throw new Error(`reader contract version 은 ${CONTRACT_VERSION}이다: ${version}`);
+    }
+    this.reader = checkedString(reader, "reader");
+    this.goal = checkedString(goal, "goal");
+    this.facts = Object.freeze(checkedStrings(facts, "facts"));
+    this.version = version;
+    Object.freeze(this);
+  }
+
+  /** @param {unknown} raw */
+  static fromMapping(raw) {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw)) throw new Error("reader contract 는 JSON 객체다");
+    const data = /** @type {Record<string, unknown>} */ (raw);
+    const expected = ["version", "reader", "goal", "facts"];
+    const unknown = Object.keys(data).filter((key) => !expected.includes(key)).sort();
+    const missing = expected.filter((key) => !(key in data)).sort();
+    if (unknown.length) throw new Error(`reader contract 의 모르는 키: ${unknown.join(", ")}`);
+    if (missing.length) throw new Error(`reader contract 의 빠진 키: ${missing.join(", ")}`);
+    return new Contract(
+      /** @type {string} */ (data.reader),
+      /** @type {string} */ (data.goal),
+      /** @type {string[]} */ (data.facts),
+      /** @type {number} */ (data.version),
+    );
+  }
+
+  get text() {
+    return [this.reader, this.goal, ...this.facts].join("\n");
+  }
+
+  get digest() {
+    return digest(JSON.stringify({ facts: this.facts, goal: this.goal, reader: this.reader, version: this.version }));
+  }
+
+  asDict() {
+    return { version: this.version, reader: this.reader, goal: this.goal, facts: [...this.facts] };
+  }
+}
+
+export class ProtectedSurface {
+  /** @param {string[]} [numbers] @param {string[]} [urls] @param {string[]} [code] @param {string[]} [links] */
+  constructor(numbers = [], urls = [], code = [], links = []) {
+    this.numbers = Object.freeze(checkedStrings(numbers, "surface.numbers", true).sort(compareText));
+    this.urls = Object.freeze(checkedStrings(urls, "surface.urls", true).sort(compareText));
+    this.code = Object.freeze(checkedStrings(code, "surface.code", true).sort(compareText));
+    this.links = Object.freeze(checkedStrings(links, "surface.links", true).sort(compareText));
+    Object.freeze(this);
+  }
+
+  /** @param {unknown} raw */
+  static fromMapping(raw) {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw)) throw new Error("surface 는 JSON 객체다");
+    const data = /** @type {Record<string, unknown>} */ (raw);
+    const expected = ["numbers", "urls", "code", "links"];
+    const unknown = Object.keys(data).filter((key) => !expected.includes(key)).sort();
+    const missing = expected.filter((key) => !(key in data)).sort();
+    if (unknown.length) throw new Error(`surface 의 모르는 키: ${unknown.join(", ")}`);
+    if (missing.length) throw new Error(`surface 의 빠진 키: ${missing.join(", ")}`);
+    return new ProtectedSurface(
+      /** @type {string[]} */ (data.numbers),
+      /** @type {string[]} */ (data.urls),
+      /** @type {string[]} */ (data.code),
+      /** @type {string[]} */ (data.links),
+    );
+  }
+
+  get text() {
+    return [
+      ...this.numbers,
+      ...this.urls,
+      ...this.code.map((value) => `\`${value}\``),
+      ...this.links.map((value) => `[](${value})`),
+    ].join("\n");
+  }
+
+  asDict() {
+    return { numbers: [...this.numbers], urls: [...this.urls], code: [...this.code], links: [...this.links] };
+  }
+}
+
+export class Outline {
+  /** @param {number} level @param {string[]} headings */
+  constructor(level, headings) {
+    if (!Number.isInteger(level) || level < 1 || level > 6) throw new Error(`outline.level 은 1~6 정수다: ${level}`);
+    this.level = level;
+    this.headings = Object.freeze(checkedStrings(headings, "outline.headings"));
+    Object.freeze(this);
+  }
+
+  /** @param {unknown} raw */
+  static fromMapping(raw) {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw)) throw new Error("outline 은 JSON 객체다");
+    const data = /** @type {Record<string, unknown>} */ (raw);
+    const expected = ["level", "headings"];
+    const unknown = Object.keys(data).filter((key) => !expected.includes(key)).sort();
+    const missing = expected.filter((key) => !(key in data)).sort();
+    if (unknown.length) throw new Error(`outline 의 모르는 키: ${unknown.join(", ")}`);
+    if (missing.length) throw new Error(`outline 의 빠진 키: ${missing.join(", ")}`);
+    return new Outline(/** @type {number} */ (data.level), /** @type {string[]} */ (data.headings));
+  }
+
+  asDict() {
+    return { level: this.level, headings: [...this.headings] };
+  }
+}
+
+export class ContractV2 {
+  /** @param {string} reader @param {string} goal @param {string[]} facts @param {ProtectedSurface | Record<string, unknown>} surface @param {Outline | Record<string, unknown>} outline @param {number} [version] */
+  constructor(reader, goal, facts, surface, outline, version = LATEST_CONTRACT_VERSION, lockedFacts = [], editPolicy = {}) {
+    if (!Number.isInteger(version) || version !== LATEST_CONTRACT_VERSION) {
+      throw new Error(`reader contract version 은 ${LATEST_CONTRACT_VERSION}다: ${version}`);
+    }
+    this.reader = checkedString(reader, "reader");
+    this.goal = checkedString(goal, "goal");
+    this.facts = Object.freeze(checkedStrings(facts, "facts", true));
+    this.surface = surface instanceof ProtectedSurface ? surface : ProtectedSurface.fromMapping(surface);
+    this.outline = outline instanceof Outline ? outline : Outline.fromMapping(outline);
+    this.lockedFacts = Object.freeze(checkedStrings(lockedFacts, "lockedFacts", true));
+    if (this.lockedFacts.some((fact) => !this.facts.includes(fact))) throw new Error("lockedFacts must select approved facts");
+    if (!editPolicy || typeof editPolicy !== "object" || Array.isArray(editPolicy)) throw new Error("editPolicy must be an object");
+    this.editPolicy = Object.freeze(Object.fromEntries(Object.entries(editPolicy).sort(([a], [b]) => compareText(a, b)).map(([rule, limits]) => {
+      if (!rule || rule !== rule.trim()) throw new Error("editPolicy requires rule names");
+      if (!limits || typeof limits !== "object" || Array.isArray(limits) || Object.keys(limits).sort().join(",") !== "maxChars,maxLines") {
+        throw new Error("editPolicy requires maxChars and maxLines");
+      }
+      if (Object.values(limits).some((n) => !Number.isInteger(n) || n < 1)) throw new Error("editPolicy limits must be positive integers");
+      return [rule, Object.freeze({maxChars: limits.maxChars, maxLines: limits.maxLines})];
+    })));
+    this.version = version;
+    Object.freeze(this);
+  }
+
+  /** @param {unknown} raw */
+  static fromMapping(raw) {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw)) throw new Error("reader contract 는 JSON 객체다");
+    const data = /** @type {Record<string, unknown>} */ (raw);
+    const expected = ["version", "reader", "goal", "facts", "surface", "outline"];
+    const unknown = Object.keys(data).filter((key) => !expected.includes(key) && !["lockedFacts", "editPolicy"].includes(key)).sort();
+    const missing = expected.filter((key) => !(key in data)).sort();
+    if (unknown.length) throw new Error(`reader contract 의 모르는 키: ${unknown.join(", ")}`);
+    if (missing.length) throw new Error(`reader contract 의 빠진 키: ${missing.join(", ")}`);
+    return new ContractV2(
+      /** @type {string} */ (data.reader),
+      /** @type {string} */ (data.goal),
+      /** @type {string[]} */ (data.facts),
+      /** @type {Record<string, unknown>} */ (data.surface),
+      /** @type {Record<string, unknown>} */ (data.outline),
+      /** @type {number} */ (data.version),
+      Object.hasOwn(data, "lockedFacts") ? data.lockedFacts : [],
+      Object.hasOwn(data, "editPolicy") ? data.editPolicy : {},
+    );
+  }
+
+  get text() {
+    return [this.reader, this.goal, ...this.facts, this.surface.text].filter(Boolean).join("\n");
+  }
+
+  get digest() {
+    const encoded = {
+      ...(Object.keys(this.editPolicy).length ? {editPolicy: this.editPolicy} : {}),
+      facts: this.facts,
+      goal: this.goal,
+      ...(this.lockedFacts.length ? {lockedFacts: this.lockedFacts} : {}),
+      outline: { headings: this.outline.headings, level: this.outline.level },
+      reader: this.reader,
+      surface: {
+        code: this.surface.code,
+        links: this.surface.links,
+        numbers: this.surface.numbers,
+        urls: this.surface.urls,
+      },
+      version: this.version,
+    };
+    return digest(JSON.stringify(encoded));
+  }
+
+  asDict() {
+    return {
+      version: this.version,
+      reader: this.reader,
+      goal: this.goal,
+      facts: [...this.facts],
+      surface: this.surface.asDict(),
+      outline: this.outline.asDict(),
+      ...(this.lockedFacts.length ? {lockedFacts: [...this.lockedFacts]} : {}),
+      ...(Object.keys(this.editPolicy).length ? {editPolicy: this.editPolicy} : {}),
+    };
+  }
+}
+
+/** @param {unknown} raw */
+export function parseContract(raw) {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) throw new Error("reader contract 는 JSON 객체다");
+  const version = /** @type {Record<string, unknown>} */ (raw).version;
+  if (version === CONTRACT_VERSION) return Contract.fromMapping(raw);
+  if (version === LATEST_CONTRACT_VERSION) return ContractV2.fromMapping(raw);
+  throw new Error(`reader contract version 은 ${CONTRACT_VERSIONS.join(",")} 가운데 하나다: ${version}`);
+}

package/src/config/settings.js

@@ -14,22 +14,51 @@ import { projectPatches } from "../data/patches.js";
  */
 export const PRESETS = {
   blog: [],
-  report: ["noQuestion", "sectionResult", "firstResultDistance", "introImage", "moreLater", "numberOrphan"],
+  report: ["noQuestion", "firstResultDistance", "introImage", "moreLater", "numberOrphan"],
   docs: [
     "noQuestion",
-    "sectionResult",
     "firstResultDistance",
     "introImage",
     "moreLater",
     "draftHistory",
     "blockUnread",
     "numberOrphan",
+    "duplicateBlock",
+    "headingUniform",
   ],
 };
-PRESETS.guide = PRESETS.blog;
-PRESETS.essay = PRESETS.report;
-PRESETS.fiction = PRESETS.report;
-PRESETS.encyclopedia = PRESETS.docs;
+// 서사 글에서만 끄는 것. 설명글의 전제 (독자가 문장 사이 이유를 따라간다, 말끝을 맺는다) 가 장면과
+// 대사에는 성립하지 않는다. 파이썬 settings.py 의 NARRATIVE 와 같다.
+// 참고 문서와 자습서는 명령 전후 상태와 완결된 예제를 보이려 같은 블록을 다시 둔다. 파이썬의 REFERENCE 와 같다.
+const REFERENCE = ["duplicateBlock", "headingUniform"];
+// 백과 표제어는 첫 절 앞의 머리말이 길게 정의와 요약을 담는 것이 관례다. 파이썬의 ENCYCLOPEDIC 과 같다.
+const ENCYCLOPEDIC = ["introLong"];
+const NARRATIVE = ["factListParagraph"];
+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 = {
@@ -40,6 +69,7 @@ export const PROFILE_OF = {
   essay: "essay",
   fiction: "fiction",
   encyclopedia: "encyclopedia",
+  chat: null,
 };
 
 export const PRESET_NAMES = Object.keys(PRESETS);
@@ -49,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
@@ -73,13 +104,11 @@ export const DEFAULT_PRESET = PRESET_NAMES[0];
  * @property {number} endingRun
  * @property {number} factListMinSentences
  * @property {number} factListMaxMeanLength
- * @property {number} topicBreakMinSentences
+ * @property {number} flowValleyMinSentences
  * @property {number} longSentenceMax
  * @property {number} duplicateBlockRatio
  * @property {number} firstResultMaxParagraphs
- * @property {number} sectionResultMinParagraphs
  * @property {number} introMaxImages
- * @property {number} headingQuestionRatio
  * @property {number} moreLaterMaxChars
  * @property {number} tableOddCellMinRows
  * @property {number} registerMinShare
@@ -90,6 +119,7 @@ export function defaultConfig() {
   return {
     preset: DEFAULT_PRESET,
     disable: new Set(),
+    enforceStyle: [],
     keywordField: null,
     introFields: [],
     endingFields: [],
@@ -113,13 +143,11 @@ export function defaultConfig() {
     endingRun: 4,
     factListMinSentences: 3,
     factListMaxMeanLength: 8.0,
-    topicBreakMinSentences: 2,
+    flowValleyMinSentences: 2,
     longSentenceMax: 30,
     duplicateBlockRatio: 0.9,
     firstResultMaxParagraphs: 4,
-    sectionResultMinParagraphs: 3,
     introMaxImages: 1,
-    headingQuestionRatio: 0.5,
     moreLaterMaxChars: 150,
     tableOddCellMinRows: 4,
     // 기준 말뭉치에서 일관된 에세이 하위 5%는 0.7576, 실제 혼합 기사는 0.625였다.
@@ -129,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} */
@@ -151,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/build.js

@@ -98,20 +98,20 @@ import { overlap, topicsOf, unionOf } from "./topics.js";
  */
 
 /**
- * 문장 안의 인용 구간. 블록의 인라인 코드 구간을 문장 좌표로 옮기고 따옴표 쌍을 더한다.
+ * 문장 안의 인용 구간. 블록 좌표의 구간을 문장 좌표로 옮긴다. 따옴표 쌍도 블록에서 재서 넘겨받는다.
+ * 문장 안에서 재면 문장 분리가 따옴표 안에서 잘릴 때 쌍이 안 잡혀 인용 예외가 풀린다. 파이썬과 같다.
  * @param {import("../analysis/splitSentences.js").Sentence} sentence
- * @param {[number, number][]} blockCodeSpans
+ * @param {[number, number][]} blockSpans
  * @returns {[number, number][]}
  */
-function quotedIn(sentence, blockCodeSpans) {
+function quotedIn(sentence, blockSpans) {
   /** @type {[number, number][]} */
   const spans = [];
-  for (const [start, end] of blockCodeSpans) {
+  for (const [start, end] of blockSpans) {
     const lo = Math.max(start, sentence.start);
     const hi = Math.min(end, sentence.end);
     if (lo < hi) spans.push([lo - sentence.start, hi - sentence.start]);
   }
-  spans.push(...markers.quoteSpans(sentence.text));
   const unique = new Map(spans.map((span) => [`${span[0]},${span[1]}`, span]));
   return [...unique.values()].sort((a, b) => a[0] - b[0] || a[1] - b[1]);
 }
@@ -219,12 +219,15 @@ function buildSection(build, section, sectionIndex) {
       continue;
     }
     const text = plainText(block.text);
-    const blockCodeSpans = codeSpans(block.text, text);
+    // 인라인 코드와 따옴표 쌍을 둘 다 블록 좌표에서 잰다. 문장 분리가 인용 안에서 잘려도 쌍이 남는다.
+    const blockSpans = [...codeSpans(block.text, text), ...markers.quoteSpans(text)].sort(
+      (a, b) => a[0] - b[0] || a[1] - b[1],
+    );
     /** @type {SentencePrint[]} */
     const blockSentences = [];
     for (const sentence of splitSentences(text)) {
       const line = block.startLine + countIn(text, "\n", sentence.start);
-      const quoted = quotedIn(sentence, blockCodeSpans);
+      const quoted = quotedIn(sentence, blockSpans);
       const made = makeSentencePrint(build, sentence.text, line, block, sectionIndex, quoted);
       // 만든 자리에서 바로 쌓는다. 다음 문장의 index 가 이 길이에서 나오므로 미루면 셈이 어긋난다.
       sentences.push(made);

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;
+}