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<string> = [
"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<string>;
}
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<NamespaceImportEdit[]> {
const { parseAst } = await loadParseAst();
let program: Program;
try {
program = parseAst(code, { sourceType: "module", lang: langOf(filename) }, filename);
} catch {
return [];
}
const candidates = new Map<string, ImportDeclaration>();
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<readonly [number, number, string, boolean]>;
/** A reference that can't be rewritten (JSX). */
blocked: boolean;
}
const usages = new Map<string, Usage>(
[...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<string, unknown>;
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<string>();
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<string, { alias: string; value: boolean }>();
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<string>, base: string): string => {
let alias = base;
while (code.includes(alias) || taken.has(alias)) alias += "$";
return alias;
};