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

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

@@ -4,16 +4,222 @@
  * Moderne Proprietary. Only for use by Moderne customers under the terms of a commercial contract.
  */
 
-import {Column, DataTable, emptyMarkers, randomId} from "@openrewrite/rewrite";
+import {Column, Cursor, DataTable, emptyMarkers, randomId} from "@openrewrite/rewrite";
 import {emptySpace, isIdentifier, J, rightPadded, space} from "@openrewrite/rewrite/java";
-import {JS, walk} from "@openrewrite/rewrite/javascript";
-import {stringLiteral} from "../module-bindings";
+import {bindingNames, declarationsOf, JS, scopeOf, walk} from "@openrewrite/rewrite/javascript";
+import {CodeStyle, DEFAULT_CODE_STYLE, indented} from "../code-style";
+import {bindingsOf, importModule, ModuleBindings, requiredModule, stringLiteral} from "../module-bindings";
 
-export {bindingsOf, isModuleScoped, sourcePathOf, stringLiteral} from "../module-bindings";
+export {sourcePathOf, stringLiteral} from "../module-bindings";
 export type {ModuleBindings} from "../module-bindings";
 
 export const HPAGENT_MODULES = new Set(['hpagent']);
 
+/** `require('hpagent')`, also when cast as in `require('hpagent') as typeof import('hpagent')`. */
+export function isHpagentRequire(e: J | undefined): boolean {
+    const call = e?.kind === JS.Kind.As ? (e as JS.As).left.element : e;
+    return HPAGENT_MODULES.has(requiredModule(call) ?? '');
+}
+
+/**
+ * What a file's hpagent imports and requires bind, and the id of the scope each binds in: the
+ * compilation unit for a top-level binding, or the block a `const {...} = require('hpagent')` sits in,
+ * as when a CLI requires the proxy agent only once it knows a proxy is configured.
+ */
+export interface HpagentBindings {
+    bindings: ModuleBindings;
+    scopes: Map<string, string>;
+    /** The `require` calls these bindings come from, so a report can tell a shape it doesn't follow. */
+    requires: Set<string>;
+    /** Names a `require` binds, which the rewrite moves itself since `maybeRebind` moves only imports. */
+    requireBound: Set<string>;
+    /** Names a default import binds, which has to become a namespace import: `https-proxy-agent` has no default export. */
+    defaults: Set<string>;
+    /** Names bound by `({...} = require('hpagent'))` into a `let` declared without a value, which keep their names. */
+    assigned: Set<string>;
+    /** The identifiers such an assignment writes, which are no use of the class as a value. */
+    assignmentTargets: Set<string>;
+    /** Names a type-only import binds, which can only ever name a type. */
+    typeOnly: Set<string>;
+}
+
+/** The local and the export each member of `({X, Y: local} = ...)` binds, with the identifiers it writes. */
+function assignmentPattern(pattern: J): {name: string; member: string; ids: string[]}[] | undefined {
+    if (!isObjectLiteral(pattern)) return undefined;
+    const bound = [];
+    for (const member of objectMembers(pattern)) {
+        if (member.kind !== JS.Kind.PropertyAssignment) return undefined;
+        const prop = member as JS.PropertyAssignment;
+        const property = propertyName(prop);
+        const local = prop.initializer ?? prop.name.element;
+        if (property === undefined || !isIdentifier(local)) return undefined;
+        bound.push({name: local.simpleName, member: property, ids: [prop.name.element.id, local.id]});
+    }
+    return bound;
+}
+
+export function emptyHpagentBindings(): HpagentBindings {
+    return {
+        bindings: new Map(), scopes: new Map(), requires: new Set(), requireBound: new Set(), defaults: new Set(),
+        assigned: new Set(), assignmentTargets: new Set(), typeOnly: new Set()
+    };
+}
+
+export function hpagentBindings(cu: JS.CompilationUnit): HpagentBindings {
+    const bindings = bindingsOf(cu, HPAGENT_MODULES);
+    const defaults = new Set<string>();
+    const typeOnly = new Set<string>();
+    for (const padded of cu.statements) {
+        const imp = padded.element as JS.Import;
+        if (imp?.kind !== JS.Kind.Import || !HPAGENT_MODULES.has(importModule(imp) ?? '') || !imp.importClause) continue;
+        const clause = imp.importClause;
+        const name = clause.name?.element;
+        if (name && !clause.typeOnly) defaults.add(name.simpleName);
+        // Type-only imports name nothing at runtime, but their names still have to move off hpagent.
+        if (clause.typeOnly && clause.namedBindings?.kind === JS.Kind.Alias) {
+            const alias = (clause.namedBindings as JS.Alias).alias;
+            if (isIdentifier(alias)) {
+                bindings.set(alias.simpleName, undefined);
+                typeOnly.add(alias.simpleName);
+            }
+        }
+        if (clause.namedBindings?.kind !== JS.Kind.NamedImports) continue;
+        for (const el of (clause.namedBindings as JS.NamedImports).elements.elements) {
+            const spec = el.element as JS.ImportSpecifier;
+            if (spec.kind !== JS.Kind.ImportSpecifier || !(clause.typeOnly || spec.importType?.element)) continue;
+            if (isIdentifier(spec.specifier)) {
+                bindings.set(spec.specifier.simpleName, spec.specifier.simpleName);
+                typeOnly.add(spec.specifier.simpleName);
+            } else if (spec.specifier.kind === JS.Kind.Alias && isIdentifier((spec.specifier as JS.Alias).alias)) {
+                const alias = spec.specifier as JS.Alias;
+                bindings.set((alias.alias as J.Identifier).simpleName, alias.propertyName.element.simpleName);
+                typeOnly.add((alias.alias as J.Identifier).simpleName);
+            }
+        }
+    }
+    const scopes = new Map([...bindings.keys()].map(local => [local, cu.id]));
+    const requires = new Set<string>();
+    const requireBound = new Set<string>();
+    const assigned = new Set<string>();
+    const assignmentTargets = new Set<string>();
+    // Each name a `let` or `var` declares without a value, with the scopes declaring it so.
+    const unassigned = new Map<string, string[]>();
+    const assignments: J.Assignment[] = [];
+    const declare = (statement: J, scope: J) => {
+        for (const decl of declarationsOf(statement)) {
+            for (const v of decl.variables) {
+                const initializer = v.element.initializer?.element;
+                const declared = v.element.name as J;
+                if (!initializer && isIdentifier(declared)) {
+                    unassigned.set(declared.simpleName, [...(unassigned.get(declared.simpleName) ?? []), scope.id]);
+                }
+                if (!isHpagentRequire(initializer)) continue;
+                requires.add((initializer!.kind === JS.Kind.As ? (initializer as JS.As).left.element : initializer)!.id);
+                const pattern = v.element.name as J;
+                const names = isIdentifier(pattern) ? [{name: pattern.simpleName, member: undefined}] : bindingNames(pattern);
+                for (const {name, member} of names) {
+                    // A name bound twice is left to the report rather than guessed between.
+                    if (scope !== cu && scopes.has(name)) continue;
+                    bindings.set(name, member);
+                    scopes.set(name, scope.id);
+                    requireBound.add(name);
+                }
+            }
+        }
+    };
+    for (const padded of cu.statements) declare(padded.element, cu);
+    walk(cu, (n: any) => {
+        if (n?.kind === J.Kind.Block) {
+            for (const padded of (n as J.Block).statements) declare(padded.element, n);
+        } else if (n?.kind === J.Kind.Assignment && isHpagentRequire((n as J.Assignment).assignment.element)) {
+            assignments.push(n);
+        }
+        return true;
+    });
+    // `let HttpsProxyAgent; ... ({HttpsProxyAgent} = require('hpagent'))`, as code does that requires hpagent
+    // only once a proxy is configured. The binding lives where the `let` is, if one declaration settles it.
+    for (const assignment of assignments) {
+        const pattern = assignmentPattern(assignment.variable);
+        if (!pattern || pattern.some(({name}) => unassigned.get(name)?.length !== 1 || bindings.has(name))) continue;
+        const call = assignment.assignment.element;
+        requires.add((call.kind === JS.Kind.As ? (call as JS.As).left.element : call).id);
+        for (const {name, member, ids} of pattern) {
+            bindings.set(name, member);
+            scopes.set(name, unassigned.get(name)![0]);
+            requireBound.add(name);
+            assigned.add(name);
+            ids.forEach(id => assignmentTargets.add(id));
+        }
+    }
+    return {bindings, scopes, requires, requireBound, defaults, assigned, assignmentTargets, typeOnly};
+}
+
+/** Whether `name` at `cursor` resolves to the hpagent binding rather than a nearer declaration. */
+export function resolvesToBinding(cursor: Cursor, name: string, found: HpagentBindings): boolean {
+    const scope = found.scopes.get(name);
+    return scope !== undefined && scopeOf(cursor).declaringScope(name)?.id === scope;
+}
+
+/** Trees that hold an identifier as a declaration or import rather than a use of it. */
+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 function inTypePosition(cursor: Cursor): boolean {
+    // The type an `as` casts to, however deep, as `ConstructorParameters<typeof HttpProxyAgent>[0]` is.
+    for (let at: Cursor | undefined = cursor; at; at = at.parentTree()) {
+        const parent = at.parentTree()?.value as J | undefined;
+        if (parent?.kind === JS.Kind.As && (parent as JS.As).right === at.value) return true;
+    }
+    return !!cursor.firstEnclosing((t: any): t is J =>
+        t?.kind === JS.Kind.TypeInfo || t?.kind === JS.Kind.TypeQuery || t?.kind === JS.Kind.TypeDeclaration);
+}
+
+/**
+ * Whether the identifier or member access at `cursor` stands for the class it names as a value: not
+ * constructed, not tested with `instanceof`, not a type, not declared or imported, and not the
+ * module a member is read from.
+ */
+export function isValueUse(cursor: Cursor): boolean {
+    const tree = cursor.value as J;
+    const parent = cursor.parentTree()?.value as J | undefined;
+    if (!parent || DECLARING_KINDS.has(parent.kind) || inTypePosition(cursor)) return false;
+    switch (parent.kind) {
+        case J.Kind.NewClass:
+            return (parent as J.NewClass).class !== tree;
+        case J.Kind.InstanceOf:
+            return (parent as J.InstanceOf).class !== tree;
+        case J.Kind.FieldAccess:
+            return (parent as J.FieldAccess).target !== tree;
+        case J.Kind.MethodInvocation: {
+            const m = parent as J.MethodInvocation;
+            return m.select?.element !== tree && m.name !== tree;
+        }
+        case J.Kind.NamedVariable:
+            return (parent as J.VariableDeclarations.NamedVariable).name !== tree;
+        default:
+            return true;
+    }
+}
+
+const MOCK_OWNERS = new Set(['vi', 'jest']);
+const MOCK_METHODS = new Set(['mock', 'doMock', 'unmock', 'unstable_mockModule']);
+
+/** `jest.mock(...)`, `vi.mock(...)` and their kin, which name the module they replace. */
+export function isMockCall(m: J.MethodInvocation): boolean {
+    const select = m.select?.element;
+    return !!select && isIdentifier(select) && MOCK_OWNERS.has(select.simpleName) && MOCK_METHODS.has(m.name.simpleName);
+}
+
+/** `jest.spyOn(hpagent, 'HttpsProxyAgent')`, which reads the class off the module by name; the class it spies on. */
+export function spiedClass(m: J.MethodInvocation): string | undefined {
+    const select = m.select?.element;
+    if (!select || !isIdentifier(select) || !MOCK_OWNERS.has(select.simpleName) || m.name.simpleName !== 'spyOn') return undefined;
+    const member = stringLiteral(m.arguments.elements[1]?.element);
+    return member !== undefined && HPAGENT_CLASSES.has(member) ? member : undefined;
+}
+
 /** Both hpagent classes tunnel with `CONNECT`, which is what `https-proxy-agent` does for either target scheme. */
 export const HPAGENT_CLASSES = new Set(['HttpProxyAgent', 'HttpsProxyAgent']);
 
@@ -50,44 +256,28 @@ const DESTINATION_TLS_OPTIONS = new Set([
 /** The `proxyRequestOptions` members, which configure the `CONNECT` request and so the proxy hop. */
 const PROXY_REQUEST_OPTIONS = new Set(['ca', 'headers', 'rejectUnauthorized']);
 
+/** hpagent's option interfaces, which the adapter's own options type stands in for. */
+export const ADAPTED_TYPES = new Set(['HttpProxyAgentOptions', 'HttpsProxyAgentOptions']);
+
+export const ADAPTER_FUNCTION = 'createProxyAgent';
+export const ADAPTER_TYPE = 'ProxyAgentOptions';
+/** What hpagent called `ProxyAgentRequestOptions`, declared beside the adapter's type where a file names it. */
+export const REQUEST_TYPE = 'ProxyRequestOptions';
+
 export const REASONS = {
-    noProxy: "hpagent's agent options have no `proxy`, so there is no proxy URL to pass as " +
-        "`https-proxy-agent`'s first argument. Supply it at the call site.",
-    spread: "The agent options are spread from another object. `proxy` is given here, so the call could become " +
-        "`new HttpsProxyAgent(proxy, {...spread})`, but the spread may itself carry a `proxyRequestOptions` or a " +
-        "destination TLS option, which would have to move rather than be passed through. Check what it holds and " +
-        "either migrate by hand or re-run with `migrateSpreadOptions` enabled.",
-    spreadNoProxy: "The agent options are spread from another object and no `proxy` is given here, so the proxy URL " +
-        "can only come from the spread and can't be read out statically. Pass it as `https-proxy-agent`'s first " +
-        "argument explicitly.",
-    notLiteral: "The agent options aren't an object literal, so `proxy` can't be separated from the rest. " +
-        "Call `new HttpsProxyAgent(options.proxy, options)` explicitly, folding any `proxyRequestOptions` " +
-        "members into the second argument.",
-    destinationTls: (option: string) => `\`${option}\` configured the TLS handshake with the destination, since ` +
-        "hpagent's `HttpsProxyAgent` extends `https.Agent`. `https-proxy-agent` spends its constructor options on " +
-        "the connection to the proxy and takes the destination's TLS options from each request, so pass this " +
-        "option to `https.request`/`fetch` instead, or to the client library making the request.",
-    unknownOption: (option: string) => `\`${option}\` isn't a recognized hpagent option, so it isn't known which ` +
-        "hop it configures. Check it against `https-proxy-agent`'s options and move it by hand.",
-    computedOption: "An agent option has a computed name, so it can't be classified. Name the option literally, " +
-        "or build the two argument lists by hand.",
-    nameTaken: "Both `HttpProxyAgent` and `HttpsProxyAgent` are bound here and both migrate to " +
-        "`https-proxy-agent`'s `HttpsProxyAgent`, which would collide. Migrate the two bindings by hand; both " +
-        "tunnel with `CONNECT`, so one agent serves http and https targets alike.",
-    value: "hpagent's agent class is used as a value rather than instantiated, so its constructor call can't be " +
-        "rewritten here. `https-proxy-agent` takes the proxy URL as its first argument, not as an option.",
-    type: "hpagent's option types don't match `https-proxy-agent`'s, whose options are generic in the proxy URL's " +
-        "scheme. Use `HttpsProxyAgentOptions<string>` from `https-proxy-agent` or declare a local type.",
+    arguments: "hpagent's constructor takes one options object, and this call doesn't pass exactly one, so it " +
+        "can't be handed to the adapter. Pass the options as a single object.",
+    value: "hpagent's agent class is used as a value rather than instantiated, as in `const Agent = HttpProxyAgent`, " +
+        "so whatever constructs it later still passes hpagent's options object. `https-proxy-agent` takes the " +
+        "proxy URL as its first argument; construct it directly, or through the adapter this migration writes.",
     reExport: "Re-exporting hpagent makes it part of this module's API. Re-export from `https-proxy-agent`, whose " +
         "constructor takes the proxy URL positionally.",
     dynamicImport: "Dynamic import of hpagent, which the automated migration doesn't follow. Import " +
         "`https-proxy-agent` instead and migrate its uses.",
-    nestedRequire: "hpagent 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.",
+    nestedRequire: "hpagent required in a shape the automated migration doesn't follow; it moves a block's " +
+        "`const {...} = require('hpagent')` but not this. Bind it that way or migrate its uses by hand.",
     mock: "Test mocks hpagent. Once the code under test constructs `https-proxy-agent`'s `HttpsProxyAgent`, mock " +
         "that module instead; its constructor takes the proxy URL as its first argument.",
-    defaultImport: "hpagent has no default export, and `https-proxy-agent` none either. Import `HttpsProxyAgent` " +
-        "as a named binding.",
 };
 
 /** What one member of an hpagent options object literal is, and so where it goes. */
@@ -96,7 +286,7 @@ export type OptionKind =
     | {kind: 'proxyRequestOptions'; value: J}
     | {kind: 'agent'; member: JS.PropertyAssignment}
     | {kind: 'spread'; value: J | undefined}
-    | {kind: 'unmappable'; option: string; reason: string};
+    | {kind: 'unmappable'};
 
 export function propertyName(prop: JS.PropertyAssignment): string | undefined {
     const name = prop.name.element;
@@ -115,22 +305,120 @@ export function objectMembers(literal: J.NewClass): J[] {
 /** Classifies one member of an hpagent options object literal. */
 export function classifyOption(statement: J): OptionKind {
     if (statement.kind === JS.Kind.Spread) return {kind: 'spread', value: (statement as JS.Spread).expression};
-    if (statement.kind !== JS.Kind.PropertyAssignment) {
-        // A method or a getter: neither a name/value pair this can read.
-        return {kind: 'unmappable', option: '(not a property)', reason: REASONS.notLiteral};
-    }
+    // A method or a getter is no name/value pair this can read.
+    if (statement.kind !== JS.Kind.PropertyAssignment) return {kind: 'unmappable'};
     const prop = statement as JS.PropertyAssignment;
     const name = propertyName(prop);
-    if (name === undefined) return {kind: 'unmappable', option: '(computed)', reason: REASONS.computedOption};
+    if (name === undefined) return {kind: 'unmappable'};
     // A shorthand `{proxy}` carries the value in its name, which the caller reads back from the property.
     const value = prop.initializer ?? prop.name.element;
     if (name === 'proxy') return {kind: 'proxy', value};
     if (name === 'proxyRequestOptions') return {kind: 'proxyRequestOptions', value};
-    if (DESTINATION_TLS_OPTIONS.has(name)) {
-        return {kind: 'unmappable', option: name, reason: REASONS.destinationTls(name)};
+    // A destination TLS option would land on the proxy hop in the two-argument form, so it takes the adapter.
+    if (DESTINATION_TLS_OPTIONS.has(name)) return {kind: 'unmappable'};
+    return AGENT_OPTIONS.has(name) ? {kind: 'agent', member: prop} : {kind: 'unmappable'};
+}
+
+/** The one options argument a construction passes, which is what the adapter takes, or undefined. */
+export function constructionArgument(n: J.NewClass): J | undefined {
+    const args = n.arguments.elements.map(a => a.element).filter(a => a.kind !== J.Kind.Empty);
+    return args.length === 1 && args[0].kind !== JS.Kind.Spread ? args[0] : undefined;
+}
+
+/** Source for a declaration the migration writes, with the text of the doc comment written above it. */
+export interface GeneratedDeclaration {
+    doc: string;
+    code: string;
+}
+
+/** The pool options hpagent gave `http.Agent`; it sent no other agent option to the proxy. */
+const POOL_OPTIONS = ['keepAlive', 'keepAliveMsecs', 'maxSockets', 'maxTotalSockets', 'maxFreeSockets', 'scheduling', 'timeout'];
+
+/** How a braced list separates its members: on one line, and on lines of their own. */
+interface Separators {
+    inline: string;
+    each: string;
+    /** After the last member on a line of its own. */
+    last: string;
+}
+
+/**
+ * `head{members}tail` on one line at `level`, or with a member to a line where that runs past the file's
+ * print width. In a `pattern`, a rest element takes no trailing comma, which the language forbids there.
+ */
+function braced(style: CodeStyle, level: number, head: string, members: string[], tail: string, pattern = false,
+                separators: Separators = {inline: ', ', each: ',', last: style.trailingCommas ? ',' : ''}): string {
+    const margin = '    '.repeat(level);
+    const inner = members.join(separators.inline);
+    const line = `${margin}${head}${style.braceSpacing ? `{ ${inner} }` : `{${inner}}`}${tail}`;
+    const indentWidth = style.indent === '\t' ? 4 : style.indent.length;
+    if (line.length - margin.length + indentWidth * level <= style.printWidth) return line;
+    const lines = members.map((member, i) => `${margin}    ${member}${i < members.length - 1
+        ? separators.each
+        : pattern && member.startsWith('...') ? '' : separators.last}`);
+    return [`${margin}${head}{`, ...lines, `${margin}}${tail}`].join('\n');
+}
+
+/**
+ * The adapter a file gets when one of its constructions can't be rewritten to the two-argument form.
+ * `agentClass` is how the file now names `https-proxy-agent`'s class.
+ */
+export function adapterSource(name: string, typeName: string, agentClass: string, typeScript: boolean,
+                              style: CodeStyle = DEFAULT_CODE_STYLE): GeneratedDeclaration {
+    const end = style.semicolons ? ';' : '';
+    const head = `function ${name}${style.functionParenSpace ? ' ' : ''}(`;
+    const parameters = ['proxy', 'proxyRequestOptions', '...options'];
+    return {
+        doc: `*
+ * hpagent's options-object constructor on \`https-proxy-agent\`, whose constructor options configure the
+ * connection to the proxy. hpagent sent the proxy only \`proxyRequestOptions\`, and handed every other
+ * option to \`https.Agent\`, which merges an agent's options into each request and so into the
+ * destination's TLS handshake. \`agent.options\` is that same per-request object here.
+ `,
+        code: indented(style, [
+            braced(style, 0, head, parameters, typeScript ? `: ${typeName}): ${agentClass}<string> {` : ') {', true),
+            braced(style, 1, 'const ', POOL_OPTIONS, ` = options${end}`, true),
+            braced(style, 1, `const agent = new ${agentClass}(proxy, `, [...POOL_OPTIONS, '...proxyRequestOptions'], `)${end}`),
+            `    Object.assign(agent.options || {}, options)${end}`,
+            `    return agent${end}`,
+            '}',
+        ].join('\n'))
+    };
+}
+
+/**
+ * The options hpagent's agents took, which the adapter takes in their place, and hpagent's
+ * `ProxyAgentRequestOptions` as `requestTypeName` where the file names that. `specifier` spells a builtin the file's way.
+ */
+export function adapterTypeSource(typeName: string | undefined, requestTypeName: string | undefined,
+                                  specifier: (module: string) => string,
+                                  style: CodeStyle = DEFAULT_CODE_STYLE): GeneratedDeclaration[] {
+    const module = (name: string) => `import(${style.quote}${specifier(name)}${style.quote})`;
+    const end = style.semicolons ? ';' : '';
+    const request = ['ca?: string[]', `headers?: ${module('http')}.OutgoingHttpHeaders`, 'rejectUnauthorized?: boolean'];
+    // A type literal written on one line keeps its delimiters either way; one written a member to a line needs them only with semicolons.
+    const separators = {inline: style.semicolons ? '; ' : ', ', each: end, last: end};
+    const declarations: GeneratedDeclaration[] = [];
+    if (typeName) {
+        declarations.push({
+            doc: "* The options hpagent's agents took: an `https.Agent`'s, plus the proxy to tunnel through. ",
+            code: indented(style, [
+                `type ${typeName} = ${module('https')}.AgentOptions & {`,
+                `    proxy: string | ${module('url')}.URL${end}`,
+                requestTypeName
+                    ? `    proxyRequestOptions?: ${requestTypeName}${end}`
+                    : braced(style, 1, 'proxyRequestOptions?: ', request, end, false, separators),
+                `}${end}`,
+            ].join('\n'))
+        });
+    }
+    if (requestTypeName) {
+        declarations.push({
+            doc: "* What hpagent sent the proxy with its `CONNECT` request, its `ProxyAgentRequestOptions`. ",
+            code: indented(style, braced(style, 0, `type ${requestTypeName} = `, request, end, false, separators))
+        });
     }
-    if (AGENT_OPTIONS.has(name)) return {kind: 'agent', member: prop};
-    return {kind: 'unmappable', option: name, reason: REASONS.unknownOption(name)};
+    return declarations;
 }
 
 /** Whether every member of a `proxyRequestOptions` literal is one hpagent forwards to the `CONNECT` request. */
@@ -187,24 +475,34 @@ export function spreadIsPlainAgentOptions(cu: JS.CompilationUnit, spread: J | un
     return literal !== undefined && objectMembers(literal).every(m => classifyOption(m).kind === 'agent');
 }
 
+/** The builtin module whose agent an hpagent class extends. */
+export function builtinAgentModule(member: string): 'http' | 'https' {
+    return member === 'HttpProxyAgent' ? 'http' : 'https';
+}
+
 /**
- * `HttpsProxyAgent<string>` as a type tree. `https-proxy-agent`'s class is generic in the proxy
- * URL's scheme with no default, so the bare name is a type error where hpagent's was not.
+ * The builtin agent an hpagent class extends, which is its type exactly: hpagent declares nothing beyond
+ * it. `https-proxy-agent`'s class extends `http.Agent` too, and is assignable to `https.Agent`, so anything
+ * the type accepted it still does. Through `local` where the file binds the builtin, else `import('…')`.
  */
-export function targetTypeReference(local: string, prefix: J.Space): J.ParameterizedType {
-    const name: J.Identifier = {
-        kind: J.Kind.Identifier, id: randomId(), prefix: emptySpace, markers: emptyMarkers,
-        annotations: [], simpleName: local
-    } as unknown as J.Identifier;
-    const stringType: J.Identifier = {...name, id: randomId(), simpleName: 'string'};
+export function builtinAgentType(local: string | undefined, specifier: string, prefix: J.Space): J {
+    const identifier = (name: string, at: J.Space = emptySpace): J.Identifier => ({
+        kind: J.Kind.Identifier, id: randomId(), prefix: at, markers: emptyMarkers, annotations: [], simpleName: name
+    } as unknown as J.Identifier);
+    const agent = {kind: J.Kind.LeftPadded, before: emptySpace, element: identifier('Agent'), markers: emptyMarkers};
+    if (local) {
+        return {kind: J.Kind.FieldAccess, id: randomId(), prefix, markers: emptyMarkers, target: identifier(local), name: agent} as unknown as J;
+    }
+    const module = {
+        kind: JS.Kind.LiteralType, id: randomId(), prefix: emptySpace, markers: emptyMarkers,
+        literal: {kind: J.Kind.Literal, id: randomId(), prefix: emptySpace, markers: emptyMarkers, value: specifier, valueSource: `'${specifier}'`}
+    };
     return {
-        kind: J.Kind.ParameterizedType, id: randomId(), prefix, markers: emptyMarkers,
-        class: name,
-        typeParameters: {
-            kind: J.Kind.Container, id: randomId(), before: emptySpace, markers: emptyMarkers,
-            elements: [rightPadded(stringType, space(''))]
-        }
-    } as unknown as J.ParameterizedType;
+        kind: JS.Kind.ImportType, id: randomId(), prefix, markers: emptyMarkers,
+        hasTypeof: rightPadded(false, emptySpace),
+        argumentAndAttributes: {kind: J.Kind.Container, before: emptySpace, elements: [rightPadded(module, emptySpace)], markers: emptyMarkers},
+        qualifier: agent
+    } as unknown as J;
 }
 
 export class HpagentManualMigrationStep {