@abreen/tada 1.4.1 → 1.5.1

package/build/toc-plugin.ts

@@ -17,6 +17,7 @@ interface AlertItem {
   kind: 'alert';
   type: string;
   title: string;
+  id?: string;
 }
 
 type TocItem = HeadingItem | DinkusItem | AlertItem;
@@ -103,12 +104,16 @@ export function tocPlugin(md: MarkdownIt): void {
   });
 }
 
-export function generateTocHtml(tocItems: TocItem[]): string {
+export function generateTocHtml(
+  tocItems: TocItem[],
+  alertIds: string[],
+): string {
   if (!tocItems || tocItems.length === 0) {
     return '';
   }
 
   let lastHeadingLevel = 1;
+  let alertIdx = 0;
   const parts = ['<ol>'];
 
   for (const item of tocItems) {
@@ -128,9 +133,11 @@ export function generateTocHtml(tocItems: TocItem[]): string {
 
     if (item.kind === 'alert') {
       const level = lastHeadingLevel + 1;
+      const id = alertIds[alertIdx++];
+      const href = `#${id}`;
       parts.push(
         `<li class="alert-item level${level} ${item.type}">` +
-          `<a href="#">${item.title}</a></li>`,
+          `<a href="${href}">${item.title}</a></li>`,
       );
     }
   }

package/build/{types.ts → types.d.ts}

@@ -40,7 +40,8 @@ export interface ContentRenderOptions {
 /** State passed from watch mode to control incremental rebuilds */
 export interface WatchState {
   changedContentFiles?: Set<string>;
-  templatesChanged?: boolean;
+  jsonDataChanged?: boolean;
+  partialsChanged?: boolean;
 }
 
 /** Result from ContentRenderer.processContent() */
@@ -78,6 +79,17 @@ export interface RenderPlainTextOptions {
   siteVariables: SiteVariables;
   validInternalTargets: Set<string>;
   assetFiles: string[];
+  literateJavaOutputPaths?: Set<string>;
+  traceCache?: Map<
+    string,
+    {
+      manifestUrl: string;
+      highlightedSource: string;
+      totalSteps: number;
+      mtime: number;
+    }
+  >;
+  javacAvailable?: boolean;
 }
 
 /** Options for code page asset rendering */
@@ -97,12 +109,15 @@ export interface RenderLiterateJavaOptions {
   siteVariables: SiteVariables;
   assetFiles: string[];
   skipExecution?: boolean;
+  validInternalTargets: Set<string>;
+  literateJavaOutputPaths?: Set<string>;
 }
 
 /** Options for copied content asset rendering */
 export interface RenderCopiedContentOptions {
   filePath: string;
   contentDir: string;
+  siteVariables: SiteVariables;
 }
 
 /** Front matter parse result (from parseFrontMatterAndContent) */
@@ -166,6 +181,78 @@ export interface LiterateRunnerEntry {
   output: string;
 }
 
+/** A single execution step captured by TraceRunner */
+export interface TraceStep {
+  line: number;
+  file: string;
+  stack: TraceStackFrame[];
+  heap: Record<string, TraceHeapObject>;
+  stdout: string;
+}
+
+export interface TraceStackFrame {
+  method: string;
+  class: string;
+  line?: number;
+  locals: Record<string, TraceValue>;
+}
+
+export type TraceValue =
+  | {
+      type: 'int' | 'long' | 'short' | 'byte' | 'float' | 'double';
+      value: number;
+    }
+  | { type: 'boolean'; value: boolean }
+  | { type: 'char' | 'String'; value: string }
+  | { type: 'null' }
+  | { type: 'ref'; id: string }
+  | { type: 'unknown' }
+  | { type: 'uninitialized' }
+  | { type: 'truncated'; remaining: number };
+
+export type TraceHeapObject =
+  | { type: string; elements: TraceValue[] }
+  | { type: string; fields: Record<string, TraceValue> }
+  | { type: string; value: string };
+
+/** Manifest written alongside trace chunks */
+export interface TraceManifest {
+  totalSteps: number;
+  chunkSize: number;
+  sourceFile: string;
+  source: string;
+  lineToSteps: Record<number, number[]>;
+}
+
+/** Position and size of a heap object in the precomputed layout. */
+export interface TraceObjectLayout {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+  /** For field objects, x-offset where value boxes start. */
+  valueX?: number;
+  /** For arrays, width of each cell. */
+  cellWidth?: number;
+  /** Field names that are structural children in the tree layout. */
+  childFields?: string[];
+}
+
+/** A precomputed layout for the entire trace (all steps). */
+export interface TraceLayout {
+  /** Stable position for every heap object that ever exists. */
+  objects: Record<string, TraceObjectLayout>;
+  /** Fields to ignore for layout on each class (from @trace-ignore). */
+  ignoreFields: Record<string, string[]>;
+}
+
+/** A single entry in a chunk file (new format with precomputed SVG). */
+export interface TraceChunkEntry {
+  line: number;
+  stdout: string;
+  svg: string;
+}
+
 /** Site config creation input (used by bin/validators) */
 export interface SiteConfigInput {
   title: string;

package/build/util.ts

@@ -5,7 +5,7 @@ export {
   getValidInternalTargets,
   shouldSkipContentFile,
 } from './utils/content-files';
-export { extensionIsMarkdown } from './utils/file-types';
+export { extensionIsMarkdown, isPartial } from './utils/file-types';
 export { createMarkdown } from './utils/markdown';
 export {
   createApplyBasePath,

package/build/utils/code.ts

@@ -1,10 +1,12 @@
 import MarkdownIt from 'markdown-it';
+import path from 'path';
 import { parse as parseJava } from 'java-parser';
 import { JSDOM } from 'jsdom';
 import { makeLogger } from '../log';
 import { getHighlighter } from './shiki-highlighter';
 import externalLinksPlugin from '../external-links-plugin';
 import applyBasePathPlugin from '../apply-base-path-plugin';
+import { createApplyBasePath } from './paths';
 import type { JavaTocEntry, SiteVariables } from '../types';
 
 interface CstNode {
@@ -32,7 +34,7 @@ interface CodeSegment {
   startLine: number;
 }
 
-const log = makeLogger(__filename);
+const log = makeLogger(import.meta.url);
 
 const PROSE_LINE = /^\s*\/\/\/(\s|$)/;
 
@@ -45,6 +47,69 @@ function createCodeMarkdown(
     .use(applyBasePathPlugin, siteVariables, options);
 }
 
+// Matches Markdown links: [text](url)
+const MARKDOWN_LINK = /\[([^\]]*)\]\(([^)]+)\)/g;
+
+/**
+ * Rewrites Markdown links in raw `///` comment lines so that relative and
+ * absolute paths become full URLs using `base + basePath`.
+ */
+export function rewriteProseLinks(
+  lines: string[],
+  siteVariables: SiteVariables,
+  pageDirPath: string,
+): string[] {
+  const applyBasePath = createApplyBasePath(siteVariables);
+  const codeExtensions = Object.keys(siteVariables.codeLanguages ?? {});
+
+  function rewriteCodeExt(p: string): string {
+    for (const ext of codeExtensions) {
+      if (p.endsWith(`.${ext}`)) {
+        return p + '.html';
+      }
+    }
+    return p;
+  }
+
+  function rewriteHref(href: string): string {
+    // Separate pathname from query/fragment
+    const match = href.match(/^([^?#]*)(.*)$/);
+    const pathname = match ? match[1] : href;
+    const suffix = match ? match[2] : '';
+
+    // Leave external, protocol-relative, and anchor-only links unchanged
+    if (
+      /^[a-zA-Z][a-zA-Z\d+.-]*:/.test(href) ||
+      href.startsWith('//') ||
+      href.startsWith('#')
+    ) {
+      return href;
+    }
+
+    if (pathname.startsWith('/')) {
+      // Absolute path: apply code ext rewriting, then base + basePath
+      return (
+        siteVariables.base + applyBasePath(rewriteCodeExt(pathname)) + suffix
+      );
+    }
+
+    // Relative path: resolve against page directory, then base + basePath
+    const resolved = path.posix.normalize(`/${pageDirPath}/${pathname}`);
+    return (
+      siteVariables.base + applyBasePath(rewriteCodeExt(resolved)) + suffix
+    );
+  }
+
+  return lines.map(line => {
+    if (!PROSE_LINE.test(line)) {
+      return line;
+    }
+    return line.replace(MARKDOWN_LINK, (whole, text, href) => {
+      return `[${text}](${rewriteHref(href)})`;
+    });
+  });
+}
+
 const KIND_LABELS: Record<string, string> = {
   constructor: 'Constructor',
   field: 'Field',
@@ -403,6 +468,7 @@ export function renderCodeSegment(
   lines: string[],
   startLine: number,
   lang: string,
+  { linkLineNumbers = true }: { linkLineNumbers?: boolean } = {},
 ): string {
   const source = lines.join('\n');
   let lineHtml: string[] | undefined;
@@ -427,7 +493,10 @@ export function renderCodeSegment(
 
   const rows = lineHtml.map((line, i) => {
     const lineNumber = startLine + i;
-    return `<span class="code-row"><a class="line-number" data-pagefind-ignore tabindex="-1" id="L${lineNumber}" href="#L${lineNumber}">${lineNumber}</a><code class="shiki language-${lang}">${line}</code></span>`;
+    const lineNumEl = linkLineNumbers
+      ? `<a class="line-number" data-pagefind-ignore tabindex="-1" id="L${lineNumber}" href="#L${lineNumber}">${lineNumber}</a>`
+      : `<span class="line-number" data-pagefind-ignore data-line="${lineNumber}">${lineNumber}</span>`;
+    return `<span class="code-row">${lineNumEl}<code class="shiki language-${lang}">${line}</code></span>`;
   });
 
   return `<pre>${rows.join('')}</pre>`;
@@ -437,6 +506,7 @@ export function renderCodeWithComments(
   sourceCode: string,
   lang: string,
   siteVariables: SiteVariables,
+  pageDirPath?: string,
 ): string {
   const md = createCodeMarkdown(siteVariables);
   const lines = sourceCode.split('\n');
@@ -490,7 +560,10 @@ export function renderCodeWithComments(
         const prose = segment.lines
           .map(line => line.replace(/^\s*\/\/\/(\s?)/, ''))
           .join('\n');
-        const source = escapeAttr(segment.lines.join('\n'));
+        const rewrittenLines = pageDirPath
+          ? rewriteProseLinks(segment.lines, siteVariables, pageDirPath)
+          : segment.lines;
+        const source = escapeAttr(rewrittenLines.join('\n'));
         return `<div class="code-prose" data-prose-source="${source}" style="--prose-indent: ${indent}ch"><div class="code-prose-gutter"></div><div class="code-prose-content">${md.render(prose)}</div></div>`;
       }
     })

package/build/utils/content-files.test.ts

@@ -0,0 +1,56 @@
+import { describe, test, expect, beforeEach, afterEach } from 'bun:test';
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import { getValidInternalTargets } from './content-files';
+
+describe('getValidInternalTargets', () => {
+  let tempDir: string;
+  let originalCwd: string;
+
+  beforeEach(() => {
+    tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'tada-targets-test-'));
+    fs.mkdirSync(path.join(tempDir, 'content'));
+    fs.mkdirSync(path.join(tempDir, 'public'), { recursive: true });
+    originalCwd = process.cwd();
+    process.chdir(tempDir);
+  });
+
+  afterEach(() => {
+    process.chdir(originalCwd);
+    fs.rmSync(tempDir, { recursive: true, force: true });
+  });
+
+  test('includes public files as valid targets', () => {
+    fs.writeFileSync(path.join(tempDir, 'public', 'test.txt'), '');
+
+    const contentDir = path.join(tempDir, 'content');
+    const targets = getValidInternalTargets(contentDir, [], [], false);
+
+    expect(targets.has('/test.txt')).toBe(true);
+  });
+
+  test('includes public index.html by exact path only', () => {
+    const coverageDir = path.join(tempDir, 'public', 'coverage');
+    fs.mkdirSync(coverageDir, { recursive: true });
+    fs.writeFileSync(path.join(coverageDir, 'index.html'), '');
+
+    const contentDir = path.join(tempDir, 'content');
+    const targets = getValidInternalTargets(contentDir, [], [], false);
+
+    expect(targets.has('/coverage/index.html')).toBe(true);
+    expect(targets.has('/coverage/')).toBe(false);
+    expect(targets.has('/coverage')).toBe(false);
+  });
+
+  test('includes nested public files', () => {
+    const subDir = path.join(tempDir, 'public', 'assets');
+    fs.mkdirSync(subDir, { recursive: true });
+    fs.writeFileSync(path.join(subDir, 'style.css'), '');
+
+    const contentDir = path.join(tempDir, 'content');
+    const targets = getValidInternalTargets(contentDir, [], [], false);
+
+    expect(targets.has('/assets/style.css')).toBe(true);
+  });
+});

package/build/utils/content-files.ts

@@ -5,6 +5,7 @@ import {
   getProcessedExtensions,
   extensionIsMarkdown,
   isLiterateJava,
+  isPartial,
 } from './file-types';
 import { getPublicDir, normalizeOutputPath } from './paths';
 
@@ -46,7 +47,7 @@ export function getBuildContentFiles(
   codeExtensions: string[],
 ): string[] {
   return getContentFiles(contentDir, codeExtensions).filter(
-    filePath => !shouldSkipContentFile(filePath),
+    filePath => !isPartial(filePath) && !shouldSkipContentFile(filePath),
   );
 }
 
@@ -96,6 +97,7 @@ export function getValidInternalTargets(
   contentDir: string,
   contentFiles: string[],
   codeExtensions: string[],
+  codeEnabled: boolean,
 ): Set<string> {
   const targets = new Set<string>();
   const codeExtensionSet = new Set(
@@ -103,6 +105,9 @@ export function getValidInternalTargets(
   );
 
   for (const filePath of contentFiles) {
+    if (isPartial(filePath)) {
+      continue;
+    }
     const relPath = path.relative(contentDir, filePath);
     const parsed = path.parse(relPath);
     const ext = parsed.ext.toLowerCase();
@@ -112,21 +117,20 @@ export function getValidInternalTargets(
       .join(path.posix.sep);
 
     if (isLiterateJava(filePath)) {
-      const baseName = path.parse(parsed.name).name;
-      const literateSubPath = path
-        .join(parsed.dir, baseName)
+      // parsed.name is e.g. "VowelCounter.java"; the output page is
+      // VowelCounter.java.html and the source file is VowelCounter.java
+      const javaSubPath = path
+        .join(parsed.dir, parsed.name)
         .split(path.sep)
         .join(path.posix.sep);
-      addGeneratedRouteAliases(targets, `/${literateSubPath}.html`);
-      targets.add(
-        normalizeOutputPath(
-          `/${path.join(parsed.dir, parsed.name).split(path.sep).join(path.posix.sep)}`,
-        ),
-      );
+      addGeneratedRouteAliases(targets, `/${javaSubPath}.html`);
+      targets.add(normalizeOutputPath(`/${javaSubPath}`));
     } else if (extensionIsMarkdown(ext) || ext === '.html') {
       addGeneratedRouteAliases(targets, `/${subPath}.html`);
     } else if (codeExtensionSet.has(ext.slice(1))) {
-      addGeneratedRouteAliases(targets, `/${subPath}.html`);
+      if (codeEnabled) {
+        addGeneratedRouteAliases(targets, `/${relPath}.html`);
+      }
       targets.add(normalizeOutputPath(`/${relPath}`));
     }
   }

package/build/utils/file-types.test.ts

@@ -3,6 +3,7 @@ import {
   getProcessedExtensions,
   extensionIsMarkdown,
   isLiterateJava,
+  isPartial,
 } from './file-types';
 
 describe('getProcessedExtensions', () => {
@@ -38,6 +39,23 @@ describe('extensionIsMarkdown', () => {
   });
 });
 
+describe('isPartial', () => {
+  test('returns true for files starting with _', () => {
+    expect(isPartial('_foo.md')).toBe(true);
+    expect(isPartial('/content/subdir/_bar.html')).toBe(true);
+  });
+
+  test('returns false for regular files', () => {
+    expect(isPartial('index.md')).toBe(false);
+    expect(isPartial('/content/page.html')).toBe(false);
+  });
+
+  test('handles paths with directories', () => {
+    expect(isPartial('/content/lectures/02/_pr1.md')).toBe(true);
+    expect(isPartial('/content/lectures/02/subdir/_foobar.html')).toBe(true);
+  });
+});
+
 describe('isLiterateJava', () => {
   test('returns true for .java.md files', () => {
     expect(isLiterateJava('Example.java.md')).toBe(true);

package/build/utils/file-types.ts

@@ -8,6 +8,10 @@ export function extensionIsMarkdown(ext: string): boolean {
   return ['.md', '.markdown'].includes(ext);
 }
 
+export function isPartial(filePath: string): boolean {
+  return path.basename(filePath).startsWith('_');
+}
+
 export function isLiterateJava(filePath: string): boolean {
   return path.basename(filePath).toLowerCase().endsWith('.java.md');
 }

package/build/utils/include.test.ts

@@ -0,0 +1,117 @@
+import { describe, test, expect, beforeEach, afterEach } from 'bun:test';
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import { createIncludeFunction } from './include';
+
+describe('createIncludeFunction', () => {
+  let tempDir: string;
+
+  beforeEach(() => {
+    tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'tada-include-test-'));
+  });
+
+  afterEach(() => {
+    fs.rmSync(tempDir, { recursive: true, force: true });
+  });
+
+  test('includes a basic Markdown partial', () => {
+    const partialPath = path.join(tempDir, '_partial.md');
+    fs.writeFileSync(partialPath, 'Hello from partial');
+
+    const callerPath = path.join(tempDir, 'page.md');
+    const include = createIncludeFunction(callerPath, {});
+    expect(include('_partial.md')).toBe('Hello from partial');
+  });
+
+  test('processes Lodash expressions in partials', () => {
+    const partialPath = path.join(tempDir, '_partial.md');
+    fs.writeFileSync(partialPath, 'Title: <%= page.title %>');
+
+    const callerPath = path.join(tempDir, 'page.md');
+    const params = { page: { title: 'Hello' } };
+    const include = createIncludeFunction(callerPath, params);
+    expect(include('_partial.md')).toBe('Title: Hello');
+  });
+
+  test('includes an HTML partial with Lodash', () => {
+    const partialPath = path.join(tempDir, '_partial.html');
+    fs.writeFileSync(partialPath, '<p><%= site.title %></p>');
+
+    const callerPath = path.join(tempDir, 'page.md');
+    const params = { site: { title: 'My Site' } };
+    const include = createIncludeFunction(callerPath, params);
+    expect(include('_partial.html')).toBe('<p>My Site</p>');
+  });
+
+  test('supports nested includes', () => {
+    const aPath = path.join(tempDir, '_a.md');
+    const bPath = path.join(tempDir, '_b.md');
+    fs.writeFileSync(aPath, 'A then <%= include("_b.md") %>');
+    fs.writeFileSync(bPath, 'B');
+
+    const callerPath = path.join(tempDir, 'page.md');
+    const include = createIncludeFunction(callerPath, {});
+    expect(include('_a.md')).toBe('A then B');
+  });
+
+  test('resolves paths relative to the calling file', () => {
+    const subdir = path.join(tempDir, 'subdir');
+    fs.mkdirSync(subdir);
+    fs.writeFileSync(path.join(subdir, '_inner.md'), 'Inner content');
+
+    const callerPath = path.join(tempDir, 'page.md');
+    const include = createIncludeFunction(callerPath, {});
+    expect(include('subdir/_inner.md')).toBe('Inner content');
+  });
+
+  test('nested includes resolve relative to the partial, not the caller', () => {
+    const subdir = path.join(tempDir, 'subdir');
+    fs.mkdirSync(subdir);
+    fs.writeFileSync(
+      path.join(subdir, '_a.md'),
+      'A then <%= include("_b.md") %>',
+    );
+    fs.writeFileSync(path.join(subdir, '_b.md'), 'B in subdir');
+
+    const callerPath = path.join(tempDir, 'page.md');
+    const include = createIncludeFunction(callerPath, {});
+    expect(include('subdir/_a.md')).toBe('A then B in subdir');
+  });
+
+  test('throws when partial not found', () => {
+    const callerPath = path.join(tempDir, 'page.md');
+    const include = createIncludeFunction(callerPath, {});
+    expect(() => include('_missing.md')).toThrow('partial not found');
+  });
+
+  test('throws when target does not start with _', () => {
+    const filePath = path.join(tempDir, 'notpartial.md');
+    fs.writeFileSync(filePath, 'content');
+
+    const callerPath = path.join(tempDir, 'page.md');
+    const include = createIncludeFunction(callerPath, {});
+    expect(() => include('notpartial.md')).toThrow('must start with "_"');
+  });
+
+  test('throws when max depth exceeded', () => {
+    // Create a chain: _0.md includes _1.md includes _2.md ... up to 11
+    for (let i = 0; i <= 10; i++) {
+      const content = i < 10 ? `<%= include("_${i + 1}.md") %>` : 'end';
+      fs.writeFileSync(path.join(tempDir, `_${i}.md`), content);
+    }
+
+    const callerPath = path.join(tempDir, 'page.md');
+    const include = createIncludeFunction(callerPath, {});
+    expect(() => include('_0.md')).toThrow('maximum include depth');
+  });
+
+  test('strips HTML comments from partials', () => {
+    const partialPath = path.join(tempDir, '_partial.md');
+    fs.writeFileSync(partialPath, 'before<!--- hidden --->after');
+
+    const callerPath = path.join(tempDir, 'page.md');
+    const include = createIncludeFunction(callerPath, {});
+    expect(include('_partial.md')).toBe('beforeafter');
+  });
+});

package/build/utils/include.ts

@@ -0,0 +1,53 @@
+import fs from 'fs';
+import path from 'path';
+import _ from 'lodash';
+import { isPartial } from './file-types';
+import { stripHtmlComments } from './render';
+
+const MAX_INCLUDE_DEPTH = 10;
+
+export function createIncludeFunction(
+  callerFilePath: string,
+  templateParams: Record<string, unknown>,
+  depth: number = 0,
+): (relativePath: string) => string {
+  return (relativePath: string): string => {
+    const callerDir = path.dirname(callerFilePath);
+    const resolved = path.resolve(callerDir, relativePath);
+
+    if (!fs.existsSync(resolved)) {
+      throw new Error(
+        `${callerFilePath}: partial not found: ${relativePath} (resolved to ${resolved})`,
+      );
+    }
+    if (!isPartial(resolved)) {
+      throw new Error(
+        `${callerFilePath}: include target must start with "_": ${relativePath}`,
+      );
+    }
+    if (depth >= MAX_INCLUDE_DEPTH) {
+      throw new Error(
+        `${callerFilePath}: maximum include depth (${MAX_INCLUDE_DEPTH}) exceeded`,
+      );
+    }
+
+    const raw = fs.readFileSync(resolved, 'utf-8');
+    const content = stripHtmlComments(raw);
+
+    const nestedInclude = createIncludeFunction(
+      resolved,
+      templateParams,
+      depth + 1,
+    );
+    const nestedParams = { ...templateParams, include: nestedInclude };
+
+    try {
+      return _.template(content)(nestedParams);
+    } catch (err) {
+      throw new Error(
+        `${resolved}: Lodash template error in partial: ${(err as Error).message}`,
+        { cause: err },
+      );
+    }
+  };
+}