@mui/internal-docs-infra 0.12.1-canary.6 → 0.12.1-canary.7

package/cli/loadNextConfig.d.mts

@@ -23,11 +23,20 @@ export type ExtractedNextConfigOptions = {
   descriptionReplacements?: DescriptionReplacement[];
   useVisibleDescription?: boolean;
   socketDir?: string;
+  /** Page-index cache directory configured on the sitemap loader. */
+  cacheDir?: string;
   /** Demo index patterns that opted into automatic `client.ts` generation. */
   demoClientRequirements?: DemoClientRequirement[];
   /** Demo index patterns that opted into automatic `page.tsx` generation. */
   demoPageRequirements?: DemoPageRequirement[];
 };
+/**
+ * Searches turbopack rules for docs-infra options (ordering,
+ * descriptionReplacements, socketDir, useVisibleDescription, cacheDir).
+ *
+ * Exported for tests.
+ */
+export declare function extractOptionsFromTurbopack(config: any): ExtractedNextConfigOptions;
 /**
  * Walks Turbopack rules to collect demo patterns that opted into automatic
  * `page.tsx` generation via the `requirePage` option.

package/cli/loadNextConfig.mjs

@@ -3,6 +3,7 @@ import path from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { createJiti } from 'jiti';
 const TYPES_LOADER = '@mui/internal-docs-infra/pipeline/loadPrecomputedTypes';
+const SITEMAP_LOADER = '@mui/internal-docs-infra/pipeline/loadPrecomputedSitemap';
 const CODE_HIGHLIGHTER_LOADER = '@mui/internal-docs-infra/pipeline/loadPrecomputedCodeHighlighter';
 const TRANSFORM_METADATA_PLUGIN = '@mui/internal-docs-infra/pipeline/transformMarkdownMetadata';
 const TRANSFORM_METADATA_PLUGIN_FUNCTION_NAME = 'transformMarkdownMetadata';
@@ -49,6 +50,9 @@ function extractOptionsFromLoaderEntries(loaders) {
     if (!result.socketDir && loader.loader === TYPES_LOADER && typeof loader.options?.socketDir === 'string') {
       result.socketDir = loader.options.socketDir;
     }
+    if (!result.cacheDir && loader.loader === SITEMAP_LOADER && typeof loader.options?.cacheDir === 'string') {
+      result.cacheDir = loader.options.cacheDir;
+    }
     if (result.useVisibleDescription === undefined && loader.options?.remarkPlugins) {
       const extracted = extractUseVisibleDescriptionFromRemarkPlugins(loader.options.remarkPlugins);
       if (typeof extracted === 'boolean') {
@@ -61,9 +65,11 @@ function extractOptionsFromLoaderEntries(loaders) {
 
 /**
  * Searches turbopack rules for docs-infra options (ordering,
- * descriptionReplacements, socketDir, useVisibleDescription).
+ * descriptionReplacements, socketDir, useVisibleDescription, cacheDir).
+ *
+ * Exported for tests.
  */
-function extractOptionsFromTurbopack(config) {
+export function extractOptionsFromTurbopack(config) {
   const rules = config?.turbopack?.rules;
   if (!rules) {
     return {};
@@ -79,6 +85,7 @@ function extractOptionsFromTurbopack(config) {
     merged.descriptionReplacements ??= extracted.descriptionReplacements;
     merged.useVisibleDescription ??= extracted.useVisibleDescription;
     merged.socketDir ??= extracted.socketDir;
+    merged.cacheDir ??= extracted.cacheDir;
   }
   return merged;
 }
@@ -166,6 +173,7 @@ function extractOptionsFromWebpackResult(result) {
     merged.descriptionReplacements ??= extracted.descriptionReplacements;
     merged.useVisibleDescription ??= extracted.useVisibleDescription;
     merged.socketDir ??= extracted.socketDir;
+    merged.cacheDir ??= extracted.cacheDir;
   }
   return merged;
 }
@@ -323,6 +331,7 @@ export async function extractDocsInfraOptionsFromNextConfig(dir) {
     descriptionReplacements: turbopack.descriptionReplacements ?? webpack.descriptionReplacements,
     useVisibleDescription: turbopack.useVisibleDescription ?? webpack.useVisibleDescription,
     socketDir: turbopack.socketDir ?? webpack.socketDir,
+    cacheDir: turbopack.cacheDir ?? webpack.cacheDir,
     demoClientRequirements: demoClientRequirements.length > 0 ? demoClientRequirements : undefined,
     demoPageRequirements: demoPageRequirements.length > 0 ? demoPageRequirements : undefined
   };

package/cli/runValidate.mjs

@@ -10,6 +10,7 @@ import { fileURLToPath } from 'url';
 import { Worker } from 'node:worker_threads';
 import { createPerformanceLogger, logPerformance, nameMark, performanceMeasure } from "../pipeline/loadPrecomputedCodeHighlighter/performanceLogger.mjs";
 import { terminateWorkerManager } from "../pipeline/loadServerTypesMeta/workerManager.mjs";
+import { DEFAULT_CACHE_DIR } from "../pipeline/cacheUtils/index.mjs";
 import { extractDocsInfraOptionsFromNextConfig } from "./loadNextConfig.mjs";
 import { ensureDemoClients } from "./ensureDemoClients.mjs";
 import { ensureDemoPages } from "./ensureDemoPages.mjs";
@@ -89,10 +90,14 @@ const runValidate = {
       descriptionReplacements,
       useVisibleDescription = false,
       socketDir: configSocketDir,
+      cacheDir: configCacheDir,
       demoClientRequirements = [],
       demoPageRequirements = []
     } = await extractDocsInfraOptionsFromNextConfig(cwd);
     const socketDir = configSocketDir ? path.resolve(cwd, configSocketDir) : undefined;
+    // Use the same page-index cache directory that the sitemap loader reads at build time.
+    // The index validation pass writes cache entries even when committed indexes are current.
+    const cacheDir = configCacheDir ?? DEFAULT_CACHE_DIR;
 
     // If neither flag is set, run both. If one is set, run only that one.
     const runIndexes = !typesOnly || indexesOnly;
@@ -189,8 +194,8 @@ const runValidate = {
     try {
       // === Validate page.mdx index files ===
       if (runIndexes) {
-        const markerDir = '.next/cache/docs-infra/index-updates';
-        const markerDirPath = path.join(cwd, markerDir);
+        const markerDir = path.posix.join(cacheDir, 'index-updates');
+        const markerDirPath = path.resolve(cwd, markerDir);
         try {
           await rm(markerDirPath, {
             recursive: true,
@@ -222,7 +227,8 @@ const runValidate = {
           baseDir: cwd,
           onlyUpdateIndexes: true,
           markerDir,
-          useVisibleDescription
+          useVisibleDescription,
+          cacheDir
         };
         const indexResults = await Promise.all(pageMdxFiles.map(filePath => {
           const taskId = taskIdCounter;
@@ -263,8 +269,8 @@ const runValidate = {
       // === Validate types.ts files ===
       if (runTypes) {
         // Use same marker directory structure for index updates from types
-        const typesMarkerDir = '.next/cache/docs-infra/types-index-updates';
-        const typesMarkerDirPath = path.join(cwd, typesMarkerDir);
+        const typesMarkerDir = path.posix.join(cacheDir, 'types-index-updates');
+        const typesMarkerDirPath = path.resolve(cwd, typesMarkerDir);
         try {
           await rm(typesMarkerDirPath, {
             recursive: true,
@@ -289,11 +295,13 @@ const runValidate = {
             syncTypesOptions: {
               updateParentIndex: {
                 baseDir: cwd,
-                markerDir: typesMarkerDir
+                markerDir: typesMarkerDir,
+                cacheDir
               },
               ordering,
               descriptionReplacements,
-              socketDir
+              socketDir,
+              cacheDir
             }
           });
         }));

package/cli/validateWorker.d.mts

@@ -11,6 +11,7 @@ interface IndexTask {
     onlyUpdateIndexes: boolean;
     markerDir: string;
     useVisibleDescription: boolean;
+    cacheDir?: string;
   };
 }
 interface TypesTask {

package/cli/validateWorker.mjs

@@ -74,7 +74,8 @@ if (parentPort) {
             updateParentIndex: excludeFromIndex ? undefined : task.syncTypesOptions.updateParentIndex,
             ordering: task.syncTypesOptions.ordering,
             descriptionReplacements: task.syncTypesOptions.descriptionReplacements,
-            socketDir: task.syncTypesOptions.socketDir
+            socketDir: task.syncTypesOptions.socketDir,
+            cacheDir: task.syncTypesOptions.cacheDir
           });
           parentPort.postMessage({
             type: 'types',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mui/internal-docs-infra",
-  "version": "0.12.1-canary.6",
+  "version": "0.12.1-canary.7",
   "author": "MUI Team",
   "description": "MUI Infra - internal documentation creation tools.",
   "license": "MIT",
@@ -804,5 +804,5 @@
   "bin": {
     "docs-infra": "./cli/index.mjs"
   },
-  "gitSha": "8d7deee2ae1eb5157dadfae77c6e82cc8e574687"
+  "gitSha": "0ffea436eb8e1aa519727d55d2e9a4daa0ec6ac2"
 }

package/pipeline/cacheUtils/constants.d.mts

@@ -0,0 +1,5 @@
+/**
+ * Default root directory for docs-infra build caches. Sits alongside the marker
+ * directories already written under `.next/cache/docs-infra`.
+ */
+export declare const DEFAULT_CACHE_DIR = ".next/cache/docs-infra";

package/pipeline/cacheUtils/constants.mjs

@@ -0,0 +1,5 @@
+/**
+ * Default root directory for docs-infra build caches. Sits alongside the marker
+ * directories already written under `.next/cache/docs-infra`.
+ */
+export const DEFAULT_CACHE_DIR = '.next/cache/docs-infra';

package/pipeline/cacheUtils/hashCacheContent.d.mts

@@ -0,0 +1,5 @@
+/**
+ * Computes the sha256 hex digest of cache source content. Used to validate that a
+ * cached value still matches the file it was derived from.
+ */
+export declare function hashCacheContent(content: string): string;

package/pipeline/cacheUtils/hashCacheContent.mjs

@@ -0,0 +1,9 @@
+import { createHash } from 'node:crypto';
+
+/**
+ * Computes the sha256 hex digest of cache source content. Used to validate that a
+ * cached value still matches the file it was derived from.
+ */
+export function hashCacheContent(content) {
+  return createHash('sha256').update(content).digest('hex');
+}

package/pipeline/cacheUtils/index.d.mts

@@ -0,0 +1,9 @@
+export { hashCacheContent } from "./hashCacheContent.mjs";
+export { loadFileCache } from "./loadFileCache.mjs";
+export { loadFileCacheEntry } from "./loadFileCacheEntry.mjs";
+export { saveFileCache } from "./saveFileCache.mjs";
+export { resolveCachePath } from "./resolveCachePath.mjs";
+export { withFileCache } from "./withFileCache.mjs";
+export type { FileCacheTask } from "./withFileCache.mjs";
+export { DEFAULT_CACHE_DIR } from "./constants.mjs";
+export type { FileCacheRef, FileCacheEntry } from "./types.mjs";

package/pipeline/cacheUtils/index.mjs

@@ -0,0 +1,7 @@
+export { hashCacheContent } from "./hashCacheContent.mjs";
+export { loadFileCache } from "./loadFileCache.mjs";
+export { loadFileCacheEntry } from "./loadFileCacheEntry.mjs";
+export { saveFileCache } from "./saveFileCache.mjs";
+export { resolveCachePath } from "./resolveCachePath.mjs";
+export { withFileCache } from "./withFileCache.mjs";
+export { DEFAULT_CACHE_DIR } from "./constants.mjs";

package/pipeline/cacheUtils/loadFileCache.d.mts

@@ -0,0 +1,13 @@
+import type { FileCacheRef } from "./types.mjs";
+/**
+ * Reads a cache entry and returns its data only when the stored hash matches the
+ * current content.
+ *
+ * Best-effort by design: a missing file, an unreadable file, malformed JSON, or a
+ * hash mismatch all resolve to `null` (a cache miss) rather than throwing, so a
+ * stale or corrupt cache can never break a build — it is simply recomputed.
+ *
+ * To overlap the cache read with reading the source file, use {@link loadFileCacheEntry}
+ * directly and compare the hash yourself.
+ */
+export declare function loadFileCache<T>(ref: FileCacheRef, content: string): Promise<T | null>;

package/pipeline/cacheUtils/loadFileCache.mjs

@@ -0,0 +1,20 @@
+import { hashCacheContent } from "./hashCacheContent.mjs";
+import { loadFileCacheEntry } from "./loadFileCacheEntry.mjs";
+/**
+ * Reads a cache entry and returns its data only when the stored hash matches the
+ * current content.
+ *
+ * Best-effort by design: a missing file, an unreadable file, malformed JSON, or a
+ * hash mismatch all resolve to `null` (a cache miss) rather than throwing, so a
+ * stale or corrupt cache can never break a build — it is simply recomputed.
+ *
+ * To overlap the cache read with reading the source file, use {@link loadFileCacheEntry}
+ * directly and compare the hash yourself.
+ */
+export async function loadFileCache(ref, content) {
+  const entry = await loadFileCacheEntry(ref);
+  if (!entry || entry.hash !== hashCacheContent(content)) {
+    return null;
+  }
+  return entry.data;
+}

package/pipeline/cacheUtils/loadFileCacheEntry.d.mts

@@ -0,0 +1,13 @@
+import type { FileCacheEntry, FileCacheRef } from "./types.mjs";
+/**
+ * Reads and parses a cache entry without validating it against any content.
+ *
+ * Best-effort: a missing file, an unreadable file, malformed JSON, or a path-containment failure
+ * all resolve to `null` (a cache miss) rather than throwing — so a stale or corrupt cache never
+ * breaks a build. Use this to read the cache in parallel with the source file, then compare
+ * `entry.hash` against `hashCacheContent(content)` once both reads complete.
+ *
+ * A non-missing read failure (e.g. a permissions error silently disabling the cache) is logged
+ * under DEBUG rather than masquerading as a cold cache.
+ */
+export declare function loadFileCacheEntry<T>(ref: FileCacheRef): Promise<FileCacheEntry<T> | null>;

package/pipeline/cacheUtils/loadFileCacheEntry.mjs

@@ -0,0 +1,47 @@
+import { readFile } from 'node:fs/promises';
+import { resolveCachePath } from "./resolveCachePath.mjs";
+// Set DOCS_INFRA_CACHE_DEBUG=1 to surface non-missing read failures and corrupt entries.
+const DEBUG = Boolean(process.env.DOCS_INFRA_CACHE_DEBUG);
+function isFileCacheEntry(value) {
+  return typeof value === 'object' && value !== null && 'hash' in value && 'data' in value && typeof value.hash === 'string';
+}
+
+/**
+ * Reads and parses a cache entry without validating it against any content.
+ *
+ * Best-effort: a missing file, an unreadable file, malformed JSON, or a path-containment failure
+ * all resolve to `null` (a cache miss) rather than throwing — so a stale or corrupt cache never
+ * breaks a build. Use this to read the cache in parallel with the source file, then compare
+ * `entry.hash` against `hashCacheContent(content)` once both reads complete.
+ *
+ * A non-missing read failure (e.g. a permissions error silently disabling the cache) is logged
+ * under DEBUG rather than masquerading as a cold cache.
+ */
+export async function loadFileCacheEntry(ref) {
+  let raw;
+  try {
+    raw = await readFile(resolveCachePath(ref), 'utf-8');
+  } catch (error) {
+    const isMissing = error instanceof Error && error.code === 'ENOENT';
+    if (DEBUG && !isMissing) {
+      console.warn(`[docs-infra cache] read failed for ${ref.namespace}/${ref.cacheKey}:`, error);
+    }
+    return null;
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    if (DEBUG) {
+      console.warn(`[docs-infra cache] ignoring corrupt entry ${ref.namespace}/${ref.cacheKey}`);
+    }
+    return null;
+  }
+  if (!isFileCacheEntry(parsed)) {
+    if (DEBUG) {
+      console.warn(`[docs-infra cache] ignoring malformed entry ${ref.namespace}/${ref.cacheKey}`);
+    }
+    return null;
+  }
+  return parsed;
+}

package/pipeline/cacheUtils/resolveCachePath.d.mts

@@ -0,0 +1,16 @@
+import type { FileCacheRef } from "./types.mjs";
+/**
+ * Resolves the absolute path of a cache entry: `{cacheDir}/{namespace}/{cacheKey}.json`.
+ *
+ * Relative `cacheDir` values resolve against the current working directory so that readers and
+ * writers running from the same project root agree on the location. `cacheKey` may contain `/`
+ * separators, which become nested directories.
+ *
+ * Fails fast if a `namespace`/`cacheKey` segment (e.g. a `..`) would escape the cache directory,
+ * so a malformed route can never read or write outside `{cacheDir}`.
+ */
+export declare function resolveCachePath({
+  cacheDir,
+  namespace,
+  cacheKey
+}: FileCacheRef): string;

package/pipeline/cacheUtils/resolveCachePath.mjs

@@ -0,0 +1,24 @@
+import { resolve, sep } from 'node:path';
+/**
+ * Resolves the absolute path of a cache entry: `{cacheDir}/{namespace}/{cacheKey}.json`.
+ *
+ * Relative `cacheDir` values resolve against the current working directory so that readers and
+ * writers running from the same project root agree on the location. `cacheKey` may contain `/`
+ * separators, which become nested directories.
+ *
+ * Fails fast if a `namespace`/`cacheKey` segment (e.g. a `..`) would escape the cache directory,
+ * so a malformed route can never read or write outside `{cacheDir}`.
+ */
+export function resolveCachePath({
+  cacheDir,
+  namespace,
+  cacheKey
+}) {
+  const base = resolve(cacheDir);
+  const full = resolve(base, namespace, `${cacheKey}.json`);
+  const baseWithSep = base.endsWith(sep) ? base : `${base}${sep}`;
+  if (!full.startsWith(baseWithSep)) {
+    throw new Error(`Cache path for "${namespace}/${cacheKey}" escapes the cache directory "${cacheDir}".`);
+  }
+  return full;
+}

package/pipeline/cacheUtils/saveFileCache.d.mts

@@ -0,0 +1,17 @@
+import type { FileCacheEntry, FileCacheRef } from "./types.mjs";
+/**
+ * Writes a precomputed cache entry (`{ hash, data }`) atomically (temp file + rename) so a
+ * concurrent reader never observes a half-written file. Creates the cache directory tree as needed.
+ *
+ * Fails fast: any filesystem error propagates so a misconfigured cache directory surfaces loudly at
+ * build time. Callers that treat the write as best-effort (e.g. {@link withFileCache}) catch it.
+ *
+ * Use this (rather than {@link saveFileCache}) when the hash is already known, so the (possibly
+ * large) hash-input string does not have to be retained just to be re-hashed here.
+ */
+export declare function saveFileCacheEntry<T>(ref: FileCacheRef, entry: FileCacheEntry<T>): Promise<void>;
+/**
+ * Writes a cache entry as `{ hash: sha256(content), data }`. Convenience over
+ * {@link saveFileCacheEntry} for callers that hold the source `content` and want it hashed here.
+ */
+export declare function saveFileCache<T>(ref: FileCacheRef, content: string, data: T): Promise<void>;

package/pipeline/cacheUtils/saveFileCache.mjs

@@ -0,0 +1,54 @@
+import { mkdir, rename, rm, writeFile } from 'node:fs/promises';
+import { dirname } from 'node:path';
+import { threadId } from 'node:worker_threads';
+import { hashCacheContent } from "./hashCacheContent.mjs";
+import { resolveCachePath } from "./resolveCachePath.mjs";
+let tempCounter = 0;
+
+/**
+ * Writes a precomputed cache entry (`{ hash, data }`) atomically (temp file + rename) so a
+ * concurrent reader never observes a half-written file. Creates the cache directory tree as needed.
+ *
+ * Fails fast: any filesystem error propagates so a misconfigured cache directory surfaces loudly at
+ * build time. Callers that treat the write as best-effort (e.g. {@link withFileCache}) catch it.
+ *
+ * Use this (rather than {@link saveFileCache}) when the hash is already known, so the (possibly
+ * large) hash-input string does not have to be retained just to be re-hashed here.
+ */
+export async function saveFileCacheEntry(ref, entry) {
+  const cachePath = resolveCachePath(ref);
+  await mkdir(dirname(cachePath), {
+    recursive: true
+  });
+
+  // Write to a temp file then atomically rename over the target, so a torn write can never corrupt
+  // the cache file an in-flight reader is parsing. The temp name includes pid + threadId + a counter
+  // so two concurrent writers (including across worker_threads, which share a pid) never collide on
+  // it. The serialized string is transient.
+  tempCounter += 1;
+  const tempPath = `${cachePath}.${process.pid}.${threadId}.${tempCounter}.tmp`;
+  try {
+    await writeFile(tempPath, JSON.stringify(entry), 'utf-8');
+    await rename(tempPath, cachePath);
+  } catch (error) {
+    try {
+      await rm(tempPath, {
+        force: true
+      });
+    } catch {
+      // Best-effort cleanup of the temp file; ignore.
+    }
+    throw error;
+  }
+}
+
+/**
+ * Writes a cache entry as `{ hash: sha256(content), data }`. Convenience over
+ * {@link saveFileCacheEntry} for callers that hold the source `content` and want it hashed here.
+ */
+export async function saveFileCache(ref, content, data) {
+  return saveFileCacheEntry(ref, {
+    hash: hashCacheContent(content),
+    data
+  });
+}

package/pipeline/cacheUtils/types.d.mts

@@ -0,0 +1,23 @@
+/**
+ * Reference to a single cache entry on disk.
+ *
+ * The entry is stored at `{cacheDir}/{namespace}/{cacheKey}.json`. `cacheKey` may
+ * contain `/` separators to nest entries (e.g. `utilities/parsing`).
+ */
+export interface FileCacheRef {
+  /** Root cache directory. Relative paths resolve against the current working directory. */
+  cacheDir: string;
+  /** Subdirectory grouping related entries (e.g. `pages-index`). */
+  namespace: string;
+  /** Entry key, used as the file name without extension. May contain `/` for nesting. */
+  cacheKey: string;
+}
+/**
+ * On-disk shape of a cache entry: the validating content hash plus the cached value.
+ */
+export interface FileCacheEntry<T> {
+  /** sha256 hex digest of the source content the cached value was derived from. */
+  hash: string;
+  /** The cached value. */
+  data: T;
+}

package/pipeline/cacheUtils/types.mjs

@@ -0,0 +1 @@
+export {};

package/pipeline/cacheUtils/withFileCache.d.mts

@@ -0,0 +1,40 @@
+import type { FileCacheRef } from "./types.mjs";
+/**
+ * A read-through file cache task: fetch an origin, derive its validating content, and either
+ * return the cached result or compute a fresh one.
+ */
+export interface FileCacheTask<TOrigin, TData> {
+  /** The cache entry to use, or `undefined` to bypass the cache entirely. */
+  ref: FileCacheRef | undefined;
+  /** Fetches the origin (e.g. reads the source file). Runs concurrently with the cache read. */
+  readOrigin: () => Promise<TOrigin> | TOrigin;
+  /**
+   * Derives the string whose sha256 validates the cache from the origin — e.g. the file content,
+   * or the content combined with the options that affect the result. May differ from what the
+   * processor consumes.
+   */
+  getCacheContent: (origin: TOrigin) => string;
+  /** Computes the result from the origin on a cache miss. */
+  processor: (origin: TOrigin) => Promise<TData> | TData;
+}
+/**
+ * Standardizes the read-through cache flow shared by the page-index and types caches:
+ *
+ * 1. Read the cache entry while fetching and hashing the origin, so the two reads overlap and the
+ *    hash is ready before the cache read resolves.
+ * 2. On a hash match, return the cached data and skip the processor.
+ * 3. On a miss (or with no `ref`), run the processor and return its result.
+ *
+ * A rejection from `readOrigin`/`getCacheContent` surfaces to the caller; the in-flight cache read
+ * is abandoned safely because {@link loadFileCacheEntry} never rejects. Populating the cache is
+ * **best-effort** — a write failure (e.g. an unwritable cache dir) is swallowed (logged under
+ * DEBUG) and the freshly computed result is returned regardless, so a cache hiccup never fails the
+ * caller or drops its output. The explicit build/validate writers (syncPageIndex/syncTypes) call
+ * {@link saveFileCache} directly and stay fail-fast.
+ */
+export declare function withFileCache<TOrigin, TData>({
+  ref,
+  readOrigin,
+  getCacheContent,
+  processor
+}: FileCacheTask<TOrigin, TData>): Promise<TData>;

package/pipeline/cacheUtils/withFileCache.mjs

@@ -0,0 +1,81 @@
+import { hashCacheContent } from "./hashCacheContent.mjs";
+import { loadFileCacheEntry } from "./loadFileCacheEntry.mjs";
+import { saveFileCacheEntry } from "./saveFileCache.mjs";
+// Set DOCS_INFRA_CACHE_DEBUG=1 to log cache hit/miss and best-effort write failures.
+const DEBUG = Boolean(process.env.DOCS_INFRA_CACHE_DEBUG);
+
+/**
+ * A read-through file cache task: fetch an origin, derive its validating content, and either
+ * return the cached result or compute a fresh one.
+ */
+
+/**
+ * Standardizes the read-through cache flow shared by the page-index and types caches:
+ *
+ * 1. Read the cache entry while fetching and hashing the origin, so the two reads overlap and the
+ *    hash is ready before the cache read resolves.
+ * 2. On a hash match, return the cached data and skip the processor.
+ * 3. On a miss (or with no `ref`), run the processor and return its result.
+ *
+ * A rejection from `readOrigin`/`getCacheContent` surfaces to the caller; the in-flight cache read
+ * is abandoned safely because {@link loadFileCacheEntry} never rejects. Populating the cache is
+ * **best-effort** — a write failure (e.g. an unwritable cache dir) is swallowed (logged under
+ * DEBUG) and the freshly computed result is returned regardless, so a cache hiccup never fails the
+ * caller or drops its output. The explicit build/validate writers (syncPageIndex/syncTypes) call
+ * {@link saveFileCache} directly and stay fail-fast.
+ */
+export async function withFileCache({
+  ref,
+  readOrigin,
+  getCacheContent,
+  processor
+}) {
+  if (!ref) {
+    return processor(await readOrigin());
+  }
+
+  // Start the cache read so it overlaps fetching and hashing the origin.
+  const cacheEntryPromise = loadFileCacheEntry(ref);
+  const origin = await readOrigin();
+  // Hash the cache content without binding it to a variable: the hash-input string can be large
+  // (e.g. a multi-MB JSON of the loaded types), and it is only needed to compute the hash — so we
+  // let it be collected immediately rather than retaining it through the cache read, the processor,
+  // and the write. saveFileCacheEntry below reuses the hash, so the content is never needed again.
+  const contentHash = hashCacheContent(getCacheContent(origin));
+  let cacheEntry = await cacheEntryPromise;
+  if (cacheEntry && cacheEntry.hash === contentHash) {
+    if (DEBUG) {
+      console.warn(`[docs-infra cache] hit ${ref.namespace}/${ref.cacheKey}`);
+    }
+    return cacheEntry.data;
+  }
+
+  // Distinguish a stale (warm-but-mismatched) miss from a cold one — a perpetual writer/reader hash
+  // divergence surfaces here, and is exactly the failure DEBUG exists to make visible. Drop the
+  // stale entry before the processor runs so its (possibly multi-MB) data is not retained alongside
+  // the freshly computed result.
+  const wasStale = Boolean(cacheEntry);
+  cacheEntry = null;
+  if (DEBUG && wasStale) {
+    console.warn(`[docs-infra cache] stale ${ref.namespace}/${ref.cacheKey} (hash mismatch, recomputing)`);
+  }
+  const data = await processor(origin);
+  try {
+    await saveFileCacheEntry(ref, {
+      hash: contentHash,
+      data
+    });
+    if (DEBUG) {
+      console.warn(`[docs-infra cache] miss → wrote ${ref.namespace}/${ref.cacheKey}`);
+    }
+  } catch (error) {
+    // Best-effort: any save failure — IO, the resolveCachePath traversal guard, or a serialization
+    // error on non-JSON-safe data — is swallowed so a misconfigured cache can never drop a page or
+    // fail a build; the computed result is returned regardless. The fail-fast writers (syncPageIndex
+    // and syncTypes, via saveFileCache) surface these instead. DEBUG logs them here.
+    if (DEBUG) {
+      console.warn(`[docs-infra cache] write failed for ${ref.namespace}/${ref.cacheKey}:`, error);
+    }
+  }
+  return data;
+}

package/pipeline/loadPrecomputedSitemap/loadPrecomputedSitemap.d.mts

@@ -6,5 +6,11 @@ export type LoaderOptions = {
     showWrapperMeasures?: boolean;
     significantDependencyCountThreshold?: number;
   };
+  /**
+   * Directory for the sha256-validated JSON cache of parsed page indexes. When set,
+   * unchanged indexes are read from `{cacheDir}/pages-index/{route}.json` instead of
+   * being re-parsed.
+   */
+  cacheDir?: string;
 };
 export declare function loadPrecomputedSitemap(this: LoaderContext<LoaderOptions>, source: string): Promise<void>;

package/pipeline/loadPrecomputedSitemap/loadPrecomputedSitemap.mjs

@@ -72,7 +72,8 @@ export async function loadPrecomputedSitemap(source) {
     // Create page index loader with root context
     const rootContext = this.rootContext || process.cwd();
     const loadPageIndex = createLoadServerPageIndex({
-      rootContext
+      rootContext,
+      cacheDir: options.cacheDir
     });
 
     // Process all markdown files in parallel using shared logic

package/pipeline/loadPrecomputedTypes/loadPrecomputedTypes.d.mts

@@ -56,6 +56,12 @@ export type LoaderOptions = {
   descriptionReplacements?: DescriptionReplacement[];
   /** Options for code blocks highlighted inside generated type metadata */
   codeBlockEmphasisOptions?: TransformHtmlCodeBlockOptions;
+  /**
+   * Directory for the sha256-validated JSON cache of the types pipeline. When set, the
+   * parsed types.md (`types-text`) and the enhanced/highlighted result (`types-enhanced`)
+   * are cached under it, keyed by content hash.
+   */
+  cacheDir?: string;
 };
 /**
  * Webpack loader that processes types and precomputes meta.