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

package/src/debug/effects.ts

@@ -1,7 +1,14 @@
 import { isReactive, isRef } from "@vue/reactivity";
 import {
-  emitDevtoolsMessage,
-  isDevtoolsEnabled,
+  formatReactivePropertyLabel,
+  getReactiveCreationLocation,
+  nextReactiveId,
+} from "../reactivity.js";
+import { insertEdge, insertEffect, insertRef } from "./trace-writer.js";
+import {
+  isDebugEnabled,
+  isTraceEnabled,
+  logDevtoolsMessage,
   TracePhase,
   traceType,
 } from "./trace.js";
@@ -22,15 +29,19 @@ export interface EffectDebugInfo {
   name?: string;
   type?: string;
   createdAt?: SourceLocation;
+  contextId?: number;
+  ownerContextId?: number | null;
+  component?: string;
   lastTriggeredByRefId?: number;
-  lastTriggeredAt?: SourceLocation;
 }
 
 export interface RefDebugInfo {
   id: number;
   kind?: string;
+  label?: string;
   createdAt?: SourceLocation;
   createdByEffectId?: number;
+  isApproxLocation?: boolean;
 }
 
 export interface EffectEdgeDebugInfo {
@@ -42,33 +53,50 @@ export interface EffectEdgeDebugInfo {
   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+)\)?$/;
+// Alloy-internal paths to skip when capturing source locations.
+// We skip core infrastructure (reactivity, render, debug, scheduler, etc.)
+// but allow component and symbol frames through so the location points at
+// the component/symbol that created the effect.
+// These patterns match both src/ and dist/src/ paths.
+const CORE_INTERNAL_PATHS = [
+  "/core/src/reactivity",
+  "/core/src/render",
+  "/core/src/scheduler",
+  "/core/src/debug/",
+  "/core/src/devtools/",
+  "/core/src/resource",
+  "/core/src/context",
+  "/core/src/tracer",
+  "/core/src/reactive-union-set",
+  "/core/src/utils",
+  "/core/dist/src/reactivity",
+  "/core/dist/src/render",
+  "/core/dist/src/scheduler",
+  "/core/dist/src/debug/",
+  "/core/dist/src/devtools/",
+  "/core/dist/src/resource",
+  "/core/dist/src/context",
+  "/core/dist/src/tracer",
+  "/core/dist/src/reactive-union-set",
+  "/core/dist/src/utils",
+];
+
 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",
+  ...CORE_INTERNAL_PATHS,
+  ...CORE_INTERNAL_PATHS.map((p) => p.replace(/\//g, "\\")),
 ];
 
 const VUE_REACTIVITY_MARKERS = [
@@ -80,70 +108,185 @@ const VUE_REACTIVITY_MARKERS = [
   "\\@vue\\",
 ];
 
-function isVueReactivityLine(line: string) {
-  return VUE_REACTIVITY_MARKERS.some((marker) => line.includes(marker));
+// ─────────────────────────────────────────────────────────────────────────────
+// Fast source location capture using V8 structured CallSite API
+// ─────────────────────────────────────────────────────────────────────────────
+
+// Lazily loaded findSourceMap from node:module
+let findSourceMap:
+  | ((path: string) =>
+      | {
+          findEntry: (
+            line: number,
+            col: number,
+          ) =>
+            | {
+                originalSource: string;
+                originalLine: number;
+                originalColumn: number;
+              }
+            | undefined;
+        }
+      | undefined)
+  | undefined;
+let findSourceMapLoaded = false;
+let realpathSync: ((path: string) => string) | undefined;
+// Cache realpath lookups to avoid repeated fs calls
+const realpathCache = new Map<string, string>();
+
+function loadFindSourceMap() {
+  if (findSourceMapLoaded) return;
+  findSourceMapLoaded = true;
+  // process.getBuiltinModule works in both ESM and CJS contexts
+  try {
+    const mod = process.getBuiltinModule?.("node:module") as
+      | typeof import("node:module")
+      | undefined;
+    if (mod && typeof mod.findSourceMap === "function") {
+      findSourceMap = mod.findSourceMap as typeof findSourceMap;
+    }
+  } catch {
+    // not available
+  }
+  try {
+    const fs = process.getBuiltinModule?.("node:fs") as
+      | typeof import("node:fs")
+      | undefined;
+    if (fs) {
+      realpathSync = fs.realpathSync;
+    }
+  } catch {
+    // not available
+  }
 }
 
-function parseStackLine(
-  line: string,
-  stack?: string,
-): SourceLocation | undefined {
-  const match = STACK_LINE.exec(line);
-  if (!match) return undefined;
-  const [, fileName, lineNumber, columnNumber] = match;
+function getRealPath(fileName: string): string {
+  if (!realpathSync) return fileName;
+  let real = realpathCache.get(fileName);
+  if (real === undefined) {
+    try {
+      real = realpathSync(fileName);
+    } catch {
+      real = fileName;
+    }
+    realpathCache.set(fileName, real);
+  }
+  return real;
+}
+
+function isSkipFile(fileName: string): boolean {
+  for (const skip of STACK_SKIP) {
+    if (fileName.includes(skip)) return true;
+  }
+  return false;
+}
+
+function isVueReactivityFile(fileName: string): boolean {
+  for (const marker of VUE_REACTIVITY_MARKERS) {
+    if (fileName.includes(marker)) return true;
+  }
+  return false;
+}
+
+function resolveSourceMap(
+  fileName: string,
+  line: number,
+  col: number,
+): { fileName: string; line: number; col: number } {
+  if (!findSourceMap) return { fileName, line, col };
+  // pnpm uses symlinks; findSourceMap only matches the real path
+  const real = getRealPath(fileName);
+  const map = findSourceMap(real);
+  if (!map) return { fileName, line, col };
+  const entry = map.findEntry(line - 1, col - 1);
+  if (!entry) return { fileName, line, col };
   return {
-    fileName,
-    lineNumber: Number(lineNumber),
-    columnNumber: Number(columnNumber),
-    stack,
+    fileName: entry.originalSource,
+    line: entry.originalLine + 1,
+    col: entry.originalColumn + 1,
   };
 }
 
+// V8 structured stack capture — avoids string formatting entirely
+const structuredPrepare = (
+  _err: Error,
+  callSites: NodeJS.CallSite[],
+): NodeJS.CallSite[] => callSites;
+
+function captureCallSites(): NodeJS.CallSite[] {
+  const orig = Error.prepareStackTrace;
+  Error.prepareStackTrace = structuredPrepare;
+  const obj: { stack?: NodeJS.CallSite[] } = {};
+  Error.captureStackTrace(obj, captureCallSites);
+  const sites = obj.stack ?? [];
+  Error.prepareStackTrace = orig;
+  return sites;
+}
+
 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 (!isDebugEnabled()) return undefined;
+  loadFindSourceMap();
+
+  const sites = captureCallSites();
+
+  // First pass: skip internal/framework frames
+  for (const site of sites) {
+    const fn = site.getFileName();
+    if (!fn) continue;
+    if (isSkipFile(fn)) continue;
+    if (skipReactives && isVueReactivityFile(fn)) continue;
+
+    const line = site.getLineNumber() ?? 0;
+    const col = site.getColumnNumber() ?? 0;
+    const resolved = resolveSourceMap(fn, line, col);
+    return {
+      fileName: resolved.fileName,
+      lineNumber: resolved.line,
+      columnNumber: resolved.col,
+    };
   }
 
+  // Second pass without reactive filter
   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;
+    for (const site of sites) {
+      const fn = site.getFileName();
+      if (!fn) continue;
+      if (isSkipFile(fn)) continue;
+
+      const line = site.getLineNumber() ?? 0;
+      const col = site.getColumnNumber() ?? 0;
+      const resolved = resolveSourceMap(fn, line, col);
+      return {
+        fileName: resolved.fileName,
+        lineNumber: resolved.line,
+        columnNumber: resolved.col,
+      };
     }
   }
 
-  return { stack };
+  return undefined;
 }
 
 function getNonRefTargetId(target: unknown): number {
   if (typeof target === "object" && target !== null) {
     const existing = nonRefTargetIds.get(target);
     if (existing) return existing;
-    const id = nonRefTargetIdCounter++;
+    const id = nextReactiveId();
     nonRefTargetIds.set(target, id);
     return id;
   }
   if (typeof target === "function") {
     const existing = nonRefTargetIds.get(target as object);
     if (existing) return existing;
-    const id = nonRefTargetIdCounter++;
+    const id = nextReactiveId();
     nonRefTargetIds.set(target as object, id);
     return id;
   }
   const existing = primitiveTargetIds.get(target);
   if (existing) return existing;
-  const id = nonRefTargetIdCounter++;
+  const id = nextReactiveId();
   primitiveTargetIds.set(target, id);
   return id;
 }
@@ -192,11 +335,11 @@ function buildEffectTargetInfo(input: {
 }
 
 function emitEffect(message: { type: string; [key: string]: unknown }) {
-  emitDevtoolsMessage(message);
+  logDevtoolsMessage(message);
 }
 
 export function update(input: Partial<EffectDebugInfo> & { id: number }) {
-  if (!isDevtoolsEnabled()) return;
+  if (!isDebugEnabled()) return;
   const existing = effects.get(input.id);
   if (!existing) return;
   const next: EffectDebugInfo = { ...existing, ...input };
@@ -214,16 +357,32 @@ export function register(input: {
   contextId?: number;
   ownerContextId?: number | null;
 }): number {
-  if (!isDevtoolsEnabled()) return -1;
+  if (!isDebugEnabled()) return -1;
   const id = effectIdCounter++;
   const info: EffectDebugInfo = {
     id,
     name: input.name,
     type: input.type,
     createdAt: input.createdAt ?? captureSourceLocation(),
+    contextId: input.contextId,
+    ownerContextId: input.ownerContextId ?? null,
   };
   effects.set(id, info);
   emitEffect({ type: traceType(TracePhase.effect.effectAdded), effect: info });
+
+  if (isTraceEnabled()) {
+    insertEffect(
+      id,
+      input.name,
+      input.type,
+      input.contextId,
+      input.ownerContextId ?? null,
+      info.createdAt?.fileName,
+      info.createdAt?.lineNumber,
+      info.createdAt?.columnNumber,
+    );
+  }
+
   return id;
 }
 
@@ -233,42 +392,90 @@ export function registerRef(input: {
   createdAt?: SourceLocation;
   createdByEffectId?: number;
   isInfrastructure?: boolean;
+  isApproxLocation?: boolean;
+  label?: string;
 }) {
-  if (!isDevtoolsEnabled()) return;
+  if (!isDebugEnabled()) return;
   if (refs.has(input.id)) return;
   const info: RefDebugInfo = {
     id: input.id,
     kind: input.kind,
     createdAt: input.createdAt ?? captureSourceLocation(),
     createdByEffectId: input.createdByEffectId,
+    label: input.label,
+    isApproxLocation: input.isApproxLocation,
   };
   refs.set(input.id, info);
   emitEffect({ type: traceType(TracePhase.effect.refAdded), ref: info });
+
+  if (isTraceEnabled()) {
+    insertRef(
+      input.id,
+      input.kind,
+      input.createdByEffectId,
+      info.createdAt?.fileName,
+      info.createdAt?.lineNumber,
+      info.createdAt?.columnNumber,
+      input.label,
+      input.isApproxLocation,
+    );
+  }
 }
 
 export function ensureRef(input: { id: number; kind?: string }) {
-  if (!isDevtoolsEnabled()) return;
+  if (!isDebugEnabled()) return;
   if (refs.has(input.id)) return;
   registerRef({ id: input.id, kind: input.kind });
 }
 
+export function ensureReactivePropertyRef(input: {
+  id: number;
+  target: object;
+  key: string | number;
+}) {
+  if (!isDebugEnabled()) return;
+  if (refs.has(input.id)) return;
+  const label = formatReactivePropertyLabel(input.target, input.key);
+  const createdAt = getReactiveCreationLocation(input.target);
+  // If the reactive wasn't created via alloy's shallowReactive wrapper,
+  // createdAt is undefined and registerRef falls back to captureSourceLocation
+  // (the first track site). Flag this as approximate.
+  const isApproxLocation = !createdAt;
+  registerRef({
+    id: input.id,
+    kind: "reactive-property",
+    label,
+    createdAt,
+    isApproxLocation,
+  });
+}
+
 export function track(input: {
   effectId: number;
   target: unknown;
   refId?: number;
   targetKey?: unknown;
-  location?: SourceLocation;
 }) {
-  if (!isDevtoolsEnabled()) return;
+  if (!isDebugEnabled()) 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 });
+
+  if (isTraceEnabled()) {
+    insertEdge(
+      "track",
+      input.effectId,
+      edge.refId,
+      edge.targetId,
+      edge.targetKey,
+      undefined,
+    );
+  }
 }
 
 export function trigger(input: {
@@ -276,25 +483,33 @@ export function trigger(input: {
   target: unknown;
   refId?: number;
   targetKey?: unknown;
-  location?: SourceLocation;
   kind?: "trigger" | "triggered-by";
   causedBy?: number;
 }) {
-  if (!isDevtoolsEnabled()) return;
+  if (!isDebugEnabled()) return;
   const edge: EffectEdgeDebugInfo = {
     id: edgeEventIdCounter++,
-    type: input.kind ?? "triggered-by",
+    type: input.kind ?? "trigger",
     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 });
 
+  if (isTraceEnabled()) {
+    insertEdge(
+      edge.type,
+      input.effectId,
+      edge.refId,
+      edge.targetId,
+      edge.targetKey,
+      input.causedBy,
+    );
+  }
+
   update({
     id: input.effectId,
     ...(input.refId !== undefined ? { lastTriggeredByRefId: input.refId } : {}),
-    lastTriggeredAt: input.location ?? captureSourceLocation(),
   });
 }
 
@@ -304,7 +519,6 @@ export function reset() {
   primitiveTargetIds.clear();
   effectIdCounter = 1;
   edgeEventIdCounter = 1;
-  nonRefTargetIdCounter = 1;
 }
 
 // Utilities used by other debug sections

package/src/debug/files.test.tsx

@@ -5,16 +5,13 @@ import {
   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;
 
@@ -38,59 +35,42 @@ afterEach(async () => {
 });
 
 it("emits file and directory add/update/remove messages", async () => {
-  const show = ref(true);
-  const collector = createMessageCollector(socket!);
+  const collector = await 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>
+      <SourceDirectory path="src">
+        <SourceFile path="index.ts" filetype="ts">
+          {"export const value = 1;"}
+        </SourceFile>
+      </SourceDirectory>
     </Output>,
   );
 
   const initialMessages = await collector.waitForRender();
-  const initialFiles = initialMessages.filter((m: DevtoolsMessage) =>
-    m.type.startsWith("files:"),
+  const initialFiles = initialMessages.filter(
+    (m: DevtoolsMessage) =>
+      (m.type.startsWith("file:") || m.type.startsWith("directory:")) &&
+      !("triggerIds" in m),
   );
   expect(initialFiles[0]).toMatchObject({
+    type: "directory:added",
     path: "./",
   });
   expect(initialFiles[1]).toMatchObject({
-    type: "files:directoryAdded",
+    type: "directory:added",
     path: "src",
   });
   expect(initialFiles[2]).toMatchObject({
-    type: "files:fileAdded",
+    type: "file:added",
     path: "src/index.ts",
     filetype: "ts",
   });
   expect(initialFiles[3]).toMatchObject({
-    type: "files:fileUpdated",
+    type: "file:updated",
     path: "src/index.ts",
-    filetype: "ts",
-    contents: expect.any(String),
+    content: 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

@@ -1,4 +1,9 @@
-import { emitDevtoolsMessage, isDevtoolsEnabled } from "./trace.js";
+import {
+  insertDirectory,
+  insertOutputFile,
+  updateOutputFileContent,
+} from "./trace-writer.js";
+import { isDebugEnabled } from "./trace.js";
 
 export interface FileUpdateInfo {
   path: string;
@@ -10,14 +15,14 @@ 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 });
+  if (!isDebugEnabled()) return;
+  insertDirectory(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 });
+  if (!isDebugEnabled()) return;
+  insertOutputFile(path, filetype, undefined);
 }
 
 /** Notify devtools that a file's contents have changed. De-duplicates by content. */
@@ -26,12 +31,7 @@ export function updated(info: FileUpdateInfo) {
   if (previous === info.contents) return;
   fileContentCache.set(info.path, info.contents);
 
-  emitDevtoolsMessage({
-    type: "files:fileUpdated",
-    path: info.path,
-    filetype: info.filetype,
-    contents: info.contents,
-  });
+  updateOutputFileContent(info.path, info.contents);
 }
 
 /** Clear all cached file state. Called when a new render begins. */

package/src/debug/index.ts

@@ -11,6 +11,7 @@ import {
   debugWatch,
 } from "./cli.js";
 import {
+  ensureReactivePropertyRef,
   ensureRef,
   register,
   registerRef,
@@ -47,6 +48,7 @@ import {
 } from "./symbols.js";
 import { trace, type TracePhaseInfo } from "./trace.js";
 
+export { isDevtoolsConnected } from "../devtools/devtools-server.js";
 export { captureSourceLocation } from "./effects.js";
 export type {
   EffectDebugInfo,
@@ -62,6 +64,7 @@ export type {
 } from "./render.js";
 export {
   isConsoleTraceEnabled,
+  isDebugEnabled,
   isDevtoolsEnabled,
   trace,
   TracePhase,
@@ -84,6 +87,7 @@ export const debug = {
     update,
     registerRef,
     ensureRef,
+    ensureReactivePropertyRef,
     track,
     trigger,
     reset,