Three New Auditors for quality-gate-swift, or Why Modular Linters Win

Modular linting that catches recursion bugs, Swift 6 concurrency traps, and unsafe pointer escapes — built on the same QualityChecker protocol as everything else.

This week I added three new checkers, and I want to talk about why the modularity of the quality gate made it almost trivial to do — and what each new auditor catches.

The Trigger

Buggy first-pass code requiring rework. Generated code frequently has subtle bugs (recursion, memory, concurrency) that you catch later.

• Convenience inits had infinite recursion flagged by SourceKit
• Accelerate FFT backend had pointer-escape memory corruption blocking tests

So I built three new auditors.

The Tools

1. RecursionAuditor

// ❌ Convenience init forwarding to itself with identical labels
class Foo {
    init(name: String, age: Int) { self.name = name; self.age = age }
    convenience init(name: String) {
        self.init(name: name)   // ← infinite recursion
    }
}

// ❌ Computed property referencing itself
struct Foo {
    var value: Int { value }
}

// ❌ Function with no base case
func loop(_ n: Int) -> Int {
    return loop(n)
}

// ❌ Mutual recursion across files (caught via project-wide call graph)
// A.swift
func a() { b() }
// B.swift
func b() { a() }

The base case heuristic was originally “any guard statement in the body.” That worked for the test fixtures. But the first time I ran the auditor against quality-gate-swift itself, it flagged its own SwiftSyntax visitor — a legitimate recursive-descent walker where the base case is “the AST is finite,” not a syntactic guard. So I tightened the heuristic to also recognize bare return statements and returns of literal/identifier expressions as evidence of a non-recursing path. Real dogfooding caught a real false positive before it shipped.

8 rule IDs. All 35 tests passing.

2. ConcurrencyAuditor

// ❌ @unchecked Sendable with no justification
final class Cache: @unchecked Sendable {
    var entries: [String: Int] = [:]
}

// ✅ With justification — accepted
// Justification: synchronized via NSLock; see Cache.swift:42
final class Cache: @unchecked Sendable {
    var entries: [String: Int] = [:]
}

// ❌ Sendable class with mutable state (private doesn’t change the rules)
final class Foo: Sendable {
    private var x = 0
}

// ❌ Task in actor capturing self without an explicit hop
actor A {
    var x = 0
    func f() {
        Task {
            self.x += 1   // races — runs off-actor
        }
    }
}

// ❌ @MainActor deinit touches stored state — runtime trap in Swift 6
@MainActor
class A {
    var x = 0
    deinit { print(x) }
}

// ❌ @preconcurrency import of a first-party module
@preconcurrency import MyAppCore   // your own code; fix it instead

The escape hatch for the “unsafe” rules is a justification comment immediately above the declaration. Adjacency is strict: a blank line, a block comment, or a comment below the decl all fail to suppress. The mechanism is searchable, auditable, and CI-friendly.

For the @preconcurrency import rule, the CLI parses Package.swift once at startup and extracts every .target(name:) literal. First-party modules get flagged; third-party modules pass through. You can also allowlist specific first-party modules during a transition.

8 rule IDs. All 65 tests passing.

3. PointerEscapeAuditor

This is the auditor I wish I’d had a year ago.

// ❌ The motivating incident, paraphrased
final class FFTBackend {
    var workspace: UnsafeMutablePointer
            
              ?
              

              
 func setup(input: [Float]) {
              
 input.withUnsafeBufferPointer { buf in
              
 self.workspace = buf.baseAddress.map { /* … 
              / }
 // ↑ pointer escapes the with-block; the memory is gone
 // after this closure returns. Compiles cleanly.
 }
 }
}

            

error: pointer escapes by being stored in a property
       FFTBackend.swift:14:13
       rule: pointer-escape.stored-in-property
       fix:  Store the pointee value or a Sendable copy instead.

• Direct return of the pointer, whether explicit or implicit-return
• Wrapped return through struct initializers, tuples, array literals, Any boxes, or ternary branches
• Assignment to outer variables, globals, static properties, instance properties
• Append/insert into outer collections
• Inout-style sinks where the pointer co-occurs with &outerVar in the same call
• Closure capture stored in an outer variable (error tier) or passed to Task { … } / DispatchQueue.async { … } (warning tier)
• Unmanaged retain leaks where Unmanaged.passRetained has no matching .release()
• OpaquePointer round-trips outside the with-block

The pointer-identity tracker is heuristic but precise about value vs. pointer access: ptr.pointee is a value (not flagged), ptr.baseAddress is a pointer (flagged), ptr + 1 is a pointer (flagged), ptr.reduce(0, +) is a value (not flagged).

For genuinely safe escape destinations — specific vDSP entry points, certain CFData accessors — there’s a user-supplied allowlist. Rather than ship a global list that drifts, you opt in per project:

pointerEscape:
  allowedEscapeFunctions:
    - vDSP_fft_zip
    - vDSP_fft_zop

Why the Modularity Mattered

The whole architecture is:

public protocol QualityChecker: Sendable {
    var id: String { get }
    var name: String { get }
    func check(configuration: Configuration) async throws -> CheckResult
}

Adding the three new auditors followed the same shape as the existing six:

1. Design proposal → architecture, rule list, test strategy, open questions. Reviewed before any code.
2. RED → write the failing test suite. One file per rule. Red and green fixtures paired.
3. GREEN → implement until tests pass. Iterate against failures.
4. DOCUMENT → DocC catalog with rule table and narrative guide.
5. REGISTER → wire into the CLI, add YAML config, parse Package.swift if needed.
6. DOGFOOD → run against the package itself, fix any false positives the test suite missed.

The reason this scales is the protocol. Every checker is a black box from the CLI’s perspective. If I want to add a tenth auditor next month — say, one that catches try? someThrowingFunction() followed by force-unwrap, or one that detects Result.success(()) patterns that should be Void-returning — I don’t have to touch any existing file. I write a new module, conform to QualityChecker, register it in one line, and ship.

What I Found Dogfooding

But they’re not infinite recursion. They terminate because the AST is finite.

This is the classic visitor-pattern false positive. The naive heuristic flagged it. I tightened the heuristic to also accept bare return statements and returns of non-call expressions as evidence of a non-recursing path. The visitor functions all have early returns after each branch matches. That’s a base case, structurally — the function returns without recursing if the input doesn’t match a recursive type.

The fix took fifteen lines. Re-running the auditor: zero diagnostics. Fixing the false positive in the auditor itself, against my own codebase, before shipping it to other projects, is exactly what dogfooding is for.

Configuration

enabledCheckers:
  - build
  - test
  - safety
  - doc-lint
  - doc-coverage
  - unreachable
  - recursion
  - concurrency
  - pointer-escape

concurrency:
  justificationKeyword: “Justification:”
  allowPreconcurrencyImports:
    - SomeLegacyDependency

pointerEscape:
  allowedEscapeFunctions:
    - vDSP_fft_zip

Try It

git clone https://github.com/jpurnell/quality-gate-swift
cd quality-gate-swift
swift build -c release
.build/release/quality-gate –check recursion concurrency pointer-escape

quality-gate

The Lesson

When the integration cost is one new file and one line in a CLI registration, you add the check. And then the bugs don’t ship.

That’s the real argument for protocol-oriented quality tooling: it lowers the friction of catching the next class of bug to the point where you actually do it.