@abreen/tada 1.13.7 → 1.14.1

package/build/utils/python-runner/trace_runner.py

@@ -5,17 +5,22 @@ import json
 import os
 import pdb
 import sys
+import traceback
 import types
 
 
 class CaptureStream(io.TextIOBase):
-    def __init__(self, sink):
+    def __init__(self, sink, stream):
         self._sink = sink
+        self._stream = stream
 
     def write(self, s):
         if not isinstance(s, str):
             s = str(s)
-        self._sink.append(s)
+        if self._sink and self._sink[-1]["stream"] == self._stream:
+            self._sink[-1]["text"] += s
+        else:
+            self._sink.append({"stream": self._stream, "text": s})
         return len(s)
 
     def flush(self):
@@ -28,9 +33,10 @@ class CaptureStream(io.TextIOBase):
 class TracePdb(pdb.Pdb):
     SYNTHETIC_FRAME_NAMES = {"<listcomp>", "<dictcomp>", "<setcomp>"}
 
-    def __init__(self, target_path, trace_writer, output_chunks):
+    def __init__(self, target_path, traced_paths, trace_writer, output_chunks):
         super().__init__(nosigint=True, readrc=False)
         self.target_path = os.path.abspath(target_path)
+        self.traced_paths = set(os.path.abspath(path) for path in traced_paths)
         self.trace_writer = trace_writer
         self.output_chunks = output_chunks
         self.pending_snapshot = None
@@ -69,18 +75,24 @@ class TracePdb(pdb.Pdb):
         if self.pending_snapshot is None:
             return
         payload = dict(self.pending_snapshot)
-        payload["stdout"] = self._drain_output()
+        payload["output"] = self._drain_output()
         self.trace_writer.write(json.dumps(payload) + "\n")
         self.trace_writer.flush()
         self.pending_snapshot = None
 
     def _drain_output(self):
         if not self.output_chunks:
-            return ""
-        output = "".join(self.output_chunks)
+            return []
+        output = list(self.output_chunks)
         self.output_chunks.clear()
         return output
 
+    def emit_crash(self, frame):
+        payload = self._capture_snapshot(frame)
+        payload["output"] = self._drain_output()
+        self.trace_writer.write(json.dumps(payload) + "\n")
+        self.trace_writer.flush()
+
     def _capture_snapshot(self, frame):
         reachable = {}
         return {
@@ -206,7 +218,7 @@ class TracePdb(pdb.Pdb):
 
     def _is_traced_frame(self, frame):
         return (
-            os.path.abspath(frame.f_code.co_filename) == self.target_path
+            os.path.abspath(frame.f_code.co_filename) in self.traced_paths
             and frame.f_code.co_name not in self.SYNTHETIC_FRAME_NAMES
         )
 
@@ -221,11 +233,14 @@ class TracePdb(pdb.Pdb):
 
 
 def main():
-    if len(sys.argv) != 2:
-        print("Usage: trace_runner.py <python_file>", file=sys.stderr)
+    if len(sys.argv) < 2:
+        print("Usage: trace_runner.py <python_file> [traced_file ...]", file=sys.stderr)
         sys.exit(1)
 
     target_path = os.path.abspath(sys.argv[1])
+    traced_paths = [os.path.abspath(path) for path in sys.argv[2:]]
+    if target_path not in traced_paths:
+        traced_paths.insert(0, target_path)
     target_dir = os.path.dirname(target_path)
     target_name = os.path.basename(target_path)
 
@@ -234,8 +249,9 @@ def main():
 
     trace_writer = sys.stdout
     output_chunks = []
-    capture = CaptureStream(output_chunks)
-    debugger = TracePdb(target_path, trace_writer, output_chunks)
+    stdout_capture = CaptureStream(output_chunks, "stdout")
+    stderr_capture = CaptureStream(output_chunks, "stderr")
+    debugger = TracePdb(target_path, traced_paths, trace_writer, output_chunks)
 
     code_globals = {
         "__name__": "__main__",
@@ -253,14 +269,21 @@ def main():
             source = f.read()
         compiled = compile(source, target_path, "exec")
 
-        sys.stdout = capture
-        sys.stderr = capture
+        sys.stdout = stdout_capture
+        sys.stderr = stderr_capture
 
         try:
             debugger.set_step()
             debugger.runcall(exec, compiled, code_globals, code_globals)
         except SystemExit:
             pass
+        except BaseException as exc:
+            debugger.flush_pending()
+            sys.stderr.write(format_target_traceback(exc, set(traced_paths)))
+            frame = find_traced_exception_frame(debugger, exc.__traceback__)
+            if frame is None:
+                raise
+            debugger.emit_crash(frame)
         finally:
             debugger.flush_pending()
     finally:
@@ -268,5 +291,27 @@ def main():
         sys.stderr = original_stderr
 
 
+def find_traced_exception_frame(debugger, tb):
+    traced = None
+    while tb is not None:
+        if debugger._is_traced_frame(tb.tb_frame):
+            traced = tb.tb_frame
+        tb = tb.tb_next
+    return traced
+
+
+def format_target_traceback(exc, traced_paths):
+    frames = [
+        frame
+        for frame in traceback.extract_tb(exc.__traceback__)
+        if os.path.abspath(frame.filename) in traced_paths
+    ]
+    return (
+        "Traceback (most recent call last):\n"
+        + "".join(traceback.format_list(frames))
+        + "".join(traceback.format_exception_only(type(exc), exc))
+    )
+
+
 if __name__ == "__main__":
     main()

package/build/utils/render.ts

@@ -25,7 +25,7 @@ import {
 } from './code';
 import { extensionIsMarkdown } from './file-types';
 import { createTraceHelpers } from './trace';
-import { createIncludeFunction } from './include';
+import { stripHtmlComments } from './html-comments';
 import { finalizeHtmlPage } from './final-html';
 import {
   createApplyBasePath,
@@ -60,6 +60,8 @@ const log = makeLogger(import.meta.url);
 
 const tadaVersion: string = pkg.version;
 
+export { stripHtmlComments } from './html-comments';
+
 const REQUIRED_FRONT_MATTER_FIELDS = ['title'];
 
 function isWatchMode(assetFiles: string[]): boolean {
@@ -433,9 +435,9 @@ function renderPlainTextContent(
       {
         manifestUrl: string;
         artifactId: string;
-        highlightedSource: string;
+        highlightedSources: { file: string; highlightedSource: string }[];
         totalSteps: number;
-        mtime: number;
+        sourceMtims: Record<string, number>;
       }
     >;
     contentDir?: string;
@@ -459,7 +461,7 @@ function renderPlainTextContent(
       `${filePath}: slides mode is only supported on Markdown pages`,
     );
   }
-  const md = createMarkdown(siteVariables, {
+  const frontMatterMd = createMarkdown(siteVariables, {
     filePath,
     slides: pageVariables.slides === true,
   });
@@ -480,8 +482,8 @@ function renderPlainTextContent(
   );
 
   // Render title and description as inline Markdown
-  renderInlineField(md, pageVariablesProcessed, 'title');
-  renderInlineField(md, pageVariablesProcessed, 'description');
+  renderInlineField(frontMatterMd, pageVariablesProcessed, 'title');
+  renderInlineField(frontMatterMd, pageVariablesProcessed, 'description');
 
   resolveAuthor(pageVariablesProcessed, filePath, dependencyCollector);
 
@@ -526,8 +528,6 @@ function renderPlainTextContent(
     params.renderTrace = helpers.renderTrace;
   }
 
-  params.include = createIncludeFunction(filePath, params, dependencyCollector);
-
   let html: string;
   try {
     html = _.template(strippedContent)(params);
@@ -541,6 +541,12 @@ function renderPlainTextContent(
   let tocItems: unknown[] | null = null;
   let alertIds: string[] = [];
   if (extensionIsMarkdown(ext)) {
+    const md = createMarkdown(siteVariables, {
+      filePath,
+      slides: pageVariables.slides === true,
+      templateParams: params,
+      dependencyCollector,
+    });
     const env: Record<string, unknown> = { alertIds: [] as string[] };
     html = md.render(html!, env);
     tocItems = (env.tocItems as unknown[] | undefined) || null;
@@ -555,10 +561,6 @@ function renderPlainTextContent(
   };
 }
 
-export function stripHtmlComments(str: string): string {
-  return str.replace(/<!---[\s\S]*?-->/g, '');
-}
-
 export function renderLiterateJavaPageAsset({
   filePath,
   contentDir,

package/build/utils/trace-core.ts

@@ -5,8 +5,14 @@ import { renderCodeSegment } from './code';
 import { splitLines } from './literate-java';
 import { normalizeOutputPath } from './paths';
 import { computeLayout } from './trace-layout';
-import { generateStepSvg } from './trace-svg';
-import type { TraceChunkEntry, TraceManifest, TraceStep } from '../types';
+import { filterStep, generateStepSvg } from './trace-svg';
+import type {
+  TraceChunkEntry,
+  TraceHeapObject,
+  TraceManifest,
+  TraceOutputEvent,
+  TraceStep,
+} from '../types';
 
 export const DEFAULT_CHUNK_SIZE = 50;
 
@@ -21,6 +27,10 @@ export interface ChunkTraceOutputResult {
   outputPaths: string[];
 }
 
+function stepOutputEvents(step: TraceStep): TraceOutputEvent[] {
+  return step.output ?? [];
+}
+
 function hashTraceFiles(files: { name: string; content: string }[]): string {
   const hasher = createHash('sha256');
   for (const file of files) {
@@ -43,13 +53,101 @@ function buildTraceOutputPath(
     .join('/');
 }
 
+function escapeAttr(value: string): string {
+  return value
+    .replaceAll('&', '&')
+    .replaceAll('"', '"')
+    .replaceAll('<', '&lt;')
+    .replaceAll('>', '&gt;');
+}
+
+function framesMatchCaller(previous: TraceStep, current: TraceStep): boolean {
+  if (current.stack.length !== previous.stack.length - 1) {
+    return false;
+  }
+
+  return current.stack.every((frame, index) => {
+    const previousFrame = previous.stack[index + 1];
+    return (
+      frame.method === previousFrame.method &&
+      frame.class === previousFrame.class
+    );
+  });
+}
+
+function addReachableHeapObjects(
+  id: string,
+  source: Record<string, TraceHeapObject>,
+  target: Record<string, TraceHeapObject>,
+): void {
+  const queue = [id];
+  const seen = new Set<string>();
+
+  while (queue.length > 0) {
+    const currentId = queue.shift()!;
+    if (seen.has(currentId) || !source[currentId]) {
+      continue;
+    }
+    seen.add(currentId);
+    target[currentId] ??= source[currentId];
+
+    const obj = source[currentId];
+    if ('elements' in obj) {
+      for (const element of obj.elements) {
+        if (element.type === 'ref') {
+          queue.push(element.id);
+        }
+      }
+    } else if ('fields' in obj) {
+      for (const value of Object.values(obj.fields)) {
+        if (value.type === 'ref') {
+          queue.push(value.id);
+        }
+      }
+    }
+  }
+}
+
+export function bridgeConstructorReturnValues(steps: TraceStep[]): TraceStep[] {
+  const bridgedSteps = steps.map(step => ({
+    ...step,
+    heap: { ...step.heap },
+    transientHeapRoots: step.transientHeapRoots
+      ? [...step.transientHeapRoots]
+      : undefined,
+  }));
+
+  for (let i = 1; i < bridgedSteps.length; i++) {
+    const previous = bridgedSteps[i - 1];
+    const current = bridgedSteps[i];
+    const poppedFrame = previous.stack[0];
+    const thisValue = poppedFrame?.locals.this;
+
+    if (
+      poppedFrame?.method !== '<init>' ||
+      thisValue?.type !== 'ref' ||
+      !framesMatchCaller(previous, current)
+    ) {
+      continue;
+    }
+
+    addReachableHeapObjects(thisValue.id, previous.heap, current.heap);
+    current.transientHeapRoots ??= [];
+    if (!current.transientHeapRoots.includes(thisValue.id)) {
+      current.transientHeapRoots.push(thisValue.id);
+    }
+  }
+
+  return bridgedSteps;
+}
+
 export function chunkTraceOutput(
   output: string,
   traceOutputDir: string,
   relDir: string,
   traceName: string,
-  sourceFile: string,
-  source: string,
+  primaryFile: string,
+  sources: { file: string; source: string }[],
   options: ChunkTraceOutputOptions = {},
 ): ChunkTraceOutputResult {
   const chunkSize = options.chunkSize ?? DEFAULT_CHUNK_SIZE;
@@ -60,18 +158,29 @@ export function chunkTraceOutput(
     .split('\n')
     .filter(l => l.length > 0);
 
-  const allSteps: TraceStep[] = lines.map(l => JSON.parse(l));
+  const allSteps: TraceStep[] = bridgeConstructorReturnValues(
+    lines.map(l => JSON.parse(l)),
+  );
 
-  const lineToSteps: Record<number, number[]> = {};
+  const lineToStepsByFile = new Map<string, Record<number, number[]>>();
+  for (const source of sources) {
+    lineToStepsByFile.set(source.file, {});
+  }
   for (let i = 0; i < allSteps.length; i++) {
     const step = allSteps[i];
+    const file = path.basename(step.file);
+    const lineToSteps = lineToStepsByFile.get(file);
+    if (!lineToSteps) {
+      continue;
+    }
     if (!lineToSteps[step.line]) {
       lineToSteps[step.line] = [];
     }
     lineToSteps[step.line].push(i);
   }
 
-  const layout = computeLayout(allSteps, ignoreFields);
+  const layoutSteps = allSteps.map(step => ({ ...step, ...filterStep(step) }));
+  const layout = computeLayout(layoutSteps, ignoreFields);
 
   let chunkEntries: TraceChunkEntry[] = [];
   let chunkIndex = 0;
@@ -79,7 +188,12 @@ export function chunkTraceOutput(
 
   for (const step of allSteps) {
     const svg = generateStepSvg(step, layout);
-    chunkEntries.push({ line: step.line, stdout: step.stdout, svg });
+    chunkEntries.push({
+      file: path.basename(step.file),
+      line: step.line,
+      output: stepOutputEvents(step),
+      svg,
+    });
 
     if (chunkEntries.length >= chunkSize) {
       chunkFiles.push({
@@ -101,9 +215,11 @@ export function chunkTraceOutput(
   const manifest: TraceManifest = {
     totalSteps: allSteps.length,
     chunkSize,
-    sourceFile,
-    source,
-    lineToSteps,
+    primaryFile,
+    sources: sources.map(source => ({
+      ...source,
+      lineToSteps: lineToStepsByFile.get(source.file) ?? {},
+    })),
   };
 
   const manifestFile = {
@@ -218,11 +334,11 @@ export function buildManifestUrl({
 }
 
 export function renderTraceWidgetHtml({
-  highlightedSource,
+  highlightedSources,
   manifestUrl,
   totalSteps,
 }: {
-  highlightedSource: string;
+  highlightedSources: { file: string; highlightedSource: string }[];
   manifestUrl?: string;
   totalSteps?: number;
 }): string {
@@ -248,5 +364,11 @@ export function renderTraceWidgetHtml({
   const wrapperClass = disabled
     ? 'trace-widget trace-disabled'
     : 'trace-widget';
-  return `<div class="${wrapperClass}"${wrapperAttrs}><noscript><p>This interactive trace requires JavaScript.</p></noscript><div class="trace-body"><div class="trace-toolbar"><div class="trace-controls" role="toolbar" aria-label="Trace navigation">${controls}</div></div><div class="trace-content"><div class="trace-diagram"></div><div class="trace-source-wrapper"><div class="trace-source">${highlightedSource}</div></div></div></div></div>`;
+  const sourcePanels = highlightedSources
+    .map((source, index) => {
+      const hidden = index === 0 ? '' : ' hidden';
+      return `<div class="trace-source" data-trace-source-file="${escapeAttr(source.file)}"${hidden}>${source.highlightedSource}</div>`;
+    })
+    .join('');
+  return `<div class="${wrapperClass}"${wrapperAttrs}><noscript><p>This interactive trace requires JavaScript.</p></noscript><div class="trace-body"><div class="trace-toolbar"><div class="trace-controls" role="toolbar" aria-label="Trace navigation">${controls}</div></div><div class="trace-content"><div class="trace-diagram"></div><div class="trace-source-wrapper">${sourcePanels}</div></div></div></div>`;
 }

package/build/utils/trace-heap.ts

@@ -0,0 +1,34 @@
+import type { TraceHeapObject } from '../types';
+
+export type TraceHeapScalar = string | number | boolean;
+
+const BOXED_PRIMITIVE_TYPES = new Set([
+  'java.lang.Boolean',
+  'java.lang.Byte',
+  'java.lang.Character',
+  'java.lang.Double',
+  'java.lang.Float',
+  'java.lang.Integer',
+  'java.lang.Long',
+  'java.lang.Short',
+]);
+
+export function isInlineHeapObject(obj: TraceHeapObject): boolean {
+  return (
+    'value' in obj &&
+    (obj.type === 'String' || BOXED_PRIMITIVE_TYPES.has(obj.type))
+  );
+}
+
+export function formatHeapObjectValue(
+  type: string,
+  value: TraceHeapScalar,
+): string {
+  if (type === 'String') {
+    return `"${value}"`;
+  }
+  if (type === 'java.lang.Character') {
+    return `'${value}'`;
+  }
+  return String(value);
+}

package/build/utils/trace-java.ts

@@ -2,11 +2,17 @@ import fs from 'fs';
 import os from 'os';
 import path from 'path';
 import { execFileSync } from 'child_process';
+import { parse as parseJava } from 'java-parser';
 import { makeLogger } from '../log';
 import { hasMainMethod, runJavac } from './literate-java';
 
 const log = makeLogger(import.meta.url);
 
+interface CstNode {
+  name?: string;
+  children?: Record<string, CstNode[]>;
+}
+
 /**
  * Parse // @trace-ignore comments from Java source code.
  * Returns a map of className -> fieldName[] for fields that should be
@@ -65,6 +71,42 @@ export function parseIgnoreFields(source: string): Record<string, string[]> {
   return result;
 }
 
+const JAVA_TOP_LEVEL_TYPE_NODES = new Set([
+  'classDeclaration',
+  'interfaceDeclaration',
+  'enumDeclaration',
+  'recordDeclaration',
+]);
+
+export function hasExplicitTopLevelTypeDeclaration(source: string): boolean {
+  let cst: CstNode;
+  try {
+    cst = parseJava(source) as CstNode;
+  } catch (err: unknown) {
+    log.debug`Failed to parse Java source for unnamed class detection: ${(err as Error).message}`;
+    return true;
+  }
+
+  const ordinaryCompilationUnit = cst.children?.ordinaryCompilationUnit?.[0];
+  const typeDeclarations =
+    ordinaryCompilationUnit?.children?.typeDeclaration ?? [];
+
+  return typeDeclarations.some(typeDeclaration =>
+    Object.keys(typeDeclaration.children ?? {}).some(childName =>
+      JAVA_TOP_LEVEL_TYPE_NODES.has(childName),
+    ),
+  );
+}
+
+export function getUnnamedClassNames(javaFilePaths: string[]): string[] {
+  return javaFilePaths
+    .filter(javaFilePath => {
+      const source = fs.readFileSync(javaFilePath, 'utf-8');
+      return !hasExplicitTopLevelTypeDeclaration(source);
+    })
+    .map(javaFilePath => path.parse(javaFilePath).name);
+}
+
 let tracerClassDir: string | null = null;
 
 function ensureTracerCompiled(): string {
@@ -87,7 +129,7 @@ function ensureTracerCompiled(): string {
   return tempDir;
 }
 
-function compileTargetFile(javaFilePath: string): string {
+function compileTargetFiles(javaFilePaths: string[]): string {
   const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'tada-trace-target-'));
 
   runJavac(
@@ -96,10 +138,10 @@ function compileTargetFile(javaFilePath: string): string {
       '-d',
       tempDir,
       '-sourcepath',
-      path.dirname(javaFilePath),
-      javaFilePath,
+      path.dirname(javaFilePaths[0]),
+      ...javaFilePaths,
     ],
-    { tempDir, label: `Compilation failed for ${javaFilePath}` },
+    { tempDir, label: `Compilation failed for ${javaFilePaths[0]}` },
   );
 
   return tempDir;
@@ -116,14 +158,25 @@ export function validateJavaTraceTarget(
   }
 }
 
-export function runJavaTrace(javaFilePath: string, className: string): string {
-  const targetClassDir = compileTargetFile(javaFilePath);
+export function runJavaTrace(
+  javaFilePaths: string[],
+  className: string,
+): string {
+  const targetClassDir = compileTargetFiles(javaFilePaths);
 
   try {
     const tracerDir = ensureTracerCompiled();
+    const unnamedClassNames = getUnnamedClassNames(javaFilePaths);
     return execFileSync(
       'java',
-      ['-cp', tracerDir, 'TraceRunner', className, targetClassDir],
+      [
+        '-cp',
+        tracerDir,
+        'TraceRunner',
+        className,
+        targetClassDir,
+        ...unnamedClassNames,
+      ],
       { timeout: 60000, encoding: 'utf-8', maxBuffer: 50 * 1024 * 1024 },
     );
   } finally {