@abreen/tada 1.1.0 → 1.3.1

package/build/serve.ts

@@ -1,8 +1,8 @@
 import fs from 'fs';
 import path from 'path';
-import { getDistDir } from './util.js';
-import { makeLogger } from './log.js';
-import { B } from './colors.js';
+import { getDistDir } from './util';
+import { makeLogger } from './log';
+import { B } from './colors';
 
 const log = makeLogger(__filename);
 
@@ -20,7 +20,9 @@ try {
   process.exit(1);
 }
 
-function resolvePathname(pathname: string): string | null {
+function resolvePathname(
+  pathname: string,
+): { filePath: string; mtime: Date } | null {
   let decodedPath: string;
   try {
     decodedPath = decodeURIComponent(pathname);
@@ -49,17 +51,27 @@ function resolvePathname(pathname: string): string | null {
     return null;
   }
 
-  return resolvedPath;
+  return { filePath: resolvedPath, mtime: stat.mtime };
 }
 
 function createResponse(req: Request): Response {
   const url = new URL(req.url);
-  const filePath = resolvePathname(url.pathname);
-  if (!filePath) {
+  const result = resolvePathname(url.pathname);
+  if (!result) {
     return new Response('Not Found', { status: 404 });
   }
 
-  return new Response(Bun.file(filePath));
+  const headers = {
+    'Cache-Control': 'no-cache',
+    'Last-Modified': result.mtime.toUTCString(),
+  };
+
+  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 });
 }
 
 function getPortArg(): number {

package/build/site-variables.ts

@@ -1,15 +1,16 @@
 import fs from 'fs';
 import path from 'path';
-import { compile as compileJsonSchema, doValidation } from './json-schema.js';
-import { getProjectDir } from './utils/paths.js';
-import type { SiteVariables } from './types.js';
-import siteSchema from './site.schema.json' with { type: 'json' };
+import { compile as compileJsonSchema, doValidation } from './json-schema';
+import { getProjectDir } from './utils/paths';
+import type { SiteVariables } from './types';
+import siteSchema from '../schema/site.schema.json' with { type: 'json' };
+import timezones from '../src/timezone/timezones.json' with { type: 'json' };
 
 const configDir = getProjectDir();
 
 const DEFAULT: Partial<SiteVariables> = {
   basePath: '/',
-  features: { search: true, code: true },
+  features: { search: true, code: true, favicon: true },
 };
 
 const isValid = compileJsonSchema(siteSchema);
@@ -48,6 +49,13 @@ function getSiteVariables(env: string): SiteVariables {
   }
 
   doValidation(isValid, variables, fileName);
+
+  if (!timezones.some(t => t.value === variables.defaultTimeZone)) {
+    throw new Error(
+      `${fileName}: defaultTimeZone "${variables.defaultTimeZone}" is not a valid time zone`,
+    );
+  }
+
   return variables;
 }
 

package/build/templates.ts

@@ -1,11 +1,11 @@
 import fs from 'fs';
 import path from 'path';
 import _ from 'lodash';
-import { compile as compileJsonSchema, doValidation } from './json-schema.js';
-import { makeLogger } from './log.js';
-import { getPackageDir, getConfigDir } from './utils/paths.js';
+import { compile as compileJsonSchema, doValidation } from './json-schema';
+import { makeLogger } from './log';
+import { getPackageDir, getConfigDir } from './utils/paths';
 import type { ValidateFunction } from 'ajv';
-import type { Logger, SiteVariables } from './types.js';
+import type { Logger, SiteVariables } from './types';
 
 const log: Logger = makeLogger(__filename);
 
@@ -23,7 +23,12 @@ const renderStack: string[] = [];
 let errorStack: string[] | null = null;
 
 // JSON data files that live in the user's config directory
-const JSON_DATA_FILES: string[] = ['nav.json', 'authors.json'];
+const REQUIRED_JSON_DATA_FILES: string[] = ['nav.json'];
+const OPTIONAL_JSON_DATA_FILES: string[] = ['authors.json'];
+const JSON_DATA_FILES: string[] = [
+  ...REQUIRED_JSON_DATA_FILES,
+  ...OPTIONAL_JSON_DATA_FILES,
+];
 
 function getHtmlTemplatesDir(): string {
   return path.resolve(getPackageDir(), 'templates');
@@ -97,12 +102,16 @@ export function compileTemplates(
   for (const fileName of JSON_DATA_FILES) {
     const filePath = path.join(jsonDir, fileName);
     if (!fs.existsSync(filePath)) {
+      if (REQUIRED_JSON_DATA_FILES.includes(fileName)) {
+        throw new Error(`Missing required config file: ${filePath}`);
+      }
       continue;
     }
 
-    // Schema validation (schemas live in the package templates dir)
+    // Schema validation
+    const schemaDir = path.resolve(getPackageDir(), 'schema');
     const schemaFile = `${path.parse(fileName).name}.schema.json`;
-    const schemaPath = path.join(htmlDir, schemaFile);
+    const schemaPath = path.join(schemaDir, schemaFile);
     if (!fs.existsSync(schemaPath)) {
       throw new Error(`Missing JSON Schema for ${fileName}: ${schemaPath}`);
     }

package/build/toc-plugin.test.ts

@@ -1,6 +1,6 @@
 import { describe, expect, test } from 'bun:test';
-import { generateTocHtml, generateCodeTocHtml } from './toc-plugin.js';
-import type { JavaTocEntry } from './types.js';
+import { generateTocHtml, generateCodeTocHtml } from './toc-plugin';
+import type { JavaTocEntry } from './types';
 
 describe('generateTocHtml', () => {
   test('returns empty string for empty array', () => {

package/build/toc-plugin.ts

@@ -1,6 +1,6 @@
 import type MarkdownIt from 'markdown-it';
 import { convertMarkdown as curlyQuote } from 'quote-quote';
-import type { JavaTocEntry } from './types.js';
+import type { JavaTocEntry } from './types';
 
 interface HeadingItem {
   kind: 'heading';

package/build/types.ts

@@ -2,23 +2,28 @@
 export interface SiteVariables {
   base: string;
   basePath: string;
-  title?: string;
-  titlePostfix?: string;
+  title: string;
+  titlePostfix: string;
   symbol?: string;
   faviconSymbol?: string;
-  courseId?: string;
-  themeColor?: string;
+  themeColor: string;
   faviconColor?: string;
   faviconFontWeight?: number;
   internalDomains?: string[];
-  defaultTimeZone?: string;
-  features?: { search?: boolean; code?: boolean; favicon?: boolean };
+  defaultTimeZone: string;
+  features?: FeatureConfig;
   codeLanguages?: Record<string, string>;
   tintHue?: number;
   tintAmount?: number;
   vars?: Record<string, unknown>;
 }
 
+export type FeatureConfig = {
+  search: boolean;
+  code: boolean;
+  favicon: boolean;
+};
+
 /** A rendered content asset ready to write to dist/ */
 export interface Asset {
   assetPath: string;
@@ -69,6 +74,7 @@ export interface Logger {
 export interface RenderPlainTextOptions {
   filePath: string;
   contentDir: string;
+  distDir: string;
   siteVariables: SiteVariables;
   validInternalTargets: Set<string>;
   assetFiles: string[];
@@ -78,6 +84,7 @@ export interface RenderPlainTextOptions {
 export interface RenderCodePageOptions {
   filePath: string;
   contentDir: string;
+  distDir: string;
   siteVariables: SiteVariables;
   assetFiles: string[];
 }
@@ -86,6 +93,7 @@ export interface RenderCodePageOptions {
 export interface RenderLiterateJavaOptions {
   filePath: string;
   contentDir: string;
+  distDir: string;
   siteVariables: SiteVariables;
   assetFiles: string[];
   skipExecution?: boolean;
@@ -169,4 +177,5 @@ export interface SiteConfigInput {
   base: string;
   basePath: string;
   internalDomains: string[];
+  features: FeatureConfig;
 }

package/build/util.ts

@@ -4,9 +4,9 @@ export {
   getFilesByExtensions,
   getValidInternalTargets,
   shouldSkipContentFile,
-} from './utils/content-files.js';
-export { extensionIsMarkdown } from './utils/file-types.js';
-export { createMarkdown } from './utils/markdown.js';
+} from './utils/content-files';
+export { extensionIsMarkdown } from './utils/file-types';
+export { createMarkdown } from './utils/markdown';
 export {
   createApplyBasePath,
   getContentDir,
@@ -15,12 +15,12 @@ export {
   getProjectDir,
   getPublicDir,
   normalizeOutputPath,
-} from './utils/paths.js';
+} from './utils/paths';
 export {
   injectAssetTags,
   renderCodePageAsset,
   renderCopiedContentAsset,
   renderLiterateJavaPageAsset,
   renderPlainTextPageAsset,
-} from './utils/render.js';
-export { parseFrontMatter } from './utils/front-matter.js';
+} from './utils/render';
+export { parseFrontMatter } from './utils/front-matter';

package/build/utils/code.ts

@@ -1,11 +1,11 @@
 import MarkdownIt from 'markdown-it';
 import { parse as parseJava } from 'java-parser';
 import { JSDOM } from 'jsdom';
-import { makeLogger } from '../log.js';
-import { getHighlighter } from './shiki-highlighter.js';
-import externalLinksPlugin from '../external-links-plugin.js';
-import applyBasePathPlugin from '../apply-base-path-plugin.js';
-import type { JavaTocEntry, SiteVariables } from '../types.js';
+import { makeLogger } from '../log';
+import { getHighlighter } from './shiki-highlighter';
+import externalLinksPlugin from '../external-links-plugin';
+import applyBasePathPlugin from '../apply-base-path-plugin';
+import type { JavaTocEntry, SiteVariables } from '../types';
 
 interface CstNode {
   name?: string;

package/build/utils/content-files.ts

@@ -1,12 +1,12 @@
 import fs from 'fs';
 import path from 'path';
-import { parseFrontMatterAndContent } from './front-matter.js';
+import { parseFrontMatterAndContent } from './front-matter';
 import {
   getProcessedExtensions,
   extensionIsMarkdown,
   isLiterateJava,
-} from './file-types.js';
-import { getPublicDir, normalizeOutputPath } from './paths.js';
+} from './file-types';
+import { getPublicDir, normalizeOutputPath } from './paths';
 
 function walkFiles(dir: string): string[] {
   return fs.readdirSync(dir).flatMap(file => {

package/build/utils/derive-theme.test.ts

@@ -1,6 +1,6 @@
 import { describe, expect, test } from 'bun:test';
 import { parse, oklch } from 'culori';
-import { deriveTheme, getTextOnColor } from './derive-theme.js';
+import { deriveTheme, getTextOnColor } from './derive-theme';
 
 function getL(hex: string): number {
   return oklch(parse(hex))!.l;

package/build/utils/derive-theme.ts

@@ -1,6 +1,6 @@
 import { parse, oklch, rgb, toGamut, formatHex } from 'culori';
 import type { Oklch, Rgb } from 'culori';
-import type { DerivedTheme } from '../types.js';
+import type { DerivedTheme } from '../types';
 
 // OKLCH lightness range for the theme color used as backgrounds/outlines
 const LIGHT_THEME_L_MIN = 0.35;

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

@@ -3,7 +3,7 @@ import {
   getProcessedExtensions,
   extensionIsMarkdown,
   isLiterateJava,
-} from './file-types.js';
+} from './file-types';
 
 describe('getProcessedExtensions', () => {
   test('includes md, markdown, html, and custom extensions', () => {

package/build/utils/front-matter.test.ts

@@ -1,8 +1,5 @@
 import { describe, expect, test } from 'bun:test';
-import {
-  parseFrontMatterAndContent,
-  parseFrontMatter,
-} from './front-matter.js';
+import { parseFrontMatterAndContent, parseFrontMatter } from './front-matter';
 
 describe('parseFrontMatter', () => {
   test('parses markdown front matter separated by blank line', () => {

package/build/utils/front-matter.ts

@@ -1,6 +1,6 @@
 import fm from 'front-matter';
-import { extensionIsMarkdown } from './file-types.js';
-import type { ParsedContent } from '../types.js';
+import { extensionIsMarkdown } from './file-types';
+import type { ParsedContent } from '../types';
 
 interface RawParsedFrontMatter {
   frontMatter: string | null;

package/build/utils/jdi-runner/LiterateRunner.java

@@ -95,6 +95,18 @@ public class LiterateRunner {
         stderrThread.setDaemon(true);
         stderrThread.start();
 
+        // Forward stdin to target VM in a background thread
+        OutputStream targetStdin = process.getOutputStream();
+        Thread stdinThread = new Thread(() -> {
+            try {
+                System.in.transferTo(targetStdin);
+                targetStdin.close();
+            } catch (IOException ignored) {
+            }
+        });
+        stdinThread.setDaemon(true);
+        stdinThread.start();
+
         int activeBlock = -1;
 
         try {
@@ -199,6 +211,7 @@ public class LiterateRunner {
             } catch (VMDisconnectedException ignored) {
             }
             stderrThread.join(1000);
+            stdinThread.join(1000);
         }
 
         // Output JSON to our own stdout

package/build/utils/literate-java.ts

@@ -1,16 +1,16 @@
 import fs from 'fs';
 import os from 'os';
 import path from 'path';
-import { execSync } from 'child_process';
-import { createMarkdown } from './markdown.js';
-import { makeLogger } from '../log.js';
-import { parseFrontMatterAndContent } from './front-matter.js';
+import { execFileSync } from 'child_process';
+import { createMarkdown } from './markdown';
+import { makeLogger } from '../log';
+import { parseFrontMatterAndContent } from './front-matter';
 import type {
   SiteVariables,
   LiterateJavaParseResult,
   LiterateCodeBlock,
   LiterateRunnerEntry,
-} from '../types.js';
+} from '../types';
 
 const log = makeLogger(__filename);
 
@@ -39,6 +39,12 @@ export function parseLiterateJava(
       continue;
     }
 
+    // Skip fences with a non-Java language tag (e.g., ```text)
+    const lang = token.info.trim();
+    if (token.type === 'fence' && lang !== '' && lang !== 'java') {
+      continue;
+    }
+
     const code = token.content;
     const codeLines = code.endsWith('\n')
       ? code.slice(0, -1).split('\n')
@@ -88,7 +94,7 @@ export function compileJavaSource(
   log.debug`Compiling ${className}.java (${javaSource.split('\n').length} lines) in ${tempDir}`;
 
   try {
-    execSync(`javac "${className}.java"`, {
+    execFileSync('javac', [`${className}.java`], {
       cwd: tempDir,
       timeout: 30000,
       stdio: ['pipe', 'pipe', 'pipe'],
@@ -120,7 +126,7 @@ function ensureRunnerCompiled(runnerDir: string): void {
   log.debug`Compiling LiterateRunner.java`;
 
   try {
-    execSync('javac LiterateRunner.java', {
+    execFileSync('javac', ['LiterateRunner.java'], {
       cwd: runnerDir,
       timeout: 30000,
       stdio: ['pipe', 'pipe', 'pipe'],
@@ -138,6 +144,7 @@ export function executeLiterateJava(
   className: string,
   classPath: string,
   codeBlocks: LiterateCodeBlock[],
+  stdin?: string,
 ): LiterateRunnerEntry[] {
   const runnerDir = path.join(__dirname, 'jdi-runner');
   ensureRunnerCompiled(runnerDir);
@@ -150,11 +157,16 @@ export function executeLiterateJava(
   log.debug`Running LiterateRunner with ${blockRanges.length} block range(s)`;
 
   try {
-    const result = execSync(
-      `java -cp "${runnerDir}" LiterateRunner "${className}" "${classPath}" '${rangesJson}'`,
-      { timeout: 30000, encoding: 'utf-8' },
+    const result = execFileSync(
+      'java',
+      ['-cp', runnerDir, 'LiterateRunner', className, classPath, rangesJson],
+      { timeout: 30000, encoding: 'utf-8', input: stdin },
     );
-    const entries: LiterateRunnerEntry[] = JSON.parse(result);
+    const raw: [number, string][] = JSON.parse(result);
+    const entries: LiterateRunnerEntry[] = raw.map(([blockIndex, output]) => ({
+      blockIndex,
+      output,
+    }));
     log.debug`LiterateRunner returned ${entries.length} output entries`;
     return entries;
   } catch (err: unknown) {
@@ -174,7 +186,7 @@ export function executeLiterateJava(
 
 export function checkJavac(): boolean {
   try {
-    execSync('javac -version', { stdio: ['pipe', 'pipe', 'pipe'] });
+    execFileSync('javac', ['-version'], { stdio: ['pipe', 'pipe', 'pipe'] });
     return true;
   } catch {
     return false;

package/build/utils/markdown.ts

@@ -7,15 +7,18 @@ import markdownItAnchor from 'markdown-it-anchor';
 import markdownItFootnote from 'markdown-it-footnote';
 import markdownItDeflist from 'markdown-it-deflist';
 import markdownItContainer from 'markdown-it-container';
-import textToId from '../text-to-id.js';
-import { getHighlighter } from './shiki-highlighter.js';
-import headingSubtitlePlugin from '../heading-subtitle-plugin.js';
-import deflistIdPlugin from '../deflist-id-plugin.js';
-import externalLinksPlugin from '../external-links-plugin.js';
-import validateInternalLinksPlugin from '../validate-internal-links-plugin.js';
-import applyBasePathPlugin from '../apply-base-path-plugin.js';
-import { tocPlugin } from '../toc-plugin.js';
-import type { SiteVariables } from '../types.js';
+import textToId from '../text-to-id';
+import { getHighlighter } from './shiki-highlighter';
+import headingSubtitlePlugin from '../heading-subtitle-plugin';
+import deflistIdPlugin from '../deflist-id-plugin';
+import externalLinksPlugin from '../external-links-plugin';
+import validateInternalLinksPlugin from '../validate-internal-links-plugin';
+import applyBasePathPlugin from '../apply-base-path-plugin';
+import { tocPlugin } from '../toc-plugin';
+import markdownItKatex from '@vscode/markdown-it-katex';
+import katex from 'katex';
+import renderA11yString from 'katex/contrib/render-a11y-string';
+import type { SiteVariables } from '../types';
 
 interface CreateMarkdownOptions {
   validatorOptions?: Record<string, unknown>;
@@ -44,6 +47,7 @@ export function createMarkdown(
     .use(validateInternalLinksPlugin, validatorOptions)
     .use(applyBasePathPlugin, siteVariables)
     .use(tocPlugin)
+    .use(markdownItKatex)
     .use(markdownItContainer, 'details', {
       marker: '<',
       validate: function (params: string) {
@@ -78,6 +82,34 @@ export function createMarkdown(
       },
     });
 
+  // The @vscode/markdown-it-katex plugin's renderers swallow errors thrown
+  // by katex.renderToString() and return error HTML instead of propagating
+  // the exception. Override the renderers so parse errors fail the build.
+  // The plugin's tokenizer ($ and $$ delimiter parsing) is kept.
+  // Each renderer also adds an aria-label with a screen-reader-friendly
+  // description generated by katex/contrib/render-a11y-string.
+  markdown.renderer.rules.math_inline = (tokens: Token[], idx: number) => {
+    const latex = tokens[idx].content;
+    const html = katex.renderToString(latex, { throwOnError: true });
+    const a11y = markdown.utils.escapeHtml(renderA11yString(latex));
+    return html.replace(
+      '<span class="katex">',
+      `<span class="katex" aria-label="${a11y}">`,
+    );
+  };
+  const katexBlockRenderer = (tokens: Token[], idx: number) => {
+    const latex = tokens[idx].content;
+    const html = katex.renderToString(latex, {
+      throwOnError: true,
+      displayMode: true,
+    });
+    const a11y = markdown.utils.escapeHtml(renderA11yString(latex));
+    return `<p class="katex-block" aria-label="${a11y}">` + html + `</p>\n`;
+  };
+  markdown.renderer.rules.math_block = katexBlockRenderer;
+  markdown.renderer.rules.math_inline_block = katexBlockRenderer;
+  markdown.renderer.rules.math_inline_bare_block = katexBlockRenderer;
+
   const usedIds = new Map<string, number>();
   markdown.use(markdownItContainer, 'alert', {
     marker: '!',

package/build/utils/paths.test.ts

@@ -9,8 +9,8 @@ import {
   getConfigDir,
   createApplyBasePath,
   normalizeOutputPath,
-} from './paths.js';
-import type { SiteVariables } from '../types.js';
+} from './paths';
+import type { SiteVariables } from '../types';
 
 describe('getPackageDir', () => {
   test('returns an absolute path', () => {

package/build/utils/paths.ts

@@ -1,5 +1,5 @@
 import path from 'path';
-import type { SiteVariables } from '../types.js';
+import type { SiteVariables } from '../types';
 
 export function getPackageDir(): string {
   return path.resolve(__dirname, '..', '..');
@@ -17,6 +17,10 @@ export function getDistDir(): string {
   return path.resolve(getProjectDir(), 'dist');
 }
 
+export function getProdDistDir(): string {
+  return path.resolve(getProjectDir(), 'dist-prod');
+}
+
 export function getPublicDir(): string {
   return path.resolve(getProjectDir(), 'public');
 }