hanlint 0.0.9 → 0.0.10

package/README.md

@@ -9,6 +9,13 @@ npx hanlint
 npx hanlint 글.md
 npx hanlint fix 글.md
 npx hanlint 글.md --format compact --errors-only
+npx hanlint spec --preset blog --register 합니다 --chars 800
+npx hanlint hook
+npx hanlint hook --reply
+npx hanlint contract init 초안.md --reader "배포를 결정할 운영자" --goal "예산을 확인한다"
+npx hanlint contract init 초안.md --reader "개발자" --goal "섹션별로 비교한다" --outline h2
+npx hanlint check contract.json 초안.md --format text
+npx hanlint verify-patch contract.json 초안.md patch.json
 ```
 
 인자 없이 치면 첫 화면이 나온다. 이 폴더의 마크다운 이름으로 만든 예시와 지금 칠 수 있는 명령이 거기 있다.
@@ -33,12 +40,40 @@ npx hanlint 글.md --format compact --errors-only
 규칙을 끈 설정 파일을 만든다. `blog`, `report`, `docs`, `guide`, `essay`, `fiction`, `encyclopedia` 일곱이고
 `npx hanlint rules` 가 지금 도는 목록을 낸다.
 
+글을 쓰기 전에는 `npx hanlint spec --preset <종류> --chars <글자 수>`로 같은 규칙판에서 숫자 사양을 받는다.
+배포 프로파일에서 관찰한 값과 현재 켜진 규칙 임계를 함께 낸다. JSON의 `rows[].basis`가 각 수의 정본을 밝힌다.
+새 점수나 품질 판정은 만들지 않는다. `chat`은 견줄 프로파일이 없어 사양을 내지 않는다.
+
+Claude Code의 PostToolUse JSON을 stdin으로 `npx hanlint hook`에 연결하면 `Edit|Write`가 저장한 마크다운
+한 파일을 검사한다. Finding이 있을 때만 다음 모델 요청용 `additionalContext` JSON을 내며 언제나 종료 코드
+0이라 쓰기를 막지 않는다. Stop에는 `npx hanlint hook --reply`를 연결한다. 마지막 답변을 `chat` 프리셋으로
+한 번 검사하고 `stop_hook_active` 재진입에서는 침묵한다. 전체 `.claude/settings.json` 예시는 루트 README에 있다.
+
 ```js
-import { lintFile } from "hanlint";
+import { Contract, Patch, check, contractFromText, contractFromTextV2, lintFile, renderCheck, verifyPatch } from "hanlint";
 
 for (const finding of lintFile("글.md")) console.log(finding.line, finding.rule, finding.why);
+
+const draftContract = contractFromText(text, "배포를 결정할 운영자", "예산을 확인한다");
+const structuredContract = contractFromTextV2(text, "개발자", "섹션별로 비교한다", 2);
+const contract = new Contract("배포를 결정할 운영자", "예산을 확인한다", ["예산은 380,000원이다."]);
+const receipt = check(text, contract);
+console.log(renderCheck(check(text, structuredContract)));
+const patch = new Patch("unexpectedNumbers", "400,000", "380,000");
+const verified = verifyPatch(text, patch, contract);
 ```
 
+Reader Contract는 `reader`, `goal`, `facts`에서 숫자, URL, 인라인 코드와 링크 목적지를 자동으로 보호한다.
+`contractFromText`와 `contract init`은 보호 원자를 많이 덮는 원문 줄부터 골라 facts 후보를 줄인다.
+사실의 진실과 보호 원자가 없는 의미는 추측하지 않으므로 사람이 초안을 확인한다.
+제목 수와 순서가 요구사항이면 `contractFromTextV2` 또는 `contract init --outline h2`를 쓴다. version 2는
+사람이 승인한 facts, 자동으로 모은 surface, 한 수준의 정확한 outline을 분리한다. `check --format text`는
+보호 원자, 제목 구조, 전체 절 제목, lint와 다음 행동을 한 화면에 보여 준다.
+check 결과는 Contract와 초안 해시, 보호 원자 차이와 기존 Finding을 담는다. Patch는 원문 한 자리에 정확히
+맞고 명시한 기존 위반을 줄이며 새 보호 원자 위반과 새 error를 만들지 않을 때만 검증된다. 이 조건은 의미나
+진실, 자연스러움의 승인이 아니다. version 2 Patch는 새 outline 위반도 거부한다. Python과 npm은 배포물의
+같은 version 1 적합성 JSON을 독립 실행하고 version 2 결과도 동등성 게이트로 견준다.
+
 파이썬 패키지 (`pip install hanlint`) 와 같은 규칙, 같은 fixture, 같은 출력이다. 지문 지도 (`audit`, `map`),
 문체 프로파일, 초안 비교 (`diff`), 평가자 겹침 (`coverage`) 은 파이썬 쪽에만 있다. 무엇을 잡고 무엇을 잡지 않는지는
 [전체 사용 안내](https://github.com/eddmpython/hanlint#readme)와

package/data/checkResult.schema.json

@@ -0,0 +1,75 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://hanlint.dev/schemas/checkResult.schema.json",
+  "title": "hanlint Check Result",
+  "description": "A deterministic receipt for a Reader Contract and a prose draft.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "version",
+    "kind",
+    "violationCount",
+    "contractSha256",
+    "draftSha256",
+    "surface",
+    "lint",
+    "meaning"
+  ],
+  "properties": {
+    "version": { "const": 1 },
+    "kind": { "const": "hanlint.checkResult" },
+    "violationCount": { "type": "integer", "minimum": 0 },
+    "contractSha256": { "$ref": "#/$defs/sha256" },
+    "draftSha256": { "$ref": "#/$defs/sha256" },
+    "surface": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "missingNumbers",
+        "unexpectedNumbers",
+        "missingUrls",
+        "unexpectedUrls",
+        "missingCode",
+        "unexpectedCode",
+        "missingLinks",
+        "unexpectedLinks"
+      ],
+      "properties": {
+        "missingNumbers": { "$ref": "#/$defs/strings" },
+        "unexpectedNumbers": { "$ref": "#/$defs/strings" },
+        "missingUrls": { "$ref": "#/$defs/strings" },
+        "unexpectedUrls": { "$ref": "#/$defs/strings" },
+        "missingCode": { "$ref": "#/$defs/strings" },
+        "unexpectedCode": { "$ref": "#/$defs/strings" },
+        "missingLinks": { "$ref": "#/$defs/strings" },
+        "unexpectedLinks": { "$ref": "#/$defs/strings" }
+      }
+    },
+    "lint": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["errorCount", "noticeCount", "errorRules", "items"],
+      "properties": {
+        "errorCount": { "type": "integer", "minimum": 0 },
+        "noticeCount": { "type": "integer", "minimum": 0 },
+        "errorRules": {
+          "type": "object",
+          "additionalProperties": { "type": "integer", "minimum": 1 }
+        },
+        "items": {
+          "type": "array",
+          "items": { "$ref": "finding.schema.json" }
+        }
+      }
+    },
+    "meaning": { "type": "string", "minLength": 1 }
+  },
+  "$defs": {
+    "sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" },
+    "strings": {
+      "type": "array",
+      "uniqueItems": true,
+      "items": { "type": "string", "minLength": 1 }
+    }
+  }
+}

package/data/checkResultV2.schema.json

@@ -0,0 +1,98 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://hanlint.dev/schemas/checkResultV2.schema.json",
+  "title": "hanlint Check Result v2",
+  "description": "A deterministic receipt for protected surface atoms, an exact heading outline, document shape, and lint findings.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "version",
+    "kind",
+    "violationCount",
+    "contractSha256",
+    "draftSha256",
+    "surface",
+    "missingFacts",
+    "lint",
+    "meaning",
+    "outline",
+    "document"
+  ],
+  "properties": {
+    "version": { "const": 2 },
+    "kind": { "const": "hanlint.checkResult" },
+    "violationCount": { "type": "integer", "minimum": 0 },
+    "contractSha256": { "$ref": "#/$defs/sha256" },
+    "draftSha256": { "$ref": "#/$defs/sha256" },
+    "missingFacts": { "type": "array", "items": { "type": "string" } },
+    "surface": { "$ref": "checkResult.schema.json#/properties/surface" },
+    "lint": { "$ref": "checkResult.schema.json#/properties/lint" },
+    "meaning": { "type": "string", "minLength": 1 },
+    "outline": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["matches", "level", "expected", "actual", "mismatches"],
+      "properties": {
+        "matches": { "type": "boolean" },
+        "level": { "type": "integer", "minimum": 1, "maximum": 6 },
+        "expected": { "$ref": "#/$defs/strings" },
+        "actual": { "$ref": "#/$defs/strings" },
+        "mismatches": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["position", "expected", "actual"],
+            "properties": {
+              "position": { "type": "integer", "minimum": 1 },
+              "expected": { "type": ["string", "null"] },
+              "actual": { "type": ["string", "null"] }
+            }
+          }
+        }
+      }
+    },
+    "document": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "sentenceCount",
+        "paragraphCount",
+        "sectionCount",
+        "wordCount",
+        "questionCount",
+        "readerCallCount",
+        "sections"
+      ],
+      "properties": {
+        "sentenceCount": { "type": "integer", "minimum": 0 },
+        "paragraphCount": { "type": "integer", "minimum": 0 },
+        "sectionCount": { "type": "integer", "minimum": 0 },
+        "wordCount": { "type": "integer", "minimum": 0 },
+        "questionCount": { "type": "integer", "minimum": 0 },
+        "readerCallCount": { "type": "integer", "minimum": 0 },
+        "sections": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["heading", "line", "paragraphCount", "codeBlockCount"],
+            "properties": {
+              "heading": { "type": "string" },
+              "line": { "type": "integer", "minimum": 1 },
+              "paragraphCount": { "type": "integer", "minimum": 0 },
+              "codeBlockCount": { "type": "integer", "minimum": 0 }
+            }
+          }
+        }
+      }
+    }
+  },
+  "$defs": {
+    "sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" },
+    "strings": {
+      "type": "array",
+      "items": { "type": "string" }
+    }
+  }
+}

package/data/finding.schema.json

@@ -0,0 +1,38 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://hanlint.dev/schemas/finding.schema.json",
+  "title": "hanlint Finding",
+  "description": "A deterministic prose issue with its location, reason, and optional local repair data.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["rule", "line", "severity", "scope", "at", "quote", "why"],
+  "properties": {
+    "rule": { "type": "string", "minLength": 1 },
+    "line": { "type": "integer", "minimum": 1 },
+    "severity": { "enum": ["error", "notice"] },
+    "scope": { "enum": ["sentence", "paragraph", "section", "document"] },
+    "at": { "type": "integer", "minimum": -1 },
+    "quote": { "type": "string", "minLength": 1 },
+    "why": { "type": "string", "minLength": 1 },
+    "fix": { "type": "string", "minLength": 1 },
+    "fragment": { "type": ["string", "null"] },
+    "replacement": { "type": "string" },
+    "candidates": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["text", "why"],
+        "properties": {
+          "text": { "type": "string", "minLength": 1 },
+          "why": { "type": "string", "minLength": 1 }
+        }
+      }
+    }
+  },
+  "dependentRequired": {
+    "fragment": ["replacement"],
+    "replacement": ["fragment"]
+  }
+}

package/data/patch.schema.json

@@ -0,0 +1,14 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://hanlint.dev/schemas/patch.schema.json",
+  "title": "hanlint Patch",
+  "description": "An exact local replacement connected to a named existing violation.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["reason", "before", "after"],
+  "properties": {
+    "reason": { "type": "string", "minLength": 1 },
+    "before": { "type": "string", "minLength": 1 },
+    "after": { "type": "string", "minLength": 1 }
+  }
+}

package/data/patchResult.schema.json

@@ -0,0 +1,86 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://hanlint.dev/schemas/patchResult.schema.json",
+  "title": "hanlint Patch Result",
+  "description": "A deterministic verification receipt for an exact prose Patch.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "version",
+    "kind",
+    "verified",
+    "violationCount",
+    "contractSha256",
+    "sourceSha256",
+    "patchSha256",
+    "resultSha256",
+    "matchCount",
+    "reason",
+    "newSurfaceIssues",
+    "newErrors",
+    "meaning"
+  ],
+  "properties": {
+    "version": { "const": 1 },
+    "kind": { "const": "hanlint.patchResult" },
+    "verified": { "type": "boolean" },
+    "violationCount": { "type": "integer", "minimum": 0 },
+    "contractSha256": { "$ref": "#/$defs/sha256" },
+    "sourceSha256": { "$ref": "#/$defs/sha256" },
+    "patchSha256": { "$ref": "#/$defs/sha256" },
+    "resultSha256": {
+      "oneOf": [
+        { "$ref": "#/$defs/sha256" },
+        { "type": "null" }
+      ]
+    },
+    "matchCount": { "type": "integer", "minimum": 0 },
+    "reason": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["name", "before", "after", "reduced"],
+      "properties": {
+        "name": { "type": "string", "minLength": 1 },
+        "before": { "type": "integer", "minimum": 0 },
+        "after": {
+          "oneOf": [
+            { "type": "integer", "minimum": 0 },
+            { "type": "null" }
+          ]
+        },
+        "reduced": { "type": "boolean" }
+      }
+    },
+    "newSurfaceIssues": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["kind", "value"],
+        "properties": {
+          "kind": {
+            "enum": [
+              "missingNumbers",
+              "unexpectedNumbers",
+              "missingUrls",
+              "unexpectedUrls",
+              "missingCode",
+              "unexpectedCode",
+              "missingLinks",
+              "unexpectedLinks"
+            ]
+          },
+          "value": { "type": "string", "minLength": 1 }
+        }
+      }
+    },
+    "newErrors": {
+      "type": "array",
+      "items": { "$ref": "finding.schema.json" }
+    },
+    "meaning": { "type": "string", "minLength": 1 }
+  },
+  "$defs": {
+    "sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" }
+  }
+}

package/data/patchResultV2.schema.json

@@ -0,0 +1,71 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://hanlint.dev/schemas/patchResultV2.schema.json",
+  "title": "hanlint Patch Result v2",
+  "description": "A deterministic verification receipt for a version 2 Reader Contract patch.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "version",
+    "kind",
+    "verified",
+    "violationCount",
+    "contractSha256",
+    "sourceSha256",
+    "patchSha256",
+    "resultSha256",
+    "matchCount",
+    "reason",
+    "newContractIssues",
+    "newErrors",
+    "meaning"
+  ],
+  "properties": {
+    "version": { "const": 2 },
+    "kind": { "const": "hanlint.patchResult" },
+    "verified": { "type": "boolean" },
+    "violationCount": { "type": "integer", "minimum": 0 },
+    "contractSha256": { "$ref": "patchResult.schema.json#/$defs/sha256" },
+    "sourceSha256": { "$ref": "patchResult.schema.json#/$defs/sha256" },
+    "patchSha256": { "$ref": "patchResult.schema.json#/$defs/sha256" },
+    "resultSha256": {
+      "oneOf": [
+        { "$ref": "patchResult.schema.json#/$defs/sha256" },
+        { "type": "null" }
+      ]
+    },
+    "matchCount": { "type": "integer", "minimum": 0 },
+    "reason": { "$ref": "patchResult.schema.json#/properties/reason" },
+    "newContractIssues": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["kind", "value"],
+        "properties": {
+          "kind": {
+            "enum": [
+              "missingNumbers",
+              "unexpectedNumbers",
+              "missingUrls",
+              "unexpectedUrls",
+              "missingCode",
+              "unexpectedCode",
+              "missingLinks",
+              "unexpectedLinks",
+              "outline",
+              "lockedFacts",
+              "editPolicy"
+            ]
+          },
+          "value": { "type": "string", "minLength": 1 }
+        }
+      }
+    },
+    "newErrors": {
+      "type": "array",
+      "items": { "$ref": "finding.schema.json" }
+    },
+    "meaning": { "type": "string", "minLength": 1 }
+  }
+}