@alloy-js/csharp 0.23.0-dev.1 → 0.23.0-dev.11

package/src/keywords.ts

@@ -0,0 +1,162 @@
+/**
+ * C# reserved keywords that cannot be used as identifiers without `@` prefix.
+ * These are case-sensitive in C#.
+ *
+ * @see https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/keywords/
+ */
+export const csharpKeywords: ReadonlySet<string> = new Set([
+  "abstract",
+  "as",
+  "base",
+  "bool",
+  "break",
+  "byte",
+  "case",
+  "catch",
+  "char",
+  "checked",
+  "class",
+  "const",
+  "continue",
+  "decimal",
+  "default",
+  "delegate",
+  "do",
+  "double",
+  "else",
+  "enum",
+  "event",
+  "explicit",
+  "extern",
+  "false",
+  "finally",
+  "fixed",
+  "float",
+  "for",
+  "foreach",
+  "goto",
+  "if",
+  "implicit",
+  "in",
+  "int",
+  "interface",
+  "internal",
+  "is",
+  "lock",
+  "long",
+  "namespace",
+  "new",
+  "null",
+  "object",
+  "operator",
+  "out",
+  "override",
+  "params",
+  "private",
+  "protected",
+  "public",
+  "readonly",
+  "ref",
+  "return",
+  "sbyte",
+  "sealed",
+  "short",
+  "sizeof",
+  "stackalloc",
+  "static",
+  "string",
+  "struct",
+  "switch",
+  "this",
+  "throw",
+  "true",
+  "try",
+  "typeof",
+  "uint",
+  "ulong",
+  "unchecked",
+  "unsafe",
+  "ushort",
+  "using",
+  "virtual",
+  "void",
+  "volatile",
+  "while",
+]);
+
+/**
+ * C# contextual keywords that are reserved in certain contexts.
+ * While not always reserved, treating them as keywords in generated code
+ * avoids subtle context-dependent issues.
+ *
+ * @see https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/keywords/#contextual-keywords
+ */
+export const csharpContextualKeywords: ReadonlySet<string> = new Set([
+  "add",
+  "allows",
+  "alias",
+  "and",
+  "ascending",
+  "args",
+  "async",
+  "await",
+  "by",
+  "descending",
+  "dynamic",
+  "equals",
+  "field",
+  "file",
+  "from",
+  "get",
+  "global",
+  "group",
+  "init",
+  "into",
+  "join",
+  "let",
+  "managed",
+  "nameof",
+  "nint",
+  "not",
+  "notnull",
+  "nuint",
+  "on",
+  "or",
+  "orderby",
+  "partial",
+  "record",
+  "remove",
+  "required",
+  "scoped",
+  "select",
+  "set",
+  "unmanaged",
+  "value",
+  "var",
+  "when",
+  "where",
+  "with",
+  "yield",
+]);
+
+/**
+ * Returns true if the given name is a C# reserved keyword.
+ * The check is case-sensitive, matching C# language semantics.
+ *
+ * Note: this only checks reserved keywords, not contextual keywords.
+ * Contextual keywords are only reserved in specific language contexts
+ * and are valid identifiers elsewhere (e.g., `value` is valid as a parameter name).
+ * Use {@link isCSharpContextualKeyword} to check contextual keywords separately.
+ */
+export function isCSharpKeyword(name: string): boolean {
+  return csharpKeywords.has(name);
+}
+
+/**
+ * Returns true if the given name is a C# contextual keyword.
+ * Contextual keywords are only reserved in specific language contexts
+ * and are generally valid as identifiers.
+ */
+export function isCSharpContextualKeyword(name: string): boolean {
+  return csharpContextualKeywords.has(name);
+}

package/src/name-policy.test.ts

@@ -0,0 +1,210 @@
+import { describe, expect, it } from "vitest";
+import {
+  isValidCSharpIdentifier,
+  sanitizeCSharpIdentifier,
+} from "./identifier-utils.js";
+import {
+  csharpContextualKeywords,
+  csharpKeywords,
+  isCSharpContextualKeyword,
+  isCSharpKeyword,
+} from "./keywords.js";
+import { createCSharpNamePolicy } from "./name-policy.js";
+
+describe("isCSharpKeyword", () => {
+  it("recognizes reserved keywords", () => {
+    expect(isCSharpKeyword("class")).toBe(true);
+    expect(isCSharpKeyword("interface")).toBe(true);
+    expect(isCSharpKeyword("string")).toBe(true);
+    expect(isCSharpKeyword("int")).toBe(true);
+    expect(isCSharpKeyword("void")).toBe(true);
+    expect(isCSharpKeyword("return")).toBe(true);
+  });
+
+  it("does not match contextual keywords", () => {
+    expect(isCSharpKeyword("async")).toBe(false);
+    expect(isCSharpKeyword("value")).toBe(false);
+    expect(isCSharpKeyword("var")).toBe(false);
+    expect(isCSharpKeyword("record")).toBe(false);
+  });
+
+  it("is case-sensitive — PascalCase versions are not keywords", () => {
+    expect(isCSharpKeyword("Class")).toBe(false);
+    expect(isCSharpKeyword("String")).toBe(false);
+    expect(isCSharpKeyword("Int")).toBe(false);
+    expect(isCSharpKeyword("Void")).toBe(false);
+  });
+
+  it("rejects non-keywords", () => {
+    expect(isCSharpKeyword("MyClass")).toBe(false);
+    expect(isCSharpKeyword("foo")).toBe(false);
+  });
+
+  it("keyword sets are non-empty", () => {
+    expect(csharpKeywords.size).toBeGreaterThan(70);
+    expect(csharpContextualKeywords.size).toBeGreaterThan(30);
+  });
+});
+
+describe("isCSharpContextualKeyword", () => {
+  it("recognizes contextual keywords", () => {
+    expect(isCSharpContextualKeyword("async")).toBe(true);
+    expect(isCSharpContextualKeyword("await")).toBe(true);
+    expect(isCSharpContextualKeyword("value")).toBe(true);
+    expect(isCSharpContextualKeyword("var")).toBe(true);
+    expect(isCSharpContextualKeyword("record")).toBe(true);
+    expect(isCSharpContextualKeyword("required")).toBe(true);
+  });
+
+  it("does not match reserved keywords", () => {
+    expect(isCSharpContextualKeyword("class")).toBe(false);
+    expect(isCSharpContextualKeyword("int")).toBe(false);
+  });
+});
+
+describe("isValidCSharpIdentifier", () => {
+  it("accepts valid identifiers", () => {
+    expect(isValidCSharpIdentifier("MyClass")).toBe(true);
+    expect(isValidCSharpIdentifier("_private")).toBe(true);
+    expect(isValidCSharpIdentifier("name123")).toBe(true);
+    expect(isValidCSharpIdentifier("a")).toBe(true);
+    expect(isValidCSharpIdentifier("_")).toBe(true);
+  });
+
+  it("rejects invalid identifiers", () => {
+    expect(isValidCSharpIdentifier("123start")).toBe(false);
+    expect(isValidCSharpIdentifier("has-dash")).toBe(false);
+    expect(isValidCSharpIdentifier("has space")).toBe(false);
+    expect(isValidCSharpIdentifier("")).toBe(false);
+    expect(isValidCSharpIdentifier("foo.bar")).toBe(false);
+  });
+
+  it("does not check for keywords (only character rules)", () => {
+    // "class" has valid characters, even though it's a keyword
+    expect(isValidCSharpIdentifier("class")).toBe(true);
+  });
+});
+
+describe("sanitizeCSharpIdentifier", () => {
+  it("passes through valid identifiers unchanged", () => {
+    expect(sanitizeCSharpIdentifier("ValidName")).toBe("ValidName");
+    expect(sanitizeCSharpIdentifier("_private")).toBe("_private");
+    expect(sanitizeCSharpIdentifier("name123")).toBe("name123");
+  });
+
+  it("prefixes underscore when first char is a digit", () => {
+    expect(sanitizeCSharpIdentifier("1foo")).toBe("_1foo");
+  });
+
+  it("replaces non-word characters with underscore", () => {
+    expect(sanitizeCSharpIdentifier("foo-bar")).toBe("foo_bar");
+    expect(sanitizeCSharpIdentifier("has space")).toBe("has_space");
+    expect(sanitizeCSharpIdentifier("a.b.c")).toBe("a_b_c");
+  });
+
+  it("handles leading special characters", () => {
+    expect(sanitizeCSharpIdentifier("$foo")).toBe("_foo");
+    expect(sanitizeCSharpIdentifier("-bar")).toBe("_bar");
+  });
+
+  it("handles empty string", () => {
+    expect(sanitizeCSharpIdentifier("")).toBe("_");
+  });
+});
+
+describe("createCSharpNamePolicy keyword escaping", () => {
+  const policy = createCSharpNamePolicy();
+
+  describe("PascalCase elements avoid most keyword conflicts naturally", () => {
+    it("class element: 'string' becomes 'String' (not a keyword, no escape)", () => {
+      expect(policy.getName("string", "class")).toBe("String");
+    });
+
+    it("class element: 'class' becomes 'Class' (not a keyword, no escape)", () => {
+      expect(policy.getName("class", "class")).toBe("Class");
+    });
+
+    it("class-property element: 'value' becomes 'Value' (not a keyword, no escape)", () => {
+      expect(policy.getName("value", "class-property")).toBe("Value");
+    });
+  });
+
+  describe("camelCase elements may hit keywords and get @-escaped", () => {
+    it("parameter: 'string' stays 'string' → gets @-escaped", () => {
+      expect(policy.getName("string", "parameter")).toBe("@string");
+    });
+
+    it("variable: 'int' stays 'int' → gets @-escaped", () => {
+      expect(policy.getName("int", "variable")).toBe("@int");
+    });
+
+    it("parameter: 'return' stays 'return' → gets @-escaped", () => {
+      expect(policy.getName("return", "parameter")).toBe("@return");
+    });
+
+    it("variable: 'value' stays 'value' — contextual keyword, not escaped", () => {
+      expect(policy.getName("value", "variable")).toBe("value");
+    });
+
+    it("parameter: 'async' stays 'async' — contextual keyword, not escaped", () => {
+      expect(policy.getName("async", "parameter")).toBe("async");
+    });
+  });
+
+  describe("non-keyword names pass through normally", () => {
+    it("parameter: 'myParam' stays 'myParam'", () => {
+      expect(policy.getName("myParam", "parameter")).toBe("myParam");
+    });
+
+    it("class: 'my-model' becomes 'MyModel'", () => {
+      expect(policy.getName("my-model", "class")).toBe("MyModel");
+    });
+
+    it("parameter: 'some-param' becomes 'someParam'", () => {
+      expect(policy.getName("some-param", "parameter")).toBe("someParam");
+    });
+  });
+
+  describe("namespace handling", () => {
+    it("applies PascalCase", () => {
+      expect(policy.getName("my-service", "namespace")).toBe("MyService");
+    });
+
+    it("single segment works", () => {
+      expect(policy.getName("system", "namespace")).toBe("System");
+    });
+
+    it("escapes keyword segments", () => {
+      // "namespace" as a namespace segment → PascalCase → "Namespace" → not a keyword
+      expect(policy.getName("namespace", "namespace")).toBe("Namespace");
+    });
+  });
+
+  describe("constant and private member escaping", () => {
+    it("constant: 'class' becomes 'CLASS' (not a keyword)", () => {
+      expect(policy.getName("class", "constant")).toBe("CLASS");
+    });
+
+    it("class-member-private: 'value' becomes '_value' (not a keyword)", () => {
+      expect(policy.getName("value", "class-member-private")).toBe("_value");
+    });
+  });
+
+  describe("identifier sanitization", () => {
+    it("sanitizes names starting with digits", () => {
+      expect(policy.getName("123foo", "class")).toBe("_123foo");
+    });
+
+    it("sanitizes names starting with digits for camelCase elements", () => {
+      expect(policy.getName("123param", "parameter")).toBe("_123param");
+    });
+
+    it("sanitizes empty string", () => {
+      expect(policy.getName("", "class")).toBe("_");
+    });
+
+    it("sanitizes namespace starting with digits", () => {
+      expect(policy.getName("123service", "namespace")).toBe("_123service");
+    });
+  });
+});

package/src/name-policy.ts

@@ -1,5 +1,7 @@
 import * as core from "@alloy-js/core";
 import * as changecase from "change-case";
+import { sanitizeCSharpIdentifier } from "./identifier-utils.js";
+import { isCSharpKeyword } from "./keywords.js";
 
 // the context in which the name policy should be applied
 export type CSharpElements =
@@ -20,10 +22,27 @@ export type CSharpElements =
   | "type-parameter"
   | "namespace";
 
-// creates the C# naming policy
+/**
+ * Prefixes the name with `@` if it is a C# keyword.
+ * This is the idiomatic C# way to use reserved words as identifiers.
+ * The check is case-sensitive, matching C# language semantics.
+ */
+function escapeIfKeyword(name: string): string {
+  return isCSharpKeyword(name) ? `@${name}` : name;
+}
+
+/**
+ * Creates the C# naming policy with case conversion and keyword escaping.
+ *
+ * After applying the appropriate case conversion for each element kind,
+ * the resulting name is checked against C# reserved and contextual keywords.
+ * If it matches (case-sensitively), the name is prefixed with `@`.
+ */
 export function createCSharpNamePolicy(): core.NamePolicy<CSharpElements> {
   return core.createNamePolicy((name, element) => {
+    let result: string;
     switch (element) {
+      case "namespace":
       case "class":
       case "struct":
       case "enum":
@@ -34,15 +53,20 @@ export function createCSharpNamePolicy(): core.NamePolicy<CSharpElements> {
       case "class-method":
       case "type-parameter":
       case "class-property":
-      case "namespace":
-        return changecase.pascalCase(name);
+        result = changecase.pascalCase(name);
+        break;
       case "constant":
-        return changecase.constantCase(name);
+        result = changecase.constantCase(name);
+        break;
       case "class-member-private":
-        return `_${changecase.camelCase(name)}`;
+        result = `_${changecase.camelCase(name)}`;
+        break;
       default:
-        return changecase.camelCase(name);
+        result = changecase.camelCase(name);
+        break;
     }
+
+    return escapeIfKeyword(sanitizeCSharpIdentifier(result));
   });
 }
 

package/src/scopes/csharp.ts

@@ -20,4 +20,15 @@ export class CSharpScope extends OutputScope {
   get ownerSymbol(): CSharpSymbol | undefined {
     return super.ownerSymbol as CSharpSymbol | undefined;
   }
+
+  override get debugInfo(): Record<string, unknown> {
+    const info = super.debugInfo;
+    if (this.enclosingNamespace) {
+      return {
+        ...info,
+        enclosingNamespace: this.enclosingNamespace.name,
+      };
+    }
+    return info;
+  }
 }

package/src/scopes/factories.ts

@@ -1,4 +1,4 @@
-import { OutputScopeOptions } from "@alloy-js/core";
+import { OutputScopeOptions, createScope } from "@alloy-js/core";
 import { NamedTypeSymbol } from "../symbols/named-type.js";
 import { CSharpClassScope } from "./class.js";
 import { useCSharpScope, useNamedTypeScope } from "./contexts.js";
@@ -21,7 +21,7 @@ export function createNamedTypeScope(
     );
   }
 
-  return new CSharpNamedTypeScope(ownerSymbol, currentScope, options);
+  return createScope(CSharpNamedTypeScope, ownerSymbol, currentScope, options);
 }
 
 export function createClassScope(
@@ -37,9 +37,9 @@ export function createClassScope(
       "Can't create C# class scope inside of " + currentScope.constructor.name,
     );
   }
-  return new CSharpClassScope(ownerSymbol, currentScope, options);
+  return createScope(CSharpClassScope, ownerSymbol, currentScope, options);
 }
 export function createMethodScope(options: OutputScopeOptions = {}) {
   const parentScope = useNamedTypeScope();
-  return new CSharpMethodScope("method scope", parentScope, options);
+  return createScope(CSharpMethodScope, "method scope", parentScope, options);
 }

package/src/scopes/namespace.ts

@@ -1,4 +1,4 @@
-import { OutputScope, useScope } from "@alloy-js/core";
+import { OutputScope, createScope, useScope } from "@alloy-js/core";
 import type { NamespaceSymbol } from "../symbols/namespace.js";
 import { CSharpNamedTypeScope } from "./named-type.js";
 import { CSharpSourceFileScope } from "./source-file.js";
@@ -32,7 +32,7 @@ export function createCSharpNamespaceScope(namespaceSymbol: NamespaceSymbol) {
     );
   }
 
-  const scope = new CSharpNamespaceScope(namespaceSymbol, parentScope);
+  const scope = createScope(CSharpNamespaceScope, namespaceSymbol, parentScope);
 
   return scope;
 }

package/src/symbols/csharp.ts

@@ -1,4 +1,5 @@
 import {
+  createSymbol,
   Namekey,
   OutputDeclarationSpace,
   OutputMemberSpace,
@@ -128,8 +129,10 @@ export class CSharpSymbol extends OutputSymbol {
 
   copy() {
     const options = this.getCopyOptions();
-    const copy = new CSharpSymbol(this.name, undefined, {
+    const binder = this.binder;
+    const copy = createSymbol(CSharpSymbol, this.name, undefined, {
       ...options,
+      binder,
       accessibility: this.#accessibility,
       isStatic: this.#isStatic,
       isVirtual: this.#isVirtual,
@@ -151,6 +154,22 @@ export class CSharpSymbol extends OutputSymbol {
     return copy;
   }
 
+  override get debugInfo(): Record<string, unknown> {
+    return {
+      ...super.debugInfo,
+      kind: this.symbolKind,
+      accessibility: this.accessibility,
+      isAbstract: this.isAbstract,
+      isVirtual: this.isVirtual,
+      isOverride: this.isOverride,
+      isStatic: this.isStatic,
+      isSealed: this.isSealed,
+      isExtern: this.isExtern,
+      isReadOnly: this.isReadOnly,
+      isNullable: this.isNullable,
+    };
+  }
+
   /**
    * Whether this symbol is static.
    */

package/src/symbols/factories.ts

@@ -1,4 +1,5 @@
 import {
+  createSymbol,
   Namekey,
   NamePolicyGetter,
   onCleanup,
@@ -37,11 +38,11 @@ export function createParameterSymbol(
       `Can't create parameter symbol outside of a method or class scope.`,
     );
   }
-  return new CSharpSymbol(
-    originalName,
-    scope.parameters,
-    withNamePolicy(options, "parameter"),
-  );
+  const binder = options.binder ?? scope.binder;
+  return createSymbol(CSharpSymbol, originalName, scope.parameters, {
+    ...withNamePolicy(options, "parameter"),
+    binder,
+  });
 }
 
 export interface CreateTypeParameterSymbolOptions extends CSharpSymbolOptions {
@@ -61,11 +62,11 @@ export function createTypeParameterSymbol(
     );
   }
 
-  return new CSharpSymbol(
-    originalName,
-    scope.typeParameters,
-    withNamePolicy(options, "type-parameter"),
-  );
+  const binder = options.binder ?? scope.binder;
+  return createSymbol(CSharpSymbol, originalName, scope.typeParameters, {
+    ...withNamePolicy(options, "type-parameter"),
+    binder,
+  });
 }
 
 export function createFieldSymbol(
@@ -91,11 +92,11 @@ export function createFieldSymbol(
     throw new Error(`Can't define a field outside of a class or struct.`);
   }
 
-  return new CSharpSymbol(
-    originalName,
-    scope.members,
-    withNamePolicy(options, nameElement),
-  );
+  const binder = options.binder ?? scope.binder;
+  return createSymbol(CSharpSymbol, originalName, scope.members, {
+    ...withNamePolicy(options, nameElement),
+    binder,
+  });
 }
 
 function withCleanup<T extends CSharpSymbol>(sym: T): T {
@@ -111,8 +112,12 @@ export function createNamedTypeSymbol(
   options?: OutputSymbolOptions,
 ) {
   const scope = useNamedTypeScope();
+  const binder = options?.binder ?? scope.ownerSymbol.binder;
   return withCleanup(
-    new NamedTypeSymbol(name, scope.ownerSymbol.members, kind, options),
+    createSymbol(NamedTypeSymbol, name, scope.ownerSymbol.members, kind, {
+      ...options,
+      binder,
+    }),
   );
 }
 
@@ -121,7 +126,9 @@ export function createNamespaceSymbol(
   options: CSharpSymbolOptions = {},
 ): NamespaceSymbol {
   const scope = useNamespaceContext();
-  const parentSymbol = scope?.symbol ?? getGlobalNamespace(useBinder());
+  const parentSymbol =
+    scope?.symbol ??
+    getGlobalNamespace(options.binder ?? scope?.symbol?.binder ?? useBinder());
   const names = normalizeNamespaceName(name);
   let current = parentSymbol;
   for (const name of names) {
@@ -155,12 +162,12 @@ function createNamespaceSymbolInternal(
       expectedName,
     )! as NamespaceSymbol;
   }
+  const binder = options.binder ?? parentSymbol.binder;
   return withCleanup(
-    new NamespaceSymbol(
-      name,
-      parentSymbol,
-      withNamePolicy(options, "namespace"),
-    ),
+    createSymbol(NamespaceSymbol, name, parentSymbol, {
+      ...withNamePolicy(options, "namespace"),
+      binder,
+    }),
   );
 }
 
@@ -184,12 +191,17 @@ export function createMethodSymbol(
     );
   }
 
+  const binder = options.binder ?? scope.binder;
   return withCleanup(
-    new MethodSymbol(
+    createSymbol(
+      MethodSymbol,
       originalName,
       scope.members,
       options.methodKind ?? "ordinary",
-      withNamePolicy(options, "class-method"),
+      {
+        ...withNamePolicy(options, "class-method"),
+        binder,
+      },
     ),
   );
 }
@@ -199,12 +211,12 @@ export function createPropertySymbol(
   options: CSharpSymbolOptions,
 ) {
   const scope = useNamedTypeScope();
+  const binder = options.binder ?? scope.binder;
   return withCleanup(
-    new CSharpSymbol(
-      name,
-      scope.members,
-      withNamePolicy(options, "class-property"),
-    ),
+    createSymbol(CSharpSymbol, name, scope.members, {
+      ...withNamePolicy(options, "class-property"),
+      binder,
+    }),
   );
 }
 
@@ -232,12 +244,12 @@ export function createVariableSymbol(
       `Can't create variable symbol outside of a lexical scope, got a ${scope.constructor.name}.`,
     );
   }
+  const binder = options.binder ?? scope.binder;
   return withCleanup(
-    new CSharpSymbol(
-      originalName,
-      scope.localVariables,
-      withNamePolicy(options, "variable"),
-    ),
+    createSymbol(CSharpSymbol, originalName, scope.localVariables, {
+      ...withNamePolicy(options, "variable"),
+      binder,
+    }),
   );
 }