Add sync-latest-to-next script and update docs #289
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,172 @@ | ||
| #!/usr/bin/env node | ||
|
|
||
| /** | ||
| * sync-latest-to-next.js | ||
| * | ||
| * Copies one or more files from a product's latest/ directory to the | ||
| * equivalent path in next/, rewriting internal links along the way. | ||
| * | ||
| * Usage: | ||
| * node scripts/sync-latest-to-next.js <file|dir> [file2|dir2 ...] | ||
| * | ||
| * Examples: | ||
| * node scripts/sync-latest-to-next.js sdk/latest/learn/concepts/baseapp.mdx | ||
| * node scripts/sync-latest-to-next.js sdk/latest/ | ||
| * node scripts/sync-latest-to-next.js sdk/latest/ hub/latest/overview.mdx | ||
| * | ||
| * The script rewrites /sdk/latest/ → /sdk/next/ in link text (preserving | ||
| * external https:// URLs). Paths must be relative to the repo root. | ||
| */ | ||
|
|
||
| import fs from 'fs'; | ||
| import path from 'path'; | ||
| import { fileURLToPath } from 'url'; | ||
|
|
||
| const __dirname = path.dirname(fileURLToPath(import.meta.url)); | ||
| const REPO_ROOT = path.join(__dirname, '..'); | ||
|
|
||
| const PRODUCTS = ['evm', 'sdk', 'hub', 'cometbft', 'ibc', 'skip-go', 'enterprise']; | ||
|
|
||
| function usage() { | ||
| console.error('Usage: node scripts/sync-latest-to-next.js <file> [file2 ...]'); | ||
| console.error(' Files must be paths relative to the repo root, e.g.:'); | ||
| console.error(' sdk/latest/learn/concepts/baseapp.mdx'); | ||
| process.exit(1); | ||
| } | ||
|
|
||
| function extractFrontMatter(content) { | ||
| const match = content.match(/^---\n[\s\S]*?\n---\n/); | ||
| return match ? match[0] : ''; | ||
| } | ||
|
|
||
| function extractBody(content) { | ||
| const match = content.match(/^---\n[\s\S]*?\n---\n([\s\S]*)$/); | ||
| return match ? match[1] : content; | ||
| } | ||
|
|
||
| function rewriteLinks(content, product) { | ||
| // Only rewrite /<product>/latest/ → /<product>/next/ for the product being synced. | ||
| // Cross-product links (e.g. /cometbft/latest/) are left unchanged — next/ files | ||
| // intentionally reference other products' latest/ versions. | ||
| const escapedProduct = product.replace(/-/g, '\\-'); | ||
| const re = new RegExp(`(https?:\\/\\/\\S+)|\\/${escapedProduct}\\/latest\\/`, 'g'); | ||
| return content.replace(re, (match, externalUrl) => { | ||
| if (externalUrl) return externalUrl; | ||
| return `/${product}/next/`; | ||
| }); | ||
|
Comment on lines
+47
to
+56
Contributor
There was a problem hiding this comment.
The comment says the function preserves "external https:// URLs", but the regex |
||
| } | ||
|
|
||
| function syncFile(relPath) { | ||
| // Normalise: strip leading ./ | ||
| relPath = relPath.replace(/^\.\//, ''); | ||
|
|
||
| // Validate the path contains /latest/ | ||
| const latestMatch = relPath.match(/^([^/]+)\/latest\/(.+)$/); | ||
| if (!latestMatch) { | ||
| console.error(`✗ ${relPath}`); | ||
| console.error(' Path must be under a product\'s latest/ directory.'); | ||
| return false; | ||
| } | ||
|
|
||
| const [, product, subPath] = latestMatch; | ||
|
|
||
| if (!PRODUCTS.includes(product)) { | ||
| console.error(`✗ ${relPath}`); | ||
| console.error(` Unknown product "${product}". Expected one of: ${PRODUCTS.join(', ')}`); | ||
| return false; | ||
| } | ||
|
|
||
| const srcPath = path.join(REPO_ROOT, relPath); | ||
| const destPath = path.join(REPO_ROOT, product, 'next', subPath); | ||
|
|
||
| if (!fs.existsSync(srcPath)) { | ||
| console.error(`✗ ${relPath}`); | ||
| console.error(` File not found: ${srcPath}`); | ||
| return false; | ||
| } | ||
|
|
||
| const srcContent = fs.readFileSync(srcPath, 'utf8'); | ||
| const srcBody = extractBody(srcContent); | ||
| const rewrittenBody = rewriteLinks(srcBody, product); | ||
|
|
||
| let rewritten; | ||
| if (fs.existsSync(destPath)) { | ||
| // Keep the destination's front matter exactly as-is (preserves noindex, canonical, | ||
| // and their positions). Only the body content is synced from latest/. | ||
| const destContent = fs.readFileSync(destPath, 'utf8'); | ||
| const destFrontMatter = extractFrontMatter(destContent); | ||
| rewritten = destFrontMatter + rewrittenBody; | ||
| } else { | ||
| // New file — use source front matter with links rewritten | ||
| rewritten = rewriteLinks(srcContent, product); | ||
| } | ||
|
|
||
| const destDir = path.dirname(destPath); | ||
| if (!fs.existsSync(destDir)) { | ||
| fs.mkdirSync(destDir, { recursive: true }); | ||
| console.log(` Created directory: ${path.relative(REPO_ROOT, destDir)}`); | ||
| } | ||
|
|
||
| const destExists = fs.existsSync(destPath); | ||
| fs.writeFileSync(destPath, rewritten, 'utf8'); | ||
|
|
||
| const destRelPath = path.relative(REPO_ROOT, destPath); | ||
| console.log(`✓ ${relPath} → ${destRelPath} ${destExists ? '(updated)' : '(created)'}`); | ||
| return true; | ||
| } | ||
|
|
||
| function collectFiles(argPath) { | ||
| const absPath = path.isAbsolute(argPath) | ||
| ? argPath | ||
| : path.join(REPO_ROOT, argPath); | ||
|
|
||
| if (!fs.existsSync(absPath)) { | ||
| console.error(`✗ Not found: ${argPath}`); | ||
| return []; | ||
| } | ||
|
|
||
| const stat = fs.statSync(absPath); | ||
| if (stat.isFile()) { | ||
| return [argPath.replace(/^\.\//, '')]; | ||
| } | ||
|
|
||
| if (stat.isDirectory()) { | ||
| const files = []; | ||
| function walk(dir) { | ||
| for (const entry of fs.readdirSync(dir, { withFileTypes: true })) { | ||
| const full = path.join(dir, entry.name); | ||
| if (entry.isDirectory()) { | ||
| walk(full); | ||
| } else if (entry.name.endsWith('.mdx')) { | ||
| files.push(path.relative(REPO_ROOT, full)); | ||
| } | ||
| } | ||
| } | ||
| walk(absPath); | ||
| return files; | ||
| } | ||
|
|
||
| return []; | ||
| } | ||
|
|
||
| // --- main --- | ||
|
|
||
| const args = process.argv.slice(2); | ||
| if (args.length === 0) usage(); | ||
|
|
||
| const allFiles = args.flatMap(collectFiles); | ||
|
|
||
| let ok = 0; | ||
| let fail = 0; | ||
|
|
||
| for (const f of allFiles) { | ||
| if (syncFile(f)) ok++; else fail++; | ||
| } | ||
|
|
||
| console.log(''); | ||
| if (fail === 0) { | ||
| console.log(`Done. ${ok} file(s) synced to next/. Review the diff before committing.`); | ||
| } else { | ||
| console.log(`Done. ${ok} succeeded, ${fail} failed.`); | ||
| process.exit(1); | ||
| } | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The instruction to run
sync-latest-to-next.jsafter editinglatest/appears twice: once in the "Notes and sync" numbered list (item 2, lines 10-11) and again as a standalone paragraph here. Having it in two places risks the two versions drifting and makes CLAUDE.md longer without adding clarity.