@hey-api/codegen-core 0.3.3 → 0.5.0

package/dist/index.d.cts

@@ -1,431 +1,575 @@
-//#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> = T extends {
+  ['~ref']: unknown;
+} ? 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 U;
+} ? U : 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 U> ? U : 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 IBiMap<Key, Value> {
+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/nodes/node.d.ts
+type MaybeRef<T> = T | Ref<T>;
+type NodeName = MaybeRef<Symbol | string | number>;
+type NodeNameSanitizer = (name: string) => string;
+type NodeRelationship = 'container' | 'reference';
+type NodeScope = 'type' | 'value';
+interface INode<T = unknown> {
+  /** Perform semantic analysis. */
+  analyze(ctx: IAnalysisContext): void;
+  /** Create a shallow copy of this node. */
+  clone(): this;
+  /** 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;
+  /** The display name of this node. */
+  readonly name: Ref<NodeName> & {
+    set(value: NodeName): void;
+    toString(): string;
+  };
+  /** Optional function to sanitize the node name. */
+  readonly nameSanitizer?: NodeNameSanitizer;
+  /** Whether this node is a root node in the file. */
+  root?: boolean;
+  /** The scope of this node. */
+  scope?: NodeScope;
+  /** Semantic children in the structure hierarchy. */
+  structuralChildren?: Map<INode, NodeRelationship>;
+  /** Semantic parents in the structure hierarchy. */
+  structuralParents?: Map<INode, NodeRelationship>;
+  /** 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 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.
+   * Kind of import if this symbol represents an import.
    *
-   * @param value The value to look up.
+   * @default 'named'
    */
-  getKey(value: Value): Key | undefined;
+  importKind?: BindingKind;
   /**
-   * Checks if a key exists in the map.
+   * Kind of symbol.
    *
-   * @param key The key to check.
+   * @default 'var'
    */
-  hasKey(key: Key): boolean;
+  kind?: SymbolKind;
   /**
-   * Checks if a value exists in the map.
+   * Arbitrary metadata about the symbol.
    *
-   * @param value The value to check.
+   * @default undefined
    */
-  hasValue(value: Value): boolean;
+  meta?: ISymbolMeta;
   /**
-   * Returns an iterator of keys.
+   * 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.
+   *
+   * @example "UserModel"
    */
-  keys(): IterableIterator<Key>;
+  name: string;
+};
+interface ISymbolRegistry {
   /**
-   * Sets a key-value pair in the map.
+   * Get a symbol.
    *
-   * @param key The key.
-   * @param value The value.
-   * @returns This instance for chaining.
+   * @param identifier Symbol identifier to reference.
+   * @returns The symbol, or undefined if not found.
    */
-  set(key: Key, value: Value): this;
+  get(identifier: ISymbolIdentifier): Symbol | undefined;
   /**
-   * Number of key-value pairs in the map.
+   * Returns whether a symbol is registered in the registry.
+   *
+   * @param identifier Symbol identifier to check.
+   * @returns True if the symbol is registered, false otherwise.
    */
-  readonly size: number;
+  isRegistered(identifier: ISymbolIdentifier): boolean;
   /**
-   * Returns an iterator of values.
+   * Returns the current symbol ID and increments it.
+   *
+   * @returns Symbol ID before being incremented.
    */
-  values(): IterableIterator<Value>;
+  readonly nextId: number;
   /**
-   * Enables iteration with `for...of`.
+   * Queries symbols by metadata filter.
+   *
+   * @param filter Metadata filter to query symbols by.
+   * @returns Array of symbols matching the filter.
    */
-  [Symbol.iterator](): IterableIterator<[Key, Value]>;
-}
-//#endregion
-//#region src/bindings/types.d.ts
-interface IBinding {
+  query(filter: ISymbolMeta): ReadonlyArray<Symbol>;
   /**
-   * Optional aliasing map for named symbols.
-   *
-   * Keys must be a subset of `names`, values are aliases.
+   * References a symbol.
    *
-   * @example { User: "ImportedUser" }
+   * @param meta Metadata filter to reference symbol by.
+   * @returns The referenced symbol.
    */
-  aliases?: Record<string, string>;
+  reference(meta: ISymbolMeta): Symbol;
   /**
-   * Name of the default binding, if any.
+   * Register a symbol globally.
+   *
+   * Deduplicates identical symbols by ID.
    *
-   * @example "React"
+   * @param symbol Symbol to register.
+   * @returns The registered symbol.
    */
-  defaultBinding?: string;
+  register(symbol: ISymbolIn): Symbol;
   /**
-   * Source file or external module from which symbols are imported.
+   * Get all symbols in the order they were registered.
    *
-   * @example "./models/user"
-   * @example "node:path"
+   * @returns Array of all registered symbols, in insert order.
    */
-  from: string;
+  registered(): IterableIterator<Symbol>;
+}
+//#endregion
+//#region src/symbols/symbol.d.ts
+declare class Symbol<Node extends INode = INode> {
   /**
-   * 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.
+   * Canonical symbol this stub resolves to, if any.
    *
-   * @example ["User", "UserDTO"]
+   * 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.
    */
-  names?: ReadonlyArray<string>;
+  private _canonical?;
   /**
-   * 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.
+   * True if this symbol is exported from its defining file.
    *
-   * @example "utils"
-   * @example true
+   * @default false
    */
-  namespaceBinding?: boolean | string;
+  private _exported;
   /**
-   * Whether the default binding is type-only.
+   * Names of files (without extension) from which this symbol is re-exported.
    *
-   * @example true
+   * @default []
    */
-  typeDefaultBinding?: boolean;
+  private _exportFrom;
   /**
-   * Subset of `names` that are imported using the `type` modifier.
-   * These symbols will be emitted as type-only imports in TypeScript.
+   * External module name if this symbol is imported from a module not managed
+   * by the project (e.g. "zod", "lodash").
    *
-   * @example ["UserDTO"]
+   * @default undefined
    */
-  typeNames?: ReadonlyArray<string>;
+  private _external?;
   /**
-   * Whether the namespace binding is type-only.
+   * The file this symbol is ultimately emitted into.
    *
-   * @example true
+   * Only top-level symbols have an assigned file.
    */
-  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;
-type IFileIn = {
+  private _file?;
   /**
-   * File extension, if any.
+   * The alias-resolved, conflict-free emitted name.
    */
-  extension?: string;
+  private _finalName?;
   /**
-   * 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).
+   * 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.
    */
-  external?: boolean;
+  private _getFilePath?;
   /**
-   * Unique file ID. If one is not provided, it will be auto-generated.
+   * How this symbol should be imported (namespace/default/named).
+   *
+   * @default 'named'
    */
-  readonly id?: number;
+  private _importKind;
   /**
-   * 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.
+   * Kind of symbol (class, type, alias, etc.).
    *
-   * @example "UserModel"
+   * @default 'var'
    */
-  name?: string;
+  private _kind;
   /**
-   * Absolute logical output path for the file.
+   * Arbitrary user metadata.
    *
-   * @example "/src/models/user.ts"
+   * @default undefined
    */
-  path?: string;
+  private _meta?;
   /**
-   * Selector array used to select this file.
+   * Intended user-facing name before conflict resolution.
    *
-   * @example ["foo", "bar"]
+   * @example "UserModel"
    */
-  readonly selector?: IFileSelector;
-};
-type IFileOut = IFileIn & {
+  private _name;
   /**
-   * Unique file ID.
+   * 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);
   /**
-   * 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 {
-  /**
-   * Get a file.
+   * Returns the canonical symbol for this instance.
    *
-   * @param identifier File identifier to reference.
-   * @returns The file, or undefined if not found.
+   * If this symbol was created as a stub, this getter returns
+   * the fully registered canonical symbol. Otherwise, it returns
+   * the symbol itself.
    */
-  get(identifier: IFileIdentifier): IFileOut | undefined;
+  get canonical(): Symbol;
   /**
-   * Returns the current file ID and increments it.
-   *
-   * @returns File ID before being incremented
+   * Indicates whether this symbol is exported from its defining file.
    */
-  readonly id: number;
+  get exported(): boolean;
   /**
-   * Returns whether a file is registered in the registry.
-   *
-   * @param identifier File identifier to check.
-   * @returns True if the file is registered, false otherwise.
+   * Names of files (without extension) that re-export this symbol.
    */
-  isRegistered(identifier: IFileIdentifier): boolean;
+  get exportFrom(): ReadonlyArray<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.
+   * External module from which this symbol originates, if any.
    */
-  reference(identifier: IFileIdentifier): IFileOut;
+  get external(): string | undefined;
   /**
-   * Get all unregistered files in the order they were referenced.
+   * Read‑only accessor for the assigned output file.
    *
-   * @returns Array of all unregistered files, in reference order.
+   * Only top-level symbols have an assigned file.
    */
-  referenced(): IterableIterator<IFileOut>;
+  get file(): File | undefined;
   /**
-   * Register a file globally.
+   * Read‑only accessor for the resolved final emitted name.
+   */
+  get finalName(): string;
+  /**
+   * Custom file path resolver, if provided.
+   */
+  get getFilePath(): ((symbol: Symbol) => string | undefined) | undefined;
+  /**
+   * How this symbol should be imported (named/default/namespace).
+   */
+  get importKind(): BindingKind;
+  /**
+   * 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;
+  /**
+   * Read‑only accessor for the defining node.
+   */
+  get node(): Node | 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;
-type 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.
    */
-  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.
    */
-  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.
    */
-  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).
    */
-  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.
    */
-  importKind?: 'namespace' | 'default' | 'named';
+  setName(name: string): void;
   /**
-   * Kind of symbol.
+   * Binds the node that defines this symbol.
+   *
+   * This may only be set once.
    */
-  kind?: 'class' | 'function' | 'type';
+  setNode(node: Node): void;
   /**
-   * Arbitrary metadata about the symbol.
-   *
-   * @default undefined
+   * Returns a debug‑friendly string representation identifying the symbol.
    */
-  meta?: ISymbolMeta;
+  toString(): string;
   /**
-   * 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.
+   * Ensures this symbol is canonical before allowing mutation.
    *
-   * @example "UserModel"
+   * 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.
    */
-  name?: string;
+  private assertCanonical;
+}
+//#endregion
+//#region src/planner/scope.d.ts
+type NameScopes = Map<string, Set<SymbolKind>>;
+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>>;
+};
+//#endregion
+//#region src/planner/types.d.ts
+type Input = Ref<object> | object | string | number | undefined;
+type NameConflictResolver = (args: {
+  attempt: number;
+  baseName: string;
+}) => string | null;
+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;
+}
+//#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 = {
   /**
-   * Placeholder name for the symbol to be replaced later with the final value.
+   * 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 "_heyapi_31_"
+   * @example true
    */
-  readonly placeholder?: string;
-};
-type ISymbolOut = Omit<ISymbolIn, 'id' | 'placeholder'> & Pick<Required<ISymbolIn>, 'id' | 'placeholder'>;
-interface ISymbolRegistry {
+  external?: boolean;
   /**
-   * Get a symbol.
+   * Language of the file.
    *
-   * @param identifier Symbol identifier to reference.
-   * @returns The symbol, or undefined if not found.
+   * @example "typescript"
    */
-  get(identifier: ISymbolIdentifier): ISymbolOut | undefined;
+  language?: Language;
   /**
-   * Returns the value associated with a symbol ID.
+   * Logical, extension-free path used for planning and routing.
    *
-   * @param symbolId Symbol ID.
-   * @return The value associated with the symbol ID, or undefined if not found.
+   * @example "src/models/user"
    */
-  getValue(symbolId: number): unknown;
+  logicalFilePath: string;
   /**
-   * Checks if the registry has a value associated with a symbol ID.
+   * 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 symbolId Symbol ID.
-   * @returns True if the registry has a value for symbol ID, false otherwise.
+   * @example "UserModel"
    */
-  hasValue(symbolId: number): boolean;
+  name?: string;
+};
+interface IFileRegistry {
   /**
-   * Returns the current symbol ID and increments it.
+   * Get a file.
    *
-   * @returns Symbol ID before being incremented.
+   * @returns The file, or undefined if not found.
    */
-  readonly id: number;
+  get(args: FileKeyArgs): File | undefined;
   /**
-   * Returns whether a symbol is registered in the registry.
+   * Returns whether a file is registered in the registry.
    *
-   * @param identifier Symbol identifier to check.
-   * @returns True if the symbol is registered, false otherwise.
+   * @returns True if the file is registered, false otherwise.
    */
-  isRegistered(identifier: ISymbolIdentifier): boolean;
+  isRegistered(args: FileKeyArgs): boolean;
   /**
-   * Queries symbols by metadata filter.
+   * Returns the current file ID and increments it.
    *
-   * @param filter Metadata filter to query symbols by.
-   * @returns Array of symbols matching the filter.
+   * @returns File ID before being incremented
    */
-  query(filter: ISymbolMeta): ReadonlyArray<ISymbolOut>;
+  readonly nextId: number;
   /**
-   * References a symbol.
+   * Register a file globally.
    *
-   * @param meta Metadata filter to reference symbol by.
-   * @returns The referenced symbol.
+   * @param file File to register.
+   * @returns Newly registered file if created, merged file otherwise.
    */
-  reference(meta: ISymbolMeta): ISymbolOut;
+  register(file: IFileIn): File;
   /**
-   * Register a symbol globally.
+   * Get all files in the order they were registered.
    *
-   * Deduplicates identical symbols by ID.
+   * @returns Array of all registered files, in insert order.
+   */
+  registered(): IterableIterator<File>;
+}
+//#endregion
+//#region src/nodes/types.d.ts
+interface INodeRegistry {
+  /**
+   * Register a syntax node.
    *
-   * @param symbol Symbol to register.
-   * @returns The registered symbol.
+   * @returns The index of the registered node.
    */
-  register(symbol: ISymbolIn): ISymbolOut;
+  add(node: INode | null): number;
   /**
-   * Get all symbols in the order they were registered.
+   * All nodes in insertion order.
+   */
+  all(): Iterable<INode>;
+  /**
+   * 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.
@@ -443,26 +587,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<Node extends INode = INode> {
+  /**
+   * The current file.
+   */
+  file: File<Node>;
+  /**
+   * 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 {
@@ -471,18 +621,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.
    *
@@ -493,82 +649,297 @@ 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<Node extends INode = INode> {
   /**
-   * The absolute path to the root folder of the project.
+   * Exports from this file.
    */
-  readonly root: string;
+  private _exports;
+  /**
+   * File extension (e.g. `.ts`).
+   */
+  private _extension?;
+  /**
+   * Actual emitted file path, including extension and directories.
+   */
+  private _finalPath?;
   /**
-   * 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.
+   * 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;
+  get imports(): ReadonlyArray<ImportModule>;
+  /**
+   * 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).
+   *
+   * 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<Node>;
+  /**
+   * 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: Node): void;
+  /**
+   * Sets the file extension.
+   */
+  setExtension(extension: string): void;
+  /**
+   * Sets the final emitted path of the file.
+   */
+  setFinalPath(path: string): void;
+  /**
+   * 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/renderer/types.d.ts
-interface IRenderer {
+//#region src/bindings.d.ts
+interface ExportMember {
   /**
-   * Renders content with replaced symbols.
+   * Name under which the symbol is exported in this file.
    *
-   * @param content Content to render.
-   * @param file The file to render.
-   * @param project The parent project the file belongs to.
-   * @returns Rendered content.
-   */
-  renderFile(content: string, file: IFile, project: IProject, meta?: IProjectRenderMeta): string;
+   * export { Foo as Bar } from "./models"
+   *
+   * exportedName === "Bar"
+   */
+  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;
   /**
-   * Returns printable data containing symbols and exports.
+   * The name this symbol will have locally in this file.
+   * This is where aliasing is applied:
    *
-   * @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.
+   * import { Foo as Foo$2 } from "./x"
+   *
+   * localName === "Foo$2"
    */
-  renderSymbols(file: IFileOut, project: IProject, meta?: IProjectRenderMeta): string;
+  localName: string;
+  /** The exported name of the symbol in its source file. */
+  sourceName: string;
+}
+type ImportModule = Pick<ImportMember, 'isTypeOnly'> & Pick<Partial<ImportMember>, 'localName'> & {
+  /** Source file. */
+  from: File;
+  /** List of symbols imported from this module. */
+  imports: Array<ImportMember>;
+  /** Import flavor. */
+  kind: BindingKind;
+};
+//#endregion
+//#region src/brands.d.ts
+declare const nodeBrand = "heyapi.node";
+declare const symbolBrand = "heyapi.symbol";
+//#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/log.d.ts
+/**
+ * Accepts a value or a readonly array of values of type T.
+ */
+type MaybeArray<T> = T | ReadonlyArray<T>;
+/**
+ * Accepts a value or a function returning a value.
+ */
+type MaybeFunc<T extends (...args: Array<any>) => any> = T | ReturnType<T>;
+declare const DebugGroups: {
+  readonly analyzer: colors.StyleFunction;
+  readonly dsl: colors.StyleFunction;
+  readonly file: colors.StyleFunction;
+  readonly registry: colors.StyleFunction;
+  readonly symbol: colors.StyleFunction;
+};
+declare const WarnGroups: {
+  readonly deprecated: colors.StyleFunction;
+};
+declare function debug(message: string, group: keyof typeof DebugGroups): void;
+declare function warn(message: string, group: keyof typeof WarnGroups): void;
+declare function warnDeprecated({
+  context,
+  field,
+  replacement
+}: {
+  context?: string;
+  field: string;
+  replacement?: MaybeFunc<(field: string) => MaybeArray<string>>;
+}): void;
+declare const log: {
+  debug: typeof debug;
+  warn: typeof warn;
+  warnDeprecated: typeof warnDeprecated;
+};
+//#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;
@@ -580,34 +951,183 @@ 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.
+ *
+ * If the value is already a Ref, returns it as-is (idempotent).
+ *
+ * @example
+ * ```ts
+ * const r = ref(123); // { '~ref': 123 }
+ * console.log(r['~ref']); // 123
+ *
+ * const r2 = ref(r); // { '~ref': 123 } (not double-wrapped)
+ * ```
+ */
+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) => FromRef<T>;
 /**
+ * Converts an object of Refs back to a plain object (unwraps all refs).
  *
- * @param source The source string to replace.
- * @param replacerFn Accepts a symbol ID, returns resolved symbol name.
- * @returns The replaced source string.
+ * @example
+ * ```ts
+ * const refs = { a: { '~ref': 1 }, b: { '~ref': "x" } };
+ * const plain = fromRefs(refs); // { a: 1, b: "x" }
+ * ```
  */
-declare const renderIds: (source: string, replacerFn: (symbolId: number) => string | undefined) => string;
+declare const fromRefs: <T extends Refs<Record<string, unknown>>>(obj: T) => FromRefs<T>;
+/**
+ * Checks whether a value is a Ref object.
+ *
+ * @param value Value to check
+ * @returns True if the value is a Ref object.
+ */
+declare const isRef: <T>(value: unknown) => value is Ref<T>;
+//#endregion
+//#region src/structure/types.d.ts
+interface StructureInsert {
+  /** Inserted data. */
+  data: unknown;
+  /** Locations where the data should be inserted. */
+  locations: ReadonlyArray<StructureLocation>;
+  /** Source of the inserted data. */
+  source: symbol;
+}
+interface StructureItem extends Pick<StructureInsert, 'data' | 'source'> {
+  /** Location of this item within the structure. */
+  location: ReadonlyArray<string>;
+}
+interface StructureLocation {
+  /** Path within the structure where the data should be inserted. */
+  path: ReadonlyArray<string>;
+  /** Shell to apply at this location. */
+  shell?: StructureShell;
+}
+interface StructureShell {
+  define: (node: StructureNode) => StructureShellResult;
+}
+interface StructureShellResult {
+  dependencies?: Array<INode>;
+  node: INode;
+}
+//#endregion
+//#region src/structure/node.d.ts
+declare class StructureNode {
+  /** Nested nodes within this node. */
+  children: Map<string, StructureNode>;
+  /** Items contained in this node. */
+  items: Array<StructureItem>;
+  /** The name of this node (e.g., "Users", "Accounts"). */
+  name: string;
+  /** Parent node in the hierarchy. Undefined if this is the root node. */
+  parent?: StructureNode;
+  /** Shell claimed for this node. */
+  shell?: StructureShell;
+  /** Source of the claimed shell. */
+  shellSource?: symbol;
+  /** True if this is a virtual root. */
+  virtual: boolean;
+  constructor(name: string, parent?: StructureNode, options?: {
+    virtual?: boolean;
+  });
+  get isRoot(): boolean;
+  /**
+   * Gets or creates a child node.
+   *
+   * If the child doesn't exist, it's created automatically.
+   *
+   * @param name - The name of the child node
+   * @returns The child node instance
+   */
+  child(name: string): StructureNode;
+  /**
+   * Gets the full path of this node in the hierarchy.
+   *
+   * @returns An array of node names from the root to this node
+   */
+  getPath(): ReadonlyArray<string>;
+  /**
+   * Yields items from a specific source with typed data.
+   *
+   * @param source - The source symbol to filter by
+   * @returns Generator of items from that source
+   */
+  itemsFrom<T = unknown>(source: symbol): Generator<StructureItem & {
+    data: T;
+  }>;
+  /**
+   * Walk all nodes in the structure (depth-first, post-order).
+   *
+   * @returns Generator of all structure nodes
+   */
+  walk(): Generator<StructureNode>;
+}
+//#endregion
+//#region src/structure/model.d.ts
+declare class StructureModel {
+  /** Root nodes mapped by their names. */
+  private _roots;
+  /** Node for data without a specific root. */
+  private _virtualRoot?;
+  /**
+   * Get all root nodes.
+   */
+  get roots(): ReadonlyArray<StructureNode>;
+  /**
+   * Insert data into the structure.
+   */
+  insert(args: StructureInsert): void;
+  /**
+   * Gets or creates a root by name.
+   *
+   * If the root doesn't exist, it's created automatically.
+   *
+   * @param name - The name of the root
+   * @returns The root instance
+   */
+  root(name: string | null): StructureNode;
+  /**
+   * Walk all nodes in the structure (depth-first, post-order).
+   *
+   * @returns Generator of all structure nodes
+   */
+  walk(): Generator<StructureNode>;
+}
 //#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 NodeName, type NodeNameSanitizer, type NodeRelationship, type NodeScope, type IOutput as Output, Project, type IProjectRenderMeta as ProjectRenderMeta, type Ref, type Refs, type RenderContext, type Renderer, type StructureInsert, type StructureItem, type StructureLocation, StructureModel, StructureNode, type StructureShell, type StructureShellResult, Symbol, type ISymbolIdentifier as SymbolIdentifier, type ISymbolIn as SymbolIn, type ISymbolMeta as SymbolMeta, defaultExtensions, defaultNameConflictResolvers, fromRef, fromRefs, isNode, isNodeRef, isRef, isSymbol, isSymbolRef, log, nodeBrand, ref, refs, simpleNameConflictResolver, symbolBrand, underscoreNameConflictResolver };
 //# sourceMappingURL=index.d.cts.map