QualityGateCore: Building a Plugin-Driven Quality Enforcement Engine for Swift

A deep technical look at how a disciplined design-first workflow produced a modular, CI-ready quality gate system spanning 20+ auditors, multiple output formats, and Swift 6.2’s full concurrency model.

Architecture

QualityGateCore is structured around a deliberate separation of concerns: a thin coordination core, a suite of independently-deployable auditor plugins, and a shared type system that binds them together without coupling their implementations.

The package dependency on quality-gate-types is the architectural keystone. By externalizing the shared domain model — findings, severity levels, output contracts — every auditor target can be compiled and tested in isolation without pulling in the full tool. This mirrors the philosophy behind Swift’s own modular stdlib design and makes the plugin surface area explicit rather than accidental.

The target list tells the full story of scope. Twenty-plus named auditors — SafetyAuditor, ConcurrencyAuditor, PointerEscapeAuditor, FloatingPointSafetyAuditor, StochasticDeterminismAuditor, MCPReadinessAuditor, and many more — each live in their own target with a corresponding test target. The QualityGateCLI is the sole entry point that assembles them, while QualityGateTestKit provides shared testing infrastructure so auditor authors aren’t reinventing assertion helpers.

QualityGateCLI
    └── QualityGateCore (orchestration)
            ├── SafetyAuditor
            ├── ConcurrencyAuditor
            ├── BuildChecker
            ├── TestRunner
            ├── DocLinter / DocCoverageChecker
            ├── UnreachableCodeAuditor
            ├── RecursionAuditor
            ├── PointerEscapeAuditor
            ├── MemoryBuilder / MemoryLifecycleGuard
            ├── AccessibilityAuditor
            ├── LoggingAuditor
            ├── TestQualityAuditor
            ├── DependencyAuditor
            ├── ReleaseReadinessAuditor
            ├── FloatingPointSafetyAuditor
            ├── MCPReadinessAuditor
            ├── StochasticDeterminismAuditor
            └── ... (shared via quality-gate-types)

Output format is a first-class design decision. The tool targets three distinct consumers — humans in a terminal, JSON-consuming CI scripts, and GitHub Code Scanning via SARIF — and the architecture treats these as separate rendering concerns downstream of a unified finding model. The .quality-gate.yml configuration layer, parsed via Yams, allows per-project customization without source changes, which is essential for a tool that must adapt to codebases it cannot control.

The SPM integration story is equally considered: both CommandPlugin and BuildToolPlugin modes are supported, acknowledging that developers want different invocation models (on-demand audit versus build-time enforcement).

The dependency on swift-syntax signals that at least some auditors perform real AST analysis rather than regex heuristics — a significant capability investment that pays dividends in precision for auditors like UnreachableCodeAuditor, RecursionAuditor, and PointerEscapeAuditor.

Implementation

The project’s 28 design proposals are the most revealing implementation artifact. A design-first workflow at this scale — 76 commits over roughly two months, landing a v1.0.0 release — means that the code largely executed against pre-reasoned plans rather than discovering structure emergently. Each proposal presumably defined the auditor’s contract, input expectations, finding schema, and edge cases before a line of production code was written.

The indexstore-db dependency is a particularly interesting choice. Rather than shelling out to xcodebuild or parsing compiler output naively, auditors that need symbol-level information can query the index directly. This enables cross-file analysis — finding unreachable code paths, tracing pointer escapes across module boundaries, detecting problematic recursion patterns — that text-based approaches simply cannot achieve reliably.

The StochasticDeterminismAuditor and MCPReadinessAuditor targets deserve special mention as indicators of forward-thinking scope. The former suggests the tool can flag code paths whose behavior is non-deterministic in ways that would undermine reproducible builds or testing. The latter reflects the project’s stated goal of being “MCP-ready” — ensuring tool descriptions are structured for consumption by AI agents, which is an unusually forward-looking quality gate concern.

Swift 6.2 and the Tools version 6.2 declaration mean the codebase operates under strict concurrency checking. For a tool that coordinates parallel auditor execution, this is both constraint and quality signal: the compiler itself enforces the absence of data races in the orchestration layer.

// Conceptual shape of the core auditor protocol, inferred from the architecture
public protocol Auditor: Sendable {
    var identifier: String { get }
    func audit(context: AuditContext) async throws -> [Finding]
}

The MemoryBuilder and MemoryLifecycleGuard pairing suggests a two-phase approach to memory analysis: construction of a memory ownership graph followed by runtime guard verification — a design that separates static analysis from dynamic contract enforcement.

The three Claude Code sessions (32 messages, 8 commits) show targeted, bounded AI assistance: two single-task sessions and one multi-task session, all reaching fully_achieved outcomes. The two friction events — one wrong approach, one instance of buggy code — are unremarkable for a tool of this complexity and reflect normal iteration rather than systemic reliance. The developer clearly maintained authorial control, using AI assistance for specific implementation tasks rather than delegating architectural judgment.

Testing Strategy

Every auditor target is paired with a dedicated test target, and QualityGateTestKit exists as a shared testing infrastructure library — a strong signal that test quality is itself a first-class concern. A tool that audits TestQualityAuditor configurations while also shipping a TestQualityAuditor auditor has a pleasingly recursive quality commitment.

The QualityGateTestKit target deserves examination on its own terms. Shared test infrastructure across 20+ auditor test targets means the team (two contributors) invested in making correct testing easy. This likely includes fixture project helpers, finding assertion DSLs, and mock AuditContext builders that let each auditor test suite focus on behavioral assertions rather than plumbing.

// Likely pattern within QualityGateTestKit
extension XCTestCase {
    func assertFindings(
        _ findings: [Finding],
        contain rule: RuleIdentifier,
        severity: Severity = .warning,
        file: StaticString = #file,
        line: UInt = #line
    ) { ... }
}

The SafetyAuditorTests, ConcurrencyAuditorTests, and PointerEscapeAuditorTests targets in particular must contend with the challenge of constructing valid Swift AST fixtures that exercise specific code patterns. The swift-syntax dependency enables this: test cases can programmatically construct syntax trees representing problematic patterns without relying on separate fixture files that drift from compiler reality.

The design-proposal workflow feeds directly into test quality. When auditor behavior is specified in writing before implementation, test cases can be derived directly from acceptance criteria rather than reverse-engineered from behavior. This is particularly valuable for edge cases in auditors like RecursionAuditor (mutual recursion? indirect enum recursion?) where the specification surface is non-obvious.

Lessons

Modular target decomposition pays compound interest. The decision to give every auditor its own SPM target — rather than organizing by feature layer within a monolithic library — means that build times stay proportional to change scope, test runs can be parallelized at the target level, and new auditors can be added without touching existing code. This lesson transfers directly to any tool that has a family of independently-motivated behaviors.

Shared type packages prevent integration debt. Externalizing quality-gate-types into its own dependency means the CLI, the core, and every auditor agree on the same finding model without circular dependencies. Projects that skip this step often discover late that their internal models have diverged and that the integration layer has become load-bearing complexity.

Design proposals are executable specifications. With 28 proposals backing 76 commits, the ratio suggests roughly one proposal per two to three commits — tight enough that proposals were genuinely guiding implementation rather than serving as post-hoc documentation. The practice of writing down the why and what before the how produced a codebase where architectural intent is recoverable without reading the commit history.

Output format is an API contract. The decision to treat SARIF as a first-class output format — not an afterthought — means the tool integrates with GitHub Code Scanning without requiring wrapper scripts. For a CLI tool targeting CI/CD pipelines, the consumer of the output is as important as the producer of it. This framing (tool output as API) transfers to any developer tool where downstream systems need to parse results.

Swift 6.2 strict concurrency as quality gate for the quality gate tool itself. Operating under complete concurrency checking in the orchestration layer forced correct-by-construction async designs for parallel auditor execution. The discipline imposed by the compiler on this codebase mirrors the discipline the tool imposes on its target projects — a productive form of dogfooding.