Function validate_deck

openkb/deck/validator.py:128–197

Validate the generated deck at ``deck_dir/index.html``. Args: deck_dir: Directory containing ``index.html``. grammar: Optional skill-declared grammar (typically read from the skill's frontmatter under ``od.deck_grammar``). When ``None``, only skill-agnost

(
    deck_dir: Path,
    grammar: Optional[DeckGrammar] = None,
)

def validate_deck(
    deck_dir: Path,
    grammar: Optional[DeckGrammar] = None,
) -> ValidationResult:
    """Validate the generated deck at ``deck_dir/index.html``.

    Args:
        deck_dir: Directory containing ``index.html``.
        grammar: Optional skill-declared grammar (typically read from the
            skill's frontmatter under ``od.deck_grammar``). When ``None``,
            only skill-agnostic invariants are checked (file present,
            parses, ≥5 slides, self-contained). When provided, also
            enforces required/allowed slide kinds.

    Returns a :class:`ValidationResult` with categorised issues. Never
    raises for structural failures — those become entries in ``errors``.
    """
    result = ValidationResult()
    index = deck_dir / "index.html"

    if not index.is_file():
        result.errors.append(f"index.html not found at {index}")
        return result

    size = index.stat().st_size
    if size > MAX_FILE_BYTES:
        result.warnings.append(
            f"index.html is {size / 1024 / 1024:.1f} MB (> {MAX_FILE_BYTES // 1024 // 1024} MB) — "
            f"likely too many inlined images."
        )

    text = index.read_text(encoding="utf-8", errors="replace")
    kind_attr = grammar.get("kind_attr") if grammar else None
    parser = _DeckParser(kind_attr=kind_attr)
    try:
        parser.feed(text)
        parser.close()
    except Exception as exc:
        result.errors.append(f"index.html failed to parse: {exc}")
        return result

    n = len(parser.slide_kinds)

    # ─── Skill-agnostic checks (always run) ──────────────────────────────────
    if n < MIN_SLIDES_HARD:
        result.errors.append(
            f'deck has {n} slides; need at least {MIN_SLIDES_HARD} <section class="slide"> blocks.'
        )

    if parser.external_links:
        result.errors.append(
            "deck is not self-contained: external references found: "
            + ", ".join(parser.external_links[:3])
            + (
                f", … (+{len(parser.external_links) - 3} more)"
                if len(parser.external_links) > 3
                else ""
            )