@kongyo2/ts-comment-scanner 1.10.0 → 1.11.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +403 -137
- package/dist/args.d.ts +2 -0
- package/dist/args.d.ts.map +1 -1
- package/dist/args.js +25 -0
- package/dist/args.js.map +1 -1
- package/dist/directives.d.ts +41 -14
- package/dist/directives.d.ts.map +1 -1
- package/dist/directives.js +103 -32
- package/dist/directives.js.map +1 -1
- package/dist/remove.d.ts +10 -1
- package/dist/remove.d.ts.map +1 -1
- package/dist/remove.js +65 -10
- package/dist/remove.js.map +1 -1
- package/dist/run.d.ts.map +1 -1
- package/dist/run.js +5 -1
- package/dist/run.js.map +1 -1
- package/dist/scanner.d.ts +11 -0
- package/dist/scanner.d.ts.map +1 -1
- package/dist/scanner.js +100 -19
- package/dist/scanner.js.map +1 -1
- package/package.json +1 -1
- package/src/args.ts +28 -0
- package/src/directives.ts +148 -35
- package/src/remove.ts +72 -12
- package/src/run.ts +5 -1
- package/src/scanner.ts +107 -19
- package/README.en.md +0 -241
package/README.md
CHANGED
|
@@ -11,103 +11,164 @@
|
|
|
11
11
|

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