@kongyo2/ts-comment-scanner 1.10.0 → 1.11.1
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.md +403 -137
- package/dist/args.d.ts +2 -0
- package/dist/args.d.ts.map +1 -1
- package/dist/args.js +25 -0
- package/dist/args.js.map +1 -1
- package/dist/directives.d.ts +41 -14
- package/dist/directives.d.ts.map +1 -1
- package/dist/directives.js +103 -32
- package/dist/directives.js.map +1 -1
- package/dist/remove.d.ts +10 -1
- package/dist/remove.d.ts.map +1 -1
- package/dist/remove.js +65 -10
- package/dist/remove.js.map +1 -1
- package/dist/run.d.ts.map +1 -1
- package/dist/run.js +5 -1
- package/dist/run.js.map +1 -1
- package/dist/scanner.d.ts +11 -0
- package/dist/scanner.d.ts.map +1 -1
- package/dist/scanner.js +100 -19
- package/dist/scanner.js.map +1 -1
- package/package.json +1 -1
- package/src/args.ts +28 -0
- package/src/directives.ts +148 -35
- package/src/remove.ts +72 -12
- package/src/run.ts +5 -1
- package/src/scanner.ts +107 -19
- package/README.en.md +0 -241
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
|
|
565
|
-
*
|
|
566
|
-
*
|
|
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
|
-
//
|
|
630
|
-
//
|
|
631
|
-
//
|
|
632
|
-
//
|
|
633
|
-
const
|
|
634
|
-
|
|
635
|
-
|
|
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
|
|
645
|
-
if (
|
|
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
|
|
713
|
-
if (!
|
|
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
|
-
/**
|
|
721
|
-
|
|
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
|
-
|
|
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,
|
|
761
|
-
* coverage file pragma, Bun's file-start marker
|
|
762
|
-
*
|
|
763
|
-
*
|
|
764
|
-
*
|
|
765
|
-
*
|
|
766
|
-
*
|
|
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
|
|
772
|
-
|
|
773
|
-
if (
|
|
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
|
|
780
|
-
*
|
|
781
|
-
*
|
|
782
|
-
*
|
|
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 (
|
|
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
|
|
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
|
|
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 —
|
|
193
|
-
*
|
|
194
|
-
*
|
|
195
|
-
*
|
|
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
|
-
|
|
544
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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) {
|