@openrewrite/recipes-nodejs 0.52.0-20261009-102010 → 0.52.1

package/src/migrate/source-map-support/source-map-support-api-source.ts

@@ -0,0 +1,470 @@
+/*
+ * Copyright 2026 the original author or authors.
+ *
+ * Moderne Proprietary. Only for use by Moderne customers under the terms of a commercial contract.
+ */
+
+import {CodeStyle, restyle} from "../code-style";
+
+/** A declaration the migration can write into a file in place of part of source-map-support's API. */
+export type ApiDeclaration =
+    | 'UrlAndMap' | 'Position' | 'CallSiteState' | 'SourceMapSupportOptions' | 'SourceMapSupportEnvironment' | 'CallSite'
+    | 'SourceMapSupportState' | 'installSourceMapSupport' | 'wrapCallSite' | 'getErrorSource' | 'mapSourcePosition'
+    | 'retrieveSourceMap' | 'resetRetrieveHandlers' | 'sourceMapSupportState' | 'retrieveSourceFile'
+    | 'resolveSourceURL' | 'mapEvalOrigin' | 'scriptNameOf' | 'formatCallSite' | 'cloneCallSite'
+    | 'prepareSourceMappedStackTrace';
+
+/** A Node builtin member the generated declarations call, keyed as `module#member`. */
+export type ApiBuiltin = 'module#findSourceMap' | 'module#SourceMap' | 'fs#readFileSync' | 'path#dirname' |
+    'path#resolve' | 'url#fileURLToPath';
+
+/** The declaration each of source-map-support's values stands for. */
+export const VALUE_MEMBERS: ReadonlyMap<string, ApiDeclaration> = new Map<string, ApiDeclaration>([
+    ['install', 'installSourceMapSupport'], ['wrapCallSite', 'wrapCallSite'], ['getErrorSource', 'getErrorSource'],
+    ['mapSourcePosition', 'mapSourcePosition'], ['retrieveSourceMap', 'retrieveSourceMap'],
+    ['resetRetrieveHandlers', 'resetRetrieveHandlers'],
+]);
+
+/** The declaration each of `@types/source-map-support`'s types stands for. */
+export const TYPE_MEMBERS: ReadonlyMap<string, ApiDeclaration> = new Map<string, ApiDeclaration>([
+    ['UrlAndMap', 'UrlAndMap'], ['Position', 'Position'], ['State', 'CallSiteState'],
+    ['Options', 'SourceMapSupportOptions'], ['Environment', 'SourceMapSupportEnvironment'], ['CallSite', 'CallSite'],
+]);
+
+/** How the generated source spells each declaration and builtin, and whether it carries TypeScript's types. */
+interface Spelling {
+    n: (declaration: ApiDeclaration) => string;
+    b: (builtin: ApiBuiltin) => string;
+    t: (typed: string) => string;
+}
+
+interface Template {
+    /** Declarations this one names, which have to be written alongside it. */
+    uses: ApiDeclaration[];
+    builtins?: ApiBuiltin[];
+    typeOnly?: boolean;
+    source: (s: Spelling) => string;
+}
+
+// Written in the default code style, to the rules `restyle` relies on.
+const TEMPLATES: Record<ApiDeclaration, Template> = {
+    UrlAndMap: {
+        uses: [], typeOnly: true,
+        source: ({n}) => `
+/** What \`retrieveSourceMap\` finds for a generated file: its source map, and where that was read from. */
+interface ${n('UrlAndMap')} {
+    url?: string | undefined;
+    map: string | import('module').SourceMapPayload;
+}`
+    },
+    Position: {
+        uses: [], typeOnly: true,
+        source: ({n}) => `
+interface ${n('Position')} {
+    source: string;
+    line: number;
+    column: number;
+    name?: string | null | undefined;
+}`
+    },
+    CallSiteState: {
+        uses: ['Position'], typeOnly: true,
+        source: ({n}) => `
+/** The positions \`wrapCallSite\` passes between the frames of one stack, to name each frame's function. */
+interface ${n('CallSiteState')} {
+    nextPosition: ${n('Position')} | null;
+    curPosition: ${n('Position')} | null;
+}`
+    },
+    SourceMapSupportEnvironment: {
+        uses: [], typeOnly: true,
+        source: ({n}) => `
+type ${n('SourceMapSupportEnvironment')} = 'auto' | 'browser' | 'node';`
+    },
+    CallSite: {
+        uses: [], typeOnly: true,
+        source: ({n}) => `
+type ${n('CallSite')} = NodeJS.CallSite;`
+    },
+    SourceMapSupportOptions: {
+        uses: ['UrlAndMap'], typeOnly: true,
+        source: ({n}) => `
+/** source-map-support's \`install\` options; Node prints uncaught errors and reads inline source maps itself. */
+interface ${n('SourceMapSupportOptions')} {
+    handleUncaughtExceptions?: boolean | undefined;
+    hookRequire?: boolean | undefined;
+    emptyCacheBetweenOperations?: boolean | undefined;
+    environment?: 'auto' | 'browser' | 'node' | undefined;
+    overrideRetrieveFile?: boolean | undefined;
+    overrideRetrieveSourceMap?: boolean | undefined;
+    retrieveFile?(path: string): string | null;
+    retrieveSourceMap?(source: string): ${n('UrlAndMap')} | null;
+}`
+    },
+    SourceMapSupportState: {
+        uses: ['UrlAndMap'], typeOnly: true,
+        builtins: ['module#SourceMap'],
+        source: ({n, b}) => `
+interface ${n('SourceMapSupportState')} {
+    fileHandlers: ((path: string) => string | null)[];
+    mapHandlers: ((source: string) => ${n('UrlAndMap')} | null)[];
+    readFiles: boolean;
+    readMaps: boolean;
+    emptyCaches: boolean;
+    installed: boolean;
+    files: Map<string, string>;
+    maps: Map<string, {url?: string | undefined; map: ${b('module#SourceMap')}; root: string} | null>;
+}`
+    },
+    installSourceMapSupport: {
+        uses: ['SourceMapSupportOptions', 'sourceMapSupportState', 'prepareSourceMappedStackTrace'],
+        source: ({n, t}) => `
+/**
+ * source-map-support's \`install\`, on Node's own source map decoder: stack traces are mapped through the
+ * \`retrieveSourceMap\` and \`retrieveFile\` handlers first, then the \`sourceMappingURL\` of each generated file.
+ */
+function ${n('installSourceMapSupport')}(options${t(`: ${n('SourceMapSupportOptions')}`)} = {})${t(': void')} {
+    const state = ${n('sourceMapSupportState')}();
+    if (options.retrieveFile) {
+        if (options.overrideRetrieveFile) {
+            state.fileHandlers.length = 0;
+            state.readFiles = false;
+        }
+        state.fileHandlers.unshift(options.retrieveFile);
+    }
+    if (options.retrieveSourceMap) {
+        if (options.overrideRetrieveSourceMap) {
+            state.mapHandlers.length = 0;
+            state.readMaps = false;
+        }
+        state.mapHandlers.unshift(options.retrieveSourceMap);
+    }
+    state.emptyCaches = state.emptyCaches || !!options.emptyCacheBetweenOperations;
+    if (!state.installed) {
+        state.installed = true;
+        // Read reflectively, as older versions of @types/node don't declare it.
+        const setSourceMapsEnabled${t(': ((enabled: boolean) => void) | undefined')} = Reflect.get(process, 'setSourceMapsEnabled');
+        setSourceMapsEnabled?.call(process, true);
+        Error.prepareStackTrace = ${n('prepareSourceMappedStackTrace')};
+    }
+}`
+    },
+    wrapCallSite: {
+        uses: ['CallSiteState', 'mapSourcePosition', 'cloneCallSite', 'mapEvalOrigin', 'scriptNameOf'],
+        source: ({n, t}) => `
+/**
+ * A call site reporting its original position, and the original name of the function the next frame calls.
+ * \`state\` is ignored unless it is an object, as when this is passed to \`Array.prototype.map\`.
+ */
+function ${n('wrapCallSite')}(frame${t(': NodeJS.CallSite')}, state${t('?: unknown')})${t(': NodeJS.CallSite')} {
+    const positions${t(`: ${n('CallSiteState')}`)} = typeof state === 'object' && state ? state${t(` as ${n('CallSiteState')}`)} : {nextPosition: null, curPosition: null};
+    if (frame.isNative()) {
+        positions.curPosition = null;
+        return frame;
+    }
+    const source = frame.getFileName() || ${n('scriptNameOf')}(frame);
+    if (source) {
+        const position = ${n('mapSourcePosition')}({source, line: frame.getLineNumber()${t('!')}, column: frame.getColumnNumber()${t('!')} - 1});
+        positions.curPosition = position;
+        const clone = ${n('cloneCallSite')}(frame);
+        const functionName = clone.getFunctionName;
+        return Object.assign(clone, {
+            getFunctionName: () => positions.nextPosition?.name || functionName(),
+            getFileName: () => position.source,
+            getLineNumber: () => position.line,
+            getColumnNumber: () => position.column + 1,
+            getScriptNameOrSourceURL: () => position.source
+        });
+    }
+    const origin = frame.isEval() && frame.getEvalOrigin();
+    if (!origin) return frame;
+    const clone = ${n('cloneCallSite')}(frame);
+    const mapped = ${n('mapEvalOrigin')}(origin);
+    clone.getEvalOrigin = () => mapped;
+    return clone;
+}`
+    },
+    getErrorSource: {
+        uses: ['sourceMapSupportState'],
+        builtins: ['fs#readFileSync'],
+        source: ({n, b, t}) => `
+/** The original source line an error was thrown from, with a caret under its column, as Node prints it. */
+function ${n('getErrorSource')}(error${t(': Error')})${t(': string | null')} {
+    const match = /\\n    at [^(]+ \\((.*):(\\d+):(\\d+)\\)/.exec(error.stack ?? '');
+    if (!match) return null;
+    const [, source, line, column] = match;
+    let contents = ${n('sourceMapSupportState')}().files.get(source${t('!')});
+    if (!contents) {
+        try {
+            contents = ${b('fs#readFileSync')}(source${t('!')}, 'utf8');
+        } catch {
+        }
+    }
+    const code = contents?.split(/\\r\\n|\\r|\\n/)[+line${t('!')} - 1];
+    return code ? \`\${source}:\${line}\\n\${code}\\n\${' '.repeat(+column${t('!')} - 1)}^\` : null;
+}`
+    },
+    mapSourcePosition: {
+        uses: ['Position', 'SourceMapSupportState', 'sourceMapSupportState', 'retrieveSourceMap', 'resolveSourceURL'],
+        builtins: ['module#SourceMap'],
+        source: ({n, b, t}) => `
+/** The original position of a generated one, or the position itself where its source map has none. */
+function ${n('mapSourcePosition')}(position${t(`: ${n('Position')}`)})${t(`: ${n('Position')}`)} {
+    const state = ${n('sourceMapSupportState')}();
+    if (!state.maps.has(position.source)) {
+        const urlAndMap = ${n('retrieveSourceMap')}(position.source);
+        let loaded${t(`: {url?: string | undefined; map: ${b('module#SourceMap')}; root: string} | null`)} = null;
+        if (urlAndMap) {
+            const payload = typeof urlAndMap.map === 'string' ? JSON.parse(urlAndMap.map.replace(/^\\)]}\\x27/, '')) : urlAndMap.map;
+            const root = payload.sourceRoot ? payload.sourceRoot.replace(/\\/?$/, '/') : '';
+            const url = urlAndMap.url;
+            loaded = {url, map: new ${b('module#SourceMap')}(payload), root};
+            payload.sourcesContent?.forEach((contents${t(': string | null')}, i${t(': number')}) => {
+                if (contents) state.files.set(${n('resolveSourceURL')}(url, root + payload.sources[i]), contents);
+            });
+        }
+        state.maps.set(position.source, loaded);
+    }
+    const loaded = state.maps.get(position.source);
+    // Node falls back to the last mapping of an earlier line, where the generated position says more.
+    const entry = loaded?.map.findEntry(position.line - 1, position.column);
+    if (!loaded || !entry || !('originalSource' in entry) || entry.generatedLine !== position.line - 1) return position;
+    return {
+        source: ${n('resolveSourceURL')}(loaded.url, loaded.root + entry.originalSource),
+        line: entry.originalLine + 1,
+        column: entry.originalColumn,
+        name: ${t('(')}entry${t(' as {name?: string})')}.name ?? null
+    };
+}`
+    },
+    retrieveSourceMap: {
+        uses: ['UrlAndMap', 'sourceMapSupportState', 'retrieveSourceFile', 'resolveSourceURL'],
+        builtins: ['module#findSourceMap'],
+        source: ({n, b, t}) => `
+/** The source map of a generated file: from the handlers, its \`sourceMappingURL\`, or what Node read as it loaded. */
+function ${n('retrieveSourceMap')}(source${t(': string')})${t(`: ${n('UrlAndMap')} | null`)} {
+    const state = ${n('sourceMapSupportState')}();
+    for (const handler of state.mapHandlers) {
+        const urlAndMap = handler(source);
+        if (urlAndMap) return urlAndMap;
+    }
+    if (!state.readMaps) return null;
+    const pattern = /(?:\\/\\/[@#][\\s]*sourceMappingURL=([^\\s\\x27\\x22]+)[\\s]*$)|(?:\\/\\*[@#][\\s]*sourceMappingURL=([^\\s*\\x27\\x22]+)[\\s]*(?:\\*\\/)[\\s]*$)/mg;
+    const contents = ${n('retrieveSourceFile')}(source) ?? '';
+    let url${t(': string | undefined')};
+    for (let match = pattern.exec(contents); match; match = pattern.exec(contents)) url = match[1] ?? match[2];
+    if (url && /^data:application\\/json[^,]+base64,/.test(url)) {
+        return {url: source, map: Buffer.from(url.slice(url.indexOf(',') + 1), 'base64').toString()};
+    }
+    const map = url && ${n('retrieveSourceFile')}(url = ${n('resolveSourceURL')}(source, url));
+    if (map) return {url, map};
+    const cached = ${b('module#findSourceMap')}(source);
+    return cached ? {url: source, map: cached.payload} : null;
+}`
+    },
+    resetRetrieveHandlers: {
+        uses: ['sourceMapSupportState'],
+        source: ({n, t}) => `
+/** Drops the \`retrieveFile\` and \`retrieveSourceMap\` handlers \`install\` was given. */
+function ${n('resetRetrieveHandlers')}()${t(': void')} {
+    const state = ${n('sourceMapSupportState')}();
+    state.fileHandlers.length = 0;
+    state.mapHandlers.length = 0;
+    state.readFiles = true;
+    state.readMaps = true;
+}`
+    },
+    sourceMapSupportState: {
+        uses: ['SourceMapSupportState'],
+        source: ({n, t}) => `
+/**
+ * What source-map-support kept between calls, which every file with these functions shares. It hangs off
+ * \`process\` rather than \`globalThis\`, where test runners such as lab would report it as a leaked global.
+ */
+function ${n('sourceMapSupportState')}()${t(`: ${n('SourceMapSupportState')}`)} {
+    const key = Symbol.for('source-map-support');
+    let state${t(`: ${n('SourceMapSupportState')} | undefined`)} = Reflect.get(process, key);
+    if (!state) {
+        state = {
+            fileHandlers: [], mapHandlers: [], readFiles: true, readMaps: true, emptyCaches: false, installed: false,
+            files: new Map(), maps: new Map()
+        };
+        Reflect.set(process, key, state);
+    }
+    return state;
+}`
+    },
+    retrieveSourceFile: {
+        uses: ['sourceMapSupportState'],
+        builtins: ['fs#readFileSync', 'url#fileURLToPath'],
+        source: ({n, b, t}) => `
+function ${n('retrieveSourceFile')}(path${t(': string')})${t(': string | null')} {
+    const state = ${n('sourceMapSupportState')}();
+    for (const handler of state.fileHandlers) {
+        const contents = handler(path);
+        if (contents) return contents;
+    }
+    if (!state.readFiles) return null;
+    path = path.trim();
+    if (path.startsWith('file:')) {
+        try {
+            path = ${b('url#fileURLToPath')}(path);
+        } catch {
+        }
+    }
+    if (!state.files.has(path)) {
+        let contents = '';
+        try {
+            contents = ${b('fs#readFileSync')}(path, 'utf8');
+        } catch {
+        }
+        state.files.set(path, contents);
+    }
+    return state.files.get(path)${t('!')};
+}`
+    },
+    resolveSourceURL: {
+        uses: [],
+        builtins: ['path#dirname', 'path#resolve'],
+        source: ({n, b, t}) => `
+/** \`url\` resolved against the directory of \`file\`, keeping a protocol such as \`file://\` in front. */
+function ${n('resolveSourceURL')}(file${t(': string | undefined')}, url${t(': string')})${t(': string')} {
+    if (!file) return url;
+    const dir = ${b('path#dirname')}(file);
+    const protocol = /^\\w+:\\/\\/[^/]*/.exec(dir)?.[0] ?? '';
+    const start = dir.slice(protocol.length);
+    if (protocol && /^\\/\\w:/.test(start)) {
+        return protocol + '/' + ${b('path#resolve')}(dir.slice(protocol.length + 1), url).replace(/\\\\/g, '/');
+    }
+    return protocol + ${b('path#resolve')}(start, url);
+}`
+    },
+    mapEvalOrigin: {
+        uses: ['mapSourcePosition'],
+        source: ({n, t}) => `
+/** An \`eval\` origin as V8 formats it, with the position of each call site mapped. */
+function ${n('mapEvalOrigin')}(origin${t(': string')})${t(': string')} {
+    let match = /^eval at ([^(]+) \\((.+):(\\d+):(\\d+)\\)$/.exec(origin);
+    if (match) {
+        const position = ${n('mapSourcePosition')}({source: match[2]${t('!')}, line: +match[3]${t('!')}, column: +match[4]${t('!')} - 1});
+        return \`eval at \${match[1]} (\${position.source}:\${position.line}:\${position.column + 1})\`;
+    }
+    match = /^eval at ([^(]+) \\((.+)\\)$/.exec(origin);
+    return match ? \`eval at \${match[1]} (\${${n('mapEvalOrigin')}(match[2]${t('!')})})\` : origin;
+}`
+    },
+    scriptNameOf: {
+        uses: [],
+        source: ({n, t}) => `
+/** The call site's \`getScriptNameOrSourceURL\`, which older versions of @types/node don't declare. */
+function ${n('scriptNameOf')}(frame${t(': NodeJS.CallSite')})${t(': string | null')} {
+    return ${t('(')}frame${t(' as unknown as {getScriptNameOrSourceURL(): string | null})')}.getScriptNameOrSourceURL();
+}`
+    },
+    formatCallSite: {
+        uses: ['scriptNameOf'],
+        source: ({n, t}) => `
+/** V8's \`CallSite.prototype.toString\`, which reads the position through the call site's own methods. */
+function ${n('formatCallSite')}(${t('this: NodeJS.CallSite')})${t(': string')} {
+    let location = '';
+    if (this.isNative()) {
+        location = 'native';
+    } else {
+        const fileName = ${n('scriptNameOf')}(this);
+        if (!fileName && this.isEval()) location = this.getEvalOrigin() + ', ';
+        location += fileName || '<anonymous>';
+        const line = this.getLineNumber();
+        if (line != null) {
+            location += ':' + line;
+            const column = this.getColumnNumber();
+            if (column) location += ':' + column;
+        }
+    }
+    const functionName = this.getFunctionName();
+    const isConstructor = this.isConstructor();
+    if (!(this.isToplevel() || isConstructor)) {
+        let typeName = this.getTypeName();
+        if (typeName === '[object Object]') typeName = 'null';
+        const methodName = this.getMethodName();
+        let call = '';
+        if (functionName) {
+            if (typeName && functionName.indexOf(typeName) !== 0) call += typeName + '.';
+            call += functionName;
+            if (methodName && functionName.indexOf('.' + methodName) !== functionName.length - methodName.length - 1) {
+                call += \` [as \${methodName}]\`;
+            }
+        } else {
+            call += typeName + '.' + (methodName || '<anonymous>');
+        }
+        return \`\${call} (\${location})\`;
+    }
+    if (isConstructor) return \`new \${functionName || '<anonymous>'} (\${location})\`;
+    return functionName ? \`\${functionName} (\${location})\` : location;
+}`
+    },
+    cloneCallSite: {
+        uses: ['formatCallSite'],
+        source: ({n, t}) => `
+/** A copy of a V8 call site whose methods can be replaced, which a call site's own can't. */
+function ${n('cloneCallSite')}(frame${t(': NodeJS.CallSite')})${t(': NodeJS.CallSite')} {
+    const clone${t(': {[name: string]: unknown}')} = {};
+    for (const name of Object.getOwnPropertyNames(Object.getPrototypeOf(frame))) {
+        const member = ${t('(')}frame${t(' as unknown as {[name: string]: () => unknown})')}[name]${t('!')};
+        clone[name] = /^(?:is|get)/.test(name) ? () => member.call(frame) : member;
+    }
+    clone.toString = ${n('formatCallSite')};
+    return clone${t(' as unknown as NodeJS.CallSite')};
+}`
+    },
+    prepareSourceMappedStackTrace: {
+        uses: ['sourceMapSupportState', 'CallSiteState', 'wrapCallSite'],
+        source: ({n, t}) => `
+/** The \`Error.prepareStackTrace\` source-map-support installs, formatting each frame at its original position. */
+function ${n('prepareSourceMappedStackTrace')}(error${t(': Error')}, stack${t(': NodeJS.CallSite[]')})${t(': string')} {
+    const state = ${n('sourceMapSupportState')}();
+    if (state.emptyCaches) {
+        state.files.clear();
+        state.maps.clear();
+    }
+    const positions${t(`: ${n('CallSiteState')}`)} = {nextPosition: null, curPosition: null};
+    const frames${t(': string[]')} = [];
+    for (let i = stack.length - 1; i >= 0; i--) {
+        frames.push('\\n    at ' + ${n('wrapCallSite')}(stack[i]${t('!')}, positions));
+        positions.nextPosition = positions.curPosition;
+    }
+    return \`\${error.name || 'Error'}: \${error.message || ''}\${frames.reverse().join('')}\`;
+}`
+    },
+};
+
+/** The order declarations are written in: the types, the API as source-map-support exports it, then its internals. */
+const ORDER = Object.keys(TEMPLATES) as ApiDeclaration[];
+
+/** `requested`, and every declaration they name, in the order they are written; JavaScript gets no types. */
+export function declarationsFor(requested: Iterable<ApiDeclaration>, typeScript: boolean): ApiDeclaration[] {
+    const needed = new Set<ApiDeclaration>();
+    const visit = (declaration: ApiDeclaration) => {
+        if (needed.has(declaration)) return;
+        needed.add(declaration);
+        TEMPLATES[declaration].uses.forEach(visit);
+    };
+    [...requested].forEach(visit);
+    return ORDER.filter(d => needed.has(d) && (typeScript || !TEMPLATES[d].typeOnly));
+}
+
+/** The builtins `declarations` call, or name as a type in TypeScript. */
+export function builtinsFor(declarations: ApiDeclaration[]): ApiBuiltin[] {
+    return [...new Set(declarations.flatMap(d => TEMPLATES[d].builtins ?? []))]
+        .sort((a, b) => a.localeCompare(b, 'en', {sensitivity: 'base'}));
+}
+
+/** The source of `declarations`, under the names given, in `style`. */
+export function apiSource(declarations: ApiDeclaration[], spelling: {
+    names: (declaration: ApiDeclaration) => string;
+    builtins: (builtin: ApiBuiltin) => string;
+    typeScript: boolean;
+    style: CodeStyle;
+}): string {
+    const s: Spelling = {n: spelling.names, b: spelling.builtins, t: typed => spelling.typeScript ? typed : ''};
+    return restyle(declarations.map(d => TEMPLATES[d].source(s).replace(/^\n/, '')).join('\n\n'), spelling.style);
+}

package/src/migrate/source-map-support/source-map-support-rewrites.ts

@@ -6,6 +6,7 @@
 
 import {Recipe} from "@openrewrite/rewrite";
 import {EnableSourceMapsAtLaunch} from "./enable-source-maps-at-launch";
+import {ReplaceSourceMapSupportApi} from "./replace-source-map-support-api";
 import {ReplaceSourceMapSupportInstall} from "./replace-source-map-support-install";
 import {ReplaceSourceMapSupportRegisterInPackageJson} from "./replace-source-map-support-register-in-package-json";
 import {ReplaceSourceMapSupportRegisterInMochaConfig} from "./replace-source-map-support-register-in-mocha-config";
@@ -16,6 +17,8 @@ export function sourceMapSupportRewriteRecipes(): Recipe[] {
         new ReplaceSourceMapSupportRegisterInPackageJson(),
         new ReplaceSourceMapSupportRegisterInMochaConfig(),
         new ReplaceSourceMapSupportInstall(),
+        // Takes the install() calls whose options the native rewrites can't map.
+        new ReplaceSourceMapSupportApi(),
         // Last of the rewrites: it takes the entry points the in-place rewrite turned down.
         new EnableSourceMapsAtLaunch(),
     ];

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

@@ -6,7 +6,8 @@
 
 import {Column, Cursor, DataTable} from "@openrewrite/rewrite";
 import {isIdentifier, J} from "@openrewrite/rewrite/java";
-import {compilationUnitOf, JavaScriptVisitor, JS, scopeOf, walk} from "@openrewrite/rewrite/javascript";
+import {compilationUnitOf, JS, scopeOf, walk} from "@openrewrite/rewrite/javascript";
+import {BuiltinBindingVisitor} from "../builtin-binding-visitor";
 import {bindingsOf, isModuleScoped, ModuleBindings, requiredModule, stringLiteral} from "../module-bindings";
 import {REGISTER_MODULES} from "./register-flag";
 
@@ -27,6 +28,12 @@ export const NON_INSTALL_MEMBERS = new Set([
     'wrapCallSite', 'getErrorSource', 'mapSourcePosition', 'retrieveSourceMap', 'resetRetrieveHandlers',
 ]);
 
+/** Trees that hold an identifier as a declaration or import rather than a use of it. */
+export const DECLARING_KINDS = new Set<string>([
+    JS.Kind.Import, JS.Kind.ImportClause, JS.Kind.ImportSpecifier, JS.Kind.Alias, JS.Kind.NamedImports,
+    JS.Kind.ExportSpecifier, JS.Kind.BindingElement, JS.Kind.ObjectBindingPattern,
+]);
+
 export const REASONS = {
     partialMapping: "Enabling source maps here would only map the modules loaded after it, where " +
         "`source-map-support` maps every stack frame: this file loads another module first, either as a static " +
@@ -34,13 +41,17 @@ export const REASONS = {
         "`--enable-source-maps` instead — which is what the `package.json` and mocha recipes set where they can — " +
         "or re-run with `allowPartialMapping` enabled to accept the narrower mapping.",
     nonNativeOption: (option: string) => `\`install\` is passed \`${option}\`, which Node's native source maps have ` +
-        "no equivalent for. Node reads a source map from the compiled file's own `//# sourceMappingURL` comment and " +
-        "offers no hook to supply one, so this call has to stay, along with the dependency.",
-    browser: "`install` is configured for a browser environment, which Node's native source maps don't cover. " +
-        "Keep `source-map-support` for the browser bundle.",
+        "no equivalent for. `ReplaceSourceMapSupportApi` writes source-map-support's `install` into the file as " +
+        "`installSourceMapSupport`, on Node's own `SourceMap`, but not for a call passing more than one argument or in " +
+        "a file it can't import Node's builtins into, such as an AMD module. Pass one options object, or bind the " +
+        "file's modules with `import` or `require`.",
+    browser: "`install` is configured for a browser, where Node's source maps don't run; browsers map stack traces " +
+        "in their developer tools. `ReplaceSourceMapSupportApi` removes such a call where it is a statement of its own " +
+        "at the top of the file, which this one isn't. Remove it by hand.",
     member: (name: string) => `\`${name}\` is part of source-map-support's API that Node doesn't expose. ` +
-        "`process.setSourceMapsEnabled(true)` and `--enable-source-maps` only enable mapping; there is no " +
-        "replacement for reading a mapped position or wrapping a call site, so this use has to stay.",
+        "`ReplaceSourceMapSupportApi` writes it into the file, on Node's own `SourceMap`, but not in a file it can't " +
+        "import Node's builtins into, such as an AMD module, nor through a binding a shorthand property also names. " +
+        "Bind the file's modules with `import` or `require`, or spell the property out.",
     localProcess: "`process` here is a local binding rather than Node's, so `process.setSourceMapsEnabled(true)` " +
         "can't be written at this point. Rename the local, or import `process` from `node:process`.",
     bannerString: "A string names `source-map-support`, which looks like code injected into a bundle (a webpack " +
@@ -51,14 +62,21 @@ export const REASONS = {
         "`NODE_OPTIONS=--enable-source-maps` for it.",
     value: "`source-map-support` is used as a value rather than called, so the use can't be rewritten in place. " +
         "Node offers `process.setSourceMapsEnabled(true)` and the `--enable-source-maps` flag, and nothing else.",
-    type: "Types from source-map-support (@types/source-map-support) have no counterpart in Node's API, which is " +
-        "the single `process.setSourceMapsEnabled(boolean)` call. Drop the type or declare a local one.",
+    type: "This type from @types/source-map-support has no counterpart in Node's API, nor is it one of those " +
+        "`ReplaceSourceMapSupportApi` declares in the file (`Options`, `UrlAndMap`, `Position`, `State`, `CallSite`, " +
+        "`Environment`). Drop the type or declare a local one.",
     reExport: "Re-exporting source-map-support makes it part of this module's API. Consumers have to call " +
         "`process.setSourceMapsEnabled(true)` themselves, or the process has to be launched with `--enable-source-maps`.",
     dynamicImport: "Dynamic import of source-map-support, which the automated migration doesn't follow. Call " +
         "`process.setSourceMapsEnabled(true)` instead, as early in the process as possible.",
     nestedRequire: "source-map-support required outside module scope, which the automated migration doesn't follow. " +
         "Move the require to the top of the file or migrate its uses by hand.",
+    assigned: (name: string) => `\`${name}\` of source-map-support is assigned, changing the library for every ` +
+        "module that loads it, which functions written into this file can't stand in for. Remove the assignment, " +
+        "or keep the code it guards from loading source-map-support.",
+    specifierString: "A source-map-support specifier is held as a value, as the `--require` argument of a child " +
+        "process or a test runner's configuration is, rather than loaded here. Pass `--enable-source-maps` to the " +
+        "process instead, or set `NODE_OPTIONS=--enable-source-maps` for it.",
     mock: "Test mocks source-map-support. Once the code under test calls `process.setSourceMapsEnabled(true)` there " +
         "is no module left to mock; assert on `process.sourceMapsEnabled` instead.",
 };
@@ -141,13 +159,64 @@ export function hasOnlyNativeOptions(arg: J | undefined): boolean {
     return nonNativeOption(arg) === undefined;
 }
 
+/** Whether the tree at `cursor` is written to: assigned, incremented or deleted. */
+export function isWriteTarget(cursor: Cursor): boolean {
+    const node = cursor.value as J;
+    const parent = cursor.parentTree()?.value as J | undefined;
+    switch (parent?.kind) {
+        case J.Kind.Assignment:
+        case J.Kind.AssignmentOperation:
+        case JS.Kind.AssignmentOperation:
+            return (parent as J.Assignment).variable === node;
+        case JS.Kind.Delete:
+            return (parent as JS.Delete).expression === node;
+        case J.Kind.Unary:
+            return [J.Unary.Type.PreIncrement, J.Unary.Type.PreDecrement, J.Unary.Type.PostIncrement,
+                J.Unary.Type.PostDecrement].includes((parent as J.Unary).operator.element);
+        default:
+            return false;
+    }
+}
+
+/** Whether an `install()` options literal sets `environment: 'browser'`. */
+export function isBrowserInstall(arg: J | undefined): boolean {
+    if (arg?.kind !== J.Kind.NewClass || (arg as J.NewClass).class) return false;
+    return ((arg as J.NewClass).body?.statements ?? []).some(s => s.element.kind === JS.Kind.PropertyAssignment &&
+        propertyName(s.element as JS.PropertyAssignment) === 'environment' &&
+        stringLiteral((s.element as JS.PropertyAssignment).initializer) === 'browser');
+}
+
+/**
+ * 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.
+ */
+export 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;
+}
+
 /**
  * Base visitor for the source-map-support migration: recognizes `install()` and the `register`
  * entry points through any binding style, and judges whether enabling native source maps at a
  * given point maps everything `source-map-support` would have. The rewrite and the finder share
  * these so they agree on which sites can be migrated.
  */
-export abstract class SourceMapSupportVisitor<P> extends JavaScriptVisitor<P> {
+export abstract class SourceMapSupportVisitor<P> extends BuiltinBindingVisitor<P> {
+    protected readonly migratedModules: ReadonlySet<string> = MODULES;
     protected bindings: ModuleBindings = new Map();
 
     protected override async visitJsCompilationUnit(cu: JS.CompilationUnit, p: P): Promise<J | undefined> {