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

package/eslint/README.md

@@ -112,6 +112,8 @@ Two ways your target can be wrong, which surface differently: `ERR_MODULE_NOT_FO
 | `no-child-process-execSync` | `child_process.execSync()` | `safeExecSync()` | `/process` | ✓ | `error` |
 | `no-unix-shell-commands` | `tar`, `grep`, `rm`, `echo`, … spawned directly | Node APIs, or a portable script fixture | — | | `error` |
 
+The member-call rules here check the **receiver**, not just the method name, so `env.tmpdir()` on some unrelated object is not a finding — and the namespace they check for can be bound by a static `import * as os`, by `const os = require('node:os')`, or by `const os = await import('node:os')`. The fix replaces the whole callee (`os.tmpdir()` → `normalizedTmpdir()`), which is correct however the binding was made. Matching the method name alone was the earlier behaviour and it produced `os.normalizedTmpdir()` — a method that does not exist, compiles, and throws.
+
 ### URLs and dynamic imports
 
 | Rule | Bans | Use instead | Subpath | Fix | `recommended` |
@@ -124,7 +126,7 @@ Two ways your target can be wrong, which surface differently: `ERR_MODULE_NOT_FO
 
 | Rule | Bans | Use instead | Subpath | Fix | `recommended` |
 |---|---|---|---|---|---|
-| `prefer-startswith-over-regex` | `/^foo/.test(s)` | `s.startsWith('foo')` | — | | `error` |
+| `prefer-startswith-over-regex` | `/^foo/.test(s)`, `` /^\*glob/.test(s) ``, `const RE = /^foo/; RE.test(s)` | `s.startsWith('foo')` | — | | `error` |
 | `no-test-scoped-functions` | helper functions declared inside `describe`/`it` | module scope | — | | — |
 | `require-justified-skip` | unannotated `it.skip`/`it.todo`, tautological assertions, empty test bodies | a `SKIP(#123): reason` annotation, or a real assertion | — | | — |
 
@@ -176,6 +178,30 @@ Raise all three to `error` once the backlog is clear. That is what this repo doe
 
 The criterion for `warn` is **migration volume**, not how real the finding is — a rule whose findings we doubted would be out of `recommended` entirely, not demoted. Everything at `error` either prevents a bug or moves a static-analysis finding left of a merge.
 
+### Running `--fix` over a large backlog
+
+Every rule that rewrites a call *and* edits imports fixes **all** of a file's call sites in a single pass, and `packages/utils/test/eslint/rules.test.ts` holds each of them to that: it runs `--fix` to its fixpoint and then asks `no-undef` whether the result still binds every identifier.
+
+That test exists because the answer used to be no. ESLint merges the fixes one `fix()` yields into a **single range spanning `min..max`**, and applies only non-overlapping ranges per pass — so a fix touching both the import and its own call site spanned everything in between, N call sites produced N nested ranges, and ESLint kept one. The rule then went quiet, because the import specifier its detection keyed on was what had just been removed. `--fix` reached a stable fixpoint over source that no longer compiles and exited clean; you found out at `tsc`. An adopter measured **146 files left with a dangling reference** across one ~4,900-site sweep, worst single file 75 unrewritten calls.
+
+`eslint-disable` interacts with this in a way worth knowing about, because it is not obvious and it took an adversarial run to find. ESLint invokes a rule's `fix()` **before** the disable filter discards the problem, so a suppressed report still consumes any once-per-file edit its rule was holding. Where that edit is an import *insert*, the rules either re-emit it from every report or carry a repair leg that recognises the orphaned call and supplies the missing import on the next pass — so a disabled call site costs an extra pass, not a broken file. Where it is an import *removal*, the removal is latched and simply goes away with the discarded report, leaving an unused import for `no-unused-vars` to point at rather than a call with nothing behind it. `exemptFiles` remains the supported way to opt a whole file out.
+
+Two more things a fixer here will not do: delete a `type`-only, aliased, or re-exported specifier (removing a re-exported one produced output that did not parse), and insert an import *between* a leading `eslint-disable-next-line` and the statement it protects, which would silently revoke the suppression.
+
+#### The binding left behind
+
+`path.join(a, b)` becomes `safePath.join(a, b)`, and when that was the file's last `path.*` reference the `import path from 'node:path'` is left bound to nothing. That is not a dangling reference, so the `no-undef` fixpoint check above is blind to it — and the same adopter measured **536 errors surviving a converged `--fix` across 232 files** (289 `no-unused-vars`, 247 `sonarjs/unused-import`), every one of them this. In a repo gating at `--max-warnings=0`, `--fix` output that does not lint clean is not a finished migration.
+
+So the rules now report it themselves, as a separate `deadUnsafeImport` finding on the import line with its own fix. Being its own finding is the point: it shows up in lint output and you can `eslint-disable` it, rather than a call rewrite quietly taking a declaration with it.
+
+Deliberately narrow:
+
+- **A closed list of modules** — `node:path`, `node:os`, `node:fs`, `node:fs/promises`, `node:child_process` and their bare spellings. All Node builtins, all side-effect-free with certainty decided when the rule was written. This is *not* a general unused-import rule and will not become one; for blanket cleanup, `eslint-plugin-unused-imports` already exists and already autofixes.
+- **Only in a file these rules migrated** — the safe symbol must already be bound. A dead import in a file this pack never touched is somebody else's business.
+- **Only whole declarations, only with zero references left** — evaluated against the source as it stands on that pass, so the removal always lands *after* the rewrite that consumed the last reference, never speculatively beside it. A partially-dead declaration (`import path, { sep }` with `sep` still live) is left alone, as are bare `import 'node:path'` side-effect imports and anything carrying a `type` specifier.
+
+This cannot be delegated: `@typescript-eslint/no-unused-vars` declares `meta.fixable: 'code'` but emits only a **suggestion** for an unused import, and `--fix` never applies suggestions; `sonarjs/unused-import` declares no fixer at all. Verified with both enabled alongside these rules in one `verifyAndFix` — the import survived. Those rules abstain for a good reason, since removing an import can change behaviour; a rule that *created* the orphan knows it just consumed the last reference and knows the module, so it can act where a generic rule cannot.
+
 ## Why custom rules
 
 A cross-platform safety helper is only as good as its enforcement. `safePath.join()` prevents a class of Windows bug precisely once — the moment someone writes `path.join()` instead, the helper's existence has bought nothing. Publishing the API without the lint rule ships half a product: the fix is available, and nothing directs anyone to it.

package/eslint/rules/dead-import.cjs

@@ -0,0 +1,201 @@
+/**
+ * Removing the import binding THIS PACK's own fixers just orphaned.
+ *
+ * ## The gap this closes
+ *
+ * `path.join(a, b)` rewrites to `safePath.join(a, b)`, and when that was the
+ * file's last `path.*` reference the `import path from 'node:path'` is left
+ * bound to nothing. An adopter measured the consequence over ~5,100 sites:
+ * `--fix` converged, and **536 errors survived across 232 files** — 289
+ * `no-unused-vars` plus 247 `sonarjs/unused-import`, every one of them this same
+ * class. Their repo gates at `--max-warnings=0`, so the fixed output did not
+ * lint clean and the migration was not actually complete.
+ *
+ * The `no-undef` fixpoint check the rest of this pack leans on is structurally
+ * blind to it: a dead import leaves nothing DANGLING, it leaves something SPARE.
+ *
+ * ## Why this cannot be delegated to the ecosystem
+ *
+ * `@typescript-eslint/no-unused-vars` declares `meta.fixable: 'code'` — and for
+ * an unused import it emits only a SUGGESTION, which `--fix` never applies.
+ * `eslint-plugin-sonarjs/unused-import` declares no fixer at all. Measured on
+ * `@typescript-eslint/eslint-plugin@8.65.0`, with both rules enabled alongside
+ * ours in a single `verifyAndFix`: the import survived. `meta.fixable` is a
+ * capability flag about the RULE, not a promise about any given report.
+ *
+ * Those rules abstain for a real reason — removing an import can change
+ * behaviour (`import './polyfill'`, modules with top-level effects), and a
+ * generic rule cannot prove otherwise. A rule that CREATED the orphan is in a
+ * strictly better position: it knows it just consumed the binding's last
+ * reference, and it knows the module, because its own config named it.
+ *
+ * ## Why the module list is closed, and hardcoded
+ *
+ * Every entry is a Node builtin that this pack already targets, and every one is
+ * side-effect-free with certainty decided here, at authoring time. The only
+ * general signal available instead would be package.json `sideEffects` — author
+ * declared, unverified, absent by default (and absence means "assume side
+ * effects"), sometimes a glob array rather than a boolean, requiring filesystem
+ * resolution per import inside a linter expected to be pure and fast, and it
+ * **does not apply to `node:` builtins at all**, which is the only case here.
+ * So: no `sideEffects` lookup, no I/O, no new dependency, and deliberately NOT
+ * a general `unused-import-no-side-effects` rule. For blanket cleanup outside
+ * this list, `eslint-plugin-unused-imports` already exists and already autofixes.
+ *
+ * Bare aliases (`path`, `os`, …) are listed beside their `node:`-prefixed
+ * spellings because the rules themselves treat the two as one module. Detecting
+ * `path.join()` from `import path from 'path'` and then declining to clean up
+ * after it would leave exactly the adopter's blocker in place for whichever
+ * spelling a file happened to use.
+ */
+
+const REMOVABLE_MODULES = new Set([
+  'node:path',
+  'path',
+  'node:os',
+  'os',
+  'node:fs',
+  'fs',
+  'node:fs/promises',
+  'fs/promises',
+  'node:child_process',
+  'child_process',
+]);
+
+const DEAD_UNSAFE_IMPORT = 'deadUnsafeImport';
+const DEAD_UNSAFE_IMPORT_MESSAGE =
+  "'{{local}}' is no longer used — this rule's autofix rewrote the last call that " +
+  "referenced it. Remove the '{{module}}' import.";
+
+/**
+ * Does this declaration bring in anything the type checker alone can see?
+ *
+ * A `type` binding has zero references by construction — scope analysis does not
+ * record type positions as references — so "nothing uses it" is not evidence of
+ * anything. Deleting one silently breaks every `typeof join` and every
+ * annotation that named it, and NEITHER `no-undef` nor `no-unused-vars` can see
+ * the damage, because the reference it broke was a type reference. Round 2 of
+ * this work learned that by shipping the deletion first.
+ */
+function hasTypeOnlyBinding(node) {
+  return (
+    node.importKind === 'type' || node.specifiers.some((spec) => spec.importKind === 'type')
+  );
+}
+
+/**
+ * Is every binding this declaration introduces now unreferenced?
+ *
+ * Whole declarations only. A partially-dead declaration (`import path, { sep }`
+ * with `sep` still live) needs comma surgery, which is where removal bugs live,
+ * and it is not the shape the adopter measured — so it is left alone and stays a
+ * visible `no-unused-vars` finding rather than a risky edit.
+ *
+ * Re-exports need no special guard: `export { path }` and `export default path`
+ * both register as references under espree AND `@typescript-eslint/parser`
+ * (measured, both parsers), so such a declaration is never dead here. Round 2
+ * added an explicit `isReExported` check for the SPECIFIER-removal path, where
+ * the reference count is not consulted at all; this path reads the count, so a
+ * second check would be a guard that can never fire.
+ */
+function isDeadRemovableImport(sourceCode, node) {
+  if (!REMOVABLE_MODULES.has(node.source.value)) {
+    return false;
+  }
+  // A bare `import 'node:path';` declares no bindings, which would make "every
+  // binding is dead" vacuously true. Whether the module has side effects is
+  // beside the point — the author wrote a statement whose only possible purpose
+  // is its effect, and deleting it is an edit nobody asked for.
+  if (node.specifiers.length === 0 || hasTypeOnlyBinding(node)) {
+    return false;
+  }
+  // `every` over a non-empty list: the `specifiers.length === 0` bail above is
+  // what makes that safe, and it is the ONLY thing that does. A second
+  // `declared.length > 0` here would look like belt-and-braces and would in fact
+  // be a guard that can never fire — which mutation testing reports as an
+  // unguarded line, correctly, because deleting the real check leaves it green.
+  return sourceCode
+    .getDeclaredVariables(node)
+    .every((variable) => variable.references.length === 0);
+}
+
+/**
+ * Report — and remove — every import declaration this pass emptied out.
+ *
+ * Runs at `Program:exit`, over the SOURCE as it stands this pass. That ordering
+ * is the safety property, not an implementation detail: while a live reference
+ * survives in the text being linted, the binding is not dead and nothing is
+ * reported. The removal therefore lands on a later pass, after the rewrite that
+ * consumed the last reference — never speculatively alongside it.
+ *
+ * `migrated` gates the whole leg on the safe symbol being bound in the file, and
+ * is what keeps this a REPAIR leg rather than a general unused-import rule. It
+ * must be read from the SOURCE and never from a flag a `fix()` can flip: ESLint
+ * runs `fix()` for a suppressed problem before the `eslint-disable` filter
+ * discards it, so any mutable "did I add the import?" flag is already spent and
+ * lying by the time this runs.
+ *
+ * Its own report, with its own `fix`, deliberately — so the deletion appears in
+ * lint output and can be suppressed at the import line, rather than a rewrite
+ * quietly taking a declaration with it.
+ *
+ * Several rules in this pack can reach the same dead declaration in the same
+ * pass (a file using only `path.join` and `path.resolve` finishes owing nothing
+ * to `path`). They emit identical removals over an identical range, so ESLint
+ * applies one and drops the rest as overlapping. Measured with the three
+ * `safePath` rules enabled together over a file using all three: one
+ * `verifyAndFix`, output clean under `no-undef` and `no-unused-vars`, nothing
+ * left to report.
+ *
+ * In a check-only run that same file yields N identical messages, one per
+ * enabled rule. **Do not "fix" that by latching across rules.** These rule
+ * instances do share a module scope here, so a `WeakMap` keyed on `SourceCode`
+ * would dedupe them — and would reintroduce the exact trap round 2 was spent
+ * escaping. ESLint runs `fix()` for a suppressed problem BEFORE the
+ * `eslint-disable` filter discards it, so an `eslint-disable-next-line` naming
+ * whichever rule happened to win the latch would consume the file's only
+ * removal and then throw it away, leaving the import permanently undeletable and
+ * unreported. Duplicate messages on a file that is about to be fixed are the
+ * cheap failure; a silently stranded file is not.
+ *
+ * @param {object} context - ESLint rule context.
+ * @param {object} sourceCode - ESLint `SourceCode` for the file being linted.
+ * @param {object[]} importNodes - Unsafe-module `ImportDeclaration`s seen this pass.
+ * @param {boolean} migrated - Was the safe symbol already bound in the SOURCE?
+ */
+function reportDeadUnsafeImports(context, sourceCode, importNodes, migrated) {
+  if (!migrated) {
+    return;
+  }
+  for (const node of importNodes) {
+    if (!isDeadRemovableImport(sourceCode, node)) {
+      continue;
+    }
+    context.report({
+      node,
+      messageId: DEAD_UNSAFE_IMPORT,
+      data: {
+        local: sourceCode
+          .getDeclaredVariables(node)
+          .map((variable) => variable.name)
+          .join("', '"),
+        module: node.source.value,
+      },
+      // `fixer.remove(node)` takes the declaration and leaves its newline, so a
+      // blank line remains where the import was. That is exactly what the
+      // specifier-removal leg in `path-function-rule-factory.cjs` has always
+      // done — its fixtures pin the leading `\n` — and matching it keeps one
+      // behaviour rather than two. Extending the range through a trailing
+      // whitespace-only remainder would tidy both, and should be done to both at
+      // once, once an adopter has measured whether their formatter cares.
+      fix: (fixer) => fixer.remove(node),
+    });
+  }
+}
+
+module.exports = {
+  DEAD_UNSAFE_IMPORT,
+  DEAD_UNSAFE_IMPORT_MESSAGE,
+  REMOVABLE_MODULES,
+  reportDeadUnsafeImports,
+};

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

@@ -35,6 +35,11 @@
  * // '@vibe-agent-toolkit/no-os-tmpdir': ['error', { exemptFiles: ['src/paths.ts'] }]
  */
 
+const {
+  DEAD_UNSAFE_IMPORT,
+  DEAD_UNSAFE_IMPORT_MESSAGE,
+  reportDeadUnsafeImports,
+} = require('./dead-import.cjs');
 const {
   UNANCHORED_EXEMPT_FILE,
   UNANCHORED_EXEMPT_MESSAGE,
@@ -43,10 +48,68 @@ const {
 } = require('./exempt-path-matcher.cjs');
 const {
   EXEMPT_AND_SAFE_MODULE_SCHEMA,
+  insertAboveWithComments,
   isNameAlreadyBound,
   resolveSafeModule,
 } = require('./safe-import.cjs');
 
+/** Does this declaration bring in `name` as a named specifier? */
+function importsName(importNode, name) {
+  return importNode.specifiers.some(
+    (spec) => spec.type === 'ImportSpecifier' && spec.imported.name === name,
+  );
+}
+
+/**
+ * The local name of `import os from 'node:os'` / `import * as os from 'node:os'`.
+ *
+ * Without it the member-expression check has no receiver to compare against,
+ * and matching on the property name alone turns every `env.tmpdir()` into an
+ * `os.tmpdir()` finding.
+ */
+function namespaceLocalName(importNode) {
+  const spec = importNode.specifiers.find(
+    (candidate) =>
+      candidate.type === 'ImportDefaultSpecifier' || candidate.type === 'ImportNamespaceSpecifier',
+  );
+  return spec ? spec.local.name : null;
+}
+
+/**
+ * The module specifier of `require('x')`, `import('x')` or `await import('x')`.
+ *
+ * A static `import * as os` is not the only way to end up holding the `node:os`
+ * namespace, and the fix does not care which way it happened — the whole callee
+ * is replaced by a free function, so `os.tmpdir()` becomes `normalizedTmpdir()`
+ * whatever bound `os`.
+ *
+ * This is NOT a return to rc.1, which matched any receiver at all and so
+ * "detected" these shapes only as a side effect of the defect that also produced
+ * `os.normalizedTmpdir()`. The receiver check stays; this widens what counts as
+ * evidence that the receiver IS the module's namespace, and nothing else.
+ *
+ * @param {object} [init] - The initialiser of a variable declarator.
+ * @returns {string|null} The literal module name, or null.
+ */
+function namespaceModuleOf(init) {
+  const expr = init?.type === 'AwaitExpression' ? init.argument : init;
+  if (!expr) {
+    return null;
+  }
+  const isDynamicImport = expr.type === 'ImportExpression';
+  const isRequire =
+    expr.type === 'CallExpression' &&
+    expr.callee.type === 'Identifier' &&
+    expr.callee.name === 'require';
+  if (!isDynamicImport && !isRequire) {
+    return null;
+  }
+  // `ImportExpression.source` / the sole `require` argument. A computed
+  // specifier names no module we can check, so it binds nothing we may rewrite.
+  const source = isDynamicImport ? expr.source : expr.arguments[0];
+  return source?.type === 'Literal' && typeof source.value === 'string' ? source.value : null;
+}
+
 /**
  * Helper function to filter unsafe import specifiers
  * Extracted to reduce nesting depth for code quality
@@ -59,7 +122,7 @@ function filterUnsafeSpecifiers(importNode, unsafeFn) {
  * Helper function to remove unsafe import specifiers
  * Extracted to reduce nesting depth for code quality
  */
-function removeUnsafeImportSpecifiers(fixer, sourceCode, unsafeImportNode, unsafeSpecs) {
+function removeUnsafeImportSpecifiers(fixer, sourceCode, unsafeSpecs) {
   const fixes = [];
   for (const spec of unsafeSpecs) {
     const comma = sourceCode.getTokenAfter(spec);
@@ -110,6 +173,7 @@ module.exports = function createNoUnsafeRule(config) {
       schema: [EXEMPT_AND_SAFE_MODULE_SCHEMA],
       messages: {
         noUnsafeOperation: message,
+        [DEAD_UNSAFE_IMPORT]: DEAD_UNSAFE_IMPORT_MESSAGE,
         [UNANCHORED_EXEMPT_FILE]: UNANCHORED_EXEMPT_MESSAGE,
       },
     },
@@ -138,33 +202,81 @@ module.exports = function createNoUnsafeRule(config) {
       // rewritten but must NOT gain a second binding of the same name — that is
       // a SyntaxError, not a redundant import. See `safe-import.cjs`.
       let hasSafeImport = isNameAlreadyBound(sourceCode, safeFn);
+      // The SAME question, answered once and never mutated. `hasSafeImport`
+      // flips the moment a fix inserts the import, and the dead-import leg must
+      // not be armed by a flag a suppressed report can spend — ESLint runs
+      // `fix()` before the `eslint-disable` filter discards the problem.
+      const safeBoundInSource = hasSafeImport;
       let unsafeImportNode = null;
+      const unsafeImportNodes = [];
       let safeImportNode = null;
+      // A SET, because a namespace can be bound by a static import, a
+      // `require()`, or a dynamic `import()` — see `namespaceModuleOf`.
+      const unsafeNamespaceNames = new Set();
+      // Latches the REMOVAL only — never the insert. See `fix()` for why the
+      // two shared edits must be treated differently.
+      let unsafeImportRemoved = false;
 
       return {
         Program(node) {
           reportUnanchoredExemptEntries(context, node);
         },
 
+        'Program:exit'() {
+          reportDeadUnsafeImports(context, sourceCode, unsafeImportNodes, safeBoundInSource);
+        },
+
         ImportDeclaration(node) {
-          // Track unsafe module imports
           if (moduleVariants.includes(node.source.value)) {
             unsafeImportNode = node;
-            for (const spec of node.specifiers) {
-              if (spec.type === 'ImportSpecifier' && spec.imported.name === unsafeFn) {
-                hasUnsafeImport = true;
-              }
+            unsafeImportNodes.push(node);
+            hasUnsafeImport = hasUnsafeImport || importsName(node, unsafeFn);
+            const local = namespaceLocalName(node);
+            if (local) {
+              unsafeNamespaceNames.add(local);
             }
           }
-
-          // Track safe module imports
           if (node.source.value === targetModule) {
             safeImportNode = node;
-            for (const spec of node.specifiers) {
-              if (spec.type === 'ImportSpecifier' && spec.imported.name === safeFn) {
-                hasSafeImport = true;
-              }
-            }
+            hasSafeImport = hasSafeImport || importsName(node, safeFn);
+          }
+        },
+
+        // `const os = require('node:os')` / `const os = await import('node:os')`.
+        //
+        // Recorded by NAME, matching how the static-import receiver has always
+        // been tracked, so a declaration must precede its use — which is the
+        // normal shape and the only one either form appears in. Resolving the
+        // receiver through scope instead would also reject a shadowing rebind,
+        // but it would change detection parity on a population an adopter has
+        // already measured across 4,963 files, so it is not worth trading here.
+        //
+        // KNOWN RESIDUAL, measured: `dead-import.cjs` only removes an
+        // `ImportDeclaration`, so after the rewrite `const os = require('node:os')`
+        // and `const os = await import('node:os')` are both left behind as
+        // `'os' is assigned a value but never used` (the dynamic form also draws
+        // `sonarjs/no-dead-store`). Removing a VariableDeclaration is a wider edit
+        // than removing an import (multiple declarators, destructuring, an `await`
+        // inside control flow), so it is deliberately not done here. A static
+        // `import * as os` — the shape that actually appears at scale — is cleaned
+        // up. An adopter confirmed the residual 2-for-2 and measured **zero** files
+        // using either dynamic shape across 4,963 tracked sources, so the
+        // population this would serve is currently empty.
+        //
+        // If it is ever extended that far, note what makes the dynamic case
+        // different in kind: the leftover `await import('node:os')` STILL RUNS.
+        // The module is loaded and the promise awaited, and only the binding is
+        // dead — so deleting the statement removes an execution, not just a name.
+        // For these builtins that is unobservable, which is precisely why the
+        // module list is closed; the same edit against an arbitrary module would
+        // not be safe, and no `sideEffects` metadata could tell you so.
+        VariableDeclarator(node) {
+          if (node.id.type !== 'Identifier') {
+            return;
+          }
+          const source = namespaceModuleOf(node.init);
+          if (source !== null && moduleVariants.includes(source)) {
+            unsafeNamespaceNames.add(node.id.name);
           }
         },
 
@@ -176,10 +288,23 @@ module.exports = function createNoUnsafeRule(config) {
             isUnsafeCall = true;
           }
 
-          // Check for member expression: obj.unsafeFn()
+          // Check for member expression: os.tmpdir()
+          //
+          // The RECEIVER must be the unsafe module's own namespace binding.
+          // Matching on the property name alone made `env.tmpdir()` — any
+          // object at all with a same-named method — an `os.tmpdir()` finding.
+          // That was survivable while the fixer rewrote only the property
+          // (`env.normalizedTmpdir()` fails to compile, so the false positive
+          // announced itself); once the whole callee is replaced it becomes
+          // `normalizedTmpdir()`, which compiles, type-checks, passes
+          // `no-undef`, and silently calls a different function with the
+          // receiver discarded. A false positive that produces WORKING code is
+          // strictly the more dangerous kind.
           if (
             checkMemberExpression &&
             node.callee.type === 'MemberExpression' &&
+            node.callee.object.type === 'Identifier' &&
+            unsafeNamespaceNames.has(node.callee.object.name) &&
             node.callee.property.name === unsafeFn
           ) {
             isUnsafeCall = true;
@@ -196,39 +321,83 @@ module.exports = function createNoUnsafeRule(config) {
             fix(fixer) {
               const fixes = [];
 
-              // Replace unsafe call with safe call
-              if (node.callee.type === 'MemberExpression') {
-                // For obj.method(), replace just the method name
-                fixes.push(fixer.replaceText(node.callee.property, safeFn));
-              } else {
-                // For method(), replace the whole callee
-                fixes.push(fixer.replaceText(node.callee, safeFn));
-              }
+              // Replace the WHOLE callee, member expression or not.
+              //
+              // Rewriting only the property turned `os.tmpdir()` into
+              // `os.normalizedTmpdir()` — a method that does not exist on the
+              // `node:os` namespace. The replacement is a free function from
+              // OUR package, and the fixer imported it correctly; it just left
+              // the call reaching for it through the wrong object. Silent, like
+              // the overlap bug below: lint went green (the rule no longer sees
+              // `tmpdir`), and it is a dangling MEMBER rather than a dangling
+              // identifier, so `no-undef` cannot see it either. `tsc` can.
+              fixes.push(fixer.replaceText(node.callee, safeFn));
 
-              // Add import if needed
+              // Add import if needed — on EVERY report, deliberately.
+              //
+              // The sister factory emits this once per file, because there a
+              // report that edits both the import and its own call site spans
+              // everything between them, N reports leave N nested ranges, and
+              // ESLint keeps one: the defect measured at 146 broken files.
+              //
+              // That guard does not belong here, and briefly having it was a
+              // mistake worth recording. These rules do NOT key detection on
+              // the import — `node.callee.name === unsafeFn` is true whether or
+              // not the specifier survives — and `hasSafeImport` is reseeded
+              // from scope each pass, so pass 2 always finished the job anyway.
+              // An adversarial run confirmed the guard changed no output at 4,
+              // 40 or 75 call sites. What it DID change was the failure mode:
+              // ESLint runs `fix()` for a suppressed problem before the
+              // `eslint-disable` filter discards it, so one disable comment on
+              // the first call site spent the once-per-file edit and stranded
+              // the file with calls the import no longer backs.
+              //
+              // Every report carrying its own import edit costs a pass and buys
+              // a fix that is correct on its own — including when applied alone
+              // from an editor's "fix this problem".
               if (!hasSafeImport) {
                 if (safeImportNode) {
                   // Add to existing safe module import
                   const lastSpecifier = safeImportNode.specifiers.at(-1);
                   fixes.push(fixer.insertTextAfter(lastSpecifier, `, ${safeFn}`));
                 } else {
-                  // Create new import after unsafe import or at the top
+                  // Land next to the imports, never after arbitrary code —
+                  // `insertTextAfter(body[0])` on a file whose first statement
+                  // is a `const` welds the declaration onto the end of it.
                   const targetNode = unsafeImportNode || sourceCode.ast.body[0];
-                  const newImport = `import { ${safeFn} } from '${targetModule}';\n`;
-                  fixes.push(fixer.insertTextAfter(targetNode, newImport));
+                  const declaration = `import { ${safeFn} } from '${targetModule}';`;
+                  fixes.push(
+                    targetNode.type === 'ImportDeclaration'
+                      ? fixer.insertTextAfter(targetNode, `\n${declaration}`)
+                      : insertAboveWithComments(fixer, sourceCode, targetNode, `${declaration}\n`),
+                  );
                 }
               }
 
-              // Remove unsafe import if it's the only specifier
-              if (hasUnsafeImport && unsafeImportNode) {
+              // Remove the unsafe import — LATCHED, unlike the insert above.
+              //
+              // The asymmetry is the whole design. An insert is safe to repeat
+              // (identical text, identical anchor, ESLint drops the duplicate)
+              // and repeating it is what keeps each report's fix correct on its
+              // own. A REMOVAL is not: if every report removes the specifier,
+              // one of those removals lands even when the report that would
+              // have rewritten the matching call was suppressed — and the
+              // suppressed call is left calling an identifier the import no
+              // longer provides. Measured: `tmpdir` undefined, permanently.
+              //
+              // Latched, the discarded first report simply takes the removal
+              // with it, and the worst case is an unused import that
+              // `no-unused-vars` will point at. A lint finding, not a crash.
+              if (hasUnsafeImport && unsafeImportNode && !unsafeImportRemoved) {
                 const unsafeSpecs = filterUnsafeSpecifiers(unsafeImportNode, unsafeFn);
                 if (unsafeImportNode.specifiers.length === 1 && unsafeSpecs.length === 1) {
                   // Remove entire import
                   fixes.push(fixer.remove(unsafeImportNode));
                 } else if (unsafeSpecs.length > 0) {
                   // Remove just the unsafe specifier
-                  fixes.push(...removeUnsafeImportSpecifiers(fixer, sourceCode, unsafeImportNode, unsafeSpecs));
+                  fixes.push(...removeUnsafeImportSpecifiers(fixer, sourceCode, unsafeSpecs));
                 }
+                unsafeImportRemoved = true;
               }
 
               return fixes;

package/eslint/rules/no-manual-path-normalize.cjs

@@ -13,14 +13,21 @@
  * const normalized = toForwardSlash(relativePath);
  */
 
+const {
+  DEAD_UNSAFE_IMPORT,
+  DEAD_UNSAFE_IMPORT_MESSAGE,
+  reportDeadUnsafeImports,
+} = require('./dead-import.cjs');
 const {
   SAFE_MODULE_ONLY_SCHEMA,
   SAFE_PATH_MODULE,
+  insertAboveWithComments,
   isNameAlreadyBound,
   resolveSafeModule,
 } = require('./safe-import.cjs');
 
 const SAFE_FN = 'toForwardSlash';
+const PATH_MODULES = new Set(['node:path', 'path']);
 
 module.exports = {
   meta: {
@@ -35,6 +42,7 @@ module.exports = {
       useToForwardSlash:
         'Use toForwardSlash() from {{safeModule}} instead of manual path normalization. ' +
         'Manual normalization is error-prone and less maintainable.',
+      [DEAD_UNSAFE_IMPORT]: DEAD_UNSAFE_IMPORT_MESSAGE,
     },
     schema: [SAFE_MODULE_ONLY_SCHEMA],
   },
@@ -46,10 +54,24 @@ module.exports = {
     // barrel must have the call rewritten WITHOUT gaining a second binding of
     // the same name — that is a SyntaxError. See `safe-import.cjs`.
     let hasToForwardSlashImport = isNameAlreadyBound(sourceCode, SAFE_FN);
+    // Never mutated — the dead-import leg must not be armed by a flag that a
+    // suppressed report's `fix()` can spend. See `dead-import.cjs`.
+    const safeBoundInSource = hasToForwardSlashImport;
     let utilsImportNode = null;
+    // `path.sep` is the last `path.*` reference in plenty of files, and
+    // `toForwardSlash(raw)` consumes it — leaving the same dead `node:path`
+    // binding the `safePath` rules used to leave.
+    const pathImportNodes = [];
 
     return {
+      'Program:exit'() {
+        reportDeadUnsafeImports(context, sourceCode, pathImportNodes, safeBoundInSource);
+      },
+
       ImportDeclaration(node) {
+        if (PATH_MODULES.has(node.source.value)) {
+          pathImportNodes.push(node);
+        }
         if (node.source.value === targetModule) {
           utilsImportNode = node;
           for (const spec of node.specifiers) {
@@ -110,12 +132,21 @@ module.exports = {
                       // Create new import at the top
                       const firstNode = sourceCode.ast.body[0];
                       const newImport = `import { ${SAFE_FN} } from '${targetModule}';\n`;
-                      fixes.push(fixer.insertTextBefore(firstNode, newImport));
+                      fixes.push(insertAboveWithComments(fixer, sourceCode, firstNode, newImport));
                     }
-                    // Multiple reports in one pass share this closure; without
-                    // this, a second occurrence in the same file inserts the
-                    // import a second time.
-                    hasToForwardSlashImport = true;
+                    // NOT latched. The comment here used to claim that without a
+                    // `hasToForwardSlashImport = true` a second occurrence would
+                    // insert the import twice; an adversarial run could not
+                    // reproduce that at any occurrence count. It cannot happen:
+                    // both reports insert identical text at the identical anchor,
+                    // so the ranges coincide and ESLint applies one and drops the
+                    // other as overlapping.
+                    //
+                    // Latching it is not free, either. ESLint runs `fix()` for a
+                    // SUPPRESSED problem before the `eslint-disable` filter
+                    // discards it, so the first report could spend the flag and
+                    // then be thrown away — leaving later occurrences rewritten
+                    // to a `toForwardSlash` nothing imports.
                   }
 
                   return fixes;