create-zudo-doc 0.2.0 → 0.2.1

package/templates/base/src/utils/docs.ts

@@ -1,22 +1,24 @@
 import type { DocsEntry } from "@/types/docs-entry";
-import fs from "node:fs";
-import path from "node:path";
-import { toTitleCase, toRouteSlug } from "@/utils/slug";
 import { docsUrl, withBase } from "@/utils/base";
 import { defaultLocale, type Locale } from "@/config/i18n";
+import {
+  buildSidebarTree,
+  type CategoryMeta,
+  type SidebarNode,
+} from "@takazudo/zudo-doc/sidebar-tree";
 
 /** Filter predicate: true when a doc should appear in navigation (sidebar, index, sitemap). */
 export function isNavVisible(doc: DocsEntry): boolean {
   return !doc.data.unlisted && !doc.data.standalone;
 }
 
-export interface CategoryMeta {
-  label?: string;
-  position?: number;
-  description?: string;
-  sortOrder?: "asc" | "desc";
-  noPage?: boolean;
-}
+// `_category_.json` loading + per-directory memoization live in the shared
+// framework package — the host keeps no parallel copy (#2030 dedup). The
+// package memoizes per resolved (absolute) contentDir, so the returned Map
+// instance is stable per directory — which `stableMergeCategoryMeta` and the
+// identity fast-path below rely on.
+export { loadCategoryMeta } from "@takazudo/zudo-doc/sidebar-tree";
+export type { CategoryMeta } from "@takazudo/zudo-doc/sidebar-tree";
 
 export interface NavNode {
   slug: string;
@@ -30,16 +32,39 @@ export interface NavNode {
   collapsed?: boolean;
 }
 
-interface BuildNode {
-  segment: string;
-  fullPath: string;
-  doc?: DocsEntry;
-  children: Map<string, BuildNode>;
+// Module-level cache — persists across all page renders during a single build.
+//
+// Bounded LRU, cap 64. A production build only ever needs a handful of
+// distinct keys — one per (locale × version × categoryMeta-variant), single
+// digits for this corpus — so 64 never evicts within one build. The cap
+// exists for dev: every content edit under HMR produces a NEW content key
+// (the key embeds nav-affecting frontmatter by design, so edits bust the
+// cache), and before #2030 the Map grew unbounded across a long dev session,
+// each entry holding an O(corpus) key string plus a full tree. With the cap,
+// stale generations age out once 64 fresher keys land. (#1902's WeakMap
+// identity fast-path keeps production hits off this Map entirely.)
+const NAV_TREE_CACHE_MAX = 64;
+const navTreeCache = new Map<string, NavNode[]>();
+
+function navTreeCacheGet(key: string): NavNode[] | undefined {
+  const hit = navTreeCache.get(key);
+  if (hit !== undefined) {
+    // Refresh recency — Map preserves insertion order, so delete+set moves
+    // the entry to the "most recently used" end.
+    navTreeCache.delete(key);
+    navTreeCache.set(key, hit);
+  }
+  return hit;
 }
 
-// Module-level caches — persist across all page renders during a single Astro build.
-const categoryMetaCache = new Map<string, Map<string, CategoryMeta>>();
-const navTreeCache = new Map<string, NavNode[]>();
+function navTreeCacheSet(key: string, value: NavNode[]): void {
+  navTreeCache.delete(key);
+  navTreeCache.set(key, value);
+  if (navTreeCache.size > NAV_TREE_CACHE_MAX) {
+    const oldest = navTreeCache.keys().next().value;
+    if (oldest !== undefined) navTreeCache.delete(oldest);
+  }
+}
 
 // Identity fast-path cache. Keyed on the docs-array reference: when nav-source
 // loaders hand back the SAME stable array instance across the build's many
@@ -99,12 +124,13 @@ function navTreeCacheKey(
 }
 
 /**
- * Build a recursive navigation tree from a flat Astro content collection.
+ * Build a recursive navigation tree from a flat content collection.
  * Mirrors the filesystem: directories become category nodes, files become leaves.
  *
- * Astro 5 glob() strips /index from IDs:
- *   getting-started/index.mdx → ID "getting-started" (category index)
- *   getting-started/intro.mdx → ID "getting-started/intro" (child page)
+ * Since #2030 the tree construction itself is delegated to the shared
+ * framework builder (`buildSidebarTree` in @takazudo/zudo-doc/sidebar-tree);
+ * this function keeps the host-side concerns: the NavNode shape consumed by
+ * every host nav surface, the content-key cache, and the identity fast-path.
  */
 export function buildNavTree(
   docs: DocsEntry[],
@@ -123,62 +149,110 @@ export function buildNavTree(
   }
 
   const cacheKey = navTreeCacheKey(docs, lang, categoryMeta);
-  const cached = navTreeCache.get(cacheKey);
+  const cached = navTreeCacheGet(cacheKey);
   if (cached) {
     rememberIdentity(docs, lang, categoryMeta, cached);
     return cached;
   }
 
-  const root: BuildNode = {
-    segment: "",
-    fullPath: "",
-    children: new Map(),
-  };
-
-  for (const doc of docs) {
-    const slug = doc.data.slug ?? toRouteSlug(doc.id);
-    const parts = slug.split("/");
-
-    if (parts.length <= 1) {
-      // Category index: Astro 5 stripped /index → single segment like "guides".
-      // Key by the route slug (honors a custom frontmatter `slug`), not the raw
-      // id — otherwise the sidebar/breadcrumb link diverges from the built route.
-      const segment = parts[0] || doc.id;
-      if (!root.children.has(segment)) {
-        root.children.set(segment, {
-          segment,
-          fullPath: segment,
-          children: new Map(),
-        });
-      }
-      root.children.get(segment)!.doc = doc;
-    } else {
-      // Multi-segment: walk the tree creating intermediate nodes as needed
-      let current = root;
-      for (let i = 0; i < parts.length; i++) {
-        const segment = parts[i] ?? "";
-        const fullPath = parts.slice(0, i + 1).join("/");
-        if (!current.children.has(segment)) {
-          current.children.set(segment, {
-            segment,
-            fullPath,
-            children: new Map(),
-          });
-        }
-        if (i === parts.length - 1) {
-          current.children.get(segment)!.doc = doc;
-        }
-        current = current.children.get(segment)!;
-      }
-    }
+  const sidebarTree = buildSidebarTree(
+    // Pass `{ id, data }` only — NOT the whole entry. zfb entries carry the
+    // raw, un-index-stripped engine slug on the top-level `slug` field
+    // (e.g. "getting-started/index"), and the shared builder prefers
+    // `entry.slug` over the id-derived form; forwarding it would mint wrong
+    // node paths. Omitting it reproduces the legacy host derivation
+    // `data.slug ?? toRouteSlug(id)` (ids arrive pre-stripped via _data.ts).
+    docs.map((d) => ({ id: d.id, data: d.data })),
+    lang,
+    {
+      categoryMeta,
+      buildHref: (slug, locale) => docsUrl(slug, locale),
+      // Host call sites own visibility: nav surfaces pre-filter via
+      // `stableNavDocs(docs.filter(isNavVisible))`, while the breadcrumb tree
+      // intentionally builds from the UNFILTERED list so unlisted pages still
+      // get breadcrumbs. Disable the builder's default unlisted/standalone
+      // filter so neither path changes behavior.
+      isNavVisible: () => true,
+    },
+  );
+  const result = sidebarTree.map(toNavNode);
+
+  // Root docs-index entry (derived slug "" — a root index.mdx arrives from
+  // _data.ts bridging as id ""). The shared builder drops empty slugs, but the
+  // legacy host builder minted a top-level node keyed "" (href /docs/) so the
+  // root page stayed present in sidebar/breadcrumb/prev-next data. Re-create
+  // that node here with the exact legacy field derivation, then re-sort with
+  // the same comparator the builder used (stable sort → idempotent for the
+  // already-sorted rest).
+  const rootDoc = findRootIndexDoc(docs);
+  if (rootDoc) {
+    result.push(toRootNavNode(rootDoc, lang, categoryMeta));
+    result.sort((a, b) => {
+      const posCompare = a.position - b.position;
+      if (posCompare !== 0) return posCompare;
+      return a.slug.localeCompare(b.slug);
+    });
   }
 
-  const result = toNavNodes(root, lang, categoryMeta);
-  navTreeCache.set(cacheKey, result);
+  navTreeCacheSet(cacheKey, result);
   rememberIdentity(docs, lang, categoryMeta, result);
   return result;
 }
 
+/** Last entry whose package-derived slug is empty ("") — i.e. the entry the
+ *  shared builder skips. Last one wins, mirroring the legacy builder's
+ *  `node.doc = doc` overwrite. (A bare id "index" is NOT matched here: both
+ *  the legacy and shared builders resolve it to a node keyed "index".) */
+function findRootIndexDoc(docs: DocsEntry[]): DocsEntry | undefined {
+  let found: DocsEntry | undefined;
+  for (const d of docs) {
+    const slug = d.data.slug ?? d.id.replace(/\/index$/, "");
+    if (slug === "") found = d;
+  }
+  return found;
+}
+
+/** Legacy-faithful node for the root docs index (slug ""): no children are
+ *  possible (a multi-segment slug never has an empty first part), label falls
+ *  back through the same chain (title is required, so it always resolves),
+ *  and href is the locale docs root. */
+function toRootNavNode(
+  doc: DocsEntry,
+  lang: Locale,
+  categoryMeta?: Map<string, CategoryMeta>,
+): NavNode {
+  const meta = categoryMeta?.get("");
+  const noPage = doc.data.category_no_page ?? meta?.noPage;
+  const sortOrder = doc.data.category_sort_order ?? meta?.sortOrder ?? "asc";
+  return {
+    slug: "",
+    label: doc.data.sidebar_label ?? doc.data.title ?? meta?.label ?? "",
+    description: doc.data.description ?? meta?.description,
+    position: doc.data.sidebar_position ?? meta?.position ?? 999,
+    href: noPage ? undefined : docsUrl("", lang),
+    hasPage: noPage !== true,
+    children: [],
+    sortOrder,
+  };
+}
+
+/** Map the shared builder's SidebarNode shape onto the host NavNode shape.
+ *  `position` and `sortOrder` defaults mirror the legacy inline builder:
+ *  position falls back to 999 (ties sort alphabetically) and sortOrder is
+ *  always materialized ("asc" unless frontmatter/sidecar set it). */
+function toNavNode(node: SidebarNode): NavNode {
+  return {
+    slug: node.id,
+    label: node.label,
+    description: node.description,
+    position: node.sidebar_position ?? 999,
+    href: node.href,
+    hasPage: node.hasPage,
+    children: node.children.map(toNavNode),
+    sortOrder: node.sortOrder ?? "asc",
+  };
+}
+
 /** Record a (docs-array identity, lang, categoryMeta) → tree mapping for the
  *  identity fast-path. No-op-safe to call multiple times for the same slot. */
 function rememberIdentity(
@@ -197,55 +271,6 @@ function rememberIdentity(
   }
 }
 
-function toNavNodes(
-  parent: BuildNode,
-  lang: Locale,
-  categoryMeta?: Map<string, CategoryMeta>,
-  parentSortOrder?: "asc" | "desc",
-): NavNode[] {
-  const nodes: NavNode[] = [];
-
-  for (const child of parent.children.values()) {
-    const doc = child.doc;
-    const meta = categoryMeta?.get(child.fullPath);
-    // Frontmatter wins over the `_category_.json` sidecar when both exist.
-    const noPage = doc?.data.category_no_page ?? meta?.noPage;
-    const sortOrder = doc?.data.category_sort_order ?? meta?.sortOrder ?? "asc";
-    const children = toNavNodes(child, lang, categoryMeta, sortOrder);
-
-    nodes.push({
-      slug: child.fullPath,
-      label:
-        doc?.data.sidebar_label ?? doc?.data.title ?? meta?.label ?? toTitleCase(child.segment),
-      description: doc?.data.description ?? meta?.description,
-      position: doc?.data.sidebar_position ?? meta?.position ?? 999,
-      href: noPage
-        ? undefined
-        : doc || children.length > 0
-          ? docsUrl(child.fullPath, lang)
-          : undefined,
-      // A `category_no_page` index.mdx is metadata-only — force hasPage false so
-      // it matches a `_category_.json` noPage category (no backing file): a
-      // non-linked header that flattenTree drops from prev/next. Otherwise the
-      // route-excluded slug would surface as a 404 pagination target.
-      hasPage: !!doc && noPage !== true,
-      children,
-      sortOrder,
-    });
-  }
-
-  // Use the PARENT's sortOrder to sort these sibling nodes
-  const order = parentSortOrder ?? "asc";
-  nodes.sort((a, b) => {
-    const posCompare = a.position - b.position;
-    if (posCompare !== 0) return order === "desc" ? -posCompare : posCompare;
-    const slugCompare = a.slug.localeCompare(b.slug);
-    return order === "desc" ? -slugCompare : slugCompare;
-  });
-
-  return nodes;
-}
-
 /**
  * Group "satellite" nodes under their primary node based on slug prefixes.
  * E.g. with prefix "claude", nodes "claude-md", "claude-commands" get moved
@@ -348,8 +373,9 @@ export interface BreadcrumbItem {
 /**
  * Build breadcrumb trail by walking the nav tree.
  *
- * Nav-node hrefs are always the LATEST `docsUrl(slug, lang)` values (see
- * `toNavNodes`). On versioned routes that would make breadcrumbs link back to
+ * Nav-node hrefs are always the LATEST `docsUrl(slug, lang)` values (see the
+ * `buildHref` wiring in `buildNavTree`). On versioned routes that would make
+ * breadcrumbs link back to
  * latest content (#1916 #1). Pass an optional `hrefFor(slug)` to remap each
  * intermediate crumb's href to the route's own URL space (e.g.
  * `versionedDocsUrl`-bound). The home crumb and the current/last crumb carry no
@@ -387,54 +413,3 @@ export function buildBreadcrumbs(
 
   return crumbs;
 }
-
-/**
- * Scan a content directory for _category_.json files and return a map
- * of relative paths to category metadata.
- * Results are memoized by contentDir.
- */
-export function loadCategoryMeta(contentDir: string): Map<string, CategoryMeta> {
-  const cached = categoryMetaCache.get(contentDir);
-  if (cached) return cached;
-  const result = new Map<string, CategoryMeta>();
-  scanDir(contentDir, contentDir, result);
-  categoryMetaCache.set(contentDir, result);
-  return result;
-}
-
-function scanDir(baseDir: string, currentDir: string, result: Map<string, CategoryMeta>): void {
-  let entries: fs.Dirent[];
-  try {
-    entries = fs.readdirSync(currentDir, { withFileTypes: true });
-  } catch {
-    return;
-  }
-
-  for (const entry of entries) {
-    if (entry.isDirectory()) {
-      const fullPath = path.join(currentDir, entry.name);
-      const categoryFile = path.join(fullPath, "_category_.json");
-      if (fs.existsSync(categoryFile)) {
-        try {
-          const raw = fs.readFileSync(categoryFile, "utf-8");
-          const parsed: unknown = JSON.parse(raw);
-          if (typeof parsed === "object" && parsed !== null) {
-            const obj = parsed as Record<string, unknown>;
-            const meta: CategoryMeta = {
-              label: typeof obj.label === "string" ? obj.label : undefined,
-              position: typeof obj.position === "number" ? obj.position : undefined,
-              description: typeof obj.description === "string" ? obj.description : undefined,
-              sortOrder: obj.sortOrder === "asc" || obj.sortOrder === "desc" ? obj.sortOrder : undefined,
-              noPage: obj.noPage === true ? true : undefined,
-            };
-            const relativePath = path.relative(baseDir, fullPath);
-            result.set(relativePath, meta);
-          }
-        } catch {
-          // skip invalid JSON
-        }
-      }
-      scanDir(baseDir, fullPath, result);
-    }
-  }
-}

package/templates/features/claudeResources/files/plugins/claude-resources-plugin.mjs

@@ -1,135 +1,45 @@
+// @ts-check
 // zfb plugin module: claude-resources.
 //
 // Wires `runClaudeResourcesPreStep` (from
 // `@takazudo/zudo-doc/integrations/claude-resources`) into zfb's
-// `preBuild` lifecycle hook. Replaces the npm `prebuild`-script glue
-// in `scripts/zfb-prebuild.mjs` for this step (the script remains in
-// place during the merge window — T6 retires it).
+// `preBuild` lifecycle hook.
 //
-// Why this shim exists (and is not the v2 integration module directly):
-//
-//   1. zfb's plugin host runs `node` without any TypeScript loader, so
-//      it cannot import `.ts` source files. The v2 integration package
-//      (`@takazudo/zudo-doc/integrations/claude-resources`) currently
-//      ships only TypeScript source through its `exports` map and has
-//      no build step.
-//
-//   2. The `runClaudeResourcesPreStep` runner pulls in `gray-matter`,
-//      which performs a CJS `require("fs")` that esbuild's
-//      configuration-loader bundle (ESM-only) cannot satisfy. Loading
-//      it inline at the top of `zfb.config.ts` therefore breaks config
-//      parsing entirely.
-//
-// Both problems are solved by isolating the runner behind a child
-// process: this shim spawns `tsx` (the project's existing TS-aware
-// Node runner, pinned via `tsx` in `package.json`) on a tiny inline
-// script that imports the runner. tsx handles `.ts` resolution and
-// Node's CJS↔ESM interop for gray-matter; the parent plugin host stays
-// in plain Node and only sees a child-process exit code.
-//
-// Inline functions are not supported by zfb's plugin runtime — see
-// `@takazudo/zfb/plugins` source comment. This file is the plugin-host
-// equivalent once the npm script is retired (T6).
-
-import { spawn } from "node:child_process";
-import { fileURLToPath } from "node:url";
-import { dirname, resolve } from "node:path";
-
-const PLUGIN_NAME = "@takazudo/zudo-doc-claude-resources";
+// Previously this shim spawned a `tsx` subprocess because the integration
+// package shipped only TypeScript source (no build step) and `gray-matter`
+// pulled in a CJS `require("fs")` that esbuild's ESM-only config-loader
+// bundle could not satisfy. Both constraints are now lifted: the package
+// ships compiled `dist/` and the plugin host is plain Node (not an esbuild
+// bundle), so the runner can be imported directly.
 
-// `tsx` is a workspace dependency of the host project and resolves to
-// `<projectRoot>/node_modules/.bin/tsx` from this file. We resolve the
-// binary explicitly so the shim does not depend on the parent shell's
-// `PATH` (the plugin host is spawned by zfb without sourcing the
-// user's profile — Node's `PATH` is whatever zfb itself was launched
-// with).
-const HERE = dirname(fileURLToPath(import.meta.url));
-const TSX_BIN = resolve(HERE, "..", "node_modules", ".bin", "tsx");
+/** @import { ZfbBuildHookContext, ZfbPlugin } from "@takazudo/zfb/plugins" */
 
-/**
- * Run the v2 claude-resources runner under tsx.
- *
- * Inlines a minimal ESM script via `tsx -e` so we don't have to ship a
- * second `.ts` file just to host the call site. The runner returns a
- * `{ claudemd, commands, skills, agents }` summary which we re-emit on
- * the child's stdout — the parent (this shim) parses it and forwards
- * the summary to the plugin host's logger.
- */
-function runRunnerUnderTsx({ claudeDir, projectRoot, docsDir }) {
-  // The runner accepts `projectRoot` and `docsDir` as relative paths
-  // (resolved against `process.cwd()` in the runner). To insulate the
-  // child from whatever cwd zfb spawned us with, we set cwd explicitly
-  // and pass absolute paths through.
-  // tsx's `-e` flag emits CJS by default (it picks the format from the
-  // entry's extension, and an inline `-e` script has none), so we wrap
-  // the body in an `async`-IIFE rather than relying on top-level await.
-  const childScript = `
-    (async () => {
-      const { runClaudeResourcesPreStep } = await import("@takazudo/zudo-doc/integrations/claude-resources");
-      const result = await runClaudeResourcesPreStep({
-        claudeDir: ${JSON.stringify(claudeDir)},
-        projectRoot: ${JSON.stringify(projectRoot)},
-        docsDir: ${JSON.stringify(docsDir)},
-      });
-      process.stdout.write(JSON.stringify(result));
-    })().catch((err) => {
-      process.stderr.write(err && err.stack ? err.stack : String(err));
-      process.exit(1);
-    });
-  `;
+import { runClaudeResourcesPreStep } from "@takazudo/zudo-doc/integrations/claude-resources";
 
-  return new Promise((resolveCall, reject) => {
-    const child = spawn(TSX_BIN, ["-e", childScript], {
-      cwd: projectRoot,
-      stdio: ["ignore", "pipe", "pipe"],
-    });
-    let stdout = "";
-    let stderr = "";
-    child.stdout.on("data", (chunk) => { stdout += chunk.toString(); });
-    child.stderr.on("data", (chunk) => { stderr += chunk.toString(); });
-    child.on("error", reject);
-    child.on("close", (code) => {
-      if (code !== 0) {
-        reject(
-          new Error(
-            `[${PLUGIN_NAME}] runner exited with code ${code}\n${stderr}`,
-          ),
-        );
-        return;
-      }
-      try {
-        resolveCall(JSON.parse(stdout));
-      } catch (err) {
-        reject(
-          new Error(
-            `[${PLUGIN_NAME}] failed to parse runner stdout: ${err.message}\nstdout: ${stdout}\nstderr: ${stderr}`,
-          ),
-        );
-      }
-    });
-  });
-}
+const PLUGIN_NAME = "@takazudo/zudo-doc-claude-resources";
 
+/** @type {ZfbPlugin} */
 export default {
   name: PLUGIN_NAME,
+
+  /** @param {ZfbBuildHookContext} ctx */
   async preBuild(ctx) {
-    const claudeDir = ctx.options.claudeDir;
+    const claudeDir = ctx.options["claudeDir"];
     if (typeof claudeDir !== "string" || claudeDir.length === 0) {
       throw new Error(
         `[${PLUGIN_NAME}] preBuild: options.claudeDir must be a non-empty string (got ${JSON.stringify(claudeDir)})`,
       );
     }
-    const projectRootOpt = ctx.options.projectRoot;
-    const docsDirOpt = ctx.options.docsDir;
-    const result = await runRunnerUnderTsx({
+    const projectRootOpt = ctx.options["projectRoot"];
+    const docsDirOpt = ctx.options["docsDir"];
+    const result = await runClaudeResourcesPreStep({
       claudeDir,
       projectRoot:
         typeof projectRootOpt === "string" ? projectRootOpt : ctx.projectRoot,
       docsDir: typeof docsDirOpt === "string" ? docsDirOpt : "src/content/docs",
     });
-    // Surface a one-line summary so build logs make the migration
-    // observable (mirrors the `[zfb-prebuild]` lines from the legacy
-    // npm-script glue).
+    // Surface a one-line summary so build logs make the generation
+    // observable.
     ctx.logger.info(
       `claude-resources: ${result.claudemd} CLAUDE.md, ${result.commands} commands, ${result.skills} skills, ${result.agents} agents`,
     );