ci: ensure that databases table in docs/schema.md is valid (#395)

This should catch mistakes like #393

---------

Signed-off-by: Gareth Jones <[email protected]>

Author: G-Rath

.github/workflows/checks.yml

@@ -79,6 +79,21 @@ jobs:
             | xargs -I '{}' bash -c \
               'echo "::error file={}::This needs to be regenerated by running \`python3 ./scripts/update-ecosystems-lists.py\`" && false'
 
+  validate_schema_databases_table:
+    permissions:
+      contents: read # to fetch code (actions/checkout)
+    name: Ensure schema databases table is valid
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out code
+        uses: actions/checkout@eef61447b9ff4aafe5dcd4e0bbf5d482be7e7871 # v4.2.1
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@f677139bbe7f9c59b41e40162b753c062f5d49a3 # v5.2.0
+        with:
+          python-version: 3.13
+      - run: python3 ./scripts/validate-schema-table.py
+
   validate-osv-schema:
     name: Validate OSV Schema
     permissions:

scripts/validate-schema-table.py

@@ -0,0 +1,56 @@
+#!/usr/bin/env python3
+
+import os
+from html.parser import HTMLParser
+
+
+class UnexpectedTagError(Exception):
+  pass
+
+
+class HTMLValidator(HTMLParser):
+  def __init__(self) -> None:
+    super().__init__()
+
+    self.__tags: list[str] = []
+
+  def handle_starttag(self, tag: str, attrs: list[tuple[str, str | None]]) -> None:
+    self.__tags.append(tag)
+
+  def handle_endtag(self, tag: str) -> None:
+    last_tag = self.__tags.pop()
+    if last_tag != tag:
+      raise UnexpectedTagError(last_tag)
+
+
+def extract_schema_table() -> tuple[str, int]:
+  raw_table = ''
+  index = -1
+
+  with open('docs/schema.md') as f:
+    for i, line in enumerate(f.readlines()):
+      if line == '<table>\n':
+        index = i + 1
+        raw_table += line
+      if raw_table != '':
+        raw_table += line
+      if line == '</table>\n':
+        break
+  return raw_table, index
+
+
+table, starting_line = extract_schema_table()
+
+validator = HTMLValidator()
+
+try:
+  validator.feed(table)
+except UnexpectedTagError as e:
+  if 'CI' in os.environ:
+    print(
+      f'::error file=docs/schema.md,line={starting_line}::unexpected {e} tag in table - ensure that the tags are properly paired'
+    )
+  print(
+    f'unexpected {e} tag in docs/schema.md databases table - ensure that the tags are properly paired'
+  )
+  exit(1)