Sync sketch formatter configuration from source

The Arduino IDE's "Auto Format" feature is configured to produce the standard Arduino sketch formatting style, as
established by the Arduino IDE 1.x formatter.

The configuration is consumed by several other projects which require the configuration in a YAML file. In order to
provide all the consumers with a single canonical source and to locate the infrastructure and activity related to the
maintenance of the file in a more appropriate repository, it is now hosted in a permanent location in the
`arduino/tooling-project-assets` repository.

The following changes have been made to the source configuration:

- Move documentation comments to a dedicated file in the upstream repository
- Make additional non-functional changes to the configuration format to facilitate maintenance
- Update to use the configuration API of ClangFormat 14.0.0

This last item did result in some functional changes to the configuration which will result in minor differences in the
formatter output.

These are actually reversions of unwanted differences from the Arduino IDE 1.x formatter output, which were unavoidable
when using the 11.0.1 version of ClangFormat in use at the time of the configuration's creation. These changes will
provide greater consistency during the migration from Arduino IDE 1.x to 2.x. The default output of the Arduino IDE
1.x formatter will continue to be considered the "gold standard" until Arduino IDE 2.x graduates from "pre-release"
status.

The Arduino IDE 2.x formatter configuration is fully customizable according to the preferences of each user. Those
already using custom configurations will not be affected in any way (though they are encouraged to sync their
configuration files from the source to bring them into compliance with the configuration API of the ClangFormat version
currently in use by Arduino IDE 2.x).

See the documentation and commit history for the source file for details on the configuration changes:

https://github.com/arduino/tooling-project-assets/tree/main/other/clang-format-configuration

arduino-ide-extension/src/node/clang-formatter.ts

@@ -122,7 +122,6 @@ function toClangOptions(
   return { UseTab: 'Never', TabWidth: 2 };
 }
 
-// See: https://releases.llvm.org/11.0.1/tools/clang/docs/ClangFormatStyleOptions.html
 export function style({ TabWidth, UseTab }: ClangFormatOptions): string {
   let styleArgument = JSON.stringify(styleJson({ TabWidth, UseTab })).replace(
     /[\\"]/g,
@@ -147,16 +146,15 @@ function styleJson({
   TabWidth,
   UseTab,
 }: ClangFormatOptions): Record<string, unknown> {
+  // Source: https://github.com/arduino/tooling-project-assets/tree/main/other/clang-format-configuration
   return {
-    Language: 'Cpp',
-    // # LLVM is the default style setting, used when a configuration option is not set here
-    BasedOnStyle: 'LLVM',
     AccessModifierOffset: -2,
     AlignAfterOpenBracket: 'Align',
-    AlignConsecutiveAssignments: false,
-    AlignConsecutiveBitFields: false,
-    AlignConsecutiveDeclarations: false,
-    AlignConsecutiveMacros: false,
+    AlignArrayOfStructures: 'None',
+    AlignConsecutiveAssignments: 'None',
+    AlignConsecutiveBitFields: 'None',
+    AlignConsecutiveDeclarations: 'None',
+    AlignConsecutiveMacros: 'None',
     AlignEscapedNewlines: 'DontAlign',
     AlignOperands: 'Align',
     AlignTrailingComments: true,
@@ -167,24 +165,26 @@ function styleJson({
     AllowShortCaseLabelsOnASingleLine: true,
     AllowShortEnumsOnASingleLine: true,
     AllowShortFunctionsOnASingleLine: 'Empty',
-    AllowShortIfStatementsOnASingleLine: 'Always',
+    AllowShortIfStatementsOnASingleLine: 'AllIfsAndElse',
     AllowShortLambdasOnASingleLine: 'Empty',
     AllowShortLoopsOnASingleLine: true,
     AlwaysBreakAfterDefinitionReturnType: 'None',
     AlwaysBreakAfterReturnType: 'None',
     AlwaysBreakBeforeMultilineStrings: false,
     AlwaysBreakTemplateDeclarations: 'No',
+    AttributeMacros: ['__capability'],
+    BasedOnStyle: 'LLVM',
     BinPackArguments: true,
     BinPackParameters: true,
-    // # Only used when "BreakBeforeBraces" set to "Custom"
+    BitFieldColonSpacing: 'Both',
     BraceWrapping: {
       AfterCaseLabel: false,
       AfterClass: false,
       AfterControlStatement: 'Never',
       AfterEnum: false,
       AfterFunction: false,
       AfterNamespace: false,
-      // #AfterObjCDeclaration:
+      AfterObjCDeclaration: false,
       AfterStruct: false,
       AfterUnion: false,
       AfterExternBlock: false,
@@ -193,104 +193,143 @@ function styleJson({
       BeforeLambdaBody: false,
       BeforeWhile: false,
       IndentBraces: false,
-      SplitEmptyFunction: false,
-      SplitEmptyRecord: false,
-      SplitEmptyNamespace: false,
+      SplitEmptyFunction: true,
+      SplitEmptyRecord: true,
+      SplitEmptyNamespace: true,
     },
-    // # Java-specific
-    // #BreakAfterJavaFieldAnnotations:
+    BreakAfterJavaFieldAnnotations: false,
     BreakBeforeBinaryOperators: 'NonAssignment',
     BreakBeforeBraces: 'Attach',
+    BreakBeforeConceptDeclarations: false,
+    BreakBeforeInheritanceComma: false,
     BreakBeforeTernaryOperators: true,
     BreakConstructorInitializers: 'BeforeColon',
+    BreakConstructorInitializersBeforeComma: false,
     BreakInheritanceList: 'BeforeColon',
     BreakStringLiterals: false,
     ColumnLimit: 0,
-    // # "" matches none
     CommentPragmas: '',
     CompactNamespaces: false,
-    ConstructorInitializerAllOnOneLineOrOnePerLine: true,
+    ConstructorInitializerAllOnOneLineOrOnePerLine: false,
     ConstructorInitializerIndentWidth: 2,
     ContinuationIndentWidth: 2,
     Cpp11BracedListStyle: false,
     DeriveLineEnding: true,
     DerivePointerAlignment: true,
     DisableFormat: false,
-    // # Docs say "Do not use this in config files". The default (LLVM 11.0.1) is "false".
-    // #ExperimentalAutoDetectBinPacking:
+    EmptyLineAfterAccessModifier: 'Leave',
+    EmptyLineBeforeAccessModifier: 'Leave',
+    ExperimentalAutoDetectBinPacking: false,
     FixNamespaceComments: false,
-    ForEachMacros: [],
+    ForEachMacros: ['foreach', 'Q_FOREACH', 'BOOST_FOREACH'],
+    IfMacros: ['KJ_IF_MAYBE'],
     IncludeBlocks: 'Preserve',
-    IncludeCategories: [],
-    // # "" matches none
+    IncludeCategories: [
+      {
+        Regex: '^"(llvm|llvm-c|clang|clang-c)/',
+        Priority: 2,
+        SortPriority: 0,
+        CaseSensitive: false,
+      },
+      {
+        Regex: '^(<|"(gtest|gmock|isl|json)/)',
+        Priority: 3,
+        SortPriority: 0,
+        CaseSensitive: false,
+      },
+      { Regex: '.*', Priority: 1, SortPriority: 0, CaseSensitive: false },
+    ],
     IncludeIsMainRegex: '',
     IncludeIsMainSourceRegex: '',
+    IndentAccessModifiers: false,
     IndentCaseBlocks: true,
     IndentCaseLabels: true,
     IndentExternBlock: 'Indent',
     IndentGotoLabels: false,
     IndentPPDirectives: 'None',
+    IndentRequires: true,
     IndentWidth: 2,
     IndentWrappedFunctionNames: false,
     InsertTrailingCommas: 'None',
-    // # Java-specific
-    // #JavaImportGroups:
-    // # JavaScript-specific
-    // #JavaScriptQuotes:
-    // #JavaScriptWrapImports
+    JavaScriptQuotes: 'Leave',
+    JavaScriptWrapImports: true,
     KeepEmptyLinesAtTheStartOfBlocks: true,
+    LambdaBodyIndentation: 'Signature',
+    Language: 'Cpp',
     MacroBlockBegin: '',
     MacroBlockEnd: '',
-    // # Set to a large number to effectively disable
     MaxEmptyLinesToKeep: 100000,
     NamespaceIndentation: 'None',
-    NamespaceMacros: [],
-    // # Objective C-specific
-    // #ObjCBinPackProtocolList:
-    // #ObjCBlockIndentWidth:
-    // #ObjCBreakBeforeNestedBlockParam:
-    // #ObjCSpaceAfterProperty:
-    // #ObjCSpaceBeforeProtocolList
+    ObjCBinPackProtocolList: 'Auto',
+    ObjCBlockIndentWidth: 2,
+    ObjCBreakBeforeNestedBlockParam: true,
+    ObjCSpaceAfterProperty: false,
+    ObjCSpaceBeforeProtocolList: true,
+    PPIndentWidth: -1,
+    PackConstructorInitializers: 'BinPack',
     PenaltyBreakAssignment: 1,
     PenaltyBreakBeforeFirstCallParameter: 1,
     PenaltyBreakComment: 1,
     PenaltyBreakFirstLessLess: 1,
+    PenaltyBreakOpenParenthesis: 1,
     PenaltyBreakString: 1,
     PenaltyBreakTemplateDeclaration: 1,
     PenaltyExcessCharacter: 1,
+    PenaltyIndentedWhitespace: 1,
     PenaltyReturnTypeOnItsOwnLine: 1,
-    // # Used as a fallback if alignment style can't be detected from code (DerivePointerAlignment: true)
     PointerAlignment: 'Right',
-    RawStringFormats: [],
+    QualifierAlignment: 'Leave',
+    ReferenceAlignment: 'Pointer',
     ReflowComments: false,
-    SortIncludes: false,
+    RemoveBracesLLVM: false,
+    SeparateDefinitionBlocks: 'Leave',
+    ShortNamespaceLines: 0,
+    SortIncludes: 'Never',
+    SortJavaStaticImport: 'Before',
     SortUsingDeclarations: false,
     SpaceAfterCStyleCast: false,
     SpaceAfterLogicalNot: false,
     SpaceAfterTemplateKeyword: false,
+    SpaceAroundPointerQualifiers: 'Default',
     SpaceBeforeAssignmentOperators: true,
+    SpaceBeforeCaseColon: false,
     SpaceBeforeCpp11BracedList: false,
     SpaceBeforeCtorInitializerColon: true,
     SpaceBeforeInheritanceColon: true,
     SpaceBeforeParens: 'ControlStatements',
+    SpaceBeforeParensOptions: {
+      AfterControlStatements: true,
+      AfterForeachMacros: true,
+      AfterFunctionDefinitionName: false,
+      AfterFunctionDeclarationName: false,
+      AfterIfMacros: true,
+      AfterOverloadedOperator: false,
+      BeforeNonEmptyParentheses: false,
+    },
     SpaceBeforeRangeBasedForLoopColon: true,
     SpaceBeforeSquareBrackets: false,
     SpaceInEmptyBlock: false,
     SpaceInEmptyParentheses: false,
     SpacesBeforeTrailingComments: 2,
-    SpacesInAngles: false,
+    SpacesInAngles: 'Leave',
     SpacesInCStyleCastParentheses: false,
     SpacesInConditionalStatement: false,
     SpacesInContainerLiterals: false,
+    SpacesInLineCommentPrefix: { Minimum: 0, Maximum: -1 },
     SpacesInParentheses: false,
     SpacesInSquareBrackets: false,
     Standard: 'Auto',
-    StatementMacros: [],
+    StatementAttributeLikeMacros: ['Q_EMIT'],
+    StatementMacros: ['Q_UNUSED', 'QT_REQUIRE_VERSION'],
     TabWidth,
-    TypenameMacros: [],
-    // # Default to LF if line endings can't be detected from the content (DeriveLineEnding).
     UseCRLF: false,
     UseTab,
-    WhitespaceSensitiveMacros: [],
+    WhitespaceSensitiveMacros: [
+      'STRINGIZE',
+      'PP_STRINGIZE',
+      'BOOST_PP_STRINGIZE',
+      'NS_SWIFT_NAME',
+      'CF_SWIFT_NAME',
+    ],
   };
 }