@kongyo2/ts-comment-scanner 1.10.0 → 1.11.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 +261 -21
- 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,13 +11,16 @@
|
|
|
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)
|
|
18
|
+
|
|
19
|
+
## 日本語
|
|
17
20
|
|
|
18
21
|
TypeScript プロジェクト内のコメントを検出・一覧・集計し、安全に削除もできる CLI / ライブラリです。TypeScript の AST を使って解析するため、文字列・テンプレートリテラル・正規表現・JSX テキストを誤検出しません。
|
|
19
22
|
|
|
20
|
-
|
|
23
|
+
### 特徴
|
|
21
24
|
|
|
22
25
|
- `.ts` `.tsx` `.mts` `.cts` を再帰的にスキャン(`node_modules` と `.git` は除外)。シンボリックリンクは明示指定時と同様に走査中も追跡し、循環は自動検知して停止
|
|
23
26
|
- 行コメント (`//`) とブロックコメント (`/* */`) を位置情報つきで報告
|
|
@@ -30,7 +33,7 @@ TypeScript プロジェクト内のコメントを検出・一覧・集計し、
|
|
|
30
33
|
- CI 向けの `--fail-on-comment`(コメント検出時に終了コード 1)
|
|
31
34
|
- CLI としても、ライブラリとしても利用可能
|
|
32
35
|
|
|
33
|
-
|
|
36
|
+
### インストール
|
|
34
37
|
|
|
35
38
|
```bash
|
|
36
39
|
npm install @kongyo2/ts-comment-scanner
|
|
@@ -42,7 +45,7 @@ npm install @kongyo2/ts-comment-scanner
|
|
|
42
45
|
npx @kongyo2/ts-comment-scanner src
|
|
43
46
|
```
|
|
44
47
|
|
|
45
|
-
|
|
48
|
+
### CLI の使い方
|
|
46
49
|
|
|
47
50
|
```
|
|
48
51
|
ts-comment-scanner [options] [paths...]
|
|
@@ -66,6 +69,7 @@ CI:
|
|
|
66
69
|
--dry-run --remove と併用: 変更せずに削除対象のみ表示
|
|
67
70
|
--remove-directives --remove と併用: 指示子コメントも削除
|
|
68
71
|
--remove-legal --remove と併用: ライセンス・法的コメントも削除
|
|
72
|
+
--keep <regex> --remove と併用: 正規表現に一致するコメントも指示子と同様に保持(複数指定可)
|
|
69
73
|
|
|
70
74
|
その他:
|
|
71
75
|
-h, --help ヘルプを表示
|
|
@@ -78,7 +82,7 @@ CI:
|
|
|
78
82
|
|
|
79
83
|
**終了コード**: `0` 成功 / `1` `--fail-on-comment` 指定時にコメントを検出 / `2` 引数・実行時エラー
|
|
80
84
|
|
|
81
|
-
|
|
85
|
+
#### 出力例
|
|
82
86
|
|
|
83
87
|
```bash
|
|
84
88
|
$ ts-comment-scanner src
|
|
@@ -117,7 +121,7 @@ $ ts-comment-scanner --json src
|
|
|
117
121
|
|
|
118
122
|
ディレクティブと判定されたコメントには `"directive": "@ts-ignore"` のように名前が付きます。
|
|
119
123
|
|
|
120
|
-
|
|
124
|
+
#### GitHub Actions で使う
|
|
121
125
|
|
|
122
126
|
`--format github` は各コメントを [workflow command](https://docs.github.com/actions/reference/workflow-commands-for-github-actions) として出力するため、PR の該当行にアノテーションが表示されます。
|
|
123
127
|
|
|
@@ -132,7 +136,7 @@ $ ts-comment-scanner --json src
|
|
|
132
136
|
|
|
133
137
|
JSON 出力の `endColumn` が排他的(コメント末尾の次の桁)なのに対し、GitHub アノテーションの列は両端含みのため、ここでは最後の文字の桁(この例では 12)が出力されます。64 KiB を超える巨大なコメントは、GitHub の上限に収まるよう安全に切り詰められます。
|
|
134
138
|
|
|
135
|
-
|
|
139
|
+
#### コメントの一括削除(コードクリーンアップ)
|
|
136
140
|
|
|
137
141
|
```bash
|
|
138
142
|
# まず削除対象を確認
|
|
@@ -143,15 +147,19 @@ ts-comment-scanner --remove src
|
|
|
143
147
|
|
|
144
148
|
# 指示子・ライセンスも含めて完全に削除
|
|
145
149
|
ts-comment-scanner --remove --remove-directives --remove-legal src
|
|
150
|
+
|
|
151
|
+
# プロジェクト独自のツールが読むマーカーも保持
|
|
152
|
+
ts-comment-scanner --remove --keep "@skipMangle" --keep "^// INJECT" src
|
|
146
153
|
```
|
|
147
154
|
|
|
148
155
|
削除は AST のコメント範囲に基づいて行われるため、文字列やコードには影響しません。さらに:
|
|
149
156
|
|
|
150
|
-
- `@ts-expect-error` / `eslint-disable`
|
|
151
|
-
- `/*! ...
|
|
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` より優先)
|
|
152
160
|
- `@ts-expect-error` や `eslint-disable-next-line` など**次行を対象にする指示子の直下の行構造を保持**: 削除すると行が消えて指示子の適用先がずれる場合(コメントだけの行など)、その行のコメントは削除せずに保持
|
|
153
161
|
- **指示子が対象を探す途中のコメントも保持**: 空行と `//` 行を読み飛ばして対象行を探す 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 の次の行でのみ有効)
|
|
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 行目では後ろに続くコメントも保持
|
|
155
163
|
- ブロックコメント除去でトークンが結合してしまう位置には空白を挿入(`a/* x */b` → `a b`)。括弧や区切り記号との間を空けていただけの空白は残さない(`f(/* x */ a)` → `f(a)`、`{/* x */}` → `{}`)
|
|
156
164
|
- コメントだけの行は行ごと削除、行末コメントは手前の空白ごと削除
|
|
157
165
|
- **空行を重複させない**: コメント行が消えた位置では、前後の空行を元のソースにあった最も広い間隔まで詰める(空行に挟まれたコメントを消しても空行は 1 行)。ファイルやブロック(`{`・`(`・`[`・JSX タグ)の先頭・末尾で、コメントとコードを隔てていただけの空行も一緒に削除。次行指示子の適用先になる空行は保持
|
|
@@ -161,7 +169,7 @@ ts-comment-scanner --remove --remove-directives --remove-legal src
|
|
|
161
169
|
|
|
162
170
|
`--remove --json` の `summary.files` は `files` 配列の件数(削除・保持・スキップのいずれかがあったファイル数)、`summary.changedFiles` は実際にコメントを削除したファイル数です。
|
|
163
171
|
|
|
164
|
-
|
|
172
|
+
#### 変更されたファイルだけを対象にする(`--diff`)
|
|
165
173
|
|
|
166
174
|
`--diff <range>` を付けると、git が変更ありと報告するファイルだけにスキャン・削除を絞り込めます。範囲は `git diff` がリビジョンとして受け付ける書式そのままで、単一リビジョンなら作業ツリーとの比較(未追跡の新規ファイルも含む・`.gitignore` は尊重)、`a..b` / `a...b` ならコミット同士の比較になります。
|
|
167
175
|
|
|
@@ -178,14 +186,14 @@ ts-comment-scanner --fail-on-comment --diff a1b2c3..d4e5f6 src
|
|
|
178
186
|
|
|
179
187
|
コーディングエージェントに作業させた後、その変更範囲だけを対象にノイズコメントを掃除する、といった使い方を想定しています。範囲内で削除されたファイルは対象外になり、リネームは新しいパスで扱われます。git は最初の入力パスが属するリポジトリで実行されるため、別リポジトリのパスを指定しても動作します。なお `--ignore` と異なり、明示的に指定したファイルにも絞り込みが適用されます。
|
|
180
188
|
|
|
181
|
-
|
|
189
|
+
#### 検出できるディレクティブ(抜粋)
|
|
182
190
|
|
|
183
191
|
各ディレクティブは実ツールのパーサー実装(正規表現・文字列比較)に合わせて判定されます。ツールやバージョンによって解釈が分かれる場合は、いずれかが有効とみなす形をすべてディレクティブとして扱います(削除時は保持側に倒れます)。
|
|
184
192
|
|
|
185
|
-
- **コンパイラ / 型**: `@ts-ignore` `@ts-expect-error` `@ts-nocheck` `@ts-check`(tsc 6・tsc 7、TypeScript ファイルを検査する Flow) / `/// <reference>` 系 / `@ts-strict-ignore`・`@ts-strict`(typescript-strict-plugin の CLI と IDE プラグイン) / `@deno-types=`・`@ts-types=`・`@ts-self-types=`(Deno)
|
|
186
|
-
- **リンター**: `eslint-disable` 系・`eslint-env`・`/* global */`・`/* exported */`・`// falls through`(no-fallthrough)・`// no default`(default-case
|
|
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` ブロックやオブジェクトリテラルの `}` の直前では普通のコメント扱い
|
|
187
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`(レガシー)
|
|
188
|
-
- **カバレッジ / テスト**: `istanbul ignore`・`c8 ignore`・`v8 ignore`・`node:coverage`・`deno-coverage-ignore` 系 / `@jest-environment(-options)`・`@vitest-environment(-options)`・`@module-tag`(Vitest 4
|
|
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`
|
|
189
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` を含む)
|
|
190
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)
|
|
191
199
|
- **スペルチェック**: `cspell:` 系(`cSpell:`・`spell-checker:`・`spellchecker:` 別名込み)・`LocalWords` / `codespell:ignore`
|
|
@@ -195,7 +203,7 @@ prettier 関連のルールは prettier 本体の実装をそのまま写して
|
|
|
195
203
|
|
|
196
204
|
TypeScript 関連のルールは tsc 6(JavaScript 実装)と tsc 7(Go 移植版)の両方の実装に合わせています。たとえば `//// @ts-ignore` や閉じ `/>` のない `/// <reference types="node">` は tsc 7 だけが、`//` の直後に NBSP を挟んだ `@ts-ignore` は tsc 6 だけが有効とみなしますが、いずれもディレクティブとして扱います。テストスイートは実際の tsc 6 とも突き合わせて検証しています。
|
|
197
205
|
|
|
198
|
-
|
|
206
|
+
### ライブラリとして使う
|
|
199
207
|
|
|
200
208
|
```ts
|
|
201
209
|
import { scanPaths, scanComments, removeComments, changedFiles, formatText } from "@kongyo2/ts-comment-scanner";
|
|
@@ -214,7 +222,7 @@ const { code, removed, kept } = removeComments("// note\nconst x = 1;\n");
|
|
|
214
222
|
const changed = await changedFiles("main..HEAD");
|
|
215
223
|
```
|
|
216
224
|
|
|
217
|
-
|
|
225
|
+
#### 主な API
|
|
218
226
|
|
|
219
227
|
| 関数 | 概要 |
|
|
220
228
|
| --- | --- |
|
|
@@ -223,7 +231,7 @@ const changed = await changedFiles("main..HEAD");
|
|
|
223
231
|
| `scanPaths(inputs, options?)` | ファイル / ディレクトリ群を再帰的にスキャン(`ignore` / `extensions` 対応) |
|
|
224
232
|
| `collectFiles(inputs, options?)` | 対象ファイルのパス一覧を収集 |
|
|
225
233
|
| `changedFiles(range, cwd?)` | git のリビジョン範囲で変更された作業ツリーのファイルを絶対パスで返す |
|
|
226
|
-
| `removeComments(source, options?)` | コメントを安全に削除(`removeDirectives` / `removeLegal` / `shouldRemove`) |
|
|
234
|
+
| `removeComments(source, options?)` | コメントを安全に削除(`removeDirectives` / `removeLegal` / `keep` / `shouldRemove`) |
|
|
227
235
|
| `detectDirective(kind, text, placement?)` | コメントがディレクティブなら正規化した名前を返す(`placement` で位置依存の判定が可能) |
|
|
228
236
|
| `isLegalComment(text)` | ライセンス・法的コメントかどうかを判定 |
|
|
229
237
|
| `formatText(results)` / `formatJson(results)` / `formatGitHub(results)` | スキャン結果を整形 |
|
|
@@ -232,10 +240,242 @@ const changed = await changedFiles("main..HEAD");
|
|
|
232
240
|
|
|
233
241
|
型: `Comment` / `CommentKind` / `FileScanResult` / `ScanOptions` / `CollectOptions` / `RemoveOptions` / `RemoveResult` / `FileText` / `FileEncoding` / `DirectivePlacement`
|
|
234
242
|
|
|
235
|
-
|
|
243
|
+
### 必要環境
|
|
236
244
|
|
|
237
245
|
Node.js 20 以上
|
|
238
246
|
|
|
239
|
-
|
|
247
|
+
### ライセンス
|
|
248
|
+
|
|
249
|
+
MIT
|
|
250
|
+
|
|
251
|
+
## English
|
|
252
|
+
|
|
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.
|
|
254
|
+
|
|
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
|
|
267
|
+
|
|
268
|
+
### Installation
|
|
269
|
+
|
|
270
|
+
```bash
|
|
271
|
+
npm install @kongyo2/ts-comment-scanner
|
|
272
|
+
```
|
|
273
|
+
|
|
274
|
+
To run without installing:
|
|
275
|
+
|
|
276
|
+
```bash
|
|
277
|
+
npx @kongyo2/ts-comment-scanner src
|
|
278
|
+
```
|
|
279
|
+
|
|
280
|
+
### CLI usage
|
|
281
|
+
|
|
282
|
+
```
|
|
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
|
|
309
|
+
```
|
|
310
|
+
|
|
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`.
|
|
312
|
+
|
|
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.
|
|
314
|
+
|
|
315
|
+
**Exit codes**: `0` success / `1` comments detected when `--fail-on-comment` is set / `2` argument or runtime error
|
|
316
|
+
|
|
317
|
+
#### Example output
|
|
318
|
+
|
|
319
|
+
```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
|
|
326
|
+
```
|
|
327
|
+
|
|
328
|
+
JSON output:
|
|
329
|
+
|
|
330
|
+
```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
|
+
}
|
|
352
|
+
```
|
|
353
|
+
|
|
354
|
+
Comments identified as directives get a name attached, such as `"directive": "@ts-ignore"`.
|
|
355
|
+
|
|
356
|
+
#### Using it in GitHub Actions
|
|
357
|
+
|
|
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
|
+
|
|
360
|
+
```yaml
|
|
361
|
+
- name: Check for stray comments
|
|
362
|
+
run: npx @kongyo2/ts-comment-scanner --format github --skip-directives --fail-on-comment src
|
|
363
|
+
```
|
|
364
|
+
|
|
365
|
+
```
|
|
366
|
+
::notice file=src/index.ts,line=1,endLine=1,col=1,endColumn=14,title=line comment::// entry point
|
|
367
|
+
```
|
|
368
|
+
|
|
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.
|
|
370
|
+
|
|
371
|
+
#### Bulk comment removal (code cleanup)
|
|
372
|
+
|
|
373
|
+
```bash
|
|
374
|
+
# First, check what would be removed
|
|
375
|
+
ts-comment-scanner --remove --dry-run src
|
|
376
|
+
|
|
377
|
+
# Actually remove (directives and license headers are kept)
|
|
378
|
+
ts-comment-scanner --remove src
|
|
379
|
+
|
|
380
|
+
# Remove everything, including directives and legal comments
|
|
381
|
+
ts-comment-scanner --remove --remove-directives --remove-legal src
|
|
382
|
+
|
|
383
|
+
# Also keep the markers a project's own tooling reads
|
|
384
|
+
ts-comment-scanner --remove --keep "@skipMangle" --keep "^// INJECT" src
|
|
385
|
+
```
|
|
386
|
+
|
|
387
|
+
Removal is driven by the AST's comment ranges, so it never touches strings or code. In addition:
|
|
388
|
+
|
|
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
|
|
401
|
+
|
|
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.
|
|
403
|
+
|
|
404
|
+
#### Scanning only changed files (`--diff`)
|
|
405
|
+
|
|
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.
|
|
407
|
+
|
|
408
|
+
```bash
|
|
409
|
+
# Scan only files with uncommitted changes
|
|
410
|
+
ts-comment-scanner --diff HEAD
|
|
411
|
+
|
|
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
|
|
417
|
+
```
|
|
418
|
+
|
|
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)
|
|
422
|
+
|
|
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.
|
|
424
|
+
|
|
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`
|
|
433
|
+
|
|
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.
|
|
437
|
+
|
|
438
|
+
### Using it as a library
|
|
439
|
+
|
|
440
|
+
```ts
|
|
441
|
+
import { scanPaths, scanComments, removeComments, changedFiles, formatText } from "@kongyo2/ts-comment-scanner";
|
|
442
|
+
|
|
443
|
+
// Scan files / directories together
|
|
444
|
+
const results = await scanPaths(["src"], { ignore: ["**/*.test.ts"] });
|
|
445
|
+
console.log(formatText(results));
|
|
446
|
+
|
|
447
|
+
// Scan a source string directly
|
|
448
|
+
const comments = scanComments("// hello\nconst x = 1;");
|
|
449
|
+
|
|
450
|
+
// Remove comments safely
|
|
451
|
+
const { code, removed, kept } = removeComments("// note\nconst x = 1;\n");
|
|
452
|
+
|
|
453
|
+
// Absolute paths of files changed in a git revision range
|
|
454
|
+
const changed = await changedFiles("main..HEAD");
|
|
455
|
+
```
|
|
456
|
+
|
|
457
|
+
#### Main API
|
|
458
|
+
|
|
459
|
+
| Function | Summary |
|
|
460
|
+
| --- | --- |
|
|
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`
|
|
474
|
+
|
|
475
|
+
### Requirements
|
|
476
|
+
|
|
477
|
+
Node.js 20 or later
|
|
478
|
+
|
|
479
|
+
### License
|
|
240
480
|
|
|
241
481
|
MIT
|
package/dist/args.d.ts
CHANGED
package/dist/args.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"args.d.ts","sourceRoot":"","sources":["../src/args.ts"],"names":[],"mappings":"AAAA,KAAK,YAAY,GAAG,MAAM,GAAG,MAAM,GAAG,QAAQ,CAAC;AAC/C,MAAM,MAAM,aAAa,GAAG,SAAS,GAAG,MAAM,GAAG,MAAM,CAAC;AAExD,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,MAAM,EAAE,YAAY,CAAC;IACrB,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,UAAU,EAAE,MAAM,EAAE,GAAG,SAAS,CAAC;IACjC,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;IACzB,UAAU,EAAE,aAAa,CAAC;IAC1B,aAAa,EAAE,OAAO,CAAC;IACvB,MAAM,EAAE,OAAO,CAAC;IAChB,gBAAgB,EAAE,OAAO,CAAC;IAC1B,WAAW,EAAE,OAAO,CAAC;IACrB,MAAM,EAAE,OAAO,CAAC;IAChB,IAAI,EAAE,OAAO,CAAC;IACd,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,qFAAqF;AACrF,qBAAa,UAAW,SAAQ,KAAK;gBACvB,OAAO,EAAE,MAAM;CAI5B;AAKD,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,UAAU,
|
|
1
|
+
{"version":3,"file":"args.d.ts","sourceRoot":"","sources":["../src/args.ts"],"names":[],"mappings":"AAAA,KAAK,YAAY,GAAG,MAAM,GAAG,MAAM,GAAG,QAAQ,CAAC;AAC/C,MAAM,MAAM,aAAa,GAAG,SAAS,GAAG,MAAM,GAAG,MAAM,CAAC;AAExD,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,MAAM,EAAE,YAAY,CAAC;IACrB,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,UAAU,EAAE,MAAM,EAAE,GAAG,SAAS,CAAC;IACjC,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;IACzB,UAAU,EAAE,aAAa,CAAC;IAC1B,aAAa,EAAE,OAAO,CAAC;IACvB,MAAM,EAAE,OAAO,CAAC;IAChB,gBAAgB,EAAE,OAAO,CAAC;IAC1B,WAAW,EAAE,OAAO,CAAC;IACrB,2DAA2D;IAC3D,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,MAAM,EAAE,OAAO,CAAC;IAChB,IAAI,EAAE,OAAO,CAAC;IACd,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,qFAAqF;AACrF,qBAAa,UAAW,SAAQ,KAAK;gBACvB,OAAO,EAAE,MAAM;CAI5B;AAKD,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,UAAU,CAiLpD"}
|
package/dist/args.js
CHANGED
|
@@ -11,6 +11,7 @@ export function parseArgs(argv) {
|
|
|
11
11
|
const paths = [];
|
|
12
12
|
const ignore = [];
|
|
13
13
|
const extensions = [];
|
|
14
|
+
const keep = [];
|
|
14
15
|
let format = "text";
|
|
15
16
|
let diff;
|
|
16
17
|
let directives = "include";
|
|
@@ -113,6 +114,16 @@ export function parseArgs(argv) {
|
|
|
113
114
|
rejectValue();
|
|
114
115
|
removeLegal = true;
|
|
115
116
|
break;
|
|
117
|
+
case "--keep": {
|
|
118
|
+
// A forgotten pattern must not swallow the next flag: `--keep --dry-run`
|
|
119
|
+
// would turn a preview into an in-place removal. A pattern that does
|
|
120
|
+
// start with `-` can still be given inline, as `--keep=-x`.
|
|
121
|
+
if (inlineValue === undefined && argv[index + 1]?.startsWith("-") === true) {
|
|
122
|
+
throw new UsageError(`option ${flag} requires a regular expression (use ${flag}=<regex> for one starting with "-")`);
|
|
123
|
+
}
|
|
124
|
+
keep.push(parsePattern(flag, readValue()));
|
|
125
|
+
break;
|
|
126
|
+
}
|
|
116
127
|
case "--dry-run":
|
|
117
128
|
rejectValue();
|
|
118
129
|
dryRun = true;
|
|
@@ -136,6 +147,7 @@ export function parseArgs(argv) {
|
|
|
136
147
|
[dryRun, "--dry-run"],
|
|
137
148
|
[removeDirectives, "--remove-directives"],
|
|
138
149
|
[removeLegal, "--remove-legal"],
|
|
150
|
+
[keep.length > 0, "--keep"],
|
|
139
151
|
]) {
|
|
140
152
|
if (set)
|
|
141
153
|
throw new UsageError(`${flag} requires --remove`);
|
|
@@ -164,11 +176,24 @@ export function parseArgs(argv) {
|
|
|
164
176
|
remove,
|
|
165
177
|
removeDirectives,
|
|
166
178
|
removeLegal,
|
|
179
|
+
keep,
|
|
167
180
|
dryRun,
|
|
168
181
|
help,
|
|
169
182
|
version,
|
|
170
183
|
};
|
|
171
184
|
}
|
|
185
|
+
/** Compiles a pattern-valued option, reporting an invalid regular expression as a usage error. */
|
|
186
|
+
function parsePattern(flag, value) {
|
|
187
|
+
if (value === "")
|
|
188
|
+
throw new UsageError(`option ${flag} requires a regular expression`);
|
|
189
|
+
try {
|
|
190
|
+
return new RegExp(value);
|
|
191
|
+
}
|
|
192
|
+
catch (error) {
|
|
193
|
+
// The engine's message names the problem: "Invalid regular expression: /(/: Unterminated group".
|
|
194
|
+
throw new UsageError(`option ${flag}: ${error.message}`);
|
|
195
|
+
}
|
|
196
|
+
}
|
|
172
197
|
function splitFlag(arg) {
|
|
173
198
|
const equalsIndex = arg.indexOf("=");
|
|
174
199
|
if (arg.startsWith("--") && equalsIndex > 2) {
|
package/dist/args.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"args.js","sourceRoot":"","sources":["../src/args.ts"],"names":[],"mappings":"
|
|
1
|
+
{"version":3,"file":"args.js","sourceRoot":"","sources":["../src/args.ts"],"names":[],"mappings":"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"}
|
package/dist/directives.d.ts
CHANGED
|
@@ -15,11 +15,34 @@ export interface DirectivePlacement {
|
|
|
15
15
|
* that ends a leading `#!` line (see bunMarkerOffset).
|
|
16
16
|
*/
|
|
17
17
|
fileStart: boolean;
|
|
18
|
+
/**
|
|
19
|
+
* The comment sits where ast-grep's suppression comment applies to the
|
|
20
|
+
* whole file: it starts the file's first line (nothing but whitespace before
|
|
21
|
+
* it) and whatever follows it starts two or more lines further down, or
|
|
22
|
+
* nothing does. Left out, the comment is assumed not to.
|
|
23
|
+
*/
|
|
24
|
+
fileWide?: boolean;
|
|
25
|
+
/**
|
|
26
|
+
* The comment sits where a linter reads a switch fall-through comment
|
|
27
|
+
* (`// falls through`): in front of a `case` or `default` clause other than
|
|
28
|
+
* the first (ESLint, oxlint and deno_lint), or in front of the closing brace
|
|
29
|
+
* of a block that ends a clause another clause follows (the comment inside
|
|
30
|
+
* `case 0: { a(); // falls through }`). Left out, nextToken decides.
|
|
31
|
+
*/
|
|
32
|
+
fallthroughSlot?: boolean;
|
|
33
|
+
/**
|
|
34
|
+
* The comment sits where `default-case` reads its `// no default` comment in
|
|
35
|
+
* a switch without a default clause: after its last clause, in front of the
|
|
36
|
+
* switch's closing brace (ESLint), or anywhere from that clause's start on
|
|
37
|
+
* (oxlint). Left out, nextToken decides.
|
|
38
|
+
*/
|
|
39
|
+
noDefaultSlot?: boolean;
|
|
18
40
|
/**
|
|
19
41
|
* The token that follows the comment past any further comments (`case`,
|
|
20
|
-
* `}`, an identifier, ...), or `""` when only comments follow
|
|
21
|
-
*
|
|
22
|
-
*
|
|
42
|
+
* `}`, an identifier, ...), or `""` when only comments follow: a coarser
|
|
43
|
+
* stand-in for the switch slots above, used when they are left out, where
|
|
44
|
+
* the fall-through and default-case comments count only in front of
|
|
45
|
+
* `case`, `default` or `}`. Left out too, any position is assumed.
|
|
23
46
|
*/
|
|
24
47
|
nextToken?: string;
|
|
25
48
|
}
|
|
@@ -42,21 +65,25 @@ export declare function bunMarkerOffset(text: string): number;
|
|
|
42
65
|
*/
|
|
43
66
|
export declare function detectDirective(kind: CommentKind, text: string, placement?: DirectivePlacement): string | undefined;
|
|
44
67
|
/**
|
|
45
|
-
* The position-dependent directives (prettier's first-comment pragmas,
|
|
46
|
-
* coverage file pragma, Bun's file-start marker
|
|
47
|
-
*
|
|
48
|
-
*
|
|
49
|
-
*
|
|
50
|
-
*
|
|
51
|
-
*
|
|
68
|
+
* The position-dependent directives (prettier's first-comment pragmas, Jest's
|
|
69
|
+
* docblock pragmas, Deno's coverage file pragma, Bun's file-start marker,
|
|
70
|
+
* ast-grep's file-wide suppression) the comment carries that are active at
|
|
71
|
+
* the given placement, sorted. Unlike detectDirective — which reports one
|
|
72
|
+
* canonical name — this sees through masking: an eslint config block can also
|
|
73
|
+
* hold a `@format` pragma, and whether that pragma is live must not hide
|
|
74
|
+
* behind the name an earlier rule already claimed. Only first-comment,
|
|
75
|
+
* file-start and file-wide gates are consulted; header-gated directives
|
|
52
76
|
* cannot change activation when the comments around them change.
|
|
53
77
|
*/
|
|
54
78
|
export declare function activePositionalDirectives(kind: CommentKind, text: string, placement: DirectivePlacement): string[];
|
|
55
79
|
/**
|
|
56
|
-
* True for license/legal comments
|
|
57
|
-
*
|
|
58
|
-
*
|
|
59
|
-
*
|
|
80
|
+
* True for license/legal comments that build tools conventionally keep when
|
|
81
|
+
* stripping comments and that license scanners rely on: the ones terser
|
|
82
|
+
* keeps (a value opening with `!` after any stars — `/*!`, `/**!`, `//!` —
|
|
83
|
+
* or holding `@preserve`, `@copyright` or `@lic…`), which cover esbuild's
|
|
84
|
+
* (`/*!`, `//!`, `@license`, `@preserve`); the machine-readable
|
|
85
|
+
* `SPDX-License-Identifier:` / `SPDX-FileCopyrightText:` tags; and copyright
|
|
86
|
+
* notices and license grants in their conventional wording.
|
|
60
87
|
*/
|
|
61
88
|
export declare function isLegalComment(text: string): boolean;
|
|
62
89
|
//# sourceMappingURL=directives.d.ts.map
|
package/dist/directives.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"directives.d.ts","sourceRoot":"","sources":["../src/directives.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;
|
|
1
|
+
{"version":3,"file":"directives.d.ts","sourceRoot":"","sources":["../src/directives.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAskB9C;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IACjC,wDAAwD;IACxD,MAAM,EAAE,OAAO,CAAC;IAChB,2FAA2F;IAC3F,YAAY,EAAE,OAAO,CAAC;IACtB;;;;OAIG;IACH,SAAS,EAAE,OAAO,CAAC;IACnB;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB;;;;;;OAMG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B;;;;;OAKG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB;;;;;;OAMG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAID;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAIpD;AAoGD;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,kBAAkB,GAAG,MAAM,GAAG,SAAS,CAgCnH;AAwDD;;;;;;;;;;GAUG;AACH,wBAAgB,0BAA0B,CAAC,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,kBAAkB,GAAG,MAAM,EAAE,CAanH;AAoBD;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAKpD"}
|