Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions .github/workflows/docs.yml
Original file line number Diff line number Diff line change
Expand Up @@ -113,6 +113,7 @@ jobs:
run: |
bash scripts/build_local.sh --draft-only
uv run python scripts/check_links.py local_preview
uv run python scripts/check_rendered_tables.py local_preview

build_and_verify_release:
needs: lint
Expand Down Expand Up @@ -144,6 +145,7 @@ jobs:
export DOCS_MODE=spec
uv run mkdocs build --strict
uv run python scripts/check_links.py site
uv run python scripts/check_rendered_tables.py site

deploy_main:
needs: build_and_verify_main
Expand Down
7 changes: 7 additions & 0 deletions .pre-commit-config.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -51,6 +51,13 @@ repos:
pass_filenames: false
files: ^(main\.py|scripts/test_schema_tables\.py|source/schemas/ucp\.json|docs/specification/reference\.md)$
stages: [pre-commit, pre-push]
- id: check-rendered-tables-tests
name: Rendered table checker unit tests
entry: uv run --frozen python scripts/test_check_rendered_tables.py
language: system
pass_filenames: false
files: ^scripts/(check_rendered_tables|test_check_rendered_tables)\.py$
stages: [pre-commit, pre-push]
- id: check-links-tests
name: Link checker unit tests
entry: uv run --frozen python scripts/test_check_links.py
Expand Down
1 change: 1 addition & 0 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -62,6 +62,7 @@ These commands should be run from the ucp root directory.
* **Build Full Multi-Version Site**: `./scripts/build_local.sh`. The resulting build will be placed in the local_preview/ directory. Add `[--draft-only]` to avoid building every version of the specification.
* **Serve the site locally after build**: `python3 -m http.server 8000 -d local_preview/`
* **Check Broken Links after build:** `uv run ./scripts/check_links.py local_preview/`
* **Check Rendered Schema Tables after build:** `uv run ./scripts/check_rendered_tables.py local_preview/`

#### Optional: build and serve specification by version(s)

Expand Down
12 changes: 8 additions & 4 deletions main.py
Original file line number Diff line number Diff line change
Expand Up @@ -1739,11 +1739,15 @@ def _format_schema_type(
)
)
elif "$ref" in schema_data:
md.append(
_render_table_from_ref(
schema_data.get("$ref"), required_list, spec_file_name, context
)
body = _render_table_from_ref(
schema_data.get("$ref"), required_list, spec_file_name, context
)
# A $ref to a scalar type (amenity_type -> reverse_domain_name) renders
# as prose. Under a table header, Markdown reads that prose as a row
# with an empty Type cell, so return it on its own.
if need_header and not body.lstrip().startswith("|"):
return body
md.append(body)
else:
for field_name, details in properties.items():
if field_name == "$ref":
Expand Down
214 changes: 214 additions & 0 deletions scripts/check_rendered_tables.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,214 @@
#!/usr/bin/env python3
"""Check the built site for schema tables that rendered wrong.

The field tables on the spec pages are generated from the JSON schemas and
OpenAPI documents by the macros in main.py. When a macro cannot name a
type, the build still succeeds: the Type cell just reads "any", "OneOf[]",
"Array[any]", or is empty. Each of those has reached the published site
before and was found by someone reading the page.

This runs after the MkDocs build and fails on the rendered output, so a
regression is caught in the PR that introduces it:

- Every schema field table (Name / Type / Requirement / Description) has a
non-empty Name and a Type that names something: no placeholder, no empty
composite such as "OneOf[]", no "any" at any nesting level.
- Every REST binding page renders its HTTP Headers table.
- Every `response_*_schema` definition in ucp.json has a rendered section
with the `ucp-response-<name>-schema` anchor somewhere on the site.

Usage: python3 scripts/check_rendered_tables.py [SITE_DIR] [--schema-base DIR]
SITE_DIR defaults to local_preview; --schema-base to source/schemas.
Exit: 0 when clean, 1 when anything is reported.
"""

from __future__ import annotations

import argparse
from html.parser import HTMLParser
import json
from pathlib import Path
import re
import sys

SCHEMA_TABLE_HEADER = ("Name", "Type", "Requirement", "Description")
HEADER_TABLE_HEADER = ("Header", "Required", "Description")

# A Type cell that reads like one of these did not resolve.
_BAD_TYPE_PATTERNS = (
re.compile(r"^any$"),
re.compile(r"\[any\]"),
re.compile(r"\[\]"),
re.compile(r"[{}]"),
)


class _TableParser(HTMLParser):
"""Collect every table on a page as a list of rows of cell text."""

def __init__(self) -> None:
super().__init__()
self.title = ""
self.ids: set[str] = set()
self.tables: list[list[list[str]]] = []
self._table: list[list[str]] | None = None
self._row: list[str] | None = None
self._cell: list[str] | None = None
self._in_title = False

def handle_starttag(self, tag, attrs):
attrs_dict = dict(attrs)
if "id" in attrs_dict:
self.ids.add(attrs_dict["id"])
if tag == "title":
self._in_title = True
elif tag == "table":
self._table = []
elif tag == "tr" and self._table is not None:
self._row = []
elif tag in ("td", "th") and self._row is not None:
self._cell = []

def handle_endtag(self, tag):
if tag == "title":
self._in_title = False
elif tag in ("td", "th") and self._cell is not None:
self._row.append(" ".join("".join(self._cell).split()))
self._cell = None
elif tag == "tr" and self._row is not None:
self._table.append(self._row)
self._row = None
elif tag == "table" and self._table is not None:
self.tables.append(self._table)
self._table = None

def handle_data(self, data):
if self._in_title:
self.title += data
if self._cell is not None:
self._cell.append(data)


def _parse(path: Path) -> _TableParser:
parser = _TableParser()
parser.feed(path.read_text(encoding="utf-8"))
return parser


def _is_redirect_stub(page: _TableParser) -> bool:
return page.title.strip() == "Redirecting..."


def _bad_type(cell: str) -> bool:
return not cell or any(p.search(cell) for p in _BAD_TYPE_PATTERNS)


def check_schema_tables(path: Path, page: _TableParser) -> list[str]:
"""Report rows whose Name or Type cell did not render."""
problems = []
for table in page.tables:
if not table or tuple(table[0]) != SCHEMA_TABLE_HEADER:
continue
for row in table[1:]:
name = row[0] if row else ""
type_cell = row[1] if len(row) > 1 else ""
if not name:
problems.append(
f"{path}: schema table row has no Name (type {type_cell!r})"
)
elif _bad_type(type_cell):
shown = name if len(name) <= 60 else name[:57] + "..."
problems.append(
f"{path}: field {shown!r} rendered with type {type_cell!r}"
)
return problems


def check_rest_headers(path: Path, page: _TableParser) -> list[str]:
"""Report a REST binding page that renders no HTTP Headers table."""
if not any(
table and tuple(table[0]) == HEADER_TABLE_HEADER for table in page.tables
):
return [f"{path}: REST binding page has no HTTP Headers table"]
return []


def response_metadata_anchors(schema_base: Path) -> dict[str, str]:
"""Map each ucp.json `response_*_schema` def to its reference anchor."""
ucp = json.loads((schema_base / "ucp.json").read_text(encoding="utf-8"))
anchors = {}
for name in ucp.get("$defs", {}):
match = re.fullmatch(r"response_(\w+)_schema", name)
if match:
anchors[name] = f"ucp-response-{match.group(1)}-schema"
return anchors


def _is_rest_binding(path: Path, site_dir: Path) -> bool:
parts = path.relative_to(site_dir).parts
return "specification" in parts and parts[-2:] == ("rest", "index.html")


def check_site(site_dir: Path, schema_base: Path) -> list[str]:
"""Run every check over the built site and return the problems found."""
problems: list[str] = []
seen_ids: set[str] = set()
pages = 0

for path in sorted(site_dir.rglob("*.html")):
page = _parse(path)
if _is_redirect_stub(page):
continue
pages += 1
seen_ids |= page.ids
problems += check_schema_tables(path, page)
if _is_rest_binding(path, site_dir):
problems += check_rest_headers(path, page)

if pages == 0:
return [f"{site_dir}: no HTML pages found; was the site built?"]

for def_name, anchor in sorted(
response_metadata_anchors(schema_base).items()
):
if anchor not in seen_ids:
problems.append(
f"ucp.json $defs/{def_name} has no rendered section (#{anchor})"
)

return problems


def main(argv: list[str] | None = None) -> int:
"""Parse arguments, run the checks and return the exit code."""
parser = argparse.ArgumentParser(description=__doc__.split("\n\n")[0])
parser.add_argument(
"site_dir",
nargs="?",
default="local_preview",
help="built site directory (default: local_preview)",
)
parser.add_argument(
"--schema-base",
default="source/schemas",
help="schema directory holding ucp.json (default: source/schemas)",
)
args = parser.parse_args(argv)

site_dir = Path(args.site_dir)
if not site_dir.is_dir():
print(f"Error: {site_dir} is not a directory", file=sys.stderr)
return 1

problems = check_site(site_dir, Path(args.schema_base))
for problem in problems:
print(problem)
if problems:
print(f"\n{len(problems)} rendering problem(s) found")
return 1
print("Rendered tables OK")
return 0


if __name__ == "__main__":
sys.exit(main())
Loading
Loading