hanlint 0.0.8 → 0.0.10

package/src/cli/main.js

@@ -10,35 +10,54 @@
  * hanlint rules                 규칙 목록을 부류로 묶어서
  * hanlint explain <규칙>        규칙의 기술서
  * hanlint patterns             문장 틀. --rule 로 그 규칙을 피하는 것만
+ * hanlint primer --preset <종류> 쓰기 전에 읽는 한 장. 켜진 규칙의 고치는 법과 본보기 전후
+ * hanlint hook                  Claude Code가 쓴 마크다운을 같은 턴에 비차단 검사
  * hanlint baseline 글들/        지금 있는 지적을 잠근다. 그다음부터 새것만 막힌다
  * hanlint baseline 글들/        지금 있는 지적을 잠근다. 그다음부터 새것만 막힌다
  * hanlint doctor                설정과 꺼진 규칙
  * hanlint init                  주석 달린 hanlint.toml. --output 과 --preset blog|report|docs
+ * hanlint contract init 글.md   원문에서 최소 Reader Contract 초안
  * ```
  * audit, guard, arena, blueprint, evidence, entailment 같은 확장 명령은 파이썬 패키지에 있다.
  */
 import { existsSync, readdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
-import { dirname, isAbsolute, join, relative, resolve } from "node:path";
+import { dirname, extname, isAbsolute, join, relative, resolve, sep } from "node:path";
 
-import { fingerprint, lintText, ruleDoc, ruleNames, ruleSummary, version } from "../index.js";
+import {
+  Patch,
+  check,
+  contractFromText,
+  contractFromTextV2,
+  fingerprint,
+  lintText,
+  parseContract,
+  renderCheck,
+  ruleDoc,
+  ruleNames,
+  ruleSummary,
+  verifyPatch,
+  version,
+} from "../index.js";
 import { Baseline, build as buildBaseline, DEFAULT_NAME as DEFAULT_BASELINE, load as loadBaseline, prune as pruneBaseline, render as renderBaseline } from "../baseline/store.js";
 import { loadConfig } from "../config/loadConfig.js";
-import { DEFAULT_PRESET, defaultConfig, offRules, PRESET_NAMES, PRESETS } from "../config/settings.js";
+import { defaultConfig, offRules, PRESET_NAMES, PRESETS } from "../config/settings.js";
 import { applyFixes } from "../edit/applyFixes.js";
 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, ruleMechanism, runAll } from "../rules/registry.js";
+import { CATEGORY_TITLES, MECHANISMS, ruleCategory, ruleFix, ruleMechanism, runAll } from "../rules/registry.js";
 import { MARKDOWN, SKIPPED_FOLDERS, markdownUnder } from "./walk.js";
 import { welcome } from "./welcome.js";
+import { rootHelp } from "./help.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";
+import { renderWritingSpec, writingSpec } from "../report/writingSpec.js";
 import { exemplarInRegister, patternInRegister } from "../report/registerMatch.js";
 
-const COMMANDS = ["lint", "fix", "print", "rules", "explain", "patterns", "baseline", "doctor", "init"];
+const COMMANDS = ["lint", "fix", "print", "rules", "explain", "patterns", "primer", "spec", "hook", "baseline", "doctor", "init", "contract", "check", "verify-patch"];
 const PYTHON_ONLY = [
   "audit",
   "map",
@@ -72,35 +91,17 @@ const THRESHOLD_FIELDS = [
   "endingRun",
   "factListMinSentences",
   "factListMaxMeanLength",
-  "topicBreakMinSentences",
+  "flowValleyMinSentences",
   "longSentenceMax",
   "duplicateBlockRatio",
   "firstResultMaxParagraphs",
-  "sectionResultMinParagraphs",
   "introMaxImages",
-  "headingQuestionRatio",
   "moreLaterMaxChars",
   "tableOddCellMinRows",
 ];
-const FLOAT_FIELDS = new Set(["headingUniformRatio", "factListMaxMeanLength", "headingQuestionRatio"]);
-
-const USAGE = `사용법: hanlint 글.md [다른.md ...] [--format text|compact|json|github] [--severity all|error|notice] [--errors-only]
-                [--config 파일] [--preset blog|report|docs] [--disable 규칙] [--baseline [파일]] [--output 파일] [--quiet]
-                [--path 이름 (stdin 의 이름)]
-        hanlint fix 글.md [--dry-run]
-        hanlint print 글.md [--layer all|sentences|paragraphs|sections|document]
-        hanlint rules [--names]
-        hanlint explain <규칙>
-        hanlint patterns [--rule 규칙]
-        hanlint baseline 글들/ [--prune] [--output 파일]
-        hanlint doctor
-        hanlint init [--output hanlint.toml] [--preset blog|report|docs] [--force]
-        hanlint --version
-
-파일 자리에 폴더를 주면 그 아래 마크다운을 전부 검사한다 (점으로 시작하는 폴더와 node_modules 는 건너뛴다).
-인자가 없으면 첫 화면이 나온다.
-한국어 글에서 반복되는 결함을 결정적으로 잡는다. 종료 코드는 0 (지적 없음), 1 (error 지적), 2 (파일이나 설정 문제).
-${PYTHON_ONLY.join(", ")} 는 파이썬 패키지 (pip install hanlint) 에 있다.`;
+const FLOAT_FIELDS = new Set(["headingUniformRatio", "factListMaxMeanLength"]);
+
+const USAGE = rootHelp();
 
 /** @type {Record<string, "value" | "list" | "flag">} */
 const OPTION_KINDS = {
@@ -118,9 +119,15 @@ const OPTION_KINDS = {
   "--dry-run": "flag",
   "--names": "flag",
   "--force": "flag",
+  "--reply": "flag",
+  "--reader": "value",
+  "--goal": "value",
+  "--outline": "value",
+  "--fact": "list",
   "--preset": "value",
   "--rule": "value",
   "--register": "value",
+  "--chars": "value",
   "--baseline": "optional",
   "--prune": "flag",
 };
@@ -226,8 +233,8 @@ function checkDisabled(config) {
 }
 
 /** @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));
+function configFrom(options, paths, start = null) {
+  const config = loadConfig(/** @type {string | undefined} */ (options["--config"]) ?? null, start ?? startFolder(paths));
   if (options["--preset"]) config.preset = choose(/** @type {string} */ (options["--preset"]), PRESET_NAMES, "--preset");
   for (const rule of /** @type {string[]} */ (options["--disable"] ?? [])) config.disable.add(rule);
   if (options["--profile"]) config.profile = /** @type {string} */ (options["--profile"]);
@@ -239,15 +246,15 @@ function configFrom(options, paths) {
 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;
+  // 경로 구분자는 언제나 /. 설정이 작업 폴더 밖일 때 두 판의 첫 줄이 갈렸다. 파이썬과 같다.
+  const label = !rel || rel.startsWith("..") || isAbsolute(rel) ? config.source : rel;
+  return label.split(sep).join("/");
 }
 
-/** 설정 출처와 지금 도는 프리셋. 기본 프리셋이면 이름을 빼서 줄이 길어지지 않게 한다.
- * @param {import("../config/settings.js").Config} config */
+/** 설정 출처와 지금 도는 프리셋. @param {import("../config/settings.js").Config} config */
 function header(config) {
   const where = configLabel(config);
-  return config.preset === DEFAULT_PRESET ? `설정: ${where}` : `설정: ${where}, 프리셋 ${config.preset}`;
+  return `설정: ${where}, 프리셋 ${config.preset}`;
 }
 
 /** @param {Map<string, import("../rules/finding.js").Finding[]>} results */
@@ -383,6 +390,73 @@ function runBaseline(args) {
   return 0;
 }
 
+/** @param {string} path */
+function readJson(path) {
+  try {
+    return JSON.parse(readFileSync(path, "utf-8"));
+  } catch (error) {
+    if (error instanceof SyntaxError) throw new Error(`${path} JSON을 읽지 못했다: ${error.message}`);
+    throw error;
+  }
+}
+
+/** @param {string[]} args */
+function runCheck(args) {
+  const { options, positionals } = parseArgs(args);
+  if (positionals.length !== 2) throw new UsageError("Reader Contract JSON과 검사할 마크다운 파일이 필요하다");
+  const format = choose(/** @type {string} */ (options["--format"] ?? "json"), ["json", "text"], "--format");
+  const [contractPath, path] = positionals;
+  const contract = parseContract(readJson(contractPath));
+  const config = configFrom(options, [path]);
+  const result = check(readOne(path), contract, config, path);
+  const rendered = format === "text" ? renderCheck(result) : JSON.stringify(result.asDict(), null, 2);
+  emit(rendered, /** @type {string | undefined} */ (options["--output"]));
+  return result.violationCount === 0 ? 0 : 1;
+}
+
+/** @param {string[]} args */
+function runContract(args) {
+  const { options, positionals } = parseArgs(args);
+  if (positionals.length !== 2 || positionals[0] !== "init") {
+    throw new UsageError("contract init과 계약 초안을 만들 마크다운 파일이 필요하다");
+  }
+  const reader = options["--reader"];
+  const goal = options["--goal"];
+  if (typeof reader !== "string" || typeof goal !== "string") {
+    throw new UsageError("contract init에는 --reader와 --goal이 필요하다");
+  }
+  const output = options["--output"];
+  if (typeof output === "string" && existsSync(output) && !options["--force"]) {
+    throw new Error(`${output} 가 이미 있다. 덮어쓰려면 --force`);
+  }
+  const outline = options["--outline"];
+  const facts = /** @type {string[]} */ (options["--fact"] ?? []);
+  let contract;
+  if (outline !== undefined) {
+    const selected = choose(/** @type {string} */ (outline), ["h1", "h2", "h3", "h4", "h5", "h6"], "--outline");
+    contract = contractFromTextV2(readOne(positionals[1]), reader, goal, Number(selected.slice(1)), facts);
+  } else {
+    if (facts.length) throw new UsageError("--fact는 --outline과 함께 version 2 계약에서 쓴다");
+    contract = contractFromText(readOne(positionals[1]), reader, goal);
+  }
+  emit(JSON.stringify(contract.asDict(), null, 2), typeof output === "string" ? output : undefined);
+  return 0;
+}
+
+/** @param {string[]} args */
+function runVerifyPatch(args) {
+  const { options, positionals } = parseArgs(args);
+  if (positionals.length !== 3) throw new UsageError("Reader Contract JSON, 수정 전 마크다운, Patch JSON이 필요하다");
+  choose(/** @type {string} */ (options["--format"] ?? "json"), ["json"], "--format");
+  const [contractPath, path, patchPath] = positionals;
+  const contract = parseContract(readJson(contractPath));
+  const patch = Patch.fromMapping(readJson(patchPath));
+  const config = configFrom(options, [path]);
+  const result = verifyPatch(readOne(path), patch, contract, config, path);
+  emit(JSON.stringify(result.asDict(), null, 2), /** @type {string | undefined} */ (options["--output"]));
+  return result.verified ? 0 : 1;
+}
+
 /** @param {string[]} args */
 function runLint(args) {
   const { options, positionals } = parseArgs(args);
@@ -515,7 +589,8 @@ function runRules(args) {
   }
   const config = configFrom(options, []);
   const off = new Set(offRules(config));
-  if (options["--format"] === "json") {
+  const format = choose(/** @type {string} */ (options["--format"] ?? "text"), ["text", "json"], "--format");
+  if (format === "json") {
     const rules = names.map((name) => {
       const exemplar = exemplarFor(name, config.preset, config.exemplars);
       /** @type {Record<string, unknown>} */
@@ -647,6 +722,136 @@ function runPatterns(args) {
   return 0;
 }
 
+/** 여러 줄을 한 줄로. 줄바꿈은 ¶ 다. 파이썬 cli/commands/primer.py 의 flat 과 같다. @param {string} text */
+function flat(text) {
+  return text
+    .split("\n")
+    .map((line) => line.trim().split(/\s+/).filter(Boolean).join(" "))
+    .filter(Boolean)
+    .join(" ¶ ");
+}
+
+/**
+ * 설정에서 켜진 규칙마다 항목 하나. 부류 순서, 그 안은 이름 순서. 파이썬 primerEntries 와 같다.
+ * @param {import("../config/settings.js").Config} config @param {string} register
+ */
+function primerEntries(config, register) {
+  const off = new Set(offRules(config));
+  const entries = [];
+  for (const category of Object.keys(CATEGORY_TITLES)) {
+    for (const name of ruleNames()) {
+      if (ruleCategory(name) !== category || off.has(name)) continue;
+      const exemplar = exemplarFor(name, config.preset, config.exemplars);
+      if (!exemplar) throw new Error(`본보기가 없는 규칙: ${name}`);
+      const shown = exemplarInRegister(exemplar, register);
+      entries.push({ rule: name, category, fix: ruleFix(name), before: shown.before, after: shown.after });
+    }
+  }
+  return entries;
+}
+
+/** 사람과 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}개. 줄마다 규칙 이름, 고치는 법, 전 (그 규칙에 잡히는 글), 후 (같은 뜻으로 통과하는 글) 순서다. 본보기의 줄바꿈은 ¶ 다`,
+  ];
+  for (const [category, title] of Object.entries(CATEGORY_TITLES)) {
+    const inside = entries.filter((entry) => entry.category === category);
+    if (!inside.length) continue;
+    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 <규칙>");
+  return lines.join("\n");
+}
+
+/** @param {string[]} args */
+function runPrimer(args) {
+  const { options } = parseArgs(args);
+  const config = configFrom(options, []);
+  const register = choose(/** @type {string} */ (options["--register"] ?? HAPNIDA), REGISTERS, "--register");
+  const entries = primerEntries(config, register);
+  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);
+    return 0;
+  }
+  emit(renderPrimer(entries, config.preset, register), output);
+  return 0;
+}
+
+/** @param {string[]} args */
+function runSpec(args) {
+  const { options } = parseArgs(args);
+  const config = configFrom(options, []);
+  const register = choose(/** @type {string} */ (options["--register"] ?? HAPNIDA), REGISTERS, "--register");
+  let targetChars = null;
+  if (options["--chars"] !== undefined) {
+    const raw = /** @type {string} */ (options["--chars"]);
+    targetChars = Number(raw);
+    if (!Number.isInteger(targetChars) || targetChars <= 0) throw new UsageError(`--chars 는 1 이상의 정수다: ${raw}`);
+  }
+  const result = writingSpec(config, register, targetChars);
+  const output = /** @type {string | undefined} */ (options["--output"]);
+  const format = choose(/** @type {string} */ (options["--format"] ?? "text"), ["text", "json"], "--format");
+  emit(format === "json" ? JSON.stringify(result, null, 2) : renderWritingSpec(result), output);
+  return 0;
+}
+
+/** Claude Code가 다음 모델 요청에 넣는 비차단 Finding 문맥. */
+function hookContext(eventName, name, findings) {
+  const where = eventName === "Stop" ? "마지막 답변" : "방금 쓴 마크다운";
+  return JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: eventName,
+      additionalContext: `hanlint가 ${where}에서 센 Finding입니다.\n${renderCompact(name, findings)}`,
+    },
+  });
+}
+
+/** 명령 훅 JSON을 stdin에서 읽어 저장 파일이나 마지막 답변을 검사한다. 언제나 종료 코드 0이다. @param {string[]} args */
+function runHook(args) {
+  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;
+    if (options["--reply"]) {
+      if (payload.hook_event_name !== "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);
+    } 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);
+    }
+    if (findings.length) process.stdout.write(`${hookContext(eventName, name, findings)}\n`);
+  } catch {
+    return 0;
+  }
+  return 0;
+}
+
 /** 잠근 지적이 몇 건인지. baseline 이 빚을 감추는 자리가 되지 않게 늘 보인다. @param {import("../config/settings.js").Config} config */
 function baselineState(config) {
   if (!config.baseline) return "없다 (hanlint baseline 글들/ 로 지금 지적을 잠근다)";
@@ -731,6 +936,7 @@ export function renderInit(preset = "blog") {
     "",
     "# 표면 치환이 바꾸면 안 되는 한국어 고유명사와 프로젝트 용어. 수치와 라틴 식별자는 자동으로 보호한다",
     '# protectedTerms = ["한린트", "김민지"]',
+    '# enforceStyle = ["noQuestion", "nounPile"]  # 선택한 문체 신호만 error로 강제한다',
     "",
     "# 사람이 승인한 프로젝트 본보기. 같은 규칙과 프리셋의 내장 본보기를 덮어쓴다",
     "# [[exemplars]]",
@@ -794,11 +1000,17 @@ function dispatch(argv) {
     throw new Error(`${command} 는 파이썬 패키지에 있다 (pip install hanlint). npm 은 ${COMMANDS.join(", ")} 을 제공한다`);
   }
   if (command === "lint") return runLint(rest);
+  if (command === "contract") return runContract(rest);
+  if (command === "check") return runCheck(rest);
+  if (command === "verify-patch") return runVerifyPatch(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);
   if (command === "patterns") return runPatterns(rest);
+  if (command === "primer") return runPrimer(rest);
+  if (command === "spec") return runSpec(rest);
+  if (command === "hook") return runHook(rest);
   if (command === "baseline") return runBaseline(rest);
   if (command === "doctor") return runDoctor(rest);
   return runInit(rest);

package/src/config/patch.js

@@ -0,0 +1,48 @@
+// @ts-check
+/** 이유가 붙은 정확 국소 Patch 입력 계약. */
+import { createHash } from "node:crypto";
+
+/** @param {unknown} value @param {string} where */
+function checkedString(value, where) {
+  if (typeof value !== "string" || !value || value !== value.trim()) {
+    throw new Error(`${where} 는 양끝 공백 없는 문자열이다`);
+  }
+  if (value !== value.normalize("NFC")) throw new Error(`${where} 는 NFC 문자열이어야 한다`);
+  return value;
+}
+
+export class Patch {
+  /** @param {string} reason @param {string} before @param {string} after */
+  constructor(reason, before, after) {
+    this.reason = checkedString(reason, "reason");
+    this.before = checkedString(before, "before");
+    this.after = checkedString(after, "after");
+    if (this.before === this.after) throw new Error("patch before 와 after 는 달라야 한다");
+    Object.freeze(this);
+  }
+
+  /** @param {unknown} raw */
+  static fromMapping(raw) {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw)) throw new Error("patch 는 JSON 객체다");
+    const data = /** @type {Record<string, unknown>} */ (raw);
+    const expected = ["reason", "before", "after"];
+    const unknown = Object.keys(data).filter((key) => !expected.includes(key)).sort();
+    const missing = expected.filter((key) => !(key in data)).sort();
+    if (unknown.length) throw new Error(`patch 의 모르는 키: ${unknown.join(", ")}`);
+    if (missing.length) throw new Error(`patch 의 빠진 키: ${missing.join(", ")}`);
+    return new Patch(
+      /** @type {string} */ (data.reason),
+      /** @type {string} */ (data.before),
+      /** @type {string} */ (data.after),
+    );
+  }
+
+  get digest() {
+    const encoded = JSON.stringify({ after: this.after, before: this.before, reason: this.reason });
+    return createHash("sha256").update(encoded, "utf8").digest("hex");
+  }
+
+  asDict() {
+    return { reason: this.reason, before: this.before, after: this.after };
+  }
+}