@mmerterden/multi-agent-pipeline 20.7.0 → 20.8.0

package/pipeline/skills/shared/external/swiftlint/references/custom-rules-and-analyze.md

@@ -1,170 +1,161 @@
-# Custom Rules and Analyze
+# Custom Rules and `swiftlint analyze`
 
-Regex custom rules for project-specific enforcement, brief coverage of Swift custom rules, and the `swiftlint analyze` workflow.
+Back to [SKILL.md](../SKILL.md).
 
-## Contents
+## Regex rules in `custom_rules`
 
-- [Regex Custom Rules](#regex-custom-rules)
-- [Swift Custom Rules](#swift-custom-rules)
-- [SwiftLint Analyze](#swiftlint-analyze)
-- [When to Use Analyzer Rules](#when-to-use-analyzer-rules)
-
----
-
-## Regex Custom Rules
-
-Regex custom rules let you enforce project-specific patterns directly in `.swiftlint.yml` without building a custom SwiftLint binary.
+`custom_rules` in `.swiftlint.yml` enforces project-specific patterns with no
+custom build of SwiftLint.
 
 ```yaml
 custom_rules:
   no_print_statements:
-    name: "No print()"
-    regex: '^\s*print\s*\('
-    message: "Use os_log or Logger instead of print()"
     severity: warning
+    regex: "^\\s*print\\("
+    name: "No print"
+    message: "Route diagnostics through Logger (or os_log), not print."
     match_kinds:
       - identifier
 
   no_hardcoded_colors:
-    name: "No hardcoded colors"
-    regex: 'UIColor\(\s*red:|\.init\(\s*red:'
-    message: "Use Color asset catalog entries instead of hardcoded RGB values"
-    severity: warning
-
+    name: "Hard-coded color"
+    regex: "(UIColor\\(red:|\\.init\\(red:)"
+    message: "Pick a color from the asset catalog."
 
   todo_requires_ticket:
-    name: "TODO requires ticket"
-    regex: '//\s*TODO(?!.*\b[A-Z]+-\d+)'
-    message: "TODOs must reference a ticket (e.g., TODO: PROJ-123)"
+    name: "TODO without ticket"
+    regex: "//\\s*TODO(?!.*[A-Z]+-\\d+)"
+    message: "Reference a ticket such as ABC-123 in every TODO."
     severity: warning
 ```
 
-### Custom rule configuration keys
-
-| Key | Required | Description |
-| --- | -------- | ----------- |
-| `name` | No | Human-readable name shown in violations |
-| `regex` | Yes | The pattern to match |
-| `capture_group` | No | Which regex capture group to highlight; defaults to `0` (the whole match) |
-| `message` | No | Custom violation message |
-| `severity` | No | `warning` (default) or `error` |
-| `match_kinds` | No | Limit matches to specific syntax kinds (e.g., `comment`, `identifier`, `string`) |
-| `excluded_match_kinds` | No | Exclude specific syntax kinds from matching; cannot be combined with `match_kinds` |
-| `included` | No | Regex pattern for file paths to include (note: regex, not glob) |
-| `excluded` | No | Regex pattern for file paths to exclude (note: regex, not glob) |
-| `execution_mode` | No | Per-rule execution mode: `default`, `swiftsyntax`, or `sourcekit` |
-
-### match_kinds values
-
-Syntax token kinds that SwiftLint recognizes: `argument`, `attribute.builtin`, `attribute.id`, `buildconfig.id`, `buildconfig.keyword`, `comment`, `comment.mark`, `comment.url`, `doccomment`, `doccomment.field`, `identifier`, `keyword`, `number`, `objectliteral`, `parameter`, `placeholder`, `string`, `string_interpolation_anchor`, `typeidentifier`.
-
-Use `match_kinds` to avoid false positives. For example, matching `print` only in `identifier` context avoids flagging it inside strings or comments.
-
-**Regex flags:** Custom rule regexes run with `s` (dot matches newlines) and `m` (`^`/`$` match line boundaries) enabled by default. Prepend `(?-s)` if you don't want `.` to match newlines.
-
-**`only_rules` interaction:** If using `only_rules` alongside `custom_rules`, you must include the literal string `custom_rules` in your `only_rules` list, or custom rules will not run.
-
-**Execution mode:** Individual custom rules can set `execution_mode` to `default`, `swiftsyntax`, or `sourcekit`. You can also set a top-level `default_execution_mode` to apply the same mode across all custom regex rules unless a rule overrides it.
+### Keys
+
+| Key | Needed | Meaning |
+|---|---|---|
+| `name` | no | label shown in output |
+| `regex` | yes | pattern to search for |
+| `capture_group` | no | which group to highlight; `0`, the whole match, by default |
+| `message` | no | text of the violation |
+| `severity` | no | `error`, or `warning` when left out |
+| `match_kinds` | no | only count matches whose syntax kind is listed |
+| `excluded_match_kinds` | no | ignore matches of these kinds; cannot be used together with `match_kinds` |
+| `included` / `excluded` | no | file path filters written as regular expressions, not globs |
+| `execution_mode` | no | `default`, `swiftsyntax` or `sourcekit` |
+
+Accepted syntax kinds, grouped:
+
+- names and code: `identifier`, `typeidentifier`, `keyword`, `parameter`,
+  `argument`, `placeholder`
+- literals: `string`, `string_interpolation_anchor`, `number`, `objectliteral`
+- comments: `doccomment`, `doccomment.field`, `comment`, `comment.url`,
+  `comment.mark`
+- attributes and build configuration: `attribute.builtin`, `attribute.id`,
+  `buildconfig.keyword`, `buildconfig.id`
+
+Kinds are the main defence against noise: restricting the print rule to
+`identifier` stops it firing on the word "print" inside a string or comment.
+
+### Gotchas
+
+- Patterns are evaluated with the `s` and `m` flags already on. To keep `.`
+  from crossing line breaks, start the pattern with `(?-s)`.
+- Under `only_rules`, custom rules only run if the literal entry
+  `custom_rules` is in the list.
+- A top-level `default_execution_mode` (for instance `swiftsyntax`) applies to
+  every custom rule that does not declare its own `execution_mode`.
 
 ```yaml
 default_execution_mode: swiftsyntax
-
-custom_rules:
-  no_print_statements:
-    regex: '^\s*print\s*\('
-    execution_mode: sourcekit
+only_rules:
+  - custom_rules
+  - force_try
 ```
 
-## Swift Custom Rules
-
-SwiftLint supports rules written in Swift using the SwiftSyntax AST. These are more powerful than regex rules but require building SwiftLint from source with Bazel.
-
-This is an advanced workflow primarily useful for organizations that need precise AST-based enforcement. For most projects, regex custom rules are sufficient.
-
-If you need Swift custom rules:
+## Rules written in Swift
 
-1. Clone [realm/SwiftLint](https://github.com/realm/SwiftLint)
-2. Scaffold a new rule with `swift run swiftlint-dev rules template <RuleName>` or add it under `Source/SwiftLintBuiltInRules/Rules/`
-3. Register the rule so it becomes part of the executable (`make register` in the SwiftLint repo workflow)
-4. Build the binary with Bazel: `bazel build :swiftlint`
-5. Use the resulting custom `swiftlint` binary in your project
+Native rules walk the SwiftSyntax tree, so they can express things a regex
+never will. The price is building SwiftLint yourself with Bazel. This suits
+organisations that need exact AST-level checks; most teams are fine with regex
+rules, and it is outside what a normal project adoption needs.
 
-This is out of scope for typical project-level adoption.
+Outline:
 
-## SwiftLint Analyze
+1. Clone realm/SwiftLint.
+2. Generate the skeleton (`swift run swiftlint-dev rules template <NewRuleName>`)
+   or hand-write the file in `Source/SwiftLintBuiltInRules/Rules/`.
+3. Register it (`make register`).
+4. Build with `bazel build :swiftlint`.
+5. Point your tooling at the resulting binary.
 
-`swiftlint analyze` runs analyzer rules that require the Swift compiler's type-checked AST. These rules can detect issues like unused imports and unused declarations that are impossible to catch with syntactic analysis alone.
+## `swiftlint analyze`
 
-### Workflow
+Analyzer rules work on the type-checked AST, which lets them see things like
+imports nothing uses or declarations nothing calls. Plain syntax cannot answer
+those questions.
 
-1. Perform a **clean** build and capture the compiler log (incremental builds will fail):
+They need the log of a **clean** build; logs from incremental builds do not
+work.
 
-```sh
-# Xcode  -  clean build required
-xcodebuild -workspace MyApp.xcworkspace -scheme MyApp clean build \
-    | tee xcodebuild.log
+```bash
+# Xcode
+xcodebuild -workspace Harbor.xcworkspace -scheme Harbor clean build | tee xcode-build.log
 
-# SwiftPM  -  clean build required, -v needed for compiler command lines
+# SwiftPM: verbose mode (-v / --verbose) prints the compiler invocations SwiftLint needs
 swift package clean
-swift build -v 2>&1 | tee swift-build.log
+swift build --verbose 2>&1 | tee spm-build.log
 ```
 
-1. Run analyze with the compiler log:
+Run it:
 
-```sh
-swiftlint analyze --compiler-log-path xcodebuild.log
-```
-
-Or via the command plugin:
+```bash
+swiftlint analyze --compiler-log-path xcode-build.log
 
-```sh
+# through the command plugin
 swift package plugin swiftlint -- analyze --compile-commands .build/debug.yaml
 ```
 
-1. Configure which analyzer rules to enable:
+Enable the rules you want:
 
 ```yaml
-# .swiftlint.yml
 analyzer_rules:
-  - unused_import
   - unused_declaration
+  - unused_import
 ```
 
-### Autocorrect with analyze
-
-Analyzer rules that support autocorrect can fix issues:
+Correct what can be corrected:
 
-```sh
-swiftlint analyze --fix --compiler-log-path xcodebuild.log
+```bash
+swiftlint analyze --compiler-log-path spm-build.log --fix
 ```
 
-`unused_import` is the most commonly used correctable analyzer rule  -  it removes unnecessary import statements.
+`unused_import` is the correctable analyzer rule most teams actually use; it
+deletes the imports a file does not need.
 
-## When to Use Analyzer Rules
+## When analyzer rules pay off
 
-Analyzer rules are slower than regular rules because they require a full build first. Use them when:
+They are slow because they need a full build, so keep them in CI rather than
+in local builds:
 
-- **Codebase hygiene matters**: `unused_import` catches import bloat that accumulates over refactoring.
-- **Dead code detection**: `unused_declaration` finds private declarations that are never referenced.
-- **CI only**: Run analyzer rules in CI rather than on every local build to avoid slowing down the development loop.
+- import hygiene with `unused_import`;
+- dead private code with `unused_declaration`.
 
-A practical pattern is to run analyzer rules in a separate CI job that runs less frequently (e.g., nightly or on main branch only):
+A separate job that runs less often (nightly, or only on the main branch)
+works well:
 
 ```yaml
-# GitHub Actions  -  nightly analyze
+name: analyze
 on:
+  workflow_dispatch:
   schedule:
     - cron: '0 6 * * *'
-
 jobs:
-  analyze:
+  dead-code:
     runs-on: macos-latest
+    timeout-minutes: 60
     steps:
       - uses: actions/checkout@v4
-      - name: Build
-        run: swift build -v 2>&1 | tee swift-build.log
-      - name: Analyze
-        run: |
-          brew install swiftlint
-          swiftlint analyze --strict --compiler-log-path swift-build.log
+      - run: brew install swiftlint
+      - run: swift build --verbose 2>&1 | tee spm-build.log
+      - run: swiftlint analyze --compiler-log-path spm-build.log --strict
 ```