@mmerterden/multi-agent-pipeline 8.6.1 → 10.0.6

package/pipeline/skills/shared/external/swiftlint/SKILL.md

@@ -0,0 +1,337 @@
+---
+name: swiftlint
+description: "Configures and enforces SwiftLint in Swift projects using build tool plugins, run scripts, and CI. Covers .swiftlint.yml configuration, disabled_rules, opt_in_rules, only_rules, analyzer_rules, baselines, autocorrect, swiftlint:disable suppressions, reporter formats (sarif, json, checkstyle), strict and lenient modes, SwiftLintBuildToolPlugin via SimplyDanny/SwiftLintPlugins, swift package plugin swiftlint, Xcode run script phases, CI integration, multiple configuration files, and rollout strategies for existing codebases. Use when setting up SwiftLint, configuring lint rules, suppressing warnings, creating baselines, choosing between build tool plugin and run script, or integrating SwiftLint into CI."
+---
+
+# SwiftLint
+
+SwiftLint enforces Swift style and conventions by linting source files against a configurable rule set. It is the most widely adopted Swift linter. This skill covers setup, configuration, rule selection, suppression, CI integration, and rollout strategy.
+
+SwiftLint is a **style enforcement tool**, not a style guide. For underlying Swift naming and design conventions, see `swift-api-design-guidelines`. For architecture patterns, see `swift-architecture`.
+
+## Contents
+
+- [Recommended Setup](#recommended-setup)
+- [Configuration](#configuration)
+- [Rule Selection Strategy](#rule-selection-strategy)
+- [Suppressions](#suppressions)
+- [Baselines](#baselines)
+- [Autocorrect](#autocorrect)
+- [CI Integration](#ci-integration)
+- [Integration Decision Tree](#integration-decision-tree)
+- [Multiple Configurations](#multiple-configurations)
+- [Common Mistakes](#common-mistakes)
+- [Review Checklist](#review-checklist)
+- [References](#references)
+
+---
+
+## Recommended Setup
+
+**Default: build tool plugin via `SimplyDanny/SwiftLintPlugins`.**
+
+Add the plugin package to `Package.swift` or via Xcode's package dependencies:
+
+```swift
+// Package.swift
+dependencies: [
+  .package(url: "https://github.com/SimplyDanny/SwiftLintPlugins", from: "<reviewed-version>")
+]
+```
+
+For SwiftPM targets, apply the plugin:
+
+```swift
+.target(
+    name: "MyApp",
+    plugins: [.plugin(name: "SwiftLintBuildToolPlugin", package: "SwiftLintPlugins")]
+)
+```
+
+For Xcode projects without a `Package.swift`, add the package dependency in the project settings, then enable the plugin under the target's Build Phases or the package's plugin trust dialog.
+
+The build tool plugin runs SwiftLint automatically on every build. No run script required.
+
+> **First build**: Xcode prompts to trust the plugin. Select "Trust & Enable All" for the SwiftLintPlugins package.
+
+For alternatives (run scripts, command plugin, Homebrew CLI), see [references/plugins-run-scripts-and-integrations.md](references/plugins-run-scripts-and-integrations.md).
+
+## Configuration
+
+Create `.swiftlint.yml` at the project root. SwiftLint discovers this file by walking up from each source file's directory.
+
+```yaml
+# .swiftlint.yml  -  conservative starter config
+disabled_rules:
+  - trailing_whitespace
+  - todo
+
+opt_in_rules:
+  - empty_count
+  - closure_spacing
+  - force_unwrapping
+  - sorted_imports
+  - vertical_whitespace_opening_braces
+  - private_swiftui_state
+  - unhandled_throwing_task
+  - accessibility_label_for_image
+
+included:
+  - Sources
+  - Tests
+
+excluded:
+  - .build
+  - DerivedData
+  - "**/.build"
+  - "**/Generated"
+
+line_length:
+  warning: 140
+  error: 200
+
+type_body_length:
+  warning: 300
+  error: 500
+
+file_length:
+  warning: 500
+  error: 1000
+```
+
+Key configuration options:
+
+| Key | Purpose |
+|-----|---------|
+| `disabled_rules` | Turn off default-enabled rules |
+| `opt_in_rules` | Turn on rules not enabled by default |
+| `only_rules` | Use _only_ the listed rules (mutually exclusive with `disabled_rules`/`opt_in_rules`) |
+| `analyzer_rules` | Rules requiring compiler logs (run via `swiftlint analyze`) |
+| `baseline` | Path to an existing baseline file used to suppress known violations |
+| `write_baseline` | Path where SwiftLint should write a new baseline file |
+| `included` | Paths to lint (default: current directory) |
+| `excluded` | Paths to skip |
+| `strict` | Elevate all warnings to errors |
+| `lenient` | Downgrade all errors to warnings |
+| `allow_zero_lintable_files` | Suppress the error when no Swift files are found |
+| `reporter` | Output format: `xcode` (default), `json`, `checkstyle`, `sarif`, `csv`, `emoji`, etc. |
+
+For full configuration details including severity tuning, environment-variable interpolation, and nested/remote configs, see [references/adoption-and-configuration.md](references/adoption-and-configuration.md).
+
+## Rule Selection Strategy
+
+SwiftLint ships with three rule categories:
+
+1. **Default rules**  -  enabled automatically, cover widely accepted conventions
+2. **Opt-in rules**  -  disabled by default, enable selectively via `opt_in_rules`
+3. **Analyzer rules**  -  require compiler logs, enabled via `analyzer_rules`
+
+Browse the full categorized list at <https://realm.github.io/SwiftLint/rule-directory.html>.
+
+**Recommended approach for new projects:**
+
+1. Start with defaults. Run `swiftlint rules` to see which rules are enabled.
+2. Disable rules that conflict with your team's established conventions.
+3. Add opt-in rules one at a time. Review violations before committing each addition.
+4. Do not use `only_rules` unless you have a specific reason to start from zero.
+
+**Recommended approach for existing codebases:**
+
+1. Start with the default rule set.
+2. Create a baseline (see [Baselines](#baselines)) to suppress all existing violations.
+3. Enforce zero new violations in CI.
+4. Burn down baseline violations incrementally.
+
+Do not transcribe or memorize the rule directory. Look up rule identifiers and configuration options at the official rule directory when needed.
+
+## Suppressions
+
+Suppress SwiftLint for specific lines when a rule produces a false positive or when the violation is intentional and reviewed.
+
+```swift
+// swiftlint:disable:next force_cast
+let view = object as! UIView
+
+let legacy = try! JSONDecoder().decode(T.self, from: data) // swiftlint:disable:this force_try
+
+// swiftlint:disable:previous large_tuple
+```
+
+Disable for a region:
+
+```swift
+// swiftlint:disable cyclomatic_complexity
+func complexRouter(...) { ... }
+// swiftlint:enable cyclomatic_complexity
+```
+
+Disable all rules (use sparingly):
+
+```swift
+// swiftlint:disable all
+// ... generated or legacy code ...
+// swiftlint:enable all
+```
+
+**Policy:**
+- Prefer targeted single-rule suppressions over `all`.
+- Always re-enable after the region ends.
+- For generated code, prefer `excluded` paths in `.swiftlint.yml` over inline suppressions.
+- For test targets with different tolerance, use a child configuration (see [Multiple Configurations](#multiple-configurations)).
+
+For full suppression syntax, see [references/rules-suppressions-and-baselines.md](references/rules-suppressions-and-baselines.md).
+
+## Baselines
+
+Baselines let you adopt SwiftLint in an existing codebase without fixing every legacy violation first.
+
+**Create a baseline:**
+
+```sh
+swiftlint --write-baseline .swiftlint.baseline
+```
+
+This records all current violations. Future runs compare against this baseline and only report new violations.
+
+**Use the baseline:**
+
+```sh
+swiftlint --baseline .swiftlint.baseline
+```
+
+In CI, pass `--baseline` so only new violations fail the build. Burn down the baseline over time by fixing legacy violations and regenerating.
+
+For baseline workflows and rollout strategy, see [references/rules-suppressions-and-baselines.md](references/rules-suppressions-and-baselines.md).
+
+## Autocorrect
+
+SwiftLint can fix some violations automatically:
+
+```sh
+swiftlint --fix
+# or the legacy alias:
+swiftlint --autocorrect
+```
+
+**Warnings:**
+
+- **Never run `--fix` as a pre-compile build phase.** Auto-fixes modify source files. If run automatically on every build, this creates an unpredictable edit-build loop and can mask real issues.
+- Run `--fix` manually or in a dedicated CI step, then review the diff.
+- Not all rules support autocorrect. Check `swiftlint rules`  -  the "Correctable" column shows which rules can auto-fix.
+- Always commit or stash before running `--fix`.
+
+## CI Integration
+
+CI is the primary enforcement surface. A CI check ensures no one merges code that increases the violation count.
+
+**Recommended CI pattern:**
+
+```yaml
+# GitHub Actions example
+- name: Lint
+  run: |
+    brew install swiftlint
+    swiftlint --strict --reporter sarif > swiftlint.sarif
+```
+
+Key CI options:
+
+| Flag | Effect |
+|------|--------|
+| `--strict` | Exits non-zero on warnings (not just errors) |
+| `--reporter sarif` | GitHub Advanced Security compatible output |
+| `--reporter json` | Machine-readable output |
+| `--reporter checkstyle` | Jenkins/SonarQube compatible |
+| `--baseline .swiftlint.baseline` | Only fail on new violations |
+
+For SARIF upload to GitHub code scanning, add `github/codeql-action/upload-sarif` after the lint step.
+
+For full CI recipes and reporter details, see [references/plugins-run-scripts-and-integrations.md](references/plugins-run-scripts-and-integrations.md).
+
+## Integration Decision Tree
+
+Choose how to run SwiftLint based on project shape:
+
+| Scenario | Recommended integration |
+|----------|------------------------|
+| SwiftPM package or Xcode project with `Package.swift` | Build tool plugin via `SwiftLintPlugins` |
+| SwiftPM project needing CLI flags (`--fix`, `--baseline`) | Command plugin: `swift package plugin swiftlint` |
+| Xcode project without SwiftPM, team uses Homebrew | Run script build phase |
+| CI/CD pipeline | Homebrew or Docker install, run `swiftlint` directly |
+| Pre-commit hook | Homebrew install + `.pre-commit-config.yaml` or git hook script |
+
+The build tool plugin is preferred for local development because it requires no PATH configuration, pins the SwiftLint version via package resolution, and runs automatically on build.
+
+For detailed setup instructions for each integration, see [references/plugins-run-scripts-and-integrations.md](references/plugins-run-scripts-and-integrations.md).
+
+## Multiple Configurations
+
+SwiftLint supports layered configuration files. A `.swiftlint.yml` in a subdirectory inherits from and overrides the parent config.
+
+Common patterns:
+
+- **Relaxed test config**: place a `.swiftlint.yml` in `Tests/` that disables `force_unwrapping` and raises `file_length`
+- **Strict module config**: place a stricter `.swiftlint.yml` in a shared module directory
+- **Remote config**: use `parent_config` with an HTTPS URL to pull a shared team config (caching supported)
+
+```yaml
+# Tests/.swiftlint.yml  -  child config
+disabled_rules:
+  - force_unwrapping
+  - force_try
+
+file_length:
+  warning: 800
+```
+
+You can also pass multiple configs on the CLI:
+
+```sh
+swiftlint --config .swiftlint.yml --config .swiftlint-extra.yml
+```
+
+Later configs override earlier ones for overlapping keys.
+
+For nested config resolution, remote configs, and CLI multi-config details, see [references/adoption-and-configuration.md](references/adoption-and-configuration.md).
+
+## Common Mistakes
+
+1. **Running `--fix` in a build phase.** Auto-fixing on every build creates unpredictable source modifications. Run `--fix` manually.
+
+2. **Using `only_rules` without understanding the implication.** This disables all rules except those listed. Most teams should use `disabled_rules` + `opt_in_rules` instead.
+
+3. **Suppressing with `// swiftlint:disable all` and forgetting to re-enable.** This silently disables all linting for the rest of the file.
+
+4. **Not pinning the SwiftLint version.** Different versions have different default rules. Use the build tool plugin (version pinned via SPM) or pin in your `Brewfile` / CI config.
+
+5. **Excluding too broadly.** Excluding `Tests/` entirely means test code gets no linting. Use a child config with relaxed rules instead.
+
+6. **Ignoring the toolchain mismatch.** SwiftLint must be built with (or compatible with) the same Swift toolchain used to compile your project. Mismatches cause parsing errors. See [references/plugins-run-scripts-and-integrations.md](references/plugins-run-scripts-and-integrations.md) for multi-toolchain guidance.
+
+7. **Adopting too many opt-in rules at once in a large codebase.** This creates an overwhelming number of violations. Add rules incrementally and use baselines.
+
+8. **Not configuring `included` paths.** Without `included`, SwiftLint scans the working directory recursively, which may pick up vendored or generated code.
+
+## Review Checklist
+
+- [ ] `.swiftlint.yml` exists at the project root with explicit `included`/`excluded` paths
+- [ ] SwiftLint version is pinned (via SPM plugin resolution, Brewfile, or CI config)
+- [ ] Build tool plugin is enabled for each target that should be linted
+- [ ] CI runs `swiftlint --strict` (or with `--baseline` for incremental adoption)
+- [ ] No `--fix` / `--autocorrect` in build phases
+- [ ] Inline suppressions target specific rules, not `all`
+- [ ] Inline suppressions include a comment explaining why
+- [ ] Test targets have appropriate config (relaxed rules via child config, not excluded entirely)
+- [ ] Autocorrect changes are reviewed in a separate commit
+- [ ] New opt-in rules are added one at a time with team consensus
+
+## References
+
+- [references/adoption-and-configuration.md](references/adoption-and-configuration.md)  -  Installation paths, `.swiftlint.yml` deep dive, severity tuning, environment variables, nested/remote configs, rollout strategy
+- [references/plugins-run-scripts-and-integrations.md](references/plugins-run-scripts-and-integrations.md)  -  Build tool plugin, command plugin, run scripts, CI recipes, multi-toolchain guidance, VS Code, Fastlane, Docker, pre-commit
+- [references/rules-suppressions-and-baselines.md](references/rules-suppressions-and-baselines.md)  -  Default vs opt-in vs analyzer rules, suppression syntax, baseline workflows, false-positive handling
+- [references/rule-reference.md](references/rule-reference.md)  -  Bundled exhaustive rule index for local lookup; verify current details with `swiftlint rules` or the official rule directory
+- [references/custom-rules-and-analyze.md](references/custom-rules-and-analyze.md)  -  Regex custom rules, Swift custom rules (brief), `swiftlint analyze`, compiler-log workflow
+- [SwiftLint documentation](https://realm.github.io/SwiftLint/)  -  Official docs
+- [SwiftLint rule directory](https://realm.github.io/SwiftLint/rule-directory.html)  -  Full categorized rule list
+- [SimplyDanny/SwiftLintPlugins](https://github.com/SimplyDanny/SwiftLintPlugins)  -  Recommended plugin package

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

@@ -0,0 +1,297 @@
+# Adoption and Configuration
+
+Detailed guidance on installing SwiftLint, configuring `.swiftlint.yml`, and rolling out linting in existing codebases.
+
+## Contents
+
+- [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)
+
+---
+
+## Installation Paths
+
+| 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 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.
+
+## Configuration File Discovery
+
+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.
+
+- 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
+
+```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
+  - first_where
+  - last_where
+  - modifier_order
+```
+
+`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:
+
+```yaml
+only_rules:
+  - line_length
+  - force_cast
+  - force_try
+```
+
+### Analyzer rules
+
+Analyzer rules require passing compiler logs to SwiftLint. They are not included in default or opt-in sets:
+
+```yaml
+analyzer_rules:
+  - unused_import
+  - unused_declaration
+```
+
+See the custom rules and analyze reference linked from SKILL.md.
+
+### Path control
+
+```yaml
+included:
+  - Sources
+  - Tests
+
+excluded:
+  - .build
+  - DerivedData
+  - Carthage
+  - Pods
+  - "**/Generated"
+  - "**/Snapshots"
+```
+
+`included` and `excluded` support glob patterns. Paths are relative to the config file's directory.
+
+### Reporter
+
+```yaml
+reporter: xcode    # default  -  Xcode-compatible warnings/errors
+# reporter: json
+# reporter: sarif
+# reporter: checkstyle
+# reporter: csv
+# reporter: emoji
+# reporter: 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.
+
+### Global modifiers
+
+```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)
+```
+
+## Severity Tuning
+
+Most rules accept `warning` and `error` thresholds:
+
+```yaml
+line_length:
+  warning: 140
+  error: 200
+  ignores_comments: true
+  ignores_urls: true
+  ignores_interpolated_strings: true
+
+type_body_length:
+  warning: 300
+  error: 500
+
+file_length:
+  warning: 500
+  error: 1000
+  ignore_comment_only_lines: true
+
+function_body_length:
+  warning: 50
+  error: 100
+
+cyclomatic_complexity:
+  warning: 10
+  error: 20
+  ignores_case_statements: true
+
+nesting:
+  type_level: 2
+  function_level: 3
+
+identifier_name:
+  min_length:
+    warning: 2
+    error: 1
+  max_length:
+    warning: 50
+    error: 60
+  excluded:
+    - id
+    - x
+    - y
+    - i
+    - j
+    - to
+```
+
+Check available configuration keys for any rule with `swiftlint rules <rule_name>` or the [rule directory](https://realm.github.io/SwiftLint/rule-directory.html).
+
+## Environment Variable Interpolation
+
+Configuration values can reference 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
+```
+
+`child_config` refines the current config with higher priority. `parent_config` provides lower-priority defaults.
+
+### Automatic nested configs
+
+A `.swiftlint.yml` in a subdirectory can also act as a nested child config for files in that subtree:
+
+```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:
+
+```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
+```
+
+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.
+
+Nested configs are only used when SwiftLint discovers configs automatically. If you pass `--config`, nested discovery is disabled.
+
+### CLI multi-config
+
+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:
+
+```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
+```
+
+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
+
+Adopting SwiftLint in an existing project without disrupting the team:
+
+### Phase 1: Baseline
+
+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`.
+
+### Phase 2: Stop the bleeding
+
+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.
+
+### Phase 3: Incremental cleanup
+
+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.
+
+### Phase 4: Mature enforcement
+
+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`.