run.py

"""
06 -- validate-gate

A CI-style pre-send gate: run inky.validate() over a template and block
a send if it has any *error*-severity diagnostic (warnings are reported
but don't block). validate_or_fail() below is the reusable gate -- copy
it straight into a CI step or a pre-send hook.

RUNNER SEAM -- read this before changing how this file is invoked:
  - `python3 run.py <path> [<path> ...]` is the REAL gate. It calls
    validate_or_fail() on the given paths, which exits the process with
    1 if any of them has an error, or lets it fall through to exit 0
    otherwise. verify.py always invokes this file with explicit argv
    paths so it observes true exit codes (bad.inky alone -> exit 1,
    good.inky alone -> exit 0).
  - `python3 run.py` with NO args is the suite-runner path (this is what
    `make examples` / run_all.py calls for every example). This example's
    whole point is to demonstrate a FAILING gate, but run_all.py runs
    every example unconditionally, so the no-args branch demonstrates
    BOTH good.inky (passes) and bad.inky (fails) by hand -- printing
    diagnostics and the exit code the gate WOULD have produced for each --
    without ever calling sys.exit(1) itself. It always exits 0. (run_all.py
    also carries a matching exemption comment for this example,
    belt-and-suspenders.)
"""

import os
import sys

sys.path.insert(0, os.path.normpath(os.path.join(os.path.dirname(__file__), "..", "..")))
import bootstrap  # noqa: E402
import inky  # noqa: E402

THIS_DIR = os.path.dirname(os.path.abspath(__file__))
dist = bootstrap.inky_example("06-validate-gate")


def report_diagnostics(path: str) -> bool:
    """
    Validate one template and print its diagnostics grouped by severity.
    Returns True iff it has at least one error-severity diagnostic.
    """
    with open(path, encoding="utf-8") as f:
        html = f.read()
    diagnostics = inky.validate(html)

    errors = [d for d in diagnostics if d["severity"] == "error"]
    warnings = [d for d in diagnostics if d["severity"] == "warning"]

    print(f"{os.path.basename(path)}:")
    for d in errors:
        print(f"  ERROR   [{d['rule']}] {d['message']}")
    for d in warnings:
        print(f"  WARNING [{d['rule']}] {d['message']}")
    if not diagnostics:
        print("  (clean)")

    return len(errors) > 0


def validate_or_fail(paths) -> None:
    """
    The reusable pre-send gate. Validate every path, print diagnostics for
    each, and exit(1) as soon as it's known at least one has an error.
    """
    has_errors = False
    for path in paths:
        if report_diagnostics(path):
            has_errors = True
    if has_errors:
        sys.exit(1)


arg_paths = sys.argv[1:]

if arg_paths:
    # Real invocation: exactly what a CI step or pre-send hook would run.
    validate_or_fail(arg_paths)
    print("gate: passed")
    with open(os.path.join(dist, "report.txt"), "w", encoding="utf-8") as f:
        f.write("gate: passed for " + ", ".join(os.path.basename(p) for p in arg_paths) + "\n")
    sys.exit(0)

# No-args demo path -- see the header comment above.
good = os.path.join(THIS_DIR, "good.inky")
bad = os.path.join(THIS_DIR, "bad.inky")

good_failed = report_diagnostics(good)
print("  -> gate would exit " + ("1 (blocked)" if good_failed else "0 (passed)") + "\n")

bad_failed = report_diagnostics(bad)
print("  -> gate would exit " + ("1 (blocked)" if bad_failed else "0 (passed)"))

with open(os.path.join(dist, "report.txt"), "w", encoding="utf-8") as f:
    f.write(f"good.inky would exit {1 if good_failed else 0}\n")
    f.write(f"bad.inky would exit {1 if bad_failed else 0}\n")