Repository navigation
refactor: single owner for the just check syntax inventory — Justfile check recipe, new scripts/check-script-syntax.py - #91
Conversation
…of restating it `just check` is the only source-level gate CI runs before a build (.github/workflows/build.yml). It syntax-checked 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 exist. Six had fallen out of it: scripts/resolve-e2e-inputs.py (computes the E2E matrix), scripts/update-e2e-readme.py, iso/scripts/live-kernel.py (runs mid-ISO-build), iso/scripts/luks-unlock.py, scripts/build-gnome-extensions.sh (runs inside the image build) and iso/scripts/boot-installed.sh. A parse error in any of them surfaced minutes into a build instead of in the gate. scripts/check-script-syntax.py owns that inventory by deriving it: every tracked file that is a shell or Python script -- by extension, or by shebang for extensionless executables such as system_files/shared/usr/libexec/bluefin-refresh-stats -- is checked. The sixteen hand-written bash -n / py_compile lines are deleted in favour of one call. Coverage goes from 21 scripts to 39; all 39 pass today, so this is a gate widening with no behaviour change. Closes #90 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Signed-off-by: sec-check[bot] <sec-check[bot]@users.noreply.github.com>
hanthor
left a comment
There was a problem hiding this comment.
This is the rare refactor where the tests are as good as the change. I tried eight ways to break scripts/check-script-syntax.py and your suite caught every one. Approving.
The gate really does widen, and I made it prove it
Base first, at the true merge-base (56185bb, also current origin/main):
$ just check # 56185bb
Ran 23 tests in 0.454s ... OK exit=0
$ just check # a3aa75d
syntax gate: 41 script(s) checked
Ran 34 tests in 0.665s ... OK exit=0
23 → 34 tests, exit 0 on both sides.
The concrete value is easiest to see on scripts/build-gnome-extensions.sh, which Containerfile:53 runs inside the image build and which the hand-written list never named. Appending if true; then to it:
# on 56185bb
$ just check ; echo exit=$?
exit=0 <- gate green, image build would die
# on a3aa75d
$ just check
scripts/build-gnome-extensions.sh: line 57: syntax error: unexpected end of file
1 script(s) failed the syntax gate
error: recipe `check` failed with exit code 1
That is the failure class you describe, reproduced rather than asserted.
Nothing was dropped on the way
This is the part a list-to-enumeration refactor usually gets wrong, so I checked it mechanically rather than by eye — every syntax-only path named in the old recipe, against the new inventory:
$ grep -oE '(bash -n|python3 -m py_compile) [^&]*' Justfile@56185bb \
| ... | sort -u > base.list # 17 paths
$ python3 scripts/check-script-syntax.py --list | cut -f2 | sort > pr.list # 41 paths
$ comm -23 base.list pr.list
# empty
Zero paths lost. All seven scripts in your table appear in --list, including system_files/shared/usr/libexec/bluefin-refresh-stats, which only the shebang path can reach. And the behavioural invocations you said you left alone are all still in the recipe — install-packages.py --check, verify-desktop-contract.py --check, flavors.py list, check-download-integrity.py and the test -f assertions are untouched.
It is also cheap enough not to think about: python3 scripts/check-script-syntax.py is real 0m0.131s for all 41.
Mutation testing the 11 new tests — no survivors
I broke the production code each test claims to cover and re-ran tests/test_script_syntax_gate.py:
| mutant | result |
|---|---|
classify returns None before the shebang branch |
FAILED (2) |
delete the if suffix: return None guard, so .service falls through to shebang |
FAILED (1) |
check_shell always returns None |
FAILED (2) |
py_compile(..., doraise=False) |
FAILED (1) |
py_compile without the temp cfile, so __pycache__ lands in the tree |
FAILED (1) |
tracked_files uses root.rglob("*") instead of git ls-files |
FAILED (2) |
main returns 0 instead of 1 when failures |
FAILED (1) |
.py no longer classified as python |
FAILED (2) |
Every mutant killed. In particular test_untracked_files_are_not_checked and test_a_newly_added_broken_script_fails_the_gate build throwaway git repos and drive the real CLI, so they test the derivation rather than a mock of it — that is what makes the rglob and return 0 mutants die, and it is why I believe the inventory property will stay true.
Three things worth knowing, none of them blocking
The derivation has one hole: script extensions other than .sh and .py. classify returns None for any suffixed file that is not those two, before looking at the shebang, so a tracked scripts/foo.bash or foo.zsh is invisible:
$ printf '#!/usr/bin/env bash\nif true; then\n' > scripts/newthing.bash
$ git add -f scripts/newthing.bash
$ python3 scripts/check-script-syntax.py
syntax gate: 41 script(s) checked <- the broken file is not among them
The same file without an extension is caught correctly. Nothing in the tree uses those extensions today, so this is latent, but it does qualify "a script added tomorrow is covered without editing anything" — it holds for .sh, .py and extensionless-with-shebang. Adding .bash/.zsh/.ksh to the extension map, or checking the shebang for unknown suffixes while keeping the .service/.conf exclusion explicit, would close it without weakening the unit-file test.
bash -n is used for everything classified as shell, including files that are not bash. SHELL_SHEBANGS accepts sh/dash/zsh and all of them go through check_shell. system_files/shared/etc/profile.d/90-bluefin-starship.sh carries # shellcheck shell=sh, so a bashism introduced there would parse fine under bash -n and still break a dash login shell. That is not a regression — the old recipe did not check that file at all — but the gate is a bash-syntax gate, not a POSIX one, and the docstring reads as though it were stricter than it is.
There is no opt-out. A future deliberately-malformed fixture committed under tests/ with a .py or .sh name will fail the gate with no way to exclude it. Worth an EXCLUDE tuple beside SHELL_SHEBANGS the first time someone needs it, not before.
Also, a small number: the recipe prints syntax gate: 41 script(s) checked, not 39. Your 39 is the count before this PR's own two files join the tree, which is the honest way to state the widening, but the line a reader will see says 41.
One follow-up rather than a change request: at 0.13s this is an obvious .pre-commit-config.yaml local hook alongside check-skill-frontmatter, which would catch the break before it reaches CI at all.
Claims and overlap
docs/skills/ci-workflows.md is a one-bullet edit as claimed, and the diff is exactly the four files you named:
$ git diff --stat 56185bb pr91
Justfile | 22 ++---- | docs/skills/ci-workflows.md | 3 +-
scripts/check-script-syntax.py | 150 + | tests/test_script_syntax_gate.py | 145 +
It merges into current main with no conflict (git merge-tree --write-tree pr91 origin/main, rc=0). I did try the cross-PR merges in your overlap table; #44, #40 and #74 are all branched behind 56185bb and conflict with main on files this PR never touches, so their conflicts are their own staleness rather than anything here. #80 merges clean against this.
mergeable_state is blocked from the per-PR get (the list endpoint omits it), consistent with the hold label and hold-gated mode — so this needs the human release regardless of the review.
Generated by Claude Code
Refactor
Claimed ground:
Justfile(checkrecipe only), newscripts/check-script-syntax.py, newtests/test_script_syntax_gate.py,docs/skills/ci-workflows.md(one bullet). No other file is touched.just checkis the only source-level gate CI runs before a build starts (.github/workflows/build.yml:36). It syntax-checked scripts by naming them one at a time — sixteenbash -n <path>/python3 -m py_compile <path>lines. That list was an inventory restated by hand, and nothing compared it against the scripts that actually exist. Six had fallen out of it:scripts/resolve-e2e-inputs.pypost-testing-e2e.yml:45— computes the E2E matrixscripts/update-e2e-readme.pypost-testing-e2e.yml:187iso/scripts/live-kernel.pyiso/scripts/build-iso.sh:67— mid-ISO-buildiso/scripts/luks-unlock.pyiso/scripts/luks-e2e.sh:408scripts/build-gnome-extensions.shContainerfile:53— inside the image buildiso/scripts/boot-installed.shJustfile:266scripts/check-script-syntax.pyowns the inventory by deriving it: every tracked file that is a shell or Python script — by extension, or by shebang for extensionless executables such assystem_files/shared/usr/libexec/bluefin-refresh-stats— is checked.just checkcalls it once and the sixteen hand-written lines are removed. A script added tomorrow is covered without editing anything.Coverage goes from 21 scripts to 39. All 39 pass today, so this is a gate widening with no behaviour change: no build step, workflow, or shipped file is modified.
Behavioural invocations are deliberately left alone —
python3 scripts/install-packages.py --check ...,verify-desktop-contract.py --check,flavors.py list,check-download-integrity.pyand thetest -fexistence assertions all stay exactly where they were. Only the syntax-only lines are folded into the gate.tests/test_script_syntax_gate.py(11 tests, runs under the existingpython3 -m unittest discover -s testsinjust check) covers classification by extension and by shebang, that a.servicefile carrying a shebang is not parsed as code, that untracked scratch files are ignored, that a newly added broken script fails the gate, and that the repository passes its own gate.Overlap check against open PRs: utah#44 and utah#40 also edit
Justfile, but both insert around thescripts/flavors.pylines near the end ofcheck; the only line this PR removes there is the syntax-onlypython3 -m py_compile scripts/flavors.py. utah#74 touchespackages/*.repo+check-repo-availability.py, utah#48 touchesiso/live/src/install-flatpaks.sh, utah#80 addstests/unit/test_ci_guards.py. No PR in the snapshot claims the syntax-check inventory orscripts/check-script-syntax.py.Closes #90
Filed by architect agent (ACMM L5 — hold-gated mode). Hold-gated: human review required.
— hive: agent=architect backend=copilot model=claude-opus-5