tuist cache fails with header '<Module>-Swift.h' not found for pure-Swift SPM products promoted to .framework under single-arch builds

Root cause analysis by Claude:

The <Module>-Swift.h line in the failing modulemap is not written by Tuist — grep -r '-Swift\.h' cli/Sources returns zero hits. It’s emitted by Xcode’s own modulemap auto-generator, which kicks in when a framework target has DEFINES_MODULE=YES, Swift sources, and no umbrella header file.

Tuist enables that auto-generation for pure-Swift SPM-promoted-to-framework targets. The relevant code is cli/Sources/TuistLoader/SwiftPackageManager/PackageInfoMapper.swift:1437-1452:

if let moduleMap {
    switch moduleMap {
    case .directory, .header, .custom:
        settingsDictionary["DEFINES_MODULE"] = "NO"   // ← suppresses Xcode auto-gen
        // …plus OTHER_CFLAGS += -fmodule-name=<Module>
    case .none:
        break                                          // ← leaves DEFINES_MODULE=YES → Xcode auto-gens
    }
}

For a pure-Swift SPM target (no .h files anywhere under publicHeadersPath), SwiftPackageManagerModuleMapGenerator.generate() returns .none — see cli/Sources/TuistLoader/SwiftPackageManager/SwiftPackageManagerModuleMapGenerator.swift:134-149. The .none branch in PackageInfoMapper does nothing, so DEFINES_MODULE stays at Xcode’s framework default (YES), no MODULEMAP_FILE is set, and Xcode synthesises a modulemap with header "<Module>-Swift.h".

That synthesised modulemap is only valid if -Swift.h is on disk when the explicit-modules dependency scanner reads it. With multi-arch simulator builds (or ONLY_ACTIVE_ARCH=YES), the build-phase scheduling happens to produce -Swift.h before the scan. With ARCHS=/EXCLUDED_ARCHS= constraining to a single arch, the scheduling shifts and the scan beats the Swift compile.

The Xcode build-ordering quirk under explicit modules isn’t Tuist’s bug, but the trigger condition — leaving Xcode in charge of modulemap synthesis for pure-Swift SPM frameworks — is.

Opened a PR for the modulemap side of this: https://github.com/tuist/tuist/pull/10971

The fix is intentionally scoped to Swift-only SwiftPM products promoted to frameworks. Those targets did not get a Tuist-provided modulemap, so Xcode could synthesize one that referenced <Module>-Swift.h. With explicit module scanning, that synthesized modulemap can be scanned before Swift emits the compatibility header, which explains the header '<Module>-Swift.h' not found failure.

I looked at the architecture angle too, especially projects where a package dependency excludes x86_64 for the simulator. There is a second concern there: cache warming builds with ONLY_ACTIVE_ARCH=NO, so it can try to produce simulator slices that the original graph cannot actually build.

I do not think we should fix that by propagating architecture exclusions into the generated project or cache consumption graph. If we do that, supported architectures become inconsistent across the graph depending on which dependency introduced the constraint and whether cache is enabled. It also means a cached binary can silently narrow the consumer target’s architecture support, which is hard to reason about.

So the current PR leaves architecture settings unchanged. That means binaries in the cache can still be partial architecture artifacts when the source graph itself only supports a partial simulator architecture set. We should treat that as a separate design problem: either make cache warming respect the exact build destination/architecture intentionally, or encode architecture support in the cache artifact metadata and selection logic so consumers never receive an incompatible binary. I would avoid solving it by mutating the consumer side of the graph.

Validated against 4.195.9 + Xcode 26.5 using the original 4-file repro: ✅ the header 'Logging-Swift.h' not found failure is gone. tuist cache Consumer --configuration Debug succeeds end-to-end without the EXCLUDED_ARCHS trigger (2 targets stored: Consumer, Logging). Thanks @pepicrft 🙌

One secondary issue surfaced when I re-tested the trigger combination from the OP: with productTypes: ["Logging": .framework] and baseSettings.base["EXCLUDED_ARCHS[sdk=iphonesimulator*]"] = "x86_64" still set, caching a first-party .framework consumer of Logging now fails with:

…/LoggingConsumer/Sources/Consumer.swift:4:40: cannot find type 'Logger' in scope
[!] 'Consumer' is missing a dependency on 'Logging' because dependency scan of Swift module 'Consumer' discovered a dependency on 'Logging'

Different root cause — PackageSettings.baseSettings only applies to SPM products, so Logging.framework is built arm64-only while the first-party Consumer.framework still builds multi-arch. Consumer’s x86_64 SwiftCompile then can’t resolve Logging because no x86_64 slice exists.

Workaround: mirror the same EXCLUDED_ARCHS[sdk=iphonesimulator*] value into the consumer project’s settings so first-party targets also build arm64-only on simulator. For example, in Project.swift:

let project = Project(
    name: "Repro",
    settings: .settings(
        base: ["EXCLUDED_ARCHS[sdk=iphonesimulator*]": "x86_64"]
    ),
    targets: [ ... ]
)

With that single addition, the cache succeeds end-to-end (2 targets stored: Consumer, Logging).

Distinct from the original modulemap issue and arguably a settings-inheritance question rather than a bug, but flagging here in case anyone hits it after upgrading. Happy to open a separate issue if it warrants its own thread.

The fix for Swift-only package framework modulemaps is now available in 4.195.9. Please update to this version to resolve the header '<Module>-Swift.h' not found error when caching pure-Swift SPM products promoted to .framework under single-arch builds.

The fix for the missing -Swift.h header in pure-Swift SPM frameworks is now available in 4.195.15. Update to this version to resolve the cache failures.