hanlint 0.0.7 → 0.0.8

package/src/cli/walk.js

@@ -0,0 +1,30 @@
+// @ts-check
+/**
+ * 폴더에서 검사할 마크다운을 찾는 규칙. 첫 화면과 검사가 **같은 함수**를 쓴다.
+ * 무엇을 건너뛰고 왜 그러는지는 파이썬 `cli/commands/shared.py` 의 SKIPPED_FOLDERS 가 소유한다.
+ */
+import { readdirSync, statSync } from "node:fs";
+import { join } from "node:path";
+
+/** 폴더를 주면 이 확장자만 찾는다. */
+export const MARKDOWN = [".md", ".markdown"];
+/** 폴더를 훑을 때 안 들어가는 이름. 점으로 시작하는 폴더도 함께 건너뛴다. */
+export const SKIPPED_FOLDERS = ["node_modules"];
+
+/** @param {string} name */
+export function isSkipped(name) {
+  return name.startsWith(".") || SKIPPED_FOLDERS.includes(name);
+}
+
+/** 폴더 아래 마크다운. 건너뛸 폴더에는 안 들어간다. 경로 문자열 순이라 두 판이 같은 차례를 낸다. @param {string} folder */
+export function markdownUnder(folder) {
+  /** @type {string[]} */
+  const found = [];
+  for (const name of [...readdirSync(folder)].sort()) {
+    const path = join(folder, name);
+    if (statSync(path).isDirectory()) {
+      if (!isSkipped(name)) found.push(...markdownUnder(path));
+    } else if (MARKDOWN.includes(name.slice(name.lastIndexOf(".")).toLowerCase())) found.push(path);
+  }
+  return found.sort();
+}

package/src/cli/welcome.js

@@ -0,0 +1,52 @@
+// @ts-check
+/**
+ * `hanlint` 를 인자 없이 쳤을 때의 첫 화면. 파이썬 cli/welcome.py 와 같은 글자다.
+ * 같은 폴더에서 두 판을 돌리면 결과가 같다. 파일을 찾는 것은 검사와 같은 함수 (walk.markdownUnder) 다.
+ */
+import { relative, sep } from "node:path";
+
+import { markdownUnder } from "./walk.js";
+
+/** 현재 폴더에서 예시로 보일 파일 수. 넷을 넘으면 목록이 안내를 밀어낸다. */
+const SAMPLE_LIMIT = 3;
+
+/** 이 폴더에서 검사가 실제로 볼 마크다운. 폴더 기준 상대 경로라 그대로 복사해 칠 수 있다. @param {string} folder */
+export function nearbyMarkdown(folder) {
+  try {
+    return markdownUnder(folder)
+      .slice(0, SAMPLE_LIMIT)
+      .map((path) => relative(folder, path).split(sep).join("/"));
+  } catch {
+    return [];
+  }
+}
+
+/** @param {string} version @param {string} [folder] */
+export function welcome(version, folder) {
+  const where = folder ?? process.cwd();
+  const nearby = nearbyMarkdown(where);
+  const example = nearby.length ? nearby[0] : "글.md";
+  const shown = [
+    [`hanlint ${example}`, "검사한다. 자리와 이유와 고칠 말이 나온다"],
+    [`hanlint fix ${example}`, "기계가 확실히 고칠 수 있는 자리를 원문에 적용한다"],
+    [`hanlint audit ${example}`, "글의 모양을 지도와 분포로 본다"],
+  ];
+  const width = Math.max(...shown.map(([command]) => command.length));
+  const lines = [
+    `hanlint ${version}  한국어 글에서 세면 확정되는 결함을 집는다. 좋은 글인지는 판정하지 않는다`,
+    "",
+    ...shown.map(([command, why]) => `  ${command.padEnd(width)}  ${why}`),
+  ];
+  if (nearby.length) {
+    lines.push("", `이 폴더의 마크다운: ${nearby.join(", ")}. 폴더를 통째로 줘도 된다 (hanlint .)`);
+  } else {
+    lines.push("", "이 폴더에는 검사할 마크다운이 없다. 파일 하나나 폴더 하나를 인자로 준다");
+  }
+  lines.push(
+    "",
+    "처음이면 hanlint init 으로 설정을 만든다. 글의 종류가 블로그가 아니면 --preset report 나 --preset docs",
+    "규칙 목록은 hanlint rules, 규칙 하나가 왜 있는지는 hanlint explain <규칙>, 지금 상태는 hanlint doctor",
+    "전체 사용법은 hanlint --help",
+  );
+  return lines.join("\n");
+}

package/src/config/settings.js

@@ -4,19 +4,71 @@
  * 기본값을 바꾸면 양쪽을 같은 작업에서 바꾼다. tests/parity 가 두 구현의 결과를 견준다.
  */
 
-export const ANALYZERS = ["surface", "kiwi"];
+import { projectExemplars } from "../data/exemplars.js";
+import { projectOperations } from "../data/operations.js";
+import { projectPatches } from "../data/patches.js";
+
+/**
+ * 글의 종류마다 처음부터 끄고 시작할 규칙. 정본은 파이썬 config/settings.py 의 PRESETS 다.
+ * @type {Record<string, string[]>}
+ */
+export const PRESETS = {
+  blog: [],
+  report: ["noQuestion", "sectionResult", "firstResultDistance", "introImage", "moreLater", "numberOrphan"],
+  docs: [
+    "noQuestion",
+    "sectionResult",
+    "firstResultDistance",
+    "introImage",
+    "moreLater",
+    "draftHistory",
+    "blockUnread",
+    "numberOrphan",
+  ],
+};
+PRESETS.guide = PRESETS.blog;
+PRESETS.essay = PRESETS.report;
+PRESETS.fiction = PRESETS.report;
+PRESETS.encyclopedia = PRESETS.docs;
+
+/** 프리셋 → 견줄 프로파일의 종류. 정본은 파이썬 config/settings.py 의 PROFILE_OF 다. @type {Record<string, string>} */
+export const PROFILE_OF = {
+  blog: "blog",
+  report: "report",
+  docs: "technicalDocs",
+  guide: "guide",
+  essay: "essay",
+  fiction: "fiction",
+  encyclopedia: "encyclopedia",
+};
+
+export const PRESET_NAMES = Object.keys(PRESETS);
+/** 설정도 옵션도 없을 때의 종류. 이 이름일 때는 출력에 프리셋을 적지 않는다. */
+export const DEFAULT_PRESET = PRESET_NAMES[0];
 
 /**
  * @typedef {object} Config
+ * @property {string} preset 글의 종류. PRESETS 가 정한 규칙을 처음부터 끈다
  * @property {Set<string>} disable 끌 규칙 이름
- * @property {string} analyzer
  * @property {string | null} keywordField
- * @property {string | null} profile
+ * @property {string[]} introFields
+ * @property {string[]} endingFields
+ * @property {string | null} profile 사용자 프로파일 파일 경로
+ * @property {number} profilePercentile outsideProfile 이 짚는 백분위
+ * @property {number} countMismatchSpan 절이 없는 글이 이 줄 수 안일 때만 글 전체를 견준다
+ * @property {string | null} baseline
  * @property {Record<string, unknown[]>} dictionary
+ * @property {import("../data/exemplars.js").Exemplar[]} exemplars 사람이 승인한 프로젝트 본보기
+ * @property {import("../data/patches.js").Patch[]} patches 사람이 승인한 국소 고침
+ * @property {import("../data/operations.js").SurfaceOperation[]} operations 사람이 승인한 표면 치환
+ * @property {string[]} protectedTerms 표면 치환이 바꾸면 안 되는 한국어 고유명사와 프로젝트 용어
+ * @property {string[]} ignoreFences 지문에서 뺄 펜스의 언어 표기. 장면 계약과 도표 원문은 코드 블록이 아니다
  * @property {string | null} source 설정을 읽은 파일. 기본값이면 null. loadConfig 가 채운다
  * @property {number} fragmentRun
  * @property {number} introMaxParagraphs
  * @property {number} headingUniformRatio
+ * @property {number} headingSentenceMaxLevel
+ * @property {number} bridgeRepeatMin
  * @property {number} nounPileMin
  * @property {number} endingRun
  * @property {number} factListMinSentences
@@ -26,20 +78,37 @@ export const ANALYZERS = ["surface", "kiwi"];
  * @property {number} duplicateBlockRatio
  * @property {number} firstResultMaxParagraphs
  * @property {number} sectionResultMinParagraphs
+ * @property {number} introMaxImages
+ * @property {number} headingQuestionRatio
+ * @property {number} moreLaterMaxChars
+ * @property {number} tableOddCellMinRows
+ * @property {number} registerMinShare
  */
 
 /** @returns {Config} */
 export function defaultConfig() {
   return {
+    preset: DEFAULT_PRESET,
     disable: new Set(),
-    analyzer: "surface",
     keywordField: null,
+    introFields: [],
+    endingFields: [],
     profile: null,
+    profilePercentile: 99,
+    countMismatchSpan: 60,
+    baseline: null,
     dictionary: {},
+    exemplars: [],
+    patches: [],
+    operations: [],
+    protectedTerms: [],
+    ignoreFences: [],
     source: null,
     fragmentRun: 3,
     introMaxParagraphs: 4,
     headingUniformRatio: 0.75,
+    headingSentenceMaxLevel: 6,
+    bridgeRepeatMin: 3,
     nounPileMin: 5,
     endingRun: 4,
     factListMinSentences: 3,
@@ -49,12 +118,23 @@ export function defaultConfig() {
     duplicateBlockRatio: 0.9,
     firstResultMaxParagraphs: 4,
     sectionResultMinParagraphs: 3,
+    introMaxImages: 1,
+    headingQuestionRatio: 0.5,
+    moreLaterMaxChars: 150,
+    tableOddCellMinRows: 4,
+    // 기준 말뭉치에서 일관된 에세이 하위 5%는 0.7576, 실제 혼합 기사는 0.625였다.
+    registerMinShare: 0.7,
   };
 }
 
 /** @param {Config} config @param {string} ruleName */
 export function enabled(config, ruleName) {
-  return !config.disable.has(ruleName);
+  return !config.disable.has(ruleName) && !PRESETS[config.preset].includes(ruleName);
+}
+
+/** 지금 꺼져 있는 규칙 이름. 프리셋이 끈 것과 disable 이 끈 것을 합친다. @param {Config} config */
+export function offRules(config) {
+  return [...new Set([...PRESETS[config.preset], ...config.disable])].sort();
 }
 
 /** @param {Record<string, unknown>} data @returns {Config} */
@@ -64,12 +144,27 @@ export function configFromMapping(data) {
     if (key === "disable") {
       config.disable = new Set(/** @type {string[]} */ (value));
     } else if (key === "analyzer") {
-      if (!ANALYZERS.includes(/** @type {string} */ (value))) {
-        throw new Error(`analyzer 는 ${ANALYZERS.join(" 또는 ")} 다: ${value}`);
+      // 0.0.7 까지의 키. hanlint init 이 surface 를 써 넣었으므로 그 값은 조용히 넘기고 다른 값은 빠졌다고 알린다.
+      if (value !== "surface") throw new Error(`analyzer 설정은 빠졌다. 분석기는 표층 하나라 키를 지운다: ${JSON.stringify(value)}`);
+    } else if (key === "preset") {
+      if (!(/** @type {string} */ (value) in PRESETS)) {
+        throw new Error(`preset 은 ${PRESET_NAMES.join(", ")} 가운데 하나다: ${JSON.stringify(value)}`);
       }
-      config.analyzer = /** @type {string} */ (value);
+      config.preset = /** @type {string} */ (value);
     } else if (key === "dictionary") {
       config.dictionary = { .../** @type {Record<string, unknown[]>} */ (value) };
+    } else if (key === "exemplars") {
+      config.exemplars = projectExemplars(value, PRESET_NAMES);
+    } else if (key === "patches") {
+      config.patches = projectPatches(value, PRESET_NAMES);
+    } else if (key === "operations") {
+      config.operations = projectOperations(value, PRESET_NAMES);
+    } else if (key === "ignoreFences" || key === "introFields" || key === "endingFields" || key === "protectedTerms") {
+      if (!Array.isArray(value) || !value.every((item) => typeof item === "string" && item.trim())) {
+        throw new Error(`${key} 는 문자열 배열이다: ${JSON.stringify(value)}`);
+      }
+      const names = value.map((item) => item.trim());
+      config[key] = key === "ignoreFences" ? names.map((name) => name.toLowerCase()) : names;
     } else if (key !== "source" && key in config) {
       config[key] = value;
     } else {

package/src/data/exemplars.js

@@ -0,0 +1,177 @@
+// @ts-check
+/**
+ * 본보기. 규칙마다 고치기 전과 후의 짝. 파이썬 data/exemplars.py 와 같다.
+ *
+ * 지적은 무엇이 틀렸는지 말하고 본보기는 무엇이 맞는지 보인다. 자리표시자 규약은 fixture 와 같다.
+ * `{em}` 은 긴 줄표, `{dot}` 은 마침표다.
+ */
+import { loadEntries } from "./load.js";
+
+const EM_DASH = String.fromCharCode(0x2014);
+const EN_DASH = String.fromCharCode(0x2013);
+const ELLIPSIS_CHAR = String.fromCharCode(0x2026);
+/** 한 줄 본보기의 표시 폭 상한. 글자 수가 아니라 폭이다. 뜻은 파이썬 data/exemplars.py 가 소유한다. */
+const ONE_LINE_LIMIT = 96;
+/** 칸을 둘 먹는 글자. 한중일 W 와 F 다. 파이썬 unicodedata.east_asian_width 와 같은 범위를 든다. */
+const WIDE = /[\u1100-\u115F\u2E80-\u303E\u3041-\u33FF\u3400-\u4DBF\u4E00-\u9FFF\uA000-\uA4CF\uAC00-\uD7A3\uF900-\uFAFF\uFE30-\uFE6F\uFF00-\uFF60\uFFE0-\uFFE6]/;
+
+/**
+ * @typedef {object} Exemplar
+ * @property {string} rule
+ * @property {string} before 그 규칙에 실제로 잡히는 글
+ * @property {string} after 같은 뜻이면서 잡히지 않는 글
+ * @property {string} moved 무엇이 달라졌는지 한 마디
+ * @property {string[]} presets 비어 있으면 기본, 값이 있으면 그 프리셋의 문맥 본보기
+ */
+
+/** @param {string} text */
+export function expand(text) {
+  return text.split("{em}").join(EM_DASH).split("{en}").join(EN_DASH).split("{dot}").join(".");
+}
+
+/** 터미널이 먹는 칸 수. 한중일 글자는 둘, 나머지는 하나다. @param {string} text */
+export function displayWidth(text) {
+  let width = 0;
+  for (const ch of text) width += WIDE.test(ch) ? 2 : 1;
+  return width;
+}
+
+/** 한 줄로 보일 때의 꼴. 줄바꿈은 공백으로 눕히고 폭이 넘치면 자른다. @param {string} text @param {number} [limit] */
+export function shorten(text, limit = ONE_LINE_LIMIT) {
+  const flat = text.split(/\s+/).filter(Boolean).join(" ");
+  if (displayWidth(flat) <= limit) return flat;
+  let kept = "";
+  let used = 0;
+  for (const ch of flat) {
+    const step = WIDE.test(ch) ? 2 : 1;
+    if (used + step > limit - 1) break;
+    kept += ch;
+    used += step;
+  }
+  return kept + ELLIPSIS_CHAR;
+}
+
+/** @param {string} text */
+export function isShortened(text) {
+  return displayWidth(text.split(/\s+/).filter(Boolean).join(" ")) > ONE_LINE_LIMIT;
+}
+
+/** @type {Exemplar[] | null} */
+let allCache = null;
+/** @type {Map<string, Exemplar> | null} */
+let defaultCache = null;
+
+/** 기본과 문맥 본보기를 모두 읽는다. @returns {Exemplar[]} */
+export function allExemplars() {
+  if (!allCache) {
+    allCache = [];
+    const defaults = new Set();
+    /** @type {Map<string, Set<string>>} */
+    const contexts = new Map();
+    for (const entry of loadEntries("exemplars.json")) {
+      const rule = /** @type {string} */ (entry.rule);
+      const presets = /** @type {string[]} */ (entry.presets ?? []);
+      if (!presets.length) {
+        if (defaults.has(rule)) throw new Error(`기본 본보기가 겹친다: ${rule}`);
+        defaults.add(rule);
+      } else {
+        const used = contexts.get(rule) ?? new Set();
+        const overlap = presets.filter((preset) => used.has(preset)).sort();
+        if (overlap.length) throw new Error(`문맥 본보기의 프리셋이 겹친다: ${rule} ${overlap.join(", ")}`);
+        for (const preset of presets) used.add(preset);
+        contexts.set(rule, used);
+      }
+      allCache.push({
+        rule,
+        before: expand(/** @type {string} */ (entry.before)),
+        after: expand(/** @type {string} */ (entry.after)),
+        moved: /** @type {string} */ (entry.moved),
+        presets,
+      });
+    }
+  }
+  return allCache;
+}
+
+/** 규칙 이름 → 본보기. @returns {Map<string, Exemplar>} */
+export function exemplars() {
+  if (!defaultCache) {
+    defaultCache = new Map(
+      allExemplars().filter((exemplar) => !exemplar.presets.length).map((exemplar) => [exemplar.rule, exemplar]),
+    );
+  }
+  return defaultCache;
+}
+
+/** 설정의 `[[exemplars]]` 를 검증한다. @param {unknown} entries @param {string[]} presetNames @returns {Exemplar[]} */
+export function projectExemplars(entries, presetNames) {
+  if (!Array.isArray(entries)) throw new Error("exemplars 는 [[exemplars]] 배열이다");
+  const allowedKeys = new Set(["rule", "before", "after", "moved", "presets"]);
+  const knownRules = new Set(exemplars().keys());
+  const knownPresets = new Set(presetNames);
+  const defaults = new Set();
+  /** @type {Map<string, Set<string>>} */
+  const contexts = new Map();
+  return entries.map((raw, offset) => {
+    const index = offset + 1;
+    if (!raw || typeof raw !== "object" || Array.isArray(raw)) throw new Error(`exemplars ${index}번째 항목은 표다`);
+    const entry = /** @type {Record<string, unknown>} */ (raw);
+    const unknown = Object.keys(entry).filter((key) => !allowedKeys.has(key)).sort();
+    if (unknown.length) throw new Error(`exemplars ${index}번째 항목의 모르는 키: ${unknown.join(", ")}`);
+    /** @type {Record<string, string>} */
+    const values = {};
+    for (const key of ["rule", "before", "after", "moved"]) {
+      const value = entry[key];
+      if (typeof value !== "string" || !value.trim()) {
+        throw new Error(`exemplars ${index}번째 항목의 ${key} 는 비지 않은 문자열이다`);
+      }
+      values[key] = value;
+    }
+    const rule = values.rule;
+    if (!knownRules.has(rule)) throw new Error(`exemplars ${index}번째 항목의 모르는 규칙: ${rule}`);
+    const rawPresets = entry.presets ?? [];
+    if (!Array.isArray(rawPresets) || !rawPresets.every((item) => typeof item === "string")) {
+      throw new Error(`exemplars ${index}번째 항목의 presets 는 문자열 배열이다`);
+    }
+    const presets = /** @type {string[]} */ (rawPresets);
+    const unknownPresets = [...new Set(presets.filter((preset) => !knownPresets.has(preset)))].sort();
+    if (unknownPresets.length) {
+      throw new Error(`exemplars ${index}번째 항목의 모르는 프리셋: ${unknownPresets.join(", ")}`);
+    }
+    if (new Set(presets).size !== presets.length) throw new Error(`프로젝트 본보기의 프리셋이 겹친다: ${rule}`);
+    if (!presets.length) {
+      if (defaults.has(rule)) throw new Error(`프로젝트 기본 본보기가 겹친다: ${rule}`);
+      defaults.add(rule);
+    } else {
+      const used = contexts.get(rule) ?? new Set();
+      const overlap = presets.filter((preset) => used.has(preset)).sort();
+      if (overlap.length) throw new Error(`프로젝트 본보기의 프리셋이 겹친다: ${rule} ${overlap.join(", ")}`);
+      for (const preset of presets) used.add(preset);
+      contexts.set(rule, used);
+    }
+    return { rule, before: expand(values.before), after: expand(values.after), moved: values.moved, presets };
+  });
+}
+
+/** @param {string} rule @param {string | null | undefined} [preset] @param {Exemplar[]} [customExemplars] @returns {Exemplar | undefined} */
+export function exemplarFor(rule, preset = null, customExemplars = []) {
+  if (preset) {
+    const contextual = customExemplars.find((exemplar) => exemplar.rule === rule && exemplar.presets.includes(preset));
+    if (contextual) return contextual;
+    const builtInContextual = allExemplars().find((exemplar) => exemplar.rule === rule && exemplar.presets.includes(preset));
+    if (builtInContextual) return builtInContextual;
+  }
+  const customDefault = customExemplars.find((exemplar) => exemplar.rule === rule && !exemplar.presets.length);
+  if (customDefault) return customDefault;
+  return exemplars().get(rule);
+}
+
+/** 전과 후를 제 줄씩. @param {Exemplar} exemplar @returns {[string, string]} */
+export function twoLines(exemplar) {
+  return [shorten(exemplar.before), shorten(exemplar.after)];
+}
+
+/** 어느 한쪽이라도 잘렸나. @param {Exemplar} exemplar */
+export function shortened(exemplar) {
+  return isShortened(exemplar.before) || isShortened(exemplar.after);
+}

package/src/data/load.js

@@ -57,6 +57,16 @@ export function loadRuleDocs() {
   return cached("ruleDocs", () => JSON.parse(readText("ruleDocs.json")));
 }
 
+/** @returns {Record<string, string>} 규칙 이름 → 부류 (규칙 파일이 사는 폴더의 투영) */
+export function loadRuleCategories() {
+  return cached("ruleCategories", () => JSON.parse(readText("ruleCategories.json")));
+}
+
+/** @returns {Record<string, string>} 규칙 이름 → 기제 (파이썬 등록부의 투영) */
+export function loadRuleMechanisms() {
+  return cached("ruleMechanisms", () => JSON.parse(readText("ruleMechanisms.json")));
+}
+
 /** @returns {string} */
 export function loadVersion() {
   return cached("version", () => JSON.parse(readText("version.json")).version);