@alloy-js/csharp 0.23.0-dev.8 → 0.24.0-dev.0

package/src/components/property/property.tsx

@@ -1,4 +1,5 @@
 import {
+  Block,
   Children,
   createSymbolSlot,
   List,
@@ -54,11 +55,49 @@ export interface PropertyProps extends AccessModifiers, PropertyModifiers {
   /** Property type */
   type: Children;
 
-  /** If property should have a getter */
-  get?: boolean;
+  /**
+   * If property should have a getter. Pass `true` for an auto-property getter (`get;`),
+   * or pass children for a getter with a body.
+   *
+   * @example auto-property
+   * ```tsx
+   * <Property name="Name" type="string" get set />
+   * ```
+   * Produces: `string Name { get; set; }`
+   *
+   * @example with body
+   * ```tsx
+   * <Property name="Name" type="string" get={<>return _name;</>} set />
+   * ```
+   * Produces:
+   * ```csharp
+   * string Name
+   * {
+   *     get { return _name; }
+   *     set;
+   * }
+   * ```
+   */
+  get?: boolean | Children;
 
-  /** If property should have a setter */
-  set?: boolean;
+  /**
+   * If property should have a setter. Pass `true` for an auto-property setter (`set;`),
+   * or pass children for a setter with a body.
+   *
+   * @example with body
+   * ```tsx
+   * <Property name="Value" type="int" get set={<>_value = value;</>} />
+   * ```
+   * Produces:
+   * ```csharp
+   * int Value
+   * {
+   *     get;
+   *     set { _value = value; }
+   * }
+   * ```
+   */
+  set?: boolean | Children;
 
   /** If property should only be set on the type creation */
   init?: boolean;
@@ -133,14 +172,42 @@ export function Property(props: PropertyProps) {
       `Cannot use 'init' and 'set' together on property '${name}'`,
     );
   }
-  // note that scope wraps the method decl so that the params get the correct scope
+
+  const hasAccessorBody =
+    (props.get && props.get !== true) || (props.set && props.set !== true);
+
   return (
     <MemberDeclaration symbol={propertySymbol}>
       <DocWhen doc={props.doc} />
       <AttributeList attributes={props.attributes} endline />
       {modifiers}
       <TypeSlot>{props.type}</TypeSlot>
-      {props.nullable && "?"} <MemberName /> {"{ "}
+      {props.nullable && "?"} <MemberName />
+      {hasAccessorBody ?
+        <AccessorBlock get={props.get} set={props.set} init={props.init} />
+      : <AutoAccessors
+          get={props.get}
+          set={props.set}
+          init={props.init}
+          initializer={props.initializer}
+        />
+      }
+    </MemberDeclaration>
+  );
+}
+
+interface AutoAccessorsProps {
+  get?: boolean | Children;
+  set?: boolean | Children;
+  init?: boolean;
+  initializer?: Children;
+}
+
+function AutoAccessors(props: AutoAccessorsProps) {
+  return (
+    <group>
+      {" "}
+      {"{ "}
       <List joiner=" ">
         {props.get && "get;"}
         {props.set && "set;"}
@@ -148,20 +215,48 @@ export function Property(props: PropertyProps) {
       </List>
       {" }"}
       {props.initializer && (
-        <PropertyInitializer>{props.initializer}</PropertyInitializer>
+        <>
+          {" ="}
+          <indent>
+            <line />
+            {props.initializer};
+          </indent>
+        </>
       )}
-    </MemberDeclaration>
+    </group>
+  );
+}
+
+interface AccessorBlockProps {
+  get?: boolean | Children;
+  set?: boolean | Children;
+  init?: boolean;
+}
+
+function AccessorBlock(props: AccessorBlockProps) {
+  return (
+    <Block newline>
+      <List hardline>
+        {props.get && <Accessor keyword="get" body={props.get} />}
+        {props.set && <Accessor keyword="set" body={props.set} />}
+        {props.init && "init;"}
+      </List>
+    </Block>
   );
 }
 
-function PropertyInitializer(props: { children: Children }) {
+interface AccessorProps {
+  keyword: string;
+  body: boolean | Children;
+}
+
+function Accessor(props: AccessorProps) {
+  if (props.body === true) {
+    return <>{props.keyword};</>;
+  }
   return (
-    <group>
-      {" ="}
-      <indent>
-        <line />
-        {props.children};
-      </indent>
-    </group>
+    <>
+      {props.keyword} <Block inline>{props.body}</Block>
+    </>
   );
 }

package/src/components/source-file/source-file.tsx

@@ -105,10 +105,7 @@ export function SourceFile(props: SourceFileProps) {
         : <>
             namespace <NamespaceName symbol={nsSymbol} />
             {sourceFileScope.hasBlockNamespace ?
-              <>
-                {" "}
-                <Block>{content}</Block>
-              </>
+              <Block newline>{content}</Block>
             : <>
                 ;<hbr />
                 <hbr />

package/src/identifier-utils.ts

@@ -0,0 +1,45 @@
+/**
+ * Checks whether the provided name is a valid C# identifier (without `@` prefix).
+ * Does not account for keyword conflicts — use {@link isCSharpKeyword} for that.
+ *
+ * @param name - The name to validate.
+ * @returns true if the name matches C# identifier rules (letter or underscore start, word chars after).
+ */
+export function isValidCSharpIdentifier(name: string): boolean {
+  return /^[A-Za-z_]\w*$/.test(name);
+}
+
+/**
+ * Transforms an arbitrary string into a valid C# identifier by replacing
+ * invalid characters. The result may still be a C# keyword — callers
+ * should combine with keyword escaping if needed.
+ *
+ * - If the first character is not a letter or underscore, a `_` prefix is added.
+ * - Subsequent non-word characters are replaced with `_`.
+ * - Empty strings become `_`.
+ *
+ * @param name - The string to sanitize.
+ * @returns A string that satisfies C# identifier character rules.
+ */
+export function sanitizeCSharpIdentifier(name: string): string {
+  if (name.length === 0) return "_";
+
+  const chars: string[] = [];
+  for (let i = 0; i < name.length; i++) {
+    const ch = name[i];
+    if (i === 0) {
+      if (/[A-Za-z_]/.test(ch)) {
+        chars.push(ch);
+      } else {
+        chars.push("_");
+        // Keep the original char if it's a word char (e.g., digit)
+        if (/\w/.test(ch)) {
+          chars.push(ch);
+        }
+      }
+    } else {
+      chars.push(/\w/.test(ch) ? ch : "_");
+    }
+  }
+  return chars.join("");
+}

package/src/index.ts

@@ -2,6 +2,8 @@ export * from "./access.jsx";
 export * from "./components/index.js";
 export * from "./contexts/format-options.js";
 export * from "./create-library.js";
+export * from "./identifier-utils.js";
+export * from "./keywords.js";
 export * from "./modifiers.js";
 export * from "./name-policy.js";
 export * from "./scopes/index.js";

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));
   });
 }