@tsonic/emitter 0.0.1

package/src/emitter-types/core.ts

@@ -0,0 +1,138 @@
+/**
+ * Core emitter types
+ */
+
+import type { MetadataFile } from "@tsonic/frontend/types/metadata.js";
+import type { TypeBinding } from "@tsonic/frontend/types/bindings.js";
+
+/**
+ * Module identity for import resolution
+ */
+export type ModuleIdentity = {
+  readonly namespace: string;
+  readonly className: string;
+  readonly filePath: string;
+};
+
+/**
+ * Module map for resolving cross-file imports
+ */
+export type ModuleMap = ReadonlyMap<string, ModuleIdentity>;
+
+/**
+ * Export source: where an export actually comes from
+ * Used to resolve re-exports to their original source
+ */
+export type ExportSource = {
+  /** Canonical file path of the actual source */
+  readonly sourceFile: string;
+  /** Name of the export in the source file */
+  readonly sourceName: string;
+};
+
+/**
+ * Map from (moduleFilePath, exportName) to actual source
+ * Key format: "moduleFilePath:exportName"
+ */
+export type ExportMap = ReadonlyMap<string, ExportSource>;
+
+/**
+ * Options for C# code generation
+ */
+export type EmitterOptions = {
+  /** Root namespace for the application */
+  readonly rootNamespace: string;
+  /** Whether to include source map comments */
+  readonly includeSourceMaps?: boolean;
+  /** Indentation style (spaces) */
+  readonly indent?: number;
+  /** Maximum line length */
+  readonly maxLineLength?: number;
+  /** Include timestamp in generated files */
+  readonly includeTimestamp?: boolean;
+  /** Whether this module is an entry point (needs Main method) */
+  readonly isEntryPoint?: boolean;
+  /** Entry point file path (for batch emit) */
+  readonly entryPointPath?: string;
+  /** External library paths (contain .metadata and .bindings directories) */
+  readonly libraries?: readonly string[];
+  /** Runtime mode: "js" uses Tsonic.JSRuntime extensions, "dotnet" uses pure .NET */
+  readonly runtime?: "js" | "dotnet";
+  /** Module map for resolving cross-file imports (populated during batch emission) */
+  readonly moduleMap?: ModuleMap;
+  /** Export map for resolving re-exports to actual source (populated during batch emission) */
+  readonly exportMap?: ExportMap;
+};
+
+/**
+ * Import binding information for qualifying imported identifiers.
+ * Local module imports are always emitted as fully-qualified references
+ * to avoid C# name ambiguity.
+ *
+ * All CLR name resolution is done in the frontend - the emitter just uses
+ * the pre-computed clrName directly (no string parsing or type lookup).
+ */
+export type ImportBinding = {
+  /** Import kind: type (interface/class), value (function/variable), or namespace (import *) */
+  readonly kind: "type" | "value" | "namespace";
+  /**
+   * Fully-qualified CLR name.
+   * - For types: the type's FQN (e.g., "MultiFileTypes.models.User")
+   * - For values/namespaces: the container class FQN (e.g., "MultiFileTypes.models.user")
+   */
+  readonly clrName: string;
+  /** For value imports: the member name inside the container (e.g., "createUser") */
+  readonly member?: string;
+};
+
+/**
+ * Context passed through emission process
+ */
+export type EmitterContext = {
+  /** Current indentation level */
+  readonly indentLevel: number;
+  /** Options for emission */
+  readonly options: EmitterOptions;
+  /** Whether currently in static context */
+  readonly isStatic: boolean;
+  /** Whether currently in async context */
+  readonly isAsync: boolean;
+  /** Whether currently emitting an array index (omit .0 from integer literals) */
+  readonly isArrayIndex?: boolean;
+  /** Current class name (for constructor emission) */
+  readonly className?: string;
+  /** Whether the current class has a superclass (for virtual/override) */
+  readonly hasSuperClass?: boolean;
+  /** Whether the module has any inheritance (to decide virtual methods) */
+  readonly hasInheritance?: boolean;
+  /** Loaded .NET metadata files (for CLR type information) */
+  readonly metadata?: ReadonlyArray<MetadataFile>;
+  /** Registry mapping TypeScript emit names to type bindings */
+  readonly bindingsRegistry?: ReadonlyMap<string, TypeBinding>;
+  /** Map of local names to import binding info (for qualifying imported identifiers) */
+  readonly importBindings?: ReadonlyMap<string, ImportBinding>;
+  /** Set of variable names known to be int (from canonical for-loop counters) */
+  readonly intLoopVars?: ReadonlySet<string>;
+};
+
+/**
+ * Result of emitting C# code
+ */
+export type EmitResult = {
+  /** The generated C# code */
+  readonly code: string;
+  /** Updated context after emission */
+  readonly context: EmitterContext;
+};
+
+/**
+ * Helper type for C# code fragments
+ */
+export type CSharpFragment = {
+  /** The code fragment */
+  readonly text: string;
+  /** Whether this needs parentheses when used in expressions */
+  readonly needsParens?: boolean;
+  /** Precedence level for operator expressions */
+  readonly precedence?: number;
+};

package/src/emitter-types/csharp-types.ts

@@ -0,0 +1,42 @@
+/**
+ * C# language-specific types
+ */
+
+/**
+ * C# access modifiers
+ */
+export type CSharpAccessModifier =
+  | "public"
+  | "private"
+  | "protected"
+  | "internal"
+  | "protected internal";
+
+/**
+ * C# class modifiers
+ */
+export type CSharpClassModifier = "static" | "abstract" | "sealed" | "partial";
+
+/**
+ * C# method modifiers
+ */
+export type CSharpMethodModifier =
+  | "static"
+  | "virtual"
+  | "override"
+  | "abstract"
+  | "async"
+  | "new"
+  | "sealed";
+
+/**
+ * Represents a C# using statement
+ */
+export type CSharpUsing = {
+  /** The namespace to import */
+  readonly namespace: string;
+  /** Whether this is a static import */
+  readonly isStatic?: boolean;
+  /** Alias for the import */
+  readonly alias?: string;
+};

package/src/emitter-types/formatting.ts

@@ -0,0 +1,13 @@
+/**
+ * Formatting helper functions
+ */
+
+import { EmitterContext } from "./core.js";
+
+/**
+ * Get indentation string for current level
+ */
+export const getIndent = (context: EmitterContext): string => {
+  const spaces = context.options.indent ?? 4;
+  return " ".repeat(spaces * context.indentLevel);
+};

package/src/emitter-types/fqn.ts

@@ -0,0 +1,81 @@
+/**
+ * Fully Qualified Name (FQN) rendering utilities
+ *
+ * All types and members are emitted with global:: prefix to eliminate
+ * any ambiguity from C# using statements or namespace resolution.
+ */
+
+/**
+ * Render a fully qualified type name with global:: prefix
+ * e.g., "System.Collections.Generic.List" → "global::System.Collections.Generic.List"
+ */
+export const renderTypeFQN = (namespace: string, typeName: string): string => {
+  return `global::${namespace}.${typeName}`;
+};
+
+/**
+ * Render a fully qualified static member access with global:: prefix
+ * e.g., ("System", "Console", "WriteLine") → "global::System.Console.WriteLine"
+ */
+export const renderMemberFQN = (
+  namespace: string,
+  typeName: string,
+  member: string
+): string => {
+  return `global::${namespace}.${typeName}.${member}`;
+};
+
+/**
+ * Render a simple namespace-qualified name with global:: prefix
+ * e.g., "System.Console" → "global::System.Console"
+ */
+export const renderFQN = (qualifiedName: string): string => {
+  return `global::${qualifiedName}`;
+};
+
+/**
+ * Common fully qualified type names used throughout emission
+ */
+export const FQN = {
+  // System types
+  Object: "global::System.Object",
+  String: "global::System.String",
+  Int32: "global::System.Int32",
+  Int64: "global::System.Int64",
+  Double: "global::System.Double",
+  Boolean: "global::System.Boolean",
+  Void: "void",
+
+  // System.Collections.Generic
+  List: (elementType: string) =>
+    `global::System.Collections.Generic.List<${elementType}>`,
+  Dictionary: (keyType: string, valueType: string) =>
+    `global::System.Collections.Generic.Dictionary<${keyType}, ${valueType}>`,
+  IEnumerable: (elementType: string) =>
+    `global::System.Collections.Generic.IEnumerable<${elementType}>`,
+
+  // System.Threading.Tasks
+  Task: "global::System.Threading.Tasks.Task",
+  TaskOf: (resultType: string) =>
+    `global::System.Threading.Tasks.Task<${resultType}>`,
+
+  // Tsonic.Runtime
+  TsonicRuntime: {
+    DynamicObject: "global::Tsonic.Runtime.DynamicObject",
+    Union: (types: string) => `global::Tsonic.Runtime.Union<${types}>`,
+  },
+
+  // Tsonic.JSRuntime
+  TsonicJSRuntime: {
+    Array: "global::Tsonic.JSRuntime.Array",
+    String: "global::Tsonic.JSRuntime.String",
+    Number: "global::Tsonic.JSRuntime.Number",
+    Math: "global::Tsonic.JSRuntime.Math",
+    Console: "global::Tsonic.JSRuntime.Console",
+  },
+
+  // System.Func delegates
+  Func: (typeArgs: string) => `global::System.Func<${typeArgs}>`,
+  Action: "global::System.Action",
+  ActionOf: (typeArgs: string) => `global::System.Action<${typeArgs}>`,
+} as const;

package/src/emitter-types/index.ts

@@ -0,0 +1,31 @@
+/**
+ * Emitter types - Public API
+ */
+
+export type {
+  EmitterOptions,
+  EmitterContext,
+  EmitResult,
+  CSharpFragment,
+  ImportBinding,
+  ModuleIdentity,
+  ModuleMap,
+  ExportSource,
+  ExportMap,
+} from "./core.js";
+export type {
+  CSharpAccessModifier,
+  CSharpClassModifier,
+  CSharpMethodModifier,
+  CSharpUsing,
+} from "./csharp-types.js";
+export {
+  createContext,
+  indent,
+  dedent,
+  withStatic,
+  withAsync,
+  withClassName,
+} from "./context.js";
+export { getIndent } from "./formatting.js";
+export { renderTypeFQN, renderMemberFQN, renderFQN, FQN } from "./fqn.js";

package/src/emitter.ts

@@ -0,0 +1,107 @@
+/**
+ * Main C# Emitter - Public API
+ * Orchestrates code generation from IR
+ */
+
+import { IrModule, Diagnostic } from "@tsonic/frontend";
+import { EmitterOptions } from "./types.js";
+import { emitModule } from "./core/module-emitter.js";
+import { buildModuleMap } from "./core/module-map.js";
+
+/**
+ * Result of batch emission
+ */
+export type EmitResult =
+  | { readonly ok: true; readonly files: Map<string, string> }
+  | { readonly ok: false; readonly errors: readonly Diagnostic[] };
+
+/**
+ * Emit a complete C# file from an IR module
+ */
+export const emitCSharpFile = (
+  module: IrModule,
+  options: Partial<EmitterOptions> = {}
+): string => {
+  return emitModule(module, options);
+};
+
+/**
+ * Batch emit multiple IR modules.
+ * Returns an error if there are file name collisions after normalization.
+ */
+export const emitCSharpFiles = (
+  modules: readonly IrModule[],
+  options: Partial<EmitterOptions> = {}
+): EmitResult => {
+  // Build module map for cross-file import resolution
+  const moduleMapResult = buildModuleMap(modules);
+
+  if (!moduleMapResult.ok) {
+    return { ok: false, errors: moduleMapResult.errors };
+  }
+
+  const moduleMap = moduleMapResult.value;
+  const exportMap = moduleMapResult.exportMap;
+  const results = new Map<string, string>();
+
+  // Find common root directory for all modules
+  const commonRoot = findCommonRoot(modules.map((m) => m.filePath));
+
+  for (const module of modules) {
+    // Create relative path from common root
+    const relativePath = module.filePath.startsWith(commonRoot)
+      ? module.filePath.slice(commonRoot.length).replace(/^\//, "")
+      : module.filePath;
+    const outputPath = relativePath.replace(/\.ts$/, ".cs");
+
+    // Mark this module as entry point if it matches the entry point path
+    const isEntryPoint = !!(
+      options.entryPointPath && module.filePath === options.entryPointPath
+    );
+    const moduleOptions = {
+      ...options,
+      isEntryPoint,
+      moduleMap, // Pass module map to each module emission
+      exportMap, // Pass export map for re-export resolution
+    };
+    const code = emitModule(module, moduleOptions);
+    results.set(outputPath, code);
+  }
+
+  return { ok: true, files: results };
+};
+
+/**
+ * Find the common root directory for a set of file paths
+ */
+const findCommonRoot = (paths: readonly string[]): string => {
+  if (paths.length === 0) return "";
+  if (paths.length === 1) {
+    const firstPath = paths[0];
+    if (!firstPath) return "";
+    const lastSlash = firstPath.lastIndexOf("/");
+    return lastSlash >= 0 ? firstPath.slice(0, lastSlash + 1) : "";
+  }
+
+  // Split all paths into segments
+  const segments = paths.map((p) => p.split("/"));
+  const firstSegments = segments[0];
+  if (!firstSegments) return "";
+
+  const minLength = Math.min(...segments.map((s) => s.length));
+
+  let commonLength = 0;
+  for (let i = 0; i < minLength; i++) {
+    const segment = firstSegments[i];
+    if (segment && segments.every((s) => s[i] === segment)) {
+      commonLength = i + 1;
+    } else {
+      break;
+    }
+  }
+
+  return firstSegments.slice(0, commonLength).join("/") + "/";
+};
+
+// Re-export emitModule for backward compatibility
+export { emitModule } from "./core/module-emitter.js";

package/src/expression-emitter.ts

@@ -0,0 +1,112 @@
+/**
+ * Expression Emitter - IR expressions to C# code
+ * Main dispatcher - delegates to specialized modules
+ */
+
+import { IrExpression, IrType } from "@tsonic/frontend";
+import { EmitterContext, CSharpFragment } from "./types.js";
+
+// Import expression emitters from specialized modules
+import { emitLiteral } from "./expressions/literals.js";
+import { emitIdentifier } from "./expressions/identifiers.js";
+import { emitArray, emitObject } from "./expressions/collections.js";
+import { emitMemberAccess } from "./expressions/access.js";
+import { emitCall, emitNew } from "./expressions/calls.js";
+import {
+  emitBinary,
+  emitLogical,
+  emitUnary,
+  emitUpdate,
+  emitAssignment,
+  emitConditional,
+} from "./expressions/operators.js";
+import {
+  emitFunctionExpression,
+  emitArrowFunction,
+} from "./expressions/functions.js";
+import {
+  emitTemplateLiteral,
+  emitSpread,
+  emitAwait,
+} from "./expressions/other.js";
+
+/**
+ * Emit a C# expression from an IR expression
+ * @param expr The IR expression to emit
+ * @param context The emitter context
+ * @param expectedType Optional expected type for contextual typing (e.g., array element type inference)
+ */
+export const emitExpression = (
+  expr: IrExpression,
+  context: EmitterContext,
+  expectedType?: IrType
+): [CSharpFragment, EmitterContext] => {
+  switch (expr.kind) {
+    case "literal":
+      return emitLiteral(expr, context);
+
+    case "identifier":
+      return emitIdentifier(expr, context);
+
+    case "array":
+      return emitArray(expr, context, expectedType);
+
+    case "object":
+      return emitObject(expr, context);
+
+    case "memberAccess":
+      return emitMemberAccess(expr, context);
+
+    case "call":
+      return emitCall(expr, context);
+
+    case "new":
+      return emitNew(expr, context);
+
+    case "binary":
+      return emitBinary(expr, context);
+
+    case "logical":
+      return emitLogical(expr, context);
+
+    case "unary":
+      return emitUnary(expr, context);
+
+    case "update":
+      return emitUpdate(expr, context);
+
+    case "assignment":
+      return emitAssignment(expr, context);
+
+    case "conditional":
+      return emitConditional(expr, context);
+
+    case "functionExpression":
+      return emitFunctionExpression(expr, context);
+
+    case "arrowFunction":
+      return emitArrowFunction(expr, context);
+
+    case "templateLiteral":
+      return emitTemplateLiteral(expr, context);
+
+    case "spread":
+      return emitSpread(expr, context);
+
+    case "await":
+      return emitAwait(expr, context);
+
+    case "this":
+      return [{ text: "this" }, context];
+
+    default:
+      // Fallback for unhandled expressions
+      return [{ text: "/* TODO: unhandled expression */" }, context];
+  }
+};
+
+// Re-export commonly used functions for backward compatibility
+export {
+  emitTypeArguments,
+  generateSpecializedName,
+} from "./expressions/identifiers.js";

package/src/expressions/access.ts

@@ -0,0 +1,104 @@
+/**
+ * Member access expression emitters
+ */
+
+import { IrExpression } from "@tsonic/frontend";
+import { EmitterContext, CSharpFragment } from "../types.js";
+import { emitExpression } from "../expression-emitter.js";
+import {
+  isExplicitViewProperty,
+  extractInterfaceNameFromView,
+} from "@tsonic/frontend/types/explicit-views.js";
+
+/**
+ * Emit a member access expression (dot notation or bracket notation)
+ */
+export const emitMemberAccess = (
+  expr: Extract<IrExpression, { kind: "memberAccess" }>,
+  context: EmitterContext
+): [CSharpFragment, EmitterContext] => {
+  // Check if this is a hierarchical member binding
+  if (expr.memberBinding) {
+    // Emit the full CLR type and member with global:: prefix
+    const { assembly, type, member } = expr.memberBinding;
+    const text = `global::${assembly}.${type}.${member}`;
+    return [{ text }, context];
+  }
+
+  const [objectFrag, newContext] = emitExpression(expr.object, context);
+
+  // Default runtime to "js" when not specified
+  const runtime = context.options.runtime ?? "js";
+
+  if (expr.isComputed) {
+    // Check if this is array index access - rewrite to static helper
+    const objectType = expr.object.inferredType;
+    const isArrayType = objectType?.kind === "arrayType";
+
+    // For TS arrays, use Tsonic.Runtime.Array.get() in BOTH modes
+    // This provides TS array semantics (auto-grow, sparse arrays, etc.)
+    // Note: Tsonic.Runtime is compiler support for lowered TS constructs (both modes)
+    //       Tsonic.JSRuntime is JS built-ins like .map/.filter (js mode only)
+    if (isArrayType) {
+      const indexContext = { ...newContext, isArrayIndex: true };
+      const [propFrag, contextWithIndex] = emitExpression(
+        expr.property as IrExpression,
+        indexContext
+      );
+      const finalContext = { ...contextWithIndex, isArrayIndex: false };
+      const text = `global::Tsonic.Runtime.Array.get(${objectFrag.text}, ${propFrag.text})`;
+      return [{ text }, finalContext];
+    }
+
+    // CLR indexer access (non-TS-array types like List<T>, string, etc.)
+    // CLR indexers require integral indices.
+    // This applies in BOTH js and dotnet modes - CLR type requirements are mode-independent.
+    const indexContext = { ...newContext, isArrayIndex: true };
+    const [propFrag, contextWithIndex] = emitExpression(
+      expr.property as IrExpression,
+      indexContext
+    );
+    const finalContext = { ...contextWithIndex, isArrayIndex: false };
+    const accessor = expr.isOptional ? "?[" : "[";
+
+    // Check if the index is already known to be int (e.g., canonical loop counter)
+    const indexExpr = expr.property as IrExpression;
+    const isKnownInt =
+      indexExpr.kind === "identifier" &&
+      context.intLoopVars?.has(indexExpr.name);
+
+    // Skip cast if index is known int, otherwise cast for safety
+    const indexText = isKnownInt ? propFrag.text : `(int)(${propFrag.text})`;
+    const text = `${objectFrag.text}${accessor}${indexText}]`;
+    return [{ text }, finalContext];
+  }
+
+  // Property access
+  const prop = expr.property as string;
+  const objectType = expr.object.inferredType;
+  const isArrayType = objectType?.kind === "arrayType";
+
+  // In JS runtime mode, rewrite array.length → global::Tsonic.Runtime.Array.length(array)
+  // In dotnet mode, there is no JS emulation - users access .Count directly on List<T>
+  if (isArrayType && prop === "length" && runtime === "js") {
+    const text = `global::Tsonic.Runtime.Array.length(${objectFrag.text})`;
+    return [{ text }, newContext];
+  }
+
+  // Handle explicit interface view properties (As_IInterface)
+  if (isExplicitViewProperty(prop)) {
+    const interfaceName = extractInterfaceNameFromView(prop);
+    if (interfaceName) {
+      // Emit as C# interface cast: ((IInterface)obj)
+      // TODO: Need to look up full interface name from metadata
+      // For now, use the extracted short name
+      const text = `((${interfaceName})${objectFrag.text})`;
+      return [{ text }, newContext];
+    }
+  }
+
+  // Regular property access
+  const accessor = expr.isOptional ? "?." : ".";
+  const text = `${objectFrag.text}${accessor}${prop}`;
+  return [{ text }, newContext];
+};