From 96dff99d8742ee4b93632595966916d47fc4ad8f Mon Sep 17 00:00:00 2001 From: dayfine Date: Fri, 6 Nov 2026 21:45:45 -0800 Subject: [PATCH 1/4] Propose pinned clang-format config with explicit style compatibility limits --- .clang-format | 36 ++++++++++++++ .github/workflows/formatter-config.yml | 20 ++++++++ devtools/format/README.md | 59 +++++++++++++++++++++++ devtools/format/test_config.py | 66 ++++++++++++++++++++++++++ 4 files changed, 181 insertions(+) create mode 100644 .clang-format create mode 100644 .github/workflows/formatter-config.yml create mode 100644 devtools/format/README.md create mode 100644 devtools/format/test_config.py diff --git a/.clang-format b/.clang-format new file mode 100644 index 0000000000..a12a778982 --- /dev/null +++ b/.clang-format @@ -0,0 +1,36 @@ +# Tested with clang-format 21.1.8. See devtools/format/README.md before use. +# Stock clang-format cannot express our no-space-before-brace / }else{ style. +# This is a review proposal, not authorization to change that convention. +BasedOnStyle: LLVM +Language: Cpp +Standard: Latest +IndentWidth: 4 +ContinuationIndentWidth: 4 +TabWidth: 4 +UseTab: Never +ColumnLimit: 0 +LineEnding: DeriveCRLF +SortIncludes: Never +IncludeBlocks: Preserve +ReflowComments: Never +FixNamespaceComments: false +NamespaceIndentation: None +CompactNamespaces: false +AccessModifierOffset: -4 +IndentCaseLabels: false +DerivePointerAlignment: false +PointerAlignment: Left +ReferenceAlignment: Left +BreakBeforeBraces: Attach +SpaceBeforeParens: ControlStatements +SpaceBeforeCpp11BracedList: false +AllowShortIfStatementsOnASingleLine: Never +AllowShortLoopsOnASingleLine: false +AllowShortBlocksOnASingleLine: Never +AllowShortFunctionsOnASingleLine: Empty +AllowShortLambdasOnASingleLine: Empty +InsertBraces: false +RemoveBracesLLVM: false +BreakConstructorInitializers: BeforeComma +BinPackArguments: false +BinPackParameters: OnePerLine diff --git a/.github/workflows/formatter-config.yml b/.github/workflows/formatter-config.yml new file mode 100644 index 0000000000..a31c74c278 --- /dev/null +++ b/.github/workflows/formatter-config.yml @@ -0,0 +1,20 @@ +name: Formatter configuration +on: + pull_request: + paths: + - '.clang-format' + - 'devtools/format/**' + - '.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' + - run: python -m pip install clang-format==21.1.8 + - run: python -m unittest discover -s devtools/format -v diff --git a/devtools/format/README.md b/devtools/format/README.md new file mode 100644 index 0000000000..df45342351 --- /dev/null +++ b/devtools/format/README.md @@ -0,0 +1,59 @@ +# C++ formatter proposal + +The root `.clang-format` is an opt-in draft, tested with **clang-format 21.1.8**. +No source files are reformatted and no source-format CI gate is enabled. + +**Known incompatibility:** stock clang-format emits `if (condition) {`, +`} else {`, `namespace Name {` and `class Name {`. The repository requires +compact braces such as `if (condition){` and `}else{`. LLVM 21 has no style +option to express that spacing. This proposal does not change AGENTS.md's +rules: do not enable format-on-save or apply its output without reviewing and +restoring the required brace spacing. Exact automatic formatting needs a +separate decision: a tested compatibility tool, or an explicitly approved +style change. No regex postprocessor or silent style change is included here. + +The configuration supplies four-space indentation, no tabs, type-attached +pointers/references, unindented namespaces and access labels, attached braces +and multiline control flow. It preserves include order (including the own-header +last rule and registration-order exceptions), existing LF/CRLF style, and comment +text. There is no forced column limit. It does not insert/remove braces or add +namespace comments; the existing code-health checks still cover those contracts. +It can change other whitespace and wrapping, so review every proposed diff. + +Install the pinned tool in an isolated environment, for example: + +```sh +uv tool install 'clang-format==21.1.8' +clang-format --version +``` + +From the repo root, preview a specific file without modifying it: + +```sh +clang-format --style=file SerialPrograms/Source/CommonFramework/Main.cpp > /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. Use `--lines=START:END` +for an edited region, while reviewing neighboring changes clang-format may make. +Do not bulk-format the repo or third-party files. `--dry-run --Werror` is not a +repository-style validator while the known brace-spacing incompatibility exists. + +Run the configuration checks (not application tests): + +```sh +python3 -m unittest discover -s devtools/format -v +``` + +Without a persistent install, the equivalent is: + +```sh +CLANG_FORMAT='uv tool run --from clang-format==21.1.8 clang-format' \ + python3 -m unittest discover -s devtools/format -v +``` + +Tests run the real formatter on small C++ examples, check line endings, includes, +indentation, comments and idempotence, and explicitly demonstrate the brace gap. +They do not assert the existing source tree is already formatted. + +Reference: [LLVM 21 style options](https://releases.llvm.org/21.1.0/tools/clang/docs/ClangFormatStyleOptions.html). diff --git a/devtools/format/test_config.py b/devtools/format/test_config.py new file mode 100644 index 0000000000..ef06714892 --- /dev/null +++ b/devtools/format/test_config.py @@ -0,0 +1,66 @@ +"""Check the formatter proposal: 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('CLANG_FORMAT', 'clang-format')) + + +def format_cpp(source): + return subprocess.run( + [*COMMAND, '--style=file', '--assume-filename=sample.cpp'], + input=source, stdout=subprocess.PIPE, stderr=subprocess.PIPE, + cwd=ROOT, check=True, + ).stdout + + +class FormatterConfigTests(unittest.TestCase): + def test_pinned_version_and_valid_configuration(self): + result = subprocess.check_output([*COMMAND, '--version'], text=True) + self.assertIn('version 21.1.8', result) + subprocess.run([*COMMAND, '--style=file', '--dump-config'], cwd=ROOT, + stdout=subprocess.DEVNULL, check=True) + + def test_indentation_pointer_alignment_and_multiline_control_flow(self): + result = format_cpp(b'void f(int *p){\nif(p){\n*p=1;\n}else{\n*p=2;\n}\n}\n') + self.assertIn(b'void f(int* p)', result) + self.assertIn(b' if (p)', result) + self.assertIn(b' *p = 1;', result) + self.assertNotIn(b'\t', result) + + 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' + result = format_cpp(source) + self.assertEqual([s for s in source.splitlines() if s.startswith(b'#include')], + [s for s in result.splitlines() if s.startswith(b'#include')]) + + 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_known_brace_spacing_gap_and_idempotence(self): + # Deliberately exposes the incompatibility, rather than claiming parity. + source = b'namespace Sample{\nvoid f(){\nif (ready()){\nrun();\n}else{\nstop();\n}\n}\n}\n' + result = format_cpp(source) + self.assertIn(b'namespace Sample {', result) + self.assertIn(b'if (ready()) {', result) + self.assertIn(b'} else {', result) + self.assertEqual(result, format_cpp(result)) From c0f34a31e50947e4d68485702c76db5906db273a Mon Sep 17 00:00:00 2001 From: dayfine Date: Fri, 6 Nov 2026 22:22:14 -0800 Subject: [PATCH 2/4] Use Uncrustify for compact control braces with token-preservation regressions --- .clang-format | 36 -------- .github/workflows/formatter-config.yml | 17 +++- .uncrustify.cfg | 87 ++++++++++++++++++ devtools/format/README.md | 120 +++++++++++++++++-------- devtools/format/test_config.py | 107 ++++++++++++++++------ 5 files changed, 263 insertions(+), 104 deletions(-) delete mode 100644 .clang-format create mode 100644 .uncrustify.cfg diff --git a/.clang-format b/.clang-format deleted file mode 100644 index a12a778982..0000000000 --- a/.clang-format +++ /dev/null @@ -1,36 +0,0 @@ -# Tested with clang-format 21.1.8. See devtools/format/README.md before use. -# Stock clang-format cannot express our no-space-before-brace / }else{ style. -# This is a review proposal, not authorization to change that convention. -BasedOnStyle: LLVM -Language: Cpp -Standard: Latest -IndentWidth: 4 -ContinuationIndentWidth: 4 -TabWidth: 4 -UseTab: Never -ColumnLimit: 0 -LineEnding: DeriveCRLF -SortIncludes: Never -IncludeBlocks: Preserve -ReflowComments: Never -FixNamespaceComments: false -NamespaceIndentation: None -CompactNamespaces: false -AccessModifierOffset: -4 -IndentCaseLabels: false -DerivePointerAlignment: false -PointerAlignment: Left -ReferenceAlignment: Left -BreakBeforeBraces: Attach -SpaceBeforeParens: ControlStatements -SpaceBeforeCpp11BracedList: false -AllowShortIfStatementsOnASingleLine: Never -AllowShortLoopsOnASingleLine: false -AllowShortBlocksOnASingleLine: Never -AllowShortFunctionsOnASingleLine: Empty -AllowShortLambdasOnASingleLine: Empty -InsertBraces: false -RemoveBracesLLVM: false -BreakConstructorInitializers: BeforeComma -BinPackArguments: false -BinPackParameters: OnePerLine diff --git a/.github/workflows/formatter-config.yml b/.github/workflows/formatter-config.yml index a31c74c278..e832227b9d 100644 --- a/.github/workflows/formatter-config.yml +++ b/.github/workflows/formatter-config.yml @@ -2,7 +2,7 @@ name: Formatter configuration on: pull_request: paths: - - '.clang-format' + - '.uncrustify.cfg' - 'devtools/format/**' - '.github/workflows/formatter-config.yml' workflow_dispatch: @@ -16,5 +16,18 @@ jobs: - uses: actions/setup-python@v6 with: python-version: '3.12' - - run: python -m pip install clang-format==21.1.8 + - 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..ee4802a6cf --- /dev/null +++ b/.uncrustify.cfg @@ -0,0 +1,87 @@ +# 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 +sp_fparen_brace = remove +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 diff --git a/devtools/format/README.md b/devtools/format/README.md index df45342351..fd554f9441 100644 --- a/devtools/format/README.md +++ b/devtools/format/README.md @@ -1,59 +1,101 @@ -# C++ formatter proposal - -The root `.clang-format` is an opt-in draft, tested with **clang-format 21.1.8**. -No source files are reformatted and no source-format CI gate is enabled. - -**Known incompatibility:** stock clang-format emits `if (condition) {`, -`} else {`, `namespace Name {` and `class Name {`. The repository requires -compact braces such as `if (condition){` and `}else{`. LLVM 21 has no style -option to express that spacing. This proposal does not change AGENTS.md's -rules: do not enable format-on-save or apply its output without reviewing and -restoring the required brace spacing. Exact automatic formatting needs a -separate decision: a tested compatibility tool, or an explicitly approved -style change. No regex postprocessor or silent style change is included here. - -The configuration supplies four-space indentation, no tabs, type-attached -pointers/references, unindented namespaces and access labels, attached braces -and multiline control flow. It preserves include order (including the own-header -last rule and registration-order exceptions), existing LF/CRLF style, and comment -text. There is no forced column limit. It does not insert/remove braces or add -namespace comments; the existing code-health checks still cover those contracts. -It can change other whitespace and wrapping, so review every proposed diff. - -Install the pinned tool in an isolated environment, for example: +# 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 -uv tool install 'clang-format==21.1.8' -clang-format --version +brew install uncrustify +uncrustify --version ``` -From the repo root, preview a specific file without modifying it: +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 -clang-format --style=file SerialPrograms/Source/CommonFramework/Main.cpp > /tmp/Main.formatted.cpp +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. Use `--lines=START:END` -for an edited region, while reviewing neighboring changes clang-format may make. -Do not bulk-format the repo or third-party files. `--dry-run --Werror` is not a -repository-style validator while the known brace-spacing incompatibility exists. +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. Existing braced + single-line `if`/`for`/`while` bodies expand onto multiple lines. +- Existing LF or CRLF style, include order (including own-header-last and + registration-order exceptions), comment text and unlimited line width. +- 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. +- 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 -Run the configuration checks (not application tests): +These are tooling tests, not application tests. They call the real formatter: ```sh python3 -m unittest discover -s devtools/format -v ``` -Without a persistent install, the equivalent is: +For a non-PATH installation: ```sh -CLANG_FORMAT='uv tool run --from clang-format==21.1.8 clang-format' \ - python3 -m unittest discover -s devtools/format -v +UNCRUSTIFY=/path/to/uncrustify python3 -m unittest discover -s devtools/format -v ``` -Tests run the real formatter on small C++ examples, check line endings, includes, -indentation, comments and idempotence, and explicitly demonstrate the brace gap. -They do not assert the existing source tree is already formatted. +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 and expose the +inherited-class spacing gap explicitly. -Reference: [LLVM 21 style options](https://releases.llvm.org/21.1.0/tools/clang/docs/ClangFormatStyleOptions.html). +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 index ef06714892..600ceb921c 100644 --- a/devtools/format/test_config.py +++ b/devtools/format/test_config.py @@ -1,4 +1,4 @@ -"""Check the formatter proposal: python3 -m unittest discover -s devtools/format -v.""" +"""Check formatter behavior: python3 -m unittest discover -s devtools/format -v.""" import os from pathlib import Path @@ -8,36 +8,39 @@ ROOT = Path(__file__).resolve().parents[2] -COMMAND = shlex.split(os.environ.get('CLANG_FORMAT', 'clang-format')) +COMMAND = shlex.split(os.environ.get('UNCRUSTIFY', 'uncrustify')) def format_cpp(source): - return subprocess.run( - [*COMMAND, '--style=file', '--assume-filename=sample.cpp'], - input=source, stdout=subprocess.PIPE, stderr=subprocess.PIPE, - cwd=ROOT, check=True, - ).stdout + 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): - result = subprocess.check_output([*COMMAND, '--version'], text=True) - self.assertIn('version 21.1.8', result) - subprocess.run([*COMMAND, '--style=file', '--dump-config'], cwd=ROOT, - stdout=subprocess.DEVNULL, check=True) - - def test_indentation_pointer_alignment_and_multiline_control_flow(self): - result = format_cpp(b'void f(int *p){\nif(p){\n*p=1;\n}else{\n*p=2;\n}\n}\n') - self.assertIn(b'void f(int* p)', result) - self.assertIn(b' if (p)', result) - self.assertIn(b' *p = 1;', result) - self.assertNotIn(b'\t', result) + 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' - result = format_cpp(source) - self.assertEqual([s for s in source.splitlines() if s.startswith(b'#include')], - [s for s in result.splitlines() if s.startswith(b'#include')]) + self.assertEqual(source, format_cpp(source)) def test_existing_lf_and_crlf_are_preserved(self): for newline in (b'\n', b'\r\n'): @@ -56,11 +59,61 @@ def test_comments_and_long_lines_are_not_reflowed(self): self.assertIn(comment, result) self.assertIn(code, result) - def test_known_brace_spacing_gap_and_idempotence(self): - # Deliberately exposes the incompatibility, rather than claiming parity. - source = b'namespace Sample{\nvoid f(){\nif (ready()){\nrun();\n}else{\nstop();\n}\n}\n}\n' + 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'namespace Sample {', result) - self.assertIn(b'if (ready()) {', result) - self.assertIn(b'} else {', result) + self.assertIn(b'operator const Type&()', result) + self.assertNotIn(b'constType', result) + self.assertIn(b'Holder>>', result) self.assertEqual(result, format_cpp(result)) From d8b038f93aec4fcc280568f744d0e983f7c4156b Mon Sep 17 00:00:00 2001 From: dayfine Date: Fri, 6 Nov 2026 22:36:28 -0800 Subject: [PATCH 3/4] Preserve compact functions, aligned spacing and authored argument layouts --- .uncrustify.cfg | 30 ++++++++++++- devtools/format/README.md | 21 +++++++-- devtools/format/test_config.py | 78 +++++++++++++++++++++++++++++++++- 3 files changed, 123 insertions(+), 6 deletions(-) diff --git a/.uncrustify.cfg b/.uncrustify.cfg index ee4802a6cf..209088c299 100644 --- a/.uncrustify.cfg +++ b/.uncrustify.cfg @@ -19,7 +19,8 @@ mod_remove_duplicate_include = false # Compact braces, with a space before control parentheses: if (ready()){ sp_before_sparen = force sp_sparen_brace = remove -sp_fparen_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 @@ -85,3 +86,30 @@ 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 index fd554f9441..6abc5a27f0 100644 --- a/devtools/format/README.md +++ b/devtools/format/README.md @@ -52,10 +52,14 @@ not source-wide compliance. Do not enable a broad format-on-save hook yet. - 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. Existing braced - single-line `if`/`for`/`while` bodies expand onto multiple lines. + 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. @@ -73,6 +77,12 @@ commit is proposed. Known limitations are recorded in the fork PR/run record: 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 @@ -95,7 +105,10 @@ UNCRUSTIFY=/path/to/uncrustify python3 -m unittest discover -s devtools/format - 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 and expose the -inherited-class spacing gap explicitly. +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 index 600ceb921c..56c5a3b0e9 100644 --- a/devtools/format/test_config.py +++ b/devtools/format/test_config.py @@ -28,7 +28,7 @@ def test_pinned_version_and_valid_configuration(self): 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' + 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)) @@ -117,3 +117,79 @@ def test_conversion_operators_and_nested_templates_preserve_tokens(self): 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)) From 16a53cc2abc9c7a3a5625545ea2da208a8c81267 Mon Sep 17 00:00:00 2001 From: dayfine Date: Fri, 6 Nov 2026 23:15:41 -0800 Subject: [PATCH 4/4] Check formatter tooling when its CMake integration changes --- .github/workflows/formatter-config.yml | 3 +++ 1 file changed, 3 insertions(+) diff --git a/.github/workflows/formatter-config.yml b/.github/workflows/formatter-config.yml index e832227b9d..6715a8b275 100644 --- a/.github/workflows/formatter-config.yml +++ b/.github/workflows/formatter-config.yml @@ -4,6 +4,9 @@ on: paths: - '.uncrustify.cfg' - 'devtools/format/**' + - 'SerialPrograms/CMakeLists.txt' + - 'SerialPrograms/cmake/Formatting.cmake' + - 'SerialPrograms/cmake/RunFormatting.cmake' - '.github/workflows/formatter-config.yml' workflow_dispatch: permissions: