ci: adopt swift-format + warnings/doc-link gates (#325)

Port the format and CI tooling from SwiftSync:
- .swift-format (120 cols, 4-space) and a one-time pre-commit hook
  (.githooks/pre-commit, enabled via scripts/setup.sh) that formats
  staged Swift files.
- CI jobs: swift-format check, a warnings gate (fails on any first-party
  warning:), and a dead-doc-link check (scripts/check-doc-links.py),
  alongside the existing go-httpbin build & test.
- Reformat Sources/ and Tests/ to satisfy the format check.
- Fix README link to the deleted CHANGELOG.md (-> GitHub releases) so the
  new doc-link gate is green.

Author: 3lvis

.githooks/pre-commit

@@ -0,0 +1,26 @@
+#!/bin/sh
+# Formats staged Swift files with swift-format before each commit.
+# Enable once per clone: ./scripts/setup.sh (or git config core.hooksPath .githooks)
+set -e
+
+# NUL-delimited so paths with spaces survive. ACM excludes deletions.
+files=$(git diff --cached --name-only --diff-filter=ACM -z -- '*.swift' | tr '\0' '\n')
+[ -z "$files" ] && exit 0
+
+if ! command -v swift >/dev/null 2>&1; then
+    echo "pre-commit: swift toolchain not found; skipping swift-format." >&2
+    exit 0
+fi
+
+echo "$files" | while IFS= read -r f; do
+    [ -n "$f" ] || continue
+    # A file with unstaged changes is partially staged; formatting in place and
+    # re-adding would pull the unstaged hunks into the commit. Skip it — CI's
+    # format check is the backstop for anything the hook can't safely touch.
+    if git diff --quiet -- "$f"; then
+        swift format --in-place "$f"
+        git add -- "$f"
+    else
+        echo "pre-commit: '$f' is partially staged; skipping format (run swift format manually)." >&2
+    fi
+done

.github/workflows/ci.yml

@@ -13,6 +13,19 @@ env:
   DEVELOPER_DIR: /Applications/Xcode_26.3.app/Contents/Developer
 
 jobs:
+  swift-format-check:
+    name: swift-format check
+    runs-on: macos-15
+    steps:
+      - uses: actions/checkout@v5
+      - name: Check formatting
+        run: |
+          swift format --in-place --recursive Sources Tests
+          if ! git diff --exit-code; then
+            echo "::error::Code is not formatted. Run: swift format --in-place --recursive Sources Tests (and commit)."
+            exit 1
+          fi
+
   build-and-test:
     name: macOS Swift Build & Test
     runs-on: macos-15
@@ -40,3 +53,27 @@ jobs:
         env:
           HTTPBIN_BASE_URL: http://127.0.0.1:8080
         run: swift test -v
+
+  warnings:
+    name: Warnings gate
+    runs-on: macos-15
+    steps:
+      - uses: actions/checkout@v5
+      # No SPM cache on purpose: a fresh build recompiles everything so warnings are
+      # actually re-emitted (an incremental build would skip unchanged files).
+      - name: Build and fail on first-party warnings
+        run: |
+          set -o pipefail
+          swift build --build-tests 2>&1 | tee build.log
+          if grep -E "warning:" build.log | grep -vE "\.build/(checkouts|artifacts)"; then
+            echo "::error::Build emitted warnings in first-party code. Fix them (the lines above)."
+            exit 1
+          fi
+
+  doc-links:
+    name: Doc link check
+    runs-on: macos-15
+    steps:
+      - uses: actions/checkout@v5
+      - name: Check relative markdown links resolve
+        run: python3 scripts/check-doc-links.py

.swift-format

@@ -0,0 +1,10 @@
+{
+  "version": 1,
+  "lineLength": 120,
+  "indentation": {
+    "spaces": 4
+  },
+  "maximumBlankLines": 1,
+  "respectsExistingLineBreaks": true,
+  "lineBreakBeforeEachArgument": false
+}

AGENTS.md

@@ -11,7 +11,11 @@ what's specific to this repo. Release history and the v8 (major) notes live in `
 - `swift build` — library only; CI also fails on any first-party `warning:`.
 - Integration tests need go-httpbin (`TestConfig.httpbinBaseURL`, default `http://127.0.0.1:8080`). Without it
   they fail fast (connection refused) — intended, not a flake. The offline / `fake*` suites need no server.
+- Formatting: `.swift-format` (120 cols, 4-space). Run `./scripts/setup.sh` once per clone to enable the
+  `.githooks/pre-commit` hook (formats staged Swift files); CI's format check is the backstop.
 - CI: `macos-15` / Xcode 26.3 / Swift 6.2.x (stricter region-isolation than local 6.3 — CI is the gate).
+  Jobs: swift-format check, build & test (go-httpbin), a warnings gate, and a dead-doc-link check
+  (`scripts/check-doc-links.py`).
 
 ## Source map
 

README.md

@@ -638,7 +638,7 @@ In your `Package.swift`:
 
 …and add `"Networking"` to your target's dependencies. In Xcode, use **File ▸ Add Package Dependencies…** and enter `https://github.com/3lvis/Networking.git`.
 
-> **Upgrading from 7.x?** 8.0.0 is a major, breaking release (async/`await` + `Result`, Swift 6, typed request bodies, a categorized error model, an event stream, and request interceptors). See [`CHANGELOG.md`](CHANGELOG.md) for the full migration.
+> **Upgrading from 7.x?** 8.0.0 is a major, breaking release (async/`await` + `Result`, Swift 6, typed request bodies, a categorized error model, an event stream, and request interceptors). See the [release notes](https://github.com/3lvis/Networking/releases) for the full migration.
 
 ## Running the tests
 

Sources/Networking/CacheExpiry.swift

@@ -13,20 +13,23 @@ final class CacheExpiry: @unchecked Sendable {
     }
 
     var ttl: Duration {
-        lock.lock(); defer { lock.unlock() }
+        lock.lock()
+        defer { lock.unlock() }
         return .seconds(ttlSeconds)
     }
 
     func setTTL(_ ttl: Duration) {
-        lock.lock(); defer { lock.unlock() }
+        lock.lock()
+        defer { lock.unlock() }
         ttlSeconds = ttl.seconds
     }
 
     // Cold = the file's last use (its modification date) is older than the TTL. A missing date (no file)
     // is treated as not-expired so a present-but-unreadable entry isn't dropped spuriously.
     func isExpired(fileDate: Date?) -> Bool {
         guard let fileDate else { return false }
-        lock.lock(); defer { lock.unlock() }
+        lock.lock()
+        defer { lock.unlock() }
         return Date().timeIntervalSince(fileDate) > ttlSeconds
     }
 }

Sources/Networking/CacheStore.swift

@@ -1,5 +1,5 @@
-import Foundation
 import CryptoKit
+import Foundation
 
 // Owns both cache tiers: the in-memory `NSCache` (warm, pressure-evicted by iOS) over the on-disk shard
 // layout (cold, durable). A non-actor, synchronous type so the nonisolated cache reads
@@ -33,8 +33,11 @@ final class CacheStore: @unchecked Sendable {
         let finalPath = "\(folderPath)/\(component)"
 
         guard let url = URL(string: finalPath),
-              let cachesURL = FileManager.default.urls(for: .cachesDirectory, in: .userDomainMask).first else {
-            throw NSError(domain: folderName, code: 9999, userInfo: [NSLocalizedDescriptionKey: "Couldn't build a cache URL for: \(finalPath)"])
+            let cachesURL = FileManager.default.urls(for: .cachesDirectory, in: .userDomainMask).first
+        else {
+            throw NSError(
+                domain: folderName, code: 9999,
+                userInfo: [NSLocalizedDescriptionKey: "Couldn't build a cache URL for: \(finalPath)"])
         }
 
         let folderURL = cachesURL.appendingPathComponent(URL(string: folderPath)!.absoluteString)
@@ -87,7 +90,8 @@ final class CacheStore: @unchecked Sendable {
             if let object = memory.object(forKey: key as AnyObject) {
                 return object
             } else if FileManager.default.exists(at: destinationURL) {
-                let fileDate = try? destinationURL.resourceValues(forKeys: [.contentModificationDateKey]).contentModificationDate
+                let fileDate = try? destinationURL.resourceValues(forKeys: [.contentModificationDateKey])
+                    .contentModificationDate
                 if expiry.isExpired(fileDate: fileDate) {
                     try FileManager.default.remove(at: destinationURL)
                     return nil
@@ -102,7 +106,8 @@ final class CacheStore: @unchecked Sendable {
                     memory.setObject(returnedObject as AnyObject, forKey: key as AnyObject)
                     // Re-warm: bump the file's mtime so an entry in active use never expires. Only happens
                     // on a memory miss, so it's ~once per entry per launch — no explicit debounce needed.
-                    try? FileManager.default.setAttributes([.modificationDate: Date()], ofItemAtPath: destinationURL.path)
+                    try? FileManager.default.setAttributes(
+                        [.modificationDate: Date()], ofItemAtPath: destinationURL.path)
                 }
 
                 return returnedObject
@@ -180,7 +185,9 @@ final class CacheStore: @unchecked Sendable {
     }
 
     private static func folderURL(named folderName: String) -> URL? {
-        guard let cachesURL = FileManager.default.urls(for: .cachesDirectory, in: .userDomainMask).first else { return nil }
+        guard let cachesURL = FileManager.default.urls(for: .cachesDirectory, in: .userDomainMask).first else {
+            return nil
+        }
         return cachesURL.appendingPathComponent(URL(string: folderName)!.absoluteString)
     }
 
@@ -195,12 +202,20 @@ final class CacheStore: @unchecked Sendable {
         let maxAge = expiry.ttl.seconds
 
         let cursorURL = domainURL.appendingPathComponent(Self.sweepCursorFileName)
-        let cursor = (try? String(contentsOf: cursorURL, encoding: .utf8)).flatMap { Int($0.trimmingCharacters(in: .whitespacesAndNewlines)) } ?? 0
+        let cursor =
+            (try? String(contentsOf: cursorURL, encoding: .utf8)).flatMap {
+                Int($0.trimmingCharacters(in: .whitespacesAndNewlines))
+            } ?? 0
         let shardURL = domainURL.appendingPathComponent(String(cursor % Self.shardCount, radix: 16))
 
-        if let files = try? FileManager.default.contentsOfDirectory(at: shardURL, includingPropertiesForKeys: [.contentModificationDateKey], options: []) {
+        if let files = try? FileManager.default.contentsOfDirectory(
+            at: shardURL, includingPropertiesForKeys: [.contentModificationDateKey], options: [])
+        {
             for file in files {
-                guard let modified = try? file.resourceValues(forKeys: [.contentModificationDateKey]).contentModificationDate else { continue }
+                guard
+                    let modified = try? file.resourceValues(forKeys: [.contentModificationDateKey])
+                        .contentModificationDate
+                else { continue }
                 if now.timeIntervalSince(modified) > maxAge {
                     try? FileManager.default.removeItem(at: file)
                 }
@@ -209,7 +224,9 @@ final class CacheStore: @unchecked Sendable {
 
         // Pre-sharding versions wrote files directly under the domain root; clear those strays (the cursor
         // file and the shard subdirectories stay).
-        if let rootEntries = try? FileManager.default.contentsOfDirectory(at: domainURL, includingPropertiesForKeys: [.isRegularFileKey], options: []) {
+        if let rootEntries = try? FileManager.default.contentsOfDirectory(
+            at: domainURL, includingPropertiesForKeys: [.isRegularFileKey], options: [])
+        {
             for entry in rootEntries where entry.lastPathComponent != Self.sweepCursorFileName {
                 if (try? entry.resourceValues(forKeys: [.isRegularFileKey]).isRegularFile) == true {
                     try? FileManager.default.removeItem(at: entry)

Sources/Networking/DownloadResponse.swift

@@ -1,4 +1,5 @@
 import Foundation
+
 #if os(macOS)
     import AppKit.NSImage
 #else
@@ -38,7 +39,8 @@ public struct ImageResponse: ImageDownloadable, @unchecked Sendable {
     public let headers: [String: AnyCodable]
     public let image: Image
 
-    public static func makeDownloadResult(image: Image, statusCode: Int, headers: [String: AnyCodable]) -> ImageResponse {
+    public static func makeDownloadResult(image: Image, statusCode: Int, headers: [String: AnyCodable]) -> ImageResponse
+    {
         ImageResponse(statusCode: statusCode, headers: headers, image: image)
     }
 }

Sources/Networking/FakeRequest.swift

@@ -15,15 +15,21 @@ struct FakeRequest {
     let statusCode: Int
     let delay: Double
 
-    init(payload: Payload, responseType: Networking.ResponseType, headerFields: [String : String]?, statusCode: Int, delay: Double) {
+    init(
+        payload: Payload, responseType: Networking.ResponseType, headerFields: [String: String]?, statusCode: Int,
+        delay: Double
+    ) {
         self.payload = payload
         self.responseType = responseType
         self.headerFields = headerFields
         self.statusCode = statusCode
         self.delay = delay
     }
 
-    static func find(ofType type: Networking.RequestType, forPath path: String, in collection: [Networking.RequestType: [String: FakeRequest]]) throws -> FakeRequest? {
+    static func find(
+        ofType type: Networking.RequestType, forPath path: String,
+        in collection: [Networking.RequestType: [String: FakeRequest]]
+    ) throws -> FakeRequest? {
         guard let requests = collection[type] else { return nil }
         guard path.count > 0 else { return nil }
 
@@ -60,15 +66,19 @@ struct FakeRequest {
                 }
                 guard replacedPath == path else { continue }
                 // Substitute the captured path values into the JSON body string (e.g. "{userID}" -> "10").
-                guard case let .data(data) = fakeRequest.payload,
-                      var responseString = String(data: data, encoding: .utf8) else { continue }
+                guard case .data(let data) = fakeRequest.payload,
+                    var responseString = String(data: data, encoding: .utf8)
+                else { continue }
 
                 for (key, value) in replacedValues {
                     responseString = responseString.replacingOccurrences(of: key, with: value)
                 }
 
                 guard let stringData = responseString.data(using: .utf8) else { continue }
-                return FakeRequest(payload: .data(stringData), responseType: fakeRequest.responseType, headerFields: fakeRequest.headerFields, statusCode: fakeRequest.statusCode, delay: fakeRequest.delay)
+                return FakeRequest(
+                    payload: .data(stringData), responseType: fakeRequest.responseType,
+                    headerFields: fakeRequest.headerFields, statusCode: fakeRequest.statusCode, delay: fakeRequest.delay
+                )
             }
         }
 

Sources/Networking/HTTPInterceptor.swift

@@ -91,11 +91,14 @@ public struct RetryInterceptor: HTTPInterceptor {
                 let exchange = try await next(request)
                 let shouldRetry = methodAllowsRetry && retryableStatusCodes.contains(exchange.response.statusCode)
                 guard shouldRetry, attempt < maxAttempts else { return exchange }
-                let delay = Self.retryAfterDelay(from: exchange.response).map { Swift.min($0, maxDelay) }
+                let delay =
+                    Self.retryAfterDelay(from: exchange.response).map { Swift.min($0, maxDelay) }
                     ?? backoffDelay(forAttempt: attempt)
                 try await Task.sleep(for: delay)
                 attempt += 1
-            } catch let error as URLError where attempt < maxAttempts && methodAllowsRetry && NetworkingError.isRetryableTransport(error) {
+            } catch let error as URLError
+                where attempt < maxAttempts && methodAllowsRetry && NetworkingError.isRetryableTransport(error)
+            {
                 try await Task.sleep(for: backoffDelay(forAttempt: attempt))
                 attempt += 1
             }
@@ -112,7 +115,8 @@ public struct RetryInterceptor: HTTPInterceptor {
     // Retry-After is either a count of seconds or an HTTP-date (RFC 9110).
     static func retryAfterDelay(from response: HTTPURLResponse) -> Duration? {
         guard let value = response.value(forHTTPHeaderField: "Retry-After")?.trimmingCharacters(in: .whitespaces),
-              !value.isEmpty else { return nil }
+            !value.isEmpty
+        else { return nil }
         if let seconds = Int(value) {
             return .seconds(max(0, seconds))
         }
@@ -149,8 +153,9 @@ public struct ResponseValidatorInterceptor: HTTPInterceptor {
         switch validate(exchange) {
         case .valid:
             return exchange
-        case let .invalid(reason):
-            throw NetworkingError.validation(reason: reason, ResponseMetadata(response: exchange.response, body: exchange.data))
+        case .invalid(let reason):
+            throw NetworkingError.validation(
+                reason: reason, ResponseMetadata(response: exchange.response, body: exchange.data))
         }
     }
 }