@abreen/tada 1.17.1 → 1.18.1

package/build/utils/shiki-highlighter.ts

@@ -78,3 +78,14 @@ export function highlightCode(code: string, lang: string): string {
     defaultColor: false,
   });
 }
+
+export function highlightCodeToHast(
+  code: string,
+  lang: string,
+): ReturnType<HighlighterGeneric<BundledLanguage, BundledTheme>['codeToHast']> {
+  return getHighlighter().codeToHast(code, {
+    lang,
+    themes: SHIKI_THEMES,
+    defaultColor: false,
+  });
+}

package/build/utils/source-template.ts

@@ -1,4 +1,4 @@
-import _ from 'lodash';
+import { compileTemplate } from '../lodash-template';
 import type { SiteVariables } from '../types';
 
 /**
@@ -17,7 +17,7 @@ export function applySourceTemplate(
   const params = { vars: siteVariables.vars || {}, site: siteVariables };
 
   try {
-    return _.template(source)(params);
+    return compileTemplate(source)(params);
   } catch (err: unknown) {
     throw new Error(
       `${filePath}: Lodash template error in source code: ${(err as Error).message}`,

package/build/utils/trace-core.ts

@@ -1,4 +1,3 @@
-import fs from 'fs';
 import path from 'path';
 import { createHash } from 'crypto';
 import { renderCodeSegment } from './code';
@@ -7,6 +6,7 @@ import { normalizeOutputPath } from './paths';
 import { computeLayout } from './trace-layout';
 import { filterStep, generateStepSvg } from './trace-svg';
 import type {
+  TraceArtifactFile,
   TraceChunkEntry,
   TraceHeapObject,
   TraceManifest,
@@ -24,14 +24,15 @@ export interface ChunkTraceOutputOptions {
 export interface ChunkTraceOutputResult {
   manifest: TraceManifest;
   artifactId: string;
-  outputPaths: string[];
+  /** `manifest.json` followed by the chunk files */
+  files: TraceArtifactFile[];
 }
 
 function stepOutputEvents(step: TraceStep): TraceOutputEvent[] {
   return step.output ?? [];
 }
 
-function hashTraceFiles(files: { name: string; content: string }[]): string {
+function hashTraceFiles(files: TraceArtifactFile[]): string {
   const hasher = createHash('sha256');
   for (const file of files) {
     hasher.update(file.name, 'utf8');
@@ -46,7 +47,8 @@ function safeSvgIdPart(value: string): string {
   return value.replace(/[^A-Za-z0-9_-]+/g, '-').replace(/^-+|-+$/g, '');
 }
 
-function buildTraceOutputPath(
+/** Output path of a trace artifact file, relative to the output directory */
+export function buildTraceOutputPath(
   relDir: string,
   traceName: string,
   artifactId: string,
@@ -147,8 +149,6 @@ export function bridgeConstructorReturnValues(steps: TraceStep[]): TraceStep[] {
 
 export function chunkTraceOutput(
   output: string,
-  traceOutputDir: string,
-  relDir: string,
   traceName: string,
   primaryFile: string,
   sources: { file: string; source: string }[],
@@ -189,7 +189,7 @@ export function chunkTraceOutput(
 
   let chunkEntries: TraceChunkEntry[] = [];
   let chunkIndex = 0;
-  const chunkFiles: { name: string; content: string }[] = [];
+  const chunkFiles: TraceArtifactFile[] = [];
 
   for (const [stepIndex, step] of allSteps.entries()) {
     const svg = generateStepSvg(
@@ -237,21 +237,7 @@ export function chunkTraceOutput(
     content: JSON.stringify(manifest),
   };
   const files = [manifestFile, ...chunkFiles];
-  const artifactId = hashTraceFiles(files);
-  const artifactDir = path.join(traceOutputDir, artifactId);
-
-  fs.mkdirSync(artifactDir, { recursive: true });
-  for (const file of files) {
-    fs.writeFileSync(path.join(artifactDir, file.name), file.content);
-  }
-
-  return {
-    manifest,
-    artifactId,
-    outputPaths: files.map(file =>
-      buildTraceOutputPath(relDir, traceName, artifactId, file.name),
-    ),
-  };
+  return { manifest, artifactId: hashTraceFiles(files), files };
 }
 
 export function highlightTraceSource(
@@ -263,67 +249,6 @@ export function highlightTraceSource(
   });
 }
 
-export function getTraceOutputPaths(
-  relDir: string,
-  traceName: string,
-  artifactId: string,
-  totalSteps: number,
-): string[] {
-  const outputPaths = [
-    buildTraceOutputPath(relDir, traceName, artifactId, 'manifest.json'),
-  ];
-  for (
-    let chunkIndex = 0;
-    chunkIndex * DEFAULT_CHUNK_SIZE < totalSteps;
-    chunkIndex++
-  ) {
-    outputPaths.push(
-      buildTraceOutputPath(
-        relDir,
-        traceName,
-        artifactId,
-        `chunk-${chunkIndex}.json`,
-      ),
-    );
-  }
-  return outputPaths;
-}
-
-function linkOrCopyFile(sourcePath: string, targetPath: string): void {
-  try {
-    fs.linkSync(sourcePath, targetPath);
-  } catch {
-    fs.copyFileSync(sourcePath, targetPath);
-  }
-}
-
-export function materializeTraceOutputs({
-  outputPaths,
-  targetDistDir,
-  sourceDistDir,
-}: {
-  outputPaths: string[];
-  targetDistDir: string;
-  sourceDistDir: string;
-}): boolean {
-  for (const relPath of outputPaths) {
-    const targetPath = path.join(targetDistDir, relPath);
-    if (fs.existsSync(targetPath)) {
-      continue;
-    }
-
-    const sourcePath = path.join(sourceDistDir, relPath);
-    if (!fs.existsSync(sourcePath)) {
-      return false;
-    }
-
-    fs.mkdirSync(path.dirname(targetPath), { recursive: true });
-    linkOrCopyFile(sourcePath, targetPath);
-  }
-
-  return true;
-}
-
 export function buildManifestUrl({
   relDir,
   traceName,

package/build/utils/trace.ts

@@ -7,11 +7,10 @@ import { toPosix } from './paths';
 import { checkJavac } from './literate-java';
 import {
   buildManifestUrl,
+  buildTraceOutputPath,
   chunkTraceOutput,
   DEFAULT_CHUNK_SIZE,
-  getTraceOutputPaths,
   highlightTraceSource,
-  materializeTraceOutputs,
   renderTraceWidgetHtml,
 } from './trace-core';
 import {
@@ -25,6 +24,7 @@ import type {
   RenderDependencyCollector,
   TraceToolAvailability,
 } from '../types';
+import type { TraceCache, TraceCacheEntry } from '../build-types';
 
 const log = makeLogger(import.meta.url);
 
@@ -33,20 +33,10 @@ export const TRACEABLE_EXTENSIONS = new Set(['.java', '.py']);
 export interface TraceContext {
   filePath: string;
   contentDir: string;
-  distDir: string;
   applyBasePath: (subPath: string) => string;
-  cache: Map<string, TraceResult>;
+  cache: TraceCache;
   toolAvailability?: TraceToolAvailability;
   dependencyCollector?: RenderDependencyCollector;
-  cachedTraceSourceDir?: string;
-}
-
-export interface TraceResult {
-  manifestUrl: string;
-  artifactId: string;
-  highlightedSources: { file: string; highlightedSource: string }[];
-  totalSteps: number;
-  sourceMtims: Record<string, number>;
 }
 
 export function isTraceSourceFile(filePath: string): boolean {
@@ -132,12 +122,10 @@ export function createTraceHelpers(context: TraceContext): {
   const {
     filePath,
     contentDir,
-    distDir,
     applyBasePath,
     cache,
     toolAvailability,
     dependencyCollector,
-    cachedTraceSourceDir,
   } = context;
   const pageDir = path.dirname(filePath);
 
@@ -202,7 +190,7 @@ export function createTraceHelpers(context: TraceContext): {
 
   function cacheIsFresh(
     sources: TraceSourceFile[],
-    cached: TraceResult,
+    cached: TraceCacheEntry,
   ): boolean {
     return sources.every(source => {
       const mtime = fs.statSync(source.absolutePath, {
@@ -229,45 +217,13 @@ export function createTraceHelpers(context: TraceContext): {
 
   function getOrRunTrace(
     sourceFile: string,
-    companionFiles?: string[],
-  ): TraceResult {
-    const sources = resolveTraceSources(sourceFile, companionFiles);
-    for (const source of sources) {
-      dependencyCollector?.traceFiles?.add(source.absolutePath);
-    }
-    const sourceFilePath = sources[0].absolutePath;
-    const traceName = path.parse(sourceFile).name;
-    const relDir = toPosix(path.relative(contentDir, pageDir));
+    sources: TraceSourceFile[],
+    traceName: string,
+  ): TraceCacheEntry {
     const cacheKey = cacheKeyForSources(sources);
-
     const cached = cache.get(cacheKey);
     if (cached && cacheIsFresh(sources, cached)) {
-      const outputPaths = getTraceOutputPaths(
-        relDir,
-        traceName,
-        cached.artifactId,
-        cached.totalSteps,
-      );
-      if (
-        materializeTraceOutputs({
-          outputPaths,
-          targetDistDir: distDir,
-          sourceDistDir: cachedTraceSourceDir || distDir,
-        })
-      ) {
-        for (const outputPath of outputPaths) {
-          dependencyCollector?.generatedOutputPaths?.add(outputPath);
-        }
-        return {
-          ...cached,
-          manifestUrl: buildManifestUrl({
-            relDir,
-            traceName,
-            artifactId: cached.artifactId,
-            applyBasePath,
-          }),
-        };
-      }
+      return cached;
     }
 
     log.info`Tracing ${B`${sourceFile}`}`;
@@ -288,49 +244,26 @@ export function createTraceHelpers(context: TraceContext): {
       fs.rmSync(workspaceDir, { recursive: true, force: true });
     }
 
-    const language = traceLanguageForFile(sourceFilePath);
-    const highlightedSources = sources.map(source => ({
-      file: source.file,
-      highlightedSource: highlightTraceSource(source.source, language),
-    }));
-    const traceOutputDir = path.join(distDir, relDir, '_traces', traceName);
-
-    const traceOutput = chunkTraceOutput(
+    const language = traceLanguageForFile(sources[0].absolutePath);
+    const { manifest, artifactId, files } = chunkTraceOutput(
       output,
-      traceOutputDir,
-      relDir,
       traceName,
       sources[0].file,
       sources.map(source => ({ file: source.file, source: source.source })),
       { chunkSize: DEFAULT_CHUNK_SIZE, ignoreFields },
     );
-    for (const outputPath of traceOutput.outputPaths) {
-      dependencyCollector?.generatedOutputPaths?.add(outputPath);
-    }
-
-    const manifestUrl = buildManifestUrl({
-      relDir,
-      traceName,
-      artifactId: traceOutput.artifactId,
-      applyBasePath,
-    });
-
-    const totalSteps = traceOutput.manifest.totalSteps;
-    const sourceMtims = getSourceMtims(sources);
-    cache.set(cacheKey, {
-      manifestUrl,
-      artifactId: traceOutput.artifactId,
-      highlightedSources,
-      totalSteps,
-      sourceMtims,
-    });
-    return {
-      manifestUrl,
-      artifactId: traceOutput.artifactId,
-      highlightedSources,
-      totalSteps,
-      sourceMtims,
+    const entry: TraceCacheEntry = {
+      artifactId,
+      files,
+      highlightedSources: sources.map(source => ({
+        file: source.file,
+        highlightedSource: highlightTraceSource(source.source, language),
+      })),
+      totalSteps: manifest.totalSteps,
+      sourceMtims: getSourceMtims(sources),
     };
+    cache.set(cacheKey, entry);
+    return entry;
   }
 
   return {
@@ -352,14 +285,24 @@ export function createTraceHelpers(context: TraceContext): {
         });
       }
 
-      const { manifestUrl, highlightedSources, totalSteps } = getOrRunTrace(
-        sourceFile,
-        companionFiles,
-      );
+      const traceName = path.parse(sourceFile).name;
+      const relDir = toPosix(path.relative(contentDir, pageDir));
+      const trace = getOrRunTrace(sourceFile, sources, traceName);
+      for (const file of trace.files) {
+        dependencyCollector?.traceOutputs?.set(
+          buildTraceOutputPath(relDir, traceName, trace.artifactId, file.name),
+          file.content,
+        );
+      }
       return renderTraceWidgetHtml({
-        highlightedSources,
-        manifestUrl,
-        totalSteps,
+        highlightedSources: trace.highlightedSources,
+        manifestUrl: buildManifestUrl({
+          relDir,
+          traceName,
+          artifactId: trace.artifactId,
+          applyBasePath,
+        }),
+        totalSteps: trace.totalSteps,
       });
     },
   };

package/build/validate-config-links.ts

@@ -1,4 +1,5 @@
 import path from 'path';
+import type { BreadcrumbEntry } from './types';
 import { encodeAuthoredUrl } from './template-globals';
 import { normalizeOutputPath } from './utils/paths';
 
@@ -73,7 +74,7 @@ function getInternalHrefTarget(href: string): string {
 function validateDirectoryLink(
   href: string,
   resolvedTarget: string,
-  validTargets: Set<string>,
+  validTargets: ReadonlySet<string>,
   context: string,
 ): string | null {
   const indexPath = normalizeOutputPath(
@@ -87,7 +88,7 @@ function validateDirectoryLink(
 
 export function validateNavLinks(
   navData: unknown,
-  validTargets: Set<string>,
+  validTargets: ReadonlySet<string>,
   fileName: string = 'nav.yaml',
 ): string[] {
   if (!Array.isArray(navData)) {
@@ -139,7 +140,7 @@ interface AuthorEntry {
 
 export function validateAuthorLinks(
   authorsData: unknown,
-  validTargets: Set<string>,
+  validTargets: ReadonlySet<string>,
   fileName: string = 'authors.yaml',
 ): string[] {
   if (!authorsData || typeof authorsData !== 'object') {
@@ -189,7 +190,7 @@ export function validateAuthorLinks(
 }
 
 export function validateConfigLinks(
-  validTargets: Set<string>,
+  validTargets: ReadonlySet<string>,
   navData: unknown,
   authorsData: unknown,
   {
@@ -208,47 +209,86 @@ function splitHref(href: string): { pathname: string; suffix: string } {
   return { pathname: match ? match[1] : href, suffix: match ? match[2] : '' };
 }
 
-export function validateParentLink(
-  parent: unknown,
+export function validateBreadcrumbs(
+  breadcrumbs: unknown,
   filePath: string,
-  validTargets: Set<string>,
+  validTargets: ReadonlySet<string>,
   sourceUrlPath: string,
-): string | null {
-  if (typeof parent === 'string' && splitHref(parent).pathname === '') {
-    return `${filePath}: broken parent link: "${parent}"`;
+): asserts breadcrumbs is BreadcrumbEntry[] | undefined {
+  if (breadcrumbs === undefined) {
+    return;
+  }
+  if (!Array.isArray(breadcrumbs)) {
+    throw new Error(`${filePath}: breadcrumbs must be a list`);
   }
+  breadcrumbs.forEach((entry: unknown, index) => {
+    const context = `${filePath}: breadcrumb entry ${index + 1}`;
+    if (!entry || typeof entry !== 'object' || Array.isArray(entry)) {
+      throw new Error(`${context} must be an object with label and url fields`);
+    }
+    const { label, url } = entry as Record<string, unknown>;
+    for (const [field, value] of Object.entries({ label, url })) {
+      if (typeof value !== 'string' || !value.trim()) {
+        throw new Error(`${context}: ${field} must be a nonempty string`);
+      }
+    }
+    const error = validateBreadcrumbLink(
+      url as string,
+      filePath,
+      validTargets,
+      sourceUrlPath,
+      index + 1,
+    );
+    if (error) {
+      throw new Error(error);
+    }
+  });
+}
 
-  const resolvedTarget = resolveParentLinkTarget(parent, sourceUrlPath);
+export function validateBreadcrumbLink(
+  url: string,
+  filePath: string,
+  validTargets: ReadonlySet<string>,
+  sourceUrlPath: string,
+  entryNumber = 1,
+): string | null {
+  const context = `${filePath}: breadcrumb entry ${entryNumber}`;
+  const resolvedTarget = resolveBreadcrumbLinkTarget(url, sourceUrlPath);
   if (!resolvedTarget) {
-    return null;
+    return `${context}: broken breadcrumb link: "${url}" (must be an internal site link with a pathname)`;
   }
 
   const directoryError = validateDirectoryLink(
-    parent as string,
+    url,
     resolvedTarget,
     validTargets,
-    `${filePath}: parent link`,
+    context,
   );
   if (directoryError) {
     return directoryError;
   }
 
   if (!validTargets.has(resolvedTarget)) {
-    return `${filePath}: broken parent link: "${parent}"`;
+    return `${context}: broken breadcrumb link: "${url}"`;
   }
 
   return null;
 }
 
-export function resolveParentLinkTarget(
-  parent: unknown,
+export function resolveBreadcrumbLinkTarget(
+  url: string,
   sourceUrlPath: string,
 ): string | null {
-  if (!parent || typeof parent !== 'string') {
+  // Breadcrumbs always point into this site. Backslashes also have special
+  // URL semantics in browsers, so they cannot be used as path separators.
+  if (
+    /^[a-zA-Z][a-zA-Z0-9+.-]*:/.test(url) ||
+    url.startsWith('//') ||
+    url.includes('\\')
+  ) {
     return null;
   }
-
-  const { pathname } = splitHref(parent);
+  const { pathname } = splitHref(url);
   if (!pathname) {
     return null;
   }

package/build/watch/build-incremental.ts

@@ -1,118 +1,61 @@
-import { compileTemplates, config } from '../templates';
-import { getDistDir } from '../util';
-import type { CompilerBuildResult } from './types';
-import type { TraceCache, WatchTraceOptions } from './compiler-types';
-import type { TadaIncrementalWatchPlan } from './planner';
-import { createSnapshot, type TadaSnapshot } from './snapshot';
+import { compileTemplates } from '../templates';
+import { validateConfig } from '../build-validation';
 import {
-  copyExistingBuildAssets,
   ensureHighlighter,
-  makeTempBuildDir,
-  removeDirIfExists,
-} from './assets';
-import { computeMutations } from './mutations';
-import { validateConfig, validateProjectConfigLinks } from './validation';
-import { buildFailedFromError, buildSucceeded } from './build-result';
-import {
-  buildFailedWithDiagnostics,
-  renderContentRecord,
-  renderPublicRecord,
-} from './build-helpers';
+  finishBuild,
+  renderSources,
+  type TadaSnapshot,
+} from '../site-build';
+import type { TraceCache } from '../build-types';
+import type { TraceToolAvailability } from '../types';
+import type { TadaIncrementalWatchPlan } from './planner';
+import type { CompileOutcome } from './types';
 
 export async function buildIncremental({
   plan,
   snapshot,
   traceCache,
-  traceOptions,
+  traceToolAvailability,
 }: {
   plan: TadaIncrementalWatchPlan;
   snapshot: TadaSnapshot;
   traceCache: TraceCache;
-  traceOptions: WatchTraceOptions;
-}): Promise<CompilerBuildResult> {
-  const distDir = getDistDir();
-  const outputDir = makeTempBuildDir(distDir);
-  try {
-    const siteVariables = snapshot.siteVariables;
-    const configDiagnostics = validateConfig(plan.scan, siteVariables);
-    if (configDiagnostics.length > 0) {
-      return buildFailedWithDiagnostics(outputDir, configDiagnostics);
-    }
-
-    compileTemplates(siteVariables);
-    await ensureHighlighter(siteVariables);
-    copyExistingBuildAssets(distDir, outputDir, snapshot.assetFiles);
-
-    const nextContentRecords = new Map(snapshot.contentRecords);
-    const nextPublicRecords = new Map(snapshot.publicRecords);
-
-    for (const sourcePath of plan.contentToRemove) {
-      nextContentRecords.delete(sourcePath);
-    }
-    for (const sourcePath of plan.publicToRemove) {
-      nextPublicRecords.delete(sourcePath);
-    }
-
-    for (const sourcePath of plan.contentToRender) {
-      nextContentRecords.delete(sourcePath);
-      const record = renderContentRecord({
-        filePath: sourcePath,
-        siteVariables,
-        scan: plan.scan,
-        assetFiles: snapshot.assetFiles,
-        outputDir,
-        traceCache,
-        traceOptions,
-        cachedTraceSourceDir: distDir,
-      });
-      if (record) {
-        nextContentRecords.set(sourcePath, record);
-      }
-    }
-
-    for (const sourcePath of plan.publicToRender) {
-      nextPublicRecords.delete(sourcePath);
-      const record = renderPublicRecord({
-        filePath: sourcePath,
-        publicDir: plan.scan.publicDir,
-      });
-      nextPublicRecords.set(sourcePath, record);
-    }
-
-    const nextSnapshot = createSnapshot({
-      siteVariables,
-      assetFiles: snapshot.assetFiles,
-      navData: config('nav'),
-      authorsData: config('authors'),
-      scan: plan.scan,
-      contentRecords: nextContentRecords,
-      publicRecords: nextPublicRecords,
-    });
+  traceToolAvailability: TraceToolAvailability;
+}): Promise<CompileOutcome> {
+  const { siteVariables } = snapshot;
+  const configDiagnostics = validateConfig(plan.scan, siteVariables);
+  if (configDiagnostics.length > 0) {
+    return { ok: false, diagnostics: configDiagnostics };
+  }
 
-    const linkDiagnostics = validateProjectConfigLinks(
-      nextSnapshot.scan.validTargets,
-    );
-    if (linkDiagnostics.length > 0) {
-      return buildFailedWithDiagnostics(outputDir, linkDiagnostics);
-    }
+  compileTemplates(siteVariables);
+  await ensureHighlighter(siteVariables);
 
-    const forceSourcePaths = new Set([
-      ...plan.contentToRender,
-      ...plan.publicToRender,
-    ]);
-    const mutations = computeMutations(
-      snapshot,
-      nextSnapshot,
-      forceSourcePaths,
-    );
-    removeDirIfExists(outputDir);
-    return buildSucceeded(nextSnapshot, {
-      kind: 'apply-mutations',
-      rootDir: distDir,
-      mutations,
-    });
-  } catch (error) {
-    removeDirIfExists(outputDir);
-    return buildFailedFromError(error);
+  const records = new Map(snapshot.records);
+  for (const source of [...plan.removeSources, ...plan.renderSources]) {
+    records.delete(source);
+  }
+  const rendered = renderSources(plan.renderSources, {
+    siteVariables,
+    scan: plan.scan,
+    assetFiles: snapshot.assetFiles,
+    isWatchMode: true,
+    traceCache,
+    traceToolAvailability,
+  });
+  for (const [source, record] of rendered.records) {
+    records.set(source, record);
   }
+
+  const result = finishBuild({
+    siteVariables,
+    scan: plan.scan,
+    assetFiles: snapshot.assetFiles,
+    generatedOutputs: snapshot.generatedOutputs,
+    records,
+    diagnostics: rendered.diagnostics,
+  });
+  return result.ok
+    ? { ...result, full: false, forceSourcePaths: plan.renderSources }
+    : result;
 }