diff --git a/.github/workflows/formatter-config.yml b/.github/workflows/formatter-config.yml new file mode 100644 index 0000000000..6715a8b275 --- /dev/null +++ b/.github/workflows/formatter-config.yml @@ -0,0 +1,36 @@ +name: Formatter configuration +on: + pull_request: + paths: + - '.uncrustify.cfg' + - 'devtools/format/**' + - 'SerialPrograms/CMakeLists.txt' + - 'SerialPrograms/cmake/Formatting.cmake' + - 'SerialPrograms/cmake/RunFormatting.cmake' + - '.github/workflows/formatter-config.yml' + workflow_dispatch: +permissions: + contents: read +jobs: + config-tests: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v7 + - uses: actions/setup-python@v6 + with: + python-version: '3.12' + - name: Build pinned Uncrustify + shell: bash + working-directory: ${{ runner.temp }} + run: | + curl --fail --location --silent --show-error \ + https://github.com/uncrustify/uncrustify/archive/refs/tags/uncrustify-0.83.0.tar.gz \ + --output uncrustify.tar.gz + printf '%s %s\n' \ + 1d4d3ab3a991c66eb24cb0a3e690573b4882fd98bc6ec64a01c283998c20dc87 \ + uncrustify.tar.gz | sha256sum --check --status + tar -xzf uncrustify.tar.gz + cmake -S uncrustify-uncrustify-0.83.0 -B uncrustify-build -DCMAKE_BUILD_TYPE=Release + cmake --build uncrustify-build --parallel 4 + echo "$RUNNER_TEMP/uncrustify-build" >> "$GITHUB_PATH" + - run: python -m unittest discover -s devtools/format -v diff --git a/.uncrustify.cfg b/.uncrustify.cfg new file mode 100644 index 0000000000..209088c299 --- /dev/null +++ b/.uncrustify.cfg @@ -0,0 +1,115 @@ +# Uncrustify 0.83.0. Usage and scope: devtools/format/README.md. +# Keep include order, comment text, existing LF/CRLF and unlimited line width. +newlines = auto +input_tab_size = 4 +output_tab_size = 4 +indent_columns = 4 +indent_continue = 4 +indent_with_tabs = 0 +indent_namespace = false +indent_access_spec = 1 +code_width = 0 +cmt_width = 0 +cmt_reflow_mode = 0 +cmt_indent_multi = false +mod_sort_include = false +mod_sort_using = false +mod_remove_duplicate_include = false + +# Compact braces, with a space before control parentheses: if (ready()){ +sp_before_sparen = force +sp_sparen_brace = remove +# Preserve alignment before short-function bodies (const/non-const overloads). +sp_fparen_brace = ignore +sp_cpp_lambda_paren_brace = remove +sp_cpp_lambda_square_brace = remove +sp_word_brace_ns = remove +sp_enum_brace = remove +sp_paren_brace = remove +sp_else_brace = remove +sp_brace_else = remove +sp_try_brace = remove +sp_catch_brace = remove +sp_brace_catch = remove +sp_do_brace_open = remove +sp_brace_close_while = remove +nl_if_brace = remove +nl_for_brace = remove +nl_while_brace = remove +nl_switch_brace = remove +nl_do_brace = remove +nl_try_brace = remove +nl_catch_brace = remove +nl_else_brace = remove +nl_brace_else = remove +nl_namespace_brace = remove +nl_class_brace = remove +nl_struct_brace = remove +nl_enum_brace = remove +# Preserve constructor brace/comment placement; attaching across a commented-out +# initializer moves the brace past the comment. Same-line gaps still collapse. +nl_fdef_brace = ignore + +# Type-attached pointers/references; conventional operator/comma spacing. +sp_before_ptr_star = remove +sp_after_ptr_star = force +sp_before_byref = remove +sp_after_byref = force +sp_assign = force +sp_arith = force +sp_compare = force +sp_bool = force +sp_after_comma = force +sp_before_comma = remove + +# Expand braced control bodies, but do not add/remove any braces or statements. +nl_split_if_one_liner = true +nl_split_for_one_liner = true +nl_split_while_one_liner = true +mod_full_brace_if = ignore +mod_full_brace_for = ignore +mod_full_brace_while = ignore +mod_full_brace_do = ignore +mod_full_brace_function = ignore +mod_paren_on_return = ignore +mod_paren_on_throw = ignore +mod_remove_extra_semicolon = false +mod_remove_empty_return = false +mod_enum_last_comma = ignore +mod_add_long_namespace_closebrace_comment = 0 +# Keep type spacing: `remove` can merge `operator const Type` into constType. +# This preserves existing standalone class-name/brace spacing as well. +sp_after_type = ignore +sp_angle_shift = ignore +sp_permit_cpp11_shift = true +indent_class = true + +sp_before_class_colon = force +sp_after_class_colon = force + +# Preserve compact functions/tables and extra spacing between tokens. +# Leading declaration alignment still needs explicit protection; see README. +nl_func_leave_one_liners = true +nl_getset_leave_one_liners = true +nl_class_leave_one_liners = true +nl_cpp_lambda_leave_one_liners = true +nl_assign_leave_one_liners = true +nl_enum_leave_one_liners = true +align_keep_extra_space = true + +# Keep closing-parenthesis columns and the repository's continuation layout. +# Keeping the first continuation verbatim makes some nested-lambda/table cases +# drift on every pass in 0.83.0. Use a stable four-space continuation instead. +indent_ignore_first_continue = false +indent_paren_close = -1 + +# The repository consistently spells parameter packs class... / typename.... +sp_type_ellipsis = remove +sp_before_ellipsis = remove +# Keep a braced argument indented relative to the enclosing call's parentheses. +indent_paren_open_brace = true +indent_func_call_param = true + +# Match existing lambda bodies inside calls; do not apply continuation twice. +indent_cpp_lambda_only_once = true +nl_brace_catch = remove diff --git a/devtools/format/README.md b/devtools/format/README.md new file mode 100644 index 0000000000..6abc5a27f0 --- /dev/null +++ b/devtools/format/README.md @@ -0,0 +1,114 @@ +# C++ formatting + +Use **Uncrustify 0.83.0** with the root `.uncrustify.cfg`. This replaces the +initial clang-format proposal: Uncrustify can produce the repository's compact +`if (condition){`, `}else{` and `namespace Name{` spelling directly. +No regex postprocessor or change to AGENTS.md's style rules is needed. + +## Install and preview + +On macOS: + +```sh +brew install uncrustify +uncrustify --version +``` + +Check for `Uncrustify-0.83.0` (Homebrew's release appends `_f`). CI builds that +release from a SHA-256-verified source archive. If your package manager supplies +a different version, install the pinned release before comparing formatter output. + +From the repo root, preview a specific file without changing it: + +```sh +uncrustify -q -c .uncrustify.cfg -l CPP \ + -f SerialPrograms/Source/CommonFramework/Main.cpp -o /tmp/Main.formatted.cpp +git diff --no-index -- SerialPrograms/Source/CommonFramework/Main.cpp /tmp/Main.formatted.cpp +``` + +A diff exits 1 when changes are present; that is expected. Apply to an explicit +file only after reviewing the preview: + +```sh +uncrustify -q -c .uncrustify.cfg -l CPP --replace --no-backup \ + SerialPrograms/Source/CommonFramework/Main.cpp +``` + +To check an explicit file without writing it: + +```sh +uncrustify -q -c .uncrustify.cfg -l CPP --check \ + SerialPrograms/Source/CommonFramework/Main.cpp +``` + +Format edited files in a separate commit from behavioral changes. Preserve +unrelated changes and do not format vendored or generated files. The repository +contains legacy formatting differences; adopting the configuration does not +require reformatting all existing sources. This PR's CI tests the configuration, +not source-wide compliance. Do not enable a broad format-on-save hook yet. + +## What this configuration covers + +- Four spaces, no indentation tabs, unindented namespaces/access labels and + type-attached pointers/references. +- Compact control/namespace braces and spaced control parentheses. Existing + standalone class brace spacing and nested-template `>>` spelling are preserved. + Braced single-line `if`/`for`/`while` bodies expand onto multiple lines; + ordinary short functions and empty constructors stay compact. +- Existing LF or CRLF style, include order (including own-header-last and + registration-order exceptions), comment text and unlimited line width. +- Existing spacing within aligned declarations/overloads, parameter-pack + spelling (`class... Args`), four-space continuation layout and existing + closing-parenthesis columns. Lambdas inside calls keep their ordinary body indentation. +- No brace insertion/removal, statement removal, include sorting or generated + namespace comments. Missing-brace and namespace/API documentation requirements + remain the responsibility of review and existing code-health checks. + +Formatting still changes indentation, spacing and some line breaks. C++ macros, +conditional compilation and newer syntax need review; a successful formatter +exit does not prove semantic equivalence or a successful native build. Main-tree +trials are performed in an isolated snapshot and reviewed before any formatting +commit is proposed. Known limitations are recorded in the fork PR/run record: + +- Class/struct brace spacing is not fully enforced: standalone declarations + retain their existing spacing, and inherited declarations can gain a space + before `{`, for example + `struct Derived : public Base {`. Uncrustify 0.83.0 does not expose a separate + configurable spacing rule for this case. Restore the repository's compact + spelling when reviewing output; this formatter is not a complete code-health + compliance check. +- Leading spaces used to align const/non-const overloads are still normalized + to the block indentation. `align_keep_extra_space` preserves spacing between + tokens, not arbitrary leading columns. Protect a deliberate table explicitly + with the tool's `// *INDENT-OFF*` / `// *INDENT-ON*` markers, or leave that + region unformatted. Tests expose this limitation and verify protected tables + remain byte-identical. No markers are added to application sources by this PR. +- Function-definition brace line breaks are preserved to avoid moving a + constructor's brace across comments or commented-out initializer entries. +- Missing braces stay missing. Formatting is not a substitute for the existing + multiline-control-flow/braces lint rules. + +## Configuration tests + +These are tooling tests, not application tests. They call the real formatter: + +```sh +python3 -m unittest discover -s devtools/format -v +``` + +For a non-PATH installation: + +```sh +UNCRUSTIFY=/path/to/uncrustify python3 -m unittest discover -s devtools/format -v +``` + +Coverage includes exact brace spelling, indentation, pointers, includes, +line-ending preservation, comment/long-line preservation, templates/designated +initializers, raw strings, macro continuations/token pasting, constructor-comment placement and idempotence. +Regressions also preserve conversion-operator tokens, short functions, empty +constructors, intra-line alignment, argument/closing-parenthesis layouts, lambdas, +attached catch chains, parameter packs and repeated-pass stability for nested +lambdas/initializer tables. Known inherited-class spacing and +leading-overload alignment gaps are tested explicitly rather than claimed fixed. + +Reference: [Uncrustify 0.83.0 options](https://github.com/uncrustify/uncrustify/blob/uncrustify-0.83.0/documentation/htdocs/default.cfg). diff --git a/devtools/format/test_config.py b/devtools/format/test_config.py new file mode 100644 index 0000000000..56c5a3b0e9 --- /dev/null +++ b/devtools/format/test_config.py @@ -0,0 +1,195 @@ +"""Check formatter behavior: python3 -m unittest discover -s devtools/format -v.""" + +import os +from pathlib import Path +import shlex +import subprocess +import unittest + + +ROOT = Path(__file__).resolve().parents[2] +COMMAND = shlex.split(os.environ.get('UNCRUSTIFY', 'uncrustify')) + + +def format_cpp(source): + result = subprocess.run( + [*COMMAND, '-q', '-c', str(ROOT / '.uncrustify.cfg'), '-l', 'CPP'], + input=source, stdout=subprocess.PIPE, stderr=subprocess.PIPE, check=True, + ) + if result.stderr: + raise RuntimeError(result.stderr.decode(errors='replace')) + return result.stdout + + +class FormatterConfigTests(unittest.TestCase): + def test_pinned_version_and_valid_configuration(self): + version = subprocess.check_output([*COMMAND, '--version'], text=True) + self.assertRegex(version.strip(), r'^Uncrustify-0\.83\.0(?:_f)?$') + format_cpp(b'void f();\n') + + def test_exact_compact_braces_and_control_parentheses(self): + source = b'namespace Example {\nvoid f(){\nif(ready()) {\nrun();\n} else {\nstop();\n}\n}\n}\n' + expected = b'namespace Example{\nvoid f(){\n if (ready()){\n run();\n }else{\n stop();\n }\n}\n}\n' + self.assertEqual(expected, format_cpp(source)) + self.assertEqual(expected, format_cpp(expected)) + + def test_class_members_access_labels_and_type_attached_pointers(self): + source = b'class Thing{\npublic:\nvoid f(int *p){\n*p=1;\n}\n};\n' + expected = b'class Thing{\npublic:\n void f(int* p){\n *p = 1;\n }\n};\n' + self.assertEqual(expected, format_cpp(source)) + + def test_include_order_is_preserved_including_own_header_last(self): + source = b'#include \n#include "Common/Cpp/Exceptions.h"\n\n#include "Own.h"\n' + self.assertEqual(source, format_cpp(source)) + + def test_existing_lf_and_crlf_are_preserved(self): + for newline in (b'\n', b'\r\n'): + with self.subTest(newline=newline): + source = newline.join([b'void f(){', b' g();', b'}', b'']) + result = format_cpp(source) + if newline == b'\r\n': + self.assertNotIn(b'\n', result.replace(b'\r\n', b'')) + else: + self.assertNotIn(b'\r', result) + + def test_comments_and_long_lines_are_not_reflowed(self): + comment = b'// ' + b' '.join([b'keep this explanation intact'] * 8) + code = b' call(' + b', '.join(b'argument_' + str(i).encode() for i in range(25)) + b');' + result = format_cpp(b'void f(){\n' + comment + b'\n' + code + b'\n}\n') + self.assertIn(comment, result) + self.assertIn(code, result) + + def test_braced_single_line_control_bodies_are_expanded(self): + result = format_cpp(b'void f(){if (x){run();}else{stop();}}\n') + self.assertIn(b'if (x){\n', result) + self.assertIn(b'}else{\n', result) + self.assertNotIn(b'{run();}', result) + self.assertEqual(result, format_cpp(result)) + + def test_templates_designated_initializers_and_raw_strings(self): + source = ( + b'template \nstruct Case{\n T input;\n T expectation;\n};\n' + b'constexpr Case cases[] = {\n {.input = 1, .expectation = 2},\n};\n' + b'const char* text = R"tag(if(x) { } else { /* keep */ })tag";\n' + ) + result = format_cpp(source) + self.assertIn(b'R"tag(if(x) { } else { /* keep */ })tag"', result) + self.assertIn(b'.input = 1', result) + self.assertIn(b'.expectation = 2', result) + self.assertEqual(result, format_cpp(result)) + + def test_macro_continuations_and_token_pasting(self): + source = ( + b'#define JOIN(a, b) a ## b\n' + b'#define TRACE(x) do { \\\n' + b' trace(#x, x); \\\n' + b'} while (false)\n' + ) + result = format_cpp(source) + self.assertIn(b'a ## b', result) + self.assertIn(b'trace(#x, x);', result) + self.assertEqual(source.count(b'\\\n'), result.count(b'\\\n')) + self.assertEqual(result, format_cpp(result)) + + def test_constructor_comment_stays_before_body_brace(self): + source = ( + b'Thing::Thing()\n : m_value(0)\n' + b'// , m_other(1)\n{\n run();\n}\n' + ) + result = format_cpp(source) + self.assertIn(b'// , m_other(1)\n{', result) + self.assertEqual(result, format_cpp(result)) + + def test_known_inherited_class_spacing_gap(self): + # Unlike control/namespace braces, this case is not fully configurable. + source = b'struct Derived : public Base{\n int value;\n};\n' + self.assertIn(b'struct Derived : public Base {', format_cpp(source)) + + def test_conversion_operators_and_nested_templates_preserve_tokens(self): + source = ( + b'template \nstruct Holder{\n' + b' operator const Type&() const{ return value; }\n' + b' Type value;\n};\n' + b'std::vector>> values;\n' + ) + result = format_cpp(source) + self.assertIn(b'operator const Type&()', result) + self.assertNotIn(b'constType', result) + self.assertIn(b'Holder>>', result) + self.assertEqual(result, format_cpp(result)) + + def test_preserves_short_functions_and_empty_constructor(self): + source = ( + b'class Value{\npublic:\n' + b' Value()\n : m_value(0)\n {}\n' + b' int get() const{ return m_value; }\n' + b' void clear(){ m_value = 0; }\n' + b'private:\n int m_value;\n};\n' + ) + self.assertEqual(source, format_cpp(source)) + + def test_preserves_manual_spacing_within_overloads(self): + source = ( + b'class Value{\npublic:\n' + b' const Type& get() const{ return m_value; }\n' + b' Type& get() { return m_value; }\n' + b' const Type* data() const;\n' + b' Type* data();\n};\n' + ) + self.assertEqual(source, format_cpp(source)) + + def test_preserves_multiline_argument_and_closing_parenthesis_layout(self): + source = ( + b'void f(){\n call(\n first,\n second\n );\n' + b' auto value = build(\n Params{\n .count = 2,\n }\n );\n}\n' + ) + self.assertEqual(source, format_cpp(source)) + + def test_preserves_template_parameter_pack_spelling(self): + source = b'template \nvoid f(Args&&... args);\n' + self.assertEqual(source, format_cpp(source)) + + def test_known_leading_overload_alignment_gap(self): + source = ( + b'class Value{\npublic:\n' + b' const Type* data() const;\n' + b' Type* data();\n};\n' + ) + result = format_cpp(source) + self.assertIn(b'\n Type* data();', result) + self.assertNotEqual(source, result) + + def test_explicitly_protected_alignment_table_is_unchanged(self): + source = ( + b'class Value{\npublic:\n' + b'// *INDENT-OFF*\n' + b' const Type& get() const{ return m_value; }\n' + b' Type& get() { return m_value; }\n' + b'// *INDENT-ON*\n};\n' + ) + self.assertEqual(source, format_cpp(source)) + + def test_preserves_lambda_body_inside_call(self): + source = ( + b'void f(){\n ScopeExit cleanup([]{\n stop();\n });\n}\n' + ) + self.assertEqual(source, format_cpp(source)) + + def test_preserves_attached_catch_chain(self): + source = ( + b'void f(){\n try{\n run();\n }catch (const First& error){\n' + b' log(error);\n }catch (const Second& error){\n' + b' log(error);\n }\n}\n' + ) + self.assertEqual(source, format_cpp(source)) + + def test_nested_lambda_and_initializer_table_are_stable(self): + sources = [ + b'void f(){\n dispatch(\n scope,\n [](Handle& h){\n run(h);\n }\n );\n done();\n}\n', + b'void f(){\n static const Database value({\n {A, "a"},\n {B, "b"},\n });\n}\n', + b'void f(){\n try{\n run();\n }catch (Error& e){\n report(\n "message");\n }\n}\n', + ] + for source in sources: + with self.subTest(source=source): + result = format_cpp(source) + self.assertEqual(result, format_cpp(result))