@abreen/tada 1.8.1 → 1.10.1

package/build/utils/source-template.ts

@@ -0,0 +1,27 @@
+import _ from 'lodash';
+import type { SiteVariables } from '../types';
+
+/**
+ * Applies Lodash template syntax to a source code file's contents so that
+ * authors can interpolate site variables (like `<%= vars.fullCourseName %>`)
+ * in their source code. The template context mirrors the one used for JSON
+ * data files in `build/templates.ts`: `vars` and `site`. Invoked from
+ * `renderCodePageAsset` and `renderCopiedContentAsset` only when
+ * `features.code` is enabled.
+ */
+export function applySourceTemplate(
+  source: string,
+  siteVariables: SiteVariables,
+  filePath: string,
+): string {
+  const params = { vars: siteVariables.vars || {}, site: siteVariables };
+
+  try {
+    return _.template(source)(params);
+  } catch (err: unknown) {
+    throw new Error(
+      `${filePath}: Lodash template error in source code: ${(err as Error).message}`,
+      { cause: err },
+    );
+  }
+}

package/build/utils/trace-core.ts

@@ -0,0 +1,203 @@
+import fs from 'fs';
+import path from 'path';
+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';
+
+export const DEFAULT_CHUNK_SIZE = 50;
+
+export interface ChunkTraceOutputOptions {
+  chunkSize?: number;
+  ignoreFields?: Record<string, string[]>;
+}
+
+export function chunkTraceOutput(
+  output: string,
+  traceOutputDir: string,
+  sourceFile: string,
+  source: string,
+  options: ChunkTraceOutputOptions = {},
+): TraceManifest {
+  const chunkSize = options.chunkSize ?? DEFAULT_CHUNK_SIZE;
+  const ignoreFields = options.ignoreFields ?? {};
+
+  fs.mkdirSync(traceOutputDir, { recursive: true });
+
+  const lines = output
+    .trim()
+    .split('\n')
+    .filter(l => l.length > 0);
+
+  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);
+  }
+
+  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 function highlightTraceSource(
+  source: string,
+  language: 'java' | 'python',
+): string {
+  return renderCodeSegment(splitLines(source), 1, language, {
+    linkLineNumbers: false,
+  });
+}
+
+export function getTraceOutputPaths(
+  relDir: string,
+  traceName: string,
+  totalSteps: number,
+): string[] {
+  const baseDir = [relDir, '_traces', traceName].filter(Boolean).join('/');
+  const outputPaths = [`${baseDir}/manifest.json`];
+  for (
+    let chunkIndex = 0;
+    chunkIndex * DEFAULT_CHUNK_SIZE < totalSteps;
+    chunkIndex++
+  ) {
+    outputPaths.push(`${baseDir}/chunk-${chunkIndex}.json`);
+  }
+  return outputPaths;
+}
+
+function linkOrCopyFile(sourcePath: string, targetPath: string): void {
+  try {
+    fs.linkSync(sourcePath, targetPath);
+  } catch {
+    fs.copyFileSync(sourcePath, targetPath);
+  }
+}
+
+export function materializeTraceOutputs({
+  outputPaths,
+  targetDistDir,
+  sourceDistDir,
+}: {
+  outputPaths: string[];
+  targetDistDir: string;
+  sourceDistDir: string;
+}): boolean {
+  for (const relPath of outputPaths) {
+    const targetPath = path.join(targetDistDir, relPath);
+    if (fs.existsSync(targetPath)) {
+      continue;
+    }
+
+    const sourcePath = path.join(sourceDistDir, relPath);
+    if (!fs.existsSync(sourcePath)) {
+      return false;
+    }
+
+    fs.mkdirSync(path.dirname(targetPath), { recursive: true });
+    linkOrCopyFile(sourcePath, targetPath);
+  }
+
+  return true;
+}
+
+export function buildManifestUrl({
+  relDir,
+  traceName,
+  applyBasePath,
+}: {
+  relDir: string;
+  traceName: string;
+  applyBasePath: (subPath: string) => string;
+}): string {
+  return applyBasePath(
+    normalizeOutputPath(
+      '/' +
+        [relDir, '_traces', traceName, 'manifest.json']
+          .filter(Boolean)
+          .join('/'),
+    ),
+  );
+}
+
+export function renderTraceWidgetHtml({
+  highlightedSource,
+  manifestUrl,
+  totalSteps,
+}: {
+  highlightedSource: string;
+  manifestUrl?: string;
+  totalSteps?: number;
+}): string {
+  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 disabled = totalSteps === undefined;
+  const counterContent = disabled ? '--' : `1/${totalSteps}`;
+  const counterStyle = disabled
+    ? ''
+    : ` style="min-width: ${String(totalSteps).length * 2 + 1}ch"`;
+  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"${counterStyle}>${counterContent}</span>` +
+    (disabled
+      ? `<button class="trace-btn trace-next" disabled tabindex="-1" aria-label="Next step" title="Next step">${iconNext}</button>`
+      : `<button class="trace-btn trace-next" aria-label="Next step" title="Next step">${iconNext}</button>`) +
+    (disabled
+      ? `<button class="trace-btn trace-last" disabled tabindex="-1" aria-label="Last step" title="Last step">${iconLast}</button>`
+      : `<button class="trace-btn trace-last" tabindex="-1" aria-label="Last step" title="Last step">${iconLast}</button>`);
+  const wrapperAttrs = manifestUrl
+    ? ` data-trace-manifest="${manifestUrl}"`
+    : '';
+  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><pre class="trace-output"></pre></div></div></div>`;
+}

package/build/utils/trace-java.ts

@@ -0,0 +1,132 @@
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import { execFileSync } from 'child_process';
+import { makeLogger } from '../log';
+import { hasMainMethod, runJavac } from './literate-java';
+
+const log = makeLogger(import.meta.url);
+
+/**
+ * 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');
+  const classStack: { name: string; depth: number }[] = [];
+  let braceDepth = 0;
+
+  for (const line of lines) {
+    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--;
+        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}`;
+
+  runJavac(['-d', tempDir, sourceFile], {
+    tempDir,
+    label: 'Failed to compile TraceRunner.java',
+  });
+
+  tracerClassDir = tempDir;
+  return tempDir;
+}
+
+function compileTargetFile(javaFilePath: string): string {
+  const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'tada-trace-target-'));
+
+  runJavac(
+    [
+      '-g',
+      '-d',
+      tempDir,
+      '-sourcepath',
+      path.dirname(javaFilePath),
+      javaFilePath,
+    ],
+    { tempDir, label: `Compilation failed for ${javaFilePath}` },
+  );
+
+  return tempDir;
+}
+
+export function validateJavaTraceTarget(
+  javaFilePath: string,
+  source: string,
+): void {
+  if (!hasMainMethod(source)) {
+    throw new Error(
+      `${javaFilePath}: no main() method found (required for tracing)`,
+    );
+  }
+}
+
+export function runJavaTrace(javaFilePath: string, className: string): string {
+  const targetClassDir = compileTargetFile(javaFilePath);
+
+  try {
+    const tracerDir = ensureTracerCompiled();
+    return execFileSync(
+      'java',
+      ['-cp', tracerDir, 'TraceRunner', className, targetClassDir],
+      { timeout: 60000, encoding: 'utf-8', maxBuffer: 50 * 1024 * 1024 },
+    );
+  } finally {
+    fs.rmSync(targetClassDir, { recursive: true, force: true });
+  }
+}

package/build/utils/trace-layout.ts

@@ -789,13 +789,41 @@ function layoutOrphans(
   result: Record<string, TraceObjectLayout>,
   yOffset: number,
 ) {
+  type OrphanSlot = { ids: string[]; lastStep: number; maxHeight: number };
+
+  const orphanIds = [...objects.keys()]
+    .filter(id => !(id in result))
+    .sort((a, b) => {
+      const aInfo = objects.get(a)!;
+      const bInfo = objects.get(b)!;
+      return (
+        aInfo.firstStep - bInfo.firstStep || aInfo.lastStep - bInfo.lastStep
+      );
+    });
+
+  const slots: OrphanSlot[] = [];
+  for (const id of orphanIds) {
+    const info = objects.get(id)!;
+    const size = sizes.get(id)!;
+
+    let slot = slots.find(existing => existing.lastStep < info.firstStep);
+    if (!slot) {
+      slot = { ids: [], lastStep: info.lastStep, maxHeight: size.height };
+      slots.push(slot);
+    } else {
+      slot.lastStep = info.lastStep;
+      slot.maxHeight = Math.max(slot.maxHeight, size.height);
+    }
+    slot.ids.push(id);
+  }
+
   let y = yOffset;
-  for (const id of objects.keys()) {
-    if (!(id in result)) {
+  for (const slot of slots) {
+    for (const id of slot.ids) {
       const size = sizes.get(id)!;
       result[id] = makeLayout(0, Math.round(y), size);
-      y += size.height + OBJ_GAP;
     }
+    y += slot.maxHeight + OBJ_GAP;
   }
 }
 

package/build/utils/trace-python.ts

@@ -0,0 +1,26 @@
+import path from 'path';
+import { execFileSyncPython, resolvePythonCommand } from '../../python/command';
+
+export function runPythonTrace(pythonFilePath: string): string {
+  const pythonCommand = resolvePythonCommand();
+  if (!pythonCommand) {
+    throw new Error('Python is required to generate Python traces');
+  }
+
+  const runnerPath = path.join(
+    import.meta.dir,
+    'python-runner',
+    'trace_runner.py',
+  );
+  const options = {
+    timeout: 60000,
+    encoding: 'utf-8' as const,
+    maxBuffer: 50 * 1024 * 1024,
+  };
+
+  return execFileSyncPython(
+    [runnerPath, pythonFilePath],
+    options,
+    pythonCommand,
+  );
+}