@kongyo2/ts-comment-scanner 1.3.0 → 1.5.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 +23 -8
- package/README.md +21 -6
- package/dist/directives.d.ts +31 -1
- package/dist/directives.d.ts.map +1 -1
- package/dist/directives.js +127 -34
- package/dist/directives.js.map +1 -1
- package/dist/files.d.ts +43 -1
- package/dist/files.d.ts.map +1 -1
- package/dist/files.js +215 -26
- 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.d.ts +11 -2
- package/dist/remove.d.ts.map +1 -1
- package/dist/remove.js +226 -45
- 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 +86 -16
- package/dist/run.js.map +1 -1
- package/dist/scanner.d.ts.map +1 -1
- package/dist/scanner.js +43 -43
- 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 +516 -0
- package/src/files.ts +370 -0
- package/src/git.ts +72 -0
- package/src/index.ts +19 -0
- package/src/remove.ts +515 -0
- package/src/report.ts +106 -0
- package/src/run.ts +317 -0
- package/src/scanner.ts +104 -0
- package/src/types.ts +19 -0
- package/src/version.ts +7 -0
|
@@ -0,0 +1,516 @@
|
|
|
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
|
+
for (const name of ruleMatches(kind, text)) {
|
|
421
|
+
if (isActiveAt(name, at)) return name;
|
|
422
|
+
}
|
|
423
|
+
return undefined;
|
|
424
|
+
}
|
|
425
|
+
|
|
426
|
+
/** Directive names of every rule the comment matches, in rule order. */
|
|
427
|
+
function* ruleMatches(kind: CommentKind, text: string): Generator<string> {
|
|
428
|
+
const lines = contentLines(kind, text, false);
|
|
429
|
+
const literalLines = kind === "block" ? contentLines(kind, text, true) : lines;
|
|
430
|
+
for (const rule of RULES) {
|
|
431
|
+
if (rule.blockOnly === true && kind !== "block") continue;
|
|
432
|
+
if (rule.lineOnly === true && kind !== "line") continue;
|
|
433
|
+
if (rule.notDocblock === true && kind === "block" && text.startsWith("/**")) continue;
|
|
434
|
+
const ruleLines = rule.keepStars === true ? literalLines : lines;
|
|
435
|
+
const candidates =
|
|
436
|
+
rule.rawText === true
|
|
437
|
+
? [text]
|
|
438
|
+
: rule.anyLine === true
|
|
439
|
+
? ruleLines
|
|
440
|
+
: rule.joinLines === true
|
|
441
|
+
? [ruleLines.join(" ")]
|
|
442
|
+
: ruleLines.slice(0, 1);
|
|
443
|
+
for (const line of candidates) {
|
|
444
|
+
const match = rule.pattern.exec(line);
|
|
445
|
+
if (!match) continue;
|
|
446
|
+
yield typeof rule.name === "string" ? rule.name : typeof rule.name === "function" ? rule.name(match) : match[0];
|
|
447
|
+
}
|
|
448
|
+
}
|
|
449
|
+
}
|
|
450
|
+
|
|
451
|
+
/**
|
|
452
|
+
* The position-dependent directives (prettier's first-comment pragmas, Bun's
|
|
453
|
+
* file-start marker) the comment carries that are active at the given
|
|
454
|
+
* placement, sorted. Unlike detectDirective — which reports one canonical
|
|
455
|
+
* name — this sees through masking: an eslint config block can also hold a
|
|
456
|
+
* `@format` pragma, and whether that pragma is live must not hide behind the
|
|
457
|
+
* name an earlier rule already claimed. Only first-comment and file-start
|
|
458
|
+
* gates are consulted; header-gated directives cannot change activation when
|
|
459
|
+
* the comments around them change.
|
|
460
|
+
*/
|
|
461
|
+
export function activePositionalDirectives(kind: CommentKind, text: string, placement: DirectivePlacement): string[] {
|
|
462
|
+
const names = new Set<string>();
|
|
463
|
+
for (const name of ruleMatches(kind, text)) {
|
|
464
|
+
if (!FIRST_COMMENT_ONLY_DIRECTIVES.has(name) && !FILE_START_ONLY_DIRECTIVES.has(name)) continue;
|
|
465
|
+
if (isActiveAt(name, placement)) names.add(name);
|
|
466
|
+
}
|
|
467
|
+
return [...names].sort();
|
|
468
|
+
}
|
|
469
|
+
|
|
470
|
+
/**
|
|
471
|
+
* True for license/legal comments (`/*!`, `@license`, `@preserve`,
|
|
472
|
+
* `@copyright`, and the machine-readable `SPDX-License-Identifier:` /
|
|
473
|
+
* `SPDX-FileCopyrightText:` tags) that build tools conventionally keep when
|
|
474
|
+
* stripping comments and that license scanners rely on.
|
|
475
|
+
*/
|
|
476
|
+
export function isLegalComment(text: string): boolean {
|
|
477
|
+
if (text.startsWith("/*!") || text.startsWith("//!")) return true;
|
|
478
|
+
if (/\bSPDX-(?:License-Identifier|FileCopyrightText):/i.test(text)) return true;
|
|
479
|
+
return /@(?:license|preserve|copyright)\b/i.test(text);
|
|
480
|
+
}
|
|
481
|
+
|
|
482
|
+
// Every ECMAScript line terminator, the way the scanner breaks lines: CRLF as
|
|
483
|
+
// one break, plus lone LF / CR and the U+2028/U+2029 separators.
|
|
484
|
+
const LINE_BREAK = /\r\n|[\n\r\u2028\u2029]/;
|
|
485
|
+
|
|
486
|
+
/**
|
|
487
|
+
* Non-empty content lines of the comment, with comment markers stripped.
|
|
488
|
+
* For line comments only the `//` marker itself is removed: extra slashes or
|
|
489
|
+
* stars are content, so `//// @ts-ignore` and `// * prettier-ignore` stay
|
|
490
|
+
* ordinary. JSDoc-style `*` prefixes are stripped for block comments unless
|
|
491
|
+
* `keepStars` asks for the literal lines (for tools that compare the raw
|
|
492
|
+
* comment value, where a leading `*` defeats the directive).
|
|
493
|
+
*/
|
|
494
|
+
function contentLines(kind: CommentKind, text: string, keepStars: boolean): string[] {
|
|
495
|
+
// In keepStars mode only the literal `/*` and `*/` markers go, matching how
|
|
496
|
+
// prettier/oxfmt read the comment value: the second star of a `/**` opener
|
|
497
|
+
// is content and defeats their exact comparison.
|
|
498
|
+
const inner =
|
|
499
|
+
kind === "line"
|
|
500
|
+
? text.replace(/^\/\//, "")
|
|
501
|
+
: keepStars
|
|
502
|
+
? text.replace(/^\/\*/, "").replace(/\*\/\s*$/, "")
|
|
503
|
+
: text.replace(/^\/\*+/, "").replace(/\*+\/\s*$/, "");
|
|
504
|
+
const lines: string[] = [];
|
|
505
|
+
for (const line of inner.split(LINE_BREAK)) {
|
|
506
|
+
const stripped = (kind === "block" && !keepStars ? line.replace(/^\s*\*+\s*/, "") : line).trim();
|
|
507
|
+
if (stripped !== "") lines.push(stripped);
|
|
508
|
+
}
|
|
509
|
+
return lines;
|
|
510
|
+
}
|
|
511
|
+
|
|
512
|
+
/** Literal last line of the comment, closing marker included, exactly as tsc slices it. */
|
|
513
|
+
function lastLine(text: string): string {
|
|
514
|
+
const lines = text.split(LINE_BREAK);
|
|
515
|
+
return lines[lines.length - 1] as string;
|
|
516
|
+
}
|