@typra/emitter 0.2.0

package/dist/src/languages/go/scaffolding.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Go scaffolding emitter — generates the LoadContext / SaveContext file.
+ *
+ * Replaces `context.go.njk` Nunjucks template with a typed TypeScript
+ * function that produces identical Go source output.
+ */
+interface GoContextContext {
+    header: string;
+    packageName: string;
+}
+/**
+ * Emit the Go context file containing LoadContext and SaveContext structs.
+ *
+ * @param ctx - header string and package name
+ * @returns Complete Go source file as a string
+ */
+export declare function emitGoContext(ctx: GoContextContext): string;
+export {};

package/dist/src/languages/go/scaffolding.js

@@ -0,0 +1,53 @@
+/**
+ * Go scaffolding emitter — generates the LoadContext / SaveContext file.
+ *
+ * Replaces `context.go.njk` Nunjucks template with a typed TypeScript
+ * function that produces identical Go source output.
+ */
+// ============================================================================
+// Main entry point
+// ============================================================================
+/**
+ * Emit the Go context file containing LoadContext and SaveContext structs.
+ *
+ * @param ctx - header string and package name
+ * @returns Complete Go source file as a string
+ */
+export function emitGoContext(ctx) {
+    const lines = [];
+    lines.push("// Code generated by Typra emitter; DO NOT EDIT.");
+    lines.push(`// ${ctx.header}`);
+    lines.push("");
+    lines.push(`package ${ctx.packageName}`);
+    lines.push("");
+    lines.push("// LoadContext provides context for loading operations");
+    lines.push("type LoadContext struct {");
+    lines.push("\t// Add any context fields needed for loading");
+    lines.push("\t// e.g., file paths, base directories, etc.");
+    lines.push("}");
+    lines.push("");
+    lines.push("// NewLoadContext creates a new LoadContext");
+    lines.push("func NewLoadContext() *LoadContext {");
+    lines.push("\treturn &LoadContext{}");
+    lines.push("}");
+    lines.push("");
+    lines.push("// SaveContext provides context for saving operations");
+    lines.push("type SaveContext struct {");
+    lines.push("\t// Add any context fields needed for saving");
+    lines.push("\t// e.g., output directories, formatting options, etc.");
+    lines.push("}");
+    lines.push("");
+    lines.push("// NewSaveContext creates a new SaveContext");
+    lines.push("func NewSaveContext() *SaveContext {");
+    lines.push("\treturn &SaveContext{}");
+    lines.push("}");
+    lines.push("");
+    lines.push("// ptrOf returns a pointer to the given value. Used by factory functions");
+    lines.push("// to set optional (pointer) fields in struct literals.");
+    lines.push("func ptrOf[T any](v T) *T {");
+    lines.push("\treturn &v");
+    lines.push("}");
+    lines.push("");
+    return lines.join("\n");
+}
+//# sourceMappingURL=scaffolding.js.map

package/dist/src/languages/go/test-emitter.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Go test emitter — BaseTestContext → Go test source code.
+ *
+ * Replaces `test.go.njk` and `_macros.njk` Nunjucks templates with
+ * typed TypeScript functions that produce identical Go test output.
+ *
+ * Each test file covers one type and contains:
+ *   - Per-example: LoadJSON, LoadYAML, Roundtrip, ToJSON, ToYAML tests
+ *   - Per-coercion: From<Title> tests for scalar-to-object expansion
+ */
+import { BaseTestContext } from "../../ir/ast.js";
+/**
+ * Emit a complete Go test file for a single type.
+ *
+ * @param ctx - test context built by `buildBaseTestContext()`
+ * @returns Complete Go test source file as a string
+ */
+export declare function emitGoTest(ctx: BaseTestContext & {
+    importPath: string;
+}): string;

package/dist/src/languages/go/test-emitter.js

@@ -0,0 +1,300 @@
+/**
+ * Go test emitter — BaseTestContext → Go test source code.
+ *
+ * Replaces `test.go.njk` and `_macros.njk` Nunjucks templates with
+ * typed TypeScript functions that produce identical Go test output.
+ *
+ * Each test file covers one type and contains:
+ *   - Per-example: LoadJSON, LoadYAML, Roundtrip, ToJSON, ToYAML tests
+ *   - Per-coercion: From<Title> tests for scalar-to-object expansion
+ */
+// ============================================================================
+// Helpers
+// ============================================================================
+/** Nunjucks `capitalize` filter: upper-case first char, lower-case rest. */
+function capitalize(s) {
+    if (!s)
+        return s;
+    return s.charAt(0).toUpperCase() + s.slice(1).toLowerCase();
+}
+/**
+ * Emit a validation assertion for a property.
+ *
+ * @param varName  - "instance" or "reloaded"
+ * @param v        - property validation descriptor
+ */
+function emitValidation(lines, varName, v) {
+    // Determine the display value for the error message — includes quotes if delimiter is "
+    const displayQuote = v.delimiter === '"' ? '"' : '';
+    const display = `${displayQuote}${v.value}${displayQuote}`;
+    if (v.isOptional) {
+        lines.push(`if ${varName}.${v.key} == nil || *${varName}.${v.key} != ${v.delimiter}${v.value}${v.delimiter} {`);
+        lines.push(`t.Errorf(\`Expected ${v.key} to be ${display}, got %v\`, ${varName}.${v.key})`);
+        lines.push(`}`);
+    }
+    else {
+        lines.push(`if ${varName}.${v.key} != ${v.delimiter}${v.value}${v.delimiter} {`);
+        lines.push(`t.Errorf(\`Expected ${v.key} to be ${display}, got %v\`, ${varName}.${v.key})`);
+        lines.push(`}`);
+    }
+}
+// ============================================================================
+// Main entry point
+// ============================================================================
+/**
+ * Emit a complete Go test file for a single type.
+ *
+ * @param ctx - test context built by `buildBaseTestContext()`
+ * @returns Complete Go test source file as a string
+ */
+export function emitGoTest(ctx) {
+    const lines = [];
+    const typeName = ctx.node.typeName.name;
+    const pkg = ctx.package ?? "";
+    const isAbstract = ctx.isAbstract;
+    // File header (template lines 14-16)
+    lines.push("// Code generated by Typra emitter; DO NOT EDIT.");
+    lines.push("");
+    lines.push(`package ${pkg}_test`);
+    // Import block (template lines 17-26)
+    if (ctx.examples.length > 0 || ctx.coercions.length > 0) {
+        lines.push(""); // {% if true %}\n — blank line between package and import
+        lines.push(`import (`);
+        lines.push(`"encoding/json"`);
+        lines.push(`"testing"`);
+        lines.push(``);
+        lines.push(`"gopkg.in/yaml.v3"`);
+        lines.push(``);
+        lines.push(`"${ctx.importPath}"`);
+        lines.push(`)`);
+    }
+    lines.push(""); // {% endif %}\n (line 26)
+    lines.push(""); // blank line 27
+    // Per-example test functions (template lines 28-234)
+    for (let i = 0; i < ctx.examples.length; i++) {
+        const sample = ctx.examples[i];
+        const isFirst = i === 0;
+        const suffix = isFirst ? "" : String(i);
+        lines.push(""); // {% for %}\n — loop body starts with \n
+        emitLoadJSONTest(lines, typeName, pkg, suffix, sample, isAbstract);
+        lines.push("");
+        emitLoadYAMLTest(lines, typeName, pkg, suffix, sample, isAbstract);
+        lines.push("");
+        emitRoundtripTest(lines, typeName, pkg, suffix, sample, isAbstract);
+        lines.push("");
+        emitToJSONTest(lines, typeName, pkg, suffix, sample, isAbstract);
+        lines.push("");
+        emitToYAMLTest(lines, typeName, pkg, suffix, sample, isAbstract);
+        lines.push(""); // blank line 233
+    }
+    lines.push(""); // {% endfor %}\n (line 234)
+    // Coercion test functions (template lines 235-271)
+    if (ctx.coercions.length > 0) {
+        lines.push(""); // {% if true %}\n — if body starts with \n
+        for (let i = 0; i < ctx.coercions.length; i++) {
+            const alt = ctx.coercions[i];
+            const isFirst = i === 0;
+            const suffix = isFirst ? "" : String(i + 1);
+            lines.push(""); // {% for %}\n — loop body starts with \n
+            emitCoercionTest(lines, typeName, pkg, suffix, alt, isAbstract);
+            lines.push(""); // blank line 269
+        }
+        lines.push(""); // {% endfor %}\n (line 270)
+        lines.push(""); // {% endif %}\n (line 271)
+    }
+    else {
+        lines.push(""); // {% if false %}...{% endif %}\n — 1 \n
+    }
+    return lines.join("\n") + "\n";
+}
+// ============================================================================
+// Per-example test emitters
+// ============================================================================
+function emitJsonDataBlock(lines, sample) {
+    lines.push("jsonData := `");
+    for (const line of sample.json) {
+        lines.push(line);
+    }
+    lines.push("`");
+}
+function emitYamlDataBlock(lines, sample) {
+    lines.push("yamlData := `");
+    for (const line of sample.yaml) {
+        lines.push(line);
+    }
+    lines.push("`");
+}
+function emitJsonUnmarshal(lines, varName = "data") {
+    lines.push(`var ${varName} map[string]interface{}`);
+    lines.push(`if err := json.Unmarshal([]byte(jsonData), &${varName}); err != nil {`);
+    lines.push(`t.Fatalf("Failed to parse JSON: %v", err)`);
+    lines.push(`}`);
+}
+function emitYamlUnmarshal(lines, varName = "data") {
+    lines.push(`var ${varName} map[string]interface{}`);
+    lines.push(`if err := yaml.Unmarshal([]byte(yamlData), &${varName}); err != nil {`);
+    lines.push(`t.Fatalf("Failed to parse YAML: %v", err)`);
+    lines.push(`}`);
+}
+function emitLoadCall(lines, typeName, pkg, ctxVar, dataVar, instanceVar) {
+    lines.push(`${ctxVar} := ${pkg}.NewLoadContext()`);
+    lines.push(`${instanceVar}, err := ${pkg}.Load${typeName}(${dataVar}, ${ctxVar})`);
+    lines.push(`if err != nil {`);
+    lines.push(`t.Fatalf("Failed to load ${typeName}: %v", err)`);
+    lines.push(`}`);
+}
+function emitAbstractExampleValidations(lines, hasValidations) {
+    lines.push("// Polymorphic types return interface{}, extract common fields via reflection or type-specific access");
+    lines.push("_ = instance // Load succeeded, exact type depends on discriminator");
+    if (hasValidations) {
+        lines.push("// Note: Validation skipped for polymorphic base types - test child types directly");
+    }
+}
+function emitConcreteExampleValidations(lines, varName, validations) {
+    if (validations.length > 0) {
+        for (const v of validations) {
+            emitValidation(lines, varName, v);
+        }
+    }
+    else {
+        lines.push(`_ = ${varName} // No scalar properties to validate`);
+    }
+}
+// ---- LoadJSON ----
+function emitLoadJSONTest(lines, typeName, pkg, suffix, sample, isAbstract) {
+    lines.push(`// Test${typeName}LoadJSON${suffix} tests loading ${typeName} from JSON`);
+    lines.push(`func Test${typeName}LoadJSON${suffix}(t *testing.T) {`);
+    emitJsonDataBlock(lines, sample);
+    emitJsonUnmarshal(lines);
+    lines.push("");
+    emitLoadCall(lines, typeName, pkg, "ctx", "data", "instance");
+    if (isAbstract) {
+        emitAbstractExampleValidations(lines, sample.validations.length > 0);
+    }
+    else {
+        emitConcreteExampleValidations(lines, "instance", sample.validations);
+    }
+    lines.push("}");
+}
+// ---- LoadYAML ----
+function emitLoadYAMLTest(lines, typeName, pkg, suffix, sample, isAbstract) {
+    lines.push(`// Test${typeName}LoadYAML${suffix} tests loading ${typeName} from YAML`);
+    lines.push(`func Test${typeName}LoadYAML${suffix}(t *testing.T) {`);
+    emitYamlDataBlock(lines, sample);
+    emitYamlUnmarshal(lines);
+    lines.push("");
+    emitLoadCall(lines, typeName, pkg, "ctx", "data", "instance");
+    if (isAbstract) {
+        emitAbstractExampleValidations(lines, sample.validations.length > 0);
+    }
+    else {
+        emitConcreteExampleValidations(lines, "instance", sample.validations);
+    }
+    lines.push("}");
+}
+// ---- Roundtrip ----
+function emitRoundtripTest(lines, typeName, pkg, suffix, sample, isAbstract) {
+    lines.push(`// Test${typeName}Roundtrip${suffix} tests load -> save -> load produces equivalent data`);
+    lines.push(`func Test${typeName}Roundtrip${suffix}(t *testing.T) {`);
+    emitJsonDataBlock(lines, sample);
+    emitJsonUnmarshal(lines);
+    lines.push("");
+    lines.push(`loadCtx := ${pkg}.NewLoadContext()`);
+    lines.push(`instance, err := ${pkg}.Load${typeName}(data, loadCtx)`);
+    lines.push(`if err != nil {`);
+    lines.push(`t.Fatalf("Failed to load ${typeName}: %v", err)`);
+    lines.push(`}`);
+    if (isAbstract) {
+        lines.push("// Polymorphic roundtrip testing requires type-specific handling");
+        lines.push("_ = instance // Load succeeded, exact type depends on discriminator");
+        lines.push("// Note: Roundtrip test skipped for polymorphic base types - test child types directly");
+    }
+    else {
+        lines.push(`saveCtx := ${pkg}.NewSaveContext()`);
+        lines.push(`savedData := instance.Save(saveCtx)`);
+        lines.push("");
+        lines.push(`reloaded, err := ${pkg}.Load${typeName}(savedData, loadCtx)`);
+        lines.push(`if err != nil {`);
+        lines.push(`t.Fatalf("Failed to reload ${typeName}: %v", err)`);
+        lines.push(`}`);
+        emitConcreteExampleValidations(lines, "reloaded", sample.validations);
+    }
+    lines.push("}");
+}
+// ---- ToJSON ----
+function emitToJSONTest(lines, typeName, pkg, suffix, sample, isAbstract) {
+    lines.push(`// Test${typeName}ToJSON${suffix} tests that ToJSON produces valid JSON`);
+    lines.push(`func Test${typeName}ToJSON${suffix}(t *testing.T) {`);
+    emitJsonDataBlock(lines, sample);
+    emitJsonUnmarshal(lines);
+    lines.push("");
+    emitLoadCall(lines, typeName, pkg, "ctx", "data", "instance");
+    if (isAbstract) {
+        lines.push("// Polymorphic ToJSON requires type-specific handling");
+        lines.push("_ = instance // Load succeeded, exact type depends on discriminator");
+        lines.push("// Note: ToJSON test skipped for polymorphic base types - test child types directly");
+    }
+    else {
+        lines.push("jsonOutput, err := instance.ToJSON()");
+        lines.push("if err != nil {");
+        lines.push(`t.Fatalf("Failed to convert to JSON: %v", err)`);
+        lines.push("}");
+        lines.push("");
+        lines.push("var parsed map[string]interface{}");
+        lines.push("if err := json.Unmarshal([]byte(jsonOutput), &parsed); err != nil {");
+        lines.push(`t.Fatalf("Failed to parse generated JSON: %v", err)`);
+        lines.push("}");
+    }
+    lines.push("}");
+}
+// ---- ToYAML ----
+function emitToYAMLTest(lines, typeName, pkg, suffix, sample, isAbstract) {
+    lines.push(`// Test${typeName}ToYAML${suffix} tests that ToYAML produces valid YAML`);
+    lines.push(`func Test${typeName}ToYAML${suffix}(t *testing.T) {`);
+    emitJsonDataBlock(lines, sample);
+    emitJsonUnmarshal(lines);
+    lines.push("");
+    emitLoadCall(lines, typeName, pkg, "ctx", "data", "instance");
+    if (isAbstract) {
+        lines.push("// Polymorphic ToYAML requires type-specific handling");
+        lines.push("_ = instance // Load succeeded, exact type depends on discriminator");
+        lines.push("// Note: ToYAML test skipped for polymorphic base types - test child types directly");
+    }
+    else {
+        lines.push("yamlOutput, err := instance.ToYAML()");
+        lines.push("if err != nil {");
+        lines.push(`t.Fatalf("Failed to convert to YAML: %v", err)`);
+        lines.push("}");
+        lines.push("");
+        lines.push("var parsed map[string]interface{}");
+        lines.push("if err := yaml.Unmarshal([]byte(yamlOutput), &parsed); err != nil {");
+        lines.push(`t.Fatalf("Failed to parse generated YAML: %v", err)`);
+        lines.push("}");
+    }
+    lines.push("}");
+}
+// ============================================================================
+// Coercion test emitter
+// ============================================================================
+function emitCoercionTest(lines, typeName, pkg, suffix, alt, isAbstract) {
+    const title = capitalize(alt.title);
+    lines.push(`// Test${typeName}From${title}${suffix} tests loading ${typeName} from ${alt.scalarType}`);
+    lines.push(`func Test${typeName}From${title}${suffix}(t *testing.T) {`);
+    lines.push(`ctx := ${pkg}.NewLoadContext()`);
+    lines.push(`instance, err := ${pkg}.Load${typeName}(${alt.value}, ctx)`);
+    lines.push(`if err != nil {`);
+    lines.push(`t.Fatalf("Failed to load ${typeName} from ${alt.scalarType}: %v", err)`);
+    lines.push(`}`);
+    if (isAbstract) {
+        lines.push("// Polymorphic alternate loading requires type-specific handling");
+        lines.push("_ = instance // Load succeeded, exact type depends on discriminator");
+        if (alt.validations.length > 0) {
+            lines.push("// Note: Validation skipped for polymorphic base types - test child types directly");
+        }
+    }
+    else {
+        emitConcreteExampleValidations(lines, "instance", alt.validations);
+    }
+    lines.push("}");
+}
+//# sourceMappingURL=test-emitter.js.map

package/dist/src/languages/go/visitor.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Go expression visitor — Expr IR → Go source fragments.
+ */
+import { Expr, TypeRegistry } from "../../ir/expansion.js";
+import { ExprVisitor } from "../../ir/visitor.js";
+export declare class GoExprVisitor implements ExprVisitor {
+    registry?: TypeRegistry;
+    constructor(registry?: TypeRegistry);
+    visitExpr(expr: Expr): string;
+    private visitConstruct;
+    private visitVariant;
+    private visitArray;
+    private escapeString;
+}

package/dist/src/languages/go/visitor.js

@@ -0,0 +1,78 @@
+/**
+ * Go expression visitor — Expr IR → Go source fragments.
+ */
+import { toPascalCase, assertNever } from "../../ir/visitor.js";
+export class GoExprVisitor {
+    registry;
+    constructor(registry) {
+        this.registry = registry;
+    }
+    visitExpr(expr) {
+        switch (expr.kind) {
+            case "string":
+                return `"${this.escapeString(expr.value)}"`;
+            case "number":
+                return String(expr.value);
+            case "boolean":
+                return expr.value ? "true" : "false";
+            case "null":
+                return "nil";
+            case "param":
+                return expr.name;
+            case "construct":
+                return this.visitConstruct(expr);
+            case "variant":
+                return this.visitVariant(expr);
+            case "array":
+                return this.visitArray(expr);
+            case "dict":
+                return `map[string]interface{}{${expr.entries.map(e => `"${e.key}": ${this.visitExpr(e.value)}`).join(", ")}}`;
+            case "field_read":
+                return `${expr.objectName}.${toPascalCase(expr.fieldName)}`;
+            default:
+                return assertNever(expr);
+        }
+    }
+    visitConstruct(expr) {
+        const typeName = expr.typeName.name;
+        if (expr.fields.length === 0) {
+            return `${typeName}{}`;
+        }
+        // Look up the target type to check which fields are optional (pointer types in Go)
+        const typeNode = this.registry?.get(typeName);
+        const fields = expr.fields.map(f => {
+            const val = this.visitExpr(f.value);
+            const prop = typeNode?.properties.find(p => p.name === f.propertyName);
+            // Optional fields are pointers in Go — wrap scalar values with a helper
+            const needsAddr = prop?.isOptional && !prop.isCollection && !prop.isDict;
+            return `${toPascalCase(f.propertyName)}: ${needsAddr ? `ptrOf(${val})` : val}`;
+        }).join(", ");
+        return `${typeName}{ ${fields} }`;
+    }
+    visitVariant(expr) {
+        // Go child types are full structs with an explicit discriminator field.
+        const variantName = expr.variantTypeName.name;
+        // Include the discriminator (e.g., Kind: "text") since Go has no default field values.
+        const discField = `${toPascalCase(expr.discriminator)}: "${expr.discriminatorValue}"`;
+        const dataFields = expr.fields.map(f => `${toPascalCase(f.propertyName)}: ${this.visitExpr(f.value)}`);
+        const allFields = [discField, ...dataFields].join(", ");
+        return `${variantName}{ ${allFields} }`;
+    }
+    visitArray(expr) {
+        const elementType = expr.elementTypeName.name;
+        // Polymorphic types are stored as []interface{} in Go (no inheritance).
+        // A type is polymorphic if it has child types in the registry.
+        const typeNode = this.registry?.get(elementType);
+        const isPolymorphic = typeNode !== undefined && typeNode.childTypes.length > 0;
+        const goElementType = isPolymorphic ? "interface{}" : elementType;
+        if (expr.items.length === 0) {
+            return `[]${goElementType}{}`;
+        }
+        const items = expr.items.map(i => this.visitExpr(i)).join(", ");
+        return `[]${goElementType}{${items}}`;
+    }
+    escapeString(s) {
+        return s.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+    }
+}
+//# sourceMappingURL=visitor.js.map

package/dist/src/languages/markdown/driver.d.ts

@@ -0,0 +1,19 @@
+import { EmitContext } from "@typespec/compiler";
+import { EmitTarget, TypraEmitterOptions } from "../../lib.js";
+import { PropertyNode, TypeNode } from "../../ir/ast.js";
+import { GeneratorOptions } from "../../emitter.js";
+export declare const generateMarkdown: (context: EmitContext<TypraEmitterOptions>, node: TypeNode, emitTarget: EmitTarget, options?: GeneratorOptions) => Promise<void>;
+export declare const renderType: (prop: PropertyNode) => string;
+export declare const renderChildTypes: (node: PropertyNode) => string;
+export declare const getChildTypes: (node: TypeNode) => {
+    source: string;
+    target: string;
+}[];
+export declare const getCompositionTypes: (node: TypeNode) => TypeNode[];
+export declare const generateCoercions: (node: TypeNode) => {
+    title: string;
+    description: string;
+    scalar: string;
+    simple: string;
+    expanded: string;
+}[];