@alloy-js/core 0.23.0-dev.9 → 0.23.0

package/src/render.ts

@@ -6,10 +6,17 @@ import { SourceFileContext } from "./context/source-file.js";
 import {
   debug,
   getRenderNodeId,
+  isDevtoolsConnected,
   isDevtoolsEnabled,
   type RenderTreeNodeInfo,
 } from "./debug/index.js";
-import { broadcastDevtoolsMessage } from "./devtools/devtools-server.js";
+import {
+  beginTransaction,
+  closeTrace,
+  commitTransaction,
+  notifyDiagnosticsReport,
+} from "./debug/trace-writer.js";
+import { isTraceEnabled } from "./debug/trace.js";
 import {
   attachDiagnosticsCollector,
   DiagnosticsCollector,
@@ -52,6 +59,43 @@ import { IntrinsicElement, isIntrinsicElement } from "./runtime/intrinsic.js";
 import { flushJobs, flushJobsAsync, waitForSignal } from "./scheduler.js";
 
 const notifiedErrors = new WeakSet<object>();
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Deferred file printing: mark files dirty during render, print once at end
+// ─────────────────────────────────────────────────────────────────────────────
+interface DirtyFileEntry {
+  renderNode: RenderedTextTree;
+  printOptions: {
+    printWidth?: number;
+    tabWidth?: number;
+    useTabs?: boolean;
+    insertFinalNewLine?: boolean;
+  };
+  path: string;
+  filetype: string;
+}
+const dirtyFiles = new Map<string, DirtyFileEntry>();
+const lastFlushTimeByFile = new Map<string, number>();
+const DEVTOOLS_FLUSH_INTERVAL_MS = 1000;
+
+function flushDirtyFile(path: string): void {
+  const entry = dirtyFiles.get(path);
+  if (!entry) return;
+  dirtyFiles.delete(path);
+  const contents = printTree(entry.renderNode, {
+    ...entry.printOptions,
+    insertFinalNewLine: entry.printOptions.insertFinalNewLine ?? true,
+    noFlush: true,
+  });
+  debug.files.updated({ path: entry.path, filetype: entry.filetype, contents });
+}
+
+function flushDirtyFiles(): void {
+  for (const path of [...dirtyFiles.keys()]) {
+    flushDirtyFile(path);
+  }
+}
+
 let lastRenderError: {
   error: { name: string; message: string; stack?: string };
   componentStack: Array<{
@@ -238,12 +282,14 @@ const {
 
 export interface OutputDirectory {
   kind: "directory";
+  /** Full path from the output root, e.g. `"generated-client/src"`. Do not prepend parent directory paths when walking the tree. */
   path: string;
   contents: (OutputDirectory | OutputFile)[];
 }
 
 export interface OutputFileBase {
   kind: "file";
+  /** Full path from the output root, e.g. `"generated-client/src/models.ext"`. Do not prepend parent directory paths when walking the tree. */
   path: string;
 }
 
@@ -275,10 +321,7 @@ function reportDiagnosticsForTree(tree: RenderedTextTree) {
   const entries = diagnostics.getDiagnostics();
   if (entries.length === 0) return;
   reportDiagnostics(diagnostics);
-  void broadcastDevtoolsMessage({
-    type: "diagnostics:report",
-    diagnostics: entries,
-  });
+  notifyDiagnosticsReport(entries);
 }
 
 // Re-export from print-hook.ts to maintain backwards compatibility
@@ -313,9 +356,13 @@ export function render(
   const tree = renderTree(children);
   flushJobs();
   const output = sourceFilesForTree(tree, options);
+  flushDirtyFiles();
   reportDiagnosticsForTree(tree);
   reportLastRenderError();
   debug.render.complete();
+  // Only close the trace DB when devtools is NOT running. When devtools is
+  // active the DB must remain open for post-render reactive updates.
+  if (isTraceEnabled() && !isDevtoolsEnabled()) closeTrace();
   if (isDevtoolsEnabled()) {
     void waitForSignal();
   }
@@ -335,9 +382,13 @@ export async function renderAsync(
   // Ensure all reactive updates are flushed before printing.
   await flushJobsAsync();
   const output = sourceFilesForTree(tree, options);
+  flushDirtyFiles();
   reportDiagnosticsForTree(tree);
   reportLastRenderError();
   debug.render.complete();
+  // Only close the trace DB when devtools is NOT running. When devtools is
+  // active the DB must remain open for post-render reactive updates.
+  if (isTraceEnabled() && !isDevtoolsEnabled()) closeTrace();
 
   return output;
 }
@@ -449,17 +500,23 @@ export function renderTree(children: Children) {
   debug.effect.reset();
   debug.symbols.reset();
   debug.files.reset();
+  dirtyFiles.clear();
+  lastFlushTimeByFile.clear();
   debug.render.initialize(rootElem);
+  if (isTraceEnabled()) beginTransaction();
   try {
     root(() => {
       attachDiagnosticsCollector(diagnostics);
       renderWorker(rootElem, children);
     });
   } catch (e) {
+    if (isTraceEnabled()) commitTransaction();
+    flushDirtyFiles();
     notifyRenderError(e);
     reportLastRenderError();
     throw e;
   }
+  if (isTraceEnabled()) commitTransaction();
 
   diagnosticsByTree.set(rootElem, diagnostics);
 
@@ -761,8 +818,12 @@ function appendChild(node: RenderedTextTree, rawChild: Child) {
       }
     } else if (isComponentCreator(child)) {
       const index = node.length;
-      const rerenderToken = isDevtoolsEnabled() ? ref(0) : undefined;
-      const breakNext = isDevtoolsEnabled() ? ref(false) : undefined;
+      const rerenderToken =
+        isDevtoolsEnabled() ? ref(0, { isInfrastructure: true }) : undefined;
+      const breakNext =
+        isDevtoolsEnabled() ?
+          ref(false, { isInfrastructure: true })
+        : undefined;
       // todo: remove this effect (only needed for context, not needed for anything else)
       effect(
         () => {
@@ -789,15 +850,21 @@ function appendChild(node: RenderedTextTree, rawChild: Child) {
             source: child.source,
             isExisting: Array.isArray(existing),
             actions: {
-              rerender: () => {
-                lastRenderError = null;
-                if (rerenderToken) rerenderToken.value++;
-              },
-              rerenderAndBreak: () => {
-                lastRenderError = null;
-                if (breakNext) breakNext.value = true;
-                if (rerenderToken) rerenderToken.value++;
-              },
+              rerender:
+                rerenderToken ?
+                  () => {
+                    lastRenderError = null;
+                    rerenderToken.value++;
+                  }
+                : () => {},
+              rerenderAndBreak:
+                breakNext && rerenderToken ?
+                  () => {
+                    lastRenderError = null;
+                    breakNext.value = true;
+                    rerenderToken.value++;
+                  }
+                : () => {},
             },
           });
           if (Array.isArray(existing)) {
@@ -809,7 +876,7 @@ function appendChild(node: RenderedTextTree, rawChild: Child) {
           let childResult: Children | undefined;
           try {
             childResult = untrack(() => {
-              const shouldBreak = breakNext?.value;
+              const shouldBreak = breakNext?.value ?? false;
               if (shouldBreak) {
                 breakNext!.value = false;
                 // eslint-disable-next-line no-debugger
@@ -927,29 +994,38 @@ function findSourceFileContext(node: RenderedTextTree) {
 }
 
 function notifyFileUpdateForNode(node: RenderedTextTree) {
-  // Only do the expensive printTree when devtools are actually enabled
-  if (!isDevtoolsEnabled()) return;
+  // Only track when devtools or trace are actually enabled
+  if (!isDevtoolsEnabled() && !isTraceEnabled()) return;
   const context = findSourceFileContext(node);
   if (!context?.meta?.sourceFile) return;
   if (context.meta.sourceFileReady === false) return;
   const sourceFile = context.meta.sourceFile;
   const renderNode: RenderedTextTree =
     (context.meta.renderNode as RenderedTextTree | undefined) ?? node;
-  // Pass noFlush here since it flushes jobs and can re-enter rendering
-  // during effect setup, triggering premature cleanup.
-  const contents = printTree(renderNode, {
-    printWidth: context.meta?.printOptions?.printWidth,
-    tabWidth: context.meta?.printOptions?.tabWidth,
-    useTabs: context.meta?.printOptions?.useTabs,
-    insertFinalNewLine: context.meta?.printOptions?.insertFinalNewLine ?? true,
-    noFlush: true,
-  });
 
-  debug.files.updated({
+  // Mark this file as dirty — defer the expensive printTree to end of render
+  dirtyFiles.set(sourceFile.path, {
+    renderNode,
+    printOptions: {
+      printWidth: context.meta?.printOptions?.printWidth,
+      tabWidth: context.meta?.printOptions?.tabWidth,
+      useTabs: context.meta?.printOptions?.useTabs,
+      insertFinalNewLine: context.meta?.printOptions?.insertFinalNewLine,
+    },
     path: sourceFile.path,
     filetype: sourceFile.filetype,
-    contents,
   });
+
+  // When a devtools client is connected, throttle file flushing to ~1s per file
+  // so the user can watch content build up during rendering.
+  if (isDevtoolsConnected()) {
+    const now = Date.now();
+    const lastFlush = lastFlushTimeByFile.get(sourceFile.path) ?? 0;
+    if (now - lastFlush >= DEVTOOLS_FLUSH_INTERVAL_MS) {
+      lastFlushTimeByFile.set(sourceFile.path, now);
+      flushDirtyFile(sourceFile.path);
+    }
+  }
 }
 
 type NormalizedChildren = NormalizedChild | NormalizedChildren[];

package/src/scheduler.ts

@@ -1,11 +1,21 @@
 import { ReactiveEffect } from "@vue/reactivity";
 import { debug } from "./debug/index.js";
+import {
+  beginTransaction,
+  commitTransaction,
+  insertEffectLifecycle,
+  insertSchedulerFlush,
+  insertSchedulerJob,
+} from "./debug/trace-writer.js";
+import { isTraceEnabled } from "./debug/trace.js";
+import { getEffectDebugId } from "./reactivity.js";
 
 export interface QueueJob {
   run(): void;
 }
 const immediateQueue = new Set<QueueJob>();
 const queue = new Set<QueueJob>();
+
 function isJobActive(job: QueueJob): boolean {
   // ReactiveEffect uses bit 0 (flags & 1) as the ACTIVE flag.
   // Skip effects that were stopped after being queued.
@@ -18,12 +28,19 @@ let resolveWaitForSignal: (() => void) | null = null;
 let jobSignalPromise: Promise<void> | null = null;
 let resolveJobSignal: (() => void) | null = null;
 
-// Maps effect debug IDs to the ref that most recently triggered them
+// Maps effect debug IDs to the ref that most recently triggered them.
+// Intentionally overwrites on repeated triggers for the same effect before flush —
+// we only need the last trigger ref for lifecycle recording, not all intermediate ones.
 const lastTriggerRef = new Map<number, number>();
 
 /**
  * Record which ref triggered an effect re-run.
  * Called from the onTrigger debug hook before the effect is scheduled.
+ *
+ * Note: if an effect is triggered multiple times before flush, only the last
+ * trigger ref is retained. This is intentional — we care about the most
+ * recent cause, and tracking all triggers would add overhead with minimal
+ * diagnostic value since only the last mutation actually caused the re-run.
  */
 export function setLastTriggerRef(effectDebugId: number, refId: number): void {
   lastTriggerRef.set(effectDebugId, refId);
@@ -52,6 +69,18 @@ export function queueJob(job: QueueJob | (() => void), immediate = false) {
     queue.add(job);
   }
 
+  if (isTraceEnabled()) {
+    const effectId = getEffectDebugId(job as object);
+    if (effectId !== undefined) {
+      insertSchedulerJob(
+        "queue",
+        effectId,
+        immediate,
+        immediateQueue.size + queue.size,
+      );
+    }
+  }
+
   if (resolveJobSignal) {
     resolveJobSignal();
     resolveJobSignal = null;
@@ -72,19 +101,69 @@ export function trackPromise(promise: Promise<any>) {
 
 export function flushJobs() {
   // First, run all synchronous jobs
+  if (isTraceEnabled()) beginTransaction();
   let job;
+  let jobCount = 0;
   while ((job = takeJob()) !== null) {
-    if (!isJobActive(job)) continue;
+    if (isTraceEnabled()) {
+      const effectId = getEffectDebugId(job as object);
+      if (effectId !== undefined) {
+        insertSchedulerJob(
+          "run",
+          effectId,
+          false,
+          immediateQueue.size + queue.size,
+        );
+      }
+    }
+    if (!isJobActive(job)) {
+      if (isTraceEnabled()) {
+        const effectId = getEffectDebugId(job as object);
+        if (effectId !== undefined) {
+          insertEffectLifecycle(
+            effectId,
+            "skipped",
+            undefined,
+            undefined,
+            undefined,
+            undefined,
+          );
+        }
+      }
+      continue;
+    }
+    if (isTraceEnabled()) {
+      const effectId = getEffectDebugId(job as object);
+      if (effectId !== undefined) {
+        const triggerRefId = lastTriggerRef.get(effectId);
+        lastTriggerRef.delete(effectId);
+        insertEffectLifecycle(
+          effectId,
+          "ran",
+          triggerRefId,
+          undefined,
+          undefined,
+          undefined,
+        );
+      }
+    }
     job.run();
+    jobCount++;
   }
 
   // If there are no pending promises, we're done
   if (pendingPromises.size > 0) {
+    if (isTraceEnabled()) commitTransaction();
     throw new Error(
       "Asynchronous jobs were found but render was called synchronously. Use `renderAsync` instead.",
     );
   }
 
+  if (isTraceEnabled()) {
+    insertSchedulerFlush(jobCount);
+    commitTransaction();
+  }
+
   debug.render.flushJobsComplete();
 }
 
@@ -115,34 +194,74 @@ export function isWaitingForSignal() {
 
 export async function flushJobsAsync() {
   // Keep running jobs until both the queues are empty and all promises are resolved
-  while (true) {
-    // First, run all synchronous jobs
-    let job;
-    while ((job = takeJob()) !== null) {
-      if (!isJobActive(job)) continue;
-      job.run();
-    }
+  if (isTraceEnabled()) beginTransaction();
+  try {
+    while (true) {
+      // First, run all synchronous jobs
+      let job;
+      while ((job = takeJob()) !== null) {
+        if (!isJobActive(job)) {
+          if (isTraceEnabled()) {
+            const effectId = getEffectDebugId(job as object);
+            if (effectId !== undefined) {
+              insertEffectLifecycle(
+                effectId,
+                "skipped",
+                undefined,
+                undefined,
+                undefined,
+                undefined,
+              );
+            }
+          }
+          continue;
+        }
+        if (isTraceEnabled()) {
+          const effectId = getEffectDebugId(job as object);
+          if (effectId !== undefined) {
+            const triggerRefId = lastTriggerRef.get(effectId);
+            lastTriggerRef.delete(effectId);
+            insertEffectLifecycle(
+              effectId,
+              "ran",
+              triggerRefId,
+              undefined,
+              undefined,
+              undefined,
+            );
+          }
+        }
+        job.run();
+      }
 
-    // If there are no pending promises, we're done
-    if (pendingPromises.size === 0) {
-      break;
-    }
+      // If there are no pending promises, we're done
+      if (pendingPromises.size === 0) {
+        break;
+      }
 
-    if (!jobSignalPromise) {
-      jobSignalPromise = new Promise<void>((resolve) => {
-        resolveJobSignal = resolve;
-      });
-    }
+      // Commit before awaiting so writes are visible, then re-open after
+      if (isTraceEnabled()) commitTransaction();
 
-    // Wait for either pending promises to complete or new jobs to arrive
-    await Promise.race([
-      Promise.allSettled(Array.from(pendingPromises)),
-      jobSignalPromise,
-    ]);
+      if (!jobSignalPromise) {
+        jobSignalPromise = new Promise<void>((resolve) => {
+          resolveJobSignal = resolve;
+        });
+      }
 
-    // Clear the job signal after each iteration so we create a new one next time
-    jobSignalPromise = null;
-    resolveJobSignal = null;
+      // Wait for either pending promises to complete or new jobs to arrive
+      await Promise.race([
+        Promise.allSettled(Array.from(pendingPromises)),
+        jobSignalPromise,
+      ]);
+
+      // Clear the job signal after each iteration so we create a new one next time
+      jobSignalPromise = null;
+      resolveJobSignal = null;
+
+      if (isTraceEnabled()) beginTransaction();
+    }
+  } finally {
+    if (isTraceEnabled()) commitTransaction();
   }
 
   debug.render.flushJobsComplete();

package/src/symbols/output-scope.ts

@@ -54,6 +54,11 @@ export interface OutputScopeOptions {
  * within a reactive context.
  */
 export abstract class OutputScope {
+  /**
+   * The declaration space keys for this scope type. Subclasses override this
+   * to declare which declaration spaces are created on construction (e.g.,
+   * `["types", "values"]`).
+   */
   static readonly declarationSpaces: Readonly<string[]> = [] as const;
 
   #name: string;
@@ -125,7 +130,8 @@ export abstract class OutputScope {
   #spaces: Record<string, OutputDeclarationSpace>;
 
   /**
-   * Get the declaration space for the given key.
+   * Get the declaration space for the given key (e.g., `"types"`, `"values"`).
+   * Returns `undefined` when no space with that key exists on this scope.
    */
   spaceFor(key: string): OutputSpace | undefined {
     return this.#spaces[key];
@@ -153,6 +159,32 @@ export abstract class OutputScope {
 
   [ReactiveFlags.SKIP] = true;
 
+  /**
+   * Subclasses must forward all three positional arguments to `super`. See
+   * {@link createScope} for the preferred instantiation path.
+   *
+   * @param name - A descriptive name for this scope (used in debugging and
+   * diagnostics).
+   * @param parentScope - The parent scope in the scope tree, or `undefined`
+   * for root scopes. Inside a component, obtain this via `useScope()`.
+   * @param options - Additional scope options; see {@link OutputScopeOptions}.
+   *
+   * @example
+   * ```ts
+   * class MyScope extends OutputScope {
+   *   constructor(
+   *     name: string,
+   *     parent: OutputScope | undefined,
+   *     options?: OutputScopeOptions,
+   *   ) {
+   *     super(name, parent, options);
+   *   }
+   * }
+   *
+   * // Inside a component:
+   * const scope = createScope(MyScope, "my-scope", useScope());
+   * ```
+   */
   constructor(
     name: string,
     parentScope: OutputScope | undefined,

package/src/symbols/output-space.ts

@@ -5,7 +5,16 @@ import { OutputScope } from "./output-scope.js";
 import { OutputSymbol } from "./output-symbol.js";
 import { SymbolTable } from "./symbol-table.js";
 
+/**
+ * A symbol table that belongs to either a scope (declaration space) or a symbol
+ * (member space).
+ */
 export type OutputSpace = OutputDeclarationSpace | OutputMemberSpace;
+
+/**
+ * A symbol table attached to an {@link OutputScope}. Holds lexical declarations
+ * visible within that scope (e.g., "types" or "values" in a TypeScript module).
+ */
 export class OutputDeclarationSpace extends SymbolTable {
   constructor(scope: OutputScope, key: string, binder?: Binder) {
     super(key, binder);
@@ -27,6 +36,10 @@ export class OutputDeclarationSpace extends SymbolTable {
   }
 }
 
+/**
+ * A symbol table attached to an {@link OutputSymbol}. Holds member declarations
+ * belonging to that symbol (e.g., "static" or "instance" members of a class).
+ */
 export class OutputMemberSpace extends SymbolTable {
   constructor(symbol: OutputSymbol, key: string, binder?: Binder) {
     super(key, binder);