Enforce documentation.yml toc coverage via ESLint

JSDoc documented items missing from the documentation.yml toc render
at an arbitrary spot at the end of the generated docs. Since the docs
workflow only runs on master, this used to go unnoticed until after
publishing.

Add a custom ESLint rule that reports documented top level items that
are not listed in the toc, giving fast feedback from lint runs. The
rule lives in the pageflow package's shared config directory, like
the jest and webpack configs reused by entry type packages.

Add toc entries for previously unlisted items. Document the error
boundary property via the established underscored @name pattern: only
an explicit @name suppresses the inferred memberof, which would
otherwise prevent toc matching, and the docs theme renders the
underscore as a dot (frontend.contentElementErrorBoundary).

Author: tf

entry_types/scrolled/package/.eslintrc.js

@@ -48,6 +48,14 @@ module.exports = {
           "patterns": ["**/entryState/**", "../**/entryState"]
         }]
       }
+    },
+    {
+      // Directories passed to documentation.js in
+      // .github/workflows/docs.yml.
+      "files": ["src/**/*.js", "spec/support/**/*.js"],
+      "rules": {
+        "documented-in-toc": "error"
+      }
     }
   ]
 };

entry_types/scrolled/package/documentation.yml

@@ -5,6 +5,7 @@ toc:
     children:
       - frontend_contentElementTypes
       - frontend_widgetTypes
+      - frontend_contentElementErrorBoundary
   - name: Editor API
     description: |
       Main entry point of editor API to register new content element types.
@@ -45,6 +46,7 @@ toc:
       - useLegalInfo
       - useMediaMuted
       - usePortraitOrientation
+      - usePrivacyLink
       - useShareProviders
       - useShareUrl
       - useTheme
@@ -60,6 +62,7 @@ toc:
       - normalizeSeed
       - renderInEntry
       - renderInContentElement
+      - renderInEntryWithContentElementLifecycle
       - renderHookInEntry
   - name: Storybook Support
     description: |

entry_types/scrolled/package/package.json

@@ -86,7 +86,7 @@
   },
   "scripts": {
     "test": "jest",
-    "lint": "eslint",
+    "lint": "eslint --rulesdir ../../../node_modules/pageflow/config/eslint-rules",
     "start-storybook": "storybook dev --port 8001",
     "build-storybook": "storybook build -o .storybook/out",
     "snapshot": "storybook build --quiet -o .storybook/out && PERCY_TOKEN=${PERCY_TOKEN:-$PT} percy storybook .storybook/out"

entry_types/scrolled/package/src/frontend/api/index.js

@@ -12,7 +12,8 @@ export const api = {
    * typeName (string), configuration (object), fallback (function returning
    * default UI), and children (content element).
    *
-   * @property {React.Component} contentElementErrorBoundary
+   * @name frontend_contentElementErrorBoundary
+   * @type {React.Component}
    */
   contentElementErrorBoundary: undefined
 }

package/.eslintrc.js

@@ -46,6 +46,18 @@ module.exports = {
     {
       "files": ["spec/**/*.js", "src/testHelpers/**/*.js"],
       "extends": ["plugin:jest/recommended"]
+    },
+    {
+      // Directories passed to documentation.js in
+      // .github/workflows/docs.yml.
+      "files": [
+        "src/editor/**/*.js",
+        "src/ui/**/*.js",
+        "src/testHelpers/**/*.js"
+      ],
+      "rules": {
+        "documented-in-toc": "error"
+      }
     }
   ]
 };

package/config/eslint-rules/documented-in-toc.js

@@ -0,0 +1,125 @@
+const fs = require('fs');
+const path = require('path');
+const yaml = require('js-yaml');
+
+// JSDoc comments on these are either nested under another item or
+// excluded from the generated docs, so they do not need toc entries.
+const skippedTags = /@(private|internal|ignore|memberof)\b/;
+
+module.exports = {
+  meta: {
+    type: 'suggestion',
+    docs: {
+      description:
+        'Ensure JSDoc documented top level items are listed in the toc ' +
+        'of documentation.yml. Otherwise they render at an arbitrary ' +
+        'spot at the end of the generated docs.'
+    },
+    schema: []
+  },
+
+  create(context) {
+    const config = findTocConfig(path.dirname(context.getFilename()));
+
+    if (!config) {
+      return {};
+    }
+
+    const sourceCode = context.getSourceCode();
+
+    return {
+      Program(program) {
+        program.body.forEach(statement => {
+          const comment = jsdocCommentBefore(statement);
+
+          if (!comment || skippedTags.test(comment.value)) {
+            return;
+          }
+
+          const name = documentedName(comment, statement);
+
+          if (name && !config.names.has(name)) {
+            context.report({
+              loc: comment.loc,
+              message:
+                `'${name}' has a JSDoc comment, but is not listed in the ` +
+                `toc in ${config.relativePath}. Add it to the section ` +
+                'where it should show up in the generated docs.'
+            });
+          }
+        });
+      }
+    };
+
+    function jsdocCommentBefore(statement) {
+      const comments = sourceCode.getCommentsBefore(statement);
+      const comment = comments[comments.length - 1];
+
+      return comment &&
+             comment.type === 'Block' &&
+             comment.value.startsWith('*') ? comment : null;
+    }
+  }
+};
+
+function documentedName(comment, statement) {
+  const tagMatch = comment.value.match(/@(?:name|alias)\s+([\w.#]+)/);
+
+  if (tagMatch) {
+    return tagMatch[1];
+  }
+
+  return declaredName(statement);
+}
+
+function declaredName(statement) {
+  switch (statement.type) {
+  case 'ExportNamedDeclaration':
+  case 'ExportDefaultDeclaration':
+    return statement.declaration && declaredName(statement.declaration);
+  case 'FunctionDeclaration':
+  case 'ClassDeclaration':
+    return statement.id && statement.id.name;
+  case 'VariableDeclaration':
+    return statement.declarations[0].id.type === 'Identifier' ?
+           statement.declarations[0].id.name : null;
+  default:
+    return null;
+  }
+}
+
+const configCache = new Map();
+
+function findTocConfig(directory) {
+  if (configCache.has(directory)) {
+    return configCache.get(directory);
+  }
+
+  const configPath = path.join(directory, 'documentation.yml');
+  let config;
+
+  if (fs.existsSync(configPath)) {
+    config = loadTocConfig(configPath);
+  }
+  else {
+    const parent = path.dirname(directory);
+    config = parent === directory ? null : findTocConfig(parent);
+  }
+
+  configCache.set(directory, config);
+  return config;
+}
+
+function loadTocConfig(configPath) {
+  const toc = yaml.safeLoad(fs.readFileSync(configPath, 'utf8')).toc || [];
+  const names = new Set();
+
+  toc.forEach(section =>
+    (section.children || []).forEach(child => names.add(child))
+  );
+
+  return {
+    names,
+    relativePath: path.relative(process.cwd(), configPath)
+  };
+}

package/documentation.yml

@@ -50,13 +50,15 @@ toc:
       - EditConfigurationView
       - ReferenceInputView
       - FileInputView
+      - OembedUrlInputView
 
   - name: Editor - Misc Views
     description: |
       General purpose Backbone views and mixins exported by `pageflow/editor`.
     children:
       - modelLifecycleTrackingView
       - DropDownButtonView
+      - DestroyMenuItem
       - ListView
       - ModelThumbnailView
 
@@ -132,4 +134,5 @@ toc:
     children:
       - factories
       - setupGlobals
+      - useFakeFeatures
       - useFakeTranslations

package/package.json

@@ -21,7 +21,7 @@
   },
   "scripts": {
     "test": "jest",
-    "lint": "eslint"
+    "lint": "eslint --rulesdir config/eslint-rules"
   },
   "dependencies": {
     "backbone-events-standalone": "^0.2.7",