create-zudo-doc 0.2.21 → 1.0.0

package/templates/base/pages/lib/_nav-source-cache.ts

@@ -32,11 +32,21 @@
 // HMR intent preserved: a content edit produces a NEW snapshot object (new
 // `collections[name]` array identity), so every memo here misses and
 // recomputes — matching the old content-keyed cache's change detection.
+//
+// PACKAGE SPLIT (epic #2344, S6):
+//   `memoizeDerived` — the generic two-level WeakMap memo — is now in the
+//   package at @takazudo/zudo-doc/nav-source-cache (no zfb imports needed).
+//   `stableDocs` stays here because it imports `getCollection` /
+//   `getContentSnapshot` from "zfb/content", which is a virtual module
+//   provided by the zfb SSG build system at compile time — not an npm package.
 
 import { getCollection, getContentSnapshot } from "zfb/content";
 import { bridgeDocsEntries, type ZfbDocsData } from "../_data";
 import type { DocPageEntry } from "./doc-page-props";
 
+// Re-export memoizeDerived from the package (pure, no zfb dep).
+export { memoizeDerived } from "@takazudo/zudo-doc/nav-source-cache";
+
 // ---------------------------------------------------------------------------
 // Snapshot anchor → stable bridged arrays
 // ---------------------------------------------------------------------------
@@ -70,6 +80,8 @@ function buildBridged(collectionName: string): DocPageEntry[] {
  * `buildNavTree` — can rely on reference equality. The entries carry the full
  * `DocPageEntry` shape (Content, body, module_specifier, id, collection) the
  * route `paths()` props need.
+ *
+ * Passed as `stableDocs` to `createNavSourceDocs` in `_nav-source-docs.ts`.
  */
 export function stableDocs(collectionName: string): DocPageEntry[] {
   const anchor = snapshotAnchor(collectionName);
@@ -86,60 +98,3 @@ export function stableDocs(collectionName: string): DocPageEntry[] {
   bridgedByAnchor.set(anchor, built);
   return built;
 }
-
-// ---------------------------------------------------------------------------
-// Generic derived-array memo (merge / filter results)
-// ---------------------------------------------------------------------------
-
-// Two-level memo: a WeakMap on the FIRST stable input array (so a new snapshot
-// drops the whole sub-map), then a string key combining the remaining stable
-// inputs' identities and the option signature.
-const derivedMemo = new WeakMap<object, Map<string, unknown>>();
-// Per-build incrementing ids for stable arrays, so a multi-array key can be a
-// cheap string. Lives in a WeakMap so it does not retain arrays past their
-// snapshot.
-const arrayId = new WeakMap<object, number>();
-let nextArrayId = 1;
-function idOf(arr: object): number {
-  let id = arrayId.get(arr);
-  if (id === undefined) {
-    id = nextArrayId++;
-    arrayId.set(arr, id);
-  }
-  return id;
-}
-
-// Anchor object for the rare case of an empty `inputs` array (e.g. an absent
-// locale collection). Lets the WeakMap still key the derived memo.
-const EMPTY_INPUT_ANCHOR: object = {};
-
-/**
- * Memoize a derived array (e.g. a locale merge or an `isNavVisible` filter)
- * on the identity of its stable inputs plus a caller-supplied option
- * signature.
- *
- * `inputs` MUST be the stable arrays returned by {@link stableDocs} (or arrays
- * derived from them through this same helper) — passing a fresh array defeats
- * the memo. `optionSig` distinguishes call sites that differ only in filter
- * options (e.g. `applyDefaultLocaleOnlyFilter`, `keepUnlisted`), so they never
- * collide on the same key.
- */
-export function memoizeDerived<T>(
-  inputs: readonly object[],
-  optionSig: string,
-  compute: () => T,
-): T {
-  const primary = inputs[0] ?? EMPTY_INPUT_ANCHOR;
-  let sub = derivedMemo.get(primary);
-  if (!sub) {
-    sub = new Map();
-    derivedMemo.set(primary, sub);
-  }
-  const key = `${inputs.map((a) => idOf(a)).join("/")}::${optionSig}`;
-  // Use has(): a legitimately-`undefined` computed result must still register
-  // as a cache hit, otherwise it recomputes every call.
-  if (sub.has(key)) return sub.get(key) as T;
-  const computed = compute();
-  sub.set(key, computed);
-  return computed;
-}

package/templates/base/pages/lib/_nav-source-docs.ts

@@ -1,237 +1,37 @@
-// Shared, identity-stable nav-source resolver.
-//
-// Picks the right collection(s) and category-meta dir for an active
-// (locale, version) pair, applying the locale-first + EN-fallback merge that
-// the doc-route `paths()` passes use, so every nav surface (desktop sidebar,
-// mobile SidebarToggle, route enumeration, MDX nav wrappers) sees the same
-// data the pages enumerate.
-//
-// IDENTITY STABILITY (why this is not a thin wrapper)
-// ---------------------------------------------------
-// Every returned `docs` / `navDocs` array and `categoryMeta` Map is memoized
-// so repeat callers within one build get the SAME instances. That is what lets
-// `buildNavTree`'s identity fast-path (`src/utils/docs.ts`) skip the O(n log n)
-// key computation on the ~900 calls a 251-page build makes. See
-// `_nav-source-cache.ts` for the snapshot-anchored memo and the original-issue
-// trace (zudolab/zudo-doc#1902 / #1882).
-//
-// Used by:
-//   - _sidebar-with-defaults.tsx / _header-with-defaults.tsx (per-page nav)
-//   - the 4 doc-route paths() files (route enumeration + nav tree)
-//   - route-enumerators.ts (sitemap) and the MDX nav wrappers
-// each picking the `NavSourceVariant` matching its filter needs.
-
-import { defaultLocale, getLocaleConfig, type Locale } from "@/config/i18n";
+// Thin stub — nav-source-docs moved to the package (epic #2344, S6).
+// Calls `createNavSourceDocs(ctx)` from @takazudo/zudo-doc/nav-source-docs
+// with the host singletons injected, then re-exports the resulting resolver
+// functions so all existing call sites continue to work unchanged.
+
+import { createNavSourceDocs } from "@takazudo/zudo-doc/nav-source-docs";
+export type { NavSourceDocs, NavSourceOptions } from "@takazudo/zudo-doc/nav-source-docs";
+import { defaultLocale, getLocaleConfig } from "@/config/i18n";
 import { settings } from "@/config/settings";
-import {
+import { loadCategoryMeta, isNavVisible } from "@/utils/docs";
+import { isDefaultLocaleOnlyPath } from "@/utils/base";
+import { stableDocs } from "./_nav-source-cache";
+
+const {
+  resolveNavSource,
+  resolveVersionedLocaleSource,
+  loadNavSourceDocs,
+  stableMergeCategoryMeta,
+  stableNavDocs,
+} = createNavSourceDocs({
+  defaultLocale,
+  docsDir: settings.docsDir,
+  getVersions: () => settings.versions,
+  getLocaleConfig,
   loadCategoryMeta,
   isNavVisible,
-  type CategoryMeta,
-} from "@/utils/docs";
-import type { DocsEntry } from "@/types/docs-entry";
-import type { DocPageEntry } from "./doc-page-props";
-import { stableDocs, memoizeDerived } from "./_nav-source-cache";
-import { mergeLocaleDocs } from "./locale-merge";
-
-// ---------------------------------------------------------------------------
-// Stable category-meta merge
-// ---------------------------------------------------------------------------
-
-// `loadCategoryMeta(dir)` is already memoized by dir (returns the same Map).
-// The locale merge of two such Maps, however, was minted fresh on every call —
-// breaking the `categoryMeta === categoryMeta` identity check in the nav-tree
-// fast-path. Memoize the merge on the (baseDir, localeDir) pair.
-const mergedCategoryMetaCache = new Map<string, Map<string, CategoryMeta>>();
-
-/** Base metadata first, locale overrides win on overlapping keys — same merge
- *  order the locale doc-route paths() use. Returns a STABLE Map per
- *  (baseDir, localeDir) pair. */
-export function stableMergeCategoryMeta(
-  baseDir: string,
-  localeDir: string,
-): Map<string, CategoryMeta> {
-  const key = `${baseDir}\n${localeDir}`;
-  const cached = mergedCategoryMetaCache.get(key);
-  if (cached) return cached;
-  const merged = new Map<string, CategoryMeta>([
-    ...loadCategoryMeta(baseDir),
-    ...loadCategoryMeta(localeDir),
-  ]);
-  mergedCategoryMetaCache.set(key, merged);
-  return merged;
-}
-
-// ---------------------------------------------------------------------------
-// Stable navDocs (isNavVisible filter) derived from a stable docs array
-// ---------------------------------------------------------------------------
-
-/** `docs.filter(isNavVisible)`, memoized on the stable `docs` identity so the
- *  filtered array also has stable identity for the nav-tree fast-path. */
-export function stableNavDocs<T extends DocsEntry>(docs: T[]): T[] {
-  return memoizeDerived([docs], "navVisible", () => docs.filter(isNavVisible));
-}
-
-// ---------------------------------------------------------------------------
-// Resolved nav source
-// ---------------------------------------------------------------------------
-
-export type NavSourceDocs = {
-  /** Full doc list (merged + draft-filtered; unlisted retained per options). */
-  docs: DocPageEntry[];
-  /** `docs.filter(isNavVisible)` — stable instance for buildNavTree. */
-  navDocs: DocPageEntry[];
-  /** Stable category-meta Map for the active (locale, version). */
-  categoryMeta: Map<string, CategoryMeta>;
-  /** Slugs that came from the locale collection (for isFallback). Empty for
-   *  default-locale / single-collection cases. */
-  localeSlugSet: ReadonlySet<string>;
+  isDefaultLocaleOnlyPath,
+  stableDocs,
+});
+
+export {
+  resolveNavSource,
+  resolveVersionedLocaleSource,
+  loadNavSourceDocs,
+  stableMergeCategoryMeta,
+  stableNavDocs,
 };
-
-/**
- * How to filter the merged doc list. The locale merge takes different options
- * at different call sites; the option signature is folded into the memo key so
- * variants never collide on a shared cache entry.
- */
-export interface NavSourceOptions {
-  /** Drop base docs matching `defaultLocaleOnlyPrefixes` (route/sidebar nav). */
-  applyDefaultLocaleOnlyFilter?: boolean;
-  /** Retain `unlisted: true` docs (route enumeration + nav). */
-  keepUnlisted?: boolean;
-}
-
-function optionSig(o: NavSourceOptions): string {
-  return `dlo=${o.applyDefaultLocaleOnlyFilter ? 1 : 0};ku=${o.keepUnlisted ? 1 : 0}`;
-}
-
-const EMPTY_SLUG_SET: ReadonlySet<string> = new Set();
-
-/**
- * Resolve the identity-stable nav source for an EN/locale (optionally
- * versioned) context. Every field is memoized so repeated calls with the same
- * logical inputs return the same instances.
- */
-export function resolveNavSource(
-  lang: Locale,
-  currentVersion: string | undefined,
-  options: NavSourceOptions = {},
-): NavSourceDocs {
-  const sig = optionSig(options);
-
-  // --- Versioned. For a non-default locale the version IS configured for,
-  //     delegate to resolveVersionedLocaleSource so every nav surface uses the
-  //     SAME version-scoped locale-first merge the page body / route
-  //     enumeration use (#1909) — keeping nav labels and locale-only version
-  //     pages in sync. Otherwise (default locale, or the version not configured
-  //     for this locale) fall back to the version's EN base collection.
-  if (currentVersion) {
-    // `versions` is `VersionConfig[] | false` — `false?.find` would throw
-    // (optional chaining only short-circuits on null/undefined).
-    const versionConfig = Array.isArray(settings.versions)
-      ? settings.versions.find((v) => v.slug === currentVersion)
-      : undefined;
-    const localeDir = versionConfig?.locales?.[lang]?.dir;
-    if (lang !== defaultLocale && localeDir) {
-      return resolveVersionedLocaleSource(
-        currentVersion,
-        versionConfig?.docsDir ?? settings.docsDir,
-        lang,
-        localeDir,
-        options,
-      );
-    }
-    const docs = stableDocs(`docs-v-${currentVersion}`);
-    const categoryMeta = loadCategoryMeta(versionConfig?.docsDir ?? settings.docsDir);
-    const navDocs = stableNavDocs(docs);
-    return { docs, navDocs, categoryMeta, localeSlugSet: EMPTY_SLUG_SET };
-  }
-
-  // --- Default locale: the "docs" collection directly.
-  if (lang === defaultLocale) {
-    const docs = stableDocs("docs");
-    const categoryMeta = loadCategoryMeta(settings.docsDir);
-    const navDocs = stableNavDocs(docs);
-    return { docs, navDocs, categoryMeta, localeSlugSet: EMPTY_SLUG_SET };
-  }
-
-  // --- Non-default locale: locale-first merge with EN fallback.
-  const baseDocs = stableDocs("docs");
-  const localeDocs = stableDocs(`docs-${lang}`);
-
-  const merged = memoizeDerived([baseDocs, localeDocs], `merge;${sig}`, () =>
-    mergeLocaleDocs<DocPageEntry>({
-      baseDocs,
-      localeDocs,
-      applyDefaultLocaleOnlyFilter: options.applyDefaultLocaleOnlyFilter,
-      keepUnlisted: options.keepUnlisted,
-    }),
-  );
-  const docs = merged.docs;
-
-  const localeDir = getLocaleConfig(lang)?.dir ?? settings.docsDir;
-  const categoryMeta = stableMergeCategoryMeta(settings.docsDir, localeDir);
-  const navDocs = stableNavDocs(docs);
-
-  return { docs, navDocs, categoryMeta, localeSlugSet: merged.localeSlugSet };
-}
-
-/**
- * Resolve the identity-stable nav source for a versioned non-default-locale
- * context — locale-specific version collection over the version's EN base.
- */
-export function resolveVersionedLocaleSource(
-  versionSlug: string,
-  versionDocsDir: string,
-  lang: Locale,
-  localeDir: string | undefined,
-  options: NavSourceOptions = {},
-): NavSourceDocs {
-  const sig = optionSig(options);
-  const baseDocs = stableDocs(`docs-v-${versionSlug}`);
-  const localeDocs = localeDir ? stableDocs(`docs-v-${versionSlug}-${lang}`) : EMPTY_DOCS;
-
-  const merged = memoizeDerived(
-    localeDir ? [baseDocs, localeDocs] : [baseDocs],
-    `vmerge;${lang};${sig}`,
-    () =>
-      mergeLocaleDocs<DocPageEntry>({
-        baseDocs,
-        localeDocs,
-        applyDefaultLocaleOnlyFilter: options.applyDefaultLocaleOnlyFilter,
-        keepUnlisted: options.keepUnlisted,
-      }),
-  );
-  const docs = merged.docs;
-
-  const categoryMeta = localeDir
-    ? stableMergeCategoryMeta(versionDocsDir, localeDir)
-    : loadCategoryMeta(versionDocsDir);
-  const navDocs = stableNavDocs(docs);
-
-  return { docs, navDocs, categoryMeta, localeSlugSet: merged.localeSlugSet };
-}
-
-// Shared empty array for the "no locale collection" branch — stable identity
-// keeps the merge memo consistent.
-const EMPTY_DOCS: DocPageEntry[] = [];
-
-// ---------------------------------------------------------------------------
-// Back-compat: loadNavSourceDocs (sidebar + header consumers)
-// ---------------------------------------------------------------------------
-
-/**
- * Per-page nav source for the desktop sidebar and mobile SidebarToggle.
- *
- * Thin adapter over {@link resolveNavSource} with the sidebar's filter options
- * (`applyDefaultLocaleOnlyFilter`, `keepUnlisted`). Returns `navDocs` already
- * filtered so callers pass it straight to `buildSidebarForSection` without a
- * fresh `.filter(isNavVisible)` that would defeat the nav-tree fast-path.
- */
-export function loadNavSourceDocs(
-  lang: Locale,
-  currentVersion: string | undefined,
-): NavSourceDocs {
-  return resolveNavSource(lang, currentVersion, {
-    applyDefaultLocaleOnlyFilter: true,
-    keepUnlisted: true,
-  });
-}