@typra/emitter 0.2.3 → 0.2.5

package/dist/src/cleanup/generated-file.d.ts

@@ -2,5 +2,6 @@ import { EmitContext } from "@typespec/compiler";
 import { TypraEmitterOptions } from "../lib.js";
 export declare function emitGeneratedFile(context: EmitContext<TypraEmitterOptions>, filePath: string, content: string, options?: {
     marker?: boolean;
+    outputRoot?: string;
 }): Promise<void>;
 export declare function emitGeneratedManifest(context: EmitContext<TypraEmitterOptions>): Promise<void>;

package/dist/src/cleanup/generated-file.js

@@ -4,7 +4,7 @@ const generatedFilesByProgram = new WeakMap();
 export async function emitGeneratedFile(context, filePath, content, options = {}) {
     const marker = options.marker ?? shouldMark(filePath);
     const finalContent = marker ? addMarker(filePath, content) : content;
-    recordGeneratedFile(context.program, filePath, marker);
+    recordGeneratedFile(context.program, filePath, marker, options.outputRoot);
     await emitFile(context.program, {
         path: filePath,
         content: finalContent,
@@ -24,13 +24,14 @@ export async function emitGeneratedManifest(context) {
         content: JSON.stringify(manifest, null, 2),
     });
 }
-function recordGeneratedFile(program, filePath, marker) {
+function recordGeneratedFile(program, filePath, marker, outputRoot) {
     let entries = generatedFilesByProgram.get(program);
     if (!entries) {
         entries = new Map();
         generatedFilesByProgram.set(program, entries);
     }
     entries.set(normalizePath(filePath), {
+        outputRoot: normalizePath(outputRoot || dirname(filePath)),
         path: normalizePath(filePath),
         marker,
     });
@@ -52,10 +53,6 @@ function markerFor(filePath) {
     return "// <auto-generated by typra-emitter>";
 }
 function normalizePath(filePath) {
-    const absolute = resolve(filePath);
-    const base = dirname(absolute);
-    return relative(base, absolute).startsWith("..")
-        ? absolute.replace(/\\/g, "/")
-        : filePath.replace(/\\/g, "/");
+    return relative(process.cwd(), resolve(filePath)).replace(/\\/g, "/");
 }
 //# sourceMappingURL=generated-file.js.map

package/dist/src/contract-surface.d.ts

@@ -0,0 +1,50 @@
+import { EmitContext } from "@typespec/compiler";
+import { EmitTarget, TypraEmitterOptions } from "./lib.js";
+import { TypeNode } from "./ir/ast.js";
+export interface ExportSurfaceMethod {
+    name: string;
+    returns: string;
+    params: Record<string, string>;
+    optional: boolean;
+    sync: boolean;
+}
+export interface ExportSurfaceProtocol {
+    name: string;
+    group: string;
+    methods: ExportSurfaceMethod[];
+}
+export interface ExportSurfaceEntry {
+    name: string;
+    kind: "type" | "value";
+    group: string;
+    source: string;
+    protocol: boolean;
+}
+export interface ExportSurfaceGroup {
+    name: string;
+    exports: string[];
+    modules: string[];
+}
+export interface TargetExportSurface {
+    target: string;
+    outputRoot: string;
+    packageName?: string;
+    namespace?: string;
+    rootExports: string[];
+    exports: ExportSurfaceEntry[];
+    groups: ExportSurfaceGroup[];
+    protocols: ExportSurfaceProtocol[];
+    modules: string[];
+}
+export interface ExportSurfaceSnapshot {
+    emitter: "typra-emitter";
+    version: 1;
+    root: {
+        object: string;
+        namespace: string;
+        alias: string;
+    };
+    targets: TargetExportSurface[];
+}
+export declare function buildExportSurfaceSnapshot(rootObject: string, rootNamespace: string, rootAlias: string, targets: EmitTarget[], nodes: TypeNode[]): ExportSurfaceSnapshot;
+export declare function emitExportSurfaceSnapshot(context: EmitContext<TypraEmitterOptions>, snapshot: ExportSurfaceSnapshot): Promise<void>;

package/dist/src/contract-surface.js

@@ -0,0 +1,176 @@
+import { emitFile, resolvePath } from "@typespec/compiler";
+import { toKebabCase, toSnakeCase } from "./ir/utilities.js";
+export function buildExportSurfaceSnapshot(rootObject, rootNamespace, rootAlias, targets, nodes) {
+    return {
+        emitter: "typra-emitter",
+        version: 1,
+        root: {
+            object: rootObject,
+            namespace: rootNamespace,
+            alias: rootAlias,
+        },
+        targets: targets
+            .map((target) => buildTargetSurface(rootNamespace, target, nodes))
+            .sort((left, right) => left.target.localeCompare(right.target)),
+    };
+}
+export async function emitExportSurfaceSnapshot(context, snapshot) {
+    await emitFile(context.program, {
+        path: resolvePath(context.emitterOutputDir, ".typra-generated", "export-surfaces.json"),
+        content: `${JSON.stringify(snapshot, null, 2)}\n`,
+    });
+}
+function buildTargetSurface(rootNamespace, target, nodes) {
+    const targetName = normalizeTarget(target.type);
+    const baseTypes = nodes.filter((node) => !node.base).sort(compareNodes);
+    const groups = buildGroups(targetName, baseTypes);
+    const exports = buildExports(targetName, baseTypes);
+    const rootExports = uniqueSorted(exports.map((entry) => entry.name));
+    const protocols = nodes
+        .filter((node) => node.isProtocol)
+        .sort(compareNodes)
+        .map((node) => ({
+        name: node.typeName.name,
+        group: node.group || "",
+        methods: node.methods
+            .map((method) => ({
+            name: method.name,
+            returns: method.returns,
+            params: sortRecord(method.params),
+            optional: method.optional,
+            sync: method.sync,
+        }))
+            .sort((left, right) => left.name.localeCompare(right.name)),
+    }));
+    return {
+        target: targetName,
+        outputRoot: target["output-dir"] || targetName,
+        ...targetMetadata(rootNamespace, targetName, target),
+        rootExports,
+        exports,
+        groups,
+        protocols,
+        modules: buildModules(targetName, baseTypes),
+    };
+}
+function buildExports(targetName, baseTypes) {
+    return baseTypes
+        .flatMap((node) => {
+        const group = node.group || "";
+        const source = sourceFor(targetName, node, group);
+        const kind = node.isProtocol ? "type" : "value";
+        return [node, ...node.childTypes].map((exportedNode) => ({
+            name: exportedNode.typeName.name,
+            kind,
+            group,
+            source,
+            protocol: node.isProtocol,
+        }));
+    })
+        .sort((left, right) => {
+        const byGroup = left.group.localeCompare(right.group);
+        if (byGroup !== 0)
+            return byGroup;
+        return left.name.localeCompare(right.name);
+    });
+}
+function buildGroups(targetName, baseTypes) {
+    const groupMap = new Map();
+    for (const node of baseTypes) {
+        const group = node.group || "";
+        if (!group)
+            continue;
+        if (!groupMap.has(group))
+            groupMap.set(group, []);
+        groupMap.get(group).push(node);
+    }
+    return Array.from(groupMap.entries())
+        .map(([name, groupNodes]) => ({
+        name,
+        exports: uniqueSorted(groupNodes.flatMap((node) => [node.typeName.name, ...node.childTypes.map((child) => child.typeName.name)])),
+        modules: uniqueSorted(groupNodes.map((node) => groupModuleName(targetName, node))),
+    }))
+        .sort((left, right) => left.name.localeCompare(right.name));
+}
+function buildModules(targetName, baseTypes) {
+    if (targetName === "rust") {
+        return uniqueSorted(["context", ...baseTypes.map((node) => node.group || moduleName(node))]);
+    }
+    return uniqueSorted(baseTypes.map((node) => sourceFor(targetName, node, node.group || "")));
+}
+function targetMetadata(rootNamespace, targetName, target) {
+    if (targetName === "go") {
+        return {
+            packageName: target["package-name"] || goPackageNameFromNamespace(rootNamespace),
+        };
+    }
+    if (targetName === "csharp") {
+        return {
+            namespace: target.namespace || rootNamespace,
+        };
+    }
+    if (targetName === "typescript") {
+        return {
+            namespace: target.namespace || rootNamespace.replace(/\.Core$/, ""),
+        };
+    }
+    if (targetName === "python") {
+        return {
+            packageName: rootNamespace.toLowerCase(),
+        };
+    }
+    return {};
+}
+function sourceFor(targetName, node, group) {
+    const name = node.typeName.name;
+    switch (targetName) {
+        case "typescript":
+            return group ? `./${group}/${toKebabCase(name)}` : `./${toKebabCase(name)}`;
+        case "python":
+            return group ? `.${group}` : `._${name}`;
+        case "rust":
+            return group ? `${group}::${toSnakeCase(name)}` : toSnakeCase(name);
+        case "go":
+            return `${toSnakeCase(name)}.go`;
+        case "csharp":
+            return group ? `${group}/${name}.cs` : `${name}.cs`;
+        default:
+            return name;
+    }
+}
+function moduleName(node) {
+    return toSnakeCase(node.typeName.name);
+}
+function groupModuleName(targetName, node) {
+    switch (targetName) {
+        case "typescript":
+            return toKebabCase(node.typeName.name);
+        case "python":
+            return `_${node.typeName.name}`;
+        case "csharp":
+            return `${node.typeName.name}.cs`;
+        default:
+            return moduleName(node);
+    }
+}
+function normalizeTarget(target) {
+    return target.toLowerCase().trim();
+}
+function goPackageNameFromNamespace(namespace) {
+    return namespace.toLowerCase().replace(/\./g, "");
+}
+function compareNodes(left, right) {
+    const leftGroup = left.group || "";
+    const rightGroup = right.group || "";
+    const byGroup = leftGroup.localeCompare(rightGroup);
+    if (byGroup !== 0)
+        return byGroup;
+    return left.typeName.name.localeCompare(right.typeName.name);
+}
+function uniqueSorted(values) {
+    return Array.from(new Set(values)).sort();
+}
+function sortRecord(record) {
+    return Object.fromEntries(Object.entries(record).sort(([left], [right]) => left.localeCompare(right)));
+}
+//# sourceMappingURL=contract-surface.js.map

package/dist/src/emitter.d.ts

@@ -10,4 +10,5 @@ export interface GeneratorOptions {
  * Matches against model name (e.g., "AgentManifest") or fully qualified name (e.g., "Prompty.AgentManifest")
  */
 export declare function filterNodes(nodes: TypeNode[], options?: GeneratorOptions): TypeNode[];
+export declare function inferRootNamespace(rootObject: string): string;
 export declare function $onEmit(context: EmitContext<TypraEmitterOptions>): Promise<void>;

package/dist/src/emitter.js

@@ -7,6 +7,7 @@ import { generateTypeScript } from "./languages/typescript/driver.js";
 import { generateGo } from "./languages/go/driver.js";
 import { generateRust } from "./languages/rust/driver.js";
 import { emitGeneratedFile, emitGeneratedManifest } from "./cleanup/generated-file.js";
+import { buildExportSurfaceSnapshot, emitExportSurfaceSnapshot } from "./contract-surface.js";
 /**
  * Filter nodes based on omit-models option.
  * Matches against model name (e.g., "AgentManifest") or fully qualified name (e.g., "Prompty.AgentManifest")
@@ -36,6 +37,28 @@ export function filterNodes(nodes, options) {
         return !omitModels.includes(name) && !omitModels.includes(fullName);
     });
 }
+export function inferRootNamespace(rootObject) {
+    const lastDot = rootObject.lastIndexOf(".");
+    return lastDot > 0 ? rootObject.slice(0, lastDot) : "Typra";
+}
+function inferRootAlias(rootNamespace) {
+    return rootNamespace.split(".").filter(Boolean).at(-1) || rootNamespace || "Typra";
+}
+function isUninstantiatedTemplate(model) {
+    return !!(model.node &&
+        "templateParameters" in model.node &&
+        model.node.templateParameters.length > 0 &&
+        !model.templateMapper);
+}
+function collectNamespaceModels(namespace, models = []) {
+    for (const [, model] of namespace.models) {
+        models.push(model);
+    }
+    for (const [, childNamespace] of namespace.namespaces) {
+        collectNamespaceModels(childNamespace, models);
+    }
+    return models;
+}
 // Registry of available code generators
 const generators = {
     markdown: generateMarkdown,
@@ -57,7 +80,9 @@ export async function $onEmit(context) {
     if (!m[0] || m[0].kind !== "Model") {
         throw new Error(`${rootObject} model not found or is not a model type.`);
     }
-    const model = resolveModel(context.program, m[0], new Set(), options["root-namespace"] || "Typra", options["root-alias"] || "Typra");
+    const rootNamespace = options["root-namespace"] || inferRootNamespace(rootObject);
+    const rootAlias = options["root-alias"] || inferRootAlias(rootNamespace);
+    const model = resolveModel(context.program, m[0], new Set(), rootNamespace, rootAlias);
     if (options["root-alias"]) {
         model.typeName = {
             namespace: model.typeName.namespace,
@@ -67,7 +92,6 @@ export async function $onEmit(context) {
     // Discover additional models not reachable from the root.
     // If root-namespace is specified, resolve all models in that namespace
     // so new types are automatically emitted without manual additional-roots.
-    const rootNamespace = options["root-namespace"] || "Typra";
     const additionalModels = [];
     const visited = new Set();
     // Collect names already in the main model tree to avoid duplicates
@@ -90,16 +114,15 @@ export async function $onEmit(context) {
     const nsRef = context.program.resolveTypeReference(rootNamespace);
     if (nsRef[0] && nsRef[0].kind === "Namespace") {
         const ns = nsRef[0];
-        for (const [, nsModel] of ns.models) {
+        for (const nsModel of collectNamespaceModels(ns)) {
             const fullName = `${rootNamespace}.${nsModel.name}`;
             if (visited.has(fullName))
                 continue;
             // Skip uninstantiated template declarations (e.g., Named<T>, Id<T>)
-            if (nsModel.node && 'templateParameters' in nsModel.node &&
-                nsModel.node.templateParameters.length > 0 && !nsModel.templateMapper) {
+            if (isUninstantiatedTemplate(nsModel)) {
                 continue;
             }
-            const additionalNode = resolveModel(context.program, nsModel, new Set(), rootNamespace, options["root-alias"] || "Typra");
+            const additionalNode = resolveModel(context.program, nsModel, new Set(), rootNamespace, rootAlias);
             additionalModels.push(additionalNode);
             visited.add(fullName);
         }
@@ -114,7 +137,7 @@ export async function $onEmit(context) {
             console.warn(`Warning: additional-root '${rootName}' not found or is not a model type. Skipping.`);
             continue;
         }
-        const additionalNode = resolveModel(context.program, ref[0], new Set(), rootNamespace, options["root-alias"] || "Typra");
+        const additionalNode = resolveModel(context.program, ref[0], new Set(), rootNamespace, rootAlias);
         additionalModels.push(additionalNode);
         visited.add(rootName);
     }
@@ -123,6 +146,10 @@ export async function $onEmit(context) {
         omitModels: options["omit-models"] || [],
         additionalModels: additionalModels,
     };
+    const exportSurfaceNodes = filterNodes(Array.from(enumerateTypes(model)), {
+        omitModels: generatorOptions.omitModels,
+        additionalModels: [...additionalModels],
+    });
     // Dispatch to registered generators
     for (const target of targets) {
         const generatorName = target.type.toLowerCase().trim();
@@ -132,6 +159,7 @@ export async function $onEmit(context) {
         }
     }
     await emitGeneratedFile(context, resolvePath(context.emitterOutputDir, "json-ast", "model.json"), JSON.stringify(model.getSanitizedObject(), null, 2), { marker: false });
+    await emitExportSurfaceSnapshot(context, buildExportSurfaceSnapshot(rootObject, rootNamespace, rootAlias, targets, exportSurfaceNodes));
     await emitGeneratedManifest(context);
 }
 //# sourceMappingURL=emitter.js.map

package/dist/src/ir/ast.js

@@ -34,7 +34,6 @@ const getModelType = (model, rootNamespace, rootAlias) => {
  * We use `any` because TypeSpec does not export `Node`, `SyntaxKind`,
  * or `TypeSpecScriptNode` from its public API surface.
  */
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
 function getNodeFilePath(node) {
     let current = node;
     while (current) {

package/dist/src/ir/lower.js

@@ -461,7 +461,21 @@ function resolveImports(rootNode, types, registry) {
  * Handles formats like "Prompty", "Message[]", "Record<unknown>", "string", "unknown".
  */
 function extractMethodTypeRefs(method) {
-    const SCALARS = new Set(["string", "int32", "float32", "float64", "boolean", "unknown"]);
+    const SCALARS = new Set([
+        "void",
+        "string",
+        "number",
+        "integer",
+        "int32",
+        "int64",
+        "float",
+        "float32",
+        "float64",
+        "numeric",
+        "boolean",
+        "unknown",
+        "any",
+    ]);
     const refs = [];
     const extract = (typeStr) => {
         // Strip nullable suffix and array suffix: "string?" → "string", "Message[]" → "Message"

package/dist/src/languages/csharp/driver.js

@@ -72,7 +72,7 @@ export const generateCsharp = async (context, node, emitTarget, options) => {
                 const csEnumName = field.enumName.charAt(0).toUpperCase() + field.enumName.slice(1);
                 const grp = enumGroup.get(field.enumName) || "";
                 const enumOutDir = grp ? `${emitTarget["output-dir"]}/${grp}` : emitTarget["output-dir"];
-                await emitCsharpFile(context, nodes[0], enumCode, `${csEnumName}.cs`, enumOutDir);
+                await emitCsharpFile(context, nodes[0], enumCode, `${csEnumName}.cs`, enumOutDir, emitTarget["output-dir"]);
             }
         }
     }
@@ -81,10 +81,10 @@ export const generateCsharp = async (context, node, emitTarget, options) => {
         const classCode = emitCSharpClass(typeDecl, csharpNamespace, visitor, allTypeDecls, findTypeDecl);
         // Emit into group subfolder (C# uses namespaces, no re-export files needed)
         const outDir = n.group ? `${emitTarget["output-dir"]}/${n.group}` : emitTarget["output-dir"];
-        await emitCsharpFile(context, n, classCode, `${n.typeName.name}.cs`, outDir);
+        await emitCsharpFile(context, n, classCode, `${n.typeName.name}.cs`, outDir, emitTarget["output-dir"]);
         if (emitTarget["test-dir"] && !n.isProtocol) {
             const testDir = n.group ? `${emitTarget["test-dir"]}/${n.group}` : emitTarget["test-dir"];
-            await emitCsharpFile(context, n, renderTests(n, csharpNamespace), `${n.typeName.name}ConversionTests.cs`, testDir);
+            await emitCsharpFile(context, n, renderTests(n, csharpNamespace), `${n.typeName.name}ConversionTests.cs`, testDir, emitTarget["test-dir"]);
         }
     }
     // Format emitted files if format option is enabled (default: true)
@@ -250,13 +250,13 @@ const renderCsharpFactoryTestValue = (typeStr) => {
         default: return '"test"';
     }
 };
-const emitCsharpFile = async (context, type, python, filename, outputDir) => {
+const emitCsharpFile = async (context, type, python, filename, outputDir, outputRoot) => {
     outputDir = outputDir || `${context.emitterOutputDir}/CSharp`;
     const typePath = type.typeName.namespace.split(".");
     // replace typename with file
     typePath.push(filename);
     const path = resolvePath(outputDir, filename);
-    await emitGeneratedFile(context, path, python);
+    await emitGeneratedFile(context, path, python, { outputRoot: outputRoot || outputDir });
 };
 /**
  * Format C# files using dotnet format.

package/dist/src/languages/csharp/emitter.js

@@ -136,6 +136,8 @@ function protocolCSharpType(typeStr) {
         return "Dictionary<string, object?>";
     if (typeStr === "unknown" || typeStr === "any")
         return "object";
+    if (typeStr === "void")
+        return "void";
     // Handle nullable types (e.g., "string?")
     if (typeStr.endsWith("?")) {
         const inner = typeStr.slice(0, -1);
@@ -173,7 +175,9 @@ function emitCSharpInterface(type, namespace, lines) {
             // Synchronous method
             if (method.optional) {
                 // Return type already includes nullability — provide default body
-                lines.push(`        ${ret} ${toPascalCase(method.name)}(${params}) => default!;`);
+                lines.push(ret === "void"
+                    ? `        void ${toPascalCase(method.name)}(${params}) { }`
+                    : `        ${ret} ${toPascalCase(method.name)}(${params}) => default!;`);
             }
             else {
                 lines.push(`        ${ret} ${toPascalCase(method.name)}(${params});`);
@@ -182,10 +186,17 @@ function emitCSharpInterface(type, namespace, lines) {
         else {
             // Async method
             if (method.optional) {
-                lines.push(`        Task<${ret}> ${toPascalCase(method.name)}Async(${params}) => Task.FromResult<${ret}>(default!);`);
+                if (ret === "void") {
+                    lines.push(`        Task ${toPascalCase(method.name)}Async(${params}) => Task.CompletedTask;`);
+                }
+                else {
+                    lines.push(`        Task<${ret}> ${toPascalCase(method.name)}Async(${params}) => Task.FromResult<${ret}>(default!);`);
+                }
             }
             else {
-                lines.push(`        Task<${ret}> ${toPascalCase(method.name)}Async(${params});`);
+                lines.push(ret === "void"
+                    ? `        Task ${toPascalCase(method.name)}Async(${params});`
+                    : `        Task<${ret}> ${toPascalCase(method.name)}Async(${params});`);
             }
         }
     }

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

@@ -10,3 +10,4 @@ export declare const goTypeMapper: Record<string, string>;
  * Main entry point for Go code generation.
  */
 export declare const generateGo: (context: EmitContext<TypraEmitterOptions>, node: TypeNode, emitTarget: EmitTarget, options?: GeneratorOptions) => Promise<void>;
+export declare function goPackageNameFromNamespace(namespace: string): string;

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

@@ -40,8 +40,7 @@ export const generateGo = async (context, node, emitTarget, options) => {
     // Build the expression IR infrastructure
     const registry = TypeRegistry.fromTypeGraph(allTypes);
     const visitor = new GoExprVisitor(registry);
-    // Determine package name from root node namespace (e.g., "Typra" -> "typra")
-    const packageName = node.typeName.namespace.toLowerCase().replace(/\./g, '');
+    const packageName = emitTarget["package-name"] || goPackageNameFromNamespace(node.typeName.namespace);
     // Collect all polymorphic type names across all nodes
     const polymorphicTypeNames = new Set();
     for (const n of nodes) {
@@ -61,7 +60,7 @@ export const generateGo = async (context, node, emitTarget, options) => {
             // Go stays flat: pass group as a header comment only, no subfolder emission
             const fileContent = emitGoFileContent(fileDecl.types, packageName, visitor, polymorphicTypeNames, fileDecl.enums, n.group || "");
             const fileName = toSnakeCase(n.typeName.name) + '.go';
-            await emitGoFile(context, fileName, fileContent, emitTarget["output-dir"]);
+            await emitGoFile(context, fileName, fileContent, emitTarget["output-dir"], emitTarget["output-dir"]);
         }
         // Emit test file for each type (skip protocols — they have no data to test)
         if (emitTarget["test-dir"] && !n.isProtocol) {
@@ -69,7 +68,7 @@ export const generateGo = async (context, node, emitTarget, options) => {
             const testContext = { ...buildTestContext(n, packageName), importPath };
             const testContent = emitGoTest(testContext);
             const testFileName = toSnakeCase(n.typeName.name) + '_test.go';
-            await emitGoFile(context, testFileName, testContent, emitTarget["test-dir"]);
+            await emitGoFile(context, testFileName, testContent, emitTarget["test-dir"], emitTarget["test-dir"]);
         }
     }
     // Format emitted files if format option is enabled (default: true)
@@ -117,12 +116,15 @@ function formatGoFiles(outputDir, testDir) {
 function buildTestContext(node, packageName) {
     return buildBaseTestContext(node, packageName, goTestOptions);
 }
+export function goPackageNameFromNamespace(namespace) {
+    return namespace.toLowerCase().replace(/\./g, "");
+}
 /**
  * Write generated Go content to file.
  */
-async function emitGoFile(context, filename, content, outputDir) {
+async function emitGoFile(context, filename, content, outputDir, outputRoot) {
     outputDir = outputDir || `${context.emitterOutputDir}/go`;
     const filePath = resolvePath(outputDir, filename);
-    await emitGeneratedFile(context, filePath, content);
+    await emitGeneratedFile(context, filePath, content, { outputRoot: outputRoot || outputDir });
 }
 //# sourceMappingURL=driver.js.map

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

@@ -814,12 +814,15 @@ function emitMethodStubs(typeName, methods, lines) {
         if (method.description) {
             lines.push(`\t// ${toPascalCase(method.name)} — ${method.description}`);
         }
-        lines.push(`\t${toPascalCase(method.name)}() ${goMethodReturnType(method.returns)}`);
+        const ret = goMethodReturnType(method.returns);
+        lines.push(`\t${toPascalCase(method.name)}()${ret ? ` ${ret}` : ""}`);
     }
     lines.push("}");
     lines.push("");
 }
 function goMethodReturnType(returns) {
+    if (returns === "void")
+        return "";
     return GO_TYPE_MAP[returns] || returns;
 }
 // ============================================================================
@@ -841,8 +844,20 @@ function protocolGoType(typeStr) {
         return "map[string]interface{}";
     if (typeStr === "unknown" || typeStr === "any")
         return "interface{}";
+    if (typeStr === "void")
+        return "";
     return GO_TYPE_MAP[typeStr] || typeStr;
 }
+function goProtocolReturn(method) {
+    const ret = protocolGoType(method.returns);
+    if (method.sync && method.optional) {
+        return ret ? ` ${ret}` : "";
+    }
+    if (method.sync) {
+        return ret ? ` (${ret}, error)` : " error";
+    }
+    return ret ? ` (${ret}, error)` : " error";
+}
 /**
  * Emit a Go interface for a protocol type.
  */
@@ -859,19 +874,7 @@ function emitProtocolInterface(type, lines) {
         const params = Object.entries(method.params)
             .map(([pName, pType]) => `${pName} ${protocolGoType(pType)}`)
             .join(", ");
-        const ret = protocolGoType(method.returns);
-        if (method.sync) {
-            // Sync method — return type without error for optional
-            if (method.optional) {
-                lines.push(`\t${toPascalCase(method.name)}(${params}) ${ret}`);
-            }
-            else {
-                lines.push(`\t${toPascalCase(method.name)}(${params}) (${ret}, error)`);
-            }
-        }
-        else {
-            lines.push(`\t${toPascalCase(method.name)}(${params}) (${ret}, error)`);
-        }
+        lines.push(`\t${toPascalCase(method.name)}(${params})${goProtocolReturn(method)}`);
     }
     lines.push("}");
     lines.push("");

package/dist/src/languages/markdown/driver.js

@@ -403,6 +403,6 @@ export const generateCoercions = (node) => {
 };
 const emitMarkdownFile = async (context, name, markdown, outputDir) => {
     const dir = outputDir || `${context.emitterOutputDir}/markdown`;
-    await emitGeneratedFile(context, resolvePath(dir, `${name}.md`), markdown);
+    await emitGeneratedFile(context, resolvePath(dir, `${name}.md`), markdown, { outputRoot: dir });
 };
 //# sourceMappingURL=driver.js.map

package/dist/src/languages/python/driver.js

@@ -100,14 +100,14 @@ export const generatePython = async (context, node, emitTarget, options) => {
             const fileDecl = lowerFile(n, registry, polymorphicTypeNames);
             const fileContent = emitPythonFileDecl(fileDecl, visitor, group);
             const outDir = group ? `${emitTarget["output-dir"]}/${group}` : emitTarget["output-dir"];
-            await emitPythonFile(context, `_${n.typeName.name}.py`, fileContent, outDir);
+            await emitPythonFile(context, `_${n.typeName.name}.py`, fileContent, outDir, emitTarget["output-dir"]);
         }
         // Render test file for each type (skip protocols — they have no data to test)
         if (emitTarget["test-dir"] && !n.isProtocol) {
             const testDir = n.group ? `${emitTarget["test-dir"]}/${n.group}` : emitTarget["test-dir"];
             const testContext = buildTestContext(n, importPath);
             const testContent = emitPythonTest(testContext);
-            await emitPythonFile(context, `test_${toSnakeCase(n.typeName.name)}.py`, testContent, testDir);
+            await emitPythonFile(context, `test_${toSnakeCase(n.typeName.name)}.py`, testContent, testDir, emitTarget["test-dir"]);
         }
     }
     // Emit group-level __init__.py for each group
@@ -115,7 +115,7 @@ export const generatePython = async (context, node, emitTarget, options) => {
         if (!group)
             continue; // Root-level types (if any) are covered by the root __init__.py
         const groupInitContent = emitPythonGroupInit(group, groupNodes);
-        await emitPythonFile(context, '__init__.py', groupInitContent, `${emitTarget["output-dir"]}/${group}`);
+        await emitPythonFile(context, '__init__.py', groupInitContent, `${emitTarget["output-dir"]}/${group}`, emitTarget["output-dir"]);
     }
     // Format emitted files if format option is enabled (default: true)
     if (emitTarget.format !== false) {
@@ -364,9 +364,9 @@ function getUniqueImportTypes(node) {
 /**
  * Write generated Python content to file using TypeSpec's emitFile API.
  */
-async function emitPythonFile(context, filename, content, outputDir) {
+async function emitPythonFile(context, filename, content, outputDir, outputRoot) {
     outputDir = outputDir || `${context.emitterOutputDir}/python`;
     const filePath = resolvePath(outputDir, filename);
-    await emitGeneratedFile(context, filePath, content);
+    await emitGeneratedFile(context, filePath, content, { outputRoot: outputRoot || outputDir });
 }
 //# sourceMappingURL=driver.js.map

package/dist/src/languages/python/emitter.js

@@ -309,6 +309,8 @@ function protocolType(typeStr) {
         return "dict[str, Any]";
     if (typeStr === "unknown" || typeStr === "any")
         return "Any";
+    if (typeStr === "void")
+        return "None";
     // Scalar types
     const mapped = TYPE_MAP[typeStr];
     if (mapped)

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

@@ -11,3 +11,14 @@ export declare const rustTypeMapper: Record<string, string>;
  * Main entry point for Rust code generation.
  */
 export declare const generateRust: (context: EmitContext<TypraEmitterOptions>, node: TypeNode, emitTarget: EmitTarget, options?: GeneratorOptions) => Promise<void>;
+/**
+ * Emit the root mod.rs file content (module declarations).
+ *
+ * @param rootModules - Module names emitted directly in the root (e.g. ["context"])
+ * @param groups - Group subfolder names (e.g. ["connection", "tools"])
+ */
+export declare function emitRustLib(rootModules: string[], groups?: string[]): string;
+/**
+ * Emit a per-group mod.rs file that declares and re-exports all modules in that group.
+ */
+export declare function emitRustGroupMod(moduleNames: string[]): string;

package/dist/src/languages/rust/driver.js

@@ -103,7 +103,7 @@ export const generateRust = async (context, node, emitTarget, options) => {
             const fileContent = emitRustFileDecl(fileDecl, visitor, polymorphicTypeNames, childToParent);
             const fileName = toSnakeCase(n.typeName.name) + '.rs';
             const outDir = group ? `${emitTarget["output-dir"]}/${group}` : emitTarget["output-dir"];
-            await emitRustFile(context, fileName, fileContent, outDir);
+            await emitRustFile(context, fileName, fileContent, outDir, emitTarget["output-dir"]);
             if (!groupModuleNames.has(group))
                 groupModuleNames.set(group, []);
             groupModuleNames.get(group).push(toSnakeCase(n.typeName.name));
@@ -121,7 +121,7 @@ export const generateRust = async (context, node, emitTarget, options) => {
             const testFileName = toSnakeCase(n.typeName.name) + '_test.rs';
             const testGroup = n.group || "";
             const testDir = testGroup ? `${emitTarget["test-dir"]}/${testGroup}` : emitTarget["test-dir"];
-            await emitRustFile(context, testFileName, testContent, testDir);
+            await emitRustFile(context, testFileName, testContent, testDir, emitTarget["test-dir"]);
             if (!testGroupModuleNames.has(testGroup))
                 testGroupModuleNames.set(testGroup, []);
             testGroupModuleNames.get(testGroup).push(toSnakeCase(n.typeName.name) + '_test');
@@ -132,7 +132,7 @@ export const generateRust = async (context, node, emitTarget, options) => {
         if (!group)
             continue; // Root-level types handled in root mod.rs
         const groupModContent = emitRustGroupMod(modules);
-        await emitRustFile(context, 'mod.rs', groupModContent, `${emitTarget["output-dir"]}/${group}`);
+        await emitRustFile(context, 'mod.rs', groupModContent, `${emitTarget["output-dir"]}/${group}`, emitTarget["output-dir"]);
     }
     // Render test group mod.rs files and test main.rs
     if (emitTarget["test-dir"]) {
@@ -142,7 +142,7 @@ export const generateRust = async (context, node, emitTarget, options) => {
             if (group) {
                 const groupModContent = '// Code generated by Typra emitter; DO NOT EDIT.\n\n#![allow(unused_imports, dead_code, non_camel_case_types, unused_variables, clippy::all)]\n\n'
                     + testMods.map(m => `mod ${m};`).join('\n') + '\n';
-                await emitRustFile(context, 'mod.rs', groupModContent, `${emitTarget["test-dir"]}/${group}`);
+                await emitRustFile(context, 'mod.rs', groupModContent, `${emitTarget["test-dir"]}/${group}`, emitTarget["test-dir"]);
                 testGroups.push(group);
             }
         }
@@ -209,10 +209,10 @@ function buildTestContext(node) {
 /**
  * Write generated Rust content to file.
  */
-async function emitRustFile(context, filename, content, outputDir) {
+async function emitRustFile(context, filename, content, outputDir, outputRoot) {
     outputDir = outputDir || `${context.emitterOutputDir}/rust`;
     const filePath = resolvePath(outputDir, filename);
-    await emitGeneratedFile(context, filePath, `${content.trimEnd()}\n`);
+    await emitGeneratedFile(context, filePath, `${content.trimEnd()}\n`, { outputRoot: outputRoot || outputDir });
 }
 /**
  * Emit the context.rs file content (LoadContext/SaveContext structs).
@@ -398,7 +398,7 @@ impl SaveContext {
  * @param rootModules - Module names emitted directly in the root (e.g. ["context"])
  * @param groups - Group subfolder names (e.g. ["connection", "tools"])
  */
-function emitRustLib(rootModules, groups = []) {
+export function emitRustLib(rootModules, groups = []) {
     let out = '// Code generated by Typra emitter; DO NOT EDIT.\n\n#![allow(unused_imports, dead_code, non_camel_case_types, unused_variables, clippy::all)]\n';
     for (const module of rootModules) {
         out += `\npub mod ${module};\npub use ${module}::*;\n`;
@@ -411,7 +411,7 @@ function emitRustLib(rootModules, groups = []) {
 /**
  * Emit a per-group mod.rs file that declares and re-exports all modules in that group.
  */
-function emitRustGroupMod(moduleNames) {
+export function emitRustGroupMod(moduleNames) {
     let out = '// Code generated by Typra emitter; DO NOT EDIT.\n\n#![allow(unused_imports, dead_code, non_camel_case_types, unused_variables, clippy::all)]\n';
     for (const module of moduleNames) {
         out += `\npub mod ${module};\npub use ${module}::*;\n`;

package/dist/src/languages/rust/emitter.js

@@ -990,14 +990,16 @@ function emitMethodTrait(type, lines) {
         if (method.description) {
             emitDocComment(method.description, "    ", lines);
         }
-        lines.push(`    fn ${toSnakeCase(method.name)}(&self) -> ${methodReturnType(method)};`);
+        const params = Object.entries(method.params)
+            .map(([pName, pType]) => `${toSnakeCase(pName)}: &${protocolRustType(pType)}`)
+            .join(", ");
+        const signatureParams = params ? `, ${params}` : "";
+        lines.push(`    fn ${toSnakeCase(method.name)}(&self${signatureParams}) -> ${methodReturnType(method)};`);
     }
     lines.push("}");
 }
 function methodReturnType(method) {
-    if (method.returns === "string")
-        return "String";
-    return RUST_TYPE_MAP[method.returns] || method.returns;
+    return protocolRustType(method.returns);
 }
 // ============================================================================
 // Protocol trait emission
@@ -1018,6 +1020,8 @@ function protocolRustType(typeStr) {
         return "serde_json::Value";
     if (typeStr === "unknown" || typeStr === "any")
         return "serde_json::Value";
+    if (typeStr === "void")
+        return "()";
     if (typeStr === "string")
         return "String";
     return RUST_TYPE_MAP[typeStr] || typeStr;
@@ -1046,7 +1050,7 @@ function emitProtocolTrait(type, lines) {
             if (method.optional) {
                 // Return type already includes nullability from ? suffix — don't double-wrap
                 lines.push(`    fn ${toSnakeCase(method.name)}(&self, ${params}) -> ${ret} {`);
-                lines.push("        None");
+                lines.push(ret === "()" ? "        ()" : "        None");
                 lines.push("    }");
             }
             else {

package/dist/src/languages/typescript/driver.js

@@ -66,14 +66,14 @@ export const generateTypeScript = async (context, node, emitTarget, options) =>
         const fileDecl = lowerFile(n, registry, polymorphicTypeNames);
         const code = emitTypeScriptFileDecl(fileDecl, visitor, tsNamespace, group);
         const outDir = group ? `${emitTarget["output-dir"]}/${group}` : emitTarget["output-dir"];
-        await emitTypeScriptFile(context, `${toKebabCase(n.typeName.name)}.ts`, code, outDir);
+        await emitTypeScriptFile(context, `${toKebabCase(n.typeName.name)}.ts`, code, outDir, emitTarget["output-dir"]);
     }
     // Emit group index.ts files
     for (const [group, groupNodes] of groupMap) {
         if (!group)
             continue;
         const groupIndexCode = emitTypeScriptGroupIndex(group, groupNodes);
-        await emitTypeScriptFile(context, "index.ts", groupIndexCode, `${emitTarget["output-dir"]}/${group}`);
+        await emitTypeScriptFile(context, "index.ts", groupIndexCode, `${emitTarget["output-dir"]}/${group}`, emitTarget["output-dir"]);
     }
     // Emit test files for all types (skip protocols — they have no data to test)
     if (emitTarget["test-dir"]) {
@@ -91,7 +91,7 @@ export const generateTypeScript = async (context, node, emitTarget, options) =>
                 importPath: testImportPath,
                 namespace: tsNamespace,
             });
-            await emitTypeScriptFile(context, `${toKebabCase(n.typeName.name)}.test.ts`, testCode, testDir);
+            await emitTypeScriptFile(context, `${toKebabCase(n.typeName.name)}.test.ts`, testCode, testDir, emitTarget["test-dir"]);
         }
     }
     // Emit root index.ts file — re-exports from group sub-indexes
@@ -201,9 +201,9 @@ function buildTestContext(node) {
 /**
  * Write generated TypeScript content to file.
  */
-async function emitTypeScriptFile(context, filename, content, outputDir) {
+async function emitTypeScriptFile(context, filename, content, outputDir, outputRoot) {
     outputDir = outputDir || `${context.emitterOutputDir}/typescript`;
     const filePath = resolvePath(outputDir, filename);
-    await emitGeneratedFile(context, filePath, content);
+    await emitGeneratedFile(context, filePath, content, { outputRoot: outputRoot || outputDir });
 }
 //# sourceMappingURL=driver.js.map

package/dist/src/languages/typescript/emitter.js

@@ -85,6 +85,8 @@ function returnType(typeStr) {
     }
     if (typeStr === "Record<unknown>")
         return "Record<string, unknown>";
+    if (typeStr === "void")
+        return "void";
     return TYPE_MAP[typeStr] || typeStr;
 }
 // ============================================================================

package/dist/src/lib.d.ts

@@ -8,6 +8,7 @@ export interface EmitTarget {
     "format"?: boolean;
     "namespace"?: string;
     "import-path"?: string;
+    "package-name"?: string;
 }
 export interface TypraEmitterOptions {
     "root-object": string;

package/dist/src/lib.js

@@ -39,6 +39,11 @@ const TypraEmitterOptionsSchema = {
                         type: "string",
                         nullable: true,
                         description: "Import path for generated code in tests. Defaults vary by language."
+                    },
+                    "package-name": {
+                        type: "string",
+                        nullable: true,
+                        description: "Language package/module name override. Currently used by Go; defaults to the emitted root namespace."
                     }
                 },
                 required: ["type"]

package/fixtures/shapes/main.tsp

@@ -1,29 +1,48 @@
 import "@typra/emitter";
+import "./model/events/session.tsp";
+import "./model/pipeline/harness.tsp";
 
 namespace Typra.Fixtures;
 
 model FixtureRoot {
+  @sample(#{ name: "fixture-root" })
   @doc("Required scalar field")
   name: string;
 
+  @sample(#{ description: "A generated fixture with broad emitter coverage." })
   @doc("Optional scalar field")
   description?: string;
 
+  @sample(#{ tags: #["typespec", "emitter", "validation"] })
   @doc("Array of scalar tags")
   tags: string[];
 
+  @sample(#{ metadata: #{ source: "fixture", version: 1 } })
   @doc("Dictionary-shaped metadata")
   metadata?: Record<unknown>;
 
+  @sample(#{ owner: #{ id: "owner-1", displayName: "Fixture Owner" } })
   @doc("Nested object field")
   owner: FixtureOwner;
 
+  @sample(#{ content: #{ kind: "text", text: "hello from a polymorphic sample" } })
   @doc("Discriminated union field")
   content: FixtureContent;
+
+  @sample(#{ status: "ready" })
+  @doc("Closed string union field")
+  status: FixtureStatus;
+
+  @sample(#{ mode: "batch" })
+  @doc("Open string union field")
+  mode?: FixtureMode;
 }
 
 model FixtureOwner {
+  @sample(#{ id: "owner-1" })
   id: string;
+
+  @sample(#{ displayName: "Fixture Owner" })
   displayName?: string;
 }
 
@@ -34,10 +53,53 @@ model FixtureContent {
 
 model TextContent extends FixtureContent {
   kind: "text";
+
+  @sample(#{ text: "hello from text content" })
   text: string;
 }
 
 model ImageContent extends FixtureContent {
   kind: "image";
+
+  @sample(#{ url: "https://example.test/image.png" })
   url: string;
 }
+
+alias FixtureStatus = "draft" | "ready" | "archived";
+alias FixtureMode = "interactive" | "batch" | string;
+
+@@coerce(FixtureReference, string, #{ id: "{value}", label: "coerced reference" }, "reference", "Load a reference from an id string.", "ref-coerced");
+@@factory(FixtureReference, "named", #{ id: "{id}", label: "{label}" }, #{ id: "string", label: "string" });
+@@method(FixtureReference, "display", "string", "Render the reference label.", #{ prefix: "string" }, true, true);
+model FixtureReference {
+  @sample(#{ id: "ref-1" })
+  id: string;
+
+  @sample(#{ label: "Primary Reference" })
+  label?: string;
+}
+
+model FixtureTool {
+  @sample(#{ name: "search" })
+  name: string;
+
+  @sample(#{ command: "search --query" })
+  command: string;
+}
+
+model FixtureToolbox {
+  @sample(#{ tools: #[#{ name: "search", command: "search --query" }] })
+  tools: FixtureTool[];
+}
+
+@@knownAs(WireOptions.maxOutputTokens, "openai", "max_completion_tokens");
+@@knownAs(WireOptions.maxOutputTokens, "anthropic", "max_tokens");
+@@knownAs(WireOptions.temperature, "openai", "temperature");
+@@defaultFor(WireOptions.temperature, "openai", 0.2);
+model WireOptions {
+  @sample(#{ maxOutputTokens: 256 })
+  maxOutputTokens?: int32;
+
+  @sample(#{ temperature: 0.7 })
+  temperature?: float32;
+}

package/fixtures/shapes/model/events/session.tsp

@@ -0,0 +1,13 @@
+import "@typra/emitter";
+
+namespace Typra.Fixtures;
+
+model Checkpoint {
+  id: string;
+  label?: string;
+}
+
+model SessionSummary {
+  sessionId: string;
+  latestCheckpoint?: Checkpoint;
+}

package/fixtures/shapes/model/pipeline/harness.tsp

@@ -0,0 +1,11 @@
+import "@typra/emitter";
+
+namespace Typra.Fixtures;
+
+@@protocol(EventSink);
+@@method(EventSink, "emit", "void", "Emit an event.", #{ event: "unknown" }, false, true);
+model EventSink {}
+
+@@protocol(CheckpointStore);
+@@method(CheckpointStore, "save", "void", "Save a checkpoint.", #{ checkpoint: "Checkpoint" }, false, false);
+model CheckpointStore {}

package/fixtures/tspconfig.yaml

@@ -4,10 +4,33 @@ options:
   "@typra/emitter":
     emitter-output-dir: "{cwd}/generated/fixtures"
     root-object: "Typra.Fixtures.FixtureRoot"
-    root-namespace: "Typra.Fixtures"
     emit-targets:
       - type: TypeScript
         output-dir: "generated/fixtures/typescript"
         test-dir: "generated/fixtures/typescript/tests"
         import-path: "../index"
         format: false
+      - type: Python
+        output-dir: "generated/fixtures/python"
+        test-dir: "generated/fixtures/python/tests"
+        import-path: "fixtures"
+        format: false
+      - type: Go
+        output-dir: "generated/fixtures/go"
+        test-dir: "generated/fixtures/go/tests"
+        import-path: "fixtures"
+        package-name: "fixtures"
+        format: false
+      - type: CSharp
+        output-dir: "generated/fixtures/csharp"
+        test-dir: "generated/fixtures/csharp/tests"
+        namespace: "Typra.Fixtures"
+        format: false
+      - type: Rust
+        output-dir: "generated/fixtures/rust"
+        test-dir: "generated/fixtures/rust/tests"
+        import-path: "fixtures::model"
+        format: false
+      - type: Markdown
+        output-dir: "generated/fixtures/markdown"
+        format: false

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@typra/emitter",
-  "version": "0.2.3",
+  "version": "0.2.5",
   "description": "Generic TypeSpec emitter for generating multi-runtime model surfaces",
   "license": "MIT",
   "repository": {
@@ -59,6 +59,7 @@
     "build": "tsc",
     "watch": "tsc --watch",
     "generate:fixtures": "tsp compile ./fixtures/shapes/main.tsp --config ./fixtures/tspconfig.yaml",
+    "validate:fixtures": "node ./scripts/validate-fixtures.mjs",
     "test": "node --test \"dist/test/*.test.js\"",
     "lint": "eslint src/ test/ --report-unused-disable-directives --max-warnings=0",
     "lint:fix": "eslint . --report-unused-disable-directives --fix",