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

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.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;