chore: add SwiftLint 0.65.0 with pinned CI version

Adds SwiftLint as a code-smell/correctness linter alongside swift-format.
No changes to Package.swift — downstream consumers are unaffected.

Setup:
- .swiftlint.yml: all default rules disabled; enable one-by-one in
  follow-up PRs as violations are fixed
- Makefile: adds `make lint` (strict) and `make lint-fix` (autocorrect)
- CI: new SwiftLint job pinned to 0.65.0 via portable_swiftlint.zip
  from GitHub releases, cached by version+OS, version-verified before
  running. Added to ci-success required-jobs gate.
- AGENTS.md: documents the linting workflow

Install locally: brew install swiftlint

Author: grdsdev

.github/workflows/ci.yml

@@ -317,10 +317,42 @@ jobs:
             echo "✅ All changed Swift files are properly formatted"
           fi
 
+  lint:
+    name: SwiftLint
+    runs-on: macos-26
+    timeout-minutes: 10
+    env:
+      SWIFTLINT_VERSION: "0.65.0"
+    steps:
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - name: Cache SwiftLint binary
+        id: cache-swiftlint
+        uses: actions/cache@27d5ce7f107fe9357f9df03efb73ab90386fccae # v5.0.5
+        with:
+          path: /usr/local/bin/swiftlint
+          key: swiftlint-${{ env.SWIFTLINT_VERSION }}-${{ runner.os }}
+      - name: Install SwiftLint ${{ env.SWIFTLINT_VERSION }}
+        if: steps.cache-swiftlint.outputs.cache-hit != 'true'
+        run: |
+          curl -fL \
+            "https://github.com/realm/SwiftLint/releases/download/${SWIFTLINT_VERSION}/portable_swiftlint.zip" \
+            -o /tmp/swiftlint.zip
+          unzip -q -o /tmp/swiftlint.zip -d /tmp/swiftlint
+          sudo mv /tmp/swiftlint/swiftlint /usr/local/bin/swiftlint
+      - name: Verify SwiftLint version
+        run: |
+          INSTALLED=$(swiftlint version)
+          if [ "$INSTALLED" != "$SWIFTLINT_VERSION" ]; then
+            echo "Expected SwiftLint $SWIFTLINT_VERSION, got $INSTALLED" && exit 1
+          fi
+          echo "SwiftLint $INSTALLED"
+      - name: Run SwiftLint
+        run: make lint
+
   ci-success:
     name: CI Success
     if: always()
-    needs: [macos, macos-legacy, spm, linux, integration-tests, library-evolution, examples, spell-check, docs, format-check]
+    needs: [macos, macos-legacy, spm, linux, integration-tests, library-evolution, examples, spell-check, docs, format-check, lint]
     runs-on: ubuntu-latest
     steps:
       - name: Check all jobs

.swiftlint.yml

@@ -0,0 +1,124 @@
+# SwiftLint configuration for supabase-swift
+# https://github.com/realm/SwiftLint
+#
+# Pinned version: 0.65.0
+# Install locally: brew install swiftlint
+# CI pins the exact binary via portable_swiftlint.zip from GitHub releases.
+#
+# This project uses Apple's swift-format for formatting/whitespace/layout
+# (run via `make format`). SwiftLint is therefore scoped to code-smell and
+# correctness rules, and all purely stylistic rules that swift-format already
+# governs are disabled to avoid the two tools fighting each other.
+#
+# Run locally with `make lint` (or `make lint-fix` to autocorrect).
+
+included:
+  - Sources
+  - Tests
+
+excluded:
+  - .build
+  - Tests/IntegrationTests/supabase
+  - "**/__Snapshots__"
+  # Legacy code kept for backwards-compatibility; not subject to new lint rules.
+  - Sources/Realtime/Deprecated
+
+# ── Rule configuration ────────────────────────────────────────────────────────
+
+identifier_name:
+  # Allow single-character names used for crypto/math fields (n, e, x, y, k)
+  # and common loop variables (i, h, l, r).
+  min_length:
+    warning: 1
+    error: 1
+  max_length:
+    warning: 50
+    error: 60
+  # Internal helpers are intentionally underscore-prefixed (_getAccessToken,
+  # _remove, _path, _task, _clock, JWKS_TTL, _20240101, etc.).
+  validates_start_with_lowercase: false
+  allowed_symbols: ["_"]
+  excluded:
+    - id
+    - db
+    - to
+    - vs
+    # Decodable struct properties whose names are dictated by the server response.
+    - Key
+    - Id
+
+type_name:
+  # Private/internal types use leading underscores (_WeakPassword, _Clock…)
+  # and some public types exceed 40 chars (AuthMFAGetAuthenticatorAssuranceLevelResponse).
+  min_length: 2
+  max_length:
+    warning: 50
+    error: 60
+  allowed_symbols: ["_"]
+
+# The project has deliberately large source files and types; raise limits to
+# avoid noise on code that is intentionally structured this way.
+file_length:
+  warning: 3400
+  error: 4000
+
+type_body_length:
+  warning: 2800
+  error: 3000
+
+function_body_length:
+  warning: 330
+  error: 400
+
+cyclomatic_complexity:
+  warning: 20
+  error: 30
+
+function_parameter_count:
+  warning: 6
+  error: 10
+
+# Types nested 2 levels deep appear legitimately in MultipartFormData and tests.
+nesting:
+  type_level:
+    warning: 2
+    error: 3
+
+# ── Opt-in rules ──────────────────────────────────────────────────────────────
+
+opt_in_rules:
+  - empty_count
+  - empty_string
+
+# ── Disabled rules ────────────────────────────────────────────────────────────
+
+disabled_rules:
+  # Owned by swift-format — let it be the single source of truth for layout.
+  - trailing_whitespace
+  - trailing_comma
+  - opening_brace
+  - comment_spacing
+  - vertical_whitespace
+  - trailing_newline
+  - closure_parameter_position
+  - line_length
+
+  # Intentionally used in Sources (StorageApi, RealtimeChannelV2) and heavily
+  # in tests. Remove from disabled_rules once the codebase is cleaned up.
+  - force_try
+  - force_cast
+
+  # Pervasive in test helpers for String <-> Data conversions.
+  - non_optional_string_data_conversion
+  - optional_data_string_conversion
+
+  # `let _ = subscription` is an intentional pattern in tests to retain
+  # ObservationToken long enough for the callback to fire (see EventEmitter.swift).
+  - redundant_discardable_let
+
+  # Style preferences that don't affect correctness.
+  - multiple_closures_with_trailing_closure
+  - for_where
+  - implicit_optional_initialization
+  # swift-format handles wrapping of very long function names across lines.
+  - function_name_whitespace

AGENTS.md

@@ -86,6 +86,21 @@ make spell-check             # cspell - Swift and Markdown sources
 
 Legitimate technical terms and project-specific words go in `dictionary.txt` at the repository root.
 
+### Linting
+
+```bash
+# Lint Sources and Tests (fails on any new violation)
+make lint
+
+# Autocorrect violations that SwiftLint can fix
+make lint-fix
+```
+
+This uses [SwiftLint](https://github.com/realm/SwiftLint) for code-smell and
+correctness rules; `swift-format` remains the source of truth for formatting,
+so the SwiftLint config (`.swiftlint.yml`) disables the purely stylistic rules
+that overlap with it. Install SwiftLint locally with `brew install swiftlint`.
+
 ### Documentation
 
 ```bash
@@ -297,6 +312,7 @@ supabase stop
 ## Important Notes for AI Coding Agents
 
 - Always run `make format` before committing Swift code
+- Run `make lint` before committing; it must not report new violations
 - Ensure new public APIs have DocC documentation comments
 - Add tests for all new functionality
 - Keep changes minimal and focused

Makefile

@@ -81,7 +81,13 @@ format:
 		-not -path '*/.*' -print0 \
 		| xargs -0 xcrun swift-format --ignore-unparsable-files --in-place
 
-.PHONY: build-for-library-evolution format warm-simulator xcodebuild test-docs test-integration
+lint:
+	swiftlint lint --strict
+
+lint-fix:
+	swiftlint lint --fix
+
+.PHONY: build-for-library-evolution format lint lint-fix warm-simulator xcodebuild test-docs test-integration
 
 .PHONY: coverage
 coverage:

Sources/Helpers/Base64URL.swift

@@ -17,7 +17,7 @@ package enum Base64URL {
     let paddingLength = requiredLength - length
     if paddingLength > 0 {
       let padding = "".padding(toLength: Int(paddingLength), withPad: "=", startingAt: 0)
-      base64 = base64 + padding
+      base64 += padding
     }
     return Data(base64Encoded: base64, options: .ignoreUnknownCharacters)
   }

Sources/RealtimeV2/WebSocket/URLSessionWebSocket.swift

@@ -74,7 +74,7 @@ final class URLSessionWebSocket: WebSocket {
 
     let session = URLSession.sessionWithConfiguration(
       configuration ?? .default,
-      onComplete: { session, task, error in
+      onComplete: { _, _, error in
         mutableState.withValue {
           if let webSocket = $0.webSocket {
             // There are three possibilities here:
@@ -104,14 +104,14 @@ final class URLSessionWebSocket: WebSocket {
           }
         }
       },
-      onWebSocketTaskOpened: { session, task, `protocol` in
+      onWebSocketTaskOpened: { _, task, `protocol` in
         mutableState.withValue {
           $0.webSocket = URLSessionWebSocket(
             _task: task, _protocol: `protocol` ?? "", session: session)
           $0.continuation.resume(returning: $0.webSocket!)
         }
       },
-      onWebSocketTaskClosed: { session, task, code, reason in
+      onWebSocketTaskClosed: { _, _, code, reason in
         mutableState.withValue {
           assert($0.webSocket != nil, "connection should exist by this time")
           $0.webSocket!._connectionClosed(code: code, reason: reason)

Sources/TestHelpers/URLRequestSnapshot.swift

@@ -15,8 +15,8 @@
   #endif
 
   extension Snapshotting where Value == URLRequest, Format == String {
-    /// A snapshot strategy for comparing requests based on a cURL representation.
-    ///
+    // A snapshot strategy for comparing requests based on a cURL representation.
+    //
     // ``` swift
     // assertSnapshot(of: request, as: .curl)
     // ```

Tests/FunctionsTests/FunctionsClientTests.swift

@@ -38,11 +38,6 @@ final class FunctionsClientTests: XCTestCase {
     sessionConfiguration: sessionConfiguration
   )
 
-  override func setUp() {
-    super.setUp()
-    //    isRecording = true
-  }
-
   func testInit() async {
     let client = FunctionsClient(
       url: url,

Tests/IntegrationTests/RealtimeIntegrationTests.swift

@@ -785,7 +785,7 @@
 
       // Verify both clients can decode presence
       // Note: Due to timing, exact presence changes may vary, but structure should be correct
-      XCTAssertTrue(presenceChanges1.count > 0, "Client 1 should receive presence changes")
+      XCTAssertTrue(!presenceChanges1.isEmpty, "Client 1 should receive presence changes")
 
       // Verify messages were received by both clients
       XCTAssertEqual(messages1.count, 3, "Client 1 should receive all 3 messages")
@@ -816,7 +816,7 @@
 
       // Verify user 1 leaving is detected by user 2
       // Note: Due to timing, exact presence changes may vary, but structure should be correct
-      XCTAssertTrue(presenceChanges2.count > 0, "Client 2 should receive presence changes")
+      XCTAssertTrue(!presenceChanges2.isEmpty, "Client 2 should receive presence changes")
 
       // Cleanup
       await channel1.unsubscribe()

Tests/PostgRESTTests/PostgrestFilterBuilderTests.swift

@@ -12,11 +12,6 @@ import XCTest
 
 final class PostgrestFilterBuilderTests: PostgrestQueryTests {
 
-  override func setUp() {
-    super.setUp()
-    // isRecording = true
-  }
-
   func testNotFilter() async throws {
     Mock(
       url: url.appendingPathComponent("users"),