@kongyo2/ts-comment-scanner 1.2.1 → 1.4.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.en.md +31 -10
- package/README.md +29 -8
- package/dist/directives.d.ts +24 -3
- package/dist/directives.d.ts.map +1 -1
- package/dist/directives.js +313 -29
- package/dist/directives.js.map +1 -1
- package/dist/files.d.ts +34 -0
- package/dist/files.d.ts.map +1 -1
- package/dist/files.js +148 -20
- package/dist/files.js.map +1 -1
- package/dist/git.js +6 -6
- package/dist/git.js.map +1 -1
- package/dist/index.d.ts +2 -2
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +1 -1
- package/dist/index.js.map +1 -1
- package/dist/remove.js +154 -29
- package/dist/remove.js.map +1 -1
- package/dist/report.d.ts.map +1 -1
- package/dist/report.js +24 -2
- package/dist/report.js.map +1 -1
- package/dist/run.d.ts.map +1 -1
- package/dist/run.js +47 -13
- package/dist/run.js.map +1 -1
- package/dist/scanner.d.ts.map +1 -1
- package/dist/scanner.js +43 -25
- package/dist/scanner.js.map +1 -1
- package/package.json +11 -5
- package/src/args.ts +198 -0
- package/src/cli.ts +12 -0
- package/src/directives.ts +492 -0
- package/src/files.ts +304 -0
- package/src/git.ts +72 -0
- package/src/index.ts +19 -0
- package/src/remove.ts +410 -0
- package/src/report.ts +106 -0
- package/src/run.ts +283 -0
- package/src/scanner.ts +104 -0
- package/src/types.ts +19 -0
- package/src/version.ts +7 -0
package/README.en.md
CHANGED
|
@@ -1,24 +1,30 @@
|
|
|
1
|
+
<p align="center">
|
|
2
|
+
<a href="https://kongyo2.github.io/ts-comment-scanner/"><img src="https://raw.githubusercontent.com/kongyo2/ts-comment-scanner/main/assets/logo.svg" width="96" height="96" alt="ts-comment-scanner logo"></a>
|
|
3
|
+
</p>
|
|
4
|
+
|
|
1
5
|
# ts-comment-scanner
|
|
2
6
|
|
|
3
7
|
[](https://www.npmjs.com/package/@kongyo2/ts-comment-scanner)
|
|
4
8
|
[](https://www.npmjs.com/package/@kongyo2/ts-comment-scanner)
|
|
5
9
|
[](https://github.com/kongyo2/ts-comment-scanner/actions/workflows/ci.yml)
|
|
10
|
+
[](https://kongyo2.github.io/ts-comment-scanner/)
|
|
6
11
|

|
|
7
12
|
[](https://nodejs.org)
|
|
8
13
|
[](./LICENSE)
|
|
9
14
|
[](https://deepwiki.com/kongyo2/ts-comment-scanner)
|
|
10
15
|
|
|
11
|
-
[日本語](./README.md) | **English**
|
|
16
|
+
[日本語](./README.md) | **English** | 📘 [Project site](https://kongyo2.github.io/ts-comment-scanner/?lang=en)
|
|
12
17
|
|
|
13
18
|
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.
|
|
14
19
|
|
|
15
20
|
## Features
|
|
16
21
|
|
|
17
|
-
- Recursively scans `.ts` `.tsx` `.mts` `.cts` (excluding `node_modules` and `.git`)
|
|
22
|
+
- 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
|
|
18
23
|
- Reports line comments (`//`) and block comments (`/* */`) with position information
|
|
19
24
|
- Outputs in three formats: text / JSON / **GitHub Actions annotations**
|
|
20
25
|
- **Automatically identifies compiler and linter directives** such as `@ts-ignore` and `eslint-disable`, so you can filter them in or out
|
|
21
26
|
- **Safe comment removal** (code cleanup): directives and license headers are kept by default
|
|
27
|
+
- 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**
|
|
22
28
|
- **Custom ignore patterns** via glob (`--ignore`) and configurable target extensions (`--ext`)
|
|
23
29
|
- **git integration (`--diff`)**: narrow the scan to files touched between specific commits or in uncommitted work
|
|
24
30
|
- `--fail-on-comment` for CI (exit code 1 when comments are detected)
|
|
@@ -95,11 +101,11 @@ $ ts-comment-scanner --json src
|
|
|
95
101
|
"kind": "line",
|
|
96
102
|
"text": "// entry point",
|
|
97
103
|
"start": 0,
|
|
98
|
-
"end":
|
|
104
|
+
"end": 14,
|
|
99
105
|
"line": 1,
|
|
100
106
|
"column": 1,
|
|
101
107
|
"endLine": 1,
|
|
102
|
-
"endColumn":
|
|
108
|
+
"endColumn": 15
|
|
103
109
|
}
|
|
104
110
|
]
|
|
105
111
|
}
|
|
@@ -119,9 +125,11 @@ Comments identified as directives get a name attached, such as `"directive": "@t
|
|
|
119
125
|
```
|
|
120
126
|
|
|
121
127
|
```
|
|
122
|
-
::notice file=src/index.ts,line=1,endLine=1,col=1,endColumn=
|
|
128
|
+
::notice file=src/index.ts,line=1,endLine=1,col=1,endColumn=14,title=line comment::// entry point
|
|
123
129
|
```
|
|
124
130
|
|
|
131
|
+
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.
|
|
132
|
+
|
|
125
133
|
### Bulk comment removal (code cleanup)
|
|
126
134
|
|
|
127
135
|
```bash
|
|
@@ -138,10 +146,12 @@ ts-comment-scanner --remove --remove-directives --remove-legal src
|
|
|
138
146
|
Removal is driven by the AST's comment ranges, so it never touches strings or code. In addition:
|
|
139
147
|
|
|
140
148
|
- Directives such as `@ts-expect-error` / `eslint-disable` are **kept by default**, because removing them would break the build or the linter
|
|
141
|
-
- Legal comments — `/*! ... */` or those containing `@license` / `@preserve` / `@copyright` — are also **kept by default**
|
|
149
|
+
- Legal comments — `/*! ... */` or those containing `@license` / `@preserve` / `@copyright` or the `SPDX-License-Identifier:` / `SPDX-FileCopyrightText:` tags — are also **kept by default**
|
|
150
|
+
- **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
|
|
142
151
|
- Whitespace is inserted where removing a block comment would otherwise join tokens together (`a/* x */b` → `a b`)
|
|
143
152
|
- Comment-only lines are removed entirely, and trailing comments are removed together with the preceding whitespace
|
|
144
|
-
- The result is re-scanned to verify
|
|
153
|
+
- The result is re-scanned to verify that the surviving comments match the protected set; if the outcome is unexpected the file is left unchanged and an error is reported
|
|
154
|
+
- Writes go through a temporary file and an atomic rename, so a failed write or a full disk can never truncate the original
|
|
145
155
|
|
|
146
156
|
### Scanning only changed files (`--diff`)
|
|
147
157
|
|
|
@@ -162,7 +172,16 @@ This is designed for workflows like letting a coding agent do some work and then
|
|
|
162
172
|
|
|
163
173
|
### Detectable directives (excerpt)
|
|
164
174
|
|
|
165
|
-
|
|
175
|
+
Each directive is matched the way the real tool's parser matches it (its regex or string comparison).
|
|
176
|
+
|
|
177
|
+
- **Compiler / types**: `@ts-ignore` `@ts-expect-error` `@ts-nocheck` `@ts-check` / `/// <reference>` / `@ts-strict-ignore`, `@ts-strict` (typescript-strict-plugin) / `@deno-types=`, `@ts-types=`, `@ts-self-types=` (Deno)
|
|
178
|
+
- **Linters**: the `eslint-disable` family, `eslint-env`, `/* global */`, `/* exported */` / the `oxlint-disable` family / the `biome-ignore` family, `rome-ignore` / the `deno-lint-ignore` family / `@flow`, `@noflow`, the `$FlowFixMe` family, `flowlint` (Flow) / `tslint:`, `jshint`, `jscs:`, `jslint` (legacy)
|
|
179
|
+
- **Formatters**: `prettier-ignore`, the `@format`/`@prettier`/`@noformat`/`@noprettier` pragmas / `oxfmt-ignore` / `dprint-ignore`, `dprint-ignore-file` / `organize-imports-ignore` / `beautify ignore/preserve` (legacy)
|
|
180
|
+
- **Coverage / testing**: `istanbul ignore`, `c8 ignore`, `v8 ignore`, `node:coverage` / `@jest-environment(-options)`, `@vitest-environment(-options)`, `@module-tag` (Vitest 4) / `Stryker disable/restore` / `type-coverage:ignore-line/-next-line` / `ts-prune-ignore-next`
|
|
181
|
+
- **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` (react-refresh / solid-refresh) / `million-ignore` / `nx-ignore-next-line` (Nx) / `@unocss-include/-ignore/-skip-start/-skip-end` / `@next-codemod-error/-ignore` (Next.js) / `/* GraphQL */`, `/* HTML */` tag comments / `//# sourceMappingURL=`, `//# sourceURL=` / `@jsx`-family pragmas
|
|
182
|
+
- **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)
|
|
183
|
+
- **Spell checkers**: the `cspell:` family (including the `cSpell:`, `spell-checker:`, `spellchecker:` aliases), `LocalWords` / `codespell:ignore`
|
|
184
|
+
- **Editors / IDEs**: `#region`, `#endregion` / `noinspection`, `<editor-fold>`, `language=` (JetBrains) / `ReSharper disable/restore`
|
|
166
185
|
|
|
167
186
|
## Using it as a library
|
|
168
187
|
|
|
@@ -193,11 +212,13 @@ const changed = await changedFiles("main..HEAD");
|
|
|
193
212
|
| `collectFiles(inputs, options?)` | Collect the list of target file paths |
|
|
194
213
|
| `changedFiles(range, cwd?)` | Absolute paths of working-tree files changed in a git revision range |
|
|
195
214
|
| `removeComments(source, options?)` | Remove comments safely (`removeDirectives` / `removeLegal` / `shouldRemove`) |
|
|
196
|
-
| `detectDirective(kind, text)` | Return a normalized name if the comment is a directive |
|
|
215
|
+
| `detectDirective(kind, text, placement?)` | Return a normalized name if the comment is a directive (`placement` enables position-sensitive rules) |
|
|
197
216
|
| `isLegalComment(text)` | Determine whether a comment is a license/legal comment |
|
|
198
217
|
| `formatText(results)` / `formatJson(results)` / `formatGitHub(results)` | Format scan results |
|
|
218
|
+
| `readFileText(file)` / `decodeFileText(data)` / `encodeFileText(text, target)` | Read/decode/encode helpers that preserve UTF-8 / UTF-16 and BOMs |
|
|
219
|
+
| `writeFileAtomic(file, data)` | Replace a file atomically through a temporary sibling |
|
|
199
220
|
|
|
200
|
-
Types: `Comment` / `CommentKind` / `FileScanResult` / `ScanOptions` / `CollectOptions` / `RemoveOptions` / `RemoveResult`
|
|
221
|
+
Types: `Comment` / `CommentKind` / `FileScanResult` / `ScanOptions` / `CollectOptions` / `RemoveOptions` / `RemoveResult` / `FileText` / `FileEncoding` / `DirectivePlacement`
|
|
201
222
|
|
|
202
223
|
## Requirements
|
|
203
224
|
|
package/README.md
CHANGED
|
@@ -1,24 +1,30 @@
|
|
|
1
|
+
<p align="center">
|
|
2
|
+
<a href="https://kongyo2.github.io/ts-comment-scanner/"><img src="https://raw.githubusercontent.com/kongyo2/ts-comment-scanner/main/assets/logo.svg" width="96" height="96" alt="ts-comment-scanner ロゴ"></a>
|
|
3
|
+
</p>
|
|
4
|
+
|
|
1
5
|
# ts-comment-scanner
|
|
2
6
|
|
|
3
7
|
[](https://www.npmjs.com/package/@kongyo2/ts-comment-scanner)
|
|
4
8
|
[](https://www.npmjs.com/package/@kongyo2/ts-comment-scanner)
|
|
5
9
|
[](https://github.com/kongyo2/ts-comment-scanner/actions/workflows/ci.yml)
|
|
10
|
+
[](https://kongyo2.github.io/ts-comment-scanner/)
|
|
6
11
|

|
|
7
12
|
[](https://nodejs.org)
|
|
8
13
|
[](./LICENSE)
|
|
9
14
|
[](https://deepwiki.com/kongyo2/ts-comment-scanner)
|
|
10
15
|
|
|
11
|
-
**日本語** | [English](./README.en.md)
|
|
16
|
+
**日本語** | [English](./README.en.md) | 📘 [プロジェクトサイト](https://kongyo2.github.io/ts-comment-scanner/)
|
|
12
17
|
|
|
13
18
|
TypeScript プロジェクト内のコメントを検出・一覧・集計し、安全に削除もできる CLI / ライブラリです。TypeScript の AST を使って解析するため、文字列・テンプレートリテラル・正規表現・JSX テキストを誤検出しません。
|
|
14
19
|
|
|
15
20
|
## 特徴
|
|
16
21
|
|
|
17
|
-
- `.ts` `.tsx` `.mts` `.cts` を再帰的にスキャン(`node_modules` と `.git` は除外)
|
|
22
|
+
- `.ts` `.tsx` `.mts` `.cts` を再帰的にスキャン(`node_modules` と `.git` は除外)。シンボリックリンクは明示指定時と同様に走査中も追跡し、循環は自動検知して停止
|
|
18
23
|
- 行コメント (`//`) とブロックコメント (`/* */`) を位置情報つきで報告
|
|
19
24
|
- テキスト / JSON / **GitHub Actions アノテーション**の 3 形式で出力
|
|
20
25
|
- `@ts-ignore` や `eslint-disable` などの**コンパイラ・リンター指示子(ディレクティブ)を自動判別**し、絞り込み・除外が可能
|
|
21
26
|
- **安全なコメント削除**(コードクリーンアップ): ディレクティブとライセンスヘッダーはデフォルトで保持
|
|
27
|
+
- UTF-8(BOM 付き可)と BOM 付き UTF-16(LE/BE)に対応。削除時もエンコーディングと BOM を保持し、不正なエンコーディングのファイルは**変更せずに**エラー報告
|
|
22
28
|
- Glob による**カスタム無視パターン** (`--ignore`)、対象拡張子の変更 (`--ext`)
|
|
23
29
|
- **git 連携 (`--diff`)**: 特定コミット間や未コミットの変更で触れられたファイルだけに対象を絞り込み
|
|
24
30
|
- CI 向けの `--fail-on-comment`(コメント検出時に終了コード 1)
|
|
@@ -119,9 +125,11 @@ $ ts-comment-scanner --json src
|
|
|
119
125
|
```
|
|
120
126
|
|
|
121
127
|
```
|
|
122
|
-
::notice file=src/index.ts,line=1,endLine=1,col=1,endColumn=
|
|
128
|
+
::notice file=src/index.ts,line=1,endLine=1,col=1,endColumn=12,title=line comment::// エントリーポイント
|
|
123
129
|
```
|
|
124
130
|
|
|
131
|
+
JSON 出力の `endColumn` が排他的(コメント末尾の次の桁)なのに対し、GitHub アノテーションの列は両端含みのため、ここでは最後の文字の桁(この例では 12)が出力されます。64 KiB を超える巨大なコメントは、GitHub の上限に収まるよう安全に切り詰められます。
|
|
132
|
+
|
|
125
133
|
### コメントの一括削除(コードクリーンアップ)
|
|
126
134
|
|
|
127
135
|
```bash
|
|
@@ -138,10 +146,12 @@ ts-comment-scanner --remove --remove-directives --remove-legal src
|
|
|
138
146
|
削除は AST のコメント範囲に基づいて行われるため、文字列やコードには影響しません。さらに:
|
|
139
147
|
|
|
140
148
|
- `@ts-expect-error` / `eslint-disable` などの指示子は、削除するとビルドやリントが壊れるため**デフォルトで保持**
|
|
141
|
-
- `/*! ... */` や `@license` / `@preserve` / `@copyright`
|
|
149
|
+
- `/*! ... */` や `@license` / `@preserve` / `@copyright`、`SPDX-License-Identifier:` / `SPDX-FileCopyrightText:` タグを含む法的コメントも**デフォルトで保持**
|
|
150
|
+
- `@ts-expect-error` や `eslint-disable-next-line` など**次行を対象にする指示子の直下の行構造を保持**: 削除すると行が消えて指示子の適用先がずれる場合(コメントだけの行など)、その行のコメントは削除せずに保持
|
|
142
151
|
- ブロックコメント除去でトークンが結合してしまう位置には空白を挿入(`a/* x */b` → `a b`)
|
|
143
152
|
- コメントだけの行は行ごと削除、行末コメントは手前の空白ごと削除
|
|
144
|
-
-
|
|
153
|
+
- 削除後のソースを再スキャンし、残ったコメントが保持対象と一致することを検証。想定外の結果になる場合はファイルを変更せずエラー報告
|
|
154
|
+
- 書き込みは一時ファイル経由のアトミック置換(書き込み失敗やディスクフルで元ファイルが壊れない)
|
|
145
155
|
|
|
146
156
|
### 変更されたファイルだけを対象にする(`--diff`)
|
|
147
157
|
|
|
@@ -162,7 +172,16 @@ ts-comment-scanner --fail-on-comment --diff a1b2c3..d4e5f6 src
|
|
|
162
172
|
|
|
163
173
|
### 検出できるディレクティブ(抜粋)
|
|
164
174
|
|
|
165
|
-
|
|
175
|
+
各ディレクティブは実ツールのパーサー実装(正規表現・文字列比較)に合わせて判定されます。
|
|
176
|
+
|
|
177
|
+
- **コンパイラ / 型**: `@ts-ignore` `@ts-expect-error` `@ts-nocheck` `@ts-check` / `/// <reference>` / `@ts-strict-ignore`・`@ts-strict`(typescript-strict-plugin) / `@deno-types=`・`@ts-types=`・`@ts-self-types=`(Deno)
|
|
178
|
+
- **リンター**: `eslint-disable` 系・`eslint-env`・`/* global */`・`/* exported */` / `oxlint-disable` 系 / `biome-ignore` 系・`rome-ignore` / `deno-lint-ignore` 系 / `@flow`・`@noflow`・`$FlowFixMe` 系・`flowlint` 系(Flow) / `tslint:`・`jshint`・`jscs:`・`jslint`(レガシー)
|
|
179
|
+
- **フォーマッタ**: `prettier-ignore`・`@format`/`@prettier`/`@noformat`/`@noprettier` pragma / `oxfmt-ignore` / `dprint-ignore`・`dprint-ignore-file` / `organize-imports-ignore` / `beautify ignore/preserve`(レガシー)
|
|
180
|
+
- **カバレッジ / テスト**: `istanbul ignore`・`c8 ignore`・`v8 ignore`・`node:coverage` / `@jest-environment(-options)`・`@vitest-environment(-options)`・`@module-tag`(Vitest 4) / `Stryker disable/restore` / `type-coverage:ignore-line/-next-line` / `ts-prune-ignore-next`
|
|
181
|
+
- **バンドラ / ランタイム**: `webpackChunkName:` などの webpack・turbopack マジックコメント / `@vite-ignore` / `#__PURE__`・`@__NO_SIDE_EFFECTS__`・`@__INLINE__`・`@__KEY__`・`@__MANGLE_PROP__`(terser/rollup 注釈) / `// @bun`(Bun) / `@refresh reset/skip/reload`(react-refresh / solid-refresh) / `million-ignore` / `nx-ignore-next-line`(Nx) / `@unocss-include/-ignore/-skip-start/-skip-end` / `@next-codemod-error/-ignore`(Next.js) / `/* GraphQL */`・`/* HTML */` タグコメント / `//# sourceMappingURL=`・`//# sourceURL=` / `@jsx` 系プラグマ
|
|
182
|
+
- **セキュリティ / 静的解析**: `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)
|
|
183
|
+
- **スペルチェック**: `cspell:` 系(`cSpell:`・`spell-checker:`・`spellchecker:` 別名込み)・`LocalWords` / `codespell:ignore`
|
|
184
|
+
- **エディタ / IDE**: `#region`・`#endregion` / `noinspection`・`<editor-fold>`・`language=`(JetBrains) / `ReSharper disable/restore`
|
|
166
185
|
|
|
167
186
|
## ライブラリとして使う
|
|
168
187
|
|
|
@@ -193,11 +212,13 @@ const changed = await changedFiles("main..HEAD");
|
|
|
193
212
|
| `collectFiles(inputs, options?)` | 対象ファイルのパス一覧を収集 |
|
|
194
213
|
| `changedFiles(range, cwd?)` | git のリビジョン範囲で変更された作業ツリーのファイルを絶対パスで返す |
|
|
195
214
|
| `removeComments(source, options?)` | コメントを安全に削除(`removeDirectives` / `removeLegal` / `shouldRemove`) |
|
|
196
|
-
| `detectDirective(kind, text)` | コメントがディレクティブなら正規化した名前を返す |
|
|
215
|
+
| `detectDirective(kind, text, placement?)` | コメントがディレクティブなら正規化した名前を返す(`placement` で位置依存の判定が可能) |
|
|
197
216
|
| `isLegalComment(text)` | ライセンス・法的コメントかどうかを判定 |
|
|
198
217
|
| `formatText(results)` / `formatJson(results)` / `formatGitHub(results)` | スキャン結果を整形 |
|
|
218
|
+
| `readFileText(file)` / `decodeFileText(data)` / `encodeFileText(text, target)` | UTF-8 / UTF-16 と BOM を保持するファイル読み書きヘルパー |
|
|
219
|
+
| `writeFileAtomic(file, data)` | 一時ファイル経由でファイルをアトミックに置換 |
|
|
199
220
|
|
|
200
|
-
型: `Comment` / `CommentKind` / `FileScanResult` / `ScanOptions` / `CollectOptions` / `RemoveOptions` / `RemoveResult`
|
|
221
|
+
型: `Comment` / `CommentKind` / `FileScanResult` / `ScanOptions` / `CollectOptions` / `RemoveOptions` / `RemoveResult` / `FileText` / `FileEncoding` / `DirectivePlacement`
|
|
201
222
|
|
|
202
223
|
## 必要環境
|
|
203
224
|
|
package/dist/directives.d.ts
CHANGED
|
@@ -1,12 +1,33 @@
|
|
|
1
1
|
import type { CommentKind } from "./types.js";
|
|
2
|
+
/**
|
|
3
|
+
* Where a comment sits in its file, for directives that are only honoured in
|
|
4
|
+
* particular positions. Omitting the placement treats every position as
|
|
5
|
+
* valid, which matches how a lone comment string is best interpreted.
|
|
6
|
+
*/
|
|
7
|
+
export interface DirectivePlacement {
|
|
8
|
+
/** The comment starts before the file's first token. */
|
|
9
|
+
header: boolean;
|
|
10
|
+
/** The comment is the file's first comment, preceded only by whitespace (or a shebang). */
|
|
11
|
+
firstComment: boolean;
|
|
12
|
+
/** The comment starts at the very first character of the file. */
|
|
13
|
+
fileStart: boolean;
|
|
14
|
+
}
|
|
2
15
|
/**
|
|
3
16
|
* Returns the canonical name of the compiler/linter/tooling directive the
|
|
4
17
|
* comment represents, or `undefined` when the comment is an ordinary comment.
|
|
18
|
+
*
|
|
19
|
+
* When a placement is given, directives that the corresponding tool only
|
|
20
|
+
* honours in certain positions (header pragmas, prettier's docblock pragma,
|
|
21
|
+
* `// @bun`) are skipped elsewhere — and the remaining rules still run, so a
|
|
22
|
+
* live directive later in the same comment (`// deno-lint-ignore-file
|
|
23
|
+
* nosemgrep` in mid-file) is not masked by a positionally dead one.
|
|
5
24
|
*/
|
|
6
|
-
export declare function detectDirective(kind: CommentKind, text: string): string | undefined;
|
|
25
|
+
export declare function detectDirective(kind: CommentKind, text: string, placement?: DirectivePlacement): string | undefined;
|
|
7
26
|
/**
|
|
8
|
-
* True for license/legal comments (`/*!`, `@license`, `@preserve`,
|
|
9
|
-
*
|
|
27
|
+
* True for license/legal comments (`/*!`, `@license`, `@preserve`,
|
|
28
|
+
* `@copyright`, and the machine-readable `SPDX-License-Identifier:` /
|
|
29
|
+
* `SPDX-FileCopyrightText:` tags) that build tools conventionally keep when
|
|
30
|
+
* stripping comments and that license scanners rely on.
|
|
10
31
|
*/
|
|
11
32
|
export declare function isLegalComment(text: string): boolean;
|
|
12
33
|
//# 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":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;
|
|
1
|
+
{"version":3,"file":"directives.d.ts","sourceRoot":"","sources":["../src/directives.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAuT9C;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IACjC,wDAAwD;IACxD,MAAM,EAAE,OAAO,CAAC;IAChB,2FAA2F;IAC3F,YAAY,EAAE,OAAO,CAAC;IACtB,kEAAkE;IAClE,SAAS,EAAE,OAAO,CAAC;CACpB;AA8DD;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,kBAAkB,GAAG,MAAM,GAAG,SAAS,CAgDnH;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAIpD"}
|