@hey-api/codegen-core 0.1.0 → 0.2.0

package/dist/index.d.cts

@@ -6,7 +6,7 @@
  * @template Key Type of the map keys
  * @template Value Type of the map values
  */
-interface ICodegenBiMap<Key, Value> {
+interface IBiMap<Key, Value> {
   /**
    * Deletes a key and its associated value from the map.
    *
@@ -73,642 +73,512 @@ interface ICodegenBiMap<Key, Value> {
   [Symbol.iterator](): IterableIterator<[Key, Value]>;
 }
 
-declare class BiMap<Key, Value> implements ICodegenBiMap<Key, Value> {
-    private map;
-    private reverse;
-    delete(key: Key): boolean;
-    deleteValue(value: Value): boolean;
-    entries(): IterableIterator<[Key, Value]>;
-    get(key: Key): Value | undefined;
-    getKey(value: Value): Key | undefined;
-    hasKey(key: Key): boolean;
-    hasValue(value: Value): boolean;
-    keys(): IterableIterator<Key>;
-    set(key: Key, value: Value): this;
-    get size(): number;
-    values(): IterableIterator<Value>;
-    [Symbol.iterator](): IterableIterator<[Key, Value]>;
-}
-
-/**
- * Arbitrary metadata passed to render functions.
- *
- * Implementors should extend this interface for their own needs.
- */
-interface ICodegenMeta {
-  [key: string]: unknown;
-}
-
-interface ICodegenOutput {
+interface IBinding {
   /**
-   * The main content of the file to output.
+   * Optional aliasing map for named symbols.
    *
-   * A raw string representing source code.
+   * Keys must be a subset of `names`, values are aliases.
    *
-   * @example "function foo(): void {\n  // implementation\n}\n"
+   * @example { User: "ImportedUser" }
    */
-  content: string;
+  aliases?: Record<string, string>;
   /**
-   * Optional metadata or hints for the emitter, such as formatting options,
-   * source maps, or language-specific flags.
+   * Name of the default binding, if any.
    *
-   * @example { format: "prettier", sourceMap: true }
+   * @example "React"
    */
-  meta: Record<string, unknown>;
+  defaultBinding?: string;
   /**
-   * Logical output path (used for writing the file).
+   * Source file or external module from which symbols are imported.
    *
-   * @example "models/user.ts"
+   * @example "./models/user"
+   * @example "node:path"
    */
-  path: string;
-}
-
-interface ICodegenRenderer {
+  from: string;
   /**
-   * Optional: hook for renderer-level setup logic (e.g., formatting, config)
+   * Names of the symbols imported from the source.
+   *
+   * Must be non-empty unless `namespaceBinding` is true.
+   * All imported names, regardless of whether they are used as types or values.
+   *
+   * @example ["User", "UserDTO"]
    */
-  configure?(options: Record<string, unknown>): void;
+  names?: ReadonlyArray<string>;
   /**
-   * Unique identifier for this renderer.
+   * If this import is a namespace import (e.g. `import * as ns from "..."`),
+   * this should be the namespace alias. Set to `true` if no alias is needed.
    *
-   * @example "typescript"
+   * @example "utils"
+   * @example true
    */
-  id: string;
+  namespaceBinding?: boolean | string;
   /**
-   * Returns printable data containing header and imports.
+   * Whether the default binding is type-only.
    *
-   * @param file The file to render.
-   * @param meta Arbitrary metadata.
-   * @returns Printable string containing header and imports.
+   * @example true
    */
-  renderHeader(file: ICodegenFile, meta?: ICodegenMeta): string;
+  typeDefaultBinding?: boolean;
   /**
-   * Returns printable data containing symbols and exports.
+   * Subset of `names` that are imported using the `type` modifier.
+   * These symbols will be emitted as type-only imports in TypeScript.
    *
-   * @param file The file to render.
-   * @param meta Arbitrary metadata.
-   * @returns Printable string containing symbols and exports.
+   * @example ["UserDTO"]
    */
-  renderSymbols(file: ICodegenFile, meta?: ICodegenMeta): string;
+  typeNames?: ReadonlyArray<string>;
   /**
-   * Function replacing symbols with resolved names.
+   * Whether the namespace binding is type-only.
    *
-   * @returns String with replaced symbols.
+   * @example true
    */
-  replacerFn(args: {
-    file: ICodegenFile;
-    headless?: boolean;
-    scope?: 'file' | 'project';
-    symbolId: number;
-  }): string | undefined;
+  typeNamespaceBinding?: boolean;
 }
 
 /**
- * Selector array used to select symbols. It doesn't have to be
- * unique, but in practice it might be desirable.
+ * Selector array used to reference resources. We don't enforce
+ * uniqueness, but in practice it's desirable.
  *
  * @example ["zod", "#/components/schemas/Foo"]
  */
-type ICodegenSymbolSelector = ReadonlyArray<string>;
+type ISelector = ReadonlyArray<string>;
 
-interface ICodegenSymbolIn {
+interface IFileIn {
   /**
-   * Symbols can be **headed** or **headless**.
-   *
-   * Headless symbols never render their `value`. Headed symbols render their
-   * `value` if defined.
-   *
-   * Symbols are rendered in the order they were registered as headed.
-   *
-   * Example 1: We register headless symbol `foo`, headed `bar`, and headed
-   * `foo`. The render order is [`bar`, `foo`].
-   *
-   * Example 2: We register headed symbol `foo` and headed `bar`. The render
-   * order is [`foo`, `bar`].
-   *
-   * Headless symbols can be used to claim a symbol or to represent imports
-   * or exports.
+   * File extension, if any.
+   */
+  readonly extension?: string;
+  /**
+   * Indicates whether the file is external, meaning it is not generated
+   * as part of the project but is referenced (e.g., a module from
+   * node_modules).
    *
-   * @default false
+   * @example true
    */
-  headless?: boolean;
+  readonly external?: boolean;
   /**
-   * The desired name for the symbol within its file. If there are multiple symbols
+   * Unique file ID. If one is not provided, it will be auto-generated.
+   */
+  readonly id?: number;
+  /**
+   * The desired name for the file within the project. If there are multiple files
    * with the same desired name, this might not end up being the actual name.
    *
    * @example "UserModel"
    */
-  readonly name: string;
+  readonly name?: string;
   /**
-   * Selector array used to select this symbol. It doesn't have to be
-   * unique, but in practice it might be desirable.
+   * Absolute logical output path for the file.
    *
-   * @example ["zod", "#/components/schemas/Foo"]
+   * @example "/src/models/user.ts"
    */
-  readonly selector?: ICodegenSymbolSelector;
+  readonly path?: string;
   /**
-   * Internal representation of the symbol (e.g. AST node, IR object, raw code).
-   * Used to generate output. If left undefined, this symbol becomes `headless`.
+   * Selector array used to select this file. It doesn't have to be
+   * unique, but in practice it might be desirable.
+   *
+   * @example ["zod", "#/components/schemas/Foo"]
    */
-  readonly value?: unknown;
+  readonly selector?: ISelector;
 }
 
-interface ICodegenSymbolOut extends ICodegenSymbolIn {
+interface IFileOut extends IFileIn {
   /**
-   * The file this symbol is located in.
-   */
-  readonly file: ICodegenFile;
-  /**
-   * Unique symbol ID.
+   * Unique file ID.
    */
   readonly id: number;
   /**
-   * Placeholder name for the symbol to be replaced later with the final value.
-   *
-   * @example "_heyapi_31_"
+   * Map holding resolved names for symbols in this file.
    */
-  readonly placeholder: string;
+  readonly resolvedNames: IBiMap<number, string>;
   /**
-   * Updates this symbol.
-   *
-   * @param symbol The values to update.
-   * @returns The updated symbol.
+   * Symbols in this file, categorized by their role.
    */
-  readonly update: (symbol: Partial<ICodegenSymbolOut>) => ICodegenSymbolOut;
+  readonly symbols: {
+    /**
+     * Symbols declared in the body of this file.
+     */
+    body: Array<number>;
+    /**
+     * Symbols re-exported from other files.
+     */
+    exports: Array<number>;
+    /**
+     * Symbols imported from other files.
+     */
+    imports: Array<number>;
+  };
 }
 
-interface SelectorMethods {
+interface IFileRegistry {
   /**
-   * Retrieves symbols matching the selector.
+   * Get a file by its ID.
    *
-   * @param selector The symbol selector to find.
-   * @param file Find symbols only in this file.
-   * @returns The array of all symbols matching the selector.
-   * @example
-   * const symbols = project.selectSymbolAll(["zod", "#/components/schemas/Foo"]);
+   * @param fileIdOrSelector File ID or selector to reference.
+   * @returns The file, or undefined if not found.
    */
-  selectSymbolAll(
-    selector: ICodegenSymbolSelector,
-    file?: ICodegenFile,
-  ): ReadonlyArray<ICodegenSymbolOut>;
+  get(fileIdOrSelector: number | ISelector): IFileOut | undefined;
   /**
-   * Retrieves the first symbol from all symbols matching the selector.
+   * Returns the current file ID and increments it.
    *
-   * @param selector The symbol selector to find.
-   * @param file Find symbols only in this file.
-   * @returns The symbol if found, or undefined otherwise.
-   * @example
-   * const symbol = project.selectSymbolFirst(["zod", "#/components/schemas/Foo"]);
+   * @returns File ID before being incremented
    */
-  selectSymbolFirst(
-    selector: ICodegenSymbolSelector,
-    file?: ICodegenFile,
-  ): ICodegenSymbolOut | undefined;
+  readonly id: number;
   /**
-   * Retrieves the first symbol from all symbols matching the selector.
+   * Returns a file by ID or selector, registering it if it doesn't exist.
    *
-   * @param selector The symbol selector to find.
-   * @param file Find symbols only in this file.
-   * @returns The symbol if found, or throw otherwise.
-   * @example
-   * const symbol = project.selectSymbolFirstOrThrow(["zod", "#/components/schemas/Foo"]);
+   * @param fileIdOrSelector File ID or selector to reference.
+   * @returns The referenced or newly registered file.
    */
-  selectSymbolFirstOrThrow(
-    selector: ICodegenSymbolSelector,
-    file?: ICodegenFile,
-  ): ICodegenSymbolOut;
+  reference(fileIdOrSelector: number | ISelector): IFileOut;
   /**
-   * Retrieves the last symbol from all symbols matching the selector.
+   * Get all unregistered files in the order they were referenced.
    *
-   * @param selector The symbol selector to find.
-   * @param file Find symbols only in this file.
-   * @returns The symbol if found, or undefined otherwise.
-   * @example
-   * const symbol = project.selectSymbolLast(["zod", "#/components/schemas/Foo"]);
+   * @returns Array of all unregistered files, in reference order.
    */
-  selectSymbolLast(
-    selector: ICodegenSymbolSelector,
-    file?: ICodegenFile,
-  ): ICodegenSymbolOut | undefined;
-}
-
-/**
- * Represents a code generation project consisting of multiple codegen files.
- * Manages imports, symbols, and output generation across the project.
- */
-interface ICodegenProject extends SelectorMethods {
+  referenced(): IterableIterator<IFileOut>;
   /**
-   * Adds an export declaration to a specific file, creating the file if it doesn't exist.
+   * Register a file globally.
    *
-   * @param fileOrPath - File instance or file path where to add the export.
-   * @param imp - The export declaration to add.
-   * @example
-   * project.addExport("models/user.ts", { from: "lib", names: ["User"] });
+   * Deduplicates identical files by ID.
+   *
+   * @param file File to register.
+   * @returns true if added, false if duplicate.
    */
-  addExport(fileOrPath: ICodegenFile | string, imp: ICodegenImport): void;
+  register(file: IFileIn): IFileOut;
   /**
-   * Adds an import declaration to a specific file, creating the file if it doesn't exist.
+   * Get all files in the order they were registered.
    *
-   * @param fileOrPath - File instance or file path where to add the import.
-   * @param imp - The import declaration to add.
-   * @example
-   * project.addImport("models/user.ts", { from: "lib", names: ["User"] });
+   * @returns Array of all registered files, in insert order.
    */
-  addImport(fileOrPath: ICodegenFile | string, imp: ICodegenImport): void;
+  registered(): IterableIterator<IFileOut>;
+}
+
+/**
+ * Arbitrary metadata passed to the project's render function.
+ *
+ * Implementers should extend this interface for their own needs.
+ */
+interface IProjectRenderMeta {
+  [key: string]: unknown;
+}
+
+/**
+ * Additional metadata about the symbol.
+ *
+ * Implementers should extend this interface for their own needs.
+ */
+interface ISymbolMeta {
+  [key: string]: unknown;
+}
+
+interface ISymbolIn {
   /**
-   * Adds a symbol to a specific file, creating the file if it doesn't exist.
+   * Array of file names (without extensions) from which this symbol is re-exported.
    *
-   * @param fileOrPath - File instance or file path where to add the symbol.
-   * @param symbol - The symbol to add.
-   * @returns The inserted symbol.
-   * @example
-   * project.addSymbol("models/user.ts", { name: "User", value: tsNode });
+   * @default undefined
    */
-  addSymbol(
-    fileOrPath: ICodegenFile | string,
-    symbol: ICodegenSymbolIn,
-  ): ICodegenSymbolOut;
+  readonly exportFrom?: ReadonlyArray<string>;
   /**
-   * Creates a new codegen file with optional metadata and adds it to the project.
-   *
-   * If a file with the same path already exists, it is returned instead.
+   * Whether this symbol is exported from its own file.
    *
-   * @param path - The logical output path for the file (e.g. "models/user.ts").
-   * @param meta - Optional renderer and metadata to attach to the file (e.g. { isInternal: true }).
-   * @returns The newly created file instance.
-   * @example
-   * const file = project.createFile("models/user.ts", { isInternal: true });
+   * @default false
    */
-  createFile(
-    path: string,
-    meta?: ICodegenFile['meta'] & { renderer?: ICodegenRenderer },
-  ): ICodegenFile;
+  readonly exported?: boolean;
   /**
-   * Ensures a codegen file exists and returns it.
+   * External module name if this symbol is imported from a module not managed
+   * by the project (e.g. "zod", "lodash").
    *
-   * If a file does not exist yet, it is created with minimal information.
-   * Later, it is expected `createFile()` will be called which will fill in
-   * the missing information such as optional metadata.
-   *
-   * @param fileOrPath - The logical output path for the file or the file itself.
-   * @returns The file instance.
-   * @example
-   * const file = project.ensureFile("models/user.ts");
+   * @default undefined
    */
-  ensureFile(fileOrPath: ICodegenFile | string): ICodegenFile;
+  readonly external?: string;
   /**
-   * Returns all files in the project in insertion order.
+   * Optional output strategy to override default behavior.
    *
-   * @example
-   * project.files.forEach(file => console.log(file.path));
+   * @returns The file path to output the symbol to, or undefined to fallback to default behavior.
    */
-  readonly files: ReadonlyArray<ICodegenFile>;
+  readonly getFilePath?: (symbol: ISymbolOut) => string | undefined;
   /**
-   * Returns all symbols declared or imported across all files.
-   *
-   * @returns Flattened list of all codegen symbols.
-   * @example
-   * project.getAllSymbols().filter(s => s.name === "User");
+   * Unique symbol ID. If one is not provided, it will be auto-generated.
    */
-  getAllSymbols(): ReadonlyArray<Pick<ICodegenSymbolOut, 'name'>>;
+  readonly id?: number;
   /**
-   * Retrieves a file by its logical output path.
+   * Arbitrary metadata about the symbol.
    *
-   * @param path - The file path to find.
-   * @returns The file if found, or undefined otherwise.
-   * @example
-   * const file = project.getFileByPath("models/user.ts");
+   * @default undefined
    */
-  getFileByPath(path: string): ICodegenFile | undefined;
+  readonly meta?: ISymbolMeta & {
+    /**
+     * Kind of import if this symbol represents an import.
+     */
+    importKind?: 'namespace' | 'default' | 'named';
+    /**
+     * Kind of symbol.
+     */
+    kind?: 'type';
+  };
   /**
-   * Retrieves a file from symbol ID included in the file.
+   * The desired name for the symbol within its file. If there are multiple symbols
+   * with the same desired name, this might not end up being the actual name.
    *
-   * @param id The symbol ID to find.
-   * @returns The file if found, undefined otherwise.
-   * @example
-   * const file = project.getFileBySymbolId(31);
+   * @example "UserModel"
    */
-  getFileBySymbolId(id: number): ICodegenFile | undefined;
+  readonly name?: string;
   /**
-   * Retrieves a symbol from ID included in the project.
+   * Placeholder name for the symbol to be replaced later with the final value.
    *
-   * @param id The symbol ID to find.
-   * @returns The symbol if found, undefined otherwise.
-   * @example
-   * const symbol = project.getSymbolById(31);
+   * @example "_heyapi_31_"
    */
-  getSymbolById(id: number): ICodegenSymbolOut | undefined;
+  readonly placeholder?: string;
   /**
-   * Returns the current file ID and increments it.
+   * Selector array used to select this symbol. It doesn't have to be
+   * unique, but in practice it might be desirable.
    *
-   * @returns File ID before being incremented
+   * @example ["zod", "#/components/schemas/Foo"]
    */
-  incrementFileId(): number;
+  readonly selector?: ISelector;
+}
+
+interface ISymbolOut extends ISymbolIn {
   /**
-   * Returns the current symbol ID and increments it.
-   *
-   * @returns Symbol ID before being incremented
+   * Array of file names (without extensions) from which this symbol is re-exported.
    */
-  incrementSymbolId(): number;
+  readonly exportFrom: ReadonlyArray<string>;
   /**
-   * Tracks added symbol across the project.
-   *
-   * @param symbol The symbol added to file.
-   * @param file The file containing the added symbol.
+   * Unique symbol ID.
    */
-  registerSymbol(symbol: ICodegenSymbolOut, file: ICodegenFile): void;
+  readonly id: number;
   /**
-   * Produces output representations for all files in the project.
+   * Placeholder name for the symbol to be replaced later with the final value.
    *
-   * @param meta Arbitrary metadata.
-   * @returns Array of outputs ready for writing or further processing.
-   * @example
-   * project.render().forEach(output => writeFile(output));
+   * @example "_heyapi_31_"
    */
-  render(meta?: ICodegenMeta): ReadonlyArray<ICodegenOutput>;
+  readonly placeholder: string;
 }
 
-interface ICodegenFile extends SelectorMethods {
+interface ISymbolRegistry {
   /**
-   * Adds an export to this file.
-   *
-   * This is also known as a re-export.
+   * Get a symbol by its ID.
    *
-   * @param exp The export to add
+   * @param symbolIdOrSelector Symbol ID or selector to reference.
+   * @returns The symbol, or undefined if not found.
    */
-  addExport(exp: ICodegenImport): void;
+  get(symbolIdOrSelector: number | ISelector): ISymbolOut | undefined;
   /**
-   * Adds an import to this file.
+   * Returns the value associated with a symbol ID.
    *
-   * @param imp The import to add
+   * @param symbolId Symbol ID.
+   * @return The value associated with the symbol ID, or undefined if not found.
    */
-  addImport(imp: ICodegenImport): void;
+  getValue(symbolId: number): unknown;
   /**
-   * Adds a symbol defined by this file.
+   * Checks if the registry has a value associated with a symbol ID.
    *
-   * @param symbol The symbol to add
+   * @param symbolId Symbol ID.
+   * @returns True if the registry has a value for symbol ID, false otherwise.
    */
-  addSymbol(symbol: ICodegenSymbolIn): ICodegenSymbolOut;
+  hasValue(symbolId: number): boolean;
   /**
-   * Ensures a symbol for the given selector exists, so it can be
-   * safely used.
+   * Returns the current symbol ID and increments it.
    *
-   * @param symbol The symbol to find. The required selector is used
-   *  to match a symbol. If there's no match, we create a headless
-   *  instance with the provided fields.
-   * @returns The symbol if it exists, headless instance otherwise.
+   * @returns Symbol ID before being incremented.
    */
-  ensureSymbol(
-    symbol: Partial<ICodegenSymbolIn> &
-      Pick<Required<ICodegenSymbolIn>, 'selector'>,
-  ): ICodegenSymbolOut;
-  /**
-   * Symbols exported from other files.
-   **/
-  exports: ReadonlyArray<ICodegenImport>;
+  readonly id: number;
   /**
-   * Returns all symbols used in this file (declared + imported).
+   * Returns a symbol by ID or selector, registering it if it doesn't exist.
    *
-   * @returns List of all symbols used in this file
+   * @param symbolIdOrSelector Symbol ID or selector to reference.
+   * @returns The referenced or newly registered symbol.
    */
-  getAllSymbols(): ReadonlyArray<Pick<ICodegenSymbolOut, 'name'>>;
+  reference(symbolIdOrSelector: number | ISelector): ISymbolOut;
   /**
-   * Finds a symbol by symbol ID.
+   * Register a symbol globally.
+   *
+   * Deduplicates identical symbols by ID.
    *
-   * @param id Symbol ID
-   * @returns The symbol if it exists, undefined otherwise.
+   * @param symbol Symbol to register.
+   * @returns The registered symbol.
    */
-  getSymbolById(id: number): ICodegenSymbolOut | undefined;
+  register(symbol: ISymbolIn): ISymbolOut;
   /**
-   * Checks if this file contains any content.
+   * Get all symbols in the order they were registered.
    *
-   * This is used to determine whether we want to process the file further.
-   * By default, we consider only symbols and exports as content.
-   *
-   * @returns True if the file contains content
+   * @returns Array of all registered symbols, in insert order.
    */
-  hasContent(): boolean;
+  registered(): IterableIterator<ISymbolOut>;
   /**
-   * Checks if this file defines a symbol with the given name.
+   * Sets a value for a symbol by its ID.
    *
-   * @param id Symbol ID to check
-   * @returns True if the symbol is defined by this file
+   * @param symbolId Symbol ID.
+   * @param value The value to set.
+   * @returns void
    */
-  hasSymbol(id: number): boolean;
+  setValue(symbolId: number, value: unknown): Map<number, unknown>;
+}
+
+declare const createBinding: ({ file, modulePath, symbol, symbolFile, }: {
+    file: IFileOut;
+    modulePath: string;
+    symbol: ISymbolOut;
+    symbolFile: IFileOut;
+}) => IBinding;
+declare const mergeBindings: (target: IBinding, source: IBinding) => void;
+
+interface IOutput {
   /**
-   * File ID within the project.
+   * The main content of the file to output.
+   *
+   * A raw string representing source code.
+   *
+   * @example "function foo(): void {\n  // implementation\n}\n"
    */
-  id: number;
-  /**
-   * Symbols imported from other files.
-   **/
-  imports: ReadonlyArray<ICodegenImport>;
-  /**
-   * Optional metadata about the file.
-   **/
-  meta: {
-    /**
-     * Optional file extension.
-     *
-     * @example ".ts"
-     */
-    extension?: '.ts' | (string & {});
-    /**
-     * Optional logical module or package name.
-     *
-     * @example "models.user"
-     */
-    moduleName?: string;
-    /**
-     * Optional path transformer.
-     *
-     * @param path Original file path passed to the constructor.
-     */
-    path?: ((path: string) => string) | string;
-    /**
-     * Renderer ID.
-     *
-     * @example "typescript"
-     */
-    renderer?: ICodegenRenderer['id'];
-  };
+  content: string;
   /**
    * Logical output path (used for writing the file).
    *
    * @example "models/user.ts"
    */
   path: string;
+}
+
+declare class FileRegistry implements IFileRegistry {
+    private _id;
+    private referenceOrder;
+    private registerOrder;
+    private selectorToId;
+    private values;
+    get(fileIdOrSelector: number | ISelector): IFileOut | undefined;
+    get id(): number;
+    private idOrSelector;
+    reference(fileIdOrSelector: number | ISelector): IFileOut;
+    referenced(): IterableIterator<IFileOut>;
+    register(file: IFileIn): IFileOut;
+    registered(): IterableIterator<IFileOut>;
+}
+
+/**
+ * Represents a code generation project consisting of multiple codegen files.
+ * Manages imports, symbols, and output generation across the project.
+ */
+interface IProject {
   /**
-   * Parent project this file belongs to.
-   */
-  project: ICodegenProject;
-  /**
-   * Returns a relative path to this file from another file.
-   *
-   * @param file The file from which we want the relative path to this file.
-   * @example "./this-file.ts"
-   */
-  relativePathFromFile(file: Pick<ICodegenFile, 'path'>): string;
-  /**
-   * Returns a relative path to file from this file.
+   * The default file to assign symbols without a specific file selector.
    *
-   * @param file The file to which we want the relative path.
-   * @example "./another-file.ts"
-   */
-  relativePathToFile(file: Pick<ICodegenFile, 'path'>): string;
-  /**
-   * Map holding resolved names for symbols in this file.
+   * @default 'main'
    */
-  resolvedNames: ICodegenBiMap<number, string>;
+  readonly defaultFileName?: string;
   /**
-   * Top-level symbols declared in this file.
-   **/
-  symbols: ReadonlyArray<ICodegenSymbolOut>;
-  /**
-   * Updates a symbol defined by this file.
+   * Optional function to transform file names before they are used.
    *
-   * @param id ID of symbol to update.
-   * @param symbol The values to update.
-   * @returns The updated symbol.
+   * @param name The original file name.
+   * @returns The transformed file name.
    */
-  updateSymbol(
-    id: number,
-    symbol: Partial<ICodegenSymbolOut>,
-  ): ICodegenSymbolOut;
-}
-
-interface ICodegenImport {
+  readonly fileName?: (name: string) => string;
   /**
-   * Optional aliasing map for imported symbols.
-   *
-   * Keys must be a subset of `names`, values are aliases.
-   *
-   * @example { User: "ImportedUser" }
+   * Centralized file registry for the project.
    */
-  aliases?: Record<string, string>;
+  readonly files: IFileRegistry;
   /**
-   * Name of the default import, if any.
+   * Produces output representations for all files in the project.
    *
-   * @example "React"
+   * @param meta Arbitrary metadata.
+   * @returns Array of outputs ready for writing or further processing.
+   * @example
+   * project.render().forEach(output => writeFile(output));
    */
-  defaultImport?: string;
+  render(meta?: IProjectRenderMeta): ReadonlyArray<IOutput>;
   /**
-   * Source file or external module from which symbols are imported.
+   * Map of available renderers by file extension.
    *
-   * For internal files, this should be a ICodegenFile instance to enable
-   * dynamic path computation. For external or system modules, use a string.
-   *
-   * @example "./models/user"
-   * @example "node:path"
+   * @example
+   * {
+   *   ".ts": tsRenderer,
+   *   ".js": jsRenderer,
+   * }
    */
-  from: ICodegenFile | string;
+  readonly renderers: Record<string, IRenderer>;
   /**
-   * Names of the symbols imported from the source.
-   *
-   * Must be non-empty unless `isNamespaceImport` is true.
-   * All imported names, regardless of whether they are used as types or values.
-   *
-   * @example ["User", "UserDTO"]
+   * The absolute path to the root folder of the project.
    */
-  names?: ReadonlyArray<string>;
+  readonly root: string;
   /**
-   * If this import is a namespace import (e.g. `import * as ns from "..."`),
-   * this should be the namespace alias. Set to `true` if no alias is needed.
+   * Retrieves files that include symbol ID. The first file is the one
+   * where the symbol is declared, the rest are files that re-export it.
    *
-   * @example "utils"
-   * @example true
+   * @param symbolId The symbol ID to find.
+   * @returns An array of files containing the symbol.
+   * @example
+   * const files = project.symbolIdToFiles(31);
+   * for (const file of files) {
+   *   console.log(file.path);
+   * }
    */
-  namespaceImport?: boolean | string;
+  symbolIdToFiles(symbolId: number): ReadonlyArray<IFileOut>;
   /**
-   * Whether the default import is type-only.
-   *
-   * @example true
+   * Centralized symbol registry for the project.
    */
-  typeDefaultImport?: boolean;
+  readonly symbols: ISymbolRegistry;
+}
+
+interface IRenderer {
   /**
-   * Subset of `names` that are imported using the `type` modifier.
-   * These symbols will be emitted as type-only imports in TypeScript.
+   * Renders content with replaced symbols.
    *
-   * @example ["UserDTO"]
+   * @param content Content to render.
+   * @param file The file to render.
+   * @param project The parent project the file belongs to.
+   * @returns Rendered content.
    */
-  typeNames?: ReadonlyArray<string>;
+  renderFile(
+    content: string,
+    file: IFile,
+    project: IProject,
+    meta?: IProjectRenderMeta,
+  ): string;
   /**
-   * Whether the namespace import is type-only.
+   * Returns printable data containing symbols and exports.
    *
-   * @example true
+   * @param file The file to render.
+   * @param project The parent project the file belongs to.
+   * @param meta Arbitrary metadata.
+   * @returns Printable string containing symbols and exports.
    */
-  typeNamespaceImport?: boolean;
+  renderSymbols(
+    file: IFileOut,
+    project: IProject,
+    meta?: IProjectRenderMeta,
+  ): string;
 }
 
-declare class CodegenFile implements ICodegenFile {
-    path: string;
-    project: ICodegenProject;
-    meta: ICodegenFile['meta'];
-    private cache;
-    private renderSymbols;
-    private state;
-    id: number;
-    resolvedNames: ICodegenBiMap<number, string>;
-    constructor(path: string, project: ICodegenProject, meta?: ICodegenFile['meta']);
-    addExport(exp: ICodegenImport): void;
-    addImport(imp: ICodegenImport): void;
-    private addImportExport;
-    private addRenderSymbol;
-    addSymbol(symbol: ICodegenSymbolIn): ICodegenSymbolOut;
-    ensureSymbol(symbol: Partial<ICodegenSymbolIn> & Pick<Required<ICodegenSymbolIn>, 'selector'>): ICodegenSymbolOut;
-    get exports(): ReadonlyArray<ICodegenImport>;
-    getAllSymbols(): ReadonlyArray<Pick<ICodegenSymbolOut, 'name'>>;
-    private getImportExportKey;
-    getSymbolById(id: number): ICodegenSymbolOut | undefined;
-    hasContent(): boolean;
-    hasSymbol(id: number): boolean;
-    get imports(): ReadonlyArray<ICodegenImport>;
-    private mergeImportExportValues;
-    static pathToFilePath(source: string): string;
-    relativePathFromFile(file: Pick<ICodegenFile, 'path'>): string;
-    relativePathToFile(file: Pick<ICodegenFile, 'path'>): string;
-    selectSymbolAll(selector: ICodegenSymbolSelector): ReadonlyArray<ICodegenSymbolOut>;
-    selectSymbolFirst(selector: ICodegenSymbolSelector): ICodegenSymbolOut | undefined;
-    selectSymbolFirstOrThrow(selector: ICodegenSymbolSelector): ICodegenSymbolOut;
-    selectSymbolLast(selector: ICodegenSymbolSelector): ICodegenSymbolOut | undefined;
-    get symbols(): ReadonlyArray<ICodegenSymbolOut>;
-    updateSymbol(id: number, symbol: Partial<ICodegenSymbolOut>): ICodegenSymbolOut;
+declare class SymbolRegistry implements ISymbolRegistry {
+    private _id;
+    private nodes;
+    private registerOrder;
+    private selectorToId;
+    private values;
+    get(symbolIdOrSelector: number | ISelector): ISymbolOut | undefined;
+    getValue(symbolId: number): unknown;
+    hasValue(symbolId: number): boolean;
+    get id(): number;
+    private idOrSelector;
+    reference(symbolIdOrSelector: number | ISelector): ISymbolOut;
+    register(symbol: ISymbolIn): ISymbolOut;
+    registered(): IterableIterator<ISymbolOut>;
+    setValue(symbolId: number, value: unknown): Map<number, unknown>;
 }
 
-declare class CodegenProject implements ICodegenProject {
-    private fileId;
-    private fileIdToFile;
-    private fileOrder;
-    private filePathToFileId;
-    private renderers;
-    private selectorToSymbolIds;
-    private symbolId;
-    private symbolIdToFileId;
-    addExport(fileOrPath: ICodegenFile | string, imp: ICodegenImport): void;
-    addImport(fileOrPath: ICodegenFile | string, imp: ICodegenImport): void;
-    addSymbol(fileOrPath: ICodegenFile | string, symbol: ICodegenSymbolIn): ICodegenSymbolOut;
-    createFile(path: string, meta?: Omit<ICodegenFile['meta'], 'renderer'> & {
-        /**
-         * Renderer to use to render this file.
-         */
-        renderer?: ICodegenRenderer;
-    }): ICodegenFile;
-    ensureFile(fileOrPath: ICodegenFile | string): ICodegenFile;
-    private ensureRenderer;
-    get files(): ReadonlyArray<ICodegenFile>;
-    getAllSymbols(): ReadonlyArray<Pick<ICodegenSymbolOut, 'name'>>;
-    getFileByPath(path: string): ICodegenFile | undefined;
-    getFileBySymbolId(id: number): ICodegenFile | undefined;
-    private getFileRenderer;
-    getSymbolById(id: number): ICodegenSymbolOut | undefined;
-    incrementFileId(): number;
-    incrementSymbolId(): number;
-    registerSymbol(symbol: ICodegenSymbolOut, file: ICodegenFile): void;
-    render(meta?: ICodegenMeta): ReadonlyArray<ICodegenOutput>;
-    selectSymbolAll(selector: ICodegenSymbolSelector, file?: ICodegenFile): ReadonlyArray<ICodegenSymbolOut>;
-    selectSymbolFirst(selector: ICodegenSymbolSelector, file?: ICodegenFile): ICodegenSymbolOut | undefined;
-    selectSymbolFirstOrThrow(selector: ICodegenSymbolSelector, file?: ICodegenFile): ICodegenSymbolOut;
-    selectSymbolLast(selector: ICodegenSymbolSelector, file?: ICodegenFile): ICodegenSymbolOut | undefined;
+declare class Project implements IProject {
+    private symbolIdToFileIds;
+    readonly defaultFileName: string;
+    readonly files: FileRegistry;
+    readonly fileName?: (name: string) => string;
+    readonly renderers: Record<string, IRenderer>;
+    readonly root: string;
+    readonly symbols: SymbolRegistry;
+    constructor({ defaultFileName, fileName, renderers, root, }: Pick<IProject, 'defaultFileName' | 'fileName' | 'renderers' | 'root'>);
+    private getRenderer;
+    private prepareFiles;
+    render(meta?: IProjectRenderMeta): ReadonlyArray<IOutput>;
+    symbolIdToFiles(symbolId: number): ReadonlyArray<IFileOut>;
+    private symbolToFileSelector;
 }
 
 /**
@@ -717,6 +587,6 @@ declare class CodegenProject implements ICodegenProject {
  * @param replacerFn Accepts a symbol ID, returns resolved symbol name.
  * @returns The replaced source string.
  */
-declare const replaceWrappedIds: (source: string, replacerFn: (symbolId: number) => string | undefined) => string;
+declare const renderIds: (source: string, replacerFn: (symbolId: number) => string | undefined) => string;
 
-export { BiMap, CodegenFile, CodegenProject, type ICodegenBiMap, type ICodegenFile, type ICodegenImport, type ICodegenMeta, type ICodegenOutput, type ICodegenProject, type ICodegenRenderer, type ICodegenSymbolIn, type ICodegenSymbolOut, type ICodegenSymbolSelector, replaceWrappedIds };
+export { type IBiMap as BiMap, type IBinding as Binding, type IFileOut as File, type IFileIn as FileIn, type IProject, type IOutput as Output, Project, type IProjectRenderMeta as ProjectRenderMeta, type IRenderer as Renderer, type ISelector as Selector, type ISymbolOut as Symbol, type ISymbolIn as SymbolIn, type ISymbolMeta as SymbolMeta, createBinding, mergeBindings, renderIds };