@yuu1111/comment-check 0.0.0 → 1.0.1

package/README.ja.md

@@ -0,0 +1,49 @@
+[English](README.md)
+
+# @yuu1111/comment-check
+
+baselineを持つ小さなcomment検査 抑制commentとplaceholder commentの増殖を止める
+
+## Install
+
+```bash
+bun add -D @yuu1111/comment-check
+```
+
+## Usage
+
+現在の検出を一度baselineへ記録し、新しく出たものだけを失敗にする
+
+```bash
+comment-check --update-baseline .
+comment-check .
+```
+
+```
+src/queue.ts:18:2 undocumented-directive TypeScript directive needs a description
+Checked 42 files: 1 new, 0 resolved, 3 baselined
+```
+
+## Rules
+
+| Rule | 検出対象 |
+|------|---------|
+| `broad-suppression` | `biome-ignore-all`、`@ts-nocheck`、ruleを書いていない `eslint-disable` |
+| `undocumented-directive` | 説明の無い `@ts-ignore` と `@ts-expect-error` |
+| `placeholder-comment` | `TODO`、`FIXME`、`XXX`、`HACK` |
+| `separator-comment` | 記号だけで作った装飾comment |
+
+## Options
+
+| Option | Description |
+|--------|-------------|
+| `--baseline <path>` | 読み書きするbaseline file（既定は `comment-baseline.json`） |
+| `--ignore <path>` | 検査から外すpath 複数指定できる |
+| `--update-baseline` | baselineを現在の検出で置き換える |
+| `--json` | 新規と解消済みの検出をJSONで出力する |
+
+## Notes
+
+生成物のディレクトリなどProjectが持つpathは `--ignore` で検査から外す 例えば `--ignore src/generated`
+
+baselineはrule、file、comment本文をキーにするため、行が動いてもそのcommentを新規とは報告しない Biomeは `biome-ignore` の理由と未使用の抑制を既に扱うため、このcheckerはBiomeが読まないcommentの細部だけを担当する

package/README.md

@@ -1,3 +1,5 @@
+[日本語](README.ja.md)
+
 # @yuu1111/comment-check
 
 Small comment checker with a baseline, used to keep suppressions and placeholder

package/package.json

@@ -1,26 +1,27 @@
-{
-  "name": "@yuu1111/comment-check",
-  "version": "0.0.0",
-  "description": "Shared comment and suppression checker",
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/yuu1111/configs.git",
-    "directory": "packages/comment-check"
-  },
-  "type": "module",
-  "bin": {
-    "comment-check": "src/cli.ts"
-  },
-  "exports": {
-    ".": "./src/scan.ts"
-  },
-  "files": [
-    "src"
-  ],
-  "keywords": [
-    "comment",
-    "lint",
-    "suppression"
-  ]
-}
+{
+	"name": "@yuu1111/comment-check",
+	"version": "1.0.1",
+	"description": "Shared comment and suppression checker",
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/yuu1111/configs.git",
+		"directory": "packages/comment-check"
+	},
+	"type": "module",
+	"bin": {
+		"comment-check": "src/cli.ts"
+	},
+	"exports": {
+		".": "./src/scan.ts"
+	},
+	"files": [
+		"README.ja.md",
+		"src"
+	],
+	"keywords": [
+		"comment",
+		"lint",
+		"suppression"
+	]
+}

package/src/baseline.ts

@@ -1,5 +1,6 @@
 import type { Finding } from "./rules";
 
+/** baselineに記録する指摘1件の識別情報と件数 */
 export interface BaselineEntry {
 	rule: string;
 	file: string;
@@ -7,16 +8,19 @@ export interface BaselineEntry {
 	count: number;
 }
 
+/** baseline fileの形式と記録済みentryの一覧 */
 export interface BaselineFile {
 	version: 1;
 	entries: BaselineEntry[];
 }
 
+/** baselineと現在の指摘を比較した結果 */
 export interface BaselineComparison {
 	added: Finding[];
 	resolved: BaselineEntry[];
 }
 
+/** entryをbaseline上で一意に識別するkeyを返す */
 export function entryKey(entry: {
 	rule: string;
 	file: string;
@@ -34,6 +38,7 @@ function compareEntries(left: BaselineEntry, right: BaselineEntry): number {
 	return leftKey < rightKey ? -1 : 1;
 }
 
+/** 指摘一覧を件数付きentryへ集計してbaselineを作成する */
 export function createBaseline(findings: Finding[]): BaselineFile {
 	const entries = new Map<string, BaselineEntry>();
 	for (const finding of findings) {
@@ -53,6 +58,7 @@ export function createBaseline(findings: Finding[]): BaselineFile {
 	return { version: 1, entries: [...entries.values()].sort(compareEntries) };
 }
 
+/** 現在の指摘とbaselineを突き合わせ、新規追加分と解消済み分を求める */
 export function compareWithBaseline(
 	findings: Finding[],
 	baseline: BaselineFile,

package/src/comments.ts

@@ -1,5 +1,7 @@
+/** 抽出するcommentの種別 */
 export type CommentKind = "line" | "block";
 
+/** 抽出したcomment1件の種別と原文上の位置 */
 export interface CommentPiece {
 	kind: CommentKind;
 	text: string;
@@ -226,6 +228,7 @@ function step(state: ScanState, source: string): void {
 	stepExpression(state, source);
 }
 
+/** 文字列や正規表現リテラルを除外してsourceからcommentを抽出する */
 export function extractComments(source: string): CommentPiece[] {
 	const shebang = source.startsWith("#!") ? source.indexOf("\n") : 0;
 	const state: ScanState = {

package/src/rules.ts

@@ -1,3 +1,4 @@
+/** comment-checkが報告するruleの識別子一覧 */
 export const RULE_IDS = [
 	"broad-suppression",
 	"undocumented-directive",
@@ -5,8 +6,10 @@ export const RULE_IDS = [
 	"separator-comment",
 ] as const;
 
+/** RULE_IDSが定義するrule識別子のunion型 */
 export type RuleId = (typeof RULE_IDS)[number];
 
+/** 検出したcomment違反1件の内容と位置 */
 export interface Finding {
 	rule: RuleId;
 	file: string;
@@ -19,6 +22,7 @@ const PLACEHOLDER_PATTERN = /\b(TODO|FIXME|XXX|HACK)\b/;
 const SEPARATOR_PATTERN = /^[-=*_#~+./\\|]{4,}$/;
 const DIRECTIVE_PATTERN = /^@ts-(?:ignore|expect-error)\b([\s\S]*)$/;
 
+/** block commentの記号を除いて空白を揃えた本文を返す */
 export function normalizeComment(body: string): string {
 	return body
 		.split("\n")
@@ -28,6 +32,7 @@ export function normalizeComment(body: string): string {
 		.trim();
 }
 
+/** comment本文を分類し、該当するruleがなければnullを返す */
 export function classifyComment(body: string): RuleId | null {
 	const text = normalizeComment(body);
 	if (text === "") {

package/src/scan.ts

@@ -22,6 +22,7 @@ const IGNORED_DIRECTORIES = new Set([
 	"vendor",
 ]);
 
+/** 区切り文字を統一し先頭の./と末尾の/を除いたpathを返す */
 export function normalizePath(path: string): string {
 	return path.split("\\").join("/").replace(/^\.\//, "").replace(/\/+$/, "");
 }
@@ -75,6 +76,7 @@ function walk(directory: string, files: Set<string>): void {
 	}
 }
 
+/** 対象pathを走査して検査対象のfile一覧を集める */
 export function collectFiles(
 	targets: string[],
 	cwd = process.cwd(),
@@ -105,6 +107,7 @@ export function collectFiles(
 		.sort();
 }
 
+/** source文字列を走査してcomment違反を検出する */
 export function scanSource(source: string, file: string): Finding[] {
 	const findings: Finding[] = [];
 	for (const comment of extractComments(source)) {
@@ -124,6 +127,7 @@ export function scanSource(source: string, file: string): Finding[] {
 	return findings;
 }
 
+/** fileを読み込んでcomment違反を検出する */
 export function scanFile(file: string, cwd = process.cwd()): Finding[] {
 	return scanSource(
 		readFileSync(file, "utf8"),
@@ -131,6 +135,7 @@ export function scanFile(file: string, cwd = process.cwd()): Finding[] {
 	);
 }
 
+/** 複数fileの違反をまとめて位置順に並べる */
 export function scanFiles(files: string[], cwd = process.cwd()): Finding[] {
 	const findings: Finding[] = [];
 	for (const file of files) {