BMAD-METHOD/tools/validate-doc-links.js

/**
 * Documentation Link Validator
 *
 * Validates site-relative links in markdown files and attempts to fix broken ones.
 *
 * What it checks:
 * - All site-relative links (starting with /) point to existing .md files
 * - Anchor links (#section) point to valid headings
 *
 * What it fixes:
 * - Broken links where the target file can be found elsewhere in /docs
 *
 * Usage:
 *   node tools/validate-doc-links.js           # Dry run (validate and show issues)
 *   node tools/validate-doc-links.js --write   # Fix auto-fixable issues
 */

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

const DOCS_ROOT = path.resolve(__dirname, '../docs');
const DRY_RUN = !process.argv.includes('--write');

// Regex to match markdown links with site-relative paths or bare .md references
const LINK_REGEX = /\[([^\]]*)\]\(((?:\.{1,2}\/|\/)[^)]+|[\w][^)\s]*\.md(?:[?#][^)]*)?)\)/g;

// File extensions that are static assets, not markdown docs
const STATIC_ASSET_EXTENSIONS = ['.zip', '.txt', '.pdf', '.png', '.jpg', '.jpeg', '.gif', '.svg', '.webp', '.ico'];

// Custom Astro page routes (not part of the docs content collection)
const CUSTOM_PAGE_ROUTES = new Set([]);

// Regex to extract headings for anchor validation
const HEADING_PATTERN = /^#{1,6}\s+(.+)$/gm;

/**
 * Get all markdown files in docs directory, excluding _* directories/files
 */
function getMarkdownFiles(dir) {
  const files = [];

  function walk(currentDir) {
    const entries = fs.readdirSync(currentDir, { withFileTypes: true });

    for (const entry of entries) {
      const fullPath = path.join(currentDir, entry.name);

      if (entry.name.startsWith('_')) {
        continue;
      }

      if (entry.isDirectory()) {
        walk(fullPath);
      } else if (entry.isFile() && (entry.name.endsWith('.md') || entry.name.endsWith('.mdx'))) {
        files.push(fullPath);
      }
    }
  }

  walk(dir);
  return files;
}

/**
 * Strip fenced code blocks from content
 */
function stripCodeBlocks(content) {
  return content.replaceAll(/```[\s\S]*?```/g, '');
}

/**
 * Convert a heading to its anchor slug
 */
function headingToAnchor(heading) {
  return heading
    .toLowerCase()
    .replaceAll(/[\u{1F300}-\u{1F9FF}]/gu, '') // Remove emojis
    .replaceAll(/[^\w\s-]/g, '') // Remove special chars
    .replaceAll(/\s+/g, '-') // Spaces to hyphens
    .replaceAll(/-+/g, '-') // Collapse hyphens
    .replaceAll(/^-+|-+$/g, ''); // Trim hyphens
}

/**
 * Extract anchor slugs from a markdown file
 */
function extractAnchors(content) {
  const anchors = new Set();
  let match;

  HEADING_PATTERN.lastIndex = 0;
  while ((match = HEADING_PATTERN.exec(content)) !== null) {
    const headingText = match[1]
      .trim()
      .replaceAll(/`[^`]+`/g, '')
      .replaceAll(/\*\*([^*]+)\*\*/g, '$1')
      .replaceAll(/\*([^*]+)\*/g, '$1')
      .replaceAll(/\[([^\]]+)\]\([^)]+\)/g, '$1')
      .trim();
    anchors.add(headingToAnchor(headingText));
  }

  return anchors;
}

/**
 * Resolve a site-relative link to a file path
 * /docs/how-to/installation/install-bmad.md -> docs/how-to/installation/install-bmad.md
 * /how-to/installation/install-bmad/ -> docs/how-to/installation/install-bmad.md or .../index.md
 */
function resolveLink(siteRelativePath, sourceFile) {
  // Strip anchor and query
  let checkPath = siteRelativePath.split('#')[0].split('?')[0];

  // Handle relative paths (including bare .md): resolve from source file's directory
  if (checkPath.startsWith('./') || checkPath.startsWith('../') || (!checkPath.startsWith('/') && checkPath.endsWith('.md'))) {
    const sourceDir = path.dirname(sourceFile);
    const resolved = path.resolve(sourceDir, checkPath);
    // Ensure the resolved path stays within DOCS_ROOT
    if (!resolved.startsWith(DOCS_ROOT + path.sep) && resolved !== DOCS_ROOT) return null;
    if (fs.existsSync(resolved) && fs.statSync(resolved).isFile()) return resolved;
    if (fs.existsSync(resolved + '.md')) return resolved + '.md';
    if (fs.existsSync(resolved + '.mdx')) return resolved + '.mdx';
    // Directory: check for index.md or index.mdx
    if (fs.existsSync(resolved) && fs.statSync(resolved).isDirectory()) {
      const indexFile = path.join(resolved, 'index.md');
      const indexMdxFile = path.join(resolved, 'index.mdx');
      if (fs.existsSync(indexFile)) return indexFile;
      if (fs.existsSync(indexMdxFile)) return indexMdxFile;
    }
    return null;
  }

  // Strip /docs/ prefix if present (legacy absolute links)
  if (checkPath.startsWith('/docs/')) {
    checkPath = checkPath.slice(5); // Remove '/docs' but keep leading '/'
  }

  if (checkPath.endsWith('/')) {
    // Could be file.md, file.mdx, or directory/index.md/mdx
    const baseName = checkPath.slice(0, -1);
    const asMd = path.join(DOCS_ROOT, baseName + '.md');
    const asMdx = path.join(DOCS_ROOT, baseName + '.mdx');
    const asIndex = path.join(DOCS_ROOT, checkPath, 'index.md');
    const asIndexMdx = path.join(DOCS_ROOT, checkPath, 'index.mdx');

    if (fs.existsSync(asMd)) return asMd;
    if (fs.existsSync(asMdx)) return asMdx;
    if (fs.existsSync(asIndex)) return asIndex;
    if (fs.existsSync(asIndexMdx)) return asIndexMdx;
    return null;
  }

  // Direct path (e.g., /path/file.md)
  const direct = path.join(DOCS_ROOT, checkPath);
  if (fs.existsSync(direct) && fs.statSync(direct).isFile()) return direct;

  // Try with .md extension
  const withMd = direct + '.md';
  if (fs.existsSync(withMd)) return withMd;

  // Try with .mdx extension
  const withMdx = direct + '.mdx';
  if (fs.existsSync(withMdx)) return withMdx;

  // Directory without trailing slash: check for index.md or index.mdx
  if (fs.existsSync(direct) && fs.statSync(direct).isDirectory()) {
    const indexFile = path.join(direct, 'index.md');
    const indexMdxFile = path.join(direct, 'index.mdx');
    if (fs.existsSync(indexFile)) return indexFile;
    if (fs.existsSync(indexMdxFile)) return indexMdxFile;
  }

  return null;
}

/**
 * Search for a file with directory context
 */
function findFileWithContext(brokenPath) {
  // Extract filename and parent directory from the broken path
  // e.g., /tutorials/getting-started/foo/ -> parent: getting-started, file: foo.md
  const cleanPath = brokenPath.replace(/\/$/, '').replace(/^(\.\.\/|\.\/|\/)+/, '');
  const parts = cleanPath.split('/');
  const fileName = parts.at(-1) + '.md';
  const parentDir = parts.length > 1 ? parts.at(-2) : null;

  const allFiles = getMarkdownFiles(DOCS_ROOT);
  const matches = [];

  for (const file of allFiles) {
    const fileBaseName = path.basename(file);
    const fileParentDir = path.basename(path.dirname(file));

    // Exact filename match with parent directory context
    if (fileBaseName === fileName) {
      if (parentDir && fileParentDir === parentDir) {
        // Strong match: both filename and parent dir match
        return [file];
      }
      matches.push(file);
    }

    // Also check for index.md in a matching directory
    if (fileBaseName === 'index.md' && fileParentDir === fileName.replace('.md', '')) {
      matches.push(file);
    }
  }

  return matches;
}

/**
 * Convert absolute file path to site-relative URL
 */
function fileToSiteRelative(filePath) {
  let relative = '/' + path.relative(DOCS_ROOT, filePath);
  relative = relative.split(path.sep).join('/');

  if (relative.endsWith('/index.md')) {
    return relative.replace(/\/index\.md$/, '/');
  }
  return relative.replace(/\.md$/, '/');
}

/**
 * Process a single file and find issues
 */
function processFile(filePath) {
  const content = fs.readFileSync(filePath, 'utf-8');
  const strippedContent = stripCodeBlocks(content);
  const issues = [];

  let match;
  LINK_REGEX.lastIndex = 0;

  while ((match = LINK_REGEX.exec(strippedContent)) !== null) {
    const linkText = match[1];
    const href = match[2];

    // Extract path and anchor
    const hashIndex = href.indexOf('#');
    const linkPath = hashIndex === -1 ? href : href.slice(0, hashIndex);
    const anchor = hashIndex === -1 ? null : href.slice(hashIndex + 1);

    // Skip static asset links (zip, txt, images, etc.)
    const linkLower = linkPath.toLowerCase();
    if (STATIC_ASSET_EXTENSIONS.some((ext) => linkLower.endsWith(ext))) {
      continue;
    }

    // Skip custom Astro page routes
    if (CUSTOM_PAGE_ROUTES.has(linkPath)) {
      continue;
    }

    // Validate the link target exists
    const targetFile = resolveLink(linkPath, filePath);

    if (!targetFile) {
      // Link is broken - try to find the file
      const candidates = findFileWithContext(linkPath);

      const issue = {
        type: 'broken-link',
        linkText,
        href,
        linkPath,
        fullMatch: match[0],
      };

      if (candidates.length === 1) {
        issue.status = 'auto-fixable';
        issue.suggestedFix = fileToSiteRelative(candidates[0]) + (anchor ? '#' + anchor : '');
        issue.foundAt = path.relative(DOCS_ROOT, candidates[0]);
      } else if (candidates.length > 1) {
        issue.status = 'needs-review';
        issue.candidates = candidates.map((c) => path.relative(DOCS_ROOT, c));
      } else {
        issue.status = 'manual-check';
      }

      issues.push(issue);
      continue;
    }

    // Validate anchor if present
    if (anchor) {
      const targetContent = fs.readFileSync(targetFile, 'utf-8');
      const anchors = extractAnchors(targetContent);
      let normalizedAnchor;
      try {
        normalizedAnchor = headingToAnchor(decodeURIComponent(anchor));
      } catch {
        normalizedAnchor = headingToAnchor(anchor);
      }

      if (!anchors.has(anchor) && !anchors.has(normalizedAnchor)) {
        issues.push({
          type: 'broken-anchor',
          linkText,
          href,
          anchor,
          status: 'manual-check',
          message: `Anchor "#${anchor}" not found`,
        });
      }
    }
  }

  return { content, issues };
}

/**
 * Apply fixes to file content
 */
function applyFixes(content, issues) {
  let updated = content;

  for (const issue of issues) {
    if (issue.status === 'auto-fixable' && issue.suggestedFix) {
      const oldLink = `[${issue.linkText}](${issue.href})`;
      const newLink = `[${issue.linkText}](${issue.suggestedFix})`;
      updated = updated.replace(oldLink, newLink);
    }
  }

  return updated;
}

// Main execution
console.log(`\nValidating docs in: ${DOCS_ROOT}`);
console.log(`Mode: ${DRY_RUN ? 'DRY RUN (use --write to fix)' : 'WRITE MODE'}\n`);

const files = getMarkdownFiles(DOCS_ROOT);
console.log(`Found ${files.length} markdown files\n`);

let totalIssues = 0;
let autoFixable = 0;
let needsReview = 0;
let manualCheck = 0;
let filesWithIssues = 0;

const allIssues = [];

for (const filePath of files) {
  const relativePath = path.relative(DOCS_ROOT, filePath);
  const { content, issues } = processFile(filePath);

  if (issues.length > 0) {
    filesWithIssues++;
    totalIssues += issues.length;

    console.log(`\n${relativePath}`);

    for (const issue of issues) {
      if (issue.status === 'auto-fixable') {
        autoFixable++;
        console.log(`  [FIX] ${issue.href}`);
        console.log(`     -> ${issue.suggestedFix}`);
      } else if (issue.status === 'needs-review') {
        needsReview++;
        console.log(`  [REVIEW] ${issue.href}`);
        console.log(`     Multiple matches found:`);
        for (const candidate of issue.candidates) {
          console.log(`       - ${candidate}`);
        }
      } else if (issue.type === 'broken-anchor') {
        manualCheck++;
        console.log(`  [MANUAL] ${issue.href}`);
        console.log(`     ${issue.message}`);
      } else {
        manualCheck++;
        console.log(`  [MANUAL] ${issue.href}`);
        console.log(`     File not found anywhere - may need to remove link`);
      }

      allIssues.push({ file: relativePath, ...issue });
    }

    // Apply fixes if not dry run
    if (!DRY_RUN) {
      const fixableIssues = issues.filter((i) => i.status === 'auto-fixable');
      if (fixableIssues.length > 0) {
        const updated = applyFixes(content, fixableIssues);
        fs.writeFileSync(filePath, updated, 'utf-8');
      }
    }
  }
}

console.log(`\n${'─'.repeat(60)}`);
console.log(`\nSummary:`);
console.log(`   Files scanned: ${files.length}`);
console.log(`   Files with issues: ${filesWithIssues}`);
console.log(`   Total issues: ${totalIssues}`);

if (totalIssues > 0) {
  console.log(`\n   Breakdown:`);
  console.log(`     Auto-fixable:  ${autoFixable}`);
  console.log(`     Needs review:  ${needsReview}`);
  console.log(`     Manual check:  ${manualCheck}`);
}

if (totalIssues === 0) {
  console.log(`\n   All links valid!`);
} else if (DRY_RUN && autoFixable > 0) {
  console.log(`\nRun with --write to auto-fix ${autoFixable} issue(s)`);
}

console.log('');

process.exit(totalIssues > 0 ? 1 : 0);