fix: multiple routes in get a git reference section

lib/endpoint/get.js

@@ -1,5 +1,7 @@
 module.exports = getEndpoint
 
+const existsSync = require('fs').existsSync
+const {join: joinPath, relative: relativePath} = require('path')
 const parseUrl = require('url').parse
 
 const cheerio = require('cheerio')
@@ -11,6 +13,7 @@ const htmlToJson = require('./html-to-json')
 async function getEndpoint (url) {
   const [pageUrl, id] = url.split('#')
   const {path: pagePath} = parseUrl(url)
+  const pageOverridePath = joinPath(__dirname, 'overrides', `${pagePath}${id}.json`)
   const pageEndpointPath = `${pagePath}${id}.html`
   let endpointHtml
 
@@ -27,6 +30,16 @@ async function getEndpoint (url) {
       .get()
       .join('\n')
 
+    // add override to cached HTML page so we can review changes and update
+    // the override if necessary
+    if (existsSync(pageOverridePath)) {
+      endpointHtml = `<!--
+  custom override at ${relativePath(process.cwd(), pageOverridePath)}
+  Make sure to review it on updates to this endpoint’s documentation
+-->
+
+${endpointHtml}`
+    }
     cache.writeHtml(pageEndpointPath, endpointHtml)
   }
 

lib/endpoint/html-to-json.js

@@ -1,5 +1,8 @@
 module.exports = htmlToJson
 
+const readFileSync = require('fs').readFileSync
+const joinPath = require('path').join
+
 const _ = require('lodash')
 const cheerio = require('cheerio')
 const markdownTable = require('markdown-table')
@@ -8,6 +11,14 @@ const elementToBlock = require('./element-to-block')
 const htmlContainsEndpoint = require('./html-contains-endpoint')
 
 function htmlToJson (html) {
+  const override = findOverride(html)
+  if (override) {
+    override.forEach(endpoint => {
+      endpoint.isOverride = true
+    })
+    return override
+  }
+
   if (!htmlContainsEndpoint(html)) {
     return
   }
@@ -47,6 +58,15 @@ function htmlToJson (html) {
   return state.results
 }
 
+function findOverride (html) {
+  if (!html.startsWith('<!--')) {
+    return
+  }
+
+  const overridePath = html.match(/custom override at (.*)/).pop()
+  return JSON.parse(readFileSync(joinPath(process.cwd(), overridePath), 'utf8'))
+}
+
 /**
  *
  */
@@ -61,7 +81,19 @@ function findRoutes (state) {
     result.method = method
     result.path = path
     state.blocks.splice(state.blocks.indexOf(routeBlock), 1)
-  } else {
+    return
+  }
+
+  const hasAuthenticatedUserRoute = !!routeBlocks.slice(1).find(block => {
+    const prevBlock = state.blocks[state.blocks.indexOf(block) - 1]
+    return prevBlock.type === 'description' && /^\/user\//.test(block.path)
+  })
+  const hasExampleRoutes = !!routeBlocks.slice(1).find(block => {
+    const prevBlock = state.blocks[state.blocks.indexOf(block) - 1]
+    return prevBlock.type === 'description' && /\bexample\b/i.test(prevBlock.text)
+  })
+
+  if (hasAuthenticatedUserRoute) {
     state.results = routeBlocks.map((routeBlock) => {
       const routeResult = _.merge({
         method: routeBlock.method,
@@ -79,6 +111,18 @@ function findRoutes (state) {
 
       return routeResult
     })
+
+    return
+  }
+
+  if (hasExampleRoutes) {
+    routeBlocks.slice(1).forEach(block => {
+      block.type = 'description'
+      block.text = '```\n' + [block.method, block.path].join(' ') + '\n```'
+
+      delete block.method
+      delete block.path
+    })
   }
 }
 

lib/endpoint/overrides/v3/git/refs/get-a-reference.json

@@ -0,0 +1,17 @@
+[
+  {
+    "name": "Get a Reference",
+    "enabledForApps": true,
+    "method": "GET",
+    "path": "/repos/:owner/:repo/git/refs/:ref",
+    "description": "Returns a branch or tag reference. Other than the [REST API](https://developer.github.com/v3/git/refs/#get-a-reference) it always returns a single reference. If the REST API returns with an array then the method responds with an error.",
+    "params": [
+      {
+        "name": "ref",
+        "type": "string",
+        "description": "Must be formatted as `heads/branch`, not just `branch`",
+        "required": true
+      }
+    ]
+  }
+]