Add test to catch fallthrough TODO condition in generated docs. (#1101)

Author: AndrewJakubowicz

.github/workflows/unit-tests.yml

@@ -17,3 +17,4 @@ jobs:
 
       - run: npm ci
       - run: npm run test:unit
+      - run: npm run test:generated-api

package.json

@@ -21,6 +21,7 @@
     "test:integration": "npm run test:integration -w lit-dev-tests",
     "test:integration:update-golden-screenshots": "npm run test:integration:update-golden-screenshots -w lit-dev-tests",
     "test:links": "npm run test:links -w lit-dev-tests",
+    "test:generated-api": "npm run test:api:no-todos -w lit-dev-tests",
     "publish-search-index": "wireit"
   },
   "wireit": {

packages/lit-dev-content/site/_includes/api.html

@@ -148,7 +148,7 @@
       ReadonlyArray<string>
 
     {%- else -%}
-      TODO
+      <span class="error-fallback-todo">TODO</span>
       {# {{ t | dump }} #}
     {%- endif -%}
 

packages/lit-dev-tests/package.json

@@ -12,7 +12,8 @@
     "test:integration:update-golden-screenshots": "wireit",
     "test:links": "wireit",
     "test:links:redirects": "wireit",
-    "test:links:internal-and-external": "wireit"
+    "test:links:internal-and-external": "wireit",
+    "test:api:no-todos": "wireit"
   },
   "wireit": {
     "build": {
@@ -78,6 +79,13 @@
       ],
       "files": [],
       "output": []
+    },
+    "test:api:no-todos": {
+      "command": "node lib/check-no-todos.js",
+      "dependencies": [
+        "build",
+        "../lit-dev-content:build"
+      ]
     }
   },
   "dependencies": {

packages/lit-dev-tests/src/check-no-todos.ts

@@ -0,0 +1,76 @@
+/**
+ * @license
+ * Copyright 2023 Google LLC
+ * SPDX-License-Identifier: BSD-3-Clause
+ */
+
+/**
+ * Our `api.html` generator template fails by rendering a `TODO`. For example
+ * see issue https://github.com/lit/lit.dev/issues/1097.
+ *
+ * This means when upgrading infrastructure, it can sometimes become a subtle
+ * error that needs manual scavenging for errant TODO's. This test scans built
+ * HTML files for instances of TODO - and breaks tests if one is found.
+ */
+
+import {readFileSync} from 'fs';
+import * as pathLib from 'path';
+import {fileURLToPath} from 'url';
+import ansi from 'ansi-escape-sequences';
+
+const {red, green, yellow, bold, reset} = ansi.style;
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = pathLib.dirname(__filename);
+const siteOutputDir = pathLib.resolve(
+  __dirname,
+  '../',
+  '../',
+  'lit-dev-content',
+  '_site'
+);
+
+const api_pages_to_check = [
+  pathLib.resolve(siteOutputDir, 'docs/api/controllers/index.html'),
+  pathLib.resolve(siteOutputDir, 'docs/api/custom-directives/index.html'),
+  pathLib.resolve(siteOutputDir, 'docs/api/decorators/index.html'),
+  pathLib.resolve(siteOutputDir, 'docs/api/directives/index.html'),
+  pathLib.resolve(siteOutputDir, 'docs/api/LitElement/index.html'),
+  pathLib.resolve(siteOutputDir, 'docs/api/misc/index.html'),
+  pathLib.resolve(siteOutputDir, 'docs/api/ReactiveElement/index.html'),
+  pathLib.resolve(siteOutputDir, 'docs/api/static-html/index.html'),
+  pathLib.resolve(siteOutputDir, 'docs/api/styles/index.html'),
+  pathLib.resolve(siteOutputDir, 'docs/api/templates/index.html'),
+];
+
+const checkNoTodos = async () => {
+  console.log('==========================================');
+  console.log("Checking lit.dev generated API for TODO's");
+  console.log('==========================================');
+  console.log();
+
+  let fail = false;
+
+  for (const page of api_pages_to_check) {
+    const content = readFileSync(page, {encoding: 'utf8'});
+
+    if (content.includes(`"error-fallback-todo"`)) {
+      fail = true;
+      console.log(`${bold + red}FOUND TODO${reset} ${yellow + page + reset}`);
+    }
+  }
+
+  console.log();
+  if (fail) {
+    console.log(
+      `${bold + red}Found TODOs in generated  API documentation!${reset}`
+    );
+    process.exit(1);
+  } else {
+    console.error(
+      `${bold + green}Generated API does not contain any TODOs!${reset}`
+    );
+  }
+};
+
+checkNoTodos();