@abreen/tada 1.0.2 → 1.1.0

package/build/utils/paths.test.ts

@@ -0,0 +1,91 @@
+import { describe, expect, test } from 'bun:test';
+import path from 'path';
+import {
+  getPackageDir,
+  getProjectDir,
+  getContentDir,
+  getDistDir,
+  getPublicDir,
+  getConfigDir,
+  createApplyBasePath,
+  normalizeOutputPath,
+} from './paths.js';
+import type { SiteVariables } from '../types.js';
+
+describe('getPackageDir', () => {
+  test('returns an absolute path', () => {
+    expect(path.isAbsolute(getPackageDir())).toBe(true);
+  });
+
+  test('points to repo root (contains package.json)', () => {
+    const dir = getPackageDir();
+    const pkg = path.join(dir, 'package.json');
+    expect(Bun.file(pkg).size).toBeGreaterThan(0);
+  });
+});
+
+describe('getProjectDir', () => {
+  test('returns process.cwd()', () => {
+    expect(getProjectDir()).toBe(process.cwd());
+  });
+});
+
+describe('directory getters', () => {
+  test('getContentDir ends with /content', () => {
+    expect(getContentDir()).toEndWith('/content');
+  });
+
+  test('getDistDir ends with /dist', () => {
+    expect(getDistDir()).toEndWith('/dist');
+  });
+
+  test('getPublicDir ends with /public', () => {
+    expect(getPublicDir()).toEndWith('/public');
+  });
+
+  test('getConfigDir equals getProjectDir', () => {
+    expect(getConfigDir()).toBe(getProjectDir());
+  });
+});
+
+describe('createApplyBasePath', () => {
+  function apply(basePath: string, subPath: string): string {
+    const site = { base: '', basePath } as SiteVariables;
+    return createApplyBasePath(site)(subPath);
+  }
+
+  test('prepends basePath to subPath', () => {
+    expect(apply('/course', '/page.html')).toBe('/course/page.html');
+  });
+
+  test('handles basePath with trailing slash', () => {
+    expect(apply('/course/', '/page.html')).toBe('/course/page.html');
+  });
+
+  test('handles root basePath', () => {
+    expect(apply('/', '/page.html')).toBe('/page.html');
+  });
+
+  test('throws for subPath without leading slash', () => {
+    expect(() => apply('/course', 'page.html')).toThrow('must start with "/"');
+  });
+});
+
+describe('normalizeOutputPath', () => {
+  test('adds leading slash if missing', () => {
+    expect(normalizeOutputPath('page.html')).toBe('/page.html');
+  });
+
+  test('preserves leading slash', () => {
+    expect(normalizeOutputPath('/page.html')).toBe('/page.html');
+  });
+
+  test('normalizes dot-segments', () => {
+    expect(normalizeOutputPath('/a/../b/page.html')).toBe('/b/page.html');
+  });
+
+  test('returns / for empty or dot path', () => {
+    expect(normalizeOutputPath('')).toBe('/');
+    expect(normalizeOutputPath('.')).toBe('/');
+  });
+});

package/{webpack/utils/paths.js → build/utils/paths.ts}

@@ -1,31 +1,34 @@
-const path = require('path');
+import path from 'path';
+import type { SiteVariables } from '../types.js';
 
-function getPackageDir() {
+export function getPackageDir(): string {
   return path.resolve(__dirname, '..', '..');
 }
 
-function getProjectDir() {
+export function getProjectDir(): string {
   return process.cwd();
 }
 
-function getContentDir() {
+export function getContentDir(): string {
   return path.resolve(getProjectDir(), 'content');
 }
 
-function getDistDir() {
+export function getDistDir(): string {
   return path.resolve(getProjectDir(), 'dist');
 }
 
-function getPublicDir() {
+export function getPublicDir(): string {
   return path.resolve(getProjectDir(), 'public');
 }
 
-function getConfigDir() {
-  return path.resolve(getProjectDir(), 'config');
+export function getConfigDir(): string {
+  return getProjectDir();
 }
 
-function createApplyBasePath(siteVariables) {
-  return function applyBasePath(subPath) {
+export function createApplyBasePath(
+  siteVariables: SiteVariables,
+): (subPath: string) => string {
+  return function applyBasePath(subPath: string): string {
     if (!subPath.startsWith('/')) {
       throw new Error('invalid internal path, must start with "/": ' + subPath);
     }
@@ -38,21 +41,10 @@ function createApplyBasePath(siteVariables) {
   };
 }
 
-function normalizeOutputPath(outputPath) {
+export function normalizeOutputPath(outputPath: string): string {
   const normalized = path.posix.normalize(outputPath);
   if (normalized === '.' || normalized === '') {
     return '/';
   }
   return normalized.startsWith('/') ? normalized : `/${normalized}`;
 }
-
-module.exports = {
-  createApplyBasePath,
-  getConfigDir,
-  getContentDir,
-  getDistDir,
-  getPackageDir,
-  getProjectDir,
-  getPublicDir,
-  normalizeOutputPath,
-};

package/{webpack/utils/render.js → build/utils/render.ts}

@@ -1,39 +1,69 @@
-const fs = require('fs');
-const path = require('path');
-const _ = require('lodash');
-const { stripHtml } = require('string-strip-html');
-const { makeLogger } = require('../log');
-const { B } = require('../colors');
-const createGlobals = require('../globals');
-const { render, json } = require('../templates');
-const {
+import fs from 'fs';
+import path from 'path';
+import _ from 'lodash';
+import { stripHtml } from 'string-strip-html';
+import { makeLogger } from '../log.js';
+import { B } from '../colors.js';
+import createGlobals from '../globals.js';
+import { render, json } from '../templates.js';
+import {
   extractJavaMethodToc,
   renderCodeSegment,
   renderCodeWithComments,
-} = require('./code');
-const { extensionIsMarkdown } = require('./file-types');
-const { createApplyBasePath, normalizeOutputPath } = require('./paths');
-const { parseFrontMatterAndContent } = require('./front-matter');
-const { createMarkdown } = require('./markdown');
-const { generateTocHtml, generateCodeTocHtml } = require('../toc-plugin');
-const {
+} from './code.js';
+import { extensionIsMarkdown } from './file-types.js';
+import {
+  createApplyBasePath,
+  normalizeOutputPath,
+  getDistDir,
+} from './paths.js';
+import { parseFrontMatterAndContent } from './front-matter.js';
+import { createMarkdown } from './markdown.js';
+import { generateTocHtml, generateCodeTocHtml } from '../toc-plugin.js';
+import {
   parseLiterateJava,
   hasMainMethod,
   deriveClassName,
   compileJavaSource,
   executeLiterateJava,
-} = require('./literate-java');
+} from './literate-java.js';
+import type {
+  Asset,
+  SiteVariables,
+  RenderPlainTextOptions,
+  RenderCodePageOptions,
+  RenderLiterateJavaOptions,
+  RenderCopiedContentOptions,
+} from '../types.js';
 
 const log = makeLogger(__filename);
 
 const REQUIRED_FRONT_MATTER_FIELDS = ['title'];
 
-function resolveAuthor(pageVariables, filePath) {
+interface TemplateParametersInput {
+  pageVariables: Record<string, unknown>;
+  siteVariables: SiteVariables;
+  content: string | null;
+  applyBasePath: (subPath: string) => string;
+  subPath: string;
+}
+
+function resolveAuthor(
+  pageVariables: Record<string, unknown>,
+  filePath: string,
+): void {
   if (!pageVariables.author) {
     return;
   }
-  const authors = json('authors.json');
-  const authorKey = pageVariables.author;
+  const authors = json('authors.json') as
+    | Record<string, Record<string, unknown>>
+    | undefined;
+  if (!authors) {
+    throw new Error(
+      `${filePath}: author "${pageVariables.author}" specified but no authors.json found`,
+    );
+  }
+  const authorKey = pageVariables.author as string;
   const authorEntry = authors[authorKey];
   if (!authorEntry) {
     throw new Error(
@@ -43,15 +73,20 @@ function resolveAuthor(pageVariables, filePath) {
   pageVariables.author = authorEntry;
 }
 
-function validateFrontMatter(pageVariables, filePath) {
-  let valid = true;
-  for (const field of REQUIRED_FRONT_MATTER_FIELDS) {
-    if (!pageVariables[field]) {
-      log.error`${filePath}: missing required front matter field: "${field}"`;
-      valid = false;
-    }
+function validateFrontMatter(
+  pageVariables: Record<string, unknown>,
+  filePath: string,
+): void {
+  const missing = REQUIRED_FRONT_MATTER_FIELDS.filter(
+    field => !pageVariables[field],
+  );
+  if (missing.length > 0) {
+    const noun = missing.length === 1 ? 'field' : 'fields';
+    const fields = missing.map(f => `"${f}"`).join(', ');
+    throw new Error(
+      `${filePath}: missing required front matter ${noun}: ${fields}`,
+    );
   }
-  return valid;
 }
 
 function createTemplateParameters({
@@ -60,7 +95,7 @@ function createTemplateParameters({
   content,
   applyBasePath,
   subPath,
-}) {
+}: TemplateParametersInput): Record<string, unknown> {
   return {
     ...(siteVariables.vars || {}),
     ...createGlobals(pageVariables, siteVariables, subPath),
@@ -73,43 +108,54 @@ function createTemplateParameters({
   };
 }
 
-function injectWebpackAssets(html, compilation, applyBasePath) {
-  const assets = compilation.getAssets();
-  const jsAssets = assets
-    .filter(asset => asset.name.endsWith('.js'))
-    .map(asset => asset.name);
-  const cssAssets = assets
-    .filter(asset => asset.name.endsWith('.css'))
-    .map(asset => asset.name);
+export function injectAssetTags(
+  html: string,
+  assetFiles: string[],
+  applyBasePath: (subPath: string) => string,
+): string {
+  const jsAssets = assetFiles.filter(f => f.endsWith('.js'));
+  const cssAssets = assetFiles.filter(f => f.endsWith('.css'));
 
   const scriptTags = jsAssets
     .map(asset => `<script defer src="${applyBasePath('/' + asset)}"></script>`)
     .join('');
-  const linkTags = cssAssets
+  const criticalAssets = cssAssets.filter(f => f.includes('critical.bundle.'));
+  const asyncAssets = cssAssets.filter(f => !f.includes('critical.bundle.'));
+
+  const distDir = getDistDir();
+  const criticalTags = criticalAssets
+    .map(asset => {
+      const css = fs.readFileSync(path.join(distDir, asset), 'utf-8');
+      return `<style>${css}</style>`;
+    })
+    .join('');
+  const asyncLinkTags = asyncAssets
     .map(
-      asset => `<link href="${applyBasePath('/' + asset)}" rel="stylesheet">`,
+      asset =>
+        `<link href="${applyBasePath('/' + asset)}" rel="stylesheet" media="print" onload="this.media='all'">` +
+        `<noscript><link href="${applyBasePath('/' + asset)}" rel="stylesheet"></noscript>`,
     )
     .join('');
 
   return html
-    .replace('<head>', `<head>${linkTags}`)
+    .replace('<head>', `<head>${criticalTags}${asyncLinkTags}`)
     .replace('</head>', `${scriptTags}</head>`);
 }
 
-function toContentAssetPath(contentDir, filePath) {
+function toContentAssetPath(contentDir: string, filePath: string): string {
   return path
     .relative(contentDir, filePath)
     .split(path.sep)
     .join(path.posix.sep);
 }
 
-function renderPlainTextPageAsset({
+export function renderPlainTextPageAsset({
   filePath,
   contentDir,
   siteVariables,
   validInternalTargets,
-  compilation,
-}) {
+  assetFiles,
+}: RenderPlainTextOptions): Asset[] {
   const { dir, name, ext } = path.parse(filePath);
   const subPath = path.relative(contentDir, path.join(dir, name));
   const applyBasePath = createApplyBasePath(siteVariables);
@@ -124,16 +170,16 @@ function renderPlainTextPageAsset({
     { validateInternalLinks: extensionIsMarkdown(ext.toLowerCase()) },
   );
 
-  if (!validateFrontMatter(pageVariables, filePath)) {
-    return [];
-  }
+  validateFrontMatter(pageVariables, filePath);
 
   if (!pageVariables.template) {
     pageVariables.template = 'default';
   }
 
   if (pageVariables.toc && tocItems) {
-    pageVariables.tocHtml = generateTocHtml(tocItems);
+    pageVariables.tocHtml = generateTocHtml(
+      tocItems as Parameters<typeof generateTocHtml>[0],
+    );
   }
 
   const templateParameters = createTemplateParameters({
@@ -144,9 +190,9 @@ function renderPlainTextPageAsset({
     subPath,
   });
 
-  const html = injectWebpackAssets(
-    render(`${pageVariables.template}.html`, templateParameters),
-    compilation,
+  const html = injectAssetTags(
+    render(`${pageVariables.template}.html`, templateParameters) as string,
+    assetFiles,
     applyBasePath,
   );
 
@@ -158,16 +204,16 @@ function renderPlainTextPageAsset({
   ];
 }
 
-function renderCodePageAsset({
+export function renderCodePageAsset({
   filePath,
   contentDir,
   siteVariables,
-  compilation,
-}) {
+  assetFiles,
+}: RenderCodePageOptions): Asset[] {
   const { dir, name, ext } = path.parse(filePath);
   const subPath = path.relative(contentDir, path.join(dir, name));
   const applyBasePath = createApplyBasePath(siteVariables);
-  const lang = siteVariables.codeLanguages[ext.slice(1).toLowerCase()];
+  const lang = siteVariables.codeLanguages![ext.slice(1).toLowerCase()];
   const sourceCode = fs.readFileSync(filePath, 'utf-8');
 
   log.info`Rendering code page ${B`${subPath + ext}`}`;
@@ -178,7 +224,7 @@ function renderCodePageAsset({
   const titleHtml = `<tt>${name + ext}</tt>`;
   const tocItems = lang === 'java' ? extractJavaMethodToc(sourceCode) : [];
   const tocHtml = generateCodeTocHtml(tocItems);
-  const pageVariables = {
+  const pageVariables: Record<string, unknown> = {
     template: 'code',
     filePath,
     title: `${name}${ext}`,
@@ -197,9 +243,9 @@ function renderCodePageAsset({
     subPath,
   });
 
-  const html = injectWebpackAssets(
-    render('code.html', templateParameters),
-    compilation,
+  const html = injectAssetTags(
+    render('code.html', templateParameters) as string,
+    assetFiles,
     applyBasePath,
   );
 
@@ -211,9 +257,11 @@ function renderCodePageAsset({
   ];
 }
 
-function renderCopiedContentAsset({ filePath, contentDir }) {
-  const ext = path.extname(filePath).toLowerCase();
-  const label = ext === '.pdf' ? 'Copying' : 'Copying source file';
+export function renderCopiedContentAsset({
+  filePath,
+  contentDir,
+}: RenderCopiedContentOptions): Asset[] {
+  const label = 'Copying source file';
   const relPath = toContentAssetPath(contentDir, filePath);
 
   log.info`${label} ${B`${relPath}`}`;
@@ -222,13 +270,17 @@ function renderCopiedContentAsset({ filePath, contentDir }) {
 
 /** Parses the file, renders using template, returns HTML & params used to generate page */
 function renderPlainTextContent(
-  filePath,
-  subPath,
-  siteVariables,
-  applyBasePath,
-  validInternalTargets,
+  filePath: string,
+  subPath: string,
+  siteVariables: SiteVariables,
+  applyBasePath: (subPath: string) => string,
+  validInternalTargets: Set<string>,
   { validateInternalLinks = true } = {},
-) {
+): {
+  content: string | null;
+  pageVariables: Record<string, unknown>;
+  tocItems: unknown[] | null;
+} {
   const sourceUrlPath = `/${subPath}.html`;
   const md = createMarkdown(siteVariables, {
     validatorOptions: {
@@ -239,7 +291,7 @@ function renderPlainTextContent(
       codeExtensions:
         siteVariables.features?.code === false
           ? []
-          : Object.keys(siteVariables.codeLanguages),
+          : Object.keys(siteVariables.codeLanguages!),
     },
   });
 
@@ -256,25 +308,32 @@ function renderPlainTextContent(
     applyBasePath,
     subPath,
   });
-  const pageVariablesProcessed = Object.entries(pageVariables)
+  const pageVariablesProcessed: Record<string, unknown> = Object.entries(
+    pageVariables,
+  )
     .map(([k, v]) => {
       const newValue =
         typeof v === 'string' ? _.template(v)(siteOnlyParams) : v;
-      return [k, newValue];
+      return [k, newValue] as [string, unknown];
     })
-    .reduce((acc, [k, v]) => {
-      acc[k] = v;
-      return acc;
-    }, {});
+    .reduce(
+      (acc, [k, v]) => {
+        acc[k] = v;
+        return acc;
+      },
+      {} as Record<string, unknown>,
+    );
 
   // Render title and description as inline Markdown
   if (pageVariablesProcessed.title) {
-    const titleHtml = md.renderInline(pageVariablesProcessed.title);
+    const titleHtml = md.renderInline(pageVariablesProcessed.title as string);
     pageVariablesProcessed.titleHtml = titleHtml;
     pageVariablesProcessed.title = stripHtml(titleHtml).result;
   }
   if (pageVariablesProcessed.description) {
-    const descriptionHtml = md.renderInline(pageVariablesProcessed.description);
+    const descriptionHtml = md.renderInline(
+      pageVariablesProcessed.description as string,
+    );
     pageVariablesProcessed.descriptionHtml = descriptionHtml;
     pageVariablesProcessed.description = stripHtml(descriptionHtml).result;
   }
@@ -291,35 +350,41 @@ function renderPlainTextContent(
     subPath,
   });
 
-  let html = null;
+  let html: string;
   try {
     html = _.template(strippedContent)(params);
-  } catch (err) {
+  } catch (err: unknown) {
     throw new Error(
-      `${filePath}: Lodash template error in page or template: ${err.message}`,
+      `${filePath}: Lodash template error in page or template: ${(err as Error).message}`,
+      { cause: err },
     );
   }
 
-  let tocItems = null;
+  let tocItems: unknown[] | null = null;
   if (extensionIsMarkdown(ext)) {
-    const env = {};
-    html = md.render(html, env);
-    tocItems = env.tocItems || null;
+    const env: Record<string, unknown> = {};
+    html = md.render(html!, env);
+    tocItems = (env.tocItems as unknown[] | undefined) || null;
   }
 
-  return { content: html, pageVariables: params.page, tocItems };
+  return {
+    content: html,
+    pageVariables: params.page as Record<string, unknown>,
+    tocItems,
+  };
 }
 
-function stripHtmlComments(str) {
+export function stripHtmlComments(str: string): string {
   return str.replace(/<!---[\s\S]*?-->/g, '');
 }
 
-function renderLiterateJavaPageAsset({
+export function renderLiterateJavaPageAsset({
   filePath,
   contentDir,
   siteVariables,
-  compilation,
-}) {
+  assetFiles,
+  skipExecution,
+}: RenderLiterateJavaOptions): Asset[] {
   const { dir, name } = path.parse(filePath);
   const className = deriveClassName(filePath);
   const subPath = path.relative(contentDir, path.join(dir, className));
@@ -336,24 +401,30 @@ function renderLiterateJavaPageAsset({
     visibleBlockIndices,
   } = parseLiterateJava(raw, siteVariables);
 
-  if (!validateFrontMatter(pageVariables, filePath)) {
-    return [];
-  }
-
-  // Compile the concatenated Java source
-  let tempDir;
-  let blockOutputMap = null;
-  try {
-    tempDir = compileJavaSource(javaSource, className);
-
-    // Execute if there is a main() method
-    if (hasMainMethod(javaSource)) {
-      const outputEntries = executeLiterateJava(className, tempDir, codeBlocks);
-      blockOutputMap = new Map(outputEntries);
-    }
-  } finally {
-    if (tempDir) {
-      fs.rmSync(tempDir, { recursive: true, force: true });
+  validateFrontMatter(pageVariables, filePath);
+
+  // Compile and execute the concatenated Java source
+  let tempDir: string | undefined;
+  let blockOutputMap: Map<number, string> | null = null;
+  if (!skipExecution) {
+    try {
+      tempDir = compileJavaSource(javaSource, className);
+
+      // Execute if there is a main() method
+      if (hasMainMethod(javaSource)) {
+        const outputEntries = executeLiterateJava(
+          className,
+          tempDir,
+          codeBlocks,
+        );
+        blockOutputMap = new Map(
+          outputEntries.map(e => [e.blockIndex, e.output]),
+        );
+      }
+    } finally {
+      if (tempDir) {
+        fs.rmSync(tempDir, { recursive: true, force: true });
+      }
     }
   }
 
@@ -376,7 +447,7 @@ function renderLiterateJavaPageAsset({
       if (line.trim().length === 0) {
         return min;
       }
-      const indent = line.match(/^(\s*)/)[1].length;
+      const indent = line.match(/^(\s*)/)![1].length;
       return Math.min(min, indent);
     }, Infinity);
     const dedented =
@@ -404,8 +475,8 @@ function renderLiterateJavaPageAsset({
     return codeHtml;
   };
 
-  const env = {};
-  const contentHtml = md.render(content, env);
+  const env: Record<string, unknown> = {};
+  const contentHtml = md.render(stripHtmlComments(content), env);
 
   // Build page variables
   const javaFileName = `${className}.java`;
@@ -415,7 +486,7 @@ function renderLiterateJavaPageAsset({
     ),
   );
 
-  const titleHtml = md.renderInline(pageVariables.title);
+  const titleHtml = md.renderInline(pageVariables.title as string);
   pageVariables.titleHtml = titleHtml;
   pageVariables.title = stripHtml(titleHtml).result;
   pageVariables.template = 'literate';
@@ -423,7 +494,9 @@ function renderLiterateJavaPageAsset({
   pageVariables.downloadName = javaFileName;
 
   if (pageVariables.toc && env.tocItems) {
-    pageVariables.tocHtml = generateTocHtml(env.tocItems);
+    pageVariables.tocHtml = generateTocHtml(
+      env.tocItems as Parameters<typeof generateTocHtml>[0],
+    );
   }
 
   resolveAuthor(pageVariables, filePath);
@@ -436,9 +509,9 @@ function renderLiterateJavaPageAsset({
     subPath,
   });
 
-  const html = injectWebpackAssets(
-    render('literate.html', templateParameters),
-    compilation,
+  const html = injectAssetTags(
+    render('literate.html', templateParameters) as string,
+    assetFiles,
     applyBasePath,
   );
 
@@ -456,11 +529,3 @@ function renderLiterateJavaPageAsset({
     },
   ];
 }
-
-module.exports = {
-  injectWebpackAssets,
-  renderCodePageAsset,
-  renderCopiedContentAsset,
-  renderLiterateJavaPageAsset,
-  renderPlainTextPageAsset,
-};