Skip to content
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
22 changes: 6 additions & 16 deletions Justfile
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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
Expand Down
3 changes: 2 additions & 1 deletion docs/skills/ci-workflows.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
150 changes: 150 additions & 0 deletions scripts/check-script-syntax.py
Original file line number Diff line number Diff line change
@@ -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())
145 changes: 145 additions & 0 deletions tests/test_script_syntax_gate.py
Original file line number Diff line number Diff line change
@@ -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()
Loading