@mui/internal-docs-infra 0.12.1-canary.2 → 0.12.1-canary.21

package/pipeline/loadIsomorphicCodeVariant/diffHast.d.mts

@@ -1,5 +1,5 @@
 import type { Nodes } from 'hast';
-import { type SourceComments, type Transforms } from "../../CodeHighlighter/types.mjs";
+import type { SourceComments, Transforms } from "../../CodeHighlighter/types.mjs";
 /**
  * Async-friendly variant of {@link ParseSource}. The build-time diff path
  * may wrap the synchronous highlighter with enhancers that need to run

package/pipeline/loadIsomorphicCodeVariant/hasAllCodeVariants.d.mts

@@ -1,4 +1,4 @@
-import { type Code } from "../../CodeHighlighter/types.mjs";
+import type { Code } from "../../CodeHighlighter/types.mjs";
 /**
  * Determines if all code variants are fully loaded and ready to render the complete content component.
  *

package/pipeline/loadIsomorphicCodeVariant/maybeCodeInitialData.d.mts

@@ -1,4 +1,4 @@
-import { type Code, type VariantExtraFiles, type VariantSource } from "../../CodeHighlighter/types.mjs";
+import type { Code, VariantExtraFiles, VariantSource } from "../../CodeHighlighter/types.mjs";
 /**
  * Type guard function that determines if we have sufficient data to render a code highlighter
  * component immediately, or if we need to start loading data first.

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.

package/pipeline/loadPrecomputedTypes/loadPrecomputedTypes.mjs

@@ -73,7 +73,10 @@ export async function loadPrecomputedTypes(source) {
     // Skip if excludeFromIndex is set in the factory call options
     const updateParentIndex = options.updateParentIndex && !excludeFromIndex ? {
       baseDir: options.updateParentIndex.baseDir ? path.resolve(rootContext, options.updateParentIndex.baseDir) : rootContext,
-      indexFileName: options.updateParentIndex.indexFileName
+      indexFileName: options.updateParentIndex.indexFileName,
+      // Forward cacheDir so the types-driven parent-index update also warms the
+      // pages-index cache (otherwise only the MDX path / on-miss reader populate it).
+      cacheDir: options.updateParentIndex.cacheDir
     } : undefined;
 
     // Call the core server-side logic
@@ -90,6 +93,7 @@ export async function loadPrecomputedTypes(source) {
       ordering: options.ordering,
       descriptionReplacements: options.descriptionReplacements,
       codeBlockEmphasisOptions: options.codeBlockEmphasisOptions,
+      cacheDir: options.cacheDir,
       sync: true,
       output: 'hastCompressed'
     });

package/pipeline/loadServerCodeMeta/resolveModulePathWithFs.d.mts

@@ -1,4 +1,4 @@
-import { type DirectoryEntry, type DirectoryReader, type ResolveModulePathOptions, type TypeAwareResolveResult } from "../loaderUtils/resolveModulePath.mjs";
+import type { DirectoryEntry, DirectoryReader, ResolveModulePathOptions, TypeAwareResolveResult } from "../loaderUtils/resolveModulePath.mjs";
 /**
  * Resolves a module path using Node.js filesystem APIs.
  * This is a convenience wrapper around the generic resolveModulePath function.

package/pipeline/loadServerCodeMeta/resolveModulePathWithFs.mjs

@@ -4,7 +4,6 @@ import { readdir } from 'fs/promises';
 // eslint-disable-next-line n/prefer-node-protocol
 import { fileURLToPath } from 'url';
 import { resolveModulePath, resolveModulePaths, resolveImportResult, resolveVariantPaths } from "../loaderUtils/resolveModulePath.mjs";
-
 /**
  * Node.js filesystem-based directory reader that converts Dirent objects
  * to the DirectoryEntry interface expected by the resolver functions.

package/pipeline/loadServerPageIndex/enrichPageIndex.d.mts

@@ -0,0 +1,15 @@
+import type { PagesMetadata } from "../syncPageIndex/metadataToMarkdown.mjs";
+import type { SitemapSectionData } from "../../createSitemap/types.mjs";
+/**
+ * Converts parsed page-index metadata into the `SitemapSectionData` read-model.
+ *
+ * Derives `prefix` and `title` from the file path (overriding the markdown H1), strips the
+ * markdown AST fields (`descriptionMarkdown`, section `titleMarkdown`) to reduce bundle size, and
+ * normalizes description whitespace exactly as the parser does so the cache (built from in-memory
+ * metadata) matches a fresh parse of the written markdown.
+ *
+ * Shared by `loadServerPageIndex` (read path) and `syncPageIndex` (cache pre-population on write).
+ * Normalization is idempotent, so re-applying it on the read path (where descriptions are already
+ * normalized) is a no-op.
+ */
+export declare function enrichPageIndex(metadata: PagesMetadata, absolutePath: string, rootContext: string): SitemapSectionData;

package/pipeline/loadServerPageIndex/enrichPageIndex.mjs

@@ -0,0 +1,50 @@
+import { extractPrefixAndTitle, stripTitleMarkdown } from "./extractPrefixAndTitle.mjs";
+import { collapseInlineWhitespace } from "../syncPageIndex/metadataToMarkdown.mjs";
+/**
+ * Converts parsed page-index metadata into the `SitemapSectionData` read-model.
+ *
+ * Derives `prefix` and `title` from the file path (overriding the markdown H1), strips the
+ * markdown AST fields (`descriptionMarkdown`, section `titleMarkdown`) to reduce bundle size, and
+ * normalizes description whitespace exactly as the parser does so the cache (built from in-memory
+ * metadata) matches a fresh parse of the written markdown.
+ *
+ * Shared by `loadServerPageIndex` (read path) and `syncPageIndex` (cache pre-population on write).
+ * Normalization is idempotent, so re-applying it on the read path (where descriptions are already
+ * normalized) is a no-op.
+ */
+export function enrichPageIndex(metadata, absolutePath, rootContext) {
+  // Override the markdown's H1 with the title generated from the path.
+  const {
+    prefix,
+    title
+  } = extractPrefixAndTitle(absolutePath, rootContext);
+  return {
+    ...metadata,
+    prefix,
+    title,
+    // Normalize the index's own (leaked) description like the parser. Spread instead of an explicit
+    // key because SitemapSectionData does not declare `description`.
+    ...(metadata.description !== undefined ? {
+      description: collapseInlineWhitespace(metadata.description)
+    } : {}),
+    // Strip markdown AST fields and normalize each page's description. keywords and types are
+    // comma-split from a whitespace-collapsed paragraph by the parser, so normalize each element
+    // the same way (collapse-then-split equals split-then-per-element-collapse, since the comma
+    // delimiter can't appear inside a value) — otherwise a cache hit diverges from a fresh parse.
+    pages: metadata.pages.map(page => {
+      const {
+        descriptionMarkdown,
+        sections,
+        ...pageWithoutMarkdown
+      } = page;
+      return {
+        ...pageWithoutMarkdown,
+        description: page.description === undefined ? undefined : collapseInlineWhitespace(page.description),
+        keywords: page.keywords?.map(collapseInlineWhitespace),
+        types: page.types?.map(collapseInlineWhitespace),
+        // Strip titleMarkdown from the sections hierarchy.
+        sections: sections ? stripTitleMarkdown(sections) : undefined
+      };
+    })
+  };
+}

package/pipeline/loadServerPageIndex/extractPrefixAndTitle.d.mts

@@ -0,0 +1,19 @@
+import type { HeadingHierarchy } from "../transformMarkdownMetadata/types.mjs";
+import type { SitemapSection } from "../../createSitemap/types.mjs";
+/**
+ * Converts a path segment to a title
+ * e.g., "docs-infra" -> "Docs Infra", "components" -> "Components"
+ */
+export declare function pathSegmentToTitle(segment: string): string;
+/**
+ * Recursively removes titleMarkdown fields from a heading hierarchy
+ */
+export declare function stripTitleMarkdown(hierarchy: HeadingHierarchy): Record<string, SitemapSection>;
+/**
+ * Extracts prefix and title from an import path
+ * e.g., "/path/to/app/docs-infra/components/page.mdx" -> { prefix: "/docs-infra/components/", title: "Docs Infra Components" }
+ */
+export declare function extractPrefixAndTitle(absolutePath: string, rootContext: string): {
+  prefix: string;
+  title: string;
+};

package/pipeline/loadServerPageIndex/extractPrefixAndTitle.mjs

@@ -0,0 +1,80 @@
+import path from 'node:path';
+/**
+ * Converts a path segment to a title
+ * e.g., "docs-infra" -> "Docs Infra", "components" -> "Components"
+ */
+export function pathSegmentToTitle(segment) {
+  return segment.split('-').map(word => word.charAt(0).toUpperCase() + word.slice(1)).join(' ');
+}
+
+/**
+ * Recursively removes titleMarkdown fields from a heading hierarchy
+ */
+export function stripTitleMarkdown(hierarchy) {
+  const result = {};
+  for (const [key, value] of Object.entries(hierarchy)) {
+    if (typeof value === 'object' && value !== null) {
+      const {
+        titleMarkdown,
+        children,
+        ...rest
+      } = value;
+      const strippedChildren = children ? stripTitleMarkdown(children) : {};
+      result[key] = {
+        ...rest,
+        // Only include children if it has keys, otherwise set to undefined
+        children: Object.keys(strippedChildren).length > 0 ? strippedChildren : undefined
+      };
+    }
+  }
+  return result;
+}
+
+/**
+ * Extracts prefix and title from an import path
+ * e.g., "/path/to/app/docs-infra/components/page.mdx" -> { prefix: "/docs-infra/components/", title: "Docs Infra Components" }
+ */
+export function extractPrefixAndTitle(absolutePath, rootContext) {
+  // Get the relative path from the root context
+  const relativePath = path.relative(rootContext, absolutePath);
+
+  // Extract the directory path (remove filename)
+  const dirPath = path.dirname(relativePath);
+
+  // Split into segments
+  const allSegments = dirPath.split(path.sep);
+
+  // Filter out segments:
+  // - Remove leading 'src' and 'app' directory markers (only if they're at the start)
+  // - Remove Next.js route groups (segments in parentheses like '(public)')
+  // - Remove current directory markers ('.' and empty strings)
+  const segments = allSegments.filter((seg, index) => {
+    // Remove 'src' only if it's the first segment
+    if (seg === 'src' && index === 0) {
+      return false;
+    }
+    // Remove 'app' only if it's the first or second segment (after 'src')
+    if (seg === 'app' && (index === 0 || index === 1 && allSegments[0] === 'src')) {
+      return false;
+    }
+    // Filter out Next.js route groups (e.g., '(public)', '(content)')
+    if (seg.startsWith('(') && seg.endsWith(')')) {
+      return false;
+    }
+    // Filter out current directory markers
+    if (seg === '.' || seg === '') {
+      return false;
+    }
+    return true;
+  });
+
+  // Generate prefix with leading and trailing slashes
+  const prefix = segments.length > 0 ? `/${segments.join('/')}/` : '/';
+
+  // Generate title from path segments
+  const title = segments.map(pathSegmentToTitle).join(' ');
+  return {
+    prefix,
+    title
+  };
+}

package/pipeline/loadServerPageIndex/index.d.mts

@@ -1,2 +1,5 @@
-export { loadServerPageIndex, createLoadServerPageIndex, extractPrefixAndTitle, pathSegmentToTitle, stripTitleMarkdown } from "./loadServerPageIndex.mjs";
-export type { CreateLoadServerPageIndexOptions, LoadServerPageIndex } from "./loadServerPageIndex.mjs";
+export { loadServerPageIndex, createLoadServerPageIndex } from "./loadServerPageIndex.mjs";
+export type { CreateLoadServerPageIndexOptions, LoadServerPageIndex } from "./loadServerPageIndex.mjs";
+export { extractPrefixAndTitle, pathSegmentToTitle, stripTitleMarkdown } from "./extractPrefixAndTitle.mjs";
+export { enrichPageIndex } from "./enrichPageIndex.mjs";
+export { resolvePageIndexCacheKey } from "./resolvePageIndexCacheKey.mjs";

package/pipeline/loadServerPageIndex/index.mjs

@@ -1 +1,4 @@
-export { loadServerPageIndex, createLoadServerPageIndex, extractPrefixAndTitle, pathSegmentToTitle, stripTitleMarkdown } from "./loadServerPageIndex.mjs";
+export { loadServerPageIndex, createLoadServerPageIndex } from "./loadServerPageIndex.mjs";
+export { extractPrefixAndTitle, pathSegmentToTitle, stripTitleMarkdown } from "./extractPrefixAndTitle.mjs";
+export { enrichPageIndex } from "./enrichPageIndex.mjs";
+export { resolvePageIndexCacheKey } from "./resolvePageIndexCacheKey.mjs";

package/pipeline/loadServerPageIndex/loadServerPageIndex.d.mts

@@ -1,5 +1,4 @@
-import type { HeadingHierarchy } from "../transformMarkdownMetadata/types.mjs";
-import type { SitemapSection, SitemapSectionData } from "../../createSitemap/types.mjs";
+import type { SitemapSectionData } from "../../createSitemap/types.mjs";
 /**
  * Options for creating a loadServerPageIndex function
  */
@@ -9,28 +8,19 @@ export interface CreateLoadServerPageIndexOptions {
    * Defaults to process.cwd().
    */
   rootContext?: string;
+  /**
+   * Directory for the sha256-validated JSON cache of parsed page indexes.
+   *
+   * When set, a read first checks `{cacheDir}/pages-index/{route}.json`; on a hash
+   * match it returns the cached data and skips the markdown parse, and on a miss it
+   * parses, writes the cache, and returns. When unset, no cache is read or written.
+   */
+  cacheDir?: string;
 }
 /**
  * Function type for loading page index data from a markdown file
  */
 export type LoadServerPageIndex = (filePath: string) => Promise<SitemapSectionData | null>;
-/**
- * Converts a path segment to a title
- * e.g., "docs-infra" -> "Docs Infra", "components" -> "Components"
- */
-export declare function pathSegmentToTitle(segment: string): string;
-/**
- * Recursively removes titleMarkdown fields from a heading hierarchy
- */
-export declare function stripTitleMarkdown(hierarchy: HeadingHierarchy): Record<string, SitemapSection>;
-/**
- * Extracts prefix and title from an import path
- * e.g., "/path/to/app/docs-infra/components/page.mdx" -> { prefix: "/docs-infra/components/", title: "Docs Infra Components" }
- */
-export declare function extractPrefixAndTitle(absolutePath: string, rootContext: string): {
-  prefix: string;
-  title: string;
-};
 /**
  * Default loadServerPageIndex function that loads page index data from a markdown file.
  * This function uses process.cwd() as the root context for resolving relative paths.
@@ -41,9 +31,10 @@ export declare const loadServerPageIndex: LoadServerPageIndex;
  *
  * This factory function creates a LoadServerPageIndex implementation that:
  * 1. Reads the markdown file from the provided file path
- * 2. Parses the markdown to extract metadata using markdownToMetadata
- * 3. Enriches the metadata with prefix and title derived from the file path
- * 4. Returns a SitemapSectionData object with page data
+ * 2. Returns a cached `SitemapSectionData` when `cacheDir` is set and the markdown is unchanged
+ * 3. Otherwise parses the markdown to extract metadata using markdownToMetadata
+ * 4. Enriches the metadata with prefix and title derived from the file path
+ * 5. Pre-populates the cache (when `cacheDir` is set) for the next cold read
  *
  * @param options - Configuration options for the loader
  * @returns LoadServerPageIndex function that takes a file path and returns Promise<SitemapSectionData | null>

package/pipeline/loadServerPageIndex/loadServerPageIndex.mjs

@@ -1,7 +1,9 @@
 import fs from 'node:fs/promises';
-import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { markdownToMetadata } from "../syncPageIndex/metadataToMarkdown.mjs";
+import { withFileCache } from "../cacheUtils/index.mjs";
+import { enrichPageIndex } from "./enrichPageIndex.mjs";
+import { resolvePageIndexCacheKey, PAGE_INDEX_CACHE_NAMESPACE } from "./resolvePageIndexCacheKey.mjs";
 
 /**
  * Options for creating a loadServerPageIndex function
@@ -11,86 +13,6 @@ import { markdownToMetadata } from "../syncPageIndex/metadataToMarkdown.mjs";
  * Function type for loading page index data from a markdown file
  */
 
-/**
- * Converts a path segment to a title
- * e.g., "docs-infra" -> "Docs Infra", "components" -> "Components"
- */
-export function pathSegmentToTitle(segment) {
-  return segment.split('-').map(word => word.charAt(0).toUpperCase() + word.slice(1)).join(' ');
-}
-
-/**
- * Recursively removes titleMarkdown fields from a heading hierarchy
- */
-export function stripTitleMarkdown(hierarchy) {
-  const result = {};
-  for (const [key, value] of Object.entries(hierarchy)) {
-    if (typeof value === 'object' && value !== null) {
-      const {
-        titleMarkdown,
-        children,
-        ...rest
-      } = value;
-      const strippedChildren = children ? stripTitleMarkdown(children) : {};
-      result[key] = {
-        ...rest,
-        // Only include children if it has keys, otherwise set to undefined
-        children: Object.keys(strippedChildren).length > 0 ? strippedChildren : undefined
-      };
-    }
-  }
-  return result;
-}
-
-/**
- * Extracts prefix and title from an import path
- * e.g., "/path/to/app/docs-infra/components/page.mdx" -> { prefix: "/docs-infra/components/", title: "Docs Infra Components" }
- */
-export function extractPrefixAndTitle(absolutePath, rootContext) {
-  // Get the relative path from the root context
-  const relativePath = path.relative(rootContext, absolutePath);
-
-  // Extract the directory path (remove filename)
-  const dirPath = path.dirname(relativePath);
-
-  // Split into segments
-  const allSegments = dirPath.split(path.sep);
-
-  // Filter out segments:
-  // - Remove leading 'src' and 'app' directory markers (only if they're at the start)
-  // - Remove Next.js route groups (segments in parentheses like '(public)')
-  // - Remove current directory markers ('.' and empty strings)
-  const segments = allSegments.filter((seg, index) => {
-    // Remove 'src' only if it's the first segment
-    if (seg === 'src' && index === 0) {
-      return false;
-    }
-    // Remove 'app' only if it's the first or second segment (after 'src')
-    if (seg === 'app' && (index === 0 || index === 1 && allSegments[0] === 'src')) {
-      return false;
-    }
-    // Filter out Next.js route groups (e.g., '(public)', '(content)')
-    if (seg.startsWith('(') && seg.endsWith(')')) {
-      return false;
-    }
-    // Filter out current directory markers
-    if (seg === '.' || seg === '') {
-      return false;
-    }
-    return true;
-  });
-
-  // Generate prefix with leading and trailing slashes
-  const prefix = segments.length > 0 ? `/${segments.join('/')}/` : '/';
-
-  // Generate title from path segments
-  const title = segments.map(pathSegmentToTitle).join(' ');
-  return {
-    prefix,
-    title
-  };
-}
-
 /**
  * Default loadServerPageIndex function that loads page index data from a markdown file.
  * This function uses process.cwd() as the root context for resolving relative paths.
@@ -102,56 +24,42 @@ export const loadServerPageIndex = createLoadServerPageIndex();
  *
  * This factory function creates a LoadServerPageIndex implementation that:
  * 1. Reads the markdown file from the provided file path
- * 2. Parses the markdown to extract metadata using markdownToMetadata
- * 3. Enriches the metadata with prefix and title derived from the file path
- * 4. Returns a SitemapSectionData object with page data
+ * 2. Returns a cached `SitemapSectionData` when `cacheDir` is set and the markdown is unchanged
+ * 3. Otherwise parses the markdown to extract metadata using markdownToMetadata
+ * 4. Enriches the metadata with prefix and title derived from the file path
+ * 5. Pre-populates the cache (when `cacheDir` is set) for the next cold read
  *
  * @param options - Configuration options for the loader
  * @returns LoadServerPageIndex function that takes a file path and returns Promise<SitemapSectionData | null>
  */
 export function createLoadServerPageIndex(options = {}) {
   const rootContext = options.rootContext ?? process.cwd();
-  return async function loadPageIndex(filePath) {
-    // Convert file:// URLs to proper file system paths for reading the file
+  const {
+    cacheDir
+  } = options;
+  return function loadPageIndex(filePath) {
+    // Convert file:// URLs to proper file system paths for reading the file.
     // Using fileURLToPath handles Windows drive letters correctly (e.g., file:///C:/... → C:\...)
     const absolutePath = filePath.startsWith('file://') ? fileURLToPath(filePath) : filePath;
-
-    // Extract prefix and title from the import path
-    const {
-      prefix,
-      title: generatedTitle
-    } = extractPrefixAndTitle(absolutePath, rootContext);
-
-    // Read the markdown file
-    const markdownContent = await fs.readFile(absolutePath, 'utf-8');
-
-    // Parse the markdown to extract metadata
-    const metadata = await markdownToMetadata(markdownContent);
-    if (!metadata) {
-      return null;
-    }
-
-    // Add prefix and override title with the generated one from the path
-    // Strip descriptionMarkdown and titleMarkdown to reduce bundle size
-    const enrichedMetadata = {
-      ...metadata,
-      prefix,
-      // Use the generated title from the path (override markdown's H1)
-      title: generatedTitle,
-      // Strip markdown AST fields from each page to reduce size
-      pages: metadata.pages.map(page => {
-        const {
-          descriptionMarkdown,
-          sections,
-          ...pageWithoutMarkdown
-        } = page;
-        return {
-          ...pageWithoutMarkdown,
-          // Strip titleMarkdown from sections hierarchy
-          sections: sections ? stripTitleMarkdown(sections) : undefined
-        };
-      })
-    };
-    return enrichedMetadata;
+    const cacheRef = cacheDir ? {
+      cacheDir,
+      namespace: PAGE_INDEX_CACHE_NAMESPACE,
+      cacheKey: resolvePageIndexCacheKey(absolutePath, rootContext)
+    } : undefined;
+
+    // The cache stores the enriched read-model keyed by the markdown hash, so a hit skips the
+    // markdownToMetadata parse.
+    return withFileCache({
+      ref: cacheRef,
+      readOrigin: () => fs.readFile(absolutePath, 'utf-8'),
+      getCacheContent: markdownContent => markdownContent,
+      processor: async markdownContent => {
+        const metadata = await markdownToMetadata(markdownContent);
+        if (!metadata) {
+          return null;
+        }
+        return enrichPageIndex(metadata, absolutePath, rootContext);
+      }
+    });
   };
 }

package/pipeline/loadServerPageIndex/resolvePageIndexCacheKey.d.mts

@@ -0,0 +1,13 @@
+/** Cache namespace (subdirectory) for page-index entries. */
+export declare const PAGE_INDEX_CACHE_NAMESPACE = "pages-index";
+/**
+ * Derives the cache key for a page-index file from its path, reusing the same
+ * route derivation as the loaded data so a writer and reader of the same index
+ * agree on the cache location.
+ *
+ * @example
+ * resolvePageIndexCacheKey('/root/src/app/components/page.mdx', '/root') // 'components'
+ * resolvePageIndexCacheKey('/root/app/utilities/parsing/page.mdx', '/root') // 'utilities/parsing'
+ * resolvePageIndexCacheKey('/root/app/page.mdx', '/root') // 'index' (root)
+ */
+export declare function resolvePageIndexCacheKey(absolutePath: string, rootContext: string): string;

package/pipeline/loadServerPageIndex/resolvePageIndexCacheKey.mjs

@@ -0,0 +1,23 @@
+import { extractPrefixAndTitle } from "./extractPrefixAndTitle.mjs";
+
+/** Cache namespace (subdirectory) for page-index entries. */
+export const PAGE_INDEX_CACHE_NAMESPACE = 'pages-index';
+
+/**
+ * Derives the cache key for a page-index file from its path, reusing the same
+ * route derivation as the loaded data so a writer and reader of the same index
+ * agree on the cache location.
+ *
+ * @example
+ * resolvePageIndexCacheKey('/root/src/app/components/page.mdx', '/root') // 'components'
+ * resolvePageIndexCacheKey('/root/app/utilities/parsing/page.mdx', '/root') // 'utilities/parsing'
+ * resolvePageIndexCacheKey('/root/app/page.mdx', '/root') // 'index' (root)
+ */
+export function resolvePageIndexCacheKey(absolutePath, rootContext) {
+  const {
+    prefix
+  } = extractPrefixAndTitle(absolutePath, rootContext);
+  // prefix is like '/components/' or '/utilities/parsing/' (or '/' for the root index).
+  const segments = prefix.split('/').filter(Boolean);
+  return segments.length > 0 ? segments.join('/') : 'index';
+}

package/pipeline/loadServerTypes/highlightTypes.d.mts

@@ -1,7 +1,7 @@
 import type { Root as HastRoot } from 'hast';
-import { type TransformHtmlCodeBlockOptions } from "../transformHtmlCodeBlock/transformHtmlCodeBlock.mjs";
-import { type TypesMeta } from "../loadServerTypesMeta/index.mjs";
-import { type TypesOutputFormat } from "./hastTypeUtils.mjs";
+import type { TransformHtmlCodeBlockOptions } from "../transformHtmlCodeBlock/transformHtmlCodeBlock.mjs";
+import type { TypesMeta } from "../loadServerTypesMeta/index.mjs";
+import type { TypesOutputFormat } from "./hastTypeUtils.mjs";
 /**
  * Result of the highlightTypes function.
  */

package/pipeline/loadServerTypes/highlightTypesMeta.d.mts

@@ -8,12 +8,12 @@
  * 4. Converts defaultText to syntax-highlighted HAST (default field)
  */
 import type { Root as HastRoot } from 'hast';
-import { type TransformHtmlCodeBlockOptions } from "../transformHtmlCodeBlock/transformHtmlCodeBlock.mjs";
-import { type TypesMeta, type ComponentTypeMeta, type HookTypeMeta, type FunctionTypeMeta, type ClassTypeMeta, type RawTypeMeta, type FormattedProperty, type FormattedParameter } from "../loadServerTypesMeta/index.mjs";
+import type { TransformHtmlCodeBlockOptions } from "../transformHtmlCodeBlock/transformHtmlCodeBlock.mjs";
+import type { TypesMeta, ComponentTypeMeta, HookTypeMeta, FunctionTypeMeta, ClassTypeMeta, RawTypeMeta, FormattedProperty, FormattedParameter } from "../loadServerTypesMeta/index.mjs";
 import type { FormattedMethod } from "../loadServerTypesMeta/formatClass.mjs";
 import type { EnumMemberMeta } from "../loadServerTypesMeta/formatRaw.mjs";
-import { type FormatInlineTypeOptions } from "./typeHighlighting.mjs";
-import { type SerializedHastRoot, type SerializedHastCompressed, type TypesOutputFormat } from "./hastTypeUtils.mjs";
+import type { FormatInlineTypeOptions } from "./typeHighlighting.mjs";
+import type { SerializedHastRoot, SerializedHastCompressed, TypesOutputFormat } from "./hastTypeUtils.mjs";
 /** A HAST root or its serialized/compressed wrapper. */
 type HastField = HastRoot | SerializedHastRoot | SerializedHastCompressed;
 /**

package/pipeline/loadServerTypes/loadServerTypes.d.mts

@@ -1,5 +1,5 @@
-import { type HighlightedTypesMeta, type HighlightedComponentTypeMeta, type HighlightedHookTypeMeta, type HighlightedFunctionTypeMeta, type HighlightedClassTypeMeta, type HighlightedMethod, type HighlightedRawTypeMeta, type HighlightedEnumMemberMeta, type HighlightedProperty, type HighlightedParameter, type HighlightedClassProperty } from "./highlightTypesMeta.mjs";
-import { type SyncTypesOptions } from "../syncTypes/index.mjs";
+import type { HighlightedTypesMeta, HighlightedComponentTypeMeta, HighlightedHookTypeMeta, HighlightedFunctionTypeMeta, HighlightedClassTypeMeta, HighlightedMethod, HighlightedRawTypeMeta, HighlightedEnumMemberMeta, HighlightedProperty, HighlightedParameter, HighlightedClassProperty } from "./highlightTypesMeta.mjs";
+import type { SyncTypesOptions } from "../syncTypes/index.mjs";
 import type { ExportData } from "../../abstractCreateTypes/index.mjs";
 import type { TypesOutputFormat } from "./hastTypeUtils.mjs";
 import type { TransformHtmlCodeBlockOptions } from "../transformHtmlCodeBlock/transformHtmlCodeBlock.mjs";