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

package/dist/test-helpers.js.map

@@ -1 +1 @@
-{"version":3,"file":"test-helpers.js","sourceRoot":"","sources":["../src/test-helpers.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"test-helpers.js","sourceRoot":"","sources":["../src/test-helpers.ts"],"names":[],"mappings":"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"}

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 this rule migrated** — the safe symbol must be bound AND the rule's own replacement must actually be called in the file (`safePath.join(…)`, `normalizedTmpdir()`, `toForwardSlash(…)`). "The safe symbol is in scope" alone is not evidence: `safePath` arrives for reasons that have nothing to do with a call this pack consumed, and an import that was dead already — dead before the pack ever ran — was then deleted as though this fixer had orphaned it. 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,251 @@
+/**
+ * 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';
+// States what the rule can actually observe, and no more. The earlier wording —
+// "this rule's autofix rewrote the last call that referenced it" — asserted a
+// CAUSE, and the leg cannot see causes: by the time a binding reads as dead the
+// rewrite that killed it is a pass in the past and left no trace naming which
+// import it drew on. On a file with two imports of the same module, one of them
+// dead since before the pack ever ran, that sentence was simply false about one
+// of the two. See `reportDeadUnsafeImports` for what the gate does prove.
+const DEAD_UNSAFE_IMPORT_MESSAGE =
+  "'{{local}}' has no remaining references, and this file already calls the safe " +
+  "replacement this rule's autofix writes. 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.
+ *
+ * ## The two-part gate, and the evidence it cannot get
+ *
+ * Both gates keep this a REPAIR leg rather than a general unused-import rule,
+ * and both must be read from the SOURCE, 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.
+ *
+ * - `safeBoundInSource` — the safe symbol is in scope at all.
+ * - `replacementCalled` — THIS rule's own replacement is actually CALLED in this
+ *   file (`safePath.join(…)`, `normalizedTmpdir()`, `toForwardSlash(…)`), which
+ *   is the text its fixer writes and nothing else does.
+ *
+ * The first alone was the whole gate once, and it let an unrelated coincidence
+ * arm the leg: `safePath` reaches scope for reasons that have nothing to do with
+ * a call this pack consumed, and any `node:path` import that happened to be dead
+ * already — dead before the pack ever ran, for somebody else's reason — was then
+ * deleted under a message claiming this fixer had orphaned it. That is the
+ * general unused-import rule the module docstring above declines to be, reached
+ * by accident. The second gate closes it: no call to this rule's replacement
+ * means this rule rewrote nothing here, whatever else is in scope.
+ *
+ * It does NOT get down to the individual declaration, and it cannot. Per-import
+ * evidence has to name WHICH import a consumed reference belonged to, and the
+ * only pass that knows is the one doing the rewrite — where every reference is
+ * still live and nothing is dead to report. Removing speculatively in that pass
+ * instead is the trap the rest of this pack is built around: a suppressed call
+ * report still runs its `fix()`, so the removal lands while the call it was
+ * paired with survives, and the file is left with a dangling reference (146 of
+ * them, measured, in the defect this file exists to prevent). Latching state
+ * across passes to carry the answer forward is the rejected `WeakMap` approach
+ * for the same reason, one layer worse. So a file holding two imports of one
+ * module, one of them dead all along, still gets both removed and one true
+ * message plus one that merely describes the file rather than the history. The
+ * message is worded to stay true of both; the residual is a redundant deletion,
+ * never a broken one.
+ *
+ * Being over-strict here is cheap by construction: a gate that declines leaves
+ * an unused import, which is a lint finding a human reads. Only firing wrongly
+ * costs anything, and only the CALL rewrite can break a file.
+ *
+ * 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} safeBoundInSource - Was the safe symbol already bound in the SOURCE?
+ * @param {boolean} replacementCalled - Does the SOURCE call this rule's own safe
+ *   replacement? Both are required, and both are the caller's to compute from
+ *   source — see the gate discussion above for why neither may be defaulted.
+ */
+function reportDeadUnsafeImports(
+  context,
+  sourceCode,
+  importNodes,
+  safeBoundInSource,
+  replacementCalled,
+) {
+  if (!safeBoundInSource || !replacementCalled) {
+    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,37 +202,100 @@ 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;
+      // The dead-import leg's OTHER gate: does this file actually call `safeFn`,
+      // the free function this fixer writes? "The safe symbol is in scope" alone
+      // let an unrelated coincidence arm the leg — see `dead-import.cjs`. Read
+      // from the source during traversal, never from a `fix()`.
+      let safeReplacementCalled = false;
       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,
+            safeReplacementCalled,
+          );
+        },
+
         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);
           }
         },
 
         CallExpression(node) {
+          if (node.callee.type === 'Identifier' && node.callee.name === safeFn) {
+            safeReplacementCalled = true;
+          }
+
           let isUnsafeCall = false;
 
           // Check for direct function call: unsafeFn()
@@ -176,10 +303,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 +336,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;