@alloy-js/go 0.0.1

package/src/scopes/source-file.ts

@@ -0,0 +1,66 @@
+import {
+  OutputScope,
+  OutputScopeOptions,
+  shallowReactive,
+  useScope,
+} from "@alloy-js/core";
+import { GoSymbol } from "../symbols/go.js";
+import { PackageSymbol } from "../symbols/package.js";
+import { GoLexicalScope } from "./lexical.js";
+import { GoPackageScope } from "./package.js";
+
+export type ImportRecords = Map<PackageSymbol, GoSymbol>;
+
+export class GoSourceFileScope extends GoLexicalScope {
+  #imports = shallowReactive<ImportRecords>(new Map());
+
+  constructor(
+    name: string,
+    parent?: GoPackageScope,
+    options?: OutputScopeOptions,
+  ) {
+    super(name, parent, options);
+  }
+
+  get imports() {
+    return this.#imports;
+  }
+
+  get parent() {
+    return super.parent! as GoPackageScope;
+  }
+
+  set parent(v: GoPackageScope) {
+    super.parent = v;
+  }
+
+  addImport(import_: PackageSymbol) {
+    if (this.#imports.has(import_)) {
+      return this.#imports.get(import_)!;
+    }
+
+    const localSymbol = new GoSymbol(import_.name, this.values, {
+      aliasTarget: import_,
+    });
+
+    this.#imports.set(import_, localSymbol);
+
+    return localSymbol;
+  }
+
+  get enclosingPackage(): PackageSymbol | undefined {
+    return this.parent?.ownerSymbol;
+  }
+}
+
+export function useSourceFileScope() {
+  let scope: OutputScope | undefined = useScope();
+  while (scope) {
+    if (scope instanceof GoSourceFileScope) {
+      return scope;
+    }
+    scope = scope.parent;
+  }
+
+  return undefined;
+}

package/src/symbols/factories.ts

@@ -0,0 +1,234 @@
+import { Namekey, NamePolicyGetter } from "@alloy-js/core";
+import { join } from "pathe";
+import { GoElements, useGoNamePolicy } from "../name-policy.js";
+import { useGoScope, useNamedTypeScope } from "../scopes/contexts.js";
+import { GoFunctionScope } from "../scopes/function.js";
+import { GoLexicalScope } from "../scopes/lexical.js";
+import { useModule } from "../scopes/module.js";
+import { GoNamedTypeScope } from "../scopes/named-type.js";
+import { useEnclosingPackageScope } from "../scopes/package.js";
+import { FunctionSymbol } from "./function.js";
+import { GoSymbol, GoSymbolOptions } from "./go.js";
+import {
+  NamedTypeSymbol,
+  NamedTypeSymbolOptions,
+  NamedTypeTypeKind,
+} from "./named-type.js";
+import { PackageSymbol } from "./package.js";
+
+/**
+ * Create a symbol for a parameter in the current func scope.
+ */
+export function createParameterSymbol(
+  originalName: string | Namekey,
+  options: GoSymbolOptions = {},
+) {
+  const scope = useGoScope();
+  if (!(scope instanceof GoFunctionScope)) {
+    throw new Error(`Can't create parameter symbol outside of a func scope.`);
+  }
+  return new GoSymbol(
+    originalName,
+    scope.parameters,
+    withNamePolicy(options, "parameter"),
+  );
+}
+
+export interface CreateTypeParameterSymbolOptions extends GoSymbolOptions {
+  scope?: GoFunctionScope | GoNamedTypeScope;
+}
+export function createTypeParameterSymbol(
+  originalName: string | Namekey,
+  options: CreateTypeParameterSymbolOptions = {},
+) {
+  const scope = options.scope ?? useGoScope();
+  if (
+    !(scope instanceof GoFunctionScope) &&
+    !(scope instanceof GoNamedTypeScope)
+  ) {
+    throw new Error(
+      "Can't create a type parameter symbol outside of a func or named type scope.",
+    );
+  }
+
+  return new GoSymbol(
+    originalName,
+    scope.typeParameters,
+    withNamePolicy(options, "type-parameter"),
+  );
+}
+
+export function createStructMemberSymbol(
+  originalName: string | Namekey,
+  options: NamedTypeSymbolOptions = {},
+) {
+  const scope = useNamedTypeScope();
+
+  if (
+    scope.ownerSymbol.typeKind !== "struct" &&
+    scope.ownerSymbol.typeKind !== "struct-member"
+  ) {
+    throw new Error(
+      `Can't define a field outside of a struct, kind ${scope.ownerSymbol.typeKind}.`,
+    );
+  }
+
+  return new NamedTypeSymbol(
+    originalName,
+    scope.members,
+    "struct-member",
+    withNamePolicy(options, "struct-member"),
+  );
+}
+
+export function createInterfaceMemberSymbol(
+  originalName: string | Namekey,
+  options: NamedTypeSymbolOptions = {},
+) {
+  const scope = useNamedTypeScope();
+
+  if (scope.ownerSymbol.typeKind !== "interface") {
+    throw new Error(
+      `Can't define a field outside of an interface, kind ${scope.ownerSymbol.typeKind}.`,
+    );
+  }
+
+  return new NamedTypeSymbol(
+    originalName,
+    scope.members,
+    "interface-member",
+    withNamePolicy(options, "interface-member"),
+  );
+}
+
+export function createPackageSymbol(name: string, path?: string) {
+  const scope = useEnclosingPackageScope();
+  const pkgSymbol = scope?.ownerSymbol;
+  if (!pkgSymbol) {
+    const mod = useModule();
+    const modName = mod.name;
+    const builtin = mod.builtin;
+    const pkgPath = path ? join(modName, path) : modName;
+    return new PackageSymbol(name, undefined, { path: pkgPath, builtin });
+  }
+  if (pkgSymbol.members.symbolNames.has(name)) {
+    return pkgSymbol.members.symbolNames.get(name)! as PackageSymbol;
+  }
+  return new PackageSymbol(name, pkgSymbol, { path });
+}
+
+export function createFunctionSymbol(
+  originalName: string | Namekey,
+  isMethod: boolean,
+  options: GoSymbolOptions = {},
+) {
+  const scope = useGoScope();
+  if (!isMethod && scope instanceof GoLexicalScope) {
+    return new FunctionSymbol(
+      originalName,
+      scope.types,
+      withNamePolicy(options, "function"),
+    );
+  }
+  return new FunctionSymbol(
+    originalName,
+    undefined,
+    withNamePolicy(options, "function"),
+  );
+}
+
+export function createPropertySymbol(
+  originalName: string | Namekey,
+  options: GoSymbolOptions,
+) {
+  const scope = useNamedTypeScope();
+  return new GoSymbol(
+    originalName,
+    scope.members,
+    withNamePolicy(options, "struct-member"),
+  );
+}
+
+export function createVariableSymbol(
+  originalName: string | Namekey,
+  options: GoSymbolOptions = {},
+) {
+  const scope = useGoScope();
+  if (!(scope instanceof GoLexicalScope)) {
+    throw new Error(
+      `Can't create variable symbol outside of a lexical scope, got a ${scope.constructor.name}.`,
+    );
+  }
+  return new GoSymbol(
+    originalName,
+    scope.values,
+    withNamePolicy(options, "variable"),
+  );
+}
+
+export function createTypeSymbol(
+  originalName: string | Namekey,
+  kind: NamedTypeTypeKind,
+  options: NamedTypeSymbolOptions = {},
+) {
+  const scope = useGoScope();
+  if (scope instanceof GoLexicalScope) {
+    return new NamedTypeSymbol(
+      originalName,
+      scope.types,
+      kind,
+      withNamePolicy(options, "type"),
+    );
+  }
+  throw new Error(
+    `Can't create type symbol outside of a lexical scope, got a ${scope.constructor.name}.`,
+  );
+}
+
+export function createNestedStructSymbol(
+  originalName: string | Namekey,
+  kind: NamedTypeTypeKind,
+  options: NamedTypeSymbolOptions = {},
+) {
+  const scope = useGoScope();
+  if (scope instanceof GoNamedTypeScope) {
+    return new NamedTypeSymbol(
+      originalName,
+      scope.ownerSymbol.members,
+      kind,
+      withNamePolicy(options, "struct-member"),
+    );
+  }
+  throw new Error(
+    `Can't create named anonymous type symbol outside of a NamedType scope, got a ${scope.constructor.name}.`,
+  );
+}
+
+let anonymousTypeID = 0;
+
+export function createAnonymousTypeSymbol(
+  kind: NamedTypeTypeKind,
+  options: NamedTypeSymbolOptions = {},
+) {
+  const name =
+    "anonymous_" + anonymousTypeID++ + "_this_should_not_appear_in_output";
+  const scope = useGoScope();
+  if (scope instanceof GoLexicalScope) {
+    return new NamedTypeSymbol(name, scope.types, kind, options);
+  } else if (scope instanceof GoNamedTypeScope) {
+    return new NamedTypeSymbol(name, scope.ownerSymbol.members, kind, options);
+  }
+  throw new Error(
+    `Can't create anonymous type symbol outside of a lexical or NamedType scope, got a ${scope.constructor.name}.`,
+  );
+}
+
+function withNamePolicy<T extends { namePolicy?: NamePolicyGetter }>(
+  options: T,
+  elementType: GoElements,
+): GoSymbolOptions {
+  return {
+    ...options,
+    namePolicy: options.namePolicy ?? useGoNamePolicy().for(elementType),
+  };
+}

package/src/symbols/function.ts

@@ -0,0 +1,17 @@
+import { Namekey, OutputSpace } from "@alloy-js/core";
+import { GoSymbol, GoSymbolOptions } from "./go.js";
+
+/**
+ * A symbol for a function in Go, including receivers.
+ */
+export class FunctionSymbol extends GoSymbol {
+  public readonly symbolKind = "function";
+
+  constructor(
+    name: string | Namekey,
+    spaces: OutputSpace | undefined,
+    options: GoSymbolOptions = {},
+  ) {
+    super(name, spaces, options);
+  }
+}

package/src/symbols/go.ts

@@ -0,0 +1,82 @@
+import {
+  Namekey,
+  OutputDeclarationSpace,
+  OutputMemberSpace,
+  OutputSpace,
+  OutputSymbol,
+  OutputSymbolOptions,
+} from "@alloy-js/core";
+import { GoScope } from "../scopes/go.js";
+import { PackageSymbol } from "./package.js";
+
+/**
+ * Options for creating a Go symbol.
+ */
+export interface GoSymbolOptions extends OutputSymbolOptions {}
+
+export type GoSymbolKinds =
+  | "symbol"
+  | "named-type"
+  | "function"
+  | "field"
+  | "package";
+
+/**
+ * This is the base type for all symbols in Go.
+ *
+ * Many subtypes of this symbol exist for specific purposes. However, this symbol
+ * may be used in cases where a more specific symbol is not required.
+ */
+export class GoSymbol extends OutputSymbol {
+  constructor(
+    name: string | Namekey,
+    spaces: OutputSpace[] | OutputSpace | undefined,
+    options: GoSymbolOptions = {},
+  ) {
+    super(name, spaces, options);
+  }
+
+  get enclosingPackage(): PackageSymbol | undefined {
+    if (this.spaces.length === 0) {
+      return undefined;
+    }
+
+    // todo: probably need to validate that a symbol can't belong to spaces in
+    // multiple packages.
+    const firstSpace = this.spaces[0];
+
+    if (firstSpace instanceof OutputMemberSpace) {
+      // this symbol is a member of something, so get the enclosing package from
+      // the symbol.
+
+      if (firstSpace.symbol.constructor.name === "PackageSymbol") {
+        // this is a package symbol, so return the package symbol itself.
+        // can't use instanceof here due to circular reference issues.
+        return firstSpace.symbol as PackageSymbol;
+      }
+
+      return (firstSpace.symbol as GoSymbol).enclosingPackage;
+    } else if (firstSpace instanceof OutputDeclarationSpace) {
+      // this symbol is in a lexical scope, so get the package symbol from the scope.
+      return (firstSpace.scope as GoScope).enclosingPackage;
+    }
+    throw new Error("No place to get package symbol from");
+  }
+
+  protected getGoCopyOptions(): GoSymbolOptions {
+    return {
+      ...this.getCopyOptions(),
+    };
+  }
+
+  protected initializeGoCopy(copy: GoSymbol) {
+    this.initializeCopy(copy);
+  }
+
+  copy(): OutputSymbol {
+    const options = this.getGoCopyOptions();
+    const copy = new GoSymbol(this.name, undefined, options);
+    this.initializeGoCopy(copy);
+    return copy;
+  }
+}

package/src/symbols/index.ts

@@ -0,0 +1,6 @@
+export * from "./factories.js";
+export * from "./function.js";
+export * from "./go.js";
+export * from "./named-type.js";
+export * from "./package.js";
+export * from "./reference.js";

package/src/symbols/named-type.ts

@@ -0,0 +1,90 @@
+import {
+  Namekey,
+  OutputSpace,
+  track,
+  TrackOpTypes,
+  trigger,
+  TriggerOpTypes,
+} from "@alloy-js/core";
+import { TypeParameterProps } from "../components/parameters/typeparameters.jsx";
+import { GoSymbol, GoSymbolOptions } from "./go.js";
+
+// represents a symbol from a .go file. Struct, interface, etc.
+export type NamedTypeTypeKind =
+  | "import"
+  | "function"
+  | "var"
+  | "type"
+  | "struct"
+  | "struct-member"
+  | "interface"
+  | "interface-member"
+  | "package";
+export type NamedTypeSymbolKind = "named-type" | "package";
+
+export interface NamedTypeSymbolOptions extends GoSymbolOptions {
+  typeParameters?: TypeParameterProps[];
+}
+
+/**
+ * A symbol for a named type in Go such as a struct, interface, and so forth.
+ */
+export class NamedTypeSymbol extends GoSymbol {
+  public readonly symbolKind: NamedTypeSymbolKind = "named-type";
+  public static readonly memberSpaces = ["members"];
+
+  constructor(
+    name: string | Namekey,
+    spaces: OutputSpace[] | OutputSpace | undefined,
+    kind: NamedTypeTypeKind,
+    options?: NamedTypeSymbolOptions,
+  ) {
+    super(name, spaces, options);
+    this.#typeKind = kind;
+    this.#typeParameters = options?.typeParameters;
+  }
+
+  #typeKind: NamedTypeTypeKind;
+  get typeKind() {
+    track(this, TrackOpTypes.GET, "typeKind");
+    return this.#typeKind;
+  }
+  set typeKind(value: NamedTypeTypeKind) {
+    const old = this.#typeKind;
+    if (old === value) {
+      return;
+    }
+    this.#typeKind = value;
+    trigger(this, TriggerOpTypes.SET, "typeKind", value, old);
+  }
+
+  #typeParameters?: TypeParameterProps[];
+  get typeParameters() {
+    track(this, TrackOpTypes.GET, "typeParameters");
+    return this.#typeParameters;
+  }
+  set typeParameters(value: TypeParameterProps[] | undefined) {
+    const old = this.#typeParameters;
+    if (old === value) {
+      return;
+    }
+    this.#typeParameters = value;
+    trigger(this, TriggerOpTypes.SET, "typeParameters", value, old);
+  }
+
+  copy() {
+    const options = this.getGoCopyOptions();
+    const copy = new NamedTypeSymbol(
+      this.name,
+      undefined,
+      this.#typeKind,
+      options,
+    );
+    this.initializeGoCopy(copy);
+    return copy;
+  }
+
+  get members() {
+    return this.memberSpaceFor("members")!;
+  }
+}

package/src/symbols/package.ts

@@ -0,0 +1,54 @@
+import { OutputSymbolOptions } from "@alloy-js/core";
+import { join } from "pathe";
+import { NamedTypeSymbol } from "./named-type.js";
+
+export interface PackageSymbolOptions extends OutputSymbolOptions {
+  path?: string;
+  builtin?: boolean;
+}
+
+/**
+ * A symbol for a package in Go.
+ */
+export class PackageSymbol extends NamedTypeSymbol {
+  public readonly symbolKind = "package";
+  constructor(
+    name: string,
+    parentPackage?: PackageSymbol,
+    options?: PackageSymbolOptions,
+  ) {
+    const space = parentPackage?.members;
+    super(name, space, "package", options);
+    this.#path = options?.path ?? name;
+    if (parentPackage) {
+      this.#fullyQualifiedName = join(
+        parentPackage.fullyQualifiedName,
+        this.#path,
+      );
+    } else {
+      this.#fullyQualifiedName = this.#path;
+    }
+    this.#builtin = options?.builtin || parentPackage?.builtin || false;
+  }
+
+  #path: string;
+  #fullyQualifiedName: string;
+  get fullyQualifiedName(): string {
+    return this.#fullyQualifiedName;
+  }
+
+  #builtin: boolean;
+  get builtin() {
+    return this.#builtin;
+  }
+
+  copy() {
+    const options = this.getGoCopyOptions();
+    const copy = new PackageSymbol(this.name, undefined, {
+      ...options,
+      path: this.#path,
+    });
+    this.initializeGoCopy(copy);
+    return copy;
+  }
+}

package/src/symbols/reference.ts

@@ -0,0 +1,87 @@
+import { memo, OutputSymbol, Refkey, resolve } from "@alloy-js/core";
+import { GoScope } from "../scopes/go.js";
+import { GoPackageScope } from "../scopes/package.js";
+import { useSourceFileScope } from "../scopes/source-file.js";
+import { GoSymbol } from "./go.js";
+import { PackageSymbol } from "./package.js";
+
+function closestPackageScope(
+  scopes: GoScope[],
+  decl: GoSymbol,
+  memberPath: GoSymbol[],
+): {
+  pkgSymbol: PackageSymbol | undefined;
+  members: GoSymbol[];
+} {
+  const allMembers = [decl, ...memberPath];
+  for (let i = allMembers.length - 1; i >= 0; i--) {
+    const member = allMembers[i];
+    if (member instanceof PackageSymbol) {
+      return { pkgSymbol: member, members: allMembers.slice(i + 1) };
+    }
+  }
+  for (let i = scopes.length - 1; i >= 0; i--) {
+    const scope = scopes[i];
+    if (scope instanceof GoPackageScope) {
+      return {
+        pkgSymbol: scope.ownerSymbol,
+        members: allMembers,
+      };
+    }
+  }
+  return {
+    pkgSymbol: undefined,
+    members: allMembers,
+  };
+}
+
+// converts a refkey to its fully qualified name
+// e.g. if refkey is for bar in enum type foo, and
+// foo is in the same namespace as the refkey, then
+// the result would be foo.bar.
+export function ref(refkey: Refkey): () => [string, OutputSymbol | undefined] {
+  const refSfScope = useSourceFileScope()!;
+  const resolveResult = resolve<GoScope, GoSymbol>(refkey as Refkey);
+
+  return memo(() => {
+    if (resolveResult.value === undefined) {
+      return ["<Unresolved Symbol>", undefined];
+    }
+
+    const result = resolveResult.value;
+    const { pathDown, memberPath } = result;
+    const { lexicalDeclaration } = result;
+
+    const parts = [];
+
+    let localSymbol: GoSymbol | undefined;
+
+    const { pkgSymbol: pkgSymbol, members: pathFromPkg } = closestPackageScope(
+      pathDown,
+      lexicalDeclaration,
+      memberPath,
+    );
+    if (pkgSymbol) {
+      // we need to import the package
+      for (const pathMember of pathFromPkg) {
+        const memberName = pathMember.name;
+        const firstChar = memberName.charAt(0);
+        if (firstChar.toLowerCase() === firstChar) {
+          throw new Error(
+            `Can't reference non-exported symbol ${pathMember.name} from another package.`,
+          );
+        }
+      }
+      localSymbol = refSfScope.addImport(pkgSymbol);
+    }
+
+    if (localSymbol) {
+      parts.push(localSymbol.name);
+    }
+    for (const member of pathFromPkg) {
+      parts.push(member.name);
+    }
+
+    return [parts.join("."), result.symbol];
+  });
+}