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

package/src/debug/effects.ts

@@ -0,0 +1,313 @@
+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;
+}): 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;
+}) {
+  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";
+}) {
+  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);
+}

package/src/debug/files.test.tsx

@@ -0,0 +1,96 @@
+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 { Show } from "../components/Show.jsx";
+import { SourceDirectory } from "../components/SourceDirectory.jsx";
+import { SourceFile } from "../components/SourceFile.jsx";
+import {
+  enableDevtools,
+  resetDevtoolsServerForTests,
+} from "../devtools/devtools-server.js";
+import { ref } from "../reactivity.js";
+import { renderAsync } from "../render.js";
+import { flushJobsAsync } from "../scheduler.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 file and directory add/update/remove messages", async () => {
+  const show = ref(true);
+  const collector = createMessageCollector(socket!);
+
+  await renderAsync(
+    <Output>
+      <Show when={show.value}>
+        <SourceDirectory path="src">
+          <SourceFile path="index.ts" filetype="ts">
+            {"export const value = 1;"}
+          </SourceFile>
+        </SourceDirectory>
+      </Show>
+    </Output>,
+  );
+
+  const initialMessages = await collector.waitForRender();
+  const initialFiles = initialMessages.filter((m: DevtoolsMessage) =>
+    m.type.startsWith("files:"),
+  );
+  expect(initialFiles[0]).toMatchObject({
+    path: "./",
+  });
+  expect(initialFiles[1]).toMatchObject({
+    type: "files:directoryAdded",
+    path: "src",
+  });
+  expect(initialFiles[2]).toMatchObject({
+    type: "files:fileAdded",
+    path: "src/index.ts",
+    filetype: "ts",
+  });
+  expect(initialFiles[3]).toMatchObject({
+    type: "files:fileUpdated",
+    path: "src/index.ts",
+    filetype: "ts",
+    contents: expect.any(String),
+  });
+
+  show.value = false;
+  await flushJobsAsync();
+
+  const updateMessages = await collector.waitForFlush();
+  const updateFiles = updateMessages.filter((m: DevtoolsMessage) =>
+    m.type.startsWith("files:"),
+  );
+  collector.stop();
+
+  expect(updateFiles[0]).toMatchObject({
+    type: "files:fileRemoved",
+    path: "src/index.ts",
+  });
+  expect(updateFiles[1]).toMatchObject({
+    type: "files:directoryRemoved",
+    path: "src",
+  });
+});

package/src/debug/files.ts

@@ -0,0 +1,40 @@
+import { emitDevtoolsMessage, isDevtoolsEnabled } from "./trace.js";
+
+export interface FileUpdateInfo {
+  path: string;
+  filetype: string;
+  contents: string;
+}
+
+const fileContentCache = new Map<string, string>();
+
+/** Record a directory being added to the output. */
+export function recordDirectory(path: string) {
+  if (!isDevtoolsEnabled()) return;
+  emitDevtoolsMessage({ type: "files:directoryAdded", path });
+}
+
+/** Record a file being added to the output. */
+export function recordFile(path: string, filetype: string) {
+  if (!isDevtoolsEnabled()) return;
+  emitDevtoolsMessage({ type: "files:fileAdded", path, filetype });
+}
+
+/** Notify devtools that a file's contents have changed. De-duplicates by content. */
+export function updated(info: FileUpdateInfo) {
+  const previous = fileContentCache.get(info.path);
+  if (previous === info.contents) return;
+  fileContentCache.set(info.path, info.contents);
+
+  emitDevtoolsMessage({
+    type: "files:fileUpdated",
+    path: info.path,
+    filetype: info.filetype,
+    contents: info.contents,
+  });
+}
+
+/** Clear all cached file state. Called when a new render begins. */
+export function reset() {
+  fileContentCache.clear();
+}

package/src/debug/index.ts

@@ -0,0 +1,126 @@
+import {
+  assertDevtoolsConnectedForSyncRender,
+  initDevtoolsIfEnabled,
+  isDevtoolsEnabled,
+} from "../devtools/devtools-server.js";
+import {
+  debugContext,
+  debugRender,
+  debugStack,
+  debugTree,
+  debugWatch,
+} from "./cli.js";
+import {
+  ensureRef,
+  register,
+  registerRef,
+  reset,
+  track,
+  trigger,
+  update,
+} from "./effects.js";
+import {
+  recordDirectory,
+  recordFile,
+  reset as resetFiles,
+  updated,
+} from "./files.js";
+import {
+  appendCustomContext,
+  appendFragmentChild,
+  appendPrintHook,
+  appendTextNode,
+  beginComponent,
+  complete,
+  error,
+  flushJobsComplete,
+  initialize,
+  prepareMemoNode,
+} from "./render.js";
+import {
+  registerScope,
+  registerSymbol,
+  reset as resetSymbols,
+  unregisterScope,
+  unregisterSymbol,
+} from "./symbols.js";
+import { trace, type TracePhaseInfo } from "./trace.js";
+
+export { captureSourceLocation } from "./effects.js";
+export type {
+  EffectDebugInfo,
+  EffectEdgeDebugInfo,
+  RefDebugInfo,
+} from "./effects.js";
+export { getRenderNodeId, type RenderTreeNodeInfo } from "./render.js";
+export type {
+  BeginComponentOptions,
+  ComponentDebugSession,
+  RenderErrorInfo,
+  RenderErrorStackEntry,
+} from "./render.js";
+export {
+  isConsoleTraceEnabled,
+  isDevtoolsEnabled,
+  trace,
+  TracePhase,
+  type TracePhaseInfo,
+} from "./trace.js";
+
+/** The full debug runtime interface, derived from the `debug` object implementation. */
+export type DebugRuntime = typeof debug;
+
+export const debug = {
+  component: {
+    stack: debugStack,
+    tree: debugTree,
+    watch: debugWatch,
+    render: debugRender,
+    context: debugContext,
+  },
+  effect: {
+    register,
+    update,
+    registerRef,
+    ensureRef,
+    track,
+    trigger,
+    reset,
+  },
+  render: {
+    initialize,
+    appendTextNode,
+    appendCustomContext,
+    appendPrintHook,
+    appendFragmentChild,
+    beginComponent,
+    prepareMemoNode,
+    error,
+    complete,
+    flushJobsComplete,
+  },
+  files: {
+    recordDirectory,
+    recordFile,
+    updated,
+    reset: resetFiles,
+  },
+  symbols: {
+    registerScope,
+    unregisterScope,
+    registerSymbol,
+    unregisterSymbol,
+    reset: resetSymbols,
+  },
+  trace(phase: TracePhaseInfo, cb: () => string, triggerIds?: Set<number>) {
+    trace(phase, cb, triggerIds ?? new Set());
+  },
+  async prepare(): Promise<void> {
+    await initDevtoolsIfEnabled();
+  },
+  assertReadyForSyncRender(): void {
+    if (isDevtoolsEnabled()) {
+      assertDevtoolsConnectedForSyncRender();
+    }
+  },
+};