blumeops/mise-tasks/docs-check-frontmatter

#!/usr/bin/env -S uv run --script
# /// script
# requires-python = ">=3.12"
# dependencies = ["rich==15.0.0"]
# ///
#MISE description="Check that all docs have required frontmatter fields"
"""Validate that all documentation files have required YAML frontmatter.

Required fields: title, tags, modified

Scans all markdown files in docs/ (excluding changelog.d/) and checks
that each file has YAML frontmatter containing the required fields.

Usage: mise run docs-check-frontmatter
"""

import re
import sys
from pathlib import Path

from rich.console import Console
from rich.table import Table

DOCS_DIR = Path(__file__).parent.parent / "docs"
HOWTO_DIR = DOCS_DIR / "how-to"
REQUIRED_FIELDS = {"title", "tags", "modified"}
# These fields are only permitted in docs/how-to/
HOWTO_ONLY_FIELDS = {"status", "requires"}

# Match YAML frontmatter block
FRONTMATTER_PATTERN = re.compile(r"^---\n(.*?)\n---\n", re.DOTALL)

# Match top-level YAML keys (not indented)
KEY_PATTERN = re.compile(r"^([a-zA-Z][a-zA-Z0-9_-]*):", re.MULTILINE)


def extract_frontmatter_keys(file_path: Path) -> set[str] | None:
    """Extract top-level keys from YAML frontmatter. Returns None if no frontmatter."""
    content = file_path.read_text()
    match = FRONTMATTER_PATTERN.match(content)
    if not match:
        return None
    frontmatter = match.group(1)
    return set(KEY_PATTERN.findall(frontmatter))


def main() -> int:
    console = Console()
    console.print("[bold]Frontmatter Validation[/bold]")
    console.print(f"Required fields: {', '.join(sorted(REQUIRED_FIELDS))}")
    console.print()

    missing_issues: list[tuple[str, set[str]]] = []
    misplaced_issues: list[tuple[str, set[str]]] = []

    for md_file in sorted(DOCS_DIR.rglob("*.md")):
        if "changelog.d" in md_file.parts:
            continue

        rel_path = str(md_file.relative_to(DOCS_DIR))
        keys = extract_frontmatter_keys(md_file)

        if keys is None:
            missing_issues.append((rel_path, REQUIRED_FIELDS))
            continue

        missing = REQUIRED_FIELDS - keys
        if missing:
            missing_issues.append((rel_path, missing))

        # Check that status/requires only appear in how-to docs
        is_howto = HOWTO_DIR in md_file.parents or md_file.parent == HOWTO_DIR
        if not is_howto:
            misplaced = keys & HOWTO_ONLY_FIELDS
            if misplaced:
                misplaced_issues.append((rel_path, misplaced))

    has_issues = bool(missing_issues or misplaced_issues)

    if missing_issues:
        console.print("[bold red]Missing Required Frontmatter[/bold red]")
        console.print()
        table = Table(show_header=True, header_style="bold")
        table.add_column("File")
        table.add_column("Missing Fields")

        for rel_path, missing in missing_issues:
            table.add_row(rel_path, ", ".join(sorted(missing)))

        console.print(table)
        console.print()

    if misplaced_issues:
        console.print("[bold red]Misplaced Frontmatter Fields[/bold red]")
        console.print(f"[dim]These fields are only allowed in {HOWTO_DIR.relative_to(DOCS_DIR)}/[/dim]")
        console.print()
        table = Table(show_header=True, header_style="bold")
        table.add_column("File")
        table.add_column("Disallowed Fields")

        for rel_path, misplaced in misplaced_issues:
            table.add_row(rel_path, ", ".join(sorted(misplaced)))

        console.print(table)
        console.print()

    if has_issues:
        return 1

    console.print("[bold green]All docs have required frontmatter![/bold green]")
    return 0


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