@kongyo2/ts-comment-scanner 1.21.0 → 1.23.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 +240 -52
- package/dist/astgrep.d.ts +4 -2
- package/dist/astgrep.d.ts.map +1 -1
- package/dist/astgrep.js +7 -4
- package/dist/astgrep.js.map +1 -1
- package/dist/containers.d.ts +48 -0
- package/dist/containers.d.ts.map +1 -0
- package/dist/containers.js +82 -0
- package/dist/containers.js.map +1 -0
- package/dist/coverage.d.ts +45 -0
- package/dist/coverage.d.ts.map +1 -0
- package/dist/coverage.js +92 -0
- package/dist/coverage.js.map +1 -0
- package/dist/directives.d.ts +13 -3
- package/dist/directives.d.ts.map +1 -1
- package/dist/directives.js +31 -11
- package/dist/directives.js.map +1 -1
- package/dist/files.d.ts +5 -0
- package/dist/files.d.ts.map +1 -1
- package/dist/files.js +103 -41
- package/dist/files.js.map +1 -1
- package/dist/imports.d.ts +12 -5
- package/dist/imports.d.ts.map +1 -1
- package/dist/imports.js +33 -10
- package/dist/imports.js.map +1 -1
- package/dist/index.d.ts +1 -1
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +1 -1
- package/dist/index.js.map +1 -1
- package/dist/lines.d.ts +11 -0
- package/dist/lines.d.ts.map +1 -1
- package/dist/lines.js +30 -0
- package/dist/lines.js.map +1 -1
- package/dist/remove.d.ts +16 -12
- package/dist/remove.d.ts.map +1 -1
- package/dist/remove.js +51 -638
- package/dist/remove.js.map +1 -1
- package/dist/run.d.ts.map +1 -1
- package/dist/run.js +11 -10
- package/dist/run.js.map +1 -1
- package/dist/scanner.d.ts +29 -0
- package/dist/scanner.d.ts.map +1 -1
- package/dist/scanner.js +122 -5
- package/dist/scanner.js.map +1 -1
- package/dist/shields.d.ts +77 -0
- package/dist/shields.d.ts.map +1 -0
- package/dist/shields.js +758 -0
- package/dist/shields.js.map +1 -0
- package/dist/splice.d.ts +40 -15
- package/dist/splice.d.ts.map +1 -1
- package/dist/splice.js +185 -69
- package/dist/splice.js.map +1 -1
- package/package.json +6 -5
- package/src/astgrep.ts +7 -5
- package/src/containers.ts +128 -0
- package/src/coverage.ts +110 -0
- package/src/directives.ts +45 -11
- package/src/files.ts +147 -53
- package/src/imports.ts +42 -17
- package/src/index.ts +1 -0
- package/src/lines.ts +33 -1
- package/src/remove.ts +58 -748
- package/src/run.ts +11 -10
- package/src/scanner.ts +160 -5
- package/src/shields.ts +852 -0
- package/src/splice.ts +216 -75
package/README.md
CHANGED
|
@@ -18,21 +18,22 @@
|
|
|
18
18
|
|
|
19
19
|
## 日本語
|
|
20
20
|
|
|
21
|
-
TypeScript のコメントを一覧し、不要なものを安全に削除する CLI
|
|
21
|
+
TypeScript と JavaScript のコメントを一覧し、不要なものを安全に削除する CLI です。インストールせずに `npx` で実行します。コーディングエージェントがコードに書き足した「レビューの指摘に従い修正」のような経緯のコメントを、エージェントが触ったファイルから取り除く用途を想定しています。
|
|
22
|
+
|
|
23
|
+
```bash
|
|
24
|
+
# 未コミットの変更があるファイルで、削除されるコメントを確かめる
|
|
25
|
+
npx @kongyo2/ts-comment-scanner --remove --dry-run --diff HEAD
|
|
26
|
+
|
|
27
|
+
# 削除する
|
|
28
|
+
npx @kongyo2/ts-comment-scanner --remove --diff HEAD
|
|
29
|
+
```
|
|
22
30
|
|
|
23
31
|
- コメントは TypeScript のパーサーで取り出すので、文字列・テンプレートリテラル・正規表現・JSX テキストの中の `//` や `/*` をコメントと取り違えません。
|
|
24
32
|
- `@ts-expect-error`・`eslint-disable`・`webpackChunkName:` のように、消すとビルドやリントの結果が変わるコメント(ディレクティブ)と、ライセンス表記は残します。
|
|
33
|
+
- 残したディレクティブは、削除の前後で同じコードに適用されます。`eslint-disable-next-line` や `/* c8 ignore next 3 */` が数える行は動かしません。
|
|
25
34
|
- `--diff` を付けると、git で変更があったファイルだけを対象にします。
|
|
26
35
|
- 結果はテキスト・JSON・GitHub Actions のアノテーションで出力します。`--fail-on-comment` を付けると、コメントがあるときに CI を失敗させられます。
|
|
27
36
|
|
|
28
|
-
### インストール
|
|
29
|
-
|
|
30
|
-
```bash
|
|
31
|
-
npm install --save-dev @kongyo2/ts-comment-scanner
|
|
32
|
-
```
|
|
33
|
-
|
|
34
|
-
インストールすると、npm scripts や `npx` から `ts-comment-scanner` コマンドを実行できます。インストールせずに `npx @kongyo2/ts-comment-scanner` で実行することもできます。
|
|
35
|
-
|
|
36
37
|
### 使い方
|
|
37
38
|
|
|
38
39
|
#### コメントを一覧する
|
|
@@ -50,10 +51,10 @@ export function resolveRange(input: string) {
|
|
|
50
51
|
}
|
|
51
52
|
```
|
|
52
53
|
|
|
53
|
-
パスを渡すと、コメントを `ファイル:行:桁` の位置つきで一覧します。ディレクティブには `[@ts-expect-error]`
|
|
54
|
+
パスを渡すと、コメントを `ファイル:行:桁` の位置つきで一覧します。ディレクティブには `[@ts-expect-error]` のように名前が付きます。パスを省略すると、カレントディレクトリが対象です。
|
|
54
55
|
|
|
55
56
|
```console
|
|
56
|
-
$ ts-comment-scanner src
|
|
57
|
+
$ npx @kongyo2/ts-comment-scanner src
|
|
57
58
|
src/range.ts:3:1 [line] // レビューの指摘に従い、空の範囲では HEAD を返すようにした
|
|
58
59
|
src/range.ts:5:36 [line] // 指摘どおり修正
|
|
59
60
|
src/range.ts:6:3 [line] [@ts-expect-error] // @ts-expect-error 上流から null が渡ることがある
|
|
@@ -66,7 +67,7 @@ src/range.ts:6:3 [line] [@ts-expect-error] // @ts-expect-error 上流から null
|
|
|
66
67
|
`--remove --dry-run` で、ファイルを変えずに削除対象を確かめます。
|
|
67
68
|
|
|
68
69
|
```console
|
|
69
|
-
$ ts-comment-scanner --remove --dry-run src
|
|
70
|
+
$ npx @kongyo2/ts-comment-scanner --remove --dry-run src
|
|
70
71
|
src/range.ts: would remove 2 (kept 1)
|
|
71
72
|
|
|
72
73
|
Would remove 2 comments across 1 file. Kept 1 protected comment.
|
|
@@ -87,7 +88,7 @@ export function resolveRange(input: string) {
|
|
|
87
88
|
ディレクティブも消すときは `--remove-directives`、ライセンス表記も消すときは `--remove-legal` を付けます。プロジェクト独自のツールが読む目印のように、ほかにも残したいコメントがあれば `--keep` に正規表現で指定します。
|
|
88
89
|
|
|
89
90
|
```bash
|
|
90
|
-
ts-comment-scanner --remove --keep "@skipMangle" --keep "^// INJECT" src
|
|
91
|
+
npx @kongyo2/ts-comment-scanner --remove --keep "@skipMangle" --keep "^// INJECT" src
|
|
91
92
|
```
|
|
92
93
|
|
|
93
94
|
何を残し、削除後のコードをどう整えるかは[削除の動作](#削除の動作)にまとめています。
|
|
@@ -101,10 +102,10 @@ ts-comment-scanner --remove --keep "@skipMangle" --keep "^// INJECT" src
|
|
|
101
102
|
|
|
102
103
|
```bash
|
|
103
104
|
# 未コミットの変更があるファイルで、削除対象を確かめる
|
|
104
|
-
ts-comment-scanner --remove --dry-run --diff HEAD
|
|
105
|
+
npx @kongyo2/ts-comment-scanner --remove --dry-run --diff HEAD
|
|
105
106
|
|
|
106
107
|
# ブランチで変更したファイルからコメントを削除する
|
|
107
|
-
ts-comment-scanner --remove --diff main...HEAD
|
|
108
|
+
npx @kongyo2/ts-comment-scanner --remove --diff main...HEAD
|
|
108
109
|
```
|
|
109
110
|
|
|
110
111
|
範囲内で削除されたファイルは対象外になり、名前を変えたファイルは新しいパスで扱います。`--diff` は、コマンドラインで直接指定したファイルにも適用します。git は、最初に指定したパスがあるリポジトリで実行します。
|
|
@@ -118,31 +119,113 @@ ts-comment-scanner --remove --diff main...HEAD
|
|
|
118
119
|
run: npx @kongyo2/ts-comment-scanner --format github --skip-directives --fail-on-comment src
|
|
119
120
|
```
|
|
120
121
|
|
|
122
|
+
#### バージョンを固定する
|
|
123
|
+
|
|
124
|
+
`npx @kongyo2/ts-comment-scanner@<バージョン>` のようにバージョンを付けると、そのバージョンで実行します。プロジェクトの devDependencies に入れておくと、npm scripts と `npx ts-comment-scanner` が、入れたバージョンで動きます。
|
|
125
|
+
|
|
126
|
+
```bash
|
|
127
|
+
npm install --save-dev @kongyo2/ts-comment-scanner
|
|
128
|
+
```
|
|
129
|
+
|
|
121
130
|
### 削除の動作
|
|
122
131
|
|
|
123
|
-
`--remove` が削除するのは、TypeScript
|
|
132
|
+
`--remove` が削除するのは、TypeScript のパーサーがコメントと判定した範囲だけです。
|
|
133
|
+
|
|
134
|
+
#### 残すコメント
|
|
124
135
|
|
|
125
136
|
- **ディレクティブ**: 対象のツールは[ディレクティブの判定](#ディレクティブの判定)にまとめています。`/** @internal */` も、消すと `stripInternal` で除いていた宣言が `.d.ts` に出てしまうので残します。`--remove-directives` を付けると削除します。
|
|
126
137
|
- **ライセンス表記**: `/*! … */`・`//! …` の形のコメント、`@license`・`@preserve`・`@copyright` や `SPDX-License-Identifier:` などの SPDX タグを含むコメント、`Copyright (c) …`・`© 2024 …`・`Licensed under …`・`All rights reserved` のような著作権表示、MIT・BSD・MPL・GPL の許諾文です。`--remove-legal` を付けると削除します。
|
|
127
138
|
- **`--keep` の正規表現に一致するコメント**: `--remove-directives` や `--remove-legal` を付けても残ります。
|
|
128
|
-
-
|
|
139
|
+
- **ディレクティブと合わせて読まれるコメント**: ツールがディレクティブを前後のコメントと合わせて読む位置では、ディレクティブの効き方を保つコメントを 1 つ残します。たとえば次の位置です。
|
|
140
|
+
- `@ts-expect-error`・`@ts-ignore` の下にある、ブロックコメントで始まる行。tsc は空行と `//` の行だけを飛ばして適用先の行を探します。この行があるあいだ抑制には適用先がなく、消すと下のコードに適用されます。
|
|
141
|
+
- `@deno-types`・`// falls through`・`/* GraphQL */`・JetBrains の `noinspection` と対象のコードの間にある、最後のコメント。これらは対象の直前のコメントとして読まれます。
|
|
142
|
+
- `/* v8 ignore next */` のようなカバレッジのヒントとコードの間にある、最初のコメント。Vitest の v8 プロバイダーは、ヒントの直後がコメントのときヒントを適用しません。
|
|
143
|
+
- `/* c8 ignore next */` や `// nosemgrep` と同じ行で、その手前にあるコメント。どちらも、同じ行の手前に英数字がないときだけ下の行にも適用されるので、手前のコメントを消すと適用範囲が広がります。
|
|
144
|
+
- JavaScript で、型のタグを持つ JSDoc の後ろに同じ宣言の JSDoc が続くときの、最後の JSDoc。tsc は宣言の最後の JSDoc のタグだけを宣言に適用するので、消すと手前の JSDoc のタグが効き始めます。
|
|
145
|
+
|
|
146
|
+
#### 削除後のコード
|
|
147
|
+
|
|
148
|
+
- コメントだけの行は行ごと、行末のコメントは手前の空白ごと削除します。空行に挟まれたコメント行を消したときは空行を 1 行にまとめ、ファイルやブロックの先頭・末尾でコメントとコードを隔てていた空行は一緒に削除します。
|
|
149
|
+
- ディレクティブが適用される行は動かしません。`eslint-disable-next-line` や `@ts-expect-error` の直下にあるコメント行と、`/* c8 ignore next 3 */` が数える範囲にあるコメント行は、コメントを削除して空行を残します。その範囲にかかる複数行のコメントは、コメントの改行を残します。下にコードが続かないときは、空行も残しません。
|
|
150
|
+
|
|
151
|
+
```ts
|
|
152
|
+
/* c8 ignore next 4 */
|
|
153
|
+
if (input === "") {
|
|
154
|
+
// 呼び出し側で弾いているので、ここには来ない
|
|
155
|
+
throw new Error("empty input");
|
|
156
|
+
}
|
|
157
|
+
```
|
|
158
|
+
|
|
159
|
+
c8 はヒントの下の 4 行を計測から外します。コメント行を詰めると 4 行目が `}` の次の行に変わるので、行を空行として残します。
|
|
160
|
+
|
|
161
|
+
```ts
|
|
162
|
+
/* c8 ignore next 4 */
|
|
163
|
+
if (input === "") {
|
|
164
|
+
|
|
165
|
+
throw new Error("empty input");
|
|
166
|
+
}
|
|
167
|
+
```
|
|
129
168
|
|
|
130
|
-
|
|
169
|
+
行の数え方はツールによって違います。c8・oxlint・Semgrep は LF だけを行の区切りとし、tsc と ESLint は CR・U+2028・U+2029 も区切りとします。どちらの数え方でも行が動かないように改行を残します。
|
|
131
170
|
|
|
132
|
-
-
|
|
171
|
+
- import・export のグループの間や、import・require とその次の文の間にあるコメントを消すと間の空行がなくなるときは、空行に置き換えて、organizeImports や dprint のグループと、newline-after-import が求める空行を保ちます。
|
|
133
172
|
- トークンがつながる位置には空白を入れます(`a/* x */b` → `a b`)。コードに挟まれた、改行を含むブロックコメントは改行に置き換え、自動セミコロン挿入による文の区切りを保ちます。
|
|
134
173
|
- JSX の `{/* … */}` は波かっこごと削除します。波かっこを外すと表示されるテキストが変わる位置では、`{" "}` か `{}` を残します。
|
|
135
174
|
|
|
175
|
+
tsc は JSDoc の `{@link X}` を `X` の使用として数えます。コメントの `{@link X}` だけが参照していた import・変数・引数は、削除後に参照がなくなり、`noUnusedLocals`・`noUnusedParameters` を有効にしていると tsc が未使用として報告します。
|
|
176
|
+
|
|
177
|
+
#### 検証と書き込み
|
|
178
|
+
|
|
136
179
|
書き込む前に削除後のソースを解析し直し、残したコメントの内容とディレクティブとしての意味、JSX の表示内容が変わっていないことを確かめます。一致しないファイルは書き換えず、エラーとして報告します。書き込みは一時ファイルを経由した置き換えなので、途中で失敗しても元のファイルは壊れません。
|
|
137
180
|
|
|
138
181
|
ファイルは UTF-8(BOM の有無は問いません)か BOM 付きの UTF-16 として読み、削除後も元の文字コードと BOM のまま書き戻します。正しくデコードできないファイルからはコメントを削除せず、エラーとして報告します。
|
|
139
182
|
|
|
140
183
|
### 対象ファイルの指定
|
|
141
184
|
|
|
142
|
-
パスを省略するとカレントディレクトリが対象です。ディレクトリは再帰的にたどり、`node_modules` と `.git`
|
|
185
|
+
パスを省略するとカレントディレクトリが対象です。ディレクトリは再帰的にたどり、`node_modules` と `.git` は除外します。シンボリックリンクもたどり、複数のパスから届く同じファイルは 1 回だけ扱います。
|
|
186
|
+
|
|
187
|
+
- `--ext` は対象の拡張子をカンマ区切りで指定します(既定: `.ts,.tsx,.mts,.cts`)。指定した一覧が既定の一覧に置き換わるので、JavaScript も対象にするなら `--ext .ts,.tsx,.js,.jsx` のようにすべて並べます。
|
|
188
|
+
- `--ignore` は Glob に一致するファイルとディレクトリを除外します。スラッシュを含まないパターン(`*.test.ts`)はファイル名に、含むパターン(`src/legacy/**`)はパスに一致します。`dist/` のように末尾をスラッシュにすると、ディレクトリだけに一致します。シンボリックリンクで同じファイルに届くパスが複数あるときは、パスごとに判定します。コマンドラインで直接指定したファイルには適用しません。
|
|
189
|
+
|
|
190
|
+
#### JavaScript
|
|
191
|
+
|
|
192
|
+
`.js`・`.jsx`・`.mjs`・`.cjs` は、tsc と同じように JavaScript として解析します。JSX は常に有効です。
|
|
193
|
+
|
|
194
|
+
tsc は JavaScript の型を JSDoc から読むので、tsc が読むタグを持つ JSDoc コメントはディレクティブとして扱い、`--remove` では残します。対象は `@type`・`@param`・型の付いた `@returns`・`@typedef`・`@callback`・`@template`・`@enum`・`@import`・`@overload`・`@satisfies`・`@this`・`@extends`・`@implements`・`@class`・`@public`・`@private`・`@protected`・`@readonly`・`@override` です。説明文だけの JSDoc と、`@deprecated`・`@example`・`@see` のようなタグだけを持つ JSDoc は削除します。
|
|
143
195
|
|
|
144
|
-
|
|
145
|
-
|
|
196
|
+
```js
|
|
197
|
+
// レビューの指摘に従い、引数の型を JSDoc に書いた
|
|
198
|
+
/**
|
|
199
|
+
* 2 つの数を足す。
|
|
200
|
+
* @param {number} a
|
|
201
|
+
* @param {number} b
|
|
202
|
+
*/
|
|
203
|
+
export function add(a, b) {
|
|
204
|
+
return a + b; // 指摘どおり修正
|
|
205
|
+
}
|
|
206
|
+
|
|
207
|
+
/** 結果を表示する。 */
|
|
208
|
+
export function show(value) {
|
|
209
|
+
console.log(value);
|
|
210
|
+
}
|
|
211
|
+
```
|
|
212
|
+
|
|
213
|
+
`npx @kongyo2/ts-comment-scanner --remove --ext .js src` で削除すると、`@param` を持つ JSDoc が残ります。
|
|
214
|
+
|
|
215
|
+
```js
|
|
216
|
+
/**
|
|
217
|
+
* 2 つの数を足す。
|
|
218
|
+
* @param {number} a
|
|
219
|
+
* @param {number} b
|
|
220
|
+
*/
|
|
221
|
+
export function add(a, b) {
|
|
222
|
+
return a + b;
|
|
223
|
+
}
|
|
224
|
+
|
|
225
|
+
export function show(value) {
|
|
226
|
+
console.log(value);
|
|
227
|
+
}
|
|
228
|
+
```
|
|
146
229
|
|
|
147
230
|
### 出力形式
|
|
148
231
|
|
|
@@ -182,6 +265,10 @@ ts-comment-scanner --remove --diff main...HEAD
|
|
|
182
265
|
|
|
183
266
|
### オプション
|
|
184
267
|
|
|
268
|
+
```text
|
|
269
|
+
npx @kongyo2/ts-comment-scanner [オプション] [パス...]
|
|
270
|
+
```
|
|
271
|
+
|
|
185
272
|
| オプション | 説明 |
|
|
186
273
|
| --- | --- |
|
|
187
274
|
| `--format <fmt>` | 出力形式。`text`・`json`・`github`(既定: `text`) |
|
|
@@ -206,7 +293,7 @@ ts-comment-scanner --remove --diff main...HEAD
|
|
|
206
293
|
|
|
207
294
|
次のツールが読むコメントを、ディレクティブとして判定します。
|
|
208
295
|
|
|
209
|
-
- **コンパイラ・型**: TypeScript(`@ts-ignore`・`@ts-expect-error`・`@ts-nocheck`・`@ts-check`・`/// <reference>`・`@internal
|
|
296
|
+
- **コンパイラ・型**: TypeScript(`@ts-ignore`・`@ts-expect-error`・`@ts-nocheck`・`@ts-check`・`/// <reference>`・`@internal`、JavaScript ファイルの JSDoc の型タグ)、Deno(`@deno-types=`・`@ts-types=`・`@ts-self-types=`)、typescript-strict-plugin(`@ts-strict`・`@ts-strict-ignore`)、Flow(`@flow`・`@noflow`・`$FlowFixMe` 系・`flowlint`)
|
|
210
297
|
- **リンター**: 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
298
|
- **フォーマッタ**: 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
299
|
- **カバレッジ・テスト**: 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
|
|
@@ -219,6 +306,12 @@ ts-comment-scanner --remove --diff main...HEAD
|
|
|
219
306
|
|
|
220
307
|
### ライブラリとして使う
|
|
221
308
|
|
|
309
|
+
同じ処理を関数として呼べます。パッケージを依存に追加して使います。
|
|
310
|
+
|
|
311
|
+
```bash
|
|
312
|
+
npm install @kongyo2/ts-comment-scanner
|
|
313
|
+
```
|
|
314
|
+
|
|
222
315
|
```ts
|
|
223
316
|
import { scanPaths, scanComments, removeComments, changedFiles, formatText } from "@kongyo2/ts-comment-scanner";
|
|
224
317
|
|
|
@@ -238,15 +331,16 @@ const changed = await changedFiles("main..HEAD");
|
|
|
238
331
|
|
|
239
332
|
| 関数 | 説明 |
|
|
240
333
|
| --- | --- |
|
|
241
|
-
| `scanComments(source, options?)` | ソース文字列のコメントを返す。`options.jsx` で JSX
|
|
242
|
-
| `scanFile(file)` | 1
|
|
334
|
+
| `scanComments(source, options?)` | ソース文字列のコメントを返す。`options.jsx` で JSX を有効にし、`options.javascript` で JavaScript として解析する |
|
|
335
|
+
| `scanFile(file)` | 1 ファイルをスキャンする。解析の方法は拡張子で決まる |
|
|
243
336
|
| `scanPaths(inputs, options?)` | ファイルとディレクトリをまとめてスキャンする。`ignore`・`extensions`・`ignoreDirs` を指定できる |
|
|
244
337
|
| `collectFiles(inputs, options?)` | スキャン対象のファイルパスを集める |
|
|
245
338
|
| `changedFiles(range, cwd?)` | git のリビジョン範囲で変更されたファイルの絶対パスを返す |
|
|
246
|
-
| `removeComments(source, options?)` | コメントを削除する。`removeDirectives`・`removeLegal`・`keep`・`shouldRemove` を指定できる |
|
|
339
|
+
| `removeComments(source, options?)` | コメントを削除する。`jsx`・`javascript`・`removeDirectives`・`removeLegal`・`keep`・`shouldRemove` を指定できる |
|
|
247
340
|
| `detectDirective(kind, text, placement?)` | ディレクティブなら正規化した名前を返す。`placement` を渡すと位置に依存する判定もする |
|
|
248
341
|
| `isLegalComment(text)` | ライセンス表記かどうかを返す |
|
|
249
342
|
| `isJsxFile(file)` | JSX を有効にして解析する拡張子かどうかを返す |
|
|
343
|
+
| `isJavaScriptFile(file)` | JavaScript として解析する拡張子かどうかを返す |
|
|
250
344
|
| `formatText(results)`・`formatJson(results)`・`formatGitHub(results)` | スキャン結果を各出力形式の文字列にする |
|
|
251
345
|
| `readFileText(file)`・`decodeFileText(data)`・`encodeFileText(text, target)` | 文字コードと BOM を保ってファイルの内容を読み書きする |
|
|
252
346
|
| `writeFileAtomic(file, data)` | 一時ファイルを経由してファイルを置き換える |
|
|
@@ -263,21 +357,22 @@ MIT
|
|
|
263
357
|
|
|
264
358
|
## English
|
|
265
359
|
|
|
266
|
-
A CLI
|
|
360
|
+
A CLI that lists the comments in a TypeScript or JavaScript project and safely removes the ones you don't want. Run it with `npx`; there is nothing to install. It is built for sweeping the narration coding agents add to code ("fixed per the review feedback") out of the files the agent touched.
|
|
361
|
+
|
|
362
|
+
```bash
|
|
363
|
+
# Preview the removal in files with uncommitted changes
|
|
364
|
+
npx @kongyo2/ts-comment-scanner --remove --dry-run --diff HEAD
|
|
365
|
+
|
|
366
|
+
# Remove the comments
|
|
367
|
+
npx @kongyo2/ts-comment-scanner --remove --diff HEAD
|
|
368
|
+
```
|
|
267
369
|
|
|
268
370
|
- Comments come from the TypeScript parser, so `//` and `/*` inside strings, template literals, regular expressions and JSX text are never mistaken for comments.
|
|
269
371
|
- 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.
|
|
372
|
+
- The directives that stay apply to the same code before and after a removal: the lines an `eslint-disable-next-line` or a `/* c8 ignore next 3 */` counts never move.
|
|
270
373
|
- `--diff` limits the work to the files git reports as changed.
|
|
271
374
|
- Results come out as text, JSON or GitHub Actions annotations, and `--fail-on-comment` fails a CI job when comments are found.
|
|
272
375
|
|
|
273
|
-
### Installation
|
|
274
|
-
|
|
275
|
-
```bash
|
|
276
|
-
npm install --save-dev @kongyo2/ts-comment-scanner
|
|
277
|
-
```
|
|
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
376
|
### Usage
|
|
282
377
|
|
|
283
378
|
#### Listing comments
|
|
@@ -295,10 +390,10 @@ export function resolveRange(input: string) {
|
|
|
295
390
|
}
|
|
296
391
|
```
|
|
297
392
|
|
|
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]`.
|
|
393
|
+
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]`. With no path, the current directory is scanned.
|
|
299
394
|
|
|
300
395
|
```console
|
|
301
|
-
$ ts-comment-scanner src
|
|
396
|
+
$ npx @kongyo2/ts-comment-scanner src
|
|
302
397
|
src/range.ts:3:1 [line] // Per the review feedback, return HEAD for an empty range
|
|
303
398
|
src/range.ts:5:36 [line] // fixed as the reviewer asked
|
|
304
399
|
src/range.ts:6:3 [line] [@ts-expect-error] // @ts-expect-error upstream may pass null
|
|
@@ -311,7 +406,7 @@ src/range.ts:6:3 [line] [@ts-expect-error] // @ts-expect-error upstream may pass
|
|
|
311
406
|
`--remove --dry-run` shows what would be removed without changing any file.
|
|
312
407
|
|
|
313
408
|
```console
|
|
314
|
-
$ ts-comment-scanner --remove --dry-run src
|
|
409
|
+
$ npx @kongyo2/ts-comment-scanner --remove --dry-run src
|
|
315
410
|
src/range.ts: would remove 2 (kept 1)
|
|
316
411
|
|
|
317
412
|
Would remove 2 comments across 1 file. Kept 1 protected comment.
|
|
@@ -332,7 +427,7 @@ export function resolveRange(input: string) {
|
|
|
332
427
|
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
428
|
|
|
334
429
|
```bash
|
|
335
|
-
ts-comment-scanner --remove --keep "@skipMangle" --keep "^// INJECT" src
|
|
430
|
+
npx @kongyo2/ts-comment-scanner --remove --keep "@skipMangle" --keep "^// INJECT" src
|
|
336
431
|
```
|
|
337
432
|
|
|
338
433
|
[How removal works](#how-removal-works) covers what is kept and how the code is tidied up afterwards.
|
|
@@ -346,10 +441,10 @@ With `--diff <range>`, only the files git reports as changed are scanned or clea
|
|
|
346
441
|
|
|
347
442
|
```bash
|
|
348
443
|
# Preview the removal in files with uncommitted changes
|
|
349
|
-
ts-comment-scanner --remove --dry-run --diff HEAD
|
|
444
|
+
npx @kongyo2/ts-comment-scanner --remove --dry-run --diff HEAD
|
|
350
445
|
|
|
351
446
|
# Remove comments from the files changed on the branch
|
|
352
|
-
ts-comment-scanner --remove --diff main...HEAD
|
|
447
|
+
npx @kongyo2/ts-comment-scanner --remove --diff main...HEAD
|
|
353
448
|
```
|
|
354
449
|
|
|
355
450
|
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.
|
|
@@ -363,31 +458,113 @@ Files deleted within the range are skipped, and renamed files are handled at the
|
|
|
363
458
|
run: npx @kongyo2/ts-comment-scanner --format github --skip-directives --fail-on-comment src
|
|
364
459
|
```
|
|
365
460
|
|
|
461
|
+
#### Pinning a version
|
|
462
|
+
|
|
463
|
+
`npx @kongyo2/ts-comment-scanner@<version>` runs that version. With the package in a project's devDependencies, npm scripts and `npx ts-comment-scanner` run the installed version.
|
|
464
|
+
|
|
465
|
+
```bash
|
|
466
|
+
npm install --save-dev @kongyo2/ts-comment-scanner
|
|
467
|
+
```
|
|
468
|
+
|
|
366
469
|
### How removal works
|
|
367
470
|
|
|
368
|
-
`--remove` deletes only the ranges the TypeScript parser reports as comments.
|
|
471
|
+
`--remove` deletes only the ranges the TypeScript parser reports as comments.
|
|
472
|
+
|
|
473
|
+
#### Comments that stay
|
|
369
474
|
|
|
370
475
|
- **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
476
|
- **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
477
|
- **Comments matching a `--keep` pattern,** even with `--remove-directives` or `--remove-legal`.
|
|
373
|
-
- **Comments
|
|
478
|
+
- **Comments a directive is read with.** Where a tool reads a directive together with the comments around it, one comment stays to keep the directive applying as it did. For example:
|
|
479
|
+
- A line that opens with a block comment below `@ts-expect-error` or `@ts-ignore`. tsc steps over blank lines and `//` lines only on its way to the line a suppression applies to, so while that line is there the suppression has no target, and without it the suppression would reach the code below.
|
|
480
|
+
- The last comment between `@deno-types`, `// falls through`, `/* GraphQL */` or a JetBrains `noinspection` and the code it is for. These are read from the comment right in front of their target.
|
|
481
|
+
- The first comment between a coverage hint such as `/* v8 ignore next */` and the code. Vitest's v8 provider applies no hint that a comment follows.
|
|
482
|
+
- A comment in front of `/* c8 ignore next */` or `// nosemgrep` on the same line. Both reach the line below only where no letter or digit precedes them on their line, so removing the comment would widen what they cover.
|
|
483
|
+
- In JavaScript, the last JSDoc comment of a declaration where one holding type tags precedes it. tsc applies only the tags of a declaration's last JSDoc comment to it, so without that comment the tags of the earlier one would take effect.
|
|
484
|
+
|
|
485
|
+
#### The code left behind
|
|
486
|
+
|
|
487
|
+
- 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.
|
|
488
|
+
- The lines a directive applies to never move. A comment line right below `eslint-disable-next-line` or `@ts-expect-error`, or among the lines a `/* c8 ignore next 3 */` counts, is removed and its line stays, empty. A multi-line comment that reaches into those lines leaves its line breaks behind. With no code below, no empty line is left.
|
|
489
|
+
|
|
490
|
+
```ts
|
|
491
|
+
/* c8 ignore next 4 */
|
|
492
|
+
if (input === "") {
|
|
493
|
+
// callers reject the empty string, so this never runs
|
|
494
|
+
throw new Error("empty input");
|
|
495
|
+
}
|
|
496
|
+
```
|
|
497
|
+
|
|
498
|
+
c8 leaves the four lines below the hint out of the report. Closing the gap would make the fourth one the line after the `}`, so the line stays:
|
|
499
|
+
|
|
500
|
+
```ts
|
|
501
|
+
/* c8 ignore next 4 */
|
|
502
|
+
if (input === "") {
|
|
503
|
+
|
|
504
|
+
throw new Error("empty input");
|
|
505
|
+
}
|
|
506
|
+
```
|
|
374
507
|
|
|
375
|
-
The
|
|
508
|
+
Tools count lines differently: c8, oxlint and Semgrep end a line at a line feed only, while tsc and ESLint also end one at a CR, U+2028 or U+2029. The line breaks that stay keep the lines in place under both counts.
|
|
376
509
|
|
|
377
|
-
-
|
|
510
|
+
- Where removing the comments between two groups of imports or exports, or between an import or require and the statement after it, would leave no empty line between them, an empty line takes their place, so organizeImports and dprint keep the groups apart and newline-after-import keeps its empty line.
|
|
378
511
|
- 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
512
|
- A JSX `{/* … */}` goes with its braces. Where dropping the braces would change the rendered text, `{" "}` or `{}` takes their place.
|
|
380
513
|
|
|
514
|
+
tsc counts a `{@link X}` in JSDoc as a use of `X`. An import, variable or parameter that only such a link referred to has no reference left once the comment is gone, and tsc reports it as unused under `noUnusedLocals` and `noUnusedParameters`.
|
|
515
|
+
|
|
516
|
+
#### Verification and writing
|
|
517
|
+
|
|
381
518
|
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
519
|
|
|
383
520
|
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.
|
|
384
521
|
|
|
385
522
|
### Choosing files
|
|
386
523
|
|
|
387
|
-
With no paths, the current directory is scanned. Directories are walked recursively, skipping `node_modules` and `.git`, and symlinks are followed.
|
|
524
|
+
With no paths, the current directory is scanned. Directories are walked recursively, skipping `node_modules` and `.git`, and symlinks are followed; a file reached by several paths is handled once.
|
|
525
|
+
|
|
526
|
+
- `--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`.
|
|
527
|
+
- `--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. Where symlinks give a file several paths, each path is matched on its own. Files listed explicitly on the command line are not subject to `--ignore`.
|
|
528
|
+
|
|
529
|
+
#### JavaScript
|
|
530
|
+
|
|
531
|
+
`.js`, `.jsx`, `.mjs` and `.cjs` files are parsed as JavaScript, the way tsc parses them. JSX is always enabled.
|
|
532
|
+
|
|
533
|
+
tsc takes the types of a JavaScript file from JSDoc, so a JSDoc comment holding a tag tsc reads is a directive, and `--remove` keeps it. The tags are `@type`, `@param`, `@returns` with a type, `@typedef`, `@callback`, `@template`, `@enum`, `@import`, `@overload`, `@satisfies`, `@this`, `@extends`, `@implements`, `@class`, `@public`, `@private`, `@protected`, `@readonly` and `@override`. A JSDoc comment that only describes, or holds only tags such as `@deprecated`, `@example` and `@see`, is removed.
|
|
534
|
+
|
|
535
|
+
```js
|
|
536
|
+
// Per the review feedback, the argument types went into JSDoc
|
|
537
|
+
/**
|
|
538
|
+
* Adds two numbers.
|
|
539
|
+
* @param {number} a
|
|
540
|
+
* @param {number} b
|
|
541
|
+
*/
|
|
542
|
+
export function add(a, b) {
|
|
543
|
+
return a + b; // fixed as the reviewer asked
|
|
544
|
+
}
|
|
545
|
+
|
|
546
|
+
/** Prints the result. */
|
|
547
|
+
export function show(value) {
|
|
548
|
+
console.log(value);
|
|
549
|
+
}
|
|
550
|
+
```
|
|
551
|
+
|
|
552
|
+
`npx @kongyo2/ts-comment-scanner --remove --ext .js src` leaves the JSDoc comment that holds the `@param` tags:
|
|
553
|
+
|
|
554
|
+
```js
|
|
555
|
+
/**
|
|
556
|
+
* Adds two numbers.
|
|
557
|
+
* @param {number} a
|
|
558
|
+
* @param {number} b
|
|
559
|
+
*/
|
|
560
|
+
export function add(a, b) {
|
|
561
|
+
return a + b;
|
|
562
|
+
}
|
|
388
563
|
|
|
389
|
-
|
|
390
|
-
|
|
564
|
+
export function show(value) {
|
|
565
|
+
console.log(value);
|
|
566
|
+
}
|
|
567
|
+
```
|
|
391
568
|
|
|
392
569
|
### Output formats
|
|
393
570
|
|
|
@@ -427,6 +604,10 @@ With `--remove`, each entry of `files` carries three arrays: `removed`, `kept` a
|
|
|
427
604
|
|
|
428
605
|
### Options
|
|
429
606
|
|
|
607
|
+
```text
|
|
608
|
+
npx @kongyo2/ts-comment-scanner [options] [paths...]
|
|
609
|
+
```
|
|
610
|
+
|
|
430
611
|
| Option | Description |
|
|
431
612
|
| --- | --- |
|
|
432
613
|
| `--format <fmt>` | Output format: `text`, `json` or `github` (default: `text`) |
|
|
@@ -451,7 +632,7 @@ Exit codes: `0` on success, `1` when `--fail-on-comment` is set and comments are
|
|
|
451
632
|
|
|
452
633
|
Comments read by these tools are detected as directives:
|
|
453
634
|
|
|
454
|
-
- **Compilers and types**: TypeScript (`@ts-ignore`, `@ts-expect-error`, `@ts-nocheck`, `@ts-check`, `/// <reference>`, `@internal
|
|
635
|
+
- **Compilers and types**: TypeScript (`@ts-ignore`, `@ts-expect-error`, `@ts-nocheck`, `@ts-check`, `/// <reference>`, `@internal`, the JSDoc type tags of a JavaScript file), Deno (`@deno-types=`, `@ts-types=`, `@ts-self-types=`), typescript-strict-plugin (`@ts-strict`, `@ts-strict-ignore`), Flow (`@flow`, `@noflow`, the `$FlowFixMe` family, `flowlint`)
|
|
455
636
|
- **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
637
|
- **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
638
|
- **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
|
|
@@ -464,6 +645,12 @@ Each rule matches a comment the way the tool's own parser does. Directives that
|
|
|
464
645
|
|
|
465
646
|
### Using it as a library
|
|
466
647
|
|
|
648
|
+
The same operations are available as functions. Add the package as a dependency:
|
|
649
|
+
|
|
650
|
+
```bash
|
|
651
|
+
npm install @kongyo2/ts-comment-scanner
|
|
652
|
+
```
|
|
653
|
+
|
|
467
654
|
```ts
|
|
468
655
|
import { scanPaths, scanComments, removeComments, changedFiles, formatText } from "@kongyo2/ts-comment-scanner";
|
|
469
656
|
|
|
@@ -483,15 +670,16 @@ const changed = await changedFiles("main..HEAD");
|
|
|
483
670
|
|
|
484
671
|
| Function | Description |
|
|
485
672
|
| --- | --- |
|
|
486
|
-
| `scanComments(source, options?)` | Returns the comments in a source string; `options.jsx` enables JSX |
|
|
487
|
-
| `scanFile(file)` | Scans one file |
|
|
673
|
+
| `scanComments(source, options?)` | Returns the comments in a source string; `options.jsx` enables JSX, and `options.javascript` parses the source as JavaScript |
|
|
674
|
+
| `scanFile(file)` | Scans one file, parsed as its extension calls for |
|
|
488
675
|
| `scanPaths(inputs, options?)` | Scans files and directories; accepts `ignore`, `extensions` and `ignoreDirs` |
|
|
489
676
|
| `collectFiles(inputs, options?)` | Collects the paths of the files to scan |
|
|
490
677
|
| `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` |
|
|
678
|
+
| `removeComments(source, options?)` | Removes comments; accepts `jsx`, `javascript`, `removeDirectives`, `removeLegal`, `keep` and `shouldRemove` |
|
|
492
679
|
| `detectDirective(kind, text, placement?)` | Returns the normalized name if the comment is a directive; `placement` enables the position-dependent rules |
|
|
493
680
|
| `isLegalComment(text)` | Returns whether the comment is a license notice |
|
|
494
681
|
| `isJsxFile(file)` | Returns whether the file's extension is parsed with JSX enabled |
|
|
682
|
+
| `isJavaScriptFile(file)` | Returns whether the file's extension is parsed as JavaScript |
|
|
495
683
|
| `formatText(results)`, `formatJson(results)`, `formatGitHub(results)` | Formats scan results in each output format |
|
|
496
684
|
| `readFileText(file)`, `decodeFileText(data)`, `encodeFileText(text, target)` | Reads and writes file contents, preserving the encoding and BOM |
|
|
497
685
|
| `writeFileAtomic(file, data)` | Replaces a file through a temporary file |
|
package/dist/astgrep.d.ts
CHANGED
|
@@ -42,8 +42,10 @@ export interface AstGrepReach {
|
|
|
42
42
|
* when deleted, so those ending on its row in front of it stay, as do those
|
|
43
43
|
* after it on its row and those touching the row its node starts on; when a
|
|
44
44
|
* release covers the next row, so do those starting there, and that row's
|
|
45
|
-
* lines stay (see nextRow). On the first row, the
|
|
46
|
-
*
|
|
45
|
+
* lines stay (see nextRow). On the first row, the node after the comment
|
|
46
|
+
* decides whether it covers the file: where that node starts less than two
|
|
47
|
+
* rows down, the unit it is stays, since whatever follows it could start
|
|
48
|
+
* further down.
|
|
47
49
|
* The releases this follows parse with tree-sitter 0.24 or later (ast-grep
|
|
48
50
|
* 0.31.1 on); before, comments in JSX braces read as standing alone.
|
|
49
51
|
*/
|
package/dist/astgrep.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"astgrep.d.ts","sourceRoot":"","sources":["../src/astgrep.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AAkBzC;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAIpF;AAMD,qGAAqG;AACrG,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAEtD;AAED,gHAAgH;AAChH,MAAM,WAAW,aAAa;IAC5B,6FAA6F;IAC7F,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,2EAA2E;IAC3E,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,iFAAiF;AACjF,MAAM,WAAW,YAAY;IAC3B,kFAAkF;IAClF,KAAK,CAAC,IAAI,EAAE,KAAK,GAAG,OAAO,CAAC;IAC5B;;;OAGG;IACH,OAAO,EAAE,KAAK,GAAG,SAAS,CAAC;CAC5B;AAED
|
|
1
|
+
{"version":3,"file":"astgrep.d.ts","sourceRoot":"","sources":["../src/astgrep.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AAkBzC;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAIpF;AAMD,qGAAqG;AACrG,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAEtD;AAED,gHAAgH;AAChH,MAAM,WAAW,aAAa;IAC5B,6FAA6F;IAC7F,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,2EAA2E;IAC3E,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,iFAAiF;AACjF,MAAM,WAAW,YAAY;IAC3B,kFAAkF;IAClF,KAAK,CAAC,IAAI,EAAE,KAAK,GAAG,OAAO,CAAC;IAC5B;;;OAGG;IACH,OAAO,EAAE,KAAK,GAAG,SAAS,CAAC;CAC5B;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,YAAY,CAC1B,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,SAAS,MAAM,EAAE,EAC5B,OAAO,EAAE,KAAK,EACd,SAAS,EAAE,aAAa,GACvB,YAAY,CAwBd"}
|
package/dist/astgrep.js
CHANGED
|
@@ -49,8 +49,10 @@ export function rowStartOffsets(text) {
|
|
|
49
49
|
* when deleted, so those ending on its row in front of it stay, as do those
|
|
50
50
|
* after it on its row and those touching the row its node starts on; when a
|
|
51
51
|
* release covers the next row, so do those starting there, and that row's
|
|
52
|
-
* lines stay (see nextRow). On the first row, the
|
|
53
|
-
*
|
|
52
|
+
* lines stay (see nextRow). On the first row, the node after the comment
|
|
53
|
+
* decides whether it covers the file: where that node starts less than two
|
|
54
|
+
* rows down, the unit it is stays, since whatever follows it could start
|
|
55
|
+
* further down.
|
|
54
56
|
* The releases this follows parse with tree-sitter 0.24 or later (ast-grep
|
|
55
57
|
* 0.31.1 on); before, comments in JSX braces read as standing alone.
|
|
56
58
|
*/
|
|
@@ -69,10 +71,11 @@ export function astGrepReach(text, rowStarts, comment, preceding) {
|
|
|
69
71
|
if (precedingRow !== undefined && precedingRow < row) {
|
|
70
72
|
breaking.push({ start: rowStart(precedingRow), end: rowStart(precedingRow + 1) });
|
|
71
73
|
}
|
|
72
|
-
const
|
|
74
|
+
const next = comment.end + text.slice(comment.end).search(TREE_SITTER_CONTENT);
|
|
75
|
+
const nextNode = opensFirstRow(text, comment.start) && next >= comment.end && next < rowStart(2) ? next : undefined;
|
|
73
76
|
return {
|
|
74
77
|
holds: (unit) => (unit.end > ownRow && unit.end <= comment.start && (unit.start >= preceding.tokenEnd || breaks(unit))) ||
|
|
75
|
-
|
|
78
|
+
unit.start === nextNode ||
|
|
76
79
|
(breaking.some((span) => unit.start < span.end && unit.end >= span.start) && breaks(unit)),
|
|
77
80
|
nextRow: coversNextRow ? { start: comment.end, end: rowStart(row + 2) } : undefined,
|
|
78
81
|
};
|
package/dist/astgrep.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"astgrep.js","sourceRoot":"","sources":["../src/astgrep.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAG5E;;;;;;GAMG;AACH,MAAM,iBAAiB,GAAG,qBAAqB,CAAC;AAChD,MAAM,mBAAmB,GAAG,mBAAmB,CAAC;AAEhD,4GAA4G;AAC5G,SAAS,aAAa,CAAC,IAAY,EAAE,MAAc;IACjD,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC;IACrC,OAAO,iBAAiB,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;AAClE,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,kBAAkB,CAAC,IAAY,EAAE,KAAa,EAAE,GAAW;IACzE,IAAI,CAAC,aAAa,CAAC,IAAI,EAAE,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IAC9C,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,mBAAmB,CAAC,CAAC;IACzD,OAAO,IAAI,KAAK,CAAC,CAAC,IAAI,aAAa,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,GAAG,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC;AACtE,CAAC;AAED,SAAS,aAAa,CAAC,IAAY;IACjC,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC;AACrC,CAAC;AAED,qGAAqG;AACrG,MAAM,UAAU,eAAe,CAAC,IAAY;IAC1C,OAAO,gBAAgB,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;AACtC,CAAC;AAqBD
|
|
1
|
+
{"version":3,"file":"astgrep.js","sourceRoot":"","sources":["../src/astgrep.ts"],"names":[],"mappings":"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"}
|
|
@@ -0,0 +1,48 @@
|
|
|
1
|
+
import type { JsxContainer } from "./jsx.js";
|
|
2
|
+
import { type Range } from "./ranges.js";
|
|
3
|
+
import type { Comment } from "./types.js";
|
|
4
|
+
/**
|
|
5
|
+
* How a comment-only JSX container goes once all its comments do: braces
|
|
6
|
+
* and all; replaced by `{" "}` together with the spaces that held it off its
|
|
7
|
+
* neighbour; or with its braces kept, only the comments going.
|
|
8
|
+
*/
|
|
9
|
+
type ContainerMode = "drop" | "space" | "keep";
|
|
10
|
+
/** A comment-only JSX container (`{/* note */}`) with the comments in it. */
|
|
11
|
+
export interface Container extends Range {
|
|
12
|
+
segment: number;
|
|
13
|
+
suspect: boolean;
|
|
14
|
+
/** The comment-only container right after it among the siblings, if any. */
|
|
15
|
+
next: Container | undefined;
|
|
16
|
+
comments: Comment[];
|
|
17
|
+
mode: ContainerMode;
|
|
18
|
+
/** What `{" "}` would replace, when the container shares its line and is held off by spaces. */
|
|
19
|
+
spaceRange: Range | undefined;
|
|
20
|
+
}
|
|
21
|
+
export declare function attachContainers(source: string, layouts: readonly JsxContainer[], comments: readonly Comment[]): Container[];
|
|
22
|
+
/**
|
|
23
|
+
* The comments, in document order, with those of every container that
|
|
24
|
+
* `merges` accepts merged into the container itself: one unit spanning its
|
|
25
|
+
* braces in place of the comments inside them.
|
|
26
|
+
*/
|
|
27
|
+
export declare function mergeContainers(comments: readonly Comment[], containerOf: ReadonlyMap<Comment, Container>, merges: (container: Container) => boolean): Array<Comment | Container>;
|
|
28
|
+
/** Whether the container's comments are all among the given ones, so that its braces can go with them. */
|
|
29
|
+
export declare function emptiedBy(container: Container, comments: ReadonlySet<Comment>): boolean;
|
|
30
|
+
/**
|
|
31
|
+
* What deleting part of the removal takes out of the source: a single
|
|
32
|
+
* comment, or a comment-only JSX container going braces and all.
|
|
33
|
+
*/
|
|
34
|
+
export interface RemovalUnit extends Range {
|
|
35
|
+
comments: readonly Comment[];
|
|
36
|
+
/** The unit is a container's braces, which go with the comments in them. */
|
|
37
|
+
braces: boolean;
|
|
38
|
+
}
|
|
39
|
+
/**
|
|
40
|
+
* The removals as the edits delete them: a comment-only container whose
|
|
41
|
+
* comments all go — and that is to go braces and all — is one unit spanning
|
|
42
|
+
* its braces, every other comment a unit of its own. Sorted, as the comments.
|
|
43
|
+
*/
|
|
44
|
+
export declare function removalUnits(removals: readonly Comment[], containerOf: ReadonlyMap<Comment, Container>): RemovalUnit[];
|
|
45
|
+
/** The comments the units delete. */
|
|
46
|
+
export declare function commentsOf(units: readonly RemovalUnit[]): Comment[];
|
|
47
|
+
export {};
|
|
48
|
+
//# sourceMappingURL=containers.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"containers.d.ts","sourceRoot":"","sources":["../src/containers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAE7C,OAAO,EAAgB,KAAK,KAAK,EAAE,MAAM,aAAa,CAAC;AACvD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAE1C;;;;GAIG;AACH,KAAK,aAAa,GAAG,MAAM,GAAG,OAAO,GAAG,MAAM,CAAC;AAE/C,8EAA8E;AAC9E,MAAM,WAAW,SAAU,SAAQ,KAAK;IACtC,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,OAAO,CAAC;IACjB,4EAA4E;IAC5E,IAAI,EAAE,SAAS,GAAG,SAAS,CAAC;IAC5B,QAAQ,EAAE,OAAO,EAAE,CAAC;IACpB,IAAI,EAAE,aAAa,CAAC;IACpB,gGAAgG;IAChG,UAAU,EAAE,KAAK,GAAG,SAAS,CAAC;CAC/B;AAED,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,SAAS,YAAY,EAAE,EAChC,QAAQ,EAAE,SAAS,OAAO,EAAE,GAC3B,SAAS,EAAE,CAkBb;AAsBD;;;;GAIG;AACH,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,SAAS,OAAO,EAAE,EAC5B,WAAW,EAAE,WAAW,CAAC,OAAO,EAAE,SAAS,CAAC,EAC5C,MAAM,EAAE,CAAC,SAAS,EAAE,SAAS,KAAK,OAAO,GACxC,KAAK,CAAC,OAAO,GAAG,SAAS,CAAC,CAQ5B;AAED,0GAA0G;AAC1G,wBAAgB,SAAS,CAAC,SAAS,EAAE,SAAS,EAAE,QAAQ,EAAE,WAAW,CAAC,OAAO,CAAC,GAAG,OAAO,CAEvF;AAED;;;GAGG;AACH,MAAM,WAAW,WAAY,SAAQ,KAAK;IACxC,QAAQ,EAAE,SAAS,OAAO,EAAE,CAAC;IAC7B,4EAA4E;IAC5E,MAAM,EAAE,OAAO,CAAC;CACjB;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAC1B,QAAQ,EAAE,SAAS,OAAO,EAAE,EAC5B,WAAW,EAAE,WAAW,CAAC,OAAO,EAAE,SAAS,CAAC,GAC3C,WAAW,EAAE,CAYf;AAED,qCAAqC;AACrC,wBAAgB,UAAU,CAAC,KAAK,EAAE,SAAS,WAAW,EAAE,GAAG,OAAO,EAAE,CAEnE"}
|