diff --git a/.clang-format b/.clang-format new file mode 100644 index 0000000..c82ee1e --- /dev/null +++ b/.clang-format @@ -0,0 +1,19 @@ +--- +BasedOnStyle: LLVM +Language: Cpp +Standard: c++17 +ColumnLimit: 100 +IndentWidth: 4 +InsertBraces: true +ContinuationIndentWidth: 4 +UseTab: Never +BreakBeforeBraces: Attach +AllowShortBlocksOnASingleLine: Never +AllowShortCaseLabelsOnASingleLine: false +AllowShortEnumsOnASingleLine: false +AllowShortFunctionsOnASingleLine: None +AllowShortIfStatementsOnASingleLine: Never +AllowShortLoopsOnASingleLine: false +BinPackArguments: false +BinPackParameters: false +SortIncludes: Never diff --git a/AGENTS.md b/AGENTS.md index b2022d5..27f7093 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -287,6 +287,12 @@ Exact UI strings, user data, identifiers, commands, paths, protocol fields, version/status markers, citations, and historical evidence are not translated merely to satisfy the prose-language rule. +Production code, tests, fixtures expressed as source, and repository tooling +must remain readable by a human reviewer. Do not compress functions, control +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. + Canonical documents: - `README.md`; diff --git a/CHANGELOG.md b/CHANGELOG.md index 406c7c9..903dc53 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,12 @@ ## Unreleased — 0.1.2 +- Normalized the recent synchronization, generation-MTP, Android backup, + Web Dashboard serialization, tests, I/O doubles and packaging code for human + readability. Added scoped C formatting rules and review guidance without + changing synchronization protocols, assertions, deployment state or runtime + behavior. + - Added the production libudev/libmtp generation adapter with bounded peer selection, object transfer and manifest-last publication; wired the trusted orchestrator mode and proved the full Firefox/Android/desktop conversation diff --git a/docs/coding_style.md b/docs/coding_style.md index 8fcf9a1..61874fa 100644 --- a/docs/coding_style.md +++ b/docs/coding_style.md @@ -6,6 +6,11 @@ Code must optimize for readability, correctness, and maintainability. Avoid clever code when a straightforward implementation is easier to verify. +These rules apply equally to production code, tests, I/O doubles, migration +bridges, and repository tooling. Code must not be manually compacted to save +lines or prompt tokens. A grouped mission remains compatible with small, +reviewable commits. + ## 2. C standard The TUI uses C17. @@ -91,11 +96,33 @@ Good: ## 6. Formatting -The repository currently has no canonical `.clang-format` file. Do not apply a -bulk formatter with tool-default behavior; introducing a format definition and -any broad normalization requires a dedicated, reviewable change. +The repository `.clang-format` defines the C presentation used by normalized +files. It targets 100 columns, four-space indentation, one statement per line, +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. -Formatting changes should not be mixed with unrelated semantic changes when avoidable. +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: + +```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 +``` + +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. ## 7. Error handling @@ -130,3 +157,7 @@ The Android side should favor: - small view models; - no unnecessary framework abstraction; - clear serialization types matching the Trainlog JSON contract. + +Python and Kotlin follow the same human-readability requirement: avoid +single-line compound statements, compressed exception handling, and opaque +chains of unrelated mutations. Formatters are aids, not substitutes for review. diff --git a/docs/current_state.md b/docs/current_state.md index be9e822..ec72f39 100644 --- a/docs/current_state.md +++ b/docs/current_state.md @@ -10,6 +10,12 @@ and deployment are not complete. Snapshot date: **2026-09-17**. +`TRAINLOG_CODE_READABILITY_V1` normalizes the recent generation-MTP, +generation/ACK, Android-backup, Web Dashboard serialization, tests, doubles and +packaging workflows without changing their contracts. The scoped C formatter +check is canonical for those files only; it does not claim that the historical +repository has been globally reformatted. + This document owns the current implemented state. Historical checkpoints and closed incidents belong in [reviews](reviews/) and the [changelog](../CHANGELOG.md). diff --git a/docs/tests.md b/docs/tests.md index 527a768..1a97578 100644 --- a/docs/tests.md +++ b/docs/tests.md @@ -1307,3 +1307,19 @@ the analogous test on the exact schema-v17 source and feeds its archive to These are software proofs. They do not claim physical USB/MTP behavior, installation over the signed release, a real user backup, or a real-device restore. + +## Readability validation + +The normalized C scope is checked non-mutatively with the explicit +`clang-format --dry-run --Werror` command in `docs/coding_style.md`. Clang C17, +the normal Meson inventory and the ASan/UBSan inventory preserve the existing +behavioral assertions. Python syntax/orchestrator tests, Android generation and +backup tests, the I/O-boundary MTP browser proof, JSON/import validators and +the isolated harness cover the other normalized sources. + +GCC 16.2.1 now compiles beyond the former `misleading-indentation` failures in +`json_writer.c`, `web_dashboard_json.c`, `web_dashboard.c`, +`dashboard_layout.c`, and `generation_mtp.c`. The separate strict build remains +blocked by distinct pre-existing `format-truncation` diagnostics in the Web +accepted-response buffer and bounded test path buffers. Warning policy remains +unchanged; GCC is not reported as green.