@kongyo2/ts-comment-scanner 1.11.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 +332 -306
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -18,227 +18,240 @@
|
|
|
18
18
|
|
|
19
19
|
## 日本語
|
|
20
20
|
|
|
21
|
-
TypeScript
|
|
21
|
+
TypeScript のコメントを一覧し、不要なものを安全に削除する CLI とライブラリです。コーディングエージェントがコードに書き足した「レビューの指摘に従い修正」のような経緯のコメントを、エージェントが触ったファイルから取り除く用途を想定しています。
|
|
22
22
|
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
-
|
|
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
|
-
|
|
45
|
-
|
|
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
|
-
|
|
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
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
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
|
-
|
|
75
|
+
`--dry-run` を外すと削除します。経緯のコメントが消え、`@ts-expect-error` は残ります。
|
|
80
76
|
|
|
81
|
-
|
|
77
|
+
```ts
|
|
78
|
+
import { normalize } from "./normalize.js";
|
|
82
79
|
|
|
83
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
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
|
-
|
|
110
|
+
範囲内で削除されたファイルは対象外になり、名前を変えたファイルは新しいパスで扱います。`--diff` は、コマンドラインで直接指定したファイルにも適用します。git は、最初に指定したパスがあるリポジトリで実行します。
|
|
123
111
|
|
|
124
|
-
####
|
|
112
|
+
#### CI で使う
|
|
125
113
|
|
|
126
|
-
`--format github`
|
|
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
|
-
|
|
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
|
-
|
|
142
|
-
# まず削除対象を確認
|
|
143
|
-
ts-comment-scanner --remove --dry-run src
|
|
130
|
+
削除した後のコードは次のように整えます。
|
|
144
131
|
|
|
145
|
-
|
|
146
|
-
|
|
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
|
-
|
|
140
|
+
### 対象ファイルの指定
|
|
156
141
|
|
|
157
|
-
|
|
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
|
-
`--
|
|
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
|
-
|
|
147
|
+
### 出力形式
|
|
173
148
|
|
|
174
|
-
`--
|
|
149
|
+
`--format` で `text`(既定)・`json`・`github` を選びます。
|
|
175
150
|
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
151
|
+
- `text`: 1 件を 1 行で `ファイル:行:桁 [line|block] [ディレクティブ名] 本文` の形に出力し、最後に件数を出力します。複数行のコメントは 1 行にまとめます。
|
|
152
|
+
- `json`: 下の形で出力します。`--json` は `--format json` と同じです。
|
|
153
|
+
- `github`: 各コメントを GitHub Actions の `::notice` コマンドとして出力します。
|
|
179
154
|
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
203
|
-
|
|
204
|
-
|
|
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
|
-
|
|
226
|
-
|
|
227
|
-
| 関数 | 概要 |
|
|
239
|
+
| 関数 | 説明 |
|
|
228
240
|
| --- | --- |
|
|
229
|
-
| `scanComments(source, options?)` |
|
|
230
|
-
| `scanFile(file)` | 1
|
|
231
|
-
| `scanPaths(inputs, options?)` |
|
|
232
|
-
| `collectFiles(inputs, options?)` |
|
|
233
|
-
| `changedFiles(range, cwd?)` | git
|
|
234
|
-
| `removeComments(source, options?)` |
|
|
235
|
-
| `detectDirective(kind, text, placement?)` |
|
|
236
|
-
| `isLegalComment(text)` |
|
|
237
|
-
| `
|
|
238
|
-
| `
|
|
239
|
-
| `
|
|
240
|
-
|
|
241
|
-
|
|
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
|
|
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
|
-
|
|
256
|
-
|
|
257
|
-
-
|
|
258
|
-
-
|
|
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
|
-
|
|
277
|
-
|
|
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
|
-
|
|
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
|
-
|
|
284
|
-
|
|
285
|
-
|
|
286
|
-
|
|
287
|
-
|
|
288
|
-
|
|
289
|
-
|
|
290
|
-
|
|
291
|
-
|
|
292
|
-
|
|
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
|
-
|
|
320
|
+
Drop `--dry-run` to remove them. The narration goes, and the `@ts-expect-error` stays:
|
|
312
321
|
|
|
313
|
-
|
|
322
|
+
```ts
|
|
323
|
+
import { normalize } from "./normalize.js";
|
|
314
324
|
|
|
315
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
332
|
-
|
|
333
|
-
|
|
334
|
-
|
|
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
|
-
|
|
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
|
|
357
|
+
#### Using it in CI
|
|
357
358
|
|
|
358
|
-
`--format github` emits each comment as a
|
|
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
|
-
|
|
368
|
+
`--remove` deletes only the ranges the TypeScript parser reports as comments. These comments stay:
|
|
370
369
|
|
|
371
|
-
|
|
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
|
-
|
|
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
|
-
|
|
378
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
385
|
+
### Choosing files
|
|
388
386
|
|
|
389
|
-
|
|
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
|
-
|
|
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
|
-
|
|
392
|
+
### Output formats
|
|
405
393
|
|
|
406
|
-
|
|
394
|
+
`--format` selects `text` (default), `json` or `github`.
|
|
407
395
|
|
|
408
|
-
|
|
409
|
-
|
|
410
|
-
|
|
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
|
-
|
|
413
|
-
|
|
414
|
-
|
|
415
|
-
|
|
416
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
435
|
-
|
|
436
|
-
|
|
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
|
|
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
|
|
474
|
+
// Scan a source string
|
|
448
475
|
const comments = scanComments("// hello\nconst x = 1;");
|
|
449
476
|
|
|
450
|
-
// Remove comments
|
|
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
|
-
|
|
458
|
-
|
|
459
|
-
| Function | Summary |
|
|
484
|
+
| Function | Description |
|
|
460
485
|
| --- | --- |
|
|
461
|
-
| `scanComments(source, options?)` |
|
|
462
|
-
| `scanFile(file)` |
|
|
463
|
-
| `scanPaths(inputs, options?)` |
|
|
464
|
-
| `collectFiles(inputs, options?)` |
|
|
465
|
-
| `changedFiles(range, cwd?)` |
|
|
466
|
-
| `removeComments(source, options?)` |
|
|
467
|
-
| `detectDirective(kind, text, placement?)` |
|
|
468
|
-
| `isLegalComment(text)` |
|
|
469
|
-
| `
|
|
470
|
-
| `
|
|
471
|
-
| `
|
|
472
|
-
|
|
473
|
-
|
|
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
|
|