@typra/emitter 0.2.0

package/dist/src/lib.js

@@ -0,0 +1,101 @@
+import { createTypeSpecLibrary } from "@typespec/compiler";
+const TypraEmitterOptionsSchema = {
+    type: "object",
+    additionalProperties: false,
+    properties: {
+        "emit-targets": {
+            type: "array",
+            items: {
+                type: "object",
+                properties: {
+                    "type": {
+                        type: "string"
+                    },
+                    "output-dir": {
+                        type: "string",
+                        nullable: true
+                    },
+                    "test-dir": {
+                        type: "string",
+                        nullable: true
+                    },
+                    "alias": {
+                        type: "object",
+                        additionalProperties: true,
+                        nullable: true
+                    },
+                    "format": {
+                        type: "boolean",
+                        nullable: true,
+                        default: true,
+                        description: "Run formatters on emitted files"
+                    },
+                    "namespace": {
+                        type: "string",
+                        nullable: true,
+                        description: "Override the namespace for the emitted code"
+                    },
+                    "import-path": {
+                        type: "string",
+                        nullable: true,
+                        description: "Import path for generated code in tests. Defaults vary by language."
+                    }
+                },
+                required: ["type"]
+            },
+            nullable: true,
+            description: "List of target languages to emit code for"
+        },
+        "root-namespace": {
+            type: "string",
+            nullable: true,
+            description: "Root namespace for the emitted code"
+        },
+        "root-object": {
+            type: "string",
+            nullable: false,
+            description: "Root object for the emitted artifacts"
+        },
+        "root-alias": {
+            type: "string",
+            nullable: true,
+            description: "Alias for the root object"
+        },
+        "omit-models": {
+            type: "array",
+            items: { type: "string" },
+            nullable: true,
+            description: "List of model names to omit from generation"
+        },
+        "schema-output-dir": {
+            type: "string",
+            nullable: true,
+            description: "Directory containing JSON schema files. Reserved for future manifest-based cleanup of omitted models."
+        },
+        "additional-roots": {
+            type: "array",
+            items: { type: "string" },
+            nullable: true,
+            description: "Additional root types to resolve and generate alongside the main root object. These types need not be referenced from the main root. Specified as fully-qualified names (e.g., 'Typra.Message')."
+        }
+    },
+    required: ["root-object"],
+};
+export const $lib = createTypeSpecLibrary({
+    name: "typra-emitter",
+    diagnostics: {},
+    emitter: { options: TypraEmitterOptionsSchema },
+    state: {
+        samples: { description: "Sample values for properties" },
+        coercions: { description: "Scalar-to-object implicit conversions" },
+        abstracts: { description: "Abstract models" },
+        factories: { description: "Factory methods for model construction" },
+        methods: { description: "Method stubs for model types" },
+        knownAs: { description: "Wire field name mappings per target system" },
+        defaultFor: { description: "Per-target required default values" },
+        protocols: { description: "Pipeline interface markers" }
+    }
+});
+export const { reportDiagnostic, createDiagnostic } = $lib;
+export const StateKeys = $lib.stateKeys;
+//# sourceMappingURL=lib.js.map

package/dist/src/testing/index.d.ts

@@ -0,0 +1,2 @@
+import { TypeSpecTestLibrary } from "@typespec/compiler/testing";
+export declare const TypraEmitTestLibrary: TypeSpecTestLibrary;

package/dist/src/testing/index.js

@@ -0,0 +1,8 @@
+import { resolvePath } from "@typespec/compiler";
+import { createTestLibrary } from "@typespec/compiler/testing";
+import { fileURLToPath } from "url";
+export const TypraEmitTestLibrary = createTestLibrary({
+    name: "typra-emitter",
+    packageRoot: resolvePath(fileURLToPath(import.meta.url), "../../../../"),
+});
+//# sourceMappingURL=index.js.map

package/dist/src/testing/test-context.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Shared Test Context Builder
+ * ===========================
+ * Provides standardized helper functions for building test contexts across all language emitters.
+ * This ensures consistency in how tests are generated from @sample decorators.
+ */
+import { TypeNode, BaseTestContext } from "../ir/ast.js";
+/**
+ * Options for building test context - language-specific transformations.
+ */
+export interface TestContextOptions {
+    /** Transform property name to target language casing (e.g., PascalCase, snake_case) */
+    renderKey: (key: string) => string;
+    /** Render boolean value as language-specific literal (e.g., "True"/"False" for Python) */
+    renderBoolean: (val: boolean) => string;
+    /** Escape string for use in language-specific string literal */
+    escapeString: (str: string) => string;
+    /** Get string delimiter based on content (e.g., '"' or '"""' for multiline) */
+    getDelimiter: (str: string) => string;
+    /** Escape JSON for embedding in test template (optional - for languages that need it) */
+    escapeJsonForTemplate?: (json: string) => string;
+    /** Escape YAML for embedding in test template (optional - for languages that need it) */
+    escapeYamlForTemplate?: (yaml: string) => string;
+    /** Default scalar values for each type (used when @sample doesn't provide example) */
+    scalarValues: Record<string, string>;
+    /** Type mapper for scalar types */
+    typeMapper: Record<string, string>;
+    /**
+     * Render an enum assertion value for a closed enum field.
+     * Called with (enumName, rawStringValue, fieldName).
+     * If provided and returns non-null, overrides default string/bool/number rendering.
+     * The returned value+delimiter replace the default.
+     */
+    renderEnumValue?: (enumName: string, rawValue: string, fieldName: string) => {
+        value: string;
+        delimiter: string;
+    } | null;
+}
+/**
+ * Build a standardized test context from a TypeNode.
+ * All language emitters should use this to ensure consistent test generation.
+ */
+export declare function buildBaseTestContext(node: TypeNode, packageName: string | undefined, options: TestContextOptions): BaseTestContext;
+/**
+ * C# test context options.
+ */
+export declare const csharpTestOptions: TestContextOptions;
+/**
+ * Python test context options.
+ */
+export declare const pythonTestOptions: TestContextOptions;
+/**
+ * TypeScript test context options.
+ */
+export declare const typescriptTestOptions: TestContextOptions;
+/**
+ * Rust test context options.
+ */
+export declare const rustTestOptions: TestContextOptions;
+/**
+ * Go test context options.
+ */
+export declare const goTestOptions: TestContextOptions;

package/dist/src/testing/test-context.js

@@ -0,0 +1,355 @@
+/**
+ * Shared Test Context Builder
+ * ===========================
+ * Provides standardized helper functions for building test contexts across all language emitters.
+ * This ensures consistency in how tests are generated from @sample decorators.
+ */
+import { getCombinations, toSnakeCase } from "../ir/utilities.js";
+import { toPascalCase } from "../ir/visitor.js";
+import * as YAML from "yaml";
+const RUST_KEYWORDS = new Set([
+    "as", "break", "const", "continue", "crate", "else", "enum", "extern",
+    "false", "fn", "for", "if", "impl", "in", "let", "loop", "match", "mod",
+    "move", "mut", "pub", "ref", "return", "self", "Self", "static", "struct",
+    "super", "trait", "true", "type", "unsafe", "use", "where", "while",
+    "async", "await", "dyn",
+]);
+function rustFieldName(name) {
+    const snake = toSnakeCase(name);
+    return RUST_KEYWORDS.has(snake) ? `r#${snake}` : snake;
+}
+/**
+ * Build a standardized test context from a TypeNode.
+ * All language emitters should use this to ensure consistent test generation.
+ */
+export function buildBaseTestContext(node, packageName, options) {
+    const examples = buildExamples(node, options);
+    const coercions = buildCoercions(node, options);
+    const isAbstract = node.isAbstract || (node.discriminator !== undefined && node.discriminator.length > 0);
+    return {
+        node,
+        isAbstract,
+        package: packageName,
+        examples,
+        coercions,
+        factories: node.factories,
+    };
+}
+/**
+ * Build test examples from @sample decorators on properties.
+ */
+function buildExamples(node, options) {
+    // Get sample properties and generate combinations
+    const samples = node.properties
+        .filter(p => p.samples && p.samples.length > 0)
+        .map(p => p.samples?.map(s => ({ ...s.sample })));
+    const combinations = samples.length > 0 ? getCombinations(samples) : [];
+    return combinations.map(c => {
+        const sample = Object.assign({}, ...c);
+        // Create YAML document with proper string escaping
+        const doc = new YAML.Document(sample);
+        YAML.visit(doc, {
+            Scalar(key, yamlNode) {
+                if (typeof yamlNode.value === 'string') {
+                    const str = yamlNode.value;
+                    if (str.includes('\n') || str.includes('\t') || str.includes('#') || str.includes(':') || str.includes('"')) {
+                        yamlNode.type = 'QUOTE_DOUBLE';
+                    }
+                }
+            }
+        });
+        // Generate JSON and optionally escape for embedding in template strings
+        let jsonStr = JSON.stringify(sample, null, 2);
+        if (options.escapeJsonForTemplate) {
+            jsonStr = options.escapeJsonForTemplate(jsonStr);
+        }
+        // Generate YAML and optionally escape for embedding in template strings
+        let yamlStr = doc.toString({ indent: 2, lineWidth: 0 });
+        if (options.escapeYamlForTemplate) {
+            yamlStr = options.escapeYamlForTemplate(yamlStr);
+        }
+        return {
+            json: jsonStr.split('\n'),
+            yaml: yamlStr.split('\n'),
+            validations: buildValidations(sample, node, options),
+        };
+    });
+}
+/**
+ * Build property validations from a sample object.
+ */
+function buildValidations(sample, node, options) {
+    return Object.keys(sample)
+        .filter(key => typeof sample[key] !== 'object')
+        .map(key => {
+        const prop = node.properties.find(p => p.name === key);
+        const rawValue = sample[key];
+        // Check for enum field (skip discriminator fields)
+        const isDiscriminator = node.discriminator === key;
+        if (prop && prop.enumName && !isDiscriminator && typeof rawValue === 'string' && options.renderEnumValue) {
+            const enumResult = options.renderEnumValue(prop.enumName, rawValue, key);
+            if (enumResult) {
+                return {
+                    key: options.renderKey(key),
+                    value: enumResult.value,
+                    delimiter: enumResult.delimiter,
+                    isOptional: prop?.isOptional || false,
+                };
+            }
+        }
+        let value;
+        let delimiter = '';
+        if (typeof rawValue === 'boolean') {
+            value = options.renderBoolean(rawValue);
+        }
+        else if (typeof rawValue === 'string') {
+            value = options.escapeString(rawValue);
+            delimiter = options.getDelimiter(rawValue);
+        }
+        else {
+            value = rawValue;
+        }
+        return {
+            key: options.renderKey(key),
+            value,
+            delimiter,
+            isOptional: prop?.isOptional || false,
+        };
+    });
+}
+/**
+ * Build coercion (scalar-to-object) test cases from node coercions.
+ */
+function buildCoercions(node, options) {
+    if (!node.coercions || node.coercions.length === 0) {
+        return [];
+    }
+    return node.coercions.map(alt => {
+        // Get example value - use provided example or default scalar value
+        const example = alt.example
+            ? (typeof alt.example === "string" ? '"' + alt.example + '"' : alt.example.toString())
+            : options.scalarValues[alt.scalar] || "null";
+        // Build validations for expanded properties
+        const validations = Object.keys(alt.expansion)
+            .filter(key => typeof alt.expansion[key] !== 'object')
+            .map(key => {
+            const prop = node.properties.find(p => p.name === key);
+            const rawValue = alt.expansion[key];
+            const isValuePlaceholder = rawValue === "{value}";
+            const value = isValuePlaceholder ? example : rawValue;
+            // Check for closed enum field (skip discriminator fields)
+            const isDiscriminator = node.discriminator === key;
+            if (prop && prop.enumName && !isDiscriminator && options.renderEnumValue) {
+                // Extract the raw string value (strip quotes if present from example substitution)
+                const strValue = typeof value === 'string' ? value.replace(/^"|"$/g, '') : String(value);
+                const enumResult = options.renderEnumValue(prop.enumName, strValue, key);
+                if (enumResult) {
+                    return {
+                        key: options.renderKey(key),
+                        value: enumResult.value,
+                        delimiter: enumResult.delimiter,
+                        isOptional: prop?.isOptional || false,
+                    };
+                }
+            }
+            // Determine delimiter - don't add quotes if it's the {value} placeholder (already has quotes)
+            const needsQuotes = typeof value === 'string' && !value.includes('"') && !isValuePlaceholder;
+            return {
+                key: options.renderKey(key),
+                value: needsQuotes ? options.escapeString(value) : value,
+                delimiter: needsQuotes ? '"' : '',
+                isOptional: prop?.isOptional || false,
+            };
+        });
+        return {
+            title: alt.title || alt.scalar,
+            scalarType: options.typeMapper[alt.scalar] || alt.scalar,
+            value: example,
+            validations,
+        };
+    });
+}
+// =============================================================================
+// Language-Specific Presets
+// =============================================================================
+/**
+ * C# test context options.
+ */
+export const csharpTestOptions = {
+    renderKey: (key) => {
+        // Convert snake_case to PascalCase
+        const pascal = key.replace(/_([a-z])/g, (_, letter) => letter.toUpperCase());
+        return pascal.charAt(0).toUpperCase() + pascal.slice(1);
+    },
+    renderBoolean: (val) => val ? "True" : "False",
+    escapeString: (str) => str.replace(/\\/g, "\\\\").replace(/"/g, '\\"'),
+    getDelimiter: (str) => str.includes('\n') ? '@"' : '"',
+    scalarValues: {
+        "boolean": "false",
+        "float": "3.14f",
+        "float32": "3.14f",
+        "float64": "3.14",
+        "number": "3.14f",
+        "int32": "3",
+        "int64": "3L",
+        "integer": "3",
+        "string": '"example"',
+    },
+    typeMapper: {
+        "string": "string",
+        "boolean": "bool",
+        "int32": "int",
+        "int64": "long",
+        "float32": "float",
+        "float64": "double",
+        "number": "float",
+    },
+};
+/**
+ * Python test context options.
+ */
+export const pythonTestOptions = {
+    renderKey: (key) => toSnakeCase(key), // camelCase from TypeSpec → snake_case for Python
+    renderBoolean: (val) => val ? "True" : "False",
+    escapeString: (str) => str.replace(/\\/g, "\\\\").replace(/"/g, '\\"'),
+    getDelimiter: (str) => str.includes('\n') ? '"""' : '"',
+    scalarValues: {
+        "boolean": "False",
+        "float": "3.14",
+        "float32": "3.14",
+        "float64": "3.14",
+        "number": "3.14",
+        "int32": "3",
+        "int64": "3",
+        "integer": "3",
+        "string": '"example"',
+    },
+    typeMapper: {
+        "string": "str",
+        "boolean": "bool",
+        "int32": "int",
+        "int64": "int",
+        "float32": "float",
+        "float64": "float",
+        "number": "float",
+    },
+};
+/**
+ * TypeScript test context options.
+ */
+export const typescriptTestOptions = {
+    renderKey: (key) => key, // camelCase - already correct from TypeSpec
+    renderBoolean: (val) => val ? "true" : "false",
+    escapeString: (str) => str
+        .replace(/\\/g, "\\\\")
+        .replace(/\n/g, "\\n")
+        .replace(/\r/g, "\\r")
+        .replace(/\t/g, "\\t")
+        .replace(/"/g, '\\"'),
+    getDelimiter: (str) => '"',
+    // Escape backslashes in JSON so escape sequences like \n remain as literals in template strings
+    escapeJsonForTemplate: (json) => json.replace(/\\/g, "\\\\"),
+    // Escape backslashes in YAML so escape sequences remain as literals in template strings
+    escapeYamlForTemplate: (yaml) => yaml.replace(/\\/g, "\\\\"),
+    scalarValues: {
+        "boolean": "false",
+        "float": "3.14",
+        "float32": "3.14",
+        "float64": "3.14",
+        "number": "3.14",
+        "int32": "3",
+        "int64": "3",
+        "integer": "3",
+        "string": '"example"',
+    },
+    typeMapper: {
+        "string": "string",
+        "boolean": "boolean",
+        "int32": "number",
+        "int64": "number",
+        "float32": "number",
+        "float64": "number",
+        "number": "number",
+    },
+};
+/**
+ * Rust test context options.
+ */
+export const rustTestOptions = {
+    renderKey: (key) => {
+        return rustFieldName(key);
+    },
+    renderBoolean: (val) => val ? "true" : "false",
+    escapeString: (str) => str
+        .replace(/\\/g, '\\\\')
+        .replace(/"/g, '\\"')
+        .replace(/\n/g, '\\n')
+        .replace(/\r/g, '\\r')
+        .replace(/\t/g, '\\t'),
+    getDelimiter: (str) => '"',
+    renderEnumValue: (enumName, rawValue) => ({
+        value: `${enumName}::${toPascalCase(rawValue)}`,
+        delimiter: '',
+    }),
+    escapeJsonForTemplate: undefined,
+    escapeYamlForTemplate: undefined,
+    scalarValues: {
+        "boolean": "false",
+        "float": "3.14",
+        "float32": "3.14",
+        "float64": "3.14",
+        "number": "3.14",
+        "int32": "3",
+        "int64": "3",
+        "integer": "3",
+        "string": '"example"',
+    },
+    typeMapper: {
+        "string": "String",
+        "boolean": "bool",
+        "int32": "i32",
+        "int64": "i64",
+        "float32": "f32",
+        "float64": "f64",
+        "number": "f64",
+    },
+};
+/**
+ * Go test context options.
+ */
+export const goTestOptions = {
+    renderKey: (key) => {
+        // Convert snake_case to PascalCase for exported Go fields
+        const pascal = key.replace(/_([a-z])/g, (_, letter) => letter.toUpperCase());
+        return pascal.charAt(0).toUpperCase() + pascal.slice(1);
+    },
+    renderBoolean: (val) => val ? "true" : "false",
+    escapeString: (str) => str
+        .replace(/\\/g, '\\\\')
+        .replace(/"/g, '\\"')
+        .replace(/\n/g, '\\n')
+        .replace(/\r/g, '\\r')
+        .replace(/\t/g, '\\t'),
+    getDelimiter: (str) => '"',
+    scalarValues: {
+        "boolean": "false",
+        "float": "3.14",
+        "float32": "3.14",
+        "float64": "3.14",
+        "number": "3.14",
+        "int32": "3",
+        "int64": "3",
+        "integer": "3",
+        "string": '"example"',
+    },
+    typeMapper: {
+        "string": "string",
+        "boolean": "bool",
+        "int32": "int32",
+        "int64": "int64",
+        "float32": "float32",
+        "float64": "float64",
+        "number": "float64",
+    },
+};
+//# sourceMappingURL=test-context.js.map

package/fixtures/shapes/main.tsp

@@ -0,0 +1,43 @@
+import "@typra/emitter";
+
+namespace Typra.Fixtures;
+
+model FixtureRoot {
+  @doc("Required scalar field")
+  name: string;
+
+  @doc("Optional scalar field")
+  description?: string;
+
+  @doc("Array of scalar tags")
+  tags: string[];
+
+  @doc("Dictionary-shaped metadata")
+  metadata?: Record<unknown>;
+
+  @doc("Nested object field")
+  owner: FixtureOwner;
+
+  @doc("Discriminated union field")
+  content: FixtureContent;
+}
+
+model FixtureOwner {
+  id: string;
+  displayName?: string;
+}
+
+@discriminator("kind")
+model FixtureContent {
+  kind: string;
+}
+
+model TextContent extends FixtureContent {
+  kind: "text";
+  text: string;
+}
+
+model ImageContent extends FixtureContent {
+  kind: "image";
+  url: string;
+}

package/fixtures/tspconfig.yaml

@@ -0,0 +1,13 @@
+emit:
+  - "@typra/emitter"
+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

package/package.json

@@ -0,0 +1,76 @@
+{
+  "name": "@typra/emitter",
+  "version": "0.2.0",
+  "description": "Generic TypeSpec emitter for generating multi-runtime model surfaces",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/sethjuarez/typra"
+  },
+  "type": "module",
+  "main": "dist/src/index.js",
+  "types": "dist/src/index.d.ts",
+  "tspMain": "src/lib/main.tsp",
+  "bin": {
+    "typra-generate": "./dist/src/cli.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "default": "./dist/src/index.js"
+    },
+    "./generate": {
+      "types": "./dist/src/generate.d.ts",
+      "default": "./dist/src/generate.js"
+    },
+    "./testing": {
+      "types": "./dist/src/testing/index.d.ts",
+      "default": "./dist/src/testing/index.js"
+    }
+  },
+  "files": [
+    "dist/src/**/*.js",
+    "dist/src/**/*.d.ts",
+    "dist/src/**/*.json",
+    "fixtures/**/*.tsp",
+    "src/lib/*.tsp",
+    "tspconfig.yaml",
+    "fixtures/tspconfig.yaml"
+  ],
+  "peerDependencies": {
+    "@typespec/compiler": "latest",
+    "@typespec/json-schema": "latest"
+  },
+  "devDependencies": {
+    "@types/node": "^24.7.0",
+
+    "@typescript-eslint/eslint-plugin": "^8.15.0",
+    "@typescript-eslint/parser": "^8.15.0",
+    "@typespec/compiler": "latest",
+    "@typespec/json-schema": "^1.8.0",
+    "eslint": "^9.15.0",
+    "markdownlint-cli": "^0.48.0",
+    "prettier": "^3.3.3",
+    "typescript": "^5.3.3",
+    "typescript-eslint": "^8.54.0"
+  },
+  "scripts": {
+    "build": "tsc",
+    "watch": "tsc --watch",
+    "generate:fixtures": "tsp compile ./fixtures/shapes/main.tsp --config ./fixtures/tspconfig.yaml",
+    "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",
+    "format": "prettier .  --write",
+    "format:check": "prettier --check ."
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "packageManager": "npm@11.5.1+sha512.232e6f5d9e799bcb486920b3e9ba907fdf96e576cf7e8c9446c8162e33a416096a1d37a9e910d9a918f6b1f606791c99bc6bb61ee2569b496ec74af13d0dbd95",
+  "dependencies": {
+
+    "xml-formatter": "^3.6.7",
+    "yaml": "^2.8.1"
+  }
+}