feat(gatsby): plugin option validation (#27242)

* Add pluginOptionsSchema to google analytics for testing

* Add structured error for plugin option validation errors

* Validate gatsbyNode.pluginOptionsSchema when defined

* Add first test, fix some bugs discovered based on it

* process.exit on invalid plugin options

* Much nicer structured error logging for invalid plugin options

* Move TODO comment to correct place

* Remove unused import

* Add new API to gatsby-node API tests

* Warn on invalid plugin schema

* Gate plugin option validation behind feature flag for now

* less formal wording

* Clean up based on code review

* Type GatsbyNode.pluginOptionsSchema

* Properly type Joi including our .dotenv() extension

* Move custom joi + types to gatsby-plugin-utils

* Disable the .dotenv extension for now

.jestSetup.js

@@ -1 +1,2 @@
 process.env.GATSBY_RECIPES_NO_COLOR = "true"
+process.env.GATSBY_EXPERIMENTAL_PLUGIN_OPTION_VALIDATION = "true"

packages/gatsby-cli/src/structured-errors/error-map.ts

@@ -420,6 +420,22 @@ const errors = {
     type: Type.PLUGIN,
     level: Level.ERROR,
   },
+  // Invalid plugin options
+  "11331": {
+    text: (context): string =>
+      [
+        stripIndent(`
+          Invalid plugin options for "${context.pluginName}":
+        `),
+      ]
+        .concat([``])
+        .concat(
+          context.validationErrors.map(error => `- ${error.message}`).join(`\n`)
+        )
+        .join(`\n`),
+    type: Type.PLUGIN,
+    level: Level.ERROR,
+  },
   // node object didn't pass validation
   "11467": {
     text: (context): string =>

packages/gatsby-plugin-google-analytics/src/gatsby-node.js

@@ -1,7 +1,39 @@
-exports.onPreInit = ({ reporter }, options) => {
-  if (!options.trackingId) {
-    reporter.warn(
-      `The Google Analytics plugin requires a tracking ID. Did you mean to add it?`
-    )
-  }
-}
+exports.pluginOptionsSchema = ({ Joi }) =>
+  Joi.object({
+    trackingId: Joi.string()
+      .required()
+      .description(
+        `The property ID; the tracking code won't be generated without it`
+      ),
+    head: Joi.boolean()
+      .default(false)
+      .description(
+        `Defines where to place the tracking script - \`true\` in the head and \`false\` in the body`
+      ),
+    anonymize: Joi.boolean().default(false),
+    respectDNT: Joi.boolean().default(false),
+    exclude: Joi.array()
+      .items(Joi.string())
+      .default([])
+      .description(`Avoids sending pageview hits from custom paths`),
+    pageTransitionDelay: Joi.number()
+      .default(0)
+      .description(
+        `Delays sending pageview hits on route update (in milliseconds)`
+      ),
+    optimizeId: Joi.string().description(
+      `Enables Google Optimize using your container Id`
+    ),
+    experimentId: Joi.string().description(
+      `Enables Google Optimize Experiment ID`
+    ),
+    variationId: Joi.string().description(
+      `Set Variation ID. 0 for original 1,2,3....`
+    ),
+    defer: Joi.boolean().description(
+      `Defers execution of google analytics script after page load`
+    ),
+    sampleRate: Joi.number(),
+    siteSpeedSampleRate: Joi.number(),
+    cookieDomain: Joi.string(),
+  })

packages/gatsby-plugin-utils/src/__tests__/index.ts

@@ -1,6 +1,5 @@
 /* eslint-disable @typescript-eslint/explicit-function-return-type */
-import Joi from "joi"
-import { validateOptionsSchema } from "../"
+import { validateOptionsSchema, Joi } from "../"
 
 it(`validates a basic schema`, async () => {
   const pluginSchema = Joi.object({

packages/gatsby-plugin-utils/src/index.ts

@@ -1 +1,2 @@
 export * from "./validate"
+export * from "./joi"

packages/gatsby-plugin-utils/src/joi.ts

@@ -0,0 +1,27 @@
+import joi from "joi"
+import { PluginOptionsSchemaJoi } from "./utils/plugin-options-schema-joi-type"
+
+export * from "./utils/plugin-options-schema-joi-type"
+export const Joi: PluginOptionsSchemaJoi = joi.extend({
+  // This tells Joi to extend _all_ types with .dotenv(), see
+  // https://github.com/sideway/joi/commit/03adf22eb1f06c47d1583617093edee3a96b3873
+  // @ts-ignore Joi types weren't updated with that commit, PR: https://github.com/sideway/joi/pull/2477
+  type: /^s/,
+  rules: {
+    // NOTE(@mxstbr): Disabled until we decide on the necessity for this API.
+    // dotenv: {
+    //   args: [`name`],
+    //   validate(value, helpers, args): void {
+    //     if (!args.name) {
+    //       return helpers.error(
+    //         `any.dotenv requires the environment variable name`
+    //       )
+    //     }
+    //     return value
+    //   },
+    //   method(name): Schema {
+    //     return this.$_addRule({ name: `dotenv`, args: { name } })
+    //   },
+    // },
+  },
+})