Skip to content

refactor: single owner for the just check syntax inventory — Justfile check recipe, new scripts/check-script-syntax.py - #91

Merged
hanthor merged 1 commit into
mainfrom
arch/script-syntax-gate
Sep 18, 2026
Merged

hanthor merged 1 commit into
mainfrom
arch/script-syntax-gate

Conversation

@hivecommons-hive

Copy link
Copy Markdown
Contributor

Refactor

Claimed ground: Justfile (check recipe only), new scripts/check-script-syntax.py, new tests/test_script_syntax_gate.py, docs/skills/ci-workflows.md (one bullet). No other file is touched.

just check is 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 — sixteen bash -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:

script where it runs
scripts/resolve-e2e-inputs.py post-testing-e2e.yml:45 — computes the E2E matrix
scripts/update-e2e-readme.py post-testing-e2e.yml:187
iso/scripts/live-kernel.py iso/scripts/build-iso.sh:67 — mid-ISO-build
iso/scripts/luks-unlock.py iso/scripts/luks-e2e.sh:408
scripts/build-gnome-extensions.sh Containerfile:53 — inside the image build
iso/scripts/boot-installed.sh Justfile:266

scripts/check-script-syntax.py owns the 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. just check calls 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.py and the test -f existence 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 existing python3 -m unittest discover -s tests in just check) covers classification by extension and by shebang, that a .service file 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 the scripts/flavors.py lines near the end of check; the only line this PR removes there is the syntax-only python3 -m py_compile scripts/flavors.py. utah#74 touches packages/*.repo + check-repo-availability.py, utah#48 touches iso/live/src/install-flatpaks.sh, utah#80 adds tests/unit/test_ci_guards.py. No PR in the snapshot claims the syntax-check inventory or scripts/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

…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>
@hivecommons-hive hivecommons-hive Bot added hold Indicates that a PR should not merge because someone has issued a /hold command. architecture agent/architect Filed or owned by the architect agent. labels Sep 16, 2026

@hanthor hanthor left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

@hivecommons-hive hivecommons-hive Bot added the agent/scanner Filed or owned by the scanner agent. label Sep 17, 2026
@hivecommons-hive hivecommons-hive Bot changed the title [architect] refactor: single owner for the just check syntax inventory — Justfile check recipe, new scripts/check-script-syntax.py refactor: single owner for the just check syntax inventory — Justfile check recipe, new scripts/check-script-syntax.py Sep 17, 2026
@hanthor
hanthor merged commit b1a99a8 into main Sep 18, 2026
14 checks passed
@hanthor
hanthor deleted the arch/script-syntax-gate branch September 18, 2026 06:01
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

agent/architect Filed or owned by the architect agent. agent/scanner Filed or owned by the scanner agent. hold Indicates that a PR should not merge because someone has issued a /hold command.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[architect] just check syntax-check inventory is hand-maintained and six scripts behind the tree

1 participant