@openrewrite/rewrite 8.91.0 → 8.91.2

package/src/javascript/add-import.ts

@@ -1,9 +1,13 @@
 import {JavaScriptVisitor} from "./visitor";
-import {emptySpace, J, rightPadded, singleSpace, space, Statement, Type} from "../java";
-import {JS} from "./tree";
+import {ElementRemovalFormatter, emptySpace, isIdentifier, J, rightPadded, singleSpace, space, Statement, Type} from "../java";
+import {JS, JSX} from "./tree";
 import {randomId} from "../uuid";
 import {emptyMarkers, markers} from "../markers";
-import {getStyle, SpacesStyle, StyleKind} from "./style";
+import {getStyle, PrettierStyle, SpacesStyle, StyleKind} from "./style";
+import {bindingNames, compilationUnitOf, cursorOf, declarationsOf, deconflict, namesDeclaredIn} from "./scope";
+import {create as produce, Draft} from "mutative";
+
+export type QuoteChar = "'" | '"';
 
 export enum ImportStyle {
     ES6Named,      // import { x } from 'module'
@@ -13,8 +17,10 @@ export enum ImportStyle {
 }
 
 export interface AddImportOptions {
-    /** The module name (e.g., 'fs', 'react') to import from */
-    module: string;
+    /** The module name (e.g., 'fs', 'react') to import from.
+     * Pass a `J.Literal` to reuse its source form verbatim, which carries the quoting,
+     * escapes and unicode form of a specifier being moved from elsewhere in the source. */
+    module: string | J.Literal;
 
     /** Optionally, the specific member to import from the module.
      * If not specified, adds a default import or namespace import.
@@ -28,9 +34,16 @@ export interface AddImportOptions {
 
     /** Optional alias for the imported member.
      * Required when member is 'default' or '*'.
+     * Taken verbatim, never deconflicted: a caller that names an alias may already have
+     * emitted code using it.
      * Cannot be combined with `sideEffectOnly`. */
     alias?: string;
 
+    /** Preferred local name, deconflicted if the file already binds it. Stands in for `alias` where
+     * `member` is 'default' or '*' and the caller wants a name it does not insist on.
+     * Cannot be combined with `sideEffectOnly`. */
+    preferredName?: string;
+
     /** If true, only add the import if the member is actually used in the file. Default: true
      * Cannot be combined with `sideEffectOnly`. */
     onlyIfReferenced?: boolean;
@@ -46,95 +59,448 @@ export interface AddImportOptions {
 
     /** Optional import style to use. If not specified, auto-detects from file and existing imports */
     style?: ImportStyle;
+
+    /** Quote character for the module specifier. If not specified, detected from the file.
+     * A `J.Literal` module carries its own quoting and takes precedence over this. */
+    quoteStyle?: QuoteChar;
 }
 
 /**
- * Register an AddImport visitor to add an import statement to a JavaScript/TypeScript file
- * @param visitor The visitor to add the import addition to
- * @param options Configuration options for the import to add
- *
- * @example
- * // Add a named import
- * maybeAddImport(visitor, { module: 'fs', member: 'readFile' });
- *
- * @example
- * // Add a default import using the 'default' member specifier
- * maybeAddImport(visitor, { module: 'react', member: 'default', alias: 'React' });
- *
- * @example
- * // Add a default import (legacy way, without specifying member)
- * maybeAddImport(visitor, { module: 'react', alias: 'React' });
- *
- * @example
- * // Add a namespace import
- * maybeAddImport(visitor, { module: 'crypto', member: '*', alias: 'crypto' });
- *
- * @example
- * // Add a side-effect import
- * maybeAddImport(visitor, { module: 'core-js/stable', sideEffectOnly: true });
+ * Ensures an import for `options.module` exists, queuing an `AddImport` edit where none already
+ * serves the request. `maybeBind`'s ESM/CommonJS lane is this function; its own JSDoc carries the
+ * return-value contract. `refuseCreate` answers `undefined` instead of queuing a new import,
+ * without affecting whether an existing binding answers the request first.
  */
-export function maybeAddImport(
+export function bindImport(
     visitor: JavaScriptVisitor<any>,
-    options: AddImportOptions
-) {
+    options: AddImportOptions,
+    refuseCreate?: boolean
+): string | undefined {
+    validate(options);
+    const module = moduleNameOf(options.module);
+    const sideEffectOnly = options.sideEffectOnly ?? false;
+    const typeOnly = options.typeOnly ?? false;
+
+    // A queued import binds the module as much as one already in the file, so it answers a later
+    // request the same way; a name a merged request never emits would be referenced but not bound.
     for (const v of visitor.afterVisit || []) {
-        if (v instanceof AddImport &&
-            v.module === options.module &&
-            v.member === options.member &&
-            v.alias === options.alias &&
-            v.sideEffectOnly === (options.sideEffectOnly ?? false) &&
-            v.typeOnly === (options.typeOnly ?? false)) {
-            return;
+        if (!(v instanceof AddImport) || v.module !== module ||
+            v.sideEffectOnly !== sideEffectOnly || v.typeOnly !== typeOnly) {
+            continue;
+        }
+        // How a specifier prints, or what name would be nice, does not say which binding is wanted.
+        // A pinned alias does: it asks for a binding of its own, which only the same request answers.
+        const answers = options.alias
+            ? v.alias === options.alias && v.member === options.member
+            : memberName(v.member) === memberName(options.member);
+        if (answers) {
+            return v.bindingName;
+        }
+    }
+
+    if (sideEffectOnly) {
+        if (refuseCreate) {
+            return undefined;
+        }
+        visitor.afterVisit.push(new AddImport(options));
+        return undefined;
+    }
+
+    // A pinned alias is the whole answer, so the file has no say and nothing below needs to read it.
+    if (options.alias) {
+        if (refuseCreate) {
+            return undefined;
+        }
+        visitor.afterVisit.push(new AddImport(options, options.alias));
+        return options.alias;
+    }
+
+    const derived = derivedName(options);
+    const cursor = cursorOf(visitor);
+    const cu = cursor && compilationUnitOf(cursor);
+    if (!cu) {
+        if (refuseCreate) {
+            return undefined;
+        }
+        visitor.afterVisit.push(new AddImport(options, derived));
+        return derived;
+    }
+
+    // An import already serving this request answers it; queuing one would, on the next cycle,
+    // derive a suffixed name from the binding this call just added. A caller that named a preference
+    // takes whatever comes back; one that did not assumes the name it derived, so a binding under
+    // any other name would leave the references it emits unbound.
+    for (const binding of moduleScopeBindings(cu)) {
+        if (binding.module === module && binding.member === memberName(options.member) &&
+            binding.typeOnly === typeOnly &&
+            (options.preferredName !== undefined || anyNameAnswers(options) ||
+                binding.name === derived)) {
+            return binding.name;
+        }
+    }
+
+    if (refuseCreate) {
+        return undefined;
+    }
+
+    // Only the module scope answers for a name, but any scope in the file occupies one. The queue
+    // gives every later request for this module the name chosen here, so it has to clear the scopes
+    // those references will sit in, which are not known yet.
+    const taken = takenNames(namesDeclaredIn(cu), visitor);
+    const name = deconflict(derived, candidate => taken.has(candidate));
+    visitor.afterVisit.push(new AddImport(options, name));
+    return name;
+}
+
+/** Rejects a request on its own terms, whatever the queue already holds. */
+function validate(options: AddImportOptions): void {
+    // Validate that a name is provided when member is 'default'
+    if (options.member === 'default' && !options.alias && !options.preferredName) {
+        throw new Error("When member is 'default', the alias parameter is required");
+    }
+
+    // Validate that a name is provided when member is '*' (namespace import)
+    if (options.member === '*' && !options.alias && !options.preferredName) {
+        throw new Error("When member is '*', the alias parameter is required");
+    }
+
+    // Validate that sideEffectOnly is not combined with incompatible options
+    if (options.sideEffectOnly) {
+        if (options.member !== undefined) {
+            throw new Error("Cannot combine sideEffectOnly with member");
+        }
+        if (options.alias !== undefined) {
+            throw new Error("Cannot combine sideEffectOnly with alias");
         }
+        if (options.preferredName !== undefined) {
+            throw new Error("Cannot combine sideEffectOnly with preferredName");
+        }
+        if (options.onlyIfReferenced !== undefined) {
+            throw new Error("Cannot combine sideEffectOnly with onlyIfReferenced");
+        }
+        if (options.typeOnly) {
+            throw new Error("Cannot combine sideEffectOnly with typeOnly");
+        }
+    }
+}
+
+/**
+ * A request that named no local name and asks for no member of the module. Having expressed no
+ * preference it has none to disappoint, so whatever the file already calls that module answers it.
+ */
+function anyNameAnswers(options: AddImportOptions): boolean {
+    return !options.sideEffectOnly && memberName(options.member) === undefined &&
+        options.alias === undefined && options.preferredName === undefined;
+}
+
+/** The local name a request asks for, before the file has a say in it. */
+function derivedName(options: AddImportOptions): string {
+    return options.alias ?? options.preferredName ?? memberName(options.member) ?? moduleNameOf(options.module);
+}
+
+/** `'default'` and an absent member both name a default import, which binds no member name of its own. */
+export function memberName(member: string | undefined): string | undefined {
+    return member === 'default' ? undefined : member;
+}
+
+/** A name introduced into the file's module scope, and where it came from when that is an import. */
+export interface ModuleScopeBinding {
+    name: string;
+    module?: string;
+    /** Carries the {@link AddImportOptions.member} spelling, so `undefined` means a default import. */
+    member?: string;
+    typeOnly?: boolean;
+}
+
+/** What the file's imports and `require`s bind at module scope, and the module each name comes from. */
+export function moduleScopeBindings(cu: JS.CompilationUnit): ModuleScopeBinding[] {
+    const bindings: ModuleScopeBinding[] = [];
+
+    const declaredByVariables = (varDecl: J.VariableDeclarations): void => {
+        for (const variable of varDecl.variables) {
+            const required = requiredModule(variable.element?.initializer?.element);
+            if (required !== undefined) {
+                bindings.push(...requireBindings(variable.element?.name, required));
+            }
+        }
+    };
+
+    for (const stmt of cu.statements) {
+        const statement = stmt.element;
+        if (statement?.kind === JS.Kind.Import) {
+            bindings.push(...importBindings(statement as JS.Import));
+            continue;
+        }
+        for (const declaration of declarationsOf(statement)) {
+            declaredByVariables(declaration);
+        }
+    }
+
+    return bindings;
+}
+
+/** The module a `require('...')` initializer names, `undefined` for an initializer that is anything else. */
+function requiredModule(initializer: J | undefined): string | undefined {
+    return initializer?.kind === J.Kind.MethodInvocation
+        ? requiredModuleOf(initializer as J.MethodInvocation)
+        : undefined;
+}
+
+/** A `require(...)` call, whatever it is passed. `obj.require('x')` selects a method rather than loading a module. */
+function isRequireCall(methodInv: J.MethodInvocation): boolean {
+    return !methodInv.select && methodInv.name?.kind === J.Kind.Identifier &&
+        (methodInv.name as J.Identifier).simpleName === 'require';
+}
+
+/**
+ * The module a `require(...)` call loads. `obj.require('x')` selects a method rather than loading a
+ * module, and a specifier that is not a string literal names none that can be read here.
+ */
+export function requiredModuleOf(methodInv: J.MethodInvocation): string | undefined {
+    if (!isRequireCall(methodInv)) {
+        return undefined;
+    }
+    const argument = methodInv.arguments?.elements[0]?.element;
+    return argument?.kind === J.Kind.Literal && typeof (argument as J.Literal).value === 'string'
+        ? moduleNameOf(argument as J.Literal)
+        : undefined;
+}
+
+/** A `require` binds a module the way an import does, so the pool records it the same way. */
+function requireBindings(pattern: J | undefined, module: string): ModuleScopeBinding[] {
+    // A whole-module require binds no member, exactly as a default import does.
+    if (pattern?.kind === J.Kind.Identifier) {
+        return [{name: (pattern as J.Identifier).simpleName, module, member: undefined, typeOnly: false}];
     }
-    visitor.afterVisit.push(new AddImport(options));
+    return bindingNames(pattern).map(bound => bound.member === undefined
+        ? {name: bound.name}
+        : {name: bound.name, module, member: bound.member, typeOnly: false});
+}
+
+/** The member a specifier imports and the name it binds it under, which are the same absent an alias. */
+function specifierBinding(specifier: JS.ImportSpecifier): { name: string; member: string } | undefined {
+    if (specifier.specifier?.kind === J.Kind.Identifier) {
+        const name = (specifier.specifier as J.Identifier).simpleName;
+        return {name, member: name};
+    }
+    if (specifier.specifier?.kind !== JS.Kind.Alias) {
+        return undefined;
+    }
+    const alias = specifier.specifier as JS.Alias;
+    return alias.propertyName?.element?.kind === J.Kind.Identifier && alias.alias?.kind === J.Kind.Identifier
+        ? {name: (alias.alias as J.Identifier).simpleName, member: (alias.propertyName.element as J.Identifier).simpleName}
+        : undefined;
+}
+
+function importBindings(jsImport: JS.Import): ModuleScopeBinding[] {
+    const moduleSpecifier = jsImport.moduleSpecifier?.element;
+    const module = moduleSpecifier?.kind === J.Kind.Literal
+        ? moduleNameOf(moduleSpecifier as J.Literal)
+        : undefined;
+    const importClause = jsImport.importClause;
+    if (!importClause) {
+        return [];
+    }
+
+    const typeOnly = importClause.typeOnly;
+    const bindings: ModuleScopeBinding[] = [];
+
+    if (importClause.name?.element?.kind === J.Kind.Identifier) {
+        bindings.push({name: (importClause.name.element as J.Identifier).simpleName, module, member: undefined, typeOnly});
+    }
+
+    const namedBindings = importClause.namedBindings;
+    if (namedBindings?.kind === J.Kind.Identifier) {
+        bindings.push({name: (namedBindings as J.Identifier).simpleName, module, member: '*', typeOnly});
+    } else if (namedBindings?.kind === JS.Kind.Alias) {
+        const alias = (namedBindings as JS.Alias).alias;
+        if (alias?.kind === J.Kind.Identifier) {
+            bindings.push({name: (alias as J.Identifier).simpleName, module, member: '*', typeOnly});
+        }
+    } else if (namedBindings?.kind === JS.Kind.NamedImports) {
+        for (const elem of (namedBindings as JS.NamedImports).elements.elements) {
+            const bound = elem.element?.kind === JS.Kind.ImportSpecifier
+                ? specifierBinding(elem.element as JS.ImportSpecifier)
+                : undefined;
+            if (bound) {
+                bindings.push({...bound, module, typeOnly});
+            }
+        }
+    }
+
+    return bindings;
+}
+
+/**
+ * Names in scope, plus those pending `AddImport`s on the `afterVisit` queue have claimed. A queued
+ * `RemoveImport` does not free one: it removes only what the file leaves unused, and binding a name
+ * it keeps is an error, where an unnecessary suffix merely reads oddly.
+ */
+function takenNames(inScope: ReadonlySet<string>, visitor: JavaScriptVisitor<any>): Set<string> {
+    const taken = new Set<string>(inScope);
+
+    for (const v of visitor.afterVisit || []) {
+        if (v instanceof AddImport && v.bindingName) {
+            taken.add(v.bindingName);
+        }
+    }
+
+    return taken;
+}
+
+/**
+ * The parser lifts surrogate pairs out of `valueSource` into `unicodeEscapes` and, when it does,
+ * sets `value` to the quoted source (`parser.ts` `mapLiteral`), so neither field alone is the
+ * module name. Reuniting them and stripping the quotes yields it for either shape of literal.
+ */
+export function moduleNameOf(module: string | J.Literal): string {
+    if (typeof module === 'string') {
+        return module;
+    }
+    const source = module.valueSource;
+    if (source === undefined) {
+        return String(module.value);
+    }
+    let restored = '';
+    let cut = 0;
+    for (const escape of module.unicodeEscapes ?? []) {
+        restored += source.slice(cut, escape.valueSourceIndex) + String.fromCharCode(parseInt(escape.codePoint, 16));
+        cut = escape.valueSourceIndex;
+    }
+    restored += source.slice(cut);
+    const quote = restored.charAt(0);
+    return (quote === "'" || quote === '"') && restored.endsWith(quote) && restored.length > 1
+        ? restored.slice(1, -1)
+        : restored;
+}
+
+function quoteOf(expression: J | undefined): QuoteChar | undefined {
+    if (expression?.kind !== J.Kind.Literal) {
+        return undefined;
+    }
+    const source = (expression as J.Literal).valueSource;
+    const quote = source?.charAt(0);
+    // JsxText carries raw text as its `valueSource`, so a leading quote alone does not make a
+    // literal quote-delimited; requiring a matching pair keeps prose out of the tally.
+    return (quote === "'" || quote === '"') && source!.length > 1 && source!.endsWith(quote)
+        ? quote
+        : undefined;
+}
+
+/**
+ * Pick the quote character for a module specifier being added to `cu`, so that it agrees
+ * with the file it lands in. An existing specifier is the most direct precedent; a Prettier
+ * config states intent even where the file itself has not been formatted to match.
+ */
+async function detectQuote(cu: JS.CompilationUnit): Promise<QuoteChar> {
+    // Static imports are top-level, so the highest-ranked signal needs no traversal to find.
+    for (const statement of cu.statements) {
+        const element = statement.element;
+        const topLevelQuote = element?.kind === JS.Kind.Import
+            ? quoteOf((element as JS.Import).moduleSpecifier?.element)
+            : element?.kind === JS.Kind.ExportDeclaration
+                ? quoteOf((element as JS.ExportDeclaration).moduleSpecifier?.element)
+                : undefined;
+        if (topLevelQuote) {
+            return topLevelQuote;
+        }
+    }
+
+    let importQuote: QuoteChar | undefined;
+    let requireQuote: QuoteChar | undefined;
+    let single = 0;
+    let double = 0;
+
+    await new class extends JavaScriptVisitor<void> {
+        override async visitImportDeclaration(jsImport: JS.Import, p: void): Promise<J | undefined> {
+            importQuote ??= quoteOf(jsImport.moduleSpecifier?.element);
+            return super.visitImportDeclaration(jsImport, p);
+        }
+
+        override async visitExportDeclaration(exportDeclaration: JS.ExportDeclaration, p: void): Promise<J | undefined> {
+            importQuote ??= quoteOf(exportDeclaration.moduleSpecifier?.element);
+            return super.visitExportDeclaration(exportDeclaration, p);
+        }
+
+        override async visitMethodInvocation(method: J.MethodInvocation, p: void): Promise<J | undefined> {
+            if (!method.select && method.name?.kind === J.Kind.Identifier &&
+                (method.name as J.Identifier).simpleName === 'require') {
+                requireQuote ??= quoteOf(method.arguments?.elements[0]?.element);
+            }
+            return super.visitMethodInvocation(method, p);
+        }
+
+        override async visitJsxAttribute(attribute: JSX.Attribute, p: void): Promise<J | undefined> {
+            // JSX attribute quoting answers to Prettier's `jsxSingleQuote`, so it is no evidence
+            // about the quote style of ordinary strings.
+            return attribute;
+        }
+
+        override async visitLiteral(literal: J.Literal, p: void): Promise<J | undefined> {
+            const quote = quoteOf(literal);
+            if (quote === "'") {
+                single++;
+            } else if (quote === '"') {
+                double++;
+            }
+            return super.visitLiteral(literal, p);
+        }
+    }().visit(cu, undefined);
+
+    // Imports outrank requires; that ordering is what makes the import-only scan above sound.
+    const specifierQuote = importQuote ?? requireQuote;
+    if (specifierQuote) {
+        return specifierQuote;
+    }
+
+    const prettier = getStyle(StyleKind.PrettierStyle, cu) as PrettierStyle | undefined;
+    if (prettier?.kind === StyleKind.PrettierStyle && !prettier.ignored) {
+        const singleQuote = prettier.config.singleQuote;
+        if (typeof singleQuote === 'boolean') {
+            return singleQuote ? "'" : '"';
+        }
+    }
+
+    return double > single ? '"' : "'";
 }
 
 export class AddImport<P> extends JavaScriptVisitor<P> {
     readonly module: string;
+    /** Set when the caller supplied the module specifier as a literal; printed verbatim. */
+    readonly moduleValueSource?: string;
+    readonly moduleUnicodeEscapes?: J.LiteralUnicodeEscape[];
     readonly member?: string;
     readonly alias?: string;
     readonly onlyIfReferenced: boolean;
     readonly sideEffectOnly: boolean;
     readonly typeOnly: boolean;
     readonly style?: ImportStyle;
+    readonly quoteStyle?: QuoteChar;
+    /** The local name this import binds; `undefined` for a side-effect import. */
+    readonly bindingName?: string;
+    /**
+     * A default import the request named no local name for, so whatever the file already calls
+     * that module answers it.
+     */
+    readonly anyNameAnswers: boolean;
 
-    constructor(options: AddImportOptions) {
+    constructor(options: AddImportOptions, bindingName?: string) {
         super();
 
-        // Validate that alias is provided when member is 'default'
-        if (options.member === 'default' && !options.alias) {
-            throw new Error("When member is 'default', the alias parameter is required");
-        }
-
-        // Validate that alias is provided when member is '*' (namespace import)
-        if (options.member === '*' && !options.alias) {
-            throw new Error("When member is '*', the alias parameter is required");
-        }
+        validate(options);
 
-        // Validate that sideEffectOnly is not combined with incompatible options
-        if (options.sideEffectOnly) {
-            if (options.member !== undefined) {
-                throw new Error("Cannot combine sideEffectOnly with member");
-            }
-            if (options.alias !== undefined) {
-                throw new Error("Cannot combine sideEffectOnly with alias");
-            }
-            if (options.onlyIfReferenced !== undefined) {
-                throw new Error("Cannot combine sideEffectOnly with onlyIfReferenced");
-            }
-            if (options.typeOnly) {
-                throw new Error("Cannot combine sideEffectOnly with typeOnly");
-            }
-        }
-
-        this.module = options.module;
+        this.module = moduleNameOf(options.module);
+        this.moduleValueSource = typeof options.module === 'string' ? undefined : options.module.valueSource;
+        this.moduleUnicodeEscapes = typeof options.module === 'string' ? undefined : options.module.unicodeEscapes;
         this.member = options.member;
         this.alias = options.alias;
         this.onlyIfReferenced = options.onlyIfReferenced ?? true;
         this.sideEffectOnly = options.sideEffectOnly ?? false;
         this.typeOnly = options.typeOnly ?? false;
         this.style = options.style;
+        this.quoteStyle = options.quoteStyle;
+        this.bindingName = this.sideEffectOnly ? undefined : bindingName ?? derivedName(options);
+        this.anyNameAnswers = anyNameAnswers(options);
     }
 
     /**
@@ -144,16 +510,9 @@ export class AddImport<P> extends JavaScriptVisitor<P> {
         if (moduleSpecifier.kind !== J.Kind.Literal) {
             return undefined;
         }
-        return (moduleSpecifier as J.Literal).value?.toString();
+        return moduleNameOf(moduleSpecifier as J.Literal);
     }
 
-    /**
-     * Check if a method invocation is a require() call
-     */
-    private isRequireCall(methodInv: J.MethodInvocation): boolean {
-        return methodInv.name?.kind === J.Kind.Identifier &&
-               (methodInv.name as J.Identifier).simpleName === 'require';
-    }
 
     /**
      * Determine the appropriate import style based on file type and existing imports
@@ -233,7 +592,7 @@ export class AddImport<P> extends JavaScriptVisitor<P> {
                     const namedVar = varDecl.variables[0].element;
                     const initializer = namedVar?.initializer?.element;
                     if (initializer?.kind === J.Kind.MethodInvocation &&
-                        this.isRequireCall(initializer as J.MethodInvocation)) {
+                        isRequireCall(initializer as J.MethodInvocation)) {
                         hasCommonJSRequires = true;
                     }
                 }
@@ -310,12 +669,8 @@ export class AddImport<P> extends JavaScriptVisitor<P> {
                     const namedVar = varDecl.variables[0].element;
                     const initializer = namedVar?.initializer?.element;
 
-                    if (initializer?.kind === J.Kind.MethodInvocation &&
-                        this.isRequireCall(initializer as J.MethodInvocation)) {
-                        const moduleName = this.getModuleNameFromRequire(initializer as J.MethodInvocation);
-                        if (moduleName === this.module) {
-                            return ImportStyle.CommonJS;
-                        }
+                    if (requiredModule(initializer) === this.module) {
+                        return ImportStyle.CommonJS;
                     }
                 }
             }
@@ -473,10 +828,10 @@ export class AddImport<P> extends JavaScriptVisitor<P> {
                         const existingElements = namedImports.elements.elements;
 
                         // Find the correct insertion position (alphabetical, case-insensitive)
-                        const newName = (this.alias || this.member!).toLowerCase();
+                        const newName = this.bindingName!.toLowerCase();
                         let insertIndex = existingElements.findIndex(elem => {
                             if (elem.element?.kind === JS.Kind.ImportSpecifier) {
-                                const name = this.getImportAlias(elem.element) || this.getImportName(elem.element);
+                                const name = specifierBinding(elem.element as JS.ImportSpecifier)?.name ?? '';
                                 return newName.localeCompare(name.toLowerCase()) < 0;
                             }
                             return false;
@@ -634,91 +989,27 @@ export class AddImport<P> extends JavaScriptVisitor<P> {
      * Check if the import matches what we're trying to add
      */
     private isMatchingImport(jsImport: JS.Import): boolean {
-        // Check module specifier
         const moduleSpecifier = jsImport.moduleSpecifier?.element;
-        if (!moduleSpecifier) {
-            return false;
-        }
-
-        const moduleName = this.getModuleName(moduleSpecifier);
-        if (moduleName !== this.module) {
+        if (!moduleSpecifier || this.getModuleName(moduleSpecifier) !== this.module) {
             return false;
         }
 
+        // A side-effect import is the clause-less one, and no import carrying bindings stands in
+        // for it — nor it for them.
         const importClause = jsImport.importClause;
-
-        // Handle side-effect imports (no import clause)
-        if (!importClause) {
-            // If we're trying to add a side-effect import and one already exists, it's a match
-            return this.sideEffectOnly;
-        }
-
-        // If we're adding a side-effect import but there's an existing import with bindings,
-        // it's not a match (side-effect import should be separate)
-        if (this.sideEffectOnly) {
-            return false;
+        if (!importClause || this.sideEffectOnly) {
+            return !importClause && this.sideEffectOnly;
         }
 
-        // Check if the typeOnly flag matches - type-only and value imports are separate
-        if (importClause.typeOnly !== this.typeOnly) {
-            return false;
-        }
-
-        // Check if the specific member or default import already exists
-        if (this.member === '*') {
-            // We're adding a namespace import, check if one exists
-            const namedBindings = importClause.namedBindings;
-            if (!namedBindings) {
-                return false;
-            }
-
-            // Namespace imports can be represented as J.Identifier or JS.Alias
-            if (namedBindings.kind === J.Kind.Identifier) {
-                const identifier = namedBindings as J.Identifier;
-                return identifier.simpleName === this.alias;
-            } else if (namedBindings.kind === JS.Kind.Alias) {
-                const alias = namedBindings as JS.Alias;
-                if (alias.alias?.kind === J.Kind.Identifier) {
-                    return (alias.alias as J.Identifier).simpleName === this.alias;
-                }
-            }
-            return false;
-        } else if (this.member === undefined || this.member === 'default') {
-            // We're adding a default import, check if one exists
-            // For member === 'default', also verify the alias matches if specified
-            if (importClause.name === undefined) {
-                return false;
-            }
-            // If we have an alias, check that it matches
-            if (this.alias && importClause.name.element?.kind === J.Kind.Identifier) {
-                const existingName = (importClause.name.element as J.Identifier).simpleName;
-                return existingName === this.alias;
-            }
-            return true;
-        } else {
-            // We're adding a named import, check if it exists
-            const namedBindings = importClause.namedBindings;
-            if (!namedBindings) {
-                return false;
-            }
-
-            if (namedBindings.kind === JS.Kind.NamedImports) {
-                const namedImports = namedBindings as JS.NamedImports;
-                for (const elem of namedImports.elements.elements) {
-                    if (elem.element?.kind === JS.Kind.ImportSpecifier) {
-                        const specifier = elem.element as JS.ImportSpecifier;
-                        const importName = this.getImportName(specifier);
-                        const aliasName = this.getImportAlias(specifier);
-
-                        if (importName === this.member && aliasName === this.alias) {
-                            return true;
-                        }
-                    }
-                }
-            }
-        }
+        return importBindings(jsImport).some(binding => this.answeredBy(binding));
+    }
 
-        return false;
+    /** Whether a binding the file already has serves this request. */
+    private answeredBy(binding: ModuleScopeBinding): boolean {
+        return binding.module === this.module &&
+            binding.member === memberName(this.member) &&
+            binding.typeOnly === this.typeOnly &&
+            (this.anyNameAnswers || binding.name === this.bindingName);
     }
 
     /**
@@ -728,52 +1019,12 @@ export class AddImport<P> extends JavaScriptVisitor<P> {
         if (varDecl.variables.length !== 1) {
             return false;
         }
-
         const namedVar = varDecl.variables[0].element;
-        if (!namedVar) {
+        const module = requiredModule(namedVar?.initializer?.element);
+        if (module !== this.module) {
             return false;
         }
-
-        const initializer = namedVar.initializer?.element;
-        if (!initializer || initializer.kind !== J.Kind.MethodInvocation) {
-            return false;
-        }
-
-        const methodInv = initializer as J.MethodInvocation;
-        if (!this.isRequireCall(methodInv)) {
-            return false;
-        }
-
-        const moduleName = this.getModuleNameFromRequire(methodInv);
-        if (moduleName !== this.module) {
-            return false;
-        }
-
-        // Check if the variable name matches what we're trying to add
-        const pattern = namedVar.name;
-        if ((this.member === undefined || this.member === 'default') && pattern?.kind === J.Kind.Identifier) {
-            // Default import style: const fs = require('fs')
-            // For member === 'default', also check the alias matches if specified
-            if (this.alias) {
-                const varName = (pattern as J.Identifier).simpleName;
-                return varName === this.alias;
-            }
-            return true;
-        } else if (this.member !== undefined && this.member !== 'default' && pattern?.kind === JS.Kind.ObjectBindingPattern) {
-            // Destructured import: const { member } = require('module')
-            const objectPattern = pattern as JS.ObjectBindingPattern;
-            for (const elem of objectPattern.bindings.elements) {
-                if (elem.element?.kind === JS.Kind.BindingElement) {
-                    const bindingElem = elem.element as JS.BindingElement;
-                    const name = (bindingElem.name as J.Identifier)?.simpleName;
-                    if (name === (this.alias || this.member)) {
-                        return true;
-                    }
-                }
-            }
-        }
-
-        return false;
+        return requireBindings(namedVar!.name, module).some(binding => this.answeredBy(binding));
     }
 
     /**
@@ -899,7 +1150,7 @@ export class AddImport<P> extends JavaScriptVisitor<P> {
         }
 
         // Step 2: Look for references that match
-        const targetName = this.alias || this.member;
+        const targetName = this.bindingName;
         const targetModule = this.module;
         let found = false;
         const self = this;
@@ -1033,15 +1284,20 @@ export class AddImport<P> extends JavaScriptVisitor<P> {
         // For side-effect imports, use emptySpace since space comes from LeftPadded.before
         // For regular imports with import clause, use emptySpace since space comes from LeftPadded.before
         // However, the printer expects the space after 'from' in the literal's prefix
-        // Note: value contains the unquoted string, valueSource contains the quoted version for printing
+        // Note: value is the unquoted module name; valueSource and unicodeEscapes are its printed form
+        let valueSource = this.moduleValueSource;
+        if (valueSource === undefined) {
+            const quote = this.quoteStyle ?? await detectQuote(compilationUnit);
+            valueSource = `${quote}${this.module}${quote}`;
+        }
         const moduleSpecifier: J.Literal = {
             id: randomId(),
             kind: J.Kind.Literal,
             prefix: this.sideEffectOnly ? emptySpace : singleSpace,
             markers: emptyMarkers,
             value: this.module,
-            valueSource: `'${this.module}'`,
-            unicodeEscapes: [],
+            valueSource,
+            unicodeEscapes: this.moduleUnicodeEscapes,
             type: undefined
         };
 
@@ -1069,7 +1325,7 @@ export class AddImport<P> extends JavaScriptVisitor<P> {
                 prefix: singleSpace,
                 markers: emptyMarkers,
                 annotations: [],
-                simpleName: this.alias!,
+                simpleName: this.bindingName!,
                 type: undefined,
                 fieldType: undefined
             };
@@ -1101,7 +1357,7 @@ export class AddImport<P> extends JavaScriptVisitor<P> {
                 prefix: singleSpace,
                 markers: emptyMarkers,
                 annotations: [],
-                simpleName: this.alias || this.module,
+                simpleName: this.bindingName!,
                 type: undefined,
                 fieldType: undefined
             };
@@ -1176,7 +1432,8 @@ export class AddImport<P> extends JavaScriptVisitor<P> {
     private createImportSpecifier(): JS.ImportSpecifier {
         let specifier: J.Identifier | JS.Alias;
 
-        if (this.alias) {
+        // An alias equal to the member says nothing `{member}` alone does not.
+        if (this.bindingName !== this.member) {
             // Aliased import: import { member as alias } from 'module'
             const propertyName: J.Identifier = {
                 id: randomId(),
@@ -1195,7 +1452,7 @@ export class AddImport<P> extends JavaScriptVisitor<P> {
                 prefix: singleSpace,
                 markers: emptyMarkers,
                 annotations: [],
-                simpleName: this.alias,
+                simpleName: this.bindingName!,
                 type: undefined,
                 fieldType: undefined
             };
@@ -1286,51 +1543,298 @@ export class AddImport<P> extends JavaScriptVisitor<P> {
         return 0;
     }
 
-    /**
-     * Get the module name from a require() call
-     */
-    private getModuleNameFromRequire(methodInv: J.MethodInvocation): string | undefined {
-        const args = methodInv.arguments?.elements;
-        if (!args || args.length === 0) {
-            return undefined;
+
+
+}
+
+/**
+ * The local name `jsImport` binds `member` of `module` to, or `undefined` where it binds
+ * something else. `'default'` and an absent `member` both mean the default import, matching
+ * {@link memberName}.
+ */
+function importBinds(jsImport: JS.Import, module: string, member: string | undefined): string | undefined {
+    const specifier = jsImport.moduleSpecifier?.element;
+    if (specifier?.kind !== J.Kind.Literal || (specifier as J.Literal).value !== module) {
+        return undefined;
+    }
+    const importClause = jsImport.importClause;
+    if (!importClause) {
+        return undefined;
+    }
+    const key = memberName(member);
+    if (key === undefined) {
+        const nameElem = importClause.name?.element;
+        return nameElem && isIdentifier(nameElem) ? nameElem.simpleName : undefined;
+    }
+    if (key === '*') {
+        const namedBindings = importClause.namedBindings;
+        return namedBindings?.kind === JS.Kind.Alias && isIdentifier((namedBindings as JS.Alias).alias)
+            ? ((namedBindings as JS.Alias).alias as J.Identifier).simpleName
+            : undefined;
+    }
+    const namedBindings = importClause.namedBindings;
+    if (namedBindings?.kind !== JS.Kind.NamedImports) {
+        return undefined;
+    }
+    for (const elem of (namedBindings as JS.NamedImports).elements.elements) {
+        const specifierNode = elem.element.specifier;
+        if (!namedSpecifierImports(specifierNode, key)) {
+            continue;
+        }
+        if (isIdentifier(specifierNode)) {
+            return specifierNode.simpleName;
+        }
+        const alias = (specifierNode as JS.Alias).alias;
+        if (isIdentifier(alias)) {
+            return alias.simpleName;
         }
+    }
+    return undefined;
+}
 
-        const firstArg = args[0].element;
-        if (!firstArg || firstArg.kind !== J.Kind.Literal || typeof (firstArg as J.Literal).value !== 'string') {
-            return undefined;
+/** Whether `specifier` imports the member `key`, under whatever local name it binds it to. */
+function namedSpecifierImports(specifier: JS.ImportSpecifier["specifier"], key: string): boolean {
+    if (isIdentifier(specifier)) {
+        return specifier.simpleName === key;
+    }
+    if (specifier.kind === JS.Kind.Alias) {
+        const propertyName = (specifier as JS.Alias).propertyName.element;
+        return isIdentifier(propertyName) && propertyName.simpleName === key;
+    }
+    return false;
+}
+
+/** Whether the named specifier binding `key` carries its own inline `type`, as in `{type a, b}`. */
+function namedSpecifierIsTypeOnly(imp: JS.Import, key: string): boolean {
+    const namedBindings = imp.importClause?.namedBindings;
+    if (namedBindings?.kind !== JS.Kind.NamedImports) {
+        return false;
+    }
+    for (const elem of (namedBindings as JS.NamedImports).elements.elements) {
+        if (namedSpecifierImports(elem.element.specifier, key)) {
+            return elem.element.importType.element;
         }
+    }
+    return false;
+}
 
-        return (firstArg as J.Literal).value?.toString();
+/** How many named specifiers `jsImport` carries, `0` for a default, namespace or side-effect import. */
+function namedImportCount(jsImport: JS.Import): number {
+    const namedBindings = jsImport.importClause?.namedBindings;
+    return namedBindings?.kind === JS.Kind.NamedImports ? (namedBindings as JS.NamedImports).elements.elements.length : 0;
+}
+
+/**
+ * Whether `jsImport`'s clause binds exactly one thing — a default, a namespace, or one named
+ * specifier. That is the only shape a module-only move can rewrite in place: whichever binding
+ * `importBinds` already matched is this one, so nothing else the clause carries goes along with it.
+ */
+function isOnlyMember(jsImport: JS.Import): boolean {
+    const importClause = jsImport.importClause;
+    if (!importClause) {
+        return false;
     }
+    const hasDefault = importClause.name !== undefined;
+    const hasNamespace = importClause.namedBindings?.kind === JS.Kind.Alias;
+    return (hasDefault ? 1 : 0) + (hasNamespace ? 1 : 0) + namedImportCount(jsImport) === 1;
+}
 
-    /**
-     * Get the import name from an import specifier
-     */
-    private getImportName(specifier: JS.ImportSpecifier): string {
-        const spec = specifier.specifier;
-        if (spec?.kind === JS.Kind.Alias) {
-            const alias = spec as JS.Alias;
-            const propertyName = alias.propertyName.element;
-            if (propertyName?.kind === J.Kind.Identifier) {
-                return (propertyName as J.Identifier).simpleName;
-            }
-        } else if (spec?.kind === J.Kind.Identifier) {
-            return (spec as J.Identifier).simpleName;
+export interface ExistingImportBinding {
+    localName: string;
+    onlyMemberOfStatement: boolean;
+}
+
+/**
+ * The existing binding for `member` of `module`, read from `cu`'s own import statements — what
+ * `maybeRebind` reads before committing to a `RebindImport` edit.
+ */
+export function existingImportBinding(
+    cu: JS.CompilationUnit,
+    module: string,
+    member: string | undefined
+): ExistingImportBinding | undefined {
+    for (const stmt of cu.statements) {
+        const element = stmt.element;
+        if (element?.kind !== JS.Kind.Import) {
+            continue;
+        }
+        const localName = importBinds(element as JS.Import, module, member);
+        if (localName !== undefined) {
+            return {localName, onlyMemberOfStatement: isOnlyMember(element as JS.Import)};
         }
-        return '';
     }
+    return undefined;
+}
 
-    /**
-     * Get the import alias from an import specifier
-     */
-    private getImportAlias(specifier: JS.ImportSpecifier): string | undefined {
-        const spec = specifier.specifier;
-        if (spec?.kind === JS.Kind.Alias) {
-            const alias = spec as JS.Alias;
-            if (alias.alias?.kind === J.Kind.Identifier) {
-                return (alias.alias as J.Identifier).simpleName;
-            }
+/**
+ * Binds `member` under the name `local` already carries, so the file's references to it still
+ * resolve. `local` itself becomes the alias, keeping the type attribution it holds, and the alias
+ * takes its prefix: that whitespace separates the specifier from a `type` keyword before it.
+ */
+function aliasing(local: J.Identifier, member: string): JS.Alias {
+    const propertyName: J.Identifier = {
+        id: randomId(),
+        kind: J.Kind.Identifier,
+        prefix: emptySpace,
+        markers: emptyMarkers,
+        annotations: [],
+        simpleName: member,
+        type: undefined,
+        fieldType: undefined
+    };
+    return {
+        id: randomId(),
+        kind: JS.Kind.Alias,
+        prefix: local.prefix,
+        markers: emptyMarkers,
+        propertyName: rightPadded(propertyName, singleSpace),
+        alias: {...local, prefix: singleSpace}
+    };
+}
+
+/**
+ * Drops the binding for `member` from `jsImport`'s clause — the default, the namespace alias, or
+ * one entry of the named list, whichever `member` names — keeping everything else the clause
+ * binds. `ElementRemovalFormatter` carries the dropped binding's prefix onto whatever prints
+ * next, the same way `RemoveImport` keeps formatting sane when trimming a list.
+ */
+function removeBinding(jsImport: JS.Import, member: string | undefined): JS.Import {
+    const importClause = jsImport.importClause;
+    if (!importClause) {
+        return jsImport;
+    }
+    const key = memberName(member);
+
+    if (key === undefined) {
+        if (!importClause.name) {
+            return jsImport;
         }
-        return undefined;
+        const namedBindings = importClause.namedBindings;
+        if (namedBindings?.kind === JS.Kind.NamedImports) {
+            // `NamedImports` keeps the space before its own `{` on the container's `before`,
+            // not on its own prefix, so the removed default's prefix has to land there instead.
+            const namedImports = namedBindings as JS.NamedImports;
+            const updated: JS.NamedImports = {
+                ...namedImports,
+                elements: {...namedImports.elements, before: importClause.name.element.prefix}
+            };
+            return {...jsImport, importClause: {...importClause, name: undefined, namedBindings: updated}};
+        }
+        if (namedBindings) {
+            const formatter = new ElementRemovalFormatter<J>();
+            formatter.markRemoved(importClause.name.element);
+            return {...jsImport, importClause: {...importClause, name: undefined, namedBindings: formatter.processKept(namedBindings)}};
+        }
+        return {...jsImport, importClause: {...importClause, name: undefined}};
+    }
+
+    if (key === '*') {
+        return {...jsImport, importClause: {...importClause, namedBindings: undefined}};
+    }
+
+    if (importClause.namedBindings?.kind !== JS.Kind.NamedImports) {
+        return jsImport;
+    }
+    const namedImports = importClause.namedBindings as JS.NamedImports;
+    const formatter = new ElementRemovalFormatter<JS.ImportSpecifier>();
+    const kept: J.RightPadded<JS.ImportSpecifier>[] = [];
+    for (const entry of namedImports.elements.elements) {
+        if (namedSpecifierImports(entry.element.specifier, key)) {
+            formatter.markRemoved(entry.element);
+        } else {
+            kept.push({...entry, element: formatter.processKept(entry.element)});
+        }
+    }
+    if (kept.length === 0) {
+        // An emptied brace list still prints, as `import D, {} from "m"`, so it goes with its
+        // last member; the caller drops the whole statement when no default remains either.
+        return {...jsImport, importClause: {...importClause, namedBindings: undefined}};
+    }
+    const updatedNamedImports: JS.NamedImports = {...namedImports, elements: {...namedImports.elements, elements: kept}};
+    return {...jsImport, importClause: {...importClause, namedBindings: updatedNamedImports}};
+}
+
+/**
+ * Moves the binding `from` names to `to`, keeping the local name it already had. In place when
+ * the statement that carries it binds nothing else — module and member specifier rewritten there
+ * directly; otherwise the old specifier drops and {@link bindImport} queues the replacement,
+ * aliased to the preserved name.
+ *
+ * Not built on `RemoveImport`/`maybeUnbind`: those only drop a binding once nothing references
+ * it, but a rebind moves one that is still in use — removal here has to be unconditional.
+ */
+export class RebindImport<P> extends JavaScriptVisitor<P> {
+    constructor(
+        readonly from: {module: string; member?: string},
+        readonly to: {module: string; member?: string},
+        readonly localName: string
+    ) {
+        super();
+    }
+
+    private transformedInPlace = false;
+    private typeOnly = false;
+
+    override async visitJsCompilationUnit(cu: JS.CompilationUnit, p: P): Promise<J | undefined> {
+        const visited = await super.visitJsCompilationUnit(cu, p) as JS.CompilationUnit;
+        if (!this.transformedInPlace) {
+            bindImport(this, {
+                module: this.to.module,
+                member: this.to.member,
+                alias: this.localName,
+                typeOnly: this.typeOnly,
+                onlyIfReferenced: false
+            });
+        }
+        return visited;
+    }
+
+    override async visitImportDeclaration(jsImport: JS.Import, p: P): Promise<J | undefined> {
+        const imp = await super.visitImportDeclaration(jsImport, p) as JS.Import;
+
+        const key = memberName(this.from.member);
+        if (importBinds(imp, this.from.module, this.from.member) === undefined) {
+            return imp;
+        }
+        // A moved named specifier's own inline `type` marks it type-only even where the clause
+        // it's leaving is not — the replacement needs the same answer to stay type-safe.
+        this.typeOnly = (imp.importClause?.typeOnly ?? false) ||
+            (key !== undefined && key !== '*' && namedSpecifierIsTypeOnly(imp, key));
+
+        if (!isOnlyMember(imp)) {
+            return removeBinding(imp, this.from.member);
+        }
+
+        this.transformedInPlace = true;
+        return produce(imp, draft => {
+            const literal = draft.moduleSpecifier!.element as Draft<J.Literal>;
+            literal.value = this.to.module;
+            const originalSource = literal.valueSource || `"${this.from.module}"`;
+            const quoteChar = originalSource.startsWith("'") ? "'" : '"';
+            literal.valueSource = `${quoteChar}${this.to.module}${quoteChar}`;
+
+            // A named specifier's local name has to stay put in the source, since it is what the
+            // rest of the file already reads; default and namespace imports carry that name on
+            // the clause itself, which needs no edit for a module-only move.
+            const toKey = memberName(this.to.member);
+            if (key !== undefined && key !== '*' && toKey !== undefined && toKey !== key) {
+                const importClause = draft.importClause;
+                if (importClause?.namedBindings?.kind === JS.Kind.NamedImports) {
+                    const namedImports = importClause.namedBindings as Draft<JS.NamedImports>;
+                    for (const elem of namedImports.elements.elements) {
+                        const specifier = elem.element;
+                        if (specifier.specifier.kind === J.Kind.Identifier && specifier.specifier.simpleName === key) {
+                            specifier.specifier = aliasing(specifier.specifier as Draft<J.Identifier>, toKey) as Draft<JS.Alias>;
+                        } else if (specifier.specifier.kind === JS.Kind.Alias) {
+                            const aliasNode = specifier.specifier as Draft<JS.Alias>;
+                            const propertyName = aliasNode.propertyName.element;
+                            if (propertyName.kind === J.Kind.Identifier && propertyName.simpleName === key) {
+                                propertyName.simpleName = toKey;
+                            }
+                        }
+                    }
+                }
+            }
+        });
     }
 }