@abreen/tada 1.17.1 → 1.18.1

package/build/source-records.ts

@@ -1,6 +1,4 @@
-import fs from 'fs';
 import path from 'path';
-import { getExtensionToShikiLanguage } from './site-variables';
 import {
   renderCodePageAsset,
   renderCopiedContentAsset,
@@ -8,41 +6,41 @@ import {
   renderPlainTextPageAsset,
   toPosix,
 } from './util';
-import { extensionIsMarkdown, isLiterateJava } from './utils/file-types';
 import type {
   Asset,
+  OutputContent,
+  HtmlOutputAnalysis,
   RenderDependencyCollector,
   SiteVariables,
   TraceToolAvailability,
 } from './types';
 import type { TadaProjectScan } from './source-model';
-import {
-  collectSourceHtmlAnalysis,
-  collectSourceOutputs,
-  type TadaSourceRecord,
-} from './watch/snapshot';
-import type { TraceCache } from './watch/compiler-types';
 
-export type TadaSourceRenderKind =
-  | 'skip'
-  | 'plain-text-page'
-  | 'literate-java'
-  | 'code-page'
-  | 'content-copy'
-  | 'public-copy';
+import type { TraceCache } from './build-types';
+
+export interface TadaSourceRecord {
+  sourcePath: string;
+  kind: 'content' | 'public';
+  outputs: Map<string, OutputContent>;
+  htmlAnalysisByOutputPath?: Map<string, HtmlOutputAnalysis>;
+  partialDeps: Set<string>;
+  traceDeps: Set<string>;
+  internalTargets: Set<string>;
+  authorKey?: string;
+}
 
 function createDependencyCollector(): {
   collector: RenderDependencyCollector;
   partials: Set<string>;
   traceFiles: Set<string>;
   internalTargets: Set<string>;
-  generatedOutputPaths: Set<string>;
+  traceOutputs: Map<string, string>;
   authorKey: string | undefined;
 } {
   const partials = new Set<string>();
   const traceFiles = new Set<string>();
   const internalTargets = new Set<string>();
-  const generatedOutputPaths = new Set<string>();
+  const traceOutputs = new Map<string, string>();
   let authorKey: string | undefined;
 
   return {
@@ -50,7 +48,7 @@ function createDependencyCollector(): {
       partials,
       traceFiles,
       internalTargets,
-      generatedOutputPaths,
+      traceOutputs,
       setAuthorKey(value: string) {
         authorKey = value;
       },
@@ -58,7 +56,7 @@ function createDependencyCollector(): {
     partials,
     traceFiles,
     internalTargets,
-    generatedOutputPaths,
+    traceOutputs,
     get authorKey() {
       return authorKey;
     },
@@ -74,7 +72,6 @@ function createEmptyContentRecord(filePath: string): TadaSourceRecord {
     partialDeps: new Set(),
     traceDeps: new Set(),
     internalTargets: new Set(),
-    generatedOutputPaths: new Set(),
   };
 }
 
@@ -82,79 +79,31 @@ function createRawContentAsset(filePath: string, contentDir: string): Asset[] {
   return [
     {
       assetPath: toPosix(path.relative(contentDir, filePath)),
-      content: fs.readFileSync(filePath),
+      content: { copyFrom: filePath },
     },
   ];
 }
 
-export function classifySourceRenderKind({
-  filePath,
-  scan,
-  siteVariables,
-}: {
-  filePath: string;
-  scan: TadaProjectScan;
-  siteVariables: SiteVariables;
-}): TadaSourceRenderKind {
-  if (scan.publicFiles.has(filePath)) {
-    return 'public-copy';
-  }
-
-  if (!scan.contentFiles.has(filePath)) {
-    return 'skip';
-  }
-
-  const ext = path.extname(filePath).slice(1).toLowerCase();
-  const lowerExt = path.extname(filePath).toLowerCase();
-  if (!scan.processedExts.has(ext)) {
-    return 'content-copy';
-  }
-
-  if (!scan.buildContentFiles.has(filePath)) {
-    return 'skip';
-  }
-
-  if (isLiterateJava(filePath)) {
-    return 'literate-java';
-  }
-
-  if (extensionIsMarkdown(lowerExt) || lowerExt === '.html') {
-    return 'plain-text-page';
-  }
-
-  if (Object.hasOwn(getExtensionToShikiLanguage(siteVariables), ext)) {
-    return 'code-page';
-  }
-
-  return 'skip';
-}
-
 export function createContentRecord({
   filePath,
   siteVariables,
   scan,
   assetFiles,
-  outputDir,
+  isWatchMode,
   traceCache,
   traceToolAvailability,
-  cachedTraceSourceDir,
   skipLiterateJavaExecution,
 }: {
   filePath: string;
   siteVariables: SiteVariables;
   scan: TadaProjectScan;
   assetFiles: string[];
-  outputDir: string;
+  isWatchMode: boolean;
   traceCache?: TraceCache;
   traceToolAvailability?: TraceToolAvailability;
-  cachedTraceSourceDir?: string;
   skipLiterateJavaExecution?: boolean;
 }): TadaSourceRecord {
-  const renderKind = classifySourceRenderKind({
-    filePath,
-    scan,
-    siteVariables,
-  });
+  const renderKind = scan.sources.get(filePath)?.renderKind ?? 'skip';
   if (renderKind === 'skip' || renderKind === 'public-copy') {
     return createEmptyContentRecord(filePath);
   }
@@ -168,11 +117,13 @@ export function createContentRecord({
         ...renderLiterateJavaPageAsset({
           filePath,
           contentDir: scan.contentDir,
-          distDir: outputDir,
           siteVariables,
           assetFiles,
+          isWatchMode,
           skipExecution: skipLiterateJavaExecution,
           validInternalTargets: scan.validTargets,
+          generatedPageTargets: scan.generatedPageTargets,
+          codePageSourceTargets: scan.codePageSourceTargets,
           literateJavaOutputPaths: scan.literateJavaOutputPaths,
           dependencyCollector: deps.collector,
         }),
@@ -183,13 +134,14 @@ export function createContentRecord({
         ...renderPlainTextPageAsset({
           filePath,
           contentDir: scan.contentDir,
-          distDir: outputDir,
           siteVariables,
           validInternalTargets: scan.validTargets,
+          generatedPageTargets: scan.generatedPageTargets,
+          codePageSourceTargets: scan.codePageSourceTargets,
           assetFiles,
+          isWatchMode,
           literateJavaOutputPaths: scan.literateJavaOutputPaths,
           dependencyCollector: deps.collector,
-          cachedTraceSourceDir,
           traceCache,
           traceToolAvailability,
         }),
@@ -200,10 +152,12 @@ export function createContentRecord({
         ...renderCodePageAsset({
           filePath,
           contentDir: scan.contentDir,
-          distDir: outputDir,
           siteVariables,
           validInternalTargets: scan.validTargets,
+          generatedPageTargets: scan.generatedPageTargets,
+          codePageSourceTargets: scan.codePageSourceTargets,
           assetFiles,
+          isWatchMode,
           literateJavaOutputPaths: scan.literateJavaOutputPaths,
           dependencyCollector: deps.collector,
         }),
@@ -224,12 +178,11 @@ export function createContentRecord({
   return {
     sourcePath: filePath,
     kind: 'content',
-    outputs: collectSourceOutputs(assets, deps.generatedOutputPaths, outputDir),
+    outputs: collectSourceOutputs(assets, deps.traceOutputs),
     htmlAnalysisByOutputPath: collectSourceHtmlAnalysis(assets),
     partialDeps: deps.partials,
     traceDeps: deps.traceFiles,
     internalTargets: deps.internalTargets,
-    generatedOutputPaths: deps.generatedOutputPaths,
     authorKey: deps.authorKey,
   };
 }
@@ -242,11 +195,46 @@ export function createPublicRecord(
   return {
     sourcePath: filePath,
     kind: 'public',
-    outputs: new Map([[relPath, fs.readFileSync(filePath)]]),
+    outputs: new Map([[relPath, { copyFrom: filePath }]]),
     htmlAnalysisByOutputPath: new Map(),
     partialDeps: new Set(),
     traceDeps: new Set(),
     internalTargets: new Set(),
-    generatedOutputPaths: new Set(),
   };
 }
+
+export function collectSourceOutputs(
+  assets: Asset[],
+  traceOutputs: ReadonlyMap<string, string>,
+): Map<string, OutputContent> {
+  const outputs = new Map<string, OutputContent>();
+  for (const asset of assets) {
+    outputs.set(asset.assetPath, asset.content);
+  }
+  for (const [outputPath, content] of traceOutputs) {
+    outputs.set(outputPath, content);
+  }
+  return outputs;
+}
+
+function cloneHtmlOutputAnalysis(
+  analysis: HtmlOutputAnalysis,
+): HtmlOutputAnalysis {
+  return { outgoingTargets: new Set(analysis.outgoingTargets) };
+}
+
+export function collectSourceHtmlAnalysis(
+  assets: Asset[],
+): Map<string, HtmlOutputAnalysis> {
+  const htmlAnalysisByOutputPath = new Map<string, HtmlOutputAnalysis>();
+  for (const asset of assets) {
+    if (!asset.assetPath.endsWith('.html') || !asset.htmlAnalysis) {
+      continue;
+    }
+    htmlAnalysisByOutputPath.set(
+      asset.assetPath,
+      cloneHtmlOutputAnalysis(asset.htmlAnalysis),
+    );
+  }
+  return htmlAnalysisByOutputPath;
+}

package/build/template-globals.ts

@@ -1,3 +1,4 @@
+import { encodePublicAssetPath } from './custom-fonts';
 import timezones from '../src/timezone/timezones.json' with { type: 'json' };
 import type { SiteVariables } from './types';
 
@@ -24,6 +25,7 @@ interface TemplateGlobals {
   classNames: (obj: Record<string, unknown>) => string;
   cx: (obj: Record<string, unknown>) => string;
   encodeAuthoredUrl: (value: string) => string;
+  encodePublicAssetPath: (value: string) => string;
   renderTimeZoneChooser: () => string;
 }
 
@@ -53,6 +55,7 @@ export default function createTemplateGlobals(
     classNames,
     cx: classNames,
     encodeAuthoredUrl,
+    encodePublicAssetPath,
     renderTimeZoneChooser,
   };
 }

package/build/templates.ts

@@ -1,6 +1,6 @@
 import fs from 'fs';
 import path from 'path';
-import _ from 'lodash';
+import { compileTemplate } from './lodash-template';
 import {
   PROJECT_CONFIG_NAMES,
   getProjectConfigBaseName,
@@ -64,7 +64,10 @@ export function render(
 
   renderStack.push(fileName);
   try {
-    return _.template(templates[fileName])(params ?? undefined);
+    if (!Object.hasOwn(templates, fileName)) {
+      throw new Error(`Unknown template "${fileName}"`);
+    }
+    return compileTemplate(templates[fileName])(params ?? undefined);
   } catch (err) {
     if (errorStack == null) {
       errorStack = renderStack.slice();

package/build/toc-plugin.ts

@@ -1,6 +1,7 @@
 import type MarkdownIt from 'markdown-it';
 import { convertMarkdown as curlyQuote } from 'quote-quote';
 import type { JavaTocEntry } from './types';
+import textToId, { deduplicateId } from './text-to-id';
 
 interface HeadingItem {
   kind: 'heading';
@@ -17,7 +18,7 @@ interface AlertItem {
   kind: 'alert';
   type: string;
   title: string;
-  id?: string;
+  id: string;
 }
 
 type TocItem = HeadingItem | DinkusItem | AlertItem;
@@ -31,6 +32,7 @@ export function tocPlugin(md: MarkdownIt): void {
     const tokens = state.tokens;
     const items: TocItem[] = [];
     const containerStack: string[] = [];
+    const usedAlertIds = new Map<string, number>();
 
     for (let i = 0; i < tokens.length; i++) {
       const token = tokens[i];
@@ -70,19 +72,22 @@ export function tocPlugin(md: MarkdownIt): void {
         const depth = containerStack.length;
         const parentIsSection = depth === 1 && containerStack[0] === 'section';
 
-        if (depth === 0 || parentIsSection) {
-          const match = token.info
-            .trim()
-            .match(/^(note|warning)(?:\s+"(.+)"|\s+(.+))?$/);
-          if (match) {
-            const type = match[1];
-            let title = (match[2] || match[3])?.trim();
-            if (title) {
-              title = md.utils.escapeHtml(curlyQuote(title));
-            } else {
-              title = type === 'warning' ? 'Warning' : 'Note';
-            }
-            items.push({ kind: 'alert', type, title });
+        const match = token.info
+          .trim()
+          .match(/^(note|warning)(?:\s+"(.+)"|\s+(.+))?$/);
+        if (match) {
+          const type = match[1];
+          const title = (match[2] || match[3])?.trim();
+          // Assign IDs to every alert, including those excluded from the TOC.
+          const id = deduplicateId(usedAlertIds, textToId(title || type));
+          token.attrSet('id', id);
+          if (depth === 0 || parentIsSection) {
+            const displayTitle = title
+              ? md.utils.escapeHtml(curlyQuote(title))
+              : type === 'warning'
+                ? 'Warning'
+                : 'Note';
+            items.push({ kind: 'alert', type, title: displayTitle, id });
           }
         }
         // Fall through to push 'alert' onto container stack
@@ -110,16 +115,12 @@ export function tocPlugin(md: MarkdownIt): void {
   });
 }
 
-export function generateTocHtml(
-  tocItems: TocItem[],
-  alertIds: string[],
-): string {
+export function generateTocHtml(tocItems: TocItem[]): string {
   if (!tocItems || tocItems.length === 0) {
     return '';
   }
 
   let lastHeadingLevel = 1;
-  let alertIdx = 0;
   const parts = ['<ol>'];
 
   for (const item of tocItems) {
@@ -139,8 +140,7 @@ export function generateTocHtml(
 
     if (item.kind === 'alert') {
       const level = lastHeadingLevel + 1;
-      const id = alertIds[alertIdx++];
-      const href = `#${id}`;
+      const href = `#${item.id}`;
       parts.push(
         `<li class="alert-item level${level} ${item.type}">` +
           `<a href="${href}">${item.title}</a></li>`,

package/build/types.d.ts

@@ -1,5 +1,11 @@
 import type { BundledLanguage } from 'shiki';
-import type { TadaProjectScan } from './source-model';
+import type { TraceCache } from './build-types';
+
+/** An explicitly authored ancestor in a page's breadcrumb trail. */
+export interface BreadcrumbEntry {
+  label: string;
+  url: string;
+}
 
 export type PlainTextLanguage = 'text' | 'txt' | 'plain';
 
@@ -18,7 +24,7 @@ export interface SerifMonoFontTuning {
 }
 
 export interface FontFamilyOverride<Tuning = unknown> {
-  regular: string;
+  regular?: string;
   italic?: string;
   bold?: string;
   boldItalic?: string;
@@ -40,6 +46,8 @@ export interface SiteVariables {
   banner?: string;
   symbol?: string;
   faviconSymbol?: string;
+  logo?: string;
+  favicon?: string;
   themeColor: string;
   faviconColor?: string;
   faviconFontWeight?: number;
@@ -71,24 +79,18 @@ export interface HtmlOutputAnalysis {
   outgoingTargets: Set<string>;
 }
 
-export interface Asset {
-  assetPath: string;
-  content: string | Buffer;
-  htmlAnalysis?: HtmlOutputAnalysis;
+/** An output copied unchanged from a source file when it is written */
+export interface CopiedFile {
+  copyFrom: string;
 }
 
-/** Options for the content rendering pipeline */
-export interface ContentRenderOptions {
-  distDir: string;
-  assetFiles: string[];
-  scan: TadaProjectScan;
-}
+/** Output content: rendered text or bytes, or a reference to a file to copy */
+export type OutputContent = string | Uint8Array | CopiedFile;
 
-/** Result from ContentRenderer.processContent() */
-export interface ContentRenderResult {
-  errors: Error[];
-  htmlAssetsByPath: Map<string, string>;
-  htmlAnalysisByPath: Map<string, HtmlOutputAnalysis>;
+export interface Asset {
+  assetPath: string;
+  content: OutputContent;
+  htmlAnalysis?: HtmlOutputAnalysis;
 }
 
 /** Logger returned by makeLogger() */
@@ -107,23 +109,15 @@ export interface Logger {
 export interface RenderPlainTextOptions {
   filePath: string;
   contentDir: string;
-  distDir: string;
   siteVariables: SiteVariables;
-  validInternalTargets: Set<string>;
+  validInternalTargets: ReadonlySet<string>;
+  generatedPageTargets?: ReadonlySet<string>;
+  codePageSourceTargets?: ReadonlySet<string>;
   assetFiles: string[];
-  literateJavaOutputPaths?: Set<string>;
+  isWatchMode: boolean;
+  literateJavaOutputPaths?: ReadonlySet<string>;
   dependencyCollector?: RenderDependencyCollector;
-  cachedTraceSourceDir?: string;
-  traceCache?: Map<
-    string,
-    {
-      manifestUrl: string;
-      artifactId: string;
-      highlightedSources: { file: string; highlightedSource: string }[];
-      totalSteps: number;
-      sourceMtims: Record<string, number>;
-    }
-  >;
+  traceCache?: TraceCache;
   traceToolAvailability?: TraceToolAvailability;
 }
 
@@ -136,11 +130,13 @@ export interface TraceToolAvailability {
 export interface RenderCodePageOptions {
   filePath: string;
   contentDir: string;
-  distDir: string;
   siteVariables: SiteVariables;
   assetFiles: string[];
-  validInternalTargets: Set<string>;
-  literateJavaOutputPaths?: Set<string>;
+  isWatchMode: boolean;
+  validInternalTargets: ReadonlySet<string>;
+  generatedPageTargets?: ReadonlySet<string>;
+  codePageSourceTargets?: ReadonlySet<string>;
+  literateJavaOutputPaths?: ReadonlySet<string>;
   dependencyCollector?: RenderDependencyCollector;
 }
 
@@ -148,12 +144,14 @@ export interface RenderCodePageOptions {
 export interface RenderLiterateJavaOptions {
   filePath: string;
   contentDir: string;
-  distDir: string;
   siteVariables: SiteVariables;
   assetFiles: string[];
+  isWatchMode: boolean;
   skipExecution?: boolean;
-  validInternalTargets: Set<string>;
-  literateJavaOutputPaths?: Set<string>;
+  validInternalTargets: ReadonlySet<string>;
+  generatedPageTargets?: ReadonlySet<string>;
+  codePageSourceTargets?: ReadonlySet<string>;
+  literateJavaOutputPaths?: ReadonlySet<string>;
   dependencyCollector?: RenderDependencyCollector;
 }
 
@@ -168,7 +166,8 @@ export interface RenderDependencyCollector {
   partials?: Set<string>;
   traceFiles?: Set<string>;
   internalTargets?: Set<string>;
-  generatedOutputPaths?: Set<string>;
+  /** Files a page generates besides its own assets, by output path */
+  traceOutputs?: Map<string, string>;
   setAuthorKey?: (authorKey: string) => void;
 }
 
@@ -287,6 +286,13 @@ export interface TraceSource {
   lineToSteps: Record<number, number[]>;
 }
 
+/** A generated trace manifest or chunk file */
+export interface TraceArtifactFile {
+  /** File name inside the trace's `sha256-*` artifact directory */
+  name: string;
+  content: string;
+}
+
 /** Position and size of a heap object in the precomputed layout. */
 export interface TraceObjectLayout {
   x: number;

package/build/util.ts

@@ -1,10 +1,6 @@
-export { getFilesByExtensions } from './utils/content-files';
 export {
   createApplyBasePath,
-  getContentDir,
   getDistDir,
-  getPackageDir,
-  getPublicDir,
   normalizeOutputPath,
   toPosix,
 } from './utils/paths';