@abreen/tada 1.13.7 → 1.14.1

package/build/watch/build-incremental.ts

@@ -1,32 +1,23 @@
 import { compileTemplates, config } from '../templates';
 import { getDistDir } from '../util';
-import { createContentRecord, createPublicRecord } from '../source-records';
-import type { CompilerBuildResult } from '../../watch/types';
-import type {
-  TadaBuildMeta,
-  TraceCache,
-  WatchTraceOptions,
-} from './compiler-types';
-import type { TadaWatchPlan } from './planner';
-import {
-  collectHtmlAnalysisByPath,
-  collectHtmlAssetsByPath,
-  createSnapshot,
-  type TadaSnapshot,
-} from './snapshot';
+import type { CompilerBuildResult } from './types';
+import type { TraceCache, WatchTraceOptions } from './compiler-types';
+import type { TadaIncrementalWatchPlan } from './planner';
+import { createSnapshot, type TadaSnapshot } from './snapshot';
 import {
   copyExistingBuildAssets,
   ensureHighlighter,
   makeTempBuildDir,
   removeDirIfExists,
-  writeAssets,
 } from './assets';
 import { computeMutations } from './mutations';
+import { validateConfig, validateProjectConfigLinks } from './validation';
+import { buildFailedFromError, buildSucceeded } from './build-result';
 import {
-  diagnosticsFromMessages,
-  validateConfig,
-  validateProjectConfigLinks,
-} from './validation';
+  buildFailedWithDiagnostics,
+  renderContentRecord,
+  renderPublicRecord,
+} from './build-helpers';
 
 export async function buildIncremental({
   plan,
@@ -34,23 +25,23 @@ export async function buildIncremental({
   traceCache,
   traceOptions,
 }: {
-  plan: TadaWatchPlan;
+  plan: TadaIncrementalWatchPlan;
   snapshot: TadaSnapshot;
   traceCache: TraceCache;
   traceOptions: WatchTraceOptions;
-}): Promise<CompilerBuildResult<TadaSnapshot, TadaBuildMeta>> {
-  const outputDir = makeTempBuildDir(plan.scan.distDir);
+}): Promise<CompilerBuildResult> {
+  const distDir = getDistDir();
+  const outputDir = makeTempBuildDir(distDir);
   try {
     const siteVariables = snapshot.siteVariables;
     const configDiagnostics = validateConfig(plan.scan);
     if (configDiagnostics.length > 0) {
-      removeDirIfExists(outputDir);
-      return { ok: false, diagnostics: configDiagnostics };
+      return buildFailedWithDiagnostics(outputDir, configDiagnostics);
     }
 
     compileTemplates(siteVariables);
     await ensureHighlighter(siteVariables);
-    copyExistingBuildAssets(getDistDir(), outputDir, snapshot.assetFiles);
+    copyExistingBuildAssets(distDir, outputDir, snapshot.assetFiles);
 
     const nextContentRecords = new Map(snapshot.contentRecords);
     const nextPublicRecords = new Map(snapshot.publicRecords);
@@ -64,25 +55,27 @@ export async function buildIncremental({
 
     for (const sourcePath of plan.contentToRender) {
       nextContentRecords.delete(sourcePath);
-      const record = createContentRecord({
+      const record = renderContentRecord({
         filePath: sourcePath,
         siteVariables,
         scan: plan.scan,
         assetFiles: snapshot.assetFiles,
         outputDir,
         traceCache,
-        traceToolAvailability: traceOptions.toolAvailability,
-        cachedTraceSourceDir: getDistDir(),
+        traceOptions,
+        cachedTraceSourceDir: distDir,
       });
-      if (record.outputs.size > 0) {
-        writeAssets(outputDir, record.outputs);
+      if (record) {
         nextContentRecords.set(sourcePath, record);
       }
     }
 
     for (const sourcePath of plan.publicToRender) {
       nextPublicRecords.delete(sourcePath);
-      const record = createPublicRecord(sourcePath, plan.scan.publicDir);
+      const record = renderPublicRecord({
+        filePath: sourcePath,
+        publicDir: plan.scan.publicDir,
+      });
       nextPublicRecords.set(sourcePath, record);
     }
 
@@ -97,11 +90,10 @@ export async function buildIncremental({
     });
 
     const linkDiagnostics = validateProjectConfigLinks(
-      nextSnapshot.validTargets,
+      nextSnapshot.scan.validTargets,
     );
     if (linkDiagnostics.length > 0) {
-      removeDirIfExists(outputDir);
-      return { ok: false, diagnostics: linkDiagnostics };
+      return buildFailedWithDiagnostics(outputDir, linkDiagnostics);
     }
 
     const forceSourcePaths = new Set([
@@ -112,35 +104,15 @@ export async function buildIncremental({
       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),
-        htmlAnalysisByPath: collectHtmlAnalysisByPath(
-          nextSnapshot.contentRecords,
-        ),
-        siteVariables,
-      },
-    };
+    return buildSucceeded(nextSnapshot, {
+      kind: 'apply-mutations',
+      rootDir: distDir,
+      mutations,
+    });
   } catch (error) {
     removeDirIfExists(outputDir);
-    return {
-      ok: false,
-      diagnostics: diagnosticsFromMessages([
-        error instanceof Error ? error.message : String(error),
-      ]),
-    };
+    return buildFailedFromError(error);
   }
 }

package/build/watch/build-result.ts

@@ -0,0 +1,19 @@
+import type { CommitPlan, CompilerBuildResult } from './types';
+import { createBuildMeta, type TadaSnapshot } from './snapshot';
+import { diagnosticsFromMessages } from './validation';
+
+export function buildSucceeded(
+  snapshot: TadaSnapshot,
+  commit: CommitPlan,
+): CompilerBuildResult {
+  return { ok: true, snapshot, commit, meta: createBuildMeta(snapshot) };
+}
+
+export function buildFailedFromError(error: unknown): CompilerBuildResult {
+  return {
+    ok: false,
+    diagnostics: diagnosticsFromMessages([
+      error instanceof Error ? error.message : String(error),
+    ]),
+  };
+}

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

@@ -7,9 +7,9 @@ import type {
 export interface TraceCacheEntry {
   manifestUrl: string;
   artifactId: string;
-  highlightedSource: string;
+  highlightedSources: { file: string; highlightedSource: string }[];
   totalSteps: number;
-  mtime: number;
+  sourceMtims: Record<string, number>;
 }
 
 export type TraceCache = Map<string, TraceCacheEntry>;

package/build/watch/compiler.ts

@@ -1,30 +1,20 @@
 import path from 'path';
-import {
-  getProjectConfigBaseName,
-  getSiteConfigBaseName,
-  getSupportedConfigFilePaths,
-} from '../config-files';
-import { getDevSiteVariables } from '../site-variables';
 import { getProjectConfigDir } from '../templates';
 import { getContentDir, getPublicDir } from '../util';
 import type {
   ChangeBatch,
   CompilerBuildResult,
-  CompilerPlanResult,
   WatchCompiler,
   WatchTarget,
-} from '../../watch/types';
+} from './types';
 import { buildFull } from './build-full';
 import { buildIncremental } from './build-incremental';
-import type {
-  TadaBuildMeta,
-  TraceCache,
-  WatchTraceOptions,
-} from './compiler-types';
+import type { TraceCache, WatchTraceOptions } from './compiler-types';
 import { checkTraceToolAvailability, isTraceSourceFile } from '../utils/trace';
-import { createTadaWatchPlan, type TadaWatchPlan } from './planner';
-import { scanProject, updateProjectScan } from '../source-model';
+import { createTadaWatchPlan } from './planner';
+import { updateProjectScan } from '../source-model';
 import type { TadaSnapshot } from './snapshot';
+import { getWatchConfigFilePaths } from './config-paths';
 
 export function invalidateTraceCacheForBatch(
   traceCache: TraceCache,
@@ -33,16 +23,16 @@ export function invalidateTraceCacheForBatch(
   for (const change of batch.changes) {
     const sourcePath = path.resolve(change.path);
     if (isTraceSourceFile(sourcePath)) {
-      traceCache.delete(sourcePath);
+      for (const [cacheKey, entry] of traceCache) {
+        if (sourcePath in entry.sourceMtims) {
+          traceCache.delete(cacheKey);
+        }
+      }
     }
   }
 }
 
-export class TadaWatchCompiler implements WatchCompiler<
-  TadaSnapshot,
-  TadaWatchPlan,
-  TadaBuildMeta
-> {
+export class TadaWatchCompiler implements WatchCompiler {
   private traceCache: TraceCache;
   private traceOptions: WatchTraceOptions;
 
@@ -55,23 +45,11 @@ export class TadaWatchCompiler implements WatchCompiler<
     const contentDir = getContentDir();
     const publicDir = getPublicDir();
     const projectConfigDir = path.resolve(getProjectConfigDir());
-    const configFilePaths = new Set([
-      ...getSupportedConfigFilePaths('.', getSiteConfigBaseName('dev')).map(
-        filePath => path.resolve(filePath),
-      ),
-      ...getSupportedConfigFilePaths(
-        projectConfigDir,
-        getProjectConfigBaseName('nav'),
-      ).map(filePath => path.resolve(filePath)),
-      ...getSupportedConfigFilePaths(
-        projectConfigDir,
-        getProjectConfigBaseName('authors'),
-      ).map(filePath => path.resolve(filePath)),
-    ]);
+    const configFilePaths = getWatchConfigFilePaths();
 
     return [
-      { path: contentDir },
-      { path: publicDir },
+      { path: contentDir, chokidar: { usePolling: true } },
+      { path: publicDir, chokidar: { usePolling: true } },
       {
         path: projectConfigDir,
         chokidar: { depth: 0 },
@@ -80,34 +58,24 @@ export class TadaWatchCompiler implements WatchCompiler<
     ];
   }
 
-  async buildInitial(): Promise<
-    CompilerBuildResult<TadaSnapshot, TadaBuildMeta>
-  > {
-    return buildFull({
-      traceCache: this.traceCache,
-      traceOptions: this.traceOptions,
-    });
-  }
-
-  async plan(
+  async build(
     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 }),
-    };
-  }
+    batch?: ChangeBatch,
+  ): Promise<CompilerBuildResult> {
+    if (batch) {
+      invalidateTraceCacheForBatch(this.traceCache, batch);
+    }
 
-  async run(
-    plan: TadaWatchPlan,
-    snapshot: TadaSnapshot | undefined,
-  ): Promise<CompilerBuildResult<TadaSnapshot, TadaBuildMeta>> {
-    if (plan.kind === 'full' || !snapshot) {
+    if (!snapshot || !batch) {
+      return buildFull({
+        traceCache: this.traceCache,
+        traceOptions: this.traceOptions,
+      });
+    }
+
+    const scan = updateProjectScan(snapshot.scan, batch);
+    const plan = createTadaWatchPlan({ snapshot, batch, scan });
+    if (plan.kind === 'full') {
       return buildFull({
         traceCache: this.traceCache,
         traceOptions: this.traceOptions,

package/build/watch/config-paths.ts

@@ -0,0 +1,56 @@
+import path from 'path';
+import {
+  getProjectConfigBaseName,
+  getSiteConfigBaseName,
+  getSupportedConfigFilePaths,
+} from '../config-files';
+import { getProjectConfigDir } from '../templates';
+
+export type WatchConfigPathKind = 'site' | 'nav' | 'authors';
+
+function getConfigPathEntries(): Array<{
+  kind: WatchConfigPathKind;
+  paths: string[];
+}> {
+  const projectConfigDir = getProjectConfigDir();
+  return [
+    {
+      kind: 'site',
+      paths: getSupportedConfigFilePaths('.', getSiteConfigBaseName('dev')),
+    },
+    {
+      kind: 'nav',
+      paths: getSupportedConfigFilePaths(
+        projectConfigDir,
+        getProjectConfigBaseName('nav'),
+      ),
+    },
+    {
+      kind: 'authors',
+      paths: getSupportedConfigFilePaths(
+        projectConfigDir,
+        getProjectConfigBaseName('authors'),
+      ),
+    },
+  ];
+}
+
+function getWatchConfigPathKinds(): Map<string, WatchConfigPathKind> {
+  return new Map(
+    getConfigPathEntries().flatMap(entry =>
+      entry.paths.map(
+        filePath => [path.resolve(filePath), entry.kind] as const,
+      ),
+    ),
+  );
+}
+
+export function getWatchConfigFilePaths(): Set<string> {
+  return new Set(getWatchConfigPathKinds().keys());
+}
+
+export function classifyWatchConfigPath(
+  filePath: string,
+): WatchConfigPathKind | undefined {
+  return getWatchConfigPathKinds().get(path.resolve(filePath));
+}

package/build/watch/engine.ts

@@ -0,0 +1,199 @@
+import chokidar from 'chokidar';
+import { applyCommitPlan } from './fs-commit';
+import type {
+  ChangeBatch,
+  CompilerBuildResult,
+  WatchEngineOptions,
+  WatchEventKind,
+  WatchLifecycleEvent,
+} from './types';
+import type { TadaSnapshot } from './snapshot';
+
+function normalizeBatch(changes: Map<string, WatchEventKind>): ChangeBatch {
+  return {
+    changes: [...changes.entries()]
+      .sort(([a], [b]) => a.localeCompare(b))
+      .map(([path, kind]) => ({ path, kind })),
+  };
+}
+
+function mapBatch(batch: ChangeBatch): Map<string, WatchEventKind> {
+  return new Map(batch.changes.map(change => [change.path, change.kind]));
+}
+
+function mergeChangeKind(
+  previous: WatchEventKind | undefined,
+  next: WatchEventKind,
+): WatchEventKind {
+  if (!previous) {
+    return next;
+  }
+  if (previous === 'add' && next === 'unlink') {
+    return 'change';
+  }
+  if (previous === 'unlink' && next === 'add') {
+    return 'change';
+  }
+  if (previous === 'add' || next === 'add') {
+    return 'add';
+  }
+  if (previous === 'unlink' || next === 'unlink') {
+    return 'unlink';
+  }
+  return 'change';
+}
+
+function toDiagnostics(error: unknown): { message: string }[] {
+  if (error instanceof Error) {
+    return [{ message: error.message }];
+  }
+  return [{ message: String(error) }];
+}
+
+export async function runWatchEngine(
+  options: WatchEngineOptions,
+): Promise<void> {
+  const debounceMs = options.debounceMs ?? 300;
+  let snapshot: TadaSnapshot | undefined;
+  let uncommitted = new Map<string, WatchEventKind>();
+  let pending = new Map<string, WatchEventKind>();
+  let timer: ReturnType<typeof setTimeout> | null = null;
+  let running = false;
+
+  async function emit(event: WatchLifecycleEvent): Promise<void> {
+    await options.onEvent?.(event);
+  }
+
+  async function waitForQuietPeriod(): Promise<void> {
+    await new Promise(resolve => setTimeout(resolve, debounceMs));
+  }
+
+  async function runBuild(batch?: ChangeBatch): Promise<CompilerBuildResult> {
+    await emit({ kind: 'build-started', batch });
+    try {
+      return await options.compiler.build(snapshot, batch);
+    } catch (error) {
+      return { ok: false, diagnostics: toDiagnostics(error) };
+    }
+  }
+
+  async function flush(): Promise<void> {
+    if (running) {
+      return;
+    }
+    running = true;
+    try {
+      let finalSuccess:
+        | {
+            batch?: ChangeBatch;
+            result: Extract<CompilerBuildResult, { ok: true }>;
+          }
+        | undefined;
+
+      while (pending.size > 0) {
+        const changes = new Map(uncommitted);
+        for (const [filePath, kind] of pending) {
+          changes.set(filePath, mergeChangeKind(changes.get(filePath), kind));
+        }
+
+        const batch = normalizeBatch(changes);
+        pending = new Map();
+        const outcome = await runBuild(batch);
+
+        if (!outcome.ok) {
+          uncommitted = mapBatch(batch);
+          await emit({
+            kind: 'build-failed',
+            batch,
+            diagnostics: outcome.diagnostics,
+          });
+          return;
+        }
+
+        applyCommitPlan(outcome.commit);
+        snapshot = outcome.snapshot;
+        uncommitted = new Map();
+        finalSuccess = { batch, result: outcome };
+
+        if (pending.size === 0) {
+          await waitForQuietPeriod();
+        }
+      }
+
+      if (finalSuccess) {
+        await emit({
+          kind: 'build-succeeded',
+          batch: finalSuccess.batch,
+          meta: finalSuccess.result.meta,
+        });
+      }
+    } finally {
+      running = false;
+      if (pending.size > 0) {
+        schedule();
+      }
+    }
+  }
+
+  function schedule(): void {
+    if (timer) {
+      clearTimeout(timer);
+    }
+    timer = setTimeout(() => {
+      timer = null;
+      void flush();
+    }, debounceMs);
+  }
+
+  function onFileChange(filePath: string, kind: WatchEventKind): void {
+    pending.set(filePath, mergeChangeKind(pending.get(filePath), kind));
+    schedule();
+  }
+
+  const startupOutcome = await runBuild();
+  if (!startupOutcome.ok) {
+    await emit({
+      kind: 'build-failed',
+      diagnostics: startupOutcome.diagnostics,
+    });
+  } else {
+    applyCommitPlan(startupOutcome.commit);
+    snapshot = startupOutcome.snapshot;
+    await emit({ kind: 'build-succeeded', meta: startupOutcome.meta });
+  }
+
+  const watcherEntries = options.compiler
+    .getWatchTargets()
+    .map(target => ({
+      target,
+      watcher: chokidar.watch(target.path, {
+        ignoreInitial: true,
+        atomic: true,
+        awaitWriteFinish: { stabilityThreshold: 100 },
+        ...target.chokidar,
+      }),
+    }));
+
+  let readyCount = 0;
+  const readyGoal = watcherEntries.length;
+  const onReady = async () => {
+    readyCount += 1;
+    if (readyCount === readyGoal) {
+      await emit({ kind: 'watching' });
+    }
+  };
+
+  for (const { watcher, target } of watcherEntries) {
+    const emitIfIncluded = (filePath: string, kind: WatchEventKind) => {
+      if (!target.filter || target.filter(filePath)) {
+        onFileChange(filePath, kind);
+      }
+    };
+    watcher.on('add', filePath => emitIfIncluded(filePath, 'add'));
+    watcher.on('change', filePath => emitIfIncluded(filePath, 'change'));
+    watcher.on('unlink', filePath => emitIfIncluded(filePath, 'unlink'));
+    watcher.on('ready', () => void onReady());
+  }
+
+  return new Promise(() => {});
+}

package/{watch → build/watch}/fs-commit.ts

@@ -1,6 +1,6 @@
 import fs from 'fs';
 import path from 'path';
-import { globals, type Globals } from '../build/globals';
+import { globals, type Globals } from '../globals';
 import type {
   ApplyMutationsCommitPlan,
   CommitPlan,
@@ -87,8 +87,6 @@ function applyFileMutation(
   const stagedPath = path.join(stagedRoot, mutation.path);
 
   if (mutation.kind === 'write') {
-    ensureParentDir(stagedPath);
-    fs.writeFileSync(stagedPath, mutation.content);
     ensureParentDir(targetPath);
     renameWithRetry(stagedPath, targetPath, globals);
     return;

package/build/watch/index.ts

@@ -1,5 +1,5 @@
 import { getDistDir } from '../util';
-import { runWatchEngine } from '../../watch/engine';
+import { runWatchEngine } from './engine';
 import { TadaWatchCompiler } from './compiler';
 import { TadaWatchRuntime } from './runtime';
 

package/build/watch/mutations.ts

@@ -1,4 +1,5 @@
-import type { TadaSnapshot } from './snapshot';
+import type { FileMutation } from './types';
+import type { TadaOutputOwner, TadaSnapshot } from './snapshot';
 
 function outputsEqual(
   left: string | Buffer | undefined,
@@ -15,16 +16,25 @@ function outputsEqual(
   return Buffer.compare(leftBuffer, rightBuffer) === 0;
 }
 
+function getOutputContent(
+  snapshot: TadaSnapshot,
+  owner: TadaOutputOwner | undefined,
+  outputPath: string,
+): string | Buffer | undefined {
+  if (!owner) {
+    return undefined;
+  }
+  const records =
+    owner.kind === 'content' ? snapshot.contentRecords : snapshot.publicRecords;
+  return records.get(owner.sourcePath)?.outputs.get(outputPath);
+}
+
 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;
-  }[] = [];
+): FileMutation[] {
+  const mutations: FileMutation[] = [];
   const allPaths = new Set([
     ...previous.outputOwners.keys(),
     ...next.outputOwners.keys(),
@@ -34,24 +44,12 @@ export function computeMutations(
     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;
+    const previousContent = getOutputContent(
+      previous,
+      previousOwner,
+      outputPath,
+    );
+    const nextContent = getOutputContent(next, nextOwner, outputPath);
 
     if (!nextOwner) {
       mutations.push({ path: outputPath, kind: 'delete' });