Add automation to open PRs for undocumented API endpoints (#189)

Adds a GitHub Actions workflow that detects new endpoints in the OpenAPI
spec without corresponding MDX stubs, and opens one PR per endpoint with
the stub file and docs.json navigation update ready to merge.

Includes an exclusion mechanism (.api-doc-ignore) to permanently suppress
PRs for endpoints that should not be documented.

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: thebiglabasky

.api-doc-ignore

@@ -0,0 +1,9 @@
+# Endpoints excluded from automatic documentation PRs.
+# Format: "METHOD /path" — must match the OpenAPI spec exactly.
+# Adding an endpoint here permanently suppresses PR creation for it.
+#
+# Example:
+#   - "GET /v1/internal/debug"
+#   - "POST /v1/experimental/beta-feature"
+
+excluded_endpoints: []

.github/scripts/detect-new-endpoints.mjs

@@ -0,0 +1,359 @@
+#!/usr/bin/env node
+
+/**
+ * detect-new-endpoints.mjs
+ *
+ * Detects undocumented API endpoints by comparing the OpenAPI spec against
+ * existing MDX stubs, then creates one PR per new endpoint.
+ *
+ * Env vars:
+ *   DRY_RUN=1    — log what would happen, don't create branches/PRs
+ *   GH_TOKEN     — GitHub token (provided by Actions)
+ */
+
+import { readFileSync, readdirSync, writeFileSync, mkdirSync, existsSync } from 'node:fs';
+import { join, basename, dirname } from 'node:path';
+import { execSync } from 'node:child_process';
+import { parse as yamlParse } from './yaml-lite.mjs';
+
+const DRY_RUN = process.env.DRY_RUN === '1';
+const ROOT = process.cwd();
+const SPEC_PATH = join(ROOT, 'api-reference', 'openapi.json');
+const DOCS_JSON_PATH = join(ROOT, 'docs.json');
+const IGNORE_PATH = join(ROOT, '.api-doc-ignore');
+
+// ---------------------------------------------------------------------------
+// Tag → directory + docs.json group mapping
+// Built from current repo state. Fallback: slugify the tag.
+// ---------------------------------------------------------------------------
+
+const TAG_MAP = {
+  'Accounts':              { dir: 'accounts',            group: 'Accounts' },
+  'Alert channels':        { dir: 'alert-channels',      group: 'Alert Channels' },
+  'Alert notifications':   { dir: 'alert-notifications', group: 'Alert Notifications' },
+  'Analytics':             { dir: 'analytics',           group: 'Analytics' },
+  'Badges':                { dir: 'badges',              group: 'Badges' },
+  'Check alerts':          { dir: 'check-alerts',        group: 'Check Alerts' },
+  'Check groups':          { dir: 'check-groups',        group: 'Check Groups' },
+  'Check results':         { dir: 'check-results',       group: 'Check Results' },
+  'Check sessions':        { dir: 'check-sessions',      group: 'Check Sessions' },
+  'Check status':          { dir: 'check-status',        group: 'Check Status' },
+  'Checks':                { dir: 'checks',              group: 'Checks and Monitors' },
+  'Client certificates':   { dir: 'client-certificates', group: 'Client Certificates' },
+  'Dashboards':            { dir: 'dashboards',          group: 'Dashboards' },
+  'Environment variables': { dir: 'environment-variables', group: 'Environment Variables' },
+  'Error Groups':          { dir: 'error-groups',        group: 'Error Groups' },
+  'Heartbeats':            { dir: 'heartbeats',          group: 'Checks and Monitors' },
+  'Incident Updates':      { dir: 'incident-updates',    group: 'Dashboard Incident Updates' },
+  'Incidents':             { dir: 'incidents',           group: 'Dashboard Incidents' },
+  'Location':              { dir: 'location',            group: 'Locations' },
+  'Maintenance windows':   { dir: 'maintenance-windows', group: 'Maintenance Windows' },
+  'Monitors':              { dir: 'monitors',            group: 'Checks and Monitors' },
+  'Private locations':     { dir: 'private-locations',   group: 'Private Locations' },
+  'Reporting':             { dir: 'reporting',           group: 'Reporting' },
+  'Runtimes':              { dir: 'runtimes',            group: 'Runtimes' },
+  'Snippets':              { dir: 'snippets',            group: 'Snippets' },
+  'Static IPs':            { dir: 'static-ips',          group: 'Static IPs' },
+  'Status Page Incidents':  { dir: 'status-page-incidents', group: 'Status Page Incidents' },
+  'Status Page Services':   { dir: 'status-page-services', group: 'Status Page Services' },
+  'Status Pages':          { dir: 'status-pages',        group: 'Status Pages' },
+  'Subscriptions':         { dir: 'status-pages',        group: 'Status Page Subscribers' },
+  'Triggers':              { dir: 'triggers',            group: 'Check Triggers' },
+};
+
+// Monitor-type endpoints under the "Checks" or "Monitors" tag go into
+// specific subgroups within "Checks and Monitors".
+const MONITOR_SUBGROUP_PATTERNS = [
+  { pattern: /icmp/i,   dir: 'monitors', subgroup: 'ICMP Monitor' },
+  { pattern: /dns/i,    dir: 'monitors', subgroup: 'DNS Monitor' },
+  { pattern: /tcp/i,    dir: 'checks',   subgroup: 'TCP Monitor' },
+  { pattern: /url/i,    dir: 'monitors', subgroup: 'URL Monitor' },
+];
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function slugify(text) {
+  return text
+    .toLowerCase()
+    .replace(/\[.*?\]\s*/g, '')     // strip [beta] etc.
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+}
+
+function run(cmd, opts = {}) {
+  if (DRY_RUN && !opts.allowInDryRun) {
+    console.log(`  [dry-run] ${cmd}`);
+    return '';
+  }
+  return execSync(cmd, { encoding: 'utf-8', cwd: ROOT, ...opts }).trim();
+}
+
+function loadSpec() {
+  const raw = readFileSync(SPEC_PATH, 'utf-8');
+  // OpenAPI descriptions may contain literal control chars (newlines in JSON strings)
+  return JSON.parse(raw.replace(/[\x00-\x1f]/g, (ch) => {
+    if (ch === '\n') return '\\n';
+    if (ch === '\r') return '\\r';
+    if (ch === '\t') return '\\t';
+    return '';
+  }));
+}
+
+function loadExclusions() {
+  if (!existsSync(IGNORE_PATH)) return new Set();
+  const raw = readFileSync(IGNORE_PATH, 'utf-8');
+  const parsed = yamlParse(raw);
+  const list = parsed?.excluded_endpoints ?? [];
+  return new Set(list.map((e) => e.trim()));
+}
+
+function scanExistingMdx() {
+  const documented = new Set();
+  const apiRefDir = join(ROOT, 'api-reference');
+
+  function walk(dir) {
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+      const full = join(dir, entry.name);
+      if (entry.isDirectory()) { walk(full); continue; }
+      if (!entry.name.endsWith('.mdx')) continue;
+      const content = readFileSync(full, 'utf-8');
+      const match = content.match(/openapi:\s*(get|post|put|delete|patch)\s+(\/\S+)/i);
+      if (match) {
+        documented.add(`${match[1].toUpperCase()} ${match[2]}`);
+      }
+    }
+  }
+  walk(apiRefDir);
+  return documented;
+}
+
+function resolveMapping(tag, summary) {
+  const mapping = TAG_MAP[tag];
+  if (!mapping) {
+    // Unknown tag — create new directory and group from tag name
+    return { dir: slugify(tag), group: tag, subgroup: null };
+  }
+
+  // For tags that map to "Checks and Monitors", check if it's a monitor subtype
+  if (mapping.group === 'Checks and Monitors' && (tag === 'Checks' || tag === 'Monitors')) {
+    for (const mp of MONITOR_SUBGROUP_PATTERNS) {
+      if (mp.pattern.test(summary)) {
+        return { dir: mp.dir, group: 'Checks and Monitors', subgroup: mp.subgroup };
+      }
+    }
+  }
+
+  return { dir: mapping.dir, group: mapping.group, subgroup: null };
+}
+
+function generateFilename(summary) {
+  const slug = slugify(summary);
+  return slug || 'unnamed-endpoint';
+}
+
+function prExists(branchName) {
+  try {
+    const result = run(
+      `gh pr list --head "${branchName}" --state all --json number --jq 'length'`,
+      { allowInDryRun: true }
+    );
+    return parseInt(result, 10) > 0;
+  } catch {
+    return false;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// docs.json updater
+// ---------------------------------------------------------------------------
+
+function addToDocsJson(docsJson, pagePath, groupName, subgroupName) {
+  // Structure: docsJson.navigation.tabs[] → { tab: "API", pages: [...] }
+  const tabs = docsJson.navigation?.tabs ?? [];
+  const apiTab = tabs.find((t) => t.tab === 'API');
+  if (!apiTab) {
+    console.warn('  ⚠ Could not find API tab in docs.json');
+    return false;
+  }
+
+  // Find "API Reference" group within the API tab's pages
+  const apiRefGroup = (apiTab.pages ?? []).find(
+    (g) => typeof g === 'object' && g.group === 'API Reference'
+  );
+  if (!apiRefGroup) {
+    console.warn('  ⚠ Could not find "API Reference" group in docs.json');
+    return false;
+  }
+
+  // Find the target group within API Reference
+  let targetGroup = apiRefGroup.pages.find(
+    (g) => typeof g === 'object' && g.group === groupName
+  );
+
+  // Create group if it doesn't exist
+  if (!targetGroup) {
+    targetGroup = { group: groupName, pages: [] };
+    apiRefGroup.pages.push(targetGroup);
+    console.log(`  + Created new group "${groupName}" in docs.json`);
+  }
+
+  // If there's a subgroup, find or create it within the target group
+  if (subgroupName) {
+    let subgroup = targetGroup.pages.find(
+      (g) => typeof g === 'object' && g.group === subgroupName
+    );
+    if (!subgroup) {
+      subgroup = { group: subgroupName, pages: [] };
+      targetGroup.pages.push(subgroup);
+      console.log(`  + Created new subgroup "${subgroupName}" in docs.json`);
+    }
+    subgroup.pages.push(pagePath);
+  } else {
+    targetGroup.pages.push(pagePath);
+  }
+
+  return true;
+}
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+
+async function main() {
+  console.log(DRY_RUN ? '🏃 DRY RUN MODE\n' : '🚀 Running endpoint sync\n');
+
+  // 1. Load inputs
+  const spec = loadSpec();
+  const exclusions = loadExclusions();
+  const documented = scanExistingMdx();
+
+  console.log(`📋 Spec endpoints: ${Object.keys(spec.paths).length} paths`);
+  console.log(`📄 Documented endpoints: ${documented.size}`);
+  console.log(`🚫 Excluded endpoints: ${exclusions.size}`);
+
+  // 2. Find undocumented endpoints
+  const undocumented = [];
+  for (const [path, methods] of Object.entries(spec.paths)) {
+    for (const [method, details] of Object.entries(methods)) {
+      if (!['get', 'post', 'put', 'delete', 'patch'].includes(method)) continue;
+      const key = `${method.toUpperCase()} ${path}`;
+
+      if (documented.has(key)) continue;
+      if (exclusions.has(key)) {
+        console.log(`  ⏭ ${key} — excluded`);
+        continue;
+      }
+
+      const tag = details.tags?.[0] ?? '';
+      const summary = details.summary ?? '';
+      const { dir, group, subgroup } = resolveMapping(tag, summary);
+      const filename = generateFilename(summary);
+
+      undocumented.push({ key, method: method.toUpperCase(), path, tag, summary, dir, group, subgroup, filename });
+    }
+  }
+
+  if (undocumented.length === 0) {
+    console.log('\n✅ All endpoints are documented (or excluded). Nothing to do.');
+    return;
+  }
+
+  console.log(`\n🆕 Found ${undocumented.length} undocumented endpoint(s):\n`);
+  for (const ep of undocumented) {
+    console.log(`  ${ep.key}  →  ${ep.dir}/${ep.filename}.mdx  [${ep.group}${ep.subgroup ? ' > ' + ep.subgroup : ''}]`);
+  }
+
+  // 3. Process each endpoint
+  let created = 0;
+  let skipped = 0;
+
+  // Store the main branch name to return to between PRs
+  const mainBranch = run('git rev-parse --abbrev-ref HEAD', { allowInDryRun: true });
+
+  for (const ep of undocumented) {
+    const branchName = `api-doc/${ep.dir}/${ep.filename}`;
+    const mdxRelPath = `api-reference/${ep.dir}/${ep.filename}.mdx`;
+    const docsJsonPagePath = `api-reference/${ep.dir}/${ep.filename}`;
+
+    console.log(`\n--- Processing: ${ep.key} ---`);
+
+    // Check for existing PR
+    if (prExists(branchName)) {
+      console.log(`  ⏭ PR already exists for branch ${branchName}`);
+      skipped++;
+      continue;
+    }
+
+    // Ensure we're on main and up to date
+    run(`git checkout ${mainBranch}`);
+
+    // Create branch
+    run(`git checkout -b "${branchName}"`);
+
+    // Create MDX stub
+    const mdxDir = join(ROOT, 'api-reference', ep.dir);
+    if (!existsSync(mdxDir)) {
+      mkdirSync(mdxDir, { recursive: true });
+      console.log(`  + Created directory: api-reference/${ep.dir}/`);
+    }
+
+    const mdxContent = `---\nopenapi: ${ep.method.toLowerCase()} ${ep.path}\ntitle: ${ep.summary.replace(/\[.*?\]\s*/g, '').trim()}\n---\n`;
+
+    if (!DRY_RUN) {
+      writeFileSync(join(ROOT, mdxRelPath), mdxContent);
+    }
+    console.log(`  + Created ${mdxRelPath}`);
+
+    // Update docs.json
+    const docsJson = JSON.parse(readFileSync(DOCS_JSON_PATH, 'utf-8'));
+    const added = addToDocsJson(docsJson, docsJsonPagePath, ep.group, ep.subgroup);
+    if (added && !DRY_RUN) {
+      writeFileSync(DOCS_JSON_PATH, JSON.stringify(docsJson, null, 2) + '\n');
+    }
+    console.log(`  + Updated docs.json → ${ep.group}${ep.subgroup ? ' > ' + ep.subgroup : ''}`);
+
+    // Commit
+    run(`git add "${mdxRelPath}" docs.json`);
+    const commitMsg = `docs(api): add ${ep.summary.replace(/\[.*?\]\s*/g, '').trim()} endpoint`;
+    run(`git commit -m "${commitMsg.replace(/"/g, '\\"')}"`);
+
+    // Push
+    run(`git push origin "${branchName}"`);
+
+    // Create PR
+    const prTitle = commitMsg;
+    const prBody = [
+      '## New API Endpoint Documentation',
+      '',
+      `**Endpoint:** \`${ep.key}\``,
+      `**Category:** ${ep.group}${ep.subgroup ? ' > ' + ep.subgroup : ''}`,
+      '',
+      'Automatically detected from OpenAPI spec update. This PR adds:',
+      `- MDX stub: \`${mdxRelPath}\``,
+      '- Navigation entry in `docs.json`',
+      '',
+      '**To exclude this endpoint permanently**, add it to `.api-doc-ignore` and close this PR.',
+      '',
+      '---',
+      '*Auto-generated by sync-api-endpoints workflow*',
+    ].join('\n');
+
+    run(`gh pr create --title "${prTitle.replace(/"/g, '\\"')}" --body "${prBody.replace(/"/g, '\\"')}" --label "auto-generated" --label "api-docs" --head "${branchName}"`);
+
+    console.log(`  ✅ PR created for ${ep.key}`);
+    created++;
+
+    // Return to main for next iteration
+    run(`git checkout ${mainBranch}`);
+  }
+
+  console.log(`\n========================================`);
+  console.log(`✅ Done. Created: ${created} | Skipped: ${skipped} | Total new: ${undocumented.length}`);
+}
+
+main().catch((err) => {
+  console.error('❌ Fatal error:', err);
+  process.exit(1);
+});