@hey-api/codegen-core 0.4.0 → 0.5.1

package/dist/index.d.mts

@@ -1,3 +1,4 @@
+
 import colors from "ansi-colors";
 
 //#region src/refs/types.d.ts
@@ -12,7 +13,9 @@ import colors from "ansi-colors";
  * console.log(num['~ref']); // 42
  * ```
  */
-type Ref<T> = {
+type Ref<T> = T extends {
+  ['~ref']: unknown;
+} ? T : {
   '~ref': T;
 };
 /**
@@ -35,7 +38,9 @@ type Refs<T> = { [K in keyof T]: Ref<T[K]> };
  * type N = FromRef<{ '~ref': number }>; // number
  * ```
  */
-type FromRef<T> = T extends Ref<infer V> ? V : T;
+type FromRef<T> = T extends {
+  '~ref': infer U;
+} ? U : T;
 /**
  * Maps every property of a Ref-wrapped object back to its plain value.
  *
@@ -46,7 +51,7 @@ type FromRef<T> = T extends Ref<infer V> ? V : T;
  * type Foo2 = FromRefs<Refs>; // { a: number; b: string }
  * ```
  */
-type FromRefs<T> = { [K in keyof T]: T[K] extends Ref<infer V> ? V : T[K] };
+type FromRefs<T> = { [K in keyof T]: T[K] extends Ref<infer U> ? U : T[K] };
 //#endregion
 //#region src/extensions.d.ts
 /**
@@ -67,19 +72,37 @@ interface ISymbolMeta {
 }
 //#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;
-  /** Parent node in the syntax tree. */
-  parent?: INode;
-  /** Root node of the syntax tree. */
-  root?: INode;
+  /** 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. */
@@ -92,7 +115,6 @@ interface INode<T = unknown> {
 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 = {
   /**
    * Array of file names (without extensions) from which this symbol is re-exported.
@@ -121,10 +143,14 @@ type ISymbolIn = {
   getFilePath?: Symbol['getFilePath'];
   /**
    * Kind of import if this symbol represents an import.
+   *
+   * @default 'named'
    */
   importKind?: BindingKind;
   /**
    * Kind of symbol.
+   *
+   * @default 'var'
    */
   kind?: SymbolKind;
   /**
@@ -195,7 +221,7 @@ interface ISymbolRegistry {
 }
 //#endregion
 //#region src/symbols/symbol.d.ts
-declare class Symbol {
+declare class Symbol<Node extends INode = INode> {
   /**
    * Canonical symbol this stub resolves to, if any.
    *
@@ -263,12 +289,6 @@ declare class Symbol {
    * @example "UserModel"
    */
   private _name;
-  /**
-   * Optional function to sanitize the symbol name.
-   *
-   * @default undefined
-   */
-  private _nameSanitizer?;
   /**
    * Node that defines this symbol.
    */
@@ -332,14 +352,10 @@ declare class Symbol {
    * 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;
+  get node(): Node | undefined;
   /**
    * Marks this symbol as a stub and assigns its canonical symbol.
    *
@@ -391,18 +407,12 @@ declare class Symbol {
    * @param name — The new name.
    */
   setName(name: string): void;
-  /**
-   * Sets a custom function to sanitize the symbol's name.
-   *
-   * @param fn — The name sanitizer function to apply.
-   */
-  setNameSanitizer(fn: SymbolNameSanitizer): void;
   /**
    * Binds the node that defines this symbol.
    *
    * This may only be set once.
    */
-  setNode(node: INode): void;
+  setNode(node: Node): void;
   /**
    * Returns a debug‑friendly string representation identifying the symbol.
    */
@@ -420,13 +430,8 @@ declare class Symbol {
   private assertCanonical;
 }
 //#endregion
-//#region src/planner/types.d.ts
-type Input = Ref<object> | object | string | number | undefined;
+//#region src/planner/scope.d.ts
 type NameScopes = Map<string, Set<SymbolKind>>;
-type NameConflictResolver = (args: {
-  attempt: number;
-  baseName: string;
-}) => string | null;
 type Scope = {
   /** Child scopes. */
   children: Array<Scope>;
@@ -437,6 +442,13 @@ type 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;
@@ -576,11 +588,11 @@ interface IOutput {
 }
 //#endregion
 //#region src/renderer.d.ts
-interface RenderContext {
+interface RenderContext<Node extends INode = INode> {
   /**
    * The current file.
    */
-  file: File;
+  file: File<Node>;
   /**
    * Arbitrary metadata.
    */
@@ -627,6 +639,13 @@ interface IProject {
   readonly nameConflictResolvers: NameConflictResolvers;
   /** Centralized node registry for the project. */
   readonly nodes: INodeRegistry;
+  /**
+   * Finalizes the project structure, resolving nodes, symbols, and dependencies.
+   *
+   * @param meta Arbitrary metadata.
+   * @returns void
+   */
+  plan(meta?: IProjectRenderMeta): void;
   /**
    * Produces output representations for all files in the project.
    *
@@ -650,7 +669,7 @@ interface IProject {
 }
 //#endregion
 //#region src/files/file.d.ts
-declare class File {
+declare class File<Node extends INode = INode> {
   /**
    * Exports from this file.
    */
@@ -736,7 +755,7 @@ declare class File {
   /**
    * Syntax nodes contained in this file.
    */
-  get nodes(): ReadonlyArray<INode>;
+  get nodes(): ReadonlyArray<Node>;
   /**
    * Renderer assigned to this file.
    */
@@ -752,7 +771,7 @@ declare class File {
   /**
    * Add a syntax node to the file.
    */
-  addNode(node: INode): void;
+  addNode(node: Node): void;
   /**
    * Sets the file extension.
    */
@@ -809,8 +828,6 @@ type ExportModule = Pick<ExportMember, 'isTypeOnly'> & {
 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:
@@ -823,29 +840,19 @@ interface ImportMember {
   /** The exported name of the symbol in its source file. */
   sourceName: string;
 }
-type ImportModule = Pick<ImportMember, 'isTypeOnly'> & {
+type ImportModule = Pick<ImportMember, 'isTypeOnly'> & Pick<Partial<ImportMember>, 'localName'> & {
   /** 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;
+  /** Import flavor. */
+  kind: BindingKind;
 };
 //#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>;
@@ -858,6 +865,42 @@ declare const defaultExtensions: Extensions;
 //#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;
@@ -915,6 +958,7 @@ declare class SymbolRegistry implements ISymbolRegistry {
 //#endregion
 //#region src/project/project.d.ts
 declare class Project implements IProject {
+  private _isPlanned;
   readonly files: FileRegistry;
   readonly nodes: NodeRegistry;
   readonly symbols: SymbolRegistry;
@@ -926,6 +970,7 @@ declare class Project implements IProject {
   readonly renderers: ReadonlyArray<Renderer>;
   readonly root: string;
   constructor(args: Pick<Partial<IProject>, 'defaultFileName' | 'defaultNameConflictResolver' | 'extensions' | 'fileName' | 'nameConflictResolvers' | 'renderers'> & Pick<IProject, 'root'>);
+  plan(meta?: IProjectRenderMeta): void;
   render(meta?: IProjectRenderMeta): ReadonlyArray<IOutput>;
 }
 //#endregion
@@ -933,10 +978,14 @@ declare class Project implements IProject {
 /**
  * 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>;
@@ -960,7 +1009,7 @@ declare const refs: <T extends Record<string, unknown>>(obj: T) => Refs<T>;
  * console.log(n); // 42
  * ```
  */
-declare const fromRef: <T extends Ref<unknown> | undefined>(ref: T) => T extends Ref<infer U> ? U : undefined;
+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).
  *
@@ -979,5 +1028,115 @@ declare const fromRefs: <T extends Refs<Record<string, unknown>>>(obj: T) => Fro
  */
 declare const isRef: <T>(value: unknown) => value is Ref<T>;
 //#endregion
-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 };
+//#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 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.mts.map