repo sync

Author: Octomerger

javascripts/explorer.js

@@ -1,5 +1,15 @@
+const explorerUrl = location.hostname === 'localhost'
+  ? 'http://localhost:3000'
+  : 'https://graphql.github.com/explorer'
 
+// Pass non-search query params to Explorer app via the iFrame
 export default function () {
-  // TODO support "Run in Explorer" links in GraphQL guides
-  // will need to handle query params separately from search queries
+  const graphiqlExplorer = document.getElementById('graphiql')
+  const queryString = window.location.search
+
+  if (!(queryString && graphiqlExplorer)) return
+
+  window.onload = () => {
+    graphiqlExplorer.contentWindow.postMessage(queryString, explorerUrl)
+  }
 }

javascripts/search.js

@@ -7,12 +7,17 @@ let $searchResultsContainer
 let $searchOverlay
 let $searchInput
 
+let isExplorerPage
+
 // This is our default placeholder, but it can be localized with a <meta> tag
 let placeholder = 'Search topics, products...'
 let version
 let language
 
 export default function search () {
+  // We don't want to mess with query params intended for the GraphQL Explorer
+  isExplorerPage = Boolean(document.getElementById('graphiql'))
+
   // First, only initialize search if the elements are on the page
   $searchInputContainer = document.getElementById('search-input-container')
   $searchResultsContainer = document.getElementById('search-results-container')
@@ -51,7 +56,9 @@ export default function search () {
   searchWithYourKeyboard('#search-input-container input', '.ais-Hits-item')
 
   // If the user already has a query in the URL, parse it and search away
-  parseExistingSearch()
+  if (!isExplorerPage) {
+    parseExistingSearch()
+  }
 
   // If not on home page, decide if search panel should be open
   toggleSearchDisplay() // must come after parseExistingSearch
@@ -133,8 +140,9 @@ async function onSearch () {
   const query = $searchInput.value
 
   // Update the URL with the search parameters in the query string
+  // UNLESS this is the GraphQL Explorer page, where a query in the URL is a GraphQL query
   const pushUrl = new URL(location)
-  pushUrl.search = query ? new URLSearchParams({ query }) : ''
+  pushUrl.search = query && !isExplorerPage ? new URLSearchParams({ query }) : ''
   history.pushState({}, '', pushUrl)
 
   // If there's a query, call the endpoint

lib/get-document-type.js

@@ -0,0 +1,17 @@
+module.exports = function getDocumentType (relativePath) {
+  if (!relativePath.endsWith('index.md')) {
+    return 'article'
+  }
+
+  // Derive the document type from the path segment length
+  switch (relativePath.split('/').length) {
+    case 1:
+      return 'homepage'
+    case 2:
+      return 'product'
+    case 3:
+      return 'category'
+    case 4:
+      return 'mapTopic'
+  }
+}

script/content-migrations/remove-map-topics.js

@@ -3,23 +3,31 @@
 const fs = require('fs')
 const path = require('path')
 const walk = require('walk-sync')
+const languages = require('../../lib/languages')
+const frontmatter = require('../../lib/read-frontmatter')
+const addRedirectToFrontmatter = require('../../lib/redirects/add-redirect-to-frontmatter')
 
 const relativeRefRegex = /\/[a-zA-Z0-9-]+/g
 const linkString = /{% [^}]*?link.*? \/(.*?) ?%}/m
 const linksArray = new RegExp(linkString.source, 'gm')
 
-const fullDirectoryPath = path.join(process.cwd(), '/content')
-const files = walk(fullDirectoryPath, {
+const walkOpts = {
   includeBasePath: true,
   directories: false
-})
+}
+
+// We only want category TOC files, not product TOCs.
+const categoryFileRegex = /content\/[^/]+?\/[^/]+?\/index.md/
 
-files.forEach(file => {
-  if (path.basename(file) !== 'index.md') return
+const fullDirectoryPaths = Object.values(languages).map(langObj => path.join(process.cwd(), langObj.dir, 'content'))
+const categoryIndexFiles = fullDirectoryPaths.map(fullDirectoryPath => walk(fullDirectoryPath, walkOpts)).flat()
+  .filter(file => categoryFileRegex.test(file))
+
+categoryIndexFiles.forEach(categoryIndexFile => {
+  let categoryIndexContent = fs.readFileSync(categoryIndexFile, 'utf8')
 
-  let fileContent = fs.readFileSync(file, 'utf-8')
   // find array of TOC link strings
-  const rawItems = fileContent.match(linksArray)
+  const rawItems = categoryIndexContent.match(linksArray)
   if (!rawItems || !rawItems[0].includes('topic_link_in_list')) return
 
   const pageToc = {}
@@ -37,24 +45,53 @@ files.forEach(file => {
       pageToc[currentTopic] = tmpArray
     }
   })
+
   for (const topic in pageToc) {
-    const oldTopicDirectory = path.dirname(file)
+    const oldTopicDirectory = path.dirname(categoryIndexFile)
     const newTopicDirectory = path.join(oldTopicDirectory, topic)
-    const topicFile = path.join(oldTopicDirectory, `${topic}.md`)
+    const oldTopicFile = path.join(oldTopicDirectory, `${topic}.md`)
+
+    // Some translated category TOCs may be outdated and contain incorrect links
+    if (!fs.existsSync(oldTopicFile)) continue
 
     if (!fs.existsSync(newTopicDirectory)) fs.mkdirSync(newTopicDirectory)
 
-    let topicContent = fs.readFileSync(topicFile, 'utf-8')
-    topicContent = topicContent.replace('mapTopic: true\n', '')
+    const { data, content } = frontmatter(fs.readFileSync(oldTopicFile, 'utf8'))
+    delete data.mapTopic
+
+    let topicContent = content
 
     const articles = pageToc[topic]
 
     articles.forEach(article => {
-      fs.renameSync(`${oldTopicDirectory}/${article}.md`, `${newTopicDirectory}/${article}.md`)
+      // Update the new map topic index file content
       topicContent = topicContent + `{% link_with_intro /${article} %}\n`
-      fileContent = fileContent.replace(`/{% link_in_list /${article}`, `/{% link_in_list /${newTopicDirectory}/${article}`)
+
+      // Update the category index file content
+      categoryIndexContent = categoryIndexContent.replace(`{% link_in_list /${article}`, `{% link_in_list /${topic}/${article}`)
+
+      // Early return if the article doesn't exist (some translated category TOCs may be outdated and contain incorrect links)
+      if (!fs.existsSync(`${oldTopicDirectory}/${article}.md`)) return
+
+      // Move the file under the new map topic directory
+      const newArticlePath = `${newTopicDirectory}/${article}.md`
+      fs.renameSync(`${oldTopicDirectory}/${article}.md`, newArticlePath)
+
+      // Read the article file so we can add a redirect from its old path
+      const articleContents = frontmatter(fs.readFileSync(newArticlePath, 'utf8'))
+      addRedirectToFrontmatter(articleContents.data.redirect_from, `${oldTopicDirectory}/${article}`)
+
+      // Write the article with updated frontmatter
+      fs.writeFileSync(newArticlePath, frontmatter.stringify(articleContents.content.trim(), articleContents.data, { lineWidth: 10000 }))
     })
-    fs.writeFileSync(`${newTopicDirectory}/index.md`, topicContent)
-    fs.unlinkSync(topicFile)
+
+    // Write the map topic index file
+    fs.writeFileSync(`${newTopicDirectory}/index.md`, frontmatter.stringify(topicContent.trim(), data, { lineWidth: 10000 }))
+
+    // Write the category index file
+    fs.writeFileSync(categoryIndexFile, categoryIndexContent)
+
+    // Delete the old map topic
+    fs.unlinkSync(oldTopicFile)
   }
 })

script/content-migrations/update-tocs.js

@@ -0,0 +1,75 @@
+#!/usr/bin/env node
+
+const fs = require('fs')
+const path = require('path')
+const walk = require('walk-sync')
+const yaml = require('js-yaml')
+const frontmatter = require('../../lib/read-frontmatter')
+const getDocumentType = require('../../lib/get-document-type')
+const languages = require('../../lib/languages')
+
+const linkString = /{% [^}]*?link.*? (\/.*?) ?%}/m
+const linksArray = new RegExp(linkString.source, 'gm')
+
+// The product order is determined by data/products.yml
+const productsFile = path.join(process.cwd(), 'data/products.yml')
+const productsYml = yaml.load(fs.readFileSync(productsFile, 'utf8'))
+const sortedProductIds = productsYml.productsInOrder.concat('early-access')
+
+// This script turns `{% link /<link> %} style content into children: [ -/<link> ] frontmatter arrays.
+//
+// It MUST be run after script/content-migrations/remove-map-topics.js.
+//
+// NOTE: The results won't work with the TOC handling currently in production, so the results must NOT
+// be committed until the updated handling is in place.
+
+const walkOpts = {
+  includeBasePath: true,
+  directories: false
+}
+
+const fullDirectoryPaths = Object.values(languages).map(langObj => path.join(process.cwd(), langObj.dir, 'content'))
+const indexFiles = fullDirectoryPaths.map(fullDirectoryPath => walk(fullDirectoryPath, walkOpts)).flat()
+  .filter(file => file.endsWith('index.md'))
+
+indexFiles
+  .forEach(indexFile => {
+    const relativePath = indexFile.replace(/^.+\/content\//, '')
+    const documentType = getDocumentType(relativePath)
+
+    const { data, content } = frontmatter(fs.readFileSync(indexFile, 'utf8'))
+
+    if (documentType === 'homepage') {
+      data.children = sortedProductIds
+    }
+
+    const linkItems = content.match(linksArray) || []
+
+    // Turn the `{% link /<link> %}` list into an array of /<link> items
+    if (documentType === 'product' || documentType === 'mapTopic') {
+      data.children = getLinks(linkItems)
+    }
+
+    if (documentType === 'category') {
+      const childMapTopics = linkItems.filter(item => item.includes('topic_'))
+
+      data.children = childMapTopics.length ? getLinks(childMapTopics) : getLinks(linkItems)
+    }
+
+    // Fix this one weird file
+    if (relativePath === 'discussions/guides/index.md') {
+      data.children = [
+        '/best-practices-for-community-conversations-on-github',
+        '/finding-discussions-across-multiple-repositories',
+        '/granting-higher-permissions-to-top-contributors'
+      ]
+    }
+
+    // Index files should no longer have body content, so we write an empty string
+    fs.writeFileSync(indexFile, frontmatter.stringify('', data, { lineWidth: 10000 }))
+  })
+
+function getLinks (linkItemArray) {
+  // do a oneoff replacement while mapping
+  return linkItemArray.map(item => item.match(linkString)[1].replace('/discussions-guides', '/guides'))
+}

script/enterprise-server-releases/create-graphql-files.js

@@ -55,10 +55,15 @@ const objectsFile = path.join(graphqlStaticDir, 'prerendered-objects.json')
 const previews = require(previewsFile)
 const changes = require(changesFile)
 const objects = require(objectsFile)
+// The prerendered objects file for the "old version" contains hardcoded links with the old version number.
+// We need to update those links to include the new version to prevent a test from failing.
+const regexOldVersion = new RegExp(oldVersion, 'gi')
+const stringifiedObject = JSON.stringify(objects[oldVersionId])
+  .replace(regexOldVersion, newVersion)
 
 previews[newVersionId] = previews[oldVersionId]
 changes[newVersionId] = changes[oldVersionId]
-objects[newVersionId] = objects[oldVersionId]
+objects[newVersionId] = JSON.parse(stringifiedObject)
 
 // check that it worked
 if (!Object.keys(previews).includes(newVersionId)) {

script/enterprise-server-releases/create-rest-files.js

@@ -4,12 +4,15 @@ const fs = require('fs')
 const path = require('path')
 const program = require('commander')
 const allVersions = require('../../lib/all-versions')
+const getOperations = require('../rest/utils/get-operations')
 const dereferencedDir = 'lib/rest/static/dereferenced'
 const decoratedDir = 'lib/rest/static/decorated'
 
 // [start-readme]
 //
-// This script creates new static openAPI files for a new version and modifies the info.version.
+// This script first copies the dereferenced schema from the previous GHES version for the new one.
+// It then replaces references to the previous version's docs URL (e.g., enterprise-server@3.0) with the new version (e.g., enterprise-server@3.1).
+// Finally, it generates a new decorated file from the new dereferenced file to ensure that the dereferenced and decorated files match.
 //
 // [end-readme]
 
@@ -32,48 +35,43 @@ if (!(Object.keys(allVersions).includes(newVersion) && Object.keys(allVersions).
   process.exit(1)
 }
 
-const oldDereferencedFilename = `${allVersions[oldVersion].openApiVersionName}.deref.json`
-const newDereferencedFilename = `${allVersions[newVersion].openApiVersionName}.deref.json`
-const oldDecoratedFilename = `${allVersions[oldVersion].openApiVersionName}.json`
-const newDecoratedFilename = `${allVersions[newVersion].openApiVersionName}.json`
+main()
 
-const oldDereferencedFile = path.join(dereferencedDir, oldDereferencedFilename)
-const newDereferencedFile = path.join(dereferencedDir, newDereferencedFilename)
-const oldDecoratedFile = path.join(decoratedDir, oldDecoratedFilename)
-const newDecoratedFile = path.join(decoratedDir, newDecoratedFilename)
+async function main () {
+  const oldDereferencedFilename = `${allVersions[oldVersion].openApiVersionName}.deref.json`
+  const newDereferencedFilename = `${allVersions[newVersion].openApiVersionName}.deref.json`
+  const newDecoratedFilename = `${allVersions[newVersion].openApiVersionName}.json`
 
-// check that the old files exist
-if (!fs.existsSync(oldDereferencedFile)) {
-  console.log(`Error! Can't find ${oldDereferencedFile} for ${oldVersion}.`)
-  process.exit(1)
-}
+  const oldDereferencedFile = path.join(dereferencedDir, oldDereferencedFilename)
+  const newDereferencedFile = path.join(dereferencedDir, newDereferencedFilename)
+  const newDecoratedFile = path.join(decoratedDir, newDecoratedFilename)
 
-if (!fs.existsSync(oldDecoratedFile)) {
-  console.log(`Error! Can't find ${oldDecoratedFile} for ${oldVersion}.`)
-  process.exit(1)
-}
+  // check that the old files exist
+  if (!fs.existsSync(oldDereferencedFile)) {
+    console.log(`Error! Can't find ${oldDereferencedFile} for ${oldVersion}.`)
+    process.exit(1)
+  }
 
-// copy the files
-fs.copyFileSync(oldDereferencedFile, newDereferencedFile)
-fs.copyFileSync(oldDecoratedFile, newDecoratedFile)
+  const oldDereferencedContent = fs.readFileSync(oldDereferencedFile, 'utf8')
 
-// check that it worked
-if (!fs.existsSync(newDereferencedFile)) {
-  console.log(`Error! Can't find ${newDereferencedFile} for ${oldVersion}.`)
-  process.exit(1)
-}
+  // Replace old version with new version
+  // (ex: enterprise-server@3.0 -> enterprise-server@3.1)
+  const regexOldVersion = new RegExp(oldVersion, 'gi')
+  const newDereferenceContent = oldDereferencedContent.replace(regexOldVersion, newVersion)
 
-if (!fs.existsSync(newDecoratedFile)) {
-  console.log(`Error! Can't find ${newDecoratedFile} for ${oldVersion}.`)
-  process.exit(1)
-}
+  // Write processed dereferenced schema to disk
+  fs.writeFileSync(newDereferencedFile, newDereferenceContent)
+  console.log(`Created ${newDereferencedFile}.`)
+
+  const dereferencedSchema = require(path.join(process.cwd(), newDereferencedFile))
 
-// set the info.version to development mode
-const derefFilepath = path.join(process.cwd(), newDereferencedFile)
-const derefSchema = require(derefFilepath)
-console.log(derefSchema.info.version)
-derefSchema.info.version = `Copy of ${oldVersion} !!DEVELOPMENT MODE - DO NOT MERGE!!`
-fs.writeFileSync(derefFilepath, JSON.stringify(derefSchema, null, 2))
+  // Store all operations in an array of operation objects
+  const operations = await getOperations(dereferencedSchema)
 
-// print success message
-console.log(`Done! Created ${newDereferencedFile} and ${newDecoratedFile}.`)
+  // Process each operation asynchronously
+  await Promise.all(operations.map(operation => operation.process()))
+
+  // Write processed operations to disk
+  fs.writeFileSync(newDecoratedFile, JSON.stringify(operations, null, 2))
+  console.log(`Done! Created ${newDecoratedFile}.`)
+}

tests/browser/browser.js

@@ -281,3 +281,30 @@ describe('language banner', () => {
     }
   })
 })
+
+// The Explorer in the iFrame will not be accessible on localhost, but we can still
+// test the query param handling
+describe('GraphQL Explorer', () => {
+  it('preserves query strings on the Explorer page without opening search', async () => {
+    const queryString = `query {
+  viewer {
+    foo
+  }
+}`
+    // Encoded as: query%20%7B%0A%20%20viewer%20%7B%0A%20%20%20%20foo%0A%20%20%7D%0A%7D
+    const encodedString = encodeURIComponent(queryString)
+    const explorerUrl = 'http://localhost:4001/en/graphql/overview/explorer'
+
+    await page.goto(`${explorerUrl}?query=${encodedString}`)
+
+    // On non-Explorer pages, query params handled by search JS get form-encoded using `+` instead of `%20`.
+    // So on these pages, the following test will be false; but on the Explorer page, it should be true.
+    expect(page.url().endsWith(encodedString)).toBe(true)
+
+    // On non-Explorer pages, query params handled by search JS will populate in the search box and the `js-open`
+    // class is added. On these pages, the following test will NOT be null; but on the Explorer page, it should be null.
+    await page.waitForSelector('#search-results-container')
+    const searchResult = await page.$('#search-results-container.js-open')
+    expect(searchResult).toBeNull()
+  })
+})