@kongyo2/ts-comment-scanner 1.10.0 → 1.11.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -11,103 +11,164 @@
11
11
  ![CodeRabbit Pull Request Reviews](https://img.shields.io/coderabbit/prs/github/kongyo2/ts-comment-scanner?utm_source=oss&utm_medium=github&utm_campaign=kongyo2%2Fts-comment-scanner&labelColor=171717&color=FF570A&link=https%3A%2F%2Fcoderabbit.ai&label=CodeRabbit+Reviews)
12
12
  [![node](https://img.shields.io/node/v/@kongyo2/ts-comment-scanner.svg)](https://nodejs.org)
13
13
  [![license](https://img.shields.io/npm/l/@kongyo2/ts-comment-scanner.svg)](./LICENSE)
14
- [![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/kongyo2/ts-comment-scanner)
14
+ [![DeepWiki](https://img.shields.io/badge/DeepWiki-kongyo2%2Fts--comment--scanner-blue.svg?logo=data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAACwAAAAyCAYAAAAnWDnqAAAAAXNSR0IArs4c6QAAA05JREFUaEPtmUtyEzEQhtWTQyQLHNak2AB7ZnyXZMEjXMGeK/AIi+QuHrMnbChYY7MIh8g01fJoopFb0uhhEqqcbWTp06/uv1saEDv4O3n3dV60RfP947Mm9/SQc0ICFQgzfc4CYZoTPAswgSJCCUJUnAAoRHOAUOcATwbmVLWdGoH//PB8mnKqScAhsD0kYP3j/Yt5LPQe2KvcXmGvRHcDnpxfL2zOYJ1mFwrryWTz0advv1Ut4CJgf5uhDuDj5eUcAUoahrdY/56ebRWeraTjMt/00Sh3UDtjgHtQNHwcRGOC98BJEAEymycmYcWwOprTgcB6VZ5JK5TAJ+fXGLBm3FDAmn6oPPjR4rKCAoJCal2eAiQp2x0vxTPB3ALO2CRkwmDy5WohzBDwSEFKRwPbknEggCPB/imwrycgxX2NzoMCHhPkDwqYMr9tRcP5qNrMZHkVnOjRMWwLCcr8ohBVb1OMjxLwGCvjTikrsBOiA6fNyCrm8V1rP93iVPpwaE+gO0SsWmPiXB+jikdf6SizrT5qKasx5j8ABbHpFTx+vFXp9EnYQmLx02h1QTTrl6eDqxLnGjporxl3NL3agEvXdT0WmEost648sQOYAeJS9Q7bfUVoMGnjo4AZdUMQku50McDcMWcBPvr0SzbTAFDfvJqwLzgxwATnCgnp4wDl6Aa+Ax283gghmj+vj7feE2KBBRMW3FzOpLOADl0Isb5587h/U4gGvkt5v60Z1VLG8BhYjbzRwyQZemwAd6cCR5/XFWLYZRIMpX39AR0tjaGGiGzLVyhse5C9RKC6ai42ppWPKiBagOvaYk8lO7DajerabOZP46Lby5wKjw1HCRx7p9sVMOWGzb/vA1hwiWc6jm3MvQDTogQkiqIhJV0nBQBTU+3okKCFDy9WwferkHjtxib7t3xIUQtHxnIwtx4mpg26/HfwVNVDb4oI9RHmx5WGelRVlrtiw43zboCLaxv46AZeB3IlTkwouebTr1y2NjSpHz68WNFjHvupy3q8TFn3Hos2IAk4Ju5dCo8B3wP7VPr/FGaKiG+T+v+TQqIrOqMTL1VdWV1DdmcbO8KXBz6esmYWYKPwDL5b5FA1a0hwapHiom0r/cKaoqr+27/XcrS5UwSMbQAAAABJRU5ErkJggg==)](https://deepwiki.com/kongyo2/ts-comment-scanner)
15
+ <!-- DeepWiki badge generated by https://deepwiki.ryoppippi.com/ -->
15
16
 
16
- **日本語** | [English](./README.en.md) | 📘 [プロジェクトサイト](https://kongyo2.github.io/ts-comment-scanner/)
17
+ [日本語](#日本語) | [English](#english) | 📘 [プロジェクトサイト](https://kongyo2.github.io/ts-comment-scanner/) / [Project site](https://kongyo2.github.io/ts-comment-scanner/?lang=en)
17
18
 
18
- TypeScript プロジェクト内のコメントを検出・一覧・集計し、安全に削除もできる CLI / ライブラリです。TypeScript の AST を使って解析するため、文字列・テンプレートリテラル・正規表現・JSX テキストを誤検出しません。
19
+ ## 日本語
19
20
 
20
- ## 特徴
21
+ TypeScript のコメントを一覧し、不要なものを安全に削除する CLI とライブラリです。コーディングエージェントがコードに書き足した「レビューの指摘に従い修正」のような経緯のコメントを、エージェントが触ったファイルから取り除く用途を想定しています。
21
22
 
22
- - `.ts` `.tsx` `.mts` `.cts` を再帰的にスキャン(`node_modules` と `.git` は除外)。シンボリックリンクは明示指定時と同様に走査中も追跡し、循環は自動検知して停止
23
- - 行コメント (`//`) とブロックコメント (`/* */`) を位置情報つきで報告
24
- - テキスト / JSON / **GitHub Actions アノテーション**の 3 形式で出力
25
- - `@ts-ignore` や `eslint-disable` などの**コンパイラ・リンター指示子(ディレクティブ)を自動判別**し、絞り込み・除外が可能
26
- - **安全なコメント削除**(コードクリーンアップ): ディレクティブとライセンスヘッダーはデフォルトで保持
27
- - UTF-8(BOM 付き可)と BOM 付き UTF-16(LE/BE)に対応。削除時もエンコーディングと BOM を保持し、不正なエンコーディングのファイルは**変更せずに**エラー報告
28
- - Glob による**カスタム無視パターン** (`--ignore`、`dist/` のような末尾スラッシュでディレクトリ限定)、対象拡張子の変更 (`--ext`、JavaScript は JSX を有効にして解析)
29
- - **git 連携 (`--diff`)**: 特定コミット間や未コミットの変更で触れられたファイルだけに対象を絞り込み
30
- - CI 向けの `--fail-on-comment`(コメント検出時に終了コード 1)
31
- - CLI としても、ライブラリとしても利用可能
23
+ - コメントは TypeScript のパーサーで取り出すので、文字列・テンプレートリテラル・正規表現・JSX テキストの中の `//` や `/*` をコメントと取り違えません。
24
+ - `@ts-expect-error`・`eslint-disable`・`webpackChunkName:` のように、消すとビルドやリントの結果が変わるコメント(ディレクティブ)と、ライセンス表記は残します。
25
+ - `--diff` を付けると、git で変更があったファイルだけを対象にします。
26
+ - 結果はテキスト・JSON・GitHub Actions のアノテーションで出力します。`--fail-on-comment` を付けると、コメントがあるときに CI を失敗させられます。
32
27
 
33
- ## インストール
28
+ ### インストール
34
29
 
35
30
  ```bash
36
- npm install @kongyo2/ts-comment-scanner
31
+ npm install --save-dev @kongyo2/ts-comment-scanner
37
32
  ```
38
33
 
39
- インストールせずに実行する場合:
34
+ インストールすると、npm scripts や `npx` から `ts-comment-scanner` コマンドを実行できます。インストールせずに `npx @kongyo2/ts-comment-scanner` で実行することもできます。
40
35
 
41
- ```bash
42
- npx @kongyo2/ts-comment-scanner src
36
+ ### 使い方
37
+
38
+ #### コメントを一覧する
39
+
40
+ `src/range.ts` を例にします。
41
+
42
+ ```ts
43
+ import { normalize } from "./normalize.js";
44
+
45
+ // レビューの指摘に従い、空の範囲では HEAD を返すようにした
46
+ export function resolveRange(input: string) {
47
+ if (input === "") return "HEAD"; // 指摘どおり修正
48
+ // @ts-expect-error 上流から null が渡ることがある
49
+ return normalize(input);
50
+ }
51
+ ```
52
+
53
+ パスを渡すと、コメントを `ファイル:行:桁` の位置つきで一覧します。ディレクティブには `[@ts-expect-error]` のように名前が付きます。
54
+
55
+ ```console
56
+ $ ts-comment-scanner src
57
+ src/range.ts:3:1 [line] // レビューの指摘に従い、空の範囲では HEAD を返すようにした
58
+ src/range.ts:5:36 [line] // 指摘どおり修正
59
+ src/range.ts:6:3 [line] [@ts-expect-error] // @ts-expect-error 上流から null が渡ることがある
60
+
61
+ 3 comments across 1 file
43
62
  ```
44
63
 
45
- ## CLI の使い方
64
+ #### コメントを削除する
46
65
 
66
+ `--remove --dry-run` で、ファイルを変えずに削除対象を確かめます。
67
+
68
+ ```console
69
+ $ ts-comment-scanner --remove --dry-run src
70
+ src/range.ts: would remove 2 (kept 1)
71
+
72
+ Would remove 2 comments across 1 file. Kept 1 protected comment.
47
73
  ```
48
- ts-comment-scanner [options] [paths...]
49
74
 
50
- 出力:
51
- --format <fmt> 出力形式: text / json / github(既定: text)
52
- --json --format json の短縮形
75
+ `--dry-run` を外すと削除します。経緯のコメントが消え、`@ts-expect-error` は残ります。
53
76
 
54
- フィルタリング:
55
- --ignore <glob> Glob に一致するファイル・ディレクトリを除外(複数指定可)
56
- --ext <list> スキャン対象の拡張子(カンマ区切り、既定: .ts,.tsx,.mts,.cts)
57
- --diff <range> git で変更されたファイルのみを対象(例: HEAD, main..HEAD)
58
- --skip-directives コンパイラ・リンター指示子を結果から除外
59
- --only-directives 指示子のみを報告
77
+ ```ts
78
+ import { normalize } from "./normalize.js";
60
79
 
61
- CI:
62
- --fail-on-comment コメントが報告された場合に終了コード 1 で終了
80
+ export function resolveRange(input: string) {
81
+ if (input === "") return "HEAD";
82
+ // @ts-expect-error 上流から null が渡ることがある
83
+ return normalize(input);
84
+ }
85
+ ```
63
86
 
64
- 削除:
65
- --remove 報告対象のコメントをファイルから削除(インプレース)
66
- --dry-run --remove と併用: 変更せずに削除対象のみ表示
67
- --remove-directives --remove と併用: 指示子コメントも削除
68
- --remove-legal --remove と併用: ライセンス・法的コメントも削除
87
+ ディレクティブも消すときは `--remove-directives`、ライセンス表記も消すときは `--remove-legal` を付けます。プロジェクト独自のツールが読む目印のように、ほかにも残したいコメントがあれば `--keep` に正規表現で指定します。
69
88
 
70
- その他:
71
- -h, --help ヘルプを表示
72
- -v, --version バージョンを表示
89
+ ```bash
90
+ ts-comment-scanner --remove --keep "@skipMangle" --keep "^// INJECT" src
73
91
  ```
74
92
 
75
- パスを省略するとカレントディレクトリを対象にします。スラッシュを含まない Glob(例: `*.test.ts`)はファイル名に、含むもの(例: `src/legacy/**`)はパスに一致します。`.gitignore` と同様に、末尾がスラッシュのパターン(例: `dist/`)はディレクトリだけに一致します。明示的に指定したファイルは `--ignore` の対象になりません。
93
+ 何を残し、削除後のコードをどう整えるかは[削除の動作](#削除の動作)にまとめています。
76
94
 
77
- `--ext` で JavaScript(`.js` `.jsx` `.mjs` `.cjs`)を追加した場合は、TypeScript 本体と同じく JSX を有効にして解析するため、React コンポーネント内の `<div>http://…</div>` のようなテキストをコメントと誤検出しません。
95
+ #### 変更したファイルだけを対象にする
78
96
 
79
- **終了コード**: `0` 成功 / `1` `--fail-on-comment` 指定時にコメントを検出 / `2` 引数・実行時エラー
97
+ `--diff <range>` を付けると、git が変更ありと報告するファイルだけを対象にします。`<range>` には `git diff` に渡すリビジョンをそのまま書きます。
80
98
 
81
- ### 出力例
99
+ - `HEAD` のようにリビジョンを 1 つだけ書くと、作業ツリーと比べます。まだ追跡していない新しいファイルも対象です(`.gitignore` に一致するものは除きます)。
100
+ - `main..HEAD` や `main...HEAD` のように書くと、コミット同士を比べます。
82
101
 
83
102
  ```bash
84
- $ ts-comment-scanner src
85
- src/index.ts:1:1 [line] // エントリーポイント
86
- src/scanner.ts:8:3 [block] /* AST を走査する */
87
- src/legacy.ts:3:1 [line] [@ts-ignore] // @ts-ignore 後で直す
103
+ # 未コミットの変更があるファイルで、削除対象を確かめる
104
+ ts-comment-scanner --remove --dry-run --diff HEAD
88
105
 
89
- 3 comments across 3 files
106
+ # ブランチで変更したファイルからコメントを削除する
107
+ ts-comment-scanner --remove --diff main...HEAD
90
108
  ```
91
109
 
92
- JSON 出力:
110
+ 範囲内で削除されたファイルは対象外になり、名前を変えたファイルは新しいパスで扱います。`--diff` は、コマンドラインで直接指定したファイルにも適用します。git は、最初に指定したパスがあるリポジトリで実行します。
93
111
 
94
- ```bash
95
- $ ts-comment-scanner --json src
112
+ #### CI で使う
113
+
114
+ `--format github` を付けると、コメントを GitHub Actions のアノテーションとして出力し、PR の該当行に表示します。`--fail-on-comment` を付けると、コメントを 1 件でも報告したときに終了コード 1 で終わります。
115
+
116
+ ```yaml
117
+ - name: Check for stray comments
118
+ run: npx @kongyo2/ts-comment-scanner --format github --skip-directives --fail-on-comment src
119
+ ```
120
+
121
+ ### 削除の動作
122
+
123
+ `--remove` が削除するのは、TypeScript のパーサーがコメントと判定した範囲だけです。次のコメントは残します。
124
+
125
+ - **ディレクティブ**: 対象のツールは[ディレクティブの判定](#ディレクティブの判定)にまとめています。`/** @internal */` も、消すと `stripInternal` で除いていた宣言が `.d.ts` に出てしまうので残します。`--remove-directives` を付けると削除します。
126
+ - **ライセンス表記**: `/*! … */`・`//! …` の形のコメント、`@license`・`@preserve`・`@copyright` や `SPDX-License-Identifier:` などの SPDX タグを含むコメント、`Copyright (c) …`・`© 2024 …`・`Licensed under …`・`All rights reserved` のような著作権表示、MIT・BSD・MPL・GPL の許諾文です。`--remove-legal` を付けると削除します。
127
+ - **`--keep` の正規表現に一致するコメント**: `--remove-directives` や `--remove-legal` を付けても残ります。
128
+ - **消すとディレクティブの効き方が変わるコメント**: たとえば `eslint-disable-next-line` の直下にあるコメント行を消すと、ディレクティブの適用先が次の行にずれます。ファイルの最初のコメントでだけ効く prettier の `@format` は、手前のコメントを消すと効き始めます。このように効き方が変わる削除はせず、そのコメントを残します。
129
+
130
+ 削除した後のコードは次のように整えます。
131
+
132
+ - コメントだけの行は行ごと、行末のコメントは手前の空白ごと削除します。空行に挟まれたコメント行を消したときは空行を 1 行にまとめ、ファイルやブロックの先頭・末尾でコメントとコードを隔てていた空行は一緒に削除します。
133
+ - トークンがつながる位置には空白を入れます(`a/* x */b` → `a b`)。コードに挟まれた、改行を含むブロックコメントは改行に置き換え、自動セミコロン挿入による文の区切りを保ちます。
134
+ - JSX の `{/* … */}` は波かっこごと削除します。波かっこを外すと表示されるテキストが変わる位置では、`{" "}` か `{}` を残します。
135
+
136
+ 書き込む前に削除後のソースを解析し直し、残したコメントの内容とディレクティブとしての意味、JSX の表示内容が変わっていないことを確かめます。一致しないファイルは書き換えず、エラーとして報告します。書き込みは一時ファイルを経由した置き換えなので、途中で失敗しても元のファイルは壊れません。
137
+
138
+ ファイルは UTF-8(BOM の有無は問いません)か BOM 付きの UTF-16 として読み、削除後も元の文字コードと BOM のまま書き戻します。正しくデコードできないファイルからはコメントを削除せず、エラーとして報告します。
139
+
140
+ ### 対象ファイルの指定
141
+
142
+ パスを省略するとカレントディレクトリが対象です。ディレクトリは再帰的にたどり、`node_modules` と `.git` は除外します。シンボリックリンクもたどります。
143
+
144
+ - `--ext` は対象の拡張子をカンマ区切りで指定します(既定: `.ts,.tsx,.mts,.cts`)。指定した一覧が既定の一覧に置き換わるので、JavaScript も対象にするなら `--ext .ts,.tsx,.js,.jsx` のようにすべて並べます。`.js`・`.jsx`・`.mjs`・`.cjs` は JSX を有効にして解析します。
145
+ - `--ignore` は Glob に一致するファイルとディレクトリを除外します。スラッシュを含まないパターン(`*.test.ts`)はファイル名に、含むパターン(`src/legacy/**`)はパスに一致します。`dist/` のように末尾をスラッシュにすると、ディレクトリだけに一致します。コマンドラインで直接指定したファイルには適用しません。
146
+
147
+ ### 出力形式
148
+
149
+ `--format` で `text`(既定)・`json`・`github` を選びます。
150
+
151
+ - `text`: 1 件を 1 行で `ファイル:行:桁 [line|block] [ディレクティブ名] 本文` の形に出力し、最後に件数を出力します。複数行のコメントは 1 行にまとめます。
152
+ - `json`: 下の形で出力します。`--json` は `--format json` と同じです。
153
+ - `github`: 各コメントを GitHub Actions の `::notice` コマンドとして出力します。
154
+
155
+ ```json
96
156
  {
97
- "summary": { "files": 1, "comments": 1, "directives": 0 },
157
+ "summary": { "files": 1, "comments": 1, "directives": 1 },
98
158
  "files": [
99
159
  {
100
- "file": "src/index.ts",
160
+ "file": "src/range.ts",
101
161
  "comments": [
102
162
  {
103
163
  "kind": "line",
104
- "text": "// エントリーポイント",
105
- "start": 0,
106
- "end": 12,
107
- "line": 1,
108
- "column": 1,
109
- "endLine": 1,
110
- "endColumn": 13
164
+ "text": "// @ts-expect-error 上流から null が渡ることがある",
165
+ "start": 174,
166
+ "end": 212,
167
+ "line": 6,
168
+ "column": 3,
169
+ "endLine": 6,
170
+ "endColumn": 41,
171
+ "directive": "@ts-expect-error"
111
172
  }
112
173
  ]
113
174
  }
@@ -115,127 +176,332 @@ $ ts-comment-scanner --json src
115
176
  }
116
177
  ```
117
178
 
118
- ディレクティブと判定されたコメントには `"directive": "@ts-ignore"` のように名前が付きます。
179
+ `line`・`column` は 1 始まりで、`endColumn` はコメントの最後の文字の次の桁です。`start`・`end` は、ファイルをデコードして BOM を除いたテキストでの 0 始まりの位置(JavaScript の文字列のインデックス)です。`directive` は、ディレクティブと判定したコメントにだけ付きます。
119
180
 
120
- ### GitHub Actions で使う
181
+ `--remove` と組み合わせると、`files` の各要素は `removed`・`kept`・`skipped` の 3 つの配列を持ちます。`skipped` は、`--skip-directives` か `--only-directives` で対象から外したコメントです。`summary` には、それぞれの件数(`removed`・`kept`・`skipped`)、`files` 配列の要素数(`files`)、実際にコメントを削除したファイル数(`changedFiles`)、`dryRun` が入ります。
121
182
 
122
- `--format github` は各コメントを [workflow command](https://docs.github.com/actions/reference/workflow-commands-for-github-actions) として出力するため、PR の該当行にアノテーションが表示されます。
183
+ ### オプション
123
184
 
124
- ```yaml
125
- - name: Check for stray comments
126
- run: npx @kongyo2/ts-comment-scanner --format github --skip-directives --fail-on-comment src
185
+ | オプション | 説明 |
186
+ | --- | --- |
187
+ | `--format <fmt>` | 出力形式。`text`・`json`・`github`(既定: `text`) |
188
+ | `--json` | `--format json` と同じ |
189
+ | `--ignore <glob>` | Glob に一致するファイル・ディレクトリを除外する(複数指定可) |
190
+ | `--ext <list>` | 対象の拡張子(カンマ区切り、既定: `.ts,.tsx,.mts,.cts`) |
191
+ | `--diff <range>` | git で変更があったファイルだけを対象にする |
192
+ | `--skip-directives` | ディレクティブを結果から除く |
193
+ | `--only-directives` | ディレクティブだけを報告する |
194
+ | `--fail-on-comment` | コメントを報告したら終了コード 1 で終わる |
195
+ | `--remove` | 報告したコメントをファイルから削除する |
196
+ | `--dry-run` | `--remove` と併用。ファイルを変えずに削除対象を表示する |
197
+ | `--remove-directives` | `--remove` と併用。ディレクティブも削除する |
198
+ | `--remove-legal` | `--remove` と併用。ライセンス表記も削除する |
199
+ | `--keep <regex>` | `--remove` と併用。正規表現に一致するコメントを残す(複数指定可) |
200
+ | `-h`, `--help` | ヘルプを表示する |
201
+ | `-v`, `--version` | バージョンを表示する |
202
+
203
+ 終了コードは、`0` が正常終了、`1` が `--fail-on-comment` を付けてコメントを報告したとき、`2` が引数の誤りや実行時のエラーです。
204
+
205
+ ### ディレクティブの判定
206
+
207
+ 次のツールが読むコメントを、ディレクティブとして判定します。
208
+
209
+ - **コンパイラ・型**: TypeScript(`@ts-ignore`・`@ts-expect-error`・`@ts-nocheck`・`@ts-check`・`/// <reference>`・`@internal`)、Deno(`@deno-types=`・`@ts-types=`・`@ts-self-types=`)、typescript-strict-plugin(`@ts-strict`・`@ts-strict-ignore`)、Flow(`@flow`・`@noflow`・`$FlowFixMe` 系・`flowlint`)
210
+ - **リンター**: ESLint(`eslint-disable` 系・`/* eslint … */`・`eslint-env`・`/* global */`・`/* exported */`・`// falls through`・`// no default`)、React Compiler(react-hooks のルールを止める `eslint-disable`・`$FlowFixMe[react-rule…]`)、oxlint(`oxlint-disable` 系)、Biome(`biome-ignore` 系・`rome-ignore`)、deno lint(`deno-lint-ignore` 系)、stylelint(`stylelint-disable` 系)、ast-grep(`ast-grep-ignore`)、TSLint・JSHint・JSCS・JSLint
211
+ - **フォーマッタ**: prettier(`prettier-ignore`・`@format` などの pragma・`/** @type */` の型キャスト)、oxfmt(`oxfmt-ignore`)、dprint・deno fmt(`dprint-ignore`・`deno-fmt-ignore` とそれぞれの `-file` 版)、import の並べ替え(`organize-imports-ignore`・`sort-imports-ignore`)、js-beautify
212
+ - **カバレッジ・テスト**: istanbul・c8・v8(`istanbul ignore` など)、Node.js(`node:coverage`)、Deno(`deno-coverage-ignore` 系)、Jest・Vitest(`@jest-environment`・`@vitest-environment`・`@module-tag`)、Stryker、type-coverage、ts-prune
213
+ - **バンドラ・ランタイム**: webpack・Turbopack のマジックコメント(`webpackChunkName:` など)、Vite(`@vite-ignore`)、terser・Rollup の注釈(`#__PURE__`・`@__NO_SIDE_EFFECTS__` など)、Bun(`// @bun`)、React Refresh・solid-refresh(`@refresh`)、Million.js、Nx、UnoCSS、Next.js の codemod、`/* GraphQL */`・`/* HTML */` タグ、`//# sourceMappingURL=`、`@jsx` 系の pragma
214
+ - **セキュリティ・静的解析**: SonarQube(`NOSONAR`)、Semgrep(`nosemgrep`)、CodeQL(`lgtm[…]`・`codeql[…]`)、DeepSource(`skipcq`)、Snyk Code(`deepcode ignore`)、Datadog(`no-dd-sa`)、gitleaks、TruffleHog、detect-secrets
215
+ - **スペルチェック**: cspell(`cspell:` など)、`LocalWords`、codespell
216
+ - **エディタ・IDE**: VS Code・JetBrains(`#region`)、JetBrains(`noinspection`・`<editor-fold>`・`language=`)、ReSharper
217
+
218
+ 判定は、各ツールのパーサーと同じ規則で行います。ファイルの先頭や `switch` 文の特定の位置でだけ効くディレクティブは、その位置にあるときだけディレクティブとして扱います。ツールやバージョンによって解釈が分かれる書き方は、どれか 1 つでも有効とみなせばディレクティブとして扱うので、`--remove` では残ります。TypeScript のディレクティブは、tsc 6 と tsc 7 のどちらかが有効とみなすものが対象です。
219
+
220
+ ### ライブラリとして使う
221
+
222
+ ```ts
223
+ import { scanPaths, scanComments, removeComments, changedFiles, formatText } from "@kongyo2/ts-comment-scanner";
224
+
225
+ // ファイルやディレクトリをまとめてスキャンする
226
+ const results = await scanPaths(["src"], { ignore: ["**/*.test.ts"] });
227
+ console.log(formatText(results));
228
+
229
+ // ソース文字列をスキャンする
230
+ const comments = scanComments("// hello\nconst x = 1;");
231
+
232
+ // コメントを削除する
233
+ const { code, removed, kept } = removeComments("// note\nconst x = 1;\n");
234
+
235
+ // git のリビジョン範囲で変更されたファイルの絶対パスを得る
236
+ const changed = await changedFiles("main..HEAD");
237
+ ```
238
+
239
+ | 関数 | 説明 |
240
+ | --- | --- |
241
+ | `scanComments(source, options?)` | ソース文字列のコメントを返す。`options.jsx` で JSX を有効にする |
242
+ | `scanFile(file)` | 1 ファイルをスキャンする |
243
+ | `scanPaths(inputs, options?)` | ファイルとディレクトリをまとめてスキャンする。`ignore`・`extensions`・`ignoreDirs` を指定できる |
244
+ | `collectFiles(inputs, options?)` | スキャン対象のファイルパスを集める |
245
+ | `changedFiles(range, cwd?)` | git のリビジョン範囲で変更されたファイルの絶対パスを返す |
246
+ | `removeComments(source, options?)` | コメントを削除する。`removeDirectives`・`removeLegal`・`keep`・`shouldRemove` を指定できる |
247
+ | `detectDirective(kind, text, placement?)` | ディレクティブなら正規化した名前を返す。`placement` を渡すと位置に依存する判定もする |
248
+ | `isLegalComment(text)` | ライセンス表記かどうかを返す |
249
+ | `isJsxFile(file)` | JSX を有効にして解析する拡張子かどうかを返す |
250
+ | `formatText(results)`・`formatJson(results)`・`formatGitHub(results)` | スキャン結果を各出力形式の文字列にする |
251
+ | `readFileText(file)`・`decodeFileText(data)`・`encodeFileText(text, target)` | 文字コードと BOM を保ってファイルの内容を読み書きする |
252
+ | `writeFileAtomic(file, data)` | 一時ファイルを経由してファイルを置き換える |
253
+
254
+ 型: `Comment`・`CommentKind`・`FileScanResult`・`ScanOptions`・`CollectOptions`・`RemoveOptions`・`RemoveResult`・`FileText`・`FileEncoding`・`DirectivePlacement`
255
+
256
+ ### 必要環境
257
+
258
+ Node.js 20 以上
259
+
260
+ ### ライセンス
261
+
262
+ MIT
263
+
264
+ ## English
265
+
266
+ A CLI and library that lists the comments in a TypeScript project and safely removes the ones you don't want. It is built for sweeping the narration coding agents add to code ("fixed per the review feedback") out of the files the agent touched.
267
+
268
+ - Comments come from the TypeScript parser, so `//` and `/*` inside strings, template literals, regular expressions and JSX text are never mistaken for comments.
269
+ - Directives such as `@ts-expect-error`, `eslint-disable` and `webpackChunkName:`, whose removal would change what your build or linter does, are kept, and so are license notices.
270
+ - `--diff` limits the work to the files git reports as changed.
271
+ - Results come out as text, JSON or GitHub Actions annotations, and `--fail-on-comment` fails a CI job when comments are found.
272
+
273
+ ### Installation
274
+
275
+ ```bash
276
+ npm install --save-dev @kongyo2/ts-comment-scanner
127
277
  ```
128
278
 
279
+ Once it is installed, npm scripts and `npx` can run the `ts-comment-scanner` command. To run it without installing, use `npx @kongyo2/ts-comment-scanner`.
280
+
281
+ ### Usage
282
+
283
+ #### Listing comments
284
+
285
+ Take `src/range.ts` as an example:
286
+
287
+ ```ts
288
+ import { normalize } from "./normalize.js";
289
+
290
+ // Per the review feedback, return HEAD for an empty range
291
+ export function resolveRange(input: string) {
292
+ if (input === "") return "HEAD"; // fixed as the reviewer asked
293
+ // @ts-expect-error upstream may pass null
294
+ return normalize(input);
295
+ }
129
296
  ```
130
- ::notice file=src/index.ts,line=1,endLine=1,col=1,endColumn=12,title=line comment::// エントリーポイント
297
+
298
+ Given a path, the command lists each comment with its `file:line:column` position. Directives are tagged with their name, such as `[@ts-expect-error]`.
299
+
300
+ ```console
301
+ $ ts-comment-scanner src
302
+ src/range.ts:3:1 [line] // Per the review feedback, return HEAD for an empty range
303
+ src/range.ts:5:36 [line] // fixed as the reviewer asked
304
+ src/range.ts:6:3 [line] [@ts-expect-error] // @ts-expect-error upstream may pass null
305
+
306
+ 3 comments across 1 file
131
307
  ```
132
308
 
133
- JSON 出力の `endColumn` が排他的(コメント末尾の次の桁)なのに対し、GitHub アノテーションの列は両端含みのため、ここでは最後の文字の桁(この例では 12)が出力されます。64 KiB を超える巨大なコメントは、GitHub の上限に収まるよう安全に切り詰められます。
309
+ #### Removing comments
134
310
 
135
- ### コメントの一括削除(コードクリーンアップ)
311
+ `--remove --dry-run` shows what would be removed without changing any file.
136
312
 
137
- ```bash
138
- # まず削除対象を確認
139
- ts-comment-scanner --remove --dry-run src
313
+ ```console
314
+ $ ts-comment-scanner --remove --dry-run src
315
+ src/range.ts: would remove 2 (kept 1)
140
316
 
141
- # 実際に削除(ディレクティブとライセンスヘッダーは保持される)
142
- ts-comment-scanner --remove src
317
+ Would remove 2 comments across 1 file. Kept 1 protected comment.
318
+ ```
319
+
320
+ Drop `--dry-run` to remove them. The narration goes, and the `@ts-expect-error` stays:
321
+
322
+ ```ts
323
+ import { normalize } from "./normalize.js";
143
324
 
144
- # 指示子・ライセンスも含めて完全に削除
145
- ts-comment-scanner --remove --remove-directives --remove-legal src
325
+ export function resolveRange(input: string) {
326
+ if (input === "") return "HEAD";
327
+ // @ts-expect-error upstream may pass null
328
+ return normalize(input);
329
+ }
146
330
  ```
147
331
 
148
- 削除は AST のコメント範囲に基づいて行われるため、文字列やコードには影響しません。さらに:
332
+ Add `--remove-directives` to remove directives too, and `--remove-legal` to remove license notices too. To keep other comments, such as markers your project's own tooling reads, pass a regular expression to `--keep`:
333
+
334
+ ```bash
335
+ ts-comment-scanner --remove --keep "@skipMangle" --keep "^// INJECT" src
336
+ ```
149
337
 
150
- - `@ts-expect-error` / `eslint-disable` などの指示子は、削除するとビルドやリントが壊れるため**デフォルトで保持**
151
- - `/*! ... */` や `@license` / `@preserve` / `@copyright`、`SPDX-License-Identifier:` / `SPDX-FileCopyrightText:` タグを含む法的コメントも**デフォルトで保持**
152
- - `@ts-expect-error` や `eslint-disable-next-line` など**次行を対象にする指示子の直下の行構造を保持**: 削除すると行が消えて指示子の適用先がずれる場合(コメントだけの行など)、その行のコメントは削除せずに保持
153
- - **指示子が対象を探す途中のコメントも保持**: 空行と `//` 行を読み飛ばして対象行を探す tsc の `@ts-ignore`/`@ts-expect-error` では、tsc 6・tsc 7 がそれぞれ読み飛ばせずに止まる最初の行(ブロックコメントの行など)を保持。対象の直前にある最後のコメントでのみ有効な指示子(`@deno-types`・`/* GraphQL */`・ESLint の `// falls through` など)では、指示子と対象の間のコメントをすべて保持
154
- - **位置依存ディレクティブを削除で有効化しない**: prettier の `@format`/`@prettier` pragma や Deno の `deno-coverage-ignore-file`(ファイル最初のコメントでのみ有効)、Bun の `// @bun`(ファイル先頭か shebang の次の行でのみ有効)が、手前のコメント削除によって保持コメント内で新たに効き始める場合は、その手前のコメントも保持
155
- - ブロックコメント除去でトークンが結合してしまう位置には空白を挿入(`a/* x */b` → `a b`)。括弧や区切り記号との間を空けていただけの空白は残さない(`f(/* x */ a)` → `f(a)`、`{/* x */}` → `{}`)
156
- - コメントだけの行は行ごと削除、行末コメントは手前の空白ごと削除
157
- - **空行を重複させない**: コメント行が消えた位置では、前後の空行を元のソースにあった最も広い間隔まで詰める(空行に挟まれたコメントを消しても空行は 1 行)。ファイルやブロック(`{`・`(`・`[`・JSX タグ)の先頭・末尾で、コメントとコードを隔てていただけの空行も一緒に削除。次行指示子の適用先になる空行は保持
158
- - **JSX のコメントは波かっこごと削除**: `{/* … */}` は `{ }` を残さず丸ごと削除(単独の行なら行ごと)。ただし波かっこが前後のテキストを区切っている場合は、外すと JSX のテキスト結合・空白除去で描画が変わるため、同じ描画になるなら `{" "}` に置き換え(行末の `<a /> {/* x */}` → `<a />{" "}`)、それ以外は `{}` を残す。削除後のソースを再解析し、各要素の子要素の描画結果を TypeScript・esbuild・Babel の空白規則で比較して検証。`{/* prettier-ignore */}` など次の兄弟要素に効く波かっこ内の指示子の直後にあるコメントコンテナは保持
159
- - 削除後のソースを再スキャンし、残ったコメントが保持対象とディレクティブの意味ごと一致することを検証。想定外の結果になる場合はファイルを変更せずエラー報告
160
- - 書き込みは一時ファイル経由のアトミック置換(書き込み失敗やディスクフルで元ファイルが壊れない)
338
+ [How removal works](#how-removal-works) covers what is kept and how the code is tidied up afterwards.
161
339
 
162
- `--remove --json` の `summary.files` は `files` 配列の件数(削除・保持・スキップのいずれかがあったファイル数)、`summary.changedFiles` は実際にコメントを削除したファイル数です。
340
+ #### Targeting changed files only
163
341
 
164
- ### 変更されたファイルだけを対象にする(`--diff`)
342
+ With `--diff <range>`, only the files git reports as changed are scanned or cleaned. The range is anything `git diff` accepts as revisions:
165
343
 
166
- `--diff <range>` を付けると、git が変更ありと報告するファイルだけにスキャン・削除を絞り込めます。範囲は `git diff` がリビジョンとして受け付ける書式そのままで、単一リビジョンなら作業ツリーとの比較(未追跡の新規ファイルも含む・`.gitignore` は尊重)、`a..b` / `a...b` ならコミット同士の比較になります。
344
+ - A single revision such as `HEAD` compares the working tree against it. Untracked new files count too, unless `.gitignore` matches them.
345
+ - `main..HEAD` or `main...HEAD` compares two commits.
167
346
 
168
347
  ```bash
169
- # 未コミットの変更があるファイルだけをスキャン
170
- ts-comment-scanner --diff HEAD
348
+ # Preview the removal in files with uncommitted changes
349
+ ts-comment-scanner --remove --dry-run --diff HEAD
171
350
 
172
- # ブランチで変更されたファイルだけからコメントを削除
351
+ # Remove comments from the files changed on the branch
173
352
  ts-comment-scanner --remove --diff main...HEAD
353
+ ```
354
+
355
+ Files deleted within the range are skipped, and renamed files are handled at their new path. `--diff` also applies to files listed explicitly on the command line. git runs in the repository that contains the first path given.
356
+
357
+ #### Using it in CI
358
+
359
+ `--format github` emits each comment as a GitHub Actions annotation, which shows up on the relevant line of the PR. With `--fail-on-comment`, the command exits with code 1 when it reports any comment.
174
360
 
175
- # 特定コミット間で変更されたファイルのみを CI でチェック
176
- ts-comment-scanner --fail-on-comment --diff a1b2c3..d4e5f6 src
361
+ ```yaml
362
+ - name: Check for stray comments
363
+ run: npx @kongyo2/ts-comment-scanner --format github --skip-directives --fail-on-comment src
177
364
  ```
178
365
 
179
- コーディングエージェントに作業させた後、その変更範囲だけを対象にノイズコメントを掃除する、といった使い方を想定しています。範囲内で削除されたファイルは対象外になり、リネームは新しいパスで扱われます。git は最初の入力パスが属するリポジトリで実行されるため、別リポジトリのパスを指定しても動作します。なお `--ignore` と異なり、明示的に指定したファイルにも絞り込みが適用されます。
366
+ ### How removal works
367
+
368
+ `--remove` deletes only the ranges the TypeScript parser reports as comments. These comments stay:
369
+
370
+ - **Directives.** [Directive detection](#directive-detection) lists the tools covered. `/** @internal */` stays as well, because without it `stripInternal` would let the declaration into the `.d.ts`. `--remove-directives` removes them.
371
+ - **License notices.** Comments shaped `/*! … */` or `//! …`; comments containing `@license`, `@preserve`, `@copyright` or an SPDX tag such as `SPDX-License-Identifier:`; copyright lines such as `Copyright (c) …`, `© 2024 …`, `Licensed under …` and `All rights reserved`; and the MIT, BSD, MPL and GPL grant texts. `--remove-legal` removes them.
372
+ - **Comments matching a `--keep` pattern,** even with `--remove-directives` or `--remove-legal`.
373
+ - **Comments whose removal would change how a directive applies.** Removing a comment line right below `eslint-disable-next-line`, for example, would move the directive onto the next line, and removing the comments in front of prettier's `@format`, which only counts in the file's first comment, would switch it on. Such comments are kept.
374
+
375
+ The code left behind is tidied up:
376
+
377
+ - Comment-only lines go entirely, and trailing comments go with the whitespace before them. Removing a comment line between two blank lines leaves one blank line, and at the start or end of the file or of a block, the blank lines that only separated the comment from the code go with it.
378
+ - A space is inserted where tokens would otherwise join (`a/* x */b` → `a b`). A multi-line block comment with code on both sides is replaced with a line break, so automatic semicolon insertion still splits the statements the same way.
379
+ - A JSX `{/* … */}` goes with its braces. Where dropping the braces would change the rendered text, `{" "}` or `{}` takes their place.
380
+
381
+ Before writing, the result is parsed again to confirm that the kept comments, their directive meaning and the rendered JSX are unchanged. A file that fails the check is left untouched and reported as an error. Files are replaced through a temporary file, so a failed write never truncates the original.
180
382
 
181
- ### 検出できるディレクティブ(抜粋)
383
+ Files are read as UTF-8 (with or without a BOM) or as UTF-16 with a BOM, and written back in the same encoding with the same BOM. A file that does not decode cleanly is reported as an error instead of being rewritten.
182
384
 
183
- 各ディレクティブは実ツールのパーサー実装(正規表現・文字列比較)に合わせて判定されます。ツールやバージョンによって解釈が分かれる場合は、いずれかが有効とみなす形をすべてディレクティブとして扱います(削除時は保持側に倒れます)。
385
+ ### Choosing files
184
386
 
185
- - **コンパイラ / 型**: `@ts-ignore` `@ts-expect-error` `@ts-nocheck` `@ts-check`(tsc 6・tsc 7、TypeScript ファイルを検査する Flow) / `/// <reference>` 系 / `@ts-strict-ignore`・`@ts-strict`(typescript-strict-plugin の CLI と IDE プラグイン) / `@deno-types=`・`@ts-types=`・`@ts-self-types=`(Deno)
186
- - **リンター**: `eslint-disable` 系・`eslint-env`・`/* global */`・`/* exported */`・`// falls through`(no-fallthrough)・`// no default`(default-case。いずれも ESLint が読む `case`・`default`・`}` の直前のみ) / React Compiler が読む `eslint-disable … react-hooks/…`・`$FlowFixMe[react-rule…]` / `oxlint-disable` 系 / `biome-ignore` 系・`rome-ignore` / `deno-lint-ignore` 系 / `stylelint-disable`・`stylelint-disable-line`・`stylelint-disable-next-line`・`stylelint-enable`(stylelint) / `@flow`・`@noflow`・`$FlowFixMe` 系・`flowlint` 系(Flow) / `tslint:`・`jshint`・`jscs:`・`jslint`(レガシー)
187
- - **フォーマッタ**: `prettier-ignore`・`@format`/`@prettier`/`@noformat`/`@noprettier` pragma・`/** @type */`/`/** @satisfies */` 型キャストコメント(prettier) / `oxfmt-ignore` / `dprint-ignore`・`dprint-ignore-file`・`deno-fmt-ignore`・`deno-fmt-ignore-file`(dprint / deno fmt) / `organize-imports-ignore`・`sort-imports-ignore` / `beautify ignore/preserve`(レガシー)
188
- - **カバレッジ / テスト**: `istanbul ignore`・`c8 ignore`・`v8 ignore`・`node:coverage`・`deno-coverage-ignore` 系 / `@jest-environment(-options)`・`@vitest-environment(-options)`・`@module-tag`(Vitest 4 以降) / `Stryker disable/restore` / `type-coverage:ignore-line/-next-line` / `ts-prune-ignore-next`
189
- - **バンドラ / ランタイム**: `webpackChunkName:` などの webpack・turbopack マジックコメント / `@vite-ignore` / `#__PURE__`・`@__NO_SIDE_EFFECTS__`・`@__INLINE__`・`@__KEY__`・`@__MANGLE_PROP__`(terser/rollup 注釈) / `// @bun`(Bun) / `@refresh reset/skip/reload/jsx-skip`(react-refresh / solid-refresh) / `million-ignore` / `nx-ignore-next-line`(Nx) / `@unocss-include/-ignore/-ide-include/-skip-start/-skip-end` / `@next-codemod-error/-ignore`(Next.js) / `/* GraphQL */`・`/* HTML */` タグコメント / `//# sourceMappingURL=`・`//# sourceURL=` / `@jsx` 系プラグマ(Deno の `@jsxImportSourceTypes` を含む)
190
- - **セキュリティ / 静的解析**: `NOSONAR`(SonarQube) / `nosemgrep`(Semgrep) / `lgtm[...]`・`codeql[...]`(CodeQL) / `skipcq`(DeepSource) / `deepcode ignore`(Snyk Code) / `no-dd-sa`・`datadog-disable`(Datadog) / `gitleaks:allow` / `trufflehog:ignore` / `pragma: allowlist secret`(detect-secrets)
191
- - **スペルチェック**: `cspell:` 系(`cSpell:`・`spell-checker:`・`spellchecker:` 別名込み)・`LocalWords` / `codespell:ignore`
192
- - **エディタ / IDE**: `#region`・`#endregion`・`// region`(VS Code / JetBrains) / `noinspection`・`//file:noinspection`・`<editor-fold>`・`language=`(JetBrains) / `ReSharper disable/restore`
387
+ With no paths, the current directory is scanned. Directories are walked recursively, skipping `node_modules` and `.git`, and symlinks are followed.
193
388
 
194
- prettier 関連のルールは prettier 本体の実装をそのまま写しています。`prettier-ignore` はコメント本文を trim した完全一致(JS/TS に `prettier-ignore-start`/`-end` はなく、普通のコメント扱い)、`@format` 系 pragma は jest-docblock と同じ docblock 解析(ファイル最初のブロックコメントのみ、`@` は行頭、行頭の空白はスペースのみ)、`/** @type */`・`/** @satisfies */` は prettier が直後の括弧を保持する型キャストコメント(tsc も JavaScript で解釈)、先頭コメントの `@flow`/`@noflow` は babel パーサーを Flow 構文に切り替える判定です。テストスイートはこれらを実際の prettier と突き合わせて検証しています。
389
+ - `--ext` sets the extensions to scan, comma-separated (default: `.ts,.tsx,.mts,.cts`). The list replaces the default, so to include JavaScript, list every extension: `--ext .ts,.tsx,.js,.jsx`. `.js`, `.jsx`, `.mjs` and `.cjs` files are parsed with JSX enabled.
390
+ - `--ignore` excludes files and directories matching a glob. A pattern without a slash (`*.test.ts`) matches file names, and one with a slash (`src/legacy/**`) matches paths. A trailing slash, as in `dist/`, matches directories only. Files listed explicitly on the command line are not subject to `--ignore`.
195
391
 
196
- TypeScript 関連のルールは tsc 6(JavaScript 実装)と tsc 7(Go 移植版)の両方の実装に合わせています。たとえば `//// @ts-ignore` や閉じ `/>` のない `/// <reference types="node">` は tsc 7 だけが、`//` の直後に NBSP を挟んだ `@ts-ignore` は tsc 6 だけが有効とみなしますが、いずれもディレクティブとして扱います。テストスイートは実際の tsc 6 とも突き合わせて検証しています。
392
+ ### Output formats
197
393
 
198
- ## ライブラリとして使う
394
+ `--format` selects `text` (default), `json` or `github`.
395
+
396
+ - `text`: one line per comment, `file:line:column [line|block] [directive] text`, followed by a count. A multi-line comment is shown on one line.
397
+ - `json`: the shape below. `--json` is shorthand for `--format json`.
398
+ - `github`: one `::notice` workflow command per comment.
399
+
400
+ ```json
401
+ {
402
+ "summary": { "files": 1, "comments": 1, "directives": 1 },
403
+ "files": [
404
+ {
405
+ "file": "src/range.ts",
406
+ "comments": [
407
+ {
408
+ "kind": "line",
409
+ "text": "// @ts-expect-error upstream may pass null",
410
+ "start": 218,
411
+ "end": 260,
412
+ "line": 6,
413
+ "column": 3,
414
+ "endLine": 6,
415
+ "endColumn": 45,
416
+ "directive": "@ts-expect-error"
417
+ }
418
+ ]
419
+ }
420
+ ]
421
+ }
422
+ ```
423
+
424
+ `line` and `column` are 1-based, and `endColumn` is the column just past the comment's last character. `start` and `end` are 0-based offsets into the decoded text with any BOM stripped (JavaScript string indices). `directive` appears only on comments detected as directives.
425
+
426
+ With `--remove`, each entry of `files` carries three arrays: `removed`, `kept` and `skipped`, where `skipped` holds the comments left out by `--skip-directives` or `--only-directives`. `summary` has their counts (`removed`, `kept`, `skipped`), the number of entries in `files` (`files`), the number of files that actually had comments removed (`changedFiles`), and `dryRun`.
427
+
428
+ ### Options
429
+
430
+ | Option | Description |
431
+ | --- | --- |
432
+ | `--format <fmt>` | Output format: `text`, `json` or `github` (default: `text`) |
433
+ | `--json` | Shorthand for `--format json` |
434
+ | `--ignore <glob>` | Exclude files and directories matching the glob (repeatable) |
435
+ | `--ext <list>` | Extensions to scan, comma-separated (default: `.ts,.tsx,.mts,.cts`) |
436
+ | `--diff <range>` | Only target files git reports as changed in the range |
437
+ | `--skip-directives` | Leave directives out of the results |
438
+ | `--only-directives` | Report directives only |
439
+ | `--fail-on-comment` | Exit with code 1 when any comment is reported |
440
+ | `--remove` | Remove the reported comments from the files |
441
+ | `--dry-run` | With `--remove`: show what would be removed without changing files |
442
+ | `--remove-directives` | With `--remove`: remove directives too |
443
+ | `--remove-legal` | With `--remove`: remove license notices too |
444
+ | `--keep <regex>` | With `--remove`: keep comments matching the regular expression (repeatable) |
445
+ | `-h`, `--help` | Show help |
446
+ | `-v`, `--version` | Show the version |
447
+
448
+ Exit codes: `0` on success, `1` when `--fail-on-comment` is set and comments are reported, `2` on a usage or runtime error.
449
+
450
+ ### Directive detection
451
+
452
+ Comments read by these tools are detected as directives:
453
+
454
+ - **Compilers and types**: TypeScript (`@ts-ignore`, `@ts-expect-error`, `@ts-nocheck`, `@ts-check`, `/// <reference>`, `@internal`), Deno (`@deno-types=`, `@ts-types=`, `@ts-self-types=`), typescript-strict-plugin (`@ts-strict`, `@ts-strict-ignore`), Flow (`@flow`, `@noflow`, the `$FlowFixMe` family, `flowlint`)
455
+ - **Linters**: ESLint (the `eslint-disable` family, `/* eslint … */`, `eslint-env`, `/* global */`, `/* exported */`, `// falls through`, `// no default`), React Compiler (`eslint-disable` of the react-hooks rules, `$FlowFixMe[react-rule…]`), oxlint (the `oxlint-disable` family), Biome (the `biome-ignore` family, `rome-ignore`), deno lint (the `deno-lint-ignore` family), stylelint (the `stylelint-disable` family), ast-grep (`ast-grep-ignore`), TSLint, JSHint, JSCS, JSLint
456
+ - **Formatters**: prettier (`prettier-ignore`, pragmas such as `@format`, `/** @type */` type casts), oxfmt (`oxfmt-ignore`), dprint and deno fmt (`dprint-ignore`, `deno-fmt-ignore` and their `-file` forms), import sorting (`organize-imports-ignore`, `sort-imports-ignore`), js-beautify
457
+ - **Coverage and testing**: istanbul, c8, v8 (`istanbul ignore` and the like), Node.js (`node:coverage`), Deno (the `deno-coverage-ignore` family), Jest and Vitest (`@jest-environment`, `@vitest-environment`, `@module-tag`), Stryker, type-coverage, ts-prune
458
+ - **Bundlers and runtimes**: webpack and Turbopack magic comments (`webpackChunkName:` and others), Vite (`@vite-ignore`), terser and Rollup annotations (`#__PURE__`, `@__NO_SIDE_EFFECTS__` and others), Bun (`// @bun`), React Refresh and solid-refresh (`@refresh`), Million.js, Nx, UnoCSS, Next.js codemods, `/* GraphQL */` and `/* HTML */` tags, `//# sourceMappingURL=`, `@jsx` pragmas
459
+ - **Security and static analysis**: SonarQube (`NOSONAR`), Semgrep (`nosemgrep`), CodeQL (`lgtm[…]`, `codeql[…]`), DeepSource (`skipcq`), Snyk Code (`deepcode ignore`), Datadog (`no-dd-sa`), gitleaks, TruffleHog, detect-secrets
460
+ - **Spell checkers**: cspell (`cspell:` and its aliases), `LocalWords`, codespell
461
+ - **Editors and IDEs**: VS Code and JetBrains (`#region`), JetBrains (`noinspection`, `<editor-fold>`, `language=`), ReSharper
462
+
463
+ Each rule matches a comment the way the tool's own parser does. Directives that only work in certain positions, such as at the top of the file or at particular points in a `switch`, are detected only there. Where tools or versions read a comment differently, it counts as a directive if any of them honours it, so `--remove` keeps it. For TypeScript, a directive counts if either tsc 6 or tsc 7 honours it.
464
+
465
+ ### Using it as a library
199
466
 
200
467
  ```ts
201
468
  import { scanPaths, scanComments, removeComments, changedFiles, formatText } from "@kongyo2/ts-comment-scanner";
202
469
 
203
- // ファイル / ディレクトリをまとめてスキャン
470
+ // Scan files and directories together
204
471
  const results = await scanPaths(["src"], { ignore: ["**/*.test.ts"] });
205
472
  console.log(formatText(results));
206
473
 
207
- // ソース文字列を直接スキャン
474
+ // Scan a source string
208
475
  const comments = scanComments("// hello\nconst x = 1;");
209
476
 
210
- // コメントを安全に削除
477
+ // Remove comments
211
478
  const { code, removed, kept } = removeComments("// note\nconst x = 1;\n");
212
479
 
213
- // git のリビジョン範囲で変更されたファイルの絶対パスを取得
480
+ // Absolute paths of the files changed in a git revision range
214
481
  const changed = await changedFiles("main..HEAD");
215
482
  ```
216
483
 
217
- ### 主な API
218
-
219
- | 関数 | 概要 |
484
+ | Function | Description |
220
485
  | --- | --- |
221
- | `scanComments(source, options?)` | ソース文字列からコメント配列を取得(`options.jsx` で TSX を解析) |
222
- | `scanFile(file)` | 1 ファイルをスキャン |
223
- | `scanPaths(inputs, options?)` | ファイル / ディレクトリ群を再帰的にスキャン(`ignore` / `extensions` 対応) |
224
- | `collectFiles(inputs, options?)` | 対象ファイルのパス一覧を収集 |
225
- | `changedFiles(range, cwd?)` | git のリビジョン範囲で変更された作業ツリーのファイルを絶対パスで返す |
226
- | `removeComments(source, options?)` | コメントを安全に削除(`removeDirectives` / `removeLegal` / `shouldRemove`) |
227
- | `detectDirective(kind, text, placement?)` | コメントがディレクティブなら正規化した名前を返す(`placement` で位置依存の判定が可能) |
228
- | `isLegalComment(text)` | ライセンス・法的コメントかどうかを判定 |
229
- | `formatText(results)` / `formatJson(results)` / `formatGitHub(results)` | スキャン結果を整形 |
230
- | `readFileText(file)` / `decodeFileText(data)` / `encodeFileText(text, target)` | UTF-8 / UTF-16 と BOM を保持するファイル読み書きヘルパー |
231
- | `writeFileAtomic(file, data)` | 一時ファイル経由でファイルをアトミックに置換 |
232
-
233
- 型: `Comment` / `CommentKind` / `FileScanResult` / `ScanOptions` / `CollectOptions` / `RemoveOptions` / `RemoveResult` / `FileText` / `FileEncoding` / `DirectivePlacement`
234
-
235
- ## 必要環境
236
-
237
- Node.js 20 以上
238
-
239
- ## ライセンス
486
+ | `scanComments(source, options?)` | Returns the comments in a source string; `options.jsx` enables JSX |
487
+ | `scanFile(file)` | Scans one file |
488
+ | `scanPaths(inputs, options?)` | Scans files and directories; accepts `ignore`, `extensions` and `ignoreDirs` |
489
+ | `collectFiles(inputs, options?)` | Collects the paths of the files to scan |
490
+ | `changedFiles(range, cwd?)` | Returns the absolute paths of the files changed in a git revision range |
491
+ | `removeComments(source, options?)` | Removes comments; accepts `removeDirectives`, `removeLegal`, `keep` and `shouldRemove` |
492
+ | `detectDirective(kind, text, placement?)` | Returns the normalized name if the comment is a directive; `placement` enables the position-dependent rules |
493
+ | `isLegalComment(text)` | Returns whether the comment is a license notice |
494
+ | `isJsxFile(file)` | Returns whether the file's extension is parsed with JSX enabled |
495
+ | `formatText(results)`, `formatJson(results)`, `formatGitHub(results)` | Formats scan results in each output format |
496
+ | `readFileText(file)`, `decodeFileText(data)`, `encodeFileText(text, target)` | Reads and writes file contents, preserving the encoding and BOM |
497
+ | `writeFileAtomic(file, data)` | Replaces a file through a temporary file |
498
+
499
+ Types: `Comment`, `CommentKind`, `FileScanResult`, `ScanOptions`, `CollectOptions`, `RemoveOptions`, `RemoveResult`, `FileText`, `FileEncoding`, `DirectivePlacement`
500
+
501
+ ### Requirements
502
+
503
+ Node.js 20 or later
504
+
505
+ ### License
240
506
 
241
507
  MIT