fix-version-menu.js

#!/usr/bin/env node
/*
 * fix-version-menu.js
 *
 * Post-processing step for a Docusaurus build: rewrites the version dropdown
 * links in built HTML so that switching version keeps the user on the same
 * page (matched by slug) instead of falling back to /GettingStarted/installation.
 *
 * Usage:
 *   node fix-version-menu.js [<gh-pages-dir>] [--dry-run] [--out <dir>]
 *
 * Defaults: gh-pages-dir = ./gh-pages
 * Scope: only HTML files under each version's commands/ directory.
 *
 * --out <dir>  Mirror the entire input tree to <dir> and apply the fixes
 *              there, leaving the input untouched. Output is a drop-in
 *              replacement for <gh-pages-dir>.
 * --dry-run    Print intended substitutions without writing anything.
 */

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

const argv = process.argv.slice(2);
const dryRun = argv.includes('--dry-run');

let outDir = null;
const positional = [];
for (let i = 0; i < argv.length; i++) {
  const a = argv[i];
  if (a === '--dry-run') continue;
  if (a === '--out') {
    outDir = argv[++i];
    if (!outDir) {
      console.error('--out requires a directory argument');
      process.exit(1);
    }
    continue;
  }
  if (a.startsWith('--out=')) {
    outDir = a.slice('--out='.length);
    continue;
  }
  if (a.startsWith('--')) {
    console.error(`Unknown flag: ${a}`);
    process.exit(1);
  }
  positional.push(a);
}

const ghPagesDir = path.resolve(positional[0] || './gh-pages');
const outDirResolved = outDir ? path.resolve(outDir) : null;

if (!fs.existsSync(ghPagesDir) || !fs.statSync(ghPagesDir).isDirectory()) {
  console.error(`Directory not found: ${ghPagesDir}`);
  process.exit(1);
}

// --- Detect versions ----------------------------------------------------------
// version key "" = unversioned latest; otherwise the directory name ("21", "21-R2", "next", ...).
// A directory is treated as a version iff it contains a "commands/" subdirectory.

function urlPrefixFor(key) {
  if (key === '') return '/docs/';
  return `/docs/${key}/`;
}

const versions = [];
if (fs.existsSync(path.join(ghPagesDir, 'commands'))) {
  versions.push({ key: '', dir: ghPagesDir, urlPrefix: '/docs/' });
}
for (const ent of fs.readdirSync(ghPagesDir, { withFileTypes: true })) {
  if (!ent.isDirectory()) continue;
  if (ent.name === 'commands') continue;
  const sub = path.join(ghPagesDir, ent.name);
  if (fs.existsSync(path.join(sub, 'commands'))) {
    versions.push({ key: ent.name, dir: sub, urlPrefix: urlPrefixFor(ent.name) });
  }
}

if (versions.length === 0) {
  console.error(`No versions with a commands/ directory found under ${ghPagesDir}`);
  process.exit(1);
}

// --- Build slug index per version --------------------------------------------
// A slug is the page path relative to the version root, without the .html suffix.
// e.g. gh-pages/21-R2/commands/alert.html -> "commands/alert" under key "21-R2".

function walk(dir, base, out) {
  if (!fs.existsSync(dir)) return;
  for (const ent of fs.readdirSync(dir, { withFileTypes: true })) {
    const p = path.join(dir, ent.name);
    if (ent.isDirectory()) walk(p, base, out);
    else if (ent.isFile() && ent.name.endsWith('.html')) {
      const rel = path.relative(base, p).split(path.sep).join('/');
      out.add(rel.replace(/\.html$/, ''));
    }
  }
}

const slugsByVersion = new Map();
for (const v of versions) {
  const set = new Set();
  walk(path.join(v.dir, 'commands'), v.dir, set);
  slugsByVersion.set(v.key, set);
}

const versionKeys = new Set(versions.map((v) => v.key));

// --- Helpers ------------------------------------------------------------------

// A segment looks like a version if it's `next`, a known on-disk version,
// or matches the 4D version pattern (e.g. "18", "21-R2", "21R3").
function isVersionSegment(seg) {
  if (versionKeys.has(seg)) return true;
  if (seg === 'next') return true;
  return /^\d+(?:-?R\d+)?$/.test(seg);
}

// Given an href like "/docs/<seg>/<rest>" or "/docs/<rest>", figure out which
// version the link belongs to. Returns { key, urlPrefix, rest } or null when
// the link points at a version we can't verify (e.g. an old version that
// isn't present on disk in this build).
function classifyHref(href) {
  const m = href.match(/^\/docs\/(?:([^/]+)\/)?(.+)$/);
  if (!m) return null;
  const seg = m[1];
  const rest = m[2];
  if (seg !== undefined) {
    if (versionKeys.has(seg)) {
      return { key: seg, urlPrefix: urlPrefixFor(seg), rest };
    }
    if (isVersionSegment(seg)) {
      // Version-shaped but not present on disk: we can't verify the target.
      return null;
    }
    // First segment is a path component of the unversioned latest.
    return { key: '', urlPrefix: '/docs/', rest: `${seg}/${rest}` };
  }
  return { key: '', urlPrefix: '/docs/', rest };
}

// Read the current page's slug from its active version-dropdown link.
function getPageSlug(html) {
  const m = html.match(
    /<a aria-current=page class="dropdown__link dropdown__link--active" href=([^ >]+)>/
  );
  if (!m) return null;
  const c = classifyHref(m[1]);
  return c ? c.rest : null;
}

// Rewrite a single <ul class=dropdown__menu>...</ul> block.
function rewriteDropdownBlock(block, pageSlug, fixes) {
  return block.replace(/<a\b([^>]*?)>/g, (match, attrs) => {
    if (!/\bclass=("dropdown__link[^"]*"|dropdown__link\b)/.test(attrs)) return match;
    const hrefMatch = attrs.match(/(\bhref=)([^ >]+)/);
    if (!hrefMatch) return match;
    const oldHref = hrefMatch[2];
    const c = classifyHref(oldHref);
    if (!c) return match;
    const targetSlugs = slugsByVersion.get(c.key);
    if (!targetSlugs || !targetSlugs.has(pageSlug)) return match;
    const newHref = c.urlPrefix + pageSlug;
    if (newHref === oldHref) return match;
    fixes.push({ from: oldHref, to: newHref });
    const newAttrs = attrs.replace(/(\bhref=)([^ >]+)/, `$1${newHref}`);
    return `<a${newAttrs}>`;
  });
}

// --- Per-file processing ------------------------------------------------------

function processFile(file) {
  const html = fs.readFileSync(file, 'utf8');
  const slug = getPageSlug(html);
  if (!slug) return { file, fixes: [], skipped: 'no active dropdown link' };

  const blockRe = /<ul class=dropdown__menu>([\s\S]*?)<\/ul>/g;
  const blocks = [];
  let m;
  while ((m = blockRe.exec(html)) !== null) {
    blocks.push({ start: m.index, end: m.index + m[0].length, content: m[0], inner: m[1] });
  }

  const fixes = [];
  let newHtml = html;
  let offset = 0;
  for (const b of blocks) {
    // Skip the locale dropdown: its <a> items carry a `lang=` attribute.
    if (/<a\b[^>]*\blang=/.test(b.inner)) continue;
    const rewritten = rewriteDropdownBlock(b.content, slug, fixes);
    if (rewritten !== b.content) {
      newHtml =
        newHtml.slice(0, b.start + offset) + rewritten + newHtml.slice(b.end + offset);
      offset += rewritten.length - b.content.length;
    }
  }

  return { file, slug, fixes, newHtml, changed: newHtml !== html };
}

// --- Walk and apply -----------------------------------------------------------

function* walkHtml(dir) {
  if (!fs.existsSync(dir)) return;
  for (const ent of fs.readdirSync(dir, { withFileTypes: true })) {
    const p = path.join(dir, ent.name);
    if (ent.isDirectory()) yield* walkHtml(p);
    else if (ent.isFile() && ent.name.endsWith('.html')) yield p;
  }
}

// When --out is given, mirror the entire input tree first so the output is a
// drop-in replacement. Then we overwrite the in-scope HTML files we rewrite.
if (outDirResolved && !dryRun) {
  if (path.relative(ghPagesDir, outDirResolved) === '' || outDirResolved === ghPagesDir) {
    console.error('--out must point to a different directory than the input.');
    process.exit(1);
  }
  fs.mkdirSync(outDirResolved, { recursive: true });
  fs.cpSync(ghPagesDir, outDirResolved, { recursive: true });
}

let totalFixes = 0;
let totalFiles = 0;

for (const v of versions) {
  for (const file of walkHtml(path.join(v.dir, 'commands'))) {
    const result = processFile(file);
    if (result.skipped) {
      console.log(`${path.relative(process.cwd(), file)}: skipped (${result.skipped})`);
      continue;
    }
    if (result.fixes.length === 0) continue;
    totalFiles++;
    totalFixes += result.fixes.length;
    const rel = path.relative(process.cwd(), file);
    const suffix = dryRun
      ? ' (dry-run)'
      : outDirResolved
      ? ` -> ${path.relative(process.cwd(), path.join(outDirResolved, path.relative(ghPagesDir, file)))}`
      : '';
    console.log(`${rel}: ${result.fixes.length} link(s) fixed${suffix}`);
    for (const fx of result.fixes) console.log(`  ${fx.from} -> ${fx.to}`);
    if (!dryRun && result.changed) {
      const dest = outDirResolved
        ? path.join(outDirResolved, path.relative(ghPagesDir, file))
        : file;
      fs.mkdirSync(path.dirname(dest), { recursive: true });
      fs.writeFileSync(dest, result.newHtml);
    }
  }
}

console.log(
  `\nTotal: ${totalFixes} link(s) fixed across ${totalFiles} file(s)${dryRun ? ' (dry-run)' : ''}.`
);