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

package/src/reactivity.ts

@@ -2,21 +2,61 @@ import {
   isRef,
   pauseTracking,
   ReactiveEffectRunner,
-  ref,
   Ref,
   resetTracking,
   ShallowReactive,
-  shallowRef,
   stop,
+  computed as vueComputed,
   effect as vueEffect,
+  ref as vueRef,
+  shallowRef as vueShallowRef,
+  toRef as vueToRef,
+  toRefs as vueToRefs,
 } from "@vue/reactivity";
-import type { RenderedTextTree } from "./render.js";
-import type { Children, ComponentCreator } from "./runtime/component.js";
+import {
+  captureSourceLocation,
+  debug,
+  isDevtoolsEnabled,
+} from "./debug/index.js";
+import { RenderedTextTree } from "./render.js";
+import { Children, ComponentCreator } from "./runtime/component.js";
 import { scheduler } from "./scheduler.js";
 import type { OutputSymbol } from "./symbols/output-symbol.js";
-import { trace, TracePhase } from "./tracer.js";
 
-// check for multiple versions of alloy here.
+function attachEffectWriteDebug(refValue: Ref<unknown>, kind: string) {
+  if (!isDevtoolsEnabled()) return;
+  const descriptor =
+    Object.getOwnPropertyDescriptor(refValue, "value") ??
+    Object.getOwnPropertyDescriptor(Object.getPrototypeOf(refValue), "value");
+  if (!descriptor?.get || !descriptor?.set) return;
+  if ((refValue as any).__alloyDebugWrapped) return;
+  Object.defineProperty(refValue, "value", {
+    get: descriptor.get,
+    set(value: unknown) {
+      descriptor.set!.call(this, value);
+      const effectId = globalContext?.meta?.effectId;
+      if (effectId !== undefined && effectId !== -1) {
+        const id = refId(refValue);
+        debug.effect.ensureRef({ id, kind });
+        debug.effect.trigger({
+          effectId,
+          target: refValue,
+          refId: id,
+          location: captureSourceLocation(),
+          kind: "trigger",
+        });
+      }
+    },
+    enumerable: descriptor.enumerable ?? true,
+    configurable: true,
+  });
+  Object.defineProperty(refValue, "__alloyDebugWrapped", {
+    value: true,
+    enumerable: false,
+    configurable: false,
+  });
+}
+
 if ((globalThis as any).__ALLOY__) {
   throw new Error(
     "Multiple versions of Alloy are loaded for this project. This will likely cause undesirable behavior.",
@@ -116,7 +156,7 @@ export function root<T>(fn: (d: Disposable) => T, options?: RootOptions): T {
     ret = untrack(() =>
       fn(() => {
         for (const d of context!.disposables) {
-          d();
+          untrack(d);
         }
       }),
     );
@@ -127,6 +167,15 @@ export function root<T>(fn: (d: Disposable) => T, options?: RootOptions): T {
   return ret;
 }
 
+export interface EffectDebugOptions {
+  name?: string;
+  type?: string;
+}
+
+export interface EffectOptions {
+  debug?: EffectDebugOptions;
+}
+
 export function untrack<T>(fn: () => T): T {
   pauseTracking();
   const v = fn();
@@ -135,17 +184,27 @@ export function untrack<T>(fn: () => T): T {
 }
 
 export function memo<T>(fn: () => T, equal?: boolean): () => T {
-  const o = shallowRef();
-  effect((prev) => {
-    const res = fn();
-    // eslint-disable-next-line @typescript-eslint/no-unused-expressions
-    (!equal || prev !== res) && (o.value = res);
-    return res;
-  }, undefined as T);
-  return () => o.value;
+  const o = shallowRef<T>();
+  effect(
+    (prev) => {
+      const res = fn();
+      // eslint-disable-next-line @typescript-eslint/no-unused-expressions
+      (!equal || prev !== res) && (o.value = res);
+      return res;
+    },
+    undefined as T,
+    {
+      debug: { name: "memo" },
+    },
+  );
+  return () => o.value as T;
 }
 
-export function effect<T>(fn: (prev?: T) => T, current?: T) {
+export function effect<T>(
+  fn: (prev?: T) => T,
+  current?: T,
+  options?: EffectOptions,
+) {
   const context: Context = {
     context: {},
     disposables: [] as (() => void)[],
@@ -157,10 +216,22 @@ export function effect<T>(fn: (prev?: T) => T, current?: T) {
     isRoot: false,
   };
 
+  const debugInfo = options?.debug;
+  const effectId = debug.effect.register({
+    name: debugInfo?.name ?? fn.name,
+    type: debugInfo?.type,
+    createdAt: captureSourceLocation(),
+  });
+
+  context.meta ??= {};
+  if (effectId !== -1) {
+    context.meta.effectId = effectId;
+  }
+
   const cleanupFn = (final: boolean) => {
     const d = context.disposables;
     context.disposables = [];
-    for (let k = 0, len = d.length; k < len; k++) d[k]();
+    for (let k = 0, len = d.length; k < len; k++) untrack(d[k]);
 
     // eslint-disable-next-line @typescript-eslint/no-unused-expressions
     final && stop(runner);
@@ -185,14 +256,56 @@ export function effect<T>(fn: (prev?: T) => T, current?: T) {
       flags: 1 | 4 | 32,
       scheduler: scheduler(),
       onTrack(event) {
-        trace(TracePhase.effect.track, () => {
-          return `tracking ${isRef(event.target) ? `Ref:${refId(event.target)}` : event.target}, ${String(event.key)}`;
-        });
+        if (effectId !== -1) {
+          const targetKey =
+            typeof event.key === "symbol" ? event.key.toString() : event.key;
+          if (isRef(event.target)) {
+            const id = refId(event.target);
+            debug.effect.ensureRef({ id, kind: "ref" });
+            debug.effect.track({
+              effectId,
+              target: event.target,
+              refId: id,
+              targetKey,
+              location: captureSourceLocation(),
+            });
+          } else {
+            debug.effect.track({
+              effectId,
+              target: event.target,
+              targetKey,
+              location: captureSourceLocation(),
+            });
+          }
+        }
+        // track edge emitted via recordEffectTrack
       },
       onTrigger(event) {
-        trace(TracePhase.effect.trigger, () => {
-          return `triggering ${isRef(event.target) ? `Ref:${refId(event.target)}` : event.target}, ${String(event.key)}`;
-        });
+        if (effectId !== -1) {
+          const targetKey =
+            typeof event.key === "symbol" ? event.key.toString() : event.key;
+          if (isRef(event.target)) {
+            const id = refId(event.target);
+            debug.effect.ensureRef({ id, kind: "ref" });
+            debug.effect.trigger({
+              effectId,
+              target: event.target,
+              refId: id,
+              targetKey,
+              location: captureSourceLocation(),
+              kind: "triggered-by",
+            });
+          } else {
+            debug.effect.trigger({
+              effectId,
+              target: event.target,
+              targetKey,
+              location: captureSourceLocation(),
+              kind: "triggered-by",
+            });
+          }
+        }
+        // trigger edge emitted via recordEffectTrigger
       },
     },
   );
@@ -253,6 +366,76 @@ export function isCustomContext(child: Children): child is CustomContext {
   );
 }
 
+export function ref<T>(value?: T): Ref<T> {
+  const result = vueRef(value) as Ref<T>;
+  attachEffectWriteDebug(result, "ref");
+  debug.effect.registerRef({
+    id: refId(result),
+    kind: "ref",
+    createdAt: captureSourceLocation(),
+    createdByEffectId: globalContext?.meta?.effectId,
+  });
+  return result;
+}
+
+export function shallowRef<T>(value?: T): Ref<T> {
+  const result = vueShallowRef(value) as Ref<T>;
+  attachEffectWriteDebug(result, "shallowRef");
+  debug.effect.registerRef({
+    id: refId(result),
+    kind: "shallowRef",
+    createdAt: captureSourceLocation(),
+    createdByEffectId: globalContext?.meta?.effectId,
+  });
+  return result;
+}
+
+export function computed<T>(getter: () => T): Ref<T> {
+  const result = vueComputed(getter) as Ref<T>;
+  debug.effect.registerRef({
+    id: refId(result),
+    kind: "computed",
+    createdAt: captureSourceLocation(),
+    createdByEffectId: globalContext?.meta?.effectId,
+  });
+  return result;
+}
+
+export function toRef<T extends object, K extends keyof T>(
+  object: T,
+  key: K,
+  defaultValue?: T[K],
+): Ref<T[K]> {
+  const result =
+    defaultValue === undefined ?
+      (vueToRef(object, key) as Ref<T[K]>)
+    : (vueToRef(object, key, defaultValue) as Ref<T[K]>);
+  attachEffectWriteDebug(result, "toRef");
+  debug.effect.registerRef({
+    id: refId(result),
+    kind: "toRef",
+    createdAt: captureSourceLocation(),
+    createdByEffectId: globalContext?.meta?.effectId,
+  });
+  return result;
+}
+
+export function toRefs<T extends object>(
+  object: T,
+): { [K in keyof T]: Ref<T[K]> } {
+  const result = vueToRefs(object) as { [K in keyof T]: Ref<T[K]> };
+  for (const refValue of Object.values(result) as Ref<unknown>[]) {
+    attachEffectWriteDebug(refValue, "toRef");
+    debug.effect.registerRef({
+      id: refId(refValue),
+      kind: "toRef",
+      createdAt: captureSourceLocation(),
+      createdByEffectId: globalContext?.meta?.effectId,
+    });
+  }
+  return result;
+}
+
 const seenRefs = new WeakMap<Ref<unknown>, number>();
 let refIdCounter = 1;
 

package/src/render-stack.ts

@@ -0,0 +1,289 @@
+import pc from "picocolors";
+import { contextsByKey } from "./context.js";
+import { SourceDirectoryContext } from "./context/source-directory.js";
+import { SourceFileContext } from "./context/source-file.js";
+import { Context, getContext } from "./reactivity.js";
+import { Component, Props, SourceLocation } from "./runtime/component.js";
+
+// Store render stack for error diagnostics
+const renderStack: Array<{
+  component: Component<any>;
+  props: Props;
+  context: Context | null;
+  source?: SourceLocation;
+}> = [];
+
+export interface RenderStackSnapshotEntry {
+  component: Component<any>;
+  props: Props;
+  context: Context | null;
+  source?: SourceLocation;
+  displayName: string;
+}
+
+export function pushStack(
+  component: Component<any>,
+  props: Props,
+  source?: SourceLocation,
+) {
+  renderStack.push({ component, props, context: getContext(), source });
+}
+
+export function popStack() {
+  renderStack.pop();
+}
+
+export function clearRenderStack() {
+  renderStack.length = 0;
+}
+
+/**
+ * Get the current rendering path from the render stack context.
+ * Prefers SourceFileContext over SourceDirectoryContext.
+ */
+export function getCurrentRenderPath(): string | undefined {
+  let currentPath: string | undefined;
+  for (let i = renderStack.length - 1; i >= 0; i--) {
+    const { context } = renderStack[i];
+    // Prefer SourceFileContext over SourceDirectoryContext
+    if (context?.context?.[SourceFileContext.id]) {
+      const fileContext = context.context[
+        SourceFileContext.id
+      ] as SourceFileContext;
+      return fileContext.path;
+    }
+    if (!currentPath && context?.context?.[SourceDirectoryContext.id]) {
+      const dirContext = context.context[
+        SourceDirectoryContext.id
+      ] as SourceDirectoryContext;
+      currentPath = dirContext.path;
+      // Don't break - keep looking for a SourceFileContext
+    }
+  }
+  return currentPath;
+}
+
+export function getRenderStackSnapshot(): RenderStackSnapshotEntry[] {
+  return renderStack.map((entry) => ({
+    component: entry.component,
+    props: entry.props,
+    context: entry.context,
+    source: entry.source,
+    displayName: getComponentDisplayName(entry.component, entry.props),
+  }));
+}
+
+// Helper functions
+function getComponentDisplayName(
+  component: Component<any>,
+  props: Props,
+): string {
+  // Check if this is a Provider and if we can find its context name
+  if (component.name === "Provider") {
+    // Try to find the context this provider is associated with
+    for (const ctx of contextsByKey.values()) {
+      if (ctx.Provider === component && ctx.name) {
+        return ctx.name;
+      }
+    }
+  }
+  return component.name;
+}
+
+function inspectProps(props: Props) {
+  const entries = Object.entries(props)
+    .filter(([key]) => key !== "children") // Exclude children prop
+    .map(([key, value]) => {
+      const formattedValue = formatValue(value);
+      return `${pc.dim(key)}: ${formattedValue}`;
+    });
+
+  return entries.length > 0 ? entries.join(pc.dim(", ")) : "";
+}
+
+function formatValue(value: unknown): string {
+  switch (typeof value) {
+    case "string":
+      return pc.blue(`"${value}"`);
+    case "number":
+    case "boolean":
+      return pc.blue(String(value));
+    case "undefined":
+      return pc.gray("undefined");
+    case "object":
+      return value ? pc.gray("{...}") : pc.gray("null");
+    case "function":
+      return pc.gray("function");
+    default:
+      return pc.gray(String(value));
+  }
+}
+
+function formatSourceLocation(source: SourceLocation): string {
+  const cwd = process.cwd();
+  let filePath = source.fileName;
+
+  // Convert to relative path if under cwd
+  if (filePath.startsWith(cwd)) {
+    filePath = filePath.slice(cwd.length + 1); // +1 to remove leading slash
+  }
+
+  return `${filePath}:${source.lineNumber}:${source.columnNumber}`;
+}
+
+/**
+ * Print the current render stack to the console for debugging.
+ *
+ * This differs from debug.component.stack in that this uses a purpose-built
+ * stack rather than walking the context chain. When this is called, the context
+ * chain has been restored. In the future this can probably be unified nicely.
+ *
+ * @param error - Optional error to print the stack trace from
+ */
+export function printRenderStack(error?: unknown) {
+  // Find the nearest SourceFileContext or SourceDirectoryContext from the render stack
+  let currentPath: string | undefined;
+  for (let i = renderStack.length - 1; i >= 0; i--) {
+    const { context } = renderStack[i];
+    // Prefer SourceFileContext over SourceDirectoryContext
+    if (context?.context?.[SourceFileContext.id]) {
+      const fileContext = context.context[
+        SourceFileContext.id
+      ] as SourceFileContext;
+      currentPath = fileContext.path;
+      break;
+    }
+    if (!currentPath && context?.context?.[SourceDirectoryContext.id]) {
+      const dirContext = context.context[
+        SourceDirectoryContext.id
+      ] as SourceDirectoryContext;
+      currentPath = dirContext.path;
+      // Don't break - keep looking for a SourceFileContext
+    }
+  }
+
+  if (currentPath) {
+    // eslint-disable-next-line no-console
+    console.error(pc.red(`Error rendering in file ${currentPath}`));
+  } else {
+    // eslint-disable-next-line no-console
+    console.error(pc.red("Error rendering:"));
+  }
+
+  // Print the error message and stack if provided
+  if (error) {
+    if (error instanceof Error) {
+      // eslint-disable-next-line no-console
+      console.error(pc.red(`  ${error.message}`));
+      if (error.stack) {
+        // Print stack lines (skip the first line which is the error message)
+        const stackLines = error.stack.split("\n").slice(1);
+        for (const line of stackLines) {
+          // eslint-disable-next-line no-console
+          console.error(pc.gray(line));
+        }
+      }
+    } else {
+      // eslint-disable-next-line no-console
+      console.error(pc.red(`  ${String(error)}`));
+    }
+    // eslint-disable-next-line no-console
+    console.error(); // Empty line before component stack
+  }
+
+  // First pass: determine which providers should be nested vs standalone
+  // A provider should be nested under its parent if it's from a different file
+  // (i.e., it's part of the component's implementation, not user-provided)
+  const nestedProviderIndices = new Set<number>();
+
+  for (let i = renderStack.length - 1; i >= 0; i--) {
+    const { component, source } = renderStack[i];
+
+    // Skip anonymous components and providers
+    if (!component.name || component.name === "Provider") {
+      continue;
+    }
+
+    // Look for providers that come immediately after this component
+    for (let j = i + 1; j < renderStack.length; j++) {
+      const providerEntry = renderStack[j];
+      if (!providerEntry.component.name) continue;
+      if (providerEntry.component.name !== "Provider") break;
+
+      // Nest provider if it's from a different file (component-internal)
+      const shouldNest =
+        !source ||
+        !providerEntry.source ||
+        source.fileName !== providerEntry.source.fileName;
+
+      if (shouldNest) {
+        nestedProviderIndices.add(j);
+      } else {
+        // Stop looking - this provider and all after should be standalone
+        break;
+      }
+    }
+  }
+
+  // Second pass: print stack entries in order, nesting providers where appropriate
+  for (let i = renderStack.length - 1; i >= 0; i--) {
+    const { component, props, source } = renderStack[i];
+
+    // Skip anonymous components
+    if (!component.name) {
+      continue;
+    }
+
+    // Skip providers that will be nested under their parent
+    if (nestedProviderIndices.has(i)) {
+      continue;
+    }
+
+    const displayName = getComponentDisplayName(component, props);
+    const sourceStr =
+      source ? pc.gray(` (${formatSourceLocation(source)})`) : "";
+
+    // eslint-disable-next-line no-console
+    console.error(`  ${pc.cyan("at")} ${pc.bold(displayName)}${sourceStr}`);
+
+    // Print props on next line if there are any
+    const propsStr = inspectProps(props);
+    if (propsStr) {
+      // eslint-disable-next-line no-console
+      console.error(`     ${propsStr}`);
+    }
+
+    // For non-Provider components, print any nested providers
+    if (component.name !== "Provider") {
+      for (let j = i + 1; j < renderStack.length; j++) {
+        if (!nestedProviderIndices.has(j)) break;
+
+        const providerEntry = renderStack[j];
+        if (!providerEntry.component.name) continue;
+
+        const providerName = getComponentDisplayName(
+          providerEntry.component,
+          providerEntry.props,
+        );
+        const providerSourceStr =
+          providerEntry.source ?
+            pc.gray(` (${formatSourceLocation(providerEntry.source)})`)
+          : "";
+
+        // eslint-disable-next-line no-console
+        console.error(
+          `     ${pc.magenta("provides")} ${pc.bold(providerName)}${providerSourceStr}`,
+        );
+
+        const providerPropsStr = inspectProps(providerEntry.props);
+        if (providerPropsStr) {
+          // eslint-disable-next-line no-console
+          console.error(`       ${providerPropsStr}`);
+        }
+      }
+    }
+  }
+
+  // Clear the stack after printing to avoid stale data on subsequent render errors
+  clearRenderStack();
+}