hanlint 0.0.17 → 0.0.18

package/data/version.json

@@ -1 +1 @@
-{"version": "0.0.17"}
+{"version": "0.0.18"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hanlint",
-  "version": "0.0.17",
+  "version": "0.0.18",
   "description": "한국어 글 검사기. Korean prose linter for Markdown: translationese, noun piles, double passives, weak structure. Zero dependencies",
   "type": "module",
   "bin": {

package/src/analysis/index.js

@@ -4,4 +4,4 @@
  * 지문이 필요로 하는 것은 넷이다. splitSentences, euiCount 와 euiAdjacent, longestNounRun, doublePassives.
  */
 export { splitSentences } from "./splitSentences.js";
-export { doublePassives, doublePassiveSpans, euiAdjacent, euiCount, longestNounRun } from "./tokenize.js";
+export { doublePassives, doublePassiveSpans, euiAdjacent, euiCount, longestNounRun, nounRuns } from "./tokenize.js";

package/src/analysis/tokenize.js

@@ -12,13 +12,13 @@ const WORD_CHARS = /^[가-힣A-Za-z0-9]+$/;
 /** 관형격 조사 의. 영문과 숫자 뒤 (API의, 600MiB의) 와 닫는 괄호 뒤 (L7(HTTP)의) 도 센다. 파이썬 tokenize.py 와 같다. */
 const GENITIVE = /([가-힣A-Za-z0-9]+|\))의(?=[\s,.)\]]|$)/g;
 const SPACED_GENITIVE = /(?<=\s)의(?=\s)/g;
-const COPULA = /^(?:이(?:고|며|다|라|란|면|라서|므로|지만|어서|었다|었고)|인|인데|입니다|였다)$/;
+export const COPULA = /^(?:이(?:고|며|다|라|란|면|라서|므로|지만|어서|었다|었고)|인|인데|입니다|였다)$/;
 const DIGITS = /^\d+$/;
 /** 수에 단위가 붙은 어절 (2012년, 30분쯤, 제16호, 100명). 수량이라 명사 나열에서 세지도 끊지도 않는다. */
 const QUANTITY = /^제?\d[\d,.]*[가-힣]{1,3}$/;
 const OPENERS = "([{\"“‘'";
 const CLOSERS = ",.?!;:)]}\"”’'";
-const EDGE_PUNCTUATION = ".,?!:;\"'“”‘’()[]{}<>";
+export const EDGE_PUNCTUATION = ".,?!:;\"'“”‘’()[]{}<>";
 
 /**
  * @typedef {object} Word
@@ -130,32 +130,47 @@ export function isBareNoun(core) {
  * 표층으로는 명사로 보이지만 명사 쌓기의 재료가 아니다. data/nonNouns.txt 가 그 목록이고 연속을 끊는다.
  * @param {string} text
  */
-export function longestNounRun(text) {
-  let longest = 0;
+/**
+ * 명사 어절 연속마다 [어절들, 센 길이]. 뜻은 파이썬 analysis/tokenize.py 의 nounRuns 가 소유한다.
+ * 수사와 단위는 세지도 끊지도 않고 어절에도 안 넣는다. 잇달은 영문 어절은 하나로 센다.
+ * @param {string} text @returns {[string[], number][]}
+ */
+export function nounRuns(text) {
+  /** @type {[string[], number][]} */
+  const runs = [];
+  /** @type {string[]} */
+  let chain = [];
   let run = 0;
   let previousAscii = false;
   let afterNumeral = false;
+  const close = () => {
+    if (run) runs.push([chain, run]);
+    chain = [];
+    run = 0;
+    previousAscii = false;
+  };
   for (const word of words(text)) {
-    if (word.opens) {
-      run = 0;
-      previousAscii = false;
-    }
+    if (word.opens) close();
     const transparent = isNumeral(word.core) || afterNumeral || isQuantity(word.core);
     afterNumeral = isNumeral(word.core);
     if (word.particle || nonNouns().has(word.core) || !isBareNoun(word.core) || isCopulaAdnominal(word.core)) {
-      run = 0;
-      previousAscii = false;
+      close();
     } else if (!transparent) {
       const isAscii = !HANGUL.test(word.core);
       if (!(isAscii && previousAscii)) run += 1;
+      chain.push(word.core);
       previousAscii = isAscii;
-      longest = Math.max(longest, run);
-    }
-    if (word.endsClause) {
-      run = 0;
-      previousAscii = false;
     }
+    if (word.endsClause) close();
   }
+  close();
+  return runs;
+}
+
+/** 명사 어절 연속의 최대 길이. nounRuns 의 센 길이 가운데 가장 큰 것. @param {string} text */
+export function longestNounRun(text) {
+  let longest = 0;
+  for (const [, length] of nounRuns(text)) longest = Math.max(longest, length);
   return longest;
 }
 

package/src/cli/help.js

@@ -7,7 +7,7 @@ export function rootHelp() {
 일상 검사
   hanlint 글.md                         글을 검사한다
   hanlint fix 글.md                     안전한 고침만 적용한다
-  hanlint hook                          AI가 저장한 마크다운을 같은 턴에 검사한다
+  hanlint hook                          AI에게 쓰기 전 작법서를 싣고, 저장한 마크다운을 같은 턴에 검사한다
 
 요구사항 잠금
   hanlint contract init 글.md --reader "독자" --goal "목표" --outline h2
@@ -23,7 +23,8 @@ export function rootHelp() {
   hanlint spec --preset <종류> --chars 800
                                          쓰기 전 숫자 사양을 만든다
   hanlint primer --preset <종류>         쓰기 전에 규칙의 고치는 법과 본보기를 한 장으로 본다
-  hanlint sheet src/ --preset screen    소스의 화면 글을 표 하나로 떨군다. 고친 표는 sheet apply 로 되돌려 쓴다
+  hanlint sheet src/ --preset screen    소스의 화면 글을 표 하나로 내보낸다. 고친 표는 sheet apply 로 되돌려 쓴다
+  hanlint usage "낱말 낱말"             그 종류의 실제 글에서 낱말이 쓰인 문장을 본다. 색인은 usage build 가 만든다
 
 추가 명령
   baseline, print

package/src/cli/main.js

@@ -6,12 +6,12 @@
  * hanlint                       인자가 없으면 첫 화면. 무엇을 칠 수 있는지 보인다
  * hanlint 글.md [다른.md ...]   검사. 서브커맨드 없이 파일이나 폴더만 주면 lint 다. `-` 는 stdin
  * hanlint fix 글.md             기계가 고칠 수 있는 지적을 원문에 적용
- * hanlint print 글.md           지문 계층 JSON
+ * hanlint print 글.md           분석표 계층 JSON
  * hanlint rules                 규칙 목록을 부류로 묶어서
  * hanlint explain <규칙>        규칙의 기술서
  * hanlint patterns             문장 틀. --rule 로 그 규칙을 피하는 것만
- * hanlint primer --preset <종류> 쓰기 전에 읽는 한 장. 켜진 규칙의 고치는 법과 본보기 전후
- * hanlint hook                  Claude Code가 쓴 마크다운을 같은 턴에 비차단 검사
+ * hanlint primer --preset <종류> 쓰기 전에 읽는 한 장. 작법서 일곱 줄과 켜진 규칙의 고치는 법, 본보기 전후
+ * hanlint hook                  에이전트 훅. --prime 은 쓰기 전 작법서, 나머지는 쓴 마크다운의 비차단 검사
  * hanlint baseline 글들/        지금 있는 지적을 잠근다. 그다음부터 새것만 막힌다
  * hanlint baseline 글들/        지금 있는 지적을 잠근다. 그다음부터 새것만 막힌다
  * hanlint doctor                설정과 꺼진 규칙
@@ -43,12 +43,22 @@ import { loadConfig } from "../config/loadConfig.js";
 import { defaultConfig, offRules, PRESET_NAMES, PRESETS } from "../config/settings.js";
 import { applyFixes } from "../edit/applyFixes.js";
 import { exemplarFor } from "../data/exemplars.js";
+import { proseGuide, proseSections } from "../data/prose.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, isSkipped, markdownUnder } from "./walk.js";
-import { SOURCE_SUFFIXES, replaceLiteral, sourceLiterals } from "../document/sourceText.js";
-import { parseSheet, renderSheet, renderSheetJson } from "../report/sheet.js";
+import { SOURCE_SUFFIXES } from "../document/sourceText.js";
+import { applyRows, parseSheet, renderSheet, renderSheetJson, sheetRows } from "../report/sheet.js";
+import {
+  buildIndex as buildUsageIndex,
+  defaultRoot as defaultUsageRoot,
+  listIndexes as listUsageIndexes,
+  loadIndex as loadUsageIndex,
+  queryCores as usageQueryCores,
+  readDocuments as readUsageDocuments,
+} from "../usage/sentences.js";
+import { USAGE_KINDS } from "../config/settings.js";
 import { welcome } from "./welcome.js";
 import { rootHelp } from "./help.js";
 import { renderCompact } from "../report/compactReport.js";
@@ -59,7 +69,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", "sheet"];
+const COMMANDS = ["lint", "fix", "print", "rules", "explain", "patterns", "primer", "spec", "hook", "baseline", "doctor", "init", "contract", "check", "verify-patch", "sheet", "usage"];
 const PYTHON_ONLY = [
   "audit",
   "map",
@@ -116,12 +126,15 @@ const OPTION_KINDS = {
   "--quiet": "flag",
   "--severity": "value",
   "--errors-only": "flag",
+  "--notices": "flag",
   "--path": "value",
   "--layer": "value",
   "--dry-run": "flag",
   "--names": "flag",
   "--force": "flag",
   "--reply": "flag",
+  "--agent": "value",
+  "--prime": "flag",
   "--reader": "value",
   "--goal": "value",
   "--outline": "value",
@@ -133,6 +146,9 @@ const OPTION_KINDS = {
   "--baseline": "optional",
   "--prune": "flag",
   "--all": "flag",
+  "--kind": "value",
+  "--limit": "value",
+  "--root": "value",
 };
 
 class UsageError extends Error {}
@@ -249,7 +265,7 @@ function configFrom(options, paths, start = null) {
 function configLabel(config) {
   if (config.source === null) return "기본값";
   const rel = relative(process.cwd(), config.source);
-  // 경로 구분자는 언제나 /. 설정이 작업 폴더 밖일 때 두 판의 첫 줄이 갈렸다. 파이썬과 같다.
+  // 경로 구분자는 언제나 /. 설정이 작업 폴더 밖일 때 두 구현의 첫 줄이 갈렸다. 파이썬과 같다.
   const label = !rel || rel.startsWith("..") || isAbsolute(rel) ? config.source : rel;
   return label.split(sep).join("/");
 }
@@ -354,7 +370,7 @@ function nextStep(results, fixable = 0) {
     if (patternsAvoiding(rule).length) return `다음: error ${errors.length}건을 고친다. 다시 쓸 틀은 hanlint patterns --rule ${rule}`;
     return `다음: error ${errors.length}건을 고친다. 규칙이 왜 있는지는 hanlint explain ${rule}`;
   }
-  if (notices) return `다음: error 0. 확인할 자리 ${notices}건을 읽고 판단한 뒤 사람과 LLM 평가로 넘어간다`;
+  if (notices) return `다음: error 0. 확인 권고 ${notices}건을 읽고 판단한 뒤 사람과 LLM 평가로 넘어간다`;
   return "다음: 세어서 잡히는 결함이 없다. 좋은 글이라는 뜻은 아니므로 사람과 LLM 평가로 넘어간다";
 }
 
@@ -528,7 +544,7 @@ function runLint(args) {
     } else {
       parts.push(
         [...shown]
-          .map(([name, findings]) => renderText(name, findings, registers.get(name), config.preset, config.exemplars))
+          .map(([name, findings]) => renderText(name, findings, registers.get(name), config.preset, config.exemplars, Boolean(options["--notices"])))
           .join("\n\n"),
       );
       if (shown.size > 1) parts.push(summary(results));
@@ -753,10 +769,17 @@ function primerEntries(config, register) {
   return entries;
 }
 
+/** 작법서를 절마다 한 줄로. 제목 두 칸 띄고 본문이다. 파이썬 proseLines 와 같다. */
+function proseLines() {
+  return proseSections().map(([title, body]) => `${title}  ${body.split(/\s+/).filter(Boolean).join(" ")}`);
+}
+
 /** 사람과 AI 가 읽는 한 장. 파이썬 renderPrimer 와 글자 단위로 같다. @param {ReturnType<typeof primerEntries>} entries @param {string} preset @param {string} register */
 function renderPrimer(entries, preset, register) {
   const lines = [
-    `hanlint primer  ${preset} 종류, ${register}체, 규칙 ${entries.length}개. 줄마다 규칙 이름, 고치는 법, 전 (그 규칙에 잡히는 글), 후 (같은 뜻으로 통과하는 글) 순서다. 본보기의 줄바꿈은 ¶ 다`,
+    ...proseLines(),
+    "",
+    `hanlint primer  ${preset} 종류, ${register}체, 규칙 ${entries.length}개. 줄마다 규칙 이름, 고치는 법, 전 (그 규칙에 잡히는 글), 후 (그 본보기에서 고친 글) 순서다. 본보기의 줄바꿈은 ¶ 다`,
   ];
   for (const [category, title] of Object.entries(CATEGORY_TITLES)) {
     const inside = entries.filter((entry) => entry.category === category);
@@ -764,7 +787,7 @@ function renderPrimer(entries, preset, register) {
     lines.push("", `${title} (${inside.length})`);
     for (const entry of inside) lines.push(`${entry.rule}  ${entry.fix}  전: ${flat(entry.before)}  후: ${flat(entry.after)}`);
   }
-  lines.push("", "후는 전부 hanlint 를 error 0 으로 통과한다 (게이트가 확인한다). 규칙 하나를 깊게 보려면 hanlint explain <규칙>");
+  lines.push("", "본보기는 해당 문맥의 예시다. 용어와 사실을 보존하고, 치환을 다른 문맥에 적용하지 않는다. 규칙을 더 보려면 hanlint explain <규칙>");
   return lines.join("\n");
 }
 
@@ -777,7 +800,7 @@ function runPrimer(args) {
   const output = /** @type {string | undefined} */ (options["--output"]);
   const format = choose(/** @type {string} */ (options["--format"] ?? "text"), ["text", "json"], "--format");
   if (format === "json") {
-    emit(JSON.stringify({ version: 1, preset: config.preset, register, rules: entries }, null, 2), output);
+    emit(JSON.stringify({ version: 1, preset: config.preset, register, prose: proseGuide(), rules: entries }, null, 2), output);
     return 0;
   }
   emit(renderPrimer(entries, config.preset, register), output);
@@ -802,53 +825,104 @@ function runSpec(args) {
   return 0;
 }
 
-/** Claude Code가 다음 모델 요청에 넣는 비차단 Finding 문맥. */
-function hookContext(eventName, name, findings) {
+/** 작법서를 싣는 이벤트. Claude Code와 Codex 모두 이 둘의 additionalContext를 모델 문맥에 넣는다. */
+const PRIME_EVENTS = ["SessionStart", "UserPromptSubmit"];
+
+/** 에이전트가 다음 모델 요청에 넣는 비차단 문맥. @param {string} eventName @param {string} context */
+function hookContext(eventName, context) {
+  return JSON.stringify({ hookSpecificOutput: { hookEventName: eventName, additionalContext: context } });
+}
+
+/** Finding을 되먹이는 문맥의 본문. 파일마다 한 덩어리다. 파이썬 findingContext 와 같다. @param {string} eventName @param {[string, import("../rules/finding.js").Finding[]][]} found */
+function findingContext(eventName, found) {
   const where = eventName === "Stop" ? "마지막 답변" : "방금 쓴 마크다운";
-  return JSON.stringify({
-    hookSpecificOutput: {
-      hookEventName: eventName,
-      additionalContext: `hanlint가 ${where}에서 센 Finding입니다.\n${renderCompact(name, findings)}`,
-    },
-  });
+  return `hanlint가 ${where}에서 센 Finding입니다.\n${found.map(([name, items]) => renderCompact(name, items)).join("\n")}`;
+}
+
+/** Codex apply_patch 본문에서 쓴 파일을 가리키는 머리 줄 (Codex 훅 문서, 2026-09-21 확인). */
+const PATCH_HEADS = ["*** Add File: ", "*** Update File: ", "*** Move to: "];
+
+/** apply_patch 본문이 쓴 파일 경로. 나온 차례대로 한 번씩이다. @param {string} patch */
+function patchPaths(patch) {
+  /** @type {string[]} */
+  const paths = [];
+  for (const line of patch.split(/\r?\n/)) {
+    for (const head of PATCH_HEADS) {
+      if (!line.startsWith(head)) continue;
+      const path = line.slice(head.length).trim();
+      if (path && !paths.includes(path)) paths.push(path);
+    }
+  }
+  return paths;
+}
+
+/** PostToolUse 입력이 쓴 파일 경로. 모르는 도구면 빈 목록이다. @param {any} payload @returns {string[]} */
+function writtenPaths(payload) {
+  const toolInput = payload.tool_input;
+  if (!toolInput || typeof toolInput !== "object" || Array.isArray(toolInput)) return [];
+  if (["Write", "Edit"].includes(payload.tool_name)) {
+    const path = toolInput.file_path;
+    return typeof path === "string" && path ? [path] : [];
+  }
+  if (payload.tool_name === "apply_patch") return typeof toolInput.command === "string" ? patchPaths(toolInput.command) : [];
+  return [];
+}
+
+/** 쓴 마크다운마다 [이름, Finding]. 상대 경로는 입력의 cwd에서 찾는다. @param {any} payload @param {Record<string, unknown>} options */
+function writtenFindings(payload, options) {
+  const base = typeof payload.cwd === "string" && payload.cwd ? payload.cwd : null;
+  /** @type {[string, import("../rules/finding.js").Finding[]][]} */
+  const found = [];
+  for (const rawPath of writtenPaths(payload)) {
+    const path = base !== null && !isAbsolute(rawPath) ? join(base, rawPath) : rawPath;
+    if (!MARKDOWN.includes(extname(path).toLowerCase())) continue;
+    try {
+      if (!statSync(path).isFile()) continue;
+    } catch {
+      continue;
+    }
+    const config = configFrom(options, [path]);
+    let findings = lintText(readFileSync(path, "utf-8"), config, rawPath);
+    if (config.baseline) findings = loadBaseline(config.baseline).keep(rawPath, findings);
+    found.push([rawPath, findings]);
+  }
+  return found;
 }
 
 /** 명령 훅 JSON을 stdin에서 읽어 저장 파일이나 마지막 답변을 검사한다. 언제나 종료 코드 0이다. @param {string[]} args */
 function runHook(args) {
+  if (args.includes("--prime") && args.includes("--reply")) throw new UsageError("--prime 과 --reply 는 함께 쓰지 않는다");
+  const { options, positionals } = parseArgs(args);
+  const agent = choose(/** @type {string} */ (options["--agent"] ?? "claude"), ["claude", "codex"], "--agent");
   try {
-    const { options, positionals } = parseArgs(args);
     if (positionals.length) return 0;
     const payload = JSON.parse(readFileSync(0, "utf-8"));
     if (!payload || typeof payload !== "object" || Array.isArray(payload)) return 0;
-    let eventName;
-    let name;
-    let findings;
+    const eventName = payload.hook_event_name;
+    if (options["--prime"]) {
+      if (PRIME_EVENTS.includes(eventName)) process.stdout.write(`${hookContext(eventName, proseGuide())}\n`);
+      return 0;
+    }
+    /** @type {[string, import("../rules/finding.js").Finding[]][]} */
+    let found;
     if (options["--reply"]) {
-      if (payload.hook_event_name !== "Stop" || payload.stop_hook_active === true) return 0;
+      if (eventName !== "Stop" || payload.stop_hook_active === true) return 0;
       const text = payload.last_assistant_message;
       if (typeof text !== "string" || !text.trim()) return 0;
       const start = typeof payload.cwd === "string" && payload.cwd ? payload.cwd : process.cwd();
       const config = configFrom(options, [], start);
       config.preset = "chat";
-      eventName = "Stop";
-      name = "<assistant>";
-      findings = lintText(text, config, name);
+      found = [["<assistant>", lintText(text, config, "<assistant>")]];
+    } else if (eventName === "PostToolUse") {
+      found = writtenFindings(payload, options);
     } else {
-      if (payload.hook_event_name !== "PostToolUse" || !["Write", "Edit"].includes(payload.tool_name)) return 0;
-      const rawPath = payload.tool_input?.file_path;
-      if (typeof rawPath !== "string" || !rawPath || !MARKDOWN.includes(extname(rawPath).toLowerCase())) return 0;
-      try {
-        if (!statSync(rawPath).isFile()) return 0;
-      } catch {
-        return 0;
-      }
-      const config = configFrom(options, [rawPath]);
-      eventName = "PostToolUse";
-      name = rawPath;
-      findings = lintText(readFileSync(rawPath, "utf-8"), config, name);
-      if (config.baseline) findings = loadBaseline(config.baseline).keep(name, findings);
+      return 0;
     }
-    if (findings.length) process.stdout.write(`${hookContext(eventName, name, findings)}\n`);
+    found = found.filter(([, items]) => items.length);
+    if (!found.length) return 0;
+    const context = findingContext(eventName, found);
+    if (options["--reply"] && agent === "codex") process.stdout.write(`${JSON.stringify({ systemMessage: context })}\n`);
+    else process.stdout.write(`${hookContext(eventName, context)}\n`);
   } catch {
     return 0;
   }
@@ -920,10 +994,10 @@ export function renderInit(preset = "blog") {
     "# hanlint baseline 이 만든 잠금 파일. 있으면 그 안의 지적은 넘기고 새로 생긴 것만 막는다",
     '# baseline = ".hanlint-baseline.json"',
     "",
-    "# 코드도 산문도 아닌 펜스의 언어 표기. 장면 계약과 도표 원문은 코드 블록으로 세지 않고 지문에서 뺀다",
+    "# 코드도 산문도 아닌 펜스의 언어 표기. 장면 계약과 도표 원문은 코드 블록으로 세지 않고 분석표에서 뺀다",
     '# ignoreFences = ["course-scene", "mermaid"]',
     "",
-    "# 임계. 기본값의 정본은 hanlint 의 config/settings.py 다",
+    "# 임계. 기본값의 기준은 hanlint 의 config/settings.py 다",
   );
   for (const name of THRESHOLD_FIELDS) {
     const value = /** @type {number} */ (defaults[name]);
@@ -931,9 +1005,16 @@ export function renderInit(preset = "blog") {
     lines.push(`# ${name} = ${shown}`);
   }
   lines.push(
+    "",
+    "# 용례. nounPile 은 그 종류의 실제 글에서 usageMin 편 이상의 문서에 나온 명사 연쇄를 짚지 않고, 사전 규칙은",
+    "# 그 종류의 문서 usageShare 이상에 나오는 항목 (사업보고서의 `에 대한`) 을 짚지 않는다.",
+    "# 종류는 프리셋이 정한다 (report 만 있다). 빈 문자열이면 어떤 프리셋에서도 용례를 보지 않는다",
+    '# usageKind = ""',
+    "# usageMin = 3",
+    "# usageShare = 0.9",
     "",
     "# 사전에 더할 항목. 키는 cliches, translationese, redundantPair, japaneseLoan, easyWords,",
-    "# screenSentence, screenNarration, screenTone, screenWord",
+    "# screenSentence, screenNarration, screenTone, screenWord, calqueFrame",
     "# [dictionary]",
     '# cliches = ["우리의 여정"]',
     '# translationese = [{ pattern = "에 대한 이해", fix = "를 아는 것" }]',
@@ -995,7 +1076,9 @@ function sourceUnder(folder) {
       if (!isSkipped(name)) found.push(...sourceUnder(path));
     } else if (SOURCE_SUFFIXES.includes(extname(name).toLowerCase())) found.push(path);
   }
-  return found.sort();
+  // 구분자를 / 로 맞춘 뒤 정렬한다. 뜻은 파이썬 sourceUnder 가 소유한다.
+  const posix = (item) => item.split(sep).join("/");
+  return found.sort((a, b) => (posix(a) < posix(b) ? -1 : posix(a) > posix(b) ? 1 : 0));
 }
 
 /** 작업 폴더 기준 상대 경로, 구분자는 `/`. 파이썬 relativeLabel 과 같은 글자를 낸다. @param {string} path */
@@ -1028,40 +1111,105 @@ function applySheet(sheetPath, dryRun) {
       failed.push(...rows.map((row) => `${placeOf(row)}: 파일이 없다`));
       continue;
     }
-    const lines = readFileSync(file, "utf-8").split("\n");
-    let changed = false;
-    // 한 줄에 고침이 여럿이면 뒤 칸부터. 앞 칸을 먼저 바꾸면 길이가 달라져 뒤 칸의 자리가 어긋난다.
-    for (const row of [...rows].sort((a, b) => a.line - b.line || b.column - a.column)) {
-      const place = placeOf(row);
-      if (row.line < 1 || row.line > lines.length) {
-        failed.push(`${place}: 그 줄이 없다`);
-        continue;
-      }
-      let newLine = lines[row.line - 1];
-      if (row.column > 0) {
-        const start = row.column - 1;
-        if (newLine.slice(start, start + row.text.length) !== row.text) {
-          failed.push(`${place}: 그 칸에 그 글이 없다. 표를 다시 뽑는다`);
-          continue;
-        }
-        newLine = newLine.slice(0, start) + row.fix + newLine.slice(start + row.text.length);
-      } else {
-        const [replaced, count] = replaceLiteral(newLine, row.text, row.fix);
-        if (count !== 1) {
-          failed.push(`${place}: 글이 그 줄에 ${count}번 있다. 한 번이어야 바꾼다`);
-          continue;
-        }
-        newLine = replaced;
-      }
-      lines[row.line - 1] = newLine;
-      changed = true;
-      applied.push(`${place}: ${row.text} -> ${row.fix}`);
-    }
-    if (changed && !dryRun) writeFileSync(file, lines.join("\n"), "utf-8");
+    // 되돌려 쓰는 뜻은 report/sheet.js 의 applyRows 가 소유한다 (브라우저의 저장소 쓰기와 같은 함수).
+    const [rewritten, done, problems] = applyRows(readFileSync(file, "utf-8"), rows);
+    applied.push(...done);
+    failed.push(...problems);
+    if (done.length && !dryRun) writeFileSync(file, rewritten, "utf-8");
   }
   return [applied, failed];
 }
 
+/** 색인이 없을 때의 안내. 뜻은 파이썬 cli/commands/usage.py 의 missingIndex 가 소유한다. @param {string} kind @param {string} root */
+function missingIndex(kind, root) {
+  const kinds = listUsageIndexes(root).map((meta) => String(meta.kind)).join(", ") || "없음";
+  return `${kind} 색인이 없다 (있는 것: ${kinds}). hanlint usage build ${kind} <글 폴더> 로 만든다 (txt, md, jsonl. 하위 폴더 포함). 사업보고서는 scripts/fetch/dartReports.py, 위키백과는 scripts/fetch/koWikipedia.py 가 받는다`;
+}
+
+/** 함께 쓰는 말 낱말 수 상한. 뜻은 파이썬 QUERY_WORDS 가 소유한다. */
+const USAGE_QUERY_WORDS = 3;
+
+/** @param {[string, number][]} pairs */
+function pairText(pairs) {
+  return pairs.map(([term, count]) => `${term} ${count}편`).join(", ");
+}
+
+/**
+ * `hanlint usage "낱말 …" --kind report --limit 5`, `hanlint usage build <종류> <글 폴더>`, `hanlint usage kinds`. 뜻은 파이썬
+ * cli/commands/usage.py 가 소유한다.
+ * @param {string[]} args
+ */
+function runUsage(args) {
+  const { options, positionals } = parseArgs(args);
+  const output = /** @type {string | undefined} */ (options["--output"]);
+  const root = /** @type {string} */ (options["--root"] ?? defaultUsageRoot());
+  const format = choose(/** @type {string} */ (options["--format"] ?? "text"), ["text", "json"], "--format");
+  if (!positionals.length) throw new UsageError('hanlint usage "낱말 …" 또는 hanlint usage build <종류> <글 폴더>');
+  if (positionals[0] === "kinds") {
+    const found = listUsageIndexes(root);
+    if (format === "json") {
+      emit(JSON.stringify({ version: 1, root, kinds: found }, null, 2), output);
+      return 0;
+    }
+    if (!found.length) {
+      emit(`${root} 에 색인이 없다. hanlint usage build <종류> <글 폴더> 로 만든다`, output);
+      return 0;
+    }
+    const lines = [`색인 ${found.length}개 (${root})`];
+    for (const meta of found) lines.push(`  ${meta.kind}: 문서 ${meta.documents}편, 문장 ${meta.sentences}개, 토큰 ${meta.terms}종`);
+    emit(lines.join("\n"), output);
+    return 0;
+  }
+  if (positionals[0] === "build") {
+    if (positionals.length !== 3) {
+      emit("hanlint usage build <종류> <글 폴더> 꼴로 준다", output);
+      return 2;
+    }
+    const [, kind, folder] = positionals;
+    if (!existsSync(folder) || !statSync(folder).isDirectory()) {
+      emit(`${folder} 는 폴더가 아니다`, output);
+      return 2;
+    }
+    const result = buildUsageIndex(kind, readUsageDocuments(folder), root);
+    emit(`${join(root, kind)}: 문서 ${result.documents}편, 문장 ${result.sentences}개, 토큰 ${result.terms}종. hanlint usage "낱말" --kind ${kind} 로 묻는다`, output);
+    return 0;
+  }
+  const kind = /** @type {string} */ (options["--kind"] ?? USAGE_KINDS[0]);
+  const limit = Math.max(Number(options["--limit"] ?? 5), 0);
+  if (!Number.isInteger(limit)) throw new UsageError("--limit 은 정수다");
+  const query = positionals.join(" ");
+  const index = loadUsageIndex(kind, root);
+  if (!index) {
+    emit(missingIndex(kind, root), output);
+    return 2;
+  }
+  const words = usageQueryCores(query)
+    .slice(0, USAGE_QUERY_WORDS)
+    .map((core) => index.collocations(core))
+    .filter((item) => item !== null && (item.predicates.length || item.following.length || item.preceding.length));
+  const hits = index.search(query, limit);
+  if (format === "json") {
+    const data = { version: 2, kind, query, documents: index.documents, sentences: index.sentences, words, hits };
+    emit(JSON.stringify(data, null, 2), output);
+    return 0;
+  }
+  const lines = [`${kind} 용례 (문서 ${index.documents}편, 문장 ${index.sentences}개): ${query}`];
+  for (const item of words) {
+    if (!item) continue;
+    lines.push(`함께 쓰는 말 (${item.term}, 문장 ${item.sampled}개에서)`);
+    for (const [label, pairs] of [["뒤 용언", item.predicates], ["뒤 명사", item.following], ["앞 명사", item.preceding]]) {
+      if (pairs.length) lines.push(`   ${label}: ${pairText(/** @type {[string, number][]} */ (pairs))}`);
+    }
+  }
+  if (!hits.length && limit > 0) lines.push("쓰인 문장이 없다. 낱말을 줄이거나 다른 낱말로 묻는다");
+  hits.forEach((hit, index) => {
+    lines.push(`${index + 1}. ${hit.text}`);
+    lines.push(`   문서 ${hit.documents}편, 출처 ${hit.source}`);
+  });
+  emit(lines.join("\n"), output);
+  return 0;
+}
+
 /** `hanlint sheet 폴더/ --preset screen` 과 `hanlint sheet apply 시트.md`. 뜻은 파이썬 cli/commands/sheet.py 가 소유한다. @param {string[]} args */
 function runSheet(args) {
   const { options, positionals } = parseArgs(args);
@@ -1089,18 +1237,8 @@ function runSheet(args) {
   }
   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");
-      // 지적이 하나이고 고침이 있으면 고침 칸에 미리 적는다. 뜻은 파이썬 cli/commands/sheet.py 의 prefilledFix 가 소유한다.
-      const only = literal.plain === literal.text && findings.length === 1 ? findings[0] : null;
-      const fix = only && only.fix !== null && only.quote === literal.plain ? only.fix : "";
-      if (findings.length || options["--all"]) rows.push({ file: label, line: literal.line, text: literal.text, findings, fix, column: literal.column });
-    }
-  }
+  // 디스크의 파일을 읽어 report.sheetRows 에 넘긴다. 행의 뜻은 그쪽이 소유한다.
+  const rows = sheetRows(files.map((file) => ({ label: relativeLabel(file), source: readFileSync(file, "utf-8") })), config, Boolean(options["--all"]));
   emit(format === "json" ? renderSheetJson(rows, config.preset, files.length) : renderSheet(rows, config.preset, files.length), output);
   return 0;
 }
@@ -1138,6 +1276,7 @@ function dispatch(argv) {
   if (command === "baseline") return runBaseline(rest);
   if (command === "doctor") return runDoctor(rest);
   if (command === "sheet") return runSheet(rest);
+  if (command === "usage") return runUsage(rest);
   return runInit(rest);
 }
 

package/src/cli/walk.js

@@ -16,7 +16,7 @@ export function isSkipped(name) {
   return name.startsWith(".") || SKIPPED_FOLDERS.includes(name);
 }
 
-/** 폴더 아래 마크다운. 건너뛸 폴더에는 안 들어간다. 경로 문자열 순이라 두 판이 같은 차례를 낸다. @param {string} folder */
+/** 폴더 아래 마크다운. 건너뛸 폴더에는 안 들어간다. 경로 문자열 순이라 두 구현이 같은 차례를 낸다. @param {string} folder */
 export function markdownUnder(folder) {
   /** @type {string[]} */
   const found = [];

package/src/cli/welcome.js

@@ -1,7 +1,7 @@
 // @ts-check
 /**
  * `hanlint` 를 인자 없이 쳤을 때의 첫 화면. 파이썬 cli/welcome.py 와 같은 글자다.
- * 같은 폴더에서 두 판을 돌리면 결과가 같다. 파일을 찾는 것은 검사와 같은 함수 (walk.markdownUnder) 다.
+ * 같은 폴더에서 두 구현을 돌리면 결과가 같다. 파일을 찾는 것은 검사와 같은 함수 (walk.markdownUnder) 다.
  */
 import { relative, sep } from "node:path";