diff --git a/Justfile b/Justfile index d0c9d322..c3e0deba 100644 --- a/Justfile +++ b/Justfile @@ -11,6 +11,12 @@ default: check: #!/usr/bin/env bash set -euo pipefail + # Every tracked shell and Python script is syntax-checked by enumeration, + # not by a list maintained here by hand. That list had fallen six scripts + # behind the tree -- including scripts/resolve-e2e-inputs.py, which decides + # the E2E matrix, and iso/scripts/live-kernel.py, which runs mid-ISO-build + # -- so a parse error in them surfaced minutes into a build instead of here. + python3 scripts/check-script-syntax.py test -f Containerfile test -f packages/bluefin.toml test -f packages/utah.toml @@ -20,9 +26,7 @@ check: grep -q 'enable gdm.service' system_files/shared/usr/lib/systemd/system-preset/85-utah-desktop.preset grep -q 'enable ublue-system-setup.service' system_files/shared/usr/lib/systemd/system-preset/85-utah-desktop.preset test -f scripts/configure-services.sh - bash -n scripts/configure-services.sh test -f scripts/configure-branding.sh - bash -n scripts/configure-branding.sh test -f scripts/verify-desktop-contract.py test -f scripts/verify-gnome-extensions.py test -f contracts/bluefin-desktop.toml @@ -31,7 +35,6 @@ check: # otherwise CI reports every extension as missing while a developer clone # (or the contract workflow's recursive checkout) passes. git submodule update --init --recursive - python3 -m py_compile scripts/verify-desktop-contract.py scripts/verify-gnome-extensions.py python3 scripts/verify-desktop-contract.py --check contracts/bluefin-desktop.toml python3 scripts/verify-gnome-extensions.py --source grep -q '/system_files/bluefin' Containerfile @@ -43,9 +46,6 @@ check: test -f iso/live/src/etc/bootc-installer/images.json test -f iso/live/src/etc/bootc-installer/recipe.json test -f iso/scripts/build-iso.sh - bash -n iso/live/src/configure-live.sh - bash -n iso/live/src/install-flatpaks.sh - bash -n iso/scripts/build-iso.sh python3 -m json.tool iso/live/src/etc/bootc-installer/images.json >/dev/null python3 -m json.tool iso/live/src/etc/bootc-installer/recipe.json >/dev/null grep -q 'org.bootcinstaller.Installer' iso/live/src/install-flatpaks.sh @@ -58,29 +58,19 @@ check: grep -q 'COPY --from=packages /repository /etc/utah-packages' Containerfile # Every executable release asset fetched during composition must be pinned # and verified; no build may resolve a mutable latest release. - python3 -m py_compile scripts/check-download-integrity.py python3 scripts/check-download-integrity.py grep -q '"utah-packages"' scripts/install-packages.py - python3 -m py_compile scripts/install-packages.py - python3 -m py_compile scripts/verify-rpm-contract.py - python3 -m py_compile scripts/check-repo-availability.py python3 scripts/install-packages.py --check packages/bluefin.toml python3 scripts/verify-rpm-contract.py --check packages/bluefin.toml pip install --quiet pyyaml 2>/dev/null || true python3 -m unittest discover -s tests -p 'test_*.py' - bash -n iso/scripts/luks-e2e.sh grep -qE 'reusable-build\.yml@(v1|[0-9a-f]{40} # v1)$' .github/workflows/build.yml test -f Containerfile.kernel - bash -n scripts/install-ogc-kernel.sh - bash -n scripts/install-nvidia.sh - bash -n scripts/clean-stage.sh - bash -n scripts/kernel-cache-tag.sh # The cache image must be built from the same base the image is, or the # prebuilt NVIDIA module would be linked against a kernel this image never # boots. Two literals, one invariant, so assert it rather than trust it. diff <(grep -m1 '^ARG BASE_IMAGE=' Containerfile) \ <(grep -m1 '^ARG BASE_IMAGE=' Containerfile.kernel) - python3 -m py_compile scripts/flavors.py python3 scripts/flavors.py list >/dev/null python3 scripts/check_workflow_outputs.py pip install --quiet jsonschema 2>/dev/null || true diff --git a/docs/skills/ci-workflows.md b/docs/skills/ci-workflows.md index 64e4dc19..000c5add 100644 --- a/docs/skills/ci-workflows.md +++ b/docs/skills/ci-workflows.md @@ -47,7 +47,8 @@ opaque `exit status 71` from the image build (comment, `.github/workflows/build.yml`). It runs three checks: - `just check` -- manifest validation, including the workflow output check - (`scripts/check_workflow_outputs.py`) and the ban on flavor literals in + (`scripts/check_workflow_outputs.py`), the syntax gate + (`scripts/check-script-syntax.py`), and the ban on flavor literals in workflows. - `just check-parity` -- `packages/bluefin.toml` against Bluefin's upstream. - `just check-repos` -- the complete installation transaction against the diff --git a/scripts/check-script-syntax.py b/scripts/check-script-syntax.py new file mode 100755 index 00000000..e25b3162 --- /dev/null +++ b/scripts/check-script-syntax.py @@ -0,0 +1,150 @@ +#!/usr/bin/env python3 +"""Syntax-check every script this repository tracks. + +`just check` is the only source-level gate CI runs before a build starts +(.github/workflows/build.yml). It used to syntax-check scripts by naming them +one at a time, so the set of checked scripts was a hand-maintained list that +nothing compared against the set of scripts that actually exist. Six scripts +had fallen out of that list, including `scripts/resolve-e2e-inputs.py`, which +computes the E2E matrix, and `iso/scripts/live-kernel.py`, which runs in the +middle of an ISO build. A syntax error in any of them surfaced as a failure +minutes into a build or an E2E lane instead of in the gate. + +This module owns that inventory by deriving it: every tracked file that is a +shell or Python script -- by extension, or by shebang for extensionless +executables -- is checked. A script added tomorrow is covered without editing +anything. +""" + +from __future__ import annotations + +import argparse +import py_compile +import subprocess +import sys +import tempfile +from pathlib import Path + +SHELL_SHEBANGS = ("sh", "bash", "dash", "zsh") +PYTHON_SHEBANGS = ("python", "python3") + + +def tracked_files(root: Path) -> list[Path]: + """Every file git tracks, so untracked scratch files are never checked.""" + out = subprocess.run( + ["git", "-C", str(root), "ls-files", "-z"], + check=True, + capture_output=True, + text=True, + ).stdout + return [root / name for name in out.split("\0") if name] + + +def _shebang_interpreter(path: Path) -> str: + try: + with path.open("rb") as handle: + first = handle.readline(256) + except OSError: + return "" + if not first.startswith(b"#!"): + return "" + line = first[2:].decode("utf-8", "replace").strip() + words = line.split() + if not words: + return "" + interpreter = Path(words[0]).name + if interpreter == "env" and len(words) > 1: + interpreter = Path(words[1]).name + return interpreter + + +def classify(path: Path) -> str | None: + """Return "shell", "python", or None for a file that is neither.""" + suffix = path.suffix + if suffix == ".sh": + return "shell" + if suffix == ".py": + return "python" + if suffix: + # A suffixed file that is not .sh/.py is not a script we own; a + # shebang inside e.g. a .service or .conf file is data, not code. + return None + interpreter = _shebang_interpreter(path) + if interpreter in SHELL_SHEBANGS: + return "shell" + if interpreter in PYTHON_SHEBANGS: + return "python" + return None + + +def check_shell(path: Path) -> str | None: + result = subprocess.run( + ["bash", "-n", str(path)], capture_output=True, text=True + ) + if result.returncode == 0: + return None + return (result.stderr or result.stdout).strip() or "bash -n failed" + + +def check_python(path: Path) -> str | None: + # doraise so the error is reported here rather than printed and swallowed; + # a throwaway cfile keeps __pycache__ out of the working tree. + with tempfile.TemporaryDirectory() as tmp: + cfile = Path(tmp) / "out.pyc" + try: + py_compile.compile(str(path), cfile=str(cfile), doraise=True) + except py_compile.PyCompileError as exc: + return str(exc).strip() + return None + + +def main(argv: list[str] | None = None) -> int: + parser = argparse.ArgumentParser(description=__doc__) + parser.add_argument( + "--root", + default=".", + help="repository root to check (default: current directory)", + ) + parser.add_argument( + "--list", + action="store_true", + help="print the scripts that would be checked and exit", + ) + args = parser.parse_args(argv) + + root = Path(args.root).resolve() + scripts: list[tuple[Path, str]] = [] + for path in tracked_files(root): + if not path.is_file(): + continue + kind = classify(path) + if kind is not None: + scripts.append((path, kind)) + scripts.sort() + + if args.list: + for path, kind in scripts: + print(f"{kind}\t{path.relative_to(root)}") + return 0 + + if not scripts: + print("no scripts found to check -- is this a git checkout?", file=sys.stderr) + return 2 + + failures = 0 + for path, kind in scripts: + error = check_shell(path) if kind == "shell" else check_python(path) + if error: + failures += 1 + print(f"{path.relative_to(root)}: {error}", file=sys.stderr) + + if failures: + print(f"{failures} script(s) failed the syntax gate", file=sys.stderr) + return 1 + + print(f"syntax gate: {len(scripts)} script(s) checked") + return 0 + + +if __name__ == "__main__": + sys.exit(main()) diff --git a/tests/test_script_syntax_gate.py b/tests/test_script_syntax_gate.py new file mode 100644 index 00000000..f381d777 --- /dev/null +++ b/tests/test_script_syntax_gate.py @@ -0,0 +1,145 @@ +"""The syntax gate must cover every script, including ones added later. + +The gate replaced a hand-maintained list inside `just check`. These tests +assert the two properties that made the list fail: that the inventory is +derived from the tree rather than restated, and that a broken script actually +fails the gate rather than being skipped. +""" +import importlib.util +import subprocess +import tempfile +import unittest +from pathlib import Path + +ROOT = Path(__file__).resolve().parents[1] + +spec = importlib.util.spec_from_file_location( + "check_script_syntax", ROOT / "scripts" / "check-script-syntax.py" +) +gate = importlib.util.module_from_spec(spec) +spec.loader.exec_module(gate) + + +def git(*args, cwd): + subprocess.run(["git", *args], cwd=cwd, check=True, capture_output=True) + + +class ClassifyTests(unittest.TestCase): + def setUp(self): + self.tmp = tempfile.TemporaryDirectory() + self.addCleanup(self.tmp.cleanup) + self.dir = Path(self.tmp.name) + + def write(self, name, body=""): + path = self.dir / name + path.parent.mkdir(parents=True, exist_ok=True) + path.write_text(body) + return path + + def test_extensions_decide_without_reading_the_file(self): + self.assertEqual(gate.classify(self.write("a.sh")), "shell") + self.assertEqual(gate.classify(self.write("a.py")), "python") + + def test_extensionless_files_are_classified_by_shebang(self): + self.assertEqual( + gate.classify(self.write("hook", "#!/usr/bin/bash\ntrue\n")), "shell" + ) + self.assertEqual( + gate.classify(self.write("tool", "#!/usr/bin/env python3\n")), "python" + ) + + def test_non_scripts_are_skipped(self): + self.assertIsNone(gate.classify(self.write("notes.md", "#!/usr/bin/bash\n"))) + self.assertIsNone(gate.classify(self.write("data", "key=value\n"))) + # A shebang inside a unit file is data the gate must not try to parse. + self.assertIsNone( + gate.classify(self.write("x.service", "#!/usr/bin/bash\n[Unit]\n")) + ) + + +class CheckerTests(unittest.TestCase): + def setUp(self): + self.tmp = tempfile.TemporaryDirectory() + self.addCleanup(self.tmp.cleanup) + self.dir = Path(self.tmp.name) + + def test_broken_shell_is_reported(self): + path = self.dir / "bad.sh" + path.write_text("if true; then\n") + self.assertIsNotNone(gate.check_shell(path)) + + def test_valid_shell_passes(self): + path = self.dir / "ok.sh" + path.write_text("set -e\nif true; then echo hi; fi\n") + self.assertIsNone(gate.check_shell(path)) + + def test_broken_python_is_reported(self): + path = self.dir / "bad.py" + path.write_text("def f(:\n") + self.assertIsNotNone(gate.check_python(path)) + + def test_python_check_leaves_no_pycache(self): + path = self.dir / "ok.py" + path.write_text("x = 1\n") + self.assertIsNone(gate.check_python(path)) + self.assertFalse((self.dir / "__pycache__").exists()) + + +class InventoryTests(unittest.TestCase): + def test_gate_covers_scripts_the_old_hand_list_missed(self): + listed = subprocess.run( + ["python3", str(ROOT / "scripts" / "check-script-syntax.py"), + "--root", str(ROOT), "--list"], + check=True, capture_output=True, text=True, + ).stdout + covered = {line.split("\t", 1)[1] for line in listed.splitlines() if line} + for missed in ( + "scripts/resolve-e2e-inputs.py", + "scripts/update-e2e-readme.py", + "iso/scripts/live-kernel.py", + "iso/scripts/luks-unlock.py", + "iso/scripts/boot-installed.sh", + "scripts/build-gnome-extensions.sh", + "system_files/shared/usr/libexec/bluefin-refresh-stats", + ): + self.assertIn(missed, covered) + + def test_repository_passes_its_own_gate(self): + result = subprocess.run( + ["python3", str(ROOT / "scripts" / "check-script-syntax.py"), + "--root", str(ROOT)], + capture_output=True, text=True, + ) + self.assertEqual(result.returncode, 0, result.stderr) + + def test_a_newly_added_broken_script_fails_the_gate(self): + with tempfile.TemporaryDirectory() as tmp: + repo = Path(tmp) + git("init", "-q", cwd=repo) + (repo / "new.sh").write_text("for x in; do\n") + git("add", "new.sh", cwd=repo) + result = subprocess.run( + ["python3", str(ROOT / "scripts" / "check-script-syntax.py"), + "--root", str(repo)], + capture_output=True, text=True, + ) + self.assertEqual(result.returncode, 1) + self.assertIn("new.sh", result.stderr) + + def test_untracked_files_are_not_checked(self): + with tempfile.TemporaryDirectory() as tmp: + repo = Path(tmp) + git("init", "-q", cwd=repo) + (repo / "kept.sh").write_text("true\n") + git("add", "kept.sh", cwd=repo) + (repo / "scratch.sh").write_text("if true; then\n") + result = subprocess.run( + ["python3", str(ROOT / "scripts" / "check-script-syntax.py"), + "--root", str(repo)], + capture_output=True, text=True, + ) + self.assertEqual(result.returncode, 0, result.stderr) + + +if __name__ == "__main__": + unittest.main()