hanlint 0.0.8 → 0.0.10

package/src/rules/code/installImport.js

@@ -5,7 +5,8 @@ import { DOCUMENT, NOTICE, finding } from "../finding.js";
 export const name = "installImport";
 export const mechanism = "contrast";
 
-const INSTALL = /(?:pip\s+install|uv\s+add|uv\s+pip\s+install|conda\s+install|poetry\s+add)\s+([^\n#|&;]+)/g;
+// 캡처는 백틱과 한글에서 멈춘다. 안 멈추면 설치 줄 뒤의 산문을 패키지로 등록한다. 파이썬과 같다.
+const INSTALL = /(?:pip\s+install|uv\s+add|uv\s+pip\s+install|conda\s+install|poetry\s+add)\s+([^\n#|&;`가-힣]+)/g;
 const IMPORT = /^\s*(?:import\s+([\w.]+(?:\s*,\s*[\w.]+)*)|from\s+([\w.]+)\s+import\b)/;
 const REQUIREMENT = /^([A-Za-z0-9][A-Za-z0-9._-]*)(?:\[([^\]]*)\])?/;
 const PY_FILE = /\b(\w+)\.py\b/g;
@@ -17,14 +18,14 @@ function stdlib() {
   return stdlibCache;
 }
 
-/** @type {Map<string, string> | null} */
+/** @type {Map<string, Set<string>> | null} */
 let packageCache = null;
 function packageOf() {
   if (!packageCache) {
     packageCache = new Map();
     for (const line of loadLines("pythonPackages.txt")) {
       const [module, pkg] = line.split("\t");
-      packageCache.set(module, pkg);
+      packageCache.set(module, new Set(pkg.split("|").map(normalize)));
     }
   }
   return packageCache;
@@ -104,9 +105,10 @@ export function run(doc) {
         for (const module of modules) {
           const top = module.split(".")[0];
           if (!top || stdlib().has(top) || local.has(top)) continue;
-          const pkg = normalize(packageOf().get(top) ?? top);
-          if (!packages.has(pkg)) {
-            findings.push(finding(name, line, code.trim(), `\`${top}\` 를 import 하는데 설치 줄에 \`${pkg}\` 가 없다. 독자는 ModuleNotFoundError 에서 멈춘다`, null, "error", DOCUMENT, block.index));
+          const acceptable = packageOf().get(top) ?? new Set([normalize(top)]);
+          if (![...acceptable].some((pkg) => packages.has(pkg))) {
+            const packageNames = [...acceptable].sort().join("`, `");
+            findings.push(finding(name, line, code.trim(), `\`${top}\` 를 import 하는데 설치 줄에 허용되는 이름 \`${packageNames}\` 가 없다. 독자는 ModuleNotFoundError 에서 멈춘다`, null, "error", DOCUMENT, block.index));
           }
         }
       }

package/src/rules/document/keywordHeading.js

@@ -19,9 +19,14 @@ export function run(doc, config) {
   const headings = doc.headings.filter(([level]) => level === 2);
   if (!keyword || headings.length < MIN_HEADINGS) return [];
   const joined = headings.map(([, text]) => text).join(" / ");
-  const missing = keyword.split(/\s+/).filter((word) => word.length >= MIN_WORD && title.includes(word) && !joined.includes(word));
+  // keywordMissing 과 같은 자리를 본다. 제목만 보면 첫 문단에만 있는 검색어가 두 규칙 사이로 빠진다. 파이썬과 같다.
+  const first = doc.paragraphs.length ? doc.paragraphs[0].text : "";
+  const promised = `${title}\n${first}`;
+  const missing = keyword
+    .split(/\s+/)
+    .filter((word) => word.length >= MIN_WORD && promised.includes(word) && !joined.includes(word));
   if (!missing.length) return [];
   return [
-    finding(name, headings[0][2], joined, `제목이 약속한 \`${missing[0]}\` 가 절 제목 어디에도 없다. 목차를 훑는 독자가 이 글이 그것을 다루는지 못 본다`, null, NOTICE, DOCUMENT, -1),
+    finding(name, headings[0][2], joined, `글이 내건 \`${missing[0]}\` 가 절 제목 어디에도 없다. 목차를 훑는 독자가 이 글이 그것을 다루는지 못 본다`, null, NOTICE, DOCUMENT, -1),
   ];
 }

package/src/rules/document/noQuestion.js

@@ -5,11 +5,11 @@ export const name = "noQuestion";
 export const mechanism = "threshold";
 
 /** @param {import("../../fingerprint/build.js").DocumentPrint} doc */
-export function run(doc) {
+export function run(doc, config) {
   if (doc.bodySections.length < 2 || doc.questionCount > 0) return [];
   const first = doc.sentences.length ? doc.sentences[0] : null;
   const why = doc.readerCallCount === 0
-    ? "물음표가 한 번도 없고 독자를 부르는 말도 없다. 독자가 품을 의문을 한 번은 대신 묻고, 독자가 할 행동을 동사로 끝내는 문장을 넣는다"
-    : "물음표가 한 번도 없다. 독자가 품을 의문을 한 번은 대신 묻고 다음 문장에서 답한다";
-  return [finding(name, first ? first.line : 1, first ? first.text : "", why, null, "error", DOCUMENT, -1)];
+    ? "물음표가 한 번도 없고 독자를 부르는 말도 없다. 질문이나 독자 호출이 필요한 글인지 판단하고 충분하면 유지한다"
+    : "물음표가 한 번도 없다. 질문이 필요한 글인지 판단하고 설명만으로 충분하면 유지한다";
+  return [finding(name, first ? first.line : 1, first ? first.text : "", why, null, config.enforceStyle.includes(name) ? "error" : "notice", DOCUMENT, -1)];
 }

package/src/rules/document/tableOddCell.js

@@ -5,7 +5,8 @@ import { DOCUMENT, NOTICE, finding } from "../finding.js";
 export const name = "tableOddCell";
 export const mechanism = "contrast";
 const SEPARATOR = /^:?-{2,}:?$/;
-const MEASURE = /^([+-]?\d[\d,]*(?:\.\d+)?)\s*([^\s\d]{0,6})$/;
+// 단위는 한 글자 이상이다. 0 을 허용하면 맨숫자 칸이 빈 단위를 받아 지적문이 깨진다. 파이썬과 같다.
+const MEASURE = /^([+-]?\d[\d,]*(?:\.\d+)?)\s*([^\s\d]{1,6})$/;
 const EMPTY = ["", "-", "--"];
 
 /** (블록 안 줄 오프셋, 칸 목록). 구분 줄은 뺀다. @param {string} text @returns {[number, string[]][]} */

package/src/rules/readerDebt.js

@@ -0,0 +1,9 @@
+// @ts-check
+/** 독자 부채는 새 판정이 아니라 reader 기제 Finding을 사람이 읽는 이름으로 묶은 것이다. */
+
+import { ruleMechanism } from "./registry.js";
+
+/** @param {import("./finding.js").Finding[]} findings */
+export function readerDebts(findings) {
+  return findings.filter((finding) => ruleMechanism(finding.rule) === "reader");
+}

package/src/rules/registry.js

@@ -24,7 +24,6 @@ import * as spacing from "./orthography/spacing.js";
 import * as spelling from "./orthography/spelling.js";
 import * as factListParagraph from "./paragraph/factListParagraph.js";
 import * as paraFragment from "./paragraph/paraFragment.js";
-import * as topicBreak from "./paragraph/topicBreak.js";
 import * as cliche from "./sentence/cliche.js";
 import * as hardWord from "./sentence/hardWord.js";
 import * as connectorRepeat from "./sentence/connectorRepeat.js";
@@ -35,7 +34,6 @@ import * as dash from "./sentence/dash.js";
 import * as deixis from "./sentence/deixis.js";
 import * as doubleNegative from "./sentence/doubleNegative.js";
 import * as doublePassive from "./sentence/doublePassive.js";
-import * as ellipsis from "./sentence/ellipsis.js";
 import * as endingRepeat from "./sentence/endingRepeat.js";
 import * as euiChain from "./sentence/euiChain.js";
 import * as fillerOpener from "./sentence/fillerOpener.js";
@@ -50,7 +48,6 @@ import * as translationese from "./sentence/translationese.js";
 import * as blockUnread from "./structure/blockUnread.js";
 import * as bridgeRepeat from "./structure/bridgeRepeat.js";
 import * as emojiBullet from "./structure/emojiBullet.js";
-import * as headingQuestion from "./structure/headingQuestion.js";
 import * as introImage from "./structure/introImage.js";
 import * as loneSubheading from "./structure/loneSubheading.js";
 import * as moreLater from "./structure/moreLater.js";
@@ -59,7 +56,6 @@ import * as headingSkip from "./structure/headingSkip.js";
 import * as headingUniform from "./structure/headingUniform.js";
 import * as introLong from "./structure/introLong.js";
 import * as sectionNoProse from "./structure/sectionNoProse.js";
-import * as sectionResult from "./structure/sectionResult.js";
 
 /**
  * @typedef {object} Rule
@@ -79,7 +75,6 @@ export const RULES = [
   deixis,
   doubleNegative,
   doublePassive,
-  ellipsis,
   endingRepeat,
   euiChain,
   fillerOpener,
@@ -94,11 +89,9 @@ export const RULES = [
   translationese,
   factListParagraph,
   paraFragment,
-  topicBreak,
   blockUnread,
   bridgeRepeat,
   emojiBullet,
-  headingQuestion,
   introImage,
   loneSubheading,
   moreLater,
@@ -107,7 +100,6 @@ export const RULES = [
   headingUniform,
   introLong,
   sectionNoProse,
-  sectionResult,
   countMismatch,
   enoughOnce,
   fieldEcho,
@@ -162,6 +154,33 @@ export function ruleSummary(name) {
   return ruleDoc(name).split("\n")[0];
 }
 
+/** 기술서의 네 절 표. 파이썬 rules/registry.py 의 REQUIRED_SECTIONS 와 같다. */
+export const REQUIRED_SECTIONS = ["왜:", "어디서:", "고치기:", "안 잡는 것:"];
+
+/** 기술서에서 절 하나의 본문을 한 줄로. 파이썬 docSection 과 같다. @param {string} doc @param {string} label */
+export function docSection(doc, label) {
+  const collected = [];
+  let inside = false;
+  for (const raw of doc.split("\n")) {
+    const line = raw.trim();
+    if (!inside) {
+      if (line.startsWith(label)) {
+        inside = true;
+        collected.push(line.slice(label.length).trim());
+      }
+      continue;
+    }
+    if (!line || REQUIRED_SECTIONS.some((other) => line.startsWith(other))) break;
+    collected.push(line);
+  }
+  return collected.filter(Boolean).join(" ");
+}
+
+/** 규칙의 고치기 절 한 줄. primer 가 쓰기 전에 읽히는 그 문장이다. @param {string} name */
+export function ruleFix(name) {
+  return docSection(ruleDoc(name), "고치기:");
+}
+
 /**
  * 부류의 사람 이름. 파이썬 rules/registry.py 의 CATEGORY_TITLES 와 같은 값과 같은 순서다.
  * @type {Record<string, string>}

package/src/rules/sentence/danglingDeixis.js

@@ -8,6 +8,20 @@ import { hasLocalAntecedent } from "../shared/localAntecedent.js";
 export const name = "danglingDeixis";
 export const mechanism = "reader";
 
+const QUESTION = "의문";
+const EXCLAIM = ["!", "！"];
+
+/**
+ * 앞 문장이 물음이나 감탄인가. 그러면 그 문장 자체가 지시어의 선행어다.
+ * 뜻은 파이썬 rules/sentence/danglingDeixis.py 의 isPrompt 가 소유한다.
+ * @param {{mood: string, text: string} | null} previous
+ */
+function isPrompt(previous) {
+  if (!previous) return false;
+  const text = previous.text.replace(/\s+$/u, "");
+  return previous.mood === QUESTION || EXCLAIM.some((mark) => text.endsWith(mark));
+}
+
 /** @param {import("../../fingerprint/build.js").DocumentPrint} doc */
 export function run(doc) {
   const findings = [];
@@ -16,6 +30,7 @@ export function run(doc) {
     if (hasLocalAntecedent(sentence)) continue;
     const reader = doc.reader.beforeSentence[sentence.index];
     if (overlap(reader.recent, sentence.topics) > 0) continue;
+    if (isPrompt(reader.previous)) continue;
     findings.push(
       finding(name, sentence.line, sentence.text, `\`${sentence.deixis[0]}\` ${fitJosa(sentence.deixis[0], "이")} 가리킬 것이 앞 문장에 없다. 가리키는 파일, 값, 코드의 이름을 쓴다`, null, "error", SENTENCE, sentence.index, null, null, danglingDeixisCandidates(sentence, reader.previous)),
     );

package/src/rules/sentence/negationRedefine.js

@@ -4,7 +4,8 @@ import { COPULA as COPULA_KIND, lastWord, parsePredicate } from "../../analysis/
 
 export const name = "negationRedefine";
 export const mechanism = "repeat";
-const NEGATION = /단순(?:한|히)\s?.{0,15}?(?:이|가)\s?아(?:닙니다|니다|니에요|니죠|닌)/;
+// 관형형 `아닌` 은 뺐다. 문장을 끝낼 수 없어 앞 문장이 부정이라는 전제를 못 만족한다. 파이썬과 같다.
+const NEGATION = /단순(?:한|히)\s?.{0,15}?(?:이|가)\s?아(?:닙니다|니다|니에요|니죠)/;
 const COPULA = /(입니다|이다|이에요|예요)[.!]?$/;
 
 /** @param {string} text */

package/src/rules/sentence/nounPile.js

@@ -13,7 +13,7 @@ export function run(doc, config) {
   for (const sentence of doc.sentences) {
     if (sentence.nounRun >= config.nounPileMin) {
       findings.push(
-        finding(name, sentence.line, sentence.text, `명사 ${sentence.nounRun}개가 조사 없이 이어진다. 관계가 표시되지 않아 독자가 조사를 끼워 넣는다. 동사로 되돌린다`, null, "error", SENTENCE, sentence.index),
+        finding(name, sentence.line, sentence.text, `명사 ${sentence.nounRun}개가 조사 없이 이어진다. 관계가 표시되지 않아 독자가 조사를 끼워 넣는다. 동사로 되돌린다`, null, config.enforceStyle.includes(name) ? "error" : "notice", SENTENCE, sentence.index),
       );
     }
   }

package/src/rules/structure/headingUniform.js

@@ -11,12 +11,12 @@ export const mechanism = "repeat";
  */
 export function run(doc, config) {
   const headings = doc.headings.filter(([level]) => level === 2);
-  // 버전이나 날짜처럼 숫자로 끝나는 제목은 어미가 아니라 판정에서 뺀다.
+  // 어미는 한글이다. 숫자, 부호, 라틴 문자로 끝나는 제목은 판정에서 뺀다. 파이썬과 같다.
   const eligible = headings.filter(([, text]) => {
     if (!text.trim()) return false;
     const trimmed = text.trimEnd();
     const char = trimmed[trimmed.length - 1];
-    return !(char >= "0" && char <= "9");
+    return char >= "가" && char <= "힣";
   });
   if (eligible.length < 3) return [];
   const [best, count, total] = shareOf(
@@ -27,7 +27,7 @@ export function run(doc, config) {
   );
   if (count / total >= config.headingUniformRatio) {
     return [
-      finding(name, eligible[0][2], eligible.map(([, text]) => text).join(" / "), `H2 ${eligible.length}개 중 ${count}개가 \`${best}\` 로 끝난다. 목차가 한 어미로 끝나면 과정이 아니라 나열로 읽힌다. 형태를 섞는다`, null, "error", DOCUMENT, -1),
+      finding(name, eligible[0][2], eligible.map(([, text]) => text).join(" / "), `H2 ${eligible.length}개 중 ${count}개가 \`${best}\` 로 끝난다. 목차가 한 어미로 끝나면 과정이 아니라 나열로 읽힌다. 그 문서의 관례라면 둔다`, null, "notice", DOCUMENT, -1),
     ];
   }
   return [];

package/src/rules/structure/introLong.js

@@ -9,8 +9,10 @@ export const mechanism = "threshold";
  * @param {import("../../config/settings.js").Config} config
  */
 export function run(doc, config) {
-  if (!doc.bodySections.length) return [];
+  // 본문 절이 하나뿐이거나 도입이 문단의 절반을 넘으면 절이 없는 글이지 도입이 긴 글이 아니다. 파이썬과 같다.
+  if (doc.bodySections.length < 2) return [];
   const paragraphs = doc.intro.paragraphs;
+  if (paragraphs.length * 2 > doc.paragraphs.length) return [];
   if (paragraphs.length > config.introMaxParagraphs) {
     const over = paragraphs[config.introMaxParagraphs];
     return [

package/data/coverageTypes.txt

@@ -1,7 +0,0 @@
-# 사람 평가자의 지적을 유형으로 가르는 표지. `유형<TAB>정규식`. coverage 가 못 집은 지적을 모을 때 쓴다. 위에서부터 먼저 맞는 것이 이긴다.
-파일과 폴더	파일|폴더|경로|만들어지지|생성|없어서|없다
-설치와 실행	설치|import|모듈|패키지|실행|오류|에러|Error|멈춘다|돌아가지
-순서와 구조	순서|먼저|앞에서|뒤에서|절|목차|위치|옮|건너
-용어와 설명	설명|뜻|처음 나온|용어|무엇인지|모른|정의
-숫자와 표	숫자|표|열|행|값|측정|잰
-문장과 표현	문장|주어|서술어|표현|반복|같은 말|어색

package/src/rules/paragraph/topicBreak.js

@@ -1,26 +0,0 @@
-// @ts-check
-import { NOTICE, PARAGRAPH, finding } from "../finding.js";
-
-export const name = "topicBreak";
-export const mechanism = "contrast";
-
-/**
- * @param {import("../../fingerprint/build.js").DocumentPrint} doc
- * @param {import("../../config/settings.js").Config} config
- */
-export function run(doc, config) {
-  const findings = [];
-  for (const section of doc.sections) {
-    const paragraphs = section.paragraphs;
-    for (let i = 0; i + 1 < paragraphs.length; i++) {
-      const previous = paragraphs[i];
-      const paragraph = paragraphs[i + 1];
-      if (paragraph.overlapWithPrevious !== 0) continue;
-      if (Math.min(previous.sentenceCount, paragraph.sentenceCount) < config.topicBreakMinSentences) continue;
-      findings.push(
-        finding(name, paragraph.startLine, paragraph.sentences[0].text, "앞 문단과 화제어가 하나도 겹치지 않는다. 앞에서 만든 것의 이름을 첫 문장에서 다시 부른다", null, NOTICE, PARAGRAPH, paragraph.index),
-      );
-    }
-  }
-  return findings;
-}

package/src/rules/sentence/ellipsis.js

@@ -1,32 +0,0 @@
-// @ts-check
-import { insideAny } from "../../fingerprint/markers.js";
-import { SENTENCE, finding } from "../finding.js";
-
-export const name = "ellipsis";
-export const mechanism = "dictionary";
-// 영숫자에 붙은 점 셋 (`v0.0.1...HEAD`, compare URL) 은 범위 표기라 말줄임표가 아니다.
-// 인라인 코드와 따옴표 안은 지문이 인용 구간으로 이미 표시해 두었으므로 여기서 다시 재지 않는다.
-const ELLIPSIS = /(?<![A-Za-z0-9])(…|\.{3,})(?![A-Za-z0-9])/g;
-const CLI_OPTION = /(?:^|\s)--?[A-Za-z0-9]/;
-
-/** 괄호 안 명령 예시의 생략 인자. 예: (kubectl get -o yaml …). @param {string} text @param {number} start @param {number} end */
-function insideCommandExample(text, start, end) {
-  const opened = text.lastIndexOf("(", start);
-  const closed = text.indexOf(")", end);
-  return opened >= 0 && closed >= 0 && !text.slice(opened, start).includes(")") && !text.slice(end, closed).includes("(") && CLI_OPTION.test(text.slice(opened + 1, closed));
-}
-
-/** @param {import("../../fingerprint/build.js").DocumentPrint} doc */
-export function run(doc) {
-  const findings = [];
-  for (const sentence of doc.sentences) {
-    const found = [...sentence.text.matchAll(ELLIPSIS)].filter((m) => {
-      const start = /** @type {number} */ (m.index);
-      return !insideAny(start, start + m[0].length, sentence.quoted) && !insideCommandExample(sentence.text, start, start + m[0].length);
-    });
-    if (found.length) {
-      findings.push(finding(name, sentence.line, sentence.text, "말줄임표로 말끝을 흐리면 독자가 결론을 받아 가지 못한다. 문장을 끝까지 쓴다", null, "error", SENTENCE, sentence.index));
-    }
-  }
-  return findings;
-}

package/src/rules/structure/headingQuestion.js

@@ -1,19 +0,0 @@
-// @ts-check
-import { DOCUMENT, finding } from "../finding.js";
-
-export const name = "headingQuestion";
-export const mechanism = "repeat";
-
-/**
- * @param {import("../../fingerprint/build.js").DocumentPrint} doc
- * @param {import("../../config/settings.js").Config} config
- */
-export function run(doc, config) {
-  const headings = doc.headings.filter(([level]) => level === 2);
-  if (headings.length < 3) return [];
-  const asking = headings.filter(([, text]) => text.trimEnd().endsWith("?")).map(([, text]) => text);
-  if (asking.length / headings.length <= config.headingQuestionRatio) return [];
-  return [
-    finding(name, headings[0][2], asking.join(" / "), `H2 ${headings.length}개 중 ${asking.length}개가 물음표로 끝난다. 목차가 과정이 아니라 FAQ 로 읽힌다. 형태를 섞는다`, null, "error", DOCUMENT, -1),
-  ];
-}

package/src/rules/structure/sectionResult.js

@@ -1,38 +0,0 @@
-// @ts-check
-import { CODE, EMBED, IMAGE, TABLE } from "../../document/model.js";
-import { NOTICE, SECTION, finding } from "../finding.js";
-
-export const name = "sectionResult";
-export const mechanism = "threshold";
-const RESULT_KINDS = [CODE, EMBED, IMAGE, TABLE];
-const FILE_NAME = /[\w가-힣-]+\.(?:csv|xlsx|xls|parquet|json|png|jpg|svg|db|sqlite|txt|py|pdf|html|md)\b/;
-const OUTPUT_WORDS = ["출력", "화면에", "찍힙니다", "나옵니다", "뜹니다", "보입니다", "만들어집니다", "생깁니다", "저장됩니다"];
-
-/** @param {import("../../fingerprint/build.js").SectionPrint} section */
-function leavesResult(section) {
-  if (section.blockKinds.some((kind) => RESULT_KINDS.includes(kind))) return true;
-  for (const paragraph of section.paragraphs) {
-    for (const sentence of paragraph.sentences) {
-      if (FILE_NAME.test(sentence.text) || OUTPUT_WORDS.some((word) => sentence.text.includes(word))) return true;
-    }
-  }
-  return false;
-}
-
-/**
- * @param {import("../../fingerprint/build.js").DocumentPrint} doc
- * @param {import("../../config/settings.js").Config} config
- */
-export function run(doc, config) {
-  const findings = [];
-  const body = doc.bodySections;
-  body.forEach((section, index) => {
-    if (index === body.length - 1) return;
-    if (section.paragraphs.length <= config.sectionResultMinParagraphs) return;
-    if (leavesResult(section)) return;
-    findings.push(
-      finding(name, section.startLine, section.title, "이 절에 독자가 확인할 결과 (코드, 표, 그림, 파일, 출력) 가 없다. 만들거나 확인할 것을 하나 넣는다", null, NOTICE, SECTION, section.index),
-    );
-  });
-  return findings;
-}