From bdef136c17b2e96e6e086e9ff16e4f45c8986b05 Mon Sep 17 00:00:00 2001
From: Dustin Schau <dustinschau@gmail.com>
Date: Wed, 24 Jul 2019 10:03:07 -0700
Subject: [PATCH 1/5] feat(gatsby): output apis.json for current valid API list

---
 packages/gatsby/apis.json                  |  58 +++++++++
 packages/gatsby/package.json               |   3 +
 packages/gatsby/scripts/output-api-file.js |  47 +++++++
 packages/gatsby/src/utils/api-node-docs.js |   2 +
 yarn.lock                                  | 137 ++++++++++++++++++++-
 5 files changed, 245 insertions(+), 2 deletions(-)
 create mode 100644 packages/gatsby/apis.json
 create mode 100644 packages/gatsby/scripts/output-api-file.js

diff --git a/packages/gatsby/apis.json b/packages/gatsby/apis.json
new file mode 100644
index 0000000000000..8486914e71f27
--- /dev/null
+++ b/packages/gatsby/apis.json
@@ -0,0 +1,58 @@
+{
+  "ssr": {
+    "replaceRenderer": {},
+    "onRenderBody": {},
+    "onPreRenderHTML": {},
+    "wrapPageElement": {},
+    "wrapRootElement": {}
+  },
+  "browser": {
+    "onClientEntry": {},
+    "onInitialClientRender": {},
+    "onPreRouteUpdate": {},
+    "onRouteUpdateDelayed": {},
+    "onRouteUpdate": {},
+    "shouldUpdateScroll": {},
+    "registerServiceWorker": {},
+    "replaceComponentRenderer": {
+      "deprecated": true
+    },
+    "wrapPageElement": {},
+    "wrapRootElement": {},
+    "onPrefetchPathname": {},
+    "onPostPrefetchPathname": {},
+    "disableCorePrefetching": {},
+    "replaceHydrateFunction": {},
+    "onServiceWorkerInstalled": {},
+    "onServiceWorkerUpdateFound": {},
+    "onServiceWorkerUpdateReady": {},
+    "onServiceWorkerActive": {},
+    "onServiceWorkerRedundant": {}
+  },
+  "node": {
+    "resolvableExtensions": {},
+    "createPages": {},
+    "createPagesStatefully": {},
+    "sourceNodes": {},
+    "onCreateNode": {},
+    "onCreatePage": {},
+    "setFieldsOnGraphQLNodeType": {},
+    "createSchemaCustomization": {
+      "version": "2.12.0"
+    },
+    "createResolvers": {
+      "version": "2.2.0"
+    },
+    "preprocessSource": {},
+    "generateSideEffects": {},
+    "onCreateBabelConfig": {},
+    "onCreateWebpackConfig": {},
+    "onPreInit": {},
+    "onPreBootstrap": {},
+    "onPostBootstrap": {},
+    "onPreBuild": {},
+    "onPostBuild": {},
+    "onPreExtractQueries": {},
+    "onCreateDevServer": {}
+  }
+}
\ No newline at end of file
diff --git a/packages/gatsby/package.json b/packages/gatsby/package.json
index 8728c6837764d..ccb48561cadf6 100644
--- a/packages/gatsby/package.json
+++ b/packages/gatsby/package.json
@@ -142,6 +142,7 @@
     "@babel/runtime": "^7.0.0",
     "babel-preset-gatsby-package": "^0.2.2",
     "cross-env": "^5.1.4",
+    "documentation": "^12.0.3",
     "react": "^16.4.2",
     "react-dom": "^16.4.2",
     "rimraf": "^2.6.1",
@@ -151,6 +152,7 @@
     "node": ">=8.0.0"
   },
   "files": [
+    "apis.json",
     "cache-dir",
     "dist",
     "graphql.js",
@@ -183,6 +185,7 @@
   },
   "scripts": {
     "build": "npm run build:src && npm run build:internal-plugins && npm run build:rawfiles && npm run build:cjs",
+    "postbuild": "node scripts/output-api-file.js",
     "build:internal-plugins": "copyfiles -u 1 src/internal-plugins/**/package.json dist",
     "build:rawfiles": "copyfiles -u 1 src/internal-plugins/**/raw_* dist",
     "build:cjs": "babel cache-dir --out-dir cache-dir/commonjs --ignore **/__tests__",
diff --git a/packages/gatsby/scripts/output-api-file.js b/packages/gatsby/scripts/output-api-file.js
new file mode 100644
index 0000000000000..db6ed78ae8d2c
--- /dev/null
+++ b/packages/gatsby/scripts/output-api-file.js
@@ -0,0 +1,47 @@
+const path = require('path')
+const documentation = require('documentation')
+const fs = require('fs-extra')
+
+const OUTPUT_FILE_NAME = `apis.json`
+
+async function outputFile() {
+  const apis = await Promise.all([
+    path.join('cache-dir', 'api-ssr-docs.js'),
+    path.join('src', 'utils', 'api-browser-docs.js'),
+    path.join('src', 'utils', 'api-node-docs.js')
+  ]
+    .map(filePath => {
+      const resolved = path.resolve(filePath)
+      const [,api] = path.basename(filePath).split('-')
+      return documentation.build(resolved, {
+        shallow: true
+      })
+        .then(contents => {
+          return [
+            contents,
+            api
+          ]
+        })
+    })
+  )
+
+  const output = apis.reduce((merged, [output, api]) => {
+    merged[api] = output.reduce((mergedOutput, doc) => {
+      if (doc.namespace.startsWith('.')) {
+        const tags = doc.tags.reduce((mergedTags, tag) => {
+          mergedTags[tag.title] = tag.description
+          return mergedTags
+        }, {})
+        mergedOutput[doc.name] = Object.assign({
+          version: tags.gatsbyVersion
+        }, !!tags.deprecated && { deprecated: true })
+      }
+      return mergedOutput
+    }, {})
+    return merged
+  }, {})
+
+  return fs.writeFile(path.resolve(OUTPUT_FILE_NAME), JSON.stringify(output, null, 2), 'utf8')
+}
+
+outputFile()
diff --git a/packages/gatsby/src/utils/api-node-docs.js b/packages/gatsby/src/utils/api-node-docs.js
index 020e7d51d1f5b..9553f5636722d 100644
--- a/packages/gatsby/src/utils/api-node-docs.js
+++ b/packages/gatsby/src/utils/api-node-docs.js
@@ -209,6 +209,7 @@ exports.setFieldsOnGraphQLNodeType = true
  * generated schema, e.g. to customize added third-party types, use the
  * [`createResolvers`](/docs/node-apis/#createResolvers) API.
  *
+ * @gatsbyVersion 2.12.0
  * @param {object} $0
  * @param {object} $0.actions
  * @param {object} $0.actions.createTypes
@@ -278,6 +279,7 @@ exports.createSchemaCustomization = true
  *
  * For fuller examples, see [`using-type-definitions`](https://github.com/gatsbyjs/gatsby/tree/master/examples/using-type-definitions).
  *
+ * @gatsbyVersion 2.2.0
  * @param {object} $0
  * @param {GraphQLSchema} $0.intermediateSchema Current GraphQL schema
  * @param {function} $0.createResolvers Add custom resolvers to GraphQL field configs
diff --git a/yarn.lock b/yarn.lock
index 6a74fb0bcced0..ee1c9286b05b7 100644
--- a/yarn.lock
+++ b/yarn.lock
@@ -3073,7 +3073,7 @@
   version "0.0.32"
   resolved "https://registry.yarnpkg.com/@types/tmp/-/tmp-0.0.32.tgz#0d3cb31022f8427ea58c008af32b80da126ca4e3"
 
-"@types/unist@*", "@types/unist@^2.0.0":
+"@types/unist@*", "@types/unist@^2.0.0", "@types/unist@^2.0.2":
   version "2.0.3"
   resolved "https://registry.yarnpkg.com/@types/unist/-/unist-2.0.3.tgz#9c088679876f374eb5983f150d4787aa6fb32d7e"
 
@@ -7665,6 +7665,11 @@ diff@^3.2.0:
   version "3.5.0"
   resolved "https://registry.yarnpkg.com/diff/-/diff-3.5.0.tgz#800c0dd1e0a8bfbc95835c202ad220fe317e5a12"
 
+diff@^4.0.1:
+  version "4.0.1"
+  resolved "https://registry.yarnpkg.com/diff/-/diff-4.0.1.tgz#0c667cb467ebbb5cea7f14f135cc2dba7780a8ff"
+  integrity sha512-s2+XdvhPCOF01LRQBC8hf4vhbVmI2CGS5aZnxLJlT5FtdhPCDFq80q++zK2KlrVorVDdL5BOGZ/VfLrVtYNF+Q==
+
 diffie-hellman@^5.0.0:
   version "5.0.3"
   resolved "http://registry.npmjs.org/diffie-hellman/-/diffie-hellman-5.0.3.tgz#40e8ee98f55a2149607146921c63e1ae5f3d2875"
@@ -7814,6 +7819,77 @@ documentation@^10.1.0:
     vue-template-compiler "^2.5.16"
     yargs "^12.0.2"
 
+documentation@^12.0.3:
+  version "12.0.3"
+  resolved "https://registry.yarnpkg.com/documentation/-/documentation-12.0.3.tgz#32f91da8e5cb4104f69db9fd32c87773a1ad6240"
+  integrity sha512-RoqkH+mQ4Vi/nFMxG0BaqPAnjKfsJ9lbLWB8KqoKVAZy+urSpk1K1zBzaFesdDkKeaR3aBgeR3RjtHp8Ut/1Wg==
+  dependencies:
+    "@babel/core" "^7.1.2"
+    "@babel/generator" "^7.1.3"
+    "@babel/parser" "7.1.3"
+    "@babel/plugin-proposal-class-properties" "^7.1.0"
+    "@babel/plugin-proposal-decorators" "^7.1.2"
+    "@babel/plugin-proposal-do-expressions" "^7.0.0"
+    "@babel/plugin-proposal-export-default-from" "^7.0.0"
+    "@babel/plugin-proposal-export-namespace-from" "^7.0.0"
+    "@babel/plugin-proposal-function-bind" "^7.0.0"
+    "@babel/plugin-proposal-function-sent" "^7.1.0"
+    "@babel/plugin-proposal-json-strings" "^7.0.0"
+    "@babel/plugin-proposal-logical-assignment-operators" "^7.0.0"
+    "@babel/plugin-proposal-nullish-coalescing-operator" "^7.0.0"
+    "@babel/plugin-proposal-numeric-separator" "^7.0.0"
+    "@babel/plugin-proposal-optional-chaining" "^7.0.0"
+    "@babel/plugin-proposal-pipeline-operator" "^7.0.0"
+    "@babel/plugin-proposal-throw-expressions" "^7.0.0"
+    "@babel/plugin-syntax-dynamic-import" "^7.0.0"
+    "@babel/plugin-syntax-import-meta" "^7.0.0"
+    "@babel/preset-env" "^7.1.0"
+    "@babel/preset-flow" "^7.0.0"
+    "@babel/preset-react" "^7.0.0"
+    "@babel/preset-stage-0" "^7.0.0"
+    "@babel/traverse" "^7.1.4"
+    "@babel/types" "^7.1.3"
+    ansi-html "^0.0.7"
+    babelify "^10.0.0"
+    chalk "^2.3.0"
+    chokidar "^2.0.4"
+    concat-stream "^1.6.0"
+    diff "^4.0.1"
+    doctrine-temporary-fork "2.1.0"
+    get-port "^4.0.0"
+    git-url-parse "^10.0.1"
+    github-slugger "1.2.0"
+    glob "^7.1.2"
+    globals-docs "^2.4.0"
+    highlight.js "^9.15.5"
+    js-yaml "^3.10.0"
+    lodash "^4.17.10"
+    mdast-util-inject "^1.1.0"
+    micromatch "^3.1.5"
+    mime "^2.2.0"
+    module-deps-sortable "5.0.0"
+    parse-filepath "^1.0.2"
+    pify "^4.0.0"
+    read-pkg-up "^4.0.0"
+    remark "^9.0.0"
+    remark-html "^8.0.0"
+    remark-reference-links "^4.0.1"
+    remark-toc "^5.0.0"
+    remote-origin-url "0.4.0"
+    resolve "^1.8.1"
+    stream-array "^1.1.2"
+    strip-json-comments "^2.0.1"
+    tiny-lr "^1.1.0"
+    unist-builder "^1.0.2"
+    unist-util-visit "^1.3.0"
+    vfile "^4.0.0"
+    vfile-reporter "^6.0.0"
+    vfile-sort "^2.1.0"
+    vinyl "^2.1.0"
+    vinyl-fs "^3.0.2"
+    vue-template-compiler "^2.5.16"
+    yargs "^12.0.2"
+
 dom-converter@~0.1:
   version "0.1.4"
   resolved "http://registry.npmjs.org/dom-converter/-/dom-converter-0.1.4.tgz#a45ef5727b890c9bffe6d7c876e7b19cb0e17f3b"
@@ -8048,6 +8124,11 @@ emoji-regex@^7.0.1, emoji-regex@^7.0.2:
   version "7.0.3"
   resolved "https://registry.yarnpkg.com/emoji-regex/-/emoji-regex-7.0.3.tgz#933a04052860c85e83c122479c4748a8e4c72156"
 
+emoji-regex@^8.0.0:
+  version "8.0.0"
+  resolved "https://registry.yarnpkg.com/emoji-regex/-/emoji-regex-8.0.0.tgz#e818fd69ce5ccfcb404594f842963bf53164cc37"
+  integrity sha512-MSjYzcWNOA0ewAHpz0MxpYFvwg6yjy1NG3xteoqz644VCo/RPgnr1/GGt+ic3iJTzQ8Eu3TdM14SawnVUmGE6A==
+
 emojis-list@^2.0.0:
   version "2.1.0"
   resolved "https://registry.yarnpkg.com/emojis-list/-/emojis-list-2.1.0.tgz#4daa4d9db00f9819880c79fa457ae5b09a1fd389"
@@ -11526,6 +11607,11 @@ is-fullwidth-code-point@^2.0.0:
   version "2.0.0"
   resolved "https://registry.yarnpkg.com/is-fullwidth-code-point/-/is-fullwidth-code-point-2.0.0.tgz#a3b30a5c4f199183167aaab93beefae3ddfb654f"
 
+is-fullwidth-code-point@^3.0.0:
+  version "3.0.0"
+  resolved "https://registry.yarnpkg.com/is-fullwidth-code-point/-/is-fullwidth-code-point-3.0.0.tgz#f116f8064fe90b3f7844a38997c0b75051269f1d"
+  integrity sha512-zymm5+u+sCsSWyD9qNaejV3DFvhCKclKdizYaJUuHA83RLjb7nSuGnddCHGv0hk+KY7BMAlsWeK4Ueg6EV6XQg==
+
 is-function@^1.0.1:
   version "1.0.1"
   resolved "https://registry.yarnpkg.com/is-function/-/is-function-1.0.1.tgz#12cfb98b65b57dd3d193a3121f5f6e2f437602b5"
@@ -19306,6 +19392,15 @@ string-width@^3.0.0:
     is-fullwidth-code-point "^2.0.0"
     strip-ansi "^5.1.0"
 
+string-width@^4.0.0:
+  version "4.1.0"
+  resolved "https://registry.yarnpkg.com/string-width/-/string-width-4.1.0.tgz#ba846d1daa97c3c596155308063e075ed1c99aff"
+  integrity sha512-NrX+1dVVh+6Y9dnQ19pR0pP4FiEIlUvdTGn8pw6CKTNq5sgib2nIhmUNT5TAmhWmvKr3WcxBcP3E8nWezuipuQ==
+  dependencies:
+    emoji-regex "^8.0.0"
+    is-fullwidth-code-point "^3.0.0"
+    strip-ansi "^5.2.0"
+
 string.prototype.padend@^3.0.0:
   version "3.0.0"
   resolved "https://registry.yarnpkg.com/string.prototype.padend/-/string.prototype.padend-3.0.0.tgz#f3aaef7c1719f170c5eab1c32bf780d96e21f2f0"
@@ -19545,7 +19640,7 @@ supports-color@^5.0.0, supports-color@^5.1.0, supports-color@^5.3.0, supports-co
   dependencies:
     has-flag "^3.0.0"
 
-supports-color@^6.1.0:
+supports-color@^6.0.0, supports-color@^6.1.0:
   version "6.1.0"
   resolved "https://registry.yarnpkg.com/supports-color/-/supports-color-6.1.0.tgz#0764abc69c63d5ac842dd4867e8d025e880df8f3"
   dependencies:
@@ -20563,6 +20658,13 @@ unist-util-stringify-position@^1.0.0, unist-util-stringify-position@^1.1.1:
   version "1.1.2"
   resolved "https://registry.yarnpkg.com/unist-util-stringify-position/-/unist-util-stringify-position-1.1.2.tgz#3f37fcf351279dcbca7480ab5889bb8a832ee1c6"
 
+unist-util-stringify-position@^2.0.0:
+  version "2.0.1"
+  resolved "https://registry.yarnpkg.com/unist-util-stringify-position/-/unist-util-stringify-position-2.0.1.tgz#de2a2bc8d3febfa606652673a91455b6a36fb9f3"
+  integrity sha512-Zqlf6+FRI39Bah8Q6ZnNGrEHUhwJOkHde2MHVk96lLyftfJJckaPslKgzhVcviXj8KcE9UJM9F+a4JEiBUTYgA==
+  dependencies:
+    "@types/unist" "^2.0.2"
+
 unist-util-visit-children@^1.0.0:
   version "1.1.2"
   resolved "https://registry.yarnpkg.com/unist-util-visit-children/-/unist-util-visit-children-1.1.2.tgz#bd78b53db9644b9c339ac502854f15471f964f5b"
@@ -20915,6 +21017,14 @@ vfile-message@^1.0.0:
   dependencies:
     unist-util-stringify-position "^1.1.1"
 
+vfile-message@^2.0.0:
+  version "2.0.1"
+  resolved "https://registry.yarnpkg.com/vfile-message/-/vfile-message-2.0.1.tgz#951881861c22fc1eb39f873c0b93e336a64e8f6d"
+  integrity sha512-KtasSV+uVU7RWhUn4Lw+wW1Zl/nW8JWx7JCPps10Y9JRRIDeDXf8wfBLoOSsJLyo27DqMyAi54C6Jf/d6Kr2Bw==
+  dependencies:
+    "@types/unist" "^2.0.2"
+    unist-util-stringify-position "^2.0.0"
+
 vfile-reporter@^5.0.0:
   version "5.1.1"
   resolved "https://registry.yarnpkg.com/vfile-reporter/-/vfile-reporter-5.1.1.tgz#419688c7e9dcaf65ba81bfdb0ad443e9e0248e09"
@@ -20926,6 +21036,18 @@ vfile-reporter@^5.0.0:
     vfile-sort "^2.1.2"
     vfile-statistics "^1.1.0"
 
+vfile-reporter@^6.0.0:
+  version "6.0.0"
+  resolved "https://registry.yarnpkg.com/vfile-reporter/-/vfile-reporter-6.0.0.tgz#753119f51dec9289b7508b457afc0cddf5e07f2e"
+  integrity sha512-8Is0XxFxWJUhPJdOg3CyZTqd3ICCWg6r304PuBl818ZG91h4FMS3Q+lrOPS+cs5/DZK3H0+AkJdH0J8JEwKtDA==
+  dependencies:
+    repeat-string "^1.5.0"
+    string-width "^4.0.0"
+    supports-color "^6.0.0"
+    unist-util-stringify-position "^2.0.0"
+    vfile-sort "^2.1.2"
+    vfile-statistics "^1.1.0"
+
 vfile-sort@^2.1.0:
   version "2.1.1"
   resolved "https://registry.yarnpkg.com/vfile-sort/-/vfile-sort-2.1.1.tgz#03acdc8a4d7870ecf0e35499f095ddd9d14cbc41"
@@ -20960,6 +21082,17 @@ vfile@^3.0.0:
     unist-util-stringify-position "^1.0.0"
     vfile-message "^1.0.0"
 
+vfile@^4.0.0:
+  version "4.0.1"
+  resolved "https://registry.yarnpkg.com/vfile/-/vfile-4.0.1.tgz#fc3d43a1c71916034216bf65926d5ee3c64ed60c"
+  integrity sha512-lRHFCuC4SQBFr7Uq91oJDJxlnftoTLQ7eKIpMdubhYcVMho4781a8MWXLy3qZrZ0/STD1kRiKc0cQOHm4OkPeA==
+  dependencies:
+    "@types/unist" "^2.0.0"
+    is-buffer "^2.0.0"
+    replace-ext "1.0.0"
+    unist-util-stringify-position "^2.0.0"
+    vfile-message "^2.0.0"
+
 vinyl-fs@^3.0.2:
   version "3.0.3"
   resolved "https://registry.yarnpkg.com/vinyl-fs/-/vinyl-fs-3.0.3.tgz#c85849405f67428feabbbd5c5dbdd64f47d31bc7"

From f12d5157a1eecb267e9a3a02d368af97060450cc Mon Sep 17 00:00:00 2001
From: Dustin Schau <dustinschau@gmail.com>
Date: Wed, 24 Jul 2019 10:06:25 -0700
Subject: [PATCH 2/5] chore: do not commit apis.json

---
 packages/gatsby/.gitignore |  1 +
 packages/gatsby/apis.json  | 58 --------------------------------------
 2 files changed, 1 insertion(+), 58 deletions(-)
 delete mode 100644 packages/gatsby/apis.json

diff --git a/packages/gatsby/.gitignore b/packages/gatsby/.gitignore
index 1fc1a12f6f52a..e681c7ff19b85 100644
--- a/packages/gatsby/.gitignore
+++ b/packages/gatsby/.gitignore
@@ -31,3 +31,4 @@ dist
 
 # built files
 cache-dir/commonjs/
+apis.json
diff --git a/packages/gatsby/apis.json b/packages/gatsby/apis.json
deleted file mode 100644
index 8486914e71f27..0000000000000
--- a/packages/gatsby/apis.json
+++ /dev/null
@@ -1,58 +0,0 @@
-{
-  "ssr": {
-    "replaceRenderer": {},
-    "onRenderBody": {},
-    "onPreRenderHTML": {},
-    "wrapPageElement": {},
-    "wrapRootElement": {}
-  },
-  "browser": {
-    "onClientEntry": {},
-    "onInitialClientRender": {},
-    "onPreRouteUpdate": {},
-    "onRouteUpdateDelayed": {},
-    "onRouteUpdate": {},
-    "shouldUpdateScroll": {},
-    "registerServiceWorker": {},
-    "replaceComponentRenderer": {
-      "deprecated": true
-    },
-    "wrapPageElement": {},
-    "wrapRootElement": {},
-    "onPrefetchPathname": {},
-    "onPostPrefetchPathname": {},
-    "disableCorePrefetching": {},
-    "replaceHydrateFunction": {},
-    "onServiceWorkerInstalled": {},
-    "onServiceWorkerUpdateFound": {},
-    "onServiceWorkerUpdateReady": {},
-    "onServiceWorkerActive": {},
-    "onServiceWorkerRedundant": {}
-  },
-  "node": {
-    "resolvableExtensions": {},
-    "createPages": {},
-    "createPagesStatefully": {},
-    "sourceNodes": {},
-    "onCreateNode": {},
-    "onCreatePage": {},
-    "setFieldsOnGraphQLNodeType": {},
-    "createSchemaCustomization": {
-      "version": "2.12.0"
-    },
-    "createResolvers": {
-      "version": "2.2.0"
-    },
-    "preprocessSource": {},
-    "generateSideEffects": {},
-    "onCreateBabelConfig": {},
-    "onCreateWebpackConfig": {},
-    "onPreInit": {},
-    "onPreBootstrap": {},
-    "onPostBootstrap": {},
-    "onPreBuild": {},
-    "onPostBuild": {},
-    "onPreExtractQueries": {},
-    "onCreateDevServer": {}
-  }
-}
\ No newline at end of file

From d81a6267c40619535880ab56ca0f5f41372acd15 Mon Sep 17 00:00:00 2001
From: Dustin Schau <dustinschau@gmail.com>
Date: Wed, 24 Jul 2019 10:19:35 -0700
Subject: [PATCH 3/5] chore: use undefined instead of assign

---
 packages/gatsby/scripts/output-api-file.js | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/packages/gatsby/scripts/output-api-file.js b/packages/gatsby/scripts/output-api-file.js
index db6ed78ae8d2c..60d882b00f946 100644
--- a/packages/gatsby/scripts/output-api-file.js
+++ b/packages/gatsby/scripts/output-api-file.js
@@ -32,9 +32,10 @@ async function outputFile() {
           mergedTags[tag.title] = tag.description
           return mergedTags
         }, {})
-        mergedOutput[doc.name] = Object.assign({
+        mergedOutput[doc.name] = {
+          deprecated: !!tags.deprecated || undefined,
           version: tags.gatsbyVersion
-        }, !!tags.deprecated && { deprecated: true })
+        }
       }
       return mergedOutput
     }, {})

From 098eed5e394a1083d4b9d723eb6a6d136c67447a Mon Sep 17 00:00:00 2001
From: Dustin Schau <dustinschau@gmail.com>
Date: Thu, 25 Jul 2019 07:48:24 -0700
Subject: [PATCH 4/5] chore: iron out tests

---
 packages/gatsby/package.json |   2 +-
 yarn.lock                    | 137 +----------------------------------
 2 files changed, 3 insertions(+), 136 deletions(-)

diff --git a/packages/gatsby/package.json b/packages/gatsby/package.json
index ccb48561cadf6..aad39a7e2e09e 100644
--- a/packages/gatsby/package.json
+++ b/packages/gatsby/package.json
@@ -142,7 +142,7 @@
     "@babel/runtime": "^7.0.0",
     "babel-preset-gatsby-package": "^0.2.2",
     "cross-env": "^5.1.4",
-    "documentation": "^12.0.3",
+    "documentation": "^10.1.0",
     "react": "^16.4.2",
     "react-dom": "^16.4.2",
     "rimraf": "^2.6.1",
diff --git a/yarn.lock b/yarn.lock
index ee1c9286b05b7..6a74fb0bcced0 100644
--- a/yarn.lock
+++ b/yarn.lock
@@ -3073,7 +3073,7 @@
   version "0.0.32"
   resolved "https://registry.yarnpkg.com/@types/tmp/-/tmp-0.0.32.tgz#0d3cb31022f8427ea58c008af32b80da126ca4e3"
 
-"@types/unist@*", "@types/unist@^2.0.0", "@types/unist@^2.0.2":
+"@types/unist@*", "@types/unist@^2.0.0":
   version "2.0.3"
   resolved "https://registry.yarnpkg.com/@types/unist/-/unist-2.0.3.tgz#9c088679876f374eb5983f150d4787aa6fb32d7e"
 
@@ -7665,11 +7665,6 @@ diff@^3.2.0:
   version "3.5.0"
   resolved "https://registry.yarnpkg.com/diff/-/diff-3.5.0.tgz#800c0dd1e0a8bfbc95835c202ad220fe317e5a12"
 
-diff@^4.0.1:
-  version "4.0.1"
-  resolved "https://registry.yarnpkg.com/diff/-/diff-4.0.1.tgz#0c667cb467ebbb5cea7f14f135cc2dba7780a8ff"
-  integrity sha512-s2+XdvhPCOF01LRQBC8hf4vhbVmI2CGS5aZnxLJlT5FtdhPCDFq80q++zK2KlrVorVDdL5BOGZ/VfLrVtYNF+Q==
-
 diffie-hellman@^5.0.0:
   version "5.0.3"
   resolved "http://registry.npmjs.org/diffie-hellman/-/diffie-hellman-5.0.3.tgz#40e8ee98f55a2149607146921c63e1ae5f3d2875"
@@ -7819,77 +7814,6 @@ documentation@^10.1.0:
     vue-template-compiler "^2.5.16"
     yargs "^12.0.2"
 
-documentation@^12.0.3:
-  version "12.0.3"
-  resolved "https://registry.yarnpkg.com/documentation/-/documentation-12.0.3.tgz#32f91da8e5cb4104f69db9fd32c87773a1ad6240"
-  integrity sha512-RoqkH+mQ4Vi/nFMxG0BaqPAnjKfsJ9lbLWB8KqoKVAZy+urSpk1K1zBzaFesdDkKeaR3aBgeR3RjtHp8Ut/1Wg==
-  dependencies:
-    "@babel/core" "^7.1.2"
-    "@babel/generator" "^7.1.3"
-    "@babel/parser" "7.1.3"
-    "@babel/plugin-proposal-class-properties" "^7.1.0"
-    "@babel/plugin-proposal-decorators" "^7.1.2"
-    "@babel/plugin-proposal-do-expressions" "^7.0.0"
-    "@babel/plugin-proposal-export-default-from" "^7.0.0"
-    "@babel/plugin-proposal-export-namespace-from" "^7.0.0"
-    "@babel/plugin-proposal-function-bind" "^7.0.0"
-    "@babel/plugin-proposal-function-sent" "^7.1.0"
-    "@babel/plugin-proposal-json-strings" "^7.0.0"
-    "@babel/plugin-proposal-logical-assignment-operators" "^7.0.0"
-    "@babel/plugin-proposal-nullish-coalescing-operator" "^7.0.0"
-    "@babel/plugin-proposal-numeric-separator" "^7.0.0"
-    "@babel/plugin-proposal-optional-chaining" "^7.0.0"
-    "@babel/plugin-proposal-pipeline-operator" "^7.0.0"
-    "@babel/plugin-proposal-throw-expressions" "^7.0.0"
-    "@babel/plugin-syntax-dynamic-import" "^7.0.0"
-    "@babel/plugin-syntax-import-meta" "^7.0.0"
-    "@babel/preset-env" "^7.1.0"
-    "@babel/preset-flow" "^7.0.0"
-    "@babel/preset-react" "^7.0.0"
-    "@babel/preset-stage-0" "^7.0.0"
-    "@babel/traverse" "^7.1.4"
-    "@babel/types" "^7.1.3"
-    ansi-html "^0.0.7"
-    babelify "^10.0.0"
-    chalk "^2.3.0"
-    chokidar "^2.0.4"
-    concat-stream "^1.6.0"
-    diff "^4.0.1"
-    doctrine-temporary-fork "2.1.0"
-    get-port "^4.0.0"
-    git-url-parse "^10.0.1"
-    github-slugger "1.2.0"
-    glob "^7.1.2"
-    globals-docs "^2.4.0"
-    highlight.js "^9.15.5"
-    js-yaml "^3.10.0"
-    lodash "^4.17.10"
-    mdast-util-inject "^1.1.0"
-    micromatch "^3.1.5"
-    mime "^2.2.0"
-    module-deps-sortable "5.0.0"
-    parse-filepath "^1.0.2"
-    pify "^4.0.0"
-    read-pkg-up "^4.0.0"
-    remark "^9.0.0"
-    remark-html "^8.0.0"
-    remark-reference-links "^4.0.1"
-    remark-toc "^5.0.0"
-    remote-origin-url "0.4.0"
-    resolve "^1.8.1"
-    stream-array "^1.1.2"
-    strip-json-comments "^2.0.1"
-    tiny-lr "^1.1.0"
-    unist-builder "^1.0.2"
-    unist-util-visit "^1.3.0"
-    vfile "^4.0.0"
-    vfile-reporter "^6.0.0"
-    vfile-sort "^2.1.0"
-    vinyl "^2.1.0"
-    vinyl-fs "^3.0.2"
-    vue-template-compiler "^2.5.16"
-    yargs "^12.0.2"
-
 dom-converter@~0.1:
   version "0.1.4"
   resolved "http://registry.npmjs.org/dom-converter/-/dom-converter-0.1.4.tgz#a45ef5727b890c9bffe6d7c876e7b19cb0e17f3b"
@@ -8124,11 +8048,6 @@ emoji-regex@^7.0.1, emoji-regex@^7.0.2:
   version "7.0.3"
   resolved "https://registry.yarnpkg.com/emoji-regex/-/emoji-regex-7.0.3.tgz#933a04052860c85e83c122479c4748a8e4c72156"
 
-emoji-regex@^8.0.0:
-  version "8.0.0"
-  resolved "https://registry.yarnpkg.com/emoji-regex/-/emoji-regex-8.0.0.tgz#e818fd69ce5ccfcb404594f842963bf53164cc37"
-  integrity sha512-MSjYzcWNOA0ewAHpz0MxpYFvwg6yjy1NG3xteoqz644VCo/RPgnr1/GGt+ic3iJTzQ8Eu3TdM14SawnVUmGE6A==
-
 emojis-list@^2.0.0:
   version "2.1.0"
   resolved "https://registry.yarnpkg.com/emojis-list/-/emojis-list-2.1.0.tgz#4daa4d9db00f9819880c79fa457ae5b09a1fd389"
@@ -11607,11 +11526,6 @@ is-fullwidth-code-point@^2.0.0:
   version "2.0.0"
   resolved "https://registry.yarnpkg.com/is-fullwidth-code-point/-/is-fullwidth-code-point-2.0.0.tgz#a3b30a5c4f199183167aaab93beefae3ddfb654f"
 
-is-fullwidth-code-point@^3.0.0:
-  version "3.0.0"
-  resolved "https://registry.yarnpkg.com/is-fullwidth-code-point/-/is-fullwidth-code-point-3.0.0.tgz#f116f8064fe90b3f7844a38997c0b75051269f1d"
-  integrity sha512-zymm5+u+sCsSWyD9qNaejV3DFvhCKclKdizYaJUuHA83RLjb7nSuGnddCHGv0hk+KY7BMAlsWeK4Ueg6EV6XQg==
-
 is-function@^1.0.1:
   version "1.0.1"
   resolved "https://registry.yarnpkg.com/is-function/-/is-function-1.0.1.tgz#12cfb98b65b57dd3d193a3121f5f6e2f437602b5"
@@ -19392,15 +19306,6 @@ string-width@^3.0.0:
     is-fullwidth-code-point "^2.0.0"
     strip-ansi "^5.1.0"
 
-string-width@^4.0.0:
-  version "4.1.0"
-  resolved "https://registry.yarnpkg.com/string-width/-/string-width-4.1.0.tgz#ba846d1daa97c3c596155308063e075ed1c99aff"
-  integrity sha512-NrX+1dVVh+6Y9dnQ19pR0pP4FiEIlUvdTGn8pw6CKTNq5sgib2nIhmUNT5TAmhWmvKr3WcxBcP3E8nWezuipuQ==
-  dependencies:
-    emoji-regex "^8.0.0"
-    is-fullwidth-code-point "^3.0.0"
-    strip-ansi "^5.2.0"
-
 string.prototype.padend@^3.0.0:
   version "3.0.0"
   resolved "https://registry.yarnpkg.com/string.prototype.padend/-/string.prototype.padend-3.0.0.tgz#f3aaef7c1719f170c5eab1c32bf780d96e21f2f0"
@@ -19640,7 +19545,7 @@ supports-color@^5.0.0, supports-color@^5.1.0, supports-color@^5.3.0, supports-co
   dependencies:
     has-flag "^3.0.0"
 
-supports-color@^6.0.0, supports-color@^6.1.0:
+supports-color@^6.1.0:
   version "6.1.0"
   resolved "https://registry.yarnpkg.com/supports-color/-/supports-color-6.1.0.tgz#0764abc69c63d5ac842dd4867e8d025e880df8f3"
   dependencies:
@@ -20658,13 +20563,6 @@ unist-util-stringify-position@^1.0.0, unist-util-stringify-position@^1.1.1:
   version "1.1.2"
   resolved "https://registry.yarnpkg.com/unist-util-stringify-position/-/unist-util-stringify-position-1.1.2.tgz#3f37fcf351279dcbca7480ab5889bb8a832ee1c6"
 
-unist-util-stringify-position@^2.0.0:
-  version "2.0.1"
-  resolved "https://registry.yarnpkg.com/unist-util-stringify-position/-/unist-util-stringify-position-2.0.1.tgz#de2a2bc8d3febfa606652673a91455b6a36fb9f3"
-  integrity sha512-Zqlf6+FRI39Bah8Q6ZnNGrEHUhwJOkHde2MHVk96lLyftfJJckaPslKgzhVcviXj8KcE9UJM9F+a4JEiBUTYgA==
-  dependencies:
-    "@types/unist" "^2.0.2"
-
 unist-util-visit-children@^1.0.0:
   version "1.1.2"
   resolved "https://registry.yarnpkg.com/unist-util-visit-children/-/unist-util-visit-children-1.1.2.tgz#bd78b53db9644b9c339ac502854f15471f964f5b"
@@ -21017,14 +20915,6 @@ vfile-message@^1.0.0:
   dependencies:
     unist-util-stringify-position "^1.1.1"
 
-vfile-message@^2.0.0:
-  version "2.0.1"
-  resolved "https://registry.yarnpkg.com/vfile-message/-/vfile-message-2.0.1.tgz#951881861c22fc1eb39f873c0b93e336a64e8f6d"
-  integrity sha512-KtasSV+uVU7RWhUn4Lw+wW1Zl/nW8JWx7JCPps10Y9JRRIDeDXf8wfBLoOSsJLyo27DqMyAi54C6Jf/d6Kr2Bw==
-  dependencies:
-    "@types/unist" "^2.0.2"
-    unist-util-stringify-position "^2.0.0"
-
 vfile-reporter@^5.0.0:
   version "5.1.1"
   resolved "https://registry.yarnpkg.com/vfile-reporter/-/vfile-reporter-5.1.1.tgz#419688c7e9dcaf65ba81bfdb0ad443e9e0248e09"
@@ -21036,18 +20926,6 @@ vfile-reporter@^5.0.0:
     vfile-sort "^2.1.2"
     vfile-statistics "^1.1.0"
 
-vfile-reporter@^6.0.0:
-  version "6.0.0"
-  resolved "https://registry.yarnpkg.com/vfile-reporter/-/vfile-reporter-6.0.0.tgz#753119f51dec9289b7508b457afc0cddf5e07f2e"
-  integrity sha512-8Is0XxFxWJUhPJdOg3CyZTqd3ICCWg6r304PuBl818ZG91h4FMS3Q+lrOPS+cs5/DZK3H0+AkJdH0J8JEwKtDA==
-  dependencies:
-    repeat-string "^1.5.0"
-    string-width "^4.0.0"
-    supports-color "^6.0.0"
-    unist-util-stringify-position "^2.0.0"
-    vfile-sort "^2.1.2"
-    vfile-statistics "^1.1.0"
-
 vfile-sort@^2.1.0:
   version "2.1.1"
   resolved "https://registry.yarnpkg.com/vfile-sort/-/vfile-sort-2.1.1.tgz#03acdc8a4d7870ecf0e35499f095ddd9d14cbc41"
@@ -21082,17 +20960,6 @@ vfile@^3.0.0:
     unist-util-stringify-position "^1.0.0"
     vfile-message "^1.0.0"
 
-vfile@^4.0.0:
-  version "4.0.1"
-  resolved "https://registry.yarnpkg.com/vfile/-/vfile-4.0.1.tgz#fc3d43a1c71916034216bf65926d5ee3c64ed60c"
-  integrity sha512-lRHFCuC4SQBFr7Uq91oJDJxlnftoTLQ7eKIpMdubhYcVMho4781a8MWXLy3qZrZ0/STD1kRiKc0cQOHm4OkPeA==
-  dependencies:
-    "@types/unist" "^2.0.0"
-    is-buffer "^2.0.0"
-    replace-ext "1.0.0"
-    unist-util-stringify-position "^2.0.0"
-    vfile-message "^2.0.0"
-
 vinyl-fs@^3.0.2:
   version "3.0.3"
   resolved "https://registry.yarnpkg.com/vinyl-fs/-/vinyl-fs-3.0.3.tgz#c85849405f67428feabbbd5c5dbdd64f47d31bc7"

From 54213b4c7d7d9918f0b1e4f80a85f346f59e2112 Mon Sep 17 00:00:00 2001
From: Dustin Schau <dustinschau@gmail.com>
Date: Thu, 25 Jul 2019 10:23:06 -0700
Subject: [PATCH 5/5] chore: make code self documenting (s/o Pieh)

---
 packages/gatsby/scripts/output-api-file.js | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/packages/gatsby/scripts/output-api-file.js b/packages/gatsby/scripts/output-api-file.js
index 60d882b00f946..3395c4db09c17 100644
--- a/packages/gatsby/scripts/output-api-file.js
+++ b/packages/gatsby/scripts/output-api-file.js
@@ -27,7 +27,8 @@ async function outputFile() {
 
   const output = apis.reduce((merged, [output, api]) => {
     merged[api] = output.reduce((mergedOutput, doc) => {
-      if (doc.namespace.startsWith('.')) {
+      const isAPI = doc.namespace.startsWith('.')
+      if (isAPI) {
         const tags = doc.tags.reduce((mergedTags, tag) => {
           mergedTags[tag.title] = tag.description
           return mergedTags