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

package/test/browser-build.test.ts

@@ -1,91 +1,156 @@
-import { execSync } from "child_process";
 import { existsSync, mkdirSync, rmSync, writeFileSync } from "fs";
-import { join } from "path";
+import { join, resolve } from "path";
+import { build, type Rolldown } from "vite";
 import { afterAll, beforeAll, describe, expect, it } from "vitest";
 
-const testDir = join(__dirname, ".temp", "vite-test-project");
+const tempDir = join(__dirname, ".temp", "browser-build-test");
+const entryFile = join(tempDir, "entry.js");
 
-describe("Browser Build Test", () => {
+// Absolute path to the compiled browser entry point.
+const corePkgDir = resolve(__dirname, "..");
+const browserEntry = resolve(corePkgDir, "dist/src/index.browser.js");
+
+/**
+ * Bundles `@alloy-js/core` for the browser using Vite and returns
+ * the concatenated output code and any warnings emitted during the build.
+ *
+ * Uses a custom resolveId plugin to force the browser entry point,
+ * because vitest's `resolve.conditions: ["source"]` leaks into the
+ * Vite build() call even with `configFile: false`, causing the test
+ * to resolve TypeScript source files instead of compiled dist.
+ */
+async function bundleForBrowser(): Promise<{
+  code: string;
+  warnings: string[];
+}> {
+  const warnings: string[] = [];
+  const result = await build({
+    configFile: false,
+    logLevel: "silent",
+    resolve: {
+      conditions: ["browser", "import"],
+      mainFields: ["browser", "module", "main"],
+    },
+    // Disable automatic process.env replacement so we can detect leaks
+    define: {},
+    plugins: [
+      {
+        name: "force-browser-entry",
+        enforce: "pre",
+        resolveId(source) {
+          // Force @alloy-js/core to resolve to the compiled browser entry,
+          // bypassing vitest's "source" condition that would resolve to TS.
+          if (source === "@alloy-js/core") {
+            return browserEntry;
+          }
+          return null;
+        },
+      },
+      {
+        name: "capture-warnings",
+        enforce: "post",
+        buildStart() {
+          // Hook into Vite's warning channel via rollup options
+        },
+      },
+    ],
+    customLogger: {
+      info() {},
+      error() {},
+      clearScreen() {},
+      hasErrorLogged() {
+        return false;
+      },
+      hasWarned: false,
+      warnOnce(msg: string) {
+        warnings.push(msg);
+      },
+      warn(msg: string) {
+        warnings.push(msg);
+      },
+    },
+    build: {
+      write: false,
+      minify: false,
+      rollupOptions: {
+        input: entryFile,
+        output: { format: "es" },
+        // Disable tree-shaking so we catch process.* references in ANY
+        // code path, even if it would be removed in a production build.
+        treeshake: false,
+        external: (id) => {
+          // Bundle @alloy-js packages — these are what we're validating
+          if (id.startsWith("@alloy-js/")) return false;
+          // Bundle relative/absolute imports (intra-package)
+          if (id.startsWith(".") || id.startsWith("/")) return false;
+          // Externalize third-party deps (vue, pathe, picocolors, …)
+          return true;
+        },
+        onwarn(warning) {
+          warnings.push(
+            typeof warning === "string" ? warning : (
+              (warning.message ?? String(warning))
+            ),
+          );
+        },
+      },
+    },
+  });
+
+  const output = (
+    Array.isArray(result) ?
+      result[0]
+    : result) as Rolldown.RolldownOutput;
+  const chunks = output.output.filter(
+    (o): o is Rolldown.OutputChunk => o.type === "chunk",
+  );
+  return { code: chunks.map((c) => c.code).join("\n"), warnings };
+}
+
+describe("browser build", () => {
   beforeAll(() => {
-    // Cleanup previous runs
-    if (existsSync(testDir)) {
-      rmSync(testDir, { recursive: true, force: true });
+    if (existsSync(tempDir)) {
+      rmSync(tempDir, { recursive: true, force: true });
     }
+    mkdirSync(tempDir, { recursive: true });
+    writeFileSync(entryFile, 'export * from "@alloy-js/core";\n');
+  });
 
-    // Create a temporary Vite project
-    mkdirSync(testDir, { recursive: true });
+  afterAll(() => {
+    if (existsSync(tempDir)) {
+      rmSync(tempDir, { recursive: true, force: true });
+    }
+  });
 
-    execSync("npm init -y", { cwd: testDir });
-    execSync("npm install vite", { cwd: testDir });
-    execSync("npm install ../../..", { cwd: testDir });
+  it("should bundle for browser without Node.js polyfills", async () => {
+    const { code, warnings } = await bundleForBrowser();
 
-    // Create a minimal Vite app
-    writeFileSync(
-      join(testDir, "index.js"),
-      `
-        import { writeOutput } from "@alloy-js/core";
-        console.log("Alloy-js core imported successfully!", writeOutput);
-      `,
-    );
+    // Sanity check: the bundle should not be empty
+    expect(code.length).toBeGreaterThan(0);
 
-    writeFileSync(
-      join(testDir, "vite.config.js"),
-      `
-        import { defineConfig } from "vite";
-    
-        export default defineConfig({
-          build: {
-            outDir: "dist",
-            target: "esnext",
-          }
-        });
-      `,
-    );
+    // The browser bundle must not reference the Node.js `process` global.
+    // If this fails, a file is using process.env / process.cwd / etc.
+    // without going through host/node-host.ts (or another browser-overridden module).
+    expect(code).not.toMatch(/\bprocess\./);
 
-    // Create an index.html file
-    writeFileSync(
-      join(testDir, "index.html"),
-      `
-      <!DOCTYPE html>
-      <html lang="en">
-      <head>
-        <meta charset="UTF-8">
-        <meta name="viewport" content="width=device-width, initial-scale=1.0">
-        <title>Vite Test</title>
-      </head>
-      <body>
-        <script type="module" src="/index.js"></script>
-      </body>
-      </html>
-      `,
-    );
+    // Should not contain static require("node:…") calls
+    expect(code).not.toMatch(/require\(\s*["']node:/);
 
-    writeFileSync(
-      join(testDir, "package.json"),
-      JSON.stringify(
-        {
-          type: "module",
-          scripts: {
-            build: "vite build",
-          },
-        },
-        null,
-        2,
-      ),
+    // Should not contain dynamic import("node:…") calls — these are the
+    // ones esbuild and other browser bundlers reject (e.g. node:sqlite, node:fs).
+    expect(code).not.toMatch(/import\(\s*["']node:/);
+
+    // Vite silently externalizes node:* modules for browser builds via its
+    // built-in rolldown:vite-resolve plugin, which hides the issue from the
+    // code assertions above. Catch those by checking for externalization warnings.
+    const nodeExternalizationWarnings = warnings.filter(
+      (w) =>
+        w.includes("externalized for browser compatibility") ||
+        w.includes("node:"),
     );
+    expect(
+      nodeExternalizationWarnings,
+      `Node.js modules were externalized for browser compatibility — missing browser shims:\n${nodeExternalizationWarnings.join("\n")}`,
+    ).toEqual([]);
   }, 30_000);
-
-  it("Vite should build successfully", () => {
-    // Run Vite build process and wait for completion
-    expect(() => {
-      execSync("npm run build", { cwd: testDir, stdio: "inherit" });
-    }).not.toThrow();
-  });
-
-  afterAll(() => {
-    // Ensure testDir exists before attempting to remove it
-    if (existsSync(testDir)) {
-      rmSync(testDir, { recursive: true, force: true });
-    }
-  });
 });

package/test/reactivity/shallow-reactive.test.tsx

@@ -1,4 +1,5 @@
 import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { refreshDebugState } from "../../src/devtools/devtools-server.js";
 import {
   getReactiveCreationLocation,
   shallowReactive,
@@ -10,6 +11,7 @@ describe("shallowReactive creation location", () => {
   beforeEach(() => {
     origDebug = process.env.ALLOY_DEBUG;
     process.env.ALLOY_DEBUG = "1";
+    refreshDebugState();
   });
 
   afterEach(() => {
@@ -18,6 +20,7 @@ describe("shallowReactive creation location", () => {
     } else {
       process.env.ALLOY_DEBUG = origDebug;
     }
+    refreshDebugState();
   });
 
   it("stores creation location keyed by raw target when debug enabled", () => {
@@ -31,6 +34,7 @@ describe("shallowReactive creation location", () => {
 
   it("does not store location when debug is disabled", () => {
     delete process.env.ALLOY_DEBUG;
+    refreshDebugState();
     const raw = { y: 2 };
     shallowReactive(raw);
 

package/test/symbols/deconflicted-name.test.ts

@@ -0,0 +1,120 @@
+import { describe, expect, it } from "vitest";
+import { Binder, createOutputBinder } from "../../src/binder.js";
+import { flushJobs } from "../../src/scheduler.js";
+import { BasicScope } from "../../src/symbols/basic-scope.js";
+import { BasicSymbol } from "../../src/symbols/basic-symbol.js";
+import type { OutputSymbol } from "../../src/symbols/output-symbol.js";
+
+function setup(
+  nameConflictResolver?: (name: string, syms: OutputSymbol[]) => void,
+) {
+  const binder: Binder = createOutputBinder({ nameConflictResolver });
+  const scope = new BasicScope("root", undefined, { binder });
+  return { binder, scope };
+}
+
+describe("deconflictedName", () => {
+  it("default resolver renames losers via deconflictedName and reverts on removal", () => {
+    const { scope } = setup();
+    const a = new BasicSymbol("foo", scope.symbols, {});
+    const b = new BasicSymbol("foo", scope.symbols, {});
+    flushJobs();
+    expect(a.name).toBe("foo");
+    expect(b.name).toBe("foo_2");
+    expect(a.deconflictedName).toBeUndefined();
+    expect(b.deconflictedName).toBe("foo_2");
+
+    b.delete();
+    flushJobs();
+    expect(a.name).toBe("foo");
+    expect(a.deconflictedName).toBeUndefined();
+  });
+
+  it("works with a custom rename scheme that doesn't match the default _N pattern", () => {
+    // Resolver uses a `$foo` prefix instead of `foo_N` suffix — the old
+    // isAutoAlias regex would never match this.
+    const customResolver = (_: string, symbols: OutputSymbol[]) => {
+      if (symbols.length === 0) return;
+      symbols[0].deconflictedName = undefined;
+      for (let i = 1; i < symbols.length; i++) {
+        symbols[i].deconflictedName = "$" + symbols[i].originalName;
+      }
+    };
+    const { scope } = setup(customResolver);
+
+    const a = new BasicSymbol("foo", scope.symbols, {});
+    const b = new BasicSymbol("foo", scope.symbols, {});
+    flushJobs();
+    expect(a.name).toBe("foo");
+    expect(b.name).toBe("$foo");
+
+    b.delete();
+    flushJobs();
+    // Survivor reverts to the original name regardless of scheme.
+    expect(a.name).toBe("foo");
+    expect(a.deconflictedName).toBeUndefined();
+  });
+
+  it("direct .name assignment does not clear an active deconflictedName", () => {
+    const { scope } = setup();
+    const a = new BasicSymbol("foo", scope.symbols, {});
+    const b = new BasicSymbol("foo", scope.symbols, {});
+    flushJobs();
+    expect(b.name).toBe("foo_2");
+
+    // User-assigns the name while a conflict rename is active.
+    b.name = "bar";
+    // Effective name still shows the deconflict rename (resolver wins while active).
+    expect(b.name).toBe("foo_2");
+
+    // Once the collision clears, the user-assigned name takes effect.
+    a.delete();
+    flushJobs();
+    expect(b.deconflictedName).toBeUndefined();
+    expect(b.name).toBe("bar");
+  });
+
+  it("detects conflict when different original names normalize to the same policy name", () => {
+    // Mirrors PR #394: under camelCase, `foo_bar` and `fooBar` both become
+    // `fooBar` — they collide on the rendered name and should be deconflicted.
+    const toCamel = (n: string) =>
+      n.replace(/_([a-z])/g, (_, c) => c.toUpperCase());
+    const { scope } = setup();
+
+    const a = new BasicSymbol("foo_bar", scope.symbols, {
+      namePolicy: toCamel,
+    });
+    const b = new BasicSymbol("fooBar", scope.symbols, {
+      namePolicy: toCamel,
+    });
+    flushJobs();
+
+    expect(a.name).toBe("fooBar");
+    // Without canonical-name grouping, `b` would keep its original `fooBar`
+    // and silently collide with `a`'s policy-applied name.
+    expect(b.name).not.toBe("fooBar");
+    expect(b.name).toMatch(/^fooBar/);
+  });
+
+  it("survivor reverts when the winner is removed (canonical-name cohort lookup)", () => {
+    // After `a` is removed, the delete hook must find `b` as a member of the
+    // same canonical-name cohort so it can clear its deconflictedName.
+    const toCamel = (n: string) =>
+      n.replace(/_([a-z])/g, (_, c) => c.toUpperCase());
+    const { scope } = setup();
+
+    const a = new BasicSymbol("foo_bar", scope.symbols, {
+      namePolicy: toCamel,
+    });
+    const b = new BasicSymbol("fooBar", scope.symbols, {
+      namePolicy: toCamel,
+    });
+    flushJobs();
+    expect(b.deconflictedName).toBeDefined();
+
+    a.delete();
+    flushJobs();
+    expect(b.deconflictedName).toBeUndefined();
+    expect(b.name).toBe("fooBar");
+  });
+});

package/test/symbols/output-scope.test.ts

@@ -206,3 +206,41 @@ describe("OutputScope#children", () => {
     expect(child2.parent).toBe(parentScope);
   });
 });
+
+describe("symbol name deduplication with name policy", () => {
+  it("deduplicates symbols whose names collide after name policy", () => {
+    const scope = createScope("scope");
+    const policy = (name: string) => name.toUpperCase();
+    const [s1] = createSymbol("foo", scope, { namePolicy: policy });
+    const [s2] = createSymbol("FOO", scope, { namePolicy: policy });
+
+    flushJobs();
+
+    expect(s1.name).toBe("FOO");
+    expect(s2.name).toBe("FOO_2");
+  });
+
+  it("deduplicates symbols when policy adds a prefix", () => {
+    const scope = createScope("scope");
+    const policy = (name: string) => (name === "reserved" ? `@${name}` : name);
+    const [s1] = createSymbol("reserved", scope, { namePolicy: policy });
+    const [s2] = createSymbol("reserved", scope, { namePolicy: policy });
+
+    flushJobs();
+
+    expect(s1.name).toBe("@reserved");
+    expect(s2.name).toBe("reserved_2");
+  });
+
+  it("does not deduplicates symbols with different names after policy", () => {
+    const scope = createScope("scope");
+    const policy = (name: string) => `prefix_${name}`;
+    const [s1] = createSymbol("foo", scope, { namePolicy: policy });
+    const [s2] = createSymbol("bar", scope, { namePolicy: policy });
+
+    flushJobs();
+
+    expect(s1.name).toBe("prefix_foo");
+    expect(s2.name).toBe("prefix_bar");
+  });
+});

package/testing/create-test-wrapper.tsx

@@ -2,20 +2,94 @@ import {
   Children,
   Declaration,
   For,
+  NameConflictResolver,
   Namekey,
   namekey,
+  NamePolicy,
   Output,
   OutputSymbol,
   shallowReactive,
 } from "../src/index.js";
 
+/**
+ * Test harness returned by {@link createTestWrapper}.
+ */
 export interface TestWrapper {
+  /**
+   * JSX wrapper providing Output + a file-level component + language scope context.
+   * Name policy is applied only when `namePolicy`/`nameConflictResolver` are
+   * passed to {@link createTestWrapper}. Pre-declares all namekeys created by
+   * {@link TestWrapper.defkey} before rendering children.
+   */
   Wrapper: (props: { children: Children }) => Children;
+
+  /**
+   * Creates a stable `Namekey` and schedules a pre-declaration inside
+   * {@link TestWrapper.Wrapper}.
+   *
+   * @remarks
+   * Call `defkey(name)` before rendering. `Wrapper` renders
+   * `<Declaration symbol={...} />` for this name so `<Reference>` to the
+   * returned namekey resolves without requiring an explicit `<Declaration>`
+   * in the test body.
+   *
+   * @example
+   * ```tsx
+   * const { Wrapper, defkey } = createTestWrapper(...);
+   * const fooKey = defkey("foo");
+   * expect(
+   *   <Wrapper><MyComponent refkey={fooKey} /></Wrapper>
+   * ).toRenderTo(`foo`);
+   * ```
+   */
   defkey: (name: string) => Namekey;
 }
 
 /**
- * Generic test wrapper creator.
+ * Create a reusable test harness for a language package. Returns a `Wrapper`
+ * component (wraps content in `<Output>` + `<SourceFile>`) and a `defkey`
+ * helper that creates stable namekeys for pre-declaring symbols.
+ *
+ * @remarks
+ *
+ * Downstream consumers import and call this from the language package's
+ * `testing/` entrypoint. The `Wrapper` automatically declares symbols
+ * created by `defkey` before rendering children, so tests can reference
+ * symbols without explicit `<Declaration>` boilerplate.
+ *
+ * @example
+ * ```ts
+ * // In your language package's testing/ entrypoint:
+ * import { FileComponent } from "./components/index.js"; // your language package's top-level file component
+ * import { createTestWrapper, type TestWrapper } from "@alloy-js/core/testing";
+ *
+ * export function createMyLangTestWrapper(): TestWrapper {
+ *   return createTestWrapper({
+ *     filePath: "test.ext",
+ *     useScope: useMyLangScope,
+ *     makeSymbol: (nk, scope) => new MyOutputSymbol(nk, scope),
+ *     SourceFile: FileComponent,
+ *   });
+ * }
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Extend your language test factory to accept and forward namePolicy:
+ * export function createMyLangTestWrapper(namePolicy?: NamePolicy<string>): TestWrapper {
+ *   return createTestWrapper({ ...langOpts, namePolicy });
+ * }
+ *
+ * // In a name-policy test:
+ * const { Wrapper } = createMyLangTestWrapper(myNamePolicy);
+ * const fooKey = namekey("foo"); // namekey(), not defkey — name policy applies
+ * // namekey() schedules no pre-declaration; the test body must declare the symbol.
+ * expect(
+ *   <Wrapper>
+ *     <MyDeclaration refkey={fooKey} name="foo" />
+ *   </Wrapper>
+ * ).toRenderTo("FOO");
+ * ```
  */
 export function createTestWrapper<
   SymbolT extends OutputSymbol,
@@ -25,6 +99,8 @@ export function createTestWrapper<
   useScope: () => ScopeT | undefined;
   makeSymbol: (nk: Namekey, scope: ScopeT) => SymbolT;
   SourceFile: (props: { path: string; children: Children }) => any;
+  namePolicy?: NamePolicy<string>;
+  nameConflictResolver?: NameConflictResolver;
 }): TestWrapper {
   const seen = shallowReactive(new Map<string, Namekey>());
   const created = new Map<Namekey, SymbolT>();
@@ -55,7 +131,10 @@ export function createTestWrapper<
   function Wrapper(props: { children: Children }) {
     const SF = opts.SourceFile;
     return (
-      <Output>
+      <Output
+        namePolicy={opts.namePolicy}
+        nameConflictResolver={opts.nameConflictResolver}
+      >
         <SF path={opts.filePath}>
           <For each={[...seen.values()]} joiner="">
             {(nk) => <Declaration symbol={createSymbol(nk)} />}

package/testing/devtools-utils.ts

@@ -5,11 +5,43 @@ export interface DevtoolsMessage {
   [key: string]: unknown;
 }
 
+const ALL_CHANNELS = [
+  "render",
+  "effects",
+  "refs",
+  "edges",
+  "symbols",
+  "scopes",
+  "files",
+  "directories",
+  "scheduler",
+  "diagnostics",
+  "errors",
+  "lifecycle",
+];
+
+/** Subscribe to all channels on the given socket. */
+export function subscribeAll(socket: WebSocket): void {
+  socket.send(JSON.stringify({ type: "subscribe", channels: ALL_CHANNELS }));
+}
+
 /**
  * Creates a message collector that accumulates messages and provides utilities
  * for waiting on conditions. Useful for tests with reactive updates.
+ *
+ * Returns a Promise because it waits for the subscription to be processed by
+ * the server before the caller starts rendering.
+ *
+ * @param channels - Optional list of channels to subscribe to. Defaults to all channels.
  */
-export function createMessageCollector(socket: WebSocket) {
+export async function createMessageCollector(
+  socket: WebSocket,
+  channels?: string[],
+) {
+  socket.send(
+    JSON.stringify({ type: "subscribe", channels: channels ?? ALL_CHANNELS }),
+  );
+  await new Promise((resolve) => setTimeout(resolve, 50));
   let renderBuffer: DevtoolsMessage[] = [];
   let flushBuffer: DevtoolsMessage[] = [];
   const completedRenderBatches: DevtoolsMessage[][] = [];
@@ -186,18 +218,28 @@ export function createMessageCollector(socket: WebSocket) {
 
 /**
  * Filter messages to only include render tree messages (those starting with "render:")
+ * Excludes trace messages (those with triggerIds).
  */
 export function filterRenderTreeMessages(
   messages: DevtoolsMessage[],
 ): DevtoolsMessage[] {
-  return messages.filter((m) => m.type.startsWith("render"));
+  return messages.filter(
+    (m) => m.type.startsWith("render") && !("triggerIds" in m),
+  );
 }
 
 /**
- * Filter messages to only include effect debug messages (those starting with "effect:")
+ * Filter messages to only include effect/ref/edge debug messages.
+ * Excludes trace messages (those with triggerIds).
  */
 export function filterEffectsMessages(
   messages: DevtoolsMessage[],
 ): DevtoolsMessage[] {
-  return messages.filter((m) => m.type.startsWith("effect:"));
+  return messages.filter(
+    (m) =>
+      (m.type.startsWith("effect:") ||
+        m.type.startsWith("ref:") ||
+        m.type.startsWith("edge:")) &&
+      !("triggerIds" in m),
+  );
 }

package/testing/extend-expect.ts

@@ -12,9 +12,30 @@ import { expect } from "vitest";
 import { flushJobs, flushJobsAsync } from "../src/scheduler.js";
 import { dedent } from "./render.js";
 
-interface ToRenderToOptions {
+/**
+ * Print options passed to `toRenderTo` / `toRenderToAsync`. These override
+ * the per-`SourceFile` print settings for the duration of the assertion,
+ * which is useful when forcing line-breaking with a narrow `printWidth` in
+ * tests without needing extremely long inputs.
+ *
+ * @example
+ * ```ts
+ * expect(<MyList items={["a", "b", "c"]} />).toRenderTo(
+ *   `
+ *   a,
+ *   b,
+ *   c
+ *   `,
+ *   { printWidth: 10 }
+ * );
+ * ```
+ */
+export interface ToRenderToOptions {
+  /** Maximum line width before the formatter wraps output. */
   printWidth?: number;
+  /** Number of spaces per indentation level. */
   tabWidth?: number;
+  /** Use tab characters instead of spaces. */
   useTabs?: boolean;
 }
 

package/testing/index.ts

@@ -1,3 +1,3 @@
-import "./extend-expect.js";
 export * from "./create-test-wrapper.jsx";
+export * from "./extend-expect.js";
 export * from "./render.js";

package/testing/render.ts

@@ -2,10 +2,19 @@ import { Children, printTree, renderTree } from "../src/index.js";
 
 export { printTree } from "../src/index.js";
 
+/**
+ * Render a JSX element tree to a string. Convenience wrapper combining
+ * `renderTree` and `printTree`.
+ */
 export function renderToString(element: Children) {
   return printTree(renderTree(element));
 }
 
+/**
+ * Dedented template literal tag. Strips leading/trailing blank lines and
+ * removes the common leading whitespace from all lines — useful for
+ * multi-line expected output in tests.
+ */
 export function d(strings: TemplateStringsArray, ...values: any[]): string {
   // Combine the strings and values
   const result = strings.reduce(