@kongyo2/ts-comment-scanner 1.9.0 → 1.11.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/dist/splice.js ADDED
@@ -0,0 +1,279 @@
1
+ import { LINE_BREAK, LINE_TERMINATOR, isBlank, lineStartOffsets } from "./lines.js";
2
+ import { firstIndexAtOrAfter, rangeAt } from "./ranges.js";
3
+ const isHorizontalSpace = (char) => char === " " || char === "\t";
4
+ // Brackets never merge with what follows them, nor punctuation with what
5
+ // precedes it, so removing a comment between them needs no space to keep
6
+ // the tokens apart, and the whitespace that only held the comment off them
7
+ // can go: `f(/* a *​/ x)` becomes `f(x)` and `{/* empty *​/}` becomes `{}`.
8
+ const OPENING_BRACKETS = "([{";
9
+ const CLOSING_PUNCTUATION = ")]},;";
10
+ /** Whether `before` and `after`, about to meet where a comment was, need a space between them. */
11
+ function needsSpace(before, after) {
12
+ return !OPENING_BRACKETS.includes(before) && !CLOSING_PUNCTUATION.includes(after);
13
+ }
14
+ // A global copy of the line-break matcher, so exec() can resume from a removal's end offset.
15
+ const NEXT_LINE_BREAK = new RegExp(LINE_BREAK.source, "g");
16
+ /** End offset (exclusive) of the last line break in the chunk, or -1 when it has none. */
17
+ function lastLineBreakEnd(chunk) {
18
+ for (let index = chunk.length - 1; index >= 0; index -= 1) {
19
+ if (LINE_TERMINATOR.test(chunk[index]))
20
+ return index + 1;
21
+ }
22
+ return -1;
23
+ }
24
+ /**
25
+ * Applies sorted, non-overlapping edits to the source, tidying the lines of
26
+ * deleted ranges. Output is accumulated as segments with incremental
27
+ * line-state tracking, so the work stays linear in the source size even for
28
+ * comment-dense files.
29
+ */
30
+ export function applyEdits(source, edits) {
31
+ const segments = [];
32
+ let cursor = 0;
33
+ /** Whether the output's current (unterminated) line is all whitespace so far. */
34
+ let lineIsBlank = true;
35
+ /** Last character of the output so far ("" while empty). */
36
+ let lastChar = "";
37
+ const push = (chunk) => {
38
+ if (chunk === "")
39
+ return;
40
+ segments.push(chunk);
41
+ const breakEnd = lastLineBreakEnd(chunk);
42
+ lineIsBlank = breakEnd === -1 ? lineIsBlank && isBlank(chunk) : isBlank(chunk.slice(breakEnd));
43
+ lastChar = chunk.slice(-1);
44
+ };
45
+ /** Deletes everything the output holds after its last line break. */
46
+ const dropCurrentLine = () => {
47
+ while (segments.length > 0) {
48
+ const last = segments[segments.length - 1];
49
+ const breakEnd = lastLineBreakEnd(last);
50
+ if (breakEnd === -1) {
51
+ segments.pop();
52
+ continue;
53
+ }
54
+ segments[segments.length - 1] = last.slice(0, breakEnd);
55
+ lineIsBlank = true;
56
+ lastChar = last.charAt(breakEnd - 1);
57
+ return;
58
+ }
59
+ lineIsBlank = true;
60
+ lastChar = "";
61
+ };
62
+ /**
63
+ * Deletes trailing spaces/tabs of the output's current line. Only called
64
+ * while that line holds code, which the trimming stops at.
65
+ */
66
+ const trimLineEnd = () => {
67
+ for (;;) {
68
+ const last = segments[segments.length - 1];
69
+ let end = last.length;
70
+ while (end > 0 && isHorizontalSpace(last[end - 1]))
71
+ end -= 1;
72
+ if (end > 0) {
73
+ segments[segments.length - 1] = last.slice(0, end);
74
+ lastChar = last.charAt(end - 1);
75
+ return;
76
+ }
77
+ segments.pop();
78
+ }
79
+ };
80
+ /** Offset of the first character at or after `from` that is not a space or tab. */
81
+ const skipSpaces = (from) => {
82
+ let index = from;
83
+ while (isHorizontalSpace(source[index]))
84
+ index += 1;
85
+ return index;
86
+ };
87
+ for (const edit of edits) {
88
+ push(source.slice(cursor, edit.start));
89
+ cursor = edit.end;
90
+ if (edit.replacement !== undefined) {
91
+ push(edit.replacement);
92
+ continue;
93
+ }
94
+ NEXT_LINE_BREAK.lastIndex = cursor;
95
+ const lineBreak = NEXT_LINE_BREAK.exec(source);
96
+ const contentEnd = lineBreak === null ? source.length : lineBreak.index;
97
+ const lineEnd = lineBreak === null ? source.length : lineBreak.index + lineBreak[0].length;
98
+ const restContent = source.slice(cursor, contentEnd);
99
+ const deleted = source.slice(edit.start, edit.end);
100
+ if (lineIsBlank && isBlank(restContent)) {
101
+ // The range occupied whole line(s): drop them entirely.
102
+ dropCurrentLine();
103
+ cursor = lineEnd;
104
+ }
105
+ else if (isBlank(restContent)) {
106
+ // Trailing after code: trim the gap, keep the line break.
107
+ trimLineEnd();
108
+ push(source.slice(contentEnd, lineEnd));
109
+ cursor = lineEnd;
110
+ }
111
+ else if (!lineIsBlank && LINE_TERMINATOR.test(deleted) && needsSpace(lastChar, source.charAt(cursor))) {
112
+ // Code on both sides of a range that spans lines. Per ECMA-262 a
113
+ // multi-line comment acts as a line terminator for semicolon
114
+ // insertion, so a real line break (matching the file's style) takes
115
+ // its place instead of merging the lines. (Right after an opening
116
+ // bracket or before closing punctuation a line terminator changes
117
+ // nothing, so a multi-line comment there goes without one.)
118
+ trimLineEnd();
119
+ push(deleted.includes("\r\n") ? "\r\n" : "\n");
120
+ }
121
+ else if (lastChar !== "" && !isBlank(lastChar)) {
122
+ // Code right before the range, more on the same line after it.
123
+ if (edit.jsx === true)
124
+ continue;
125
+ const next = source.charAt(cursor);
126
+ if (!isBlank(next)) {
127
+ // `a/* x *​/b` would merge tokens: keep them apart.
128
+ if (needsSpace(lastChar, next))
129
+ push(" ");
130
+ }
131
+ else if (OPENING_BRACKETS.includes(lastChar)) {
132
+ // `(/* x *​/ a` — the space only held the comment off the code.
133
+ cursor = skipSpaces(cursor);
134
+ }
135
+ }
136
+ else {
137
+ // Whitespace (or the line start) right before the range: the
138
+ // whitespace after it collapses into that.
139
+ cursor = skipSpaces(cursor);
140
+ if (edit.jsx !== true && !lineIsBlank && CLOSING_PUNCTUATION.includes(source.charAt(cursor))) {
141
+ // `a /* x *​/)` — the space before only held the comment off the code.
142
+ trimLineEnd();
143
+ }
144
+ }
145
+ }
146
+ segments.push(source.slice(cursor));
147
+ return segments.join("");
148
+ }
149
+ /**
150
+ * Deletions of the blank lines that removing whole comment lines would pile
151
+ * up. Where comment-only lines vanish, the blank lines around them close
152
+ * ranks: two paragraphs that a comment stood between, each separated from it
153
+ * by a blank line, end up separated by two. Every run of blank and vanishing
154
+ * lines is therefore trimmed to as many blank lines as the widest gap it
155
+ * held — never more than the source had in one place, never fewer than it
156
+ * had on either side — except at the start or end of the file, or of a
157
+ * block (an opening bracket ending the line before, a closing one starting
158
+ * the line after, or JSX tags), where only the blank lines that already sat
159
+ * against that edge stay: the ones on the far side of the comment merely
160
+ * separated the comment from the code.
161
+ *
162
+ * `deletions` are the ranges about to be deleted, sorted; a line vanishes
163
+ * when every non-whitespace character on it is deleted. Blank lines hold
164
+ * nothing but spaces and tabs (a lone vertical tab or no-break space is
165
+ * content to tsc 7) and lie outside every comment. `shieldedLines` are
166
+ * lines a surviving next-line directive reaches (1-based): the blank lines
167
+ * among them stay, so no code moves into the directive's reach.
168
+ */
169
+ export function blankLineEdits(source, deletions, comments, shieldedLines, tags) {
170
+ const offsets = lineStartOffsets(source);
171
+ // A final line break ends the last line rather than opening an empty one.
172
+ const lineCount = offsets.length > 1 && offsets[offsets.length - 1] === source.length ? offsets.length - 1 : offsets.length;
173
+ const lineStart = (line) => offsets[line];
174
+ const lineContentEnd = (line) => endOfContent(source, lineStart(line), offsets[line + 1] ?? source.length);
175
+ const kinds = [];
176
+ for (let line = 0; line < lineCount; line += 1) {
177
+ kinds.push(lineKind(source, lineStart(line), offsets[line + 1] ?? source.length, lineContentEnd(line), deletions, comments));
178
+ }
179
+ /** Offset of the first (or last) character on the line that survives the deletions and is not whitespace. */
180
+ const survivingEdge = (line, fromEnd) => {
181
+ const start = lineStart(line);
182
+ const end = lineContentEnd(line);
183
+ for (let step = 0; step < end - start; step += 1) {
184
+ const index = fromEnd ? end - 1 - step : start + step;
185
+ if (!isBlank(source[index]) && rangeAt(deletions, index) === undefined)
186
+ return index;
187
+ }
188
+ return undefined;
189
+ };
190
+ const opensBlock = (line) => {
191
+ const index = survivingEdge(line, true);
192
+ return (index !== undefined &&
193
+ rangeAt(comments, index) === undefined &&
194
+ (OPENING_BRACKETS.includes(source[index]) || tags.openingTagEnds.has(index + 1)));
195
+ };
196
+ // (A line's first surviving character is never inside a comment unless it
197
+ // is the comment's opening slash, so no comment check is needed here.)
198
+ const closesBlock = (line) => {
199
+ const index = survivingEdge(line, false);
200
+ return index !== undefined && (")]}".includes(source[index]) || tags.closingTagStarts.has(index));
201
+ };
202
+ const edits = [];
203
+ let line = 0;
204
+ while (line < lineCount) {
205
+ if (kinds[line] === "code") {
206
+ line += 1;
207
+ continue;
208
+ }
209
+ const first = line;
210
+ const blanks = [];
211
+ // Blank lines between consecutive vanishing lines, from before the first to after the last.
212
+ const gaps = [0];
213
+ for (; line < lineCount && kinds[line] !== "code"; line += 1) {
214
+ if (kinds[line] === "vanishing") {
215
+ gaps.push(0);
216
+ }
217
+ else {
218
+ blanks.push(line);
219
+ gaps[gaps.length - 1] = gaps[gaps.length - 1] + 1;
220
+ }
221
+ }
222
+ if (gaps.length === 1)
223
+ continue;
224
+ const leading = gaps[0];
225
+ const trailing = gaps[gaps.length - 1];
226
+ const atStart = first === 0;
227
+ const atEnd = line === lineCount;
228
+ let keep;
229
+ if (atStart || atEnd) {
230
+ keep = atEnd ? (atStart ? 0 : trailing) : leading;
231
+ }
232
+ else {
233
+ const opens = opensBlock(first - 1);
234
+ const closes = closesBlock(line);
235
+ if (opens && closes)
236
+ keep = Math.min(leading, trailing);
237
+ else if (opens)
238
+ keep = leading;
239
+ else if (closes)
240
+ keep = trailing;
241
+ else
242
+ keep = gaps.reduce((widest, gap) => Math.max(widest, gap));
243
+ }
244
+ for (const [position, blank] of blanks.entries()) {
245
+ if (shieldedLines.has(blank + 1))
246
+ keep = Math.max(keep, position + 1);
247
+ }
248
+ for (const blank of blanks.slice(keep)) {
249
+ edits.push({ start: lineStart(blank), end: lineContentEnd(blank) });
250
+ }
251
+ }
252
+ return edits;
253
+ }
254
+ /** Offset where the line's content ends, before its line break (CRLF counts as one). */
255
+ function endOfContent(source, start, end) {
256
+ if (end - start >= 2 && source[end - 2] === "\r" && source[end - 1] === "\n")
257
+ return end - 2;
258
+ if (end > start && LINE_TERMINATOR.test(source[end - 1]))
259
+ return end - 1;
260
+ return end;
261
+ }
262
+ function lineKind(source, start, end, contentEnd, deletions, comments) {
263
+ // Sorted, non-overlapping ranges end in ascending order too, so the first
264
+ // one ending past the line start is the only candidate for touching it.
265
+ const touches = (ranges) => {
266
+ const range = ranges[firstIndexAtOrAfter(ranges, start + 1, (candidate) => candidate.end)];
267
+ return range !== undefined && range.start < end;
268
+ };
269
+ if (touches(deletions)) {
270
+ let covered = true;
271
+ for (let index = start; index < contentEnd && covered; index += 1) {
272
+ covered = isBlank(source[index]) || rangeAt(deletions, index) !== undefined;
273
+ }
274
+ if (covered)
275
+ return "vanishing";
276
+ }
277
+ return /^[ \t]*$/.test(source.slice(start, contentEnd)) && !touches(comments) ? "blank" : "code";
278
+ }
279
+ //# sourceMappingURL=splice.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"splice.js","sourceRoot":"","sources":["../src/splice.ts"],"names":[],"mappings":"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"}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@kongyo2/ts-comment-scanner",
3
- "version": "1.9.0",
3
+ "version": "1.11.0",
4
4
  "description": "CLI to detect, report and safely remove comments across a TypeScript project.",
5
5
  "keywords": [
6
6
  "typescript",
package/src/args.ts CHANGED
@@ -12,6 +12,8 @@ export interface CliOptions {
12
12
  remove: boolean;
13
13
  removeDirectives: boolean;
14
14
  removeLegal: boolean;
15
+ /** Patterns of comments --remove keeps anyway (--keep). */
16
+ keep: RegExp[];
15
17
  dryRun: boolean;
16
18
  help: boolean;
17
19
  version: boolean;
@@ -32,6 +34,7 @@ export function parseArgs(argv: string[]): CliOptions {
32
34
  const paths: string[] = [];
33
35
  const ignore: string[] = [];
34
36
  const extensions: string[] = [];
37
+ const keep: RegExp[] = [];
35
38
  let format: OutputFormat = "text";
36
39
  let diff: string | undefined;
37
40
  let directives: DirectiveMode = "include";
@@ -132,6 +135,18 @@ export function parseArgs(argv: string[]): CliOptions {
132
135
  rejectValue();
133
136
  removeLegal = true;
134
137
  break;
138
+ case "--keep": {
139
+ // A forgotten pattern must not swallow the next flag: `--keep --dry-run`
140
+ // would turn a preview into an in-place removal. A pattern that does
141
+ // start with `-` can still be given inline, as `--keep=-x`.
142
+ if (inlineValue === undefined && argv[index + 1]?.startsWith("-") === true) {
143
+ throw new UsageError(
144
+ `option ${flag} requires a regular expression (use ${flag}=<regex> for one starting with "-")`,
145
+ );
146
+ }
147
+ keep.push(parsePattern(flag, readValue()));
148
+ break;
149
+ }
135
150
  case "--dry-run":
136
151
  rejectValue();
137
152
  dryRun = true;
@@ -156,6 +171,7 @@ export function parseArgs(argv: string[]): CliOptions {
156
171
  [dryRun, "--dry-run"],
157
172
  [removeDirectives, "--remove-directives"],
158
173
  [removeLegal, "--remove-legal"],
174
+ [keep.length > 0, "--keep"],
159
175
  ] as const) {
160
176
  if (set) throw new UsageError(`${flag} requires --remove`);
161
177
  }
@@ -186,12 +202,24 @@ export function parseArgs(argv: string[]): CliOptions {
186
202
  remove,
187
203
  removeDirectives,
188
204
  removeLegal,
205
+ keep,
189
206
  dryRun,
190
207
  help,
191
208
  version,
192
209
  };
193
210
  }
194
211
 
212
+ /** Compiles a pattern-valued option, reporting an invalid regular expression as a usage error. */
213
+ function parsePattern(flag: string, value: string): RegExp {
214
+ if (value === "") throw new UsageError(`option ${flag} requires a regular expression`);
215
+ try {
216
+ return new RegExp(value);
217
+ } catch (error) {
218
+ // The engine's message names the problem: "Invalid regular expression: /(/: Unterminated group".
219
+ throw new UsageError(`option ${flag}: ${(error as Error).message}`);
220
+ }
221
+ }
222
+
195
223
  function splitFlag(arg: string): [string, string | undefined] {
196
224
  const equalsIndex = arg.indexOf("=");
197
225
  if (arg.startsWith("--") && equalsIndex > 2) {
package/src/directives.ts CHANGED
@@ -45,6 +45,13 @@ interface DirectiveRule {
45
45
  * trimmed body, so `/** prettier-ignore *​/` is NOT a suppression to them).
46
46
  */
47
47
  keepStars?: boolean;
48
+ /**
49
+ * The match only counts when the comment is the file's first comment, for
50
+ * a tool that reads one docblock at the top of the file (Jest) where
51
+ * another tool reports the same name from anywhere (Vitest) — so the gate
52
+ * belongs to the rule rather than to the name.
53
+ */
54
+ firstCommentOnly?: boolean;
48
55
  }
49
56
 
50
57
  // stylelint's configuration commands, compared verbatim (as in its
@@ -71,6 +78,9 @@ function stylelintDirective(token: string): string | undefined {
71
78
  // --require-pragma looks for and --check-ignore-pragma stops on.
72
79
  const FORMAT_PRAGMA_KEYS: ReadonlySet<string> = new Set(["format", "prettier", "noformat", "noprettier"]);
73
80
 
81
+ // The docblock keys jest-runner reads to pick and configure a file's test environment.
82
+ const JEST_DOCBLOCK_KEYS: ReadonlySet<string> = new Set(["jest-environment", "jest-environment-options"]);
83
+
74
84
  // The canonical spelling of each JSX pragma, keyed by its lowercased name.
75
85
  const JSX_PRAGMAS: ReadonlyMap<string, string> = new Map(
76
86
  ["jsx", "jsxFrag", "jsxRuntime", "jsxImportSource", "jsxImportSourceTypes"].map((name) => [
@@ -154,6 +164,14 @@ const RULES: DirectiveRule[] = [
154
164
  name: "rome-ignore",
155
165
  anyLine: true,
156
166
  },
167
+ // ast-grep reads a comment as a suppression when its first alphabetic
168
+ // character starts `ast-grep-ignore` (`is_suppression_comment` in its
169
+ // `combined.rs`), so the comment marker, stars and other punctuation may
170
+ // precede it while a word in front makes it prose; `: rule-id, ...` limits
171
+ // it to the rules named. Standing alone it suppresses the next line, after
172
+ // code it suppresses the statement it trails, and in the file-wide position
173
+ // (on the first line, with the next node two or more lines down) the file.
174
+ { pattern: /^\P{Alphabetic}*ast-grep-ignore/u, rawText: true, name: "ast-grep-ignore" },
157
175
  // Deno. deno_lint compares the first whitespace-delimited token of the
158
176
  // trimmed comment text with the directive, so a JSDoc star in front defeats
159
177
  // it; `deno-lint-ignore` may be a block comment (the only form inside JSX
@@ -302,6 +320,12 @@ const RULES: DirectiveRule[] = [
302
320
  // anything but an ASCII letter or digit (`@ts-strict-ignore: legacy`).
303
321
  { pattern: /(?:^|\s)@ts-strict(-ignore)?(?=\s|$)/, name: tsStrictName, anyLine: true },
304
322
  { pattern: /(?:^[\s*]*|\/\/+\s*|\/\*+\s*)@ts-strict(-ignore)?(?![A-Za-z0-9])/im, rawText: true, name: tsStrictName },
323
+ // tsc's stripInternal leaves a declaration out of the emitted .d.ts when
324
+ // one of its leading comments contains `@internal` — a bare substring
325
+ // check on the raw comment text, of either kind (`hasInternalAnnotation`
326
+ // in tsc 6's declarations transformer and in tsc 7's port alike). knip
327
+ // also skips exports tagged `@internal` in production mode.
328
+ { pattern: /@internal/, rawText: true, name: "@internal" },
305
329
  // Flow. The pragmas live in the file's leading comments. Prettier's babel
306
330
  // parser switches to Flow syntax when /@(?:no)?flow\b/ matches anywhere in
307
331
  // the text before the first token (isFlowFile in its parse/babel.js), so
@@ -432,6 +456,21 @@ const RULES: DirectiveRule[] = [
432
456
  name: (match) => `@${match[1]}`,
433
457
  anyLine: true,
434
458
  },
459
+ // Jest itself reads the two @jest- pragmas from the docblock opening the
460
+ // file, through jest-docblock (`docblock.parse(docblock.extract(source))`
461
+ // in jest-runner), and takes whatever value follows the key: a scoped
462
+ // package (`@edge-runtime/jest-environment`) or a path (`./env.js`), which
463
+ // Vitest's `[\w-]+` value never matches.
464
+ {
465
+ pattern: /^\/\*/,
466
+ rawText: true,
467
+ blockOnly: true,
468
+ firstCommentOnly: true,
469
+ name: (match) =>
470
+ docblockPragmas(match.input)
471
+ .filter((key) => JEST_DOCBLOCK_KEYS.has(key))
472
+ .map((key) => `@${key}`),
473
+ },
435
474
  // Vitest module tags: /(\/\/|\*)\s*@module-tag\s+([\w\-/]+)\b/ over the
436
475
  // whole file, so the tag has to follow a `//` or a `*` — any of the
437
476
  // comment's — with only whitespace between.
@@ -559,11 +598,34 @@ export interface DirectivePlacement {
559
598
  * that ends a leading `#!` line (see bunMarkerOffset).
560
599
  */
561
600
  fileStart: boolean;
601
+ /**
602
+ * The comment sits where ast-grep's suppression comment applies to the
603
+ * whole file: it starts the file's first line (nothing but whitespace before
604
+ * it) and whatever follows it starts two or more lines further down, or
605
+ * nothing does. Left out, the comment is assumed not to.
606
+ */
607
+ fileWide?: boolean;
608
+ /**
609
+ * The comment sits where a linter reads a switch fall-through comment
610
+ * (`// falls through`): in front of a `case` or `default` clause other than
611
+ * the first (ESLint, oxlint and deno_lint), or in front of the closing brace
612
+ * of a block that ends a clause another clause follows (the comment inside
613
+ * `case 0: { a(); // falls through }`). Left out, nextToken decides.
614
+ */
615
+ fallthroughSlot?: boolean;
616
+ /**
617
+ * The comment sits where `default-case` reads its `// no default` comment in
618
+ * a switch without a default clause: after its last clause, in front of the
619
+ * switch's closing brace (ESLint), or anywhere from that clause's start on
620
+ * (oxlint). Left out, nextToken decides.
621
+ */
622
+ noDefaultSlot?: boolean;
562
623
  /**
563
624
  * The token that follows the comment past any further comments (`case`,
564
- * `}`, an identifier, ...), or `""` when only comments follow. ESLint's
565
- * switch-clause comments (`// falls through`, `// no default`) count only in
566
- * front of certain tokens. Left out, any token is assumed.
625
+ * `}`, an identifier, ...), or `""` when only comments follow: a coarser
626
+ * stand-in for the switch slots above, used when they are left out, where
627
+ * the fall-through and default-case comments count only in front of
628
+ * `case`, `default` or `}`. Left out too, any position is assumed.
567
629
  */
568
630
  nextToken?: string;
569
631
  }
@@ -626,13 +688,16 @@ const FIRST_COMMENT_ONLY_DIRECTIVES = new Set([
626
688
  // line after its shebang; anywhere else the marker is inert.
627
689
  const FILE_START_ONLY_DIRECTIVES = new Set(["@bun"]);
628
690
 
629
- // ESLint's no-fallthrough reads the last comment before the next `case` or
630
- // `default` (or before a case block's closing brace), and default-case the
631
- // last one before the switch's closing brace; in front of anything else the
632
- // same words are prose.
633
- const SWITCH_CLAUSE_TARGETS: ReadonlyMap<string, ReadonlySet<string>> = new Map([
634
- ["fallthrough", new Set(["case", "default", "}"])],
635
- ["no-default", new Set(["}"])],
691
+ // The linters read their switch comments only in particular slots (see
692
+ // fallthroughSlot and noDefaultSlot); in front of anything else the same
693
+ // words are prose. Without the slots, the tokens a comment in one of them can
694
+ // stand in front of are the coarse check.
695
+ const SWITCH_CLAUSE_SLOTS: ReadonlyMap<
696
+ string,
697
+ { slot: (placement: DirectivePlacement) => boolean | undefined; tokens: ReadonlySet<string> }
698
+ > = new Map([
699
+ ["fallthrough", { slot: (placement) => placement.fallthroughSlot, tokens: new Set(["case", "default", "}"]) }],
700
+ ["no-default", { slot: (placement) => placement.noDefaultSlot, tokens: new Set(["}"]) }],
636
701
  ]);
637
702
 
638
703
  function isActiveAt(name: string, placement: DirectivePlacement): boolean {
@@ -641,8 +706,12 @@ function isActiveAt(name: string, placement: DirectivePlacement): boolean {
641
706
  if (HEADER_ONLY_DIRECTIVES.has(name) || name.startsWith("triple-slash-")) {
642
707
  return placement.header;
643
708
  }
644
- const targets = SWITCH_CLAUSE_TARGETS.get(name);
645
- if (targets !== undefined) return placement.nextToken === undefined || targets.has(placement.nextToken);
709
+ const switchClause = SWITCH_CLAUSE_SLOTS.get(name);
710
+ if (switchClause !== undefined) {
711
+ const slot = switchClause.slot(placement);
712
+ if (slot !== undefined) return slot;
713
+ return placement.nextToken === undefined || switchClause.tokens.has(placement.nextToken);
714
+ }
646
715
  return true;
647
716
  }
648
717
 
@@ -709,19 +778,27 @@ export function detectDirective(kind: CommentKind, text: string, placement?: Dir
709
778
  // Semgrep suppression, with the next-line shield that goes with it); only
710
779
  // without one does a marker found after other text name the comment.
711
780
  let mention: string | undefined;
712
- for (const { name, opening } of ruleMatches(kind, text)) {
713
- if (!isActiveAt(name, at)) continue;
714
- if (opening) return name;
715
- mention ??= name;
781
+ for (const match of ruleMatches(kind, text)) {
782
+ if (!isMatchActiveAt(match, at)) continue;
783
+ if (match.opening) return match.name;
784
+ mention ??= match.name;
716
785
  }
717
786
  return mention;
718
787
  }
719
788
 
720
- /** Directive names of every rule the comment matches, in rule order. */
721
- /** A rule's directive name, and whether its match opens the comment rather than following other text. */
789
+ /**
790
+ * A rule's directive name, whether its match opens the comment rather than
791
+ * following other text, and whether the rule only counts in the file's
792
+ * first comment.
793
+ */
722
794
  interface RuleMatch {
723
795
  name: string;
724
796
  opening: boolean;
797
+ firstCommentOnly: boolean;
798
+ }
799
+
800
+ function isMatchActiveAt(match: RuleMatch, placement: DirectivePlacement): boolean {
801
+ return isActiveAt(match.name, placement) && (!match.firstCommentOnly || placement.firstComment);
725
802
  }
726
803
 
727
804
  function* ruleMatches(kind: CommentKind, text: string): Generator<RuleMatch> {
@@ -751,40 +828,76 @@ function* ruleMatches(kind: CommentKind, text: string): Generator<RuleMatch> {
751
828
  const name =
752
829
  typeof rule.name === "string" ? rule.name : typeof rule.name === "function" ? rule.name(match) : match[0];
753
830
  if (name === undefined) continue;
754
- for (const each of typeof name === "string" ? [name] : name) yield { name: each, opening };
831
+ const firstCommentOnly = rule.firstCommentOnly === true;
832
+ for (const each of typeof name === "string" ? [name] : name) yield { name: each, opening, firstCommentOnly };
755
833
  }
756
834
  }
757
835
  }
758
836
 
837
+ // ast-grep suppresses the whole file from a suppression comment in the
838
+ // file-wide position (see DirectivePlacement.fileWide), and only the next line
839
+ // from one anywhere else — so a comment moving into that position changes its
840
+ // reach.
841
+ const FILE_WIDE_SUPPRESSIONS: ReadonlySet<string> = new Set(["ast-grep-ignore"]);
842
+
759
843
  /**
760
- * The position-dependent directives (prettier's first-comment pragmas, Deno's
761
- * coverage file pragma, Bun's file-start marker) the comment carries that are
762
- * active at the given placement, sorted. Unlike detectDirective — which
763
- * reports one canonical name — this sees through masking: an eslint config
764
- * block can also hold a `@format` pragma, and whether that pragma is live
765
- * must not hide behind the name an earlier rule already claimed. Only
766
- * first-comment and file-start gates are consulted; header-gated directives
844
+ * The position-dependent directives (prettier's first-comment pragmas, Jest's
845
+ * docblock pragmas, Deno's coverage file pragma, Bun's file-start marker,
846
+ * ast-grep's file-wide suppression) the comment carries that are active at
847
+ * the given placement, sorted. Unlike detectDirective — which reports one
848
+ * canonical name — this sees through masking: an eslint config block can also
849
+ * hold a `@format` pragma, and whether that pragma is live must not hide
850
+ * behind the name an earlier rule already claimed. Only first-comment,
851
+ * file-start and file-wide gates are consulted; header-gated directives
767
852
  * cannot change activation when the comments around them change.
768
853
  */
769
854
  export function activePositionalDirectives(kind: CommentKind, text: string, placement: DirectivePlacement): string[] {
770
855
  const names = new Set<string>();
771
- for (const { name } of ruleMatches(kind, text)) {
772
- if (!FIRST_COMMENT_ONLY_DIRECTIVES.has(name) && !FILE_START_ONLY_DIRECTIVES.has(name)) continue;
773
- if (isActiveAt(name, placement)) names.add(name);
856
+ for (const match of ruleMatches(kind, text)) {
857
+ const { name } = match;
858
+ if (FILE_WIDE_SUPPRESSIONS.has(name)) {
859
+ if (placement.fileWide === true) names.add(`${name}:file`);
860
+ continue;
861
+ }
862
+ const positional =
863
+ match.firstCommentOnly || FIRST_COMMENT_ONLY_DIRECTIVES.has(name) || FILE_START_ONLY_DIRECTIVES.has(name);
864
+ if (positional && isMatchActiveAt(match, placement)) names.add(name);
774
865
  }
775
866
  return [...names].sort();
776
867
  }
777
868
 
869
+ // Copyright notices and license grants in their conventional wording, as the
870
+ // headers of most projects and of vendored code spell them out without any
871
+ // tag: `Copyright (c) Microsoft Corporation. All rights reserved.`, `Copyright
872
+ // 2011 Mozilla Foundation`, `Copyright Joyent, Inc.`, `© 2024 Someone`,
873
+ // `Licensed under the MIT License`, the MIT, BSD, MPL and GPL texts. These
874
+ // are what license scanners (REUSE, ScanCode) read a file's notices from.
875
+ const LEGAL_NOTICES: readonly RegExp[] = [
876
+ /\bcopyright\s*(?:\(c\)|©|\d{4})/i,
877
+ /\bCopyright\s+[A-Z]/,
878
+ /(?:©|\(c\))\s*\d{4}/i,
879
+ /\blicensed under\b/i,
880
+ /\ball rights reserved\b/i,
881
+ /\bpermission is hereby granted\b/i,
882
+ /\bredistribution and use in source and binary forms\b/i,
883
+ /\bsubject to the terms of the Mozilla Public License\b/i,
884
+ /\bGNU (?:Affero |Lesser )?General Public License\b/i,
885
+ ];
886
+
778
887
  /**
779
- * True for license/legal comments (`/*!`, `@license`, `@preserve`,
780
- * `@copyright`, and the machine-readable `SPDX-License-Identifier:` /
781
- * `SPDX-FileCopyrightText:` tags) that build tools conventionally keep when
782
- * stripping comments and that license scanners rely on.
888
+ * True for license/legal comments that build tools conventionally keep when
889
+ * stripping comments and that license scanners rely on: the ones terser
890
+ * keeps (a value opening with `!` after any stars — `/*!`, `/**!`, `//!` —
891
+ * or holding `@preserve`, `@copyright` or `@lic…`), which cover esbuild's
892
+ * (`/*!`, `//!`, `@license`, `@preserve`); the machine-readable
893
+ * `SPDX-License-Identifier:` / `SPDX-FileCopyrightText:` tags; and copyright
894
+ * notices and license grants in their conventional wording.
783
895
  */
784
896
  export function isLegalComment(text: string): boolean {
785
- if (text.startsWith("/*!") || text.startsWith("//!")) return true;
897
+ if (/^\/[/*]\**!/.test(text)) return true;
898
+ if (/@(?:preserve|copyright|lic)/i.test(text)) return true;
786
899
  if (/\bSPDX-(?:License-Identifier|FileCopyrightText):/i.test(text)) return true;
787
- return /@(?:license|preserve|copyright)\b/i.test(text);
900
+ return LEGAL_NOTICES.some((notice) => notice.test(text));
788
901
  }
789
902
 
790
903
  /**