aihand 0.0.1 → 0.1.0

package/src/read/refactor.ts

@@ -0,0 +1,576 @@
+import type { ExportDeclaration, ImportDeclaration, ImportDeclarationStructure, ImportSpecifierStructure, Node, Project, SourceFile, VariableStatement } from 'ts-morph'
+import { existsSync } from 'node:fs'
+import { relative, resolve } from 'node:path'
+import process from 'node:process'
+import { Node as TsNode, SyntaxKind } from 'ts-morph'
+
+// AST-level refactors (ts-morph). Counterpart to the read-only tree-sitter
+// analysis: moving a file rewrites every importer's specifier through the type
+// checker, so ./x and ../x all resolve — never regex.
+//
+// ts-morph's move() rewrites RELATIVE specifiers but leaves path-alias ones
+// (`@/...`) pointing at the old location — it can't re-derive an alias path.
+// We patch those ourselves from compilerOptions.paths, else move() would
+// silently break every alias importer (the exact regex-style 误伤 AST is meant to prevent).
+
+export interface AliasPrefix { alias: string, target: string }
+
+async function openProject(): Promise<Project> {
+    const { Project, QuoteKind } = await import('ts-morph')
+    // The tsconfig that carries compilerOptions.paths + a real `include`. A solution-style
+    // root tsconfig (files:[] + references) has no source graph, so prefer the app one.
+    const tsConfigFilePath = ['tsconfig.app.json', 'tsconfig.json'].map(f => resolve(f)).find(existsSync)
+    if (!tsConfigFilePath) {
+        console.error('refactor: no tsconfig.json (or tsconfig.app.json) found in cwd')
+        process.exit(1)
+    }
+    // Single quotes match this repo's style; without this, generated imports come out double-quoted.
+    return new Project({ tsConfigFilePath, manipulationSettings: { quoteKind: QuoteKind.Single } })
+}
+
+// Alias prefixes from compilerOptions.paths, e.g. {"@/*":["./src/*"]} → [{ alias: '@', target: '<abs>/src' }]
+// Both sides strip the trailing '/*'; the joining '/' is added back in toAlias so neither side double-slashes.
+function aliasPrefixes(project: Project): AliasPrefix[] {
+    const opts = project.getCompilerOptions()
+    const base = opts.baseUrl ?? process.cwd()
+    const out: AliasPrefix[] = []
+    for (const [pattern, targets] of Object.entries(opts.paths ?? {})) {
+        if (!pattern.endsWith('/*') || !targets[0]?.endsWith('/*'))
+            continue
+        out.push({ alias: pattern.slice(0, -2), target: resolve(base, targets[0].slice(0, -2)) })
+    }
+    return out
+}
+
+// Strip a TS/JS extension if present — specifiers may carry an explicit `.ts` or none, so any path
+// comparison must normalise both sides through this. (`@/x` and `@/x.ts` resolve to the same module.)
+function stripExt(p: string): string {
+    const ext = ['.tsx', '.ts', '.jsx', '.js'].find(e => p.endsWith(e))
+    return ext ? p.slice(0, -ext.length) : p
+}
+
+// Build the extensionless alias specifier for an absolute path (matches ts-morph's relative-rewrite style).
+export function toAlias(absPath: string, prefixes: AliasPrefix[]): string | null {
+    const noExt = stripExt(absPath)
+    for (const { alias, target } of prefixes) {
+        if (noExt === target || noExt.startsWith(`${target}/`))
+            return `${alias}/${noExt.slice(target.length + 1)}`
+    }
+    return null
+}
+
+// Reverse of toAlias: resolve an alias-form specifier (`@/a`) to the extensionless absolute path it
+// points at (`<base>/src/a`), or null if it's not an alias specifier. Used to match dynamic-import
+// specifiers against the file being moved — getModuleSpecifierSourceFile() only covers import/export
+// declarations, never `import('...')` calls, so those must be resolved by hand.
+function aliasSpecToAbs(spec: string, prefixes: AliasPrefix[]): string | null {
+    for (const { alias, target } of prefixes) {
+        if (spec === alias)
+            return target
+        if (spec.startsWith(`${alias}/`))
+            return `${target}/${spec.slice(alias.length + 1)}`
+    }
+    return null
+}
+
+// Pure core: move a file inside an already-open project, patching alias importers.
+// Returns the changed source files (unsaved). No IO, no exit — testable in isolation.
+// Throws if src isn't in the project (the caller decides how to surface it).
+export function moveInProject(project: Project, srcAbs: string, destAbs: string): SourceFile[] {
+    const sf = project.getSourceFile(srcAbs)
+    if (!sf)
+        throw new Error(`${srcAbs} not in project`)
+    // Refuse to clobber an existing file. ts-morph's move() would throw a raw "provide the overwrite
+    // option" error; surface a clear one instead (overwriting would silently destroy the dest's content).
+    if (srcAbs !== destAbs && project.getSourceFile(destAbs))
+        throw new Error(`destination ${destAbs} already exists; move to a fresh path or delete it first`)
+
+    const prefixes = aliasPrefixes(project)
+    const srcNoExt = stripExt(srcAbs)
+    // An alias-form specifier that resolves to the file we're moving. The aliasSpecToAbs match (vs.
+    // getModuleSpecifierSourceFile()) excludes npm scoped packages (`@scope/pkg` → node_modules, not sf)
+    // AND works for forms ts-morph doesn't resolve: dynamic imports and side-effect imports.
+    const pointsAtSrc = (spec: string) => {
+        const resolved = aliasSpecToAbs(spec, prefixes)
+        return resolved !== null && stripExt(resolved) === srcNoExt
+    }
+    // ts-morph's move() rewrites RELATIVE specifiers (any kind) but leaves alias ones stale — and never
+    // touches alias dynamic imports / side-effect imports at all. We capture every alias-form reference
+    // BEFORE move() (which invalidates resolution), then re-point each from the NEW location. Crucially
+    // the new specifier is computed per-importer via specifierFrom: alias if dest is still under an alias
+    // root, else a relative path — so moving OUT of the alias root degrades importers to `../x`, not stale.
+    const declFixups: { decl: ImportDeclaration | ExportDeclaration, file: SourceFile }[] = []
+    const litFixups: { lit: Node & { setLiteralValue: (v: string) => void }, file: SourceFile }[] = []
+    // Every importer (relative or alias) is a changed file — collect them all, not via isSaved()
+    // (which conflates "never saved" with "modified" and breaks on in-memory / freshly-created files).
+    const changed = new Set<SourceFile>()
+    // getReferencingSourceFiles() covers named/default/namespace imports + re-exports, but MISSES pure
+    // side-effect alias imports (`import '@/a'`) — those resolve to undefined and aren't tracked as refs.
+    // So scan every source file's imports/exports directly by spec, not just the referencing set.
+    for (const ref of project.getSourceFiles()) {
+        if (ref === sf)
+            continue
+        for (const d of ref.getImportDeclarations()) {
+            if (pointsAtSrc(d.getModuleSpecifierValue())) {
+                changed.add(ref)
+                declFixups.push({ decl: d, file: ref })
+            }
+        }
+        for (const d of ref.getExportDeclarations()) {
+            const spec = d.getModuleSpecifierValue()
+            if (spec && pointsAtSrc(spec)) {
+                changed.add(ref)
+                declFixups.push({ decl: d, file: ref })
+            }
+        }
+        for (const call of ref.getDescendantsOfKind(SyntaxKind.CallExpression)) {
+            if (call.getExpression().getKind() !== SyntaxKind.ImportKeyword)
+                continue
+            const arg = call.getArguments()[0]
+            if (arg && TsNode.isStringLiteral(arg) && pointsAtSrc(arg.getLiteralValue())) {
+                changed.add(ref)
+                litFixups.push({ lit: arg, file: ref })
+            }
+        }
+    }
+    // Relative importers are rewritten natively by move() but still count as changed files. They surface
+    // through getReferencingSourceFiles() (alias-only side-effect imports don't, hence the spec scan above).
+    for (const ref of sf.getReferencingSourceFiles())
+        changed.add(ref)
+
+    sf.move(destAbs) // rewrites relative-specifier importers (incl. relative dynamic imports)
+    changed.add(sf) // sf is now the moved file (same node, new path)
+
+    // Re-point each captured alias reference from the new location. specifierFrom yields the alias form
+    // when dest sits under an alias root, else the relative path — one rule covers in-root and out-of-root.
+    for (const { decl, file } of declFixups)
+        decl.setModuleSpecifier(specifierFrom(file, destAbs, prefixes))
+    for (const { lit, file } of litFixups)
+        lit.setLiteralValue(specifierFrom(file, destAbs, prefixes))
+
+    return [...changed]
+}
+
+// Find a top-level named declaration (var/function/class/interface/type/enum) by name.
+// Returns a renameable node, or null if absent/ambiguous-as-unsupported.
+function findNamedDecl(sf: SourceFile, name: string) {
+    return (
+        sf.getVariableDeclaration(name)
+        ?? sf.getFunction(name)
+        ?? sf.getClass(name)
+        ?? sf.getInterface(name)
+        ?? sf.getTypeAlias(name)
+        ?? sf.getEnum(name)
+        ?? null
+    )
+}
+
+// Pure core: rename a top-level symbol across the whole project (type-checker driven, so it
+// rewrites alias imports too and never touches same-named-but-unrelated locals). Returns changed files.
+export function renameInProject(project: Project, fileAbs: string, oldName: string, newName: string): SourceFile[] {
+    const sf = project.getSourceFile(fileAbs)
+    if (!sf)
+        throw new Error(`${fileAbs} not in project`)
+    const decl = findNamedDecl(sf, oldName)
+    if (!decl)
+        throw new Error(`no top-level declaration named '${oldName}' in ${fileAbs}`)
+
+    // Export-alias barrier: `export { old as pub }` decouples the local name from the public name —
+    // importers reference `pub`, not `old`. TS's reference resolver treats both as one symbol, so
+    // ts-morph's rename corrupts importers (`import { pub }` → `import { fresh }`) while the public
+    // name should stay `pub`. Same stance as the barrel barrier in move-symbol: reject rather than
+    // silently break. Rename the public name directly, or rename local+export together by hand.
+    for (const exp of sf.getExportDeclarations()) {
+        for (const spec of exp.getNamedExports()) {
+            if (spec.getAliasNode() && spec.getNameNode().getText() === oldName)
+                throw new Error(`'${oldName}' is exported under the alias '${spec.getAliasNode()!.getText()}' (export { ${oldName} as ${spec.getAliasNode()!.getText()} }); renaming the local name would corrupt importers that reference the public name. Rename '${spec.getAliasNode()!.getText()}' instead, or rewrite the export by hand.`)
+        }
+    }
+
+    // Capture referencing files before rename so we can report them (rename mutates in place).
+    const changed = new Set<SourceFile>([sf])
+    for (const ref of decl.findReferences()) {
+        for (const r of ref.getReferences())
+            changed.add(r.getSourceFile())
+    }
+
+    decl.rename(newName)
+    return [...changed]
+}
+
+// The module specifier B should use to reach a target source file: alias form if the target sits
+// under an alias root, else a relative path. Mirrors what move/rename produce.
+function specifierFrom(from: SourceFile, toAbs: string, prefixes: AliasPrefix[]): string {
+    const alias = toAlias(toAbs, prefixes)
+    if (alias)
+        return alias
+    const to = from.getProject().getSourceFile(toAbs) ?? from.getProject().addSourceFileAtPath(toAbs)
+    return from.getRelativePathAsModuleSpecifierTo(to)
+}
+
+// The local binding a named import introduces. For `delay as _delay` the binding is `_delay`
+// (the alias), not the imported name `delay` — code references the alias, so its symbol is the
+// one usage checks must compare against. Falls back to the name node when there's no alias.
+function bindingNodeOf(ni: { getNameNode: () => Node, getAliasNode: () => Node | undefined }): Node {
+    return ni.getAliasNode() ?? ni.getNameNode()
+}
+
+// Does any identifier inside `scope` resolve (by symbol identity) to the binding `bindingNode`?
+// Symbol identity — not text — is the line that makes `arr.length` (a property access whose `length`
+// has Array.length's symbol) NOT count as a use of an imported binding also named `length`.
+function scopeUsesBinding(scope: Node, bindingNode: Node): boolean {
+    const target = bindingNode.getSymbol()
+    if (!target)
+        return false
+    let used = false
+    scope.forEachDescendant((node, traversal) => {
+        if (used) {
+            traversal.stop()
+            return
+        }
+        if (!TsNode.isIdentifier(node))
+            return
+        // The binding's own declaration node carries the same symbol — it's not a *use*. Skip it so
+        // whole-file scans (dead-import pruning) don't count the import line itself as usage.
+        if (node === bindingNode)
+            return
+        // Skip the property side of `a.b` and the key side of `{ b: ... }` — those names are
+        // member/property symbols, never an imported binding.
+        const parent = node.getParent()
+        if (TsNode.isPropertyAccessExpression(parent) && parent.getNameNode() === node)
+            return
+        if (TsNode.isPropertyAssignment(parent) && parent.getNameNode() === node)
+            return
+        if (node.getSymbol() === target)
+            used = true
+    })
+    return used
+}
+
+// Pure core: move a single exported symbol from A to B. Carries the declaration + the imports it
+// depends on, rewrites every external importer (A→B), and back-imports into A if A still uses it.
+// Throws if the symbol is missing, or if B already exports something with the same name.
+export function moveSymbolInProject(project: Project, fromAbs: string, name: string, toAbs: string): SourceFile[] {
+    const from = project.getSourceFile(fromAbs)
+    if (!from)
+        throw new Error(`${fromAbs} not in project`)
+    const decl = findNamedDecl(from, name)
+    if (!decl)
+        throw new Error(`no top-level declaration named '${name}' in ${fromAbs}`)
+    // Moving a symbol to its own file is a no-op that ts-morph mishandles (removes then re-reads a
+    // forgotten node). Refuse with a clear message rather than leak the internal error.
+    if (fromAbs === toAbs)
+        throw new Error(`source and destination are the same file (${fromAbs}); nothing to move`)
+
+    const to = project.getSourceFile(toAbs) ?? project.createSourceFile(toAbs, '')
+    if (to !== from && findNamedDecl(to, name))
+        throw new Error(`${toAbs} already declares '${name}'`)
+
+    // ── Safety gates: refuse forms we'd otherwise silently half-move into broken code. ──
+    const guardScope = (decl.getKindName() === 'VariableDeclaration'
+        ? (decl as { getVariableStatementOrThrow: () => Node }).getVariableStatementOrThrow()
+        : decl) as Node
+
+    // Gap A: the declaration references a same-file, top-level symbol other than itself. If that symbol
+    // is NOT exported, moving would leave it undefined in B (it can't be imported) — refuse. If it IS
+    // exported, B can import it back from A: collect those names so step 1b adds `import { … } from A`.
+    // Without this back-import the moved declaration references a name that no longer exists in B (TS2304).
+    const siblingDeps = new Set<string>()
+    for (const id of guardScope.getDescendantsOfKind(80 /* Identifier */)) {
+        const parent = id.getParent()
+        if (TsNode.isPropertyAccessExpression(parent) && parent.getNameNode() === id)
+            continue
+        const sym = id.getSymbol()
+        if (!sym)
+            continue
+        for (const d of sym.getDeclarations()) {
+            if (d.getSourceFile() !== from || d === decl)
+                continue
+            const stmt = TsNode.isVariableDeclaration(d) ? d.getVariableStatementOrThrow() : d
+            if (stmt.getParent()?.getKindName() !== 'SourceFile')
+                continue // only top-level declarations matter
+            const exported = TsNode.isExportable(stmt) && stmt.isExported()
+            if (!exported)
+                throw new Error(`'${name}' depends on local symbol '${id.getText()}' (not exported); export it or move them together`)
+            siblingDeps.add(id.getText())
+        }
+    }
+
+    // Gap C: the symbol is re-exported by a barrel (`export { name } from A`). After the move that
+    // barrel still points at A, which no longer has it — an indirect break. Refuse for now.
+    for (const ref of from.getReferencingSourceFiles()) {
+        for (const ed of ref.getExportDeclarations()) {
+            if (ed.getModuleSpecifierSourceFile() === from && ed.getNamedExports().some(ne => ne.getName() === name))
+                throw new Error(`'${name}' is re-exported by ${ref.getFilePath()}; update the barrel first or move it manually`)
+        }
+    }
+
+    // Gap D: the symbol is reached through a namespace import (`import * as A` then `A.name`). We can't
+    // rewrite `A.name` to point at B, so that access would break. Refuse for now.
+    for (const r of decl.findReferences()) {
+        for (const ref of r.getReferences()) {
+            const node = ref.getNode()
+            const parent = node.getParent()
+            if (TsNode.isPropertyAccessExpression(parent) && parent.getNameNode() === node && ref.getSourceFile() !== from)
+                throw new Error(`'${name}' is accessed via a namespace import in ${ref.getSourceFile().getFilePath()}; move it manually`)
+        }
+    }
+
+    // Gap E: the symbol is the file's default export (`export default function name` or
+    // `export { name as default }` / `export default name`). Default importers (`import f from A`)
+    // bind their own local name to A's default slot — we can't know all those local names to rewrite,
+    // and the moved declaration loses its default-ness, so A no longer has a default → TS2306. Refuse.
+    if (TsNode.isExportable(guardScope) && (guardScope as { isDefaultExport: () => boolean }).isDefaultExport())
+        throw new Error(`'${name}' is the default export of ${fromAbs}; default importers bind arbitrary local names that can't be rewritten. Make it a named export first, or move it manually.`)
+    for (const ed of from.getExportDeclarations()) {
+        for (const ne of ed.getNamedExports()) {
+            if (ed.getModuleSpecifierValue()) continue // re-export from elsewhere, not our local symbol
+            if (ne.getNameNode().getText() === name && ne.getAliasNode()?.getText() === 'default')
+                throw new Error(`'${name}' is the default export of ${fromAbs} (export { ${name} as default }); default importers bind arbitrary local names that can't be rewritten. Make it a named export first, or move it manually.`)
+        }
+    }
+
+    // Gap F: the symbol is exported under an alias (`export { name as pub }`). Importers reference the
+    // public name `pub`; after the move the moved declaration is a plain `const name` in B (not exported
+    // under `pub`), and A's `export { name as pub }` now points at a local `import { name } from B` —
+    // which B doesn't export → TS2459. The public-name boundary can't be preserved by a plain move. Refuse.
+    for (const ed of from.getExportDeclarations()) {
+        if (ed.getModuleSpecifierValue()) continue
+        for (const ne of ed.getNamedExports()) {
+            const alias = ne.getAliasNode()?.getText()
+            if (ne.getNameNode().getText() === name && alias && alias !== 'default')
+                throw new Error(`'${name}' is exported under the alias '${alias}' (export { ${name} as ${alias} }); the public name '${alias}' that importers reference can't survive a plain move. Rewrite the export, or move it manually.`)
+        }
+    }
+
+    const prefixes = aliasPrefixes(project)
+
+    // The declaration text to carry. For a variable, the statement is shared across declarators
+    // (`export const a = 1, b = 2`), so we must NOT carry/remove the whole statement — only the
+    // target declarator, reconstructing its own `export const X = ...` so siblings stay untouched.
+    const varStmt: VariableStatement | null = decl.getKindName() === 'VariableDeclaration'
+        ? (decl as { getVariableStatementOrThrow: () => VariableStatement }).getVariableStatementOrThrow()
+        : null
+    const sharedDeclarators = varStmt ? varStmt.getDeclarations().length > 1 : false
+    // decl.getText() for a VariableDeclaration is just `X = ...` (no keyword) — rebuild `export const`.
+    // For a multi-declarator statement we rebuild just the target declarator (siblings stay in A), so
+    // we can't carry the shared statement's JSDoc unambiguously. Otherwise getText(true) keeps the
+    // leading JSDoc with the moved declaration.
+    const declText = varStmt
+        ? sharedDeclarators
+            ? `${varStmt.isExported() ? 'export ' : ''}${varStmt.getDeclarationKind()} ${decl.getText()}`
+            : varStmt.getText(true)
+        : (decl as { getText: (includeJsDoc?: boolean) => string }).getText(true)
+
+    // Which of A's imports does the declaration actually depend on? Decide per binding by symbol
+    // identity over the declaration's scope — this excludes property-name collisions, and naturally
+    // covers named / default / namespace / type-only bindings alike.
+    const depScope = (varStmt ?? decl) as Node
+    const carried: ImportDeclarationStructure[] = []
+    for (const imp of from.getImportDeclarations()) {
+        const struct = imp.getStructure()
+        const keptNamed = imp.getNamedImports().filter(n => scopeUsesBinding(depScope, bindingNodeOf(n)))
+        const dflt = imp.getDefaultImport()
+        const ns = imp.getNamespaceImport()
+        const keepDflt = dflt ? scopeUsesBinding(depScope, dflt) : false
+        const keepNs = ns ? scopeUsesBinding(depScope, ns) : false
+        if (!keptNamed.length && !keepDflt && !keepNs)
+            continue
+        // Relative specifiers must be re-pathed from B; bare/alias carry as-is.
+        let spec = struct.moduleSpecifier
+        if (spec.startsWith('.')) {
+            const target = imp.getModuleSpecifierSourceFile()
+            if (target)
+                spec = specifierFrom(to, target.getFilePath(), prefixes)
+        }
+        carried.push({
+            ...struct,
+            moduleSpecifier: spec,
+            defaultImport: keepDflt ? struct.defaultImport : undefined,
+            namespaceImport: keepNs ? struct.namespaceImport : undefined,
+            namedImports: keptNamed.map(n => n.getStructure()),
+        })
+    }
+
+    // External importers of the symbol (before we mutate) → their files need the A→B rewrite.
+    // CRITICAL: capture the matching import declarations + the moved named-import's structure NOW.
+    // Once the declaration leaves A, A may export nothing and `from`'s importers stop resolving to it
+    // — so a post-removal `getModuleSpecifierSourceFile() === from` check would miss them all.
+    const refFiles = new Set<SourceFile>()
+    const rewrites: { rf: SourceFile, imp: ImportDeclaration, moved: ImportSpecifierStructure, typeOnly: boolean }[] = []
+    for (const ref of decl.findReferences()) {
+        for (const r of ref.getReferences()) {
+            const rf = r.getSourceFile()
+            if (rf !== from)
+                refFiles.add(rf)
+        }
+    }
+    for (const rf of refFiles) {
+        for (const imp of rf.getImportDeclarations()) {
+            if (imp.getModuleSpecifierSourceFile() !== from)
+                continue
+            const ni = imp.getNamedImports().find(n => n.getName() === name)
+            // `import type { F }` carries type-only at the DECLARATION level, not the specifier — capture both.
+            if (ni)
+                rewrites.push({ rf, imp, moved: ni.getStructure(), typeOnly: imp.isTypeOnly() })
+        }
+    }
+    const aStillUses = decl.findReferences().some(ref =>
+        ref.getReferences().some(r => r.getSourceFile() === from && r.getNode() !== (decl as { getNameNode?: () => Node }).getNameNode?.()))
+
+    // 1. Write B: the declaration first, then its carried imports prepended in structured form
+    //    (preserves type-only / namespace / default exactly — no string concatenation).
+    //    If B already has content not ending in a newline, prepend one so the declaration doesn't
+    //    glue onto the previous statement (`Y = 1export const F...` is a syntax error).
+    const existing = to.getFullText()
+    const lead = existing.length && !existing.endsWith('\n') ? '\n' : ''
+    to.insertText(existing.length, `${lead}${declText}\n`)
+    for (const c of carried) {
+        // Merge a carried dependency into B's existing same-module import rather than duplicating the line.
+        const existingImp = to.getImportDeclarations().find(d => d.getModuleSpecifierValue() === c.moduleSpecifier)
+        if (existingImp && !c.defaultImport && !c.namespaceImport && Array.isArray(c.namedImports)) {
+            for (const ni of c.namedImports)
+                existingImp.addNamedImport(ni)
+        }
+        else {
+            to.insertImportDeclaration(0, c)
+        }
+    }
+
+    // 1b. Back-import the exported same-file siblings the moved declaration depends on (Gap A's allowed
+    //     case): `F` stays referencing `helper`, but `helper` lives in A — B must import it from A or
+    //     it's an undefined name (TS2304). Skipped when moving within the same file.
+    if (to !== from && siblingDeps.size) {
+        const aSpec = specifierFrom(to, fromAbs, prefixes)
+        const existingA = to.getImportDeclarations().find(d => d.getModuleSpecifierValue() === aSpec && !d.isTypeOnly())
+        if (existingA) {
+            const have = new Set(existingA.getNamedImports().map(n => n.getName()))
+            for (const s of siblingDeps)
+                if (!have.has(s))
+                    existingA.addNamedImport(s)
+        }
+        else {
+            to.insertImportDeclaration(0, { moduleSpecifier: aSpec, namedImports: [...siblingDeps] })
+        }
+    }
+
+    // 2. Remove the declaration from A. For a multi-declarator statement, remove only this declarator
+    //    so the siblings survive; otherwise remove the whole statement/declaration.
+    if (sharedDeclarators)
+        (decl as { remove: () => void }).remove()
+    else
+        (varStmt ?? decl).remove()
+
+    // 2b. Prune imports A no longer uses. The moved symbol may have been the sole user of a dependency
+    //     import; left behind it's a dead import (TS6133). Re-check whole-file usage AFTER removal, so
+    //     a binding still used by other code in A correctly stays (it was carried to B in parallel).
+    for (const imp of from.getImportDeclarations()) {
+        for (const ni of imp.getNamedImports()) {
+            if (!scopeUsesBinding(from, bindingNodeOf(ni)))
+                ni.remove()
+        }
+        const dflt = imp.getDefaultImport()
+        if (dflt && !scopeUsesBinding(from, dflt))
+            imp.removeDefaultImport()
+        const ns = imp.getNamespaceImport()
+        if (ns && !scopeUsesBinding(from, ns))
+            imp.removeNamespaceImport()
+        if (!imp.getNamedImports().length && !imp.getDefaultImport() && !imp.getNamespaceImport())
+            imp.remove()
+    }
+
+    // 3. Rewrite external importers from the handles captured before mutation: drop the name from the
+    //    A-import (preserving its alias / type-only structure via the saved structure), then re-add it
+    //    under B's specifier — merging into an existing B-import rather than duplicating a same-module line.
+    const toSpecFor = (f: SourceFile) => specifierFrom(f, toAbs, prefixes)
+    for (const { rf, imp, moved, typeOnly } of rewrites) {
+        const bSpec = toSpecFor(rf)
+        const ni = imp.getNamedImports().find(n => n.getName() === name)
+        if (ni) {
+            ni.remove()
+            if (imp.getNamedImports().length === 0 && !imp.getDefaultImport() && !imp.getNamespaceImport())
+                imp.remove()
+        }
+        // Merge only into a B-import of matching type-only-ness (a `type` import can't host a value one).
+        const existingB = rf.getImportDeclarations().find(d => d.getModuleSpecifierValue() === bSpec && d.isTypeOnly() === typeOnly)
+        if (existingB)
+            existingB.addNamedImport(moved)
+        else
+            rf.addImportDeclaration({ moduleSpecifier: bSpec, namedImports: [moved], isTypeOnly: typeOnly })
+    }
+
+    // 4. If A still uses the symbol, back-import it from B.
+    if (aStillUses)
+        from.addImportDeclaration({ moduleSpecifier: specifierFrom(from, toAbs, prefixes), namedImports: [name] })
+
+    return [...new Set<SourceFile>([from, to, ...refFiles])]
+}
+
+export async function moveFile(src: string, dest: string, dry = false): Promise<void> {
+    const project = await openProject()
+    const root = process.cwd()
+    let changed: SourceFile[]
+    try {
+        changed = moveInProject(project, resolve(src), resolve(dest))
+    }
+    catch {
+        console.error(`refactor: ${src} not in tsconfig project (check include globs)`)
+        process.exit(1)
+    }
+
+    console.log(`move ${relative(root, src)} → ${relative(root, dest)}`)
+    console.log(`${changed.length} file(s) ${dry ? 'would change' : 'changed'}:`)
+    for (const f of changed)
+        console.log(`  ${relative(root, f.getFilePath())}`)
+
+    if (dry)
+        return
+    await project.save()
+    console.log('saved. verify: tsc --noEmit')
+}
+
+export async function moveSymbol(from: string, name: string, to: string, dry = false): Promise<void> {
+    const project = await openProject()
+    const root = process.cwd()
+    let changed: SourceFile[]
+    try {
+        changed = moveSymbolInProject(project, resolve(from), name, resolve(to))
+    }
+    catch (e) {
+        console.error(`refactor: ${(e as Error).message}`)
+        process.exit(1)
+    }
+
+    console.log(`move-symbol ${name}: ${relative(root, from)} → ${relative(root, to)}`)
+    console.log(`${changed.length} file(s) ${dry ? 'would change' : 'changed'}:`)
+    for (const f of changed)
+        console.log(`  ${relative(root, f.getFilePath())}`)
+
+    if (dry)
+        return
+    await project.save()
+    console.log('saved. verify: tsc --noEmit')
+}
+
+export async function renameSymbol(file: string, oldName: string, newName: string, dry = false): Promise<void> {
+    const project = await openProject()
+    const root = process.cwd()
+    let changed: SourceFile[]
+    try {
+        changed = renameInProject(project, resolve(file), oldName, newName)
+    }
+    catch (e) {
+        console.error(`refactor: ${(e as Error).message}`)
+        process.exit(1)
+    }
+
+    console.log(`rename ${oldName} → ${newName} (in ${relative(root, file)})`)
+    console.log(`${changed.length} file(s) ${dry ? 'would change' : 'changed'}:`)
+    for (const f of changed)
+        console.log(`  ${relative(root, f.getFilePath())}`)
+
+    if (dry)
+        return
+    await project.save()
+    console.log('saved. verify: tsc --noEmit')
+}