hanlint 0.0.10 → 0.0.13

package/src/cli/main.js

@@ -46,7 +46,9 @@ import { exemplarFor } from "../data/exemplars.js";
 import { patterns, patternsAvoiding } from "../data/patterns.js";
 import { HAPNIDA, REGISTERS } from "../analysis/grammar/index.js";
 import { CATEGORY_TITLES, MECHANISMS, ruleCategory, ruleFix, ruleMechanism, runAll } from "../rules/registry.js";
-import { MARKDOWN, SKIPPED_FOLDERS, markdownUnder } from "./walk.js";
+import { MARKDOWN, SKIPPED_FOLDERS, isSkipped, markdownUnder } from "./walk.js";
+import { SOURCE_SUFFIXES, replaceLiteral, sourceLiterals } from "../document/sourceText.js";
+import { parseSheet, renderSheet, renderSheetJson } from "../report/sheet.js";
 import { welcome } from "./welcome.js";
 import { rootHelp } from "./help.js";
 import { renderCompact } from "../report/compactReport.js";
@@ -57,7 +59,7 @@ import { renderText } from "../report/textReport.js";
 import { renderWritingSpec, writingSpec } from "../report/writingSpec.js";
 import { exemplarInRegister, patternInRegister } from "../report/registerMatch.js";
 
-const COMMANDS = ["lint", "fix", "print", "rules", "explain", "patterns", "primer", "spec", "hook", "baseline", "doctor", "init", "contract", "check", "verify-patch"];
+const COMMANDS = ["lint", "fix", "print", "rules", "explain", "patterns", "primer", "spec", "hook", "baseline", "doctor", "init", "contract", "check", "verify-patch", "sheet"];
 const PYTHON_ONLY = [
   "audit",
   "map",
@@ -130,6 +132,7 @@ const OPTION_KINDS = {
   "--chars": "value",
   "--baseline": "optional",
   "--prune": "flag",
+  "--all": "flag",
 };
 
 class UsageError extends Error {}
@@ -929,7 +932,8 @@ export function renderInit(preset = "blog") {
   }
   lines.push(
     "",
-    "# 사전에 더할 항목. 키는 cliches, translationese, redundantPair, japaneseLoan",
+    "# 사전에 더할 항목. 키는 cliches, translationese, redundantPair, japaneseLoan, easyWords,",
+    "# screenSentence, screenNarration, screenTone",
     "# [dictionary]",
     '# cliches = ["우리의 여정"]',
     '# translationese = [{ pattern = "에 대한 이해", fix = "를 아는 것" }]',
@@ -981,6 +985,106 @@ function runInit(args) {
   return 0;
 }
 
+/** 폴더 아래 소스 파일. 뜻은 파이썬 cli/commands/sheet.py 의 sourceUnder 가 소유한다. @param {string} folder @returns {string[]} */
+function sourceUnder(folder) {
+  /** @type {string[]} */
+  const found = [];
+  for (const name of readdirSync(folder).sort()) {
+    const path = join(folder, name);
+    if (statSync(path).isDirectory()) {
+      if (!isSkipped(name)) found.push(...sourceUnder(path));
+    } else if (SOURCE_SUFFIXES.includes(extname(name).toLowerCase())) found.push(path);
+  }
+  return found.sort();
+}
+
+/** 작업 폴더 기준 상대 경로, 구분자는 `/`. 파이썬 relativeLabel 과 같은 글자를 낸다. @param {string} path */
+function relativeLabel(path) {
+  const rel = relative(process.cwd(), resolve(path));
+  const label = !rel || rel.startsWith("..") || isAbsolute(rel) ? path : rel;
+  return label.split(sep).join("/").replaceAll("\\", "/");
+}
+
+/** 표의 고침을 파일에 쓴다. 뜻은 파이썬 applySheet 가 소유한다. @param {string} sheetPath @param {boolean} dryRun @returns {[string[], string[]]} */
+function applySheet(sheetPath, dryRun) {
+  const parsed = parseSheet(readFileSync(sheetPath, "utf-8"));
+  /** @type {string[]} */
+  const applied = [];
+  const failed = [...parsed.problems];
+  /** @type {Map<string, import("../report/sheet.js").SheetRow[]>} */
+  const byFile = new Map();
+  for (const row of parsed.rows) {
+    if (!byFile.has(row.file)) byFile.set(row.file, []);
+    /** @type {import("../report/sheet.js").SheetRow[]} */ (byFile.get(row.file)).push(row);
+  }
+  for (const file of [...byFile.keys()].sort()) {
+    const rows = /** @type {import("../report/sheet.js").SheetRow[]} */ (byFile.get(file));
+    if (!existsSync(file)) {
+      failed.push(...rows.map((row) => `${row.file}:${row.line}: 파일이 없다`));
+      continue;
+    }
+    const lines = readFileSync(file, "utf-8").split("\n");
+    let changed = false;
+    for (const row of rows) {
+      const place = `${row.file}:${row.line}`;
+      if (row.line < 1 || row.line > lines.length) {
+        failed.push(`${place}: 그 줄이 없다`);
+        continue;
+      }
+      const [newLine, count] = replaceLiteral(lines[row.line - 1], row.text, row.fix);
+      if (count !== 1) {
+        failed.push(`${place}: 글이 그 줄에 ${count}번 있다. 한 번이어야 바꾼다`);
+        continue;
+      }
+      lines[row.line - 1] = newLine;
+      changed = true;
+      applied.push(`${place}: ${row.text} -> ${row.fix}`);
+    }
+    if (changed && !dryRun) writeFileSync(file, lines.join("\n"), "utf-8");
+  }
+  return [applied, failed];
+}
+
+/** `hanlint sheet 폴더/ --preset screen` 과 `hanlint sheet apply 시트.md`. 뜻은 파이썬 cli/commands/sheet.py 가 소유한다. @param {string[]} args */
+function runSheet(args) {
+  const { options, positionals } = parseArgs(args);
+  const output = /** @type {string | undefined} */ (options["--output"]);
+  if (!positionals.length) throw new UsageError("hanlint sheet 폴더/ 또는 hanlint sheet apply 시트.md");
+  if (positionals[0] === "apply") {
+    if (positionals.length !== 2) {
+      emit("hanlint sheet apply 시트.md 꼴로 시트 하나를 준다", output);
+      return 2;
+    }
+    const dryRun = Boolean(options["--dry-run"]);
+    const [applied, failed] = applySheet(positionals[1], dryRun);
+    const lines = [`${dryRun ? "볼 것" : "적용"} ${applied.length}건, 실패 ${failed.length}건`];
+    lines.push(...applied.map((item) => `  ${item}`));
+    lines.push(...failed.map((item) => `  실패 ${item}`));
+    emit(lines.join("\n"), output);
+    return failed.length ? 1 : 0;
+  }
+  /** @type {string[]} */
+  const files = [];
+  for (const target of positionals) {
+    if (!existsSync(target)) throw new Error(`${target} 이 없다`);
+    if (statSync(target).isDirectory()) files.push(...sourceUnder(target));
+    else files.push(target);
+  }
+  const config = configFrom(options, files);
+  const format = choose(/** @type {string} */ (options["--format"] ?? "markdown"), ["markdown", "json"], "--format");
+  /** @type {import("../report/sheet.js").SheetRow[]} */
+  const rows = [];
+  for (const file of files) {
+    const label = relativeLabel(file);
+    for (const literal of sourceLiterals(readFileSync(file, "utf-8"), label)) {
+      const findings = runAll(fingerprint(literal.plain, config), config).filter((finding) => finding.severity === "error");
+      if (findings.length || options["--all"]) rows.push({ file: label, line: literal.line, text: literal.text, findings, fix: "" });
+    }
+  }
+  emit(format === "json" ? renderSheetJson(rows, config.preset, files.length) : renderSheet(rows, config.preset, files.length), output);
+  return 0;
+}
+
 /** @param {string[]} argv */
 function dispatch(argv) {
   if (!argv.length) {
@@ -1013,6 +1117,7 @@ function dispatch(argv) {
   if (command === "hook") return runHook(rest);
   if (command === "baseline") return runBaseline(rest);
   if (command === "doctor") return runDoctor(rest);
+  if (command === "sheet") return runSheet(rest);
   return runInit(rest);
 }
 

package/src/config/patch.js

@@ -1,6 +1,6 @@
 // @ts-check
 /** 이유가 붙은 정확 국소 Patch 입력 계약. */
-import { createHash } from "node:crypto";
+import { sha256 } from "../digest.js";
 
 /** @param {unknown} value @param {string} where */
 function checkedString(value, where) {
@@ -39,7 +39,7 @@ export class Patch {
 
   get digest() {
     const encoded = JSON.stringify({ after: this.after, before: this.before, reason: this.reason });
-    return createHash("sha256").update(encoded, "utf8").digest("hex");
+    return sha256(encoded);
   }
 
   asDict() {

package/src/config/readerContract.js

@@ -1,6 +1,6 @@
 // @ts-check
 /** 모델과 실행 환경에 독립적인 최소 Reader Contract와 정확 Patch. */
-import { createHash } from "node:crypto";
+import { sha256 } from "../digest.js";
 
 export const CONTRACT_VERSION = 1;
 export const LATEST_CONTRACT_VERSION = 2;
@@ -38,7 +38,7 @@ function compareText(left, right) {
 
 /** @param {string} text */
 function digest(text) {
-  return createHash("sha256").update(text, "utf8").digest("hex");
+  return sha256(text);
 }
 
 export class Contract {

package/src/config/settings.js

@@ -12,9 +12,11 @@ import { projectPatches } from "../data/patches.js";
  * 글의 종류마다 처음부터 끄고 시작할 규칙. 정본은 파이썬 config/settings.py 의 PRESETS 다.
  * @type {Record<string, string[]>}
  */
+// 화면의 글에서만 켜는 것. 산문의 모든 종류가 처음부터 끈다. 파이썬 settings.py 의 SCREEN 과 같다.
+const SCREEN = ["screenNarration", "screenSentence", "screenTone"];
 export const PRESETS = {
-  blog: [],
-  report: ["noQuestion", "firstResultDistance", "introImage", "moreLater", "numberOrphan"],
+  blog: [...SCREEN],
+  report: ["noQuestion", "firstResultDistance", "introImage", "moreLater", "numberOrphan", ...SCREEN],
   docs: [
     "noQuestion",
     "firstResultDistance",
@@ -25,6 +27,7 @@ export const PRESETS = {
     "numberOrphan",
     "duplicateBlock",
     "headingUniform",
+    ...SCREEN,
   ],
 };
 // 서사 글에서만 끄는 것. 설명글의 전제 (독자가 문장 사이 이유를 따라간다, 말끝을 맺는다) 가 장면과
@@ -58,7 +61,54 @@ const CONVERSATION = [
   "promiseRecall",
   "sectionNoProse",
 ];
-PRESETS.chat = CONVERSATION;
+PRESETS.chat = [...CONVERSATION, ...SCREEN];
+// 화면의 글에서 끄는 것. 문장과 문단과 글의 짜임을 재는 규칙은 화면의 글 한 마디에 전제가 없다. 파이썬 settings.py 의 SCREEN_OFF 와 같다.
+const SCREEN_OFF = [
+  "cliche",
+  "connectorRepeat",
+  "danglingDeixis",
+  "deixis",
+  "doubleNegative",
+  "draftHistory",
+  "endingRepeat",
+  "euiChain",
+  "fillerOpener",
+  "imperativePeriod",
+  "longSentence",
+  "negationRedefine",
+  "nounPile",
+  "numberOrphan",
+  "outsideProfile",
+  "factListParagraph",
+  "paraFragment",
+  "blockUnread",
+  "bridgeRepeat",
+  "emojiBullet",
+  "headingSentence",
+  "headingSkip",
+  "headingUniform",
+  "introImage",
+  "introLong",
+  "loneSubheading",
+  "moreLater",
+  "sectionNoProse",
+  "countMismatch",
+  "enoughOnce",
+  "fieldEcho",
+  "keywordHeading",
+  "keywordMissing",
+  "noQuestion",
+  "promiseRecall",
+  "tableOddCell",
+  "duplicateBlock",
+  "firstResultDistance",
+  "inputFileSource",
+  "installImport",
+  "platformApi",
+];
+PRESETS.screen = SCREEN_OFF;
+/** enforceStyle 에 넣을 수 있는 규칙. 파이썬 settings.py 의 ENFORCEABLE 과 같다. */
+export const ENFORCEABLE = ["noQuestion", "nounPile", "screenNarration", "screenTone"];
 
 /** 프리셋 → 견줄 프로파일의 종류. 정본은 파이썬 config/settings.py 의 PROFILE_OF 다. @type {Record<string, string>} */
 export const PROFILE_OF = {
@@ -70,6 +120,7 @@ export const PROFILE_OF = {
   fiction: "fiction",
   encyclopedia: "encyclopedia",
   chat: null,
+  screen: null,
 };
 
 export const PRESET_NAMES = Object.keys(PRESETS);
@@ -180,8 +231,8 @@ export function configFromMapping(data) {
       }
       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의 배열이다");
+      if (!Array.isArray(value) || value.some((name) => !ENFORCEABLE.includes(name))) {
+        throw new Error(`enforceStyle 은 ${ENFORCEABLE.join(", ")}의 배열이다`);
       }
       config.enforceStyle = [...value];
     } else if (key === "dictionary") {

package/src/data/load.js

@@ -3,13 +3,8 @@
  * data 폴더를 읽는다. 파이썬 정본의 투영이라 파일 모양이 같다. txt 는 한 줄에 항목 하나, json 은 toml 을 옮긴 것.
  * 한 번 읽은 것은 기억한다.
  */
-import { readFileSync } from "node:fs";
-import { dirname, join } from "node:path";
-import { fileURLToPath } from "node:url";
-
 import { compile } from "../regex.js";
-
-const DATA_DIR = join(dirname(fileURLToPath(import.meta.url)), "..", "..", "data");
+import { readData } from "./read.js";
 /** @type {Map<string, unknown>} */
 const cache = new Map();
 
@@ -26,7 +21,7 @@ function cached(key, make) {
 
 /** @param {string} name */
 export function readText(name) {
-  return readFileSync(join(DATA_DIR, name), "utf-8");
+  return readData(name);
 }
 
 /** `#` 으로 시작하면 주석, 빈 줄은 무시. @param {string} name @returns {string[]} */

package/src/data/profiles.js

@@ -3,7 +3,7 @@
  * 참조 분포 (프로파일) 의 자료형과 읽기. 파이썬 data/profiles.py 와 같다. 종류별 프로파일은 profiles.json (투영) 에서,
  * 사용자 프로파일은 `hanlint profile build` 가 만든 파일에서 읽는다. 히스토그램은 정확한 계수라 두 판의 셈이 같다.
  */
-import { readFileSync } from "node:fs";
+import { readExternal } from "./read.js";
 
 import { readText } from "./load.js";
 
@@ -103,7 +103,7 @@ const users = new Map();
 export function userProfile(path) {
   let profile = users.get(path);
   if (!profile) {
-    const data = JSON.parse(readFileSync(path, "utf-8"));
+    const data = JSON.parse(readExternal(path));
     if (data.version !== PROFILE_VERSION || !("profile" in data)) {
       throw new Error(`프로파일 파일이 아니다: ${path}. hanlint profile build 로 다시 만든다`);
     }

package/src/data/read.js

@@ -0,0 +1,21 @@
+// @ts-check
+/** 같은 자료를 Node 파일 또는 브라우저 배포 묶음에서 읽는다. */
+const isNode = typeof process === "object" && Boolean(process.versions?.node);
+const fileSystem = isNode ? await import("node:fs") : null;
+const files = isNode ? null : await fetch(new URL("../../data/siteData.json", import.meta.url)).then((response) => {
+  if (!response.ok) throw new Error("검사 자료를 불러오지 못했습니다. 새로고침해 주세요.");
+  return response.json();
+});
+
+/** @param {string} name @returns {string} */
+export function readData(name) {
+  if (fileSystem) return fileSystem.readFileSync(new URL(`../../data/${name}`, import.meta.url), "utf8");
+  if (typeof files[name] !== "string") throw new Error(`검사 자료가 없습니다: ${name}`);
+  return files[name];
+}
+
+/** @param {string} path @returns {string} */
+export function readExternal(path) {
+  if (!fileSystem) throw new Error("파일 경로 읽기는 Node에서 지원합니다. 브라우저에는 텍스트를 전달해 주세요.");
+  return fileSystem.readFileSync(path, "utf8");
+}

package/src/digest.js

@@ -0,0 +1,44 @@
+// @ts-check
+/** FIPS 180-4 SHA-256. 동기 공개 계약을 Node와 브라우저에서 같은 UTF-8 해시로 유지한다. */
+// 상수와 라운드의 출처: https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.180-4.pdf (4.2.2, 6.2).
+const WORDS = [
+  0x428a2f98, 0x71374491, 0xb5c0fbcf, 0xe9b5dba5, 0x3956c25b, 0x59f111f1, 0x923f82a4, 0xab1c5ed5,
+  0xd807aa98, 0x12835b01, 0x243185be, 0x550c7dc3, 0x72be5d74, 0x80deb1fe, 0x9bdc06a7, 0xc19bf174,
+  0xe49b69c1, 0xefbe4786, 0x0fc19dc6, 0x240ca1cc, 0x2de92c6f, 0x4a7484aa, 0x5cb0a9dc, 0x76f988da,
+  0x983e5152, 0xa831c66d, 0xb00327c8, 0xbf597fc7, 0xc6e00bf3, 0xd5a79147, 0x06ca6351, 0x14292967,
+  0x27b70a85, 0x2e1b2138, 0x4d2c6dfc, 0x53380d13, 0x650a7354, 0x766a0abb, 0x81c2c92e, 0x92722c85,
+  0xa2bfe8a1, 0xa81a664b, 0xc24b8b70, 0xc76c51a3, 0xd192e819, 0xd6990624, 0xf40e3585, 0x106aa070,
+  0x19a4c116, 0x1e376c08, 0x2748774c, 0x34b0bcb5, 0x391c0cb3, 0x4ed8aa4a, 0x5b9cca4f, 0x682e6ff3,
+  0x748f82ee, 0x78a5636f, 0x84c87814, 0x8cc70208, 0x90befffa, 0xa4506ceb, 0xbef9a3f7, 0xc67178f2,
+];
+const rotate = (value, shift) => (value >>> shift) | (value << (32 - shift));
+
+/** @param {string} text @returns {string} */
+export function sha256(text) {
+  const bytes = new TextEncoder().encode(text);
+  const buffer = new Uint8Array(Math.ceil((bytes.length + 9) / 64) * 64);
+  buffer.set(bytes);
+  buffer[bytes.length] = 0x80;
+  const view = new DataView(buffer.buffer);
+  view.setUint32(buffer.length - 8, Math.floor(bytes.length / 0x20000000));
+  view.setUint32(buffer.length - 4, bytes.length * 8);
+  const hash = [0x6a09e667, 0xbb67ae85, 0x3c6ef372, 0xa54ff53a, 0x510e527f, 0x9b05688c, 0x1f83d9ab, 0x5be0cd19];
+  const words = new Uint32Array(64);
+  for (let offset = 0; offset < buffer.length; offset += 64) {
+    for (let index = 0; index < 16; index++) words[index] = view.getUint32(offset + index * 4);
+    for (let index = 16; index < 64; index++) {
+      const left = words[index - 15], right = words[index - 2];
+      const first = rotate(left, 7) ^ rotate(left, 18) ^ (left >>> 3);
+      const second = rotate(right, 17) ^ rotate(right, 19) ^ (right >>> 10);
+      words[index] = words[index - 16] + first + words[index - 7] + second;
+    }
+    let [a, b, c, d, e, f, g, h] = hash;
+    for (let index = 0; index < 64; index++) {
+      const first = h + (rotate(e, 6) ^ rotate(e, 11) ^ rotate(e, 25)) + ((e & f) ^ (~e & g)) + WORDS[index] + words[index];
+      const second = (rotate(a, 2) ^ rotate(a, 13) ^ rotate(a, 22)) + ((a & b) ^ (a & c) ^ (b & c));
+      [a, b, c, d, e, f, g, h] = [(first + second) | 0, a, b, c, (d + first) | 0, e, f, g];
+    }
+    [a, b, c, d, e, f, g, h].forEach((value, index) => { hash[index] = (hash[index] + value) | 0; });
+  }
+  return hash.map((value) => (value >>> 0).toString(16).padStart(8, "0")).join("");
+}

package/src/document/sourceText.js

@@ -0,0 +1,143 @@
+// @ts-check
+/**
+ * 소스 파일의 글 마디. 사람이 읽는 한국어 문자열 리터럴과 JSX 글을 줄 번호와 함께 뽑는다.
+ * 뜻과 규칙은 파이썬 document/sourceText.py 가 소유한다. 여기는 같은 값을 낸다.
+ */
+
+export const SOURCE_SUFFIXES = [".js", ".jsx", ".mjs", ".cjs", ".ts", ".tsx", ".rs", ".py"];
+
+const KOREAN = /[가-힣]/;
+// 문자열의 경계. 줄을 앞에서부터 훑어 여는 따옴표에서 같은 닫는 따옴표까지를 한 마디로 본다. 파이썬 sourceText.py 와 같다.
+const QUOTES = ["'", '"', "`"];
+const EXPRESSION = /\{[^{}]*\}/g;
+const BLOCK_COMMENT = /\/\*[\s\S]*?\*\//g;
+const DEVELOPER_LINE = /new Error\(|console\.|panic!\(|expect\(|assert/;
+const RUST_CONTINUATION = /\\\r?\n[ \t]*/g;
+const RUST_TEST_MARKER = "#[cfg(test)]";
+
+/**
+ * @typedef {object} SourceLiteral
+ * @property {number} line 1부터 세는 줄 번호. 여러 줄을 이은 러스트 문자열은 시작 줄이다
+ * @property {string} text 따옴표와 태그를 뺀 글. 파일에 있는 그대로라 되돌려 쓸 때 찾을 수 있다
+ * @property {string} plain 검사에 쓰는 글. 식 (`${...}`, `{...}`) 을 비우고 공백을 하나로 모았다
+ */
+
+/** 템플릿 리터럴의 `${ ... }` 식을 (중첩 괄호를 세어) 같은 길이의 빈칸으로 바꾼다. @param {string} source */
+export function withoutTemplateExpressions(source) {
+  let output = "";
+  let index = 0;
+  while (index < source.length) {
+    if (source[index] === "$" && source[index + 1] === "{") {
+      let depth = 0;
+      let cursor = index + 1;
+      for (; cursor < source.length; cursor++) {
+        if (source[cursor] === "{") depth += 1;
+        else if (source[cursor] === "}") {
+          depth -= 1;
+          if (depth === 0) break;
+        }
+      }
+      output += " ".repeat(cursor + 1 - index);
+      index = cursor + 1;
+      continue;
+    }
+    output += source[index];
+    index += 1;
+  }
+  return output;
+}
+
+/** 주석과 개발자용 줄을 걷어낸 소스. 줄 번호는 유지한다. @param {string} source @param {string} path */
+export function userFacingSource(source, path) {
+  const isRust = path.endsWith(".rs");
+  let body = source;
+  if (isRust && body.includes(RUST_TEST_MARKER)) body = body.slice(0, body.indexOf(RUST_TEST_MARKER));
+  if (isRust) body = body.replace(RUST_CONTINUATION, "");
+  body = body.replace(BLOCK_COMMENT, (block) => block.replace(/[^\n]/g, " "));
+  return body
+    .split("\n")
+    .map((line) => {
+      const trimmed = line.trim();
+      if (trimmed.startsWith("//") || trimmed.startsWith("*") || trimmed.startsWith("#")) return "";
+      if (DEVELOPER_LINE.test(line)) return "";
+      return line.replace(/\/\/.*$/, "");
+    })
+    .join("\n");
+}
+
+/** 검사에 쓰는 글. 식을 비우고 공백을 하나로 모은다. @param {string} text */
+export function plainText(text) {
+  let copy = withoutTemplateExpressions(text);
+  while (EXPRESSION.test(copy)) copy = copy.replace(EXPRESSION, " ");
+  return copy.replace(/\s+/g, " ").trim();
+}
+
+/** `start` 의 따옴표를 닫는 자리. 역슬래시 뒤 글자는 건너뛴다. 없으면 -1. @param {string} line @param {number} start */
+function closingQuote(line, start) {
+  const quote = line[start];
+  let index = start + 1;
+  while (index < line.length) {
+    const char = line[index];
+    if (char === "\\") {
+      index += 2;
+      continue;
+    }
+    if (char === quote) return index;
+    index += 1;
+  }
+  return -1;
+}
+
+/** 한 줄의 글 마디를 나온 차례로. 뜻은 파이썬 lineLiterals 가 소유한다. @param {string} line @returns {string[]} */
+export function lineLiterals(line) {
+  /** @type {string[]} */
+  const found = [];
+  let index = 0;
+  while (index < line.length) {
+    const char = line[index];
+    if (QUOTES.includes(char)) {
+      const end = closingQuote(line, index);
+      if (end < 0) break;
+      found.push(line.slice(index + 1, end));
+      index = end + 1;
+      continue;
+    }
+    if (char === ">" && (index === 0 || !"=-".includes(line[index - 1]))) {
+      const end = line.indexOf("<", index + 1);
+      if (end > index) {
+        const inner = line.slice(index + 1, end);
+        found.push(inner);
+        if (!inner.includes("{")) {
+          index = end;
+          continue;
+        }
+      }
+    }
+    index += 1;
+  }
+  return found;
+}
+
+/** 소스에서 글 마디를 줄 번호 순으로. @param {string} source @param {string} [path] @returns {SourceLiteral[]} */
+export function sourceLiterals(source, path = "") {
+  /** @type {SourceLiteral[]} */
+  const found = [];
+  userFacingSource(source, path).split("\n").forEach((line, index) => {
+    for (const raw of lineLiterals(line)) {
+      const text = raw.trim();
+      const plain = plainText(text);
+      if (text && KOREAN.test(plain)) found.push({ line: index + 1, text, plain });
+    }
+  });
+  return found;
+}
+
+/**
+ * 한 줄 안에서 글 `old` 를 `new` 로 바꾼다. 몇 번 나왔는지 같이 준다 (한 번일 때만 바꾼 것이 확정이다).
+ * @param {string} lineText @param {string} oldText @param {string} newText @returns {[string, number]}
+ */
+export function replaceLiteral(lineText, oldText, newText) {
+  const count = lineText.split(oldText).length - 1;
+  if (count !== 1) return [lineText, count];
+  return [lineText.replace(oldText, () => newText), 1];
+}

package/src/fingerprint/dictionaries.js

@@ -12,6 +12,9 @@ export const DICTIONARY_FILES = {
   spacing: "spacing.toml",
   confusable: "confusable.toml",
   easyWords: "easyWords.toml",
+  screenSentence: "screenSentence.toml",
+  screenNarration: "screenNarration.toml",
+  screenTone: "screenTone.toml",
 };
 const GROUP_REF = /\$(\d)/g;
 const FINALS = { ㄴ: 4, ㄹ: 8 };

package/src/guard/contract.js

@@ -1,6 +1,6 @@
 // @ts-check
 /** Reader Contract 검사와 이유가 붙은 국소 Patch 검증. */
-import { createHash } from "node:crypto";
+import { sha256 } from "../digest.js";
 
 import { Patch } from "../config/patch.js";
 import { Contract, ContractV2, Outline, ProtectedSurface, parseContract } from "../config/readerContract.js";
@@ -16,7 +16,7 @@ import { compareText, factLines, protectedSurface, surfaceDiff, surfaceViolation
 
 /** @param {string} text */
 function digest(text) {
-  return createHash("sha256").update(text, "utf8").digest("hex");
+  return sha256(text);
 }
 
 /** 원문의 보호 표면을 모두 덮는 version 1 Contract 초안을 만든다. @param {string} text @param {string} reader @param {string} goal */

package/src/guard/outline.js

@@ -6,7 +6,7 @@
 /** @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} */
+/** @param {Pick<import("../config/readerContract.js").Outline, "level" | "headings">} outline @param {import("../fingerprint/build.js").DocumentPrint} doc @returns {OutlineDiff} */
 export function compareOutline(outline, doc) {
   const actual = doc.headings.filter(([level]) => level === outline.level).map(([, title]) => title);
   const mismatches = [];