@tsonic/frontend 0.0.1

package/src/types/ref-parameters.ts

@@ -0,0 +1,268 @@
+/**
+ * Ref/Out Parameter Handling - Generate C# ref/out/in keywords from TSByRef wrapper.
+ *
+ * C# supports pass-by-reference parameters (ref, out, in) which don't have direct
+ * JavaScript equivalents. TypeScript code uses TSByRef<T> wrapper:
+ *
+ * TypeScript: const result = { value: 0 }; TryParse("42", result);
+ * C#:         int result; TryParse("42", out result);
+ *
+ * @see spec/ref-out-parameters.md for complete documentation
+ */
+
+import * as ts from "typescript";
+import type { ParameterMetadata } from "./metadata.js";
+import { isTSByRef, getTSByRefWrappedType } from "./support-types.js";
+
+/**
+ * Parameter modifier for C# emission.
+ */
+export type ParameterModifier = "ref" | "out" | "in" | "none";
+
+/**
+ * Information about a ref/out/in parameter.
+ */
+export type RefParameterInfo = {
+  readonly isRef: boolean;
+  readonly isOut: boolean;
+  readonly isIn: boolean;
+  readonly modifier: ParameterModifier;
+  readonly wrappedType: ts.Type;
+};
+
+/**
+ * Get ref/out/in information from parameter metadata.
+ *
+ * @param paramMetadata - Parameter metadata from .metadata.json
+ * @returns Parameter modifier to use in C# emission
+ */
+export const getParameterModifier = (
+  paramMetadata: ParameterMetadata
+): ParameterModifier => {
+  if (paramMetadata.isOut) {
+    return "out";
+  }
+  if (paramMetadata.isRef) {
+    return "ref";
+  }
+  if (paramMetadata.isIn) {
+    return "in";
+  }
+  return "none";
+};
+
+/**
+ * Check if parameter requires TSByRef wrapper based on metadata.
+ *
+ * @param paramMetadata - Parameter metadata from .metadata.json
+ * @returns True if parameter should use TSByRef<T> in TypeScript
+ */
+export const requiresTSByRef = (paramMetadata: ParameterMetadata): boolean => {
+  return (
+    paramMetadata.isRef || paramMetadata.isOut || (paramMetadata.isIn ?? false)
+  );
+};
+
+/**
+ * Get ref parameter info from TypeScript type and metadata.
+ *
+ * @param paramType - TypeScript parameter type
+ * @param paramMetadata - Parameter metadata from .metadata.json
+ * @param checker - TypeScript type checker
+ * @returns Ref parameter info if applicable, undefined otherwise
+ */
+export const getRefParameterInfo = (
+  paramType: ts.Type,
+  paramMetadata: ParameterMetadata,
+  checker: ts.TypeChecker
+): RefParameterInfo | undefined => {
+  // Check if type is TSByRef<T>
+  if (!isTSByRef(paramType, checker)) {
+    return undefined;
+  }
+
+  // Extract wrapped type
+  const wrappedType = getTSByRefWrappedType(paramType, checker);
+  if (!wrappedType) {
+    return undefined;
+  }
+
+  return {
+    isRef: paramMetadata.isRef,
+    isOut: paramMetadata.isOut,
+    isIn: paramMetadata.isIn ?? false,
+    modifier: getParameterModifier(paramMetadata),
+    wrappedType,
+  };
+};
+
+/**
+ * Extract variable name from TSByRef argument expression.
+ *
+ * TypeScript: TryParse("42", result)  // where result = { value: 0 }
+ * C#:         TryParse("42", out result)
+ *
+ * @param argumentNode - Argument AST node
+ * @returns Variable identifier name, or undefined if not extractable
+ */
+export const extractRefArgumentVariable = (
+  argumentNode: ts.Expression
+): string | undefined => {
+  // Handle simple identifier
+  if (ts.isIdentifier(argumentNode)) {
+    return argumentNode.text;
+  }
+
+  // Handle property access (unlikely for ref params, but possible)
+  if (ts.isPropertyAccessExpression(argumentNode)) {
+    return argumentNode.name.text;
+  }
+
+  // Cannot extract variable name from complex expressions
+  return undefined;
+};
+
+/**
+ * Check if argument expression is a TSByRef wrapper object literal.
+ *
+ * Detects: { value: 0 } or { value: initialValue }
+ *
+ * @param argumentNode - Argument AST node
+ * @returns True if argument is object literal with 'value' property
+ */
+export const isTSByRefObjectLiteral = (
+  argumentNode: ts.Expression
+): boolean => {
+  if (!ts.isObjectLiteralExpression(argumentNode)) {
+    return false;
+  }
+
+  // Check if object has exactly one property named 'value'
+  const properties = argumentNode.properties;
+  if (properties.length !== 1) {
+    return false;
+  }
+
+  const prop = properties[0];
+  if (!prop || !ts.isPropertyAssignment(prop)) {
+    return false;
+  }
+
+  if (!ts.isIdentifier(prop.name)) {
+    return false;
+  }
+
+  return prop.name.text === "value";
+};
+
+/**
+ * Generate C# parameter declaration with modifier.
+ *
+ * @param modifier - Parameter modifier (ref/out/in/none)
+ * @param typeName - C# type name
+ * @param paramName - Parameter name
+ * @returns C# parameter declaration
+ */
+export const generateCSharpParameter = (
+  modifier: ParameterModifier,
+  typeName: string,
+  paramName: string
+): string => {
+  if (modifier === "none") {
+    return `${typeName} ${paramName}`;
+  }
+  return `${modifier} ${typeName} ${paramName}`;
+};
+
+/**
+ * Generate C# argument with modifier for method call.
+ *
+ * @param modifier - Parameter modifier (ref/out/in/none)
+ * @param argumentExpression - C# argument expression
+ * @returns C# argument with modifier
+ */
+export const generateCSharpArgument = (
+  modifier: ParameterModifier,
+  argumentExpression: string
+): string => {
+  if (modifier === "none") {
+    return argumentExpression;
+  }
+  return `${modifier} ${argumentExpression}`;
+};
+
+/**
+ * Check if variable declaration is needed for out parameter.
+ *
+ * For out parameters in TypeScript:
+ *   const result = { value: 0 };  // Declaration
+ *   TryParse("42", result);       // Usage
+ *
+ * For out parameters in C#:
+ *   TryParse("42", out int result);  // Inline declaration
+ *
+ * @param argumentNode - Argument AST node
+ * @returns True if variable should be declared before the call
+ */
+export const needsOutVariableDeclaration = (
+  argumentNode: ts.Expression
+): boolean => {
+  // If argument is already a simple identifier, it's already declared
+  if (ts.isIdentifier(argumentNode)) {
+    return false;
+  }
+
+  // If argument is an object literal { value: ... }, we need to declare the variable
+  if (isTSByRefObjectLiteral(argumentNode)) {
+    return true;
+  }
+
+  return false;
+};
+
+/**
+ * Extract initial value from TSByRef object literal.
+ *
+ * { value: 42 } → 42
+ * { value: getDefault() } → getDefault()
+ *
+ * @param argumentNode - Argument AST node (must be object literal)
+ * @returns Initial value expression, or undefined if no initializer
+ */
+export const extractTSByRefInitialValue = (
+  argumentNode: ts.Expression
+): ts.Expression | undefined => {
+  if (!ts.isObjectLiteralExpression(argumentNode)) {
+    return undefined;
+  }
+
+  const properties = argumentNode.properties;
+  if (properties.length !== 1) {
+    return undefined;
+  }
+
+  const prop = properties[0];
+  if (!prop || !ts.isPropertyAssignment(prop)) {
+    return undefined;
+  }
+
+  return prop.initializer;
+};
+
+/**
+ * Determine if ref/out parameter should use inline declaration in C#.
+ *
+ * C# 7.0+ supports inline out var:
+ *   if (int.TryParse("42", out var result)) { ... }
+ *
+ * We use this when the TypeScript code declares the wrapper inline.
+ *
+ * @param argumentNode - Argument AST node
+ * @returns True if should use inline declaration
+ */
+export const shouldUseInlineDeclaration = (
+  argumentNode: ts.Expression
+): boolean => {
+  // Use inline declaration if argument is an object literal
+  return isTSByRefObjectLiteral(argumentNode);
+};

package/src/types/result.test.ts

@@ -0,0 +1,157 @@
+/**
+ * Tests for Result type
+ */
+
+import { describe, it } from "mocha";
+import { expect } from "chai";
+import {
+  ok,
+  error,
+  map,
+  flatMap,
+  mapError,
+  unwrapOr,
+  unwrapOrElse,
+  isOk,
+  isError,
+} from "./result.js";
+
+describe("Result", () => {
+  describe("ok and error constructors", () => {
+    it("should create ok result", () => {
+      const result = ok<number, string>(42);
+      expect(result.ok).to.equal(true);
+      if (result.ok) {
+        expect(result.value).to.equal(42);
+      }
+    });
+
+    it("should create error result", () => {
+      const result = error<number, string>("Something went wrong");
+      expect(result.ok).to.equal(false);
+      if (!result.ok) {
+        expect(result.error).to.equal("Something went wrong");
+      }
+    });
+  });
+
+  describe("map", () => {
+    it("should map ok value", () => {
+      const result = ok<number, string>(5);
+      const mapped = map(result, (x) => x * 2);
+
+      expect(mapped.ok).to.equal(true);
+      if (mapped.ok) {
+        expect(mapped.value).to.equal(10);
+      }
+    });
+
+    it("should pass through error", () => {
+      const result = error<number, string>("Error");
+      const mapped = map(result, (x) => x * 2);
+
+      expect(mapped.ok).to.equal(false);
+      if (!mapped.ok) {
+        expect(mapped.error).to.equal("Error");
+      }
+    });
+  });
+
+  describe("flatMap", () => {
+    it("should flatMap ok value", () => {
+      const result = ok<number, string>(5);
+      const mapped = flatMap(result, (x) => ok(x.toString()));
+
+      expect(mapped.ok).to.equal(true);
+      if (mapped.ok) {
+        expect(mapped.value).to.equal("5");
+      }
+    });
+
+    it("should handle flatMap returning error", () => {
+      const result = ok<number, string>(5);
+      const mapped = flatMap(result, (x) =>
+        x > 10 ? ok(x) : error("Too small")
+      );
+
+      expect(mapped.ok).to.equal(false);
+      if (!mapped.ok) {
+        expect(mapped.error).to.equal("Too small");
+      }
+    });
+
+    it("should pass through original error", () => {
+      const result = error<number, string>("Original error");
+      const mapped = flatMap(result, (x) => ok(x * 2));
+
+      expect(mapped.ok).to.equal(false);
+      if (!mapped.ok) {
+        expect(mapped.error).to.equal("Original error");
+      }
+    });
+  });
+
+  describe("mapError", () => {
+    it("should map error value", () => {
+      const result = error<number, string>("Error");
+      const mapped = mapError(result, (e) => e.toUpperCase());
+
+      expect(mapped.ok).to.equal(false);
+      if (!mapped.ok) {
+        expect(mapped.error).to.equal("ERROR");
+      }
+    });
+
+    it("should pass through ok value", () => {
+      const result = ok<number, string>(42);
+      const mapped = mapError(result, (e) => e.toUpperCase());
+
+      expect(mapped.ok).to.equal(true);
+      if (mapped.ok) {
+        expect(mapped.value).to.equal(42);
+      }
+    });
+  });
+
+  describe("unwrapOr", () => {
+    it("should return value for ok", () => {
+      const result = ok<number, string>(42);
+      expect(unwrapOr(result, 0)).to.equal(42);
+    });
+
+    it("should return default for error", () => {
+      const result = error<number, string>("Error");
+      expect(unwrapOr(result, 0)).to.equal(0);
+    });
+  });
+
+  describe("unwrapOrElse", () => {
+    it("should return value for ok", () => {
+      const result = ok<number, string>(42);
+      expect(unwrapOrElse(result, (_e) => 0)).to.equal(42);
+    });
+
+    it("should call function for error", () => {
+      const result = error<number, string>("Error");
+      expect(unwrapOrElse(result, () => 0)).to.equal(0);
+    });
+  });
+
+  describe("isOk and isError", () => {
+    it("should identify ok results", () => {
+      const okResult = ok<number, string>(42);
+      const errorResult = error<number, string>("Error");
+
+      expect(isOk(okResult)).to.equal(true);
+      expect(isOk(errorResult)).to.equal(false);
+    });
+
+    it("should identify error results", () => {
+      const okResult = ok<number, string>(42);
+      const errorResult = error<number, string>("Error");
+
+      expect(isError(okResult)).to.equal(false);
+      expect(isError(errorResult)).to.equal(true);
+    });
+  });
+});

package/src/types/result.ts

@@ -0,0 +1,48 @@
+/**
+ * Result type for functional error handling
+ */
+
+export type Result<T, E> =
+  | { readonly ok: true; readonly value: T }
+  | { readonly ok: false; readonly error: E };
+
+export const ok = <T, E>(value: T): Result<T, E> => ({
+  ok: true,
+  value,
+});
+
+export const error = <T, E>(error: E): Result<T, E> => ({
+  ok: false,
+  error,
+});
+
+export const map = <T, U, E>(
+  result: Result<T, E>,
+  fn: (value: T) => U
+): Result<U, E> => (result.ok ? ok(fn(result.value)) : result);
+
+export const flatMap = <T, U, E>(
+  result: Result<T, E>,
+  fn: (value: T) => Result<U, E>
+): Result<U, E> => (result.ok ? fn(result.value) : result);
+
+export const mapError = <T, E, F>(
+  result: Result<T, E>,
+  fn: (error: E) => F
+): Result<T, F> => (result.ok ? result : error(fn(result.error)));
+
+export const unwrapOr = <T, E>(result: Result<T, E>, defaultValue: T): T =>
+  result.ok ? result.value : defaultValue;
+
+export const unwrapOrElse = <T, E>(
+  result: Result<T, E>,
+  fn: (error: E) => T
+): T => (result.ok ? result.value : fn(result.error));
+
+export const isOk = <T, E>(
+  result: Result<T, E>
+): result is { readonly ok: true; readonly value: T } => result.ok;
+
+export const isError = <T, E>(
+  result: Result<T, E>
+): result is { readonly ok: false; readonly error: E } => !result.ok;

package/src/types/support-types.test.ts

@@ -0,0 +1,81 @@
+/**
+ * Tests for support types recognition using real TypeScript types.
+ */
+
+import { describe, it, before, after } from "mocha";
+import { strict as assert } from "assert";
+import { checkUnsupportedSupportType } from "./support-types.js";
+import {
+  createTestHarness,
+  getSupportTypes,
+  type TestHarness,
+} from "./test-harness.js";
+
+describe("Support Types", () => {
+  let harness: TestHarness;
+  let types: ReturnType<typeof getSupportTypes>;
+
+  before(() => {
+    // Create test harness with real TypeScript program
+    harness = createTestHarness();
+    types = getSupportTypes(harness);
+  });
+
+  after(() => {
+    // Clean up temporary files
+    harness.cleanup();
+  });
+
+  describe("checkUnsupportedSupportType", () => {
+    it("should detect TSUnsafePointer as unsupported", () => {
+      const error = checkUnsupportedSupportType(
+        types.unsafePointer,
+        harness.checker
+      );
+
+      assert.ok(error);
+      assert.match(error!, /unsafe pointer/i);
+    });
+
+    it("should detect TSFixed as unsupported", () => {
+      const error = checkUnsupportedSupportType(types.fixed, harness.checker);
+
+      assert.ok(error);
+      assert.match(error!, /fixed-size buffer/i);
+    });
+
+    it("should detect TSStackAlloc as unsupported", () => {
+      const error = checkUnsupportedSupportType(
+        types.stackAlloc,
+        harness.checker
+      );
+
+      assert.ok(error);
+      assert.match(error!, /stackalloc/i);
+    });
+
+    it("should allow TSByRef (supported)", () => {
+      const error = checkUnsupportedSupportType(types.byRef, harness.checker);
+
+      assert.equal(error, undefined);
+    });
+
+    it("should allow TSNullable (supported)", () => {
+      const error = checkUnsupportedSupportType(
+        types.nullable,
+        harness.checker
+      );
+
+      assert.equal(error, undefined);
+    });
+
+    it("should allow TSDelegate (supported)", () => {
+      const error = checkUnsupportedSupportType(
+        types.delegate,
+        harness.checker
+      );
+
+      assert.equal(error, undefined);
+    });
+  });
+});