hanlint 0.0.8 → 0.0.10

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

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

package/src/index.js

@@ -13,15 +13,53 @@
 import { readFileSync } from "node:fs";
 
 import { loadConfig } from "./config/loadConfig.js";
+import { Patch } from "./config/patch.js";
+import {
+  CONTRACT_VERSION,
+  CONTRACT_VERSIONS,
+  LATEST_CONTRACT_VERSION,
+  Contract,
+  ContractV2,
+  Outline,
+  ProtectedSurface,
+  parseContract,
+} from "./config/readerContract.js";
 import { configFromMapping, defaultConfig } from "./config/settings.js";
 import { loadVersion } from "./data/load.js";
 import { parseMarkdown } from "./document/parseMarkdown.js";
 import { applyFixes } from "./edit/applyFixes.js";
 import { buildFingerprint } from "./fingerprint/build.js";
 import { fingerprintDict } from "./report/fingerprintJson.js";
+import { check, contractFromText, contractFromTextV2, verifyPatch } from "./guard/contract.js";
+import { CheckResult, PatchResult, renderCheck } from "./guard/receipt.js";
 import { ruleDoc, ruleNames, ruleSummary, runAll } from "./rules/registry.js";
 
-export { applyFixes, configFromMapping, defaultConfig, fingerprintDict, loadConfig, ruleDoc, ruleNames, ruleSummary };
+export {
+  CheckResult,
+  CONTRACT_VERSION,
+  CONTRACT_VERSIONS,
+  Contract,
+  ContractV2,
+  LATEST_CONTRACT_VERSION,
+  Outline,
+  Patch,
+  PatchResult,
+  ProtectedSurface,
+  applyFixes,
+  check,
+  contractFromText,
+  contractFromTextV2,
+  configFromMapping,
+  defaultConfig,
+  fingerprintDict,
+  loadConfig,
+  parseContract,
+  renderCheck,
+  ruleDoc,
+  ruleNames,
+  ruleSummary,
+  verifyPatch,
+};
 export const version = loadVersion();
 
 /**

package/src/report/compactReport.js

@@ -9,6 +9,6 @@ function flat(text) {
 /** @param {string} path @param {import("../rules/finding.js").Finding[]} findings */
 export function renderCompact(path, findings) {
   return findings
-    .map((f) => `${path}:${f.line} [${f.rule}] ${flat(f.why)}` + (f.fix ? `  고친 뒤: ${flat(f.fix)}` : ""))
+    .map((f) => `${path}:${f.line} [${f.rule}] ${f.severity === "notice" ? "notice: " : ""}${flat(f.why)}` + (f.fix ? `  고친 뒤: ${flat(f.fix)}` : ""))
     .join("\n");
 }

package/src/report/writingSpec.js

@@ -0,0 +1,174 @@
+// @ts-check
+/** 쓰기 전 숫자 사양. 파이썬 config/writingSpec.py와 같은 셈과 글자를 낸다. */
+
+import { HAPNIDA, REGISTERS } from "../analysis/grammar/index.js";
+import { PROFILE_OF, defaultConfig, enabled } from "../config/settings.js";
+import { profileOf, userProfile } from "../data/profiles.js";
+
+export const SPEC_VERSION = 1;
+const CHARS_PER_WORD = 6;
+
+/** 양수 반올림. 파이썬의 nearest와 같다. @param {number} value */
+function nearest(value) {
+  return Math.floor(value + 0.5);
+}
+
+/** @param {import("../data/profiles.js").Histogram} histogram @param {number} level */
+function percentile(histogram, level) {
+  return histogram.percentiles.get(level) ?? 0;
+}
+
+/** @param {number} value */
+function percent(value) {
+  return nearest(value * 100);
+}
+
+/** @param {import("./settings.js").Config} config */
+function selectedProfile(config) {
+  if (config.profile) return userProfile(config.profile);
+  const kind = PROFILE_OF[config.preset];
+  if (kind === null) throw new Error(`${config.preset} 은 종류 프로파일이 없어 사양을 낼 수 없다`);
+  const profile = profileOf(kind);
+  if (profile === null) throw new Error(`${kind} 프로파일을 찾지 못했다`);
+  return profile;
+}
+
+/**
+ * 현재 규칙판을 쓰기 전 숫자 사양으로 편다. 품질 점수나 새 임계는 만들지 않는다.
+ * @param {import("./settings.js").Config} [config]
+ * @param {string} [register]
+ * @param {number | null} [targetChars]
+ */
+export function writingSpec(config = defaultConfig(), register = HAPNIDA, targetChars = null) {
+  if (!REGISTERS.includes(register)) throw new Error(`register 는 ${REGISTERS.join(", ")} 가운데 하나다: ${register}`);
+  if (targetChars !== null && targetChars <= 0) throw new Error(`chars 는 1 이상이어야 한다: ${targetChars}`);
+  const profile = selectedProfile(config);
+  const sentence = profile.sentence;
+  const paragraph = profile.paragraph.get("sentenceCount");
+  if (!paragraph) throw new Error("프로파일에 paragraph.sentenceCount가 없다");
+  const perParagraph = percentile(paragraph, 50);
+  if (perParagraph <= 0) throw new Error("프로파일의 문단당 문장 중앙값이 1 이상이어야 한다");
+  const lengthHistogram = sentence.get("length");
+  if (!lengthHistogram) throw new Error("프로파일에 sentence.length가 없다");
+  const lengthP50 = percentile(lengthHistogram, 50);
+  if (lengthP50 <= 0) throw new Error("프로파일의 문장 길이 중앙값이 1 이상이어야 한다");
+
+  const rows = [];
+  let amount = `문단마다 문장 ${perParagraph}~${percentile(paragraph, 90)}개`;
+  if (targetChars !== null) {
+    const sentences = Math.max(1, nearest(targetChars / CHARS_PER_WORD / lengthP50));
+    const paragraphs = Math.max(1, nearest(sentences / perParagraph));
+    amount = `문단 ${paragraphs}개, ${amount}, 문장 ${sentences}개 안팎`;
+  }
+  rows.push({ id: "amount", label: "분량", guidance: amount, basis: [`profile.${profile.kind}.paragraph.sentenceCount`] });
+
+  let length = `중앙 ${lengthP50}어절, 문장 90%가 ${percentile(lengthHistogram, 90)}어절 이하`;
+  const lengthBasis = [`profile.${profile.kind}.sentence.length`];
+  if (enabled(config, "longSentence")) {
+    length += `. ${config.longSentenceMax}어절을 넘으면 longSentence가 지적`;
+    lengthBasis.push("rule.longSentence");
+  }
+  rows.push({ id: "sentenceLength", label: "문장 길이", guidance: length, basis: lengthBasis });
+
+  if (profile.endingRuns !== null) {
+    let endingText = `같은 끝맺음 연속 중앙 ${percentile(profile.endingRuns, 50)}개, 90%가 ${percentile(profile.endingRuns, 90)}개 이하`;
+    const endingBasis = [`profile.${profile.kind}.endingRuns`];
+    if (enabled(config, "endingRepeat")) {
+      endingText += `. 인과나 독자 호출 없이 ${config.endingRun}개부터 endingRepeat가 지적`;
+      endingBasis.push("rule.endingRepeat");
+    }
+    rows.push({ id: "endingRun", label: "끝맺음", guidance: endingText, basis: endingBasis });
+  }
+
+  const commas = sentence.get("commas");
+  if (!commas) throw new Error("프로파일에 sentence.commas가 없다");
+  rows.push({
+    id: "commas",
+    label: "쉼표",
+    guidance: `문장 중앙 ${percentile(commas, 50)}개, 90%가 ${percentile(commas, 90)}개 이하, 99%가 ${percentile(commas, 99)}개 이하`,
+    basis: [`profile.${profile.kind}.sentence.commas`],
+  });
+
+  const eui = sentence.get("euiCount");
+  if (!eui) throw new Error("프로파일에 sentence.euiCount가 없다");
+  let euiText = `문장 중앙 ${percentile(eui, 50)}개, 90%가 ${percentile(eui, 90)}개 이하`;
+  const euiBasis = [`profile.${profile.kind}.sentence.euiCount`];
+  if (enabled(config, "euiChain")) {
+    euiText += ". 3개부터, 붙은 2개부터 euiChain이 지적";
+    euiBasis.push("rule.euiChain");
+  }
+  rows.push({ id: "euiCount", label: "의", guidance: euiText, basis: euiBasis });
+
+  const nounRun = sentence.get("nounRun");
+  if (!nounRun) throw new Error("프로파일에 sentence.nounRun이 없다");
+  let nounText = `문장 90%에서 조사 없는 명사 연쇄가 ${percentile(nounRun, 90)}개 이하`;
+  const nounBasis = [`profile.${profile.kind}.sentence.nounRun`];
+  if (enabled(config, "nounPile")) {
+    nounText += `. ${config.nounPileMin}개부터 nounPile이 지적`;
+    nounBasis.push("rule.nounPile");
+  }
+  rows.push({ id: "nounRun", label: "명사 연쇄", guidance: nounText, basis: nounBasis });
+
+  const newTopics = sentence.get("newTopics");
+  if (!newTopics) throw new Error("프로파일에 sentence.newTopics가 없다");
+  rows.push({
+    id: "newTopics",
+    label: "새 화제",
+    guidance: `문장 중앙 ${percentile(newTopics, 50)}개, 90%가 ${percentile(newTopics, 90)}개 이하`,
+    basis: [`profile.${profile.kind}.sentence.newTopics`],
+  });
+
+  const connector = profile.rates.connector;
+  rows.push({
+    id: "connector",
+    label: "문두 접속",
+    guidance: `문서 중앙은 문장의 ${percent(connector.p50)}%, 문서 90%가 ${percent(connector.p90)}% 이하`,
+    basis: [`profile.${profile.kind}.rates.connector`],
+  });
+
+  const numbers = sentence.get("numbers");
+  if (!numbers) throw new Error("프로파일에 sentence.numbers가 없다");
+  const numberP50 = percentile(numbers, 50);
+  const numberP90 = percentile(numbers, 90);
+  const numberText =
+    numberP50 === 0 && numberP90 === 0
+      ? "문장 중앙과 90%에서 숫자 없음"
+      : `문장 중앙 ${numberP50}개, 90%가 ${numberP90}개 이하`;
+  rows.push({ id: "numbers", label: "숫자", guidance: numberText, basis: [`profile.${profile.kind}.sentence.numbers`] });
+
+  const question = profile.rates.question;
+  let questionText;
+  let questionBasis;
+  if (enabled(config, "noQuestion")) {
+    questionText = config.enforceStyle.includes("noQuestion")
+      ? "선택한 정책: 절이 2개 이상이면 글 전체에 물음표 최소 1개"
+      : "물음표 부재는 notice다. 질문 없이 충분히 설명했다면 유지한다";
+    questionBasis = [`profile.${profile.kind}.rates.question`, "rule.noQuestion"];
+  } else {
+    questionText = `규칙 요구 없음. 문서 중앙은 문장의 ${percent(question.p50)}%, 문서 90%가 ${percent(question.p90)}% 이하`;
+    questionBasis = [`profile.${profile.kind}.rates.question`];
+  }
+  rows.push({ id: "question", label: "물음표", guidance: questionText, basis: questionBasis });
+
+  return {
+    version: SPEC_VERSION,
+    kind: "hanlint.writingSpec",
+    preset: config.preset,
+    register,
+    targetChars,
+    profile: profile.kind,
+    rows,
+  };
+}
+
+/** 사람이 읽는 꼴. basis는 JSON에서 확인한다. @param {ReturnType<typeof writingSpec>} spec */
+export function renderWritingSpec(spec) {
+  const target = spec.targetChars !== null ? `, ${spec.targetChars}자` : "";
+  const lines = [
+    `hanlint spec  ${spec.preset} 종류, ${spec.register}체${target}. 같은 규칙판의 임계와 ${spec.profile} 프로파일을 쓰기 전 숫자로 편다`,
+  ];
+  const width = Math.max(...spec.rows.map((row) => row.label.length));
+  for (const row of spec.rows) lines.push(`  ${row.label.padEnd(width)}  ${row.guidance}`);
+  lines.push("", "이 사양은 품질 점수가 아니다. 쓴 뒤 같은 설정으로 hanlint <글.md>를 실행해 Finding을 확인한다");
+  return lines.join("\n");
+}

package/src/rules/code/inputFileSource.js

@@ -33,15 +33,15 @@ export function run(doc) {
   const reported = new Set();
   for (const block of doc.codeBlocks) {
     const reader = doc.reader.beforeBlock[block.index];
-    const [blockWrites, blockDirs] = createdIn(block.lines.map(([, line]) => line));
-    // 이 블록이 만드는 폴더는 같은 블록의 읽기에도 미리 센다. 파일은 블록 안에서 쓴 것 (blockWrites) 만 따로 본다.
+    const [, blockDirs] = createdIn(block.lines.map(([, line]) => line));
+    // 폴더 준비는 블록 단위로 보고 파일 공급은 실제 줄 순서로 쌓는다.
     const have = new Set([...reader.files, ...blockDirs, ...reported]);
     for (const [line, code] of block.lines) {
       const reads = readsIn(code);
       for (const path of reads) {
         if (!isDataFile(path)) continue;
         const name2 = fileName(path);
-        if (have.has(name2) || blockWrites.has(name2) || doc.reader.mentionedBefore(block.index, name2)) continue;
+        if (have.has(name2) || doc.reader.mentionedBefore(block.index, name2)) continue;
         findings.push(finding(name, line, code.trim(), `\`${name2}\` 을 읽는데 글 어디에서도 만들지 않았다. 독자는 여기서 파일 없음 오류로 멈춘다`, null, "error", DOCUMENT, block.index));
       }
       for (const path of [...writeTargets(code), ...reads]) {
@@ -52,6 +52,8 @@ export function run(doc) {
         reported.add(directory);
         findings.push(finding(name, line, code.trim(), `\`${directory}\` 폴더를 쓰는데 글 어디에서도 만들지 않았다. 없으면 파일을 쓰다 멈춘다`, null, NOTICE, DOCUMENT, block.index));
       }
+      const [made] = createdIn([code]);
+      for (const file of made) have.add(file);
     }
   }
   return findings;