@alloy-js/csharp 0.1.0

package/src/components/Class.tsx

@@ -0,0 +1,210 @@
+import * as core from "@alloy-js/core";
+import {
+  AccessModifier,
+  getAccessModifier,
+  getMethodModifier,
+  MethodModifier,
+} from "../modifiers.js";
+import { CSharpElements, useCSharpNamePolicy } from "../name-policy.js";
+import { CSharpOutputSymbol } from "../symbols/csharp-output-symbol.js";
+import { createCSharpMemberScope, useCSharpScope } from "../symbols/scopes.js";
+import { Name } from "./Name.js";
+import { ParameterProps, Parameters } from "./Parameters.js";
+
+// properties for creating a class
+export interface ClassProps extends Omit<core.DeclarationProps, "nameKind"> {
+  name: string;
+  accessModifier?: AccessModifier;
+  typeParameters?: Record<string, core.Refkey>;
+}
+
+// a C# class declaration
+export function Class(props: ClassProps) {
+  const name = useCSharpNamePolicy().getName(props.name!, "class");
+  const scope = useCSharpScope();
+
+  const thisClassSymbol = scope.binder.createSymbol<CSharpOutputSymbol>({
+    name: name,
+    scope,
+    refkey: props.refkey ?? core.refkey(props.name),
+  });
+
+  // this creates a new scope for the class definition.
+  // members will automatically "inherit" this scope so
+  // that refkeys to them will produce the fully-qualified
+  // name e.g. Foo.Bar.
+  const thisClassScope = createCSharpMemberScope(
+    scope.binder,
+    scope,
+    thisClassSymbol,
+    "class-decl",
+  );
+
+  let typeParams: string | undefined;
+  if (props.typeParameters) {
+    const typeParamNames = new Array<string>();
+    for (const entry of Object.entries(props.typeParameters)) {
+      typeParamNames.push(
+        useCSharpNamePolicy().getName(entry[0], "type-parameter"),
+      );
+      // create a symbol for each type param so its
+      // refkey resolves to the type param's name
+      scope.binder.createSymbol<CSharpOutputSymbol>({
+        name: entry[0],
+        scope: thisClassScope,
+        refkey: entry[1],
+      });
+    }
+    typeParams = `<${typeParamNames.join(", ")}>`;
+  }
+
+  return <core.Declaration symbol={thisClassSymbol}>
+      {getAccessModifier(props.accessModifier)}class <Name />{typeParams}{!props.children && ";"}{props.children &&
+        <>
+          {"\n{"}
+            <core.Scope value={thisClassScope}>
+              {props.children}
+            </core.Scope>
+          {"}"}
+        </>
+        }
+    </core.Declaration>;
+}
+
+export interface ClassConstructorProps {
+  accessModifier?: AccessModifier;
+  parameters?: Array<ParameterProps>;
+  refkey?: core.Refkey;
+  symbol?: core.OutputSymbol;
+  children?: core.Children;
+}
+
+// a C# class constructor
+export function ClassConstructor(props: ClassConstructorProps) {
+  const scope = useCSharpScope();
+  if (scope.kind !== "member" || scope.name !== "class-decl") {
+    throw new Error(
+      "can't define a class constructor outside of a class-decl scope",
+    );
+  }
+
+  // fetch the class name from the scope
+  const name = useCSharpNamePolicy().getName(scope.owner.name, "class-method");
+  const ctorSymbol = scope.binder.createSymbol<CSharpOutputSymbol>({
+    name: name,
+    scope,
+    refkey: props.refkey ?? core.refkey(name),
+  });
+
+  // scope for ctor declaration
+  const ctorDeclScope = createCSharpMemberScope(
+    scope.binder,
+    scope,
+    ctorSymbol,
+    "constructor-decl",
+  );
+
+  const accessModifier = getAccessModifier(props.accessModifier);
+  const params = props.parameters ?
+    <Parameters parameters={props.parameters} />
+  : "";
+
+  // note that scope wraps the ctor decl so that the params get the correct scope
+  return <core.Declaration symbol={ctorSymbol}>
+    <core.Scope value={ctorDeclScope}>
+      {accessModifier}<Name />({params}){!props.children && " {}"}{props.children &&
+        <>
+          {"\n{"}
+            {props.children}
+          {"}"}
+        </>
+        }
+      </core.Scope>
+    </core.Declaration>;
+}
+
+// properties for creating a class member
+export interface ClassMemberProps {
+  name: string;
+  type: core.Children;
+  accessModifier?: AccessModifier;
+  refkey?: core.Refkey;
+}
+
+// a C# class member (i.e. a field within a class like "private int count")
+export function ClassMember(props: ClassMemberProps) {
+  let nameElement: CSharpElements = "class-member-private";
+  if (props.accessModifier === "public") {
+    nameElement = "class-member-public";
+  }
+  const name = useCSharpNamePolicy().getName(props.name, nameElement);
+  const scope = useCSharpScope();
+  if (scope.kind !== "member" || scope.name !== "class-decl") {
+    throw new Error(
+      "can't define a class member outside of a class-decl scope",
+    );
+  }
+
+  const memberSymbol = scope.binder.createSymbol<CSharpOutputSymbol>({
+    name: name,
+    scope,
+    refkey: props.refkey ?? core.refkey(props.name),
+  });
+
+  return <core.Declaration symbol={memberSymbol}>
+      {getAccessModifier(props.accessModifier)}{props.type} <Name />;
+    </core.Declaration>;
+}
+
+// properties for creating a method
+export interface ClassMethodProps
+  extends Omit<core.DeclarationProps, "nameKind"> {
+  name: string;
+  accessModifier?: AccessModifier;
+  methodModifier?: MethodModifier;
+  parameters?: Array<ParameterProps>;
+  returns?: core.Children;
+}
+
+// a C# class method
+export function ClassMethod(props: ClassMethodProps) {
+  const name = useCSharpNamePolicy().getName(props.name!, "class-method");
+  const scope = useCSharpScope();
+  if (scope.kind !== "member" || scope.name !== "class-decl") {
+    throw new Error("can't define a class method outside of a class scope");
+  }
+
+  const methodSymbol = scope.binder.createSymbol<CSharpOutputSymbol>({
+    name: name,
+    scope,
+    refkey: props.refkey ?? core.refkey(props.name),
+  });
+
+  // scope for method declaration
+  const methodScope = createCSharpMemberScope(
+    scope.binder,
+    scope,
+    methodSymbol,
+    "method-decl",
+  );
+
+  const accessModifier = getAccessModifier(props.accessModifier);
+  const methodModifier = getMethodModifier(props.methodModifier);
+  const params = props.parameters ?
+    <Parameters parameters={props.parameters} />
+  : "";
+  const returns = props.returns ?? "void";
+
+  // note that scope wraps the method decl so that the params get the correct scope
+  return <core.Declaration symbol={methodSymbol}>
+    <core.Scope value={methodScope}>
+      {accessModifier}{methodModifier}{returns} <Name />({params}){!props.children && " {}"}{props.children &&
+        <>
+          {"\n{"}
+            {props.children}
+          {"}"}
+        </>
+        }
+      </core.Scope>
+    </core.Declaration>;
+}

package/src/components/Declaration.tsx

@@ -0,0 +1,17 @@
+import * as core from "@alloy-js/core";
+import { createCSharpSymbol } from "../symbols/csharp-output-symbol.js";
+
+// properties for creating a declaration
+export interface DeclarationProps {
+  name: string;
+  refkey?: core.Refkey;
+  children?: core.Children;
+}
+
+// declares a symbol in the program (class, enum, interface etc)
+export function Declaration(props: DeclarationProps) {
+  const sym = createCSharpSymbol(props);
+  return <core.Declaration symbol={sym}>
+    {props.children}
+  </core.Declaration>;
+}

package/src/components/Enum.tsx

@@ -0,0 +1,74 @@
+import * as core from "@alloy-js/core";
+import { AccessModifier, getAccessModifier } from "../modifiers.js";
+import { useCSharpNamePolicy } from "../name-policy.js";
+import { CSharpOutputSymbol } from "../symbols/csharp-output-symbol.js";
+import { createCSharpMemberScope, useCSharpScope } from "../symbols/scopes.js";
+import { Name } from "./Name.jsx";
+
+// properties for creating an enum
+export interface EnumProps extends Omit<core.DeclarationProps, "nameKind"> {
+  name: string;
+  accessModifier?: AccessModifier;
+}
+
+// a C# enum declaration
+export function Enum(props: EnumProps) {
+  const name = useCSharpNamePolicy().getName(props.name!, "enum");
+  const scope = useCSharpScope();
+
+  const thisEnumSymbol = scope.binder.createSymbol<CSharpOutputSymbol>({
+    name: name,
+    scope,
+    refkey: props.refkey ?? core.refkey(props.name),
+  });
+
+  // this creates a new scope for the enum definition.
+  // members will automatically "inherit" this scope so
+  // that refkeys to them will produce the fully-qualified
+  // name e.g. Foo.Bar.
+  const thisEnumScope = createCSharpMemberScope(
+    scope.binder,
+    scope,
+    thisEnumSymbol,
+    "enum-decl",
+  );
+
+  return <core.Declaration symbol={thisEnumSymbol}>
+      {getAccessModifier(props.accessModifier)}enum <Name />{!props.children && ";"}{props.children && 
+        <>
+          {"\n{"}
+            <core.Scope value={thisEnumScope}>
+              {props.children}
+            </core.Scope>
+          {"}"}
+        </>
+        }
+    </core.Declaration>;
+}
+
+// properties for creating a C# enum member
+export interface EnumMemberProps {
+  name: string;
+  refkey?: core.Refkey;
+}
+
+// a member within a C# enum
+export function EnumMember(props: EnumMemberProps) {
+  const scope = useCSharpScope();
+  if (scope.kind === "member" && scope.name !== "enum-decl") {
+    throw new Error(
+      "can't define an enum member outside of an enum-decl scope",
+    );
+  }
+
+  const name = useCSharpNamePolicy().getName(props.name, "enum-member");
+  const thisEnumValueSymbol = scope.binder.createSymbol<CSharpOutputSymbol>({
+    name: name,
+    scope,
+    refkey: props.refkey ?? core.refkey(props.name),
+  });
+
+  return <core.Declaration symbol={thisEnumValueSymbol}>
+      <Name />
+    </core.Declaration>;
+}

package/src/components/Name.tsx

@@ -0,0 +1,11 @@
+import * as core from "@alloy-js/core";
+
+// the name within the current declaration
+export function Name() {
+  const declSymbol = core.useContext(core.DeclarationContext);
+  if (!declSymbol) {
+    throw new Error("missing declaration context");
+  }
+
+  return <>{declSymbol.name}</>;
+}

package/src/components/Namespace.tsx

@@ -0,0 +1,39 @@
+import * as core from "@alloy-js/core";
+import { createCSharpNamespaceScope } from "../symbols/scopes.js";
+
+// contains the info for the current namespace
+export interface NamespaceContext {
+  name: string;
+}
+
+const NamespaceContext = core.createContext<NamespaceContext>();
+
+// returns the current namespace
+export function useNamespace(): NamespaceContext | undefined {
+  return core.useContext(NamespaceContext) as NamespaceContext;
+}
+
+// properties for creating a C# namespace
+export interface NamespaceProps {
+  name: string;
+  children?: core.Children;
+}
+
+// a C# namespace. contains one or more source files
+export function Namespace(props: NamespaceProps) {
+  const scope = createCSharpNamespaceScope(
+    core.useBinder(),
+    core.useScope(),
+    props.name,
+  );
+
+  const namespaceCtx: NamespaceContext = {
+    name: props.name,
+  };
+
+  return <NamespaceContext.Provider value={namespaceCtx}>
+      <core.Scope value={scope}>
+        {props.children}
+      </core.Scope>
+    </NamespaceContext.Provider>;
+}

package/src/components/Parameters.tsx

@@ -0,0 +1,52 @@
+import * as core from "@alloy-js/core";
+import { useCSharpNamePolicy } from "../name-policy.js";
+import { CSharpOutputSymbol } from "../symbols/csharp-output-symbol.js";
+import { useCSharpScope } from "../symbols/scopes.js";
+import { Name } from "./Name.js";
+
+export interface ParameterProps {
+  name: string;
+  type: core.Children;
+  refkey?: core.Refkey;
+  symbol?: core.OutputSymbol;
+}
+
+// a constructor/method parameter
+export function Parameter(props: ParameterProps) {
+  const name = useCSharpNamePolicy().getName(props.name, "parameter");
+  const scope = useCSharpScope();
+  if (
+    scope.kind !== "member" ||
+    (scope.name !== "constructor-decl" && scope.name !== "method-decl")
+  ) {
+    throw new Error(
+      "can't define a parameter outside of a constructor-decl or method-decl scope",
+    );
+  }
+
+  const memberSymbol = scope.binder.createSymbol<CSharpOutputSymbol>({
+    name: name,
+    scope,
+    refkey: props.refkey ?? core.refkey(props.name),
+  });
+
+  return <core.Declaration symbol={memberSymbol}>
+      {props.type} <Name />
+    </core.Declaration>;
+}
+
+export interface ParametersProps {
+  // param name and type
+  parameters: Array<ParameterProps>;
+}
+
+// a collection of parameters
+export function Parameters(props: ParametersProps): Array<core.Child | string> {
+  return core.mapJoin(
+    props.parameters,
+    (param) => {
+      return <Parameter {...param} />;
+    },
+    { joiner: ", " },
+  );
+}

package/src/components/ProjectDirectory.tsx

@@ -0,0 +1,54 @@
+import * as core from "@alloy-js/core";
+import { join } from "pathe";
+
+// properties for creating the project directory
+export interface ProjectDirectoryProps {
+  // the name of the project directory
+  name: string;
+
+  // the semver of the project
+  version: string;
+
+  // project description
+  description: string;
+
+  // parent path where the project directory will be created
+  path: string;
+
+  // directory name for source files. defaults to "src"
+  srcDir?: string;
+
+  // the .NET TFM for this project. defaults to net8.0
+  targetFrameworkMoniker?: string;
+
+  // child components of the project
+  children?: core.Children;
+}
+
+// the top-level C# project directory. includes a csproj file
+export function ProjectDirectory(props: ProjectDirectoryProps) {
+  if (!props.srcDir) {
+    props.srcDir = "src";
+  }
+
+  if (!props.targetFrameworkMoniker) {
+    props.targetFrameworkMoniker = "net8.0";
+  }
+
+  return <core.SourceDirectory path={join(props.path, props.name)}>
+    <core.SourceFile path={props.name+".csproj"} filetype="xml">
+      {core.code`
+        <Project Sdk="Microsoft.NET.Sdk">
+          <PropertyGroup>
+            <Version>${props.version}</Version>
+            <Description>${props.description}</Description>
+            <TargetFramework>${props.targetFrameworkMoniker}</TargetFramework>
+          </PropertyGroup>
+        </Project>
+      `}
+    </core.SourceFile>
+    <core.SourceDirectory path={props.srcDir}>
+      {props.children}
+    </core.SourceDirectory>
+  </core.SourceDirectory>;
+}

package/src/components/Reference.tsx

@@ -0,0 +1,13 @@
+import * as core from "@alloy-js/core";
+import { ref } from "../symbols/reference.js";
+
+export interface ReferenceProps {
+  refkey: core.Refkey;
+}
+
+// used to resolve refkey references within source files
+export function Reference({ refkey }: ReferenceProps) {
+  const reference = ref(refkey);
+
+  return <>{reference}</>;
+}

package/src/components/SourceFile.tsx

@@ -0,0 +1,69 @@
+import * as core from "@alloy-js/core";
+import { useNamespace } from "./Namespace.jsx";
+import { Reference } from "./Reference.jsx";
+import { UsingDirective } from "./UsingDirective.jsx";
+
+// contains the info for the current source file
+export interface SourceFileContext {
+  // adds a namespace to the array of using statements
+  addUsing(namespace: string): void;
+}
+
+const SourceFileContext = core.createContext<SourceFileContext>();
+
+// returns the current source file
+export function useSourceFile(): SourceFileContext | undefined {
+  return core.useContext(SourceFileContext) as SourceFileContext;
+}
+
+// properties fro creating a C# source file
+export interface SourceFileProps {
+  path: string;
+  using?: Array<string>;
+  children?: core.Children;
+}
+
+// a C# source file. exists within the context of a namespace
+// contains using statements and declarations
+export function SourceFile(props: SourceFileProps) {
+  const namespaceCtx = useNamespace();
+
+  if (!namespaceCtx) {
+    throw new Error("SourceFile must be declared inside a namespace");
+  }
+
+  const using: Array<string> = core.reactive(new Array<string>());
+  if (props.using) {
+    using.push(...props.using);
+  }
+
+  // adds the specified namespace to the array of using statements.
+  // called via SourceFileContext.addUsing when resolving refkeys.
+  function addUsing(namespace: string): void {
+    if (!using.includes(namespace)) {
+      using.push(namespace);
+    }
+  }
+
+  const sourceFileCtx: SourceFileContext = {
+    addUsing,
+  };
+
+  return <core.SourceFile path={props.path} filetype="cs" reference={Reference}>
+      <SourceFileContext.Provider value={sourceFileCtx}>
+        <core.Scope name={props.path} kind="source-file">
+          {using.length > 0 ? (
+            <>
+              <UsingDirective namespaces={using} />{"\n"}
+            </>
+          ) : undefined}namespace {namespaceCtx.name}{!props.children && " {}"}{props.children && 
+            <>
+              {"\n{"}
+                {props.children}
+              {"}"}
+            </>
+          }
+        </core.Scope>
+      </SourceFileContext.Provider>
+    </core.SourceFile>;
+}

package/src/components/UsingDirective.tsx

@@ -0,0 +1,19 @@
+import * as core from "@alloy-js/core";
+
+export interface UsingDirectiveProps {
+  namespaces: Array<string>;
+}
+
+// one ore more C# using directives
+export function UsingDirective(props: UsingDirectiveProps) {
+  // we need core.memo here so that the contents are in a reactive context.
+  // the values for namespaces are reactive thus we need to observe any changes.
+  return core.memo(() => {
+    props.namespaces.sort();
+    return core
+      .mapJoin(props.namespaces, (namespace) => {
+        return `using ${namespace};`;
+      })
+      .join("");
+  });
+}

package/src/components/index.ts

@@ -0,0 +1,10 @@
+export * from "./Class.js";
+export * from "./Declaration.js";
+export * from "./Enum.js";
+export * from "./Name.js";
+export * from "./Namespace.js";
+export * from "./Parameters.js";
+export * from "./ProjectDirectory.js";
+export * from "./Reference.js";
+export * from "./SourceFile.js";
+export * from "./UsingDirective.js";

package/src/components/stc/index.ts

@@ -0,0 +1,13 @@
+import * as core from "@alloy-js/core";
+import * as base from "../index.js";
+
+export const Class = core.stc(base.Class);
+export const ClassConstructor = core.stc(base.ClassConstructor);
+export const ClassMember = core.stc(base.ClassMember);
+export const ClassMethod = core.stc(base.ClassMethod);
+export const Enum = core.stc(base.Enum);
+export const EnumMember = core.stc(base.EnumMember);
+export const Parameter = core.stc(base.Parameter);
+export const Parameters = core.stc(base.Parameters);
+export const ProjectDirectory = core.stc(base.ProjectDirectory);
+export const UsingDirective = core.stc(base.UsingDirective);

package/src/index.ts

@@ -0,0 +1,4 @@
+export * from "./components/index.js";
+export * from "./modifiers.js";
+export * from "./name-policy.js";
+export * from "./symbols/index.js";

package/src/modifiers.ts

@@ -0,0 +1,45 @@
+// the possible C# access modifiers
+// https://learn.microsoft.com/dotnet/csharp/programming-guide/classes-and-structs/access-modifiers
+export type AccessModifier =
+  | "public"
+  | "protected"
+  | "private"
+  | "internal"
+  | "protected-internal"
+  | "private-protected"
+  | "file";
+
+// maps the above access modifier value to its C# syntax.
+// note that the C# keyword includes a trailing space
+const accessModifierLookup: Record<AccessModifier, string> = {
+  public: "public ",
+  protected: "protected ",
+  private: "private ",
+  internal: "internal ",
+  "protected-internal": "protected internal ",
+  "private-protected": "private protected ",
+  file: "file ",
+};
+
+// returns the C# syntax for the specified access modifier.
+// if no access modifier is specified, the empty string is returned.
+export function getAccessModifier(accessModifier?: AccessModifier): string {
+  return accessModifier ? accessModifierLookup[accessModifier] : "";
+}
+
+export type MethodModifier = "abstract" | "sealed" | "static" | "virtual";
+
+// maps the above method modifier value to its C# syntax.
+// note that the C# keyword includes a trailing space
+const methodModifierLookup: Record<MethodModifier, string> = {
+  abstract: "abstract ",
+  sealed: "sealed ",
+  static: "static ",
+  virtual: "virtual ",
+};
+
+// returns the C# syntax for the specified method modifier.
+// if no method modifier is specified, the empty string is returned.
+export function getMethodModifier(methodModifier?: MethodModifier): string {
+  return methodModifier ? methodModifierLookup[methodModifier] : "";
+}

package/src/name-policy.ts

@@ -0,0 +1,41 @@
+import * as core from "@alloy-js/core";
+import * as changecase from "change-case";
+
+// the context in which the name policy should be applied
+export type CSharpElements =
+  | "class"
+  | "constant"
+  | "enum"
+  | "enum-member"
+  | "function"
+  | "interface"
+  | "class-member-private"
+  | "class-member-public"
+  | "class-method"
+  | "parameter"
+  | "type-parameter";
+
+// creates the C# naming policy
+export function createCSharpNamePolicy(): core.NamePolicy<CSharpElements> {
+  return core.createNamePolicy((name, element) => {
+    switch (element) {
+      case "class":
+      case "enum":
+      case "enum-member":
+      case "interface":
+      case "class-member-public":
+      case "class-method":
+      case "type-parameter":
+        return changecase.pascalCase(name);
+      case "constant":
+        return changecase.constantCase(name);
+      default:
+        return changecase.camelCase(name);
+    }
+  });
+}
+
+// gets the active C# naming policy
+export function useCSharpNamePolicy(): core.NamePolicy<CSharpElements> {
+  return core.useNamePolicy();
+}