swift-build-resolver

Swift Build Resolver

Get a broken Swift build green with surgical changes. Diagnose from the compiler, fix the root cause, re-build, repeat — never paper over an error.

Before applying a fix, gauge its blast radius with cx references --name X (or gitnexus_impact): if a type must become Sendable and it's captured across many call sites, prefer actor-wrapping over a local conformance. Optional external tools — fall back to Grep when absent. See ${CLAUDE_PLUGIN_ROOT}/rules/tool-routing.md.

Detect the build unit first: an *.xcodeproj/*.xcworkspace + scheme ⇒ xcodebuild; a Package.swift ⇒ swift build/swift test. A pure-logic SPM package builds in seconds on the host — prefer it over a simulator build when the failing code lives there.

When NOT

• Python ruff / mypy / pytest toolchain failures → python-build-resolver
• Rust / Cargo toolchain failures → rust-build-resolver

Diagnose

SwiftPM

swift build 2>&1
swift package resolve 2>&1
swift package show-dependencies 2>&1
swift package dump-package        # validate Package.swift syntax
cat Package.resolved | head -40   # pinned versions
swift --version                   # toolchain / language mode

Xcode

xcodebuild -list                                  # schemes / targets
xcrun simctl list devices available | head -20    # which simulators exist (names age each Xcode release)
xcodebuild -scheme <Scheme> -destination 'generic/platform=iOS Simulator' build 2>&1 | tail -60
xcodebuild -showBuildSettings 2>&1 | grep -E 'SWIFT_VERSION|SWIFT_STRICT_CONCURRENCY|CODE_SIGN|PRODUCT_BUNDLE_IDENTIFIER'

If a named-simulator destination is reported unavailable/ineligible, retry the build with generic/platform=iOS Simulator before assuming a code fault — the default device name may simply not be installed (see xcode-tooling module references/xcodebuild-spm.md).

Error → likely cause → fix

Compiler error (substring)	Cause	Surgical fix
cannot find type 'X' in scope	Missing import or typo	Add import <Module> / correct the name
value of type 'X' has no member 'Y'	Wrong type / missing extension	Fix the type or add the member
type 'X' does not conform to protocol 'Y'	Missing requirement	Implement the required member(s)
initializer requires that 'X' conform to 'Decodable'	Missing Codable	Add Codable / a custom init(from:)
expression is 'async' but is not marked with 'await'	Missing await	Add await at the call site
non-sendable type 'X' passed in implicitly async call	Sendable violation	Make X Sendable (value type / final + immutable), or move the boundary
actor-isolated property ... referenced from non-isolated context	Isolation mismatch	await it, mark the caller async, or nonisolated the member if truly safe
@MainActor function cannot be called from non-isolated context	Main-actor hop	await + make the caller async, or await MainActor.run { … }
reference to captured var 'X' in concurrently-executing code	Mutable capture	Capture a let copy, or move state into an actor
main actor-isolated ... can not be referenced from a Sendable closure	Closure crosses isolation	Hop with await MainActor.run, or restructure ownership
ambiguous use of 'X'	Overload/shadowing	Fully qualify or annotate the expected type
cannot assign to property: 'X' is a 'let' constant	Mutating immutable	let → var, or restructure to avoid mutation