hanlint 0.0.18 → 0.0.19

package/src/document/sourceText.js

@@ -1,22 +1,22 @@
 // @ts-check
 /**
  * 소스 파일의 글 마디. 사람이 읽는 한국어 문자열 리터럴과 JSX 글을 줄 번호와 함께 뽑는다.
- * 뜻과 규칙은 파이썬 document/sourceText.py 가 소유한다. 여기는 같은 값을 낸다.
+ * 뜻과 규칙은 파이썬 document/sourceText.py가 정한다. 여기는 같은 값을 낸다.
  */
 
 export const SOURCE_SUFFIXES = [".js", ".jsx", ".mjs", ".cjs", ".ts", ".tsx", ".rs", ".py", ".html", ".htm", ".vue", ".svelte"];
-/** 태그 사이 글과 속성값을 JSX 와 같은 길로 읽는 파일. HTML 주석 `<!-- -->` 을 걷어낸다. */
+/** 태그 사이 글과 속성값을 JSX와 같은 길로 읽는 파일. HTML 주석 `<!-- -->`을 걷어낸다. */
 const MARKUP_SUFFIXES = [".html", ".htm", ".vue", ".svelte"];
 
 const KOREAN = /[가-힣]/;
-// 문자열의 경계. 줄을 앞에서부터 훑어 여는 따옴표에서 같은 닫는 따옴표까지를 한 마디로 본다. 파이썬 sourceText.py 와 같다.
+// 문자열의 경계. 줄을 앞에서부터 훑어 여는 따옴표에서 같은 닫는 따옴표까지를 한 마디로 본다. 파이썬 sourceText.py와 같다.
 const QUOTES = ["'", '"', "`"];
 const BLOCK_COMMENT = /\/\*[\s\S]*?\*\//g;
 const HTML_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)]";
-/** 문장을 끊지 않는 HTML 인라인 태그. 같은 줄에서 이 태그만 사이에 둔 글 조각은 한 마디로 잇는다. 파이썬 INLINE_TAGS 와 같다. */
+/** 문장을 끊지 않는 HTML 인라인 태그. 같은 줄에서 이 태그만 사이에 둔 글 조각은 한 마디로 잇는다. 파이썬 INLINE_TAGS와 같다. */
 const INLINE_TAGS = new Set("a abbr b bdi bdo cite code data del dfn em i ins kbd mark q s samp small span strong sub sup time u var wbr br".split(" "));
 const INLINE_TAG = /<\/?([a-zA-Z][a-zA-Z0-9]*)[^<>]*>/g;
 const INLINE_GAP = /^(?:\s*<\/?[a-zA-Z][a-zA-Z0-9]*[^<>]*>)+\s*$/;
@@ -32,11 +32,11 @@ const HEAD_TEXT = /^\s*[^<\s][^<]*(?=<\/)/;
  * @typedef {object} SourceLiteral
  * @property {number} line 1부터 세는 줄 번호. 여러 줄을 이은 러스트 문자열은 시작 줄이다
  * @property {string} text 따옴표와 태그를 뺀 글. 파일에 있는 그대로라 되돌려 쓸 때 찾을 수 있다
- * @property {string} plain 검사에 쓰는 글. 식 (`${...}`, `{...}`) 을 비우고 공백을 하나로 모았다
- * @property {number} column 1부터 세는 칸. 그 줄에서 text 가 시작하는 자리
+ * @property {string} plain 검사에 쓰는 글. 식(`${...}`, `{...}`)을 비우고 공백을 하나로 모았다
+ * @property {number} column 1부터 세는 칸. 그 줄에서 text가 시작하는 위치
  */
 
-/** `start` 의 `{` 를 닫는 `}` 의 자리. 뜻은 파이썬 balancedEnd 가 소유한다. @param {string} line @param {number} start */
+/** `start`의 `{`를 닫는 `}`의 위치. 뜻은 파이썬 balancedEnd가 정한다. @param {string} line @param {number} start */
 function balancedEnd(line, start) {
   let depth = 0;
   let index = start;
@@ -58,7 +58,7 @@ function balancedEnd(line, start) {
   return -1;
 }
 
-/** 글에 낀 식 `{...}` 와 `${...}` 의 [시작, 끝 다음]. 뜻은 파이썬 expressionSpans 가 소유한다. @param {string} text @returns {[number, number][]} */
+/** 글에 낀 식 `{...}`와 `${...}`의 [시작, 끝 다음]. 뜻은 파이썬 expressionSpans가 정한다. @param {string} text @returns {[number, number][]} */
 export function expressionSpans(text) {
   /** @type {[number, number][]} */
   const spans = [];
@@ -77,7 +77,7 @@ export function expressionSpans(text) {
   return spans;
 }
 
-/** 템플릿 리터럴의 `${ ... }` 식을 같은 길이의 빈칸으로 바꾼다. 뜻은 파이썬 withoutTemplateExpressions 가 소유한다. @param {string} source */
+/** 템플릿 리터럴의 `${ ... }` 식을 같은 길이의 빈칸으로 바꾼다. 뜻은 파이썬 withoutTemplateExpressions가 정한다. @param {string} source */
 export function withoutTemplateExpressions(source) {
   let output = source;
   for (const [start, end] of expressionSpans(source)) {
@@ -107,8 +107,8 @@ export function userFacingSource(source, path) {
 
 
 /**
- * 따옴표 밖의 `//` 부터 자른다. `https://` 처럼 `:` 뒤의 `//` 는 주소라 두고, 문자열 안의 `//` 도 둔다.
- * 뜻은 파이썬 document/sourceText.py 의 withoutLineComment 가 소유한다.
+ * 따옴표 밖의 `//`부터 자른다. `https://`처럼 `:` 뒤의 `//`는 주소라 두고, 문자열 안의 `//`도 둔다.
+ * 뜻은 파이썬 document/sourceText.py의 withoutLineComment가 정한다.
  */
 export function withoutLineComment(line) {
   let quote = null;
@@ -132,12 +132,12 @@ export function plainText(text) {
     cursor = end;
   }
   plain += text.slice(cursor);
-  // 인라인 태그를 비운다. 이름이 영문자로 시작하는 것만이라 `<대상> 필요` 의 꺾쇠는 남는다.
+  // 인라인 태그를 비운다. 이름이 영문자로 시작하는 것만이라 `<대상> 필요`의 꺾쇠는 남는다.
   plain = plain.replace(INLINE_TAG, (tag, name) => (INLINE_TAGS.has(name.toLowerCase()) ? "" : tag));
   return plain.replace(/\s+/g, " ").trim();
 }
 
-/** `start` 의 따옴표를 닫는 자리. 백틱 안의 `${...}` 은 통째로 건너뛴다. 뜻은 파이썬 closingQuote 가 소유한다. @param {string} line @param {number} start */
+/** `start`의 따옴표를 닫는 위치. 백틱 안의 `${...}`은 통째로 건너뛴다. 뜻은 파이썬 closingQuote가 정한다. @param {string} line @param {number} start */
 function closingQuote(line, start) {
   const quote = line[start];
   let index = start + 1;
@@ -159,14 +159,14 @@ function closingQuote(line, start) {
   return -1;
 }
 
-/** `index` 의 `>` 가 JSX 여는 태그의 끝인가. 뜻은 파이썬 tagCloses 가 소유한다. @param {string} line @param {number} index */
+/** `index`의 `>`가 JSX 여는 태그의 끝인가. 뜻은 파이썬 tagCloses가 정한다. @param {string} line @param {number} index */
 function tagCloses(line, index) {
   if (index === 0 || line[index + 1] === "=") return false;
   const before = line[index - 1];
   return "\"'}".includes(before) || /[A-Za-z0-9]/.test(before);
 }
 
-/** `start` 부터의 JSX 글이 끝나는 `<` 의 자리. 식 안의 `<` 는 글의 끝이 아니다. 뜻은 파이썬 jsxTextEnd 가 소유한다. @param {string} line @param {number} start */
+/** `start`부터의 JSX 글이 끝나는 `<`의 위치. 식 안의 `<`는 글의 끝이 아니다. 뜻은 파이썬 jsxTextEnd가 정한다. @param {string} line @param {number} start */
 function jsxTextEnd(line, start) {
   let index = start;
   while (index < line.length) {
@@ -183,7 +183,7 @@ function jsxTextEnd(line, start) {
   return -1;
 }
 
-/** 글에 낀 식 안의 글 마디. 뜻은 파이썬 innerLiterals 가 소유한다. @param {string} text @param {number} offset @returns {[number, string][]} */
+/** 글에 낀 식 안의 글 마디. 뜻은 파이썬 innerLiterals가 정한다. @param {string} text @param {number} offset @returns {[number, string][]} */
 function innerLiterals(text, offset) {
   /** @type {[number, string][]} */
   const found = [];
@@ -194,10 +194,10 @@ function innerLiterals(text, offset) {
   return found;
 }
 
-/** 한 줄의 글 마디를 [시작 자리, 글] 로 나온 차례로. 뜻은 파이썬 lineLiterals 가 소유한다. @param {string} line @param {number} [offset] @returns {[number, string][]} */
+/** 한 줄의 글 마디를 [시작 위치, 글]로 나온 차례로. 뜻은 파이썬 lineLiterals가 정한다. @param {string} line @param {number} [offset] @returns {[number, string][]} */
 /**
- * openEnded (마크업 파일) 이면 여는 태그 뒤 줄 끝까지의 글과 줄 처음부터 닫는 태그 앞까지의 글도 마디다.
- * 뜻은 파이썬 lineLiterals 가 소유한다.
+ * openEnded(마크업 파일)이면 여는 태그 뒤 줄 끝까지의 글과 줄 처음부터 닫는 태그 앞까지의 글도 마디다.
+ * 뜻은 파이썬 lineLiterals가 정한다.
  * @param {string} line @param {number} [offset] @param {boolean} [openEnded]
  */
 export function lineLiterals(line, offset = 0, openEnded = false) {
@@ -239,7 +239,7 @@ export function lineLiterals(line, offset = 0, openEnded = false) {
 
 /**
  * 사이가 인라인 태그뿐인 태그 사이 글 조각을 한 마디로 잇는다. 태그 안의 속성 문자열은 잇기에 끼지 않고 제 마디로 남는다.
- * 뜻은 파이썬 joinInline 이 소유한다.
+ * 뜻은 파이썬 joinInline이 정한다.
  * @param {string} line @param {[number, string][]} found @param {number} offset @returns {[number, string][]}
  */
 function joinInline(line, found, offset) {
@@ -263,13 +263,13 @@ function joinInline(line, found, offset) {
   return [...joined, ...attributes].sort((a, b) => a[0] - b[0]);
 }
 
-/** position 이 태그 안 (`<` 뒤, `>` 앞) 인가. @param {string} line @param {number} position */
+/** position이 태그 안(`<` 뒤, `>` 앞)인가. @param {string} line @param {number} position */
 function insideTag(line, position) {
   const opened = line.lastIndexOf("<", position - 1);
   return opened >= 0 && line.lastIndexOf(">", position - 1) < opened;
 }
 
-/** 사이가 인라인 태그뿐이고 형제 (`</a><a>`) 가 아니다. @param {string} gap */
+/** 사이가 인라인 태그뿐이고 형제(`</a><a>`)가 아니다. @param {string} gap */
 function inlineOnly(gap) {
   if (!INLINE_GAP.test(gap) || SIBLING_GAP.test(gap)) return false;
   return [...gap.matchAll(INLINE_TAG)].every((match) => INLINE_TAGS.has(match[1].toLowerCase()));
@@ -280,7 +280,7 @@ export function sourceLiterals(source, path = "") {
   /** @type {SourceLiteral[]} */
   const found = [];
   const markup = MARKUP_SUFFIXES.some((suffix) => path.endsWith(suffix));
-  // 마크업은 주석 지우기가 줄 수를 지키므로 원문 줄과 나란히 간다. script 블록 판정은 원문 줄로 한다 (`// 주석</script>` 가 지워져도).
+  // 마크업은 주석 지우기가 줄 수를 지키므로 원문 줄과 나란히 간다. script 블록 판정은 원문 줄로 한다 (`// 주석</script>`가 지워져도).
   const rawLines = markup ? source.split("\n") : [];
   let inCode = false;
   userFacingSource(source, path).split("\n").forEach((line, index) => {
@@ -304,7 +304,7 @@ export function sourceLiterals(source, path = "") {
 }
 
 /**
- * 한 줄 안에서 글 `old` 를 `new` 로 바꾼다. 몇 번 나왔는지 같이 준다 (한 번일 때만 바꾼 것이 확정이다).
+ * 한 줄 안에서 글 `old`를 `new`로 바꾼다. 몇 번 나왔는지 같이 준다 (한 번일 때만 바꾼 것이 확정이다).
  * @param {string} lineText @param {string} oldText @param {string} newText @returns {[string, number]}
  */
 export function replaceLiteral(lineText, oldText, newText) {

package/src/fingerprint/build.js

@@ -1,5 +1,5 @@
 // @ts-check
-/** 문서 모델을 한 번 훑어 글 지문을 만든다. 텍스트를 읽는 유일한 자리다. 파이썬 fingerprint/build.py 와 같다. */
+/** 문서 모델을 한 번 훑어 글 분석 결과를 만든다. 텍스트를 읽는 곳은 여기 하나다. 파이썬 fingerprint/build.py와 같다. */
 import { defaultConfig } from "../config/settings.js";
 import { NONE as NO_REGISTER, documentRegister, lastWord, registerOfWord } from "../analysis/grammar/register.js";
 import { doublePassiveSpans, euiCount, longestNounRun, splitSentences } from "../analysis/index.js";
@@ -88,9 +88,9 @@ import { overlap, topicsOf, unionOf } from "./topics.js";
  * @property {number} readerCallCount
  * @property {[number, string, number, string][]} countPromises (수, 단위, 줄, 원문)
  * @property {import("./codeBlocks.js").CodeBlock[]} codeBlocks 코드 펜스를 언어와 본문 줄로 푼 것
- * @property {import("./readerState.js").ReaderTrail} reader 자리마다의 독자 상태. 약속과 회수 표지는 final 에 있다
+ * @property {import("./readerState.js").ReaderTrail} reader 위치마다의 독자 상태. 약속하는 말과 다시 다루는 말은 final에 있다
  * @property {[string, number, number][]} disabled
- * @property {import("../document/model.js").Block[]} ignored 설정이 지문에서 뺀 펜스
+ * @property {import("../document/model.js").Block[]} ignored 설정이 글 분석에서 뺀 펜스
  * @property {string} register
  * @property {number} registerShare
  * @property {SectionPrint} intro
@@ -131,7 +131,7 @@ function makeSentencePrint(build, text, line, block, sectionIndex, quoted) {
   const { entries } = build;
   const ending = markers.endingOf(text);
   const protectedSpans = markers.termSpans(text, build.protectedTerms);
-  // 인용 안의 것과 보호한 용어에 걸친 것은 뺀다. 뜻은 파이썬 fingerprint/build.py 의 kept 가 정한다.
+  // 인용 안의 것과 보호한 용어에 걸친 것은 뺀다. 뜻은 파이썬 fingerprint/build.py의 kept가 정한다.
   /** @param {number} start @param {number} end */
   const kept = (start, end) => !markers.insideAny(start, end, quoted) && !markers.overlapsAny(start, end, protectedSpans);
   const deixis = markers
@@ -233,7 +233,7 @@ function buildSection(build, section, sectionIndex) {
       const line = block.startLine + countIn(text, "\n", sentence.start);
       const quoted = quotedIn(sentence, blockSpans);
       const made = makeSentencePrint(build, sentence.text, line, block, sectionIndex, quoted);
-      // 만든 자리에서 바로 쌓는다. 다음 문장의 index 가 이 길이에서 나오므로 미루면 셈이 어긋난다.
+      // 만든 곳에서 바로 쌓는다. 다음 문장의 index가 이 길이에서 나오므로 미루면 셈이 어긋난다.
       sentences.push(made);
       blockSentences.push(made);
     }
@@ -269,7 +269,7 @@ function buildSection(build, section, sectionIndex) {
  * @returns {DocumentPrint}
  */
 export function buildFingerprint(doc, config = defaultConfig()) {
-  // 코드도 산문도 아닌 펜스는 지문에 들어오기 전에 뺀다. 모든 진입점이 여기를 지나므로 한 자리면 된다.
+  // 코드도 산문도 아닌 펜스는 분석에 들어오기 전에 뺀다. 모든 진입점이 여기를 지나므로 한 곳이면 된다.
   doc = dropFences(doc, config.ignoreFences);
   const build = {
     entries: entriesFor(config),

package/src/fingerprint/codeBlocks.js

@@ -1,8 +1,8 @@
 // @ts-check
 /**
- * 코드 블록을 언어와 본문으로 나눈다. 지문이 한 번 만들고 (DocumentPrint.codeBlocks) code 부류 규칙과 독자 상태가
- * 읽는다. 파이썬 fingerprint/codeBlocks.py 와 같다.
- * 펜스 첫 줄의 언어 표기 (```python) 를 읽고 본문 줄에 원문 줄 번호를 붙인다. text 펜스는 출력이다.
+ * 코드 블록을 언어와 본문으로 나눈다. 글 분석이 한 번 만들고(DocumentPrint.codeBlocks) code 묶음 규칙과 독자 상태가
+ * 읽는다. 파이썬 fingerprint/codeBlocks.py와 같다.
+ * 펜스 첫 줄의 언어 표기(```python)를 읽고 본문 줄에 원문 줄 번호를 붙인다. text 펜스는 출력이다.
  */
 import { CODE } from "../document/model.js";
 import { fenceLanguage } from "../document/parseMarkdown.js";

package/src/fingerprint/codeMarkers.js

@@ -1,7 +1,7 @@
 // @ts-check
 /**
  * 코드 줄에서 파일의 공급과 수요를 읽는다. 어떤 줄이 파일을 만들고 (쓰기, 폴더 만들기) 어떤 줄이 파일을 읽는가.
- * 파이썬 fingerprint/codeMarkers.py 와 같다. 줄마다 대조하므로 여러 줄에 걸친 호출은 보지 않는다.
+ * 파이썬 fingerprint/codeMarkers.py와 같다. 줄마다 대조하므로 여러 줄에 걸친 호출은 보지 않는다.
  */
 
 const QUOTED = "\\(\\s*[\"']([^\"'\\n]+)[\"']";
@@ -19,7 +19,7 @@ const WRITES = new RegExp(
 const SHELL_WRITES = /(?:>>?|-o|-O|--output|Out-File)\s*["']?([\w./\\-]+\.[A-Za-z0-9]+)/g;
 const SQL_PATHS = /FROM\s+'([^']+\.(?:csv|parquet|json|xlsx))'/gi;
 const MAKES_DIR = /(?:mkdir(?:\s+-p)?|makedirs|md)\s*\(?\s*["']?([\w./\\-]+)|Path\(\s*["']([^"']+)["']\s*\)\.mkdir/g;
-/** open 의 모드에 이 글자가 있으면 쓰기다. 없으면 (기본 r) 읽기다. */
+/** open의 모드에 이 글자가 있으면 쓰기다. 없으면 (기본 r) 읽기다. */
 const WRITE_MODES = [..."wax"];
 
 /** @param {string} path */
@@ -41,7 +41,7 @@ function all(pattern, text, group) {
 }
 
 /**
- * 코드 줄들이 만드는 [파일 이름, 폴더 이름]. 쓰기 함수, 셸 리다이렉션, 쓰기 모드의 open, mkdir 을 본다.
+ * 코드 줄들이 만드는 [파일 이름, 폴더 이름]. 쓰기 함수, 셸 리다이렉션, 쓰기 모드의 open, mkdir 호출을 본다.
  * @param {string[]} lines
  * @returns {[Set<string>, Set<string>]}
  */
@@ -59,7 +59,7 @@ export function createdIn(lines) {
   return [files, dirs];
 }
 
-/** 한 줄이 읽는 경로. 읽기 함수, 읽기 모드의 open, SQL 의 FROM 차례다. @param {string} code */
+/** 한 줄이 읽는 경로. 읽기 함수, 읽기 모드의 open, SQL의 FROM 차례다. @param {string} code */
 export function readsIn(code) {
   const reads = all(READS, code, 1);
   for (const match of code.matchAll(OPENS)) if (!isWriteMode(match[2])) reads.push(match[1]);

package/src/fingerprint/dictionaries.js

@@ -1,5 +1,5 @@
 // @ts-check
-/** 사전들을 한 번 컴파일하고 문장에서 맞는 자리를 찾는다. 설정의 dictionary 항목을 더한다. */
+/** 사전들을 한 번 컴파일하고 문장에서 맞는 부분을 찾는다. 설정의 dictionary 항목을 더한다. */
 import { loadEntries } from "../data/load.js";
 import { compile } from "../regex.js";
 
@@ -20,11 +20,11 @@ export const DICTIONARY_FILES = {
 };
 const GROUP_REF = /\$(\d)/g;
 const FINALS = { ㄴ: 4, ㄹ: 8 };
-// {조사} 자리표시자. 낱말 뒤에 조사가 붙었거나 낱말이 끝나는 자리. 파이썬 dictionaries.py 와 같은 글자다.
+// {조사} 자리표시자. 단어 뒤에 조사가 붙었거나 단어가 끝나는 곳. 파이썬 dictionaries.py와 같은 글자다.
 const JOSA_TAIL = "(?=(?:에서는|으로는|에서|에게|까지|부터|보다|처럼|으로|이나|은|는|이|가|을|를|의|에|로|와|과|도|만)?(?![가-힣]))";
 const PLACEHOLDER = /\{(ㄴ|ㄹ|조사)\}/g;
 
-/** 받침으로 끝나는 음절 399개의 문자 부류. @param {"ㄴ" | "ㄹ"} final */
+/** 받침으로 끝나는 음절 399개의 글자 집합. @param {"ㄴ" | "ㄹ"} final */
 function syllableClass(final) {
   let chars = "";
   for (let initial = 0; initial < 19; initial++) {
@@ -46,8 +46,8 @@ export function expandClasses(pattern) {
  * @property {string} source
  * @property {string | null} fix
  * @property {{ pattern: import("../regex.js").Pattern, into: string }[]} to 문장 전체를 다시 쓰는 규칙. 앞의 것부터 시도한다
- * @property {string} raw pattern 의 원문. 내장 항목만 갖고 설정 항목은 빈 글자라 관용으로 접히지 않는다
- * @property {import("../regex.js").Pattern | null} unless 문장 전체에서 이것이 맞으면 그 문장에서는 항목이 맞지 않는다. 파이썬 Entry.unless 와 같다
+ * @property {string} raw pattern의 원문. 내장 항목만 갖고 설정 항목은 빈 글자라 관용으로 접히지 않는다
+ * @property {import("../regex.js").Pattern | null} unless 문장 전체에서 이것이 맞으면 그 문장에서는 항목이 맞지 않는다. 파이썬 Entry.unless와 같다
  */
 
 /**
@@ -96,7 +96,7 @@ export function entriesFor(config) {
   const extra = [];
   for (const [dictionary, items] of Object.entries(config.dictionary)) {
     if (!(dictionary in DICTIONARY_FILES)) {
-      throw new Error(`모르는 사전: ${dictionary}. ${Object.keys(DICTIONARY_FILES).join(", ")} 가운데 하나다`);
+      throw new Error(`모르는 사전: ${dictionary}. 쓸 수 있는 이름: ${Object.keys(DICTIONARY_FILES).join(", ")}`);
     }
     for (const raw of items) extra.push(entryFrom(dictionary, /** @type {Record<string, unknown> | string} */ (raw)));
   }
@@ -110,7 +110,7 @@ export function applyFix(match, fix) {
 
 /**
  * to 규칙으로 문장을 다시 쓴다. 빈 그룹이 남긴 겹 공백은 하나로 줄이고 양끝을 다듬는다. 원문과 같으면 null.
- * 뜻은 파이썬 fingerprint/dictionaries.py 의 rewriteBy 가 소유한다.
+ * 뜻은 파이썬 fingerprint/dictionaries.py의 rewriteBy가 정한다.
  * @param {string} text @param {Entry["to"]} rules
  */
 export function rewriteBy(text, rules) {

package/src/fingerprint/markers.js

@@ -1,14 +1,14 @@
 // @ts-check
 /**
- * 문장에서 표지를 센다. 종결어미 부류, 서법, 접속부사, 인과, 지시어, 헤지, 약속과 회수, 독자 호출, 수 약속.
- * 낱말 목록은 전부 data/ 가 정본이다. 파이썬 fingerprint/markers.py 와 같다.
+ * 문장에서 정해 둔 말을 센다. 종결어미 묶음, 서법, 접속부사, 인과 접속사, 지시어, 얼버무리는 말, 약속하는 말과 다시 다루는 말, 독자 호출, 수 약속.
+ * 단어 목록은 모두 data/에 있다. 파이썬 fingerprint/markers.py와 같다.
  */
 import { loadLines, loadPatterns } from "../data/load.js";
 import { compile, escape } from "../regex.js";
 
 const TRAILING = /[\s.?!"'”’)\]]+$/;
 const NUMBER = /\d+(?:[.,]\d+)*/g;
-/** 값으로 견주는 수. NUMBER 는 수의 개수를 세고 이것은 수의 정체를 센다. 천 단위 쉼표까지 한 수로 읽는다. */
+/** 값으로 비교하는 수. NUMBER는 수의 개수를 세고 이것은 수의 정체를 센다. 천 단위 쉼표까지 한 수로 읽는다. */
 const NUMERAL = /\d[\d,]*(?:\.\d+)?/g;
 const COMMA = /,/g;
 // 따옴표 쌍. 안은 사용이 아니라 인용이다. 작은따옴표는 앞이 문장 첫머리나 공백이나 여는 괄호일 때만.
@@ -27,7 +27,7 @@ const OPTIONAL_SPACE = /\s?/.source;
 
 /** @type {Record<string, number> | null} */
 let numberCache = null;
-/** 수사 → 값. 정본은 data/koreanNumbers.txt. */
+/** 수사 → 값. 목록은 data/koreanNumbers.txt에 있다. */
 export function koreanNumbers() {
   if (!numberCache) {
     numberCache = {};
@@ -148,7 +148,7 @@ export function quoteSpans(text) {
 }
 
 /**
- * 설정의 protectedTerms 가 글에 나온 [시작, 끝] 전부. 겹쳐 나온 자리도 따로 센다. 파이썬 termSpans 와 같다.
+ * 설정의 protectedTerms가 글에 나온 [시작, 끝] 전부. 겹쳐 나온 것도 따로 센다. 파이썬 termSpans와 같다.
  * @param {string} text @param {string[]} terms @returns {[number, number][]}
  */
 export function termSpans(text, terms) {
@@ -164,7 +164,7 @@ export function termSpans(text, terms) {
   return found.sort((a, b) => a[0] - b[0] || a[1] - b[1]);
 }
 
-/** 두 구간이 한 글자라도 겹치는가. 파이썬 overlapsAny 와 같다. @param {number} start @param {number} end @param {[number, number][]} spans */
+/** 두 구간이 한 글자라도 겹치는가. 파이썬 overlapsAny와 같다. @param {number} start @param {number} end @param {[number, number][]} spans */
 export function overlapsAny(start, end, spans) {
   return spans.some(([spanStart, spanEnd]) => spanStart < end && start < spanEnd);
 }
@@ -189,7 +189,7 @@ export function countPromisesIn(text) {
 }
 
 /** @param {string} text */
-/** 글에 나온 수의 정체 (천 단위 쉼표를 뗀 꼴). 독자 상태가 쌓고 numberOrphan 이 견준다. @param {string} text @returns {Set<string>} */
+/** 글에 나온 수의 정체 (천 단위 쉼표를 뗀 꼴). 독자 상태가 쌓고 numberOrphan이 비교한다. @param {string} text @returns {Set<string>} */
 export function numeralsIn(text) {
   const found = new Set();
   for (const match of text.matchAll(NUMERAL)) found.add(match[0].replaceAll(",", ""));

package/src/fingerprint/readerState.js

@@ -1,28 +1,28 @@
 // @ts-check
 /**
- * 독자 상태. 글을 위에서 아래로 읽는 독자가 어느 자리에서 무엇을 손에 들고 무엇을 이미 보았는가.
- * 파이썬 fingerprint/readerState.py 와 같다. reader 기제의 규칙은 어느 자리가 요구하는 것을 그 자리의 상태에
- * 대 본다. 상태는 블록과 문장 순서로 쌓이고 한 번 쌓은 것은 바뀌지 않는다. 집합은 고치지 않는다.
+ * 독자 상태. 글을 위에서 아래로 읽는 독자가 어느 위치에서 무엇을 이미 알고 무엇을 이미 보았는가.
+ * 파이썬 fingerprint/readerState.py와 같다. 독자 상태를 보는 규칙(reader)은 한 위치가 필요로 하는 것을 그 위치의
+ * 상태와 대조한다. 상태는 블록과 문장 순서로 쌓이고 한 번 쌓은 것은 바뀌지 않는다. 집합은 고치지 않는다.
  */
 import { CODE, PROSE } from "../document/model.js";
 import { createdIn } from "./codeMarkers.js";
 import { numeralsIn } from "./markers.js";
 
 /**
- * 한 자리 (문장 하나 또는 블록 하나) 를 읽기 직전의 독자.
+ * 한 위치(문장 하나 또는 블록 하나)를 읽기 직전의 독자.
  * @typedef {object} ReaderState
  * @property {import("./build.js").SentencePrint | null} previous 바로 앞에 읽은 산문 문장
  * @property {Set<string>} recent 손에 든 화제어. 바로 앞 문장의 것이고 앞 문장이 없으면 빈 집합
- * @property {Set<string>} known 이 자리 앞까지 산문에 나온 화제어 전부
+ * @property {Set<string>} known 이 위치 앞까지 산문에 나온 화제어 전부
  * @property {Set<string>} numerals 지금까지 산문과 블록에 나온 수 (천 단위 쉼표를 뗀 꼴)
  * @property {Set<string>} files 앞선 코드 블록이 만든 파일 이름과 폴더
  * @property {number} sentencesRead 지금까지 읽은 산문 문장 수
- * @property {[number, string][]} promises 지금까지 뒤로 미룬 표지 (줄, 원문)
- * @property {[number, string][]} recalls 지금까지 앞을 회수한 표지 (줄, 원문)
+ * @property {[number, string][]} promises 지금까지 뒤로 미룬 말(줄, 원문)
+ * @property {[number, string][]} recalls 지금까지 앞의 이야기를 다시 다룬 말(줄, 원문)
  */
 
 /**
- * 자리마다의 독자 상태. 문장은 index 로, 블록은 index 로 찾는다.
+ * 위치마다의 독자 상태. 문장은 index로, 블록은 index로 찾는다.
  * @typedef {object} ReaderTrail
  * @property {ReaderState[]} beforeSentence
  * @property {ReaderState[]} beforeBlock
@@ -84,7 +84,7 @@ function afterBlock(state, block, code) {
 }
 
 /**
- * 블록 순서로 한 번 지나며 자리마다의 상태를 적는다. 산문 블록은 문장 하나씩, 나머지는 블록째 읽는다.
+ * 블록 순서로 한 번 지나며 위치마다의 상태를 적는다. 산문 블록은 문장 하나씩, 나머지는 블록째 읽는다.
  * @param {import("../document/model.js").Block[]} blocks
  * @param {import("./codeBlocks.js").CodeBlock[]} codeBlocks
  * @param {import("./build.js").SentencePrint[]} sentences

package/src/fingerprint/sourceSentence.js

@@ -1,5 +1,5 @@
 // @ts-check
-/** 평문 지문의 문장을 마크다운 표식을 보존한 원문 문장에 다시 맞춘다. */
+/** 평문 분석 결과의 문장을 마크다운 표식을 보존한 원문 문장에 다시 맞춘다. */
 import { splitSentences } from "../analysis/splitSentences.js";
 import { plainText } from "../document/plainText.js";
 

package/src/fingerprint/topics.js

@@ -1,5 +1,5 @@
 // @ts-check
-/** 화제어 집합. 조사를 뗀 명사 어절의 근사. 파이썬 fingerprint/topics.py 와 같다. */
+/** 화제어 집합. 조사를 뗀 명사 어절의 어림. 파이썬 fingerprint/topics.py와 같다. */
 import { stripJosa, tailOf, words } from "../analysis/tokenize.js";
 import { loadLines } from "../data/load.js";
 

package/src/guard/contract.js

@@ -1,5 +1,5 @@
 // @ts-check
-/** Reader Contract 검사와 이유가 붙은 국소 Patch 검증. */
+/** Reader Contract 검사와, 이유를 붙여 한 곳만 바꾸는 Patch의 검증. */
 import { sha256 } from "../digest.js";
 
 import { Patch } from "../config/patch.js";
@@ -19,7 +19,7 @@ function digest(text) {
   return sha256(text);
 }
 
-/** 원문의 보호 표면을 모두 덮는 version 1 Contract 초안을 만든다. @param {string} text @param {string} reader @param {string} goal */
+/** 원문의 지켜야 할 숫자·링크·코드를 모두 담는 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);
@@ -27,15 +27,15 @@ export function contractFromText(text, reader, goal) {
   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 (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(", ")}`);
+    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] */
+/** 원문에서 자동으로 찾은 숫자·링크·코드와 한 수준의 제목을 따로 담은 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);
@@ -50,7 +50,7 @@ export function contractFromTextV2(text, reader, goal, outlineLevel = 2, facts =
   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(", ")}`);
+    throw new Error(`reader, goal, facts에 원문에 없는 숫자·링크·코드가 들었다: ${issues.join(", ")}`);
   }
   return contract;
 }

package/src/guard/editLocality.js

@@ -1,5 +1,5 @@
 // @ts-check
-/** 선택한 규칙의 Finding 줄과 원문 변경 창을 대조한다. */
+/** 고른 규칙의 지적이 있는 줄과 원문에서 바뀐 범위를 대조한다. */
 export function editIssues(text, patch, findings, policy) {
   if (!Object.keys(policy).length) return [];
   const limits = policy[patch.reason];

package/src/guard/outline.js

@@ -1,5 +1,5 @@
 // @ts-check
-/** Reader Contract가 잠근 제목 순서와 글 지문의 구조 요약. */
+/** Reader Contract가 고정한 제목 순서와, 글 분석 결과에서 뽑은 구조 요약. */
 
 /** @typedef {{position: number, expected: string | null, actual: string | null}} OutlineMismatch */
 /** @typedef {{matches: boolean, level: number, expected: string[], actual: string[], mismatches: OutlineMismatch[]}} OutlineDiff */

package/src/guard/receipt.js

@@ -1,14 +1,14 @@
 // @ts-check
-/** Reader Contract 검사와 Patch 검증의 결정적 영수증. */
+/** 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 CHECK_MEANING_V2 = "violationCount는 계약에 적은 숫자·링크·코드의 어긋남, 제목 구조의 어긋남, 빠진 고정 문구, hanlint 오류를 더한 수다. facts 사이의 관계와 사실 여부, 빠진 뜻, 독자에게 쓸모 있는지와 자연스러운지는 검사하지 않는다";
 export const PATCH_MEANING = "verified는 정확히 한 자리를 바꾸고 명시한 기존 위반을 줄이며 새 보호 원자 위반과 새 error를 만들지 않았다는 뜻뿐이다. 수정문의 의미와 진실, 자연스러움은 승인하지 않는다";
-export const PATCH_MEANING_V2 = "verified는 정확히 한 자리를 바꾸고 명시한 기존 위반을 줄이며 새 계약 위반과 새 error를 만들지 않고 선택한 수정 예산을 지켰다는 뜻뿐이다. 수정문의 의미와 진실, 자연스러움은 승인하지 않는다";
+export const PATCH_MEANING_V2 = "verified는 정확히 한 곳을 바꾸고, 적어 둔 기존 위반을 줄이고, 새 계약 위반과 새 오류를 만들지 않고, 고른 수정 예산을 지켰다는 뜻뿐이다. 고친 문장의 뜻이 맞는지, 사실인지, 자연스러운지는 보증하지 않는다";
 
 /** @param {import("../rules/finding.js").Finding[]} findings */
 function errorRules(findings) {
@@ -32,7 +32,7 @@ export class CheckResult {
     this.document = document;
     this.missingFacts = missingFacts;
     if (![1, 2].includes(contractVersion)) {
-      throw new Error(`check result contractVersion 은 1 또는 2다: ${contractVersion}`);
+      throw new Error(`check result의 contractVersion은 1이나 2여야 한다. 받은 값: ${contractVersion}`);
     }
     const hasStructure = outline !== null && document !== null;
     if (hasStructure !== (contractVersion === 2)) {
@@ -89,7 +89,7 @@ export class PatchResult {
     this.resultText = values.resultText;
     this.contractVersion = values.contractVersion;
     if (![1, 2].includes(values.contractVersion)) {
-      throw new Error(`patch result contractVersion 은 1 또는 2다: ${values.contractVersion}`);
+      throw new Error(`patch result의 contractVersion은 1이나 2여야 한다. 받은 값: ${values.contractVersion}`);
     }
   }
 
@@ -137,7 +137,7 @@ export class PatchResult {
   }
 }
 
-/** 사람이 결론, 근거, 다음 행동 순서로 읽는 검사 영수증. @param {CheckResult} result */
+/** 사람이 결론, 근거, 다음 할 일의 순서로 읽는 검사 결과. @param {CheckResult} result */
 export function renderCheck(result) {
   const lines = [result.violationCount === 0 ? "계약 위반 없음" : `계약 위반 ${result.violationCount}건`];
   const labels = [
@@ -162,19 +162,19 @@ export function renderCheck(result) {
   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(`  ${index + 1}. ${section.heading} (${section.line}줄, 문단 ${section.paragraphCount}, 코드 ${section.codeBlockCount})`);
     });
   }
-  lines.push(`- lint: error ${result.errorCount}, notice ${result.noticeCount}`);
+  lines.push(`- lint: 오류 ${result.errorCount}건, 경고 ${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(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다음: 경고를 읽고 고칠지 그대로 둘지 정한다");
+  else lines.push("\n다음: 규칙으로 셀 수 있는 계약 위반은 없다. 뜻과 자연스러움은 사람이 읽고 판단한다");
   lines.push("", result.contractVersion === 1 ? CHECK_MEANING : CHECK_MEANING_V2);
   return lines.join("\n");
 }

package/src/guard/surface.js

@@ -1,5 +1,5 @@
 // @ts-check
-/** 계약 본문과 결과 글 사이의 보호 원자 차이. */
+/** 계약 본문과 결과 글 사이에서 지켜야 할 숫자·링크·코드의 차이. */
 
 /**
  * @typedef {object} SurfaceDiff
@@ -107,7 +107,7 @@ export function surfaceViolationCount(diff) {
   return Object.values(diff).reduce((total, values) => total + values.length, 0);
 }
 
-/** 원문의 보호 원자를 뜻 없는 정렬 집합으로 분리한다. @param {string} text */
+/** 원문의 지켜야 할 숫자·링크·코드를 뜻과 상관없이 정렬한 집합으로 나눈다. @param {string} text */
 export function protectedSurface(text) {
   const surfaceText = text.normalize("NFC");
   return {
@@ -118,7 +118,7 @@ export function protectedSurface(text) {
   };
 }
 
-/** 원문의 보호 표면을 모두 덮는 Contract 사실 후보 줄. @param {string} text */
+/** 원문의 지켜야 할 숫자·링크·코드를 모두 담는 Contract 사실 후보 줄. @param {string} text */
 export function factLines(text) {
   const surfaceText = text.normalize("NFC");
   const seen = new Set();
@@ -144,7 +144,7 @@ export function factLines(text) {
     ),
   );
   if (!uncovered.size) {
-    throw new Error("원문에 자동으로 보호할 숫자, URL, 인라인 코드, 링크 목적지가 없다. facts를 직접 작성한다");
+    throw new Error("원문에 자동으로 지킬 숫자, URL, 인라인 코드, 링크 목적지가 없다. facts를 직접 작성한다");
   }
 
   const selected = new Set();