ci: Add format-code-sample-tabs to CI format workflow

Adds a codegen script that auto-fixes code sample tab order and titles
in guide and brand-guide markdown files. Runs as part of the Format CI
workflow, which auto-commits fixes on non-main branches.

The script:
- Reorders tabs to match API reference canonical order
  (JavaScript → cURL → Python → Ruby → PHP → C# → Java → Go → Seam CLI)
- Normalizes tab titles ("cURL (bash)" → "cURL", "Javascript" → "JavaScript")
- Ensures GitBook tab syncing works across all code blocks on a page

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: louis-pre

.github/workflows/format.yml

@@ -29,6 +29,8 @@ jobs:
           passphrase: ${{ secrets.GPG_PASSPHRASE }}
       - name: Setup
         uses: ./.github/actions/setup
+      - name: Format code sample tabs
+        run: npm run format-code-sample-tabs
       - name: Format
         run: npm run format
       - name: Commit

codegen/format-code-sample-tabs.ts

@@ -0,0 +1,92 @@
+import { readFileSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+import { globSync } from 'glob'
+
+const CANONICAL_ORDER = [
+  'JavaScript',
+  'cURL',
+  'Python',
+  'Ruby',
+  'PHP',
+  'C#',
+  'Java',
+  'Go',
+  'Seam CLI',
+]
+
+const TITLE_FIXES: Record<string, string> = {
+  'cURL (bash)': 'cURL',
+  Bash: 'cURL',
+  Javascript: 'JavaScript',
+  javascript: 'JavaScript',
+}
+
+const tabsBlockPattern = /\{%\s*tabs\s*%\}[\s\S]*?\{%\s*endtabs\s*%\}/g
+
+const tabPattern =
+  /\{%\s*tab\s+title="([^"]+)"\s*%\}([\s\S]*?)\{%\s*endtab\s*%\}/g
+
+function canonicalIndex(title: string): number {
+  const normalized = TITLE_FIXES[title] ?? title
+  const idx = CANONICAL_ORDER.indexOf(normalized)
+  return idx === -1 ? CANONICAL_ORDER.length + 1 : idx
+}
+
+function formatTabsBlock(block: string): { result: string; changed: boolean } {
+  const tabs: Array<{ title: string; content: string }> = []
+  for (const match of block.matchAll(tabPattern)) {
+    tabs.push({ title: match[1], content: match[2] })
+  }
+
+  if (tabs.length < 2) return { result: block, changed: false }
+
+  const originalTitles = tabs.map((t) => t.title)
+  const sorted = [...tabs].sort(
+    (a, b) => canonicalIndex(a.title) - canonicalIndex(b.title),
+  )
+  const sortedTitles = sorted.map((t) => t.title)
+  const needsRename = originalTitles.some((t) => t in TITLE_FIXES)
+  const needsReorder = originalTitles.some((t, i) => t !== sortedTitles[i])
+
+  if (!needsReorder && !needsRename) return { result: block, changed: false }
+
+  const lines = ['{% tabs %}']
+  for (const tab of sorted) {
+    const title = TITLE_FIXES[tab.title] ?? tab.title
+    lines.push(`{% tab title="${title}" %}`)
+    lines.push(tab.content.trimEnd())
+    lines.push('{% endtab %}')
+    lines.push('')
+  }
+  while (lines.at(-1) === '') lines.pop()
+  lines.push('{% endtabs %}')
+
+  return { result: lines.join('\n'), changed: true }
+}
+
+const dirs = ['docs/guides', 'docs/brand-guides']
+const files = dirs.flatMap((dir) => globSync(join(dir, '**/*.md')))
+
+let totalChanged = 0
+
+for (const file of files) {
+  const content = readFileSync(file, 'utf-8')
+  let changed = false
+
+  const updated = content.replace(tabsBlockPattern, (block) => {
+    const { result, changed: blockChanged } = formatTabsBlock(block)
+    if (blockChanged) changed = true
+    return result
+  })
+
+  if (changed) {
+    writeFileSync(file, updated)
+    totalChanged++
+  }
+}
+
+if (totalChanged > 0) {
+  // eslint-disable-next-line no-console
+  console.log(`Formatted tabs in ${String(totalChanged)} file(s).`)
+}

package.json

@@ -24,7 +24,8 @@
     "lint": "eslint .",
     "postlint": "prettier --check --ignore-path .prettierignore .",
     "format": "prettier --write --ignore-path .prettierignore .",
-    "preformat": "eslint --fix ."
+    "preformat": "eslint --fix .",
+    "format-code-sample-tabs": "tsx codegen/format-code-sample-tabs.ts"
   },
   "engines": {
     "node": ">=22.11.0",