Add a script for syncing rest and webhooks (#36688)

package.json

@@ -195,6 +195,9 @@
     "prettier-check": "prettier -c \"**/*.{ts,tsx,js,mjs,scss,yml,yaml}\"",
     "prevent-pushes-to-main": "node script/prevent-pushes-to-main.js",
     "rest-dev": "src/rest/scripts/update-files.js",
+    "openapi-docs": "src/rest/docs.js",
+    "sync-rest": "src/rest/scripts/update-files.js",
+    "sync-webhooks": "src/rest/scripts/update-files.js -o webhooks",
     "show-action-deps": "echo 'Action Dependencies:' && rg '^[\\s|-]*(uses:.*)$' .github -I -N --no-heading -r '$1$2' | sort | uniq | cut -c 7-",
     "prestart": "node script/cmp-files.js package-lock.json .installed.package-lock.json || npm install && cp package-lock.json .installed.package-lock.json",
     "start": "cross-env NODE_ENV=development ENABLED_LANGUAGES=en nodemon server.js",

src/rest/docs.js

@@ -0,0 +1,62 @@
+#!/usr/bin/env node
+
+import chalk from 'chalk'
+import { readFile } from 'fs/promises'
+import { allVersions } from '../../lib/all-versions.js'
+
+// Translate the docs versioning nomenclature back to the OpenAPI names
+const invertedVersionMapping = JSON.parse(await readFile('src/rest/lib/config.json')).versionMapping
+const versionMapping = {}
+Object.assign(
+  versionMapping,
+  ...Object.entries(invertedVersionMapping).map(([a, b]) => ({ [b]: a }))
+)
+const openApiVersions = Object.values(allVersions)
+  .map((version) => version.openApiVersionName)
+  .map((version) => (version in versionMapping ? versionMapping[version] : version))
+  .join(', ')
+
+const log = console.log
+
+log(chalk.green.bold.underline('REST docs\n'))
+log(chalk.green.bold('  Examples of ways you can build the REST docs locally:\n'))
+log(chalk.cyan.bold('  - All versions:') + '  ' + chalk.magenta('npm run sync-rest ; npm run dev'))
+log(
+  chalk.cyan.bold('  - Dotcom only:') +
+    '   ' +
+    chalk.magenta('npm run sync-rest -- --version api.github.com ; npm run dev')
+)
+log(
+  chalk.cyan.bold('  - Two versions:') +
+    '  ' +
+    chalk.magenta('npm run sync-rest -- --version ghes-3.7 ghes-3.8 ; npm run dev')
+)
+log(
+  chalk.cyan.bold('  - Dotcom and next calendar date version:') +
+    ' ' +
+    chalk.magenta('npm run sync-rest -- --next --version api.github.com ; npm run dev')
+)
+log(chalk.green.bold.underline('\nWebhook docs\n'))
+log(chalk.green.bold('  Examples of ways you can build the Webhook docs locally:\n'))
+log(
+  chalk.cyan.bold('  - All versions:') + '  ' + chalk.magenta('npm run sync-webhooks ; npm run dev')
+)
+log(
+  chalk.cyan.bold('  - Dotcom only:') +
+    '   ' +
+    chalk.magenta('npm run sync-webhooks -- --version api.github.com ; npm run dev')
+)
+log(
+  chalk.cyan.bold('  - Two versions:') +
+    '  ' +
+    chalk.magenta('npm run sync-webhooks -- --version ghes-3.7 ghes-3.8 ; npm run dev')
+)
+log(chalk.green.bold('\nYou can build specific versions of the REST and Webhook docs.\n'))
+log(chalk.white.bold('  Versions that can be built: ', openApiVersions, '\n'))
+log(chalk.green.bold('\nThere are also additional options you can pass. For details run:\n'))
+log(chalk.white.bold('  npm run sync-rest -- --help'))
+log(chalk.white('  or'))
+log(chalk.white.bold('  npm run sync-webhooks -- --help'))
+log(chalk.green.bold('\nTo start the local development server run:\n'))
+log(chalk.white.bold('  npm run dev'))
+log('\n\n')