jamdesk 1.0.0

package/vendored/scripts/enhance-navigation.cjs

@@ -0,0 +1,354 @@
+#!/usr/bin/env node
+/**
+ * Enhance Navigation Script
+ *
+ * Reads docs.json and enhances navigation pages with metadata extracted from MDX frontmatter.
+ * This allows the sidebar to display:
+ * - Page titles from frontmatter (instead of path-derived titles)
+ * - API method badges (POST, GET, etc.) for API pages
+ *
+ * Usage:
+ *   node scripts/enhance-navigation.cjs                    # Uses default content directory
+ *   node scripts/enhance-navigation.cjs --project acme     # Uses project's content
+ *   PROJECT_NAME=acme node scripts/enhance-navigation.cjs  # Same as above
+ *
+ * Input:  projects/<name>/docs.json (or content/docs.json)
+ * Output: public/docs.json (enhanced with title/method from MDX frontmatter)
+ */
+
+const fs = require('fs');
+const fsPromises = require('fs/promises');
+const path = require('path');
+const matter = require('gray-matter');
+
+// Parse command line arguments
+const args = process.argv.slice(2);
+const projectArgIndex = args.indexOf('--project');
+const projectFromArg = projectArgIndex !== -1 ? args[projectArgIndex + 1] : null;
+const projectName = projectFromArg || process.env.PROJECT_NAME;
+
+// Determine paths based on project
+// Use JAMDESK_PROJECTS_DIR if set, otherwise fall back to local projects/
+const projectsDir = process.env.JAMDESK_PROJECTS_DIR || path.join(__dirname, '../projects');
+
+function getProjectDir() {
+  if (projectName) {
+    return path.join(projectsDir, projectName);
+  }
+  return path.join(__dirname, '../content');
+}
+
+function getDocsJsonPath() {
+  // Read from public/docs.json (already copied and has custom file flags)
+  return path.join(__dirname, '../public/docs.json');
+}
+
+function getOutputPath() {
+  return path.join(__dirname, '../public/docs.json');
+}
+
+/**
+ * Parse API method from frontmatter api field
+ * Examples:
+ *   "POST /analytics/post" -> "POST"
+ *   "GET" -> "GET"
+ *   "DELETE /user/{id}" -> "DELETE"
+ */
+function parseApiMethod(apiField) {
+  if (!apiField || typeof apiField !== 'string') return null;
+
+  const trimmed = apiField.trim().toUpperCase();
+  const methods = ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'HEAD', 'OPTIONS'];
+
+  for (const method of methods) {
+    if (trimmed.startsWith(method)) {
+      return method;
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Parse API method from frontmatter openapi field
+ * Examples:
+ *   "openapi/analyst-insights.yaml GET /analyst/insights" -> "GET"
+ *   "specs/users.yml POST /users" -> "POST"
+ *   "GET /path" -> "GET"  (fallback to api format)
+ */
+function parseOpenApiMethod(openapiField) {
+  if (!openapiField || typeof openapiField !== 'string') return null;
+
+  const trimmed = openapiField.trim();
+  const methods = ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'HEAD', 'OPTIONS'];
+
+  // Split by whitespace and look for method
+  const parts = trimmed.split(/\s+/);
+
+  for (const part of parts) {
+    const upper = part.toUpperCase();
+    if (methods.includes(upper)) {
+      return upper;
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Collect all page paths from navigation structure
+ */
+function collectPagePaths(navigation, paths = new Set()) {
+  if (!navigation) return paths;
+
+  // Handle pages array
+  if (navigation.pages && Array.isArray(navigation.pages)) {
+    for (const page of navigation.pages) {
+      const pagePath = typeof page === 'string' ? page : page?.page;
+      if (pagePath) paths.add(pagePath);
+    }
+  }
+
+  // Handle groups array
+  if (navigation.groups && Array.isArray(navigation.groups)) {
+    for (const group of navigation.groups) {
+      collectPagePaths(group, paths);
+    }
+  }
+
+  // Handle tabs array
+  if (navigation.tabs && Array.isArray(navigation.tabs)) {
+    for (const tab of navigation.tabs) {
+      collectPagePaths(tab, paths);
+    }
+  }
+
+  // Handle anchors array
+  if (navigation.anchors && Array.isArray(navigation.anchors)) {
+    for (const anchor of navigation.anchors) {
+      collectPagePaths(anchor, paths);
+    }
+  }
+
+  // Handle languages array (multi-language docs)
+  if (navigation.languages && Array.isArray(navigation.languages)) {
+    for (const lang of navigation.languages) {
+      collectPagePaths(lang, paths);
+    }
+  }
+
+  // Handle direct array (e.g., when passed a pages array directly)
+  if (Array.isArray(navigation)) {
+    for (const item of navigation) {
+      if (item && typeof item === 'object' && 'group' in item) {
+        collectPagePaths(item, paths);
+      } else {
+        const pagePath = typeof item === 'string' ? item : item?.page;
+        if (pagePath) paths.add(pagePath);
+      }
+    }
+  }
+
+  return paths;
+}
+
+/**
+ * Read all MDX frontmatter in parallel
+ */
+async function loadAllFrontmatter(pagePaths) {
+  const projectDir = getProjectDir();
+  const cache = new Map();
+
+  const promises = Array.from(pagePaths).map(async (pagePath) => {
+    const mdxPath = path.join(projectDir, pagePath + '.mdx');
+
+    try {
+      const content = await fsPromises.readFile(mdxPath, 'utf8');
+      const { data } = matter(content);
+      cache.set(pagePath, data);
+    } catch {
+      // File doesn't exist or can't be read - cache null
+      cache.set(pagePath, null);
+    }
+  });
+
+  await Promise.all(promises);
+  return cache;
+}
+
+/**
+ * Enhance a single page with cached frontmatter data
+ */
+function enhancePageWithCache(page, frontmatterCache) {
+  // If page is already an object with method/title, preserve it
+  const pagePath = typeof page === 'string' ? page : page.page;
+  const existingMethod = typeof page === 'object' ? page.method : undefined;
+  const existingTitle = typeof page === 'object' ? page.title : undefined;
+
+  // Get frontmatter from cache
+  const frontmatter = frontmatterCache.get(pagePath);
+
+  if (!frontmatter) {
+    // No frontmatter found, return original
+    return page;
+  }
+
+  // Extract title, method, icon, and tag from frontmatter
+  // Check both 'api' field (legacy) and 'openapi' field (new OpenAPI support)
+  const title = existingTitle || frontmatter.title;
+  const method = existingMethod ||
+    parseApiMethod(frontmatter.api) ||
+    parseOpenApiMethod(frontmatter.openapi);
+  const icon = frontmatter.icon;
+  const tag = frontmatter.tag;
+
+  // If we have enhancements, return object format
+  if (title || method || icon || tag) {
+    return {
+      page: pagePath,
+      ...(title && { title }),
+      ...(method && { method }),
+      ...(icon && { icon }),
+      ...(tag && { tag }),
+    };
+  }
+
+  // No enhancements, return original
+  return page;
+}
+
+/**
+ * Recursively enhance pages in a navigation structure
+ */
+function enhancePages(pages, cache) {
+  if (!pages || !Array.isArray(pages)) return pages;
+
+  return pages.map(item => {
+    // If it's a group (has 'group' property), recurse into its pages
+    if (item && typeof item === 'object' && 'group' in item) {
+      return {
+        ...item,
+        pages: enhancePages(item.pages, cache),
+      };
+    }
+
+    // It's a page, enhance it
+    return enhancePageWithCache(item, cache);
+  });
+}
+
+/**
+ * Enhance groups array
+ */
+function enhanceGroups(groups, cache) {
+  if (!groups || !Array.isArray(groups)) return groups;
+
+  return groups.map(group => ({
+    ...group,
+    pages: enhancePages(group.pages, cache),
+  }));
+}
+
+/**
+ * Enhance tabs array
+ */
+function enhanceTabs(tabs, cache) {
+  if (!tabs || !Array.isArray(tabs)) return tabs;
+
+  return tabs.map(tab => ({
+    ...tab,
+    ...(tab.groups && { groups: enhanceGroups(tab.groups, cache) }),
+    ...(tab.pages && { pages: enhancePages(tab.pages, cache) }),
+  }));
+}
+
+/**
+ * Enhance anchors array
+ */
+function enhanceAnchors(anchors, cache) {
+  if (!anchors || !Array.isArray(anchors)) return anchors;
+
+  return anchors.map(anchor => ({
+    ...anchor,
+    ...(anchor.groups && { groups: enhanceGroups(anchor.groups, cache) }),
+    ...(anchor.pages && { pages: enhancePages(anchor.pages, cache) }),
+    ...(anchor.tabs && { tabs: enhanceTabs(anchor.tabs, cache) }),
+  }));
+}
+
+/**
+ * Main function to enhance navigation
+ */
+async function enhanceNavigation() {
+  const docsJsonPath = getDocsJsonPath();
+  const outputPath = getOutputPath();
+
+  if (projectName) {
+    console.log(`🔧 Enhancing navigation for project: ${projectName}`);
+  }
+
+  // Check if docs.json exists
+  if (!fs.existsSync(docsJsonPath)) {
+    console.log(`  No docs.json found at ${docsJsonPath}, skipping enhancement`);
+    return;
+  }
+
+  // Read docs.json
+  let config;
+  try {
+    const content = fs.readFileSync(docsJsonPath, 'utf8');
+    config = JSON.parse(content);
+  } catch (err) {
+    console.error(`  Error reading docs.json: ${err.message}`);
+    process.exit(1);
+  }
+
+  console.log('  📖 Reading MDX frontmatter to enhance navigation...');
+
+  // Step 1: Collect all page paths from navigation
+  const pagePaths = collectPagePaths(config.navigation);
+
+  // Step 2: Load all frontmatter in parallel
+  const frontmatterCache = await loadAllFrontmatter(pagePaths);
+
+  // Step 3: Enhance navigation structure using cached frontmatter
+  if (config.navigation) {
+    // Handle languages wrapper (multi-language docs)
+    if (config.navigation.languages) {
+      config.navigation.languages = config.navigation.languages.map(lang => ({
+        ...lang,
+        ...(lang.anchors && { anchors: enhanceAnchors(lang.anchors, frontmatterCache) }),
+        ...(lang.tabs && { tabs: enhanceTabs(lang.tabs, frontmatterCache) }),
+        ...(lang.groups && { groups: enhanceGroups(lang.groups, frontmatterCache) }),
+        ...(lang.pages && { pages: enhancePages(lang.pages, frontmatterCache) }),
+      }));
+    }
+    if (config.navigation.anchors) {
+      config.navigation.anchors = enhanceAnchors(config.navigation.anchors, frontmatterCache);
+    }
+    if (config.navigation.tabs) {
+      config.navigation.tabs = enhanceTabs(config.navigation.tabs, frontmatterCache);
+    }
+    if (config.navigation.groups) {
+      config.navigation.groups = enhanceGroups(config.navigation.groups, frontmatterCache);
+    }
+    if (config.navigation.pages) {
+      config.navigation.pages = enhancePages(config.navigation.pages, frontmatterCache);
+    }
+  }
+
+  // Write enhanced config to public/docs.json
+  try {
+    fs.writeFileSync(outputPath, JSON.stringify(config, null, 2));
+    console.log(`  ✓ Enhanced navigation written to ${outputPath}`);
+  } catch (err) {
+    console.error(`  Error writing enhanced docs.json: ${err.message}`);
+    process.exit(1);
+  }
+}
+
+// Run the script
+enhanceNavigation().catch(err => {
+  console.error('Error enhancing navigation:', err);
+  process.exit(1);
+});