@player-lang/functional-dsl-generator 0.0.2-next.0

package/src/default-value-generator.ts

@@ -0,0 +1,307 @@
+import type { NodeType, ObjectType } from "@xlr-lib/xlr";
+import {
+  isStringType,
+  isNumberType,
+  isBooleanType,
+  isObjectType,
+  isArrayType,
+  isRefType,
+  isOrType,
+  isAndType,
+  isPrimitiveConst,
+  isAssetWrapperRef,
+  isExpressionRef,
+  isBindingRef,
+} from "./utils";
+
+/**
+ * Configuration for default value generation
+ */
+export interface DefaultValueConfig {
+  /**
+   * Maximum depth for recursive object defaults.
+   * Prevents infinite recursion for deeply nested or circular types.
+   *
+   * The depth counter starts at 0 for the root object and increments
+   * for each nested object level. When depth equals maxDepth, nested
+   * objects are returned as empty `{}` instead of recursing further.
+   *
+   * Example with maxDepth=3:
+   * - Root object (depth 0): full defaults generated
+   * - level1.nested (depth 1): full defaults generated
+   * - level1.nested.child (depth 2): full defaults generated
+   * - level1.nested.child.deep (depth 3): returns {} (depth limit reached)
+   *
+   * Default: 3
+   */
+  maxDepth?: number;
+
+  /**
+   * Type names to skip (user must provide these values).
+   * Typically includes "Asset" and "AssetWrapper".
+   */
+  skipTypes?: Set<string>;
+}
+
+const DEFAULT_CONFIG: Required<DefaultValueConfig> = {
+  maxDepth: 3,
+  skipTypes: new Set(["Asset", "AssetWrapper"]),
+};
+
+/**
+ * Context for tracking default generation state
+ */
+interface GenerationContext {
+  depth: number;
+  config: Required<DefaultValueConfig>;
+}
+
+/**
+ * Generates smart default values for builder classes.
+ *
+ * This generator creates sensible defaults for required fields:
+ * - String → ""
+ * - Number → 0
+ * - Boolean → false
+ * - Array → []
+ * - Object → {} or recursive defaults for required properties
+ * - Expression/Binding → ""
+ * - Union types → uses the first non-null/undefined variant
+ * - AssetWrapper → SKIPPED (user must provide)
+ */
+export class DefaultValueGenerator {
+  private readonly config: Required<DefaultValueConfig>;
+
+  constructor(config: DefaultValueConfig = {}) {
+    this.config = {
+      ...DEFAULT_CONFIG,
+      ...config,
+      skipTypes: config.skipTypes ?? DEFAULT_CONFIG.skipTypes,
+    };
+  }
+
+  /**
+   * Generate default values for an ObjectType.
+   *
+   * @param objectType - The XLR ObjectType to generate defaults for
+   * @param assetType - Optional asset type string for Asset types
+   * @returns Record of property names to default values
+   */
+  generateDefaults(
+    objectType: ObjectType,
+    assetType?: string,
+  ): Record<string, unknown> {
+    const defaults: Record<string, unknown> = {};
+
+    // Add asset type default if this is an asset
+    if (assetType) {
+      defaults["type"] = assetType;
+    }
+
+    // Add default ID for assets (types that extend Asset)
+    if (objectType.extends?.ref.startsWith("Asset")) {
+      defaults["id"] = "";
+    }
+    // Also add default ID for non-Asset types that have an 'id' property
+    else if ("id" in objectType.properties) {
+      defaults["id"] = "";
+    }
+
+    // Process each property
+    const context: GenerationContext = {
+      depth: 0,
+      config: this.config,
+    };
+
+    for (const [propName, prop] of Object.entries(objectType.properties)) {
+      // Const values take precedence
+      if (isPrimitiveConst(prop.node)) {
+        defaults[propName] = prop.node.const;
+        continue;
+      }
+
+      // Only generate defaults for required properties
+      if (!prop.required) {
+        continue;
+      }
+
+      // Skip if we already have a default (e.g., id)
+      if (propName in defaults) {
+        continue;
+      }
+
+      const defaultValue = this.getDefaultForType(prop.node, context);
+      if (defaultValue !== undefined) {
+        defaults[propName] = defaultValue;
+      }
+    }
+
+    return defaults;
+  }
+
+  /**
+   * Get the default value for a specific type node.
+   *
+   * @param node - The type node
+   * @param context - Generation context for tracking depth
+   * @returns The default value, or undefined if the type should be skipped
+   */
+  private getDefaultForType(
+    node: NodeType,
+    context: GenerationContext,
+  ): unknown {
+    // Skip AssetWrapper - user must provide
+    if (isAssetWrapperRef(node)) {
+      return undefined;
+    }
+
+    // Check for other skip types
+    if (isRefType(node)) {
+      const baseName = node.ref.split("<")[0];
+      if (context.config.skipTypes.has(baseName)) {
+        return undefined;
+      }
+    }
+
+    // Handle primitive types
+    if (isStringType(node)) {
+      return "";
+    }
+
+    if (isNumberType(node)) {
+      return 0;
+    }
+
+    if (isBooleanType(node)) {
+      return false;
+    }
+
+    // Handle Expression and Binding refs
+    if (isExpressionRef(node) || isBindingRef(node)) {
+      return "";
+    }
+
+    // Handle arrays
+    if (isArrayType(node)) {
+      return [];
+    }
+
+    // Handle union types - pick first non-null/undefined variant
+    if (isOrType(node)) {
+      return this.getDefaultForUnion(node.or, context);
+    }
+
+    // Handle intersection types - try to merge defaults
+    if (isAndType(node)) {
+      return this.getDefaultForIntersection(node.and, context);
+    }
+
+    // Handle object types with depth limit
+    if (isObjectType(node)) {
+      if (context.depth >= context.config.maxDepth) {
+        return {};
+      }
+
+      return this.getDefaultForObject(node, {
+        ...context,
+        depth: context.depth + 1,
+      });
+    }
+
+    // Handle null/undefined types
+    if (node.type === "null") {
+      return null;
+    }
+
+    if (node.type === "undefined") {
+      return undefined;
+    }
+
+    // Refs to other types - return empty object as a safe default
+    if (isRefType(node)) {
+      return {};
+    }
+
+    return undefined;
+  }
+
+  /**
+   * Get default for a union type by picking the first non-null/undefined variant.
+   */
+  private getDefaultForUnion(
+    variants: NodeType[],
+    context: GenerationContext,
+  ): unknown {
+    for (const variant of variants) {
+      // Skip null and undefined
+      if (variant.type === "null" || variant.type === "undefined") {
+        continue;
+      }
+
+      const defaultValue = this.getDefaultForType(variant, context);
+      if (defaultValue !== undefined) {
+        return defaultValue;
+      }
+    }
+
+    // If all variants are null/undefined, return undefined
+    return undefined;
+  }
+
+  /**
+   * Get default for an intersection type by attempting to merge.
+   */
+  private getDefaultForIntersection(
+    parts: NodeType[],
+    context: GenerationContext,
+  ): unknown {
+    // For intersections, we need to satisfy all parts
+    // Start with an empty object and merge
+    const merged: Record<string, unknown> = {};
+
+    for (const part of parts) {
+      const partDefault = this.getDefaultForType(part, context);
+
+      if (
+        partDefault !== undefined &&
+        typeof partDefault === "object" &&
+        partDefault !== null &&
+        !Array.isArray(partDefault)
+      ) {
+        Object.assign(merged, partDefault);
+      }
+    }
+
+    return Object.keys(merged).length > 0 ? merged : {};
+  }
+
+  /**
+   * Get default for an object type by processing required properties.
+   */
+  private getDefaultForObject(
+    node: ObjectType,
+    context: GenerationContext,
+  ): Record<string, unknown> {
+    const result: Record<string, unknown> = {};
+
+    for (const [propName, prop] of Object.entries(node.properties)) {
+      // Const values take precedence
+      if (isPrimitiveConst(prop.node)) {
+        result[propName] = prop.node.const;
+        continue;
+      }
+
+      // Only generate defaults for required properties
+      if (!prop.required) {
+        continue;
+      }
+
+      const defaultValue = this.getDefaultForType(prop.node, context);
+      if (defaultValue !== undefined) {
+        result[propName] = defaultValue;
+      }
+    }
+
+    return result;
+  }
+}

package/src/generator.ts

@@ -0,0 +1,257 @@
+import type { ObjectType, NamedType } from "@xlr-lib/xlr";
+import { isGenericNamedType } from "@xlr-lib/xlr-utils";
+import {
+  toFactoryName,
+  toBuilderClassName,
+  getAssetTypeFromExtends,
+  type TypeRegistry,
+} from "./utils";
+import {
+  type TypeScriptContext,
+  type UnexportedTypeInfo,
+} from "./type-resolver";
+import { TypeCollector } from "./type-collector";
+import { TypeTransformer } from "./type-transformer";
+import {
+  ImportGenerator,
+  type ImportGeneratorConfig,
+} from "./import-generator";
+import {
+  BuilderClassGenerator,
+  type BuilderInfo,
+} from "./builder-class-generator";
+
+// Re-export types for public API
+export type { TypeScriptContext, UnexportedTypeInfo } from "./type-resolver";
+export type { BuilderInfo } from "./builder-class-generator";
+
+/**
+ * Configuration for the generator
+ */
+export interface GeneratorConfig {
+  /** Import path for functional utilities (default: "@player-lang/functional-dsl") */
+  functionalImportPath?: string;
+  /** Import path for player-ui types (default: "@player-ui/types") */
+  typesImportPath?: string;
+  /**
+   * TypeScript context for automatic import resolution.
+   * When provided, the generator will automatically resolve import paths
+   * using TypeScript's module resolution.
+   */
+  tsContext?: TypeScriptContext;
+  /** Function to generate the type import path for a given type name */
+  typeImportPathGenerator?: (typeName: string) => string;
+  /**
+   * Set of type names that are defined in the same source file as the main type.
+   * Types not in this set will be imported from their own source files using typeImportPathGenerator.
+   * When tsContext is provided, this is computed automatically from the source file.
+   */
+  sameFileTypes?: Set<string>;
+  /**
+   * Explicitly maps type names to their package names for external imports.
+   * Types in this map will be imported from the specified package (e.g., "@player-lang/types").
+   * This takes precedence over typeImportPathGenerator for the specified types.
+   */
+  externalTypes?: Map<string, string>;
+  /**
+   * Type registry for resolving nested interface references.
+   * Maps type names to their XLR ObjectType definitions.
+   * Used to find AssetWrapper paths in nested interfaces.
+   */
+  typeRegistry?: TypeRegistry;
+}
+
+/**
+ * Result of builder generation including warnings
+ */
+export interface GeneratorResult {
+  /** Generated TypeScript code */
+  code: string;
+  /** Types that need to be exported in their source files */
+  unexportedTypes: UnexportedTypeInfo[];
+}
+
+/**
+ * Generates functional builder TypeScript code from XLR types.
+ * This class orchestrates the type collection, transformation, and code generation.
+ */
+export class FunctionalBuilderGenerator {
+  private readonly namedType: NamedType<ObjectType>;
+  private readonly config: GeneratorConfig;
+
+  /** Import generator handles import tracking and generation */
+  private readonly importGenerator: ImportGenerator;
+
+  /** Type transformer handles XLR to TypeScript type conversion */
+  private readonly typeTransformer: TypeTransformer;
+
+  /** Type collector handles collecting type references */
+  private readonly typeCollector: TypeCollector;
+
+  /** Builder class generator handles class code generation */
+  private readonly builderClassGenerator: BuilderClassGenerator;
+
+  /** Map short type names to their full qualified names */
+  private readonly namespaceMemberMap = new Map<string, string>();
+
+  constructor(namedType: NamedType<ObjectType>, config: GeneratorConfig = {}) {
+    this.namedType = namedType;
+    this.config = config;
+
+    // Create import generator config
+    const importConfig: ImportGeneratorConfig = {
+      functionalImportPath: config.functionalImportPath,
+      typesImportPath: config.typesImportPath,
+      tsContext: config.tsContext,
+      typeImportPathGenerator: config.typeImportPathGenerator,
+      sameFileTypes: config.sameFileTypes,
+      externalTypes: config.externalTypes,
+      typeRegistry: config.typeRegistry,
+    };
+
+    // Initialize the import generator
+    this.importGenerator = new ImportGenerator(importConfig);
+
+    // Initialize the type transformer with the import generator as context
+    this.typeTransformer = new TypeTransformer(this.importGenerator);
+
+    // Initialize the type collector with the import generator as tracker
+    this.typeCollector = new TypeCollector(
+      this.importGenerator,
+      this.importGenerator.getGenericParamSymbols(),
+      namedType.name,
+      this.importGenerator.getNamespaceMemberMap(),
+      config.typeRegistry,
+    );
+
+    // Initialize the builder class generator with the type transformer and type registry
+    this.builderClassGenerator = new BuilderClassGenerator(
+      this.typeTransformer,
+      config.typeRegistry,
+    );
+  }
+
+  /**
+   * Get list of types that exist but need to be exported.
+   * Call this after generate() to get warnings for the user.
+   */
+  getUnexportedTypes(): UnexportedTypeInfo[] {
+    return this.importGenerator.getUnexportedTypes();
+  }
+
+  /**
+   * Get list of types that couldn't be resolved at all.
+   * These types are used in the generated code but won't be imported,
+   * causing type errors. Often these are namespaced types (e.g., Validation.CrossfieldReference).
+   */
+  getUnresolvedTypes(): string[] {
+    return this.importGenerator.getUnresolvedTypes();
+  }
+
+  /**
+   * Generate the builder code
+   */
+  generate(): string {
+    // Collect generic parameter symbols first so we can exclude them from imports
+    // This MUST happen before createBuilderInfo since transformTypeForConstraint needs it
+    this.typeCollector.collectGenericParamSymbols(this.namedType);
+
+    const mainBuilder = this.createBuilderInfo(this.namedType);
+
+    // Collect types from generic constraints/defaults for import generation
+    this.typeCollector.collectTypesFromGenericTokens(this.namedType);
+
+    // Collect all referenced types for imports (no nested builders are generated)
+    this.typeCollector.collectReferencedTypes(this.namedType);
+
+    // Generate main builder class (this also sets needsAssetImport flag)
+    const mainBuilderCode =
+      this.builderClassGenerator.generateBuilderClass(mainBuilder);
+
+    // Generate imports after builder code so we know what imports are needed
+    const imports = this.importGenerator.generateImports(mainBuilder.name);
+
+    return [imports, mainBuilderCode].filter(Boolean).join("\n\n");
+  }
+
+  private createBuilderInfo(namedType: NamedType<ObjectType>): BuilderInfo {
+    const assetType = getAssetTypeFromExtends(namedType);
+    const isAsset = !!assetType;
+
+    let genericParams: string | undefined;
+    if (isGenericNamedType(namedType)) {
+      // Deduplicate generic parameters by symbol name
+      // This handles cases where a type extends another generic type without
+      // passing type arguments, causing XLR to collect parameters from both
+      const seenParams = new Set<string>();
+      genericParams = namedType.genericTokens
+        .filter((t) => {
+          if (seenParams.has(t.symbol)) {
+            return false;
+          }
+          seenParams.add(t.symbol);
+          return true;
+        })
+        .map((t) => {
+          let param = t.symbol;
+          if (t.constraints) {
+            const constraintType =
+              this.typeTransformer.transformTypeForConstraint(t.constraints);
+            // Skip 'any' constraints - these represent unconstrained generics in TypeScript
+            // Adding "extends any" is redundant and reduces type safety
+            if (constraintType !== "any") {
+              param += ` extends ${constraintType}`;
+            }
+          }
+          if (t.default) {
+            param += ` = ${this.typeTransformer.transformTypeForConstraint(t.default)}`;
+          }
+          return param;
+        })
+        .join(", ");
+    }
+
+    return {
+      name: namedType.name,
+      className: toBuilderClassName(namedType.name),
+      factoryName: toFactoryName(namedType.name),
+      objectType: namedType,
+      assetType,
+      genericParams,
+      isAsset,
+    };
+  }
+}
+
+/**
+ * Generate functional builder code from a NamedType<ObjectType>
+ * @param namedType - The XLR NamedType to generate a builder for
+ * @param config - Optional generator configuration
+ * @returns Generated TypeScript code for the functional builder
+ */
+export function generateFunctionalBuilder(
+  namedType: NamedType<ObjectType>,
+  config: GeneratorConfig = {},
+): string {
+  const generator = new FunctionalBuilderGenerator(namedType, config);
+  return generator.generate();
+}
+
+/**
+ * Generate functional builder code with warnings about unexported types.
+ * Use this when you want to get detailed information about types that need
+ * to be exported in their source files.
+ *
+ * @param namedType - The XLR NamedType to generate a builder for
+ * @param config - Optional generator configuration
+ * @returns Generated code and list of types that need to be exported
+ */
+export function generateFunctionalBuilderWithWarnings(
+  namedType: NamedType<ObjectType>,
+  config: GeneratorConfig = {},
+): GeneratorResult {
+  const generator = new FunctionalBuilderGenerator(namedType, config);
+  const code = generator.generate();
+  const unexportedTypes = generator.getUnexportedTypes();
+  return { code, unexportedTypes };
+}