generate-folder-indexes.cjs

#!/usr/bin/env node

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

let matter = null;
try {
  matter = require('gray-matter');
} catch (error) {
  console.warn('gray-matter not available; using basic frontmatter parser.');
}

// Absolute path to the docs pages directory that we crawl.
const DOCS_ROOT = path.join(__dirname, '..', 'docs', 'pages');
// Markers so we only overwrite files previously generated by this script.
const GENERATED_MARKER = '{/* AUTOGENERATED: This file is generated by utils/generate-folder-indexes.js */}';
const LEGACY_MARKER = '<!-- AUTOGENERATED: This file is generated by utils/generate-folder-indexes.js -->';
// Allow the caller to force refresh manually-maintained indexes.
const FORCE = process.argv.includes('--force');

let unchangedCount = 0;
let changedCount = 0;
// Message rendered on each generated page to set expectations for readers.
const NAVIGATION_NOTICE = '> _Note:_ This page is auto-generated. Please use the sidebar to explore the docs instead of\n' +
  '> navigating directory paths directly.';

// Known acronyms that toTitleCase would otherwise mangle (e.g. "vpns" → "Vpns").
const ACRONYM_MAP = {
  vpn: 'VPN',
  vpns: 'VPNs',
};

// Normalises file/folder names like `risk-management` into `Risk Management`.
function toTitleCase(input) {
  if (!input) return '';
  return input
    .replace(/[._-]+/g, ' ')
    .split(' ')
    .filter(Boolean)
    .map((word) => {
      const lower = word.toLowerCase();
      return ACRONYM_MAP[lower] ?? (word.charAt(0).toUpperCase() + word.slice(1));
    })
    .join(' ');
}

// Minimal frontmatter parser with a gray-matter fallback.
function parseFrontmatter(raw) {
  if (matter) {
    return matter(raw).data || {};
  }

  const match = raw.match(/^---\n([\s\S]*?)\n---/);
  if (!match) {
    return {};
  }

  const lines = match[1].split('\n');
  const data = {};
  for (const line of lines) {
    const trimmed = line.trim();
    if (!trimmed || trimmed.startsWith('#')) continue;
    const colonIndex = trimmed.indexOf(':');
    if (colonIndex === -1) continue;
    const key = trimmed.slice(0, colonIndex).trim();
    let value = trimmed.slice(colonIndex + 1).trim();
    value = value.replace(/^['"]|['"]$/g, '');
    if (key && value && !(key in data)) {
      data[key] = value;
    }
  }
  return data;
}

// Strips SEO suffixes like "| Security Alliance" or "| SEAL" from titles.
function cleanTitle(title) {
  if (!title) return '';
  return title
    .replace(/\s*\|\s*Security Alliance\s*$/i, '')
    .replace(/\s*\|\s*SEAL\s*$/i, '')
    .trim();
}

// Attempts to read the frontmatter title from a file, ignoring errors.
function readFrontmatterTitle(filePath) {
  try {
    const raw = fs.readFileSync(filePath, 'utf8');
    const parsed = parseFrontmatter(raw);
    const title = parsed && typeof parsed.title === 'string'
      ? parsed.title.trim()
      : '';
    return cleanTitle(title);
  } catch (error) {
    console.warn(`Warning: unable to read frontmatter from ${filePath}: ${error.message}`);
    return '';
  }
}

// Escapes double quotes so titles stay valid YAML.
function escapeFrontmatterValue(value) {
  return value.replace(/"/g, '\\"');
}

// Ensure Windows-style paths are converted to POSIX-style.
function normalizeSlashes(p) {
  return p.replace(/\\/g, '/');
}

// Converts a relative MDX path into a route path (e.g. `opsec/guide.mdx` -> `/opsec/guide`).
function toRoutePathFromRelative(relativePath) {
  const normalized = normalizeSlashes(relativePath);
  const withoutExtension = normalized.replace(/\.mdx$/i, '');
  let route = `/${withoutExtension}`;
  route = route.replace(/\/+/g, '/');
  if (route.length > 1 && route.endsWith('/index')) {
    route = route.slice(0, -('/index'.length));
  }
  if (route.length > 1 && route.endsWith('/')) {
    route = route.slice(0, -1);
  }
  return route;
}

// Normalises routes coming from sidebar links so we can compare easily.
function normalizeRouteFromLink(link) {
  if (!link) {
    return '/';
  }
  let route = normalizeSlashes(String(link).trim());
  if (!route.startsWith('/')) {
    route = `/${route}`;
  }
  route = route.replace(/\/+/g, '/');
  if (route.length > 1 && route.endsWith('/')) {
    route = route.slice(0, -1);
  }
  return route || '/';
}

// Adds a route and its ancestor segments (e.g. `/opsec/travel` -> `/opsec`, `/opsec/travel`).
function addRouteWithAncestors(route, routeSet) {
  if (!route || route === '/') {
    return;
  }
  const segments = route.split('/').filter(Boolean);
  let current = '';
  segments.forEach((segment) => {
    current += `/${segment}`;
    routeSet.add(current);
  });
}

// Recursively extracts every route in the sidebar configuration.
// Also builds an order map if provided (key: route, value: position index).
function collectRoutesFromSidebar(items, routeSet, orderMap = null, counter = { value: 0 }) {
  if (!Array.isArray(items) || items.length === 0) {
    return;
  }
  items.forEach((item) => {
    if (!item || typeof item !== 'object') {
      return;
    }
    if (typeof item.link === 'string') {
      const route = normalizeRouteFromLink(item.link);
      addRouteWithAncestors(route, routeSet);
      if (orderMap && !orderMap.has(route)) {
        orderMap.set(route, counter.value++);
      }
    }
    if (Array.isArray(item.items)) {
      collectRoutesFromSidebar(item.items, routeSet, orderMap, counter);
    }
  });
}

// Determines the current Git branch, ignoring failures (e.g. CI without git metadata).
function detectCurrentBranch() {
  try {
    const result = childProcess.execSync('git rev-parse --abbrev-ref HEAD', {
      cwd: path.join(__dirname, '..'),
      stdio: ['ignore', 'pipe', 'ignore'],
    });
    return result.toString().trim();
  } catch (error) {
    return null;
  }
}

// Resolves the active branch from environment variables or Git.
function resolveCurrentBranch() {
  const candidates = [
    process.env.CF_PAGES_BRANCH,
    process.env.BRANCH,
    process.env.GITHUB_REF_NAME,
  ];

  for (const candidate of candidates) {
    if (typeof candidate === 'string') {
      const trimmed = candidate.trim();
      if (trimmed) {
        return trimmed;
      }
    }
  }

  return detectCurrentBranch();
}

// Decides whether the current branch should be treated as production (`main`) for filtering.
function resolvePrimaryFilterBranch() {
  const branch = resolveCurrentBranch();
  if (!branch) {
    return null;
  }

  const normalized = branch.trim();
  const lower = normalized.toLowerCase();
  const cfPrimary = typeof process.env.CF_PAGES_PRIMARY_BRANCH === 'string'
    ? process.env.CF_PAGES_PRIMARY_BRANCH.trim()
    : '';

  if (lower === 'main') {
    return 'main';
  }

  if (lower === 'production') {
    return 'main';
  }

  if (cfPrimary && lower === cfPrimary.trim().toLowerCase()) {
    return 'main';
  }

  return null;
}

// Loads and evaluates `vocs.config.ts`, tweaking env vars so the sidebar matches the branch.
function loadSidebarConfig(branchName) {
  const configPath = path.join(__dirname, '..', 'vocs.config.ts');
  if (!fs.existsSync(configPath)) {
    return null;
  }

  const raw = fs.readFileSync(configPath, 'utf8');
  const sanitized = raw
    .replace(/^(?:import[^\n]*\n)+/, '')
    .replace(/export default defineConfig\(config\)\s*;?\s*$/, 'return defineConfig(config);')
    .replace(/\bas const\b/g, '')
    .replace(/head\([^)]*\)\s*\{[\s\S]*?\n  \},/, '')
    .replace(/new Set<[^>]+>\(/g, 'new Set(')
    .replace(/function\s+(\w+)\(([^)]*)\)\s*:\s*[^\s{]+/g, (_, name, params) => {
      const cleaned = params.replace(/:\s*[^,)]+/g, '');
      return `function ${name}(${cleaned})`;
    });

  const loader = new Function('defineConfig', sanitized);
  const previousCF = Object.prototype.hasOwnProperty.call(process.env, 'CF_PAGES_BRANCH')
    ? process.env.CF_PAGES_BRANCH
    : undefined;

  if (branchName) {
    process.env.CF_PAGES_BRANCH = branchName;
  } else {
    delete process.env.CF_PAGES_BRANCH;
  }

  try {
    return loader((cfg) => cfg);
  } catch (error) {
    console.warn(`Warning: unable to evaluate vocs.config.ts: ${error.message}`);
    return null;
  } finally {
    if (previousCF === undefined) {
      delete process.env.CF_PAGES_BRANCH;
    } else {
      process.env.CF_PAGES_BRANCH = previousCF;
    }
  }
}

// Builds the set of routes that are permitted on production (main) deployments.
// Also returns the order map for sidebar ordering.
function buildAllowedRouteSet(branchName) {
  const config = loadSidebarConfig(branchName);
  if (!config || !Array.isArray(config.sidebar)) {
    return { allowedRoutes: null, orderMap: null };
  }

  const routes = new Set();
  const orderMap = new Map();
  collectRoutesFromSidebar(config.sidebar, routes, orderMap);

  return { allowedRoutes: routes, orderMap };
}

// Tests if a route is allowed to appear based on the current branch rules.
function isRouteAllowed(route, allowedRoutes) {
  if (!allowedRoutes || allowedRoutes.size === 0) {
    return true;
  }
  if (!route || route === '/') {
    return true;
  }
  return allowedRoutes.has(route);
}

// Checks whether a directory (or its descendants) contains any allowed MDX pages.
function directoryHasDocs(dirPath, allowedRoutes) {
  try {
    const entries = fs.readdirSync(dirPath, { withFileTypes: true });
    for (const entry of entries) {
      if (entry.isFile()
        && entry.name.toLowerCase().endsWith('.mdx')
        && entry.name.toLowerCase() !== 'index.mdx') {
        const filePath = path.join(dirPath, entry.name);
        const route = toRoutePathFromRelative(path.relative(DOCS_ROOT, filePath));
        if (isRouteAllowed(route, allowedRoutes)) {
          return true;
        }
      }

      if (entry.isDirectory() && !shouldIgnoreDirectory(entry.name)) {
        const folderPath = path.join(dirPath, entry.name);
        if (directoryHasDocs(folderPath, allowedRoutes)) {
          return true;
        }
      }
    }
    return false;
  } catch (error) {
    console.warn(`Warning: unable to inspect directory ${dirPath}: ${error.message}`);
    return false;
  }
}

// Derives the display title for a folder, preferring its own index/overview title if present.
function readFolderTitle(dirPath) {
  const candidates = [
    path.join(dirPath, 'index.mdx'),
    path.join(dirPath, 'overview.mdx'),
  ];

  for (const candidate of candidates) {
    if (fs.existsSync(candidate)) {
      const title = readFrontmatterTitle(candidate);
      if (title) {
        return title;
      }
    }
  }

  return toTitleCase(path.basename(dirPath));
}

// Deduplicates entries by route and prefers directories when both file and folder exist.
// Sorts by sidebar order if orderMap is provided, otherwise falls back to alphabetical.
function finalizeEntries(entries, orderMap = null) {
  const byRoute = new Map();
  entries.forEach((entry) => {
    const existing = byRoute.get(entry.route);
    if (!existing || (entry.sourceType === 'directory' && existing.sourceType !== 'directory')) {
      byRoute.set(entry.route, entry);
    }
  });

  return Array.from(byRoute.values())
    .sort((a, b) => {
      if (orderMap && orderMap.size > 0) {
        const orderA = orderMap.has(a.route) ? orderMap.get(a.route) : Infinity;
        const orderB = orderMap.has(b.route) ? orderMap.get(b.route) : Infinity;
        if (orderA !== orderB) {
          return orderA - orderB;
        }
      }
      // Fallback to alphabetical for items not in sidebar
      return a.title.localeCompare(b.title, undefined, { sensitivity: 'base' });
    })
    .map(({ sourceType, ...rest }) => rest);
}

// Assembles the list of child pages/folders for the current directory.
function buildPageEntries(dirPath, files, subdirs, allowedRoutes, orderMap = null) {
  const entries = [];

  files.forEach((file) => {
    const filePath = path.join(dirPath, file.name);
    const route = toRoutePathFromRelative(path.relative(DOCS_ROOT, filePath));
    const fallbackTitle = toTitleCase(file.name.replace(/\.mdx$/i, ''));
    const title = readFrontmatterTitle(filePath) || fallbackTitle;
    if (!isRouteAllowed(route, allowedRoutes)) {
      return;
    }
    entries.push({
      title,
      route,
      sourceType: 'file',
    });
  });

  subdirs.forEach((dirent) => {
    const folderPath = path.join(dirPath, dirent.name);
    const hasDocs = directoryHasDocs(folderPath, allowedRoutes);
    if (!hasDocs) {
      return;
    }
    const route = toRoutePathFromRelative(path.relative(DOCS_ROOT, folderPath));
    if (!isRouteAllowed(route, allowedRoutes) && allowedRoutes) {
      return;
    }
    const title = readFolderTitle(folderPath);
    entries.push({
      title,
      route,
      sourceType: 'directory',
    });
  });

  return finalizeEntries(entries, orderMap);
}

// Tells whether an index file was previously generated by this script.
function hasGeneratedMarker(content) {
  if (!content) return false;
  return content.includes(GENERATED_MARKER) || content.includes(LEGACY_MARKER);
}

// Removes a generated index when no allowed entries remain.
function removeGeneratedIndex(dirPath) {
  const indexPath = path.join(dirPath, 'index.mdx');
  if (!fs.existsSync(indexPath)) {
    return;
  }
  const content = fs.readFileSync(indexPath, 'utf8');
  if (!hasGeneratedMarker(content)) {
    return;
  }
  fs.unlinkSync(indexPath);
  changedCount++;
}

// Writes (or updates) an index.mdx file for a directory.
function writeIndex(dirPath, pageEntries) {
  const indexPath = path.join(dirPath, 'index.mdx');
  const existingContent = fs.existsSync(indexPath)
    ? fs.readFileSync(indexPath, 'utf8')
    : null;
  const isGenerated = hasGeneratedMarker(existingContent);

  if (existingContent && !isGenerated && !FORCE) {
    unchangedCount++;
    return;
  }

  if (pageEntries.length === 0) {
    if (isGenerated) {
      fs.unlinkSync(indexPath);
      changedCount++;
    }
    return;
  }

  const folderTitle = (() => {
    if (dirPath === DOCS_ROOT) {
      return 'Documentation';
    }
    const segment = path.basename(dirPath);
    return toTitleCase(segment);
  })();

  const lines = [];
  lines.push('---');
  lines.push(`title: "${escapeFrontmatterValue(folderTitle)}"`);
  lines.push('---');
  lines.push('');
  lines.push(GENERATED_MARKER);
  lines.push('');
  lines.push(`# ${folderTitle}`);
  lines.push('');
  lines.push(NAVIGATION_NOTICE);
  lines.push('');
  lines.push('## Pages');
  lines.push('');
  pageEntries.forEach(({ title, route }) => {
    lines.push(`- [${title}](${route})`);
  });
  lines.push('');

  const nextContent = lines.join('\n');

  if (existingContent === nextContent) {
    unchangedCount++;
    return;
  }

  fs.writeFileSync(indexPath, nextContent);
  changedCount++;
}

// Filter system/hidden directories that should not appear in the docs.
function shouldIgnoreDirectory(name) {
  return name.startsWith('.') || name === 'node_modules' || name === 'config';
}

// Recursively traverses the docs tree, generating indexes bottom-up.
function generateAll(dirPath, depth = 0, allowedRoutes = null, orderMap = null) {
  const entries = fs.readdirSync(dirPath, { withFileTypes: true });

  const subdirs = entries.filter((entry) => entry.isDirectory() && !shouldIgnoreDirectory(entry.name));
  subdirs.forEach((dirent) => generateAll(path.join(dirPath, dirent.name), depth + 1, allowedRoutes, orderMap));

  if (depth === 0) {
    return;
  }

  const mdxFiles = entries.filter((entry) => entry.isFile()
    && entry.name.toLowerCase().endsWith('.mdx')
    && entry.name.toLowerCase() !== 'index.mdx');

  const pageEntries = buildPageEntries(dirPath, mdxFiles, subdirs, allowedRoutes, orderMap);
  if (pageEntries.length > 0) {
    writeIndex(dirPath, pageEntries);
    return;
  }

  removeGeneratedIndex(dirPath);
}

// Entry point when run as a CLI script.
function main() {
  if (!fs.existsSync(DOCS_ROOT)) {
    console.error(`Docs directory not found at ${DOCS_ROOT}`);
    process.exit(1);
  }

  const filterBranch = resolvePrimaryFilterBranch();
  const { allowedRoutes, orderMap } = buildAllowedRouteSet(filterBranch);

  generateAll(DOCS_ROOT, 0, allowedRoutes, orderMap);
  console.log(`Folder indexes: ${changedCount} changed, ${unchangedCount} unchanged.`);
}

if (require.main === module) {
  main();
}

module.exports = {
  main,
  generateAll,
  writeIndex,
};