@abreen/tada 1.4.1 → 1.5.0

package/build/utils/trace.test.ts

@@ -0,0 +1,169 @@
+import { describe, test, expect, beforeEach, afterEach } from 'bun:test';
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import { chunkTraceOutput, parseIgnoreFields } from './trace';
+import type { TraceManifest } from '../types';
+
+describe('chunkTraceOutput', () => {
+  let tempDir: string;
+
+  beforeEach(() => {
+    tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'tada-trace-test-'));
+  });
+
+  afterEach(() => {
+    fs.rmSync(tempDir, { recursive: true, force: true });
+  });
+
+  test('chunks JSONL output into files and writes manifest', () => {
+    const lines = [];
+    for (let i = 0; i < 5; i++) {
+      lines.push(
+        JSON.stringify({
+          line: i + 1,
+          file: 'Test.java',
+          stack: [{ method: 'main', class: 'Test', locals: {} }],
+          heap: {},
+          stdout: '',
+        }),
+      );
+    }
+    const output = lines.join('\n') + '\n';
+    const outputDir = path.join(tempDir, '_traces', 'Test');
+
+    const manifest = chunkTraceOutput(
+      output,
+      outputDir,
+      'Test.java',
+      'public class Test {}',
+      3,
+    );
+
+    // Should create 2 chunks (3 + 2)
+    const chunk0 = JSON.parse(
+      fs.readFileSync(path.join(outputDir, 'chunk-0.json'), 'utf-8'),
+    );
+    const chunk1 = JSON.parse(
+      fs.readFileSync(path.join(outputDir, 'chunk-1.json'), 'utf-8'),
+    );
+    expect(chunk0).toHaveLength(3);
+    expect(chunk1).toHaveLength(2);
+
+    // Chunks now contain TraceChunkEntry objects with precomputed SVG
+    expect(chunk0[0].svg).toContain('<svg');
+    expect(chunk0[0]).toHaveProperty('line');
+    expect(chunk0[0]).toHaveProperty('stdout');
+
+    // Manifest (returned value and file on disk should both be correct)
+    const manifestFile = JSON.parse(
+      fs.readFileSync(path.join(outputDir, 'manifest.json'), 'utf-8'),
+    ) as TraceManifest;
+    expect(manifest.totalSteps).toBe(5);
+    expect(manifest.chunkSize).toBe(3);
+    expect(manifestFile.sourceFile).toBe('Test.java');
+    expect(manifestFile.source).toBe('public class Test {}');
+    expect(manifest.lineToSteps[1]).toEqual([0]);
+    expect(manifest.lineToSteps[5]).toEqual([4]);
+  });
+
+  test('handles single chunk', () => {
+    const line = JSON.stringify({
+      line: 1,
+      file: 'Test.java',
+      stack: [],
+      heap: {},
+      stdout: 'hello\n',
+    });
+    const outputDir = path.join(tempDir, '_traces', 'Test');
+
+    const manifest = chunkTraceOutput(
+      line,
+      outputDir,
+      'Test.java',
+      'class Test {}',
+      50,
+    );
+
+    expect(manifest.totalSteps).toBe(1);
+    const chunk0 = JSON.parse(
+      fs.readFileSync(path.join(outputDir, 'chunk-0.json'), 'utf-8'),
+    );
+    expect(chunk0).toHaveLength(1);
+    expect(chunk0[0].stdout).toBe('hello\n');
+  });
+
+  test('passes ignoreFields from source to layout', () => {
+    const source = `class Node {
+    int value;
+    Node left;
+    Node right;
+    Node parent; // @trace-ignore
+}
+public class Test {
+    public static void main(String[] args) {}
+}`;
+    const fields = parseIgnoreFields(source);
+    expect(fields).toEqual({ Node: ['parent'] });
+  });
+
+  test('parseIgnoreFields handles multiple classes', () => {
+    const source = `class A {
+    A prev; // @trace-ignore
+    A next;
+}
+class B {
+    B up; // @trace-ignore
+    B down; // @trace-ignore
+}`;
+    const fields = parseIgnoreFields(source);
+    expect(fields).toEqual({ A: ['prev'], B: ['up', 'down'] });
+  });
+
+  test('parseIgnoreFields handles inner classes with $ separator', () => {
+    const source = `public class SearchTreeDemo {
+    static class Node {
+        String data;
+        Node left;
+        Node right;
+        Node parent; // @trace-ignore
+    }
+
+    public static void main(String[] args) {}
+}`;
+    const fields = parseIgnoreFields(source);
+    expect(fields).toEqual({ SearchTreeDemo$Node: ['parent'] });
+  });
+
+  test('parseIgnoreFields returns empty for no annotations', () => {
+    const source = `class Node { int x; }`;
+    expect(parseIgnoreFields(source)).toEqual({});
+  });
+
+  test('maps repeated lines to multiple step indices', () => {
+    const lines = [];
+    // Simulate a loop: line 3 executes at steps 0, 1, 2
+    for (let i = 0; i < 3; i++) {
+      lines.push(
+        JSON.stringify({
+          line: 3,
+          file: 'Test.java',
+          stack: [],
+          heap: {},
+          stdout: '',
+        }),
+      );
+    }
+    const outputDir = path.join(tempDir, '_traces', 'Test');
+
+    const manifest = chunkTraceOutput(
+      lines.join('\n'),
+      outputDir,
+      'Test.java',
+      '',
+      50,
+    );
+
+    expect(manifest.lineToSteps[3]).toEqual([0, 1, 2]);
+  });
+});

package/build/utils/trace.ts

@@ -0,0 +1,334 @@
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import { execFileSync } from 'child_process';
+import { makeLogger } from '../log';
+import { B } from '../colors';
+import { normalizeOutputPath } from './paths';
+import { hasMainMethod } from './literate-java';
+import { renderCodeSegment } from './code';
+import { computeLayout } from './trace-layout';
+import { generateStepSvg } from './trace-svg';
+import type { TraceStep, TraceManifest, TraceChunkEntry } from '../types';
+
+const log = makeLogger(import.meta.url);
+
+const DEFAULT_CHUNK_SIZE = 50;
+
+/**
+ * Parse // @trace-ignore comments from Java source code.
+ * Returns a map of className -> fieldName[] for fields that should be
+ * excluded from layout consideration.
+ */
+export function parseIgnoreFields(source: string): Record<string, string[]> {
+  const result: Record<string, string[]> = {};
+  const lines = source.split('\n');
+  // Track nesting: Java inner classes are reported as Outer$Inner by the tracer.
+  // Each entry is [className, braceDepthWhenOpened].
+  const classStack: { name: string; depth: number }[] = [];
+  let braceDepth = 0;
+
+  for (const line of lines) {
+    // Strip strings and comments (except @trace-ignore) to avoid false braces
+    const stripped = line
+      .replace(/"(?:[^"\\]|\\.)*"/g, '')
+      .replace(/\/\/(?!.*@trace-ignore).*/g, '');
+
+    const classMatch = stripped.match(/\bclass\s+(\w+)/);
+    if (classMatch) {
+      classStack.push({ name: classMatch[1], depth: braceDepth });
+    }
+
+    for (const ch of stripped) {
+      if (ch === '{') {
+        braceDepth++;
+      }
+      if (ch === '}') {
+        braceDepth--;
+        // Pop classes whose scope has ended
+        while (
+          classStack.length > 0 &&
+          braceDepth <= classStack[classStack.length - 1].depth
+        ) {
+          classStack.pop();
+        }
+      }
+    }
+
+    const currentClass =
+      classStack.length > 0 ? classStack.map(c => c.name).join('$') : null;
+
+    if (currentClass && line.includes('// @trace-ignore')) {
+      const before = line.split('//')[0].trim();
+      const withoutSemicolon = before.endsWith(';')
+        ? before.slice(0, -1).trim()
+        : before;
+      const parts = withoutSemicolon.split(/\s+/);
+      if (parts.length >= 2) {
+        const fieldName = parts[parts.length - 1];
+        if (!result[currentClass]) {
+          result[currentClass] = [];
+        }
+        result[currentClass].push(fieldName);
+      }
+    }
+  }
+
+  return result;
+}
+
+let tracerClassDir: string | null = null;
+
+function ensureTracerCompiled(): string {
+  if (tracerClassDir) {
+    return tracerClassDir;
+  }
+
+  const sourceDir = path.join(import.meta.dir, 'jdi-runner');
+  const sourceFile = path.join(sourceDir, 'TraceRunner.java');
+  const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'tada-tracer-'));
+
+  log.debug`Compiling TraceRunner.java into ${tempDir}`;
+
+  try {
+    execFileSync('javac', ['-d', tempDir, sourceFile], {
+      timeout: 30000,
+      stdio: ['pipe', 'pipe', 'pipe'],
+    });
+  } catch (err: unknown) {
+    const execErr = err as { stderr?: Buffer; message: string };
+    const stderr = execErr.stderr ? execErr.stderr.toString() : execErr.message;
+    fs.rmSync(tempDir, { recursive: true, force: true });
+    throw new Error(`Failed to compile TraceRunner.java:\n${stderr}`, {
+      cause: err,
+    });
+  }
+
+  tracerClassDir = tempDir;
+  return tempDir;
+}
+
+function compileTargetFile(javaFilePath: string): string {
+  const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'tada-trace-target-'));
+
+  try {
+    execFileSync(
+      'javac',
+      [
+        '-g',
+        '-d',
+        tempDir,
+        '-sourcepath',
+        path.dirname(javaFilePath),
+        javaFilePath,
+      ],
+      { timeout: 30000, stdio: ['pipe', 'pipe', 'pipe'] },
+    );
+  } catch (err: unknown) {
+    const execErr = err as { stderr?: Buffer; message: string };
+    const stderr = execErr.stderr ? execErr.stderr.toString() : execErr.message;
+    fs.rmSync(tempDir, { recursive: true, force: true });
+    throw new Error(`Compilation failed for ${javaFilePath}:\n${stderr}`, {
+      cause: err,
+    });
+  }
+
+  return tempDir;
+}
+
+export function chunkTraceOutput(
+  output: string,
+  traceOutputDir: string,
+  sourceFile: string,
+  source: string,
+  chunkSize: number = DEFAULT_CHUNK_SIZE,
+): TraceManifest {
+  fs.mkdirSync(traceOutputDir, { recursive: true });
+
+  const lines = output
+    .trim()
+    .split('\n')
+    .filter(l => l.length > 0);
+
+  // Parse all steps first (needed for layout pass)
+  const allSteps: TraceStep[] = lines.map(l => JSON.parse(l));
+
+  const lineToSteps: Record<number, number[]> = {};
+  for (let i = 0; i < allSteps.length; i++) {
+    const step = allSteps[i];
+    if (!lineToSteps[step.line]) {
+      lineToSteps[step.line] = [];
+    }
+    lineToSteps[step.line].push(i);
+  }
+
+  // Parse @trace-ignore comments from source
+  const ignoreFields = parseIgnoreFields(source);
+
+  // Compute stable layout across all steps, then generate SVG per step
+  const layout = computeLayout(allSteps, ignoreFields);
+
+  let chunkEntries: TraceChunkEntry[] = [];
+  let chunkIndex = 0;
+
+  for (const step of allSteps) {
+    const svg = generateStepSvg(step, layout);
+    chunkEntries.push({ line: step.line, stdout: step.stdout, svg });
+
+    if (chunkEntries.length >= chunkSize) {
+      fs.writeFileSync(
+        path.join(traceOutputDir, `chunk-${chunkIndex}.json`),
+        JSON.stringify(chunkEntries),
+      );
+      chunkEntries = [];
+      chunkIndex++;
+    }
+  }
+
+  if (chunkEntries.length > 0) {
+    fs.writeFileSync(
+      path.join(traceOutputDir, `chunk-${chunkIndex}.json`),
+      JSON.stringify(chunkEntries),
+    );
+  }
+
+  const manifest: TraceManifest = {
+    totalSteps: allSteps.length,
+    chunkSize,
+    sourceFile,
+    source,
+    lineToSteps,
+  };
+
+  fs.writeFileSync(
+    path.join(traceOutputDir, 'manifest.json'),
+    JSON.stringify(manifest),
+  );
+
+  return manifest;
+}
+
+export interface TraceContext {
+  filePath: string;
+  contentDir: string;
+  distDir: string;
+  applyBasePath: (subPath: string) => string;
+  cache: Map<string, TraceResult>;
+}
+
+export interface TraceResult {
+  manifestUrl: string;
+  highlightedSource: string;
+  totalSteps: number;
+  mtime: number;
+}
+
+export function createTraceHelpers(context: TraceContext): {
+  renderTrace: (javaFile: string) => string;
+} {
+  const { filePath, contentDir, distDir, applyBasePath, cache } = context;
+  const pageDir = path.dirname(filePath);
+
+  function getOrRunTrace(javaFile: string): TraceResult {
+    const javaFilePath = path.resolve(pageDir, javaFile);
+
+    const cached = cache.get(javaFilePath);
+    if (cached) {
+      const mtime = fs.statSync(javaFilePath, {
+        throwIfNoEntry: false,
+      })?.mtimeMs;
+      if (mtime !== undefined && mtime === cached.mtime) {
+        return cached;
+      }
+    }
+
+    if (!fs.existsSync(javaFilePath)) {
+      throw new Error(`Trace target not found: ${javaFilePath}`);
+    }
+
+    const source = fs.readFileSync(javaFilePath, 'utf-8');
+    if (!hasMainMethod(source)) {
+      throw new Error(
+        `${javaFilePath}: no main() method found (required for tracing)`,
+      );
+    }
+
+    const className = path.parse(javaFile).name;
+    log.info`Tracing ${B`${javaFile}`}`;
+
+    const targetClassDir = compileTargetFile(javaFilePath);
+
+    try {
+      const tracerDir = ensureTracerCompiled();
+      const output = execFileSync(
+        'java',
+        ['-cp', tracerDir, 'TraceRunner', className, targetClassDir],
+        { timeout: 60000, encoding: 'utf-8', maxBuffer: 50 * 1024 * 1024 },
+      );
+
+      const sourceLines = source.split('\n');
+      if (sourceLines[sourceLines.length - 1] === '') {
+        sourceLines.pop();
+      }
+      const ext = path.extname(javaFile).slice(1).toLowerCase();
+      const lang = ext === 'java' ? 'java' : 'text';
+      const highlightedSource = renderCodeSegment(sourceLines, 1, lang, {
+        linkLineNumbers: false,
+      });
+
+      const relDir = path
+        .relative(contentDir, pageDir)
+        .split(path.sep)
+        .join(path.posix.sep);
+      const traceOutputDir = path.join(distDir, relDir, '_traces', className);
+
+      const manifest = chunkTraceOutput(
+        output,
+        traceOutputDir,
+        `${className}.java`,
+        source,
+        DEFAULT_CHUNK_SIZE,
+      );
+
+      const manifestUrl = applyBasePath(
+        normalizeOutputPath(
+          '/' +
+            [relDir, '_traces', className, 'manifest.json']
+              .filter(Boolean)
+              .join('/'),
+        ),
+      );
+
+      const totalSteps = manifest.totalSteps;
+      const mtime = fs.statSync(javaFilePath).mtimeMs;
+      cache.set(javaFilePath, {
+        manifestUrl,
+        highlightedSource,
+        totalSteps,
+        mtime,
+      });
+      return { manifestUrl, highlightedSource, totalSteps, mtime };
+    } finally {
+      fs.rmSync(targetClassDir, { recursive: true, force: true });
+    }
+  }
+
+  return {
+    renderTrace: (javaFile: string): string => {
+      const { manifestUrl, highlightedSource, totalSteps } =
+        getOrRunTrace(javaFile);
+      const svgAttrs = `aria-hidden='true' width='16' height='16' viewBox='0 0 24 24' fill='none' stroke='currentColor' stroke-width='2' stroke-linecap='round' stroke-linejoin='round'`;
+      const iconFirst = `<svg xmlns='http://www.w3.org/2000/svg' ${svgAttrs}><line x1='2' y1='6' x2='2' y2='18'/><polyline points='10 6 4 12 10 18'/><line x1='4' y1='12' x2='22' y2='12'/></svg>`;
+      const iconPrev = `<svg xmlns='http://www.w3.org/2000/svg' ${svgAttrs}><polyline points='10 6 4 12 10 18'/><line x1='4' y1='12' x2='22' y2='12'/></svg>`;
+      const iconNext = `<svg xmlns='http://www.w3.org/2000/svg' ${svgAttrs}><line x1='2' y1='12' x2='20' y2='12'/><polyline points='14 6 20 12 14 18'/></svg>`;
+      const iconLast = `<svg xmlns='http://www.w3.org/2000/svg' ${svgAttrs}><line x1='2' y1='12' x2='20' y2='12'/><polyline points='14 6 20 12 14 18'/><line x1='22' y1='6' x2='22' y2='18'/></svg>`;
+      const controls =
+        `<button class="trace-btn trace-first" disabled tabindex="-1" aria-label="First step" title="First step">${iconFirst}</button>` +
+        `<button class="trace-btn trace-prev" disabled tabindex="-1" aria-label="Previous step" title="Previous step">${iconPrev}</button>` +
+        `<span class="trace-step-counter" style="min-width: ${String(totalSteps).length * 2 + 1}ch">1/${totalSteps}</span>` +
+        `<button class="trace-btn trace-next" aria-label="Next step" title="Next step">${iconNext}</button>` +
+        `<button class="trace-btn trace-last" tabindex="-1" aria-label="Last step" title="Last step">${iconLast}</button>`;
+      return `<div class="trace-widget" data-trace-manifest="${manifestUrl}"><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><pre class="trace-output"></pre></div></div></div>`;
+    },
+  };
+}

package/build/validate-internal-links-plugin.test.ts

@@ -80,11 +80,18 @@ describe('validateInternalLinks', () => {
     );
   });
 
-  test('rewrites code extensions to .html', () => {
-    const md = createMd(['/src/App.html'], { codeExtensions: ['java'] });
+  test('resolves code file links to .ext.html pages', () => {
+    const md = createMd(['/src/App.java.html'], { codeExtensions: ['java'] });
     expect(() => md.render('[App](/src/App.java)')).not.toThrow();
   });
 
+  test('throws for link missing the code extension', () => {
+    const md = createMd(['/src/App.java.html'], { codeExtensions: ['java'] });
+    expect(() => md.render('[App](/src/App.html)')).toThrow(
+      'broken internal link',
+    );
+  });
+
   test('detects directory links that should reference index.html', () => {
     const md = createMd(['/docs/index.html']);
     // The plugin logs the "directory link" message and throws a generic
@@ -103,4 +110,25 @@ describe('validateInternalLinks', () => {
     const md = createMd([]);
     expect(() => md.render('[CDN](//cdn.example.com/lib.js)')).not.toThrow();
   });
+
+  test('throws for .java.html link when code feature is disabled', () => {
+    // When features.code is false, codeExtensions is [] and no code pages
+    // are generated. Only the raw .java file exists as a valid target.
+    const md = createMd(['/src/Rectangle.java'], { codeExtensions: [] });
+    expect(() => md.render('[Rect](/src/Rectangle.java.html)')).toThrow(
+      'broken internal link',
+    );
+  });
+
+  test('throws for .py.html link when code feature is disabled', () => {
+    const md = createMd(['/src/demo.py'], { codeExtensions: [] });
+    expect(() => md.render('[Demo](/src/demo.py.html)')).toThrow(
+      'broken internal link',
+    );
+  });
+
+  test('allows .java link to raw file when code feature is disabled', () => {
+    const md = createMd(['/src/Rectangle.java'], { codeExtensions: [] });
+    expect(() => md.render('[Rect](/src/Rectangle.java)')).not.toThrow();
+  });
 });

package/build/validate-internal-links-plugin.ts

@@ -3,7 +3,7 @@ import type Token from 'markdown-it/lib/token.mjs';
 import path from 'path';
 import { makeLogger } from './log';
 
-const log = makeLogger(__filename);
+const log = makeLogger(import.meta.url);
 
 interface ValidateInternalLinksOptions {
   enabled?: boolean;
@@ -47,11 +47,11 @@ function rewriteCodeLink(
   pathname: string,
   codeExtPattern: RegExp | null,
 ): string {
-  if (!codeExtPattern) {
+  if (!codeExtPattern || !codeExtPattern.test(pathname)) {
     return pathname;
   }
 
-  return pathname.replace(codeExtPattern, '.html');
+  return `${pathname}.html`;
 }
 
 function resolveLinkPath(

package/build/watch-reload-client.ts

@@ -3,24 +3,8 @@ declare const __WEBSOCKET_PORT__: number;
 (function () {
   const style = document.createElement('style');
   style.textContent = [
-    '@keyframes tada-shimmer {',
-    '  0%, 25% { background-position: 200% 0; }',
-    '  100% { background-position: -200% 0; }',
-    '}',
-    'header.tada-rebuilding {',
-    '  background-image: linear-gradient(',
-    '    90deg,',
-    '    transparent 25%,',
-    '    var(--bg2-color) 50%,',
-    '    transparent 75%',
-    '  ) !important;',
-    '  background-color: var(--bg-color-translucent) !important;',
-    '  background-size: 200% 100% !important;',
-    '  background-repeat: no-repeat !important;',
-    '  animation: tada-shimmer 2s ease-in-out infinite !important;',
-    '}',
-    'body.tada-rebuilding-cursor,',
-    'body.tada-rebuilding-cursor * {',
+    'body.loading-cursor,',
+    'body.loading-cursor * {',
     '  cursor: wait !important;',
     '}',
   ].join('\n');
@@ -37,9 +21,9 @@ declare const __WEBSOCKET_PORT__: number;
       console.log('[watch-reload] Rebuilding...');
       const header = document.querySelector('header');
       if (header) {
-        header.classList.add('tada-rebuilding');
+        header.classList.add('loading');
       }
-      document.body.classList.add('tada-rebuilding-cursor');
+      document.body.classList.add('loading-cursor');
     } else if (event.data === 'reload') {
       console.log('[watch-reload] Reloading page...');
       window.location.reload();