@alloy-js/go 0.0.1

package/src/create-module.ts

@@ -0,0 +1,347 @@
+import {
+  Binder,
+  LibrarySymbolReference,
+  namekey,
+  refkey,
+  REFKEYABLE,
+  TO_SYMBOL,
+  useBinder,
+} from "@alloy-js/core";
+import { basename } from "pathe";
+import { FunctionSymbol, GoSymbol, PackageSymbol } from "./index.js";
+import { NamedTypeSymbol } from "./symbols/named-type.js";
+
+export interface MemberDescriptor {
+  kind: string;
+  type?: LibrarySymbolReference | (() => LibrarySymbolReference);
+}
+
+export interface FieldDescriptor extends MemberDescriptor {
+  kind: "field";
+}
+
+export interface FunctionDescriptor extends MemberDescriptor {
+  kind: "function";
+}
+
+export interface MethodDescriptor extends MemberDescriptor {
+  kind: "method";
+}
+
+export interface VariableDescriptor extends MemberDescriptor {
+  kind: "var";
+}
+
+export interface EmbedDescriptor extends MemberDescriptor {
+  kind: "embed";
+}
+
+export interface NamedTypeDescriptor<M extends Record<string, Descriptor>> {
+  kind: string;
+  members: M;
+}
+
+export interface TypeDescriptor<M extends Record<string, Descriptor>>
+  extends NamedTypeDescriptor<M> {
+  kind: "type";
+}
+
+export interface PackageDescriptor<M extends Record<string, Descriptor>>
+  extends NamedTypeDescriptor<M> {
+  kind: "package";
+  path?: string;
+  name?: string;
+  members: M;
+}
+
+export interface StructDescriptor<M extends Record<string, Descriptor>>
+  extends NamedTypeDescriptor<M> {
+  kind: "struct";
+}
+
+export interface InterfaceDescriptor<M extends Record<string, Descriptor>>
+  extends NamedTypeDescriptor<M> {
+  kind: "interface";
+}
+
+export type Descriptor =
+  | PackageDescriptor<any>
+  | FieldDescriptor
+  | FunctionDescriptor
+  | MethodDescriptor
+  | VariableDescriptor
+  | StructDescriptor<any>
+  | InterfaceDescriptor<any>
+  | TypeDescriptor<any>
+  | EmbedDescriptor;
+
+export type StrictDescriptor =
+  | PackageDescriptor<Record<string, StrictDescriptor>>
+  | FieldDescriptor
+  | FunctionDescriptor
+  | MethodDescriptor
+  | VariableDescriptor
+  | StructDescriptor<Record<string, StrictDescriptor>>
+  | InterfaceDescriptor<Record<string, StrictDescriptor>>
+  | TypeDescriptor<Record<string, StrictDescriptor>>
+  | EmbedDescriptor;
+
+export type ResolveDescriptor<D> =
+  D extends NamedTypeDescriptor<infer M> ?
+    LibrarySymbolReference & { [K in keyof M]: ResolveDescriptor<M[K]> }
+  : LibrarySymbolReference;
+
+export type LibraryFrom<T> = ResolveDescriptor<T> & LibrarySymbolReference;
+
+interface InternalContext {
+  ownerSymbol(binder: Binder | undefined): GoSymbol | null;
+  builtin: boolean;
+}
+
+export function createModule<T extends PackageDescriptor<any>>(
+  name: string,
+  props: T,
+  builtin: boolean = false,
+): LibraryFrom<T> {
+  return createSymbolEntry(name, props, {
+    ownerSymbol(_binder: Binder | undefined) {
+      return null;
+    },
+    builtin,
+  }) as LibraryFrom<T>;
+}
+
+function createSymbolEntry(
+  name: string,
+  descriptor: Descriptor,
+  context: InternalContext,
+): LibrarySymbolReference {
+  const symbols = new WeakMap<Binder, GoSymbol>();
+
+  function getSymbol(binder: Binder | undefined) {
+    // We cache symbols per binder to ensure we only create one symbol. We also
+    // track an unbound symbol for cases where there is no binder (mostly
+    // tests).
+    return mapGet(symbols, binder, () =>
+      createSymbolFromDescriptor(
+        name,
+        binder,
+        descriptor,
+        context,
+        initializeMembers,
+      ),
+    );
+  }
+
+  const newContext: InternalContext = {
+    ownerSymbol(binder) {
+      return getSymbol(binder) as NamedTypeSymbol;
+    },
+    builtin: context.builtin,
+  };
+
+  function initializeMembers() {
+    for (const key of Object.keys(obj)) {
+      if (typeof key === "symbol") continue;
+      (obj as any)[key][TO_SYMBOL]();
+    }
+  }
+
+  const obj: LibrarySymbolReference & Record<string, unknown> = {
+    [REFKEYABLE]() {
+      return getSymbol(useBinder()).refkeys[0];
+    },
+    [TO_SYMBOL]() {
+      return getSymbol(useBinder());
+    },
+  };
+
+  switch (descriptor.kind) {
+    case "package":
+    case "struct":
+    case "interface":
+      for (const [memberName, memberDesc] of Object.entries(
+        descriptor.members,
+      ) as any) {
+        obj[memberName] = createSymbolEntry(memberName, memberDesc, newContext);
+      }
+      break;
+  }
+
+  return obj;
+}
+
+function createSymbolFromDescriptor(
+  name: string,
+  binder: Binder | undefined,
+  descriptor: Descriptor,
+  context: InternalContext,
+  lazyMemberInitializer: () => void,
+): GoSymbol {
+  const ownerSymbol = context.ownerSymbol(binder) as GoSymbol;
+
+  if (ownerSymbol === null && descriptor.kind !== "package") {
+    throw new Error(
+      `Cannot create a non-package symbol (${name}) without an owner symbol.`,
+    );
+  }
+
+  switch (descriptor.kind) {
+    case "package":
+      if (ownerSymbol === null) {
+        const dname = basename(name);
+        const packageName = descriptor.name ?? dname;
+        const packageSymbol = new PackageSymbol(packageName, undefined, {
+          binder,
+          refkeys: refkey(),
+          lazyMemberInitializer,
+          path: descriptor.path,
+          builtin: context.builtin,
+        });
+        return packageSymbol;
+      }
+      if (!(ownerSymbol instanceof PackageSymbol)) {
+        throw new Error(
+          `Cannot create a package symbol (${name}) with a non-package owner symbol (${ownerSymbol.name}).`,
+        );
+      }
+      if (ownerSymbol.members.symbolNames.has(name)) {
+        return ownerSymbol.members.symbolNames.get(name)! as PackageSymbol;
+      }
+      return new PackageSymbol(name, ownerSymbol as PackageSymbol, {
+        binder,
+        refkeys: refkey(),
+        lazyMemberInitializer,
+        path: descriptor.path,
+        builtin: context.builtin,
+      });
+    case "struct":
+    case "interface":
+    case "type":
+      if (!(ownerSymbol instanceof PackageSymbol)) {
+        throw new Error(
+          `Cannot create a named type symbol (${name}) with a non-package owner symbol (${ownerSymbol.name}).`,
+        );
+      }
+      return new NamedTypeSymbol(
+        namekey(name),
+        ownerSymbol.members,
+        descriptor.kind,
+        {
+          binder,
+          refkeys: refkey(),
+          lazyMemberInitializer,
+        },
+      );
+    case "function":
+      if (!(ownerSymbol instanceof PackageSymbol)) {
+        throw new Error(
+          `Cannot create a function symbol (${name}) with a non-package owner symbol (${ownerSymbol.name}).`,
+        );
+      }
+      return new FunctionSymbol(namekey(name), ownerSymbol.members, {
+        binder,
+        refkeys: refkey(),
+      });
+    case "field":
+      if (!(ownerSymbol instanceof NamedTypeSymbol)) {
+        throw new Error(
+          `Cannot create a field symbol (${name}) with a non-named-type owner symbol (${ownerSymbol.name}).`,
+        );
+      }
+      return new NamedTypeSymbol(
+        namekey(name),
+        ownerSymbol.members,
+        ownerSymbol.typeKind === "interface" ?
+          "interface-member"
+        : "struct-member",
+        {
+          binder,
+          refkeys: refkey(),
+          type:
+            descriptor.type === undefined ? undefined
+            : typeof descriptor.type === "function" ?
+              descriptor.type()[TO_SYMBOL]()
+            : descriptor.type[TO_SYMBOL](),
+          lazyMemberInitializer,
+        },
+      );
+    case "embed": {
+      if (!(ownerSymbol instanceof NamedTypeSymbol)) {
+        throw new Error(
+          `Cannot create a field symbol (${name}) with a non-named-type owner symbol (${ownerSymbol.name}).`,
+        );
+      }
+      const symbol = new NamedTypeSymbol(
+        namekey(name),
+        ownerSymbol.members,
+        ownerSymbol.typeKind === "interface" ?
+          "interface-member"
+        : "struct-member",
+        {
+          binder,
+          refkeys: refkey(),
+          type:
+            descriptor.type === undefined ? undefined
+            : typeof descriptor.type === "function" ?
+              descriptor.type()[TO_SYMBOL]()
+            : descriptor.type[TO_SYMBOL](),
+          lazyMemberInitializer,
+        },
+      );
+      symbol.copyMembersTo(ownerSymbol);
+      return symbol;
+    }
+    case "var":
+      if (!(ownerSymbol instanceof PackageSymbol)) {
+        throw new Error(
+          `Cannot create a variable symbol (${name}) with a non-package owner symbol (${ownerSymbol.name}).`,
+        );
+      }
+      return new GoSymbol(namekey(name), ownerSymbol.members, {
+        binder,
+        refkeys: refkey(),
+        type:
+          descriptor.type === undefined ? undefined
+          : typeof descriptor.type === "function" ?
+            descriptor.type()[TO_SYMBOL]()
+          : descriptor.type[TO_SYMBOL](),
+      });
+    default:
+      throw "Unsupported";
+  }
+}
+
+const defaultsPerMap = new WeakMap<object, unknown>();
+
+function mapGet<T extends WeakKey, V>(
+  map: WeakMap<T, V>,
+  key: T | undefined,
+): V | undefined;
+function mapGet<T extends WeakKey, V>(
+  map: WeakMap<T, V>,
+  key: T | undefined,
+  init: () => V,
+): V;
+function mapGet<T extends WeakKey, V>(
+  map: WeakMap<T, V>,
+  key: T | undefined,
+  init?: () => V,
+): V | undefined {
+  if (key === undefined) {
+    // Use a per-map default store when callers request a value for an undefined key.
+    let value = defaultsPerMap.get(map as unknown as object) as V | undefined;
+    if (value === undefined && init) {
+      value = init();
+      defaultsPerMap.set(map as unknown as object, value);
+    }
+    return value;
+  }
+
+  let value = map.get(key);
+  if (value === undefined && init) {
+    value = init();
+    map.set(key, value);
+  }
+  return value;
+}

package/src/index.ts

@@ -0,0 +1,5 @@
+export * from "./builtins/index.js";
+export * from "./components/index.js";
+export * from "./name-policy.js";
+export * from "./scopes/index.js";
+export * from "./symbols/index.js";

package/src/name-policy.ts

@@ -0,0 +1,65 @@
+import { createNamePolicy, NamePolicy, useNamePolicy } from "@alloy-js/core";
+
+export type GoElements =
+  | "parameter"
+  | "type-parameter"
+  | "function"
+  | "type"
+  | "variable"
+  | "struct-member"
+  | "interface-member";
+
+const GLOBAL_RESERVED_WORDS = new Set([
+  "break",
+  "case",
+  "chan",
+  "const",
+  "continue",
+  "default",
+  "defer",
+  "else",
+  "fallthrough",
+  "for",
+  "func",
+  "go",
+  "goto",
+  "if",
+  "import",
+  "interface",
+  "map",
+  "package",
+  "range",
+  "return",
+  "select",
+  "struct",
+  "switch",
+  "type",
+  "var",
+]);
+
+/**
+ * Ensures a valid Go identifier for the given element kind.
+ * @param name - The name to validate.
+ * @param element - The Go element kind.
+ * @returns A Go-safe name.
+ */
+function ensureNonReservedName(name: string, _element: GoElements): string {
+  const suffix = "_";
+
+  // Global reserved words always need handling
+  if (GLOBAL_RESERVED_WORDS.has(name)) {
+    return `${name}${suffix}`;
+  }
+
+  return name;
+}
+
+export function createGoNamePolicy(): NamePolicy<GoElements> {
+  return createNamePolicy((name, element) => {
+    return ensureNonReservedName(name, element);
+  });
+}
+
+export function useGoNamePolicy(): NamePolicy<GoElements> {
+  return useNamePolicy();
+}

package/src/scopes/contexts.ts

@@ -0,0 +1,45 @@
+import { useScope } from "@alloy-js/core";
+import { GoFunctionScope } from "./function.js";
+import { GoScope } from "./go.js";
+import { GoLexicalScope } from "./lexical.js";
+import { GoNamedTypeScope } from "./named-type.js";
+
+export function useGoScope() {
+  const scope = useScope();
+  if (!(scope instanceof GoScope)) {
+    throw new Error("Expected a Go scope, got a different kind of scope.");
+  }
+
+  return scope;
+}
+
+export function useNamedTypeScope() {
+  const scope = useGoScope();
+  if (!(scope instanceof GoNamedTypeScope)) {
+    throw new Error(
+      "Expected a named type scope, got a " + scope.constructor.name,
+    );
+  }
+
+  return scope;
+}
+
+export function useFuncScope() {
+  const scope = useGoScope();
+  if (!(scope instanceof GoFunctionScope)) {
+    throw new Error(
+      `Expected a function scope, but got ${scope.constructor.name}.`,
+    );
+  }
+  return scope;
+}
+
+export function useLexicalScope() {
+  const scope = useGoScope();
+  if (!(scope instanceof GoLexicalScope)) {
+    throw new Error(
+      `Expected a lexical scope, but got ${scope.constructor.name}.`,
+    );
+  }
+  return scope;
+}

package/src/scopes/factories.ts

@@ -0,0 +1,29 @@
+import { OutputScopeOptions } from "@alloy-js/core";
+import { NamedTypeSymbol } from "../symbols/named-type.js";
+import { useGoScope } from "./contexts.js";
+import { GoFunctionScope } from "./function.js";
+import { GoNamedTypeScope } from "./named-type.js";
+import { GoSourceFileScope } from "./source-file.js";
+
+export function createNamedTypeScope(
+  ownerSymbol: NamedTypeSymbol,
+  options: OutputScopeOptions = {},
+) {
+  const currentScope = useGoScope();
+  if (
+    !(currentScope instanceof GoNamedTypeScope) &&
+    !(currentScope instanceof GoSourceFileScope)
+  ) {
+    throw new Error(
+      "Can't create Go type declaration scope inside of " +
+        currentScope.constructor.name,
+    );
+  }
+
+  return new GoNamedTypeScope(ownerSymbol, currentScope, options);
+}
+
+export function createFunctionScope(options: OutputScopeOptions = {}) {
+  const parentScope = useGoScope();
+  return new GoFunctionScope("function scope", parentScope, options);
+}

package/src/scopes/function.ts

@@ -0,0 +1,22 @@
+import type { OutputSpace } from "@alloy-js/core";
+import { GoLexicalScope } from "./lexical.js";
+
+export class GoFunctionScope extends GoLexicalScope {
+  public static readonly declarationSpaces = [
+    "local-variables",
+    "parameters",
+    "type-parameters",
+  ];
+
+  get localVariables(): OutputSpace {
+    return this.spaceFor("local-variables")!;
+  }
+
+  get parameters(): OutputSpace {
+    return this.spaceFor("parameters")!;
+  }
+
+  get typeParameters(): OutputSpace {
+    return this.spaceFor("type-parameters")!;
+  }
+}

package/src/scopes/go.ts

@@ -0,0 +1,18 @@
+import { OutputScope, OutputScopeOptions } from "@alloy-js/core";
+import { PackageSymbol } from "../symbols/package.js";
+
+export class GoScope extends OutputScope {
+  constructor(
+    name: string,
+    parent: GoScope | undefined,
+    options?: OutputScopeOptions,
+  ) {
+    super(name, parent, options);
+    this.#packageSymbol = parent?.enclosingPackage;
+  }
+
+  #packageSymbol: PackageSymbol | undefined;
+  get enclosingPackage() {
+    return this.#packageSymbol;
+  }
+}

package/src/scopes/index.ts

@@ -0,0 +1,9 @@
+export * from "./contexts.js";
+export * from "./factories.js";
+export * from "./function.js";
+export * from "./go.js";
+export * from "./lexical.js";
+export * from "./module.js";
+export * from "./named-type.js";
+export * from "./package.js";
+export * from "./source-file.js";

package/src/scopes/lexical.ts

@@ -0,0 +1,14 @@
+import { type OutputSpace } from "@alloy-js/core";
+import { GoScope } from "./go.js";
+
+export class GoLexicalScope extends GoScope {
+  public static readonly declarationSpaces = ["values", "types"];
+
+  get values(): OutputSpace {
+    return this.spaceFor("values")!;
+  }
+
+  get types(): OutputSpace {
+    return this.spaceFor("types")!;
+  }
+}

package/src/scopes/module.ts

@@ -0,0 +1,35 @@
+import { OutputScope, useScope } from "@alloy-js/core";
+import { GoScope } from "./go.js";
+
+export class GoModuleScope extends GoScope {
+  constructor(name: string, builtin = false) {
+    super(name, undefined);
+    this.#builtin = builtin;
+  }
+
+  #builtin: boolean;
+  get builtin() {
+    return this.#builtin;
+  }
+}
+
+export function createGoModuleScope(name: string) {
+  const parentScope = useScope();
+  if (parentScope) {
+    throw new Error("Modules can only be created at the top level");
+  }
+  const scope = new GoModuleScope(name);
+  return scope;
+}
+
+export function useModule() {
+  let scope: OutputScope | undefined = useScope();
+  while (scope) {
+    if (scope instanceof GoModuleScope) {
+      return scope;
+    }
+    scope = scope.parent;
+  }
+
+  throw new Error("A module is not in scope");
+}

package/src/scopes/named-type.ts

@@ -0,0 +1,49 @@
+import { type OutputScopeOptions } from "@alloy-js/core";
+import { NamedTypeSymbol } from "../symbols/named-type.js";
+import { GoScope } from "./go.js";
+import { GoModuleScope } from "./module.js";
+import { GoSourceFileScope } from "./source-file.js";
+
+/**
+ * This scope contains NamedTypeSymbols for types that are declared in
+ * containers like packages. This scope is a member scope which whose
+ * member symbol is a NamedTypeSymbol.
+ */
+export class GoNamedTypeScope extends GoScope {
+  public static readonly declarationSpaces = [];
+
+  constructor(
+    ownerSymbol: NamedTypeSymbol,
+    parentScope:
+      | GoNamedTypeScope
+      | GoSourceFileScope
+      | GoModuleScope
+      | undefined,
+    options: OutputScopeOptions = {},
+  ) {
+    super(`${ownerSymbol.name} scope`, parentScope, {
+      ownerSymbol,
+      ...options,
+    });
+  }
+
+  get ownerSymbol(): NamedTypeSymbol {
+    return super.ownerSymbol as NamedTypeSymbol;
+  }
+
+  get enclosingPackage() {
+    return this.ownerSymbol.enclosingPackage;
+  }
+
+  get members() {
+    return this.ownerSymbol.members;
+  }
+
+  /**
+   * For now, we stuff type parameters into the member scope. This is to ensure
+   * name conflicts are handled correctly.
+   */
+  get typeParameters() {
+    return this.ownerSymbol.members;
+  }
+}

package/src/scopes/package.ts

@@ -0,0 +1,55 @@
+import { OutputScope, useScope } from "@alloy-js/core";
+import type { PackageSymbol } from "../symbols/package.js";
+import { GoModuleScope } from "./module.js";
+import { GoNamedTypeScope } from "./named-type.js";
+
+export class GoPackageScope extends GoNamedTypeScope {
+  constructor(
+    packageSymbol: PackageSymbol,
+    parentScope?: GoPackageScope | GoModuleScope,
+  ) {
+    super(packageSymbol, parentScope, { binder: packageSymbol.binder });
+  }
+
+  get ownerSymbol() {
+    return super.ownerSymbol as PackageSymbol;
+  }
+}
+
+export function createGoPackageScope(packageSymbol: PackageSymbol) {
+  const parentScope = useScope();
+  if (
+    parentScope &&
+    !(
+      parentScope instanceof GoPackageScope ||
+      parentScope instanceof GoModuleScope
+    )
+  ) {
+    throw new Error("Packages can only be created within a package or module");
+  }
+
+  const scope = new GoPackageScope(packageSymbol, parentScope);
+
+  return scope;
+}
+
+export function useEnclosingPackageScope(): GoPackageScope | undefined {
+  const currentScope = useScope();
+  if (!(currentScope instanceof GoPackageScope)) {
+    return undefined;
+  }
+
+  return currentScope;
+}
+
+export function usePackage() {
+  let scope: OutputScope | undefined = useScope();
+  while (scope) {
+    if (scope instanceof GoPackageScope) {
+      return scope;
+    }
+    scope = scope.parent;
+  }
+
+  throw new Error("A package is not in scope");
+}