@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.
@@ -0,0 +1,492 @@
1
+ import type { CommentKind } from "./types.js";
2
+
3
+ interface DirectiveRule {
4
+ pattern: RegExp;
5
+ /** Fixed name, or derive it from the match. Defaults to the full matched text. */
6
+ name?: string | ((match: RegExpExecArray) => string);
7
+ blockOnly?: boolean;
8
+ /** Only match line comments (e.g. JetBrains suppressions in JS/TS). */
9
+ lineOnly?: boolean;
10
+ /** Match any content line, not just the first (for docblock pragmas). */
11
+ anyLine?: boolean;
12
+ /**
13
+ * Match the content lines joined into one, for label-plus-options directives
14
+ * whose options may continue on later lines, like a block comment opening
15
+ * with `jshint` and `esversion: 6` below it. The label still has to open
16
+ * the comment.
17
+ */
18
+ joinLines?: boolean;
19
+ /**
20
+ * Match against the raw comment text, markers included, for tools that
21
+ * compare the literal source (bun's `// @bun` prefix, Stryker's
22
+ * `^\s?Stryker` on the comment value, JSLint's no-space-after-marker rule).
23
+ */
24
+ rawText?: boolean;
25
+ /**
26
+ * Skip `/**`-opened block comments: webpack evaluates the comment body as
27
+ * an object literal (JSDoc stars break it), and dprint/datadog skip only
28
+ * whitespace before their marker, so a leading `*` defeats them.
29
+ */
30
+ notDocblock?: boolean;
31
+ /**
32
+ * Match content lines verbatim, without stripping JSDoc `*` prefixes, for
33
+ * tools that compare the literal comment value (prettier/oxfmt compare the
34
+ * trimmed body, so `/** prettier-ignore *​/` is NOT a suppression to them).
35
+ */
36
+ keepStars?: boolean;
37
+ }
38
+
39
+ const RULES: DirectiveRule[] = [
40
+ // ESLint
41
+ { pattern: /^eslint-(?:disable|enable)(?:-next-line|-line)?\b/ },
42
+ { pattern: /^eslint-env\b/ },
43
+ { pattern: /^eslint\s+\S/, name: "eslint", blockOnly: true, joinLines: true },
44
+ {
45
+ pattern: /^(globals?|exported)\s+\S/,
46
+ name: (match) => match[1] as string,
47
+ blockOnly: true,
48
+ joinLines: true,
49
+ },
50
+ // TSLint (legacy)
51
+ { pattern: /^tslint:[a-z-]+/ },
52
+ // JSHint (legacy): `key: value` options and ignore markers (`jshint
53
+ // esversion: 6`, `jshint ignore:line`) plus `-W###`/`+W###` warning toggles.
54
+ // Requiring those shapes keeps prose like `jshint is unused` ordinary.
55
+ { pattern: /^jshint\s+(?:[A-Za-z$_][\w$]*\s*:|[-+]W\d+\b)/, name: "jshint", joinLines: true },
56
+ // JSCS (legacy). Spacing after the colon is lenient (`jscs: enable` works),
57
+ // so the name is normalised to the compact form.
58
+ { pattern: /^jscs:\s*(disable|enable|ignore)\b/, name: (match) => `jscs:${match[1]}`, joinLines: true },
59
+ // JSLint (legacy): the directive word must sit immediately after the
60
+ // comment marker with no space (`/*jslint devel*/` works, `/* jslint */`
61
+ // does not) and needs a body, so these match the raw text. The whole-line
62
+ // pragmas (`/*jslint-disable*/`, `//jslint-ignore-line`) are exact strings.
63
+ { pattern: /^\/[/*](jslint|property)\s+\S/, rawText: true, name: (match) => match[1] as string },
64
+ { pattern: /^\/\*jslint-(disable|enable)\*\/$/, rawText: true, name: (match) => `jslint-${match[1]}` },
65
+ { pattern: /^\/\/jslint-(ignore-line|quiet)$/, rawText: true, name: (match) => `jslint-${match[1]}` },
66
+ // oxlint
67
+ { pattern: /^oxlint-(?:disable|enable)(?:-next-line|-line)?\b/ },
68
+ // Biome
69
+ { pattern: /^biome-ignore(?:-all|-start|-end)?\b/ },
70
+ // Rome (Biome's predecessor). Case-insensitive keyword with `-` or `_`,
71
+ // then known categories and a mandatory colon — without the colon Rome
72
+ // reported a parse diagnostic and the suppression stayed inert.
73
+ {
74
+ pattern: /^rome[-_]ignore\s*(?:(?:parse|format|lint)(?:\([^)]*\))?\s*)+:/i,
75
+ name: "rome-ignore",
76
+ anyLine: true,
77
+ },
78
+ // Deno
79
+ { pattern: /^deno-(?:lint-ignore(?:-file)?|fmt-ignore(?:-file)?|coverage-ignore(?:-file|-start|-stop)?)\b/ },
80
+ // Deno type directives. deno_graph matches them case-insensitively at the
81
+ // comment start; `@deno-types` accepts a bare specifier, the newer names
82
+ // require quotes.
83
+ { pattern: /^@deno-types\s*=\s*(?:"[^"\n]+"|'[^'\n]+'|\S+)/i, name: "@deno-types" },
84
+ { pattern: /^@ts-types\s*=\s*(?:"[^"\n]+"|'[^'\n]+')/i, name: "@ts-types" },
85
+ { pattern: /^@ts-self-types\s*=\s*(?:"[^"\n]+"|'[^'\n]+')/i, name: "@ts-self-types" },
86
+ // Formatter suppressions (prettier, and oxfmt which mirrors it). Both
87
+ // parsers compare the exact trimmed comment body, so the marker must be the
88
+ // whole comment (joinLines makes `$` span every line): hyphenated
89
+ // lookalikes (`oxfmt-ignore-more`) and prose stay ordinary. keepStars,
90
+ // because the literal comparison also means a JSDoc `*` before the marker
91
+ // (`/** prettier-ignore *​/`) leaves the comment ordinary — verified against
92
+ // prettier 3.8.
93
+ { pattern: /^prettier-ignore(?:-start|-end)?$/, joinLines: true, keepStars: true },
94
+ { pattern: /^oxfmt-ignore$/, joinLines: true, keepStars: true },
95
+ // dprint. The file pragma is a starts-with check (trailing text allowed) on
96
+ // the file's leading comments, skipping only whitespace — a `/**` docblock
97
+ // star defeats it. The node pragma is a substring bounded by
98
+ // non-alphanumerics anywhere in the comment, so a reason may follow.
99
+ { pattern: /^dprint-ignore-file/, notDocblock: true, name: "dprint-ignore-file" },
100
+ {
101
+ pattern: /(?:^|[^\p{L}\p{N}])dprint-ignore(?![\p{L}\p{N}])/u,
102
+ name: "dprint-ignore",
103
+ anyLine: true,
104
+ },
105
+ // Prettier pragma mode (--require-pragma / --check-ignore-pragma). Prettier
106
+ // reads them via jest-docblock: only the file's first block comment counts
107
+ // and the pragma has to open a line. The lookahead keeps distinct keys like
108
+ // `@prettier-plugin` ordinary, matching jest-docblock's `@(\S+)` parsing.
109
+ { pattern: /^@(?:no)?(?:format|prettier)(?=\s|$)/, blockOnly: true, anyLine: true },
110
+ // prettier-plugin-organize-imports: a literal whole-file substring check,
111
+ // `//` and single space included, so it matches the raw comment text.
112
+ { pattern: /\/\/ organize-imports-ignore/, rawText: true, name: "organize-imports-ignore" },
113
+ // js-beautify (legacy): exact-shape block comments with single spaces; only
114
+ // the ignore/preserve pairs have an effect.
115
+ {
116
+ pattern: /^\/\* beautify(?: (?:ignore|preserve):(?:start|end))+ \*\/$/,
117
+ rawText: true,
118
+ blockOnly: true,
119
+ name: "beautify",
120
+ },
121
+ // Coverage tools. The mode is part of the name so that consumers can tell
122
+ // next-statement pragmas (`next`, `if`, ...) from file/range ones (`file`,
123
+ // `start`, `stop`). The c8 CLI (v8-to-istanbul) and Node core only parse
124
+ // block comments, but istanbul-lib-instrument and Vitest's v8 provider
125
+ // (ast-v8-to-istanbul) honour line comments too, so no rule is block-only.
126
+ { pattern: /^istanbul\s+ignore\s+([a-z]+)/, name: (match) => `istanbul-ignore-${match[1]}` },
127
+ { pattern: /^istanbul\s+ignore\b/, name: "istanbul-ignore" },
128
+ { pattern: /^c8\s+ignore\s+([a-z]+)/, name: (match) => `c8-ignore-${match[1]}` },
129
+ { pattern: /^c8\s+ignore\b/, name: "c8-ignore" },
130
+ { pattern: /^v8\s+ignore\s+([a-z]+)/, name: (match) => `v8-ignore-${match[1]}` },
131
+ { pattern: /^v8\s+ignore\b/, name: "v8-ignore" },
132
+ {
133
+ pattern: /^node:coverage\s+(disable|enable|ignore)\b/,
134
+ name: (match) => `node:coverage-${match[1]}`,
135
+ },
136
+ // type-coverage: substring match in any comment. There is no ignore-file
137
+ // comment — file-level ignores are a CLI option only.
138
+ {
139
+ pattern: /type-coverage:ignore-(next-line|line)/,
140
+ name: (match) => `type-coverage:ignore-${match[1]}`,
141
+ anyLine: true,
142
+ },
143
+ // StrykerJS mutation testing. The instrumenter runs
144
+ // /^\s?Stryker (disable|restore)( next-line)? <mutators>/ against the raw
145
+ // comment value: at most one space before `Stryker`, single literal spaces,
146
+ // and a mandatory mutator list (`all` or names) — hence the rawText match.
147
+ {
148
+ pattern: /^\/[/*]\s?Stryker (disable|restore)( next-line)? [a-zA-Z]/,
149
+ rawText: true,
150
+ name: (match) => `stryker-${match[1]}${match[2] === undefined ? "" : "-next-line"}`,
151
+ },
152
+ // ts-prune: substring of the closest leading comment above an export.
153
+ { pattern: /ts-prune-ignore-next/, name: "ts-prune-ignore-next", anyLine: true },
154
+ // typescript-strict-plugin: token-equality scan over the whole file (the
155
+ // CLI splits comment lines on spaces, the IDE plugin uses a TODO scan).
156
+ {
157
+ pattern: /(?:^|\s)@ts-strict(-ignore)?(?=\s|$)/,
158
+ name: (match) => (match[1] === undefined ? "@ts-strict" : "@ts-strict-ignore"),
159
+ anyLine: true,
160
+ },
161
+ // Flow. The pragmas live in the file's leading docblock and are matched as
162
+ // whole words (text may surround them). Suppressions must open the comment
163
+ // and take an optional [error-code]; all four historical suppressors are
164
+ // recognised ($FlowIssue/$FlowIgnore stopped working in Flow 0.281 but
165
+ // still gate older setups). flowlint takes rule:severity pairs.
166
+ {
167
+ pattern: /(?:^|[\s*/])@(no)?flow(?=$|[\s*/])/,
168
+ name: (match) => (match[1] === undefined ? "@flow" : "@noflow"),
169
+ anyLine: true,
170
+ },
171
+ {
172
+ pattern: /^\$Flow(FixMe|ExpectedError|Issue|Ignore)(?:\[[a-z-]+\])?(?![\w-])/,
173
+ name: (match) => `$Flow${match[1]}`,
174
+ },
175
+ {
176
+ pattern: /^flowlint(-line|-next-line)?\s+[a-z][a-z-]*\s*:\s*(?:off|warn|error)/,
177
+ name: (match) => `flowlint${match[1] ?? ""}`,
178
+ joinLines: true,
179
+ },
180
+ // Bundlers. webpack's gate regex requires the colon to follow the key
181
+ // immediately and evaluates the body as an object literal, which JSDoc
182
+ // stars break — turbopack magic comments mirror the same `key: value` form.
183
+ { pattern: /^webpack[A-Z][A-Za-z]+:/, name: "webpack-magic-comment", notDocblock: true },
184
+ { pattern: /^turbopack[A-Z][A-Za-z]+:/, name: "turbopack-magic-comment", notDocblock: true },
185
+ // Vite matches the literal block comment (`/\/\*\s*@vite-ignore\s*\*\//` in
186
+ // importAnalysis), so line comments, suffixes and trailing words stay
187
+ // ordinary.
188
+ { pattern: /^\/\*\s*@vite-ignore\s*\*\/$/, rawText: true, blockOnly: true, name: "@vite-ignore" },
189
+ // Terser/Rollup annotations: a bare substring search over any comment kind,
190
+ // so leading or trailing words keep the annotation active.
191
+ { pattern: /[#@]__(?:PURE|NO_SIDE_EFFECTS|INLINE|NOINLINE|KEY|MANGLE_PROP)__/, anyLine: true },
192
+ // Million.js: substring of the leading comments of a component.
193
+ { pattern: /million-ignore/, name: "million-ignore", anyLine: true },
194
+ {
195
+ pattern: /^@million (jsx-)?skip$/,
196
+ joinLines: true,
197
+ name: (match) => (match[1] === undefined ? "@million-skip" : "@million-jsx-skip"),
198
+ },
199
+ // Nx project graph: substring; the comment has to end on the line right
200
+ // above the import it hides.
201
+ { pattern: /nx-ignore-next-line/, name: "nx-ignore-next-line", anyLine: true },
202
+ // UnoCSS: include/ignore are raw whole-file substring checks; the skip
203
+ // markers must be their own comment.
204
+ { pattern: /@unocss-(include|ignore)/, name: (match) => `@unocss-${match[1]}`, anyLine: true },
205
+ { pattern: /^@unocss-skip-(start|end)\b/, name: (match) => `@unocss-skip-${match[1]}` },
206
+ // Next.js codemod markers: `next build` fails while an unresolved
207
+ // @next-codemod-error comment is attached to the call.
208
+ { pattern: /@next-codemod-(error|ignore)/, name: (match) => `@next-codemod-${match[1]}`, anyLine: true },
209
+ // Bun: the runtime treats a file starting with the literal bytes `// @bun`
210
+ // (optionally followed by flags like `@bytecode`) as already transpiled.
211
+ { pattern: /^\/\/ @bun/, rawText: true, lineOnly: true, name: "@bun" },
212
+ // React Fast Refresh / solid-refresh. react-refresh looks for the
213
+ // substring `@refresh reset` in any comment; solid-refresh requires its
214
+ // pragma to be the entire comment body.
215
+ { pattern: /^@refresh (skip|reload)$/, joinLines: true, name: (match) => `@refresh-${match[1]}` },
216
+ { pattern: /@refresh reset/, name: "@refresh-reset", anyLine: true },
217
+ // Embedded-language tag comments: prettier formats the following template
218
+ // literal when the whole comment is `GraphQL` (graphql-tag-pluck matches it
219
+ // case-insensitively) or `HTML` (prettier's exact ` HTML ` value).
220
+ { pattern: /^graphql$/i, joinLines: true, name: "GraphQL" },
221
+ { pattern: /^\/\* HTML \*\/$/, rawText: true, blockOnly: true, name: "HTML" },
222
+ // Source maps (`//# sourceMappingURL=`, legacy `//@`, and the block form)
223
+ { pattern: /^[#@]\s*(source(?:Mapping)?URL)=/, name: (match) => match[1] as string },
224
+ // JSX pragmas (docblock pragmas: block comments only, honoured on any line)
225
+ { pattern: /^@jsx(?:Runtime|ImportSource|Frag)?\b/, blockOnly: true, anyLine: true },
226
+ // Test runners. Jest reads these from the file's leading docblock, but
227
+ // Vitest (which also honours the @jest- spellings) matches the pragma with
228
+ // a bare regex over the whole file, so any comment kind and position can be
229
+ // active; both regexes require a value after the tag.
230
+ {
231
+ pattern: /@((?:jest|vitest)-environment)\s+[\w-]/,
232
+ name: (match) => `@${match[1]}`,
233
+ anyLine: true,
234
+ },
235
+ {
236
+ pattern: /@((?:jest|vitest)-environment-options)\s+\S/,
237
+ name: (match) => `@${match[1]}`,
238
+ anyLine: true,
239
+ },
240
+ // Vitest module tags. Vitest requires the tag to sit right after a `//` or
241
+ // `*` marker, which is what a content-line start means here.
242
+ { pattern: /^@module-tag\s+[\w/-]/, name: "@module-tag", anyLine: true },
243
+ // SonarQube/SonarCloud: the trimmed comment (JSDoc star stripped) has to
244
+ // START with NOSONAR, case-insensitively; any suffix keeps it active.
245
+ { pattern: /^NOSONAR/i, name: "NOSONAR" },
246
+ // Semgrep: ` nosemgrep`/` nosem` (case-insensitive) on the finding line or
247
+ // standalone above it, with optional `:`/`=` rule ids. Semgrep itself needs
248
+ // no trailing boundary; the lookahead just keeps words like `nosemantic`
249
+ // ordinary.
250
+ { pattern: /(?:^|\s)nosem(?:grep)?(?![\w-])/i, name: "nosemgrep", anyLine: true },
251
+ // CodeQL / LGTM alert suppressions: the AlertSuppression queries only read
252
+ // `//` comments, so block comments — even single-line ones — stay ordinary.
253
+ // `lgtm[...]` matches anywhere in the comment; bare `lgtm` only at the
254
+ // start or after a `;`; `codeql[...]` requires the bracketed query id.
255
+ { pattern: /\blgtm\s*\[[^\]]*\]/i, lineOnly: true, name: "lgtm" },
256
+ { pattern: /(?:^|;)\s*lgtm(?!\w)(?!\s*\[)/i, lineOnly: true, name: "lgtm" },
257
+ { pattern: /\bcodeql\s*\[[^\]]*\]/i, lineOnly: true, name: "codeql" },
258
+ // DeepSource: bare `skipcq` or `skipcq: CODE1, CODE2`, on the flagged line
259
+ // or standalone above it (it may trail other comment text).
260
+ { pattern: /\bskipcq(?![\w-])/, name: "skipcq", anyLine: true },
261
+ // Snyk Code (DeepCode, legacy): `deepcode ignore RuleId: reason`, with a
262
+ // `file ` prefix for the file-wide form.
263
+ { pattern: /^(?:file\s+)?deepcode\s+ignore\b/, name: "deepcode-ignore" },
264
+ // Datadog static analysis: the keyword must directly follow the comment
265
+ // opener (whitespace aside); a `/**` star defeats it. Applies to the next
266
+ // line, or the whole file from line 1.
267
+ { pattern: /^(no-dd-sa|datadog-disable)/, notDocblock: true, name: (match) => match[1] as string },
268
+ // Secret scanners: raw substring checks on the finding line.
269
+ { pattern: /gitleaks:allow/, name: "gitleaks:allow", anyLine: true },
270
+ { pattern: /trufflehog:ignore/, name: "trufflehog:ignore", anyLine: true },
271
+ // detect-secrets: `pragma: allowlist secret` (legacy `whitelist`) on the
272
+ // finding line, or the nextline form standing alone above it.
273
+ { pattern: /^pragma: ?allowlist[ -]nextline[ -]secret/, name: "pragma-allowlist-nextline-secret" },
274
+ { pattern: /^pragma: ?(?:allow|white)list[ -]secret/, name: "pragma-allowlist-secret" },
275
+ // cspell in-document directives: `\b(?:spell-?checker|c?spell)::?` (yes,
276
+ // bare `spell:` counts) anywhere in the text, case-insensitive, followed by
277
+ // one of the known directive verbs. Names are normalised to `cspell:<verb>`.
278
+ {
279
+ pattern:
280
+ /\b(?:c?spell|spell-?checker)::?\s*(disable(?:-line|-next(?:-line)?)?|enable|ignore(?:-?words?)?|words?|(?:flag|forbid)(?:-?words?)?|ignore_?reg_?exp|include_?reg_?exp|dictionar(?:y|ies)|locale?|language|(?:enable|disable)(?:allow)?compoundwords|(?:enable|disable)casesensitive)\b(?!-)/i,
281
+ name: (match) => `cspell:${(match[1] as string).toLowerCase()}`,
282
+ anyLine: true,
283
+ },
284
+ // cspell's legacy emacs-style word list (case-sensitive, colon optional).
285
+ { pattern: /\bLocalWords(?::|\s+\S)/, name: "LocalWords", anyLine: true },
286
+ // codespell: the tag must follow a punctuation character (the comment
287
+ // marker itself at line starts) with at most one space between.
288
+ {
289
+ pattern: /(?:^|[^\w\s]\s?)codespell:ignore(-next-line)?(?![\w-])/,
290
+ name: (match) => `codespell:ignore${match[1] ?? ""}`,
291
+ anyLine: true,
292
+ },
293
+ // JetBrains IDEs. `noinspection` suppressions are line comments in JS/TS
294
+ // and take comma-separated inspection ids; editor-fold markers are
295
+ // substring checks; a `language=` comment injects a language into the
296
+ // literal that follows.
297
+ { pattern: /^noinspection\s+[A-Za-z0-9_.-]+/, lineOnly: true, name: "noinspection" },
298
+ {
299
+ pattern: /<(\/?)editor-fold/,
300
+ name: (match) => (match[1] === "/" ? "editor-fold-end" : "editor-fold"),
301
+ anyLine: true,
302
+ },
303
+ { pattern: /^language=\S/, name: "language-injection" },
304
+ // ReSharper/Rider suppressions (`ReSharper disable once RuleName`, ...).
305
+ { pattern: /^ReSharper (disable|restore)\b/, lineOnly: true, name: (match) => `resharper-${match[1]}` },
306
+ // Editor folding
307
+ { pattern: /^#(?:region|endregion)\b/ },
308
+ ];
309
+
310
+ const TRIPLE_SLASH = /^\/\/\/\s*<(reference|amd-dependency|amd-module)\b/;
311
+
312
+ /**
313
+ * Where a comment sits in its file, for directives that are only honoured in
314
+ * particular positions. Omitting the placement treats every position as
315
+ * valid, which matches how a lone comment string is best interpreted.
316
+ */
317
+ export interface DirectivePlacement {
318
+ /** The comment starts before the file's first token. */
319
+ header: boolean;
320
+ /** The comment is the file's first comment, preceded only by whitespace (or a shebang). */
321
+ firstComment: boolean;
322
+ /** The comment starts at the very first character of the file. */
323
+ fileStart: boolean;
324
+ }
325
+
326
+ const ANY_PLACEMENT: DirectivePlacement = { header: true, firstComment: true, fileStart: true };
327
+
328
+ // File-wide pragmas (check pragmas, triple-slash directives, Flow/JSLint
329
+ // header pragmas, Deno's *-ignore-file and @ts-self-types forms) only count
330
+ // before the first token; anywhere later the tools treat them as ordinary
331
+ // text. dprint-ignore-file is deliberately absent: a stray one below the
332
+ // header no longer skips the file, but dprint's node pragma still matches
333
+ // inside it, so the comment stays an active `dprint-ignore` and must keep its
334
+ // tag. Coverage file pragmas (`istanbul ignore file`, `c8/v8 ignore file`)
335
+ // are NOT gated: istanbul-lib-instrument and Vitest's v8 provider
336
+ // (ast-v8-to-istanbul) honour them on any comment in the file. Test
337
+ // environment pragmas are not gated either: Vitest matches them (including
338
+ // the @jest- spellings) with a regex over the whole file, and neither are
339
+ // @ts-strict pragmas (typescript-strict-plugin scans every line). @jsx
340
+ // pragmas stay ungated too: tsc only reads leading ones, but Babel's JSX
341
+ // transform scans every comment in the file.
342
+ const HEADER_ONLY_DIRECTIVES = new Set([
343
+ "@ts-nocheck",
344
+ "@ts-check",
345
+ "@flow",
346
+ "@noflow",
347
+ "@ts-self-types",
348
+ "jslint",
349
+ "property",
350
+ ]);
351
+
352
+ // Prettier's pragma mode reads the pragma through jest-docblock, which only
353
+ // ever extracts the file's FIRST comment (a shebang may precede it) — a
354
+ // docblock behind any other comment is ignored. Verified against prettier 3.8.
355
+ const FIRST_COMMENT_ONLY_DIRECTIVES = new Set(["@format", "@noformat", "@prettier", "@noprettier"]);
356
+
357
+ // Bun treats a file as pre-transpiled only when it literally STARTS with
358
+ // `// @bun`; after a shebang or any other leading content the marker is inert.
359
+ const FILE_START_ONLY_DIRECTIVES = new Set(["@bun"]);
360
+
361
+ function isActiveAt(name: string, placement: DirectivePlacement): boolean {
362
+ if (FILE_START_ONLY_DIRECTIVES.has(name)) return placement.fileStart;
363
+ if (FIRST_COMMENT_ONLY_DIRECTIVES.has(name)) return placement.firstComment;
364
+ if (
365
+ HEADER_ONLY_DIRECTIVES.has(name) ||
366
+ (name.startsWith("deno-") && name.endsWith("-ignore-file")) ||
367
+ name.startsWith("triple-slash-")
368
+ ) {
369
+ return placement.header;
370
+ }
371
+ return true;
372
+ }
373
+
374
+ // Mirrors the TypeScript compiler's own comment-directive matching, verified
375
+ // against tsc: the suppression directives are case-sensitive PREFIX matches
376
+ // (`@ts-ignoreTODO` is active), while the file-wide check pragmas are
377
+ // case-insensitive and must end at a word boundary (`@ts-nocheckfoo` is not).
378
+ const TS_LINE_SUPPRESSION = /^\/\/\/?\s*@ts-(ignore|expect-error)/;
379
+ const TS_LINE_CHECK_PRAGMA = /^\/\/\/?\s*@ts-(nocheck|check)\b/i;
380
+ // Block comments: only the suppression directives, and only on the comment's
381
+ // literal last line (`*/` included), even when that line is otherwise blank.
382
+ // tsc trims the line and then allows one run of `/`/`*` characters before the
383
+ // directive, so `* @ts-ignore */` counts but `/ * @ts-ignore */` does not.
384
+ const TS_BLOCK_SUPPRESSION = /^\s*[/*]*\s*@ts-(ignore|expect-error)/;
385
+
386
+ /**
387
+ * Returns the canonical name of the compiler/linter/tooling directive the
388
+ * comment represents, or `undefined` when the comment is an ordinary comment.
389
+ *
390
+ * When a placement is given, directives that the corresponding tool only
391
+ * honours in certain positions (header pragmas, prettier's docblock pragma,
392
+ * `// @bun`) are skipped elsewhere — and the remaining rules still run, so a
393
+ * live directive later in the same comment (`// deno-lint-ignore-file
394
+ * nosemgrep` in mid-file) is not masked by a positionally dead one.
395
+ */
396
+ export function detectDirective(kind: CommentKind, text: string, placement?: DirectivePlacement): string | undefined {
397
+ const at = placement ?? ANY_PLACEMENT;
398
+ if (kind === "line") {
399
+ const tripleSlash = TRIPLE_SLASH.exec(text);
400
+ if (tripleSlash) {
401
+ const name = `triple-slash-${tripleSlash[1]}`;
402
+ if (isActiveAt(name, at)) return name;
403
+ }
404
+ const suppression = TS_LINE_SUPPRESSION.exec(text);
405
+ if (suppression) {
406
+ return `@ts-${suppression[1]}`;
407
+ }
408
+ const checkPragma = TS_LINE_CHECK_PRAGMA.exec(text);
409
+ if (checkPragma) {
410
+ const name = `@ts-${checkPragma[1]?.toLowerCase()}`;
411
+ if (isActiveAt(name, at)) return name;
412
+ }
413
+ } else {
414
+ const suppression = TS_BLOCK_SUPPRESSION.exec(lastLine(text));
415
+ if (suppression) {
416
+ return `@ts-${suppression[1]}`;
417
+ }
418
+ }
419
+
420
+ const lines = contentLines(kind, text, false);
421
+ const literalLines = kind === "block" ? contentLines(kind, text, true) : lines;
422
+ for (const rule of RULES) {
423
+ if (rule.blockOnly === true && kind !== "block") continue;
424
+ if (rule.lineOnly === true && kind !== "line") continue;
425
+ if (rule.notDocblock === true && kind === "block" && text.startsWith("/**")) continue;
426
+ const ruleLines = rule.keepStars === true ? literalLines : lines;
427
+ const candidates =
428
+ rule.rawText === true
429
+ ? [text]
430
+ : rule.anyLine === true
431
+ ? ruleLines
432
+ : rule.joinLines === true
433
+ ? [ruleLines.join(" ")]
434
+ : ruleLines.slice(0, 1);
435
+ for (const line of candidates) {
436
+ const match = rule.pattern.exec(line);
437
+ if (!match) continue;
438
+ const name =
439
+ typeof rule.name === "string" ? rule.name : typeof rule.name === "function" ? rule.name(match) : match[0];
440
+ if (isActiveAt(name, at)) return name;
441
+ }
442
+ }
443
+ return undefined;
444
+ }
445
+
446
+ /**
447
+ * True for license/legal comments (`/*!`, `@license`, `@preserve`,
448
+ * `@copyright`, and the machine-readable `SPDX-License-Identifier:` /
449
+ * `SPDX-FileCopyrightText:` tags) that build tools conventionally keep when
450
+ * stripping comments and that license scanners rely on.
451
+ */
452
+ export function isLegalComment(text: string): boolean {
453
+ if (text.startsWith("/*!") || text.startsWith("//!")) return true;
454
+ if (/\bSPDX-(?:License-Identifier|FileCopyrightText):/i.test(text)) return true;
455
+ return /@(?:license|preserve|copyright)\b/i.test(text);
456
+ }
457
+
458
+ // Every ECMAScript line terminator, the way the scanner breaks lines: CRLF as
459
+ // one break, plus lone LF / CR and the U+2028/U+2029 separators.
460
+ const LINE_BREAK = /\r\n|[\n\r\u2028\u2029]/;
461
+
462
+ /**
463
+ * Non-empty content lines of the comment, with comment markers stripped.
464
+ * For line comments only the `//` marker itself is removed: extra slashes or
465
+ * stars are content, so `//// @ts-ignore` and `// * prettier-ignore` stay
466
+ * ordinary. JSDoc-style `*` prefixes are stripped for block comments unless
467
+ * `keepStars` asks for the literal lines (for tools that compare the raw
468
+ * comment value, where a leading `*` defeats the directive).
469
+ */
470
+ function contentLines(kind: CommentKind, text: string, keepStars: boolean): string[] {
471
+ // In keepStars mode only the literal `/*` and `*/` markers go, matching how
472
+ // prettier/oxfmt read the comment value: the second star of a `/**` opener
473
+ // is content and defeats their exact comparison.
474
+ const inner =
475
+ kind === "line"
476
+ ? text.replace(/^\/\//, "")
477
+ : keepStars
478
+ ? text.replace(/^\/\*/, "").replace(/\*\/\s*$/, "")
479
+ : text.replace(/^\/\*+/, "").replace(/\*+\/\s*$/, "");
480
+ const lines: string[] = [];
481
+ for (const line of inner.split(LINE_BREAK)) {
482
+ const stripped = (kind === "block" && !keepStars ? line.replace(/^\s*\*+\s*/, "") : line).trim();
483
+ if (stripped !== "") lines.push(stripped);
484
+ }
485
+ return lines;
486
+ }
487
+
488
+ /** Literal last line of the comment, closing marker included, exactly as tsc slices it. */
489
+ function lastLine(text: string): string {
490
+ const lines = text.split(LINE_BREAK);
491
+ return lines[lines.length - 1] as string;
492
+ }