@typra/emitter 0.2.0

package/dist/src/generate.js

@@ -0,0 +1,104 @@
+import path from "path";
+import { fileURLToPath } from "url";
+import { execFileSync } from "child_process";
+import { existsSync, mkdirSync, writeFileSync, unlinkSync } from "fs";
+import * as YAML from "yaml";
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+/**
+ * Generate Typra runtime surfaces.
+ *
+ * @example
+ * ```typescript
+ * import { generate } from '@typra/emitter/generate';
+ *
+ * await generate({
+ *   output: './generated',
+ *   targets: ['python', 'csharp'],
+ *   rootObject: 'Typra.Widget',
+ *   omit: ['LegacyWidget']
+ * });
+ * ```
+ */
+export async function generate(options) {
+    const { output, targets = ["python", "csharp", "typescript", "go"], rootObject = "Typra.FixtureRoot", omit = [], namespace = "Typra", rootAlias, generateTests = true, format = true, } = options;
+    // Resolve the model path (inside the package)
+    // __dirname is dist/src at runtime, so we need to go up two levels to package root
+    const packageRoot = path.resolve(__dirname, "../..");
+    const modelPath = path.resolve(packageRoot, "lib/model/main.tsp");
+    // Ensure output directory exists
+    const outputDir = path.resolve(output);
+    if (!existsSync(outputDir)) {
+        mkdirSync(outputDir, { recursive: true });
+    }
+    // Build emit targets configuration
+    const emitTargets = buildEmitTargets(targets, outputDir, generateTests, format);
+    // Create temporary tspconfig.yaml
+    const tspConfig = {
+        emit: ["@typra/emitter"],
+        options: {
+            "@typra/emitter": {
+                "emitter-output-dir": outputDir,
+                "root-object": rootObject,
+                "root-namespace": namespace,
+                ...(rootAlias && { "root-alias": rootAlias }),
+                ...(omit.length > 0 && { "omit-models": omit }),
+                "emit-targets": emitTargets,
+            },
+        },
+    };
+    // Write temporary config file
+    const tempConfigPath = path.join(outputDir, ".tspconfig.temp.yaml");
+    writeFileSync(tempConfigPath, YAML.stringify(tspConfig));
+    try {
+        // Run tsp compile — use execFileSync to avoid shell injection
+        execFileSync("tsp", ["compile", modelPath, "--config", tempConfigPath], {
+            stdio: "inherit",
+            cwd: outputDir,
+        });
+        return {
+            success: true,
+            outputDir,
+            targets: Array.isArray(targets) ? targets : Object.keys(targets),
+        };
+    }
+    catch (error) {
+        return {
+            success: false,
+            outputDir,
+            targets: Array.isArray(targets) ? targets : Object.keys(targets),
+            errors: [error instanceof Error ? error.message : String(error)],
+        };
+    }
+    finally {
+        // Clean up temp config
+        try {
+            unlinkSync(tempConfigPath);
+        }
+        catch {
+            // Ignore cleanup errors
+        }
+    }
+}
+function buildEmitTargets(targets, baseOutput, generateTests, format) {
+    if (Array.isArray(targets)) {
+        // Simple array of target names - use default directories
+        return targets.map(target => ({
+            type: target,
+            "output-dir": path.join(baseOutput, target),
+            "test-dir": generateTests ? path.join(baseOutput, target, "tests") : undefined,
+            format,
+        }));
+    }
+    else {
+        // Object with per-target configuration
+        return Object.entries(targets).map(([target, opts]) => ({
+            type: target,
+            "output-dir": opts.outputDir,
+            "test-dir": opts.testDir,
+            format: opts.format ?? format,
+            namespace: opts.namespace,
+        }));
+    }
+}
+//# sourceMappingURL=generate.js.map

package/dist/src/index.d.ts

@@ -0,0 +1,4 @@
+export { $onEmit, GeneratorOptions, filterNodes } from "./emitter.js";
+export { $lib } from "./lib.js";
+export { $sample, $abstract, $coerce, $factory, $method, $knownAs, $defaultFor, $protocol } from "./decorators.js";
+export { generate, GenerateOptions, GenerateResult, TargetLanguage, TargetOptions } from "./generate.js";

package/dist/src/index.js

@@ -0,0 +1,5 @@
+export { $onEmit, filterNodes } from "./emitter.js";
+export { $lib } from "./lib.js";
+export { $sample, $abstract, $coerce, $factory, $method, $knownAs, $defaultFor, $protocol } from "./decorators.js";
+export { generate } from "./generate.js";
+//# sourceMappingURL=index.js.map

package/dist/src/ir/ast.d.ts

@@ -0,0 +1,235 @@
+import { Type, Model, Scalar, Union, Program, ModelProperty } from "@typespec/compiler";
+import { SampleEntry, FactoryEntry, MethodEntry, KnownAsEntry, DefaultForEntry } from "../decorators.js";
+export interface TypeName {
+    namespace: string;
+    name: string;
+}
+export interface Coercion {
+    scalar: string;
+    expansion: {
+        [key: string]: any;
+    };
+    example?: any;
+    title?: string;
+    description?: string;
+}
+export declare class TypeNode {
+    model: Model;
+    typeName: TypeName;
+    description: string;
+    base: TypeName | null;
+    childTypes: TypeNode[];
+    coercions: Coercion[];
+    properties: PropertyNode[];
+    isAbstract: boolean;
+    isProtocol: boolean;
+    discriminator: string | undefined;
+    factories: FactoryEntry[];
+    methods: MethodEntry[];
+    /** Semantic group derived from the TSP source subfolder (e.g. "connection", "tools"). */
+    group: string;
+    constructor(model: Model, description: string);
+    retrievePolymorphicTypes(): any;
+    getSanitizedObject(): Record<string, any>;
+}
+export declare class PropertyNode {
+    name: string;
+    typeName: TypeName;
+    description: string;
+    samples: SampleEntry[];
+    knownAs: KnownAsEntry[];
+    defaultFor: DefaultForEntry[];
+    isScalar: boolean;
+    isOptional: boolean;
+    isCollection: boolean;
+    isAny: boolean;
+    isDict: boolean;
+    defaultValue: string | number | boolean | null;
+    allowedValues: string[];
+    /** Name of the string-literal union alias (e.g., "Role"), null if unnamed or not an enum. */
+    enumName: string | null;
+    /** True when the union includes a bare `string` variant (open enum — accepts any string). */
+    isOpenEnum: boolean;
+    property: ModelProperty;
+    type: TypeNode | undefined;
+    constructor(property: ModelProperty, description: string);
+    getSanitizedObject(): Record<string, any>;
+}
+export declare const enumerateTypes: (node: TypeNode, visited?: Set<string>) => IterableIterator<TypeNode>;
+export declare const resolveModel: (program: Program, model: Model, visited: Set<string> | undefined, rootNamespace: string, rootAlias: string) => TypeNode;
+export declare const resolveModelChildren: (program: Program, model: Model, visited: Set<string>, rootNamespace: string, rootAlias: string) => TypeNode[];
+export declare const resolveProperty: (program: Program, property: ModelProperty, visited: Set<string>, rootNamespace: string, rootAlias: string) => PropertyNode;
+export declare const resolveScalarProperty: (program: Program, property: ModelProperty, scalar: Scalar) => PropertyNode;
+export declare const resolveIntrinsicProperty: (program: Program, property: ModelProperty, intrinsic: Type, visited: Set<string>) => PropertyNode;
+export declare const resolveModelProperty: (program: Program, property: ModelProperty, model: Model, visited: Set<string>, rootNamespace: string, rootAlias: string) => PropertyNode;
+export declare const resolveUnionProperty: (program: Program, property: ModelProperty, union: Union, visited: Set<string>, rootNamespace: string, rootAlias: string) => PropertyNode;
+/**
+ * Context for rendering a single Python class.
+ */
+export interface PythonClassContext {
+    /** The TypeNode being rendered */
+    node: TypeNode;
+    /** Type mapping from TypeSpec types to Python types */
+    typeMapper: Record<string, string>;
+    /** Processed coercion representations for scalar-to-object constructors */
+    coercions: Array<{
+        scalar: string;
+        alternate: string;
+    }>;
+    /** Polymorphic type information if this is a discriminated type */
+    polymorphicTypes: ReturnType<TypeNode['retrievePolymorphicTypes']> | undefined;
+    /** Import types needed from other modules */
+    imports: string[];
+    /** Collection properties with their nested type info for load_* methods */
+    collectionTypes: Array<{
+        prop: PropertyNode;
+        type: string[];
+    }>;
+    /** The property name that receives the scalar value in a coercion expansion */
+    coercionProperty: string | null;
+    /** Maps factory.name → safe Python method name (prefixed with create_ on field collision) */
+    factoryNameMap: Record<string, string>;
+    /** Pre-rendered factory method bodies via expression IR */
+    renderedFactories: Array<{
+        name: string;
+        safeName: string;
+        params: Record<string, string>;
+        body: string;
+    }>;
+    /** Pre-rendered coercion expressions via expression IR */
+    renderedCoercions: Array<{
+        scalar: string;
+        expression: string;
+    }>;
+    /** Type names referenced in factory expressions (for file-level import resolution) */
+    factoryTypeRefs: string[];
+}
+/**
+ * Context for rendering a Python file containing one or more classes.
+ */
+export interface PythonFileContext {
+    /** Whether any class in the file is abstract */
+    containsAbstract: boolean;
+    /** Python typing imports needed (e.g., "Any", "Callable", "Optional") */
+    typings: string[];
+    /** Grouped imports: each entry maps a module name to the types imported from it */
+    imports: Array<{
+        module: string;
+        names: string[];
+    }>;
+    /** Array of class contexts to render */
+    classes: PythonClassContext[];
+    /** Type mapping from TypeSpec types to Python types */
+    typeMapper: Record<string, string>;
+}
+/**
+ * Context for rendering a Python __init__.py file.
+ */
+export interface PythonInitContext {
+    /** Base types (types without a parent) for top-level imports */
+    baseTypes: TypeNode[];
+    /** All types for __all__ export list */
+    types: TypeNode[];
+}
+/**
+ * Context for rendering Python test files.
+ */
+export interface PythonTestContext {
+    /** The TypeNode being tested */
+    node: TypeNode;
+    /** Flattened sample combinations for testing */
+    examples: Array<{
+        json: string[];
+        yaml: string[];
+        validation: Array<{
+            key: string;
+            value: any;
+            delimeter: string;
+        }>;
+    }>;
+    /** Coercion representation tests */
+    coercions: Array<{
+        title: string;
+        scalar: string;
+        value: string;
+        validation: Array<{
+            key: string;
+            value: any;
+            delimeter: string;
+        }>;
+    }>;
+}
+/**
+ * Context for rendering the LoadContext file.
+ */
+export interface PythonLoadContextContext {
+    /** File header comment */
+    header: string;
+    /** Package name for imports in test file */
+    package?: string;
+}
+/**
+ * Base render context interface - all language contexts should extend this.
+ * This ensures consistency across emitters.
+ */
+export interface BaseRenderContext {
+    /** The TypeNode being rendered */
+    node: TypeNode;
+    /** Type mapping from TypeSpec types to target language types */
+    typeMapper: Record<string, string>;
+}
+/**
+ * Validation assertion for a single property in a test.
+ */
+export interface PropertyValidation {
+    /** Property name in target language casing (PascalCase, snake_case, camelCase) */
+    key: string;
+    /** Expected value after loading */
+    value: any;
+    /** String delimiter for assertions (", """, etc.) */
+    delimiter: string;
+    /** Whether property is optional/pointer (for Go, C# nullable) */
+    isOptional: boolean;
+}
+/**
+ * A single test example generated from @sample decorators.
+ */
+export interface TestExample {
+    /** JSON representation as lines */
+    json: string[];
+    /** YAML representation as lines */
+    yaml: string[];
+    /** Property assertions to validate after loading */
+    validations: PropertyValidation[];
+}
+/**
+ * A coercion (scalar-to-object) representation test case.
+ */
+export interface CoercionTest {
+    /** Human-readable test name/title */
+    title: string;
+    /** Scalar type name in target language */
+    scalarType: string;
+    /** Example scalar value as string literal */
+    value: string;
+    /** Validations after expansion to full object */
+    validations: PropertyValidation[];
+}
+/**
+ * Base test context interface - all language test contexts should use this structure.
+ * This ensures consistency in test generation across all emitters.
+ */
+export interface BaseTestContext {
+    /** The TypeNode being tested */
+    node: TypeNode;
+    /** Whether this is an abstract/polymorphic base type (skip direct instantiation tests) */
+    isAbstract: boolean;
+    /** Package/namespace name for imports (optional - not used by all languages) */
+    package?: string;
+    /** Test examples from @sample decorators */
+    examples: TestExample[];
+    /** Coercion (scalar-to-object) representation tests */
+    coercions: CoercionTest[];
+    /** Factory methods declared via @factory (for auto-generated factory tests) */
+    factories: FactoryEntry[];
+}