import type { ImportDeclaration, Program } from "@oxc-project/types"; import picomatch from "picomatch"; import type * as rolldown from "rolldown"; /** * `rolldown` and `rolldown/parseAst` load `@rolldown/binding-*` at module * scope, so they are imported lazily on first use (#562). */ const loadRolldown = () => import("rolldown"); const loadParseAst = () => import("rolldown/parseAst"); /** * Packages whose namespace imports are rewritten by default. Their root * modules re-export every service (`export * as Lambda from "./Lambda/index.ts"`), * and every one of them declares `"sideEffects": false`. */ export const DEFAULT_NAMESPACE_IMPORT_PACKAGES: ReadonlyArray = [ "alchemy", "@alchemy.run/*", ]; /** * Options for {@link namespaceImportPlugin}. */ export interface NamespaceImportPluginOptions { /** * Extra package names or globs whose namespace imports are rewritten, in * addition to {@link DEFAULT_NAMESPACE_IMPORT_PACKAGES}. Matched with * picomatch against the package name of the import specifier. Only list * packages that declare `"sideEffects": false`. */ readonly packages?: ReadonlyArray; } const SUPPORTED_FILE_RE = /\.(?:m?[jt]sx?|cjs|cts)$/; /** * Rolldown plugin that rewrites namespace imports of barrel packages into * named imports, so `experimental.lazyBarrel` only compiles the re-exports * a module actually uses. * * ```ts * import * as AWS from "@alchemy.run/aws"; * AWS.Lambda.Function; * // becomes * import { Lambda as AWS$Lambda } from "@alchemy.run/aws"; * AWS$Lambda.Function; * ``` * * Rolldown loads every export of a barrel imported with `import * as ns`, * even when only `ns.X` is read, so without this rewrite one * `import * as AWS from "@alchemy.run/aws"` parses every AWS service. * * A namespace is only rewritten when every reference to its name is a * static member access (`ns.X`, or `ns.X` in a type). Anything else — * passing the namespace around, computed access, a shadowing binding, * JSX — leaves the import untouched. */ export const namespaceImportPlugin = ( options: NamespaceImportPluginOptions = {}, ): rolldown.Plugin => { const isMatch = picomatch([...DEFAULT_NAMESPACE_IMPORT_PACKAGES, ...(options.packages ?? [])]); const matchesSpecifier = (specifier: string) => { const name = packageNameOf(specifier); return name !== null && isMatch(name); }; return { name: "alchemy:namespace-imports", transform: { filter: { id: SUPPORTED_FILE_RE, code: /import\s*\*\s*as\s/ }, async handler(code, id, meta) { const edits = await collectNamespaceImportEdits(code, id, matchesSpecifier); if (edits.length === 0) return null; const s = meta.magicString ?? new (await loadRolldown()).RolldownMagicString(code); for (const edit of edits) s.overwrite(edit.start, edit.end, edit.text); return { code: s }; }, }, }; }; /** A source replacement over `[start, end)`. */ export interface NamespaceImportEdit { readonly start: number; readonly end: number; readonly text: string; } /** * Returns the edits that rewrite each eligible namespace import in `code` * (see {@link namespaceImportPlugin}), or an empty array when nothing is * rewritten. */ export async function collectNamespaceImportEdits( code: string, filename: string, matchesSpecifier: (specifier: string) => boolean, ): Promise { const { parseAst } = await loadParseAst(); let program: Program; try { program = parseAst(code, { sourceType: "module", lang: langOf(filename) }, filename); } catch { return []; } const candidates = new Map(); for (const statement of program.body) { if (statement.type !== "ImportDeclaration") continue; if (statement.importKind === "type" || statement.phase) continue; if (statement.attributes.length > 0) continue; const [specifier, ...rest] = statement.specifiers; if (specifier?.type !== "ImportNamespaceSpecifier" || rest.length > 0) continue; if (!matchesSpecifier(statement.source.value)) continue; // Two imports binding the same name is a syntax error; skip defensively. if (candidates.has(specifier.local.name)) { candidates.delete(specifier.local.name); continue; } candidates.set(specifier.local.name, statement); } if (candidates.size === 0) return []; interface Usage { /** Identifier nodes with the namespace's name, wherever they appear. */ identifiers: number; /** Rewritable member accesses: `[start, end, member, isType]`. */ members: Array; /** A reference that can't be rewritten (JSX). */ blocked: boolean; } const usages = new Map( [...candidates.keys()].map((name) => [name, { identifiers: 0, members: [], blocked: false }]), ); // `inType` is set once the walk enters a type: everything below it is // erased by the TypeScript transform, so its members import as `type`. const visit = (node: unknown, inType: boolean): void => { if (Array.isArray(node)) { for (const child of node) visit(child, inType); return; } if (node === null || typeof node !== "object") return; const n = node as { type?: unknown } & Record; const type = n.type as string; if (type === "Identifier" || type === "JSXIdentifier") { const usage = usages.get(n.name as string); if (usage) { usage.identifiers++; if (type === "JSXIdentifier") usage.blocked = true; } // Fall through: a binding's `typeAnnotation` hangs off its Identifier. } else if (type === "TSImportEqualsDeclaration") { // `import L = AWS.Lambda` aliases a value through a type-shaped name. const usage = usages.get(rootName(n.moduleReference)); if (usage) usage.blocked = true; } else if (type === "MemberExpression" || type === "TSQualifiedName") { const [object, property] = type === "MemberExpression" ? [n.object, n.property] : [n.left, n.right]; const o = object as { type: string; name?: string }; const p = property as { type: string; name?: string }; const usage = o.type === "Identifier" ? usages.get(o.name!) : undefined; if (usage && p.type === "Identifier" && n.computed !== true) { usage.members.push([n.start as number, n.end as number, p.name!, inType]); } } const childInType = inType || TYPE_NODES.has(type); for (const key in n) { if (key === "parent" || key === "type" || key === "start" || key === "end") continue; visit(n[key], childInType); } }; visit(program.body, false); const edits: NamespaceImportEdit[] = []; const taken = new Set(); for (const [name, declaration] of candidates) { const usage = usages.get(name)!; // One identifier is the import's own binding; every other one must be // the object of a rewritable member access. if (usage.blocked || usage.members.length === 0) continue; if (usage.identifiers !== usage.members.length + 1) continue; const aliases = new Map(); for (const [, , member, isType] of usage.members) { const existing = aliases.get(member); if (existing) { existing.value ||= !isType; continue; } const alias = uniqueAlias(code, taken, `${name}$${member}`); taken.add(alias); aliases.set(member, { alias, value: !isType }); } const specifiers = [...aliases] .map(([member, { alias, value }]) => `${value ? "" : "type "}${member} as ${alias}`) .join(", "); const source = code.slice(declaration.source.start, declaration.source.end); edits.push({ start: declaration.start, end: declaration.end, text: `import { ${specifiers} } from ${source};`, }); for (const [start, end, member] of usage.members) { edits.push({ start, end, text: aliases.get(member)!.alias }); } } return edits; } /** * Nodes whose descendants are all types. `typeof ns.X` is a type query over * a value, which a `type` import still satisfies. */ const TYPE_NODES = new Set([ "TSTypeAnnotation", "TSTypeReference", "TSTypeQuery", "TSInterfaceDeclaration", "TSInterfaceHeritage", "TSClassImplements", "TSTypeAliasDeclaration", "TSTypeParameterInstantiation", "TSTypeParameterDeclaration", ]); /** The leftmost identifier of `a.b.c` (or `a`), or `""`. */ const rootName = (node: unknown): string => { let n = node as { type?: string; name?: string; left?: unknown; object?: unknown } | null; while (n && (n.type === "TSQualifiedName" || n.type === "MemberExpression")) { n = (n.left ?? n.object) as typeof n; } return n?.type === "Identifier" ? n.name! : ""; }; /** The package name of a bare import specifier, or `null` for relative/absolute ones. */ const packageNameOf = (specifier: string): string | null => { if (specifier.startsWith(".") || specifier.startsWith("/") || specifier.includes(":")) { return null; } const parts = specifier.split("/"); return specifier.startsWith("@") ? parts.slice(0, 2).join("/") : parts[0]!; }; const langOf = (filename: string): "js" | "jsx" | "ts" | "tsx" => { const clean = filename.replace(/[?#].*$/, ""); if (clean.endsWith(".tsx")) return "tsx"; if (clean.endsWith(".jsx")) return "jsx"; // TS is a superset of JS for parsing published `.js` files. return "ts"; }; /** `base`, suffixed until it occurs nowhere in `code` and isn't already `taken`. */ const uniqueAlias = (code: string, taken: ReadonlySet, base: string): string => { let alias = base; while (code.includes(alias) || taken.has(alias)) alias += "$"; return alias; };