@kongyo2/ts-comment-scanner 1.10.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/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
  /**
package/src/remove.ts CHANGED
@@ -2,7 +2,7 @@ import { activePositionalDirectives, bunMarkerOffset, isLegalComment, type Direc
2
2
  import type { JsxContainer } from "./jsx.js";
3
3
  import { LINE_TERMINATOR, isBlank, lineStartOffsets } from "./lines.js";
4
4
  import { firstIndexAtOrAfter, type Range } from "./ranges.js";
5
- import { analyzeSource } from "./scanner.js";
5
+ import { analyzeSource, isFileWidePosition, opensFirstRow } from "./scanner.js";
6
6
  import { applyEdits, blankLineEdits, type Edit } from "./splice.js";
7
7
  import type { Comment } from "./types.js";
8
8
 
@@ -12,6 +12,13 @@ export interface RemoveOptions {
12
12
  removeDirectives?: boolean;
13
13
  /** Also remove license/legal comments. Default: false (kept for safety). */
14
14
  removeLegal?: boolean;
15
+ /**
16
+ * Extra protection: return true to keep a comment the way directives are
17
+ * kept, for markers only a project's own tooling reads (a build template's
18
+ * placeholder, a custom linter tag). Wins over removeDirectives and
19
+ * removeLegal; such comments are reported in `kept`.
20
+ */
21
+ keep?: (comment: Comment) => boolean;
15
22
  /** Extra predicate: return false to leave a comment out of the removal entirely. */
16
23
  shouldRemove?: (comment: Comment) => boolean;
17
24
  }
@@ -22,7 +29,9 @@ export interface RemoveResult {
22
29
  removed: Comment[];
23
30
  /**
24
31
  * Comments kept because they are protected: directives, license headers,
25
- * comments whose removal would shift code under a next-line directive or
32
+ * comments the `keep` predicate claims, comments that make a directive
33
+ * trailing rather than standalone (ast-grep's suppression), comments whose
34
+ * removal would shift code under a next-line directive or
26
35
  * that sit between a directive and the code it reaches past them for (or
27
36
  * the JSX sibling it applies to), and comments whose removal would move a
28
37
  * position-dependent directive (prettier's first-comment pragma, Deno's
@@ -189,10 +198,11 @@ function firstChangedSurvivor(
189
198
  * The placement bits the position-dependent directives care about, derived
190
199
  * without a parse: the comment is the file's first comment when nothing but
191
200
  * whitespace (or a shebang) precedes it — any earlier comment's text keeps
192
- * the slice non-blank — and it sits at the file start when it begins where
193
- * Bun reads its marker. Header status needs the token structure, but
194
- * removing comments never moves a comment across the first token, so the
195
- * positional check does not consult it.
201
+ * the slice non-blank — it sits at the file start when it begins where Bun
202
+ * reads its marker, and in ast-grep's file-wide position when it also opens
203
+ * the first line with the next node two or more lines down. Header status
204
+ * needs the token structure, but removing comments never moves a comment
205
+ * across the first token, so the positional check does not consult it.
196
206
  */
197
207
  function positionalPlacement(text: string, comment: Comment): DirectivePlacement {
198
208
  const shebangLength = /^#!.*/.exec(text)?.[0].length ?? 0;
@@ -200,6 +210,7 @@ function positionalPlacement(text: string, comment: Comment): DirectivePlacement
200
210
  header: false,
201
211
  firstComment: isBlank(text.slice(shebangLength, comment.start)),
202
212
  fileStart: comment.start === bunMarkerOffset(text),
213
+ fileWide: isFileWidePosition(text, comment.start, comment.end),
203
214
  };
204
215
  }
205
216
 
@@ -228,6 +239,7 @@ function editKeepingBom(source: string, edits: readonly Edit[]): string {
228
239
  }
229
240
 
230
241
  function isProtected(comment: Comment, options: RemoveOptions): boolean {
242
+ if (options.keep?.(comment) === true) return true;
231
243
  if (comment.directive !== undefined && options.removeDirectives !== true) return true;
232
244
  if (isLegalComment(comment.text) && options.removeLegal !== true) return true;
233
245
  return false;
@@ -499,6 +511,10 @@ function shieldNextLineDirectives(
499
511
  const blockingLines = new Set<number>();
500
512
  const shieldedGaps: Array<readonly [number, number]> = [];
501
513
  const siblingTargets = new Set<Container>();
514
+ /** Directives whose own line, up to where they start, has to stay as it is. */
515
+ const linePrefixes: Comment[] = [];
516
+ /** Directives whose last line, from where they end, has to stay as it is. */
517
+ const lineSuffixes: Comment[] = [];
502
518
  const processed = new Set<Comment>();
503
519
  let stillRemoved = removed;
504
520
  let units: RemovalUnit[] | undefined;
@@ -526,6 +542,11 @@ function shieldNextLineDirectives(
526
542
  added = true;
527
543
  }
528
544
  }
545
+ if (SIBLING_SENSITIVE.has(directive)) {
546
+ linePrefixes.push(comment);
547
+ if (opensFirstRow(source, comment.start)) lineSuffixes.push(comment);
548
+ added = true;
549
+ }
529
550
  if (!isNextLineDirective(directive)) continue;
530
551
  // In JSX, such a directive in braces applies to the sibling after it,
531
552
  // whatever line that is on (prettier leaves the element after
@@ -539,10 +560,13 @@ function shieldNextLineDirectives(
539
560
  // A trailing formatter or scanner suppression (`a = [1]; // oxfmt-ignore`,
540
561
  // `secret(); // nosemgrep`) targets its own line, so it shields nothing
541
562
  // below it. In JSX, the container holding the comment is what has to
542
- // stand on lines of its own.
543
- if (TRAILING_TARGETS_OWN_LINE.has(directive) && !occupiesWholeLines(source, holder ?? comment)) {
544
- continue;
545
- }
563
+ // stand on lines of its own. ast-grep looks only at what precedes the
564
+ // comment on its line: with nothing there it suppresses the next line,
565
+ // even when code follows the comment (`/* ast-grep-ignore *​/ foo();`).
566
+ const trailing = SIBLING_SENSITIVE.has(directive)
567
+ ? !opensItsLine(source, comment)
568
+ : TRAILING_TARGETS_OWN_LINE.has(directive) && !occupiesWholeLines(source, holder ?? comment);
569
+ if (trailing) continue;
546
570
  // Counted pragmas like `c8 ignore next 3` cover several lines.
547
571
  for (let offset = 1; offset <= shieldedLineCount(comment); offset += 1) {
548
572
  const line = comment.endLine + offset;
@@ -589,6 +613,25 @@ function shieldNextLineDirectives(
589
613
  protect(group);
590
614
  changed = true;
591
615
  }
616
+ for (const directive of linePrefixes) {
617
+ // Whatever ends on the directive's line in front of it: the comments
618
+ // that make it a trailing suppression, or that it trails.
619
+ const lineStart = lineOffsets[directive.line - 1] as number;
620
+ const group = currentUnits().filter((unit) => unit.end > lineStart && unit.end <= directive.start);
621
+ if (group.length === 0) continue;
622
+ protect(group.flatMap((unit) => unit.comments));
623
+ changed = true;
624
+ }
625
+ for (const directive of lineSuffixes) {
626
+ // Whatever follows the directive on the line it ends on, when it opens
627
+ // the file: deleting the node after it there can leave the next one two
628
+ // lines down, which makes the suppression file-wide.
629
+ const lineEnd = lineOffsets[directive.endLine] ?? source.length;
630
+ const group = currentUnits().filter((unit) => unit.start >= directive.end && unit.start < lineEnd);
631
+ if (group.length === 0) continue;
632
+ protect(group.flatMap((unit) => unit.comments));
633
+ changed = true;
634
+ }
592
635
  return changed;
593
636
  };
594
637
 
@@ -746,6 +789,16 @@ const TRAILING_TARGETS_OWN_LINE = new Set([
746
789
  "nosemgrep",
747
790
  ]);
748
791
 
792
+ // ast-grep reads a suppression's reach from the nodes beside it, comments
793
+ // included. It tells a trailing suppression from a standalone one by whether
794
+ // the node before it ends on its line, and keys a trailing one to where that
795
+ // node starts. On the file's first line, a standalone one covers the whole
796
+ // file when the node after it starts two or more lines down. Deleting a
797
+ // comment in front of it on its line can therefore turn it into a next-line
798
+ // suppression or move what it trails, and on the first line deleting the
799
+ // comment after it can make it file-wide — so those comments stay.
800
+ const SIBLING_SENSITIVE = new Set(["ast-grep-ignore"]);
801
+
749
802
  // The suppressions tsc looks past blank and `//` lines for (see
750
803
  // firstBlockingLines). They stay next-line directives as well: Flow, which
751
804
  // honours them in TypeScript files, applies them to the very next line.
@@ -827,6 +880,7 @@ const NEXT_LINE_DIRECTIVES = new Set([
827
880
  "pragma-allowlist-nextline-secret",
828
881
  "cspell:disable-next",
829
882
  "HTML",
883
+ "ast-grep-ignore",
830
884
  ]);
831
885
 
832
886
  function isNextLineDirective(name: string): boolean {
@@ -853,12 +907,18 @@ function shieldedLineCount(comment: Comment): number {
853
907
  * scanner numbers them (a lone `\r`, U+2028 and U+2029 count too).
854
908
  */
855
909
  function occupiesWholeLines(source: string, range: Range): boolean {
856
- for (let index = range.start - 1; index >= 0; index -= 1) {
910
+ if (!opensItsLine(source, range)) return false;
911
+ for (let index = range.end; index < source.length; index += 1) {
857
912
  const char = source[index] as string;
858
913
  if (LINE_TERMINATOR.test(char)) break;
859
914
  if (!isBlank(char)) return false;
860
915
  }
861
- for (let index = range.end; index < source.length; index += 1) {
916
+ return true;
917
+ }
918
+
919
+ /** True when nothing but whitespace precedes the range on its first line. */
920
+ function opensItsLine(source: string, range: Range): boolean {
921
+ for (let index = range.start - 1; index >= 0; index -= 1) {
862
922
  const char = source[index] as string;
863
923
  if (LINE_TERMINATOR.test(char)) break;
864
924
  if (!isBlank(char)) return false;
package/src/run.ts CHANGED
@@ -48,6 +48,8 @@ Removal:
48
48
  --dry-run With --remove: show what would be removed, change nothing
49
49
  --remove-directives With --remove: also delete directive comments
50
50
  --remove-legal With --remove: also delete license/legal comments
51
+ --keep <regex> With --remove: also keep comments matching the regular
52
+ expression, like directives (repeatable)
51
53
 
52
54
  General:
53
55
  -h, --help Show this help
@@ -58,7 +60,8 @@ skipping node_modules and .git. Ignore globs without a slash match file names,
58
60
  and a trailing slash (dist/) restricts a glob to directories. JavaScript files
59
61
  (.js, .jsx, .mjs, .cjs) added with --ext are parsed with JSX enabled. Removal
60
62
  keeps directives and license headers unless explicitly requested, so builds
61
- and linters keep working.
63
+ and linters keep working; --keep protects the markers only a project's own
64
+ tooling reads, e.g. --keep "@skipMangle" or --keep "^// INJECT".
62
65
 
63
66
  --diff narrows any scan or removal to files changed in git: a single revision
64
67
  compares the working tree against it (HEAD covers all uncommitted work,
@@ -229,6 +232,7 @@ async function runRemove(options: CliOptions, collectOptions: CollectOptions, io
229
232
  jsx: isJsxFile(file),
230
233
  removeDirectives: options.removeDirectives,
231
234
  removeLegal: options.removeLegal,
235
+ keep: (comment) => options.keep.some((pattern) => pattern.test(comment.text)),
232
236
  shouldRemove: (comment) => inScope(comment, options.directives),
233
237
  });
234
238
  if (result.changed) {
package/src/scanner.ts CHANGED
@@ -1,6 +1,8 @@
1
1
  import ts from "typescript";
2
2
  import { bunMarkerOffset, detectDirective, type DirectivePlacement } from "./directives.js";
3
3
  import { jsxLayout, type JsxLayout } from "./jsx.js";
4
+ import { isBlank } from "./lines.js";
5
+ import { firstIndexAtOrAfter } from "./ranges.js";
4
6
  import type { Comment, CommentKind } from "./types.js";
5
7
 
6
8
  export interface ScanOptions {
@@ -27,6 +29,8 @@ export function analyzeSource(source: string, options: ScanOptions = {}): Source
27
29
  const jsxParents: Array<ts.JsxElement | ts.JsxFragment> = [];
28
30
  const ranges: ts.CommentRange[] = [];
29
31
  const seen = new Set<number>();
32
+ /** Every token, in document order. */
33
+ const tokens: ts.Node[] = [];
30
34
 
31
35
  const collect = (found: readonly ts.CommentRange[] | undefined): void => {
32
36
  if (!found) return;
@@ -49,6 +53,7 @@ export function analyzeSource(source: string, options: ScanOptions = {}): Source
49
53
  // end-of-file token). Treat them as trivia like any other comment.
50
54
  const children = node.getChildren(sourceFile).filter((child) => !ts.isJSDoc(child));
51
55
  if (children.length === 0) {
56
+ tokens.push(node);
52
57
  if (node.kind === ts.SyntaxKind.JsxText) {
53
58
  jsxTextSpans.push([node.getFullStart(), node.getEnd()]);
54
59
  }
@@ -91,30 +96,39 @@ export function analyzeSource(source: string, options: ScanOptions = {}): Source
91
96
  const shebangEnd = ts.getShebang(source)?.length ?? 0;
92
97
  const firstCommentPos = sorted.length > 0 ? (sorted[0] as ts.CommentRange).pos : -1;
93
98
  const bunMarkerPos = bunMarkerOffset(source);
94
- // The token after each comment, past the comments that follow it (`""` when
95
- // only comments do): walking back from the last comment, a gap holding code
96
- // supplies its first token and a blank one passes on the next comment's.
97
- const nextTokens: string[] = [];
98
- let following = "";
99
- for (let index = sorted.length - 1; index >= 0; index -= 1) {
100
- const gapEnd = sorted[index + 1]?.pos ?? source.length;
101
- const gap = source.slice((sorted[index] as ts.CommentRange).end, gapEnd);
102
- following = /^\s*([A-Za-z_$][\w$]*|\S)/.exec(gap)?.[1] ?? following;
103
- nextTokens[index] = following;
104
- }
105
- const placementOf = (pos: number, index: number): DirectivePlacement => ({
106
- header: pos < firstTokenStart,
107
- firstComment: pos === firstCommentPos && /^\s*$/.test(source.slice(shebangEnd, pos)),
108
- fileStart: pos === bunMarkerPos,
109
- nextToken: nextTokens[index] as string,
110
- });
99
+ // The token after a comment, past any further comments: no token overlaps
100
+ // a comment, so it is the first one ending at or past the comment's end
101
+ // (the end-of-file token ends at the text's end). Token ends never
102
+ // decrease in document order, so a binary search finds it — without
103
+ // skipping the leading trivia a token start would need.
104
+ const tokenAfter = (offset: number): ts.Node =>
105
+ tokens[firstIndexAtOrAfter(tokens, offset, (token) => token.end)] as ts.Node;
106
+ const placementOf = (range: ts.CommentRange): DirectivePlacement => {
107
+ // The switch slots walk the syntax tree, so they are worked out only for
108
+ // the comments a switch-clause rule matched, when it asks.
109
+ let slots: ReturnType<typeof switchSlots> | undefined;
110
+ const slotsOf = (): ReturnType<typeof switchSlots> => (slots ??= switchSlots(tokenAfter(range.end)));
111
+ const firstComment = range.pos === firstCommentPos;
112
+ return {
113
+ header: range.pos < firstTokenStart,
114
+ firstComment: firstComment && /^\s*$/.test(source.slice(shebangEnd, range.pos)),
115
+ fileStart: range.pos === bunMarkerPos,
116
+ fileWide: firstComment && isFileWidePosition(source, range.pos, range.end),
117
+ get fallthroughSlot() {
118
+ return slotsOf().fallthroughSlot;
119
+ },
120
+ get noDefaultSlot() {
121
+ return slotsOf().noDefaultSlot;
122
+ },
123
+ };
124
+ };
111
125
 
112
- const comments = sorted.map((range, index): Comment => {
126
+ const comments = sorted.map((range): Comment => {
113
127
  const kind: CommentKind = range.kind === ts.SyntaxKind.SingleLineCommentTrivia ? "line" : "block";
114
128
  const text = source.slice(range.pos, range.end);
115
129
  const startPosition = sourceFile.getLineAndCharacterOfPosition(range.pos);
116
130
  const endPosition = sourceFile.getLineAndCharacterOfPosition(range.end);
117
- const directive = detectDirective(kind, text, placementOf(range.pos, index));
131
+ const directive = detectDirective(kind, text, placementOf(range));
118
132
  return {
119
133
  kind,
120
134
  text,
@@ -130,3 +144,77 @@ export function analyzeSource(source: string, options: ScanOptions = {}): Source
130
144
 
131
145
  return { comments, jsx: jsxLayout(source, sourceFile, jsxParents, comments) };
132
146
  }
147
+
148
+ /**
149
+ * Whether a comment from `start` to `end` sits where ast-grep's suppression
150
+ * comment covers the whole file (`get_suppression_kind` in its `combined.rs`):
151
+ * on the first line with nothing but whitespace in front of it, and with the
152
+ * next node — code or another comment — starting two or more lines further
153
+ * down, or with nothing after it at all. Lines are counted the way tree-sitter
154
+ * counts its rows, by line feeds alone.
155
+ */
156
+ export function isFileWidePosition(text: string, start: number, end: number): boolean {
157
+ if (!opensFirstRow(text, start)) return false;
158
+ const next = text.slice(end).search(/\S/);
159
+ return next === -1 || lineFeedCount(text.slice(0, end + next)) >= 2;
160
+ }
161
+
162
+ /** Whether nothing but whitespace, and no line feed, precedes the offset: the start of tree-sitter's first row. */
163
+ export function opensFirstRow(text: string, offset: number): boolean {
164
+ const before = text.slice(0, offset);
165
+ return isBlank(before) && !before.includes("\n");
166
+ }
167
+
168
+ function lineFeedCount(text: string): number {
169
+ return text.split("\n").length - 1;
170
+ }
171
+
172
+ /**
173
+ * The switch slots (see DirectivePlacement) a comment in front of the given
174
+ * token sits in. The token is what follows the comment past any further
175
+ * comments — the end-of-file token at the latest, whose parent is the file.
176
+ */
177
+ function switchSlots(token: ts.Node): { fallthroughSlot: boolean; noDefaultSlot: boolean } {
178
+ let fallthroughSlot = false;
179
+ let noDefaultSlot = false;
180
+ const parent = token.parent;
181
+ if (
182
+ (token.kind === ts.SyntaxKind.CaseKeyword || token.kind === ts.SyntaxKind.DefaultKeyword) &&
183
+ ts.isCaseOrDefaultClause(parent)
184
+ ) {
185
+ // In front of a clause: where ESLint, oxlint and deno_lint read the
186
+ // comment saying the clause before it falls through — so not the first.
187
+ fallthroughSlot = parent.parent.clauses[0] !== parent;
188
+ } else if (
189
+ token.kind === ts.SyntaxKind.CloseBraceToken &&
190
+ ts.isBlock(parent) &&
191
+ ts.isCaseOrDefaultClause(parent.parent)
192
+ ) {
193
+ // Inside a block that is the last statement of a clause (its only one,
194
+ // for ESLint and oxlint), in front of its closing brace — read when
195
+ // another clause follows.
196
+ const clause = parent.parent;
197
+ const clauses = clause.parent.clauses;
198
+ fallthroughSlot = clause.statements.at(-1) === parent && clauses.at(-1) !== clause;
199
+ } else if (token.kind === ts.SyntaxKind.CloseBraceToken && ts.isCaseBlock(parent)) {
200
+ // After the last clause of a switch, in front of its closing brace:
201
+ // where ESLint's default-case reads its comment.
202
+ noDefaultSlot = lacksDefaultClause(parent);
203
+ }
204
+ // oxlint's default-case reads the last comment from the last clause's
205
+ // start to the switch's end, so the comments inside that clause count too
206
+ // — all but one in front of the clause's opening `case`.
207
+ for (let node = parent; !noDefaultSlot && !ts.isSourceFile(node); node = node.parent) {
208
+ noDefaultSlot =
209
+ ts.isCaseClause(node) &&
210
+ node.parent.clauses.at(-1) === node &&
211
+ lacksDefaultClause(node.parent) &&
212
+ (node !== parent || token.kind !== ts.SyntaxKind.CaseKeyword);
213
+ }
214
+ return { fallthroughSlot, noDefaultSlot };
215
+ }
216
+
217
+ /** Whether the switch has clauses but none of them is a default clause. */
218
+ function lacksDefaultClause(caseBlock: ts.CaseBlock): boolean {
219
+ return caseBlock.clauses.length > 0 && !caseBlock.clauses.some(ts.isDefaultClause);
220
+ }