@gtkx/codegen 0.21.0 → 1.0.0-rc.1

package/src/store/react/pipeline.ts

@@ -0,0 +1,90 @@
+import type { ElementProp } from "@gtkx/config";
+import { sortStringsBy } from "@gtkx/utils";
+import type { Library } from "../../gir/library.js";
+import { type GirNamespace, namespaceDirectory } from "../../gir/namespace.js";
+import { ImportsBuilder } from "../../writer/imports.js";
+import { generateElementComponentsSection } from "./element-components.js";
+import { createElementPropTypegen, type ElementPropTypegen } from "./element-prop-types.js";
+import { assembleElementProps } from "./element-props.js";
+import { buildGirIndex } from "./gir-index.js";
+import { collectIntrinsicElementClasses, type GlibNamedClass } from "./intrinsic-elements.js";
+import { generateJsxSection } from "./jsx.js";
+import { generateMetadata } from "./metadata.js";
+
+export type JsxNamespaceFile = {
+    directory: string;
+    source: string;
+};
+
+type JsxFiles = {
+    namespaces: JsxNamespaceFile[];
+    metadata: string;
+    intrinsicElementCount: number;
+};
+
+export const generateJsxFiles = (library: Library, userElementProps?: Record<string, ElementProp[]>): JsxFiles => {
+    const intrinsicElements = collectIntrinsicElementClasses(library);
+    const intrinsicElementByGlibName = new Map(intrinsicElements.map((entry) => [entry.glibName, entry]));
+    const namespacesWithIntrinsicElements = new Map<string, GirNamespace>();
+    for (const entry of intrinsicElements) {
+        namespacesWithIntrinsicElements.set(entry.namespace.name, entry.namespace);
+    }
+
+    const girIndex = buildGirIndex(library);
+    const elementProps = assembleElementProps(girIndex, userElementProps ?? {});
+    const typegen = createElementPropTypegen(girIndex, elementProps);
+
+    const namespaces: JsxNamespaceFile[] = [];
+    let intrinsicElementCount = 0;
+    for (const namespace of sortStringsBy(namespacesWithIntrinsicElements.values(), (entry) => entry.name)) {
+        const { source, count } = generateJsxNamespace(namespace, library, {
+            typegen,
+            intrinsicElements,
+            intrinsicElementByGlibName,
+        });
+        namespaces.push({ directory: namespaceDirectory(namespace), source });
+        intrinsicElementCount += count;
+    }
+
+    const metadata = generateMetadata(library, elementProps);
+
+    return { namespaces, metadata, intrinsicElementCount };
+};
+
+type JsxNamespaceContext = {
+    typegen: ElementPropTypegen;
+    intrinsicElements: GlibNamedClass[];
+    intrinsicElementByGlibName: Map<string, GlibNamedClass>;
+};
+
+const generateJsxNamespace = (
+    targetNamespace: GirNamespace,
+    library: Library,
+    context: JsxNamespaceContext,
+): { source: string; count: number } => {
+    const { typegen, intrinsicElements, intrinsicElementByGlibName } = context;
+    const targetDirectory = namespaceDirectory(targetNamespace);
+    const imports = new ImportsBuilder();
+    imports.addSideEffect(`@gtkx/gi/${targetDirectory}`);
+
+    const elementComponents = generateElementComponentsSection(targetNamespace, library, {
+        imports,
+        typegen,
+        intrinsicElements,
+        intrinsicElementByGlibName,
+    });
+    const excludeNames = new Set<string>(elementComponents.exportedNames);
+    const { source: jsxSection, intrinsicCount } = generateJsxSection(targetNamespace, library, {
+        excludeNames,
+        imports,
+        typegen,
+        intrinsicElements,
+        intrinsicElementByGlibName,
+    });
+
+    const body = [imports.toSource().trimEnd(), "", jsxSection];
+    if (elementComponents.source.length > 0) body.push("", elementComponents.source);
+
+    const count = elementComponents.exportedNames.size + intrinsicCount;
+    return { source: `${body.join("\n")}\n`, count };
+};

package/src/store/react/props.ts

@@ -0,0 +1,197 @@
+import { toCamelIdentifier, upperFirst } from "@gtkx/utils";
+import { forEachAncestor } from "../../analysis/inheritance.js";
+import { renderHandlerParameters, renderHandlerResultType } from "../../analysis/param-structure.js";
+import { renderBaseTypeFor, type TsTypeTarget } from "../../analysis/ts-type.js";
+import type { GirClass } from "../../gir/class.js";
+import type { Library } from "../../gir/library.js";
+import type { GirNamespace } from "../../gir/namespace.js";
+import type { GirSignal } from "../../gir/parameter.js";
+import { type GirProperty, isConstructableProperty } from "../../gir/property.js";
+import type { TypeId } from "../../gir/type-id.js";
+import { renderJsDoc } from "../../writer/doc.js";
+import {
+    classExposesMethod,
+    giNamespaceAlias,
+    isIntrinsicElementClass,
+    signalHandlerName,
+} from "./intrinsic-elements.js";
+
+type IntrinsicElementPropsEntries = {
+    propLines: string[];
+    imports: Map<string, string>;
+    objectPropNames: string[];
+};
+
+type IntrinsicElementPropsOptions = {
+    library: Library;
+    klass: GirClass;
+    namespace: GirNamespace;
+    isIntrinsicElementAncestor?: (candidate: GirClass) => boolean;
+};
+
+type PropTypeRenderContext = {
+    library: Library;
+    imports: Map<string, string>;
+};
+
+type SignalRenderOptions = {
+    types: PropTypeRenderContext;
+    signal: GirSignal;
+    selfType: string;
+};
+
+type PropEntryCollector = {
+    propLines: string[];
+    imports: Map<string, string>;
+    objectPropNames: string[];
+    acceptProperty: (property: GirProperty) => void;
+    acceptSignal: (signal: GirSignal) => void;
+};
+
+const createPropEntryCollector = (owner: PropOwner): PropEntryCollector => {
+    const { library } = owner;
+    const imports = new Map<string, string>();
+    const types: PropTypeRenderContext = { library, imports };
+    const propLines: string[] = [];
+    const objectPropNames: string[] = [];
+    const seen = new Set<string>();
+
+    const acceptProperty = (property: GirProperty): void => {
+        if (!property.introspectable) return;
+        const jsName = toCamelIdentifier(property.name);
+        if (seen.has(jsName)) return;
+        seen.add(jsName);
+        const tsType = renderReactPropType(types, property.type, false);
+        const doc = renderJsDoc(property.doc);
+        if (isObjectProp(owner, property, jsName)) {
+            propLines.push(`${doc}${jsName}?: ${tsType} | ReactElement | null | undefined;`);
+            objectPropNames.push(jsName);
+            return;
+        }
+        const settable = isConstructableProperty(property);
+        if (settable) propLines.push(`${doc}${jsName}?: ${tsType} | null | undefined;`);
+        propLines.push(
+            `${settable ? "" : doc}onNotify${upperFirst(jsName)}?: ((value: ${tsType} | null, self: Self) => void) | null | undefined;`,
+        );
+    };
+
+    const acceptSignal = (signal: GirSignal): void => {
+        const handlerName = signalHandlerName(signal.name);
+        if (seen.has(handlerName)) return;
+        seen.add(handlerName);
+        const signature = renderSignalHandler({ types, signal, selfType: "Self" });
+        propLines.push(`${renderJsDoc(signal.doc)}${handlerName}?: (${signature}) | undefined;`);
+    };
+
+    return { propLines, imports, objectPropNames, acceptProperty, acceptSignal };
+};
+
+export const buildElementPropsEntries = (options: IntrinsicElementPropsOptions): IntrinsicElementPropsEntries => {
+    const { library, klass, namespace, isIntrinsicElementAncestor = () => false } = options;
+    const collector = createPropEntryCollector({ library, klass, namespace });
+    walkIntrinsicElementMembers({
+        library,
+        klass,
+        namespace,
+        isIntrinsicElementAncestor,
+        acceptProperty: collector.acceptProperty,
+        acceptSignal: collector.acceptSignal,
+    });
+    return { propLines: collector.propLines, imports: collector.imports, objectPropNames: collector.objectPropNames };
+};
+
+type InterfacePropsOptions = {
+    library: Library;
+    iface: GirClass;
+    namespace: GirNamespace;
+};
+
+export const buildInterfacePropsEntries = (options: InterfacePropsOptions): IntrinsicElementPropsEntries => {
+    const { library, iface, namespace } = options;
+    const collector = createPropEntryCollector({ library, klass: iface, namespace });
+    for (const property of iface.properties) collector.acceptProperty(property);
+    for (const signal of iface.signals) collector.acceptSignal(signal);
+    return { propLines: collector.propLines, imports: collector.imports, objectPropNames: collector.objectPropNames };
+};
+
+type IntrinsicElementMemberWalk = {
+    library: Library;
+    klass: GirClass;
+    namespace: GirNamespace;
+    isIntrinsicElementAncestor: (candidate: GirClass) => boolean;
+    acceptProperty: (property: GirProperty) => void;
+    acceptSignal: (signal: GirSignal) => void;
+};
+
+const walkIntrinsicElementMembers = (walk: IntrinsicElementMemberWalk): void => {
+    const { library, klass, namespace, isIntrinsicElementAncestor, acceptProperty, acceptSignal } = walk;
+    const visitMembers = (memberClass: GirClass): void => {
+        for (const property of memberClass.properties) acceptProperty(property);
+        for (const signal of memberClass.signals) acceptSignal(signal);
+    };
+    const ancestry = { library, namespace };
+    visitMembers(klass);
+    forEachAncestor(ancestry, klass, (ancestor) => visitMembers(ancestor.klass), isIntrinsicElementAncestor);
+};
+
+const resolvesToGObjectClass = (library: Library, ref: TypeId | undefined): boolean => {
+    if (ref === undefined) return false;
+    const resolved = library.typeOf(ref);
+    if (resolved?.kind !== "class") return false;
+    return isIntrinsicElementClass(resolved.value, resolved.namespace, library);
+};
+
+type PropOwner = {
+    library: Library;
+    klass: GirClass;
+    namespace: GirNamespace;
+};
+
+export const isObjectProp = (owner: PropOwner, property: GirProperty, jsName: string): boolean => {
+    if (!property.writable || property.constructOnly) return false;
+    if (!resolvesToGObjectClass(owner.library, property.type)) return false;
+    if (jsName === "child" && classExposesMethod(owner.klass, owner.namespace, owner.library, "set_child")) {
+        return false;
+    }
+    return true;
+};
+
+const renderSignalHandler = (options: SignalRenderOptions): string => {
+    const { types, signal, selfType } = options;
+    const params = [
+        ...renderHandlerParameters(signal.parameters, (ref, nullable) => renderReactPropType(types, ref, nullable)),
+        `self: ${selfType}`,
+    ];
+    const result = renderHandlerResultType({
+        library: types.library,
+        signal,
+        renderType: (ref, nullable) => renderReactPropType(types, ref, nullable),
+        includeCallerAllocated: false,
+        optOut: true,
+    });
+    return `(${params.join(", ")}) => ${result}`;
+};
+
+export const reactTarget = (context: PropTypeRenderContext): TsTypeTarget => ({
+    containerStyle: "record",
+    callbackType: "((...args: unknown[]) => unknown)",
+    byteArrayAsNumber: false,
+    renderNamed: (resolved, name) => {
+        if (resolved?.kind === "alias") {
+            return resolved.value.target === undefined
+                ? "number"
+                : renderBaseTypeFor(context.library, reactTarget(context), resolved.value.target);
+        }
+        context.imports.set(name.namespaceName, giNamespaceAlias(name.namespaceName));
+        return `${giNamespaceAlias(name.namespaceName)}.${name.typeName}`;
+    },
+    renderGtype: () => {
+        context.imports.set("GObject", giNamespaceAlias("GObject"));
+        return `${giNamespaceAlias("GObject")}.Type`;
+    },
+});
+
+const renderReactPropType = (context: PropTypeRenderContext, ref: TypeId | undefined, isNullable: boolean): string => {
+    const base = renderBaseTypeFor(context.library, reactTarget(context), ref);
+    return isNullable ? `${base} | null` : base;
+};

package/src/store/store-fs.ts

@@ -0,0 +1,112 @@
+import { existsSync, mkdirSync, mkdtempSync, renameSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
+import { dirname, join, relative } from "node:path";
+import { compileStore } from "./compile-store.js";
+
+export type StoreOptions = {
+    storeDir: string;
+    linkDir: string;
+    version: string;
+};
+
+type StoreFile = {
+    fileName: string;
+    source: string;
+};
+
+export const subpathExport = (stem: string): { types: string; default: string } => ({
+    types: `./${stem}.d.ts`,
+    default: `./${stem}.js`,
+});
+
+type Manifest = {
+    name: string;
+    type: "module";
+    version: string;
+    sideEffects: true;
+    exports: Record<string, unknown>;
+    peerDependencies?: Record<string, string>;
+};
+
+type ManifestInput = {
+    name: string;
+    version: string;
+    exports: Record<string, unknown>;
+    peerDependencies?: Record<string, string>;
+};
+
+export const buildManifest = (input: ManifestInput): Manifest => {
+    const manifest: Manifest = {
+        name: input.name,
+        type: "module",
+        version: input.version,
+        sideEffects: true,
+        exports: { "./package.json": "./package.json", ...input.exports },
+    };
+    if (input.peerDependencies) {
+        manifest.peerDependencies = input.peerDependencies;
+    }
+    return manifest;
+};
+
+export const writeStore = (params: WriteStoreParams): void => {
+    const tmp = tempStoreFor(params.storeDir);
+    try {
+        for (const file of params.files) {
+            writeSourceFile(tmp, file.fileName, file.source);
+        }
+        compileStore({
+            storeDir: tmp,
+            files: params.files,
+            packageName: params.manifest.name,
+            exports: params.manifest.exports,
+        });
+        writePackageJson(tmp, params.manifest);
+        for (const raw of params.rawFiles ?? []) {
+            writeFileSync(join(tmp, raw.relativePath), raw.content);
+        }
+        symlinkRelative(join(tmp, "node_modules", ...params.manifest.name.split("/")), tmp);
+        swapStore(tmp, params.storeDir, params.linkDir);
+    } finally {
+        rmSync(tmp, { recursive: true, force: true });
+    }
+};
+
+type WriteStoreParams = {
+    storeDir: string;
+    linkDir: string;
+    files: StoreFile[];
+    manifest: Manifest;
+    rawFiles?: { relativePath: string; content: string }[];
+};
+
+const writeSourceFile = (storeDir: string, fileName: string, source: string): void => {
+    const filePath = join(storeDir, fileName);
+    mkdirSync(dirname(filePath), { recursive: true });
+    writeFileSync(filePath, source);
+};
+
+const symlinkRelative = (linkPath: string, realTarget: string): void => {
+    mkdirSync(dirname(linkPath), { recursive: true });
+    rmSync(linkPath, { recursive: true, force: true });
+    symlinkSync(relative(dirname(linkPath), realTarget), linkPath, "dir");
+};
+
+const writePackageJson = (storeDir: string, manifest: Manifest): void => {
+    writeFileSync(join(storeDir, "package.json"), `${JSON.stringify(manifest, null, 2)}\n`);
+};
+
+const swapStore = (tmp: string, storeDir: string, visibleLink: string): void => {
+    const previous = `${storeDir}.old`;
+    rmSync(previous, { recursive: true, force: true });
+    if (existsSync(storeDir)) {
+        renameSync(storeDir, previous);
+    }
+    renameSync(tmp, storeDir);
+    rmSync(previous, { recursive: true, force: true });
+    symlinkRelative(visibleLink, storeDir);
+};
+
+const tempStoreFor = (storeDir: string): string => {
+    mkdirSync(dirname(storeDir), { recursive: true });
+    return mkdtempSync(`${storeDir}.tmp-`);
+};

package/src/writer/context.ts

@@ -0,0 +1,48 @@
+import type { Library } from "../gir/library.js";
+import type { GirNamespace } from "../gir/namespace.js";
+import { ModuleBuilder } from "./module.js";
+
+export class ModuleContext {
+    public module: ModuleBuilder = new ModuleBuilder();
+    public namespace: GirNamespace;
+    public library: Library;
+
+    constructor(namespace: GirNamespace, library: Library) {
+        this.namespace = namespace;
+        this.library = library;
+    }
+
+    addRuntimeImport(name: string): void {
+        this.module.imports.addNamed("@gtkx/runtime", name);
+    }
+
+    addRuntimeTypeImport(name: string): void {
+        this.module.imports.addNamed("@gtkx/runtime", name, true);
+    }
+
+    hoistDescriptor(expression: string): string {
+        return this.module.hoistDescriptor(expression);
+    }
+
+    addGObjectBootstrapImports(): void {
+        if (this.namespace.name === "GObject") return;
+        if (this.namespace.name === "GLib") return;
+        this.module.imports.addSideEffect("../gobject/overrides/object.js");
+        this.module.imports.addSideEffect("../gobject/overrides/value.js");
+    }
+
+    addCrossNamespaceImport(namespaceName: string): string {
+        if (namespaceName === this.namespace.name) return namespaceName;
+        const directory = namespaceName.toLowerCase();
+        const isFoundational = directory === "gobject" || directory === "glib";
+        const path = isFoundational ? `../${directory}/${directory}.js` : `../${directory}/index.js`;
+        if (!isFoundational) this.module.imports.addSideEffect(path);
+        this.module.imports.addNamespace(path, namespaceName);
+        return namespaceName;
+    }
+
+    qualify(namespaceName: string, typeName: string): string {
+        if (namespaceName === this.namespace.name) return typeName;
+        return `${this.addCrossNamespaceImport(namespaceName)}.${typeName}`;
+    }
+}

package/src/writer/doc.ts

@@ -0,0 +1,11 @@
+import { gtkDocToMarkdown } from "./gtk-doc.js";
+
+const escapeCommentTerminators = (doc: string): string => doc.replaceAll("*/", "*\\/");
+
+export const renderJsDoc = (doc: string | undefined): string => {
+    if (doc === undefined || doc.length === 0) return "";
+    const lines = escapeCommentTerminators(gtkDocToMarkdown(doc)).split("\n");
+    if (lines.length === 1) return `/** ${lines[0]} */\n`;
+    const body = lines.map((line) => (line.length === 0 ? " *" : ` * ${line}`)).join("\n");
+    return `/**\n${body}\n */\n`;
+};

package/src/writer/emit.ts

@@ -0,0 +1,26 @@
+export const indent = (block: string, level: number): string => {
+    if (level <= 0) return block;
+    const prefix = "    ".repeat(level);
+    return block
+        .split("\n")
+        .map((line) => (line.length === 0 ? line : `${prefix}${line}`))
+        .join("\n");
+};
+
+export const renderBlock = (head: string, body: string): string => `${head} {\n${indent(body, 1)}\n}`;
+
+export const renderBraced = (body: string): string => `{\n${indent(body, 1)}\n}`;
+
+export const renderBracedOrEmpty = (head: string, body: string): string =>
+    body.length === 0 ? `${head} {}` : renderBlock(head, body);
+
+export const indentMembers = (members: string[]): string => members.map((member) => indent(member, 1)).join("\n\n");
+
+export const joinArgs = (parts: Array<string | undefined>): string =>
+    parts.filter((part): part is string => part !== undefined).join(", ");
+
+export const arrayLiteral = (elements: string[]): string => {
+    if (elements.length === 0) return "[]";
+    const lines = elements.map((element) => `    ${element},`);
+    return `[\n${lines.join("\n")}\n]`;
+};

package/src/writer/gtk-doc.ts

@@ -0,0 +1,74 @@
+import { toCamelCase } from "@gtkx/utils";
+
+const CONSTANT_MAP: Record<string, string> = { TRUE: "true", FALSE: "false", NULL: "null" };
+
+const CALLABLE_LINK_KINDS: Set<string> = new Set(["method", "func", "ctor", "vfunc"]);
+
+const SENTINEL = String.fromCharCode(0xe000);
+
+const CODE_BLOCK_OPEN = "|[";
+const CODE_BLOCK_CLOSE = "]|";
+const CODE_LANGUAGE_PATTERN = /^\s*<!--\s*language="([^"]*)"\s*-->/;
+const FENCED_BLOCK_PATTERN = /```[\s\S]*?```/g;
+const INLINE_CODE_PATTERN = /`[^`\n]*`/g;
+const LINK_PATTERN = /\[(\w+)@([\w.:%#-]+)\]/g;
+const CONSTANT_PATTERN = /(?<!\w)%(\w+)/g;
+const TYPE_REF_PATTERN = /(?<!\w)#(\w+)/g;
+const PARAM_REF_PATTERN = /(?<!\w)@(\w+)/g;
+const FUNCTION_REF_PATTERN = /\b([a-z_][a-z0-9_]*)\(\)/g;
+
+const renderLink = (kind: string, target: string): string => {
+    const segments = target.split(/::|[.:]/);
+    const lastIndex = segments.length - 1;
+    if (CALLABLE_LINK_KINDS.has(kind) || kind === "property") {
+        segments[lastIndex] = toCamelCase(segments[lastIndex] ?? "");
+    }
+    const symbol = segments.join(".");
+    return `\`${symbol}${CALLABLE_LINK_KINDS.has(kind) ? "()" : ""}\``;
+};
+
+const renderCodeFence = (body: string): string => {
+    const languageMatch = body.match(CODE_LANGUAGE_PATTERN);
+    const fence = (languageMatch?.[1] ?? "").trim().toLowerCase();
+    const rest = languageMatch === null ? body : body.slice(languageMatch[0].length);
+    const code = rest.replace(/^\s+/, "").replace(/\n+$/, "");
+    return `\`\`\`${fence}\n${code}\n\`\`\``;
+};
+
+const protectCodeBlocks = (raw: string, protect: (value: string) => string): string => {
+    let result = "";
+    let cursor = 0;
+    while (cursor < raw.length) {
+        const open = raw.indexOf(CODE_BLOCK_OPEN, cursor);
+        if (open === -1) break;
+        const close = raw.indexOf(CODE_BLOCK_CLOSE, open + CODE_BLOCK_OPEN.length);
+        if (close === -1) break;
+        result += raw.slice(cursor, open);
+        result += protect(renderCodeFence(raw.slice(open + CODE_BLOCK_OPEN.length, close)));
+        cursor = close + CODE_BLOCK_CLOSE.length;
+    }
+    return result + raw.slice(cursor);
+};
+
+export const gtkDocToMarkdown = (raw: string): string => {
+    const stash: string[] = [];
+    const protect = (value: string): string => {
+        const token = `${SENTINEL}${stash.length}${SENTINEL}`;
+        stash.push(value);
+        return token;
+    };
+
+    let text = protectCodeBlocks(raw, protect);
+    text = text.replace(FENCED_BLOCK_PATTERN, (block) => protect(block));
+    text = text.replace(INLINE_CODE_PATTERN, (span) => protect(span));
+    text = text.replace(LINK_PATTERN, (_match, kind: string, target: string) => protect(renderLink(kind, target)));
+    text = text.replace(CONSTANT_PATTERN, (_match, name: string) => protect(`\`${CONSTANT_MAP[name] ?? name}\``));
+    text = text.replace(TYPE_REF_PATTERN, (_match, name: string) => protect(`\`${name}\``));
+    text = text.replace(PARAM_REF_PATTERN, (_match, name: string) => protect(`\`${name}\``));
+    text = text.replace(FUNCTION_REF_PATTERN, (_match, name: string) => protect(`\`${name}()\``));
+
+    for (let index = stash.length - 1; index >= 0; index -= 1) {
+        text = text.replaceAll(`${SENTINEL}${index}${SENTINEL}`, stash[index] ?? "");
+    }
+    return text;
+};

package/src/writer/imports.ts

@@ -0,0 +1,59 @@
+import { sortStrings, sortStringsBy, sourceStringLiteral } from "@gtkx/utils";
+
+type NamespaceImport = {
+    alias: string;
+    isType: boolean;
+};
+
+export class ImportsBuilder {
+    private named = new Map<string, Map<string, boolean>>();
+    private namespaces = new Map<string, NamespaceImport>();
+    private sideEffects = new Set<string>();
+
+    addNamed(specifier: string, name: string, isType = false): void {
+        let bucket = this.named.get(specifier);
+        if (bucket === undefined) {
+            bucket = new Map();
+            this.named.set(specifier, bucket);
+        }
+        bucket.set(name, (bucket.get(name) ?? true) && isType);
+    }
+
+    addNamespace(specifier: string, alias: string, isType = false): void {
+        if (!this.namespaces.has(specifier)) {
+            this.namespaces.set(specifier, { alias, isType });
+        }
+    }
+
+    addSideEffect(specifier: string): void {
+        this.sideEffects.add(specifier);
+    }
+
+    toSource(): string {
+        const lines: string[] = [];
+        for (const specifier of this.sideEffects) {
+            lines.push(`import ${sourceStringLiteral(specifier)};`);
+        }
+        const specifiers = new Set<string>([...this.named.keys(), ...this.namespaces.keys()]);
+        const sortedSpecifiers = sortStrings(specifiers);
+        for (const specifier of sortedSpecifiers) {
+            const namespaceImport = this.namespaces.get(specifier);
+            const namedNames = this.named.get(specifier);
+            if (namespaceImport?.isType === true) {
+                lines.push(`import type * as ${namespaceImport.alias} from ${sourceStringLiteral(specifier)};`);
+                continue;
+            }
+            const parts: string[] = [];
+            if (namespaceImport !== undefined) parts.push(`* as ${namespaceImport.alias}`);
+            if (namedNames !== undefined && namedNames.size > 0) {
+                const sortedNames = sortStringsBy(namedNames.entries(), ([name]) => name).map(([name, isType]) =>
+                    isType ? `type ${name}` : name,
+                );
+                parts.push(`{ ${sortedNames.join(", ")} }`);
+            }
+            if (parts.length === 0) continue;
+            lines.push(`import ${parts.join(", ")} from ${sourceStringLiteral(specifier)};`);
+        }
+        return lines.length === 0 ? "" : `${lines.join("\n")}\n`;
+    }
+}

package/src/writer/module.ts

@@ -0,0 +1,45 @@
+import { ImportsBuilder } from "./imports.js";
+
+export class ModuleBuilder {
+    public imports: ImportsBuilder = new ImportsBuilder();
+    private bindings: string[] = [];
+    private bindingNames = new Set<string>();
+    private hoistedDescriptors = new Map<string, string>();
+    private declarations: string[] = [];
+    private registrations: string[] = [];
+
+    appendBinding(code: string, name?: string): void {
+        if (name !== undefined) {
+            if (this.bindingNames.has(name)) return;
+            this.bindingNames.add(name);
+        }
+        this.bindings.push(code);
+    }
+
+    hoistDescriptor(expression: string): string {
+        const existing = this.hoistedDescriptors.get(expression);
+        if (existing !== undefined) return existing;
+        const name = `_desc${this.hoistedDescriptors.size}`;
+        this.hoistedDescriptors.set(expression, name);
+        this.appendBinding(`const ${name} = ${expression};`, name);
+        return name;
+    }
+
+    appendDeclaration(code: string): void {
+        this.declarations.push(code);
+    }
+
+    appendRegistration(code: string): void {
+        this.registrations.push(code);
+    }
+
+    toSource(): string {
+        const sections: string[] = [];
+        const importsBlock = this.imports.toSource();
+        if (importsBlock.length > 0) sections.push(importsBlock.trimEnd());
+        if (this.declarations.length > 0) sections.push(this.declarations.join("\n\n"));
+        if (this.bindings.length > 0) sections.push(this.bindings.join("\n\n"));
+        if (this.registrations.length > 0) sections.push(this.registrations.join("\n\n"));
+        return `${sections.join("\n\n")}\n`;
+    }
+}