diff --git a/AGENTS.md b/AGENTS.md index 3c299d3..32af629 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -294,6 +294,11 @@ flow, declarations, assertions, or cleanup onto one line to reduce line or token count. Grouped missions may and should use small comprehensible commits. Perform an explicit readability review before the final commit. +Readable source is a blocking acceptance criterion. Every new or modified C/H +file must pass the changed-file `clang-format` check; tests and fixtures follow +the same rule. Run `tools/check_changed_c_format.sh ` without +formatting unrelated historical files. + Canonical documents: - `README.md`; diff --git a/docs/coding_style.md b/docs/coding_style.md index 61874fa..3cf3088 100644 --- a/docs/coding_style.md +++ b/docs/coding_style.md @@ -102,24 +102,21 @@ explicit control-flow braces, vertical long parameter lists, and no short function or control body on one line. Contract literals may exceed the target when splitting them would make the protocol less reviewable. -Do not apply the formatter blindly to the entire historical tree. A change -normalizes the files it owns and checks that explicit scope. The reproducible, -non-mutating check for the currently normalized C readability scope is: +Readable source is a blocking acceptance criterion. Do not compress source to +save lines or model tokens. Tests and fixtures follow the same standard. + +Do not apply the formatter blindly to the entire historical tree. Format the +new or modified regions, then use the reproducible, non-mutating changed-file +gate with the branch base revision: ```bash -clang-format --dry-run --Werror \ - tui/src/dashboard_layout.c \ - tui/src/generation_mtp.c \ - tui/src/json_writer.c \ - tui/src/web_dashboard.c \ - tui/src/web_dashboard_json.c \ - tui/include/trainlog/generation_mtp.h \ - tui/tools/generation_mtp_adapter.c \ - tui/tests/generation_mtp_adapter_double.c \ - tui/tests/test_generation_mtp.c \ - tui/tests/test_web_server.c +tools/check_changed_c_format.sh main ``` +The helper derives the merge-base, includes changed and untracked C/H files, +and invokes `clang-format --dry-run --Werror` without modifying them. A +different base revision may be supplied for stacked work. + Formatting changes should not be mixed with unrelated semantic changes when avoidable. Review readability explicitly before the final commit, including tests and cleanup/error paths. diff --git a/tools/check_changed_c_format.sh b/tools/check_changed_c_format.sh new file mode 100755 index 0000000..6b66b49 --- /dev/null +++ b/tools/check_changed_c_format.sh @@ -0,0 +1,25 @@ +#!/bin/sh +# Check only C and header files changed from a caller-selected Git base. + +set -eu + +base_ref=${1:-main} +base_commit=$(git merge-base HEAD "$base_ref") +temporary_list=$(mktemp) +trap 'rm -f "$temporary_list"' EXIT HUP INT TERM + +{ + git diff --name-only --diff-filter=ACMR "$base_commit" -- '*.c' '*.h' + git ls-files --others --exclude-standard -- '*.c' '*.h' +} | sort -u >"$temporary_list" + +if [ ! -s "$temporary_list" ]; then + echo "CHANGED_C_FORMAT=PASS (no changed C/H files)" + exit 0 +fi + +while IFS= read -r source_file; do + clang-format --dry-run --Werror "$source_file" +done <"$temporary_list" + +echo "CHANGED_C_FORMAT=PASS"