#!/usr/bin/env node /** * Chain Page Generator * * Generates chain documentation pages from the chain-data.js configuration. * Also automatically updates docs.json navigation to include all CMS chains. * * Run with: node scripts/generate-chain-pages.js --i-know-this-overwrites * Normally run via scripts/update-docs.js, which orders the stages correctly. * * Options: * --dry-run Preview changes without writing files * --chain=X Only generate page for specific chain slug (skips nav update) * --partners Only generate partner pages * --other Only generate other network pages */ const fs = require('fs'); const path = require('path'); // CHAIN_DATA_PATH lets update-docs.js point this at a freshly-generated // chain-data.js staged in a temp dir, so a dry run evaluates what the pipeline // WOULD produce rather than the committed snapshot. See sync-from-cms.js. const { partnerChains, otherChains, allChains } = require(process.env.CHAIN_DATA_PATH || './chain-data.js'); /** * Gas-sponsoring, keyed by chain id, read from the committed Compose table. * * Not derivable from the CMS today: it is the union of Alchemy / Pimlico / * Gelato bundler coverage. generate-tables.js carries the column forward in * that snippet; this reads the same values so the chain pages and the table * cannot disagree. Parsed lazily and cached — the file is read once per run. */ let _composeGas = null; function composeGas(chainId) { if (_composeGas === null) { _composeGas = new Map(); const p = path.join(__dirname, '..', 'snippets', 'supported-chains-compose.mdx'); if (fs.existsSync(p)) { let inTable = false; for (const line of fs.readFileSync(p, 'utf8').split('\n')) { const t = line.trim(); if (!t.startsWith('|')) continue; const c = t.slice(1, t.endsWith('|') ? -1 : undefined).split('|').map((x) => x.trim().replace(/`/g, '')); if (/^[-:\s]+$/.test(c[0])) { inTable = true; continue; } if (inTable && c.length >= 4 && c[2]) _composeGas.set(String(c[2]), c[3].startsWith('\u2713')); } } } return _composeGas.get(String(chainId)) === true; } // Chains with custom content that should NOT be auto-generated // These pages are manually maintained and will be skipped during generation // but still included in navigation const CUSTOM_CONTENT_CHAINS = [ 'arweave', // Custom "coming soon" page 'fogo', // Custom content 'kite-ai', // Custom subgraphs documentation (not in CMS) 'polymarket', // Custom Turbo pipelines documentation 'saga', // Custom subgraphs documentation (not in CMS) 'stellar', // Custom content 'sui', // Custom content ]; // Known non-EVM chains (use explicit list, assume everything else is EVM) const NON_EVM_CHAINS = ['sui', 'stellar', 'arweave', 'solana', 'bitcoin', 'near', 'starknet', 'tron', 'fogo']; // Parse command line arguments const args = process.argv.slice(2); const isDryRun = args.includes('--dry-run'); const specificChain = args.find(a => a.startsWith('--chain='))?.split('=')[1]; const partnersOnly = args.includes('--partners'); // Pages whose nav removal the gate approved; retired after the nav is written. let approvedRemovals = []; const otherOnly = args.includes('--other'); // This script rewrites every chain page and the docs.json Chains navigation from // chain-data.js. The derivation defects it used to warn about were fixed in // #560-#562, and destructive changes are now held by the diff gate — but it is // still a whole-section rewrite, and it can only preserve what it knows how to // emit. Gas-sponsoring props were hand-added to 28 pages in July and this // generator did not know about them, so the first regeneration stripped every // one. Require an explicit acknowledgement. if (!isDryRun && !args.includes('--i-know-this-overwrites')) { console.error( 'Refusing to run.\n\n' + 'This regenerates all chain pages and the docs.json Chains nav from\n' + 'scripts/chain-data.js. Removals, withdrawn support claims, prefix and slug\n' + 'changes are held by the diff gate; anything this generator does not know how\n' + 'to emit is silently dropped.\n\n' + 'Normally run via: node scripts/update-docs.js --dry-run\n\n' + 'Preview: node scripts/generate-chain-pages.js --dry-run\n' + 'Override: node scripts/generate-chain-pages.js --i-know-this-overwrites\n' ); process.exit(1); } /** * Generate the MDX content for a chain page */ function generateChainPage(chain) { // Skip chains with custom content - they are manually maintained if (CUSTOM_CONTENT_CHAINS.includes(chain.slug)) { console.log(` ⏭️ Skipping ${chain.name} - has custom content (manually maintained)`); return null; } const hasMainnet = chain.mainnet !== null; const hasTestnet = chain.testnet !== null; // A chain is EVM-compatible unless it's in the known non-EVM list const isEVMCompatible = !NON_EVM_CHAINS.includes(chain.slug); // Build imports const imports = [ "import { ChainHeaderTabs } from '/snippets/chain-specific/chain-header-tabs.jsx';", "import { ChainOverview } from '/snippets/chain-specific/chain-overview.jsx';", ]; if (chain.isPartner) { imports.push("import ChainPartnershipSection from '/snippets/chain-specific/chain-partnership-section.mdx';"); } imports.push( "import ChainGettingStarted from '/snippets/chain-specific/chain-getting-started.mdx';", "import { ChainSubgraphsSection } from '/snippets/chain-specific/chain-subgraphs-section.jsx';", "import { ChainMirrorSection } from '/snippets/chain-specific/chain-mirror-section.jsx';", "import { ChainTurboSection } from '/snippets/chain-specific/chain-turbo-section.jsx';", "import { ChainEdgeSection } from '/snippets/chain-specific/chain-edge-section.jsx';", "import { ChainComposeSection } from '/snippets/chain-specific/chain-compose-section.jsx';", "import ChainSupportSection from '/snippets/chain-specific/chain-support-section.mdx';" ); // Build frontmatter const frontmatter = `--- title: "${chain.name}" "og:title": "${chain.name} - Goldsky Docs" sidebarTitle: "${chain.name}" public: true ---`; // Build ChainHeaderTabs props - only show if we have complete chain data from chainlist let headerTabsProps = []; const edgeMainnetSupported = chain.products?.edge?.mainnet || false; const edgeTestnetSupported = chain.products?.edge?.testnet || false; let hasChainData = false; // Only include mainnet if we have chainId, currency, AND explorerUrl (from chainlist enrichment) const hasCompleteMainnetData = hasMainnet && chain.mainnet.chainId && chain.mainnet.currency && chain.mainnet.explorerUrl; const hasCompleteTestnetData = hasTestnet && chain.testnet?.chainId && chain.testnet?.currency && chain.testnet?.explorerUrl; if (hasCompleteMainnetData) { hasChainData = true; headerTabsProps.push( ` primaryTitle="${chain.mainnet.title}"`, ` primaryChainId="${chain.mainnet.chainId}"`, ` primaryCurrency="${chain.mainnet.currency}"`, ` primaryExplorerUrl="${chain.mainnet.explorerUrl}"` ); } if (hasCompleteTestnetData) { hasChainData = true; headerTabsProps.push( ` secondaryTitle="${chain.testnet.title}"`, ` secondaryChainId="${chain.testnet.chainId}"`, ` secondaryCurrency="${chain.testnet.currency}"`, ` secondaryExplorerUrl="${chain.testnet.explorerUrl}"` ); } // Add Edge support flags only if we have chain data to display if (hasChainData) { headerTabsProps.push( ` edgeMainnetSupported={${edgeMainnetSupported}}`, ` edgeTestnetSupported={${edgeTestnetSupported}}` ); } // Build networks array for subgraphs/mirror. // // Filtered by per-network SUPPORT, not merely by "this slot has a slug". // ChainSubgraphsSection renders the list whenever EITHER flag is true, so an // unsupported network listed here is published as a deployable slug on a page // that simultaneously says it is unsupported. chains/arc.mdx did exactly that: // `networks` carried ["Arc Mainnet", "arc-mainnet"] beside // mainnetSupported={false}, for a network that is `hidden` in the CMS with // hasSubgraphSupport false. // // Latent until now — it needed a chain with one supported and one unsupported // network — and the subgraph withdrawals in this same change turned it on for // 18 chain/slot pairs at once. const networks = []; if (hasMainnet && chain.mainnet.subgraphSlug && chain.products.subgraphs.mainnet === true) { networks.push(`["${chain.mainnet.title}", "${chain.mainnet.subgraphSlug}"]`); } if (hasTestnet && chain.testnet.subgraphSlug && chain.products.subgraphs.testnet === true) { networks.push(`["${chain.testnet.title}", "${chain.testnet.subgraphSlug}"]`); } const networksArray = networks.length > 0 ? `[${networks.join(', ')}]` : '[]'; // Build content sections let content = `${frontmatter} ${imports.join('\n')} `; // Add ChainHeaderTabs only if we have chain ID data if (hasChainData) { content += ` `; } // Overview section content += `## Overview `; // Partnership section for partner chains if (chain.isPartner) { content += ` `; } // Getting started section content += `## Getting started `; // Subgraphs section content += `## Subgraphs `; // Mirror section content += `## Mirror `; // Turbo section const primarySlug = chain.mainnet?.mirrorSlug || chain.testnet?.mirrorSlug || ''; const secondarySlug = chain.testnet?.mirrorSlug || ''; content += `## Turbo `; // Edge section (shows "NOT COMPATIBLE" for non-EVM chains) content += `## Edge RPC `; // Compose section // // gasSponsoring* drive a "GAS SPONSORING SUPPORTED" badge in the component. // They were hand-added on 35 pages and this generator never emitted them, so // the first regeneration stripped all 69 of them and silently dropped the // badge — real, user-facing information destroyed by a run that otherwise // looked clean. Nothing gated it: the diff gate covers navigation, support // claims, prefixes and slugs, not arbitrary page props. // // Read from the Compose table rather than reinstated by hand, so there is one // source. That table carries the column forward from its committed self until // the CMS gains gasSponsorshipProviders, at which point both become derived // together. Checked against the 28 pages that had the props: 26 matched the // table exactly, and the 2 that did not (polygon-pos, tempo) were pages that // had gone stale against it, not table errors. const gasM = chain.mainnet && chain.mainnet.chainId ? composeGas(chain.mainnet.chainId) : false; const gasT = chain.testnet && chain.testnet.chainId ? composeGas(chain.testnet.chainId) : false; content += `## Compose `; // Support section content += `## Getting support `; return content; } /** * Write chain page to file */ function writeChainPage(chain, content) { const filePath = path.join(__dirname, '..', 'chains', `${chain.slug}.mdx`); if (isDryRun) { console.log(` 📄 Would write: ${filePath}`); return; } fs.writeFileSync(filePath, content, 'utf8'); console.log(` ✅ Written: ${filePath}`); } // Custom chains not in CMS that should be added to navigation // Format: { slug: 'partner' | 'other' } const CUSTOM_CHAINS_NAV = { 'kite-ai': 'partner', // Not in CMS, add to Partners 'saga': 'partner', // Not in CMS, add to Partners }; /** * Update docs.json navigation with chain pages from CMS */ /** * Which chain pages would leave the navigation, computed WITHOUT writing. * * Shares the ownership rule with updateDocsJsonNavigation: only the Partners * and Other networks groups are rewritten, so only those may report removals. * chains/introduction and chains/supported-networks live elsewhere in the tab * and are never touched. */ function computeNavRemovals() { const docsJsonPath = path.join(__dirname, '..', 'docs.json'); const docsJson = JSON.parse(fs.readFileSync(docsJsonPath, 'utf8')); const chainsTab = docsJson.navigation?.tabs?.find((t) => t.tab === 'Chains'); if (!chainsTab || !chainsTab.groups) return []; const OWNED_GROUPS = ['Partners', 'Other networks']; const proposed = new Set([ ...partnerChains.map((c) => `chains/${c.slug}`), ...otherChains.map((c) => `chains/${c.slug}`), ...Object.keys(CUSTOM_CHAINS_NAV).map((s) => `chains/${s}`), ]); const removals = []; for (const g of chainsTab.groups) { if (!OWNED_GROUPS.includes(g.group)) continue; for (const p of g.pages || []) { if (typeof p === 'string' && !proposed.has(p)) { removals.push({ kind: 'nav-remove', subject: p, from: 'in nav', to: 'removed' }); } } } return removals; } /** True when it is safe to write. Runs before any file is touched. */ function preflightGate() { const removals = computeNavRemovals(); if (!removals.length) return true; const { checkGate, reportGate } = require('./reconcile/lib/diffgate.js'); const result = checkGate(removals); if (!reportGate(result, { dryRun: isDryRun })) return false; // Everything got through the gate — remember it, so the approved pages can be // retired along with their nav entries. approvedRemovals = removals.map((r) => r.subject); return true; } /** * Retire the page files for nav entries the gate approved removing. * * A generated page dropped from navigation but left on disk is an orphan: the * URL still resolves, nothing links to it, and it silently goes stale. The * validator flags exactly this, so leaving them meant every approved removal * left the tree failing validation. * * Deleting is safe here precisely BECAUSE it is gated — reaching this point * means a human named the page in the decision log. Custom-content pages are * never touched: they are hand-maintained, not generated, and their presence in * nav is managed by CUSTOM_CHAINS_NAV rather than by chain-data.js. */ function retireApprovedPages() { if (!approvedRemovals.length) return; for (const page of approvedRemovals) { const slug = page.replace(/^chains\//, ''); if (CUSTOM_CONTENT_CHAINS.includes(slug)) { console.log(` kept ${page}.mdx — custom content, not generated`); continue; } const file = path.join(__dirname, '..', `${page}.mdx`); if (!fs.existsSync(file)) continue; if (isDryRun) { console.log(` would retire ${page}.mdx (approved removal)`); continue; } fs.unlinkSync(file); console.log(` retired ${page}.mdx (approved removal)`); } } function updateDocsJsonNavigation() { const docsJsonPath = path.join(__dirname, '..', 'docs.json'); // NOTE: the dry-run check used to sit here and return immediately, which // meant the nav diff — and therefore the gate — never ran in a dry run. A // preview that cannot tell you what it would refuse to do is not a preview. // The whole comparison now runs either way; only the write is skipped. // Read current docs.json const docsJson = JSON.parse(fs.readFileSync(docsJsonPath, 'utf8')); // Find the Chains tab const chainsTab = docsJson.navigation?.tabs?.find(t => t.tab === 'Chains'); if (!chainsTab || !chainsTab.groups) { console.log('\n⚠️ Could not find Chains tab in docs.json navigation'); return; } // Build partner and other network pages from CMS data let partnerPages = partnerChains .map(c => `chains/${c.slug}`); let otherPages = otherChains .map(c => `chains/${c.slug}`); // Add custom chains not in CMS. // CUSTOM_CHAINS_NAV is an override, so it must also REMOVE the page from the // other group. Without that, a chain present in chain-data.js (e.g. kite-ai, // in otherChains) and also listed here as 'partner' lands in both groups — // the old check only looked within the group being added to. Object.entries(CUSTOM_CHAINS_NAV).forEach(([slug, group]) => { const page = `chains/${slug}`; if (group === 'partner') { otherPages = otherPages.filter(p => p !== page); if (!partnerPages.includes(page)) partnerPages.push(page); } else if (group === 'other') { partnerPages = partnerPages.filter(p => p !== page); if (!otherPages.includes(page)) otherPages.push(page); } }); // Sort alphabetically partnerPages.sort(); otherPages.sort(); // --- diff gate: a page must not silently leave the navigation ------------- // The .mdx is never deleted, so a dropped page does NOT appear as a removed // file in the diff — it just stops being reachable. That invisibility is what // let PR #454 take three chains out of the nav and merge in 24 seconds. // Compare ONLY against the two groups this function rewrites. Scanning the // whole Chains tab flagged chains/introduction and chains/supported-networks, // which live in a different group and are never touched — a gate that cries // wolf on pages it cannot affect trains people to approve without reading. const OWNED_GROUPS = ['Partners', 'Other networks']; const proposed = new Set([...partnerPages, ...otherPages]); const before = []; for (const g of chainsTab.groups || []) { if (!OWNED_GROUPS.includes(g.group)) continue; for (const p of g.pages || []) before.push(p); } const navRemovals = before .filter((p) => typeof p === 'string' && !proposed.has(p)) .map((p) => ({ kind: 'nav-remove', subject: p, from: 'in nav', to: 'removed' })); // The gate itself runs PRE-FLIGHT in main(), not here — by this point the // page loop has already written every .mdx, and refusing only docs.json // would leave the tree half-applied: 149 pages updated, navigation not. // preflightGate() below performs the same comparison before anything is // written; reaching here means it passed. // Update Partners group const partnersGroup = chainsTab.groups.find(g => g.group === 'Partners'); if (partnersGroup) { partnersGroup.pages = partnerPages; } // Update Other networks group const otherGroup = chainsTab.groups.find(g => g.group === 'Other networks'); if (otherGroup) { otherGroup.pages = otherPages; } // Write back if (isDryRun) { const added = [...proposed].filter((p) => !before.includes(p)); console.log('\n📋 Would update docs.json navigation:'); console.log(` Partners: ${partnerPages.length} Other networks: ${otherPages.length}`); if (added.length) console.log(` + ${added.join(', ')}`); const removed = before.filter((p) => !proposed.has(p)); if (removed.length) console.log(` - ${removed.join(', ')} (approved)`); return; } fs.writeFileSync(docsJsonPath, JSON.stringify(docsJson, null, 2) + '\n'); console.log(`\n📋 Updated docs.json navigation:`); console.log(` Partners: ${partnerPages.length} chains`); console.log(` Other networks: ${otherPages.length} chains`); } /** * REMOVED: Edge snippet generation. * * This used to build snippets/supported-chains-edge.mdx from chain-data.js, * which made it the SECOND writer of that file — generate-tables.js * builds it from the CMS. The two disagreed, and this one lost rows: * * chain-data.js holds one mainnet + one testnet per chain (D3), so any * network beyond that pair is invisible to it. Measured 2026-08-05: 45 rows * here versus 48 from the CMS, silently dropping Ethereum Sepolia (11155111) * and both Mantle networks (5000, 5003) — Mantle has no chain page at all, * so a chain-shaped model cannot represent it. * * Running this script would therefore have reverted the corrections in PR #522 * the moment anyone regenerated chain pages, with no error and no diff anyone * was looking for. Exactly the failure mode of PR #454. * * The Edge and Compose tables now have one owner: * node scripts/generate-tables.js */ // Main execution function main() { console.log('🚀 Chain Page Generator\n'); if (isDryRun) { console.log('🔍 DRY RUN MODE - no files will be written\n'); } // Pre-flight: refuse before writing anything, not after. Skipped for // --chain=X, which does not touch navigation. if (!specificChain && !preflightGate()) { process.exitCode = 1; return; } let chainsToProcess = []; if (specificChain) { const chain = allChains.find(c => c.slug === specificChain); if (!chain) { console.error(`❌ Chain not found: ${specificChain}`); process.exit(1); } chainsToProcess = [chain]; } else if (partnersOnly) { chainsToProcess = partnerChains; } else if (otherOnly) { chainsToProcess = otherChains; } else { chainsToProcess = allChains; } console.log(`Processing ${chainsToProcess.length} chain(s)...\n`); let generated = 0; let skipped = 0; for (const chain of chainsToProcess) { console.log(`📦 ${chain.name} (${chain.slug})`); const content = generateChainPage(chain); if (content) { writeChainPage(chain, content); generated++; } else { skipped++; } } console.log(`\n✨ Done! Generated: ${generated}, Skipped: ${skipped}`); // The Edge/Compose snippets are NOT written here — see the note above // generateEdgeSnippet's former home. One owner: generate-tables.js. console.log('\n📄 Edge/Compose snippets not touched — run scripts/generate-tables.js'); // Update docs.json navigation (unless generating specific chain only) if (!specificChain) { updateDocsJsonNavigation(); retireApprovedPages(); } } main();