@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 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
  [![npm version](https://img.shields.io/npm/v/@kongyo2/ts-comment-scanner.svg)](https://www.npmjs.com/package/@kongyo2/ts-comment-scanner)
4
8
  [![npm downloads](https://img.shields.io/npm/dm/@kongyo2/ts-comment-scanner.svg)](https://www.npmjs.com/package/@kongyo2/ts-comment-scanner)
5
9
  [![CI](https://github.com/kongyo2/ts-comment-scanner/actions/workflows/ci.yml/badge.svg)](https://github.com/kongyo2/ts-comment-scanner/actions/workflows/ci.yml)
10
+ [![coverage](https://img.shields.io/badge/coverage-100%25-3178C6)](https://kongyo2.github.io/ts-comment-scanner/)
6
11
  ![CodeRabbit Pull Request Reviews](https://img.shields.io/coderabbit/prs/github/kongyo2/ts-comment-scanner?utm_source=oss&utm_medium=github&utm_campaign=kongyo2%2Fts-comment-scanner&labelColor=171717&color=FF570A&link=https%3A%2F%2Fcoderabbit.ai&label=CodeRabbit+Reviews)
7
12
  [![node](https://img.shields.io/node/v/@kongyo2/ts-comment-scanner.svg)](https://nodejs.org)
8
13
  [![license](https://img.shields.io/npm/l/@kongyo2/ts-comment-scanner.svg)](./LICENSE)
9
14
  [![Ask DeepWiki](https://deepwiki.com/badge.svg)](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": 12,
104
+ "end": 14,
99
105
  "line": 1,
100
106
  "column": 1,
101
107
  "endLine": 1,
102
- "endColumn": 13
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=13,title=line comment::// entry point
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 it, and if the outcome is unexpected the file is left unchanged and an error is reported
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
- `@ts-ignore` `@ts-expect-error` `@ts-nocheck` `@ts-check` / the `eslint-disable` family, `eslint-env`, `/* global */` / `tslint:`, `jshint`, `jscs:` / the `oxlint-disable` family / the `biome-ignore` family / the `deno-lint-ignore` family / `prettier-ignore`, `oxfmt-ignore` / `istanbul ignore`, `c8 ignore`, `v8 ignore`, `node:coverage` / webpack magic comments such as `webpackChunkName:` and turbopack magic comments such as `turbopackIgnore:` / `@vite-ignore` / `#__PURE__` / `//# sourceMappingURL=`, `//# sourceURL=` / `@jsx`-family pragmas / `@jest-environment`, `@vitest-environment` / `/// <reference>` / `#region`, `#endregion`
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
  [![npm version](https://img.shields.io/npm/v/@kongyo2/ts-comment-scanner.svg)](https://www.npmjs.com/package/@kongyo2/ts-comment-scanner)
4
8
  [![npm downloads](https://img.shields.io/npm/dm/@kongyo2/ts-comment-scanner.svg)](https://www.npmjs.com/package/@kongyo2/ts-comment-scanner)
5
9
  [![CI](https://github.com/kongyo2/ts-comment-scanner/actions/workflows/ci.yml/badge.svg)](https://github.com/kongyo2/ts-comment-scanner/actions/workflows/ci.yml)
10
+ [![coverage](https://img.shields.io/badge/coverage-100%25-3178C6)](https://kongyo2.github.io/ts-comment-scanner/)
6
11
  ![CodeRabbit Pull Request Reviews](https://img.shields.io/coderabbit/prs/github/kongyo2/ts-comment-scanner?utm_source=oss&utm_medium=github&utm_campaign=kongyo2%2Fts-comment-scanner&labelColor=171717&color=FF570A&link=https%3A%2F%2Fcoderabbit.ai&label=CodeRabbit+Reviews)
7
12
  [![node](https://img.shields.io/node/v/@kongyo2/ts-comment-scanner.svg)](https://nodejs.org)
8
13
  [![license](https://img.shields.io/npm/l/@kongyo2/ts-comment-scanner.svg)](./LICENSE)
9
14
  [![Ask DeepWiki](https://deepwiki.com/badge.svg)](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=13,title=line comment::// エントリーポイント
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
- `@ts-ignore` `@ts-expect-error` `@ts-nocheck` `@ts-check` / `eslint-disable` 系・`eslint-env`・`/* global */` / `tslint:`・`jshint`・`jscs:` / `oxlint-disable` 系 / `biome-ignore` 系 / `deno-lint-ignore` 系 / `prettier-ignore`・`oxfmt-ignore` / `istanbul ignore`・`c8 ignore`・`v8 ignore`・`node:coverage` / `webpackChunkName:` などの webpack マジックコメント・`turbopackIgnore:` などの turbopack マジックコメント / `@vite-ignore` / `#__PURE__` / `//# sourceMappingURL=`・`//# sourceURL=` / `@jsx` 系プラグマ / `@jest-environment`・`@vitest-environment` / `/// <reference>` / `#region`・`#endregion`
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
 
@@ -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`, `@copyright`)
9
- * that build tools conventionally keep when stripping comments.
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
@@ -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;AA+F9C;;;GAGG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAkCnF;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAGpD"}
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"}