@tsonic/emitter 0.0.1

package/src/types/unions.test.ts

@@ -0,0 +1,397 @@
+/**
+ * Tests for union type emission
+ * Verifies TypeScript unions map to C# Union<T1, T2>
+ */
+
+import { describe, it } from "mocha";
+import { expect } from "chai";
+import { emitModule } from "../emitter.js";
+import { IrModule } from "@tsonic/frontend";
+
+describe("Union Type Emission", () => {
+  it("should emit nullable type as T?", () => {
+    const module: IrModule = {
+      kind: "module",
+      filePath: "/test/nullable.ts",
+      namespace: "Test",
+      className: "nullable",
+      isStaticContainer: true,
+      imports: [],
+      exports: [],
+      body: [
+        {
+          kind: "variableDeclaration",
+          declarationKind: "const",
+          isExported: false,
+          declarations: [
+            {
+              kind: "variableDeclarator",
+              name: { kind: "identifierPattern", name: "maybeString" },
+              type: {
+                kind: "unionType",
+                types: [
+                  { kind: "primitiveType", name: "string" },
+                  { kind: "primitiveType", name: "null" },
+                ],
+              },
+              initializer: { kind: "literal", value: null },
+            },
+          ],
+        },
+      ],
+    };
+
+    const code = emitModule(module);
+
+    // Should use nullable syntax
+    expect(code).to.include("string? maybeString");
+  });
+
+  it("should emit two-type union as Union<T1, T2>", () => {
+    const module: IrModule = {
+      kind: "module",
+      filePath: "/test/union.ts",
+      namespace: "Test",
+      className: "union",
+      isStaticContainer: true,
+      imports: [],
+      exports: [],
+      body: [
+        {
+          kind: "variableDeclaration",
+          declarationKind: "const",
+          isExported: false,
+          declarations: [
+            {
+              kind: "variableDeclarator",
+              name: { kind: "identifierPattern", name: "value" },
+              type: {
+                kind: "unionType",
+                types: [
+                  { kind: "primitiveType", name: "string" },
+                  { kind: "primitiveType", name: "number" },
+                ],
+              },
+              initializer: { kind: "literal", value: "hello" },
+            },
+          ],
+        },
+      ],
+    };
+
+    const code = emitModule(module);
+
+    // Should use Union<T1, T2>
+    expect(code).to.include("Union<string, double> value");
+    expect(code).to.include("using Tsonic.Runtime");
+  });
+
+  it("should emit function returning union type", () => {
+    const module: IrModule = {
+      kind: "module",
+      filePath: "/test/unionFunc.ts",
+      namespace: "Test",
+      className: "unionFunc",
+      isStaticContainer: true,
+      imports: [],
+      exports: [],
+      body: [
+        {
+          kind: "functionDeclaration",
+          name: "getValue",
+          parameters: [],
+          returnType: {
+            kind: "unionType",
+            types: [
+              { kind: "primitiveType", name: "string" },
+              { kind: "primitiveType", name: "number" },
+            ],
+          },
+          body: {
+            kind: "blockStatement",
+            statements: [
+              {
+                kind: "returnStatement",
+                expression: { kind: "literal", value: "hello" },
+              },
+            ],
+          },
+          isAsync: false,
+          isGenerator: false,
+          isExported: true,
+        },
+      ],
+    };
+
+    const code = emitModule(module);
+
+    // Should return Union<string, double>
+    expect(code).to.include("public static Union<string, double> getValue()");
+  });
+
+  it("should emit function parameter with union type", () => {
+    const module: IrModule = {
+      kind: "module",
+      filePath: "/test/unionParam.ts",
+      namespace: "Test",
+      className: "unionParam",
+      isStaticContainer: true,
+      imports: [],
+      exports: [],
+      body: [
+        {
+          kind: "functionDeclaration",
+          name: "process",
+          parameters: [
+            {
+              kind: "parameter",
+              pattern: { kind: "identifierPattern", name: "input" },
+              type: {
+                kind: "unionType",
+                types: [
+                  { kind: "primitiveType", name: "string" },
+                  { kind: "primitiveType", name: "boolean" },
+                ],
+              },
+              isOptional: false,
+              isRest: false,
+              passing: "value",
+            },
+          ],
+          returnType: { kind: "voidType" },
+          body: {
+            kind: "blockStatement",
+            statements: [],
+          },
+          isAsync: false,
+          isGenerator: false,
+          isExported: true,
+        },
+      ],
+    };
+
+    const code = emitModule(module);
+
+    // Should accept Union<string, bool> parameter
+    expect(code).to.include("process(Union<string, bool> input)");
+  });
+
+  it("should handle union with custom types", () => {
+    const module: IrModule = {
+      kind: "module",
+      filePath: "/test/customUnion.ts",
+      namespace: "Test",
+      className: "customUnion",
+      isStaticContainer: true,
+      imports: [],
+      exports: [],
+      body: [
+        {
+          kind: "functionDeclaration",
+          name: "getResult",
+          parameters: [],
+          returnType: {
+            kind: "unionType",
+            types: [
+              { kind: "referenceType", name: "User", typeArguments: [] },
+              { kind: "referenceType", name: "Product", typeArguments: [] },
+            ],
+          },
+          body: {
+            kind: "blockStatement",
+            statements: [
+              {
+                kind: "returnStatement",
+                expression: { kind: "identifier", name: "user" },
+              },
+            ],
+          },
+          isAsync: false,
+          isGenerator: false,
+          isExported: true,
+        },
+      ],
+    };
+
+    const code = emitModule(module);
+
+    // Should use Union<User, Product>
+    expect(code).to.include("Union<User, Product> getResult()");
+  });
+
+  it("should emit three-type union as Union<T1, T2, T3>", () => {
+    const module: IrModule = {
+      kind: "module",
+      filePath: "/test/union3.ts",
+      namespace: "Test",
+      className: "union3",
+      isStaticContainer: true,
+      imports: [],
+      exports: [],
+      body: [
+        {
+          kind: "variableDeclaration",
+          declarationKind: "const",
+          isExported: false,
+          declarations: [
+            {
+              kind: "variableDeclarator",
+              name: { kind: "identifierPattern", name: "value" },
+              type: {
+                kind: "unionType",
+                types: [
+                  { kind: "primitiveType", name: "string" },
+                  { kind: "primitiveType", name: "number" },
+                  { kind: "primitiveType", name: "boolean" },
+                ],
+              },
+              initializer: { kind: "literal", value: "hello" },
+            },
+          ],
+        },
+      ],
+    };
+
+    const code = emitModule(module);
+
+    // Should use Union<T1, T2, T3>
+    expect(code).to.include("Union<string, double, bool> value");
+    expect(code).to.include("using Tsonic.Runtime");
+  });
+
+  it("should emit four-type union as Union<T1, T2, T3, T4>", () => {
+    const module: IrModule = {
+      kind: "module",
+      filePath: "/test/union4.ts",
+      namespace: "Test",
+      className: "union4",
+      isStaticContainer: true,
+      imports: [],
+      exports: [],
+      body: [
+        {
+          kind: "functionDeclaration",
+          name: "process",
+          parameters: [],
+          returnType: {
+            kind: "unionType",
+            types: [
+              { kind: "primitiveType", name: "string" },
+              { kind: "primitiveType", name: "number" },
+              { kind: "primitiveType", name: "boolean" },
+              { kind: "referenceType", name: "Date", typeArguments: [] },
+            ],
+          },
+          body: {
+            kind: "blockStatement",
+            statements: [
+              {
+                kind: "returnStatement",
+                expression: { kind: "literal", value: "hello" },
+              },
+            ],
+          },
+          isAsync: false,
+          isGenerator: false,
+          isExported: true,
+        },
+      ],
+    };
+
+    const code = emitModule(module);
+
+    // Should use Union<T1, T2, T3, T4>
+    expect(code).to.include("Union<string, double, bool, Date> process()");
+  });
+
+  it("should emit eight-type union as Union<T1, T2, T3, T4, T5, T6, T7, T8>", () => {
+    const module: IrModule = {
+      kind: "module",
+      filePath: "/test/union8.ts",
+      namespace: "Test",
+      className: "union8",
+      isStaticContainer: true,
+      imports: [],
+      exports: [],
+      body: [
+        {
+          kind: "variableDeclaration",
+          declarationKind: "const",
+          isExported: false,
+          declarations: [
+            {
+              kind: "variableDeclarator",
+              name: { kind: "identifierPattern", name: "value" },
+              type: {
+                kind: "unionType",
+                types: [
+                  { kind: "primitiveType", name: "string" },
+                  { kind: "primitiveType", name: "number" },
+                  { kind: "primitiveType", name: "boolean" },
+                  { kind: "referenceType", name: "User", typeArguments: [] },
+                  { kind: "referenceType", name: "Product", typeArguments: [] },
+                  { kind: "referenceType", name: "Order", typeArguments: [] },
+                  { kind: "referenceType", name: "Payment", typeArguments: [] },
+                  { kind: "referenceType", name: "Invoice", typeArguments: [] },
+                ],
+              },
+              initializer: { kind: "literal", value: "hello" },
+            },
+          ],
+        },
+      ],
+    };
+
+    const code = emitModule(module);
+
+    // Should use Union<T1, T2, T3, T4, T5, T6, T7, T8>
+    expect(code).to.include(
+      "Union<string, double, bool, User, Product, Order, Payment, Invoice> value"
+    );
+  });
+
+  it("should fall back to object for unions with more than 8 types", () => {
+    const module: IrModule = {
+      kind: "module",
+      filePath: "/test/union9.ts",
+      namespace: "Test",
+      className: "union9",
+      isStaticContainer: true,
+      imports: [],
+      exports: [],
+      body: [
+        {
+          kind: "variableDeclaration",
+          declarationKind: "const",
+          isExported: false,
+          declarations: [
+            {
+              kind: "variableDeclarator",
+              name: { kind: "identifierPattern", name: "value" },
+              type: {
+                kind: "unionType",
+                types: [
+                  { kind: "primitiveType", name: "string" },
+                  { kind: "primitiveType", name: "number" },
+                  { kind: "primitiveType", name: "boolean" },
+                  { kind: "referenceType", name: "T1", typeArguments: [] },
+                  { kind: "referenceType", name: "T2", typeArguments: [] },
+                  { kind: "referenceType", name: "T3", typeArguments: [] },
+                  { kind: "referenceType", name: "T4", typeArguments: [] },
+                  { kind: "referenceType", name: "T5", typeArguments: [] },
+                  { kind: "referenceType", name: "T6", typeArguments: [] },
+                ],
+              },
+              initializer: { kind: "literal", value: "hello" },
+            },
+          ],
+        },
+      ],
+    };
+
+    const code = emitModule(module);
+
+    // Should fall back to object for 9+ types
+    expect(code).to.include("object value");
+  });
+});

package/src/types/unions.ts

@@ -0,0 +1,62 @@
+/**
+ * Union type emission
+ */
+
+import { IrType } from "@tsonic/frontend";
+import { EmitterContext } from "../types.js";
+import { emitType } from "./emitter.js";
+
+/**
+ * Emit union types as nullable (T?), Union<T1, T2>, or object
+ */
+export const emitUnionType = (
+  type: Extract<IrType, { kind: "unionType" }>,
+  context: EmitterContext
+): [string, EmitterContext] => {
+  // C# doesn't have native union types
+  // Strategy:
+  // 1. Nullable types (T | null | undefined) → T?
+  // 2. Two-type unions → Union<T1, T2>
+  // 3. Multi-type unions → object (fallback)
+
+  // Check if it's a nullable type (T | null | undefined)
+  const nonNullTypes = type.types.filter(
+    (t) =>
+      !(
+        t.kind === "primitiveType" &&
+        (t.name === "null" || t.name === "undefined")
+      )
+  );
+
+  if (nonNullTypes.length === 1) {
+    // This is a nullable type (T | null | undefined)
+    const firstType = nonNullTypes[0];
+    if (!firstType) {
+      return ["object?", context];
+    }
+    const [baseType, newContext] = emitType(firstType, context);
+    // Add ? suffix for nullable types (both value types and reference types)
+    // This includes string?, int?, double?, etc. per spec/04-type-mappings.md
+    return [`${baseType}?`, newContext];
+  }
+
+  // Multi-type unions (2-8 types) → Union<T1, T2, ...>
+  if (type.types.length >= 2 && type.types.length <= 8) {
+    const typeStrings: string[] = [];
+    let currentContext = context;
+
+    for (const t of type.types) {
+      const [typeStr, newContext] = emitType(t, currentContext);
+      typeStrings.push(typeStr);
+      currentContext = newContext;
+    }
+
+    return [
+      `global::Tsonic.Runtime.Union<${typeStrings.join(", ")}>`,
+      currentContext,
+    ];
+  }
+
+  // Fallback for unions with more than 8 types: use object
+  return ["object", context];
+};

package/src/types.ts

@@ -0,0 +1,33 @@
+/**
+ * C# Emitter Types
+ * Main dispatcher - re-exports from emitter-types/ subdirectory
+ */
+
+export type {
+  EmitterOptions,
+  EmitterContext,
+  EmitResult,
+  CSharpFragment,
+  CSharpAccessModifier,
+  CSharpClassModifier,
+  CSharpMethodModifier,
+  CSharpUsing,
+  ImportBinding,
+  ModuleIdentity,
+  ModuleMap,
+  ExportSource,
+  ExportMap,
+} from "./emitter-types/index.js";
+export {
+  createContext,
+  indent,
+  dedent,
+  withStatic,
+  withAsync,
+  withClassName,
+  getIndent,
+  renderTypeFQN,
+  renderMemberFQN,
+  renderFQN,
+  FQN,
+} from "./emitter-types/index.js";

package/testcases/README.md

@@ -0,0 +1,213 @@
+# Golden Test Suite
+
+This directory contains **golden tests** for the Tsonic emitter - tests that verify the exact C# output generated from TypeScript input.
+
+## Structure
+
+Each test case is a directory containing three files:
+
+```
+testcases/
+  category/          # e.g., arrays, async, functions
+    subcategory/     # e.g., basic, advanced
+      title.txt      # One-line test description
+      FileName.ts    # TypeScript input (name becomes C# class name)
+      expected.cs    # Expected C# output
+```
+
+**Important**: The `.ts` filename determines the generated C# class name. For example:
+
+- `Basic.ts` → `class Basic`
+- `UserService.ts` → `class UserService`
+
+## How It Works
+
+1. **Auto-discovery**: The test harness (`golden.test.ts`) automatically discovers all test cases
+2. **Nested describes**: Test cases are organized into nested `describe` blocks matching the directory structure
+3. **Full pipeline**: Each test runs the complete TypeScript → IR → C# pipeline
+4. **Exact comparison**: Generated C# is compared character-by-character with expected output
+
+## Adding a New Test
+
+1. **Create a directory** under the appropriate category:
+
+   ```bash
+   mkdir -p testcases/arrays/destructuring
+   ```
+
+2. **Add three files**:
+
+   **`title.txt`** - Single line description:
+
+   ```
+   should emit array destructuring assignment
+   ```
+
+   **`ArrayDestructure.ts`** - TypeScript input:
+
+   ```typescript
+   export function destructure(arr: number[]): number {
+     const [first, second] = arr;
+     return first + second;
+   }
+   ```
+
+   **`expected.cs`** - Expected C# output (without header):
+
+   ```csharp
+   using Tsonic.Runtime;
+
+   namespace TestCases.Arrays
+   {
+       public static class ArrayDestructure
+       {
+           public static double destructure(Tsonic.Runtime.Array<double> arr)
+               {
+               var first = arr[0];
+               var second = arr[1];
+               return first + second;
+               }
+       }
+   }
+   ```
+
+   **Note**: Do NOT include the file header (`// Generated from:...`) in expected files. The test harness automatically generates and prepends the header using a shared constant from `constants.ts`. This ensures tests don't break when the header format changes.
+
+3. **Run tests**:
+   ```bash
+   npm run test:emitter
+   ```
+
+## Tips
+
+### Getting the Expected Output
+
+The easiest way to create `expected.cs` is to:
+
+1. Create the `.ts` file with your input
+2. Create a temporary `expected.cs` with placeholder content
+3. Run the tests - they will fail and show you the actual output
+4. Copy the actual output to `expected.cs`
+5. **Remove the header** (the first 4 lines starting with `// Generated from:`)
+
+Or use the CLI to generate it:
+
+```bash
+cd packages/emitter/testcases/arrays/destructuring
+tsonic emit ArrayDestructure.ts --out-dir temp
+# Remove header lines before saving
+tail -n +5 temp/ArrayDestructure.cs > expected.cs
+```
+
+### File Path Normalization
+
+The harness normalizes:
+
+- Line endings (`\r\n` → `\n`)
+- Trailing whitespace
+- Timestamps (`Generated at: ...` → `TIMESTAMP`)
+
+This makes tests resilient to minor formatting changes.
+
+### Namespace Calculation
+
+The namespace is derived from the directory path:
+
+```
+testcases/arrays/basic/Basic.ts
+    └─ TestCases.Arrays (namespace)
+                 └─ Basic (class name from filename)
+
+testcases/async/advanced/PromiseHelper.ts
+    └─ TestCases.Async.Advanced
+                       └─ PromiseHelper
+```
+
+## Test Organization
+
+Organize tests by feature category:
+
+- **`arrays/`** - Array operations, destructuring, spread
+- **`async/`** - Async/await, promises, generators
+- **`functions/`** - Function declarations, arrow functions, closures
+- **`classes/`** - Class declarations, methods, inheritance
+- **`types/`** - Type mappings, unions, generics
+- **`interop/`** - .NET interop, imports
+- **`edge-cases/`** - Corner cases, error conditions
+
+Within each category, use subdirectories for complexity:
+
+- `basic/` - Simple, fundamental cases
+- `advanced/` - Complex scenarios
+- `edge-cases/` - Unusual inputs
+
+## Running Tests
+
+```bash
+# Run all emitter tests (including golden tests)
+npm run test:emitter
+
+# Run only golden tests (via mocha grep)
+npm run test:emitter -- --grep "Golden Tests"
+
+# Run specific category
+npm run test:emitter -- --grep "Golden Tests arrays"
+```
+
+## Troubleshooting
+
+### Test fails with "No .ts input file found"
+
+Make sure your test directory contains exactly one `.ts` file (other than `title.txt`).
+
+### Test fails with "Incomplete test case"
+
+You're missing one of the required files:
+
+- `title.txt`
+- `*.ts`
+- `expected.cs`
+
+### Test fails with diff showing wrong class name
+
+The C# class name comes from the `.ts` filename, not the directory name.
+
+Example:
+
+- ❌ `input.ts` → `class input`
+- ✅ `ArrayHelper.ts` → `class ArrayHelper`
+
+### Test fails with diff showing wrong namespace
+
+Check the directory structure. Namespace is built from path components:
+
+```
+testcases/foo/bar/Test.ts → TestCases.Foo (not TestCases.Foo.Bar)
+```
+
+The last directory component becomes the class name prefix, not part of the namespace.
+
+## Benefits
+
+✅ **Easy to add** - Just create 3 files
+✅ **Exact verification** - Catches any output changes
+✅ **Auto-discovered** - No manual test registration
+✅ **Well-organized** - Nested describes match directory structure
+✅ **Fast feedback** - Clear diffs when tests fail
+✅ **Comprehensive** - Tests full TS → IR → C# pipeline
+
+## Contribution Guidelines
+
+When adding golden tests:
+
+1. **Be specific** - One test per feature/behavior
+2. **Use descriptive names** - File and title should be clear
+3. **Keep it simple** - Focus on one aspect per test
+4. **Add comments** - Explain non-obvious behavior in the `.ts` file
+5. **Verify output** - Ensure expected.cs is actually correct
+
+## See Also
+
+- [Emitter Implementation](../src/emitter.ts)
+- [Golden Test Harness](../src/golden.test.ts)
+- [Tsonic Spec](../../../spec/)

package/testcases/arrays/basic/ArrayLiteral.ts

@@ -0,0 +1,4 @@
+export function createArray(): number[] {
+  const arr = [1, 2, 3];
+  return arr;
+}