@kongyo2/ts-comment-scanner 1.11.0 → 1.15.0

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
@@ -18,227 +18,240 @@
18
18
 
19
19
  ## 日本語
20
20
 
21
- TypeScript プロジェクト内のコメントを検出・一覧・集計し、安全に削除もできる CLI / ライブラリです。TypeScript の AST を使って解析するため、文字列・テンプレートリテラル・正規表現・JSX テキストを誤検出しません。
21
+ TypeScript のコメントを一覧し、不要なものを安全に削除する CLI とライブラリです。コーディングエージェントがコードに書き足した「レビューの指摘に従い修正」のような経緯のコメントを、エージェントが触ったファイルから取り除く用途を想定しています。
22
22
 
23
- ### 特徴
24
-
25
- - `.ts` `.tsx` `.mts` `.cts` を再帰的にスキャン(`node_modules` と `.git` は除外)。シンボリックリンクは明示指定時と同様に走査中も追跡し、循環は自動検知して停止
26
- - 行コメント (`//`) とブロックコメント (`/* */`) を位置情報つきで報告
27
- - テキスト / JSON / **GitHub Actions アノテーション**の 3 形式で出力
28
- - `@ts-ignore` や `eslint-disable` などの**コンパイラ・リンター指示子(ディレクティブ)を自動判別**し、絞り込み・除外が可能
29
- - **安全なコメント削除**(コードクリーンアップ): ディレクティブとライセンスヘッダーはデフォルトで保持
30
- - UTF-8(BOM 付き可)と BOM 付き UTF-16(LE/BE)に対応。削除時もエンコーディングと BOM を保持し、不正なエンコーディングのファイルは**変更せずに**エラー報告
31
- - Glob による**カスタム無視パターン** (`--ignore`、`dist/` のような末尾スラッシュでディレクトリ限定)、対象拡張子の変更 (`--ext`、JavaScript は JSX を有効にして解析)
32
- - **git 連携 (`--diff`)**: 特定コミット間や未コミットの変更で触れられたファイルだけに対象を絞り込み
33
- - CI 向けの `--fail-on-comment`(コメント検出時に終了コード 1)
34
- - CLI としても、ライブラリとしても利用可能
23
+ - コメントは TypeScript のパーサーで取り出すので、文字列・テンプレートリテラル・正規表現・JSX テキストの中の `//` や `/*` をコメントと取り違えません。
24
+ - `@ts-expect-error`・`eslint-disable`・`webpackChunkName:` のように、消すとビルドやリントの結果が変わるコメント(ディレクティブ)と、ライセンス表記は残します。
25
+ - `--diff` を付けると、git で変更があったファイルだけを対象にします。
26
+ - 結果はテキスト・JSON・GitHub Actions のアノテーションで出力します。`--fail-on-comment` を付けると、コメントがあるときに CI を失敗させられます。
35
27
 
36
28
  ### インストール
37
29
 
38
30
  ```bash
39
- npm install @kongyo2/ts-comment-scanner
31
+ npm install --save-dev @kongyo2/ts-comment-scanner
40
32
  ```
41
33
 
42
- インストールせずに実行する場合:
34
+ インストールすると、npm scripts や `npx` から `ts-comment-scanner` コマンドを実行できます。インストールせずに `npx @kongyo2/ts-comment-scanner` で実行することもできます。
43
35
 
44
- ```bash
45
- 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
+ }
46
51
  ```
47
52
 
48
- ### CLI の使い方
53
+ パスを渡すと、コメントを `ファイル:行:桁` の位置つきで一覧します。ディレクティブには `[@ts-expect-error]` のように名前が付きます。
49
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
50
62
  ```
51
- ts-comment-scanner [options] [paths...]
52
-
53
- 出力:
54
- --format <fmt> 出力形式: text / json / github(既定: text)
55
- --json --format json の短縮形
56
-
57
- フィルタリング:
58
- --ignore <glob> Glob に一致するファイル・ディレクトリを除外(複数指定可)
59
- --ext <list> スキャン対象の拡張子(カンマ区切り、既定: .ts,.tsx,.mts,.cts)
60
- --diff <range> git で変更されたファイルのみを対象(例: HEAD, main..HEAD)
61
- --skip-directives コンパイラ・リンター指示子を結果から除外
62
- --only-directives 指示子のみを報告
63
-
64
- CI:
65
- --fail-on-comment コメントが報告された場合に終了コード 1 で終了
66
-
67
- 削除:
68
- --remove 報告対象のコメントをファイルから削除(インプレース)
69
- --dry-run --remove と併用: 変更せずに削除対象のみ表示
70
- --remove-directives --remove と併用: 指示子コメントも削除
71
- --remove-legal --remove と併用: ライセンス・法的コメントも削除
72
- --keep <regex> --remove と併用: 正規表現に一致するコメントも指示子と同様に保持(複数指定可)
73
-
74
- その他:
75
- -h, --help ヘルプを表示
76
- -v, --version バージョンを表示
63
+
64
+ #### コメントを削除する
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.
77
73
  ```
78
74
 
79
- パスを省略するとカレントディレクトリを対象にします。スラッシュを含まない Glob(例: `*.test.ts`)はファイル名に、含むもの(例: `src/legacy/**`)はパスに一致します。`.gitignore` と同様に、末尾がスラッシュのパターン(例: `dist/`)はディレクトリだけに一致します。明示的に指定したファイルは `--ignore` の対象になりません。
75
+ `--dry-run` を外すと削除します。経緯のコメントが消え、`@ts-expect-error` は残ります。
80
76
 
81
- `--ext` で JavaScript(`.js` `.jsx` `.mjs` `.cjs`)を追加した場合は、TypeScript 本体と同じく JSX を有効にして解析するため、React コンポーネント内の `<div>http://…</div>` のようなテキストをコメントと誤検出しません。
77
+ ```ts
78
+ import { normalize } from "./normalize.js";
82
79
 
83
- **終了コード**: `0` 成功 / `1` `--fail-on-comment` 指定時にコメントを検出 / `2` 引数・実行時エラー
80
+ export function resolveRange(input: string) {
81
+ if (input === "") return "HEAD";
82
+ // @ts-expect-error 上流から null が渡ることがある
83
+ return normalize(input);
84
+ }
85
+ ```
84
86
 
85
- #### 出力例
87
+ ディレクティブも消すときは `--remove-directives`、ライセンス表記も消すときは `--remove-legal` を付けます。プロジェクト独自のツールが読む目印のように、ほかにも残したいコメントがあれば `--keep` に正規表現で指定します。
86
88
 
87
89
  ```bash
88
- $ ts-comment-scanner src
89
- src/index.ts:1:1 [line] // エントリーポイント
90
- src/scanner.ts:8:3 [block] /* AST を走査する */
91
- src/legacy.ts:3:1 [line] [@ts-ignore] // @ts-ignore 後で直す
92
-
93
- 3 comments across 3 files
90
+ ts-comment-scanner --remove --keep "@skipMangle" --keep "^// INJECT" src
94
91
  ```
95
92
 
96
- JSON 出力:
93
+ 何を残し、削除後のコードをどう整えるかは[削除の動作](#削除の動作)にまとめています。
94
+
95
+ #### 変更したファイルだけを対象にする
96
+
97
+ `--diff <range>` を付けると、git が変更ありと報告するファイルだけを対象にします。`<range>` には `git diff` に渡すリビジョンをそのまま書きます。
98
+
99
+ - `HEAD` のようにリビジョンを 1 つだけ書くと、作業ツリーと比べます。まだ追跡していない新しいファイルも対象です(`.gitignore` に一致するものは除きます)。
100
+ - `main..HEAD` や `main...HEAD` のように書くと、コミット同士を比べます。
97
101
 
98
102
  ```bash
99
- $ ts-comment-scanner --json src
100
- {
101
- "summary": { "files": 1, "comments": 1, "directives": 0 },
102
- "files": [
103
- {
104
- "file": "src/index.ts",
105
- "comments": [
106
- {
107
- "kind": "line",
108
- "text": "// エントリーポイント",
109
- "start": 0,
110
- "end": 12,
111
- "line": 1,
112
- "column": 1,
113
- "endLine": 1,
114
- "endColumn": 13
115
- }
116
- ]
117
- }
118
- ]
119
- }
103
+ # 未コミットの変更があるファイルで、削除対象を確かめる
104
+ ts-comment-scanner --remove --dry-run --diff HEAD
105
+
106
+ # ブランチで変更したファイルからコメントを削除する
107
+ ts-comment-scanner --remove --diff main...HEAD
120
108
  ```
121
109
 
122
- ディレクティブと判定されたコメントには `"directive": "@ts-ignore"` のように名前が付きます。
110
+ 範囲内で削除されたファイルは対象外になり、名前を変えたファイルは新しいパスで扱います。`--diff` は、コマンドラインで直接指定したファイルにも適用します。git は、最初に指定したパスがあるリポジトリで実行します。
123
111
 
124
- #### GitHub Actions で使う
112
+ #### CI で使う
125
113
 
126
- `--format github` は各コメントを [workflow command](https://docs.github.com/actions/reference/workflow-commands-for-github-actions) として出力するため、PR の該当行にアノテーションが表示されます。
114
+ `--format github` を付けると、コメントを GitHub Actions のアノテーションとして出力し、PR の該当行に表示します。`--fail-on-comment` を付けると、コメントを 1 件でも報告したときに終了コード 1 で終わります。
127
115
 
128
116
  ```yaml
129
117
  - name: Check for stray comments
130
118
  run: npx @kongyo2/ts-comment-scanner --format github --skip-directives --fail-on-comment src
131
119
  ```
132
120
 
133
- ```
134
- ::notice file=src/index.ts,line=1,endLine=1,col=1,endColumn=12,title=line comment::// エントリーポイント
135
- ```
121
+ ### 削除の動作
136
122
 
137
- JSON 出力の `endColumn` が排他的(コメント末尾の次の桁)なのに対し、GitHub アノテーションの列は両端含みのため、ここでは最後の文字の桁(この例では 12)が出力されます。64 KiB を超える巨大なコメントは、GitHub の上限に収まるよう安全に切り詰められます。
123
+ `--remove` が削除するのは、TypeScript のパーサーがコメントと判定した範囲だけです。次のコメントは残します。
138
124
 
139
- #### コメントの一括削除(コードクリーンアップ)
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` は、手前のコメントを消すと効き始めます。このように効き方が変わる削除はせず、そのコメントを残します。
140
129
 
141
- ```bash
142
- # まず削除対象を確認
143
- ts-comment-scanner --remove --dry-run src
130
+ 削除した後のコードは次のように整えます。
144
131
 
145
- # 実際に削除(ディレクティブとライセンスヘッダーは保持される)
146
- ts-comment-scanner --remove src
132
+ - コメントだけの行は行ごと、行末のコメントは手前の空白ごと削除します。空行に挟まれたコメント行を消したときは空行を 1 行にまとめ、ファイルやブロックの先頭・末尾でコメントとコードを隔てていた空行は一緒に削除します。
133
+ - トークンがつながる位置には空白を入れます(`a/* x */b` → `a b`)。コードに挟まれた、改行を含むブロックコメントは改行に置き換え、自動セミコロン挿入による文の区切りを保ちます。
134
+ - JSX の `{/* … */}` は波かっこごと削除します。波かっこを外すと表示されるテキストが変わる位置では、`{" "}` か `{}` を残します。
147
135
 
148
- # 指示子・ライセンスも含めて完全に削除
149
- ts-comment-scanner --remove --remove-directives --remove-legal src
136
+ 書き込む前に削除後のソースを解析し直し、残したコメントの内容とディレクティブとしての意味、JSX の表示内容が変わっていないことを確かめます。一致しないファイルは書き換えず、エラーとして報告します。書き込みは一時ファイルを経由した置き換えなので、途中で失敗しても元のファイルは壊れません。
150
137
 
151
- # プロジェクト独自のツールが読むマーカーも保持
152
- ts-comment-scanner --remove --keep "@skipMangle" --keep "^// INJECT" src
153
- ```
138
+ ファイルは UTF-8(BOM の有無は問いません)か BOM 付きの UTF-16 として読み、削除後も元の文字コードと BOM のまま書き戻します。正しくデコードできないファイルからはコメントを削除せず、エラーとして報告します。
154
139
 
155
- 削除は AST のコメント範囲に基づいて行われるため、文字列やコードには影響しません。さらに:
140
+ ### 対象ファイルの指定
156
141
 
157
- - `@ts-expect-error` / `eslint-disable` などの指示子は、削除するとビルドやリントが壊れるため**デフォルトで保持**。tsc の `stripInternal` が宣言ファイルから除外する目印の `@internal` も、消すと内部 API が `.d.ts` に漏れるため保持
158
- - 法的コメントも**デフォルトで保持**: terser・esbuild が残すもの(`/*! ... */`・`/**! ... */`・`//! ...`、`@license`・`@licence`・`@preserve`・`@copyright`)、`SPDX-License-Identifier:` / `SPDX-FileCopyrightText:` タグ、そしてタグのない慣用的な著作権表示・ライセンス文(`Copyright (c) …`・`Copyright 2011 …`・`© 2024 …`・`Licensed under …`・`All rights reserved`・MIT / BSD / MPL / GPL の許諾文)
159
- - **プロジェクト独自のマーカーは `--keep` で保持**: ビルドテンプレートの置換位置や独自リンターのタグなど、汎用ツールの指示子ではないマーカーは、正規表現で指定すると指示子と同様に保持(`--remove-directives` より優先)
160
- - `@ts-expect-error` や `eslint-disable-next-line` など**次行を対象にする指示子の直下の行構造を保持**: 削除すると行が消えて指示子の適用先がずれる場合(コメントだけの行など)、その行のコメントは削除せずに保持
161
- - **指示子が対象を探す途中のコメントも保持**: 空行と `//` 行を読み飛ばして対象行を探す tsc の `@ts-ignore`/`@ts-expect-error` では、tsc 6・tsc 7 がそれぞれ読み飛ばせずに止まる最初の行(ブロックコメントの行など)を保持。対象の直前にある最後のコメントでのみ有効な指示子(`@deno-types`・`/* GraphQL */`・ESLint の `// falls through` など)では、指示子と対象の間のコメントをすべて保持
162
- - **位置依存ディレクティブを削除で有効化しない**: prettier の `@format`/`@prettier` pragma や Jest の docblock の `@jest-environment`、Deno の `deno-coverage-ignore-file`(ファイル最初のコメントでのみ有効)、Bun の `// @bun`(ファイル先頭か shebang の次の行でのみ有効)、ast-grep の `ast-grep-ignore`(1 行目にあって次の行が空ならファイル全体に効く)が、手前のコメント削除によって保持コメント内で新たに効き始める場合は、その手前のコメントも保持。ast-grep は同じ行の手前にあるコメントの有無で「行末の抑制」か「次行の抑制」かが変わり、1 行目では後ろに続くノードの位置でファイル全体に効くかが変わるため、その行の手前のコメントと、1 行目では後ろに続くコメントも保持
163
- - ブロックコメント除去でトークンが結合してしまう位置には空白を挿入(`a/* x */b` → `a b`)。括弧や区切り記号との間を空けていただけの空白は残さない(`f(/* x */ a)` → `f(a)`、`{/* x */}` → `{}`)
164
- - コメントだけの行は行ごと削除、行末コメントは手前の空白ごと削除
165
- - **空行を重複させない**: コメント行が消えた位置では、前後の空行を元のソースにあった最も広い間隔まで詰める(空行に挟まれたコメントを消しても空行は 1 行)。ファイルやブロック(`{`・`(`・`[`・JSX タグ)の先頭・末尾で、コメントとコードを隔てていただけの空行も一緒に削除。次行指示子の適用先になる空行は保持
166
- - **JSX のコメントは波かっこごと削除**: `{/* … */}` は `{ }` を残さず丸ごと削除(単独の行なら行ごと)。ただし波かっこが前後のテキストを区切っている場合は、外すと JSX のテキスト結合・空白除去で描画が変わるため、同じ描画になるなら `{" "}` に置き換え(行末の `<a /> {/* x */}` → `<a />{" "}`)、それ以外は `{}` を残す。削除後のソースを再解析し、各要素の子要素の描画結果を TypeScript・esbuild・Babel の空白規則で比較して検証。`{/* prettier-ignore */}` など次の兄弟要素に効く波かっこ内の指示子の直後にあるコメントコンテナは保持
167
- - 削除後のソースを再スキャンし、残ったコメントが保持対象とディレクティブの意味ごと一致することを検証。想定外の結果になる場合はファイルを変更せずエラー報告
168
- - 書き込みは一時ファイル経由のアトミック置換(書き込み失敗やディスクフルで元ファイルが壊れない)
142
+ パスを省略するとカレントディレクトリが対象です。ディレクトリは再帰的にたどり、`node_modules` と `.git` は除外します。シンボリックリンクもたどります。
169
143
 
170
- `--remove --json` の `summary.files` は `files` 配列の件数(削除・保持・スキップのいずれかがあったファイル数)、`summary.changedFiles` は実際にコメントを削除したファイル数です。
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/` のように末尾をスラッシュにすると、ディレクトリだけに一致します。コマンドラインで直接指定したファイルには適用しません。
171
146
 
172
- #### 変更されたファイルだけを対象にする(`--diff`)
147
+ ### 出力形式
173
148
 
174
- `--diff <range>` を付けると、git が変更ありと報告するファイルだけにスキャン・削除を絞り込めます。範囲は `git diff` がリビジョンとして受け付ける書式そのままで、単一リビジョンなら作業ツリーとの比較(未追跡の新規ファイルも含む・`.gitignore` は尊重)、`a..b` / `a...b` ならコミット同士の比較になります。
149
+ `--format` で `text`(既定)・`json`・`github` を選びます。
175
150
 
176
- ```bash
177
- # 未コミットの変更があるファイルだけをスキャン
178
- ts-comment-scanner --diff HEAD
151
+ - `text`: 1 件を 1 行で `ファイル:行:桁 [line|block] [ディレクティブ名] 本文` の形に出力し、最後に件数を出力します。複数行のコメントは 1 行にまとめます。
152
+ - `json`: 下の形で出力します。`--json` は `--format json` と同じです。
153
+ - `github`: 各コメントを GitHub Actions の `::notice` コマンドとして出力します。
179
154
 
180
- # ブランチで変更されたファイルだけからコメントを削除
181
- ts-comment-scanner --remove --diff main...HEAD
182
-
183
- # 特定コミット間で変更されたファイルのみを CI でチェック
184
- ts-comment-scanner --fail-on-comment --diff a1b2c3..d4e5f6 src
155
+ ```json
156
+ {
157
+ "summary": { "files": 1, "comments": 1, "directives": 1 },
158
+ "files": [
159
+ {
160
+ "file": "src/range.ts",
161
+ "comments": [
162
+ {
163
+ "kind": "line",
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"
172
+ }
173
+ ]
174
+ }
175
+ ]
176
+ }
185
177
  ```
186
178
 
187
- コーディングエージェントに作業させた後、その変更範囲だけを対象にノイズコメントを掃除する、といった使い方を想定しています。範囲内で削除されたファイルは対象外になり、リネームは新しいパスで扱われます。git は最初の入力パスが属するリポジトリで実行されるため、別リポジトリのパスを指定しても動作します。なお `--ignore` と異なり、明示的に指定したファイルにも絞り込みが適用されます。
188
-
189
- #### 検出できるディレクティブ(抜粋)
179
+ `line`・`column` は 1 始まりで、`endColumn` はコメントの最後の文字の次の桁です。`start`・`end` は、ファイルをデコードして BOM を除いたテキストでの 0 始まりの位置(JavaScript の文字列のインデックス)です。`directive` は、ディレクティブと判定したコメントにだけ付きます。
190
180
 
191
- 各ディレクティブは実ツールのパーサー実装(正規表現・文字列比較)に合わせて判定されます。ツールやバージョンによって解釈が分かれる場合は、いずれかが有効とみなす形をすべてディレクティブとして扱います(削除時は保持側に倒れます)。
181
+ `--remove` と組み合わせると、`files` の各要素は `removed`・`kept`・`skipped` の 3 つの配列を持ちます。`skipped` は、`--skip-directives` か `--only-directives` で対象から外したコメントです。`summary` には、それぞれの件数(`removed`・`kept`・`skipped`)、`files` 配列の要素数(`files`)、実際にコメントを削除したファイル数(`changedFiles`)、`dryRun` が入ります。
192
182
 
193
- - **コンパイラ / 型**: `@ts-ignore` `@ts-expect-error` `@ts-nocheck` `@ts-check`(tsc 6・tsc 7、TypeScript ファイルを検査する Flow) / `/// <reference>` 系 / `@internal`(tsc の `stripInternal`、knip の本番モード) / `@ts-strict-ignore`・`@ts-strict`(typescript-strict-plugin の CLI と IDE プラグイン) / `@deno-types=`・`@ts-types=`・`@ts-self-types=`(Deno)
194
- - **リンター**: `eslint-disable` 系・`eslint-env`・`/* global */`・`/* exported */`・`// falls through`(no-fallthrough)・`// no default`(default-case) / React Compiler が読む `eslint-disable … react-hooks/…`・`$FlowFixMe[react-rule…]` / `oxlint-disable` 系 / `biome-ignore` 系・`rome-ignore` / `deno-lint-ignore` 系 / `ast-grep-ignore`(ast-grep) / `stylelint-disable`・`stylelint-disable-line`・`stylelint-disable-next-line`・`stylelint-enable`(stylelint) / `@flow`・`@noflow`・`$FlowFixMe` 系・`flowlint` 系(Flow) / `tslint:`・`jshint`・`jscs:`・`jslint`(レガシー)。`// falls through` は ESLint・oxlint・deno_lint が読む位置(2 番目以降の `case`/`default` の直前、後に別の節が続く節の最後の文であるブロックの `}` の直前)、`// no default` は default 節のない switch の最後の節以降(ESLint は閉じ `}` の直前、oxlint は最後の節の中も)でのみ有効で、`if` ブロックやオブジェクトリテラルの `}` の直前では普通のコメント扱い
195
- - **フォーマッタ**: `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`(レガシー)
196
- - **カバレッジ / テスト**: `istanbul ignore`・`c8 ignore`・`v8 ignore`・`node:coverage`・`deno-coverage-ignore` 系 / `@jest-environment(-options)`・`@vitest-environment(-options)`・`@module-tag`(Vitest 4 以降。Jest がファイル先頭の docblock から読む `@jest-environment @edge-runtime/jest-environment` のようなスコープ付きパッケージやパス指定も含む) / `Stryker disable/restore` / `type-coverage:ignore-line/-next-line` / `ts-prune-ignore-next`
197
- - **バンドラ / ランタイム**: `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` を含む)
198
- - **セキュリティ / 静的解析**: `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)
199
- - **スペルチェック**: `cspell:` 系(`cSpell:`・`spell-checker:`・`spellchecker:` 別名込み)・`LocalWords` / `codespell:ignore`
200
- - **エディタ / IDE**: `#region`・`#endregion`・`// region`(VS Code / JetBrains) / `noinspection`・`//file:noinspection`・`<editor-fold>`・`language=`(JetBrains) / `ReSharper disable/restore`
183
+ ### オプション
201
184
 
202
- 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 と突き合わせて検証しています。
203
-
204
- TypeScript 関連のルールは tsc 6(JavaScript 実装)と tsc 7(Go 移植版)の両方の実装に合わせています。たとえば `//// @ts-ignore` や閉じ `/>` のない `/// <reference types="node">` は tsc 7 だけが、`//` の直後に NBSP を挟んだ `@ts-ignore` は tsc 6 だけが有効とみなしますが、いずれもディレクティブとして扱います。テストスイートは実際の tsc 6 とも突き合わせて検証しています。
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 のどちらかが有効とみなすものが対象です。
205
219
 
206
220
  ### ライブラリとして使う
207
221
 
208
222
  ```ts
209
223
  import { scanPaths, scanComments, removeComments, changedFiles, formatText } from "@kongyo2/ts-comment-scanner";
210
224
 
211
- // ファイル / ディレクトリをまとめてスキャン
225
+ // ファイルやディレクトリをまとめてスキャンする
212
226
  const results = await scanPaths(["src"], { ignore: ["**/*.test.ts"] });
213
227
  console.log(formatText(results));
214
228
 
215
- // ソース文字列を直接スキャン
229
+ // ソース文字列をスキャンする
216
230
  const comments = scanComments("// hello\nconst x = 1;");
217
231
 
218
- // コメントを安全に削除
232
+ // コメントを削除する
219
233
  const { code, removed, kept } = removeComments("// note\nconst x = 1;\n");
220
234
 
221
- // git のリビジョン範囲で変更されたファイルの絶対パスを取得
235
+ // git のリビジョン範囲で変更されたファイルの絶対パスを得る
222
236
  const changed = await changedFiles("main..HEAD");
223
237
  ```
224
238
 
225
- #### 主な API
226
-
227
- | 関数 | 概要 |
239
+ | 関数 | 説明 |
228
240
  | --- | --- |
229
- | `scanComments(source, options?)` | ソース文字列からコメント配列を取得(`options.jsx` で TSX を解析) |
230
- | `scanFile(file)` | 1 ファイルをスキャン |
231
- | `scanPaths(inputs, options?)` | ファイル / ディレクトリ群を再帰的にスキャン(`ignore` / `extensions` 対応) |
232
- | `collectFiles(inputs, options?)` | 対象ファイルのパス一覧を収集 |
233
- | `changedFiles(range, cwd?)` | git のリビジョン範囲で変更された作業ツリーのファイルを絶対パスで返す |
234
- | `removeComments(source, options?)` | コメントを安全に削除(`removeDirectives` / `removeLegal` / `keep` / `shouldRemove`) |
235
- | `detectDirective(kind, text, placement?)` | コメントがディレクティブなら正規化した名前を返す(`placement` で位置依存の判定が可能) |
236
- | `isLegalComment(text)` | ライセンス・法的コメントかどうかを判定 |
237
- | `formatText(results)` / `formatJson(results)` / `formatGitHub(results)` | スキャン結果を整形 |
238
- | `readFileText(file)` / `decodeFileText(data)` / `encodeFileText(text, target)` | UTF-8 / UTF-16 と BOM を保持するファイル読み書きヘルパー |
239
- | `writeFileAtomic(file, data)` | 一時ファイル経由でファイルをアトミックに置換 |
240
-
241
- 型: `Comment` / `CommentKind` / `FileScanResult` / `ScanOptions` / `CollectOptions` / `RemoveOptions` / `RemoveResult` / `FileText` / `FileEncoding` / `DirectivePlacement`
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`
242
255
 
243
256
  ### 必要環境
244
257
 
@@ -250,227 +263,240 @@ MIT
250
263
 
251
264
  ## English
252
265
 
253
- A CLI / library that detects, lists, and summarizes comments in a TypeScript project — and can also remove them safely. It analyzes code through the TypeScript AST, so it never mistakes strings, template literals, regular expressions, or JSX text for comments.
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.
254
267
 
255
- ### Features
256
-
257
- - Recursively scans `.ts` `.tsx` `.mts` `.cts` (excluding `node_modules` and `.git`); symlinks are followed during the walk just like explicit inputs, with cycles detected automatically
258
- - Reports line comments (`//`) and block comments (`/* */`) with position information
259
- - Outputs in three formats: text / JSON / **GitHub Actions annotations**
260
- - **Automatically identifies compiler and linter directives** such as `@ts-ignore` and `eslint-disable`, so you can filter them in or out
261
- - **Safe comment removal** (code cleanup): directives and license headers are kept by default
262
- - Handles UTF-8 (with or without BOM) and BOM-marked UTF-16 (LE/BE); removal preserves the encoding and BOM, and files with a broken encoding are reported as errors **without being modified**
263
- - **Custom ignore patterns** via glob (`--ignore`, with a trailing slash such as `dist/` restricting a pattern to directories) and configurable target extensions (`--ext`, parsing JavaScript with JSX enabled)
264
- - **git integration (`--diff`)**: narrow the scan to files touched between specific commits or in uncommitted work
265
- - `--fail-on-comment` for CI (exit code 1 when comments are detected)
266
- - Usable both as a CLI and as a library
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.
267
272
 
268
273
  ### Installation
269
274
 
270
275
  ```bash
271
- npm install @kongyo2/ts-comment-scanner
276
+ npm install --save-dev @kongyo2/ts-comment-scanner
272
277
  ```
273
278
 
274
- To run without installing:
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`.
275
280
 
276
- ```bash
277
- npx @kongyo2/ts-comment-scanner src
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
+ }
278
296
  ```
279
297
 
280
- ### CLI usage
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]`.
281
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
282
307
  ```
283
- ts-comment-scanner [options] [paths...]
284
-
285
- Output:
286
- --format <fmt> Output format: text / json / github (default: text)
287
- --json Shorthand for --format json
288
-
289
- Filtering:
290
- --ignore <glob> Exclude files/directories matching the glob (repeatable)
291
- --ext <list> Extensions to scan (comma-separated, default: .ts,.tsx,.mts,.cts)
292
- --diff <range> Only files git reports changed (e.g. HEAD, main..HEAD)
293
- --skip-directives Exclude compiler/linter directives from the results
294
- --only-directives Report only directives
295
-
296
- CI:
297
- --fail-on-comment Exit with code 1 if any comment is reported
298
-
299
- Removal:
300
- --remove Remove reported comments from files (in place)
301
- --dry-run With --remove: show what would be removed without changing files
302
- --remove-directives With --remove: also remove directive comments
303
- --remove-legal With --remove: also remove license/legal comments
304
- --keep <regex> With --remove: also keep comments matching the regular expression, like directives (repeatable)
305
-
306
- Other:
307
- -h, --help Show help
308
- -v, --version Show version
308
+
309
+ #### Removing comments
310
+
311
+ `--remove --dry-run` shows what would be removed without changing any file.
312
+
313
+ ```console
314
+ $ ts-comment-scanner --remove --dry-run src
315
+ src/range.ts: would remove 2 (kept 1)
316
+
317
+ Would remove 2 comments across 1 file. Kept 1 protected comment.
309
318
  ```
310
319
 
311
- If no paths are given, the current directory is used. A glob without a slash (e.g. `*.test.ts`) matches against file names, while one that contains a slash (e.g. `src/legacy/**`) matches against paths. As in `.gitignore`, a pattern ending in a slash (e.g. `dist/`) matches directories only. Files passed explicitly are never subject to `--ignore`.
320
+ Drop `--dry-run` to remove them. The narration goes, and the `@ts-expect-error` stays:
312
321
 
313
- JavaScript files added through `--ext` (`.js`, `.jsx`, `.mjs`, `.cjs`) are parsed with JSX enabled, just as TypeScript itself parses them, so text such as `<div>http://…</div>` inside a React component is never mistaken for a comment.
322
+ ```ts
323
+ import { normalize } from "./normalize.js";
314
324
 
315
- **Exit codes**: `0` success / `1` comments detected when `--fail-on-comment` is set / `2` argument or runtime error
325
+ export function resolveRange(input: string) {
326
+ if (input === "") return "HEAD";
327
+ // @ts-expect-error upstream may pass null
328
+ return normalize(input);
329
+ }
330
+ ```
316
331
 
317
- #### Example output
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`:
318
333
 
319
334
  ```bash
320
- $ ts-comment-scanner src
321
- src/index.ts:1:1 [line] // entry point
322
- src/scanner.ts:8:3 [block] /* walk the AST */
323
- src/legacy.ts:3:1 [line] [@ts-ignore] // @ts-ignore fix later
324
-
325
- 3 comments across 3 files
335
+ ts-comment-scanner --remove --keep "@skipMangle" --keep "^// INJECT" src
326
336
  ```
327
337
 
328
- JSON output:
338
+ [How removal works](#how-removal-works) covers what is kept and how the code is tidied up afterwards.
339
+
340
+ #### Targeting changed files only
341
+
342
+ With `--diff <range>`, only the files git reports as changed are scanned or cleaned. The range is anything `git diff` accepts as revisions:
343
+
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.
329
346
 
330
347
  ```bash
331
- $ ts-comment-scanner --json src
332
- {
333
- "summary": { "files": 1, "comments": 1, "directives": 0 },
334
- "files": [
335
- {
336
- "file": "src/index.ts",
337
- "comments": [
338
- {
339
- "kind": "line",
340
- "text": "// entry point",
341
- "start": 0,
342
- "end": 14,
343
- "line": 1,
344
- "column": 1,
345
- "endLine": 1,
346
- "endColumn": 15
347
- }
348
- ]
349
- }
350
- ]
351
- }
348
+ # Preview the removal in files with uncommitted changes
349
+ ts-comment-scanner --remove --dry-run --diff HEAD
350
+
351
+ # Remove comments from the files changed on the branch
352
+ ts-comment-scanner --remove --diff main...HEAD
352
353
  ```
353
354
 
354
- Comments identified as directives get a name attached, such as `"directive": "@ts-ignore"`.
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.
355
356
 
356
- #### Using it in GitHub Actions
357
+ #### Using it in CI
357
358
 
358
- `--format github` emits each comment as a [workflow command](https://docs.github.com/actions/reference/workflow-commands-for-github-actions), so annotations appear on the relevant lines of a PR.
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.
359
360
 
360
361
  ```yaml
361
362
  - name: Check for stray comments
362
363
  run: npx @kongyo2/ts-comment-scanner --format github --skip-directives --fail-on-comment src
363
364
  ```
364
365
 
365
- ```
366
- ::notice file=src/index.ts,line=1,endLine=1,col=1,endColumn=14,title=line comment::// entry point
367
- ```
366
+ ### How removal works
368
367
 
369
- While the JSON output's `endColumn` is exclusive (the column after the comment), GitHub annotation columns are inclusive, so the annotation reports the column of the last character (14 in this example). Comments larger than GitHub's 64 KiB annotation limit are truncated safely.
368
+ `--remove` deletes only the ranges the TypeScript parser reports as comments. These comments stay:
370
369
 
371
- #### Bulk comment removal (code cleanup)
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.
372
374
 
373
- ```bash
374
- # First, check what would be removed
375
- ts-comment-scanner --remove --dry-run src
375
+ The code left behind is tidied up:
376
376
 
377
- # Actually remove (directives and license headers are kept)
378
- ts-comment-scanner --remove src
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.
379
380
 
380
- # Remove everything, including directives and legal comments
381
- ts-comment-scanner --remove --remove-directives --remove-legal src
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.
382
382
 
383
- # Also keep the markers a project's own tooling reads
384
- ts-comment-scanner --remove --keep "@skipMangle" --keep "^// INJECT" src
385
- ```
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.
386
384
 
387
- Removal is driven by the AST's comment ranges, so it never touches strings or code. In addition:
385
+ ### Choosing files
388
386
 
389
- - Directives such as `@ts-expect-error` / `eslint-disable` are **kept by default**, because removing them would break the build or the linter. So is `@internal`, the marker tsc's `stripInternal` leaves declarations out of the emitted `.d.ts` by: removing it would leak internal APIs into the declarations
390
- - Legal comments are also **kept by default**: the ones terser and esbuild keep (`/*! ... */`, `/**! ... */`, `//! ...`, `@license`, `@licence`, `@preserve`, `@copyright`), the `SPDX-License-Identifier:` / `SPDX-FileCopyrightText:` tags, and copyright notices and license grants in their conventional, untagged wording (`Copyright (c) …`, `Copyright 2011 …`, `© 2024 …`, `Licensed under …`, `All rights reserved`, the MIT / BSD / MPL / GPL grant texts)
391
- - **Project-specific markers stay with `--keep`**: markers no general-purpose tool reads — a build template's placeholder, a custom linter tag — are kept like directives when a regular expression matches them (winning over `--remove-directives`)
392
- - **The line structure below next-line directives** (`@ts-expect-error`, `eslint-disable-next-line`, ...) **is preserved**: when removing comments would delete a line and shift the directive's target (e.g. a comment-only line), those comments are kept instead
393
- - **Comments a directive looks past for its target are kept too**: below tsc's `@ts-ignore`/`@ts-expect-error`, which skip blank and `//` lines to find their target, the first line tsc 6 or tsc 7 stops at (a block-comment line, say) is kept; between a directive that only counts as the last comment before its target (`@deno-types`, `/* GraphQL */`, ESLint's `// falls through`, ...) and that target, every comment is kept
394
- - **Position-dependent directives are never activated by a removal**: when deleting a leading comment would make prettier's `@format`/`@prettier` pragma, a `@jest-environment` in Jest's docblock or Deno's `deno-coverage-ignore-file` (honoured only in the file's first comment), Bun's `// @bun` marker (honoured only at the very start of the file or on the line after a shebang) or ast-grep's `ast-grep-ignore` (file-wide on the first line when the line below it is empty) newly take effect in a kept comment, the leading comment is kept as well. Whether an ast-grep suppression trails something or stands alone depends on the comments before it on its line, and on the first line whether it covers the whole file depends on the node after it, so the comments before it on its line stay, and on the first line the ones after it too
395
- - Whitespace is inserted where removing a block comment would otherwise join tokens together (`a/* x */b` → `a b`), and none is left where it only held the comment off a bracket or punctuation (`f(/* x */ a)` → `f(a)`, `{/* x */}` → `{}`)
396
- - Comment-only lines are removed entirely, and trailing comments are removed together with the preceding whitespace
397
- - **No blank-line pile-ups**: where comment-only lines vanish, the blank lines around them close ranks to the widest gap the source had there (removing a comment that sat between two blank lines leaves one, not two). At the start or end of the file or of a block (`{`, `(`, `[`, JSX tags), the blank lines that only separated the comment from the code go with it, while those already against the edge stay. Blank lines a next-line directive reaches stay put
398
- - **JSX comments go with their braces**: `{/* ... */}` is removed as a whole — its line too, when it stands alone — instead of leaving `{ }` behind. Where the braces also keep rendered text apart, dropping them would change what the element renders (JSX merges and trims text across them), so `{" "}` takes their place when that renders the same (`<a /> {/* x */}` at the end of a line → `<a />{" "}`), and otherwise `{}` stays. The output is re-parsed and every element's rendered children compared under the whitespace rules of TypeScript, esbuild and Babel. A comment container right after a directive in braces that applies to the next sibling (`{/* prettier-ignore */}`, ...) is kept
399
- - The result is re-scanned to verify that the surviving comments match the protected set, directive meaning included; if the outcome is unexpected the file is left unchanged and an error is reported
400
- - Writes go through a temporary file and an atomic rename, so a failed write or a full disk can never truncate the original
387
+ With no paths, the current directory is scanned. Directories are walked recursively, skipping `node_modules` and `.git`, and symlinks are followed.
401
388
 
402
- With `--remove --json`, `summary.files` counts the entries of the `files` array (every file with removed, kept or skipped comments) and `summary.changedFiles` counts the files that actually had comments removed.
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`.
403
391
 
404
- #### Scanning only changed files (`--diff`)
392
+ ### Output formats
405
393
 
406
- With `--diff <range>`, scanning and removal are limited to the files git reports as changed. The range is exactly what `git diff` accepts as revisions: a single revision compares the working tree against it (untracked new files included, honouring `.gitignore`), while `a..b` / `a...b` compare two commits.
394
+ `--format` selects `text` (default), `json` or `github`.
407
395
 
408
- ```bash
409
- # Scan only files with uncommitted changes
410
- ts-comment-scanner --diff HEAD
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.
411
399
 
412
- # Remove comments only from files changed on the branch
413
- ts-comment-scanner --remove --diff main...HEAD
414
-
415
- # Check only files changed between two commits in CI
416
- ts-comment-scanner --fail-on-comment --diff a1b2c3..d4e5f6 src
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
+ }
417
422
  ```
418
423
 
419
- This is designed for workflows like letting a coding agent do some work and then sweeping noise comments out of just the files it touched. Files deleted within the range are excluded, and renames are handled at their new path. git runs in the repository that contains the first input path, so pointing at another repository's checkout works too. Note that unlike `--ignore`, the narrowing also applies to explicitly listed files.
420
-
421
- #### Detectable directives (excerpt)
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.
422
425
 
423
- Each directive is matched the way the real tool's parser matches it (its regex or string comparison). Where tools or versions disagree, every form any of them honours counts as a directive, so removal errs on the side of keeping the comment.
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`.
424
427
 
425
- - **Compiler / types**: `@ts-ignore` `@ts-expect-error` `@ts-nocheck` `@ts-check` (tsc 6, tsc 7, and Flow checking TypeScript files) / the `/// <reference>` family / `@internal` (tsc's `stripInternal`, knip's production mode) / `@ts-strict-ignore`, `@ts-strict` (typescript-strict-plugin's CLI and IDE plugin) / `@deno-types=`, `@ts-types=`, `@ts-self-types=` (Deno)
426
- - **Linters**: the `eslint-disable` family, `eslint-env`, `/* global */`, `/* exported */`, `// falls through` (no-fallthrough), `// no default` (default-case) / the `eslint-disable … react-hooks/…` and `$FlowFixMe[react-rule…]` suppressions React Compiler reads / the `oxlint-disable` family / the `biome-ignore` family, `rome-ignore` / the `deno-lint-ignore` family / `ast-grep-ignore` (ast-grep) / `stylelint-disable`, `stylelint-disable-line`, `stylelint-disable-next-line`, `stylelint-enable` (stylelint) / `@flow`, `@noflow`, the `$FlowFixMe` family, `flowlint` (Flow) / `tslint:`, `jshint`, `jscs:`, `jslint` (legacy). `// falls through` only counts where ESLint, oxlint and deno_lint read it — in front of a `case`/`default` other than the first, or of the `}` of a block that ends a clause another follows — and `// no default` only after the last clause of a switch without a default (in front of its closing `}` for ESLint, anywhere in that clause for oxlint); in front of an `if` block's or an object literal's `}` they are ordinary comments
427
- - **Formatters**: `prettier-ignore`, the `@format`/`@prettier`/`@noformat`/`@noprettier` pragmas, `/** @type */` / `/** @satisfies */` type-cast comments (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` (legacy)
428
- - **Coverage / testing**: `istanbul ignore`, `c8 ignore`, `v8 ignore`, `node:coverage`, the `deno-coverage-ignore` family / `@jest-environment(-options)`, `@vitest-environment(-options)`, `@module-tag` (Vitest 4+; including the scoped packages and paths Jest reads from the docblock opening the file, such as `@jest-environment @edge-runtime/jest-environment`) / `Stryker disable/restore` / `type-coverage:ignore-line/-next-line` / `ts-prune-ignore-next`
429
- - **Bundlers / runtimes**: webpack and turbopack magic comments such as `webpackChunkName:` / `@vite-ignore` / `#__PURE__`, `@__NO_SIDE_EFFECTS__`, `@__INLINE__`, `@__KEY__`, `@__MANGLE_PROP__` (terser/rollup annotations) / `// @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 */` tag comments / `//# sourceMappingURL=`, `//# sourceURL=` / `@jsx`-family pragmas (Deno's `@jsxImportSourceTypes` included)
430
- - **Security / static analysis**: `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)
431
- - **Spell checkers**: the `cspell:` family (including the `cSpell:`, `spell-checker:`, `spellchecker:` aliases), `LocalWords` / `codespell:ignore`
432
- - **Editors / IDEs**: `#region`, `#endregion`, `// region` (VS Code / JetBrains) / `noinspection`, `//file:noinspection`, `<editor-fold>`, `language=` (JetBrains) / `ReSharper disable/restore`
428
+ ### Options
433
429
 
434
- The prettier rules copy prettier's own implementation: `prettier-ignore` is an exact match on the trimmed comment body (JS/TS has no `prettier-ignore-start`/`-end`, so those stay ordinary comments), the `@format`-family pragmas go through the same docblock parsing as jest-docblock (the file's first block comment only, `@` at the start of a line, spaces only before it), `/** @type */` and `/** @satisfies */` are the type-cast comments whose following parentheses prettier keeps (and which tsc honours in JavaScript), and `@flow`/`@noflow` in the leading comments is what switches its babel parser to Flow syntax. The test suite cross-checks these rules against the real prettier.
435
-
436
- The TypeScript rules follow both tsc 6 (the JavaScript compiler) and tsc 7 (the Go port). `//// @ts-ignore` and a `/// <reference types="node">` without its closing `/>` are live to tsc 7 alone, and an `@ts-ignore` behind a no-break space after `//` to tsc 6 alone; all of them count as directives. The test suite cross-checks these rules against the real tsc 6 as well.
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.
437
464
 
438
465
  ### Using it as a library
439
466
 
440
467
  ```ts
441
468
  import { scanPaths, scanComments, removeComments, changedFiles, formatText } from "@kongyo2/ts-comment-scanner";
442
469
 
443
- // Scan files / directories together
470
+ // Scan files and directories together
444
471
  const results = await scanPaths(["src"], { ignore: ["**/*.test.ts"] });
445
472
  console.log(formatText(results));
446
473
 
447
- // Scan a source string directly
474
+ // Scan a source string
448
475
  const comments = scanComments("// hello\nconst x = 1;");
449
476
 
450
- // Remove comments safely
477
+ // Remove comments
451
478
  const { code, removed, kept } = removeComments("// note\nconst x = 1;\n");
452
479
 
453
- // Absolute paths of files changed in a git revision range
480
+ // Absolute paths of the files changed in a git revision range
454
481
  const changed = await changedFiles("main..HEAD");
455
482
  ```
456
483
 
457
- #### Main API
458
-
459
- | Function | Summary |
484
+ | Function | Description |
460
485
  | --- | --- |
461
- | `scanComments(source, options?)` | Get an array of comments from a source string (parse TSX with `options.jsx`) |
462
- | `scanFile(file)` | Scan a single file |
463
- | `scanPaths(inputs, options?)` | Recursively scan files / directories (supports `ignore` / `extensions`) |
464
- | `collectFiles(inputs, options?)` | Collect the list of target file paths |
465
- | `changedFiles(range, cwd?)` | Absolute paths of working-tree files changed in a git revision range |
466
- | `removeComments(source, options?)` | Remove comments safely (`removeDirectives` / `removeLegal` / `keep` / `shouldRemove`) |
467
- | `detectDirective(kind, text, placement?)` | Return a normalized name if the comment is a directive (`placement` enables position-sensitive rules) |
468
- | `isLegalComment(text)` | Determine whether a comment is a license/legal comment |
469
- | `formatText(results)` / `formatJson(results)` / `formatGitHub(results)` | Format scan results |
470
- | `readFileText(file)` / `decodeFileText(data)` / `encodeFileText(text, target)` | Read/decode/encode helpers that preserve UTF-8 / UTF-16 and BOMs |
471
- | `writeFileAtomic(file, data)` | Replace a file atomically through a temporary sibling |
472
-
473
- Types: `Comment` / `CommentKind` / `FileScanResult` / `ScanOptions` / `CollectOptions` / `RemoveOptions` / `RemoveResult` / `FileText` / `FileEncoding` / `DirectivePlacement`
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`
474
500
 
475
501
  ### Requirements
476
502