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

package/docs/api/contexts/csharp-context.md

@@ -0,0 +1,21 @@
+# csharp context
+
+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.
+
+```ts
+const csharpContextualKeywords: ReadonlySet<string>
+```
+
+## Accessor
+
+```ts
+const myContext = useContext(csharpContext);
+```
+
+## Context interface
+
+string
+
+## See also
+
+* <https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/keywords/#contextual-keywords>

package/docs/api/contexts/index.md

@@ -0,0 +1,3 @@
+# csharp — contexts
+
+- [csharp context](csharp-context.md) — C# contextual keywords that are reserved in certain contexts.

package/docs/api/functions/createCSharpNamePolicy.md

@@ -1,5 +1,9 @@
 # createCSharpNamePolicy
 
+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 `@`.
+
 ```ts
 import { createCSharpNamePolicy } from "@alloy-js/csharp";
 

package/docs/api/functions/index.md

@@ -4,7 +4,7 @@
 - [accessibilityFromProps](accessibilityFromProps.md) — import { accessibilityFromProps } from "@alloy-js/csharp";
 - [computeModifiersPrefix](computeModifiersPrefix.md) — Resolve the modifier prefix
 - [createClassScope](createClassScope.md) — import { createClassScope } from "@alloy-js/csharp";
-- [createCSharpNamePolicy](createCSharpNamePolicy.md) — import { createCSharpNamePolicy } from "@alloy-js/csharp";
+- [createCSharpNamePolicy](createCSharpNamePolicy.md) — Creates the C# naming policy with case conversion and keyword escaping.
 - [createCSharpNamespaceScope](createCSharpNamespaceScope.md) — import { createCSharpNamespaceScope } from "@alloy-js/csharp";
 - [createFieldSymbol](createFieldSymbol.md) — import { createFieldSymbol } from "@alloy-js/csharp";
 - [createLibrary](createLibrary.md) — import { createLibrary } from "@alloy-js/csharp";
@@ -19,9 +19,13 @@
 - [createVariableSymbol](createVariableSymbol.md) — import { createVariableSymbol } from "@alloy-js/csharp";
 - [getAccessModifier](getAccessModifier.md) — import { getAccessModifier } from "@alloy-js/csharp";
 - [getAsyncModifier](getAsyncModifier.md) — import { getAsyncModifier } from "@alloy-js/csharp";
+- [isCSharpContextualKeyword](isCSharpContextualKeyword.md) — Returns true if the given name is a C# contextual keyword.
+- [isCSharpKeyword](isCSharpKeyword.md) — Returns true if the given name is a C# reserved keyword.
+- [isValidCSharpIdentifier](isValidCSharpIdentifier.md) — Checks whether the provided name is a valid C# identifier (without `@` prefix).
 - [makeModifiers](makeModifiers.md) — import { makeModifiers } from "@alloy-js/csharp";
 - [nonAccessibilityFromProps](nonAccessibilityFromProps.md) — import { nonAccessibilityFromProps } from "@alloy-js/csharp";
 - [ref](ref.md) — import { ref } from "@alloy-js/csharp";
+- [sanitizeCSharpIdentifier](sanitizeCSharpIdentifier.md) — Transforms an arbitrary string into a valid C# identifier by replacing invalid characters.
 - [useCsharpFormatOptions](useCsharpFormatOptions.md) — import { useCsharpFormatOptions } from "@alloy-js/csharp";
 - [useCSharpNamePolicy](useCSharpNamePolicy.md) — import { useCSharpNamePolicy } from "@alloy-js/csharp";
 - [useCSharpScope](useCSharpScope.md) — import { useCSharpScope } from "@alloy-js/csharp";

package/docs/api/functions/isCSharpContextualKeyword.md

@@ -0,0 +1,20 @@
+# isCSharpContextualKeyword
+
+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.
+
+```ts
+import { isCSharpContextualKeyword } from "@alloy-js/csharp";
+
+
+function isCSharpContextualKeyword(name: string): boolean;
+```
+
+## Parameters
+
+|      |        |   |
+| ---- | ------ | - |
+| name | string |   |
+
+## Returns
+
+boolean

package/docs/api/functions/isCSharpKeyword.md

@@ -0,0 +1,22 @@
+# isCSharpKeyword
+
+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 [isCSharpContextualKeyword](../iscsharpcontextualkeyword/) to check contextual keywords separately.
+
+```ts
+import { isCSharpKeyword } from "@alloy-js/csharp";
+
+
+function isCSharpKeyword(name: string): boolean;
+```
+
+## Parameters
+
+|      |        |   |
+| ---- | ------ | - |
+| name | string |   |
+
+## Returns
+
+boolean

package/docs/api/functions/isValidCSharpIdentifier.md

@@ -0,0 +1,20 @@
+# isValidCSharpIdentifier
+
+Checks whether the provided name is a valid C# identifier (without `@` prefix). Does not account for keyword conflicts — use [isCSharpKeyword](../iscsharpkeyword/) for that.
+
+```ts
+import { isValidCSharpIdentifier } from "@alloy-js/csharp";
+
+
+function isValidCSharpIdentifier(name: string): boolean;
+```
+
+## Parameters
+
+|      |        |   |
+| ---- | ------ | - |
+| name | string |   |
+
+## Returns
+
+boolean true if the name matches C# identifier rules (letter or underscore start, word chars after).

package/docs/api/functions/sanitizeCSharpIdentifier.md

@@ -0,0 +1,24 @@
+# sanitizeCSharpIdentifier
+
+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 `_`.
+
+```ts
+import { sanitizeCSharpIdentifier } from "@alloy-js/csharp";
+
+
+function sanitizeCSharpIdentifier(name: string): string;
+```
+
+## Parameters
+
+|      |        |   |
+| ---- | ------ | - |
+| name | string |   |
+
+## Returns
+
+string A string that satisfies C# identifier character rules.

package/docs/api/index.md

@@ -1,6 +1,7 @@
 # @alloy-js/csharp API Reference
 
 - [components](components/index.md) (53 items)
-- [functions](functions/index.md) (31 items)
+- [contexts](contexts/index.md) (1 items)
+- [functions](functions/index.md) (35 items)
 - [types](types/index.md) (60 items)
-- [variables](variables/index.md) (1 items)
+- [variables](variables/index.md) (2 items)

package/docs/api/variables/csharpKeywords.md

@@ -0,0 +1,11 @@
+# csharpKeywords
+
+C# reserved keywords that cannot be used as identifiers without `@` prefix. These are case-sensitive in C#.
+
+```ts
+csharpKeywords: ReadonlySet<string>
+```
+
+## See also
+
+* <https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/keywords/>

package/docs/api/variables/index.md

@@ -1,3 +1,4 @@
 # csharp — variables
 
 - [Attribute](Attribute.md) — Render a csharp attribute.
+- [csharpKeywords](csharpKeywords.md) — C# reserved keywords that cannot be used as identifiers without `@` prefix.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alloy-js/csharp",
-  "version": "0.23.0-dev.10",
+  "version": "0.23.0-dev.11",
   "description": "Alloy components for CSharp language.",
   "repository": {
     "type": "git",
@@ -43,7 +43,7 @@
   "author": "jhendrix@microsoft.com",
   "license": "MIT",
   "dependencies": {
-    "@alloy-js/core": "~0.22.0 || >= 0.23.0-dev.16",
+    "@alloy-js/core": "~0.22.0 || >= 0.23.0-dev.18",
     "@alloy-js/msbuild": "~0.22.0 || >= 0.23.0-dev.2",
     "change-case": "^5.4.4",
     "marked": "^16.1.1",
@@ -52,7 +52,7 @@
   "devDependencies": {
     "@alloy-js/cli": "~0.22.0 || >= 0.23.0-dev.6",
     "@alloy-js/rollup-plugin": "~0.1.0 || >= 0.1.1-dev.2",
-    "@alloy-js/typescript": "~0.22.0 || >= 0.23.0-dev.9",
+    "@alloy-js/typescript": "~0.22.0 || >= 0.23.0-dev.10",
     "@microsoft/api-extractor": "~7.52.8",
     "@rollup/plugin-typescript": "^12.1.2",
     "@types/js-yaml": "^4.0.9",

package/src/components/method/method.test.tsx

@@ -207,3 +207,39 @@ describe("format", () => {
   `);
   });
 });
+
+describe("name policy deduplication", () => {
+  it("deduplicates parameters that collide after case conversion", () => {
+    const params = [
+      { name: "my-param", type: "int" },
+      { name: "myParam", type: "string" },
+    ];
+    expect(
+      <Wrapper>
+        <Method public name="MethodOne" parameters={params} />
+      </Wrapper>,
+    ).toRenderTo(`
+      public class TestClass
+      {
+          public void MethodOne(int myParam, string myParam_2) {}
+      }
+    `);
+  });
+
+  it("deduplicates parameters that are keywords", () => {
+    const params = [
+      { name: "string", type: "int" },
+      { name: "string", type: "bool" },
+    ];
+    expect(
+      <Wrapper>
+        <Method public name="MethodOne" parameters={params} />
+      </Wrapper>,
+    ).toRenderTo(`
+      public class TestClass
+      {
+          public void MethodOne(int @string, bool string_2) {}
+      }
+    `);
+  });
+});

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