Cache Twoslash results across documentation builds

.github/actions/cache-docs/action.yaml

@@ -0,0 +1,19 @@
+name: Cache documentation build
+description: Restore the VitePress and Twoslash build caches
+
+runs:
+  using: composite
+  steps:
+  - id: cache-key
+    shell: bash
+    run: |
+      namespace=$(node --input-type=module --eval \
+        "import { getFedifyTwoslashCacheNamespace } from './docs/.vitepress/twoslash-cache.mts'; console.log(getFedifyTwoslashCacheNamespace());")
+      echo "namespace=$namespace" >> "$GITHUB_OUTPUT"
+      echo "docs-tree=$(git rev-parse HEAD:docs)" >> "$GITHUB_OUTPUT"
+  - uses: actions/cache@v6
+    with:
+      path: docs/.vitepress/cache
+      key: ${{ runner.os }}-${{ runner.arch }}-vitepress-${{ steps.cache-key.outputs.namespace }}-${{ steps.cache-key.outputs.docs-tree }}
+      restore-keys: |
+        ${{ runner.os }}-${{ runner.arch }}-vitepress-${{ steps.cache-key.outputs.namespace }}-

.github/workflows/main.yaml

@@ -292,6 +292,7 @@ jobs:
     steps:
     - uses: actions/checkout@v6
     - uses: ./.github/actions/setup-mise
+    - uses: ./.github/actions/cache-docs
     - run: pnpm run build
       working-directory: ${{ github.workspace }}/docs/
     - uses: actions/upload-artifact@v7
@@ -497,6 +498,7 @@ jobs:
     steps:
     - uses: actions/checkout@v6
     - uses: ./.github/actions/setup-mise
+    - uses: ./.github/actions/cache-docs
     - run: |
         set -ex
         if [[ "$GITHUB_REF_TYPE" = "tag" ]]; then

docs/.vitepress/config.mts

@@ -14,6 +14,7 @@ import {
 } from "vitepress-plugin-group-icons";
 import llmstxt from "vitepress-plugin-llms";
 import { withMermaid } from "vitepress-plugin-mermaid";
+import { createFedifyTwoslashCache } from "./twoslash-cache.mts";
 
 const jsrRefVersion = process.env.JSR_REF_VERSION ?? "unstable";
 
@@ -355,6 +356,7 @@ export default withMermaid(defineConfig({
     ],
     codeTransformers: [
       transformerTwoslash({
+        typesCache: createFedifyTwoslashCache(),
         twoslashOptions: {
           compilerOptions: {
             moduleResolution: ModuleResolutionKind.Bundler,

docs/.vitepress/twoslash-cache.mts

@@ -0,0 +1,171 @@
+import { createFileSystemTypesCache } from "@shikijs/vitepress-twoslash/cache-fs";
+import { createHash } from "node:crypto";
+import {
+  existsSync,
+  type Dirent,
+  readdirSync,
+  readFileSync,
+  rmSync,
+} from "node:fs";
+import { join, relative, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const cacheFormatVersion = 1;
+const docsDir = fileURLToPath(new URL("../", import.meta.url));
+const repositoryDir = fileURLToPath(new URL("../../", import.meta.url));
+
+function isDeclarationFile(path: string): boolean {
+  return path.endsWith(".d.ts") ||
+    path.endsWith(".d.mts") ||
+    path.endsWith(".d.cts");
+}
+
+function collectDeclarationFiles(directory: string): string[] {
+  if (!existsSync(directory)) return [];
+
+  const files: string[] = [];
+  const entries = readdirSync(directory, { withFileTypes: true });
+  for (const entry of entries) {
+    if (entry.name === "node_modules") continue;
+
+    const path = join(directory, entry.name);
+    if (entry.isDirectory()) {
+      files.push(...collectDeclarationFiles(path));
+    } else if (entry.isFile() && isDeclarationFile(path)) {
+      files.push(path);
+    }
+  }
+  return files;
+}
+
+function getPackageDirectories(): string[] {
+  const packagesDir = join(repositoryDir, "packages");
+  return readdirSync(packagesDir, { withFileTypes: true })
+    .filter((entry: Dirent) => entry.isDirectory())
+    .map((entry: Dirent) => join(packagesDir, entry.name));
+}
+
+function getTypeEnvironmentFiles(): string[] {
+  const files = [
+    fileURLToPath(import.meta.url),
+    join(repositoryDir, "deno.json"),
+    join(repositoryDir, "package.json"),
+    join(repositoryDir, "pnpm-lock.yaml"),
+    join(repositoryDir, "pnpm-workspace.yaml"),
+    join(docsDir, "package.json"),
+    join(docsDir, ".vitepress", "config.mts"),
+  ];
+
+  for (const packageDir of getPackageDirectories()) {
+    const packageJson = join(packageDir, "package.json");
+    if (existsSync(packageJson)) files.push(packageJson);
+    files.push(...collectDeclarationFiles(join(packageDir, "dist")));
+  }
+
+  return files.sort();
+}
+
+export function getFedifyTwoslashCacheNamespace(): string {
+  const hash = createHash("sha256");
+  hash.update(`fedify-twoslash-cache:${cacheFormatVersion}\0`);
+  hash.update(`${process.platform}:${process.arch}:${process.versions.node}\0`);
+
+  for (const path of getTypeEnvironmentFiles()) {
+    hash.update(relative(repositoryDir, path));
+    hash.update("\0");
+    hash.update(readFileSync(path));
+    hash.update("\0");
+  }
+
+  return hash.digest("hex");
+}
+
+function normalizeForCacheKey(
+  value: unknown,
+  seen: WeakSet<object>,
+): unknown {
+  if (typeof value === "bigint") return `${value}n`;
+  if (typeof value === "function") return value.toString();
+  if (typeof value === "symbol") return value.toString();
+  if (value == null || typeof value !== "object") return value;
+  if (seen.has(value)) return "[Circular]";
+  seen.add(value);
+
+  if (Array.isArray(value)) {
+    return value.map((item) => normalizeForCacheKey(item, seen));
+  }
+  if (value instanceof Map) {
+    return Array.from(value.entries())
+      .map(([key, item]) => [
+        normalizeForCacheKey(key, seen),
+        normalizeForCacheKey(item, seen),
+      ])
+      .sort(([left], [right]) =>
+        JSON.stringify(left).localeCompare(JSON.stringify(right))
+      );
+  }
+  if (value instanceof Set) {
+    return Array.from(value.values())
+      .map((item) => normalizeForCacheKey(item, seen))
+      .sort((left, right) =>
+        JSON.stringify(left).localeCompare(JSON.stringify(right))
+      );
+  }
+
+  return Object.fromEntries(
+    Object.entries(value)
+      .sort(([left], [right]) => left.localeCompare(right))
+      .map(([key, item]) => [key, normalizeForCacheKey(item, seen)]),
+  );
+}
+
+function getEntryCacheKey(
+  code: string,
+  lang: string | undefined,
+  options: unknown,
+): string {
+  return JSON.stringify(
+    normalizeForCacheKey(
+      { cacheFormatVersion, code, lang, options },
+      new WeakSet(),
+    ),
+  );
+}
+
+export function createFedifyTwoslashCache(): ReturnType<
+  typeof createFileSystemTypesCache
+> {
+  const namespace = getFedifyTwoslashCacheNamespace();
+  const cacheRoot = resolve(docsDir, ".vitepress", "cache", "twoslash");
+  const cacheDir = join(cacheRoot, namespace);
+
+  // Restored CI caches can contain obsolete type environments.  Keeping only
+  // the current one prevents the cache artifact from growing without bound.
+  if (existsSync(cacheRoot)) {
+    for (const entry of readdirSync(cacheRoot, { withFileTypes: true })) {
+      if (entry.name !== namespace) {
+        rmSync(join(cacheRoot, entry.name), { recursive: true, force: true });
+      }
+    }
+  }
+
+  const cache = createFileSystemTypesCache({
+    dir: cacheDir,
+  });
+
+  return {
+    init: cache.init,
+    read(code, lang, options, meta) {
+      return cache.read(getEntryCacheKey(code, lang, options), lang, options, meta);
+    },
+    write(code, data, lang, options, meta) {
+      cache.write(
+        getEntryCacheKey(code, lang, options),
+        data,
+        lang,
+        options,
+        meta,
+      );
+    },
+  };
+}

docs/package.json

@@ -42,7 +42,7 @@
     "@opentelemetry/sdk-node": "catalog:",
     "@opentelemetry/sdk-trace-base": "catalog:",
     "@sentry/node": "^8.47.0",
-    "@shikijs/vitepress-twoslash": "^3.23.0",
+    "@shikijs/vitepress-twoslash": "^4.3.1",
     "@teidesu/deno-types": "^2.1.4",
     "@types/amqplib": "catalog:",
     "@types/better-sqlite3": "catalog:",
@@ -71,10 +71,11 @@
     "stringify-entities": "^4.0.4",
     "temporal-polyfill": "catalog:",
     "typescript": "catalog:",
-    "vitepress": "^2.0.0-alpha.17",
+    "vitepress": "^2.0.0-alpha.18",
     "vitepress-plugin-group-icons": "^1.7.5",
     "vitepress-plugin-llms": "^1.13.1",
     "vitepress-plugin-mermaid": "^2.0.17",
+    "vue": "^3.5.40",
     "x-forwarded-fetch": "^0.2.0"
   },
   "scripts": {