@codacy/tools-swiftlint-0

Table of Contents

• Overview
• Updating patterns
• Updating the SwiftLint version
• Development
• Notes for maintainers

Overview

Swift linter using the SwiftLint binary. Uses the CLI execution strategy — spawns swiftlint via spawnTool() and parses its JSON output.

Updating patterns

# Re-fetch pattern metadata from the Codacy API
pnpm prefetch

# Commit the result
git add src/patterns.json

Pattern IDs follow the format SwiftLint_force_cast, SwiftLint_cyclomatic_complexity, etc. Rule IDs use snake*case and are prefixed with SwiftLint* to form the Codacy pattern ID.

Updating the SwiftLint version

1. Update preferredVersion in src/adapter.ts
2. Update the download URL template if the release format changed
3. Run pnpm prefetch to check for new/removed rules
4. Run pnpm test to verify compatibility
5. If the major version changes, create a new adapter package (swiftlint-1/)

Development

pnpm build    # Build with tsup
pnpm test     # Run tests (mocked tests always run; integration tests require swiftlint in PATH)

To install SwiftLint locally:

# macOS
brew install swiftlint

# Linux (requires Swift toolchain for full rule coverage)
# Download from https://github.com/realm/SwiftLint/releases

Notes for maintainers

• Preset mappings (src/pattern-mappings.json): the test-only rules are gated on the test framework they check. quick uses SwiftLint's own quick/quickspec tags; nimble matches nimble_operator and prefer_nimble; xctest covers the seven XCTest rules. Quick and Nimble are separate entities because Nimble is usable on its own, and both are matched case-sensitively (Quick, Nimble) — neither Swift manifest parser normalizes case. XCTest ships with Xcode and appears in no manifest, so it is detected by a file signal on the *Tests.swift naming Xcode and SwiftPM both generate. The two swiftui-tagged rules stay universal: SwiftUI is also an Apple framework, and unlike XCTest it leaves no file-name trace, so a mapping key for it would have no producer and its patterns would be dead rather than merely off.

• JSON output quirk: SwiftLint's --reporter json output has line and character fields as strings, not numbers. The adapter uses parseInt() to convert them.

• Absolute file paths: SwiftLint reports absolute file paths in its JSON output. The adapter converts them to paths relative to repositoryRoot using path.relative().

• Version subcommand: SwiftLint uses swiftlint version (no -- prefix), not swiftlint --version.

• Config generation: When Codacy patterns are provided, the adapter generates a .swiftlint.yml with only_rules: to restrict analysis to the requested rules.

• Linux SourceKit limitation: On Linux, SwiftLint requires the Swift toolchain (SourceKit) for full rule coverage. Without it, some syntax-aware rules may not fire. The adapter emits a warning at the start of analysis on Linux.

• macOS portable zip: The portable_swiftlint.zip for macOS may extract to a nested directory structure. The install() method recursively searches the extraction directory for the binary.

• Download assets:

  • macOS (any arch): portable_swiftlint.zip
  • Linux amd64: swiftlint_linux_amd64.zip
  • Linux arm64: swiftlint_linux_arm64.zip

• Exit codes: 0 = no issues, 1 = issues found (or fatal), 2 = config error. Both 0 and 1 are treated as success.

• Category normalization: patterns.json categories are passed through if valid; unknown categories are normalized to "BestPractice".