hanlint 0.0.9 → 0.0.12

package/src/index.js

@@ -8,20 +8,69 @@
  * ```
  *
  * 합격과 불합격을 판정하지 않는다. 지적 목록이 비어 있다는 것은 세어서 잡히는 결함이 없다는 뜻이다.
- * 지문 지도 (audit, map) 와 프로파일은 파이썬 패키지에 있다.
+ * 같은 공개 API를 Node와 브라우저가 공유한다. 파일 경로를 읽는 API만 Node 전용이다.
  */
-import { readFileSync } from "node:fs";
-
-import { loadConfig } from "./config/loadConfig.js";
+import { readExternal } from "./data/read.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 { headingsOf } from "./document/model.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 { compareOutline } from "./guard/outline.js";
+import { protectedSurface, surfaceDiff } from "./guard/surface.js";
 import { ruleDoc, ruleNames, ruleSummary, runAll } from "./rules/registry.js";
+import { renderJson } from "./report/jsonReport.js";
+import { learnExemplars } from "./learn/edits.js";
+import { learnOperations } from "./learn/operations.js";
+
+const nodeConfig = typeof process === "object" && process.versions?.node ? await import("./config/loadConfig.js") : null;
 
-export { applyFixes, configFromMapping, defaultConfig, fingerprintDict, loadConfig, ruleDoc, ruleNames, ruleSummary };
+/** Node 파일 설정. 브라우저에서는 configFromMapping에 설정 객체를 전달한다. @param {string | null} path @param {string | null} start */
+export function loadConfig(path = null, start = null) {
+  if (!nodeConfig) throw new Error("브라우저에서는 configFromMapping으로 설정 객체를 전달해 주세요.");
+  return nodeConfig.loadConfig(path, start);
+}
+
+export {
+  CheckResult,
+  CONTRACT_VERSION,
+  CONTRACT_VERSIONS,
+  Contract,
+  ContractV2,
+  LATEST_CONTRACT_VERSION,
+  Outline,
+  Patch,
+  PatchResult,
+  ProtectedSurface,
+  applyFixes,
+  check,
+  contractFromText,
+  contractFromTextV2,
+  configFromMapping,
+  defaultConfig,
+  fingerprintDict,
+  parseContract,
+  renderCheck,
+  ruleDoc,
+  ruleNames,
+  ruleSummary,
+  verifyPatch,
+};
 export const version = loadVersion();
 
 /**
@@ -50,5 +99,33 @@ export function lintText(text, config = defaultConfig(), path = null) {
  * @param {import("./config/settings.js").Config} [config]
  */
 export function lintFile(path, config = defaultConfig()) {
-  return lintText(readFileSync(path, "utf-8"), config, path);
+  return lintText(readExternal(path), config, path);
+}
+
+/** 지적, 문체 본보기, 승인 고침과 지문을 같은 분석에서 제공한다. @param {string} text @param {import("./config/settings.js").Config} config */
+export function inspectText(text, config = defaultConfig()) {
+  const document = fingerprint(text, config);
+  const findings = runAll(document, config);
+  const path = "draft.md";
+  const report = JSON.parse(renderJson(new Map([[path, findings]]), null,
+    new Map([[path, document.register]]), config.preset, config.exemplars,
+    new Map([[path, document]]), config.patches, config.operations, config.protectedTerms));
+  return { findings, report: report.files[0], document: fingerprintDict(document) };
+}
+
+/** 사람 수정 전후에서 승인할 후보를 추출한다. 후보 자체는 승인이 아니다. @param {string} before @param {string} after @param {import("./config/settings.js").Config} config */
+export function learnText(before, after, config = defaultConfig()) {
+  const beforeDoc = fingerprint(before, config), afterDoc = fingerprint(after, config);
+  return {
+    exemplars: learnExemplars(beforeDoc, afterDoc, runAll(beforeDoc, config), runAll(afterDoc, config), config.preset),
+    operations: learnOperations(beforeDoc, afterDoc, config.preset, config.protectedTerms),
+  };
+}
+
+/** 자유 원고의 표면과 H2 순서를 비교한다. 빈 글과 반복 제목도 관찰하며 승인 계약을 만들지 않는다. @param {string} before @param {string} after @param {import("./config/settings.js").Config} config */
+export function compareRevision(before, after, config = defaultConfig()) {
+  const original = before.normalize("NFC");
+  const outline = { level: 2, headings: headingsOf(parseMarkdown(original), 2).map((heading) => heading.text) };
+  return { surface: protectedSurface(original), changes: surfaceDiff(original, after),
+    outline: compareOutline(outline, fingerprint(after, config)) };
 }

package/src/learn/edits.js

@@ -0,0 +1,31 @@
+// @ts-check
+/** Python learn/edits.py와 같은 원문 문장 대응 및 지적 소멸 후보다. */
+import { sourceSentenceTexts } from "../fingerprint/sourceSentence.js";
+import { readerKind } from "../fingerprint/readerState.js";
+import { localCue, SENTENCE } from "../rules/finding.js";
+import { changedSentencePairs } from "./pairs.js";
+
+export function learnExemplars(beforeDoc, afterDoc, beforeFindings, afterFindings, preset = null) {
+  const pairs = changedSentencePairs(beforeDoc.sentences, afterDoc.sentences);
+  const rawBefore = sourceSentenceTexts(beforeDoc), rawAfter = sourceSentenceTexts(afterDoc);
+  const remaining = new Set(afterFindings.filter((item) => item.scope === SENTENCE && item.at >= 0).map((item) => `${item.rule}:${item.at}`));
+  const beforeByIndex = new Map(beforeDoc.sentences.map((item) => [item.index, item]));
+  const seen = new Set(), learned = [];
+  for (const finding of beforeFindings) {
+    const key = `${finding.rule}:${finding.at}`;
+    if (finding.scope !== SENTENCE || finding.at < 0 || seen.has(key)) continue;
+    const after = pairs.get(finding.at), before = beforeByIndex.get(finding.at);
+    if (!after || !before || after.some((item) => remaining.has(`${finding.rule}:${item.index}`))) continue;
+    const afterPlain = after.map((item) => item.text.trim()).filter(Boolean).join(" ");
+    const afterText = after.filter((item) => item.text.trim()).map((item) => (rawAfter.get(item.index) ?? item.text).trim()).join(" ");
+    if (!afterText || before.text.trim() === afterPlain) continue;
+    seen.add(key);
+    learned.push({ rule: finding.rule, before: (rawBefore.get(before.index) ?? before.text).trim(), after: afterText,
+      moved: "실제 수정본의 문장으로 바꿈", why: finding.why, beforeLine: before.line,
+      afterLines: [...new Set(after.map((item) => item.line))], sentence: before.text.trim(),
+      cue: localCue(finding), reader: readerKind(before, beforeDoc.reader.beforeSentence[finding.at]),
+      ...(preset ? { presets: [preset] } : {}),
+    });
+  }
+  return learned;
+}

package/src/learn/operations.js

@@ -0,0 +1,28 @@
+// @ts-check
+/** Python learn/operations.py의 표면 치환 후보와 증거 묶음. */
+import { operationFromApproval } from "../data/operations.js";
+import { sourceSentenceTexts } from "../fingerprint/sourceSentence.js";
+import { changedSentencePairs } from "./pairs.js";
+
+export function learnOperations(beforeDoc, afterDoc, preset = null, protectedTerms = []) {
+  const pairs = changedSentencePairs(beforeDoc.sentences, afterDoc.sentences);
+  const rawBefore = sourceSentenceTexts(beforeDoc), rawAfter = sourceSentenceTexts(afterDoc);
+  const beforeByIndex = new Map(beforeDoc.sentences.map((item) => [item.index, item]));
+  const grouped = new Map(), presets = preset ? [preset] : [];
+  for (const [index, after] of pairs) {
+    const before = beforeByIndex.get(index);
+    if (after.length !== 1 || !before) continue;
+    const sourceBefore = (rawBefore.get(index) ?? before.text).trim();
+    const sourceAfter = (rawAfter.get(after[0].index) ?? after[0].text).trim();
+    const operation = operationFromApproval(sourceBefore, sourceAfter, presets, protectedTerms);
+    if (!operation) continue;
+    const key = JSON.stringify([operation.before, operation.after]);
+    const item = grouped.get(key) ?? { kind: "surfaceSubstitution", before: operation.before, after: operation.after, evidence: [] };
+    item.evidence.push({ sourceBefore, sourceAfter, beforeLine: before.line, afterLine: after[0].line });
+    grouped.set(key, item);
+  }
+  return [...grouped.values()].map((item) => ({ ...item, evidenceCount: item.evidence.length,
+    guards: { maximumCharacters: 32, maximumSurfaceEditDistance: 1, protectedFacts: true, uniqueWordBoundary: true },
+    ...(preset ? { presets } : {}),
+  }));
+}

package/src/learn/pairs.js

@@ -0,0 +1,57 @@
+// @ts-check
+/** Python SequenceMatcher(autojunk=False)의 문장 대응. 가장 긴 연속 일치의 앞쪽을 먼저 택한다. */
+function longest(left, right, start, end, otherStart, otherEnd) {
+  let best = [start, otherStart, 0], previous = new Map();
+  const positions = new Map();
+  for (let index = otherStart; index < otherEnd; index++) {
+    const list = positions.get(right[index]) ?? [];
+    list.push(index);
+    positions.set(right[index], list);
+  }
+  for (let index = start; index < end; index++) {
+    const current = new Map();
+    for (const other of positions.get(left[index]) ?? []) {
+      const size = (previous.get(other - 1) ?? 0) + 1;
+      current.set(other, size);
+      if (size > best[2]) best = [index - size + 1, other - size + 1, size];
+    }
+    previous = current;
+  }
+  return best;
+}
+
+/** @param {string[]} left @param {string[]} right */
+export function changedRanges(left, right) {
+  const pending = [[0, left.length, 0, right.length]], blocks = [];
+  while (pending.length) {
+    const [start, end, otherStart, otherEnd] = pending.pop();
+    const [at, other, size] = longest(left, right, start, end, otherStart, otherEnd);
+    if (!size) continue;
+    blocks.push([at, other, size]);
+    if (start < at && otherStart < other) pending.push([start, at, otherStart, other]);
+    if (at + size < end && other + size < otherEnd) pending.push([at + size, end, other + size, otherEnd]);
+  }
+  blocks.sort((a, b) => a[0] - b[0] || a[1] - b[1]);
+  blocks.push([left.length, right.length, 0]);
+  const ranges = [];
+  let start = 0, otherStart = 0;
+  for (const [at, other, size] of blocks) {
+    if (start < at || otherStart < other) ranges.push([start, at, otherStart, other]);
+    start = at + size;
+    otherStart = other + size;
+  }
+  return ranges;
+}
+
+/** 기존 Python learn의 일대일 및 한 문장 분할 대응을 그대로 따른다. */
+export function changedSentencePairs(before, after) {
+  const pairs = new Map();
+  for (const [start, end, otherStart, otherEnd] of changedRanges(before.map((item) => item.text), after.map((item) => item.text))) {
+    const count = end - start, otherCount = otherEnd - otherStart;
+    if (!count || !otherCount) continue;
+    if (count === otherCount) {
+      for (let offset = 0; offset < count; offset++) pairs.set(before[start + offset].index, [after[otherStart + offset]]);
+    } else if (count === 1) pairs.set(before[start].index, after.slice(otherStart, otherEnd));
+  }
+  return pairs;
+}

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;

package/src/rules/code/installImport.js

@@ -18,14 +18,14 @@ function stdlib() {
   return stdlibCache;
 }
 
-/** @type {Map<string, string> | null} */
+/** @type {Map<string, Set<string>> | null} */
 let packageCache = null;
 function packageOf() {
   if (!packageCache) {
     packageCache = new Map();
     for (const line of loadLines("pythonPackages.txt")) {
       const [module, pkg] = line.split("\t");
-      packageCache.set(module, pkg);
+      packageCache.set(module, new Set(pkg.split("|").map(normalize)));
     }
   }
   return packageCache;
@@ -105,9 +105,10 @@ export function run(doc) {
         for (const module of modules) {
           const top = module.split(".")[0];
           if (!top || stdlib().has(top) || local.has(top)) continue;
-          const pkg = normalize(packageOf().get(top) ?? top);
-          if (!packages.has(pkg)) {
-            findings.push(finding(name, line, code.trim(), `\`${top}\` 를 import 하는데 설치 줄에 \`${pkg}\` 가 없다. 독자는 ModuleNotFoundError 에서 멈춘다`, null, "error", DOCUMENT, block.index));
+          const acceptable = packageOf().get(top) ?? new Set([normalize(top)]);
+          if (![...acceptable].some((pkg) => packages.has(pkg))) {
+            const packageNames = [...acceptable].sort().join("`, `");
+            findings.push(finding(name, line, code.trim(), `\`${top}\` 를 import 하는데 설치 줄에 허용되는 이름 \`${packageNames}\` 가 없다. 독자는 ModuleNotFoundError 에서 멈춘다`, null, "error", DOCUMENT, block.index));
           }
         }
       }

package/src/rules/document/noQuestion.js

@@ -5,11 +5,11 @@ export const name = "noQuestion";
 export const mechanism = "threshold";
 
 /** @param {import("../../fingerprint/build.js").DocumentPrint} doc */
-export function run(doc) {
+export function run(doc, config) {
   if (doc.bodySections.length < 2 || doc.questionCount > 0) return [];
   const first = doc.sentences.length ? doc.sentences[0] : null;
   const why = doc.readerCallCount === 0
-    ? "물음표가 한 번도 없고 독자를 부르는 말도 없다. 독자가 품을 의문을 한 번은 대신 묻고, 독자가 할 행동을 동사로 끝내는 문장을 넣는다"
-    : "물음표가 한 번도 없다. 독자가 품을 의문을 한 번은 대신 묻고 다음 문장에서 답한다";
-  return [finding(name, first ? first.line : 1, first ? first.text : "", why, null, "error", DOCUMENT, -1)];
+    ? "물음표가 한 번도 없고 독자를 부르는 말도 없다. 질문이나 독자 호출이 필요한 글인지 판단하고 충분하면 유지한다"
+    : "물음표가 한 번도 없다. 질문이 필요한 글인지 판단하고 설명만으로 충분하면 유지한다";
+  return [finding(name, first ? first.line : 1, first ? first.text : "", why, null, config.enforceStyle.includes(name) ? "error" : "notice", DOCUMENT, -1)];
 }

package/src/rules/readerDebt.js

@@ -0,0 +1,9 @@
+// @ts-check
+/** 독자 부채는 새 판정이 아니라 reader 기제 Finding을 사람이 읽는 이름으로 묶은 것이다. */
+
+import { ruleMechanism } from "./registry.js";
+
+/** @param {import("./finding.js").Finding[]} findings */
+export function readerDebts(findings) {
+  return findings.filter((finding) => ruleMechanism(finding.rule) === "reader");
+}

package/src/rules/registry.js

@@ -56,6 +56,9 @@ import * as headingSkip from "./structure/headingSkip.js";
 import * as headingUniform from "./structure/headingUniform.js";
 import * as introLong from "./structure/introLong.js";
 import * as sectionNoProse from "./structure/sectionNoProse.js";
+import * as screenNarration from "./screen/screenNarration.js";
+import * as screenSentence from "./screen/screenSentence.js";
+import * as screenTone from "./screen/screenTone.js";
 
 /**
  * @typedef {object} Rule
@@ -116,6 +119,9 @@ export const RULES = [
   duplicateBlock,
   firstResultDistance,
   platformApi,
+  screenNarration,
+  screenSentence,
+  screenTone,
 ];
 
 /**
@@ -154,6 +160,33 @@ export function ruleSummary(name) {
   return ruleDoc(name).split("\n")[0];
 }
 
+/** 기술서의 네 절 표. 파이썬 rules/registry.py 의 REQUIRED_SECTIONS 와 같다. */
+export const REQUIRED_SECTIONS = ["왜:", "어디서:", "고치기:", "안 잡는 것:"];
+
+/** 기술서에서 절 하나의 본문을 한 줄로. 파이썬 docSection 과 같다. @param {string} doc @param {string} label */
+export function docSection(doc, label) {
+  const collected = [];
+  let inside = false;
+  for (const raw of doc.split("\n")) {
+    const line = raw.trim();
+    if (!inside) {
+      if (line.startsWith(label)) {
+        inside = true;
+        collected.push(line.slice(label.length).trim());
+      }
+      continue;
+    }
+    if (!line || REQUIRED_SECTIONS.some((other) => line.startsWith(other))) break;
+    collected.push(line);
+  }
+  return collected.filter(Boolean).join(" ");
+}
+
+/** 규칙의 고치기 절 한 줄. primer 가 쓰기 전에 읽히는 그 문장이다. @param {string} name */
+export function ruleFix(name) {
+  return docSection(ruleDoc(name), "고치기:");
+}
+
 /**
  * 부류의 사람 이름. 파이썬 rules/registry.py 의 CATEGORY_TITLES 와 같은 값과 같은 순서다.
  * @type {Record<string, string>}
@@ -165,6 +198,7 @@ export const CATEGORY_TITLES = {
   document: "두 자리를 대조해 세는 것",
   orthography: "표기와 띄어쓰기",
   code: "코드 블록 사이를 대조하는 것",
+  screen: "화면의 글에서 세는 것",
 };
 
 /** 규칙이 세는 방법. @param {string} name */

package/src/rules/screen/screenNarration.js

@@ -0,0 +1,10 @@
+// @ts-check
+import { firstMatchFindings } from "../shared/dictionaryRule.js";
+
+export const name = "screenNarration";
+export const mechanism = "dictionary";
+
+/** @param {import("../../fingerprint/build.js").DocumentPrint} doc */
+export function run(doc) {
+  return firstMatchFindings(doc, "screenNarration", name);
+}

package/src/rules/screen/screenSentence.js

@@ -0,0 +1,10 @@
+// @ts-check
+import { firstMatchFindings } from "../shared/dictionaryRule.js";
+
+export const name = "screenSentence";
+export const mechanism = "dictionary";
+
+/** @param {import("../../fingerprint/build.js").DocumentPrint} doc */
+export function run(doc) {
+  return firstMatchFindings(doc, "screenSentence", name);
+}

package/src/rules/screen/screenTone.js

@@ -0,0 +1,10 @@
+// @ts-check
+import { firstMatchFindings } from "../shared/dictionaryRule.js";
+
+export const name = "screenTone";
+export const mechanism = "dictionary";
+
+/** @param {import("../../fingerprint/build.js").DocumentPrint} doc */
+export function run(doc) {
+  return firstMatchFindings(doc, "screenTone", name);
+}

package/src/rules/sentence/nounPile.js

@@ -13,7 +13,7 @@ export function run(doc, config) {
   for (const sentence of doc.sentences) {
     if (sentence.nounRun >= config.nounPileMin) {
       findings.push(
-        finding(name, sentence.line, sentence.text, `명사 ${sentence.nounRun}개가 조사 없이 이어진다. 관계가 표시되지 않아 독자가 조사를 끼워 넣는다. 동사로 되돌린다`, null, "error", SENTENCE, sentence.index),
+        finding(name, sentence.line, sentence.text, `명사 ${sentence.nounRun}개가 조사 없이 이어진다. 관계가 표시되지 않아 독자가 조사를 끼워 넣는다. 동사로 되돌린다`, null, config.enforceStyle.includes(name) ? "error" : "notice", SENTENCE, sentence.index),
       );
     }
   }

package/src/rules/shared/dictionaryRule.js

@@ -43,3 +43,33 @@ export function dictionaryFindings(doc, dictionary, ruleName, severity = ERROR)
   }
   return findings;
 }
+
+/**
+ * 문장마다 가장 앞의 매치 하나만 지적한다. 뜻은 파이썬 rules/shared/dictionaryRule.py 의 firstMatchFindings 가 소유한다.
+ * 구체 무늬와 종결어미가 한 사전에 같이 사는 화면 사전에 쓴다. fix 는 내지 않는다.
+ * @param {import("../../fingerprint/build.js").DocumentPrint} doc
+ * @param {string} dictionary
+ * @param {string} ruleName
+ * @param {string} [severity]
+ * @returns {import("../finding.js").Finding[]}
+ */
+export function firstMatchFindings(doc, dictionary, ruleName, severity = ERROR) {
+  const findings = [];
+  for (const sentence of doc.sentences) {
+    const match = sentence.matches.find((m) => m.dictionary === dictionary);
+    if (!match) continue;
+    findings.push(
+      finding(
+        ruleName,
+        sentence.line + countNewlines(sentence.text.slice(0, match.start)),
+        sentence.text,
+        `\`${match.text}\` ${match.why} (${match.source})`,
+        null,
+        severity,
+        SENTENCE,
+        sentence.index,
+      ),
+    );
+  }
+  return findings;
+}