@abreen/tada 1.4.1 → 1.5.1

package/build/generate-content-assets.ts

@@ -24,7 +24,7 @@ import type {
   WatchState,
 } from './types';
 
-const log = makeLogger(__filename);
+const log = makeLogger(import.meta.url);
 
 export class ContentRenderer {
   private siteVariables: SiteVariables;
@@ -32,6 +32,15 @@ export class ContentRenderer {
   private sourceFileCache: Map<string, Asset[]>;
   private lastBuildFiles: Set<string>;
   private javacAvailable: boolean | undefined;
+  private traceCache: Map<
+    string,
+    {
+      manifestUrl: string;
+      highlightedSource: string;
+      totalSteps: number;
+      mtime: number;
+    }
+  > = new Map();
 
   constructor(siteVariables: SiteVariables) {
     this.siteVariables = siteVariables || {};
@@ -53,16 +62,26 @@ export class ContentRenderer {
 
   getDirtySourceFiles(
     buildContentFiles: string[],
-    { changedContentFiles, templatesChanged }: WatchState = {},
+    { changedContentFiles, jsonDataChanged, partialsChanged }: WatchState = {},
   ): Set<string> {
     if (
       this.lastBuildFiles.size === 0 ||
       !changedContentFiles ||
-      templatesChanged
+      jsonDataChanged ||
+      partialsChanged
     ) {
       return new Set(buildContentFiles);
     }
 
+    // If any .java file changed, the trace cache will be stale, so rebuild
+    // all content pages to pick up the new trace output.
+    const javaFileChanged = [...changedContentFiles].some(f =>
+      f.endsWith('.java'),
+    );
+    if (javaFileChanged) {
+      return new Set(buildContentFiles);
+    }
+
     const buildFileSet = new Set(buildContentFiles);
     const dirtySourceFiles = new Set<string>();
     for (const filePath of changedContentFiles) {
@@ -107,6 +126,7 @@ export class ContentRenderer {
     distDir: string,
     validInternalTargets: Set<string>,
     assetFiles: string[],
+    literateJavaOutputPaths: Set<string>,
   ): Asset[] {
     const ext = path.extname(filePath).toLowerCase();
     const assets: Asset[] = [];
@@ -120,6 +140,8 @@ export class ContentRenderer {
           siteVariables: this.siteVariables,
           assetFiles,
           skipExecution: !this.javacAvailable,
+          validInternalTargets,
+          literateJavaOutputPaths,
         }),
       );
       return assets;
@@ -134,6 +156,9 @@ export class ContentRenderer {
           siteVariables: this.siteVariables,
           validInternalTargets,
           assetFiles,
+          literateJavaOutputPaths,
+          traceCache: this.traceCache,
+          javacAvailable: this.javacAvailable,
         }),
       );
       return assets;
@@ -166,7 +191,11 @@ export class ContentRenderer {
     contentDir: string,
   ): void {
     for (const filePath of copiedSourceFiles) {
-      for (const asset of renderCopiedContentAsset({ filePath, contentDir })) {
+      for (const asset of renderCopiedContentAsset({
+        filePath,
+        contentDir,
+        siteVariables: this.siteVariables,
+      })) {
         const outPath = path.join(distDir, asset.assetPath);
         fs.mkdirSync(path.dirname(outPath), { recursive: true });
         fs.writeFileSync(outPath, asset.content);
@@ -256,7 +285,20 @@ export class ContentRenderer {
       contentDir,
       buildContentFiles,
       Object.keys(this.siteVariables.codeLanguages || {}),
+      isFeatureEnabled(this.siteVariables, 'code'),
     );
+    const literateJavaOutputPaths = new Set<string>();
+    for (const filePath of buildContentFiles) {
+      if (isLiterateJava(filePath)) {
+        const parsed = path.parse(path.relative(contentDir, filePath));
+        const javaPath = path
+          .join(parsed.dir, parsed.name)
+          .split(path.sep)
+          .join(path.posix.sep);
+        literateJavaOutputPaths.add(`/${javaPath}`);
+      }
+    }
+
     const errors: Error[] = [];
 
     const configLinkErrors = validateConfigLinks(
@@ -275,8 +317,7 @@ export class ContentRenderer {
       log.info`Processing ${dirtySourceFiles.size} content ${noun}`;
     }
 
-    const hasLiterateJava = [...dirtySourceFiles].some(isLiterateJava);
-    if (hasLiterateJava && this.javacAvailable === undefined) {
+    if (this.javacAvailable === undefined && dirtySourceFiles.size > 0) {
       this.javacAvailable = checkJavac();
       if (!this.javacAvailable) {
         log.warn`javac was not found; literate Java pages will not include execution output`;
@@ -292,6 +333,7 @@ export class ContentRenderer {
           distDir,
           validInternalTargets,
           assetFiles,
+          literateJavaOutputPaths,
         );
       } catch (err) {
         errors.push(err as Error);

package/build/generate-favicon.ts

@@ -8,7 +8,7 @@ import { getPackageDir } from './utils/paths';
 import { deriveTheme } from './utils/derive-theme';
 import type { SiteVariables } from './types';
 
-const log = makeLogger(__filename);
+const log = makeLogger(import.meta.url);
 
 const FONT_PATH = path.join(
   getPackageDir(),

package/build/generate-fonts.ts

@@ -3,7 +3,7 @@ import path from 'path';
 import { getPackageDir } from './utils/paths';
 import { makeLogger } from './log';
 
-const log = makeLogger(__filename);
+const log = makeLogger(import.meta.url);
 const FONTS_DIR = path.join(getPackageDir(), 'fonts');
 
 export function copyFonts(distDir: string): void {

package/build/generate-katex-assets.ts

@@ -3,7 +3,7 @@ import path from 'path';
 import * as sass from 'sass';
 import { makeLogger } from './log';
 
-const log = makeLogger(__filename);
+const log = makeLogger(import.meta.url);
 
 export function copyKatexAssets(distDir: string): void {
   log.info`Copying KaTeX assets`;

package/build/log.test.ts

@@ -88,12 +88,18 @@ describe('makeLogger', () => {
     expect(log.minLogLevel).toBe('info');
   });
 
-  test('handles __filename-style name', () => {
+  test('handles path-style name', () => {
     const log = makeLogger('/path/to/module.ts');
     const { stdout } = captureOutput(() => log.info`test`);
     expect(stdout).toContain('test');
   });
 
+  test('handles file:// URL name', () => {
+    const log = makeLogger('file:///path/to/module.ts');
+    const { stdout } = captureOutput(() => log.info`test`);
+    expect(stdout).toContain('test');
+  });
+
   test('interpolates objects in template', () => {
     const log = makeLogger('test');
     const obj = { key: 'value' };

package/build/log.ts

@@ -51,7 +51,10 @@ export function makeLogger(name: string, logLevel: string = 'info'): Logger {
   if (!name) {
     name = '';
   } else {
-    // Allow for passing __filename
+    // Allow for passing import.meta.url (file:// URL) or a plain path
+    if (name.startsWith('file://')) {
+      name = new URL(name).pathname;
+    }
     name = path.basename(name, path.extname(name));
   }
 

package/build/markdown-plugins.test.ts

@@ -5,6 +5,7 @@ import applyBasePathPlugin from './apply-base-path-plugin';
 import deflistIdPlugin from './deflist-id-plugin';
 import externalLinksPlugin from './external-links-plugin';
 import headingSubtitlePlugin from './heading-subtitle-plugin';
+import columnsPlugin from './columns-plugin';
 import { createMarkdown } from './utils/markdown';
 import { stripHtmlComments, injectKatexStylesheet } from './utils/render';
 import type { SiteVariables } from './types';
@@ -30,7 +31,7 @@ describe('apply-base-path-plugin', () => {
       ].join('\n'),
     );
 
-    expect(html).toContain('href="/course/src/example.html?view=1#top"');
+    expect(html).toContain('href="/course/src/example.java.html?view=1#top"');
     expect(html).toContain('src="/course/images/pic.png"');
     expect(html).toContain('src="/course/images/raw.png"');
     expect(html).toContain('href="/course/about/"');
@@ -66,7 +67,7 @@ describe('apply-base-path-plugin', () => {
 
     const html = md.render('[App](./App.java)');
 
-    expect(html).toContain('href="./App.html"');
+    expect(html).toContain('href="./App.java.html"');
     expect(html).not.toContain('href="./App.java"');
   });
 
@@ -230,11 +231,40 @@ describe('custom markdown containers', () => {
     expect(html).toContain('<div class="alert note">');
     expect(html).toContain('<p class="title" id="read-this">');
     expect(html).toContain(
-      '<div class="alert warning"><p class="title">Warning</p>',
+      '<div class="alert warning"><p class="title" id="warning">Warning</p>',
     );
     expect(html).toContain('<p>Body</p>');
     expect(html).toContain('<p>Careful</p>');
   });
+
+  test('deduplicates alert IDs', () => {
+    const md = createProjectMarkdown();
+
+    const html = md.render(
+      [
+        '!!! note',
+        'First',
+        '!!!',
+        '',
+        '!!! note',
+        'Second',
+        '!!!',
+        '',
+        '!!! note "Custom"',
+        'Third',
+        '!!!',
+        '',
+        '!!! note "Custom"',
+        'Fourth',
+        '!!!',
+      ].join('\n'),
+    );
+
+    expect(html).toContain('<p class="title" id="note">Note</p>');
+    expect(html).toContain('<p class="title" id="note-2">Note</p>');
+    expect(html).toContain('id="custom"');
+    expect(html).toContain('id="custom-2"');
+  });
 });
 
 describe('hidden_fence rule', () => {
@@ -375,6 +405,38 @@ describe('katex plugin', () => {
   });
 });
 
+describe('columns plugin', () => {
+  const md = new MarkdownIt().use(columnsPlugin);
+
+  test('basic two-column layout', () => {
+    const html = md.render('+++\nCol 1\n+++\nCol 2\n+++\n');
+    expect(html).toContain('<div class="columns">');
+    expect(html).toContain('<p>Col 1</p>');
+    expect(html).toContain('<p>Col 2</p>');
+    // Two column divs inside the wrapper
+    expect(html).toMatch(
+      /<div class="columns">\n<div>\n.*<\/div>\n<div>\n.*<\/div>\n<\/div>/s,
+    );
+  });
+
+  test('rich markdown inside columns', () => {
+    const html = md.render('+++\n## Heading\n- item\n+++\nA paragraph.\n+++\n');
+    expect(html).toContain('<h2>Heading</h2>');
+    expect(html).toContain('<li>');
+    expect(html).toContain('<p>A paragraph.</p>');
+  });
+
+  test('incomplete block with only two fences is not matched', () => {
+    const html = md.render('+++\nContent\n+++\n');
+    expect(html).not.toContain('<div class="columns">');
+  });
+
+  test('empty columns produce no content errors', () => {
+    const html = md.render('+++\n+++\n+++\n');
+    expect(html).toContain('<div class="columns">');
+  });
+});
+
 describe('injectKatexStylesheet', () => {
   test('injects deferred KaTeX stylesheet link into <head>', () => {
     const html =

package/build/pagefind.ts

@@ -9,7 +9,7 @@ import {
 import { assertMutoolAvailable, extractPdfPages } from './pdf-text';
 import type { SiteVariables } from './types';
 
-const log = makeLogger(__filename);
+const log = makeLogger(import.meta.url);
 const PAGEFIND_VERBOSE = process.env.TADA_LOG_LEVEL === 'debug';
 const PAGEFIND_OUTPUT_SUBDIR = 'pagefind';
 

package/build/pipeline.ts

@@ -1,4 +1,3 @@
-#!/usr/bin/env bun
 import fs from 'fs';
 import { getDevSiteVariables, getProdSiteVariables } from './site-variables';
 import { compileTemplates } from './templates';
@@ -22,9 +21,11 @@ import { makeLogger, printFlair } from './log';
 import { generateBuildManifest, getNextVersion } from './build-manifest';
 import path from 'path';
 
-const log = makeLogger(__filename);
+const log = makeLogger(import.meta.url);
 
-async function runPipeline(mode: 'development' | 'production'): Promise<void> {
+export async function runPipeline(
+  mode: 'development' | 'production',
+): Promise<void> {
   const isDev = mode === 'development';
   const siteVariables = isDev ? getDevSiteVariables() : getProdSiteVariables();
   let distDir: string;
@@ -100,20 +101,3 @@ async function runPipeline(mode: 'development' | 'production'): Promise<void> {
 
   printFlair();
 }
-
-// CLI entry point
-const arg = process.argv[2];
-if (arg === 'dev') {
-  runPipeline('development').catch(err => {
-    log.error`Build failed: ${err.message}`;
-    process.exit(1);
-  });
-} else if (arg === 'prod') {
-  runPipeline('production').catch(err => {
-    log.error`Build failed: ${err.message}`;
-    process.exit(1);
-  });
-} else {
-  console.error('Usage: pipeline.js <dev|prod>');
-  process.exit(1);
-}

package/build/serve.test.ts

@@ -0,0 +1,59 @@
+import { describe, test, expect, beforeAll, afterAll } from 'bun:test';
+import fs from 'fs';
+import path from 'path';
+import { resolvePathname } from './serve';
+
+let tmpDir: string;
+
+beforeAll(() => {
+  tmpDir = fs.mkdtempSync('/tmp/serve-test-');
+  fs.writeFileSync(path.join(tmpDir, 'index.html'), '<h1>hello</h1>');
+  fs.mkdirSync(path.join(tmpDir, 'sub'));
+  fs.writeFileSync(path.join(tmpDir, 'sub', 'page.html'), '<p>page</p>');
+});
+
+afterAll(() => {
+  fs.rmSync(tmpDir, { recursive: true });
+});
+
+describe('resolvePathname', () => {
+  test('resolves a file at the root', () => {
+    const result = resolvePathname(tmpDir, '/index.html');
+    expect(result).not.toBeNull();
+    expect(result!.filePath).toBe(path.join(tmpDir, 'index.html'));
+    expect(result!.mtime).toBeInstanceOf(Date);
+  });
+
+  test('resolves a file in a subdirectory', () => {
+    const result = resolvePathname(tmpDir, '/sub/page.html');
+    expect(result).not.toBeNull();
+    expect(result!.filePath).toBe(path.join(tmpDir, 'sub', 'page.html'));
+  });
+
+  test('returns null for nonexistent file', () => {
+    expect(resolvePathname(tmpDir, '/missing.html')).toBeNull();
+  });
+
+  test('returns null for directory', () => {
+    expect(resolvePathname(tmpDir, '/sub')).toBeNull();
+  });
+
+  test('returns null for path traversal', () => {
+    expect(resolvePathname(tmpDir, '/../etc/passwd')).toBeNull();
+  });
+
+  test('returns null for encoded path traversal', () => {
+    expect(resolvePathname(tmpDir, '/%2e%2e/etc/passwd')).toBeNull();
+  });
+
+  test('returns null for invalid URL encoding', () => {
+    expect(resolvePathname(tmpDir, '/%ZZ')).toBeNull();
+  });
+
+  test('decodes percent-encoded path', () => {
+    fs.writeFileSync(path.join(tmpDir, 'spaced file.html'), 'ok');
+    const result = resolvePathname(tmpDir, '/spaced%20file.html');
+    expect(result).not.toBeNull();
+    expect(result!.filePath).toBe(path.join(tmpDir, 'spaced file.html'));
+  });
+});

package/build/serve.ts

@@ -1,26 +1,12 @@
 import fs from 'fs';
 import path from 'path';
-import { getDistDir } from './util';
 import { makeLogger } from './log';
 import { B } from './colors';
 
-const log = makeLogger(__filename);
+const log = makeLogger(import.meta.url);
 
-function messageReady(port: number): void {
-  if (process.send) {
-    process.send({ ready: true, port });
-  }
-}
-
-let distDir: string;
-try {
-  distDir = getDistDir();
-} catch (err) {
-  log.error`Failed to start server: ${err}`;
-  process.exit(1);
-}
-
-function resolvePathname(
+export function resolvePathname(
+  distDir: string,
   pathname: string,
 ): { filePath: string; mtime: Date } | null {
   let decodedPath: string;
@@ -54,45 +40,35 @@ function resolvePathname(
   return { filePath: resolvedPath, mtime: stat.mtime };
 }
 
-function createResponse(req: Request): Response {
-  const url = new URL(req.url);
-  const result = resolvePathname(url.pathname);
-  if (!result) {
-    return new Response('Not Found', { status: 404 });
-  }
+export interface StartServerOptions {
+  port?: number;
+  distDir: string;
+  onReady?: (port: number) => void;
+}
 
-  const headers = {
-    'Cache-Control': 'no-cache',
-    'Last-Modified': result.mtime.toUTCString(),
-  };
+export function startServer(options: StartServerOptions): void {
+  const { port = 8080, distDir, onReady } = options;
 
-  const ims = req.headers.get('If-Modified-Since');
-  if (ims && new Date(ims) >= new Date(headers['Last-Modified'])) {
-    return new Response(null, { status: 304, headers });
-  }
+  function createResponse(req: Request): Response {
+    const url = new URL(req.url);
+    const result = resolvePathname(distDir, url.pathname);
+    if (!result) {
+      return new Response('Not Found', { status: 404 });
+    }
 
-  return new Response(Bun.file(result.filePath), { headers });
-}
+    const headers = {
+      'Cache-Control': 'no-cache',
+      'Last-Modified': result.mtime.toUTCString(),
+    };
 
-function getPortArg(): number {
-  const idx = process.argv.indexOf('--port');
-  if (idx === -1) {
-    return 8080;
-  }
-  const raw = process.argv[idx + 1];
-  if (!raw) {
-    log.error`--port requires a value`;
-    process.exit(1);
-  }
-  const port = parseInt(raw, 10);
-  if (isNaN(port) || port <= 0 || port >= 65536) {
-    log.error`Invalid port value: ${raw}`;
-    process.exit(1);
+    const ims = req.headers.get('If-Modified-Since');
+    if (ims && new Date(ims) >= new Date(headers['Last-Modified'])) {
+      return new Response(null, { status: 304, headers });
+    }
+
+    return new Response(Bun.file(result.filePath), { headers });
   }
-  return port;
-}
 
-function listen(port: number): void {
   try {
     const server = Bun.serve({
       port,
@@ -104,21 +80,11 @@ function listen(port: number): void {
     });
 
     log.info`Dev server: ${B`http://localhost:${server.port}/index.html`}`;
-    messageReady(server.port as number);
+    if (onReady) {
+      onReady(server.port as number);
+    }
   } catch (err) {
     log.error`Failed to start server on port ${port}: ${err}`;
     process.exit(1);
   }
 }
-
-listen(getPortArg());
-
-process.on('uncaughtException', err => {
-  log.error`Uncaught exception: ${err}`;
-  process.exit(1);
-});
-
-process.on('unhandledRejection', reason => {
-  log.error`Unhandled rejection: ${reason}`;
-  process.exit(1);
-});

package/build/templates.ts

@@ -7,7 +7,7 @@ import { getPackageDir, getConfigDir } from './utils/paths';
 import type { ValidateFunction } from 'ajv';
 import type { Logger, SiteVariables } from './types';
 
-const log: Logger = makeLogger(__filename);
+const log: Logger = makeLogger(import.meta.url);
 
 // Store all templates in memory (don't read template files during build)
 const templates: Record<string, string> = {};
@@ -120,7 +120,7 @@ export function compileTemplates(
     log.debug`Reading ${fileName}`;
     jsonData[fileName] = JSON.parse(
       _.template(fs.readFileSync(filePath, 'utf-8'))({
-        ...(siteVariables.vars || {}),
+        vars: siteVariables.vars || {},
         site: siteVariables,
         base: siteVariables.base,
         basePath: siteVariables.basePath,

package/build/toc-plugin.test.ts

@@ -4,20 +4,14 @@ import type { JavaTocEntry } from './types';
 
 describe('generateTocHtml', () => {
   test('returns empty string for empty array', () => {
-    expect(generateTocHtml([])).toBe('');
-  });
-
-  test('returns empty string for null/undefined', () => {
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    expect(generateTocHtml(null as any)).toBe('');
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    expect(generateTocHtml(undefined as any)).toBe('');
+    expect(generateTocHtml([], [])).toBe('');
   });
 
   test('generates heading items with correct level and link', () => {
-    const html = generateTocHtml([
-      { kind: 'heading', level: '2', id: 'intro', innerHtml: 'Introduction' },
-    ]);
+    const html = generateTocHtml(
+      [{ kind: 'heading', level: '2', id: 'intro', innerHtml: 'Introduction' }],
+      [],
+    );
     expect(html).toContain('<ol>');
     expect(html).toContain('class="heading-item level2"');
     expect(html).toContain('href="#intro"');
@@ -26,33 +20,54 @@ describe('generateTocHtml', () => {
   });
 
   test('generates dinkus items', () => {
-    const html = generateTocHtml([{ kind: 'dinkus' }]);
+    const html = generateTocHtml([{ kind: 'dinkus' }], []);
     expect(html).toContain('class="dinkus-item"');
   });
 
   test('generates alert items at one level deeper than last heading', () => {
-    const html = generateTocHtml([
-      { kind: 'heading', level: '2', id: 'sec', innerHtml: 'Section' },
-      { kind: 'alert', type: 'warning', title: 'Caution' },
-    ]);
+    const html = generateTocHtml(
+      [
+        { kind: 'heading', level: '2', id: 'sec', innerHtml: 'Section' },
+        { kind: 'alert', type: 'warning', title: 'Caution' },
+      ],
+      ['caution'],
+    );
     expect(html).toContain('class="alert-item level3 warning"');
+    expect(html).toContain('href="#caution"');
     expect(html).toContain('Caution');
   });
 
   test('alert before any heading uses level 2 (lastHeadingLevel defaults to 1)', () => {
-    const html = generateTocHtml([
-      { kind: 'alert', type: 'note', title: 'Note' },
-    ]);
+    const html = generateTocHtml(
+      [{ kind: 'alert', type: 'note', title: 'Note' }],
+      ['note'],
+    );
     expect(html).toContain('class="alert-item level2 note"');
+    expect(html).toContain('href="#note"');
+  });
+
+  test('alert links use deduplicated IDs', () => {
+    const html = generateTocHtml(
+      [
+        { kind: 'alert', type: 'note', title: 'Note' },
+        { kind: 'alert', type: 'note', title: 'Note' },
+      ],
+      ['note', 'note-2'],
+    );
+    expect(html).toContain('href="#note"');
+    expect(html).toContain('href="#note-2"');
   });
 
   test('handles mixed items in order', () => {
-    const html = generateTocHtml([
-      { kind: 'heading', level: '2', id: 'a', innerHtml: 'A' },
-      { kind: 'dinkus' },
-      { kind: 'heading', level: '3', id: 'b', innerHtml: 'B' },
-      { kind: 'alert', type: 'note', title: 'FYI' },
-    ]);
+    const html = generateTocHtml(
+      [
+        { kind: 'heading', level: '2', id: 'a', innerHtml: 'A' },
+        { kind: 'dinkus' },
+        { kind: 'heading', level: '3', id: 'b', innerHtml: 'B' },
+        { kind: 'alert', type: 'note', title: 'FYI' },
+      ],
+      ['fyi'],
+    );
     expect(html).toContain('level2');
     expect(html).toContain('dinkus-item');
     expect(html).toContain('level3');