@openrewrite/recipes-nodejs 0.51.0 → 0.51.2

package/src/migrate/hpagent/swap-hpagent-dependency.ts

@@ -4,35 +4,23 @@
  * Moderne Proprietary. Only for use by Moderne customers under the terms of a commercial contract.
  */
 
-import {ExecutionContext, Option, Recipe, TreeVisitor} from "@openrewrite/rewrite";
-import {getMemberKeyName, isMember, isObject, Json, JsonVisitor} from "@openrewrite/rewrite/json";
-import {anyBeneath, dirOf, isPackageJson, RemoveUnusedDependency} from "../remove-unused-dependency";
-import {insertPaddedAfter, literal, member, memberIndex} from "../json-edits";
-import {ReplaceHpagent} from "./replace-hpagent";
+import {Option, Recipe} from "@openrewrite/rewrite";
+import {changeDependency} from "@openrewrite/rewrite/javascript";
 import {TARGET_MODULE} from "./hpagent-support";
 
-const SECTIONS = ['dependencies', 'devDependencies', 'optionalDependencies', 'peerDependencies'];
-
 /**
  * `https-proxy-agent` 7 is the last major to keep hpagent's Node floor: hpagent supports Node 14 and
  * up, as do `https-proxy-agent` 7 and 8, while 9 requires Node 20.
  */
 const DEFAULT_VERSION = "^7.0.6";
 
-export class SwapHpagentDependency extends RemoveUnusedDependency {
+export class SwapHpagentDependency extends Recipe {
     readonly name = "org.openrewrite.node.migrate.hpagent.swap-hpagent-dependency";
     readonly displayName = "Swap the `hpagent` dependency for `https-proxy-agent`";
-    readonly description = "Replaces `hpagent` with `https-proxy-agent` in each `package.json` that declares it, in the " +
-        "same section and position, so the declaration order is left as it was. Where a source beneath the " +
-        "`package.json` still references hpagent — a usage the migration left in place, a mock, or a bundler " +
-        "configuration naming it — `https-proxy-agent` is added alongside and hpagent kept, since both are then " +
-        "needed. A `package.json` whose sources the migration didn't reach is left alone entirely, rather than " +
-        "gaining a dependency nothing uses. Lock files are not regenerated; run the package manager's install afterwards.";
+    readonly description = "Replaces `hpagent` with `https-proxy-agent` in each `package.json` that declares it, in " +
+        "whichever dependency section declares it, and updates the lock file to match.";
     readonly tags = ["hpagent", "https-proxy-agent"];
 
-    protected readonly module = 'hpagent';
-    protected readonly packages = ['hpagent'];
-
     @Option({
         displayName: "`https-proxy-agent` version",
         description: "The version range to declare for `https-proxy-agent`. The default keeps hpagent's Node 14 " +
@@ -42,58 +30,15 @@ export class SwapHpagentDependency extends RemoveUnusedDependency {
     })
     version?: string;
 
-    /** Mirrors `ReplaceHpagent`'s option, so the scan judges usage by the migration that will actually run. */
-    private readonly migrateSpreadOptions?: boolean;
-
-    constructor(options?: { version?: string; accountForMigration?: boolean; migrateSpreadOptions?: boolean }) {
-        super({accountForMigration: options?.accountForMigration});
-        this.version = options?.version;
-        this.migrateSpreadOptions = options?.migrateSpreadOptions;
-    }
-
-    protected migrationRecipes(): Recipe[] {
-        return [new ReplaceHpagent({migrateSpreadOptions: this.migrateSpreadOptions})];
-    }
-
-    protected override replacementModules(): string[] {
-        return [TARGET_MODULE];
+    constructor(options?: { version?: string }) {
+        super(options);
     }
 
-    async editorWithData(acc: {referencingFiles: string[]; parsedFiles: string[]; replacementFiles: string[]}): Promise<TreeVisitor<any, ExecutionContext>> {
-        const version = this.version ?? DEFAULT_VERSION;
-        return new class extends JsonVisitor<ExecutionContext> {
-            protected async visitDocument(doc: Json.Document, _ctx: ExecutionContext): Promise<Json | undefined> {
-                if (!isPackageJson(doc.sourcePath) || !isObject(doc.value)) return doc;
-                const dir = dirOf(doc.sourcePath);
-                // Nothing beneath was parsed, so there is no telling whether the migration reached it.
-                if (!anyBeneath(dir, acc.parsedFiles)) return doc;
-                const stillUsed = anyBeneath(dir, acc.referencingFiles);
-                // Nothing beneath came to use the replacement, so declaring it would add an unused dependency.
-                if (!anyBeneath(dir, acc.replacementFiles)) return doc;
-
-                const root = doc.value as Json.Object;
-                let changed = false;
-                const members = root.members.map(padded => {
-                    if (!isMember(padded.element)) return padded;
-                    const section = padded.element as Json.Member;
-                    if (!SECTIONS.includes(getMemberKeyName(section) ?? '') || !isObject(section.value)) return padded;
-                    const obj = section.value as Json.Object;
-                    const hpagent = memberIndex(obj, 'hpagent');
-                    // Only a section declaring hpagent needs the replacement, and only where it isn't already there.
-                    if (hpagent < 0 || memberIndex(obj, TARGET_MODULE) >= 0) return padded;
-                    changed = true;
-                    const replacement = member(TARGET_MODULE, literal(version));
-                    const declaration = obj.members[hpagent];
-                    const updated = stillUsed
-                        ? insertPaddedAfter(obj.members, hpagent, replacement as Json)
-                        // Replacing it in place keeps the section's formatting and its declaration order.
-                        : obj.members.map((m, i) => i === hpagent
-                            ? {...m, element: {...replacement, prefix: declaration.element.prefix} as Json}
-                            : m);
-                    return {...padded, element: {...section, value: {...obj, members: updated}} as Json.Member};
-                });
-                return changed ? {...doc, value: {...root, members}} as Json.Document : doc;
-            }
-        };
+    async recipeList(): Promise<Recipe[]> {
+        return [await changeDependency({
+            oldPackageName: 'hpagent',
+            newPackageName: TARGET_MODULE,
+            newVersion: this.version ?? DEFAULT_VERSION
+        })];
     }
 }

package/src/migrate/package-json-support.ts

@@ -0,0 +1,34 @@
+/*
+ * Copyright 2026 the original author or authors.
+ *
+ * Moderne Proprietary. Only for use by Moderne customers under the terms of a commercial contract.
+ */
+
+import {emptyMarkers, randomId} from "@openrewrite/rewrite";
+import {getMemberKeyName, isMember, Json, rightPadded, space} from "@openrewrite/rewrite/json";
+
+export function dirOf(path: string): string {
+    const i = path.lastIndexOf('/');
+    return i < 0 ? '' : path.substring(0, i);
+}
+
+export function isPackageJson(path: string): boolean {
+    return (path === 'package.json' || path.endsWith('/package.json')) && !path.includes('node_modules/');
+}
+
+export function anyBeneath(dir: string, files: string[]): boolean {
+    return files.some(file => dir === '' || file.startsWith(dir + '/'));
+}
+
+/** Removes members named in `keys`, handing the removed last member's trailing space to the one before it. */
+export function removeMembers(obj: Json.Object, keys: Set<string>): Json.Object {
+    const kept = obj.members.filter(rp => !(isMember(rp.element) && keys.has(getMemberKeyName(rp.element as Json.Member) ?? '')));
+    if (kept.length === obj.members.length) return obj;
+    if (kept.length === 0) {
+        const empty: Json.Empty = {kind: Json.Kind.Empty, id: randomId(), prefix: space(''), markers: emptyMarkers};
+        return {...obj, members: [rightPadded(empty, space(''))]};
+    }
+    const closing = obj.members[obj.members.length - 1].after;
+    kept[kept.length - 1] = {...kept[kept.length - 1], after: closing};
+    return {...obj, members: kept};
+}

package/src/migrate/path/remove-path-dependency.ts

@@ -9,7 +9,7 @@ import {getMemberKeyName, isObject, Json, JsonVisitor} from "@openrewrite/rewrit
 import {JS, walk} from "@openrewrite/rewrite/javascript";
 import {J} from "@openrewrite/rewrite/java";
 import {PlainText} from "@openrewrite/rewrite/text";
-import {anyBeneath, dirOf, isPackageJson, removeMembers} from "../remove-unused-dependency";
+import {anyBeneath, dirOf, isPackageJson, removeMembers} from "../package-json-support";
 import {requiredModule, stringLiteral} from "../module-bindings";
 
 const SECTIONS = new Set(['dependencies', 'devDependencies', 'optionalDependencies', 'peerDependencies']);

package/src/migrate/process-exit-code.ts

@@ -19,8 +19,8 @@ export class AvoidImplicitCoercionOfExitCode extends Recipe {
     readonly tags: string[] = ["DEP0164"];
 
     async editor(): Promise<TreeVisitor<any, ExecutionContext>> {
-        return check(usesType("global.NodeJS.Process"), new class extends JavaScriptVisitor<ExecutionContext> {
-            exitMatcher = new MethodMatcher("Process exit(..)");
+        return check(usesType("NodeJS.Process"), new class extends JavaScriptVisitor<ExecutionContext> {
+            exitMatcher = new MethodMatcher("NodeJS.Process exit(..)");
 
             private isProcessExitCodeAccess(fieldAccess: J.FieldAccess): boolean {
                 if (fieldAccess.name.element.simpleName !== "exitCode") {
@@ -33,7 +33,7 @@ export class AvoidImplicitCoercionOfExitCode extends Recipe {
 
                     if (idType?.kind === Type.Kind.Class) {
                         const classType = idType as Type.Class;
-                        return classType.fullyQualifiedName === "global.NodeJS.Process";
+                        return classType.fullyQualifiedName === "NodeJS.Process";
                     }
                 }
 

package/src/migrate/process-features-tls.ts

@@ -17,7 +17,7 @@ export class RemoveUsageOfProcessFeaturesTlsConstants extends Recipe {
     readonly tags: string[] = ["DEP0189"];
 
     async editor(): Promise<TreeVisitor<any, ExecutionContext>> {
-        return check(usesType("global.NodeJS.Process"), new class extends JavaScriptVisitor<ExecutionContext> {
+        return check(usesType("NodeJS.Process"), new class extends JavaScriptVisitor<ExecutionContext> {
             protected async visitExpression(expression: Expression, p: ExecutionContext): Promise<J | undefined> {
                 const ret = await super.visitExpression(expression, p) as Expression;
                 if (await pattern`process.features.tls_alpn`.match(ret, this.cursor)

package/src/migrate/prop-types/remove-prop-types.ts

@@ -11,7 +11,7 @@ import {declarationsOf, JavaScriptVisitor, JS, maybeUnbind, walk as walkTree} fr
 import {PlainText} from "@openrewrite/rewrite/text";
 import * as semver from "semver";
 import {bindingsOf, importModule, requiredModule, stringLiteral} from "../module-bindings";
-import {anyBeneath, dirOf, isPackageJson, removeMembers} from "../remove-unused-dependency";
+import {anyBeneath, dirOf, isPackageJson, removeMembers} from "../package-json-support";
 
 const MODULE = 'prop-types';
 const JSX_RUNTIMES = new Set(['react', 'preact', 'preact/compat']);

package/src/migrate/remove-dependencies.ts

@@ -0,0 +1,21 @@
+/*
+ * Copyright 2026 the original author or authors.
+ *
+ * Moderne Proprietary. Only for use by Moderne customers under the terms of a commercial contract.
+ */
+
+import {Recipe} from "@openrewrite/rewrite";
+import {removeDependency} from "@openrewrite/rewrite/javascript";
+
+/**
+ * Removes a library's packages from every `package.json` that declares them, updating the lock file
+ * to match, through the native dependency recipe.
+ */
+export abstract class RemoveDependencies extends Recipe {
+    /** The packages removed together, e.g. the library and its `@types`. */
+    protected abstract readonly packages: string[];
+
+    async recipeList(): Promise<Recipe[]> {
+        return Promise.all(this.packages.map(packageName => removeDependency({packageName})));
+    }
+}

package/src/migrate/server-response-write-header.ts

@@ -0,0 +1,51 @@
+/*
+ * Copyright 2026 the original author or authors.
+ *
+ * Moderne Proprietary. Only for use by Moderne customers under the terms of a commercial contract.
+ */
+import {check, ExecutionContext, or, Recipe, TreeVisitor} from "@openrewrite/rewrite";
+import {JavaScriptVisitor, template, usesType} from "@openrewrite/rewrite/javascript";
+import {J, Type} from "@openrewrite/rewrite/java";
+
+export class ReplaceServerResponseWriteHeader extends Recipe {
+    readonly name = "org.openrewrite.node.migrate.http.replace-server-response-write-header"
+    readonly displayName: string = "Replace `ServerResponse.writeHeader()` with `writeHead()`";
+    readonly description: string = "`ServerResponse.prototype.writeHeader()` was an undocumented alias for `writeHead()` " +
+        "that was deprecated in Node.js 11 (DEP0063) and removed in Node.js 26. The signatures are identical.";
+    readonly tags: string[] = ["DEP0063"];
+
+    async editor(): Promise<TreeVisitor<any, ExecutionContext>> {
+        return check(or(
+            usesType("http.ServerResponse"),
+            usesType("node:http.ServerResponse"),
+        ), new class extends JavaScriptVisitor<ExecutionContext> {
+
+            private isServerResponseType(type: Type | undefined): boolean {
+                if (!type) return false;
+                if (type.kind === Type.Kind.Class) {
+                    const fqn = (type as Type.Class).fullyQualifiedName;
+                    return fqn === "http.ServerResponse" || fqn === "node:http.ServerResponse";
+                }
+                if (type.kind === Type.Kind.Parameterized) {
+                    return this.isServerResponseType((type as Type.Parameterized).type);
+                }
+                return false;
+            }
+
+            protected async visitMethodInvocation(method: J.MethodInvocation, p: ExecutionContext): Promise<J | undefined> {
+                const m = await super.visitMethodInvocation(method, p) as J.MethodInvocation;
+
+                if (m.name.simpleName !== "writeHeader" || !m.select) {
+                    return m;
+                }
+                if (!this.isServerResponseType(m.select.element.type)) {
+                    return m;
+                }
+
+                const target = m.select.element;
+                const args = m.arguments.elements;
+                return await template`${target}.writeHead(${args})`.apply(m, this.cursor);
+            }
+        });
+    }
+}

package/src/migrate/source-map-support/enable-source-maps-at-launch.ts

@@ -0,0 +1,289 @@
+/*
+ * Copyright 2026 the original author or authors.
+ *
+ * Moderne Proprietary. Only for use by Moderne customers under the terms of a commercial contract.
+ */
+
+import {ExecutionContext, ScanningRecipe, Tree, TreeVisitor} from "@openrewrite/rewrite";
+import {J} from "@openrewrite/rewrite/java";
+import {JavaScriptVisitor, JS, maybeUnbind} from "@openrewrite/rewrite/javascript";
+import {getMemberKeyName, isLiteral, isMember, isObject, Json, JsonVisitor} from "@openrewrite/rewrite/json";
+import {PlainText} from "@openrewrite/rewrite/text";
+import {dirOf, isPackageJson} from "../package-json-support";
+import {addSourceMapsFlag, launchesNode, REGISTER_MODULES, shebangWithSourceMapsFlag} from "./register-flag";
+import {isSourceMapSupport, SourceMapSupportVisitor, sourcePathOf, stringLiteral} from "./source-map-support-support";
+
+interface Accumulator {
+    /** Files holding an `install()` or `register` entry point the in-place rewrite declines. */
+    declined: string[];
+    /** `bin` targets each `package.json` declares, as repo-relative paths. */
+    binTargets: string[];
+    /** Files whose shebang can carry Node's flags. */
+    rewritableShebangs: string[];
+    /** Packages with a script that runs Node directly, which can take the flag. */
+    launchableScripts: string[];
+    /** Every `package.json` directory, so a source can be attributed to its package. */
+    packageDirs: string[];
+}
+
+/** The nearest enclosing directory that is a package, for a repo-relative path. */
+function packageOf(path: string, packageDirs: string[]): string | undefined {
+    const candidates = packageDirs.filter(dir => dir === '' || path.startsWith(dir + '/'));
+    return candidates.sort((a, b) => b.length - a.length)[0];
+}
+
+function joinPath(dir: string, rest: string): string {
+    const normalized = rest.replace(/^\.\//, '');
+    return dir === '' ? normalized : `${dir}/${normalized}`;
+}
+
+export class EnableSourceMapsAtLaunch extends ScanningRecipe<Accumulator> {
+    readonly name = "org.openrewrite.node.migrate.source-map-support.enable-source-maps-at-launch";
+    readonly displayName = "Enable native source maps at launch and drop `source-map-support`";
+    readonly description = "Where `source-map-support` is installed too late for `process.setSourceMapsEnabled(true)` " +
+        "to stand in for it — in an ES module, every `import` is evaluated before any statement runs, so the call " +
+        "would only map what loads after it — this puts `--enable-source-maps` on whatever launches the process " +
+        "instead, which Node applies before the first module loads. The flag goes into the package's `bin` shebang " +
+        "(as `#!/usr/bin/env -S node --enable-source-maps`) and into any `package.json` script that runs `node` or " +
+        "`mocha` directly. The `install()` call and `register` import are then redundant and are removed, rather " +
+        "than replaced by a call that would map less. A package with no launcher this recipe can reach is left " +
+        "alone and reported by `FindSourceMapSupportManualMigrations`.";
+    readonly tags = ["source-map-support"];
+
+    initialValue(_ctx: ExecutionContext): Accumulator {
+        return {declined: [], binTargets: [], rewritableShebangs: [], launchableScripts: [], packageDirs: []};
+    }
+
+    async scanner(acc: Accumulator): Promise<TreeVisitor<any, ExecutionContext>> {
+        const js = new class extends SourceMapSupportVisitor<ExecutionContext> {
+            protected override async visitShebang(shebang: JS.Shebang, p: ExecutionContext): Promise<J | undefined> {
+                if (shebangWithSourceMapsFlag(shebang.text)) acc.rewritableShebangs.push(sourcePathOf(this.cursor));
+                return super.visitShebang(shebang, p);
+            }
+
+            protected override async visitImportDeclaration(jsImport: JS.Import, p: ExecutionContext): Promise<J | undefined> {
+                if (!jsImport.importClause && REGISTER_MODULES.has(stringLiteral(jsImport.moduleSpecifier?.element) ?? '')) {
+                    this.recordIfDeclined();
+                }
+                return super.visitImportDeclaration(jsImport, p);
+            }
+
+            protected override async visitMethodInvocation(method: J.MethodInvocation, p: ExecutionContext): Promise<J | undefined> {
+                if (this.isInstall(method) || isRegisterRequire(method)) this.recordIfDeclined();
+                return super.visitMethodInvocation(method, p);
+            }
+
+            /** Only a site the in-place rewrite turns down is this recipe's business. */
+            private recordIfDeclined(): void {
+                if (this.mapsEverythingLoaded()) return;
+                const path = sourcePathOf(this.cursor);
+                if (!acc.declined.includes(path)) acc.declined.push(path);
+            }
+        };
+
+        const json = new class extends JsonVisitor<ExecutionContext> {
+            protected override async visitDocument(doc: Json.Document, p: ExecutionContext): Promise<Json | undefined> {
+                if (!isPackageJson(doc.sourcePath) || !isObject(doc.value)) return doc;
+                const dir = dirOf(doc.sourcePath);
+                if (!acc.packageDirs.includes(dir)) acc.packageDirs.push(dir);
+                const root = doc.value as Json.Object;
+                for (const padded of root.members) {
+                    if (!isMember(padded.element)) continue;
+                    const member = padded.element as Json.Member;
+                    const key = getMemberKeyName(member) ?? '';
+                    if (key === 'bin') {
+                        for (const target of binTargetsOf(member.value)) acc.binTargets.push(joinPath(dir, target));
+                    } else if (key === 'scripts' && isObject(member.value)) {
+                        const launchable = (member.value as Json.Object).members.some(entry => {
+                            if (!isMember(entry.element)) return false;
+                            const value = (entry.element as Json.Member).value;
+                            return isLiteral(value) && typeof value.value === 'string' && launchesNode(value.value);
+                        });
+                        if (launchable && !acc.launchableScripts.includes(dir)) acc.launchableScripts.push(dir);
+                    }
+                }
+                return doc;
+            }
+        };
+
+        return new class extends TreeVisitor<Tree, ExecutionContext> {
+            protected override async accept(tree: Tree, p: ExecutionContext): Promise<Tree | undefined> {
+                if (tree.kind === JS.Kind.CompilationUnit) return js.visit(tree, p);
+                if (tree.kind === Json.Kind.Document) return json.visit(tree, p);
+                if (tree.kind === PlainText.Kind.PlainText) {
+                    const text = tree as PlainText;
+                    const first = text.text.split('\n', 1)[0];
+                    if (shebangWithSourceMapsFlag(first)) acc.rewritableShebangs.push(text.sourcePath);
+                }
+                return tree;
+            }
+        };
+    }
+
+    async editorWithData(acc: Accumulator): Promise<TreeVisitor<any, ExecutionContext>> {
+        const packageOfPath = (path: string) => enclosingPackage(path, acc.packageDirs);
+
+        // A package can take the flag if a script runs Node, or if a shebang this recipe can rewrite
+        // belongs to it — either the declining file's own or one its `bin` points at.
+        const shebangsFor = (dir: string) => acc.rewritableShebangs.filter(path =>
+            packageOfPath(path) === dir &&
+            (acc.declined.includes(path) || acc.binTargets.includes(path)));
+
+        const declinedPackages = new Set(acc.declined.map(packageOfPath));
+        const flagged = new Set([...declinedPackages].filter(dir =>
+            acc.launchableScripts.includes(dir) || shebangsFor(dir).length > 0));
+
+        const removeSites = new Set(acc.declined.filter(path => flagged.has(packageOfPath(path))));
+        const shebangsToFlag = new Set([...flagged].flatMap(shebangsFor));
+        // A shebang already puts the flag on the process this package launches, so its scripts —
+        // which may run unrelated tools — are left as they are.
+        const scriptPackages = new Set([...flagged].filter(dir => shebangsFor(dir).length === 0));
+
+        const js = new class extends JavaScriptVisitor<ExecutionContext> {
+            protected override async visitJsCompilationUnit(cu: JS.CompilationUnit, p: ExecutionContext): Promise<J | undefined> {
+                const flagShebang = shebangsToFlag.has(cu.sourcePath);
+                const removeHere = removeSites.has(cu.sourcePath);
+                if (!flagShebang && !removeHere) return cu;
+
+                let statements = cu.statements;
+                if (flagShebang) {
+                    statements = statements.map(padded => {
+                        if (padded.element.kind !== JS.Kind.Shebang) return padded;
+                        const flagged = shebangWithSourceMapsFlag((padded.element as JS.Shebang).text);
+                        return flagged ? {...padded, element: {...padded.element, text: flagged} as JS.Shebang} : padded;
+                    });
+                }
+                if (removeHere) {
+                    statements = withoutStatements(statements, s => isRedundantEntryPoint(s));
+                }
+                const result = statements === cu.statements ? cu : {...cu, statements} as JS.CompilationUnit;
+                const visited = await super.visitJsCompilationUnit(result, p) as JS.CompilationUnit;
+                if (removeHere) {
+                    // The launch flag covers the whole process, so nothing needs the module any more.
+                    maybeUnbind(this, {module: 'source-map-support'});
+                    maybeUnbind(this, {module: 'source-map-support', member: 'install'});
+                }
+                return visited;
+            }
+        };
+
+        const json = new class extends JsonVisitor<ExecutionContext> {
+            protected override async visitDocument(doc: Json.Document, p: ExecutionContext): Promise<Json | undefined> {
+                if (!isPackageJson(doc.sourcePath) || !isObject(doc.value)) return doc;
+                if (!scriptPackages.has(dirOf(doc.sourcePath))) return doc;
+                const root = doc.value as Json.Object;
+                let changed = false;
+                const members = root.members.map(padded => {
+                    if (!isMember(padded.element)) return padded;
+                    const member = padded.element as Json.Member;
+                    if (getMemberKeyName(member) !== 'scripts' || !isObject(member.value)) return padded;
+                    const scripts = member.value as Json.Object;
+                    let sectionChanged = false;
+                    const entries = scripts.members.map(entry => {
+                        if (!isMember(entry.element)) return entry;
+                        const script = entry.element as Json.Member;
+                        const value = script.value;
+                        if (!isLiteral(value) || typeof value.value !== 'string') return entry;
+                        const updated = addSourceMapsFlag(value.value);
+                        if (updated === value.value) return entry;
+                        sectionChanged = true;
+                        return {
+                            ...entry,
+                            element: {...script, value: {...value, value: updated, source: JSON.stringify(updated)}} as Json.Member
+                        };
+                    });
+                    if (!sectionChanged) return padded;
+                    changed = true;
+                    return {...padded, element: {...member, value: {...scripts, members: entries}} as Json.Member};
+                });
+                return changed ? {...doc, value: {...root, members}} as Json.Document : doc;
+            }
+        };
+
+        return new class extends TreeVisitor<Tree, ExecutionContext> {
+            protected override async accept(tree: Tree, p: ExecutionContext): Promise<Tree | undefined> {
+                if (tree.kind === JS.Kind.CompilationUnit) return js.visit(tree, p);
+                if (tree.kind === Json.Kind.Document) return json.visit(tree, p);
+                if (tree.kind === PlainText.Kind.PlainText) {
+                    const text = tree as PlainText;
+                    if (!shebangsToFlag.has(text.sourcePath)) return tree;
+                    const lines = text.text.split('\n');
+                    const flagged = shebangWithSourceMapsFlag(lines[0]);
+                    if (!flagged) return tree;
+                    return {...text, text: [flagged, ...lines.slice(1)].join('\n')} as PlainText;
+                }
+                return tree;
+            }
+        };
+    }
+}
+
+/**
+ * Drops the statements `remove` selects, handing the first of a removed run its successor's place
+ * in the layout, so the blank line that separated it from what came before isn't left behind. Only
+ * the whitespace moves: a comment sits in the prefix of the statement it documents, so taking the
+ * successor's prefix wholesale would delete the comment that belongs to it.
+ */
+function withoutStatements(statements: J.RightPadded<any>[], remove: (s: J) => boolean): J.RightPadded<any>[] {
+    const kept: J.RightPadded<any>[] = [];
+    let pendingWhitespace: string | undefined;
+    for (const padded of statements) {
+        if (remove(padded.element)) {
+            pendingWhitespace ??= (padded.element.prefix as J.Space).whitespace;
+            continue;
+        }
+        kept.push(pendingWhitespace === undefined ? padded : {
+            ...padded,
+            element: {...padded.element, prefix: {...padded.element.prefix, whitespace: pendingWhitespace}}
+        });
+        pendingWhitespace = undefined;
+    }
+    return kept;
+}
+
+/** The innermost package a repo-relative path belongs to, of those the scan saw. */
+function enclosingPackage(path: string, packageDirs: string[]): string {
+    return packageOf(path, packageDirs) ?? '';
+}
+
+/** `require('source-map-support/register')`, which loads the module for its side effect alone. */
+function isRegisterRequire(m: J.MethodInvocation): boolean {
+    return !m.select && m.name.simpleName === 'require' &&
+        REGISTER_MODULES.has(stringLiteral(m.arguments.elements[0]?.element) ?? '');
+}
+
+/** Whether a top-level statement exists only to install source-map-support. */
+function isRedundantEntryPoint(statement: J): boolean {
+    if (statement.kind === JS.Kind.Import) {
+        const imp = statement as JS.Import;
+        return !imp.importClause && isSourceMapSupport(stringLiteral(imp.moduleSpecifier?.element));
+    }
+    const expression = statement.kind === JS.Kind.ExpressionStatement
+        ? (statement as JS.ExpressionStatement).expression
+        : statement;
+    const call = expression?.kind === JS.Kind.Await ? (expression as JS.Await).expression : expression;
+    if (call?.kind !== J.Kind.MethodInvocation) return false;
+    const m = call as J.MethodInvocation;
+    if (isRegisterRequire(m)) return true;
+    if (m.name.simpleName !== 'install') return false;
+    const select = m.select?.element;
+    return select?.kind === J.Kind.MethodInvocation
+        ? isSourceMapSupport(requiredModuleOf(select as J.MethodInvocation))
+        : select !== undefined;
+}
+
+function requiredModuleOf(m: J.MethodInvocation): string | undefined {
+    return !m.select && m.name.simpleName === 'require'
+        ? stringLiteral(m.arguments.elements[0]?.element)
+        : undefined;
+}
+
+function binTargetsOf(value: Json.Value): string[] {
+    if (isLiteral(value)) return typeof value.value === 'string' ? [value.value] : [];
+    if (!isObject(value)) return [];
+    return (value as Json.Object).members.flatMap(padded => {
+        if (!isMember(padded.element)) return [];
+        const entry = (padded.element as Json.Member).value;
+        return isLiteral(entry) && typeof entry.value === 'string' ? [entry.value] : [];
+    });
+}

package/src/migrate/source-map-support/migrate-source-map-support-to-native.ts

@@ -14,17 +14,22 @@ export class MigrateSourceMapSupportToNative extends Recipe {
     readonly displayName = "Migrate `source-map-support` to Node.js native source maps";
     readonly description = "Replaces the `source-map-support` package with Node.js's built-in source map support. " +
         "Where Node is launched from `package.json` scripts or mocha/ava configuration, `source-map-support/register` becomes " +
-        "the `--enable-source-maps` flag; in code, `install()` and `register` imports become `process.setSourceMapsEnabled(true)`. " +
+        "the `--enable-source-maps` flag; in code, `install()` and `register` imports become " +
+        "`process.setSourceMapsEnabled(true)` where that maps everything the module loads. Where it would not " +
+        "— in an ES module every `import` is evaluated before any statement runs — the flag goes on the " +
+        "launcher instead, in the package's `bin` shebang or a `node` script, and the entry point is removed " +
+        "as redundant. " +
         "Uses with no native equivalent (custom `retrieveSourceMap`, browser bundles, webpack banners) are left in place, and " +
-        "the dependency is removed from each `package.json` that no longer needs it. Everything left in place is " +
-        "recorded in the `SourceMapSupportManualMigrationSteps` data table with a suggested replacement.";
+        "the dependency is removed from each `package.json` that declares it, with the lock file updated to match. " +
+        "Everything left in place is recorded in the `SourceMapSupportManualMigrationSteps` data table with a " +
+        "suggested replacement, and has to be migrated before building, since the dependency is removed regardless.";
     readonly tags = ["source-map-support"];
 
     async recipeList(): Promise<Recipe[]> {
         return [
             ...sourceMapSupportRewriteRecipes(),
             new FindSourceMapSupportManualMigrations(),
-            new RemoveUnusedSourceMapSupportDependency({accountForMigration: true}),
+            new RemoveUnusedSourceMapSupportDependency(),
         ];
     }
 }

package/src/migrate/source-map-support/register-flag.ts

@@ -30,6 +30,54 @@ function commandOf(segment: string): string | undefined {
     return undefined;
 }
 
+/** A `#!/usr/bin/env node` line, which `env -S` lets carry Node's own flags. */
+const SHEBANG = /^#!(\s*\S*\/env\s+)(-S\s+)?node(?=\s|$)(.*)$/;
+
+const ENABLE_FLAG = '--enable-source-maps';
+
+export function hasSourceMapsFlag(text: string): boolean {
+    return new RegExp(`(^|\\s)${ENABLE_FLAG}(\\s|$)`).test(text);
+}
+
+/**
+ * Whether any part of a shell command launches this package's own code under Node. An inline
+ * `node -e` program and a `node_modules/...` entry point are Node processes too, but neither loads
+ * the module whose entry point is being removed, so neither is a launcher worth flagging.
+ */
+export function launchesNode(script: string): boolean {
+    return script.split(/(\s*(?:&&|\|\||;|\|)\s*)/).some((part, i) => {
+        if (i % 2 === 1 || !NODE_FLAG_COMMANDS.has(commandOf(part) ?? '')) return false;
+        if (/(^|\s)(?:-e|--eval|-p|--print)(?=\s|$)/.test(part)) return false;
+        return !/(^|\s)node_modules\//.test(part);
+    });
+}
+
+/**
+ * Adds `--enable-source-maps` to each part of a shell command that runs Node or mocha, so the flag
+ * is in place before any module loads. Parts running anything else are left alone, since a flag
+ * they don't recognize would fail them.
+ */
+export function addSourceMapsFlag(script: string): string {
+    const parts = script.split(/(\s*(?:&&|\|\||;|\|)\s*)/);
+    return parts.map((part, i) => {
+        if (i % 2 === 1 || !NODE_FLAG_COMMANDS.has(commandOf(part) ?? '') || hasSourceMapsFlag(part)) return part;
+        // Straight after the command, where Node's own flags have to sit: anything later is the script's.
+        return part.replace(/(^|\s)((?:\S*[\\/])?(?:node|mocha|_mocha))(?=\s|$)/, `$1$2 ${ENABLE_FLAG}`);
+    }).join('');
+}
+
+/**
+ * The shebang with `--enable-source-maps` added, or undefined where the line isn't a plain
+ * `env node` shebang. `env -S` is what allows an argument at all; without it the kernel hands
+ * `node --enable-source-maps` to `env` as a single program name.
+ */
+export function shebangWithSourceMapsFlag(line: string): string | undefined {
+    const match = SHEBANG.exec(line);
+    if (!match || hasSourceMapsFlag(line)) return undefined;
+    const [, env, dashS, rest] = match;
+    return `#!${env}${dashS ?? '-S '}node ${ENABLE_FLAG}${rest}`;
+}
+
 /**
  * Replaces `-r source-map-support/register` with `--enable-source-maps` in each part of a shell
  * command that runs Node or mocha. Parts that run anything else are left alone, since a flag they