@mmerterden/multi-agent-pipeline 20.7.0 → 20.8.0

package/pipeline/skills/shared/external/swiftlint/references/adoption-and-configuration.md

@@ -1,297 +1,230 @@
-# Adoption and Configuration
+# Adopting and Configuring SwiftLint
 
-Detailed guidance on installing SwiftLint, configuring `.swiftlint.yml`, and rolling out linting in existing codebases.
+Back to [SKILL.md](../SKILL.md).
 
-## Contents
+## Ways to install
 
-- [Installation Paths](#installation-paths)
-- [Configuration File Discovery](#configuration-file-discovery)
-- [Configuration Deep Dive](#configuration-deep-dive)
-- [Severity Tuning](#severity-tuning)
-- [Environment Variable Interpolation](#environment-variable-interpolation)
-- [Nested and Child Configurations](#nested-and-child-configurations)
-- [Remote Configuration](#remote-configuration)
-- [Rollout Strategy for Existing Codebases](#rollout-strategy-for-existing-codebases)
+| Method | Command or source | Good fit |
+|---|---|---|
+| SwiftLintPlugins package | SwiftPM dependency on `SimplyDanny/SwiftLintPlugins` | The default whenever a `Package.swift` exists; the version is pinned by resolution |
+| Homebrew | `brew install swiftlint` | a CLI on build agents, in git hooks, or on its own |
+| Mint | `mint install realm/SwiftLint` | projects whose tool versions Mint already manages |
+| CocoaPods | `pod 'SwiftLint'` | Older CocoaPods projects; the binary lands at `${PODS_ROOT}/SwiftLint/swiftlint` |
+| Release binary | the project's GitHub releases page (github.com/realm/SwiftLint/releases) | Locked-down CI images |
 
----
+For day-to-day local linting the build tool plugin beats every other option on
+the list. Setup steps are in
+[integrations guide](plugins-run-scripts-and-integrations.md).
 
-## Installation Paths
+## How SwiftLint finds its config
 
-| Method | When to use |
-| -------- | ------------- |
-| **SwiftLintPlugins SPM package** | Default for any project with `Package.swift`. Pins version automatically. |
-| **Homebrew** (`brew install swiftlint`) | CI runners, pre-commit hooks, standalone CLI usage. |
-| **Mint** (`mint install realm/SwiftLint`) | Teams using Mint for tool management. |
-| **CocoaPods** (`pod 'SwiftLint'`) | Legacy projects already using CocoaPods. Binary is at `${PODS_ROOT}/SwiftLint/swiftlint`. |
-| **Pre-built binary** | Download from [GitHub releases](https://github.com/realm/SwiftLint/releases). Useful for controlled CI environments. |
+- The top-level `.swiftlint.yml` is the main configuration. For each file,
+  SwiftLint searches upward from the file's folder, and the nearest
+  `.swiftlint.yml` it meets may be merged on top.
+- No file anywhere means the built-in defaults apply.
+- The root file governs the whole tree unless a nested file refines a subtree.
+- A given file gets at most one nested config merged in.
+- Passing `--config` switches discovery off, nested lookup included.
 
-The build tool plugin (via `SwiftLintPlugins`) is recommended over all other local integration methods. See the plugins and integrations reference linked from SKILL.md for setup details.
+Where each runner starts looking:
 
-## Configuration File Discovery
+| Runner | Working directory |
+|---|---|
+| Build tool plugin | the highest `.swiftlint.yml` inside the package or project folder, or the package/project root when there is none |
+| Run script phase | `${SRCROOT}`, or whatever build setting the script uses |
+| Plain CLI | the shell's current directory |
 
-SwiftLint treats the top-level `.swiftlint.yml` as the main configuration, then optionally merges the nearest nested `.swiftlint.yml` found while walking up from an individual file.
+## Key-by-key
 
-- If no config is found, SwiftLint uses its built-in defaults.
-- A project root config applies to all files unless a nested config refines it for a subtree.
-- At most one nested `.swiftlint.yml` is merged for any given file.
-- Passing `--config` overrides automatic discovery entirely and disables nested-config lookup.
-
-Working directory behavior:
-- The build tool plugin uses the topmost `.swiftlint.yml` within the package/project directory as its working directory, and falls back to the package/project root if no config file is found there.
-- Run scripts use `${SRCROOT}` or the Xcode build setting for the working directory.
-- CLI invocations use the shell's current directory.
-
-## Configuration Deep Dive
-
-### Rule control keys
+### Rule selection
 
 ```yaml
-# Enable defaults minus these:
-disabled_rules:
-  - trailing_whitespace
-  - todo
-
-# Add these on top of defaults:
 opt_in_rules:
-  - empty_count
   - closure_spacing
-  - sorted_imports
-  - vertical_whitespace_opening_braces
   - contains_over_filter_count
+  - empty_count
   - first_where
   - last_where
   - modifier_order
+  - sorted_imports
+  - vertical_whitespace_opening_braces
 ```
 
-`only_rules` is mutually exclusive with `disabled_rules` and `opt_in_rules`. Use it only when you want to start from an empty rule set and explicitly list every rule:
+`only_rules` starts from nothing and runs exactly what you list:
 
 ```yaml
 only_rules:
-  - line_length
   - force_cast
   - force_try
+  - line_length
 ```
 
-### Analyzer rules
-
-Analyzer rules require passing compiler logs to SwiftLint. They are not included in default or opt-in sets:
+Analyzer rules sit outside both the default and opt-in sets and have their own
+key:
 
 ```yaml
 analyzer_rules:
-  - unused_import
   - unused_declaration
+  - unused_import
 ```
 
-See the custom rules and analyze reference linked from SKILL.md.
-
-### Path control
+### Paths
 
 ```yaml
-included:
-  - Sources
-  - Tests
-
 excluded:
-  - .build
-  - DerivedData
-  - Carthage
-  - Pods
-  - "**/Generated"
   - "**/Snapshots"
+  - "**/Generated"
+  - Pods
+  - Carthage
+  - DerivedData
+  - .build
 ```
 
-`included` and `excluded` support glob patterns. Paths are relative to the config file's directory.
+`included` and `excluded` take globs. Paths resolve relative to the folder that
+holds the config file.
 
-### Reporter
+### Output and exit behaviour
 
-```yaml
-reporter: xcode    # default  -  Xcode-compatible warnings/errors
-# reporter: json
-# reporter: sarif
-# reporter: checkstyle
-# reporter: csv
-# reporter: emoji
-# reporter: github-actions-logging
-```
+Reporters: `xcode` (the default), `json`, `sarif`, `checkstyle`, `csv`,
+`emoji`, `github-actions-logging`.
 
-Use `sarif` for GitHub code scanning integration. Use `json` for custom tooling. Use `github-actions-logging` for inline PR annotations without SARIF upload.
+- `sarif` for code scanning uploads.
+- `json` when your own scripts consume the output.
+- `github-actions-logging` for inline pull request annotations with no SARIF
+  upload step.
 
-### Global modifiers
+Flags:
 
-```yaml
-strict: true       # all warnings become errors
-# lenient: true    # all errors become warnings (useful during initial adoption)
-allow_zero_lintable_files: true  # don't error when no .swift files are found (useful in CI)
-```
+- `strict: true` makes warnings count as errors.
+- `lenient: true` makes errors count as warnings, which helps during the first
+  days of adoption.
+- `allow_zero_lintable_files: true` keeps CI green on jobs that happen to see
+  no Swift files.
 
-## Severity Tuning
+## Tuning thresholds
 
-Most rules accept `warning` and `error` thresholds:
+Most measuring rules accept a `warning` and an `error` level.
 
 ```yaml
-line_length:
-  warning: 140
-  error: 200
-  ignores_comments: true
-  ignores_urls: true
-  ignores_interpolated_strings: true
+identifier_name:
+  excluded: [i, id, j, to, x, y]
+  min_length: {error: 1, warning: 2}
+  max_length: {error: 60, warning: 50}
 
-type_body_length:
-  warning: 300
-  error: 500
+nesting: {function_level: 3, type_level: 2}
 
-file_length:
-  warning: 500
-  error: 1000
-  ignore_comment_only_lines: true
+cyclomatic_complexity: {ignores_case_statements: true, error: 20, warning: 10}
 
-function_body_length:
-  warning: 50
-  error: 100
+function_body_length: {error: 100, warning: 50}
 
-cyclomatic_complexity:
-  warning: 10
-  error: 20
-  ignores_case_statements: true
+type_body_length: {error: 500, warning: 300}
 
-nesting:
-  type_level: 2
-  function_level: 3
+file_length: {ignore_comment_only_lines: true, error: 1000, warning: 500}
 
-identifier_name:
-  min_length:
-    warning: 2
-    error: 1
-  max_length:
-    warning: 50
-    error: 60
-  excluded:
-    - id
-    - x
-    - y
-    - i
-    - j
-    - to
+line_length:
+  ignores_urls: true
+  ignores_comments: true
+  ignores_interpolated_strings: true
+  error: 200
+  warning: 140
 ```
 
-Check available configuration keys for any rule with `swiftlint rules <rule_name>` or the [rule directory](https://realm.github.io/SwiftLint/rule-directory.html).
+To see which keys a rule accepts, run `swiftlint rules <rule_name>` or open
+its page in the rule directory.
 
-## Environment Variable Interpolation
+## Environment variables in config values
 
-Configuration values can reference environment variables:
+Values can interpolate environment variables:
 
 ```yaml
-included:
-  - ${PROJECT_DIR}/Sources
-
 excluded:
-  - ${PROJECT_DIR}/Generated
-```
-
-This is useful when SwiftLint is invoked from different working directories (e.g., run scripts vs CLI).
-
-## Nested and Child Configurations
-
-SwiftLint supports both explicit parent/child config chaining and automatic nested configs.
-
-### Explicit local parent/child configs
-
-Use `child_config` and `parent_config` to layer configs deliberately:
-
-```yaml
-# .swiftlint.yml
-child_config: .swiftlint-strict.yml
-parent_config: Base/.swiftlint-base.yml
+  - ${PROJECT_DIR}/Generated   # code generator output
+included:
+  - ${PROJECT_DIR}/Sources     # app code
 ```
 
-`child_config` refines the current config with higher priority. `parent_config` provides lower-priority defaults.
+This keeps paths stable when the same config is used from a run script and
+from a terminal that starts in a different folder.
 
-### Automatic nested configs
+## Parent, child and nested configs
 
-A `.swiftlint.yml` in a subdirectory can also act as a nested child config for files in that subtree:
+Two mechanisms exist: explicit chaining and automatic nesting.
 
-```text
-MyProject/
-├── .swiftlint.yml          # root config
-├── Sources/
-│   └── .swiftlint.yml      # stricter config for production code (optional)
-└── Tests/
-    └── .swiftlint.yml      # relaxed config for test code
-```
-
-Example child config for tests:
+- `child_config: <path>` layers another file on top, with higher priority.
+- `parent_config: <path>` pulls in a file underneath, with lower priority.
+- Automatic nesting: a `.swiftlint.yml` inside a subfolder (a stricter one in
+  `Sources/`, a looser one in `Tests/`) acts as a child for that subtree.
 
 ```yaml
 # Tests/.swiftlint.yml
 disabled_rules:
-  - force_unwrapping
-  - force_try
   - force_cast
-
-file_length:
-  warning: 800
-  error: 1500
-
-function_body_length:
-  warning: 100
-  error: 200
+  - force_try
+  - force_unwrapping
+function_body_length: {error: 200, warning: 100}
+file_length: {error: 1500, warning: 800}
 ```
 
-Rule state from parent and child configs is merged. A child config only overrides the parent when it explicitly states the opposite for the same rule. For example, a parent `disabled_rules` entry still applies unless the child opt-ins that same rule, and a parent opt-in still applies unless the child disables it.
-
-For `included` and `excluded`, SwiftLint applies special merge behavior: paths are resolved relative to each config file, child `excluded` entries can remove parent `included` entries, and child `included` entries can re-include paths excluded by the parent.
+How merging behaves:
 
-Nested configs are only used when SwiftLint discovers configs automatically. If you pass `--config`, nested discovery is disabled.
+- Rule on/off state is merged. A child changes a rule only when it says the
+  opposite about that same rule: a rule the parent disabled stays off unless
+  the child opts it in, and a parent opt-in stays on unless the child disables
+  it.
+- `included` and `excluded` are special. Each is resolved relative to its own
+  config file, a child's `excluded` can carve paths out of the parent's
+  `included`, and a child's `included` can bring back paths the parent
+  excluded.
+- Nested files only take part in automatic discovery. `--config` turns them
+  off.
+- With several `--config` flags, each later file overrides the earlier ones.
 
-### CLI multi-config
+## Remote parent configs
 
-Pass multiple configs via CLI. Later configs override earlier ones:
-
-```sh
-swiftlint --config .swiftlint.yml --config .swiftlint-strict.yml
-```
-
-## Remote Configuration
-
-Pull a shared team configuration using `parent_config` with an HTTPS URL:
+A shared team config can live behind HTTPS:
 
 ```yaml
-parent_config: https://example.com/team-swiftlint.yml
-remote_timeout: 2           # seconds, default is 2
-remote_timeout_if_cached: 1  # seconds, used when a cached version exists
+parent_config: https://config.example.org/lint/swiftlint-base.yml
+remote_timeout: 2
+remote_timeout_if_cached: 1
 ```
 
-Remote configs are cached locally. If the fetch fails or times out, the cached version is used. If no cache exists and the fetch fails, SwiftLint fails with an error.
-
-**Caution:** Remote configs introduce a network dependency. Ensure CI runners can reach the URL, or use a local copy as a fallback.
-
-## Rollout Strategy for Existing Codebases
+- `remote_timeout` defaults to 2 seconds.
+- `remote_timeout_if_cached` is the shorter wait used when a cached copy is on
+  disk.
+- SwiftLint caches the download. If a fetch fails or times out it falls back
+  to the cache; with no cache and no network it stops with an error.
+- This makes lint depend on the network. Check that CI can reach the URL or
+  keep a local copy to fall back on.
 
-Adopting SwiftLint in an existing project without disrupting the team:
+## Rolling out on an existing codebase
 
-### Phase 1: Baseline
+### Phase 1: take a snapshot
 
-1. Install SwiftLint with defaults (or your team's starter config).
-2. Run once to see the violation landscape: `swiftlint --reporter json | python3 -m json.tool | head -50`
-3. Generate a baseline: `swiftlint --write-baseline .swiftlint.baseline`
-4. Commit the baseline and config. CI now passes with `--baseline .swiftlint.baseline`.
+1. Install with the defaults or the starter config from SKILL.md.
+2. Look at what you are dealing with:
+   `swiftlint lint --reporter json | python3 -m json.tool | less`
+3. Record it: `swiftlint --write-baseline .swiftlint.baseline`.
+4. Put both files, the new baseline and `.swiftlint.yml`, in one commit.
+5. CI now runs with `--baseline` and passes.
 
-### Phase 2: Stop the bleeding
+### Phase 2: no new violations
 
-1. CI enforces `swiftlint --strict --baseline .swiftlint.baseline`  -  no new violations allowed.
-2. The build tool plugin shows warnings locally (developers see issues as they edit).
-3. Do not enable `--fix` in CI or build phases.
+- CI runs `swiftlint --strict --baseline .swiftlint.baseline`.
+- Developers see warnings in Xcode through the plugin.
+- `--fix` stays out of CI and out of build phases.
 
-### Phase 3: Incremental cleanup
+### Phase 3: pay it down
 
-1. Pick a rule with many baseline violations. Fix violations in a dedicated PR.
-2. Regenerate the baseline after each cleanup PR.
-3. Add opt-in rules one at a time once the team is comfortable.
-4. Move toward removing the baseline entirely as violations are cleaned up.
+- Pick the rule with the most hits and fix it in a pull request of its own.
+- Regenerate the baseline after each such PR.
+- Turn on further opt-in rules one per change.
+- The goal is to delete the baseline file.
 
-### Phase 4: Mature enforcement
+### Phase 4: steady state
 
-1. Baseline is empty or removed.
-2. `--strict` in CI, build tool plugin in local builds.
-3. New opt-in rules go through team review before enabling.
-4. Consider analyzer rules for high-value checks like `unused_import`.
+- The baseline is empty or gone.
+- CI runs `--strict`; the plugin covers local builds.
+- Proposals for extra opt-in rules are reviewed by the team first.
+- Consider analyzer rules such as `unused_import`
+  (see [custom rules and analyze](custom-rules-and-analyze.md)).