@typra/emitter 0.2.4 → 0.2.5

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.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")
@@ -145,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();
@@ -154,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/languages/rust/emitter.js

@@ -990,16 +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 === "void")
-        return "()";
-    if (method.returns === "string")
-        return "String";
-    return RUST_TYPE_MAP[method.returns] || method.returns;
+    return protocolRustType(method.returns);
 }
 // ============================================================================
 // Protocol trait emission

package/fixtures/shapes/main.tsp

@@ -5,27 +5,44 @@ 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;
 }
 
@@ -36,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/tspconfig.yaml

@@ -21,8 +21,16 @@ options:
         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.4",
+  "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",