Bunoshfile.js

import fs from 'node:fs';
import path from 'node:path';

const { shell, fetch, task, stopOnFailures } = global.bunosh;
const { say } = global.bunosh;

const ROOT = process.cwd();
const DIST_DIR = path.join(ROOT, 'dist');
const DOCS_DIR = path.join(ROOT, 'src', 'content', 'docs');

const REPO_URL = process.env.CODECEPTJS_DOCS_REPO || 'https://github.com/codeceptjs/CodeceptJS.git';
const BRANCH = process.env.CODECEPTJS_DOCS_BRANCH || '4.x';
const SYNC_ROOT = path.join(ROOT, '.codeceptjs-docs');
const REPO_DIR = path.join(SYNC_ROOT, 'repo');
const STAGING_DIR = path.join(SYNC_ROOT, 'staging');
const ASTRO_CONFIG = path.join(ROOT, 'astro.config.mjs');
const SYNC_MARKER = '<!-- Auto-generated by scripts/sync-codeceptjs-docs.mjs from codeceptjs/CodeceptJS@4.x. Do not edit. -->';

const SKIP_LINKS = new Set([
  'changelog',
  'web-api',
  'mobile-api',
  'cheatsheet',
]);

const RELEASES_REPO = process.env.CODECEPTJS_RELEASES_REPO || 'codeceptjs/CodeceptJS';
const RELEASES_OUTPUT = path.join(DOCS_DIR, 'release.md');
const RELEASES_PER_PAGE = 3;
const RELEASES_MARKER = `<!-- Auto-generated by bunosh release:pull from ${RELEASES_REPO} GitHub Releases. Do not edit. -->`;

const HELPERS_DIR = path.join(DOCS_DIR, 'helpers');
const WEBAPI_DIR = path.join(DOCS_DIR, 'webapi');

const WEB_HELPERS = {
  Playwright: path.join(HELPERS_DIR, 'playwright.md'),
  WebDriver: path.join(HELPERS_DIR, 'web-driver.md'),
  Puppeteer: path.join(HELPERS_DIR, 'puppeteer.md'),
};
const WEB_HELPER_NAMES = Object.keys(WEB_HELPERS);

const MOBILE_HELPERS = {
  Appium: path.join(HELPERS_DIR, 'appium.md'),
  Detox: path.join(HELPERS_DIR, 'detox.md'),
};

const WEB_OUTPUT = path.join(DOCS_DIR, 'web-api.md');
const MOBILE_OUTPUT = path.join(DOCS_DIR, 'mobile-api.md');

const WEB_METHOD_OVERRIDES = {
  click: {
    compactDifferences: true,
    notes: [
      'ARIA locators are supported. Update examples to include the new locator type where relevant.',
      '`I.click({ aria: "Select" });`',
      '`I.click("Select");`',
    ],
    helperPrefix: {
      WebDriver:
        'In WebDriver, click can only happen on an actionable element. Use specific locators and wait for element readiness when needed.',
    },
  },
};

/**
 * Start the Astro dev server (syncs docs and regenerates the unified API first).
 */
export async function dev() {
  await prepareContent();
  await shell`astro dev`;
}

/**
 * Alias of `dev` — kept because package.json (`start`, `serve`) and the README
 * invoke the `serve` command name directly.
 */
export async function serve() {
  await dev();
}

/**
 * Build the static site (syncs docs and regenerates the unified API first).
 */
export async function build() {
  stopOnFailures();
  await prepareContent();
  await task('Build static site', () => shell`astro build`);
  say('static site built into dist/');
}

/**
 * Preview the production build locally.
 */
export async function preview() {
  await shell`astro preview`;
}

/**
 * Scrape the site into Meilisearch via the docs-scraper Docker image.
 */
export async function searchScrape() {
  await shell`docker run -t --rm --env-file .env -v ${ROOT}/docsearch.json:/docs-scraper/docsearch.json getmeili/docs-scraper:latest pipenv run ./docs_scraper docsearch.json`;
}

/**
 * Build and publish the site to the codeceptjs.github.io deploy branch.
 */
export async function publish() {
  stopOnFailures();

  await task('Install dependencies', () => shell`npm i`);
  say('dependencies installed');

  await build();

  await task('Write CNAME', () => Bun.write(path.join(DIST_DIR, 'CNAME'), 'codecept.io\n'));
  say(`wrote CNAME to ${DIST_DIR}`);

  await pushDeployBranch();
  say('pushed dist/ to codeceptjs.github.io@master');
}

/**
 * Sync CodeceptJS docs from the upstream repository into src/content/docs.
 */
export async function docsSync() {
  const { links, diff, considered } = await stageUpstreamDocs();

  await task('Apply curated docs', () => {
    for (const { target, content } of diff.changes) {
      fs.mkdirSync(path.dirname(target), { recursive: true });
      fs.writeFileSync(target, content);
    }
  });

  let images = 0;
  await task('Copy referenced images', () => { images = syncReferencedImages(links); });
  say(`copied ${images} referenced image(s)`);

  reportSyncResult(diff, considered);
}

/**
 * Verify synced docs are up to date without writing (CI check; fails on drift).
 */
export async function docsSyncCheck() {
  const { diff, considered } = await stageUpstreamDocs();
  assertNoDocsDrift(diff);
  say(`docs:sync-check ok — ${considered} curated docs in sync`);
}

/**
 * Regenerate the unified web/mobile API pages from helper docblocks.
 */
export async function docsUnifiedApi() {
  const { webContent, mobileContent } = await buildUnifiedApiContent();

  await task('Write unified API pages', () => {
    writeFile(WEB_OUTPUT, webContent);
    writeFile(MOBILE_OUTPUT, mobileContent);
  });
  say(`generated ${path.relative(ROOT, WEB_OUTPUT)} and ${path.relative(ROOT, MOBILE_OUTPUT)}`);
}

/**
 * Alias of `docs:unified-api` — kept because package.json (`update`) and the
 * README invoke the legacy `docs:update` command name directly.
 */
export async function docsUpdate() {
  await docsUnifiedApi();
}

/**
 * Verify unified API pages are up to date without writing (CI check; fails on drift).
 */
export async function docsUnifiedApiCheck() {
  const { webContent, mobileContent } = await buildUnifiedApiContent();
  assertUnifiedApiUpToDate(webContent, mobileContent);
  say('unified API docs are up to date');
}

/**
 * Pull releases from the CodeceptJS GitHub repository into src/content/docs/release.md.
 * Fetches 3 releases per page from the GitHub Releases API.
 * @param {number} [pages=5] - Number of pages to fetch (3 releases per page).
 */
export async function releasePull(pages = 5) {
  stopOnFailures();
  await pullReleases(Math.max(1, Number(pages) || 5));
}

/**
 * Refresh every piece of generated content in one shot: sync upstream docs,
 * regenerate the unified web/mobile API pages, and pull the latest releases.
 * This is the command the CodeceptJS release pipeline triggers.
 */
export async function docs() {
  await docsSync();
  await docsUnifiedApi();
  await releasePull();
}

// ===========================================================================
// Helpers
// ===========================================================================

async function prepareContent() {
  await docsSync();
  await docsUnifiedApi();
  await pullReleases(5, { soft: true }); // tolerate offline / rate-limited GitHub
}

async function pushDeployBranch() {
  await task('Push deploy branch', () => shell`
    git init
    git remote add origin git@github.com:codeceptjs/codeceptjs.github.io.git
    git checkout -b deploy
    git reset --soft HEAD~$(git rev-list --count HEAD ^master)
    git add -A
    git commit -m "deploy"
    git push -f origin deploy:master
  `.cwd(DIST_DIR));
}

/**
 * Clone upstream, stage its docs, and diff them against the curated copies.
 * Writes nothing — returns the planned changes so callers decide what to do.
 */
async function stageUpstreamDocs() {
  stopOnFailures();

  await cloneUpstream();
  say(`cloned ${REPO_URL}@${BRANCH} into ${REPO_DIR}`);

  let stagedCount = 0;
  await task('Stage upstream docs', () => { stagedCount = buildStaging(); });
  say(`staged ${stagedCount} files in ${STAGING_DIR}`);

  let links;
  let diff;
  let considered = 0;
  await task('Scan curated docs', () => {
    links = collectSidebarLinks();
    diff = diffCuratedDocs(links);
    considered = links.size - [...SKIP_LINKS].filter((l) => links.has(l)).length;
  });
  say(`scanned ${considered} sidebar-listed docs`);

  return { links, diff, considered };
}

async function cloneUpstream() {
  await task('Clone CodeceptJS docs', async () => {
    fs.rmSync(REPO_DIR, { recursive: true, force: true });
    fs.mkdirSync(SYNC_ROOT, { recursive: true });
    const res = await shell`git clone --depth=1 --branch ${BRANCH} --single-branch ${REPO_URL} ${REPO_DIR}`;
    if (res.hasFailed) {
      throw new Error(`git clone failed for ${REPO_URL}@${BRANCH} (is git installed and the branch reachable?)`);
    }
  });
}

function diffCuratedDocs(links) {
  const changes = [];
  let unchanged = 0;
  const missing = [];
  for (const link of links) {
    if (SKIP_LINKS.has(link)) continue;
    const srcFile = path.join(STAGING_DIR, `${link}.md`);
    if (!fs.existsSync(srcFile)) {
      missing.push(link);
      continue;
    }
    const target = path.join(DOCS_DIR, `${link}.md`);
    const content = Buffer.from(stripStagedSlug(fs.readFileSync(srcFile, 'utf8')), 'utf8');
    let existing = null;
    try { existing = fs.readFileSync(target); } catch (e) {
      if (e.code !== 'ENOENT') throw e;
    }
    if (existing && existing.equals(content)) {
      unchanged += 1;
      continue;
    }
    changes.push({ link, target, content });
  }
  return { changes, unchanged, missing };
}

function collectImagePaths(markdown) {
  const paths = new Set();
  const patterns = [
    /!\[[^\]]*\]\(\s*<?([^)>\s]+)>?/g, // ![alt](path)
    /<img[^>]+src=["']([^"']+)["']/gi, // <img src="path">
  ];
  for (const re of patterns) {
    let m;
    while ((m = re.exec(markdown)) !== null) {
      const p = m[1].trim();
      if (!p || /^(?:[a-z]+:)?\/\//i.test(p) || p.startsWith('data:') || p.startsWith('/')) continue;
      paths.add(p.split('#')[0].split('?')[0]);
    }
  }
  return [...paths];
}

// Curated docs reference upstream images by relative path; copy those images
// from staging into src/content/docs so the Astro build can resolve them.
function syncReferencedImages(links) {
  let copied = 0;
  for (const link of links) {
    if (SKIP_LINKS.has(link)) continue;
    const staged = path.join(STAGING_DIR, `${link}.md`);
    if (!fs.existsSync(staged)) continue;
    const linkDir = path.posix.dirname(link);
    for (const rel of collectImagePaths(fs.readFileSync(staged, 'utf8'))) {
      const relFromRoot = path.posix.normalize(
        linkDir === '.' ? rel : path.posix.join(linkDir, rel),
      );
      if (relFromRoot.startsWith('..')) continue;
      const src = path.join(STAGING_DIR, relFromRoot);
      if (!fs.existsSync(src)) continue;
      const dest = path.join(DOCS_DIR, relFromRoot);
      const srcBuf = fs.readFileSync(src);
      let destBuf = null;
      try { destBuf = fs.readFileSync(dest); } catch (e) {
        if (e.code !== 'ENOENT') throw e;
      }
      if (destBuf && destBuf.equals(srcBuf)) continue;
      fs.mkdirSync(path.dirname(dest), { recursive: true });
      fs.writeFileSync(dest, srcBuf);
      copied += 1;
    }
  }
  return copied;
}

function assertNoDocsDrift(diff) {
  if (diff.changes.length === 0) return;
  const names = diff.changes.map((c) => `${c.link}.md`);
  const head = names.slice(0, 20).map((f) => `  ${f}`).join('\n');
  const more = names.length > 20 ? `\n  …and ${names.length - 20} more` : '';
  throw new Error(`docs:sync-check failed — ${names.length} files would change:\n${head}${more}`);
}

function reportSyncResult(diff, considered) {
  say(`copied ${diff.changes.length} (${diff.unchanged} unchanged) of ${considered} sidebar-listed docs`);
  if (diff.missing.length === 0) return;
  say(`note: ${diff.missing.length} sidebar links have no upstream source (kept local-only or generated):`);
  for (const m of diff.missing.slice(0, 30)) say(`  ${m}`);
  if (diff.missing.length > 30) say(`  …and ${diff.missing.length - 30} more`);
}

/**
 * Generate the unified web + mobile API markdown. Writes nothing — returns the
 * content so callers decide whether to write it or assert it is up to date.
 */
async function buildUnifiedApiContent() {
  stopOnFailures();

  let webContent;
  let mobileContent;
  await task('Build unified API content', () => {
    webContent = generateWebApiContent();
    mobileContent = generateMobileApiContent();
  });
  say('built web + mobile unified API content');

  return { webContent, mobileContent };
}

function assertUnifiedApiUpToDate(webContent, mobileContent) {
  const webOk = isFileUpToDate(WEB_OUTPUT, webContent);
  const mobileOk = isFileUpToDate(MOBILE_OUTPUT, mobileContent);
  if (webOk && mobileOk) return;

  const outdated = [];
  if (!webOk) outdated.push(path.relative(ROOT, WEB_OUTPUT));
  if (!mobileOk) outdated.push(path.relative(ROOT, MOBILE_OUTPUT));
  throw new Error(`Unified API docs are outdated: ${outdated.join(', ')}\nRun: bunosh docs:unified-api`);
}

async function pullReleases(pages, { soft = false } = {}) {
  let releases = [];
  await task(`Fetch releases from ${RELEASES_REPO}`, async () => {
    releases = await fetchReleases(pages, soft);
  });

  if (releases.length === 0) {
    if (soft) {
      say('skipped release notes — no releases fetched (offline or rate-limited)');
      return;
    }
    throw new Error(`No releases returned from ${RELEASES_REPO} (rate-limited or network error?)`);
  }

  await task('Write release notes', () => {
    fs.writeFileSync(RELEASES_OUTPUT, renderReleases(releases), 'utf8');
  });
  say(`wrote ${releases.length} releases to ${path.relative(ROOT, RELEASES_OUTPUT)}`);
}

async function fetchReleases(pages, soft) {
  const headers = {
    Accept: 'application/vnd.github+json',
    'User-Agent': 'codecept-site-release-pull',
  };
  if (process.env.GITHUB_TOKEN) headers.Authorization = `Bearer ${process.env.GITHUB_TOKEN}`;

  const all = [];
  for (let page = 1; page <= pages; page += 1) {
    const url = `https://api.github.com/repos/${RELEASES_REPO}/releases?per_page=${RELEASES_PER_PAGE}&page=${page}`;
    const res = await fetch(url, { headers });
    if (res.hasFailed) {
      if (soft) return all;
      throw new Error(`GitHub API request failed for ${url}: ${res.output}`);
    }
    let batch;
    try {
      batch = JSON.parse(res.output);
    } catch {
      if (soft) return all;
      throw new Error(`GitHub API returned non-JSON for ${url}`);
    }
    if (!Array.isArray(batch) || batch.length === 0) break;
    all.push(...batch.filter((r) => !r.draft));
    if (batch.length < RELEASES_PER_PAGE) break;
  }
  return all;
}

function demoteHeadings(markdown) {
  return markdown
    .replace(/\r\n/g, '\n')
    .split('\n')
    .map((line) => {
      const m = line.match(/^(#{1,5})\s+/);
      return m ? line.replace(/^#{1,5}/, '#'.repeat(m[1].length + 1)) : line;
    })
    .join('\n')
    .trim();
}

function renderReleases(releases) {
  const lines = [
    '---',
    'title: Release Notes',
    'description: Latest CodeceptJS releases, pulled from GitHub.',
    '---',
    RELEASES_MARKER,
    '',
  ];

  for (const r of releases) {
    const titleText = (r.name && r.name.trim()) || r.tag_name;
    const date = r.published_at ? r.published_at.slice(0, 10) : '';
    const tag = r.prerelease ? ' _(pre-release)_' : '';
    lines.push(`## [${titleText}](${r.html_url})${tag}`);
    lines.push('');
    if (date) {
      lines.push(`_Released ${date}_`);
      lines.push('');
    }
    const body = (r.body || '').trim();
    lines.push(body ? demoteHeadings(body) : '_No release notes._');
    lines.push('');
  }

  return lines.join('\n').trimEnd() + '\n';
}

function toKebab(name) {
  return name
    .replace(/([A-Z]+)([A-Z][a-z])/g, '$1-$2')
    .replace(/([a-z\d])([A-Z])/g, '$1-$2')
    .toLowerCase();
}

function normalizeRel(rel) {
  const segments = rel.split('/');
  const file = segments.pop();
  const dot = file.lastIndexOf('.');
  const stem = dot >= 0 ? file.slice(0, dot) : file;
  const ext = dot >= 0 ? file.slice(dot) : '';
  return [...segments.map(toKebab), toKebab(stem) + ext.toLowerCase()].join('/');
}

function walk(dir, relBase = '') {
  const entries = fs.readdirSync(dir, { withFileTypes: true });
  const files = [];
  for (const entry of entries) {
    const rel = relBase ? path.posix.join(relBase, entry.name) : entry.name;
    const abs = path.join(dir, entry.name);
    if (entry.isDirectory()) {
      files.push(...walk(abs, rel));
    } else if (entry.isFile()) {
      files.push({ abs, rel });
    }
  }
  return files;
}

function titleFromFilename(relPath) {
  const base = path.basename(relPath, path.extname(relPath));
  return base.replace(/[-_]+/g, ' ').replace(/\b\w/g, (c) => c.toUpperCase());
}

function expectedSlug(relPath) {
  return relPath.replace(/\.md$/i, '').toLowerCase();
}

function parseFrontmatter(text) {
  const normalized = text.replace(/\r\n/g, '\n');
  const match = normalized.match(/^---\n([\s\S]*?)\n---\n?/);
  if (!match) return { fields: {}, body: normalized };
  const block = match[1];
  const body = normalized.slice(match[0].length);
  const fields = {};
  for (const line of block.split('\n')) {
    const m = line.match(/^([A-Za-z0-9_-]+)\s*:\s*(.*)$/);
    if (!m) continue;
    fields[m[1]] = m[2].trim();
  }
  return { fields, body };
}

function stripLeadingTitleHeading(body, title) {
  const stripped = body.replace(/^#\s+[^\n]*\n+/, '');
  if (stripped !== body) return stripped;
  if (!title) return body;
  const escaped = title.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
  const h2Re = new RegExp(
    `^((?:<!--[\\s\\S]*?-->\\s*\\n+)*)##\\s+${escaped}\\s*\\n+`
  );
  return body.replace(h2Re, '$1');
}

function transformMarkdown(srcText, outRel) {
  const { fields, body } = parseFrontmatter(srcText);
  const title = (fields.title && fields.title.length > 0) ? fields.title : titleFromFilename(outRel);
  const out = ['---', `title: ${title}`];
  if (fields.permalink) {
    const normalizedPermalink = fields.permalink.replace(/^\//, '').toLowerCase();
    if (normalizedPermalink && normalizedPermalink !== expectedSlug(outRel)) {
      out.push(`slug: ${normalizedPermalink}`);
    }
  }
  out.push('---', SYNC_MARKER, '');
  return out.join('\n') + stripLeadingTitleHeading(body.replace(/^\n+/, ''), title);
}

function buildStaging() {
  fs.rmSync(STAGING_DIR, { recursive: true, force: true });
  const docsDir = path.join(REPO_DIR, 'docs');
  if (!fs.existsSync(docsDir)) {
    throw new Error(`No docs/ directory found in cloned repo at ${docsDir}`);
  }
  const files = walk(docsDir);
  for (const { abs, rel } of files) {
    const outRel = normalizeRel(rel);
    const target = path.join(STAGING_DIR, outRel);
    fs.mkdirSync(path.dirname(target), { recursive: true });
    if (outRel.toLowerCase().endsWith('.md')) {
      fs.writeFileSync(target, transformMarkdown(fs.readFileSync(abs, 'utf8'), outRel));
    } else {
      fs.copyFileSync(abs, target);
    }
  }
  return files.length;
}

function collectSidebarLinks() {
  const config = fs.readFileSync(ASTRO_CONFIG, 'utf8');
  const links = new Set();
  for (const m of config.matchAll(/\blink:\s*['"]([^'"]+)['"]/g)) {
    links.add(m[1].replace(/^\/+|\/+$/g, ''));
  }
  const topicsMatch = config.match(/topics\s*:\s*{([\s\S]*?)\n\s*}/);
  if (topicsMatch) {
    for (const m of topicsMatch[1].matchAll(/['"]([^'"]+)['"]/g)) {
      links.add(m[1].replace(/^\/+|\/+$/g, ''));
    }
  }
  return links;
}

function stripStagedSlug(text) {
  return text.replace(/^slug:\s*.+\n/m, '');
}

function readFile(filePath) {
  return fs.readFileSync(filePath, 'utf8').replace(/\r\n/g, '\n');
}

function normalizeForFile(content) {
  return content.replace(/\n/g, '\r\n');
}

function writeFile(filePath, content) {
  fs.writeFileSync(filePath, normalizeForFile(content), 'utf8');
}

function escRegExp(text) {
  return text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
}

function extractMethods(helperContent) {
  const methods = [];
  const seen = new Set();
  const re = /^###\s+([A-Za-z][A-Za-z0-9_]*)\s*$/gm;
  let match;

  while ((match = re.exec(helperContent)) !== null) {
    const method = match[1];
    if (!/^[a-z][A-Za-z0-9_]*$/.test(method)) continue;
    if (!method.startsWith('_') && !seen.has(method)) {
      seen.add(method);
      methods.push(method);
    }
  }

  return methods;
}

function extractMethodDoc(helperContent, method) {
  const heading = new RegExp(`^###\\s+${escRegExp(method)}\\s*$`, 'm');
  const start = helperContent.search(heading);
  if (start === -1) return null;

  const fromHeading = helperContent.slice(start);
  const firstLineBreak = fromHeading.indexOf('\n');
  if (firstLineBreak === -1) return '';

  const afterHeading = fromHeading.slice(firstLineBreak + 1);
  const nextHeadingIdx = afterHeading.search(/^###\s+/m);
  const section =
    nextHeadingIdx === -1 ? afterHeading : afterHeading.slice(0, nextHeadingIdx);

  return section.trim();
}

function availability(exists) {
  return exists ? 'Supported' : 'Not supported';
}

function normalizeDocForDiff(content) {
  return content
    .replace(/\r\n/g, '\n')
    .replace(/\[\d+\]/g, '[]')
    .replace(/[ \t]+/g, ' ')
    .replace(/\n{3,}/g, '\n\n')
    .trim();
}

function commonBodyText(mustache) {
  return mustache
    .split('\n')
    .filter((line) => !/^@(?:param|returns?)\b/.test(line.trim()))
    .join('\n')
    .replace(/\n{3,}/g, '\n\n')
    .trim();
}

function stripParamsAndReturns(text) {
  const lines = text.split('\n');
  const out = [];
  const isHeading = (l) =>
    /^(?:#{2,5}\s+Parameters?|\*\*Parameters\*\*|#{2,5}\s+Returns?|\*\*Returns\*\*)\s*$/.test(l);
  const isBulletOrIndented = (l) => l.trim() === '' || /^[ \t]*[*\-+]\s/.test(l) || /^[ \t]+\S/.test(l);

  let i = 0;
  while (i < lines.length) {
    const line = lines[i];
    if (isHeading(line)) {
      i += 1;
      while (i < lines.length && isBulletOrIndented(lines[i])) i += 1;
      continue;
    }
    if (/^Returns\s+/.test(line)) { i += 1; continue; }
    if (/^@(?:param|returns?)\b/.test(line.trim())) { i += 1; continue; }
    out.push(line);
    i += 1;
  }
  return out.join('\n');
}

function normalizeForSubtract(text) {
  return text
    .replace(/\r\n/g, '\n')
    .replace(/_([^_\n]+)_/g, '*$1*')
    .replace(/\[([^\]]+)\]\[\d+\]/g, '$1')
    .replace(/\[([^\]]+)\]\([^)]+\)/g, '$1')
    .replace(/[ \t]+/g, ' ')
    .replace(/\n+/g, '\n')
    .trim();
}

function helperResidue(helperDoc, commonBody) {
  let text = helperDoc;
  if (commonBody && helperDoc.includes(commonBody)) {
    text = helperDoc.split(commonBody).join('');
  } else if (commonBody) {
    const normCommon = normalizeForSubtract(commonBody);
    const normHelper = normalizeForSubtract(helperDoc);
    text = normCommon && normHelper.includes(normCommon)
      ? normHelper.split(normCommon).join('')
      : helperDoc;
  }
  text = stripParamsAndReturns(text);
  return text.replace(/\n{3,}/g, '\n\n').trim();
}

function renderAvailabilityTable(headers, row) {
  const th = headers
    .map((h) => `<th style="border: 1px solid var(--sl-color-hairline); padding: 0.45rem 0.6rem; text-align: left;">${h}</th>`)
    .join('');
  const td = row
    .map((c) => `<td style="border: 1px solid var(--sl-color-hairline); padding: 0.45rem 0.6rem; vertical-align: top;">${c}</td>`)
    .join('');

  return [
    '<table style="border-collapse: collapse; width: 100%;">',
    `  <thead><tr>${th}</tr></thead>`,
    `  <tbody><tr>${td}</tr></tbody>`,
    '</table>',
  ];
}

function normalizeWebUnifiedAnchors(content) {
  return content
    .replace(/#fillfield\b/g, '#ifillfield')
    .replace(/#click\b/g, '#iclick')
}

function normalizeMobileUnifiedAnchors(content) {
  return content
    .replace(/#tap\b/g, '#itap')
    .replace(/#relaunchApp\b/g, '#irelaunchapp')
    .replace(/#relaunchapp\b/g, '#irelaunchapp')
    .replace(/#click\b/g, '#iclick');
}

function parseJSDocParam(line) {
  const match = line.match(/^@param\s+\{([^}]+)\}\s+(\[[^\]]+\]|[^\s]+)\s*(.*)$/);
  if (!match) return null;
  return {
    type: match[1].trim(),
    name: match[2].trim(),
    description: match[3].trim(),
  };
}

function parseJSDocReturn(line) {
  const match = line.match(/^@returns?\s+\{([^}]+)\}\s*(.*)$/);
  if (!match) return null;
  return {
    type: match[1].trim(),
    description: match[2].trim(),
  };
}

function formatSharedBlock(content) {
  const lines = content.split('\n');
  const body = [];
  const params = [];
  const returns = [];

  for (const line of lines) {
    const trimmed = line.trim();
    if (trimmed.startsWith('@param ')) {
      const param = parseJSDocParam(trimmed);
      if (param) {
        params.push(param);
        continue;
      }
    }
    if (/^@returns?\s+/.test(trimmed)) {
      const ret = parseJSDocReturn(trimmed);
      if (ret) {
        returns.push(ret);
        continue;
      }
    }
    body.push(line);
  }

  while (body.length && body[body.length - 1].trim() === '') {
    body.pop();
  }

  const out = [...body];

  if (params.length) {
    out.push('');
    out.push('**Parameters**');
    out.push('');
    for (const param of params) {
      const desc = param.description ? ` - ${param.description}` : '';
      out.push(`- \`${param.name}\` \`${param.type}\`${desc}`);
    }
  }

  if (returns.length) {
    out.push('');
    out.push('**Returns**');
    out.push('');
    for (const ret of returns) {
      const desc = ret.description ? ` - ${ret.description}` : '';
      out.push(`- \`${ret.type}\`${desc}`);
    }
  }

  return out.join('\n').trim();
}

function normalizeMethodDocHeadings(content) {
  if (!content) return content;
  return content
    .replace(/^#{4,5}\s+Parameters\s*$/gm, '**Parameters**')
    .replace(/^#{4,5}\s+Returns?\s*$/gm, '**Returns**');
}

function generateWebApiContent() {
  for (const [helperName, filePath] of Object.entries(WEB_HELPERS)) {
    if (!fs.existsSync(filePath)) {
      throw new Error(
        `Missing helper source for ${helperName}: ${path.relative(ROOT, filePath)}`,
      );
    }
  }

  const helperDocs = Object.fromEntries(
    Object.entries(WEB_HELPERS).map(([name, file]) => [name, readFile(file)]),
  );

  const helperMethods = Object.fromEntries(
    Object.entries(helperDocs).map(([name, content]) => [name, new Set(extractMethods(content))]),
  );

  for (const helperName of WEB_HELPER_NAMES) {
    if (helperMethods[helperName].size === 0) {
      throw new Error(
        `No public methods were extracted for ${helperName}. Check heading format in ${path.relative(
          ROOT,
          WEB_HELPERS[helperName],
        )}.`,
      );
    }
  }

  const webapiFiles = fs
    .readdirSync(WEBAPI_DIR)
    .filter((name) => name.endsWith('.mustache'))
    .sort((a, b) => a.localeCompare(b));

  const lines = [
    '---',
    'title: Web API (Unified)',
    '---',
    '',
    '<!-- Auto-generated from helpers -->',
    '',
    '## Methods',
    '',
  ];

  for (const fileName of webapiFiles) {
    const method = path.basename(fileName, '.mustache');
    const supportedAnywhere = WEB_HELPER_NAMES.some((name) => helperMethods[name].has(method));
    if (!supportedAnywhere) continue;
    const methodCall = `I.${method}()`;
    const rawShared = readFile(path.join(WEBAPI_DIR, fileName)).trim();
    const sharedBlock = formatSharedBlock(rawShared);
    const commonBody = commonBodyText(rawShared);

    lines.push(`### \`${methodCall}\``);
    lines.push('');
    lines.push(
      ...renderAvailabilityTable(
        WEB_HELPER_NAMES,
        WEB_HELPER_NAMES.map((name) => availability(helperMethods[name].has(method))),
      ),
    );
    lines.push('');
    lines.push(sharedBlock || '_No shared snippet found._');
    lines.push('');

    const override = WEB_METHOD_OVERRIDES[method];
    if (override?.notes?.length) {
      lines.push('');
      for (const note of override.notes) {
        lines.push(`- ${note}`);
      }
      lines.push('');
    }

    const helperDocsByMethod = WEB_HELPER_NAMES.map((helperName) => {
      const methodDoc = extractMethodDoc(helperDocs[helperName], method);
      const prefix = override?.helperPrefix?.[helperName] || '';
      const residue = methodDoc ? helperResidue(methodDoc, commonBody) : '';
      return {
        helperName,
        supported: helperMethods[helperName].has(method),
        methodDoc,
        prefix,
        residue,
        normalized: residue ? normalizeDocForDiff(residue) : '',
      };
    });

    const helpersWithUniqueContent = helperDocsByMethod.filter(
      (item) => item.supported && item.residue,
    );
    const uniqueGroups = new Map();
    for (const item of helpersWithUniqueContent) {
      const key = item.normalized;
      if (!uniqueGroups.has(key)) uniqueGroups.set(key, []);
      uniqueGroups.get(key).push(item.helperName);
    }

    const hasHelperPrefixOverrides = helperDocsByMethod.some((item) => item.prefix);

    const compactDifferences = method === 'click' || Boolean(override?.compactDifferences);
    if (helpersWithUniqueContent.length > 0 || hasHelperPrefixOverrides) {
      lines.push('Helper-Specific Differences');
      lines.push('');

      if (compactDifferences) {
        for (const item of helperDocsByMethod) {
          if (!item.prefix) continue;
          lines.push(`**${item.helperName}**`);
          lines.push('');
          lines.push(item.prefix);
          lines.push('');
        }
        continue;
      }

      for (const item of helperDocsByMethod) {
        if (!item.supported) continue;
        if (!item.residue && !item.prefix) continue;

        lines.push(`**${item.helperName}**`);
        lines.push('');
        if (item.prefix) {
          lines.push(item.prefix);
          lines.push('');
        }
        if (item.residue) {
          lines.push(normalizeMethodDocHeadings(item.residue));
          lines.push('');
        }
      }
    }
  }

  return normalizeWebUnifiedAnchors(lines.join('\n').trimEnd() + '\n');
}

function generateMobileApiContent() {
  const helperDocs = Object.fromEntries(
    Object.entries(MOBILE_HELPERS).map(([name, file]) => [name, readFile(file)]),
  );

  const appiumMethods = extractMethods(helperDocs.Appium);
  const detoxMethods = extractMethods(helperDocs.Detox);
  const allMethods = Array.from(new Set([...appiumMethods, ...detoxMethods])).sort((a, b) =>
    a.localeCompare(b),
  );

  const hasMethod = {
    Appium: new Set(appiumMethods),
    Detox: new Set(detoxMethods),
  };

  const lines = [
    '---',
    'title: Mobile API (Unified)',
    '---',
    '',
    '<!-- Auto-generated by scripts/generate-unified-api.mjs -->',
    '',
    'This page is generated from Appium and Detox helper docblocks.',
    'For hybrid/mobile webview flows, ARIA locators such as `{ aria: "Sign in" }` are available in web helpers.',
    '',
    '## Methods',
    '',
  ];

  for (const method of allMethods) {
    const methodCall = `I.${method}()`;
    lines.push(`### \`${methodCall}\``);
    lines.push('');
    lines.push(
      ...renderAvailabilityTable(
        ['Appium', 'Detox'],
        [availability(hasMethod.Appium.has(method)), availability(hasMethod.Detox.has(method))],
      ),
    );
    lines.push('');

    for (const helperName of ['Appium', 'Detox']) {
      const methodDoc = extractMethodDoc(helperDocs[helperName], method);
      lines.push(`**${helperName}**`);
      lines.push('');
      if (methodDoc) {
        lines.push(normalizeMethodDocHeadings(methodDoc));
      } else {
        lines.push('_Not available in this helper._');
      }
      lines.push('');
    }
  }

  return normalizeMobileUnifiedAnchors(lines.join('\n').trimEnd() + '\n');
}

function isFileUpToDate(filePath, generatedContent) {
  if (!fs.existsSync(filePath)) return false;
  const existing = fs.readFileSync(filePath, 'utf8');
  return existing === normalizeForFile(generatedContent);
}