Skip to content

Navigation Menu

Sign in
Sign up

ci: emit the gate status check this repo is required to produce #25

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
noahgift merged 1 commit into master from ci/emit-gate-context
Aug 28, 2026
Merged
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
41 changes: 41 additions & 0 deletions .github/workflows/gate.yml
View file Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,41 @@
# Emits the `gate` status check required by the paiml org ruleset "Green Main".
#
# Without a job whose NAME is literally `gate`, every PR in this repo reports
# mergeStateStatus: BLOCKED while every visible check is green -- the missing
# context is one the repo cannot produce, so no contributor can unblock it.
#
# The job name below IS the status-check context. Renaming it to something
# friendlier silently re-breaks merging for the whole repo.
name: Gate

on:
pull_request:
push:
branches: [master]

permissions:
contents: read

jobs:
gate:
name: gate
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4

- uses: actions/setup-python@v5
with:
python-version: '3.11'

- name: Install YAML parser
run: python3 -m pip install --quiet pyyaml

# Probe the instrument before trusting it: every checker is fed an input
# it MUST reject. A checker that cannot fail would make this gate a green
# light that measures nothing.
- name: Gate self-test (every checker must reject a broken fixture)
run: python3 ci/gate.py --self-test

# Each check prints its denominator and fails when it inspected 0 files.
- name: Gate checks
run: python3 ci/gate.py
211 changes: 211 additions & 0 deletions ci/gate.py
View file Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,211 @@
#!/usr/bin/env python3
"""Repository gate: checks that the book's example sources are still parseable.

This repo has no build and no test suite -- it is the source listing for
*Python for DevOps*. So the gate checks what the repo actually IS: Python
examples, notebooks, shell scripts, Kubernetes/CI YAML and JSON that a reader
is expected to be able to run.

Two rules keep this from becoming a green light that means nothing:

* Every check prints its DENOMINATOR ("checked N files") and FAILS when N is
zero. A check that silently inspected nothing must never read as a pass.
* `--self-test` feeds every checker a deliberately broken fixture and fails
unless the checker rejects it. A checker that cannot fail is not a check.

Usage:
python3 ci/gate.py --self-test # prove the instruments can fail
python3 ci/gate.py # run the checks against the repo
"""

from __future__ import annotations

import argparse
import ast
import json
import subprocess
import sys
import tempfile
from pathlib import Path

# Vendored JS dependencies are not ours to lint.
EXCLUDE_SUBSTRINGS = ("node_modules/",)
# Helm chart templates are Go text/template, not YAML, and do not parse as YAML.
YAML_EXCLUDE_SUBSTRINGS = EXCLUDE_SUBSTRINGS + ("/templates/",)


def tracked(*globs: str, exclude: tuple[str, ...] = EXCLUDE_SUBSTRINGS) -> list[str]:
"""Files git tracks matching any glob, minus vendored/templated paths."""
out = subprocess.run(
["git", "ls-files", "-z", "--", *globs],
capture_output=True,
text=True,
check=True,
).stdout
files = [f for f in out.split("0円") if f]
return sorted(f for f in files if not any(x in f for x in exclude))


# --- checkers -------------------------------------------------------------
# Each returns a list of "path: reason" strings; empty means the file is fine.


def check_python(path: str) -> list[str]:
try:
ast.parse(Path(path).read_bytes(), filename=path)
except SyntaxError as exc:
return [f"{path}: line {exc.lineno}: {exc.msg}"]
return []


def _cells_error(cells: list) -> str | None:
bad = [
i
for i, cell in enumerate(cells)
if not isinstance(cell, dict) or "cell_type" not in cell
]
return f"cell {bad[0]} has no 'cell_type'" if bad else None


def _notebook_error(doc: object) -> str | None:
if not isinstance(doc, dict):
return f"top level is {type(doc).__name__}, expected object"
if "nbformat" not in doc:
return "missing 'nbformat' key"
if not isinstance(doc.get("cells"), list):
return "'cells' is missing or not a list"
return _cells_error(doc["cells"])


def check_notebook(path: str) -> list[str]:
try:
doc = json.loads(Path(path).read_text(encoding="utf-8"))
except (ValueError, UnicodeDecodeError) as exc:
return [f"{path}: not valid JSON: {exc}"]
error = _notebook_error(doc)
return [f"{path}: {error}"] if error else []


def check_shell(path: str) -> list[str]:
proc = subprocess.run(
["bash", "-n", path], capture_output=True, text=True, check=False
)
if proc.returncode != 0:
detail = (proc.stderr or proc.stdout).strip().splitlines()
return [f"{path}: {detail[0] if detail else 'bash -n failed'}"]
return []


def check_yaml(path: str) -> list[str]:
import yaml # imported lazily so --self-test can report a clear error

try:
list(yaml.safe_load_all(Path(path).read_text(encoding="utf-8")))
except (yaml.YAMLError, UnicodeDecodeError) as exc:
return [f"{path}: {str(exc).splitlines()[0]}"]
return []


def check_json(path: str) -> list[str]:
try:
json.loads(Path(path).read_text(encoding="utf-8"))
except (ValueError, UnicodeDecodeError) as exc:
return [f"{path}: {exc}"]
return []


CHECKS = (
# name, checker, globs, exclude, broken fixture (suffix, bytes)
(
"python-syntax",
check_python,
("*.py",),
EXCLUDE_SUBSTRINGS,
(".py", "def broken(:\n"),
),
(
"notebook-structure",
check_notebook,
("*.ipynb",),
EXCLUDE_SUBSTRINGS,
(".ipynb", '{"nbformat": 4, "cells": "not-a-list"}'),
),
(
"shell-syntax",
check_shell,
("*.sh",),
EXCLUDE_SUBSTRINGS,
(".sh", "if true; then\n echo unterminated\n"),
),
(
"yaml-parse",
check_yaml,
("*.yml", "*.yaml"),
YAML_EXCLUDE_SUBSTRINGS,
(".yaml", "a:\n - b\n c: broken indent\n"),
),
(
"json-parse",
check_json,
("*.json",),
EXCLUDE_SUBSTRINGS,
(".json", '{"trailing": "comma",}'),
),
)


def self_test() -> int:
"""Prove every checker rejects an input it must reject."""
failures = 0
with tempfile.TemporaryDirectory() as tmp:
for name, checker, _globs, _exclude, (suffix, payload) in CHECKS:
fixture = Path(tmp) / f"broken{suffix}"
fixture.write_text(payload, encoding="utf-8")
problems = checker(str(fixture))
if problems:
print(f" ok {name}: rejected its broken fixture")
else:
print(f" FAIL {name}: ACCEPTED a broken fixture -- checker is inert")
failures += 1
print(f"self-test: probed {len(CHECKS)} checkers, {failures} inert")
return 1 if failures else 0


def _run_one(spec) -> bool:
"""Run one check. Returns True only if it inspected files and all passed."""
name, checker, globs, exclude, _fixture = spec
files = tracked(*globs, exclude=exclude)
problems = [problem for path in files for problem in checker(path)]
passed = bool(files) and not problems
label = "ok " if passed else "FAIL"
print(f" {label} {name}: checked {len(files)} files, {len(problems)} bad")
if not files:
print(" -> inspected 0 files; that is a failure, not a pass")
for problem in problems:
print(f" -> {problem}")
return passed


def run_checks() -> int:
failed = sum(1 for spec in CHECKS if not _run_one(spec))
print(f"gate: ran {len(CHECKS)} checks, {failed} failed")
return 1 if failed else 0


def main() -> int:
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument(
"--self-test",
action="store_true",
help="assert every checker rejects a deliberately broken fixture",
)
args = parser.parse_args()
if args.self_test:
print("== gate self-test: can each checker fail? ==")
return self_test()
print("== gate: repository checks ==")
return run_checks()


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

AltStyle によって変換されたページ (->オリジナル) /