@alloy-js/csharp 0.23.0-dev.0 → 0.23.0-dev.3

package/package.json

@@ -1,7 +1,11 @@
 {
   "name": "@alloy-js/csharp",
-  "version": "0.23.0-dev.0",
+  "version": "0.23.0-dev.3",
   "description": "Alloy components for CSharp language.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/alloy-framework/alloy.git"
+  },
   "exports": {
     ".": {
       "import": "./dist/src/index.js"
@@ -32,23 +36,23 @@
   "author": "jhendrix@microsoft.com",
   "license": "MIT",
   "dependencies": {
-    "@alloy-js/core": "~0.22.0 || >= 0.23.0-dev.0",
-    "@alloy-js/msbuild": "~0.22.0 || >= 0.23.0-dev.0",
+    "@alloy-js/core": "~0.22.0 || >= 0.23.0-dev.8",
+    "@alloy-js/msbuild": "~0.22.0 || >= 0.23.0-dev.1",
     "change-case": "^5.4.4",
     "marked": "^16.1.1",
     "pathe": "^2.0.3"
   },
   "devDependencies": {
-    "@alloy-js/cli": "~0.22.0 || >= 0.23.0-dev.0",
-    "@alloy-js/rollup-plugin": "~0.1.0 || >= 0.1.1-dev.0",
-    "@alloy-js/typescript": "~0.22.0 || >= 0.23.0-dev.0",
+    "@alloy-js/cli": "~0.22.0 || >= 0.23.0-dev.3",
+    "@alloy-js/rollup-plugin": "~0.1.0 || >= 0.1.1-dev.1",
+    "@alloy-js/typescript": "~0.22.0 || >= 0.23.0-dev.4",
     "@microsoft/api-extractor": "~7.52.8",
     "@rollup/plugin-typescript": "^12.1.2",
     "@types/js-yaml": "^4.0.9",
     "concurrently": "^9.2.0",
     "js-yaml": "^4.1.0",
     "typescript": "^5.8.3",
-    "vitest": "^3.2.4"
+    "vitest": "3.2.4"
   },
   "type": "module",
   "scripts": {

package/src/components/enum/member.tsx

@@ -1,4 +1,10 @@
-import { MemberDeclaration, MemberName, Namekey, Refkey } from "@alloy-js/core";
+import {
+  createSymbol,
+  MemberDeclaration,
+  MemberName,
+  Namekey,
+  Refkey,
+} from "@alloy-js/core";
 import { useCSharpNamePolicy } from "../../name-policy.js";
 import { useNamedTypeScope } from "../../scopes/contexts.js";
 import { CSharpSymbol } from "../../symbols/csharp.js";
@@ -23,10 +29,15 @@ export function EnumMember(props: EnumMemberProps) {
     throw new Error("EnumMember must be used within an EnumDeclaration.");
   }
 
-  const thisEnumValueSymbol = new CSharpSymbol(props.name, symbol.members, {
-    refkeys: props.refkey,
-    namePolicy: useCSharpNamePolicy().for("enum-member"),
-  });
+  const thisEnumValueSymbol = createSymbol(
+    CSharpSymbol,
+    props.name,
+    symbol.members,
+    {
+      refkeys: props.refkey,
+      namePolicy: useCSharpNamePolicy().for("enum-member"),
+    },
+  );
 
   return (
     <MemberDeclaration symbol={thisEnumValueSymbol}>

package/src/components/lexical-scope.tsx

@@ -1,4 +1,9 @@
-import { Scope, ScopePropsWithInfo, ScopePropsWithValue } from "@alloy-js/core";
+import {
+  Scope,
+  ScopePropsWithInfo,
+  ScopePropsWithValue,
+  createScope,
+} from "@alloy-js/core";
 import { useCSharpScope } from "../scopes/contexts.js";
 import { CSharpLexicalScope } from "../scopes/lexical.js";
 
@@ -20,9 +25,15 @@ export function LexicalScope(props: LexicalScopeProps) {
     scope = props.value;
   } else {
     const parentScope = useCSharpScope();
-    scope = new CSharpLexicalScope(props.name ?? "lexical scope", parentScope, {
-      ...props,
-    });
+    scope = createScope(
+      CSharpLexicalScope,
+      props.name ?? "lexical scope",
+      parentScope,
+      {
+        ...props,
+        binder: parentScope?.binder,
+      },
+    );
   }
 
   return <Scope value={scope}>{props.children}</Scope>;

package/src/components/method-scope.tsx

@@ -1,4 +1,9 @@
-import { Scope, ScopePropsWithInfo, ScopePropsWithValue } from "@alloy-js/core";
+import {
+  Scope,
+  ScopePropsWithInfo,
+  ScopePropsWithValue,
+  createScope,
+} from "@alloy-js/core";
 import { useCSharpScope } from "../scopes/contexts.js";
 import { CSharpMethodScope } from "../scopes/method.js";
 
@@ -18,9 +23,15 @@ export function MethodScope(props: MethodScopeProps) {
     scope = props.value;
   } else {
     const parentScope = useCSharpScope();
-    scope = new CSharpMethodScope(props.name ?? "method scope", parentScope, {
-      ...props,
-    });
+    scope = createScope(
+      CSharpMethodScope,
+      props.name ?? "method scope",
+      parentScope,
+      {
+        ...props,
+        binder: parentScope?.binder,
+      },
+    );
   }
 
   return <Scope value={scope}>{props.children}</Scope>;

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

@@ -1,6 +1,15 @@
+import { Attribute } from "#components/attributes/attributes.jsx";
 import { ClassDeclaration } from "#components/class/declaration.jsx";
 import { Namespace } from "#components/namespace/namespace.jsx";
-import { Children, FormatOptions, Indent, Output, Prose } from "@alloy-js/core";
+import {
+  Children,
+  FormatOptions,
+  Indent,
+  List,
+  Output,
+  Prose,
+} from "@alloy-js/core";
+import { Serialization } from "@alloy-js/csharp/global/System/Text/Json";
 import { describe, expect, it } from "vitest";
 import { CSharpFormatOptions } from "../../contexts/format-options.js";
 import { SourceFile } from "./source-file.jsx";
@@ -93,4 +102,29 @@ describe("format options", () => {
          indented 3 spaces
     `);
   });
+
+  it("respect docComment and using (and docComment before using)", () => {
+    expect(
+      <Output>
+        <SourceFile
+          path="Test1.cs"
+          headerComment={"This is a file comment"}
+          header={<Prose>// ---------Some Fake Heder-----------</Prose>}
+        >
+          <List>
+            <Attribute name={Serialization.JsonConverterAttribute} />
+            <ClassDeclaration public name="TestClass1" />
+          </List>
+        </SourceFile>
+      </Output>,
+    ).toRenderTo(`
+      /// This is a file comment
+      // ---------Some Fake Heder-----------
+
+      using System.Text.Json.Serialization;
+      
+      [JsonConverter]
+      public class TestClass1;
+    `);
+  });
 });

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

@@ -1,3 +1,4 @@
+import { DocComment } from "#components/doc/comment.jsx";
 import { NamespaceScopes } from "#components/namespace-scopes.jsx";
 import { NamespaceName } from "#components/namespace/namespace-name.jsx";
 import { Reference } from "#components/Reference.jsx";
@@ -7,7 +8,10 @@ import {
   Children,
   computed,
   SourceFile as CoreSourceFile,
+  createScope,
+  List,
   Scope,
+  Show,
   useBinder,
 } from "@alloy-js/core";
 import {
@@ -34,14 +38,26 @@ export interface SourceFileProps extends CSharpFormatOptions {
    * explicit usings is not necessary when referencing symbols via refkeys.
    */
   using?: string[];
+  /* * Optional header content to include at the top of the file */
+  header?: Children;
+  /* * Optional doc comment to include at the top of the file, this will be before 'header' if both are provided */
+  headerComment?: string;
 }
 
 /** A C# source file exists within the context of a namespace contains using statements and declarations */
 export function SourceFile(props: SourceFileProps) {
-  const sourceFileScope = new CSharpSourceFileScope(props.path);
+  const binder = useBinder();
+  const sourceFileScope = createScope(
+    CSharpSourceFileScope,
+    props.path,
+    undefined,
+    {
+      binder,
+    },
+  );
 
   const nsContext = useNamespaceContext();
-  const globalNs = getGlobalNamespace(useBinder());
+  const globalNs = getGlobalNamespace(binder);
   const nsSymbol = nsContext ? nsContext.symbol : globalNs;
   const usings = computed(() => {
     return (
@@ -59,12 +75,21 @@ export function SourceFile(props: SourceFileProps) {
     useTabs: props.useTabs,
   });
 
+  const header =
+    props.header || props.headerComment ?
+      <SourceFileHeader
+        header={props.header}
+        headerComment={props.headerComment}
+      />
+    : undefined;
+
   return (
     <CoreSourceFile
       path={props.path}
       filetype="cs"
       reference={Reference}
       {...opts}
+      header={header}
     >
       <Scope value={sourceFileScope}>
         {(sourceFileScope.usings.size > 0 ||
@@ -96,3 +121,20 @@ export function SourceFile(props: SourceFileProps) {
     </CoreSourceFile>
   );
 }
+
+interface SourceFileHeaderProps {
+  header?: Children;
+  headerComment?: string;
+}
+
+function SourceFileHeader(props: SourceFileHeaderProps) {
+  return (
+    <List>
+      <Show when={props.headerComment !== undefined}>
+        <DocComment>{props.headerComment}</DocComment>
+      </Show>
+      <Show when={props.header !== undefined}>{props.header}</Show>
+      <hbr />
+    </List>
+  );
+}

package/src/contexts/global-namespace.ts

@@ -1,4 +1,4 @@
-import { Binder, useBinder } from "@alloy-js/core";
+import { Binder, createSymbol, useBinder } from "@alloy-js/core";
 import { NamespaceSymbol } from "../symbols/namespace.js";
 
 export function useGlobalNamespace() {
@@ -7,12 +7,17 @@ export function useGlobalNamespace() {
 }
 
 const globalNamespaces = new WeakMap<Binder, NamespaceSymbol>();
-let defaultGlobalNamespace = new NamespaceSymbol("global", undefined, {
-  isGlobal: true,
-});
+let defaultGlobalNamespace = createSymbol(
+  NamespaceSymbol,
+  "global",
+  undefined,
+  {
+    isGlobal: true,
+  },
+);
 
 export function resetGlobalNamespace() {
-  defaultGlobalNamespace = new NamespaceSymbol("global", undefined, {
+  defaultGlobalNamespace = createSymbol(NamespaceSymbol, "global", undefined, {
     isGlobal: true,
   });
 }
@@ -25,7 +30,7 @@ export function getGlobalNamespace(binder: Binder | undefined) {
   let namespace = globalNamespaces.get(binder);
 
   if (!namespace) {
-    namespace = new NamespaceSymbol("global", undefined, {
+    namespace = createSymbol(NamespaceSymbol, "global", undefined, {
       binder,
       isGlobal: true,
     });

package/src/create-library.ts

@@ -1,5 +1,6 @@
 import {
   Binder,
+  createSymbol,
   LibrarySymbolReference,
   namekey,
   refkey,
@@ -124,10 +125,15 @@ export function createLibrary<T extends Record<string, Descriptor>>(
                 name,
               )! as NamespaceSymbol;
             } else {
-              ownerSymbol = new NamespaceSymbol(namekey(name), ownerSymbol!, {
-                binder,
-                refkeys: refkey(),
-              });
+              ownerSymbol = createSymbol(
+                NamespaceSymbol,
+                namekey(name),
+                ownerSymbol!,
+                {
+                  binder,
+                  refkeys: refkey(),
+                },
+              );
             }
           }
 
@@ -214,7 +220,8 @@ function createSymbolFromDescriptor(
       if (ownerSymbol.members.symbolNames.has(name)) {
         return ownerSymbol.members.symbolNames.get(name)! as NamespaceSymbol;
       }
-      return new NamespaceSymbol(
+      return createSymbol(
+        NamespaceSymbol,
         namekey(name),
         ownerSymbol as NamespaceSymbol,
         {
@@ -228,7 +235,8 @@ function createSymbolFromDescriptor(
     case "interface":
     case "struct":
     case "record":
-      return new NamedTypeSymbol(
+      return createSymbol(
+        NamedTypeSymbol,
         namekey(name),
         ownerSymbol.members,
         descriptor.kind,
@@ -239,7 +247,8 @@ function createSymbolFromDescriptor(
         },
       );
     case "method":
-      return new MethodSymbol(
+      return createSymbol(
+        MethodSymbol,
         namekey(name),
         ownerSymbol.members,
         descriptor.methodKind,
@@ -250,7 +259,7 @@ function createSymbolFromDescriptor(
       );
     case "field":
     case "property":
-      return new CSharpSymbol(namekey(name), ownerSymbol.members, {
+      return createSymbol(CSharpSymbol, namekey(name), ownerSymbol.members, {
         binder,
         refkeys: refkey(),
         type:
@@ -262,7 +271,7 @@ function createSymbolFromDescriptor(
         lazyMemberInitializer,
       });
     case "generic":
-      return new CSharpSymbol(namekey(name), ownerSymbol.members, {
+      return createSymbol(CSharpSymbol, namekey(name), ownerSymbol.members, {
         binder,
         refkeys: refkey(),
       });

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

package/src/symbols/named-type.ts

@@ -1,4 +1,4 @@
-import { Namekey, OutputSpace } from "@alloy-js/core";
+import { Namekey, OutputSpace, createSymbol } from "@alloy-js/core";
 import { CSharpSymbol, CSharpSymbolOptions } from "./csharp.js";
 
 // represents a symbol from a .cs file. Class, enum, interface etc.
@@ -38,11 +38,16 @@ export class NamedTypeSymbol extends CSharpSymbol {
 
   copy() {
     const options = this.getCopyOptions();
-    const copy = new NamedTypeSymbol(
+    const binder = this.binder;
+    const copy = createSymbol(
+      NamedTypeSymbol,
       this.name,
       undefined,
       this.#typeKind,
-      options,
+      {
+        ...options,
+        binder,
+      },
     );
     this.initializeCopy(copy);
     return copy;
@@ -51,4 +56,11 @@ export class NamedTypeSymbol extends CSharpSymbol {
   get members() {
     return this.memberSpaceFor("members")!;
   }
+
+  override get debugInfo(): Record<string, unknown> {
+    return {
+      ...super.debugInfo,
+      typeKind: this.typeKind,
+    };
+  }
 }