@alloy-js/core 0.23.0-dev.9 → 0.23.0

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;
@@ -128,30 +178,113 @@ export abstract class OutputSymbol {
     return this.#originalName;
   }
 
-  // this field is set by calling the name accessor.
-  #name!: string;
+  // The user-assigned name (as set by constructor or direct `.name =`
+  // assignments). Always defined after construction.
+  #userName!: string;
+
+  // The name assigned by a name-conflict resolver, if any. When present, this
+  // takes precedence over `#userName` in the computed `name` getter. Resolvers
+  // assign via the `deconflictedName` setter; clearing (setting to undefined)
+  // causes the symbol to fall back to its user-assigned name.
+  #deconflictedName: string | undefined;
+
   /**
-   * 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.
+   *
+   * The effective name is computed as `deconflictedName ?? userName`, so if a
+   * name-conflict resolver has assigned a {@link OutputSymbol.deconflictedName | deconflictedName}, that value
+   * is returned here; otherwise the value most recently assigned to `name` is
+   * returned.
    *
    * @reactive
    */
   get name() {
     track(this, TrackOpTypes.GET, "name");
-    return this.#name;
+    return this.#deconflictedName ?? this.#userName;
   }
 
   set name(name: string) {
-    const old = this.#name;
+    const policyApplied =
+      this.#namePolicy && !this.#ignoreNamePolicy ?
+        this.#namePolicy(name)
+      : name;
 
-    if (old === name) {
+    if (this.#userName === policyApplied) {
       return;
     }
 
-    this.#name =
-      this.#namePolicy && !this.#ignoreNamePolicy ?
-        this.#namePolicy(name)
-      : name;
-    trigger(this, TriggerOpTypes.SET, "name", name, old);
+    const old = this.#deconflictedName ?? this.#userName;
+    this.#userName = policyApplied;
+    const next = this.#deconflictedName ?? this.#userName;
+    if (next !== old) {
+      trigger(this, TriggerOpTypes.SET, "name", next, old);
+    }
+  }
+
+  /**
+   * The name assigned by a name-conflict resolver, or `undefined` when the
+   * symbol is not currently renamed by conflict resolution.
+   *
+   * Resolvers should assign to this slot (rather than `name`) to record that a
+   * rename exists only because of a conflict. On re-deconfliction (e.g. after
+   * a conflicting symbol is removed), resolvers clear this slot by assigning
+   * `undefined`; the effective {@link OutputSymbol.name | name} then falls back to the
+   * user-assigned name, which in turn falls back to the original name.
+   *
+   * Name policy is applied to values written here (unless `ignoreNamePolicy`
+   * is true), matching `name`'s behavior.
+   *
+   * @reactive
+   */
+  get deconflictedName(): string | undefined {
+    track(this, TrackOpTypes.GET, "deconflictedName");
+    return this.#deconflictedName;
+  }
+
+  set deconflictedName(value: string | undefined) {
+    const policyApplied =
+      value !== undefined && this.#namePolicy && !this.#ignoreNamePolicy ?
+        this.#namePolicy(value)
+      : value;
+
+    if (this.#deconflictedName === policyApplied) {
+      return;
+    }
+
+    const oldName = this.#deconflictedName ?? this.#userName;
+    const oldDeconflicted = this.#deconflictedName;
+    this.#deconflictedName = policyApplied;
+    trigger(
+      this,
+      TriggerOpTypes.SET,
+      "deconflictedName",
+      policyApplied,
+      oldDeconflicted,
+    );
+    const nextName = this.#deconflictedName ?? this.#userName;
+    if (nextName !== oldName) {
+      trigger(this, TriggerOpTypes.SET, "name", nextName, oldName);
+    }
+  }
+
+  /**
+   * The canonical requested name for this symbol: the result of applying the
+   * symbol's name policy to its {@link OutputSymbol.originalName | originalName}, or the original name
+   * itself when no policy applies. This is the name the symbol would carry if
+   * there were no conflicts, and is stable across the symbol's lifetime (it
+   * depends only on the immutable `originalName` and the name policy).
+   *
+   * Used by {@link SymbolTable} as the grouping key for name-conflict
+   * resolution, so that symbols whose original names normalize to the same
+   * policy-applied name (e.g. `foo_bar` and `fooBar` under camelCase) are
+   * recognized as conflicting.
+   */
+  get canonicalName(): string {
+    if (this.#ignoreNamePolicy || !this.#namePolicy) {
+      return this.originalName;
+    }
+    return this.#namePolicy(this.originalName);
   }
 
   #id: number;
@@ -338,6 +471,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 +647,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 +779,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 +804,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/symbols/symbol-table.ts

@@ -13,7 +13,7 @@ export abstract class SymbolTable extends ReactiveUnionSet<OutputSymbol> {
   #deconflictNames = () => {
     for (const name of this.#namesToDeconflict) {
       const conflictedSymbols = [...this].filter(
-        (sym) => sym.originalName === name && !sym.ignoreNameConflict,
+        (sym) => sym.canonicalName === name && !sym.ignoreNameConflict,
       );
       if (this.#nameConflictResolver) {
         this.#nameConflictResolver(name, conflictedSymbols);
@@ -67,7 +67,7 @@ export abstract class SymbolTable extends ReactiveUnionSet<OutputSymbol> {
             `${formatSymbolName(symbol)} added to ${formatSymbolTableName(this)}`,
         );
 
-        this.#namesToDeconflict.add(symbol.name);
+        this.#namesToDeconflict.add(symbol.canonicalName);
 
         queueJob(this.#deconflictNames);
 
@@ -79,6 +79,12 @@ export abstract class SymbolTable extends ReactiveUnionSet<OutputSymbol> {
           () =>
             `${formatSymbolName(symbol)} removed from ${formatSymbolTableName(this)}`,
         );
+        // Re-run conflict resolution for the deleted symbol's canonical name
+        // so survivors in the same cohort (those that share the canonical
+        // name) can clear any prior `deconflictedName` rename now that the
+        // collision is reduced.
+        this.#namesToDeconflict.add(symbol.canonicalName);
+        queueJob(this.#deconflictNames);
       },
     });
 
@@ -135,8 +141,12 @@ export abstract class SymbolTable extends ReactiveUnionSet<OutputSymbol> {
  * to have a suffix of _2, _3, etc.
  */
 function defaultConflictHandler(_: string, conflictedSymbols: OutputSymbol[]) {
+  if (conflictedSymbols.length === 0) return;
+  // The first symbol keeps its original name; clear any prior deconflict
+  // rename so it reverts after a collision is resolved.
+  conflictedSymbols[0].deconflictedName = undefined;
   for (let i = 1; i < conflictedSymbols.length; i++) {
-    conflictedSymbols[i].name =
+    conflictedSymbols[i].deconflictedName =
       conflictedSymbols[i].originalName + "_" + (i + 1);
   }
 }

package/src/utils.tsx

@@ -1,4 +1,4 @@
-import { ref, Ref, toRaw } from "@vue/reactivity";
+import { Ref, toRaw } from "@vue/reactivity";
 import { BaseListProps } from "./components/List.jsx";
 import {
   createCustomContext,
@@ -9,6 +9,7 @@ import {
   getContext,
   memo,
   onCleanup,
+  ref,
   root,
   untrack,
 } from "./reactivity.js";
@@ -129,14 +130,16 @@ export function mapJoin<T, U, V>(
     }
     return slot;
   }
-  const firstNonEmptyIndex = ref(-1);
-  const lastNonEmptyIndex = ref(-1);
+  const firstNonEmptyIndex = ref(-1, { isInfrastructure: true });
+  const lastNonEmptyIndex = ref(-1, { isInfrastructure: true });
   const mapped: Children[] = [];
   let enderMemo: (() => Children) | undefined;
 
   // Creates a ref placeholder that stores the joiner node for a boundary.
   function createJoinerRef(): Ref<Children | undefined> {
-    return ref<unknown>(undefined) as Ref<Children | undefined>;
+    return ref<unknown>(undefined, { isInfrastructure: true }) as Ref<
+      Children | undefined
+    >;
   }
 
   // Makes sure we have a joiner ref at the requested boundary index.

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());