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

package/src/{debug.ts → debug/cli.ts}

@@ -1,127 +1,16 @@
-import { isReactive } from "@vue/reactivity";
 import Table from "cli-table3";
 import pc from "picocolors";
-import { contextsByKey } from "./context.js";
-import { Context, getContext } from "./reactivity.js";
+import { contextsByKey } from "../context.js";
+import { getContext, untrack } from "../reactivity.js";
+import { isReactiveTarget } from "./effects.js";
 
-interface DebugInterface {
-  component: {
-    stack(): void;
-    tree(): void;
-    watch(): void;
-    render(): void;
-    context(): void;
-  };
-}
-
-const debug: DebugInterface = {
-  component: {
-    stack: debugStack,
-    tree() {
-      //eslint-disable-next-line no-console
-      console.log("tree");
-    },
-    watch() {
-      //eslint-disable-next-line no-console
-      console.log("watch");
-    },
-    render() {
-      //eslint-disable-next-line no-console
-      console.log("render");
-    },
-    context: debugContext,
-  },
-};
-
-function debugStack() {
-  let currentContext = getContext();
-  let foundContexts: Context[] = [];
-  while (currentContext !== null) {
-    if (
-      currentContext.context &&
-      Object.getOwnPropertySymbols(currentContext.context)[0]
-    ) {
-      foundContexts.push(currentContext);
-    }
-
-    if (
-      currentContext.componentOwner &&
-      currentContext.componentOwner.component.name !== "Provider"
-    ) {
-      process.stdout.write(
-        style.component.name(currentContext.componentOwner.component.name) +
-          "\n",
-      );
-      const table = kvTable();
-      const props = currentContext.componentOwner.props;
-
-      table.push([
-        { hAlign: "right", content: "props" },
-        props && Object.keys(props).length > 0 ?
-          dumpValue(props)
-        : pc.gray("(none)"),
-      ]);
-
-      table.push([
-        { hAlign: "right", content: "contexts" },
-        foundContexts.length > 0 ?
-          foundContexts.map((c) => printContext(c, true)).join("\n")
-        : pc.gray("(none)"),
-      ]);
-
-      process.stdout.write(table.toString() + "\n\n");
-      foundContexts = [];
-    }
-
-    currentContext = currentContext.owner;
-  }
-}
-
-function debugContext() {
-  let currentContext = getContext();
-  while (currentContext !== null) {
-    //eslint-disable-next-line no-console
-    console.log(printContext(currentContext));
-    currentContext = currentContext.owner;
-  }
-}
-function printContext(context: Context, omitOwner: boolean = false) {
-  if (!context.context) return "";
-  const key = Object.getOwnPropertySymbols(context.context)[0];
-  if (!key) return "";
-  const contextDefinition = contextsByKey.get(key);
-  const contextName = contextDefinition?.name ?? "unknown context";
-  const value = context.context[key];
-
-  let output = style.context.name(contextName);
-  if (!omitOwner) {
-    const owner = findContextOwner(context);
-    output += " provided by " + style.component.name(owner);
-  }
-
-  output += "\n" + dumpValue(value) + "\n";
-
-  return output;
-}
-
-function findContextOwner(context: Context) {
-  let currentContext: Context | null = context;
-  while (
-    currentContext &&
-    (currentContext.componentOwner === undefined ||
-      currentContext.componentOwner.component.name === "Provider")
-  ) {
-    currentContext = currentContext.owner;
+function reactiveTag(value: unknown) {
+  if (isReactiveTarget(value)) {
+    return " " + pc.greenBright(`reactive`) + " ";
   }
-
-  return currentContext?.componentOwner?.component.name ?? "unknown";
-}
-declare global {
-  var debug: DebugInterface;
+  return "";
 }
 
-globalThis.debug = debug;
-
 const style = {
   value: {
     primitive(value: string | number | boolean | null | undefined) {
@@ -151,13 +40,6 @@ const style = {
   },
 };
 
-function reactiveTag(value: unknown) {
-  if (isReactive(value)) {
-    return " " + pc.greenBright(`reactive`) + " ";
-  }
-  return "";
-}
-
 function dumpValue(value: unknown, level = 0) {
   switch (typeof value) {
     case "boolean":
@@ -209,3 +91,110 @@ function kvTable(sep = "  ") {
     style: { "padding-left": 0, "padding-right": 0 },
   });
 }
+
+function printContext(
+  context: ReturnType<typeof getContext>,
+  omitOwner = false,
+) {
+  if (!context?.context) return "";
+  const key = Object.getOwnPropertySymbols(context.context)[0];
+  if (!key) return "";
+  const contextDefinition = contextsByKey.get(key);
+  const contextName = contextDefinition?.name ?? "unknown context";
+  const value = context.context[key];
+
+  let output = style.context.name(contextName);
+  if (!omitOwner) {
+    const owner = findContextOwner(context);
+    output += " provided by " + style.component.name(owner);
+  }
+
+  output += "\n" + dumpValue(value) + "\n";
+
+  return output;
+}
+
+function findContextOwner(context: ReturnType<typeof getContext>) {
+  let currentContext = context;
+  while (
+    currentContext &&
+    (currentContext.componentOwner === undefined ||
+      currentContext.componentOwner.component.name === "Provider")
+  ) {
+    currentContext = currentContext.owner;
+  }
+
+  return currentContext?.componentOwner?.component.name ?? "unknown";
+}
+
+export function debugStack() {
+  untrack(() => {
+    let currentContext = getContext();
+    let foundContexts: (typeof currentContext)[] = [];
+    while (currentContext !== null) {
+      if (
+        currentContext.context &&
+        Object.getOwnPropertySymbols(currentContext.context)[0]
+      ) {
+        foundContexts.push(currentContext);
+      }
+
+      if (
+        currentContext.componentOwner &&
+        currentContext.componentOwner.component.name !== "Provider"
+      ) {
+        process.stdout.write(
+          style.component.name(currentContext.componentOwner.component.name) +
+            "\n",
+        );
+        const table = kvTable();
+        const props = currentContext.componentOwner.props;
+
+        table.push([
+          { hAlign: "right", content: "props" },
+          props && Object.keys(props).length > 0 ?
+            dumpValue(props)
+          : pc.gray("(none)"),
+        ]);
+
+        table.push([
+          { hAlign: "right", content: "contexts" },
+          foundContexts.length > 0 ?
+            foundContexts.map((c) => printContext(c, true)).join("\n")
+          : pc.gray("(none)"),
+        ]);
+
+        process.stdout.write(table.toString() + "\n\n");
+        foundContexts = [];
+      }
+
+      currentContext = currentContext.owner;
+    }
+  });
+}
+
+export function debugContext() {
+  untrack(() => {
+    let currentContext = getContext();
+    while (currentContext !== null) {
+      // eslint-disable-next-line no-console
+      console.log(printContext(currentContext));
+      currentContext = currentContext.owner;
+    }
+  });
+}
+
+export function debugTree() {
+  // eslint-disable-next-line no-console
+  console.log("tree");
+}
+
+export function debugWatch() {
+  // eslint-disable-next-line no-console
+  console.log("watch");
+}
+
+export function debugRender() {
+  // eslint-disable-next-line no-console
+  console.log("render");
+}

package/src/debug/diagnostics.test.tsx

@@ -0,0 +1,55 @@
+import { afterEach, beforeEach, expect, it } from "vitest";
+import WebSocket from "ws";
+import {
+  createMessageCollector,
+  type DevtoolsMessage,
+} from "../../testing/devtools-utils.js";
+import { Output } from "../components/Output.jsx";
+import {
+  enableDevtools,
+  resetDevtoolsServerForTests,
+} from "../devtools/devtools-server.js";
+import { DiagnosticsCollector } from "../diagnostics.js";
+import { renderAsync } from "../render.js";
+
+let socket: WebSocket | undefined;
+
+beforeEach(async () => {
+  const server = await enableDevtools({ port: 0 });
+  socket = new WebSocket(`ws://127.0.0.1:${server.port}`);
+
+  await new Promise<void>((resolve, reject) => {
+    socket?.once("open", resolve);
+    socket?.once("error", reject);
+  });
+});
+
+afterEach(async () => {
+  if (socket) {
+    socket.close();
+    socket = undefined;
+  }
+
+  await resetDevtoolsServerForTests();
+});
+
+it("emits diagnostics:report messages", async () => {
+  const collector = createMessageCollector(socket!);
+  const diagnostics = new DiagnosticsCollector();
+
+  diagnostics.emit({ message: "Test diagnostic", severity: "warning" });
+
+  await renderAsync(<Output>{"ok"}</Output>);
+
+  const messages = await collector.waitForRender();
+  const diagnosticsMessages = messages.filter(
+    (m: DevtoolsMessage) => m.type === "diagnostics:report",
+  );
+
+  collector.stop();
+
+  expect(diagnosticsMessages[0]).toMatchObject({
+    type: "diagnostics:report",
+    diagnostics: expect.any(Array),
+  });
+});

package/src/debug/effects.test.tsx

@@ -0,0 +1,89 @@
+import { afterEach, beforeEach, expect, it } from "vitest";
+import WebSocket from "ws";
+import {
+  createMessageCollector,
+  filterEffectsMessages,
+} from "../../testing/devtools-utils.js";
+import { Output } from "../components/Output.jsx";
+import {
+  enableDevtools,
+  resetDevtoolsServerForTests,
+} from "../devtools/devtools-server.js";
+import { effect, ref } from "../reactivity.js";
+import { renderAsync } from "../render.js";
+import { debug } from "./index.js";
+
+let socket: WebSocket | undefined;
+
+beforeEach(async () => {
+  debug.effect.reset();
+
+  const server = await enableDevtools({ port: 0 });
+  socket = new WebSocket(`ws://127.0.0.1:${server.port}`);
+  await new Promise<void>((resolve, reject) => {
+    socket?.once("open", resolve);
+    socket?.once("error", reject);
+  });
+});
+
+afterEach(async () => {
+  if (socket) {
+    socket.close();
+    socket = undefined;
+  }
+
+  await resetDevtoolsServerForTests();
+  debug.effect.reset();
+});
+
+it("emits effect, ref, edge, and update messages", async () => {
+  const collector = createMessageCollector(socket!);
+  const r1 = ref(0);
+
+  // Create an effect that reads r1.
+  let observed = 0;
+  effect(() => {
+    observed = r1.value;
+  });
+
+  // Mutate r1 to trigger the effect.
+  r1.value = 42;
+
+  await renderAsync(<Output>{"ok"}</Output>);
+
+  const messages = await collector.waitForRender();
+  const effectsMessages = filterEffectsMessages(messages);
+  collector.stop();
+
+  // Check that core message types are present
+  const byType = (type: string) =>
+    effectsMessages.filter((m: any) => m.type === type);
+  expect(byType("effect:refAdded").length).toBeGreaterThanOrEqual(1);
+  expect(byType("effect:effectAdded").length).toBeGreaterThanOrEqual(1);
+  expect(byType("effect:track").length).toBeGreaterThanOrEqual(1);
+  expect(byType("effect:trigger").length).toBeGreaterThanOrEqual(1);
+  expect(byType("effect:effectUpdated").length).toBeGreaterThanOrEqual(1);
+
+  // Verify message shapes
+  expect(byType("effect:refAdded")[0]).toMatchObject({
+    ref: expect.objectContaining({ id: expect.any(Number), kind: "ref" }),
+  });
+  expect(byType("effect:effectAdded")[0]).toMatchObject({
+    effect: expect.objectContaining({ id: expect.any(Number) }),
+  });
+  expect(byType("effect:track")[0]).toMatchObject({
+    edge: expect.objectContaining({
+      type: "track",
+      effectId: expect.any(Number),
+      refId: expect.any(Number),
+    }),
+  });
+  expect(byType("effect:trigger")[0]).toMatchObject({
+    edge: expect.objectContaining({
+      effectId: expect.any(Number),
+      refId: expect.any(Number),
+    }),
+  });
+
+  expect(observed).toBe(42);
+});

package/src/debug/effects.ts

@@ -0,0 +1,317 @@
+import { isReactive, isRef } from "@vue/reactivity";
+import {
+  emitDevtoolsMessage,
+  isDevtoolsEnabled,
+  TracePhase,
+  traceType,
+} from "./trace.js";
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Effects debug
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface SourceLocation {
+  fileName?: string;
+  lineNumber?: number;
+  columnNumber?: number;
+  stack?: string;
+}
+
+export interface EffectDebugInfo {
+  id: number;
+  name?: string;
+  type?: string;
+  createdAt?: SourceLocation;
+  lastTriggeredByRefId?: number;
+  lastTriggeredAt?: SourceLocation;
+}
+
+export interface RefDebugInfo {
+  id: number;
+  kind?: string;
+  createdAt?: SourceLocation;
+  createdByEffectId?: number;
+}
+
+export interface EffectEdgeDebugInfo {
+  id: number;
+  type: "track" | "trigger" | "triggered-by";
+  effectId: number;
+  refId?: number;
+  targetId?: number;
+  targetKind?: "ref" | "target";
+  targetLabel?: string;
+  targetKey?: string | number;
+  location?: SourceLocation;
+}
+
+const effects = new Map<number, EffectDebugInfo>();
+const refs = new Map<number, RefDebugInfo>();
+let effectIdCounter = 1;
+let edgeEventIdCounter = 1;
+let nonRefTargetIdCounter = 1;
+const nonRefTargetIds = new WeakMap<object, number>();
+const primitiveTargetIds = new Map<unknown, number>();
+
+const STACK_LINE = /\s*at\s+(?:.+?\s+\()?(.+?):(\d+):(\d+)\)?$/;
+const STACK_SKIP = [
+  "node:internal",
+  "/node_modules/",
+  "\\node_modules\\",
+  "/@vue/",
+  "\\@vue\\",
+  "/@alloy-js/",
+  "\\@alloy-js\\",
+  "/packages/core/src/reactivity",
+  "/packages/core/src/devtools/effects-debug",
+  "/packages/core/dist/src/reactivity",
+  "\\packages\\core\\dist\\src\\reactivity",
+  "/packages/core/dist/src/devtools/effects-debug",
+  "\\packages\\core\\dist\\src\\devtools\\effects-debug",
+  "captureSourceLocation",
+];
+
+const VUE_REACTIVITY_MARKERS = [
+  "@vue/reactivity",
+  "reactivity.esm",
+  "reactivity.cjs",
+  "reactivity.global",
+  "/@vue/",
+  "\\@vue\\",
+];
+
+function isVueReactivityLine(line: string) {
+  return VUE_REACTIVITY_MARKERS.some((marker) => line.includes(marker));
+}
+
+function parseStackLine(
+  line: string,
+  stack?: string,
+): SourceLocation | undefined {
+  const match = STACK_LINE.exec(line);
+  if (!match) return undefined;
+  const [, fileName, lineNumber, columnNumber] = match;
+  return {
+    fileName,
+    lineNumber: Number(lineNumber),
+    columnNumber: Number(columnNumber),
+    stack,
+  };
+}
+
+export function captureSourceLocation(
+  skipReactives = true,
+): SourceLocation | undefined {
+  if (!isDevtoolsEnabled()) return undefined;
+  const stack = new Error().stack;
+  if (!stack) {
+    return { stack: "" };
+  }
+  const lines = stack.split("\n").slice(1);
+  for (const line of lines) {
+    if (STACK_SKIP.some((skip) => line.includes(skip))) continue;
+    const parsed = parseStackLine(line, stack);
+    if (parsed) return parsed;
+  }
+
+  if (skipReactives) {
+    for (const line of lines) {
+      if (STACK_SKIP.some((skip) => line.includes(skip))) continue;
+      if (isVueReactivityLine(line)) continue;
+      const parsed = parseStackLine(line, stack);
+      if (parsed) return parsed;
+    }
+  }
+
+  return { stack };
+}
+
+function getNonRefTargetId(target: unknown): number {
+  if (typeof target === "object" && target !== null) {
+    const existing = nonRefTargetIds.get(target);
+    if (existing) return existing;
+    const id = nonRefTargetIdCounter++;
+    nonRefTargetIds.set(target, id);
+    return id;
+  }
+  if (typeof target === "function") {
+    const existing = nonRefTargetIds.get(target as object);
+    if (existing) return existing;
+    const id = nonRefTargetIdCounter++;
+    nonRefTargetIds.set(target as object, id);
+    return id;
+  }
+  const existing = primitiveTargetIds.get(target);
+  if (existing) return existing;
+  const id = nonRefTargetIdCounter++;
+  primitiveTargetIds.set(target, id);
+  return id;
+}
+
+function formatNonRefTargetLabel(target: unknown): string {
+  if (Array.isArray(target)) return "[]";
+  try {
+    return String(target);
+  } catch {
+    return "[Unserializable]";
+  }
+}
+
+/**
+ * Sanitize a Map/object key to ensure it's serializable.
+ */
+function sanitizeTargetKey(key: unknown): string | number | undefined {
+  if (key === undefined) return undefined;
+  if (typeof key === "string" || typeof key === "number") return key;
+  if (typeof key === "symbol") return key.toString();
+  if (typeof key === "object" || typeof key === "function") return "Object";
+  return String(key);
+}
+
+function buildEffectTargetInfo(input: {
+  target: unknown;
+  refId?: number;
+}): Pick<
+  EffectEdgeDebugInfo,
+  "refId" | "targetId" | "targetKind" | "targetLabel"
+> {
+  if (input.refId !== undefined) {
+    return {
+      refId: input.refId,
+      targetId: input.refId,
+      targetKind: "ref",
+    };
+  }
+
+  const targetId = getNonRefTargetId(input.target);
+  return {
+    targetId,
+    targetKind: "target",
+    targetLabel: formatNonRefTargetLabel(input.target),
+  };
+}
+
+function emitEffect(message: { type: string; [key: string]: unknown }) {
+  emitDevtoolsMessage(message);
+}
+
+export function update(input: Partial<EffectDebugInfo> & { id: number }) {
+  if (!isDevtoolsEnabled()) return;
+  const existing = effects.get(input.id);
+  if (!existing) return;
+  const next: EffectDebugInfo = { ...existing, ...input };
+  effects.set(input.id, next);
+  emitEffect({
+    type: traceType(TracePhase.effect.effectUpdated),
+    effect: next,
+  });
+}
+
+export function register(input: {
+  name?: string;
+  type?: string;
+  createdAt?: SourceLocation;
+  contextId?: number;
+  ownerContextId?: number | null;
+}): number {
+  if (!isDevtoolsEnabled()) return -1;
+  const id = effectIdCounter++;
+  const info: EffectDebugInfo = {
+    id,
+    name: input.name,
+    type: input.type,
+    createdAt: input.createdAt ?? captureSourceLocation(),
+  };
+  effects.set(id, info);
+  emitEffect({ type: traceType(TracePhase.effect.effectAdded), effect: info });
+  return id;
+}
+
+export function registerRef(input: {
+  id: number;
+  kind?: string;
+  createdAt?: SourceLocation;
+  createdByEffectId?: number;
+  isInfrastructure?: boolean;
+}) {
+  if (!isDevtoolsEnabled()) return;
+  if (refs.has(input.id)) return;
+  const info: RefDebugInfo = {
+    id: input.id,
+    kind: input.kind,
+    createdAt: input.createdAt ?? captureSourceLocation(),
+    createdByEffectId: input.createdByEffectId,
+  };
+  refs.set(input.id, info);
+  emitEffect({ type: traceType(TracePhase.effect.refAdded), ref: info });
+}
+
+export function ensureRef(input: { id: number; kind?: string }) {
+  if (!isDevtoolsEnabled()) return;
+  if (refs.has(input.id)) return;
+  registerRef({ id: input.id, kind: input.kind });
+}
+
+export function track(input: {
+  effectId: number;
+  target: unknown;
+  refId?: number;
+  targetKey?: unknown;
+  location?: SourceLocation;
+}) {
+  if (!isDevtoolsEnabled()) return;
+  const edge: EffectEdgeDebugInfo = {
+    id: edgeEventIdCounter++,
+    type: "track",
+    effectId: input.effectId,
+    ...buildEffectTargetInfo({ target: input.target, refId: input.refId }),
+    targetKey: sanitizeTargetKey(input.targetKey),
+    location: input.location ?? captureSourceLocation(),
+  };
+  emitEffect({ type: traceType(TracePhase.effect.track), edge });
+}
+
+export function trigger(input: {
+  effectId: number;
+  target: unknown;
+  refId?: number;
+  targetKey?: unknown;
+  location?: SourceLocation;
+  kind?: "trigger" | "triggered-by";
+  causedBy?: number;
+}) {
+  if (!isDevtoolsEnabled()) return;
+  const edge: EffectEdgeDebugInfo = {
+    id: edgeEventIdCounter++,
+    type: input.kind ?? "triggered-by",
+    effectId: input.effectId,
+    ...buildEffectTargetInfo({ target: input.target, refId: input.refId }),
+    targetKey: sanitizeTargetKey(input.targetKey),
+    location: input.location ?? captureSourceLocation(),
+  };
+  emitEffect({ type: traceType(TracePhase.effect.trigger), edge });
+
+  update({
+    id: input.effectId,
+    ...(input.refId !== undefined ? { lastTriggeredByRefId: input.refId } : {}),
+    lastTriggeredAt: input.location ?? captureSourceLocation(),
+  });
+}
+
+export function reset() {
+  effects.clear();
+  refs.clear();
+  primitiveTargetIds.clear();
+  effectIdCounter = 1;
+  edgeEventIdCounter = 1;
+  nonRefTargetIdCounter = 1;
+}
+
+// Utilities used by other debug sections
+export function isRefTarget(value: unknown) {
+  return isRef(value);
+}
+
+export function isReactiveTarget(value: unknown) {
+  return isReactive(value);
+}