@mmerterden/multi-agent-pipeline 20.6.0 → 20.8.0

package/pipeline/skills/shared/external/swiftlint/references/plugins-run-scripts-and-integrations.md

@@ -1,184 +1,165 @@
-# Plugins, Run Scripts, and Integrations
+# Plugins, Run Scripts and Other Integrations
 
-Setup instructions for each SwiftLint integration method: build tool plugin, command plugin, Xcode run scripts, CI, and secondary integrations.
+Back to [SKILL.md](../SKILL.md).
 
-## Contents
+## Build tool plugin (first choice)
 
-- [Build Tool Plugin (Recommended)](#build-tool-plugin-recommended)
-- [Command Plugin](#command-plugin)
-- [Xcode Run Script Build Phase](#xcode-run-script-build-phase)
-- [CI Recipes](#ci-recipes)
-- [Working With Multiple Swift Versions](#working-with-multiple-swift-versions)
-- [VS Code](#vs-code)
-- [Fastlane](#fastlane)
-- [Docker](#docker)
-- [Pre-commit Hook](#pre-commit-hook)
+`SwiftLintBuildToolPlugin` comes from the `SimplyDanny/SwiftLintPlugins`
+package. Homebrew and `PATH` tweaks are unnecessary.
 
----
+### SwiftPM
 
-## Build Tool Plugin (Recommended)
-
-The `SwiftLintBuildToolPlugin` from [SimplyDanny/SwiftLintPlugins](https://github.com/SimplyDanny/SwiftLintPlugins) runs SwiftLint as part of the build. No Homebrew or PATH setup needed.
+```swift
+// swift-tools-version: 5.9
+import PackageDescription
 
-### SwiftPM setup
+let lint: Target.PluginUsage = .plugin(name: "SwiftLintBuildToolPlugin", package: "SwiftLintPlugins")
 
-```swift
-// Package.swift
 let package = Package(
-    name: "MyApp",
+    name: "Orchard",
     dependencies: [
-    .package(url: "https://github.com/SimplyDanny/SwiftLintPlugins", from: "<reviewed-version>")
+        // pin an exact, reviewed release
+        .package(url: "https://github.com/SimplyDanny/SwiftLintPlugins", exact: "<reviewed-version>")
     ],
     targets: [
-        .target(
-            name: "MyApp",
-            plugins: [.plugin(name: "SwiftLintBuildToolPlugin", package: "SwiftLintPlugins")]
-        ),
-        .testTarget(
-            name: "MyAppTests",
-            dependencies: ["MyApp"],
-            plugins: [.plugin(name: "SwiftLintBuildToolPlugin", package: "SwiftLintPlugins")]
-        )
+        .target(name: "Orchard", plugins: [lint]),
+        .testTarget(name: "OrchardTests", dependencies: ["Orchard"], plugins: [lint])
     ]
 )
 ```
 
-### Xcode project setup (no Package.swift)
+### Xcode project without `Package.swift`
 
-1. **File > Add Package Dependencies** → add `https://github.com/SimplyDanny/SwiftLintPlugins`
-2. For each target you want to lint, go to **Build Phases** and add `SwiftLintBuildToolPlugin` under **Run Build Tool Plug-ins**
-3. When prompted, trust the plugin
+1. Choose Add Package Dependencies from the File menu and paste the
+   SwiftLintPlugins URL.
+2. For every target to lint: Build Phases > Run Build Tool Plug-ins, add
+   `SwiftLintBuildToolPlugin`.
+3. Trust the plugin when Xcode asks.
 
-### Plugin trust
+### Headless CI with `xcodebuild`
 
-On first build, Xcode shows a trust dialog. Select **Trust & Enable All** for the SwiftLintPlugins package. In CI with `xcodebuild`, pass:
+The trust prompt cannot be answered on a build agent, so skip validation:
 
-```sh
-xcodebuild -skipPackagePluginValidation -skipMacroValidation ...
+```bash
+xcodebuild -scheme Orchard -skipPackagePluginValidation -skipMacroValidation build
 ```
 
-### Limitations
+### What the plugin cannot do
 
-- The build tool plugin cannot run `--fix` (it has read-only access to sources).
-- It cannot pass `--baseline` or other CLI flags  -  build tool plugins do not accept arguments. Use config keys like `baseline:` / `write_baseline:` where available, or switch to the command plugin / direct CLI for advanced flag-based workflows.
-- It runs on every build, which is desirable for local development but may slow clean builds in large projects.
+- No `--fix`: build tool plugins get read-only access to sources.
+- No command-line flags at all, `--baseline` included. Use the `baseline:` and
+  `write_baseline:` config keys, or move to the command plugin or the CLI.
+- Because it fires with each build, clean builds of big projects get
+  noticeably slower.
 
-## Command Plugin
+## Command plugin
 
-The command plugin provides broad SwiftPM-based CLI access to SwiftLint, including `--fix`, `--baseline`, and `analyze` workflows that the build tool plugin cannot handle directly:
+Same `SwiftLintPlugins` dependency, but invoked on demand through SwiftPM with
+read-write access to sources. Anything after `--` goes straight to the CLI, so
+`--fix`, `--baseline` and `analyze` all work.
 
-```sh
-swift package plugin swiftlint
-swift package plugin swiftlint --fix
-swift package plugin swiftlint -- --strict --baseline .swiftlint.baseline
+```bash
+swift package plugin swiftlint --fix           # rewrite correctable violations
+swift package plugin swiftlint                 # plain lint
+swift package plugin swiftlint -- --baseline .swiftlint.baseline --strict   # CLI flags after --
 swift package plugin swiftlint -- analyze --compile-commands .build/debug.yaml
 ```
 
-The command plugin requires the same `SwiftLintPlugins` dependency. It has read-write access to sources (for `--fix`) and accepts all CLI flags after `--`.
-
-## Xcode Run Script Build Phase
-
-Use a run script when the build tool plugin is impractical for your project shape or when you need CLI features the build tool plugin cannot provide (for example `--fix` locally or `--baseline`). Xcode projects can still use the build tool plugin via Xcode Package Dependency even without a local `Package.swift`.
+## Run script build phase
 
-### Basic run script
-
-1. Select the target → **Build Phases** → **+** → **New Run Script Phase**
-2. Move the phase **after Compile Sources**  -  SwiftLint is designed to analyze valid, compilable source code; linting before compilation leads to confusing results
-3. Add the script:
-
-```sh
-if command -v swiftlint >/dev/null 2>&1; then
-    swiftlint
-else
-    echo "warning: SwiftLint not installed. Install with: brew install swiftlint"
-fi
-```
+Reach for this when the plugin does not fit or you want CLI-only behaviour in
+Xcode, such as a local `--fix` or `--baseline`. Note that a plain Xcode project
+can still use the plugin through a package dependency, no `Package.swift`
+needed.
 
-On Apple Silicon with Homebrew, `swiftlint` is often installed at `/opt/homebrew/bin/swiftlint`. If the run script cannot find it, either export that path in the build phase or create a symlink into `/usr/local/bin`:
+Create it from the target's Build Phases tab (the + button, then New Run
+Script Phase) and move it so it sits below Compile Sources. SwiftLint assumes code that compiles; linting
+earlier produces confusing results.
 
-```sh
-if [[ "$(uname -m)" == arm64 ]]; then
-  export PATH="/opt/homebrew/bin:$PATH"
+```bash
+if [ "$(uname -m)" = "arm64" ]; then
+  PATH="/opt/homebrew/bin:${PATH}"; export PATH
 fi
 
-if command -v swiftlint >/dev/null 2>&1; then
-  swiftlint
-else
-  echo "warning: SwiftLint not installed. Install with: brew install swiftlint"
-fi
+command -v swiftlint > /dev/null || {
+  echo "warning: SwiftLint missing. Install it with: brew install swiftlint"
+  exit 0
+}
+swiftlint
 ```
 
-### Run script with script input files (Xcode 15+)
+- Homebrew on Apple silicon installs to `/opt/homebrew/bin/swiftlint`, which is
+  not on Xcode's default `PATH`. Export it as above, or symlink the binary into
+  `/usr/local/bin`.
+- User script sandboxing (`ENABLE_USER_SCRIPT_SANDBOXING`) is on by default in
+  projects created with Xcode 15 or later. When the build log shows a
+  `deny(1) file-read-data` sandbox error naming swiftlint, set
+  `ENABLE_USER_SCRIPT_SANDBOXING = NO` on that target.
 
-Xcode 15 sandboxes run scripts by default. If SwiftLint fails with `Sandbox: swiftlint ... deny(1) file-read-data`, set `ENABLE_USER_SCRIPT_SANDBOXING = NO` for the target. Input files and input file lists are a separate optimization for limiting which files are linted.
+### Limiting the files a run script lints
 
-1. Set `ENABLE_USER_SCRIPT_SANDBOXING = NO` for the target if the script cannot read source files under Xcode 15+
-2. Under the run script phase, check **Based on dependency analysis**
-3. Add either explicit **Input Files** or readable `.xcfilelist` paths under **Input File Lists**
-4. Use `--use-script-input-file-lists` when Xcode is providing `.xcfilelist` paths:
+Input files are an optional speed-up on top of the basic script:
 
-```sh
-if command -v swiftlint >/dev/null 2>&1; then
-  swiftlint --use-script-input-file-lists
-fi
-```
+1. Turn sandboxing off if the script needs it.
+2. Tick "Based on dependency analysis".
+3. List sources under Input Files, or point Input File Lists at `.xcfilelist`
+   files.
 
-This requires Xcode to populate `SCRIPT_INPUT_FILE_LIST_COUNT` and `SCRIPT_INPUT_FILE_LIST_n` with readable `.xcfilelist` paths. Use `--use-script-input-files` only when Xcode is populating `SCRIPT_INPUT_FILE_COUNT` and `SCRIPT_INPUT_FILE_n` directly via **Input Files** rather than **Input File Lists**.
+Then tell SwiftLint where to read them from:
 
-Alternatively, to lint the full target without file lists:
+- `--use-script-input-file-lists` reads `SCRIPT_INPUT_FILE_LIST_COUNT` and
+  `SCRIPT_INPUT_FILE_LIST_0`, `_1`, and so on; each points at a readable
+  `.xcfilelist`.
+- `--use-script-input-files` reads `SCRIPT_INPUT_FILE_COUNT` and
+  `SCRIPT_INPUT_FILE_0`, `_1`, and so on, taken from Input Files directly.
 
-```sh
-if command -v swiftlint >/dev/null 2>&1; then
-    swiftlint lint --config "${SRCROOT}/.swiftlint.yml"
-fi
-```
+To lint the whole target every time instead:
 
-And uncheck **Based on dependency analysis** if you want it to run every build.
+```bash
+swiftlint lint --config "${SRCROOT}/.swiftlint.yml"
+```
 
-### CocoaPods run script
+and untick "Based on dependency analysis" so the phase is never skipped.
 
-```sh
-"${PODS_ROOT}/SwiftLint/swiftlint"
-```
+With CocoaPods the binary path is `"${PODS_ROOT}/SwiftLint/swiftlint"`.
 
-## CI Recipes
+## Recipes for CI services
 
-### GitHub Actions
+### GitHub Actions: inline annotations
 
 ```yaml
-name: SwiftLint
+name: lint
 on:
   pull_request:
     paths: ['**/*.swift']
-
 jobs:
-  lint:
+  swiftlint:
     runs-on: macos-latest
+    timeout-minutes: 15
     steps:
       - uses: actions/checkout@v4
-      - name: Install SwiftLint
-        run: brew install swiftlint
-      - name: Lint
-        run: swiftlint --strict --reporter github-actions-logging
+      - run: brew install swiftlint
+      - run: swiftlint lint --reporter github-actions-logging --strict
 ```
 
-For SARIF upload to GitHub code scanning:
+### GitHub Actions: code scanning
 
 ```yaml
-      - name: Lint (SARIF)
-        run: swiftlint --strict --reporter sarif > swiftlint.sarif
+      - name: Lint
+        run: swiftlint lint --reporter sarif --strict > lint.sarif
         continue-on-error: true
-      - name: Upload SARIF
-        uses: github/codeql-action/upload-sarif@v3
+      - uses: github/codeql-action/upload-sarif@v3
+        if: always()
         with:
-          sarif_file: swiftlint.sarif
+          sarif_file: lint.sarif
 ```
 
-### GitHub Actions with baseline
+`continue-on-error` lets the upload step run even when lint fails.
+
+### GitHub Actions: during baseline adoption
 
 ```yaml
-      - name: Lint (baseline)
-        run: swiftlint --strict --baseline .swiftlint.baseline --reporter github-actions-logging
+      - run: swiftlint lint --reporter github-actions-logging --baseline .swiftlint.baseline --strict
 ```
 
 ### GitLab CI
@@ -186,122 +167,121 @@ For SARIF upload to GitHub code scanning:
 ```yaml
 swiftlint:
   image: ghcr.io/realm/swiftlint:latest
+  stage: test
   script:
-    - swiftlint --strict --reporter codeclimate > swiftlint.json
+    - swiftlint lint --reporter codeclimate --strict > code-quality.json
   artifacts:
     reports:
-      codequality: swiftlint.json
+      codequality: code-quality.json
 ```
 
-If you want GitLab JUnit-style output instead, use `--reporter gitlab` and publish the result as a JUnit artifact rather than `codequality`.
+GitLab can also show results as test failures: switch to `--reporter gitlab`,
+which writes JUnit XML, and attach that file as a `junit` report.
 
-### Bitrise / other CI
+### Bitrise and other hosted runners
 
-```sh
+```bash
 brew install swiftlint
 swiftlint --strict
 ```
 
-### Reporter summary
+## Reporters at a glance
 
-| Reporter | Format | Best for |
-| -------- | ------ | -------- |
-| `xcode` | Xcode-compatible text | Local builds, Xcode run scripts |
-| `github-actions-logging` | GitHub Actions annotations | PR inline comments |
-| `sarif` | SARIF JSON | GitHub code scanning |
-| `json` | JSON array | Custom tooling, dashboards |
+| Reporter | Output | Typical consumer |
+|---|---|---|
+| `xcode` | Xcode-style diagnostics | local runs, run scripts |
+| `emoji` | decorated text | fun in a terminal |
+| `github-actions-logging` | workflow commands | inline PR annotations |
+| `csv` | comma-separated rows | spreadsheets |
+| `sarif` | SARIF | code scanning |
 | `checkstyle` | XML | Jenkins, SonarQube |
-| `csv` | CSV | Spreadsheet analysis |
-| `emoji` | Text with emoji | Fun terminal output |
+| `json` | JSON array | scripts, dashboards |
 
-## Working With Multiple Swift Versions
+## Swift toolchain compatibility
 
-SwiftLint is predominantly SwiftSyntax-based, but some rules still rely on SourceKit/Clang for additional analysis. It must remain compatible with the Swift toolchain used to compile your project.
+SwiftLint parses mostly through SwiftSyntax, yet a few rules still go through
+SourceKit and Clang, so the linter has to agree with the toolchain that
+compiles the code. Rule of thumb: lint with the same toolchain you build with.
 
-**Key rules:**
+On macOS SwiftLint looks for a toolchain in this order:
 
-1. Run SwiftLint with the same Swift toolchain used to build your project.
-2. On macOS, SwiftLint resolves the toolchain in this order: `XCODE_DEFAULT_TOOLCHAIN_OVERRIDE`, `TOOLCHAIN_DIR` or `TOOLCHAINS`, `xcrun -find swift`, `/Applications/Xcode.app/...`, `/Applications/Xcode-beta.app/...`, `~/Applications/Xcode.app/...`, `~/Applications/Xcode-beta.app/...`.
-3. In CI with multiple Xcode versions, set `DEVELOPER_DIR` before running SwiftLint:
+1. `XCODE_DEFAULT_TOOLCHAIN_OVERRIDE`
+2. `TOOLCHAIN_DIR` or `TOOLCHAINS`
+3. `xcrun -find swift`
+4. `/Applications/Xcode.app/...`
+5. `/Applications/Xcode-beta.app/...`
+6. `~/Applications/Xcode.app/...`
+7. `~/Applications/Xcode-beta.app/...`
 
-```sh
-export DEVELOPER_DIR=/Applications/Xcode_16.app/Contents/Developer
-swiftlint
-```
-
-1. The build tool plugin automatically uses the correct toolchain because it runs within the build system.
-2. Homebrew-installed SwiftLint may lag behind the latest Swift release. If you see parsing errors after updating Xcode, check for a SwiftLint update.
-3. `sourcekitd.framework` is expected in the selected toolchain's `usr/lib/` directory. Toolchain mismatches typically show up as parsing or SourceKit failures.
+- CI machines with several Xcodes installed: export `DEVELOPER_DIR` first, for
+  example `DEVELOPER_DIR=/Applications/Xcode_16.4.app/Contents/Developer`.
+- The build tool plugin lives inside the build system and picks the right
+  toolchain by itself.
+- The Homebrew formula can trail a new Swift release. Parse errors right after
+  an Xcode upgrade usually mean SwiftLint needs updating.
+- The selected toolchain must contain `usr/lib/sourcekitd.framework`. A
+  mismatch shows up as parse failures or SourceKit errors.
 
 ## VS Code
 
-The [SwiftLint VS Code extension](https://marketplace.visualstudio.com/items?itemName=vknabel.vscode-swiftlint) runs SwiftLint on save.
+The `vknabel.vscode-swiftlint` extension lints when you save:
 
 ```json
-// .vscode/settings.json
 {
-    "swiftlint.enable": true,
-    "swiftlint.path": "/opt/homebrew/bin/swiftlint",
-    "swiftlint.autoLintWorkspace": false
+  "swiftlint.autoLintWorkspace": false,
+  "swiftlint.enable": true,
+  "swiftlint.path": "/opt/homebrew/bin/swiftlint"
 }
 ```
 
 ## Fastlane
 
 ```ruby
-# Fastfile
 lane :lint do
   swiftlint(
-    mode: :lint,
-    config_file: ".swiftlint.yml",
+    raise_if_swiftlint_error: true,
     strict: true,
-    raise_if_swiftlint_error: true
+    config_file: ".swiftlint.yml",
+    mode: :lint
   )
 end
 ```
 
 ## Docker
 
-The official SwiftLint Docker image is useful for Linux CI:
+The official image suits Linux CI:
 
-```sh
-docker run --rm -v "$(pwd):/work" -w /work ghcr.io/realm/swiftlint:<reviewed-version> --strict
+```bash
+docker run --rm -v "$PWD:/src" -w /src ghcr.io/realm/swiftlint:<pinned-version> --strict
 ```
 
-## Pre-commit Hook
+## Pre-commit
 
-### Using the pre-commit framework
+### With the pre-commit framework
 
 ```yaml
-# .pre-commit-config.yaml
 repos:
   - repo: https://github.com/realm/SwiftLint
-    rev: <reviewed-version>
+    rev: <pinned-version>
     hooks:
       - id: swiftlint
+        name: SwiftLint (fix, then check)
+        entry: swiftlint --fix --strict
 ```
 
-To apply fixes and fail on warnings/errors from the hook, use an `entry` override:
+The `entry` override applies automatic fixes and still fails the commit on any
+remaining warning or error.
 
-```yaml
-# .pre-commit-config.yaml
-repos:
-  - repo: https://github.com/realm/SwiftLint
-    rev: <reviewed-version>
-    hooks:
-      - id: swiftlint
-        entry: swiftlint --fix --strict
-```
+### Plain git hook
 
-### Manual git hook
+`.git/hooks/pre-commit`:
 
-```sh
-#!/bin/sh
-# .git/hooks/pre-commit
-if command -v swiftlint >/dev/null 2>&1; then
-    git diff --cached --name-only --diff-filter=d -- '*.swift' | \
-        xargs -I{} swiftlint lint --path "{}" --strict --quiet
-fi
+```bash
+#!/bin/bash
+git diff --cached --diff-filter=d --name-only -- '*.swift' \
+  | xargs -I{} swiftlint lint --strict --quiet "{}"
 ```
 
-Make it executable: `chmod +x .git/hooks/pre-commit`
+Git ignores the hook until it has the execute bit, so run `chmod +x` on it. Older SwiftLint
+releases took the file through `--path "{}"`; current releases take paths as
+plain arguments.