@abreen/tada 1.9.0 → 1.10.1

package/src/validators.ts

@@ -0,0 +1,45 @@
+export interface ResponseValidators {
+  etag: string | null;
+  lastModified: string | null;
+}
+
+export const EMPTY_RESPONSE_VALIDATORS: ResponseValidators = Object.freeze({
+  etag: null,
+  lastModified: null,
+});
+
+export function getResponseValidators(source: {
+  headers: { get(name: string): string | null };
+}): ResponseValidators {
+  return {
+    etag: source.headers.get('ETag'),
+    lastModified: source.headers.get('Last-Modified'),
+  };
+}
+
+export function hasUsableResponseValidators(
+  validators: ResponseValidators,
+): boolean {
+  return validators.etag !== null || validators.lastModified !== null;
+}
+
+export function hasResponseValidatorsChanged(
+  previous: ResponseValidators,
+  current: ResponseValidators,
+): boolean {
+  if (previous.etag !== null && current.etag !== null) {
+    return current.etag !== previous.etag;
+  }
+
+  if (previous.lastModified !== null && current.lastModified !== null) {
+    return current.lastModified !== previous.lastModified;
+  }
+
+  return false;
+}
+
+export function getPreferredValidatorKey(
+  validators: ResponseValidators,
+): string | null {
+  return validators.etag ?? validators.lastModified;
+}

package/templates/_footer.html

@@ -1,5 +1,5 @@
 <% if (site.features.footer) { %>
 <footer data-pagefind-ignore>
-  <p>Generated by <a href="https://github.com/abreen/Tada" target="_blank">Tada</a> <%= tadaVersion %></p>
+  <p>Built using <a href="https://github.com/abreen/Tada" target="_blank">Tada</a> <%= tadaVersion %></p>
 </footer>
 <% } %>

package/templates/_theme.scss

@@ -6,11 +6,9 @@
   // Background & foreground color tint
   --tint-hue: <%= tintHue %>deg;
   --tint-amount: <%= tintAmount / 100 %>;
-
   --link-active-color: #000;
-
-  --warning-bg-color: hsl(36 95% 70%);
-  --note-bg-color: hsl(209 95% 75%);
+  --warning-bg-color: hsl(36deg 95% 70%);
+  --note-bg-color: hsl(209deg 95% 75%);
 
   // Main foreground color (the color of most text)
   --fg-color: hsl(var(--tint-hue) calc(8% * var(--tint-amount)) 8%);
@@ -20,7 +18,6 @@
 
   // Secondary foreground color (lighter)
   --fg2-color: hsl(var(--tint-hue) calc(6% * var(--tint-amount)) 45%);
-
   --link-color: <%= linkColor %>;
   --link-color-hover: <%= linkColorHover %>;
 
@@ -35,24 +32,20 @@
   --bg2-color-translucent: hsl(
     var(--tint-hue) calc(12% * var(--tint-amount)) 92% / 66%
   );
-
   --box-shadow: 0 2px 9px
     hsl(var(--tint-hue) calc(85% * var(--tint-amount)) 10% / 25%);
   --backdrop-filter: blur(10px);
-
   --font:
-    'Inter', -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Helvetica,
-    Arial, sans-serif, 'Apple Color Emoji', 'Segoe UI Emoji', 'Segoe UI Symbol';
+    'Inter', -apple-system, 'BlinkMacSystemFont', 'Segoe UI', 'Roboto',
+    'Helvetica', 'Arial', sans-serif, 'Apple Color Emoji', 'Segoe UI Emoji',
+    'Segoe UI Symbol';
   --heading-font: var(--font);
-  --mono-font: 'Google Sans Code', Consolas, Courier, monospace;
-
+  --mono-font: 'Google Sans Code', 'Consolas', 'Courier', monospace;
   --font-size: 16px;
   --font-size-smaller: 15px;
   --font-size-small: 13px;
-
   --font-weight: 400;
   --line-height: 1.7;
-
   --mono-font-size: 0.94em;
   --mono-line-height: 1.5;
   --mono-border-radius: 0.375em;
@@ -77,7 +70,6 @@
     --theme-color: <%= themeColorDark %>;
     --theme-color-text: <%= themeColorTextDark %>;
     --text-on-theme: <%= textOnThemeDark %>;
-
     --fg-color: hsl(var(--tint-hue) calc(10% * var(--tint-amount)) 92%);
     --fg-color-translucent: hsl(
       var(--tint-hue) calc(85% * var(--tint-amount)) 90% / 33%
@@ -93,14 +85,11 @@
     --bg2-color-translucent: hsl(
       var(--tint-hue) calc(12% * var(--tint-amount)) 12% / 66%
     );
-
     --box-shadow: 0 3px 8px
       hsl(var(--tint-hue) calc(33% * var(--tint-amount)) 8% / 70%);
-
     --link-active-color: #fff;
-
-    --warning-bg-color: hsl(36 77% 27%);
-    --note-bg-color: hsl(209 90% 25%);
+    --warning-bg-color: hsl(36deg 77% 27%);
+    --note-bg-color: hsl(209deg 90% 25%);
 
     // SVG icons (dark overrides)
     --icon-search: url("data:image/svg+xml;utf8,<svg xmlns='http://www.w3.org/2000/svg' width='16' height='16' viewBox='0 0 24 24'><circle cx='11' cy='11' r='7' stroke='<%= iconColorDark %>' stroke-width='2' fill='none'/><line x1='16.5' y1='16.5' x2='22' y2='22' stroke='<%= iconColorDark %>' stroke-width='2' stroke-linecap='round'/></svg>");

package/watch/engine.ts

@@ -0,0 +1,296 @@
+import chokidar from 'chokidar';
+import { applyCommitPlan } from './fs-commit';
+import { emitWatchEvent } from './events';
+import type {
+  ChangeBatch,
+  CompilerBuildResult,
+  CompilerPlanResult,
+  WatchEngineOptions,
+  WatchEventKind,
+} from './types';
+
+function normalizeBatch(changes: Map<string, WatchEventKind>): ChangeBatch {
+  return {
+    changes: [...changes.entries()]
+      .sort(([a], [b]) => a.localeCompare(b))
+      .map(([path, kind]) => ({ path, 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) }];
+}
+
+function isNoopCommit(commit: {
+  kind: string;
+  mutations?: unknown[];
+}): boolean {
+  return (
+    commit.kind === 'apply-mutations' && (commit.mutations?.length ?? 0) === 0
+  );
+}
+
+type BuildAttemptOutcome<Snapshot, Meta> =
+  | { kind: 'skipped'; batch: ChangeBatch; initial: boolean }
+  | {
+      kind: 'succeeded';
+      batch?: ChangeBatch;
+      initial: boolean;
+      result: Extract<CompilerBuildResult<Snapshot, Meta>, { ok: true }>;
+    }
+  | {
+      kind: 'failed';
+      batch?: ChangeBatch;
+      initial: boolean;
+      diagnostics: { message: string }[];
+      meta?: Meta;
+    };
+
+export async function runWatchEngine<Snapshot, Plan, Meta>(
+  options: WatchEngineOptions<Snapshot, Plan, Meta>,
+): Promise<void> {
+  const debounceMs = options.debounceMs ?? 300;
+  let snapshot: Snapshot | undefined;
+  let pending = new Map<string, WatchEventKind>();
+  let blocked = new Map<string, WatchEventKind>();
+  let timer: ReturnType<typeof setTimeout> | null = null;
+  let running = false;
+
+  async function waitForQuietPeriod(): Promise<void> {
+    await new Promise(resolve => setTimeout(resolve, debounceMs));
+  }
+
+  async function runBuild(
+    batch?: ChangeBatch,
+    initial: boolean = false,
+  ): Promise<BuildAttemptOutcome<Snapshot, Meta>> {
+    await emitWatchEvent(options, { kind: 'build-started', batch, initial });
+    try {
+      let result: CompilerBuildResult<Snapshot, Meta> | null = null;
+      if (initial) {
+        result = await options.compiler.buildInitial();
+      } else if (batch) {
+        const nextPlan: CompilerPlanResult<Plan> = await options.compiler.plan(
+          snapshot,
+          batch,
+        );
+        if (nextPlan.kind === 'skip') {
+          return { kind: 'skipped', batch, initial };
+        }
+        result = await options.compiler.run(nextPlan.plan, snapshot);
+      }
+      if (!result) {
+        return { kind: 'skipped', batch: batch!, initial };
+      }
+
+      if (result.ok) {
+        return { kind: 'succeeded', batch, initial, result };
+      }
+
+      return {
+        kind: 'failed',
+        batch,
+        initial,
+        diagnostics: result.diagnostics,
+        meta: result.meta,
+      };
+    } catch (error) {
+      return {
+        kind: 'failed',
+        batch,
+        initial,
+        diagnostics: toDiagnostics(error),
+      };
+    }
+  }
+
+  async function flush(): Promise<void> {
+    if (running) {
+      return;
+    }
+    running = true;
+    try {
+      let finalSuccess:
+        | {
+            batch?: ChangeBatch;
+            initial: boolean;
+            result: Extract<CompilerBuildResult<Snapshot, Meta>, { ok: true }>;
+            changed: boolean;
+          }
+        | undefined;
+
+      while (pending.size > 0) {
+        const batch = normalizeBatch(pending);
+        pending = new Map();
+        const outcome = await runBuild(batch, false);
+
+        if (outcome.kind === 'skipped') {
+          if (pending.size === 0 && !finalSuccess) {
+            await emitWatchEvent(options, {
+              kind: 'build-skipped',
+              batch: outcome.batch,
+            });
+          }
+          continue;
+        }
+
+        if (outcome.kind === 'failed') {
+          await emitWatchEvent(options, {
+            kind: 'build-failed',
+            initial: outcome.initial,
+            batch: outcome.batch,
+            diagnostics: outcome.diagnostics,
+            meta: outcome.meta,
+          });
+          if (outcome.batch) {
+            for (const change of outcome.batch.changes) {
+              blocked.set(
+                change.path,
+                mergeChangeKind(blocked.get(change.path), change.kind),
+              );
+            }
+          }
+          return;
+        }
+
+        const changed = !isNoopCommit(outcome.result.commit);
+        if (changed) {
+          applyCommitPlan(outcome.result.commit);
+        }
+        snapshot = outcome.result.snapshot;
+        finalSuccess = {
+          batch: outcome.batch,
+          initial: outcome.initial,
+          result: outcome.result,
+          changed: (finalSuccess?.changed ?? false) || changed,
+        };
+
+        if (pending.size === 0) {
+          await waitForQuietPeriod();
+        }
+      }
+
+      if (finalSuccess) {
+        await emitWatchEvent(options, {
+          kind: 'build-succeeded',
+          initial: finalSuccess.initial,
+          batch: finalSuccess.batch,
+          changed: finalSuccess.changed,
+          snapshot: finalSuccess.result.snapshot,
+          meta: finalSuccess.result.meta,
+          diagnostics: finalSuccess.result.diagnostics || [],
+        });
+      }
+    } 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 {
+    if (blocked.size > 0) {
+      for (const [blockedPath, blockedKind] of blocked) {
+        pending.set(
+          blockedPath,
+          mergeChangeKind(pending.get(blockedPath), blockedKind),
+        );
+      }
+      blocked = new Map();
+    }
+    pending.set(filePath, mergeChangeKind(pending.get(filePath), kind));
+    schedule();
+  }
+
+  const initialOutcome = await runBuild(undefined, true);
+  if (initialOutcome.kind === 'failed') {
+    await emitWatchEvent(options, {
+      kind: 'build-failed',
+      initial: true,
+      diagnostics: initialOutcome.diagnostics,
+      meta: initialOutcome.meta,
+    });
+  } else if (initialOutcome.kind === 'succeeded') {
+    applyCommitPlan(initialOutcome.result.commit);
+    snapshot = initialOutcome.result.snapshot;
+    await emitWatchEvent(options, {
+      kind: 'build-succeeded',
+      initial: true,
+      changed: !isNoopCommit(initialOutcome.result.commit),
+      snapshot: initialOutcome.result.snapshot,
+      meta: initialOutcome.result.meta,
+      diagnostics: initialOutcome.result.diagnostics || [],
+    });
+  }
+
+  const watcherEntries = options.compiler
+    .getWatchTargets()
+    .map(target => ({
+      target,
+      watcher: chokidar.watch(target.path, {
+        ignoreInitial: true,
+        atomic: true,
+        awaitWriteFinish: { stabilityThreshold: 100 },
+        depth: target.chokidar?.depth,
+      }),
+    }));
+
+  let readyCount = 0;
+  const readyGoal = watcherEntries.length;
+  const onReady = async () => {
+    readyCount += 1;
+    if (readyCount === readyGoal) {
+      await emitWatchEvent(options, { 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/events.ts

@@ -0,0 +1,10 @@
+import type { WatchEngineOptions, WatchLifecycleEvent } from './types';
+
+export async function emitWatchEvent<Snapshot, Plan, Meta>(
+  options: WatchEngineOptions<Snapshot, Plan, Meta>,
+  event: WatchLifecycleEvent<Snapshot, Meta>,
+): Promise<void> {
+  if (options.onEvent) {
+    await options.onEvent(event);
+  }
+}

package/watch/fs-commit.ts

@@ -0,0 +1,102 @@
+import fs from 'fs';
+import path from 'path';
+import type {
+  ApplyMutationsCommitPlan,
+  CommitPlan,
+  FileMutation,
+  ReplaceRootCommitPlan,
+} from './types';
+
+function removeDirIfExists(dir: string): void {
+  fs.rmSync(dir, { recursive: true, force: true });
+}
+
+function ensureParentDir(filePath: string): void {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+}
+
+function pruneEmptyDirs(rootDir: string, filePath: string): void {
+  let currentDir = path.dirname(filePath);
+  const root = path.resolve(rootDir);
+  while (currentDir !== root) {
+    try {
+      fs.rmdirSync(currentDir);
+    } catch (err) {
+      const code = (err as NodeJS.ErrnoException).code;
+      if (code === 'ENOTEMPTY' || code === 'ENOENT') {
+        break;
+      }
+      throw err;
+    }
+    currentDir = path.dirname(currentDir);
+  }
+}
+
+function applyFileMutation(
+  rootDir: string,
+  mutation: FileMutation,
+  stagedRoot: string,
+): void {
+  const targetPath = path.join(rootDir, mutation.path);
+  const stagedPath = path.join(stagedRoot, mutation.path);
+
+  if (mutation.kind === 'write') {
+    ensureParentDir(stagedPath);
+    fs.writeFileSync(stagedPath, mutation.content);
+    ensureParentDir(targetPath);
+    fs.renameSync(stagedPath, targetPath);
+    return;
+  }
+
+  fs.rmSync(targetPath, { force: true });
+  pruneEmptyDirs(rootDir, targetPath);
+}
+
+function applyMutations(plan: ApplyMutationsCommitPlan): void {
+  const stagedRoot = fs.mkdtempSync(path.join(plan.rootDir, '.watch-stage-'));
+  try {
+    for (const mutation of plan.mutations) {
+      if (mutation.kind === 'write') {
+        const stagedPath = path.join(stagedRoot, mutation.path);
+        ensureParentDir(stagedPath);
+        fs.writeFileSync(stagedPath, mutation.content);
+      }
+    }
+
+    for (const mutation of plan.mutations) {
+      applyFileMutation(plan.rootDir, mutation, stagedRoot);
+    }
+  } finally {
+    removeDirIfExists(stagedRoot);
+  }
+}
+
+function replaceRoot(plan: ReplaceRootCommitPlan): void {
+  const { targetPath, stagedPath } = plan;
+  const backupDir = `${targetPath}.bak-${process.pid}-${Date.now()}`;
+  const targetExists = fs.existsSync(targetPath);
+
+  try {
+    if (targetExists) {
+      fs.renameSync(targetPath, backupDir);
+    }
+    fs.renameSync(stagedPath, targetPath);
+    if (targetExists) {
+      removeDirIfExists(backupDir);
+    }
+  } catch (err) {
+    if (!fs.existsSync(targetPath) && fs.existsSync(backupDir)) {
+      fs.renameSync(backupDir, targetPath);
+    }
+    throw err;
+  }
+}
+
+export function applyCommitPlan(plan: CommitPlan): void {
+  if (plan.kind === 'replace-root') {
+    replaceRoot(plan);
+    return;
+  }
+
+  applyMutations(plan);
+}

package/watch/types.d.ts

@@ -0,0 +1,103 @@
+export type WatchEventKind = 'add' | 'change' | 'unlink';
+
+export interface FileChange {
+  path: string;
+  kind: WatchEventKind;
+}
+
+export interface ChangeBatch {
+  changes: FileChange[];
+}
+
+export interface WatchTarget {
+  path: string;
+  chokidar?: { depth?: number };
+  filter?: (filePath: string) => boolean;
+}
+
+export interface WatchDiagnostic {
+  message: string;
+}
+
+export interface WriteFileMutation {
+  kind: 'write';
+  path: string;
+  content: string | Buffer;
+}
+
+export interface DeleteFileMutation {
+  kind: 'delete';
+  path: string;
+}
+
+export type FileMutation = WriteFileMutation | DeleteFileMutation;
+
+export interface ReplaceRootCommitPlan {
+  kind: 'replace-root';
+  stagedPath: string;
+  targetPath: string;
+}
+
+export interface ApplyMutationsCommitPlan {
+  kind: 'apply-mutations';
+  rootDir: string;
+  mutations: FileMutation[];
+}
+
+export type CommitPlan = ReplaceRootCommitPlan | ApplyMutationsCommitPlan;
+
+export type CompilerPlanResult<Plan> =
+  | { kind: 'skip' }
+  | { kind: 'build'; plan: Plan };
+
+export type CompilerBuildResult<Snapshot, Meta> =
+  | {
+      ok: true;
+      snapshot: Snapshot;
+      commit: CommitPlan;
+      diagnostics?: WatchDiagnostic[];
+      meta?: Meta;
+    }
+  | { ok: false; diagnostics: WatchDiagnostic[]; meta?: Meta };
+
+export interface WatchCompiler<Snapshot, Plan, Meta> {
+  getWatchTargets(): WatchTarget[];
+  buildInitial(): Promise<CompilerBuildResult<Snapshot, Meta>>;
+  plan(
+    snapshot: Snapshot | undefined,
+    batch: ChangeBatch,
+  ): Promise<CompilerPlanResult<Plan>>;
+  run(
+    plan: Plan,
+    snapshot: Snapshot | undefined,
+  ): Promise<CompilerBuildResult<Snapshot, Meta>>;
+}
+
+export type WatchLifecycleEvent<Snapshot, Meta> =
+  | { kind: 'watching' }
+  | { kind: 'build-started'; batch?: ChangeBatch; initial: boolean }
+  | {
+      kind: 'build-succeeded';
+      initial: boolean;
+      batch?: ChangeBatch;
+      changed: boolean;
+      snapshot: Snapshot;
+      meta?: Meta;
+      diagnostics: WatchDiagnostic[];
+    }
+  | {
+      kind: 'build-failed';
+      initial: boolean;
+      batch?: ChangeBatch;
+      diagnostics: WatchDiagnostic[];
+      meta?: Meta;
+    }
+  | { kind: 'build-skipped'; batch: ChangeBatch };
+
+export interface WatchEngineOptions<Snapshot, Plan, Meta> {
+  compiler: WatchCompiler<Snapshot, Plan, Meta>;
+  debounceMs?: number;
+  onEvent?: (
+    event: WatchLifecycleEvent<Snapshot, Meta>,
+  ) => void | Promise<void>;
+}