@hey-api/codegen-core 0.3.2 → 0.4.0

package/dist/index.d.cts

@@ -1,446 +1,563 @@
-//#region src/bimap/types.d.ts
+import colors from "ansi-colors";
+
+//#region src/refs/types.d.ts
+
 /**
- * Bi-directional map interface.
+ * Ref wrapper which ensures a stable reference for a value.
  *
- * Keys map to values and values map back to keys.
+ * @example
+ * ```ts
+ * type NumRef = Ref<number>; // { '~ref': number }
+ * const num: NumRef = { '~ref': 42 };
+ * console.log(num['~ref']); // 42
+ * ```
+ */
+type Ref<T> = {
+  '~ref': T;
+};
+/**
+ * Maps every property of `T` to a `Ref` of that property.
+ *
+ * @example
+ * ```ts
+ * type Foo = { a: number; b: string };
+ * type Refs = Refs<Foo>; // { a: Ref<number>; b: Ref<string> }
+ * const refs: Refs = { a: { '~ref': 1 }, b: { '~ref': 'x' } };
+ * console.log(refs.a['~ref'], refs.b['~ref']); // 1 'x'
+ * ```
+ */
+type Refs<T> = { [K in keyof T]: Ref<T[K]> };
+/**
+ * Unwraps a Ref to its value type.
+ *
+ * @example
+ * ```ts
+ * type N = FromRef<{ '~ref': number }>; // number
+ * ```
+ */
+type FromRef<T> = T extends Ref<infer V> ? V : T;
+/**
+ * Maps every property of a Ref-wrapped object back to its plain value.
+ *
+ * @example
+ * ```ts
+ * type Foo = { a: number; b: string };
+ * type Refs = Refs<Foo>; // { a: Ref<number>; b: Ref<string> }
+ * type Foo2 = FromRefs<Refs>; // { a: number; b: string }
+ * ```
+ */
+type FromRefs<T> = { [K in keyof T]: T[K] extends Ref<infer V> ? V : T[K] };
+//#endregion
+//#region src/extensions.d.ts
+/**
+ * Arbitrary metadata passed to the project's render function.
  *
- * @template Key Type of the map keys
- * @template Value Type of the map values
+ * 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 IBiMap<Key, Value> {
+interface ISymbolMeta {
+  [key: string]: unknown;
+}
+//#endregion
+//#region src/nodes/node.d.ts
+interface INode<T = unknown> {
+  /** Perform semantic analysis. */
+  analyze(ctx: IAnalysisContext): void;
+  /** Whether this node is exported from its file. */
+  exported?: boolean;
+  /** The file this node belongs to. */
+  file?: File;
+  /** The programming language associated with this node */
+  language: Language;
+  /** Parent node in the syntax tree. */
+  parent?: INode;
+  /** Root node of the syntax tree. */
+  root?: INode;
+  /** The symbol associated with this node. */
+  symbol?: Symbol;
+  /** Convert this node into AST representation. */
+  toAst(): T;
+  /** Brand used for renderer dispatch. */
+  readonly '~brand': string;
+}
+//#endregion
+//#region src/symbols/types.d.ts
+type BindingKind = 'default' | 'named' | 'namespace';
+type ISymbolIdentifier = number | ISymbolMeta;
+type SymbolKind = 'class' | 'enum' | 'function' | 'interface' | 'namespace' | 'type' | 'var';
+type SymbolNameSanitizer = (name: string) => string;
+type ISymbolIn = {
   /**
-   * Deletes a key and its associated value from the map.
+   * Array of file names (without extensions) from which this symbol is re-exported.
    *
-   * @param key The key to delete.
+   * @default undefined
    */
-  delete(key: Key): boolean;
+  exportFrom?: ReadonlyArray<string>;
   /**
-   * Deletes a value and its associated key from the map.
+   * Whether this symbol is exported from its own file.
    *
-   * @param value The value to delete.
+   * @default false
    */
-  deleteValue(value: Value): boolean;
+  exported?: boolean;
   /**
-   * Returns an iterator of [key, value] pairs.
+   * External module name if this symbol is imported from a module not managed
+   * by the project (e.g. "zod", "lodash").
+   *
+   * @default undefined
    */
-  entries(): IterableIterator<[Key, Value]>;
+  external?: string;
   /**
-   * Gets the value associated with a key.
+   * Optional output strategy to override default behavior.
    *
-   * @param key The key to look up.
+   * @returns The file path to output the symbol to, or undefined to fallback to default behavior.
    */
-  get(key: Key): Value | undefined;
+  getFilePath?: Symbol['getFilePath'];
   /**
-   * Gets the key associated with a value.
-   *
-   * @param value The value to look up.
+   * Kind of import if this symbol represents an import.
+   */
+  importKind?: BindingKind;
+  /**
+   * Kind of symbol.
    */
-  getKey(value: Value): Key | undefined;
+  kind?: SymbolKind;
   /**
-   * Checks if a key exists in the map.
+   * Arbitrary metadata about the symbol.
    *
-   * @param key The key to check.
+   * @default undefined
    */
-  hasKey(key: Key): boolean;
+  meta?: ISymbolMeta;
   /**
-   * Checks if a value exists in the map.
+   * The intended, user-facing name of the symbol before any conflict resolution.
+   * It is **not** guaranteed to be the final emitted name — aliasing may occur if the
+   * file contains conflicting local identifiers or other symbols with the same intended name.
    *
-   * @param value The value to check.
+   * @example "UserModel"
    */
-  hasValue(value: Value): boolean;
+  name: string;
+};
+interface ISymbolRegistry {
   /**
-   * Returns an iterator of keys.
+   * Get a symbol.
+   *
+   * @param identifier Symbol identifier to reference.
+   * @returns The symbol, or undefined if not found.
    */
-  keys(): IterableIterator<Key>;
+  get(identifier: ISymbolIdentifier): Symbol | undefined;
   /**
-   * Sets a key-value pair in the map.
+   * Returns whether a symbol is registered in the registry.
    *
-   * @param key The key.
-   * @param value The value.
-   * @returns This instance for chaining.
+   * @param identifier Symbol identifier to check.
+   * @returns True if the symbol is registered, false otherwise.
    */
-  set(key: Key, value: Value): this;
+  isRegistered(identifier: ISymbolIdentifier): boolean;
   /**
-   * Number of key-value pairs in the map.
+   * Returns the current symbol ID and increments it.
+   *
+   * @returns Symbol ID before being incremented.
    */
-  readonly size: number;
+  readonly nextId: number;
   /**
-   * Returns an iterator of values.
+   * Queries symbols by metadata filter.
+   *
+   * @param filter Metadata filter to query symbols by.
+   * @returns Array of symbols matching the filter.
    */
-  values(): IterableIterator<Value>;
+  query(filter: ISymbolMeta): ReadonlyArray<Symbol>;
   /**
-   * Enables iteration with `for...of`.
+   * References a symbol.
+   *
+   * @param meta Metadata filter to reference symbol by.
+   * @returns The referenced symbol.
    */
-  [Symbol.iterator](): IterableIterator<[Key, Value]>;
-}
-//#endregion
-//#region src/bindings/types.d.ts
-interface IBinding {
+  reference(meta: ISymbolMeta): Symbol;
   /**
-   * Optional aliasing map for named symbols.
+   * Register a symbol globally.
    *
-   * Keys must be a subset of `names`, values are aliases.
+   * Deduplicates identical symbols by ID.
    *
-   * @example { User: "ImportedUser" }
+   * @param symbol Symbol to register.
+   * @returns The registered symbol.
    */
-  aliases?: Record<string, string>;
+  register(symbol: ISymbolIn): Symbol;
   /**
-   * Name of the default binding, if any.
+   * Get all symbols in the order they were registered.
    *
-   * @example "React"
+   * @returns Array of all registered symbols, in insert order.
    */
-  defaultBinding?: string;
+  registered(): IterableIterator<Symbol>;
+}
+//#endregion
+//#region src/symbols/symbol.d.ts
+declare class Symbol {
   /**
-   * Source file or external module from which symbols are imported.
+   * Canonical symbol this stub resolves to, if any.
    *
-   * @example "./models/user"
-   * @example "node:path"
+   * Stubs created during DSL construction may later be associated
+   * with a fully registered symbol. Once set, all property lookups
+   * should defer to the canonical symbol.
    */
-  from: string;
+  private _canonical?;
   /**
-   * 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.
+   * True if this symbol is exported from its defining file.
    *
-   * @example ["User", "UserDTO"]
+   * @default false
    */
-  names?: ReadonlyArray<string>;
+  private _exported;
   /**
-   * 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.
+   * Names of files (without extension) from which this symbol is re-exported.
    *
-   * @example "utils"
-   * @example true
+   * @default []
    */
-  namespaceBinding?: boolean | string;
+  private _exportFrom;
   /**
-   * Whether the default binding is type-only.
+   * External module name if this symbol is imported from a module not managed
+   * by the project (e.g. "zod", "lodash").
    *
-   * @example true
+   * @default undefined
    */
-  typeDefaultBinding?: boolean;
+  private _external?;
   /**
-   * Subset of `names` that are imported using the `type` modifier.
-   * These symbols will be emitted as type-only imports in TypeScript.
+   * The file this symbol is ultimately emitted into.
    *
-   * @example ["UserDTO"]
+   * Only top-level symbols have an assigned file.
    */
-  typeNames?: ReadonlyArray<string>;
+  private _file?;
   /**
-   * Whether the namespace binding is type-only.
+   * The alias-resolved, conflict-free emitted name.
+   */
+  private _finalName?;
+  /**
+   * Custom strategy to determine file output path.
    *
-   * @example true
+   * @returns The file path to output the symbol to, or undefined to fallback to default behavior.
    */
-  typeNamespaceBinding?: boolean;
-}
-//#endregion
-//#region src/files/types.d.ts
-/**
- * Selector array used to reference files.
- *
- * @example ["foo", "bar"]
- */
-type IFileSelector = ReadonlyArray<string>;
-type IFileIdentifier = number | IFileSelector;
-interface IFileIn {
+  private _getFilePath?;
   /**
-   * File extension, if any.
+   * How this symbol should be imported (namespace/default/named).
+   *
+   * @default 'named'
    */
-  readonly extension?: string;
+  private _importKind;
   /**
-   * 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).
+   * Kind of symbol (class, type, alias, etc.).
    *
-   * @example true
+   * @default 'var'
    */
-  readonly external?: boolean;
+  private _kind;
   /**
-   * Unique file ID. If one is not provided, it will be auto-generated.
+   * Arbitrary user metadata.
+   *
+   * @default undefined
    */
-  readonly id?: number;
+  private _meta?;
   /**
-   * 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.
+   * Intended user-facing name before conflict resolution.
    *
    * @example "UserModel"
    */
-  readonly name?: string;
+  private _name;
   /**
-   * Absolute logical output path for the file.
+   * Optional function to sanitize the symbol name.
    *
-   * @example "/src/models/user.ts"
+   * @default undefined
    */
-  readonly path?: string;
+  private _nameSanitizer?;
+  /**
+   * Node that defines this symbol.
+   */
+  private _node?;
+  /** Brand used for identifying symbols. */
+  readonly '~brand' = "heyapi.symbol";
+  /** Globally unique, stable symbol ID. */
+  readonly id: number;
+  constructor(input: ISymbolIn, id: number);
   /**
-   * Selector array used to select this file.
+   * Returns the canonical symbol for this instance.
    *
-   * @example ["foo", "bar"]
+   * If this symbol was created as a stub, this getter returns
+   * the fully registered canonical symbol. Otherwise, it returns
+   * the symbol itself.
    */
-  readonly selector?: IFileSelector;
-}
-interface IFileOut extends IFileIn {
+  get canonical(): Symbol;
   /**
-   * Unique file ID.
+   * Indicates whether this symbol is exported from its defining file.
    */
-  readonly id: number;
+  get exported(): boolean;
   /**
-   * Map holding resolved names for symbols in this file.
-   */
-  readonly resolvedNames: IBiMap<number, string>;
-  /**
-   * Symbols in this file, categorized by their role.
-   */
-  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 IFileRegistry {
+   * Names of files (without extension) that re-export this symbol.
+   */
+  get exportFrom(): ReadonlyArray<string>;
   /**
-   * Get a file.
-   *
-   * @param identifier File identifier to reference.
-   * @returns The file, or undefined if not found.
+   * External module from which this symbol originates, if any.
    */
-  get(identifier: IFileIdentifier): IFileOut | undefined;
+  get external(): string | undefined;
   /**
-   * Returns the current file ID and increments it.
+   * Read‑only accessor for the assigned output file.
    *
-   * @returns File ID before being incremented
+   * Only top-level symbols have an assigned file.
    */
-  readonly id: number;
+  get file(): File | undefined;
   /**
-   * Returns whether a file is registered in the registry.
-   *
-   * @param identifier File identifier to check.
-   * @returns True if the file is registered, false otherwise.
+   * Read‑only accessor for the resolved final emitted name.
    */
-  isRegistered(identifier: IFileIdentifier): boolean;
+  get finalName(): string;
   /**
-   * Returns a file by identifier, registering it if it doesn't exist.
-   *
-   * @param identifier File identifier to reference.
-   * @returns The referenced or newly registered file.
+   * Custom file path resolver, if provided.
    */
-  reference(identifier: IFileIdentifier): IFileOut;
+  get getFilePath(): ((symbol: Symbol) => string | undefined) | undefined;
   /**
-   * Get all unregistered files in the order they were referenced.
-   *
-   * @returns Array of all unregistered files, in reference order.
+   * How this symbol should be imported (named/default/namespace).
    */
-  referenced(): IterableIterator<IFileOut>;
+  get importKind(): BindingKind;
   /**
-   * Register a file globally.
+   * Indicates whether this is a canonical symbol (not a stub).
+   */
+  get isCanonical(): boolean;
+  /**
+   * The symbol's kind (class, type, alias, variable, etc.).
+   */
+  get kind(): SymbolKind;
+  /**
+   * Arbitrary user‑provided metadata associated with this symbol.
+   */
+  get meta(): ISymbolMeta | undefined;
+  /**
+   * User-intended name before aliasing or conflict resolution.
+   */
+  get name(): string;
+  /**
+   * Optional function to sanitize the symbol name.
+   */
+  get nameSanitizer(): SymbolNameSanitizer | undefined;
+  /**
+   * Read‑only accessor for the defining node.
+   */
+  get node(): INode | undefined;
+  /**
+   * Marks this symbol as a stub and assigns its canonical symbol.
    *
-   * Deduplicates identical files by ID.
+   * After calling this, all semantic queries (name, kind, file,
+   * meta, etc.) should reflect the canonical symbol's values.
    *
-   * @param file File to register.
-   * @returns true if added, false if duplicate.
+   * @param symbol — The canonical symbol this stub should resolve to.
    */
-  register(file: IFileIn): IFileOut;
+  setCanonical(symbol: Symbol): void;
   /**
-   * Get all files in the order they were registered.
+   * Marks the symbol as exported from its file.
    *
-   * @returns Array of all registered files, in insert order.
+   * @param exported — Whether the symbol is exported.
    */
-  registered(): IterableIterator<IFileOut>;
-}
-//#endregion
-//#region src/extensions/types.d.ts
-/**
- * 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;
-}
-//#endregion
-//#region src/symbols/types.d.ts
-type ISymbolIdentifier = number | ISymbolMeta;
-interface ISymbolIn {
+  setExported(exported: boolean): void;
   /**
-   * Array of file names (without extensions) from which this symbol is re-exported.
+   * Records file names that re‑export this symbol.
    *
-   * @default undefined
+   * @param list — Source files re‑exporting this symbol.
    */
-  readonly exportFrom?: ReadonlyArray<string>;
+  setExportFrom(list: ReadonlyArray<string>): void;
   /**
-   * Whether this symbol is exported from its own file.
+   * Assigns the output file this symbol will be emitted into.
    *
-   * @default false
+   * This may only be set once.
    */
-  readonly exported?: boolean;
+  setFile(file: File): void;
   /**
-   * External module name if this symbol is imported from a module not managed
-   * by the project (e.g. "zod", "lodash").
+   * Assigns the conflict‑resolved final local name for this symbol.
    *
-   * @default undefined
+   * This may only be set once.
    */
-  readonly external?: string;
+  setFinalName(name: string): void;
   /**
-   * Optional output strategy to override default behavior.
+   * Sets how this symbol should be imported.
    *
-   * @returns The file path to output the symbol to, or undefined to fallback to default behavior.
+   * @param kind — The import strategy (named/default/namespace).
    */
-  readonly getFilePath?: (symbol: ISymbolOut) => string | undefined;
+  setImportKind(kind: BindingKind): void;
   /**
-   * Unique symbol ID. If one is not provided, it will be auto-generated.
+   * Sets the symbol's kind (class, type, alias, variable, etc.).
+   *
+   * @param kind — The new symbol kind.
    */
-  readonly id?: number;
+  setKind(kind: SymbolKind): void;
   /**
-   * Kind of import if this symbol represents an import.
+   * Updates the intended user‑facing name for this symbol.
+   *
+   * @param name — The new name.
    */
-  readonly importKind?: 'namespace' | 'default' | 'named';
+  setName(name: string): void;
   /**
-   * Kind of symbol.
+   * Sets a custom function to sanitize the symbol's name.
+   *
+   * @param fn — The name sanitizer function to apply.
    */
-  readonly kind?: 'type';
+  setNameSanitizer(fn: SymbolNameSanitizer): void;
   /**
-   * Arbitrary metadata about the symbol.
+   * Binds the node that defines this symbol.
    *
-   * @default undefined
+   * This may only be set once.
    */
-  readonly meta?: ISymbolMeta;
+  setNode(node: INode): void;
   /**
-   * 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.
-   *
-   * @example "UserModel"
+   * Returns a debug‑friendly string representation identifying the symbol.
    */
-  readonly name?: string;
+  toString(): string;
   /**
-   * Placeholder name for the symbol to be replaced later with the final value.
+   * Ensures this symbol is canonical before allowing mutation.
    *
-   * @example "_heyapi_31_"
+   * A symbol that has been marked as a stub (i.e., its `_canonical` points
+   * to a different symbol) may not be mutated. This guard throws an error
+   * if any setter attempts to modify a stub, preventing accidental writes
+   * to non‑canonical instances.
+   *
+   * @throws {Error} If the symbol is a stub and is being mutated.
    */
-  readonly placeholder?: string;
+  private assertCanonical;
+}
+//#endregion
+//#region src/planner/types.d.ts
+type Input = Ref<object> | object | string | number | undefined;
+type NameScopes = Map<string, Set<SymbolKind>>;
+type NameConflictResolver = (args: {
+  attempt: number;
+  baseName: string;
+}) => string | null;
+type Scope = {
+  /** Child scopes. */
+  children: Array<Scope>;
+  /** Resolved names in this scope. */
+  localNames: NameScopes;
+  /** Parent scope, if any. */
+  parent?: Scope;
+  /** Symbols registered in this scope. */
+  symbols: Array<Ref<Symbol>>;
+};
+interface IAnalysisContext {
+  /** Register a dependency on another symbol. */
+  addDependency(symbol: Ref<Symbol>): void;
+  /** Register a dependency on another symbol or analyze further. */
+  analyze(input: Input): void;
+  /** Get local names in the current scope. */
+  localNames(scope: Scope): NameScopes;
+  /** Pop the current local scope. */
+  popScope(): void;
+  /** Push a new local scope. */
+  pushScope(): void;
+  /** Current local scope. */
+  scope: Scope;
+  /** Stack of local name scopes. */
+  scopes: Scope;
+  /** Top-level symbol for the current analysis pass. */
+  symbol?: Symbol;
+  /** Walks all symbols in the scope tree in depth-first order. */
+  walkScopes(callback: (symbol: Ref<Symbol>, scope: Scope) => void, scope?: Scope): void;
 }
-interface ISymbolOut extends ISymbolIn {
+//#endregion
+//#region src/languages/types.d.ts
+type Extensions = Partial<Record<Language, ReadonlyArray<string>>>;
+type Language = 'c' | 'c#' | 'c++' | 'css' | 'dart' | 'go' | 'haskell' | 'html' | 'java' | 'javascript' | 'json' | 'kotlin' | 'lua' | 'markdown' | 'matlab' | 'perl' | 'php' | 'python' | 'r' | 'ruby' | 'rust' | 'scala' | 'shell' | 'sql' | 'swift' | 'typescript' | 'yaml' | (string & {});
+// other/custom language
+
+type NameConflictResolvers = Partial<Record<Language, NameConflictResolver>>;
+//#endregion
+//#region src/files/types.d.ts
+type FileKeyArgs = Pick<Required<File>, 'logicalFilePath'> & Pick<Partial<File>, 'external' | 'language'>;
+type IFileIn = {
   /**
-   * Array of file names (without extensions) from which this symbol is re-exported.
+   * 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).
+   *
+   * @example true
    */
-  readonly exportFrom: ReadonlyArray<string>;
+  external?: boolean;
   /**
-   * Unique symbol ID.
+   * Language of the file.
+   *
+   * @example "typescript"
    */
-  readonly id: number;
+  language?: Language;
   /**
-   * Placeholder name for the symbol to be replaced later with the final value.
+   * Logical, extension-free path used for planning and routing.
    *
-   * @example "_heyapi_31_"
+   * @example "src/models/user"
    */
-  readonly placeholder: string;
-}
-interface ISymbolRegistry {
+  logicalFilePath: string;
   /**
-   * Get a symbol.
+   * 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.
    *
-   * @param identifier Symbol identifier to reference.
-   * @returns The symbol, or undefined if not found.
+   * @example "UserModel"
    */
-  get(identifier: ISymbolIdentifier): ISymbolOut | undefined;
+  name?: string;
+};
+interface IFileRegistry {
   /**
-   * Returns the value associated with a symbol ID.
+   * Get a file.
    *
-   * @param symbolId Symbol ID.
-   * @return The value associated with the symbol ID, or undefined if not found.
+   * @returns The file, or undefined if not found.
    */
-  getValue(symbolId: number): unknown;
+  get(args: FileKeyArgs): File | undefined;
   /**
-   * Checks if the registry has a value associated with a symbol ID.
+   * Returns whether a file is registered in the registry.
    *
-   * @param symbolId Symbol ID.
-   * @returns True if the registry has a value for symbol ID, false otherwise.
+   * @returns True if the file is registered, false otherwise.
    */
-  hasValue(symbolId: number): boolean;
+  isRegistered(args: FileKeyArgs): boolean;
   /**
-   * Returns the current symbol ID and increments it.
+   * Returns the current file ID and increments it.
    *
-   * @returns Symbol ID before being incremented.
+   * @returns File ID before being incremented
    */
-  readonly id: number;
+  readonly nextId: number;
   /**
-   * Returns whether a symbol is registered in the registry.
+   * Register a file globally.
    *
-   * @param identifier Symbol identifier to check.
-   * @returns True if the symbol is registered, false otherwise.
+   * @param file File to register.
+   * @returns Newly registered file if created, merged file otherwise.
    */
-  isRegistered(identifier: ISymbolIdentifier): boolean;
+  register(file: IFileIn): File;
   /**
-   * Queries symbols by metadata filter.
+   * Get all files in the order they were registered.
    *
-   * @param filter Metadata filter to query symbols by.
-   * @returns Array of symbols matching the filter.
+   * @returns Array of all registered files, in insert order.
    */
-  query(filter: ISymbolMeta): ReadonlyArray<ISymbolOut>;
+  registered(): IterableIterator<File>;
+}
+//#endregion
+//#region src/nodes/types.d.ts
+interface INodeRegistry {
   /**
-   * References a symbol.
+   * Register a syntax node.
    *
-   * @param meta Metadata filter to reference symbol by.
-   * @returns The referenced symbol.
+   * @returns The index of the registered node.
    */
-  reference(meta: ISymbolMeta): ISymbolOut;
+  add(node: INode | null): number;
   /**
-   * Register a symbol globally.
-   *
-   * Deduplicates identical symbols by ID.
-   *
-   * @param symbol Symbol to register.
-   * @returns The registered symbol.
+   * All nodes in insertion order.
    */
-  register(symbol: ISymbolIn): ISymbolOut;
+  all(): Iterable<INode>;
   /**
-   * Get all symbols in the order they were registered.
+   * Remove a node by its index.
    *
-   * @returns Array of all registered symbols, in insert order.
+   * @param index Index of the node to remove.
    */
-  registered(): IterableIterator<ISymbolOut>;
+  remove(index: number): void;
   /**
-   * Sets a value for a symbol by its ID.
+   * Update a node at the given index.
    *
-   * @param symbolId Symbol ID.
-   * @param value The value to set.
-   * @returns void
+   * @param index Index of the node to update.
+   * @param node New node to set.
    */
-  setValue(symbolId: number, value: unknown): Map<number, unknown>;
+  update(index: number, node: INode | null): void;
 }
 //#endregion
-//#region src/bindings/utils.d.ts
-declare const createBinding: ({
-  file,
-  modulePath,
-  symbol,
-  symbolFile
-}: {
-  file: IFileOut;
-  modulePath: string;
-  symbol: ISymbolOut;
-  symbolFile: IFileOut;
-}) => IBinding;
-declare const mergeBindings: (target: IBinding, source: IBinding) => void;
-//#endregion
-//#region src/output/types.d.ts
+//#region src/output.d.ts
 interface IOutput {
   /**
    * The main content of the file to output.
@@ -458,26 +575,32 @@ interface IOutput {
   path: string;
 }
 //#endregion
-//#region src/files/registry.d.ts
-declare class FileRegistry implements IFileRegistry {
-  private _id;
-  private referenceOrder;
-  private registerOrder;
-  private selectorToId;
-  private values;
-  get(identifier: IFileIdentifier): IFileOut | undefined;
-  get id(): number;
-  private identifierToFile;
-  isRegistered(identifier: IFileIdentifier): boolean;
-  reference(identifier: IFileIdentifier): IFileOut;
-  referenced(): IterableIterator<IFileOut>;
-  register(file: IFileIn): IFileOut;
-  registered(): IterableIterator<IFileOut>;
+//#region src/renderer.d.ts
+interface RenderContext {
+  /**
+   * The current file.
+   */
+  file: File;
+  /**
+   * Arbitrary metadata.
+   */
+  meta?: IProjectRenderMeta;
+  /**
+   * The project the file belongs to.
+   */
+  project: IProject;
+}
+interface Renderer {
+  /** Renders the given file. */
+  render(ctx: RenderContext): string;
+  /** Returns whether this renderer can render the given file. */
+  supports(ctx: RenderContext): boolean;
 }
 //#endregion
 //#region src/project/types.d.ts
 /**
- * Represents a code generation project consisting of multiple codegen files.
+ * Represents a code generation project consisting of codegen files.
+ *
  * Manages imports, symbols, and output generation across the project.
  */
 interface IProject {
@@ -486,18 +609,24 @@ interface IProject {
    *
    * @default 'main'
    */
-  readonly defaultFileName?: string;
+  readonly defaultFileName: string;
+  /** Default name conflict resolver used when a file has no specific resolver. */
+  readonly defaultNameConflictResolver: NameConflictResolver;
+  /** Maps language to array of extensions. First element is used by default. */
+  readonly extensions: Extensions;
   /**
-   * Optional function to transform file names before they are used.
+   * Function to transform file names before they are used.
    *
    * @param name The original file name.
    * @returns The transformed file name.
    */
   readonly fileName?: (name: string) => string;
-  /**
-   * Centralized file registry for the project.
-   */
+  /** Centralized file registry for the project. */
   readonly files: IFileRegistry;
+  /** Map of language-specific name conflict resolvers for files in the project. */
+  readonly nameConflictResolvers: NameConflictResolvers;
+  /** Centralized node registry for the project. */
+  readonly nodes: INodeRegistry;
   /**
    * Produces output representations for all files in the project.
    *
@@ -508,82 +637,273 @@ interface IProject {
    */
   render(meta?: IProjectRenderMeta): ReadonlyArray<IOutput>;
   /**
-   * Map of available renderers by file extension.
+   * List of available renderers.
    *
    * @example
-   * {
-   *   ".ts": tsRenderer,
-   *   ".js": jsRenderer,
-   * }
+   * [new TypeScriptRenderer()]
    */
-  readonly renderers: Record<string, IRenderer>;
+  readonly renderers: ReadonlyArray<Renderer>;
+  /** The absolute path to the root folder of the project. */
+  readonly root: string;
+  /** Centralized symbol registry for the project. */
+  readonly symbols: ISymbolRegistry;
+}
+//#endregion
+//#region src/files/file.d.ts
+declare class File {
   /**
-   * The absolute path to the root folder of the project.
+   * Exports from this file.
    */
-  readonly root: string;
+  private _exports;
   /**
-   * 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.
+   * File extension (e.g. `.ts`).
+   */
+  private _extension?;
+  /**
+   * Actual emitted file path, including extension and directories.
+   */
+  private _finalPath?;
+  /**
+   * Imports to this file.
+   */
+  private _imports;
+  /**
+   * Language of the file.
+   */
+  private _language?;
+  /**
+   * Logical, extension-free path used for planning and routing.
+   */
+  private _logicalFilePath;
+  /**
+   * Base name of the file (without extension).
+   */
+  private _name?;
+  /**
+   * Syntax nodes contained in this file.
+   */
+  private _nodes;
+  /**
+   * Renderer assigned to this file.
+   */
+  private _renderer?;
+  /** Brand used for identifying files. */
+  readonly '~brand' = "heyapi.file";
+  /** All names defined in this file, including local scopes. */
+  allNames: NameScopes;
+  /** Whether this file is external to the project. */
+  external: boolean;
+  /** Unique identifier for the file. */
+  readonly id: number;
+  /** The project this file belongs to. */
+  readonly project: IProject;
+  /** Names declared at the top level of the file. */
+  topLevelNames: NameScopes;
+  constructor(input: IFileIn, id: number, project: IProject);
+  /**
+   * Exports from this file.
+   */
+  get exports(): ReadonlyArray<ExportModule>;
+  /**
+   * Read-only accessor for the file extension.
+   */
+  get extension(): string | undefined;
+  /**
+   * Read-only accessor for the final emitted path.
    *
-   * @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);
-   * }
+   * If undefined, the file has not yet been assigned a final path
+   * or is external to the project and should not be emitted.
    */
-  symbolIdToFiles(symbolId: number): ReadonlyArray<IFileOut>;
+  get finalPath(): string | undefined;
   /**
-   * Centralized symbol registry for the project.
+   * Imports to this file.
    */
-  readonly symbols: ISymbolRegistry;
-}
-//#endregion
-//#region src/renderer/types.d.ts
-interface IRenderer {
+  get imports(): ReadonlyArray<ImportModule>;
   /**
-   * Renders content with replaced symbols.
+   * Language of the file; inferred from nodes or fallback if not set explicitly.
+   */
+  get language(): Language | undefined;
+  /**
+   * Logical, extension-free path used for planning and routing.
+   */
+  get logicalFilePath(): string;
+  /**
+   * Base name of the file (without extension).
    *
-   * @param content Content to render.
-   * @param file The file to render.
-   * @param project The parent project the file belongs to.
-   * @returns Rendered content.
+   * If no name was set explicitly, it is inferred from the logical file path.
+   */
+  get name(): string;
+  /**
+   * Syntax nodes contained in this file.
+   */
+  get nodes(): ReadonlyArray<INode>;
+  /**
+   * Renderer assigned to this file.
+   */
+  get renderer(): Renderer | undefined;
+  /**
+   * Add an export group to the file.
+   */
+  addExport(group: ExportModule): void;
+  /**
+   * Add an import group to the file.
+   */
+  addImport(group: ImportModule): void;
+  /**
+   * Add a syntax node to the file.
+   */
+  addNode(node: INode): void;
+  /**
+   * Sets the file extension.
+   */
+  setExtension(extension: string): void;
+  /**
+   * Sets the final emitted path of the file.
    */
-  renderFile(content: string, file: IFile, project: IProject, meta?: IProjectRenderMeta): string;
+  setFinalPath(path: string): void;
   /**
-   * Returns printable data containing symbols and exports.
+   * Sets the language of the file.
+   */
+  setLanguage(lang: Language): void;
+  /**
+   * Sets the name of the file.
+   */
+  setName(name: string): void;
+  /**
+   * Sets the renderer assigned to this file.
+   */
+  setRenderer(renderer: Renderer): void;
+  /**
+   * Returns a debug‑friendly string representation identifying the file.
+   */
+  toString(): string;
+}
+//#endregion
+//#region src/bindings.d.ts
+interface ExportMember {
+  /**
+   * Name under which the symbol is exported in this file.
    *
-   * @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.
+   * export { Foo as Bar } from "./models"
+   *
+   * exportedName === "Bar"
    */
-  renderSymbols(file: IFileOut, project: IProject, meta?: IProjectRenderMeta): string;
+  exportedName: string;
+  /** Whether this export is type-only. */
+  isTypeOnly: boolean;
+  /** Export flavor. */
+  kind: BindingKind;
+  /** The exported name of the symbol in its source file. */
+  sourceName: string;
+}
+type ExportModule = Pick<ExportMember, 'isTypeOnly'> & {
+  /** Whether this module can export all symbols: `export * from 'module'`. */
+  canExportAll: boolean;
+  /** Members exported from this module. */
+  exports: Array<ExportMember>;
+  /** Source file. */
+  from: File;
+  /** Namespace export: `export * as ns from 'module'`. Mutually exclusive with `exports`. */
+  namespaceExport?: string;
+};
+interface ImportMember {
+  /** Whether this import is type-only. */
+  isTypeOnly: boolean;
+  /** Import flavor. */
+  kind: BindingKind;
+  /**
+   * The name this symbol will have locally in this file.
+   * This is where aliasing is applied:
+   *
+   * import { Foo as Foo$2 } from "./x"
+   *
+   * localName === "Foo$2"
+   */
+  localName: string;
+  /** The exported name of the symbol in its source file. */
+  sourceName: string;
+}
+type ImportModule = Pick<ImportMember, 'isTypeOnly'> & {
+  /** Source file. */
+  from: File;
+  /** List of symbols imported from this module. */
+  imports: Array<ImportMember>;
+  /** Namespace import: `import * as name from 'module'`. Mutually exclusive with `imports`. */
+  namespaceImport?: string;
+};
+//#endregion
+//#region src/brands.d.ts
+declare const nodeBrand = "heyapi.node";
+declare const symbolBrand = "heyapi.symbol";
+//#endregion
+//#region src/debug.d.ts
+declare const DEBUG_GROUPS: {
+  readonly analyzer: colors.StyleFunction;
+  readonly dsl: colors.StyleFunction;
+  readonly file: colors.StyleFunction;
+  readonly registry: colors.StyleFunction;
+  readonly symbol: colors.StyleFunction;
+};
+declare function debug(message: string, group: keyof typeof DEBUG_GROUPS): void;
+//#endregion
+//#region src/guards.d.ts
+declare function isNode(value: unknown): value is INode;
+declare function isNodeRef(value: Ref<unknown>): value is Ref<INode>;
+declare function isSymbol(value: unknown): value is Symbol;
+declare function isSymbolRef(value: Ref<unknown>): value is Ref<Symbol>;
+//#endregion
+//#region src/languages/extensions.d.ts
+declare const defaultExtensions: Extensions;
+//#endregion
+//#region src/languages/resolvers.d.ts
+declare const defaultNameConflictResolvers: NameConflictResolvers;
+//#endregion
+//#region src/planner/resolvers.d.ts
+declare const simpleNameConflictResolver: NameConflictResolver;
+declare const underscoreNameConflictResolver: NameConflictResolver;
+//#endregion
+//#region src/files/registry.d.ts
+type FileId = number;
+declare class FileRegistry implements IFileRegistry {
+  private _id;
+  private _values;
+  private readonly project;
+  constructor(project: IProject);
+  get(args: FileKeyArgs): File | undefined;
+  isRegistered(args: FileKeyArgs): boolean;
+  get nextId(): FileId;
+  register(file: IFileIn): File;
+  registered(): IterableIterator<File>;
+  private createFileKey;
+}
+//#endregion
+//#region src/nodes/registry.d.ts
+declare class NodeRegistry implements INodeRegistry {
+  private list;
+  add(node: INode | null): number;
+  all(): Iterable<INode>;
+  remove(index: number): void;
+  update(index: number, node: INode | null): void;
 }
 //#endregion
 //#region src/symbols/registry.d.ts
 type SymbolId = number;
 declare class SymbolRegistry implements ISymbolRegistry {
   private _id;
-  private indices;
-  private nodes;
-  private queryCache;
-  private queryCacheDependencies;
-  private registerOrder;
-  private stubCache;
-  private stubs;
-  private values;
-  get(identifier: ISymbolIdentifier): ISymbolOut | undefined;
-  getValue(symbolId: SymbolId): unknown;
-  hasValue(symbolId: SymbolId): boolean;
-  get id(): SymbolId;
+  private _indices;
+  private _queryCache;
+  private _queryCacheDependencies;
+  private _registered;
+  private _stubs;
+  private _stubCache;
+  private _values;
+  get(identifier: ISymbolIdentifier): Symbol | undefined;
   isRegistered(identifier: ISymbolIdentifier): boolean;
-  query(filter: ISymbolMeta): ReadonlyArray<ISymbolOut>;
-  reference(meta: ISymbolMeta): ISymbolOut;
-  register(symbol: ISymbolIn): ISymbolOut;
-  registered(): IterableIterator<ISymbolOut>;
-  setValue(symbolId: SymbolId, value: unknown): Map<SymbolId, unknown>;
+  get nextId(): SymbolId;
+  query(filter: ISymbolMeta): ReadonlyArray<Symbol>;
+  reference(meta: ISymbolMeta): Symbol;
+  register(symbol: ISymbolIn): Symbol;
+  registered(): IterableIterator<Symbol>;
   private buildCacheKey;
   private buildIndexKeySpace;
   private indexSymbol;
@@ -595,34 +915,69 @@ declare class SymbolRegistry implements ISymbolRegistry {
 //#endregion
 //#region src/project/project.d.ts
 declare class Project implements IProject {
-  private symbolIdToFileIds;
-  readonly defaultFileName: string;
   readonly files: FileRegistry;
+  readonly nodes: NodeRegistry;
+  readonly symbols: SymbolRegistry;
+  readonly defaultFileName: string;
+  readonly defaultNameConflictResolver: NameConflictResolver;
+  readonly extensions: Extensions;
   readonly fileName?: (name: string) => string;
-  readonly renderers: Record<string, IRenderer>;
+  readonly nameConflictResolvers: NameConflictResolvers;
+  readonly renderers: ReadonlyArray<Renderer>;
   readonly root: string;
-  readonly symbols: SymbolRegistry;
-  constructor({
-    defaultFileName,
-    fileName,
-    renderers,
-    root
-  }: Pick<IProject, 'defaultFileName' | 'fileName' | 'renderers' | 'root'>);
-  private getRenderer;
-  private prepareFiles;
+  constructor(args: Pick<Partial<IProject>, 'defaultFileName' | 'defaultNameConflictResolver' | 'extensions' | 'fileName' | 'nameConflictResolvers' | 'renderers'> & Pick<IProject, 'root'>);
   render(meta?: IProjectRenderMeta): ReadonlyArray<IOutput>;
-  symbolIdToFiles(symbolId: number): ReadonlyArray<IFileOut>;
-  private symbolToFileSelector;
 }
 //#endregion
-//#region src/renderer/utils.d.ts
+//#region src/refs/refs.d.ts
+/**
+ * Wraps a single value in a Ref object.
+ *
+ * @example
+ * ```ts
+ * const r = ref(123); // { '~ref': 123 }
+ * console.log(r['~ref']); // 123
+ * ```
+ */
+declare const ref: <T>(value: T) => Ref<T>;
+/**
+ * Converts a plain object to an object of Refs (deep, per property).
+ *
+ * @example
+ * ```ts
+ * const obj = { a: 1, b: "x" };
+ * const refs = refs(obj); // { a: { '~ref': 1 }, b: { '~ref': "x" } }
+ * ```
+ */
+declare const refs: <T extends Record<string, unknown>>(obj: T) => Refs<T>;
+/**
+ * Unwraps a single Ref object to its value.
+ *
+ * @example
+ * ```ts
+ * const r = { '~ref': 42 };
+ * const n = fromRef(r); // 42
+ * console.log(n); // 42
+ * ```
+ */
+declare const fromRef: <T extends Ref<unknown> | undefined>(ref: T) => T extends Ref<infer U> ? U : undefined;
+/**
+ * Converts an object of Refs back to a plain object (unwraps all refs).
+ *
+ * @example
+ * ```ts
+ * const refs = { a: { '~ref': 1 }, b: { '~ref': "x" } };
+ * const plain = fromRefs(refs); // { a: 1, b: "x" }
+ * ```
+ */
+declare const fromRefs: <T extends Refs<Record<string, unknown>>>(obj: T) => FromRefs<T>;
 /**
+ * Checks whether a value is a Ref object.
  *
- * @param source The source string to replace.
- * @param replacerFn Accepts a symbol ID, returns resolved symbol name.
- * @returns The replaced source string.
+ * @param value Value to check
+ * @returns True if the value is a Ref object.
  */
-declare const renderIds: (source: string, replacerFn: (symbolId: number) => string | undefined) => string;
+declare const isRef: <T>(value: unknown) => value is Ref<T>;
 //#endregion
-export { type IBiMap as BiMap, type IBinding as Binding, type IFileOut as File, type IFileIdentifier as FileIdentifier, type IFileIn as FileIn, type IProject, type IOutput as Output, Project, type IProjectRenderMeta as ProjectRenderMeta, type IRenderer as Renderer, type ISymbolOut as Symbol, type ISymbolIdentifier as SymbolIdentifier, type ISymbolIn as SymbolIn, type ISymbolMeta as SymbolMeta, createBinding, mergeBindings, renderIds };
+export { type IAnalysisContext as AnalysisContext, type BindingKind, type ExportMember, type ExportModule, type Extensions, File, type IFileIn as FileIn, type FromRef, type FromRefs, type IProject, type ImportMember, type ImportModule, type Language, type NameConflictResolver, type NameConflictResolvers, type INode as Node, type IOutput as Output, Project, type IProjectRenderMeta as ProjectRenderMeta, type Ref, type Refs, type RenderContext, type Renderer, Symbol, type ISymbolIdentifier as SymbolIdentifier, type ISymbolIn as SymbolIn, type ISymbolMeta as SymbolMeta, debug, defaultExtensions, defaultNameConflictResolvers, fromRef, fromRefs, isNode, isNodeRef, isRef, isSymbol, isSymbolRef, nodeBrand, ref, refs, simpleNameConflictResolver, symbolBrand, underscoreNameConflictResolver };
 //# sourceMappingURL=index.d.cts.map