enhance-modules-json.js

#!/usr/bin/env node

// Purpose: Enhances the modules.json with filesystem content structure
// for both auto-generated and human-written documentation

const fs = require('fs');
const path = require('path');

// Get paths from environment or use defaults
const DOCS_VERSION_DIR = process.env.DOCS_VERSION_DIR || path.join(__dirname, '../../../website/src/content/docs/main');
const OUTPUT_DIR = path.join(DOCS_VERSION_DIR, 'modules');
const MODULES_JSON_PATH = path.join(DOCS_VERSION_DIR, 'modules.json');

// Read the existing modules.json generated by the bash script
function readExistingModulesJson() {
  try {
    const content = fs.readFileSync(MODULES_JSON_PATH, 'utf8');
    return JSON.parse(content);
  } catch (error) {
    console.error('Error reading modules.json:', error);
    return { modules: [] };
  }
}

// Scan a module directory for manual documentation files
function scanModuleDirectory(moduleDir, moduleName) {
  const content = { reference: null, guides: [], examples: [] };
  
  if (!fs.existsSync(moduleDir)) {
    return content;
  }

  const items = fs.readdirSync(moduleDir, { withFileTypes: true });
  
  for (const item of items) {
    if (item.name === 'reference' && item.isDirectory()) {
      // Reference docs are auto-generated, just mark as present
      content.reference = { path: '/reference', text: 'Reference' };
    } else if (item.isFile() && item.name.endsWith('.mdx') && item.name !== 'index.mdx') {
      // Human-written guides at the module root level
      const baseName = path.basename(item.name, '.mdx');
      const title = formatTitle(baseName);
      content.guides.push({
        path: `/${baseName}`,
        text: title,
        file: item.name
      });
    } else if (item.isDirectory() && item.name === 'examples') {
      // Examples subdirectory
      const examplesDir = path.join(moduleDir, 'examples');
      const exampleFiles = fs.readdirSync(examplesDir, { withFileTypes: true })
        .filter(file => file.isFile() && file.name.endsWith('.mdx'))
        .map(file => {
          const baseName = path.basename(file.name, '.mdx');
          const title = formatTitle(baseName);
          return {
            path: `/examples/${baseName}`,
            text: title,
            file: file.name
          };
        });
      
      if (exampleFiles.length > 0) {
        content.examples = exampleFiles;
      }
    }
  }

  return content;
}

// Convert kebab-case to Title Case
function formatTitle(str) {
  return str
    .split('-')
    .map(word => word.charAt(0).toUpperCase() + word.slice(1))
    .join(' ');
}

// Build the enhanced module structure
function buildEnhancedModuleStructure(module) {
  const moduleDir = path.join(OUTPUT_DIR, module.module);
  const content = scanModuleDirectory(moduleDir, module.module);
  
  // Build the sub-navigation structure
  const sub = [];
  
  // Always add reference first if it exists
  if (content.reference) {
    sub.push(content.reference);
  }
  
  // Add guides
  if (content.guides.length > 0) {
    sub.push(...content.guides);
  }
  
  // Add examples as a submenu if they exist
  if (content.examples.length > 0) {
    sub.push({
      path: '/examples',
      text: 'Examples',
      sub: content.examples
    });
  }
  
  return {
    ...module,
    sub: sub.length > 0 ? sub : undefined,
    hasContent: sub.length > 0
  };
}

// Main function
function enhanceModulesJson() {
  console.log('Enhancing modules.json with filesystem content...');
  
  const existingData = readExistingModulesJson();
  
  // Enhance each module with content structure
  const enhancedModules = existingData.modules.map(buildEnhancedModuleStructure);
  
  // Update the JSON structure
  const enhancedData = {
    ...existingData,
    modules: enhancedModules,
    generatedAt: new Date().toISOString(),
    version: '2.0'
  };
  
  // Write the enhanced JSON back
  fs.writeFileSync(MODULES_JSON_PATH, JSON.stringify(enhancedData, null, 2));
  
  console.log(`Enhanced modules.json with ${enhancedModules.length} modules`);
  
  // Log summary of content found
  const modulesWithContent = enhancedModules.filter(m => m.hasContent);
  const modulesWithGuides = enhancedModules.filter(m => m.sub?.some(s => s.file));
  const modulesWithExamples = enhancedModules.filter(m => m.sub?.some(s => s.sub));
  
  console.log(`- ${modulesWithContent.length} modules have additional content`);
  console.log(`- ${modulesWithGuides.length} modules have human-written guides`);
  console.log(`- ${modulesWithExamples.length} modules have examples`);
}

// Run if called directly
if (require.main === module) {
  enhanceModulesJson();
}

module.exports = { enhanceModulesJson, scanModuleDirectory, formatTitle };