@abreen/tada 1.8.1 → 1.10.1

package/build/watch/assets.ts

@@ -0,0 +1,111 @@
+import fs from 'fs';
+import path from 'path';
+import { bundle } from '../bundle';
+import { copyFonts } from '../generate-fonts';
+import { copyKatexAssets } from '../generate-katex-assets';
+import { generateFavicons } from '../generate-favicon';
+import { generateWebAppManifest } from '../generate-web-app-manifest';
+import { getPackageDir, toPosix } from '../util';
+import { initHighlighter } from '../utils/shiki-highlighter';
+import type { SiteVariables } from '../types';
+
+const RELOAD_CLIENT_PATH = path.resolve(
+  getPackageDir(),
+  'build/watch-reload-client.ts',
+);
+
+export function makeTempBuildDir(distDir: string): string {
+  const parentDir = path.dirname(distDir);
+  const prefix = `${path.basename(distDir)}-watch-`;
+  return fs.mkdtempSync(path.join(parentDir, prefix));
+}
+
+export function removeDirIfExists(dir: string): void {
+  fs.rmSync(dir, { recursive: true, force: true });
+}
+
+export async function ensureHighlighter(
+  siteVariables: SiteVariables,
+): Promise<void> {
+  const langs = [
+    ...new Set([
+      'plaintext',
+      'text',
+      ...Object.values(siteVariables.codeLanguages || {}),
+    ]),
+  ];
+  await initHighlighter(langs);
+}
+
+export async function bundleWatchAssets(
+  outputDir: string,
+  siteVariables: SiteVariables,
+  wsPort: number,
+): Promise<string[]> {
+  const appAssets = await bundle(siteVariables, {
+    mode: 'development',
+    distDir: outputDir,
+  });
+  const reloadAssets = await Bun.build({
+    entrypoints: [RELOAD_CLIENT_PATH],
+    outdir: outputDir,
+    naming: '[name].bundle.[ext]',
+    sourcemap: 'inline',
+    define: { __WEBSOCKET_PORT__: String(wsPort) },
+  });
+  return [
+    ...appAssets,
+    ...reloadAssets.outputs.map(output =>
+      toPosix(path.relative(outputDir, output.path)),
+    ),
+  ];
+}
+
+export async function populateStaticAssets(
+  outputDir: string,
+  siteVariables: SiteVariables,
+): Promise<void> {
+  copyFonts(outputDir);
+  copyKatexAssets(outputDir);
+  if (siteVariables.features.favicon !== false) {
+    await generateFavicons(siteVariables, outputDir);
+    generateWebAppManifest(siteVariables, outputDir);
+  }
+}
+
+export function copyExistingBuildAssets(
+  distDir: string,
+  outputDir: string,
+  assetFiles: string[],
+): void {
+  const relPaths = [
+    ...assetFiles,
+    'inter/InterVariable.woff2',
+    'google-sans-code/GoogleSansCodeVariable.woff2',
+  ];
+
+  for (const relPath of relPaths) {
+    const sourcePath = path.join(distDir, relPath);
+    if (!fs.existsSync(sourcePath)) {
+      continue;
+    }
+    const destinationPath = path.join(outputDir, relPath);
+    fs.mkdirSync(path.dirname(destinationPath), { recursive: true });
+    try {
+      fs.linkSync(sourcePath, destinationPath);
+    } catch {
+      fs.copyFileSync(sourcePath, destinationPath);
+    }
+  }
+}
+
+export function writeAssets(
+  outputDir: string,
+  assets: Map<string, string | Buffer>,
+): void {
+  for (const [assetPath, content] of assets) {
+    const outputPath = path.join(outputDir, assetPath);
+    fs.mkdirSync(path.dirname(outputPath), { recursive: true });
+    fs.writeFileSync(outputPath, content);
+  }
+}

package/build/watch/build-full.ts

@@ -0,0 +1,124 @@
+import { compileTemplates, json } from '../templates';
+import { getDevSiteVariables } from '../site-variables';
+import { getDistDir } from '../util';
+import type { CompilerBuildResult } from '../../watch/types';
+import {
+  collectHtmlAssetsByPath,
+  createSnapshot,
+  scanProject,
+  type TadaSourceRecord,
+  type TadaSnapshot,
+} from './snapshot';
+import type {
+  TadaBuildMeta,
+  TraceCache,
+  WatchTraceOptions,
+} from './compiler-types';
+import {
+  bundleWatchAssets,
+  ensureHighlighter,
+  makeTempBuildDir,
+  populateStaticAssets,
+  removeDirIfExists,
+  writeAssets,
+} from './assets';
+import { createPublicRecord, renderContentRecord } from './records';
+import {
+  diagnosticsFromMessages,
+  validateConfig,
+  validateJsonLinks,
+} from './validation';
+
+export async function buildFull({
+  wsPort,
+  traceCache,
+  traceOptions,
+}: {
+  wsPort: number;
+  traceCache: TraceCache;
+  traceOptions: WatchTraceOptions;
+}): Promise<CompilerBuildResult<TadaSnapshot, TadaBuildMeta>> {
+  const distDir = getDistDir();
+  const outputDir = makeTempBuildDir(distDir);
+  try {
+    const siteVariables = getDevSiteVariables();
+    const scan = scanProject(siteVariables);
+    const configDiagnostics = validateConfig(scan);
+    if (configDiagnostics.length > 0) {
+      removeDirIfExists(outputDir);
+      return { ok: false, diagnostics: configDiagnostics };
+    }
+
+    compileTemplates(siteVariables);
+    await ensureHighlighter(siteVariables);
+
+    const assetFiles = await bundleWatchAssets(
+      outputDir,
+      siteVariables,
+      wsPort,
+    );
+    await populateStaticAssets(outputDir, siteVariables);
+
+    const contentRecords = new Map<string, TadaSourceRecord>();
+    for (const filePath of scan.contentFiles) {
+      const record = renderContentRecord({
+        filePath,
+        siteVariables,
+        scan,
+        assetFiles,
+        outputDir,
+        traceCache,
+        traceToolAvailability: traceOptions.toolAvailability,
+        cachedTraceSourceDir: distDir,
+      });
+      if (record.outputs.size > 0) {
+        contentRecords.set(filePath, record);
+      }
+    }
+
+    const publicRecords = new Map<string, TadaSourceRecord>();
+    for (const filePath of scan.publicFiles) {
+      const record = createPublicRecord(filePath, scan.publicDir);
+      writeAssets(outputDir, record.outputs);
+      publicRecords.set(filePath, record);
+    }
+
+    const linkDiagnostics = validateJsonLinks(scan.validTargets);
+    if (linkDiagnostics.length > 0) {
+      removeDirIfExists(outputDir);
+      return { ok: false, diagnostics: linkDiagnostics };
+    }
+
+    const nextSnapshot = createSnapshot({
+      siteVariables,
+      assetFiles,
+      navData: json('nav.json'),
+      authorsData: json('authors.json'),
+      scan,
+      contentRecords,
+      publicRecords,
+    });
+
+    return {
+      ok: true,
+      snapshot: nextSnapshot,
+      commit: {
+        kind: 'replace-root',
+        stagedPath: outputDir,
+        targetPath: distDir,
+      },
+      meta: {
+        htmlAssetsByPath: collectHtmlAssetsByPath(nextSnapshot.contentRecords),
+        siteVariables,
+      },
+    };
+  } catch (error) {
+    removeDirIfExists(outputDir);
+    return {
+      ok: false,
+      diagnostics: diagnosticsFromMessages([
+        error instanceof Error ? error.message : String(error),
+      ]),
+    };
+  }
+}

package/build/watch/build-incremental.ts

@@ -0,0 +1,139 @@
+import { compileTemplates, json } from '../templates';
+import { getDistDir } from '../util';
+import type { CompilerBuildResult } from '../../watch/types';
+import type {
+  TadaBuildMeta,
+  TraceCache,
+  WatchTraceOptions,
+} from './compiler-types';
+import type { TadaWatchPlan } from './planner';
+import {
+  collectHtmlAssetsByPath,
+  createSnapshot,
+  type TadaSnapshot,
+} from './snapshot';
+import {
+  copyExistingBuildAssets,
+  ensureHighlighter,
+  makeTempBuildDir,
+  removeDirIfExists,
+} from './assets';
+import { computeMutations } from './mutations';
+import { createPublicRecord, renderContentRecord } from './records';
+import {
+  diagnosticsFromMessages,
+  validateConfig,
+  validateJsonLinks,
+} from './validation';
+
+export async function buildIncremental({
+  plan,
+  snapshot,
+  traceCache,
+  traceOptions,
+}: {
+  plan: TadaWatchPlan;
+  snapshot: TadaSnapshot;
+  traceCache: TraceCache;
+  traceOptions: WatchTraceOptions;
+}): Promise<CompilerBuildResult<TadaSnapshot, TadaBuildMeta>> {
+  const outputDir = makeTempBuildDir(plan.scan.distDir);
+  try {
+    const siteVariables = snapshot.siteVariables;
+    const configDiagnostics = validateConfig(plan.scan);
+    if (configDiagnostics.length > 0) {
+      removeDirIfExists(outputDir);
+      return { ok: false, diagnostics: configDiagnostics };
+    }
+
+    compileTemplates(siteVariables);
+    await ensureHighlighter(siteVariables);
+    copyExistingBuildAssets(getDistDir(), 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,
+        traceToolAvailability: traceOptions.toolAvailability,
+        cachedTraceSourceDir: getDistDir(),
+        persistOutputs: false,
+      });
+      if (record.outputs.size > 0) {
+        nextContentRecords.set(sourcePath, record);
+      }
+    }
+
+    for (const sourcePath of plan.publicToRender) {
+      nextPublicRecords.delete(sourcePath);
+      const record = createPublicRecord(sourcePath, plan.scan.publicDir);
+      nextPublicRecords.set(sourcePath, record);
+    }
+
+    const nextSnapshot = createSnapshot({
+      siteVariables,
+      assetFiles: snapshot.assetFiles,
+      navData: json('nav.json'),
+      authorsData: json('authors.json'),
+      scan: plan.scan,
+      contentRecords: nextContentRecords,
+      publicRecords: nextPublicRecords,
+    });
+
+    const linkDiagnostics = validateJsonLinks(nextSnapshot.validTargets);
+    if (linkDiagnostics.length > 0) {
+      removeDirIfExists(outputDir);
+      return { ok: false, diagnostics: linkDiagnostics };
+    }
+
+    const forceSourcePaths = new Set([
+      ...plan.contentToRender,
+      ...plan.publicToRender,
+    ]);
+    const mutations = computeMutations(
+      snapshot,
+      nextSnapshot,
+      forceSourcePaths,
+    ).map(mutation =>
+      mutation.kind === 'write'
+        ? {
+            kind: 'write' as const,
+            path: mutation.path,
+            content: mutation.content!,
+          }
+        : { kind: 'delete' as const, path: mutation.path },
+    );
+    removeDirIfExists(outputDir);
+    return {
+      ok: true,
+      snapshot: nextSnapshot,
+      commit: { kind: 'apply-mutations', rootDir: getDistDir(), mutations },
+      meta: {
+        htmlAssetsByPath: collectHtmlAssetsByPath(nextSnapshot.contentRecords),
+        siteVariables,
+      },
+    };
+  } catch (error) {
+    removeDirIfExists(outputDir);
+    return {
+      ok: false,
+      diagnostics: diagnosticsFromMessages([
+        error instanceof Error ? error.message : String(error),
+      ]),
+    };
+  }
+}

package/build/watch/compiler-types.d.ts

@@ -0,0 +1,19 @@
+import type { SiteVariables, TraceToolAvailability } from '../types';
+
+export interface TraceCacheEntry {
+  manifestUrl: string;
+  highlightedSource: string;
+  totalSteps: number;
+  mtime: number;
+}
+
+export type TraceCache = Map<string, TraceCacheEntry>;
+
+export interface TadaBuildMeta {
+  htmlAssetsByPath: Map<string, string>;
+  siteVariables: SiteVariables;
+}
+
+export interface WatchTraceOptions {
+  toolAvailability: TraceToolAvailability;
+}

package/build/watch/compiler.ts

@@ -0,0 +1,112 @@
+import path from 'path';
+import { getDevSiteVariables } from '../site-variables';
+import { getJsonDataDir } from '../templates';
+import { getContentDir, getPublicDir } from '../util';
+import type {
+  ChangeBatch,
+  CompilerBuildResult,
+  CompilerPlanResult,
+  WatchCompiler,
+  WatchTarget,
+} from '../../watch/types';
+import { buildFull } from './build-full';
+import { buildIncremental } from './build-incremental';
+import type {
+  TadaBuildMeta,
+  TraceCache,
+  WatchTraceOptions,
+} from './compiler-types';
+import { checkTraceToolAvailability, isTraceSourceFile } from '../utils/trace';
+import { createTadaWatchPlan, type TadaWatchPlan } from './planner';
+import { scanProject, type TadaSnapshot, updateProjectScan } from './snapshot';
+
+export function invalidateTraceCacheForBatch(
+  traceCache: TraceCache,
+  batch: ChangeBatch,
+): void {
+  for (const change of batch.changes) {
+    const sourcePath = path.resolve(change.path);
+    if (isTraceSourceFile(sourcePath)) {
+      traceCache.delete(sourcePath);
+    }
+  }
+}
+
+export class TadaWatchCompiler
+  implements WatchCompiler<TadaSnapshot, TadaWatchPlan, TadaBuildMeta>
+{
+  private wsPort: number;
+  private traceCache: TraceCache;
+  private traceOptions: WatchTraceOptions;
+
+  constructor({ wsPort }: { wsPort: number }) {
+    this.wsPort = wsPort;
+    this.traceCache = new Map();
+    this.traceOptions = { toolAvailability: checkTraceToolAvailability() };
+  }
+
+  getWatchTargets(): WatchTarget[] {
+    const contentDir = getContentDir();
+    const publicDir = getPublicDir();
+    const jsonDataDir = path.resolve(getJsonDataDir());
+    const configFilePaths = new Set([
+      path.resolve('site.dev.json'),
+      path.resolve(jsonDataDir, 'nav.json'),
+      path.resolve(jsonDataDir, 'authors.json'),
+    ]);
+
+    return [
+      { path: contentDir },
+      { path: publicDir },
+      {
+        path: jsonDataDir,
+        chokidar: { depth: 0 },
+        filter: filePath => configFilePaths.has(path.resolve(filePath)),
+      },
+    ];
+  }
+
+  async buildInitial(): Promise<
+    CompilerBuildResult<TadaSnapshot, TadaBuildMeta>
+  > {
+    return buildFull({
+      wsPort: this.wsPort,
+      traceCache: this.traceCache,
+      traceOptions: this.traceOptions,
+    });
+  }
+
+  async plan(
+    snapshot: TadaSnapshot | undefined,
+    batch: ChangeBatch,
+  ): Promise<CompilerPlanResult<TadaWatchPlan>> {
+    invalidateTraceCacheForBatch(this.traceCache, batch);
+    const scan = snapshot
+      ? updateProjectScan(snapshot, batch)
+      : scanProject(getDevSiteVariables());
+    return {
+      kind: 'build',
+      plan: createTadaWatchPlan({ snapshot, batch, scan }),
+    };
+  }
+
+  async run(
+    plan: TadaWatchPlan,
+    snapshot: TadaSnapshot | undefined,
+  ): Promise<CompilerBuildResult<TadaSnapshot, TadaBuildMeta>> {
+    if (plan.kind === 'full' || !snapshot) {
+      return buildFull({
+        wsPort: this.wsPort,
+        traceCache: this.traceCache,
+        traceOptions: this.traceOptions,
+      });
+    }
+
+    return buildIncremental({
+      plan,
+      snapshot,
+      traceCache: this.traceCache,
+      traceOptions: this.traceOptions,
+    });
+  }
+}

package/build/watch/index.ts

@@ -0,0 +1,22 @@
+import { getDistDir } from '../util';
+import { runWatchEngine } from '../../watch/engine';
+import { TadaWatchCompiler } from './compiler';
+import { TadaWatchRuntime } from './runtime';
+
+export async function runWatch(options: {
+  httpPort?: number;
+  wsPort?: number;
+}): Promise<void> {
+  const wsPort = options.wsPort ?? 35729;
+  const runtime = new TadaWatchRuntime({
+    wsPort,
+    httpPort: options.httpPort,
+    distDir: getDistDir(),
+  });
+
+  await runWatchEngine({
+    compiler: new TadaWatchCompiler({ wsPort }),
+    onEvent: event => runtime.onEvent(event),
+    debounceMs: 300,
+  });
+}

package/build/watch/mutations.ts

@@ -0,0 +1,75 @@
+import type { TadaSnapshot } from './snapshot';
+
+function outputsEqual(
+  left: string | Buffer | undefined,
+  right: string | Buffer | undefined,
+): boolean {
+  if (left === undefined || right === undefined) {
+    return left === right;
+  }
+  if (typeof left === 'string' && typeof right === 'string') {
+    return left === right;
+  }
+  const leftBuffer = typeof left === 'string' ? Buffer.from(left) : left;
+  const rightBuffer = typeof right === 'string' ? Buffer.from(right) : right;
+  return Buffer.compare(leftBuffer, rightBuffer) === 0;
+}
+
+export function computeMutations(
+  previous: TadaSnapshot,
+  next: TadaSnapshot,
+  forceSourcePaths: Set<string> = new Set(),
+): { path: string; kind: 'write' | 'delete'; content?: string | Buffer }[] {
+  const mutations: {
+    path: string;
+    kind: 'write' | 'delete';
+    content?: string | Buffer;
+  }[] = [];
+  const allPaths = new Set([
+    ...previous.outputOwners.keys(),
+    ...next.outputOwners.keys(),
+  ]);
+
+  for (const outputPath of [...allPaths].sort()) {
+    const previousOwner = previous.outputOwners.get(outputPath);
+    const nextOwner = next.outputOwners.get(outputPath);
+
+    const previousContent =
+      previousOwner?.kind === 'content'
+        ? previous.contentRecords
+            .get(previousOwner.sourcePath)
+            ?.outputs.get(outputPath)
+        : previousOwner
+          ? previous.publicRecords
+              .get(previousOwner.sourcePath)
+              ?.outputs.get(outputPath)
+          : undefined;
+    const nextContent =
+      nextOwner?.kind === 'content'
+        ? next.contentRecords.get(nextOwner.sourcePath)?.outputs.get(outputPath)
+        : nextOwner
+          ? next.publicRecords
+              .get(nextOwner.sourcePath)
+              ?.outputs.get(outputPath)
+          : undefined;
+
+    if (!nextOwner) {
+      mutations.push({ path: outputPath, kind: 'delete' });
+      continue;
+    }
+
+    if (
+      !previousOwner ||
+      !outputsEqual(previousContent, nextContent) ||
+      forceSourcePaths.has(nextOwner.sourcePath)
+    ) {
+      mutations.push({
+        path: outputPath,
+        kind: 'write',
+        content: nextContent!,
+      });
+    }
+  }
+
+  return mutations;
+}