@abreen/tada 1.0.2 → 1.2.0

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

@@ -1,39 +1,66 @@
-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 { isFeatureEnabled } from '../features';
+import { makeLogger } from '../log';
+import { B } from '../colors';
+import createGlobals from '../globals';
+import { render, json } from '../templates';
+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';
+import { extensionIsMarkdown } from './file-types';
+import { createApplyBasePath, normalizeOutputPath } from './paths';
+import { parseFrontMatterAndContent } from './front-matter';
+import { createMarkdown } from './markdown';
+import { generateTocHtml, generateCodeTocHtml } from '../toc-plugin';
+import {
   parseLiterateJava,
   hasMainMethod,
   deriveClassName,
   compileJavaSource,
   executeLiterateJava,
-} = require('./literate-java');
+} from './literate-java';
+import type {
+  Asset,
+  SiteVariables,
+  RenderPlainTextOptions,
+  RenderCodePageOptions,
+  RenderLiterateJavaOptions,
+  RenderCopiedContentOptions,
+} from '../types';
 
 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 +70,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 +92,7 @@ function createTemplateParameters({
   content,
   applyBasePath,
   subPath,
-}) {
+}: TemplateParametersInput): Record<string, unknown> {
   return {
     ...(siteVariables.vars || {}),
     ...createGlobals(pageVariables, siteVariables, subPath),
@@ -73,43 +105,65 @@ 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,
+  distDir: 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 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) {
+export function injectKatexStylesheet(
+  html: string,
+  applyBasePath: (subPath: string) => string,
+): string {
+  const href = applyBasePath('/katex/katex.min.css');
+  const tag =
+    `<link href="${href}" rel="stylesheet" media="print" onload="this.media='all'">` +
+    `<noscript><link href="${href}" rel="stylesheet"></noscript>`;
+  return html.replace('<head>', `<head>${tag}`);
+}
+
+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,
+  distDir,
   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 +178,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,11 +198,14 @@ function renderPlainTextPageAsset({
     subPath,
   });
 
-  const html = injectWebpackAssets(
-    render(`${pageVariables.template}.html`, templateParameters),
-    compilation,
-    applyBasePath,
-  );
+  const templateHtml = render(
+    `${pageVariables.template}.html`,
+    templateParameters,
+  ) as string;
+  let html = injectAssetTags(templateHtml, assetFiles, applyBasePath, distDir);
+  if (templateHtml.includes('class="katex"')) {
+    html = injectKatexStylesheet(html, applyBasePath);
+  }
 
   return [
     {
@@ -158,16 +215,17 @@ function renderPlainTextPageAsset({
   ];
 }
 
-function renderCodePageAsset({
+export function renderCodePageAsset({
   filePath,
   contentDir,
+  distDir,
   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 +236,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,10 +255,11 @@ function renderCodePageAsset({
     subPath,
   });
 
-  const html = injectWebpackAssets(
-    render('code.html', templateParameters),
-    compilation,
+  const html = injectAssetTags(
+    render('code.html', templateParameters) as string,
+    assetFiles,
     applyBasePath,
+    distDir,
   );
 
   return [
@@ -211,9 +270,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 +283,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: {
@@ -236,10 +301,9 @@ function renderPlainTextContent(
       filePath,
       sourceUrlPath,
       validTargets: validInternalTargets,
-      codeExtensions:
-        siteVariables.features?.code === false
-          ? []
-          : Object.keys(siteVariables.codeLanguages),
+      codeExtensions: isFeatureEnabled(siteVariables, 'code')
+        ? Object.keys(siteVariables.codeLanguages!)
+        : [],
     },
   });
 
@@ -256,25 +320,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 +362,42 @@ 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,
+  distDir,
   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 +414,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 +460,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 +488,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 +499,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 +507,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,11 +522,11 @@ function renderLiterateJavaPageAsset({
     subPath,
   });
 
-  const html = injectWebpackAssets(
-    render('literate.html', templateParameters),
-    compilation,
-    applyBasePath,
-  );
+  const templateHtml = render('literate.html', templateParameters) as string;
+  let html = injectAssetTags(templateHtml, assetFiles, applyBasePath, distDir);
+  if (templateHtml.includes('class="katex"')) {
+    html = injectKatexStylesheet(html, applyBasePath);
+  }
 
   return [
     {
@@ -456,11 +542,3 @@ function renderLiterateJavaPageAsset({
     },
   ];
 }
-
-module.exports = {
-  injectWebpackAssets,
-  renderCodePageAsset,
-  renderCopiedContentAsset,
-  renderLiterateJavaPageAsset,
-  renderPlainTextPageAsset,
-};

package/build/utils/shiki-highlighter.ts

@@ -0,0 +1,29 @@
+import type { HighlighterGeneric, BundledLanguage, BundledTheme } from 'shiki';
+import { makeLogger } from '../log';
+
+const log = makeLogger(__filename);
+
+let highlighter: HighlighterGeneric<BundledLanguage, BundledTheme> | null =
+  null;
+
+export async function initHighlighter(langs: string[]): Promise<void> {
+  if (highlighter) {
+    return;
+  }
+  log.debug`Initializing syntax highlighter`;
+  const { createHighlighter } = await import('shiki');
+  highlighter = await createHighlighter({
+    themes: ['github-light', 'github-dark'],
+    langs,
+  });
+}
+
+export function getHighlighter(): HighlighterGeneric<
+  BundledLanguage,
+  BundledTheme
+> {
+  if (!highlighter) {
+    throw new Error('Shiki highlighter not initialized');
+  }
+  return highlighter;
+}

package/build/validate-internal-links-plugin.test.ts

@@ -0,0 +1,106 @@
+import { describe, expect, test } from 'bun:test';
+import MarkdownIt from 'markdown-it';
+import validateInternalLinks from './validate-internal-links-plugin';
+
+function createMd(
+  validTargets: string[],
+  options: { sourceUrlPath?: string; codeExtensions?: string[] } = {},
+) {
+  const md = new MarkdownIt({ html: true });
+  md.use(validateInternalLinks, {
+    enabled: true,
+    filePath: 'test.md',
+    sourceUrlPath: options.sourceUrlPath ?? '/test.html',
+    validTargets: new Set(validTargets),
+    codeExtensions: options.codeExtensions ?? [],
+  });
+  return md;
+}
+
+describe('validateInternalLinks', () => {
+  test('does nothing when disabled', () => {
+    const md = new MarkdownIt();
+    md.use(validateInternalLinks, { enabled: false });
+    expect(() => md.render('[link](/missing.html)')).not.toThrow();
+  });
+
+  test('throws when required options are missing', () => {
+    const md = new MarkdownIt();
+    expect(() => {
+      md.use(validateInternalLinks, { enabled: true });
+      md.render('test');
+    }).toThrow('requires filePath');
+  });
+
+  test('allows valid internal links', () => {
+    const md = createMd(['/about.html']);
+    expect(() => md.render('[About](/about.html)')).not.toThrow();
+  });
+
+  test('allows external links', () => {
+    const md = createMd([]);
+    expect(() => md.render('[Google](https://google.com)')).not.toThrow();
+  });
+
+  test('allows anchor links', () => {
+    const md = createMd([]);
+    expect(() => md.render('[Section](#top)')).not.toThrow();
+  });
+
+  test('allows mailto links', () => {
+    const md = createMd([]);
+    expect(() => md.render('[Email](mailto:test@example.com)')).not.toThrow();
+  });
+
+  test('throws for broken internal link', () => {
+    const md = createMd(['/about.html']);
+    expect(() => md.render('[Missing](/missing.html)')).toThrow(
+      'broken internal link',
+    );
+  });
+
+  test('strips query and hash before validating', () => {
+    const md = createMd(['/page.html']);
+    expect(() => md.render('[Page](/page.html?v=1#section)')).not.toThrow();
+  });
+
+  test('resolves relative links from source path', () => {
+    const md = createMd(['/docs/guide.html'], {
+      sourceUrlPath: '/docs/index.html',
+    });
+    expect(() => md.render('[Guide](guide.html)')).not.toThrow();
+  });
+
+  test('throws for broken relative link', () => {
+    const md = createMd(['/docs/guide.html'], {
+      sourceUrlPath: '/docs/index.html',
+    });
+    expect(() => md.render('[Missing](missing.html)')).toThrow(
+      'broken internal link',
+    );
+  });
+
+  test('rewrites code extensions to .html', () => {
+    const md = createMd(['/src/App.html'], { codeExtensions: ['java'] });
+    expect(() => md.render('[App](/src/App.java)')).not.toThrow();
+  });
+
+  test('detects directory links that should reference index.html', () => {
+    const md = createMd(['/docs/index.html']);
+    // The plugin logs the "directory link" message and throws a generic
+    // "broken internal link(s)" error, so match the thrown message.
+    expect(() => md.render('[Docs](/docs)')).toThrow('broken internal link');
+  });
+
+  test('validates links in raw HTML blocks', () => {
+    const md = createMd(['/about.html']);
+    expect(() => md.render('<a href="/missing.html">link</a>')).toThrow(
+      'broken internal link',
+    );
+  });
+
+  test('allows protocol-relative URLs', () => {
+    const md = createMd([]);
+    expect(() => md.render('[CDN](//cdn.example.com/lib.js)')).not.toThrow();
+  });
+});