Xcode Doctor: Static Analysis Engine for Xcode Configuration

Context

iOS and macOS developers encounter a recurring class of failure: the build works locally, tests pass, but App Store submission fails due to a configuration issue that Xcode never flagged. Signing certificate mismatches, missing entitlement files, Watch companion app linking failures, Widget extension bundle ID conflicts — these errors surface only after a complete build cycle and submission review.

The review turnaround from Apple is typically 24–48 hours per correction cycle. A single configuration issue discovered post-submission can delay a release by days.

Problem

The root cause is architectural: Xcode surfaces configuration errors reactively — at build time or submission time. The project configuration itself — the project.pbxproj file, entitlement plists, signing settings — is inspectable at any time. But manually auditing these files is slow, requires deep knowledge of the format, and is error-prone enough that most developers don't do it.

There was no tool that statically analyzed Xcode project configuration before a build — the equivalent of a linter for project structure rather than source code.

Constraints

• —Read-only by design — the tool must never write to or modify project files, even unintentionally. Any diagnostic tool that can corrupt a project is worse than no tool.
• —Analysis must complete in under 2 seconds — slow enough to feel like a build step defeats the purpose of running before a build
• —Zero telemetry — .xcodeproj files contain proprietary app structure, team IDs, bundle identifiers, and signing configurations
• —Apple notarization required for Gatekeeper-compliant distribution without forcing users to override security settings
• —Must work without Xcode open and without invoking any Xcode CLI tools — the analysis engine must be self-contained

Architecture: The Static Analysis Engine

Implementation: Bundle ID Consistency Check

The WatchKit companion bundle ID check — one of the most common App Store rejection causes — validates that the Watch app's bundle ID is exactly [parent].watchkitapp and the Watch extension's ID is [parent].watchkitapp.watchkitextension:

struct WatchBundleIDCheck: DiagnosticCheck {
    func run(on project: ParsedProject) -> [DiagnosticFinding] {
        var findings: [DiagnosticFinding] = []

        guard let watchTarget = project.targets
            .first(where: { $0.productType == .watchKitApp }),
              let hostTarget = project.targets
            .first(where: { $0.dependencies.contains(watchTarget.id) })
        else { return findings }

        let hostBundleID = hostTarget.buildSettings["PRODUCT_BUNDLE_IDENTIFIER"] ?? ""
        let watchBundleID = watchTarget.buildSettings["PRODUCT_BUNDLE_IDENTIFIER"] ?? ""
        let expectedWatchID = "\(hostBundleID).watchkitapp"

        if watchBundleID != expectedWatchID {
            findings.append(.init(
                severity: .error,
                targetName: watchTarget.name,
                message: "Watch app bundle ID '\(watchBundleID)' must be '\(expectedWatchID)'",
                resolution: "In the Watch app target's Build Settings, set " +
                    "PRODUCT_BUNDLE_IDENTIFIER to \(expectedWatchID)"
            ))
        }

        return findings
    }
}

Solution Highlights

• •Static .xcodeproj XML/plist analysis — no Xcode dependency, no build invocation needed
• •9 checks completing in under 2 seconds on any modern Mac
• •Read-only sandboxed access — write operations architecturally prevented at the file system level
• •Severity-classified findings with per-issue actionable resolution instructions
• •Zero telemetry — all analysis is local, no network requests of any kind
• •Apple notarization with SHA-256 checksum for verifiable download integrity

Key Technical Learnings

Technical FAQ