chore(gatsby): output apis.json for current valid API list (gatsbyjs#…

…16061)

* feat(gatsby): output apis.json for current valid API list

* chore: do not commit apis.json

* chore: use undefined instead of assign

* chore: iron out tests

* chore: make code self documenting (s/o Pieh)

packages/gatsby/.gitignore

@@ -31,3 +31,4 @@ dist
 
 # built files
 cache-dir/commonjs/
+apis.json

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": "^10.1.0",
     "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__",

packages/gatsby/scripts/output-api-file.js

@@ -0,0 +1,49 @@
+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) => {
+      const isAPI = doc.namespace.startsWith('.')
+      if (isAPI) {
+        const tags = doc.tags.reduce((mergedTags, tag) => {
+          mergedTags[tag.title] = tag.description
+          return mergedTags
+        }, {})
+        mergedOutput[doc.name] = {
+          deprecated: !!tags.deprecated || undefined,
+          version: tags.gatsbyVersion
+        }
+      }
+      return mergedOutput
+    }, {})
+    return merged
+  }, {})
+
+  return fs.writeFile(path.resolve(OUTPUT_FILE_NAME), JSON.stringify(output, null, 2), 'utf8')
+}
+
+outputFile()

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