@vibe-agent-toolkit/utils 0.1.42-rc.1 → 0.1.42

package/eslint/rules/path-function-rule-factory.cjs

@@ -9,6 +9,11 @@
  * subpath that owns `safePath`, NOT the barrel. See `safe-import.cjs`.
  */
 
+const {
+  DEAD_UNSAFE_IMPORT,
+  DEAD_UNSAFE_IMPORT_MESSAGE,
+  reportDeadUnsafeImports,
+} = require('./dead-import.cjs');
 const {
   UNANCHORED_EXEMPT_FILE,
   UNANCHORED_EXEMPT_MESSAGE,
@@ -18,6 +23,7 @@ const {
 const {
   EXEMPT_AND_SAFE_MODULE_SCHEMA,
   SAFE_PATH_MODULE,
+  insertAboveWithComments,
   isNameAlreadyBound,
   resolveSafeModule,
 } = require('./safe-import.cjs');
@@ -58,10 +64,31 @@ function removeSpecifier(fixer, sourceCode, importNode, spec) {
 
 /**
  * Track path module specifiers from an import declaration.
+ *
+ * Two specifier shapes are deliberately NOT tracked, because tracking them is
+ * what let the fixer delete them:
+ *
+ * - **Type-only** (`import { type join, … }` / `import type { join }`). The
+ *   binding exists only for the type checker; there is no call to rewrite, and
+ *   removing the specifier silently breaks every `typeof join` that referenced
+ *   it. `no-undef` cannot see the damage — it is a TYPE reference.
+ * - **Aliased** (`import { join as pathJoin }`). The rule never reported
+ *   `pathJoin(...)` in the first place — `classifyCall` matches on the callee's
+ *   name — so tracking the specifier bought nothing and cost the whole import:
+ *   an unrelated unbound `join(` elsewhere in the file made the fixer remove
+ *   the alias, breaking every working `pathJoin` call site.
  */
 function trackPathImport(node, unsafeFn, state) {
+  if (node.importKind === 'type') {
+    return;
+  }
   for (const spec of node.specifiers) {
-    if (spec.type === 'ImportSpecifier' && spec.imported.name === unsafeFn) {
+    if (
+      spec.type === 'ImportSpecifier' &&
+      spec.importKind !== 'type' &&
+      spec.imported.name === unsafeFn &&
+      spec.local.name === unsafeFn
+    ) {
       state.namedImportSpec = spec;
       state.namedImportNode = node;
     }
@@ -71,6 +98,24 @@ function trackPathImport(node, unsafeFn, state) {
   }
 }
 
+/**
+ * Is `name` re-exported by a bare `export { name }` in this file?
+ *
+ * Removing the import specifier then leaves the export naming nothing, and the
+ * result does not PARSE — `Export 'join' is not defined`. An autofix whose
+ * output cannot be parsed is the worst outcome available, so the specifier
+ * stays and the call sites are still rewritten. Whatever is left is a lint
+ * finding a human can read, not a broken file.
+ */
+function isReExported(sourceCode, name) {
+  return sourceCode.ast.body.some(
+    (node) =>
+      node.type === 'ExportNamedDeclaration' &&
+      !node.source &&
+      node.specifiers.some((spec) => spec.local?.name === name),
+  );
+}
+
 /**
  * Track safe module import from an import declaration.
  */
@@ -83,51 +128,183 @@ function trackSafeImport(node, state) {
   }
 }
 
+/**
+ * Is `name` resolvable from `node`'s scope outward — a parameter, a local, an
+ * import, or a configured global?
+ *
+ * Used only to decide whether a bare `join(...)` with no `node:path` import is
+ * OUR `join` or somebody else's. `import { join } from 'lodash'` binds the name
+ * and is not our business; an unbound `join` is a ReferenceError waiting to
+ * happen, and — see `classifyCall` — is exactly what a half-applied autofix
+ * leaves behind.
+ */
+function isIdentifierBound(sourceCode, node, name) {
+  for (let scope = sourceCode.getScope(node); scope; scope = scope.upper) {
+    if (scope.variables.some((variable) => variable.name === name)) {
+      return true;
+    }
+  }
+  return false;
+}
+
 /**
  * Check if a call expression is an unsafe path function call.
- * Returns { isUnsafe, isNamed } or null if not a match.
+ *
+ * Returns `{ isNamed }` — or `{ importOnly: true }` for a call that is already
+ * correct and merely missing its import — or null if not a match.
  */
-function classifyCall(node, unsafeFn, state) {
-  // Direct call from named import: join(...)
-  if (
-    node.callee.type === 'Identifier' &&
-    node.callee.name === unsafeFn &&
-    state.namedImportSpec
-  ) {
-    return { isNamed: true };
+function classifyCall(node, unsafeFn, state, sourceCode) {
+  const isMember = node.callee.type === 'MemberExpression' && node.callee.property.type === 'Identifier';
+
+  // Direct call: join(...)
+  if (node.callee.type === 'Identifier' && node.callee.name === unsafeFn) {
+    if (state.namedImportSpec) {
+      return { isNamed: true };
+    }
+    // REPAIR LEG. Keying detection on "did I see the import?" made this rule
+    // stop reporting the moment a fix removed the specifier, so a partial
+    // `--fix` reached a stable fixpoint over source that no longer compiles and
+    // exited clean.
+    //
+    // Gated on `safePath` already being bound, which is what makes it a repair
+    // rather than a second, sloppier detector. An unbound `join` is NOT reliably
+    // our `join`: ESLint scope analysis does not bind `declare global { function
+    // join() }`, and it cannot see an ambient global from a `globals.d.ts`, an
+    // `@types` package, or a bundler — `resolve` and `relative` are entirely
+    // plausible as those. Requiring `safePath` in scope narrows this to the
+    // half-migrated file it exists to finish, where the name really was ours.
+    if (state.safePathBoundInSource && !isIdentifierBound(sourceCode, node.callee, unsafeFn)) {
+      return { isNamed: false };
+    }
+    return null;
   }
-  // Member expression: path.join(...)
+
+  // Namespace call: path.join(...)
   if (
-    node.callee.type === 'MemberExpression' &&
+    isMember &&
     node.callee.object.type === 'Identifier' &&
     node.callee.object.name === state.defaultImportName &&
-    node.callee.property.type === 'Identifier' &&
     node.callee.property.name === unsafeFn
   ) {
     return { isNamed: false };
   }
+
+  // REPAIR LEG, the other half: `safePath.join(...)` with no `safePath` in
+  // scope. This is what a partially-applied fix leaves — and without it, that
+  // state is PERMANENT rather than transient.
+  //
+  // ESLint runs `fix()` for a problem BEFORE the `eslint-disable` filter
+  // discards it, so a suppressed report on the first call site consumes the
+  // once-per-file import edit and then throws it away. Every other call is
+  // rewritten to `safePath.join`, nothing imports `safePath`, and no report
+  // survives to carry the import on any later pass. Recognising the orphaned
+  // call is what closes that loop; it costs one extra pass, and only in a file
+  // that is already broken.
+  if (
+    isMember &&
+    node.callee.object.type === 'Identifier' &&
+    node.callee.object.name === SAFE_OBJECT &&
+    node.callee.property.name === unsafeFn &&
+    !isIdentifierBound(sourceCode, node.callee.object, SAFE_OBJECT)
+  ) {
+    return { importOnly: true };
+  }
+
   return null;
 }
 
 /**
  * Build auto-fix for an unsafe path function call.
+ *
+ * ## Why the import edits are emitted at most ONCE per file
+ *
+ * ESLint merges the fixes one `fix()` yields into a SINGLE range spanning
+ * `min..max`, and applies only non-overlapping ranges per pass. A fix that
+ * touches both the import and its own call site therefore spans everything in
+ * between — so N such reports produce N nested ranges, ESLint keeps the
+ * shortest and DISCARDS THE REST.
+ *
+ * That is not an edge case, it is every file with more than one call site. The
+ * import edit landed, the other calls did not, and (before `classifyCall` grew
+ * its bare-call leg) the next pass could no longer see them because the
+ * specifier it keyed on was gone. `--fix` reached a stable fixpoint over source
+ * that does not compile and exited clean. An adopter measured 146 files left
+ * with a dangling reference across one sweep — worst single file, 75 call sites.
+ *
+ * So: the shared edits belong to the first report, and every later report emits
+ * a fix LOCAL to its own callee. Nothing overlaps, and one pass fixes the file.
+ * `no-manual-path-normalize.cjs` carries the same guard for the same reason.
+ *
+ * Only the FIRST report's fix is self-sufficient, and that is load-bearing:
+ * applying a later one ALONE — an editor's "fix this problem", or an
+ * `eslint-disable` on the first call site — rewrites the call without adding
+ * the import. ESLint runs `fix()` before the disable filter, so a suppressed
+ * report consumes the once-per-file edit and then discards it.
+ *
+ * That state is recoverable rather than permanent ONLY because `classifyCall`
+ * has a repair leg for an orphaned `safePath.join(...)`. Without it the file
+ * stays broken through every subsequent `--fix`, because no report is left to
+ * carry the import — measured, not reasoned about. An earlier draft of this
+ * comment asserted the recovery came free from `hasSafePathImport` being seeded
+ * from scope; that was wrong, and an adversarial run produced the stable broken
+ * fixpoint to prove it.
+ *
+ * The shared edits still cannot be hoisted onto their own report: removing
+ * `join` from the import while a suppressed `join(...)` call survives is the
+ * same broken output reached a different way. `exemptFiles` opts a whole file
+ * out.
  */
-function buildFix(fixer, node, unsafeFn, isNamed, sourceCode, state) {
+function importSafePath(fixer, sourceCode, state) {
+  if (state.safeImportNode) {
+    const lastSpec = state.safeImportNode.specifiers.at(-1);
+    return fixer.insertTextAfter(lastSpec, `, ${SAFE_OBJECT}`);
+  }
+  const targetNode = state.namedImportNode || sourceCode.ast.body[0];
+  const declaration = `import { ${SAFE_OBJECT} } from '${state.safeModule}';`;
+  // Land the new import next to the imports, not after arbitrary code. A file
+  // reported only through a repair leg may have no path import at all, and
+  // `insertTextAfter(body[0])` would push the declaration below the statement
+  // that needs it — legal, since imports hoist, but it reads as though the
+  // fixer lost track of the file.
+  return targetNode.type === 'ImportDeclaration'
+    ? fixer.insertTextAfter(targetNode, `\n${declaration}`)
+    : insertAboveWithComments(fixer, sourceCode, targetNode, `${declaration}\n`);
+}
+
+function buildFix(fixer, node, unsafeFn, classification, sourceCode, state) {
+  // REPAIR: an orphaned `safePath.join(...)` is already the call we want, and
+  // the only thing missing is the import that a discarded report was carrying.
+  //
+  // This deliberately ignores `state.hasSafePathImport`. That flag is mutated
+  // inside `fix()`, and ESLint runs `fix()` for a SUPPRESSED problem before the
+  // disable filter throws it away — so on every pass the suppressed report
+  // spends the flag first and the repair emits nothing. The file then never
+  // recovers, which is precisely the stable broken fixpoint this leg exists to
+  // break. The gate that makes ignoring the flag safe is immutable: this
+  // classification is only reached when `safePath` is unbound in the SOURCE.
+  //
+  // Several orphaned calls yield the identical insert at the identical anchor,
+  // so ESLint applies one and drops the rest as overlapping — which is the
+  // desired outcome, not a hazard.
+  if (classification.importOnly) {
+    return [importSafePath(fixer, sourceCode, state)];
+  }
+
   const fixes = [fixer.replaceText(node.callee, `${SAFE_OBJECT}.${unsafeFn}`)];
 
   if (!state.hasSafePathImport) {
-    if (state.safeImportNode) {
-      const lastSpec = state.safeImportNode.specifiers.at(-1);
-      fixes.push(fixer.insertTextAfter(lastSpec, `, ${SAFE_OBJECT}`));
-    } else {
-      const targetNode = state.namedImportNode || sourceCode.ast.body[0];
-      fixes.push(fixer.insertTextAfter(targetNode, `\nimport { ${SAFE_OBJECT} } from '${state.safeModule}';`));
-    }
+    fixes.push(importSafePath(fixer, sourceCode, state));
     state.hasSafePathImport = true;
   }
 
-  if (isNamed && state.namedImportNode) {
+  if (
+    classification.isNamed &&
+    state.namedImportNode &&
+    !state.namedImportRemoved &&
+    !isReExported(sourceCode, unsafeFn)
+  ) {
     fixes.push(...removeSpecifier(fixer, sourceCode, state.namedImportNode, state.namedImportSpec));
+    state.namedImportRemoved = true;
   }
 
   return fixes;
@@ -148,6 +325,7 @@ module.exports = function createPathFunctionRule(config) {
       schema: [EXEMPT_AND_SAFE_MODULE_SCHEMA],
       messages: {
         noUnsafePathFn: message,
+        [DEAD_UNSAFE_IMPORT]: DEAD_UNSAFE_IMPORT_MESSAGE,
         [UNANCHORED_EXEMPT_FILE]: UNANCHORED_EXEMPT_MESSAGE,
       },
     },
@@ -170,12 +348,25 @@ module.exports = function createPathFunctionRule(config) {
         safeModule: resolveSafeModule(context, SAFE_PATH_MODULE),
         namedImportSpec: null,
         namedImportNode: null,
+        // Both of these guard a SHARED edit against being emitted by more than
+        // one report — see `buildFix` for what ESLint does with the overlap.
+        namedImportRemoved: false,
         defaultImportName: null,
         // Seeded from SCOPE, not from "did I see an import from SAFE_MODULE?".
         // A file already importing `safePath` from the barrel needs the call
         // rewritten but must NOT gain a second binding of the same name.
         hasSafePathImport: isNameAlreadyBound(sourceCode, SAFE_OBJECT),
+        // The SAME question, answered once and never mutated. `hasSafePathImport`
+        // flips to true the moment a fix inserts the import, and gating the
+        // repair leg on a flag that the first report can flip would arm it for
+        // the rest of THIS pass — re-admitting the ambient-global false positive
+        // in any file that also has a `path.join()` to fix.
+        safePathBoundInSource: isNameAlreadyBound(sourceCode, SAFE_OBJECT),
         safeImportNode: null,
+        // EVERY path-module declaration, not just the one carrying `unsafeFn`.
+        // A file's dead binding is `import path from 'node:path'`, which
+        // `trackPathImport` only ever recorded as a NAME. See `dead-import.cjs`.
+        pathImportNodes: [],
       };
 
       return {
@@ -183,8 +374,18 @@ module.exports = function createPathFunctionRule(config) {
           reportUnanchoredExemptEntries(context, node);
         },
 
+        'Program:exit'() {
+          reportDeadUnsafeImports(
+            context,
+            sourceCode,
+            state.pathImportNodes,
+            state.safePathBoundInSource,
+          );
+        },
+
         ImportDeclaration(node) {
           if (PATH_MODULES.has(node.source.value)) {
+            state.pathImportNodes.push(node);
             trackPathImport(node, unsafeFn, state);
           }
           if (node.source.value === state.safeModule) {
@@ -193,7 +394,7 @@ module.exports = function createPathFunctionRule(config) {
         },
 
         CallExpression(node) {
-          const classification = classifyCall(node, unsafeFn, state);
+          const classification = classifyCall(node, unsafeFn, state, sourceCode);
           if (!classification) {
             return;
           }
@@ -206,7 +407,7 @@ module.exports = function createPathFunctionRule(config) {
             // drift from where the fixer actually writes the import.
             data: { safeModule: state.safeModule },
             fix(fixer) {
-              return buildFix(fixer, node, unsafeFn, classification.isNamed, sourceCode, state);
+              return buildFix(fixer, node, unsafeFn, classification, sourceCode, state);
             },
           });
         },

package/eslint/rules/prefer-startswith-over-regex.cjs

@@ -1,9 +1,9 @@
 /**
  * ESLint rule: prefer-startswith-over-regex
  *
- * Catches `/^literal/.test(s)` and `/literal$/.test(s)` patterns where the
- * literal portion contains only plain characters and `\/` escape sequences,
- * and recommends `s.startsWith('literal')` / `s.endsWith('literal')`.
+ * Catches `/^literal/.test(s)` and `/literal$/.test(s)` patterns whose body
+ * flattens to a plain string, and recommends `s.startsWith('literal')` /
+ * `s.endsWith('literal')`.
  *
  * Why a local rule?
  * `unicorn/prefer-string-starts-ends-with` already handles the simple case
@@ -11,11 +11,32 @@
  * common `\/` (escaped slash) sequence. SonarCloud's S6557 catches these,
  * but only post-merge. This rule shifts that detection left into ESLint.
  *
+ * ## Two shapes this rule deliberately does NOT limit itself to
+ *
+ * Both were narrowings in the first draft, and an adopter found each of them
+ * the same way: SonarCloud raised a MAJOR S6557 on code this rule had reported
+ * green.
+ *
+ * 1. **The regex need not be inline.** `const RE = /^x/; RE.test(s)` is the
+ *    same violation as `/^x/.test(s)` — see {@link resolveRegex}.
+ * 2. **An escaped non-special character is a literal character.** `\*` is an
+ *    unambiguous `*`; refusing every escape but `\/` skipped it — see
+ *    {@link literalEquivalent}.
+ *
+ * Neither could have been caught by scanning an adopter's tree. The rule runs
+ * at `error` there, so its finding count is zero BY CONSTRUCTION — lint cannot
+ * go green while a violation exists. A 0-vs-0 tie against another
+ * implementation is not agreement, it is two rules both failing to fire. For
+ * any rule an adopter reports zero findings for, that rule is *unmeasured*.
+ *
  * Examples:
  *   /^file:\/\//.test(s)   →  s.startsWith('file://')
+ *   /^\*glob/.test(s)      →  s.startsWith('*glob')
+ *   const R = /^a/; R.test(s) →  s.startsWith('a')
  *   /^https?:\/\//.test(s) →  NOT flagged (contains `?` quantifier)
  *   /^[a-z]+/.test(s)      →  NOT flagged (contains `[` character class)
- *   /\.txt$/.test(s)       →  NOT flagged (contains `.` metachar)
+ *   /\.txt$/.test(s)       →  NOT flagged (`.` is a metachar; `\.` would flag)
+ *   /^\d+/.test(s)         →  NOT flagged (`\d` is a character class)
  */
 
 'use strict';
@@ -23,24 +44,126 @@
 const METACHARS = new Set(['^', '$', '+', '[', '{', '(', '.', '?', '*', '|']);
 
 /**
- * Treat `\/` as a single literal `/` and check the remainder for any
- * regex metacharacter or other backslash-escape we don't understand.
- * Returns the literal string if safely convertible, otherwise null.
+ * Escape sequences whose meaning is NOT "the character that follows the
+ * backslash": character classes (`\d`, `\w`, `\s`, `\p`), assertions (`\b`),
+ * numeric escapes and backreferences (`\0`–`\9`, `\k`), and the code-point
+ * forms (`\x`, `\u`, `\c`). `\n`, `\r`, `\t`, `\v`, `\f` ARE single literal
+ * characters, but flattening them would put a raw control character into the
+ * suggested `startsWith('…')` string, so they are rejected too.
+ *
+ * Every other escape — `\/`, `\.`, `\*`, `\+`, `\(`, `\\`, `\-` … — is an
+ * identity escape, and the character it protects is exactly what a
+ * `startsWith` comparison would look for.
+ */
+const MEANINGFUL_ESCAPE = /[0-9BDPSWbcdfknprstuvwx]/;
+
+/**
+ * Flatten a regex body to the plain string it is equivalent to.
+ *
+ * Returns the literal string if safely convertible, otherwise null. Scans
+ * character by character rather than doing a `replaceAll` of the one escape we
+ * happen to like: `\/` was accepted and `\*` was not, though both denote a
+ * single literal character and neither is a metacharacter once escaped.
  */
 function literalEquivalent(patternBody) {
-  // Step 1: collapse `\/` (the only escape we accept) into a literal `/`.
-  const flattened = patternBody.replaceAll(String.raw`\/`, '/');
-  // Step 2: any remaining `\` is an escape we don't understand (\d, \w, \\, etc.).
-  if (flattened.includes('\\')) {
-    return null;
-  }
-  // Step 3: reject any regex metacharacter we'd be silently flattening.
-  for (const ch of flattened) {
-    if (METACHARS.has(ch)) {
+  let literal = '';
+
+  for (let index = 0; index < patternBody.length; index += 1) {
+    const char = patternBody[index];
+
+    if (char === '\\') {
+      const escaped = patternBody[index + 1];
+      // A trailing lone backslash is not a valid pattern; refuse to guess.
+      if (escaped === undefined || MEANINGFUL_ESCAPE.test(escaped)) {
+        return null;
+      }
+      literal += escaped;
+      index += 1;
+      continue;
+    }
+
+    // Unescaped metacharacter: flattening it would change what matches.
+    if (METACHARS.has(char)) {
       return null;
     }
+    literal += char;
+  }
+
+  return literal;
+}
+
+/**
+ * Find the variable `identifier` resolves to, searching outward from its scope.
+ */
+function findVariable(sourceCode, identifier) {
+  for (let scope = sourceCode.getScope(identifier); scope; scope = scope.upper) {
+    const found = scope.variables.find((variable) => variable.name === identifier.name);
+    if (found) {
+      return found;
+    }
+  }
+  return null;
+}
+
+/**
+ * The regex `node` denotes: itself when it is a regex literal, or the literal
+ * a single-assignment variable was initialised with.
+ *
+ * The indirection matters because hoisting a regex to a module-level `const` is
+ * the normal way to write one — and examining only inline literals meant the
+ * rule went quiet on exactly the code most likely to run hot.
+ *
+ * Conservative on purpose: one definition, one write, and that write is a regex
+ * literal. A binding assigned more than once could hold anything by the time
+ * `.test()` runs, and nothing here proves which value that is.
+ *
+ * `indirect` is what lets the caller treat a hoisted regex differently from an
+ * inline one — see the `g`/`y` guard, which only a shared object can trip.
+ *
+ * @returns {{pattern: string, flags: string, indirect: boolean} | null}
+ */
+function resolveRegex(sourceCode, node) {
+  if (node.type === 'Literal' && node.regex) {
+    return { ...node.regex, indirect: false };
+  }
+  if (node.type !== 'Identifier') {
+    return null;
+  }
+
+  const variable = findVariable(sourceCode, node);
+  if (variable?.defs.length !== 1) {
+    return null;
+  }
+  const [definition] = variable.defs;
+  if (definition.type !== 'Variable' || !definition.node.init) {
+    return null;
   }
-  return flattened;
+  if (variable.references.filter((reference) => reference.isWrite()).length !== 1) {
+    return null;
+  }
+
+  const { init } = definition.node;
+  return init.type === 'Literal' && init.regex ? { ...init.regex, indirect: true } : null;
+}
+
+/**
+ * Render the flattened literal as JS SOURCE, not as a bare character run.
+ *
+ * The literal is a string of characters; the message drops it into
+ * `startsWith(…)`, which a human reads as source. Those are different
+ * languages, and interpolating one into the other loses exactly the characters
+ * that matter. `/^C:\\Users/` flattens to `C:\Users` — one backslash — and
+ * emitting it raw produced the advice `startsWith('C:\Users')`, which JavaScript
+ * reads back as `"C:Users"`. Worse in the realistic case: a `/^\\\\/` UNC check
+ * became `startsWith('\\')`, i.e. ONE backslash, silently true for any
+ * single-backslash path. A literal containing `'` produced advice that is a
+ * `SyntaxError` outright.
+ *
+ * This rule has no fixer, so the message IS the deliverable — there is no
+ * autofixer downstream that would have escaped it correctly.
+ */
+function asSourceLiteral(literal) {
+  return JSON.stringify(literal);
 }
 
 module.exports = {
@@ -48,21 +171,26 @@ module.exports = {
     type: 'problem',
     docs: {
       description:
-        String.raw`Prefer String#startsWith / String#endsWith over /^literal/.test() — even when the literal includes \/ escape sequences`,
+        String.raw`Prefer String#startsWith / String#endsWith over /^literal/.test() — including escaped literals such as \/ and \*, and regexes held in a const`,
       recommended: true,
     },
     messages: {
+      // `{{pattern}}` carries its FLAGS. Rendering `/^abc/` for a source
+      // `/^abc/g` hid the one character that decides whether the advice is
+      // right, from the one person positioned to notice.
       preferStartsWith:
-        "Prefer `<string>.startsWith('{{literal}}')` over `/{{pattern}}/.test(<string>)`. " +
-        String.raw`Treat \/ as the literal / character.`,
+        'Prefer `<string>.startsWith({{literal}})` over `/{{pattern}}/{{flags}}.test(<string>)`. ' +
+        String.raw`An escaped character such as \/ or \* is the literal character itself.`,
       preferEndsWith:
-        "Prefer `<string>.endsWith('{{literal}}')` over `/{{pattern}}/.test(<string>)`. " +
-        String.raw`Treat \/ as the literal / character.`,
+        'Prefer `<string>.endsWith({{literal}})` over `/{{pattern}}/{{flags}}.test(<string>)`. ' +
+        String.raw`An escaped character such as \/ or \* is the literal character itself.`,
     },
     schema: [],
   },
 
   create(context) {
+    const sourceCode = context.getSourceCode();
+
     return {
       CallExpression(node) {
         if (
@@ -72,37 +200,55 @@ module.exports = {
         ) {
           return;
         }
-        const obj = node.callee.object;
-        if (obj.type !== 'Literal' || !obj.regex) {
+        // `startsWith` needs a string receiver where `.test()` would have
+        // coerced one. Arity is the only part of that this rule can check
+        // without types — a zero-argument `.test()` coerces `undefined` to
+        // "undefined" and is nobody's prefix check. A non-string ARGUMENT
+        // (`/^\[object/.test(v)`) remains a known limitation: `.test` coerces,
+        // `startsWith` throws, and only a type checker can tell them apart.
+        if (node.arguments.length !== 1) {
           return;
         }
-        const { pattern, flags } = obj.regex;
+
+        const regex = resolveRegex(sourceCode, node.callee.object);
+        if (!regex) {
+          return;
+        }
+        const { pattern, flags, indirect } = regex;
         if (flags.includes('i') || flags.includes('m')) {
           return;
         }
+        // `g` and `y` make `.test()` STATEFUL through `lastIndex`. A regex
+        // LITERAL is reconstructed on every evaluation, so its cursor is always
+        // 0 and the flags are inert; a hoisted `const` is one object that
+        // remembers. `const RE = /^abc/g` answers [true, false, true, false] to
+        // four calls on the same string where `startsWith` answers true four
+        // times — so resolving through a binding is precisely what makes this
+        // advice wrong, and precisely where it must not be given.
+        if (indirect && (flags.includes('g') || flags.includes('y'))) {
+          return;
+        }
+
+        const report = (messageId, literal) => {
+          context.report({
+            node,
+            messageId,
+            data: { literal: asSourceLiteral(literal), pattern, flags },
+          });
+        };
 
         if (pattern.startsWith('^')) {
-          const body = pattern.slice(1);
-          const literal = literalEquivalent(body);
+          const literal = literalEquivalent(pattern.slice(1));
           if (literal !== null && literal !== '') {
-            context.report({
-              node,
-              messageId: 'preferStartsWith',
-              data: { literal, pattern },
-            });
+            report('preferStartsWith', literal);
             return;
           }
         }
 
         if (pattern.endsWith('$') && !pattern.endsWith(String.raw`\$`)) {
-          const body = pattern.slice(0, -1);
-          const literal = literalEquivalent(body);
+          const literal = literalEquivalent(pattern.slice(0, -1));
           if (literal !== null && literal !== '') {
-            context.report({
-              node,
-              messageId: 'preferEndsWith',
-              data: { literal, pattern },
-            });
+            report('preferEndsWith', literal);
           }
         }
       },

package/eslint/rules/safe-import.cjs

@@ -68,6 +68,28 @@ function isNameAlreadyBound(sourceCode, name) {
   return scope.variables.some((variable) => variable.name === name);
 }
 
+/**
+ * Insert `text` above `node`, ABOVE its leading comments.
+ *
+ * `fixer.insertTextBefore(node)` uses the node's own start offset, which is
+ * after any comment attached to it — so inserting an import before the first
+ * statement dropped it BETWEEN an `eslint-disable-next-line` and the line that
+ * directive protects. The directive then applies to the inserted import, and
+ * the statement the developer had deliberately suppressed silently becomes
+ * fixable. A fixer that can revoke a suppression is a fixer that edits code
+ * nobody asked it to touch.
+ *
+ * @param {object} fixer - ESLint rule fixer.
+ * @param {object} sourceCode - ESLint `SourceCode` for the file being fixed.
+ * @param {object} node - The node to insert above.
+ * @param {string} text - Text to insert, including its own trailing newline.
+ */
+function insertAboveWithComments(fixer, sourceCode, node, text) {
+  const comments = sourceCode.getCommentsBefore(node);
+  const start = (comments[0] ?? node).range[0];
+  return fixer.insertTextBeforeRange([start, start], text);
+}
+
 /**
  * The `safeModule` rule option: point the fixer at YOUR re-export seam.
  *
@@ -135,6 +157,7 @@ module.exports = {
   SAFE_MODULE_ONLY_SCHEMA,
   SAFE_PATH_MODULE,
   SAFE_PROCESS_MODULE,
+  insertAboveWithComments,
   isNameAlreadyBound,
   resolveSafeModule,
   withSafeModuleOption,