hanlint 0.0.1

package/src/analysis/index.js

@@ -0,0 +1,34 @@
+// @ts-check
+/**
+ * 분석기. 지문 생성이 필요로 하는 넷만 드러낸다. sentences, euiCount, longestNounRun, doublePassives.
+ * npm 에는 의존성 0 의 surface 만 있다. kiwi 정밀 모드는 파이썬 패키지 (`pip install hanlint[kiwi]`) 에 있다.
+ */
+import { splitSentences } from "./surface/splitSentences.js";
+import * as tokenize from "./surface/tokenize.js";
+
+/**
+ * @typedef {object} Analyzer
+ * @property {string} name
+ * @property {(text: string) => import("./surface/splitSentences.js").Sentence[]} sentences
+ * @property {(sentence: string) => number} euiCount
+ * @property {(sentence: string) => number} longestNounRun
+ * @property {(sentence: string) => string[]} doublePassives
+ */
+
+/** @type {Analyzer} */
+export const surfaceAnalyzer = {
+  name: "surface",
+  sentences: splitSentences,
+  euiCount: tokenize.euiCount,
+  longestNounRun: tokenize.longestNounRun,
+  doublePassives: tokenize.doublePassives,
+};
+
+/** @param {string} name @returns {Analyzer} */
+export function makeAnalyzer(name) {
+  if (name === "surface") return surfaceAnalyzer;
+  if (name === "kiwi") {
+    throw new Error("kiwi 분석기는 파이썬 패키지에 있다 (pip install hanlint[kiwi]). npm 에서는 --analyzer surface 를 쓴다");
+  }
+  throw new Error(`모르는 분석기: ${name}. surface 를 쓴다`);
+}

package/src/analysis/surface/splitSentences.js

@@ -0,0 +1,36 @@
+// @ts-check
+/** 종결 부호 뒤 공백에서 문장을 나눈다. 파이썬 analysis/surface/splitSentences.py 와 같다. */
+
+const TERMINAL = /[.?!]+\s+(?=\S)/g;
+const ABBREVIATION = /(?:^|[^A-Za-z])[A-Za-z]$/;
+
+/**
+ * @typedef {object} Sentence
+ * @property {string} text
+ * @property {number} start 분석에 넣은 문자열 안의 시작 오프셋
+ * @property {number} end
+ */
+
+/** @param {string} text @returns {Sentence[]} */
+export function splitSentences(text) {
+  /** @type {Sentence[]} */
+  const sentences = [];
+  let start = 0;
+  for (const match of text.matchAll(TERMINAL)) {
+    const index = /** @type {number} */ (match.index);
+    const before = text.slice(0, index);
+    if (ABBREVIATION.test(before)) continue;
+    const end = index + match[0].trimEnd().length;
+    const segment = text.slice(start, end);
+    const piece = segment.trim();
+    if (piece) sentences.push({ text: piece, start: start + (segment.length - segment.trimStart().length), end });
+    start = index + match[0].length;
+  }
+  const rest = text.slice(start);
+  const tail = rest.trim();
+  if (tail) {
+    const lead = rest.length - rest.trimStart().length;
+    sentences.push({ text: tail, start: start + lead, end: start + lead + tail.length });
+  }
+  return sentences;
+}

package/src/analysis/surface/tokenize.js

@@ -0,0 +1,162 @@
+// @ts-check
+/**
+ * 어절 단위 근사. 조사와 어미 꼬리 사전으로 명사 어절을 가려낸다. 파이썬 analysis/surface/tokenize.py 와 같은 판정이다.
+ * 띄어 쓴 조사와 계사는 앞 어절에 붙은 것으로, 영문 어절 연속은 한 덩어리로, 수사와 바로 뒤 단위는 수량으로 본다.
+ */
+import { loadLines } from "../../data/load.js";
+import { splitWords, stripChars } from "../../text.js";
+
+const HANGUL = /[가-힣]/;
+const WORD_CHARS = /^[가-힣A-Za-z0-9]+$/;
+const GENITIVE = /([가-힣]+)의(?=[\s,.)\]]|$)/g;
+const SPACED_GENITIVE = /(?<=\s)의(?=\s)/g;
+const COPULA = /^(?:이(?:고|며|다|라|란|면|라서|므로|지만|어서|었다|었고)|인|인데|입니다|였다)$/;
+const DIGITS = /^\d+$/;
+const OPENERS = "([{\"“‘'";
+const CLOSERS = ",.?!;:)]}\"”’'";
+const EDGE_PUNCTUATION = ".,?!:;\"'“”‘’()[]{}<>";
+
+/**
+ * @typedef {object} Word
+ * @property {string} core 앞뒤 부호를 뗀 어절
+ * @property {boolean} endsClause 뒤에 쉼표, 종결 부호, 닫는 괄호가 붙어 있었는가
+ * @property {boolean} opens 앞에 여는 괄호나 따옴표가 있었는가
+ * @property {boolean} particle 띄어 쓴 조사나 계사인가
+ */
+
+/** @type {Map<string, string[]>} */
+const tailCache = new Map();
+
+/** 긴 것부터. @param {string} name */
+export function tails(name) {
+  let sorted = tailCache.get(name);
+  if (!sorted) {
+    sorted = [...loadLines(name)].sort((a, b) => b.length - a.length);
+    tailCache.set(name, sorted);
+  }
+  return sorted;
+}
+
+/** @type {Set<string> | null} */
+let josaCache = null;
+export function josaSet() {
+  if (!josaCache) josaCache = new Set(loadLines("josa.txt"));
+  return josaCache;
+}
+
+/** @type {Set<string> | null} */
+let euiNounCache = null;
+export function euiNouns() {
+  if (!euiNounCache) euiNounCache = new Set(loadLines("euiNouns.txt"));
+  return euiNounCache;
+}
+
+/** @type {Set<string> | null} */
+let numeralCache = null;
+export function numerals() {
+  if (!numeralCache) numeralCache = new Set(loadLines("koreanNumbers.txt").map((line) => line.split("\t")[0]));
+  return numeralCache;
+}
+
+/** @param {string} core */
+export function isNumeral(core) {
+  return numerals().has(core) || DIGITS.test(core);
+}
+
+/** @param {string} text @returns {Word[]} */
+export function words(text) {
+  return splitWords(text).map((raw) => {
+    const core = stripChars(raw, EDGE_PUNCTUATION);
+    const particle = josaSet().has(core) || COPULA.test(core);
+    return { core, endsClause: CLOSERS.includes(raw[raw.length - 1]), opens: OPENERS.includes(raw[0]), particle };
+  });
+}
+
+/** @param {string} core @param {string} name */
+export function tailOf(core, name) {
+  for (const tail of tails(name)) {
+    if (core.endsWith(tail) && core.length > tail.length) return tail;
+  }
+  return null;
+}
+
+/** @param {string} core */
+export function stripJosa(core) {
+  const tail = tailOf(core, "josa.txt");
+  return tail ? core.slice(0, -tail.length) : core;
+}
+
+/** 조사도 어미도 붙지 않은 한글, 영문, 숫자 어절인가. @param {string} core */
+export function isBareNoun(core) {
+  if (!core || !WORD_CHARS.test(core)) return false;
+  if (!HANGUL.test(core)) return true;
+  return tailOf(core, "josa.txt") === null && tailOf(core, "verbTails.txt") === null;
+}
+
+/** 명사 어절 연속의 최대 길이. @param {string} text */
+export function longestNounRun(text) {
+  let longest = 0;
+  let run = 0;
+  let previousAscii = false;
+  let afterNumeral = false;
+  for (const word of words(text)) {
+    if (word.opens) {
+      run = 0;
+      previousAscii = false;
+    }
+    const transparent = isNumeral(word.core) || afterNumeral;
+    afterNumeral = isNumeral(word.core);
+    if (word.particle || !isBareNoun(word.core)) {
+      run = 0;
+      previousAscii = false;
+    } else if (!transparent) {
+      const isAscii = !HANGUL.test(word.core);
+      if (!(isAscii && previousAscii)) run += 1;
+      previousAscii = isAscii;
+      longest = Math.max(longest, run);
+    }
+    if (word.endsClause) {
+      run = 0;
+      previousAscii = false;
+    }
+  }
+  return longest;
+}
+
+/** 관형격 조사 의 의 수. @param {string} text */
+export function euiCount(text) {
+  let attached = 0;
+  for (const match of text.matchAll(GENITIVE)) {
+    if (!euiNouns().has(`${match[1]}의`)) attached += 1;
+  }
+  return attached + [...text.matchAll(SPACED_GENITIVE)].length;
+}
+
+/** 초성과 중성이 정해진 한글 음절 28개의 정규식 범위. @param {number} initial @param {number} vowel */
+export function syllableRange(initial, vowel) {
+  const first = 0xac00 + (initial * 21 + vowel) * 28;
+  return `${String.fromCharCode(first)}-${String.fromCharCode(first + 27)}`;
+}
+
+const PASSIVE_TAIL = `[${syllableRange(12, 20)}${syllableRange(12, 6)}]`;
+
+/** @type {RegExp | null} */
+let passivePattern = null;
+export function doublePassivePattern() {
+  if (!passivePattern) {
+    const stems = ["되어"];
+    const contraction = { 이: "여", 히: "혀", 리: "려", 기: "겨" };
+    for (const stem of loadLines("passiveStems.txt")) {
+      const last = stem[stem.length - 1];
+      stems.push(last in contraction ? stem.slice(0, -1) + contraction[last] : `${stem}어`);
+    }
+    const alternatives = [...stems].sort((a, b) => b.length - a.length).join("|");
+    passivePattern = new RegExp(`(${alternatives})${PASSIVE_TAIL}`, "g");
+  }
+  return passivePattern;
+}
+
+/** 이중 피동의 표층형을 `되어지` 꼴로. @param {string} text */
+export function doublePassives(text) {
+  return [...text.matchAll(doublePassivePattern())].map((match) => `${match[1]}지`);
+}

package/src/cli/main.js

@@ -0,0 +1,376 @@
+// @ts-check
+/**
+ * 명령줄 진입점. 파이썬 CLI 와 같은 인자, 같은 출력, 같은 종료 코드다 (0 지적 없음, 1 error 있음, 2 파일이나 설정 문제).
+ *
+ * ```
+ * hanlint 글.md [다른.md ...]   검사. 서브커맨드 없이 파일만 주면 lint 다. `-` 는 stdin
+ * hanlint fix 글.md             기계가 고칠 수 있는 지적을 원문에 적용
+ * hanlint print 글.md           지문 계층 JSON
+ * hanlint rules                 규칙 목록
+ * hanlint explain <규칙>        규칙의 기술서
+ * hanlint init                  주석 달린 hanlint.toml
+ * ```
+ * audit, map, profile 과 kiwi 정밀 모드는 파이썬 패키지 (pip install hanlint) 에 있다.
+ */
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, isAbsolute, relative, resolve } from "node:path";
+
+import { analyzerFor, fingerprint, lintText, ruleDoc, ruleNames, ruleSummary, version } from "../index.js";
+import { loadConfig } from "../config/loadConfig.js";
+import { defaultConfig } from "../config/settings.js";
+import { applyFixes } from "../edit/applyFixes.js";
+import { runAll } from "../rules/registry.js";
+import { renderCompact } from "../report/compactReport.js";
+import { LAYERS, renderFingerprintJson } from "../report/fingerprintJson.js";
+import { renderGithub } from "../report/githubReport.js";
+import { renderJson } from "../report/jsonReport.js";
+import { renderText } from "../report/textReport.js";
+
+const COMMANDS = ["lint", "fix", "print", "rules", "explain", "init"];
+const PYTHON_ONLY = ["audit", "map", "profile", "coverage", "diff"];
+const FORMATS = ["text", "compact", "json", "github"];
+const SEVERITIES = ["all", "error", "notice"];
+const ANALYZER_CHOICES = ["surface", "kiwi"];
+const STDIN = "-";
+const STDIN_NAME = "<stdin>";
+const THRESHOLD_FIELDS = [
+  "fragmentRun",
+  "introMaxParagraphs",
+  "headingUniformRatio",
+  "nounPileMin",
+  "endingRun",
+  "factListMinSentences",
+  "factListMaxMeanLength",
+  "topicBreakMinSentences",
+  "longSentenceMax",
+  "duplicateBlockRatio",
+  "firstResultMaxParagraphs",
+  "sectionResultMinParagraphs",
+];
+const FLOAT_FIELDS = new Set(["headingUniformRatio", "factListMaxMeanLength"]);
+
+const USAGE = `사용법: hanlint 글.md [다른.md ...] [--format text|compact|json|github] [--severity all|error|notice] [--errors-only]
+                [--config 파일] [--disable 규칙] [--output 파일] [--quiet] [--path 이름 (stdin 의 이름)]
+        hanlint fix 글.md [--dry-run]
+        hanlint print 글.md [--layer all|sentences|paragraphs|sections|document]
+        hanlint rules [--names]
+        hanlint explain <규칙>
+        hanlint init [--path hanlint.toml] [--force]
+        hanlint --version
+
+한국어 글에서 반복되는 결함을 결정적으로 잡는다. 종료 코드는 0 (지적 없음), 1 (error 지적), 2 (파일이나 설정 문제).
+audit, map, profile 과 kiwi 정밀 모드는 파이썬 패키지 (pip install hanlint) 에 있다.`;
+
+/** @type {Record<string, "value" | "list" | "flag">} */
+const OPTION_KINDS = {
+  "--format": "value",
+  "--config": "value",
+  "--disable": "list",
+  "--analyzer": "value",
+  "--output": "value",
+  "--no-color": "flag",
+  "--quiet": "flag",
+  "--severity": "value",
+  "--errors-only": "flag",
+  "--path": "value",
+  "--layer": "value",
+  "--dry-run": "flag",
+  "--names": "flag",
+  "--force": "flag",
+};
+
+class UsageError extends Error {}
+
+/**
+ * @param {string[]} args
+ * @returns {{ options: Record<string, string | string[] | boolean>, positionals: string[] }}
+ */
+function parseArgs(args) {
+  /** @type {Record<string, string | string[] | boolean>} */
+  const options = {};
+  /** @type {string[]} */
+  const positionals = [];
+  for (let i = 0; i < args.length; i++) {
+    let arg = args[i];
+    if (!arg.startsWith("--")) {
+      positionals.push(arg);
+      continue;
+    }
+    let inlineValue = null;
+    const eq = arg.indexOf("=");
+    if (eq > 0) {
+      inlineValue = arg.slice(eq + 1);
+      arg = arg.slice(0, eq);
+    }
+    const kind = OPTION_KINDS[arg];
+    if (!kind) throw new UsageError(`모르는 옵션: ${arg}`);
+    if (kind === "flag") {
+      options[arg] = true;
+      continue;
+    }
+    const value = inlineValue ?? args[++i];
+    if (value === undefined) throw new UsageError(`${arg} 에 값이 없다`);
+    if (kind === "list") {
+      const list = /** @type {string[]} */ (options[arg] ?? []);
+      list.push(value);
+      options[arg] = list;
+    } else {
+      options[arg] = value;
+    }
+  }
+  return { options, positionals };
+}
+
+/** 서브커맨드 없이 파일이나 옵션만 주면 lint 로 본다. @param {string[]} argv */
+export function normalizeArgv(argv) {
+  if (!argv.length) return ["lint"];
+  if (COMMANDS.includes(argv[0]) || PYTHON_ONLY.includes(argv[0]) || ["-h", "--help", "--version"].includes(argv[0])) return argv;
+  return ["lint", ...argv];
+}
+
+/** @param {string} value @param {string[]} choices @param {string} option */
+function choose(value, choices, option) {
+  if (!choices.includes(value)) throw new UsageError(`${option} 는 ${choices.join(", ")} 가운데 하나다: ${value}`);
+  return value;
+}
+
+/** @param {string} text @param {string | undefined} output */
+function emit(text, output) {
+  if (output === undefined) {
+    process.stdout.write(`${text}\n`);
+    return;
+  }
+  writeFileSync(output, text.endsWith("\n") ? text : `${text}\n`, "utf-8");
+  process.stderr.write(`${output} 에 썼다\n`);
+}
+
+/** 설정을 찾기 시작할 폴더. 첫 실제 파일의 폴더, 전부 stdin 이면 현재 폴더. @param {string[]} paths */
+function startFolder(paths) {
+  for (const path of paths) if (path !== STDIN) return dirname(resolve(path));
+  return process.cwd();
+}
+
+/** @param {Record<string, string | string[] | boolean>} options @param {string[]} paths */
+function configFrom(options, paths) {
+  const config = loadConfig(/** @type {string | undefined} */ (options["--config"]) ?? null, startFolder(paths));
+  for (const rule of /** @type {string[]} */ (options["--disable"] ?? [])) config.disable.add(rule);
+  if (options["--analyzer"]) config.analyzer = choose(/** @type {string} */ (options["--analyzer"]), ANALYZER_CHOICES, "--analyzer");
+  return config;
+}
+
+/** 출력 첫 줄에 적을 설정 출처. 현재 폴더 아래면 상대 경로, 아니면 그대로. @param {import("../config/settings.js").Config} config */
+function configLabel(config) {
+  if (config.source === null) return "기본값";
+  const rel = relative(process.cwd(), config.source);
+  if (!rel || rel.startsWith("..") || isAbsolute(rel)) return config.source;
+  return rel;
+}
+
+/** @param {Map<string, import("../rules/finding.js").Finding[]>} results */
+function summary(results) {
+  let errors = 0;
+  let notices = 0;
+  for (const findings of results.values()) {
+    for (const f of findings) {
+      if (f.severity === "error") errors += 1;
+      else if (f.severity === "notice") notices += 1;
+    }
+  }
+  return `파일 ${results.size}개, error ${errors}, notice ${notices}`;
+}
+
+/** (이름, 본문). `-` 면 stdin 을 UTF-8 로 읽는다. @param {string} path @param {string} stdinName @returns {[string, string]} */
+function readInput(path, stdinName) {
+  if (path === STDIN) return [stdinName, readFileSync(0, "utf-8")];
+  return [path, readFileSync(path, "utf-8")];
+}
+
+/** @param {string[]} args */
+function runLint(args) {
+  const { options, positionals } = parseArgs(args);
+  if (!positionals.length) throw new UsageError("검사할 마크다운 파일이 필요하다");
+  const format = choose(/** @type {string} */ (options["--format"] ?? "text"), FORMATS, "--format");
+  const severity = options["--errors-only"] ? "error" : choose(/** @type {string} */ (options["--severity"] ?? "all"), SEVERITIES, "--severity");
+  const config = configFrom(options, positionals);
+  analyzerFor(config);
+  const stdinName = /** @type {string} */ (options["--path"] ?? STDIN_NAME);
+  /** @type {Map<string, import("../rules/finding.js").Finding[]>} */
+  const results = new Map();
+  for (const path of positionals) {
+    const [name, text] = readInput(path, stdinName);
+    results.set(name, lintText(text, config, name));
+  }
+  const hasError = [...results.values()].some((findings) => findings.some((f) => f.severity === "error"));
+  /** @type {Map<string, import("../rules/finding.js").Finding[]>} */
+  const shown = new Map();
+  for (const [name, findings] of results) shown.set(name, severity === "all" ? findings : findings.filter((f) => f.severity === severity));
+
+  const output = /** @type {string | undefined} */ (options["--output"]);
+  if (format === "json") {
+    emit(renderJson(shown, configLabel(config)), output);
+  } else if (format === "github") {
+    emit([...shown].map(([name, findings]) => renderGithub(name, findings)).join("\n"), output);
+  } else {
+    const parts = [];
+    if (!options["--quiet"]) parts.push(`설정: ${configLabel(config)}`);
+    if (format === "compact") {
+      const body = [...shown]
+        .filter(([, findings]) => findings.length)
+        .map(([name, findings]) => renderCompact(name, findings))
+        .join("\n");
+      if (body) parts.push(body);
+      parts.push(summary(shown));
+      emit(parts.join("\n"), output);
+    } else {
+      parts.push([...shown].map(([name, findings]) => renderText(name, findings)).join("\n\n"));
+      if (shown.size > 1) parts.push(summary(shown));
+      emit(parts.join("\n\n"), output);
+    }
+  }
+  return hasError ? 1 : 0;
+}
+
+/** @param {string[]} args */
+function runFix(args) {
+  const { options, positionals } = parseArgs(args);
+  if (!positionals.length) throw new UsageError("고칠 마크다운 파일이 필요하다");
+  const config = configFrom(options, positionals);
+  const analyzer = analyzerFor(config);
+  void analyzer;
+  const lines = [];
+  for (const path of positionals) {
+    const text = readFileSync(path, "utf-8");
+    // notice 는 제안이라 손으로 정한다. 확정된 error 만 원문에 넣는다.
+    const result = applyFixes(
+      text,
+      runAll(fingerprint(text, config, path), config).filter((f) => f.severity === "error"),
+    );
+    for (const [line, fragment, replacement] of result.applied) lines.push(`${path}:${line}  ${fragment} → ${replacement}`);
+    for (const [line, fragment, reason] of result.skipped) lines.push(`${path}:${line}  건너뜀 ${fragment}: ${reason}`);
+    if (result.text !== text && !options["--dry-run"]) writeFileSync(path, result.text, "utf-8");
+    lines.push(`${path}  ${result.applied.length}곳 고침, ${result.skipped.length}곳 건너뜀` + (options["--dry-run"] ? " (미리보기, 파일은 그대로)" : ""));
+  }
+  process.stdout.write(`${lines.join("\n")}\n`);
+  return 0;
+}
+
+/** @param {string[]} args */
+function runPrint(args) {
+  const { options, positionals } = parseArgs(args);
+  if (positionals.length !== 1) throw new UsageError("마크다운 파일 하나가 필요하다. `-` 는 stdin");
+  const layer = choose(/** @type {string} */ (options["--layer"] ?? "all"), LAYERS, "--layer");
+  const config = configFrom(options, positionals);
+  const [name, text] = readInput(positionals[0], /** @type {string} */ (options["--path"] ?? STDIN_NAME));
+  emit(renderFingerprintJson(fingerprint(text, config, name), layer), /** @type {string | undefined} */ (options["--output"]));
+  return 0;
+}
+
+/** @param {string[]} args */
+function runRules(args) {
+  const { options } = parseArgs(args);
+  const names = ruleNames();
+  if (options["--names"]) {
+    process.stdout.write(`${names.join("\n")}\n`);
+    return 0;
+  }
+  const width = Math.max(...names.map((name) => name.length));
+  const lines = names.map((name) => `${name.padEnd(width)}  ${ruleSummary(name)}`);
+  process.stdout.write(`${lines.join("\n")}\n\n규칙 ${names.length}개. 자세히 보려면 hanlint explain <규칙>\n`);
+  return 0;
+}
+
+/** @param {string[]} args */
+function runExplain(args) {
+  const { positionals } = parseArgs(args);
+  if (positionals.length !== 1) throw new UsageError("규칙 이름 하나가 필요하다. hanlint rules 로 목록을 본다");
+  const doc = ruleDoc(positionals[0]);
+  process.stdout.write(`${positionals[0]}\n\n${doc}\n`);
+  return 0;
+}
+
+/** 주석 달린 hanlint.toml. 파이썬 `hanlint init` 과 같은 글자다. */
+export function renderInit() {
+  const defaults = defaultConfig();
+  const lines = ["# hanlint 설정. 규칙을 끄려면 disable 에 이름을 넣는다. 규칙의 기술서는 hanlint explain <규칙>.", "", "# 규칙 목록과 한 줄 설명"];
+  for (const name of ruleNames()) lines.push(`#   ${name}: ${ruleSummary(name)}`);
+  lines.push(
+    "",
+    "disable = []",
+    "",
+    "# surface 는 의존성 0 기본, kiwi 는 pip install hanlint[kiwi] 가 있을 때",
+    `analyzer = "${defaults.analyzer}"`,
+    "",
+    "# 대표 검색어를 읽을 frontmatter 필드. 없으면 keywordMissing 은 돌지 않는다",
+    '# keywordField = "primaryKeyword"',
+    "",
+    "# hanlint profile build 가 만든 파일. 있으면 참조 글과의 편차 구간을 notice 로 더한다",
+    '# profile = "profile.json"',
+    "",
+    "# 임계. 기본값의 정본은 hanlint 의 config/settings.py 다",
+  );
+  for (const name of THRESHOLD_FIELDS) {
+    const value = /** @type {number} */ (defaults[name]);
+    const shown = FLOAT_FIELDS.has(name) && Number.isInteger(value) ? value.toFixed(1) : String(value);
+    lines.push(`# ${name} = ${shown}`);
+  }
+  lines.push(
+    "",
+    "# 사전에 더할 항목. 키는 cliches, translationese, redundantPair, japaneseLoan",
+    "# [dictionary]",
+    '# cliches = ["우리의 여정"]',
+    '# translationese = [{ pattern = "에 대한 이해", fix = "를 아는 것" }]',
+    "",
+  );
+  return lines.join("\n");
+}
+
+/** @param {string[]} args */
+function runInit(args) {
+  const { options } = parseArgs(args);
+  const path = /** @type {string} */ (options["--path"] ?? "hanlint.toml");
+  if (existsSync(path) && !options["--force"]) throw new Error(`${path} 가 이미 있다. 덮어쓰려면 --force`);
+  writeFileSync(path, renderInit(), "utf-8");
+  process.stdout.write(`${path} 를 만들었다. 규칙을 끄려면 disable 에 이름을 넣는다\n`);
+  return 0;
+}
+
+/** @param {string[]} argv */
+function dispatch(argv) {
+  const [command, ...rest] = normalizeArgv(argv);
+  if (command === "-h" || command === "--help") {
+    process.stdout.write(`${USAGE}\n`);
+    return 0;
+  }
+  if (command === "--version") {
+    process.stdout.write(`hanlint ${version}\n`);
+    return 0;
+  }
+  if (PYTHON_ONLY.includes(command)) {
+    throw new Error(`${command} 는 파이썬 패키지에 있다 (pip install hanlint). npm 은 lint, fix, print, rules, explain, init 을 제공한다`);
+  }
+  if (command === "lint") return runLint(rest);
+  if (command === "fix") return runFix(rest);
+  if (command === "print") return runPrint(rest);
+  if (command === "rules") return runRules(rest);
+  if (command === "explain") return runExplain(rest);
+  return runInit(rest);
+}
+
+/** @param {string[]} argv @returns {number} */
+export function main(argv) {
+  try {
+    return dispatch(argv);
+  } catch (error) {
+    if (error instanceof UsageError) {
+      process.stderr.write(`${error.message}\n\n${USAGE}\n`);
+      return 2;
+    }
+    const failure = /** @type {NodeJS.ErrnoException} */ (error);
+    if (failure.code === "ENOENT") {
+      process.stderr.write(`${failure.path} 를 찾지 못했다. 경로를 확인하거나 hanlint --help\n`);
+      return 2;
+    }
+    process.stderr.write(`${failure.message}\n`);
+    return 2;
+  }
+}

package/src/config/loadConfig.js

@@ -0,0 +1,51 @@
+// @ts-check
+/** 설정 파일을 찾아 읽는다. `hanlint.toml` 이거나 `pyproject.toml` 의 `[tool.hanlint]` 다. 파이썬과 같은 탐색이다. */
+import { existsSync, readFileSync } from "node:fs";
+import { basename, dirname, join, resolve } from "node:path";
+
+import { configFromMapping, defaultConfig } from "./settings.js";
+import { parseToml } from "./toml.js";
+
+export const CONFIG_NAME = "hanlint.toml";
+export const PYPROJECT_NAME = "pyproject.toml";
+
+/** @param {string} path */
+export function readConfigFile(path) {
+  let data = parseToml(readFileSync(path, "utf-8"));
+  if (basename(path) === PYPROJECT_NAME) {
+    const tool = /** @type {Record<string, unknown>} */ (data.tool ?? {});
+    data = /** @type {Record<string, unknown>} */ (tool.hanlint ?? {});
+  }
+  const config = configFromMapping(data);
+  config.source = path;
+  return config;
+}
+
+/** start 에서 위로 올라가며 hanlint.toml 이나 [tool.hanlint] 를 가진 pyproject.toml 을 찾는다. @param {string} start */
+export function findConfigFile(start) {
+  let folder = resolve(start);
+  while (true) {
+    const candidate = join(folder, CONFIG_NAME);
+    if (existsSync(candidate)) return candidate;
+    const pyproject = join(folder, PYPROJECT_NAME);
+    if (existsSync(pyproject)) {
+      const data = parseToml(readFileSync(pyproject, "utf-8"));
+      const tool = /** @type {Record<string, unknown>} */ (data.tool ?? {});
+      if ("hanlint" in tool) return pyproject;
+    }
+    const parent = dirname(folder);
+    if (parent === folder) return null;
+    folder = parent;
+  }
+}
+
+/**
+ * `path` 를 주면 그 파일만 읽는다. 안 주면 `start` (기본 현재 폴더) 에서 찾고, 없으면 기본값이다.
+ * @param {string | null} [path]
+ * @param {string | null} [start]
+ */
+export function loadConfig(path = null, start = null) {
+  if (path) return readConfigFile(path);
+  const found = findConfigFile(start ?? process.cwd());
+  return found ? readConfigFile(found) : defaultConfig();
+}