[JarryShaw]

• Searched for similar pull requests
• Followed the coding style (make pylint, make mypy, make isort)
• make test passes, and a test case covers the change
• Added a changelog entry — N/A — centralised in docs(changelog): shared 1.5.0 changelog — long-lived, merges last (#610, #616, #617, #618, #620) #657

What is the purpose of your pull request?

• refactor — restructures code without changing behaviour

---

Description of your pull request and other information

The first PR for #2047 (owner's ruling: option (a)).

• New util/_actions.py: standard library only and 3.7-syntax. It provides annotation/annotate, group, set_output (with the heredoc form for multiline values), summary/open_summary, say/emit, exit_status and run. The tee-to-log that pip_install and regenerate_samples both copied becomes run. Escaping follows GitHub's workflow-commands reference.
• Scripts moved onto it: apt_packages, classify_changes, coverage_report, leg_summary, pip_install, regenerate_samples and vendor_code_changed. Each keeps its exact output, with escape=False where a script escapes its own way. On /usr/bin/python3.7, main's and this branch's copies gave byte-identical stdout, stderr, exit code, outputs file and summary file on 10 cases.
• Not moved yet:
  • The annotations in apt_packages, leg_summary and coverage_report stay literal (marked #2047). ci: a failed KTLO leg turns main and pull requests red; report it as a warning and exit 0 #1672's KTLO guard (commands() in test_ktlo_legs_stay_green_1672.py) reads literal print('::level text, and routing them through the helper would blind it. Teaching the guard to see _actions.annotate comes next.
  • verdict_covers_checkout.py, superseded.py and project_status.py are left out: each runs from a single-file checkout or download.
• Tests: the new tests/project/test_actions_helper_2047.py checks the stdlib-only and 3.7-parse rules, the exact output and escaping, and that every migrated script loads both as util.x and from its file path. It errors without the helper and passes here (21 passed). Every existing test of the migrated scripts passes unchanged, and none was edited.

[JarryShaw]

GOOD TO GO at 17c9c8692 (Sonnet cross-review). The reviewer confirmed:

• Behaviour unchanged: byte-identical exit code, stdout, stderr, outputs file and summary file on 43 adversarial cases each under 3.7 and 3.14. These covered unset and empty env vars, a signal-killed subprocess, non-UTF-8 bytes, %, :, , and \n in leg names, and LC_ALL=C.
• Escaping: matches escapeData/escapeProperty in @actions/core.
• Imports: every caller runs the script from a full checkout as python util/x.py.
• KTLO guard: ci: a failed KTLO leg turns main and pull requests red; report it as a warning and exit 0 #1672's guard loses nothing on any script a KTLO step runs.

Being tightened before ready: the new test's 3.7 check lets f"{x=}" through, and its stdlib check uses the running interpreter's module list, so tomllib passes. It also never runs a script as python util/x.py. The worker is fixing all three, and this will get a delta re-review.

[JarryShaw]

Pushed 967d90722 (was 17c9c8692). This tightens the new test, which now checks for real that the helper is safe on 3.7 and standard library only:

• Imports: the helper's imports are checked against a fixed list of modules that exist on 3.7.
• f-strings: a tokenize check rejects f"{x=}".
• Scripts run for real: each migrated script is run as python util/<script>.py and must import _actions from util/.
• Output: set_output takes the multiline form for \r as well as \n.

Each check fails on a planted violation; I re-planted tomllib and f"{os=}" myself, and both failed. Delta re-review in progress.

[JarryShaw]

GOOD TO GO at 967d90722 (Sonnet delta re-review). The reviewer seeded one violation for each new check and saw each one fail:

• Import allowlist: a function-local import tomllib fails the import check.
• f-string check: f"{x=}" fails the tokenize check, which flags the = forms and spares ==, walrus and :=^5. Its skip below 3.12 only affects experimental legs, since LATEST runs on the newest CPython.
• Subprocess test: forcing from util import _actions fails it, so it tells the two import branches apart.

No set_output caller can produce \r, so no output changes. With the KTLO guard and apt tests: 83 passed.

[JarryShaw]

should we separate action helper scripts from other project maintenance scripts in the util folder? or everything is actually already action helpers?

[JarryShaw]

Almost everything in util/ already is an Actions helper. Of the scripts on main, every one but pyshark_encap_map.py is invoked by a workflow. They fall into two groups:

• Actions plumbing, reading or writing GITHUB_*: apt_packages, ci_timing, classify_changes, coverage_report, discussion_report, leg_summary, project_status, python_versions, superseded, update_python_versions, vendor_code_changed, vendor_test_gate, verdict_covers_checkout.
• Dual-use: run by workflows, but also run by hand. bump_version, cap_file_size, changelog_md, conda-build, conda_vendor, pip_install, pytest_shards, regenerate_samples, run_unittest_leg, wheel_rename. For example, run_unittest_leg is how the ordering check runs locally.

So the line between the groups would be fuzzy, and a move costs churn everywhere: every run: python util/x.py, every util.x import in tests, the sparse checkouts and the single-file download in project-status.yml, plus _actions' import path.

Needs you:

• (a) Recommended: keep util/ flat. Give workflows.rst's scripts table a column saying whether each script is CI-only or also run by hand.
• (b) Split into util/ci/ for the plumbing, with _actions.py alongside, and leave util/ for the dual-use scripts. That would be its own issue, after refactor(util): share one stdlib-only Actions helper across the CI scripts (#2047) #2050 lands.

This PR is ready to merge either way.

[JarryShaw]

take (a)

[JarryShaw]

Recorded: (a). util/ stays flat. The scripts table in workflows.rst gains a column saying whether each script is CI-only or also run by hand. This PR adds its own row to that table, so I will make the column change as a docs-only follow-up once this merges, rather than move this head.

[github-actions]

Coverage: 91.54% (unit tier, Python 3.15, 967d90722, Unit Tests run success)

Package	Statements	Missed	Branches	Partial	Cover
pcapkit (top level)	104	4	20	2	95.16%
pcapkit/const	19599	881	2618	867	92.11%
pcapkit/corekit	2567	71	816	37	96.57%
pcapkit/dumpkit	282	3	102	3	98.44%
pcapkit/foundation	2930	23	1022	25	98.79%
pcapkit/interface	138	4	52	3	96.32%
pcapkit/protocols	17436	219	4582	185	98.15%
pcapkit/toolkit	872	36	298	10	95.21%
pcapkit/utilities	529	7	160	5	98.26%
pcapkit/vendor	4431	1995	1018	167	51.73%

Per-file detail: the coverage-html artifact of this run.

[JarryShaw]

Ordering check on 967d90722: the project leg (util/run_unittest_leg.py project) ran 1867 tests, OK (71 skipped). CI: 61 checks green, 0 failing. KTLO 3.8, 3.9 and 3.10 legs: 0 failing tests. Ready to merge. The workflows.rst column from your ruling follows as a docs-only change once this lands.