@mmerterden/multi-agent-pipeline 20.6.0 → 20.8.0

package/pipeline/skills/shared/external/swiftlint/references/rules-suppressions-and-baselines.md

@@ -1,283 +1,198 @@
-# Rules, Suppressions, and Baselines
+# Rules, Suppressions and Baselines
 
-Guidance on SwiftLint rule categories, inline suppression syntax, baseline workflows, and false-positive handling.
+Back to [SKILL.md](../SKILL.md). Every identifier is indexed in the
+[rule reference](rule-reference.md).
 
-## Contents
+## The three kinds of rule
 
-- [Rule Categories](#rule-categories)
-- [Browsing Rules](#browsing-rules)
-- [Suppression Syntax](#suppression-syntax)
-- [Suppression Policy](#suppression-policy)
-- [Baselines](#baselines)
-- [False Positives](#false-positives)
-- [Generated Code and Test Targets](#generated-code-and-test-targets)
+**Default.** On out of the box because nearly every Swift codebase already
+agrees with them, for example `force_cast`, `line_length` and
+`trailing_semicolon`. Turn one off with `disabled_rules`.
 
----
-
-## Rule Categories
-
-SwiftLint rules fall into three categories:
-
-### Default rules
-
-Enabled automatically. These cover widely agreed-upon conventions (e.g., `line_length`, `force_cast`, `trailing_semicolon`). Disable specific ones via `disabled_rules` in `.swiftlint.yml`.
-
-### Opt-in rules
-
-Disabled by default because they are more opinionated or may not suit every project. Enable selectively via `opt_in_rules`:
+**Opt-in.** Off out of the box because they take a stronger position. A fuller
+opt-in list than the starter config:
 
 ```yaml
 opt_in_rules:
-  - empty_count
+  - accessibility_label_for_image
+  - accessibility_trait_for_button
   - closure_spacing
-  - force_unwrapping
-  - sorted_imports
-  - contains_over_filter_count
-  - first_where
-  - last_where
-  - modifier_order
-  - vertical_whitespace_opening_braces
+  - empty_count
   - explicit_init
+  - force_unwrapping
   - joined_default_parameter
-  - redundant_nil_coalescing
   - private_swiftui_state
+  - redundant_nil_coalescing
+  - sorted_imports
   - unhandled_throwing_task
-  - accessibility_label_for_image
-  - accessibility_trait_for_button
+  - vertical_whitespace_opening_braces
 ```
 
-### Analyzer rules
+**Analyzer.** Need type information from the compiler, so they only run under
+`swiftlint analyze` fed with compiler logs. See
+[custom rules and analyze](custom-rules-and-analyze.md).
 
-Require the Swift compiler's AST information. Must be run via `swiftlint analyze` with compiler logs. See the custom rules and analyze reference linked from SKILL.md.
+## Looking rules up
 
-```yaml
-analyzer_rules:
-  - unused_import
-  - unused_declaration
+```bash
+swiftlint rules               # all rules, with enabled / disabled / correctable columns
+swiftlint rules --enabled     # just the enabled ones
+swiftlint rules --disabled    # just the disabled ones
+swiftlint rules force_unwrapping   # one rule in detail
 ```
 
-## Browsing Rules
+## Rules you will meet early
+
+### Default rules with options
+
+| Rule | Checks | Options |
+|---|---|---|
+| `line_length` | characters per line | `warning`, `error`, `ignores_urls`, `ignores_comments`, `ignores_interpolated_strings` |
+| `file_length` | lines per file | `warning`, `error`, `ignore_comment_only_lines` |
+| `type_body_length` | lines inside a type body | `warning`, `error` |
+| `function_body_length` | lines inside a function body | `warning`, `error` |
+| `function_parameter_count` | number of parameters | `warning`, `error`, `ignores_default_parameters` |
+| `cyclomatic_complexity` | branching complexity | `warning`, `error`, `ignores_case_statements` |
+| `nesting` | how deep types and functions nest | `type_level`, `function_level` |
+| `blanket_disable_command` | a `swiftlint:disable` that silences the rest of the file | `allowed_rules`, `always_blanket_disable` |
+| `identifier_name` | identifier length and casing | `min_length`, `max_length`, `excluded` (short names such as `id`, `x`, `i`) |
+| `type_name` | type name length and casing | `min_length`, `max_length`, `excluded` |
+| `large_tuple` | tuple arity | `warning`, `error` |
+| `force_cast` | `as!` | severity only |
+| `force_try` | `try!` | severity only |
+| `todo` | `// TODO:` and `// FIXME:` | severity only |
+| `trailing_whitespace` | spaces at line end | `ignores_empty_lines`, `ignores_comments` |
+| `trailing_comma` | commas after the last element | `mandatory_comma` (`true` demands them) |
+| `vertical_whitespace` | runs of blank lines | `max_empty_lines` |
+| `opening_brace` | `{` kept on the declaration line | `allow_multiline_func` |
+| `colon` | spacing around colons | `flexible_right_spacing`, `apply_to_dictionaries` |
+| `deployment_target` | `@available` / `#available` checks the deployment target already guarantees | `iOS_deployment_target`, `macOS_deployment_target`, and siblings |
+
+### Opt-in rules worth considering
+
+| Rule | Why turn it on |
+|---|---|
+| `force_unwrapping` | Every `!` is a potential crash. Relax it for tests in a child config. |
+| `private_swiftui_state` | `@State`, `@StateObject` and `@FocusState` must be `private`, so nothing outside the view can mutate its state. |
+| `unhandled_throwing_task` | `Task { try ... }` with no `do/catch` drops its error on the floor. |
+| `sorted_imports` | Alphabetical imports mean fewer merge conflicts. Correctable. |
+| `modifier_order` | Declaration modifiers always in the same order. Correctable. |
+| `accessibility_label_for_image` | Images must carry an accessibility label. |
+| `accessibility_trait_for_button` | Tappable elements must carry a button trait. |
+| `empty_count` | `.isEmpty` rather than `.count == 0`. |
+| `closure_spacing` | Spaces just inside closure braces. |
+| `contains_over_filter_count` | `.contains` rather than `.filter { }.count`. |
+| `first_where` / `last_where` | `.first(where:)` rather than `.filter { }.first`. |
+| `redundant_nil_coalescing` | Catches `value ?? nil`. |
+| `implicit_return` | Single-expression bodies drop the `return`. |
+| `self_binding` | One consistent name when rebinding `self` (`guard let self`); option `bind_identifier`. |
+| `shorthand_optional_binding` | `if let name` over `if let name = name` (Swift 5.7 and later). |
+| `expiring_todo` | TODO/FIXME comments carrying a date escalate to warnings, then errors, once overdue; thresholds and severities configurable. |
 
-List all rules and their status:
+### Analyzer rules
 
-```sh
-swiftlint rules                    # all rules with enabled/disabled/correctable status
-swiftlint rules --enabled          # only currently enabled rules
-swiftlint rules --disabled         # only currently disabled rules
-swiftlint rules <rule_identifier>  # detailed info for one rule
-```
+| Rule | Finds |
+|---|---|
+| `unused_import` | imports nothing in the file needs; correctable |
+| `unused_declaration` | private declarations that nothing references |
+| `capture_variable` | mutable variables captured by a closure |
+| `explicit_self` | instance member access without `self.` |
+| `typesafe_array_init` | `Array(items.map { ... })` where the `map` result is already an array |
 
-The official [rule directory](https://realm.github.io/SwiftLint/rule-directory.html) provides descriptions, configuration options, and examples for every rule.
-
-Do not memorize or transcribe the rule directory. Look up specific rules when needed.
-
-## Commonly Encountered Rules Quick Reference
-
-An agent writing or reviewing Swift code should understand what these frequently triggered rules enforce. Each rule can be configured in `.swiftlint.yml` using the rule identifier as a key.
-
-### Default rules (enabled automatically)
-
-| Rule | What it enforces | Key config options |
-| ------ | ------------------ | -------------------- |
-| `line_length` | Max characters per line | `warning`, `error`, `ignores_urls`, `ignores_comments`, `ignores_interpolated_strings` |
-| `file_length` | Max lines per file | `warning`, `error`, `ignore_comment_only_lines` |
-| `type_body_length` | Max lines in a type body | `warning`, `error` |
-| `function_body_length` | Max lines in a function body | `warning`, `error` |
-| `function_parameter_count` | Max parameters per function | `warning`, `error`, `ignores_default_parameters` |
-| `cyclomatic_complexity` | Max branching complexity | `warning`, `error`, `ignores_case_statements` |
-| `nesting` | Max nesting depth | `type_level`, `function_level` |
-| `blanket_disable_command` | Prevents `swiftlint:disable` from disabling rules for the rest of the file | `allowed_rules`, `always_blanket_disable` |
-| `identifier_name` | Naming length and conventions | `min_length`, `max_length`, `excluded` (list of allowed short names like `id`, `x`, `i`) |
-| `type_name` | Type naming length and conventions | `min_length`, `max_length`, `excluded` |
-| `large_tuple` | Max tuple size | `warning`, `error` |
-| `force_cast` | Flags `as!` | severity only |
-| `force_try` | Flags `try!` | severity only |
-| `todo` | Flags `// TODO:` and `// FIXME:` | severity only |
-| `trailing_whitespace` | Trailing spaces on lines | `ignores_empty_lines`, `ignores_comments` |
-| `trailing_comma` | Trailing commas in collections | `mandatory_comma` (when `true`, *requires* trailing commas) |
-| `vertical_whitespace` | Max consecutive blank lines | `max_empty_lines` |
-| `opening_brace` | Brace placement (`{` on same line) | `allow_multiline_func` |
-| `colon` | Spacing around colons | `flexible_right_spacing`, `apply_to_dictionaries` |
-| `deployment_target` | Flags `@available` / `#available` checks that use versions already satisfied by the deployment target | `iOS_deployment_target`, `macOS_deployment_target`, etc. |
-
-### High-value opt-in rules
-
-| Rule | What it enforces | Why enable it |
-| ------ | ------------------ | --------------- |
-| `force_unwrapping` | Flags `!` unwraps | Catches crashes; relax in tests via child config |
-| `private_swiftui_state` | `@State`, `@StateObject`, `@FocusState` must be `private` | Prevents accidental external mutation of view state |
-| `unhandled_throwing_task` | `Task { try ... }` without `do/catch` | Silently swallowed errors in async contexts |
-| `sorted_imports` | Import statements in alphabetical order | Reduces merge conflicts; auto-correctable |
-| `modifier_order` | Consistent declaration modifier ordering | Readability; auto-correctable |
-| `accessibility_label_for_image` | Images must have accessibility labels | Accessibility compliance |
-| `accessibility_trait_for_button` | Buttons must have accessibility traits | Accessibility compliance |
-| `empty_count` | Use `.isEmpty` instead of `.count == 0` | Performance and clarity |
-| `closure_spacing` | Spaces inside closure braces | Formatting consistency |
-| `contains_over_filter_count` | `.contains` instead of `.filter { }.count` | Performance |
-| `first_where` / `last_where` | `.first(where:)` instead of `.filter { }.first` | Performance |
-| `redundant_nil_coalescing` | Flags `x ?? nil` | Dead code |
-| `implicit_return` | Single-expression returns don't need `return` | Modern Swift style |
-| `self_binding` | Consistent `guard let self` naming | Configurable: `bind_identifier` |
-| `shorthand_optional_binding` | `if let x` instead of `if let x = x` | Swift 5.7+ style |
-| `expiring_todo` | TODOs/FIXMEs with dates become warnings or errors after expiry | Project hygiene with configurable thresholds and severities |
-
-### Analyzer rules (require compiler logs)
-
-| Rule | What it enforces |
-| ------ | ------------------ |
-| `unused_import` | Flags unnecessary `import` statements; auto-correctable |
-| `unused_declaration` | Flags private declarations never referenced |
-| `capture_variable` | Flags mutable variables captured by closures |
-| `explicit_self` | Requires `self.` for instance members |
-| `typesafe_array_init` | Flags `Array(x.map { ... })` → use `x.map { ... }` directly |
-
-### Per-rule configuration pattern
-
-Every rule that accepts configuration uses its identifier as the YAML key:
+## Configuring one rule
+
+Each configurable rule takes its identifier as a YAML key:
 
 ```yaml
-# Threshold-based rules use warning/error:
-line_length:
+line_length:                 # thresholds
   warning: 140
   error: 200
 
-# Boolean option rules:
-trailing_comma:
+trailing_comma:              # boolean option
   mandatory_comma: true
 
-# Rules with excluded identifiers:
-identifier_name:
-  excluded:
-    - id
-    - x
-    - y
+identifier_name:             # identifiers exempt from the rule
+  excluded: [id, x, y]
 
-# Rules with a single severity override:
-force_cast: error    # shorthand for severity: error
+force_cast: error            # shorthand for severity: error
 
-# Deployment target rule:
-deployment_target:
+deployment_target:           # minimum versions already guaranteed
   iOS_deployment_target: "16.0"
 ```
 
-Run `swiftlint rules <rule_identifier>` to see all available configuration keys for any rule.
-
-## Suppression Syntax
-
-### Single-line suppressions
+## Suppression syntax
 
 ```swift
-// swiftlint:disable:next force_cast
-let view = object as! UIView
+// swiftlint:disable:next force_unwrapping
+let icon = iconsByKind[kind]!                             // next line
 
-let value = dict["key"]! // swiftlint:disable:this force_unwrapping
+let port = Int(raw)! // swiftlint:disable:this force_unwrapping   // same line
 
-// swiftlint:disable:previous large_tuple
+let host = hosts[0]!
+// swiftlint:disable:previous force_unwrapping           // previous line
 ```
 
-- `:next`  -  suppresses on the next line
-- `:this`  -  suppresses on the same line
-- `:previous`  -  suppresses on the previous line
-
-### Region suppressions
+A region can name several rules separated by spaces:
 
 ```swift
 // swiftlint:disable cyclomatic_complexity function_body_length
-func complexLegacyFunction() {
-    // ... long function ...
+func migrate(_ record: LegacyRecord) {
+    // many branches
 }
 // swiftlint:enable cyclomatic_complexity function_body_length
 ```
 
-Multiple rules can be listed in one directive, separated by spaces.
+Leaving out `// swiftlint:enable all` after `// swiftlint:disable all` switches
+the linter off for the remainder of the file.
 
-### Disable all rules
-
-```swift
-// swiftlint:disable all
-// ... entire block is unlinted ...
-// swiftlint:enable all
-```
+## Suppression policy
 
-If you forget `// swiftlint:enable all`, the rest of the file is unlinted. This is a common mistake.
+- `disable all` is reserved for generated code that the config genuinely
+  cannot exclude.
+- Put a short justification after the directive:
 
-## Suppression Policy
+  ```swift
+  // swiftlint:disable:next force_cast - storyboard guarantees this cell class
+  let cell = collection.dequeueReusableCell(withReuseIdentifier: "Tile", for: path) as! TileCell
+  ```
 
-- **Target specific rules.** Never use `// swiftlint:disable all` unless the block is generated code that cannot be excluded via config.
-- **Add a reason.** Follow the suppression with a brief comment explaining why:
-
-```swift
-// swiftlint:disable:next force_cast  -  guaranteed by Interface Builder outlet type
-let cell = tableView.dequeueReusableCell(...) as! CustomCell
-```
-
-- **Re-enable after regions.** Always pair `disable` with `enable`.
-- **Prefer config-level exclusion** for entire files or directories of generated code.
-- **Review suppressions in code review.** Inline suppressions should be as scrutinized as the code they protect.
-- **Treat suppressions as tech debt.** Track and reduce them over time.
+- Every `disable` has an `enable`.
+- Whole generated files or folders go in `excluded`, not behind comments.
+- Review suppressions as carefully as the code around them.
+- Count them as technical debt; track them and bring the number down.
 
 ## Baselines
 
-Baselines record all existing violations so only new violations are reported.
-
-### Creating a baseline
-
-```sh
-swiftlint --write-baseline .swiftlint.baseline
-```
-
-This creates a JSON file listing every current violation by file, line, and rule. Commit this file to the repository.
-
-### Using a baseline
-
-```sh
-swiftlint --baseline .swiftlint.baseline
-```
-
-Violations matching the baseline are suppressed. New violations (new files, new lines, new rules) are reported normally.
-
-### Updating a baseline
-
-After fixing violations, regenerate:
-
-```sh
-swiftlint --write-baseline .swiftlint.baseline
-```
-
-The new baseline will be smaller. Commit the update.
-
-### Baseline in CI
-
-```sh
-swiftlint --strict --baseline .swiftlint.baseline --reporter github-actions-logging
-```
-
-This fails the build only on new violations not present in the baseline.
-
-### Baseline vs suppressions
-
-| Approach | When to use |
-| -------- | ----------- |
-| Baseline | Adopting SwiftLint in a large existing codebase |
-| Inline suppression | Specific intentional deviation from a rule |
-| `disabled_rules` | Team disagrees with a rule project-wide |
-| `excluded` paths | Generated or vendored code |
-| Child config | Different rules for test vs production code |
+- `swiftlint --write-baseline .swiftlint.baseline` writes a JSON file listing
+  every current violation with its file, line and rule. Commit it.
+- `swiftlint --baseline .swiftlint.baseline` hides violations that match an
+  entry. New files, new lines and newly triggered rules still report.
+- After fixing some violations, run `--write-baseline` again and commit the
+  smaller file.
+- CI that only fails on new violations:
+  `swiftlint --strict --baseline .swiftlint.baseline --reporter github-actions-logging`
 
-## False Positives
+### Choosing a tool
 
-When SwiftLint flags code incorrectly:
+| Situation | Reach for |
+|---|---|
+| Switching lint on in a large existing codebase | baseline |
+| One deliberate exception in one place | inline suppression with a reason |
+| The team disagrees with a rule everywhere | `disabled_rules` |
+| Generated or vendored sources | `excluded` |
+| Tests need different limits than production | child config |
 
-1. **Check if it's a real false positive** by reading the rule description in the [rule directory](https://realm.github.io/SwiftLint/rule-directory.html).
-2. **Check your config**  -  threshold tuning may resolve it (e.g., raising `line_length` for a file with long URLs).
-3. **Suppress with a reason** if it's genuinely incorrect.
-4. **File an issue** at [realm/SwiftLint](https://github.com/realm/SwiftLint/issues) if the false positive is reproducible and affects others.
+## False positives
 
-## Generated Code and Test Targets
+1. Read the rule's page in the directory to confirm it really misfired.
+2. Try tuning instead of silencing, for example a higher `line_length` for
+   lines dominated by long URLs.
+3. If it is still wrong, suppress with a reason.
+4. Report a minimal reproduction to the realm/SwiftLint issue tracker.
 
-### Generated code
+## Generated code and tests
 
-Exclude generated code directories in `.swiftlint.yml`:
+Keep generated sources out of the lint pass entirely:
 
 ```yaml
 excluded:
@@ -286,21 +201,20 @@ excluded:
   - "**/*.generated.swift"
 ```
 
-This is preferable to inline `// swiftlint:disable all` markers because it keeps generated files completely out of the lint pass.
+That is cleaner than a `disable all` at the top of each file.
 
-### Test targets
-
-Tests legitimately use patterns that production code should avoid (force unwraps, long functions, etc.). Use a child `.swiftlint.yml` in the test directory:
+Tests get a looser child config instead of an exclusion:
 
 ```yaml
 # Tests/.swiftlint.yml
 disabled_rules:
-  - force_unwrapping
-  - force_try
+  - file_length
   - force_cast
+  - force_try
+  - force_unwrapping
   - function_body_length
   - type_body_length
-  - file_length
 ```
 
-This is better than excluding tests entirely, because tests still benefit from formatting rules, naming conventions, and other applicable checks.
+Tests still benefit from formatting, naming and the rest of the rules, which a
+full exclusion would throw away.