@alloy-js/core 0.23.0-dev.1 → 0.23.0-dev.11

package/package.json

@@ -1,7 +1,11 @@
 {
   "name": "@alloy-js/core",
-  "version": "0.23.0-dev.1",
+  "version": "0.23.0-dev.11",
   "description": "",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/alloy-framework/alloy.git"
+  },
   "main": "./dist/src/index.js",
   "exports": {
     ".": {
@@ -23,33 +27,43 @@
     },
     "./components": {
       "import": "./dist/src/components/index.js"
+    },
+    "./devtools": {
+      "types": "./dist/src/devtools-entry.d.ts",
+      "browser": "./dist/src/devtools-entry.browser.js",
+      "import": "./dist/src/devtools-entry.js"
     }
   },
   "browser": {
     "./dist/src/host/alloy-host.js": "./dist/src/host/alloy-host.browser.js",
     "./src/host/alloy-host.ts": "./src/host/alloy-host.browser.ts",
     "./dist/src/inspect.js": "./dist/src/inspect.browser.js",
-    "./src/inspect.ts": "./src/inspect.browser.ts"
+    "./src/inspect.ts": "./src/inspect.browser.ts",
+    "./dist/src/devtools/devtools-server.js": "./dist/src/devtools/devtools-server.browser.js",
+    "./src/devtools/devtools-server.ts": "./src/devtools/devtools-server.browser.ts"
   },
   "keywords": [],
   "author": "brian.terlson@microsoft.com",
   "license": "MIT",
   "dependencies": {
+    "@types/ws": "^8.18.1",
     "@vue/reactivity": "^3.5.13",
-    "picocolors": "^1.1.1",
     "cli-table3": "^0.6.5",
+    "devalue": "^5.6.2",
     "pathe": "^2.0.3",
-    "prettier": "^3.6.2"
+    "picocolors": "^1.1.1",
+    "prettier": "^3.6.2",
+    "ws": "^8.19.0"
   },
   "devDependencies": {
-    "@alloy-js/cli": "~0.22.0 || >= 0.23.0-dev.1",
-    "@alloy-js/rollup-plugin": "~0.1.0 || >= 0.1.1-dev.0",
+    "@alloy-js/cli": "~0.22.0 || >= 0.23.0-dev.3",
+    "@alloy-js/rollup-plugin": "~0.1.0 || >= 0.1.1-dev.1",
     "@microsoft/api-extractor": "~7.52.8",
     "@rollup/plugin-typescript": "^12.1.2",
     "concurrently": "^9.2.0",
     "typescript": "^5.8.3",
     "vite": "^7.0.6",
-    "vitest": "^3.2.4"
+    "vitest": "3.2.4"
   },
   "type": "module",
   "scripts": {

package/scripts/copy-devtools-ui.mjs

@@ -0,0 +1,26 @@
+#!/usr/bin/env node
+
+import { copyFile, mkdir } from "fs/promises";
+import { dirname, join } from "path";
+import { fileURLToPath } from "url";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+const srcFile = join(__dirname, "../../devtools/dist/index.html");
+const destFile = join(__dirname, "../dist/devtools/index.html");
+
+async function copyDevtoolsUi() {
+  try {
+    await mkdir(dirname(destFile), { recursive: true });
+    await copyFile(srcFile, destFile);
+    // eslint-disable-next-line no-console
+    console.log("Copied devtools UI to core dist");
+  } catch (error) {
+    // eslint-disable-next-line no-console
+    console.error("Failed to copy devtools UI:", error);
+    process.exit(1);
+  }
+}
+
+void copyDevtoolsUi();

package/src/binder.ts

@@ -2,8 +2,11 @@ import { computed, Ref, ShallowRef, shallowRef } from "@vue/reactivity";
 import { useBinder } from "./context/binder.js";
 import { useMemberContext } from "./context/member-scope.js";
 import { useScope } from "./context/scope.js";
-import { effect } from "./reactivity.js";
+import { debug, TracePhase } from "./debug/index.js";
+import { emitDiagnostic, type DiagnosticHandle } from "./diagnostics.js";
+import { effect, onCleanup } from "./reactivity.js";
 import {
+  inspectRefkey,
   isMemberRefkey,
   MemberRefkey,
   refkey,
@@ -13,12 +16,7 @@ import {
 } from "./refkey.js";
 import { OutputScope } from "./symbols/output-scope.js";
 import { type OutputSymbol } from "./symbols/output-symbol.js";
-import {
-  formatRefkeys,
-  formatSymbolName,
-  trace,
-  TracePhase,
-} from "./tracer.js";
+import { formatRefkeys, formatSymbolName } from "./tracer.js";
 export type Metadata = object;
 
 /**
@@ -211,6 +209,24 @@ export interface BinderOptions {
   nameConflictResolver?: NameConflictResolver;
 }
 
+export function createScope<TScope extends OutputScope, Args extends unknown[]>(
+  ctor: new (...args: Args) => TScope,
+  ...args: Args
+): TScope {
+  const scope = new ctor(...args);
+  debug.symbols.registerScope(scope);
+  return scope;
+}
+
+export function createSymbol<
+  TSymbol extends OutputSymbol,
+  Args extends unknown[],
+>(ctor: new (...args: Args) => TSymbol, ...args: Args): TSymbol {
+  const symbol = new ctor(...args);
+  debug.symbols.registerSymbol(symbol);
+  return symbol;
+}
+
 export function createOutputBinder(options: BinderOptions = {}): Binder {
   const binder: Binder = {
     resolveDeclarationByKey,
@@ -247,6 +263,7 @@ export function createOutputBinder(options: BinderOptions = {}): Binder {
   }
 
   function notifySymbolDeleted(symbol: OutputSymbol) {
+    debug.symbols.unregisterSymbol(symbol);
     if (!refkey) {
       return;
     }
@@ -458,25 +475,25 @@ export function createOutputBinder(options: BinderOptions = {}): Binder {
     const resolvedSymbol = getSymbolForRefkey(refkey);
 
     return computed(() => {
-      trace(
+      debug.trace(
         TracePhase.resolve.pending,
         () => `Resolving ${formatRefkeys(refkey)}.`,
       );
       const symbol = resolvedSymbol.value as TSymbol;
       if (!symbol) {
-        trace(
+        debug.trace(
           TracePhase.resolve.failure,
           () => `No symbol for ${formatRefkeys(refkey)}.`,
         );
         return undefined;
       }
-      trace(
+      debug.trace(
         TracePhase.resolve.pending,
         () =>
           `${formatRefkeys(refkey)} resolved to ${formatSymbolName(symbol)}.`,
       );
       if (symbol.isTransient) {
-        trace(
+        debug.trace(
           TracePhase.resolve.failure,
           () => `Symbol ${formatSymbolName(symbol)} is transient.`,
         );
@@ -485,7 +502,7 @@ export function createOutputBinder(options: BinderOptions = {}): Binder {
 
       const chain = scopeChain(symbol.scope);
       if (chain.some((scope) => scope.isTransient)) {
-        trace(
+        debug.trace(
           TracePhase.resolve.failure,
           () => `Symbol ${formatSymbolName(symbol)} is in a transient scope.`,
         );
@@ -533,7 +550,7 @@ export function createOutputBinder(options: BinderOptions = {}): Binder {
         for (const descriptor of allDescriptors) {
           const member = descriptor.symbol as TSymbol;
           if (currentBase.isTyped && !currentBase.hasTypeSymbol) {
-            trace(
+            debug.trace(
               TracePhase.resolve.pending,
               () =>
                 `${formatRefkeys(refkey)} needs type information from a parent type.`,
@@ -550,7 +567,7 @@ export function createOutputBinder(options: BinderOptions = {}): Binder {
           currentBase = member;
         }
 
-        trace(
+        debug.trace(
           TracePhase.resolve.success,
           () =>
             `${formatRefkeys(refkey)} successfully resolved to ${formatSymbolName(symbol)}.`,
@@ -626,54 +643,63 @@ export function createOutputBinder(options: BinderOptions = {}): Binder {
   }
 
   function notifySymbolCreated(symbol: OutputSymbol): void {
-    effect<Refkey[]>((oldRefkeys) => {
-      if (symbol.refkeys) {
-        trace(
-          TracePhase.resolve.pending,
-          () => `Notifying resolutions for ${formatRefkeys(symbol.refkeys)}.`,
-        );
-      }
-
-      if (oldRefkeys) {
-        for (const refkey of oldRefkeys) {
-          if (!symbol.refkeys.includes(refkey)) {
-            // remove the old refkey from the known declarations
-            knownDeclarations.delete(refkey);
+    effect<Refkey[]>(
+      (oldRefkeys) => {
+        if (symbol.refkeys) {
+          debug.trace(
+            TracePhase.resolve.pending,
+            () => `Notifying resolutions for ${formatRefkeys(symbol.refkeys)}.`,
+          );
+        }
 
-            // reset any waiting declarations
-            if (waitingDeclarations.has(refkey)) {
-              const signal = waitingDeclarations.get(refkey)!;
-              signal.value = undefined;
+        if (oldRefkeys) {
+          for (const refkey of oldRefkeys) {
+            if (!symbol.refkeys.includes(refkey)) {
+              // remove the old refkey from the known declarations
+              knownDeclarations.delete(refkey);
+
+              // reset any waiting declarations
+              if (waitingDeclarations.has(refkey)) {
+                const signal = waitingDeclarations.get(refkey)!;
+                signal.value = undefined;
+              }
             }
           }
         }
-      }
 
-      for (const refkey of symbol.refkeys) {
-        // notify those waiting for this refkey
-        knownDeclarations.set(refkey, symbol);
-        if (waitingDeclarations.has(refkey)) {
-          const signal = waitingDeclarations.get(refkey)!;
-          signal.value = symbol;
-        }
+        for (const refkey of symbol.refkeys) {
+          // notify those waiting for this refkey
+          knownDeclarations.set(refkey, symbol);
+          if (waitingDeclarations.has(refkey)) {
+            const signal = waitingDeclarations.get(refkey)!;
+            signal.value = symbol;
+          }
 
-        const scope = symbol.scope;
-        if (!scope) {
-          continue;
-        }
+          const scope = symbol.scope;
+          if (!scope) {
+            continue;
+          }
 
-        // notify those waiting for this symbol name
-        const waitingScope = waitingSymbolNames.get(scope);
-        if (waitingScope) {
-          const waitingName = waitingScope.get(symbol.name);
-          if (waitingName) {
-            waitingName.value = symbol;
+          // notify those waiting for this symbol name
+          const waitingScope = waitingSymbolNames.get(scope);
+          if (waitingScope) {
+            const waitingName = waitingScope.get(symbol.name);
+            if (waitingName) {
+              waitingName.value = symbol;
+            }
           }
         }
-      }
 
-      return [...symbol.refkeys];
-    });
+        return [...symbol.refkeys];
+      },
+      undefined,
+      {
+        debug: {
+          name: "binder:notifySymbolCreated",
+          type: "binder",
+        },
+      },
+    );
   }
 }
 
@@ -702,11 +728,49 @@ export function resolve<
     throw new Error("Can't resolve refkey without a binder");
   }
 
-  return binder.resolveDeclarationByKey(
+  const result = binder.resolveDeclarationByKey(
     scope as TScope,
     refkey,
     options,
   ) as any;
+
+  let diagnosticHandle: DiagnosticHandle | null = null;
+
+  effect(
+    () => {
+      if (result.value === undefined) {
+        // Emit diagnostic for this specific reference site
+        if (!diagnosticHandle) {
+          diagnosticHandle = emitDiagnostic({
+            severity: "warning",
+            message: `Unresolved refkey: ${inspectRefkey(refkey)}`,
+          });
+        }
+      } else {
+        // Dismiss diagnostic when resolved
+        if (diagnosticHandle) {
+          diagnosticHandle.dismiss();
+          diagnosticHandle = null;
+        }
+      }
+    },
+    undefined,
+    {
+      debug: {
+        name: `binder:resolve:${inspectRefkey(refkey)}`,
+        type: "binder",
+      },
+    },
+  );
+
+  onCleanup(() => {
+    if (diagnosticHandle) {
+      diagnosticHandle.dismiss();
+      diagnosticHandle = null;
+    }
+  });
+
+  return result;
 }
 
 /**

package/src/components/AccessExpression.test.tsx

@@ -0,0 +1,132 @@
+import { describe, expect, it } from "vitest";
+import "../../testing/extend-expect.js";
+import {
+  BasePartProps,
+  createAccessExpression,
+} from "../components/AccessExpression.jsx";
+import { code } from "../index.js";
+import { printTree, renderTree } from "../render.js";
+import { Children } from "../runtime/component.js";
+
+interface TestPartProps extends BasePartProps {
+  name?: string;
+  args?: Children;
+}
+
+interface TestPart extends Record<string, unknown> {
+  name: string | undefined;
+  args: Children | undefined;
+  isFirst: boolean;
+}
+
+const { Expression, Part } = createAccessExpression<TestPartProps, TestPart>({
+  createDescriptor(props, symbol, first) {
+    return {
+      name: symbol?.name ?? props.name,
+      args: props.args,
+      isFirst: first,
+    };
+  },
+
+  getBase(part) {
+    return part.name ?? "";
+  },
+
+  formatPart(part, _prevPart, _inCallChain) {
+    if (part.args !== undefined) {
+      return code`.${part.name}(${part.args})`;
+    }
+    return code`.${part.name}`;
+  },
+
+  isCallPart(part) {
+    return part.args !== undefined;
+  },
+});
+
+describe("createAccessExpression", () => {
+  it("renders a single part as the base", () => {
+    expect(
+      <Expression>
+        <Part name="foo" />
+      </Expression>,
+    ).toRenderTo("foo");
+  });
+
+  it("renders multiple parts with dot access", () => {
+    expect(
+      <Expression>
+        <Part name="foo" />
+        <Part name="bar" />
+        <Part name="baz" />
+      </Expression>,
+    ).toRenderTo("foo.bar.baz");
+  });
+
+  it("renders parts with call arguments", () => {
+    expect(
+      <Expression>
+        <Part name="foo" />
+        <Part name="bar" args="x, y" />
+      </Expression>,
+    ).toRenderTo("foo.bar(x, y)");
+  });
+
+  it("returns empty for no parts", () => {
+    expect(<Expression>{false}</Expression>).toRenderTo("");
+  });
+
+  it("flattens nested Expression instances", () => {
+    const inner = (
+      <Expression>
+        <Part name="bar" />
+        <Part name="baz" />
+      </Expression>
+    );
+
+    expect(
+      <Expression>
+        <Part name="foo" />
+        {inner}
+      </Expression>,
+    ).toRenderTo("foo.bar.baz");
+  });
+
+  it("ignores non-Part children", () => {
+    expect(
+      <Expression>
+        <Part name="foo" />
+        {"some string"}
+        <Part name="bar" />
+      </Expression>,
+    ).toRenderTo("foo.bar");
+  });
+});
+
+describe("createAccessExpression: call chain formatting", () => {
+  it("uses linear format with only one call", () => {
+    const tree = renderTree(
+      <Expression>
+        <Part name="foo" />
+        <Part name="bar" args="x" />
+      </Expression>,
+    );
+    // Single call → linear, no grouping.
+    expect(printTree(tree)).toBe("foo.bar(x)");
+  });
+
+  it("uses call chain format with multiple calls", () => {
+    const tree = renderTree(
+      <Expression>
+        <Part name="foo" />
+        <Part name="bar" args="x" />
+        <Part name="baz" args="y" />
+      </Expression>,
+    );
+    // Multiple calls → call chain with group/indent wrapping.
+    const result = printTree(tree);
+    // Should contain both calls.
+    expect(result).toContain("bar(x)");
+    expect(result).toContain("baz(y)");
+  });
+});