import { existsSync, mkdirSync } from 'fs' import { readFile, writeFile } from 'fs/promises' import path from 'path' import { slug } from 'github-slugger' import { allVersions } from '../../../../lib/all-versions.js' import { categoriesWithoutSubcategories, REST_DATA_DIR, REST_SCHEMA_FILENAME, } from '../../lib/index.js' import getOperations, { getWebhooks } from './get-operations.js' import { ENABLED_APPS_DIR, ENABLED_APPS_FILENAME } from '../../../github-apps/lib/index.js' import { WEBHOOK_DATA_DIR, WEBHOOK_SCHEMA_FILENAME } from '../../../webhooks/lib/index.js' const STATIC_REDIRECTS = 'lib/redirects/static/client-side-rest-api-redirects.json' const REST_DEREFERENCED_DIR = 'src/rest/data/dereferenced' // All of the schema releases that we store in allVersions // Ex: 'api.github.com', 'ghec', 'ghes-3.6', 'ghes-3.5', // 'ghes-3.4', 'ghes-3.3', 'ghes-3.2', 'github.ae' const OPENAPI_VERSION_NAMES = Object.keys(allVersions).map( (elem) => allVersions[elem].openApiVersionName ) export async function decorate(schemas) { console.log('\nš Decorating the OpenAPI schema files in src/rest/data/dereferenced.\n') const { restSchemas, webhookSchemas } = await getOpenApiSchemaFiles(schemas) const webhookOperations = await getWebhookOperations(webhookSchemas) await createStaticWebhookFiles(webhookOperations) const restOperations = await getRestOperations(restSchemas) await createStaticRestFiles(restOperations) await updateRestMetaData(restSchemas) } async function getRestOperations(restSchemas) { console.log('\nāļø Start generating static REST files\n') const restSchemaData = await getDereferencedFiles(restSchemas) const restOperations = {} for (const [schemaName, schema] of Object.entries(restSchemaData)) { try { // get all of the operations and wehbooks for a particular version of the openapi const operations = await getOperations(schema) // process each operation and webhook, asynchronously rendering markdown and stuff if (operations.length) { console.log(`...processing ${schemaName} rest operations`) await Promise.all(operations.map((operation) => operation.process())) restOperations[schemaName] = operations } } catch (error) { throw new Error( "š Whoops! It looks like the decorator script wasn't able to parse the dereferenced schema. A recent change may not yet be supported by the decorator. Please reach out in the #docs-engineering slack channel for help." ) } } return restOperations } async function getWebhookOperations(webhookSchemas) { console.log('āļø Start generating static webhook files\n') const webhookSchemaData = await getDereferencedFiles(webhookSchemas) const webhookOperations = {} for (const [schemaName, schema] of Object.entries(webhookSchemaData)) { try { const webhooks = await getWebhooks(schema) if (webhooks.length) { console.log(`...processing ${schemaName} webhook operations`) await Promise.all(webhooks.map((webhook) => webhook.process())) webhookOperations[schemaName] = webhooks } } catch (error) { throw new Error( "š Whoops! It looks like the decorator script wasn't able to parse the dereferenced schema. A recent change may not yet be supported by the decorator. Please reach out in the #docs-engineering slack channel for help." ) } } return webhookOperations } async function createStaticRestFiles(restOperations) { const clientSideRedirects = await getCategoryOverrideRedirects() for (const schemaName in restOperations) { const operations = restOperations[schemaName] await addRestClientSideRedirects(operations, clientSideRedirects) const categories = [...new Set(operations.map((operation) => operation.category))].sort() // Orders the operations by their category and subcategories. // All operations must have a category, but operations don't need // a subcategory. When no subcategory is present, the subcategory // property is an empty string (''). /* Example: { [category]: { '': { "description": "", "operations": [] }, [subcategory sorted alphabetically]: { "description": "", "operations": [] } } } */ const operationsByCategory = {} categories.forEach((category) => { operationsByCategory[category] = {} const categoryOperations = operations.filter((operation) => operation.category === category) categoryOperations .filter((operation) => !operation.subcategory) .map((operation) => (operation.subcategory = operation.category)) const subcategories = [ ...new Set(categoryOperations.map((operation) => operation.subcategory)), ].sort() // the first item should be the item that has no subcategory // e.g., when the subcategory = category const firstItemIndex = subcategories.indexOf(category) if (firstItemIndex > -1) { const firstItem = subcategories.splice(firstItemIndex, 1)[0] subcategories.unshift(firstItem) } subcategories.forEach((subcategory) => { operationsByCategory[category][subcategory] = {} const subcategoryOperations = categoryOperations.filter( (operation) => operation.subcategory === subcategory ) operationsByCategory[category][subcategory] = subcategoryOperations }) }) const restFilename = path .join(REST_DATA_DIR, schemaName, REST_SCHEMA_FILENAME) .replace('.deref', '') // write processed operations to disk await writeFile(restFilename, JSON.stringify(operationsByCategory, null, 2)) console.log('Wrote', path.relative(process.cwd(), restFilename)) // Create the src/github-apps/data files used for // https://docs.github.com/en/rest/overview/endpoints-available-for-github-apps const enabledAppsFilename = path.join(ENABLED_APPS_DIR, schemaName, ENABLED_APPS_FILENAME) const enabledAppsVersionDir = path.join(ENABLED_APPS_DIR, schemaName) const operationsEnabledForGitHubApps = {} for (const category of categories) { const categoryOperations = operations.filter((operation) => operation.category === category) // This is a collection of operations that have `enabledForGitHubApps = true` // It's grouped by resource title to make rendering easier operationsEnabledForGitHubApps[category] = categoryOperations .filter((operation) => operation.enabledForGitHubApps) .map((operation) => ({ slug: slug(operation.title), subcategory: operation.subcategory, verb: operation.verb, requestPath: operation.requestPath, })) } // When a new version is added, we need to create the directory for it if (!existsSync(enabledAppsVersionDir)) { mkdirSync(enabledAppsVersionDir) } await writeFile(enabledAppsFilename, JSON.stringify(operationsEnabledForGitHubApps, null, 2)) console.log('Wrote', enabledAppsFilename) } await writeFile(STATIC_REDIRECTS, JSON.stringify(clientSideRedirects, null, 2), 'utf8') console.log('Wrote', STATIC_REDIRECTS) } async function getDereferencedFiles(schemas) { const schemaData = {} for (const filename of schemas) { const file = path.join(REST_DEREFERENCED_DIR, `${filename}.deref.json`) const schema = JSON.parse(await readFile(file)) schemaData[filename] = schema } return schemaData } async function createStaticWebhookFiles(webhookSchemas) { if (!Object.keys(webhookSchemas).length) { console.log( 'š” No webhooks exist in the dereferenced files. No static webhook files will be generated.\n' ) return } // Create a map of webhooks (e.g. check_run, issues, release) to the // webhook's actions (e.g. created, deleted, etc.). // // Some webhooks like the ping webhook have no action types -- in cases // like this we set a default action of 'default'. // // Example: /* { 'branch-protection-rule': { created: Webhook { descriptionHtml: '
A branch protection rule was created.
', summaryHtml: 'This event occurs when there is activity relating to branch protection rules. For more information, see "About protected branches." For information about the Branch protection APIs, see the GraphQL documentation and the REST API documentation.
\n' + 'In order to install this event on a GitHub App, the app must have read-only access on repositories administration.
A branch protection rule was deleted.
', summaryHtml: 'This event occurs when there is activity relating to branch protection rules. For more information, see "About protected branches." For information about the Branch protection APIs, see the GraphQL documentation and the REST API documentation.
\n' + 'In order to install this event on a GitHub App, the app must have read-only access on repositories administration.