@alloy-js/core 0.23.0-dev.12 → 0.23.0-dev.15

package/src/debug/trace.ts

@@ -3,6 +3,7 @@
  */
 import type { ServerToClientMessage } from "../devtools/devtools-protocol.js";
 import { isDevtoolsEnabled } from "../devtools/devtools-server.js";
+import { env, sourceMapsEnabled } from "../host/node-host.js";
 import { untrack } from "../reactivity.js";
 import { initTrace, isTraceEnabled } from "./trace-writer.js";
 
@@ -21,12 +22,12 @@ export function isDebugEnabled(): boolean {
 // Environment configuration
 // ─────────────────────────────────────────────────────────────────────────────
 
-const traceEnv = process.env.ALLOY_TRACE ?? "";
+const traceEnv = env("ALLOY_TRACE") ?? "";
 const tracePhases = new Set<string>(
   traceEnv === "" ? [] : traceEnv.split(",").map((t) => t.trim()),
 );
 
-const debuggerIdsEnv = process.env.ALLOY_BREAK_ON_DID ?? "";
+const debuggerIdsEnv = env("ALLOY_BREAK_ON_DID") ?? "";
 const debuggerIds = new Set<number>();
 debuggerIdsEnv.split(",").forEach((id) => {
   const num = parseInt(id, 10);
@@ -37,9 +38,9 @@ debuggerIdsEnv.split(",").forEach((id) => {
 
 /** Parse the ALLOY_BREAK_ON_DID environment variable into a set of IDs. */
 export function parseBreakOnIds(): Set<number> {
-  const env = process.env.ALLOY_BREAK_ON_DID ?? "";
+  const raw = env("ALLOY_BREAK_ON_DID") ?? "";
   const ids = new Set<number>();
-  env.split(",").forEach((id) => {
+  raw.split(",").forEach((id) => {
     const num = parseInt(id, 10);
     if (!isNaN(num)) {
       ids.add(num);
@@ -65,7 +66,7 @@ if (tracePhases.size > 0) {
 }
 
 // Initialize SQLite trace writer if ALLOY_DEBUG_TRACE is set
-const traceDbEnv = process.env.ALLOY_DEBUG_TRACE;
+const traceDbEnv = env("ALLOY_DEBUG_TRACE");
 if (traceDbEnv) {
   const traceDbPath =
     traceDbEnv === "1" || traceDbEnv === "true" ? "alloy-trace.db" : traceDbEnv;
@@ -82,7 +83,7 @@ if (traceDbEnv) {
 if (import.meta.url.includes("/dist/dev/")) {
   // eslint-disable-next-line no-console
   console.log("Alloy debug build loaded.");
-  if (process.sourceMapsEnabled) {
+  if (sourceMapsEnabled()) {
     // eslint-disable-next-line no-console
     console.log("  Source maps enabled.");
   } else {

package/src/host/node-host.browser.ts

@@ -0,0 +1,23 @@
+/**
+ * Browser stub for Node.js host APIs.
+ *
+ * Replaces `node-host.ts` in browser builds so that no Node.js globals
+ * (`process`, etc.) are referenced.
+ */
+
+export function env(_key: string): string | undefined {
+  return undefined;
+}
+
+export function cwd(): string {
+  return "";
+}
+
+export function stdoutWrite(text: string): void {
+  // eslint-disable-next-line no-console
+  console.log(text);
+}
+
+export function sourceMapsEnabled(): boolean {
+  return false;
+}

package/src/host/node-host.ts

@@ -0,0 +1,22 @@
+/**
+ * Node.js host APIs.
+ *
+ * Provides access to Node.js-specific process APIs. In browser builds this
+ * module is replaced by `node-host.browser.ts` which returns safe defaults.
+ */
+
+export function env(key: string): string | undefined {
+  return process.env[key];
+}
+
+export function cwd(): string {
+  return process.cwd();
+}
+
+export function stdoutWrite(text: string): void {
+  process.stdout.write(text);
+}
+
+export function sourceMapsEnabled(): boolean {
+  return !!(process as any).sourceMapsEnabled;
+}

package/src/library-symbol-reference.ts

@@ -1,10 +1,62 @@
 import { RefkeyableObject } from "./refkey.js";
 import { OutputSymbol } from "./symbols/output-symbol.js";
 
+/**
+ * Well-known symbol for the lazy-symbol-creation protocol used by external
+ * library descriptors. Objects implementing `[TO_SYMBOL]()` are recognized as
+ * {@link LibrarySymbolReference} values that can be passed anywhere a refkey
+ * is accepted.
+ *
+ * @remarks
+ *
+ * Implement `[TO_SYMBOL]()` on a descriptor object to register it as a
+ * referenceable library symbol. Inside the method:
+ *
+ * 1. Call {@link useBinder} to get the current binder context.
+ * 2. Look up (or create) the symbol for that binder in a
+ *    `WeakMap<object, OutputSymbol>` (use a sentinel object for the
+ *    no-binder case, since `WeakMap` keys must be objects).
+ * 3. On first creation, construct the symbol and register it into the
+ *    appropriate space for your library, passing `{ binder }`
+ *    (see {@link OutputSymbolOptions.binder}).
+ *
+ * The method is called by language package code each time the descriptor is
+ * used as a reference (e.g. inside `ref()`). It is NOT called by the binder
+ * itself.
+ *
+ * @example
+ *
+ * ```ts
+ * const defaultKey = {};
+ * const symbols = new WeakMap<object, MySymbol>();
+ * const descriptor: LibrarySymbolReference = {
+ *   [REFKEYABLE]() {
+ *     return descriptor[TO_SYMBOL]().refkeys[0];
+ *   },
+ *   [TO_SYMBOL]() {
+ *     const binder = useBinder();
+ *     const key = binder ?? defaultKey;
+ *     let sym = symbols.get(key);
+ *     if (!sym) {
+ *       sym = new MySymbol("SomeType", space, { binder });
+ *       symbols.set(key, sym);
+ *     }
+ *     return sym;
+ *   },
+ * };
+ * ```
+ */
 export const TO_SYMBOL: unique symbol = Symbol(
   "Alloy.RefkeyableObject.TO_SYMBOL",
 );
 
+/**
+ * An object that acts as a lazy reference to an external library symbol.
+ * Implements {@link REFKEYABLE} and `[TO_SYMBOL]()`.
+ *
+ * Use {@link isLibrarySymbolReference} to test whether an unknown value is a
+ * library symbol reference.
+ */
 export interface LibrarySymbolReference extends RefkeyableObject {
   [TO_SYMBOL](): OutputSymbol;
 }

package/src/name-policy.ts

@@ -1,20 +1,47 @@
+/**
+ * A function that transforms a name according to a naming policy for a
+ * specific element kind. Obtained from {@link NamePolicy.for}.
+ */
 export interface NamePolicyGetter {
   (originalName: string): string;
 }
 export interface NamePolicy<TElements extends string> {
   /**
-   * Apply the language policy to the provided name for the provided element
-   * type.
+   * Apply the language policy to the provided name for the provided element type.
+   * When `element` is `undefined`, returns `originalName` unchanged.
    */
   getName(originalName: string, element: TElements | undefined): string;
   /**
    * Get a function that takes a name and applies the naming policy to it.
+   * When `element` is `undefined`, returns an identity function.
    */
   for(element: TElements | undefined): NamePolicyGetter;
 }
 
+/**
+ * Creates a name policy that transforms symbol names based on element kind.
+ *
+ * @example
+ * ```ts
+ * const policy = createNamePolicy((name, element) => {
+ *   if (element === "value") return toCamelCase(name);
+ *   if (element === "type")  return toPascalCase(name);
+ *   return name;
+ * });
+ * <Output namePolicy={policy}>...</Output>
+ * ```
+ *
+ * @remarks
+ * `element` identifies the kind of declaration (e.g., `"value"`, `"type"`).
+ * The set of valid element strings is defined by the language package.
+ *
+ * When `element` is `undefined` (outside a declaration context), {@link NamePolicy.getName}
+ * and {@link NamePolicy.for} short-circuit and return the original name unchanged — the
+ * namer callback is **not** invoked. The namer therefore always receives a defined `T`.
+ * This means names outside a declaration context cannot be transformed by the policy.
+ */
 export function createNamePolicy<T extends string>(
-  namer: (name: string, elements: T) => string,
+  namer: (name: string, element: T) => string,
 ): NamePolicy<T> {
   const forCache = new Map<string, NamePolicyGetter>();
   const noopGetter = (name: string) => name;

package/src/reactivity.ts

@@ -200,6 +200,21 @@ export function findCurrentEffectId(): number | undefined {
   return undefined;
 }
 
+/**
+ * Returns a getter caching the result of `fn`. Re-evaluates when reactive
+ * dependencies change. See the [Reactivity docs](../../reactivity.md) for details.
+ *
+ * @param fn - Function to memoize.
+ * @param equal - Skip updates when value is unchanged.
+ * @param name - Debug label for traces.
+ * @returns A zero-argument getter returning the cached value.
+ *
+ * @example
+ * ```ts
+ * const fullName = memo(() => `${first.value} ${last.value}`);
+ * fullName(); // cached; re-evaluates when first or last changes
+ * ```
+ */
 export function memo<T>(fn: () => T, equal?: boolean, name?: string): () => T {
   const memoLabel = name ? `memo:${name}` : "memo";
   const o = shallowRef<T>(undefined as T, {

package/src/render-stack.ts

@@ -2,6 +2,7 @@ import pc from "picocolors";
 import { contextsByKey } from "./context.js";
 import { SourceDirectoryContext } from "./context/source-directory.js";
 import { SourceFileContext } from "./context/source-file.js";
+import { cwd } from "./host/node-host.js";
 import { Context, getContext } from "./reactivity.js";
 import { Component, Props, SourceLocation } from "./runtime/component.js";
 
@@ -125,12 +126,12 @@ function formatValue(value: unknown): string {
 }
 
 function formatSourceLocation(source: SourceLocation): string {
-  const cwd = process.cwd();
+  const currentCwd = cwd();
   let filePath = source.fileName;
 
   // Convert to relative path if under cwd
-  if (filePath.startsWith(cwd)) {
-    filePath = filePath.slice(cwd.length + 1); // +1 to remove leading slash
+  if (currentCwd && filePath.startsWith(currentCwd)) {
+    filePath = filePath.slice(currentCwd.length + 1); // +1 to remove leading slash
   }
 
   return `${filePath}:${source.lineNumber}:${source.columnNumber}`;

package/src/render.ts

@@ -282,12 +282,14 @@ const {
 
 export interface OutputDirectory {
   kind: "directory";
+  /** Full path from the output root, e.g. `"generated-client/src"`. Do not prepend parent directory paths when walking the tree. */
   path: string;
   contents: (OutputDirectory | OutputFile)[];
 }
 
 export interface OutputFileBase {
   kind: "file";
+  /** Full path from the output root, e.g. `"generated-client/src/models.ext"`. Do not prepend parent directory paths when walking the tree. */
   path: string;
 }
 

package/src/symbols/output-scope.ts

@@ -54,6 +54,11 @@ export interface OutputScopeOptions {
  * within a reactive context.
  */
 export abstract class OutputScope {
+  /**
+   * The declaration space keys for this scope type. Subclasses override this
+   * to declare which declaration spaces are created on construction (e.g.,
+   * `["types", "values"]`).
+   */
   static readonly declarationSpaces: Readonly<string[]> = [] as const;
 
   #name: string;
@@ -125,7 +130,8 @@ export abstract class OutputScope {
   #spaces: Record<string, OutputDeclarationSpace>;
 
   /**
-   * Get the declaration space for the given key.
+   * Get the declaration space for the given key (e.g., `"types"`, `"values"`).
+   * Returns `undefined` when no space with that key exists on this scope.
    */
   spaceFor(key: string): OutputSpace | undefined {
     return this.#spaces[key];
@@ -153,6 +159,32 @@ export abstract class OutputScope {
 
   [ReactiveFlags.SKIP] = true;
 
+  /**
+   * Subclasses must forward all three positional arguments to `super`. See
+   * {@link createScope} for the preferred instantiation path.
+   *
+   * @param name - A descriptive name for this scope (used in debugging and
+   * diagnostics).
+   * @param parentScope - The parent scope in the scope tree, or `undefined`
+   * for root scopes. Inside a component, obtain this via `useScope()`.
+   * @param options - Additional scope options; see {@link OutputScopeOptions}.
+   *
+   * @example
+   * ```ts
+   * class MyScope extends OutputScope {
+   *   constructor(
+   *     name: string,
+   *     parent: OutputScope | undefined,
+   *     options?: OutputScopeOptions,
+   *   ) {
+   *     super(name, parent, options);
+   *   }
+   * }
+   *
+   * // Inside a component:
+   * const scope = createScope(MyScope, "my-scope", useScope());
+   * ```
+   */
   constructor(
     name: string,
     parentScope: OutputScope | undefined,

package/src/symbols/output-space.ts

@@ -5,7 +5,16 @@ import { OutputScope } from "./output-scope.js";
 import { OutputSymbol } from "./output-symbol.js";
 import { SymbolTable } from "./symbol-table.js";
 
+/**
+ * A symbol table that belongs to either a scope (declaration space) or a symbol
+ * (member space).
+ */
 export type OutputSpace = OutputDeclarationSpace | OutputMemberSpace;
+
+/**
+ * A symbol table attached to an {@link OutputScope}. Holds lexical declarations
+ * visible within that scope (e.g., "types" or "values" in a TypeScript module).
+ */
 export class OutputDeclarationSpace extends SymbolTable {
   constructor(scope: OutputScope, key: string, binder?: Binder) {
     super(key, binder);
@@ -27,6 +36,10 @@ export class OutputDeclarationSpace extends SymbolTable {
   }
 }
 
+/**
+ * A symbol table attached to an {@link OutputSymbol}. Holds member declarations
+ * belonging to that symbol (e.g., "static" or "instance" members of a class).
+ */
 export class OutputMemberSpace extends SymbolTable {
   constructor(symbol: OutputSymbol, key: string, binder?: Binder) {
     super(key, binder);

package/src/symbols/output-symbol.ts

@@ -37,6 +37,12 @@ export interface OutputSymbolOptions {
    * will be reported to this binder. This binder will be able to find this
    * symbol via its refkey and other means. Without a binder, this symbol will
    * be unbound, which means it cannot be referenced by refkey.
+   *
+   * @remarks
+   *
+   * When constructing an external library symbol, pass `{ binder }` here to
+   * ensure the symbol is registered with the binder. See {@link TO_SYMBOL} for
+   * the full implementation protocol.
    */
   binder?: Binder;
 
@@ -97,7 +103,15 @@ export interface OutputSymbolOptions {
   ignoreNameConflict?: boolean;
 
   /**
-   * Provide a function which lazy-initializes members when an enumeration of members are needed.
+   * Provide a function which lazy-initializes members the first time
+   * `resolveMemberByName()` is called on this symbol. Called at most once.
+   *
+   * @remarks
+   *
+   * Only `resolveMemberByName()` triggers this callback — iterating
+   * `OutputMemberSpace` directly does not. The callback fires regardless of
+   * whether the symbol belongs to any scope, so it is safe to use on scopeless
+   * external library symbols.
    */
   lazyMemberInitializer?: () => void;
 }
@@ -110,11 +124,47 @@ let symbolCount = 0;
  *
  * @remarks
  *
- * This class is the base implementation of symbol. Most languages will have
- * subtypes that provide additional metadata. Symbols are reactive values, so
- * you can observe changes to their properties in a reactive context.
+ * This is an abstract base class. Language packages must subclass it and
+ * implement the abstract {@link OutputSymbol.copy | copy()} method, which
+ * creates a clone that tracks the original's name and flags.
+ *
+ * Subtypes typically add language-specific properties (e.g., accessibility,
+ * static/abstract flags). Symbols are reactive values, so you can observe
+ * changes to their properties in a reactive context.
+ *
+ * To construct a scopeless external library symbol — one that resolves via
+ * refkey but does not appear in any declaration space — pass `undefined` as
+ * the `spaces` constructor argument and supply `{ binder }` in `options`.
+ * See {@link OutputSymbolOptions} (`binder` option) and {@link TO_SYMBOL}.
+ *
+ * @example
+ *
+ * ```ts
+ * import { createSymbol, OutputSymbol, OutputSpace } from "@alloy-js/core";
+ *
+ * class MySymbol extends OutputSymbol {
+ *   copy() {
+ *     // getCopyOptions() already includes binder
+ *     const opts = this.getCopyOptions();
+ *     const sym = createSymbol(MySymbol, this.name, undefined, opts);
+ *     this.initializeCopy(sym);
+ *     return sym;
+ *   }
+ * }
+ *
+ * // name: string | Namekey; spaces: OutputSpace | OutputSpace[] | undefined; options: OutputSymbolOptions
+ * const sym = createSymbol(MySymbol, namekey, scope.symbols, { binder });
+ *
+ * // Construct a scopeless external library symbol (resolves via refkey only):
+ * const extSym = createSymbol(MySymbol, namekey, undefined, { binder });
+ * ```
  */
 export abstract class OutputSymbol {
+  /**
+   * The member space keys for this symbol type. Subclasses override this to
+   * declare which member spaces are created on construction (e.g.,
+   * `["static", "instance"]`).
+   */
   public static readonly memberSpaces: Readonly<string[]> = [];
 
   #originalName: string;
@@ -131,7 +181,8 @@ export abstract class OutputSymbol {
   // this field is set by calling the name accessor.
   #name!: string;
   /**
-   * The name of this symbol.
+   * The name of this symbol. Assigning to this property applies the active
+   * name policy (unless `ignoreNamePolicy` is true) before storing the value.
    *
    * @reactive
    */
@@ -338,6 +389,13 @@ export abstract class OutputSymbol {
     return this.#metadata;
   }
 
+  /**
+   * Copy this symbol into the given space. Calls {@link OutputSymbol.copy} and places
+   * the result in `space`, then returns the copy.
+   *
+   * @param space - The space to place the copy in.
+   * @returns The copy of this symbol, now belonging to `space`.
+   */
   copyToSpace(space: OutputSpace) {
     const copy = this.copy();
     copy.spaces = space;
@@ -507,6 +565,14 @@ export abstract class OutputSymbol {
   // proxy.
   [ReactiveFlags.SKIP] = true;
 
+  /**
+   * @param name - The symbol name, or a {@link Namekey} carrying name and
+   * options (e.g., `ignoreNamePolicy`).
+   * @param spaces - The declaration or member space(s) this symbol belongs to.
+   * Pass `undefined` for scopeless external library symbols (see `binder` option).
+   * @param options - Additional symbol options (binder, refkeys, metadata,
+   * type, name policy, etc.).
+   */
   constructor(
     name: string | Namekey,
     spaces: OutputSpace[] | OutputSpace | undefined,
@@ -631,17 +697,19 @@ export abstract class OutputSymbol {
   }
 
   /**
-   * Makes a copy of this symbol which will update the name and flags
-   * of the clone when the original symbol is updated.
+   * Create a clone of this symbol whose name and flags reactively track the
+   * original.
    *
    * @remarks
    *
-   * This is used to create a symbol that is a copy of this symbol, but
-   * with a different scope. Changes to the copy will not affect the
-   * original symbol, and changes to the original symbol's name and flags
-   * will overwrite the copy's name and flags.
+   * Called by `SymbolTable.copyTo` during scope/space transfers.
+   * Subclasses implement cloning logic and call `getCopyOptions` for
+   * base options and `initializeCopy` to wire up member copying and
+   * name tracking.
    *
-   * @param newScope - The scope to use for the copy.
+   * **Space registration contract:** The returned clone must not be registered
+   * in any space on exit. `copyToSpace()` calls this method and assigns the
+   * space afterward.
    */
   abstract copy(): OutputSymbol;
 
@@ -654,6 +722,19 @@ export abstract class OutputSymbol {
     };
   }
 
+  /**
+   * Wires up reactive member-space copying and name tracking from this symbol
+   * to its `copy`.
+   *
+   * @remarks
+   *
+   * Iterates each member space and calls `copyTo` on the corresponding space
+   * on `copy`. Then installs a reactive watcher so that any future change to
+   * `this.name` is immediately mirrored onto `copy.name`.
+   *
+   * **Must be called by every `copy()` override** before the override returns.
+   * Pair with `getCopyOptions` to supply the base constructor options.
+   */
   protected initializeCopy(copy: OutputSymbol) {
     for (const sourceSpace of this.memberSpaces) {
       const targetSpace = copy.memberSpaceFor(sourceSpace.key);

package/src/symbols/symbol-slot.test.tsx

@@ -1,6 +1,6 @@
 import { shallowRef } from "@vue/reactivity";
 import { expect, it } from "vitest";
-import { renderTree } from "../render.js";
+import { getDiagnosticsForTree, renderTree } from "../render.js";
 import { flushJobs } from "../scheduler.js";
 import { BasicSymbol } from "./basic-symbol.js";
 import { emitSymbol } from "./symbol-flow.js";
@@ -21,6 +21,33 @@ it("captures firstSymbol", async () => {
   expect(Slot.firstSymbol.value!.name).toBe("a");
 });
 
+it("emits error diagnostic when rendered more than once", async () => {
+  const Slot = createSymbolSlot();
+
+  const tree = renderTree(
+    <>
+      <Slot>
+        {() => {
+          emitSymbol(new BasicSymbol("a", undefined));
+        }}
+      </Slot>
+      <Slot>
+        {() => {
+          emitSymbol(new BasicSymbol("b", undefined));
+        }}
+      </Slot>
+    </>,
+  );
+  await flushJobs();
+
+  const diagnostics = getDiagnosticsForTree(tree);
+  expect(diagnostics.length).toBe(1);
+  expect(diagnostics[0].severity).toBe("error");
+  expect(diagnostics[0].message).toContain(
+    "SymbolSlot rendered more than once",
+  );
+});
+
 it("captures firstSymbol when emitting a ref to a symbol", async () => {
   const Slot = createSymbolSlot();
   const symref = shallowRef<BasicSymbol | undefined>();

package/src/symbols/symbol-slot.tsx

@@ -1,4 +1,5 @@
 import { Ref, ShallowReactive, shallowRef } from "@vue/reactivity";
+import { emitDiagnostic } from "../diagnostics.js";
 import { effect, onCleanup } from "../reactivity.js";
 import type { Children, Component } from "../runtime/component.js";
 import { OutputSymbol } from "./output-symbol.js";
@@ -35,6 +36,13 @@ export function createSymbolSlot(): SymbolSlot {
   const symbolSlotRef: Ref<ShallowReactive<Set<OutputSymbol>> | undefined> =
     shallowRef();
   function SymbolSlot(props: { children: Children }) {
+    if (symbolSlotRef.value !== undefined) {
+      emitDiagnostic({
+        message:
+          "SymbolSlot rendered more than once. The second render will overwrite symbols captured by the first render.",
+        severity: "error",
+      });
+    }
     const set = takeSymbols();
     symbolSlotRef.value = set;
 

package/src/write-output.ts

@@ -1,5 +1,6 @@
 import { dirname, relative, resolve } from "pathe";
 import { AlloyHost } from "./host/alloy-host.js";
+import { cwd } from "./host/node-host.js";
 import { OutputDirectory } from "./render.js";
 import { traverseOutput } from "./utils.js";
 /**
@@ -17,7 +18,7 @@ export async function writeOutput(
         return;
       }
       // eslint-disable-next-line no-console
-      console.log("create", relative(process.cwd(), path));
+      console.log("create", relative(cwd(), path));
       await AlloyHost.mkdir(path);
     },
     async visitFile(file) {
@@ -25,10 +26,10 @@ export async function writeOutput(
         const path = resolve(basePath, file.path);
         if (await AlloyHost.exists(path)) {
           // eslint-disable-next-line no-console
-          console.log("overwrite", relative(process.cwd(), path));
+          console.log("overwrite", relative(cwd(), path));
         } else {
           // eslint-disable-next-line no-console
-          console.log("create", relative(process.cwd(), path));
+          console.log("create", relative(cwd(), path));
         }
 
         await AlloyHost.write(path, file.contents);
@@ -38,10 +39,10 @@ export async function writeOutput(
         const target = resolve(basePath, file.path);
         if (await AlloyHost.exists(target)) {
           // eslint-disable-next-line no-console
-          console.log("copy over", relative(process.cwd(), target));
+          console.log("copy over", relative(cwd(), target));
         } else {
           // eslint-disable-next-line no-console
-          console.log("copy", relative(process.cwd(), target));
+          console.log("copy", relative(cwd(), target));
         }
         await AlloyHost.mkdir(dirname(target));
         await AlloyHost.write(target, AlloyHost.read(source).stream());