Spm Build Analysis

1---2name: spm-build-analysis3description: Analyze Swift Package Manager dependencies, package plugins, module variants, and CI-oriented build overhead that slow Xcode builds. Use when a developer suspects packages, plugins, or dependency graph shape are hurting clean or incremental build performance, mentions SPM slowness, package resolution time, build plugin overhead, duplicate module builds from configuration drift, circular dependencies between modules, oversized modules needing splitting, or modularization best practices.4---5 6# SPM Build Analysis7 8Use this skill when package structure, plugins, or dependency configuration are likely contributing to slow Xcode builds.9 10## Core Rules11 12- Treat package analysis as evidence gathering first, not a mandate to replace dependencies.13- Separate package-graph issues from project-setting issues.14- Do not rewrite package manifests or dependency sources without explicit approval.15 16## What To Inspect17 18- `Package.swift` and `Package.resolved`19- local packages vs remote packages20- package plugin and build-tool usage21- binary target footprint22- dependency layering, repeated imports, and potential cycles23- build logs or timing summaries that show package-related work24 25## Verification Before Recommending26 27Before including any local package in a recommendation, verify that it is actually part of the project's dependency graph. A `Vendor/` directory may contain packages that are not linked to any target.28 29- Check `project.pbxproj` for `XCLocalSwiftPackageReference` entries that reference the package path.30- Check `XCSwiftPackageProductDependency` entries to confirm the package's product is linked to at least one target.31- If a local package exists on disk but is not referenced in the project, do not include it in build-time recommendations.32 33When recommending version pins for branch-tracked dependencies:34 35- Use the helper script to scan all branch-pinned dependencies at once:36  ```bash37  python3 scripts/check_spm_pins.py --project App.xcodeproj38  ```39  This checks `git ls-remote --tags` for each branch-pinned package and reports which have tags available for pinning.40- If no tags exist, recommend pinning to a specific commit revision hash for determinism instead.41- Note which packages are branch-pinned because the upstream simply has no tags, versus packages that have tags but are intentionally tracking a branch.42 43## Focus Areas44 45- package graph shape and how much work changes trigger downstream46- plugin overhead during local development and CI47- checkout or fetch cost signals that show up in clean environments48- configuration drift that forces duplicate module builds49- risks from package targets that use different macros or options while sharing dependencies50- dependency direction violations (features depending on each other instead of shared lower layers)51- circular dependencies between modules (extract shared contracts into a protocol module)52- oversized modules (200+ files) that widen incremental rebuild scope53- umbrella modules using `@_exported import` that create hidden dependency chains54- missing interface/implementation separation that blocks build parallelism55- test targets depending on the app target instead of the module under test56- Swift macro rebuild cascading: heavy use of Swift macros (e.g., TCA, swift-syntax-based libraries) can cause a trivial source change to cascade into near-full rebuilds because macro expansion invalidates downstream modules57- `swift-syntax` building universally (all architectures) when no prebuilt binary is available, adding significant clean-build overhead58- multi-platform build multiplication: adding a secondary platform target (e.g., watchOS) can cause shared SPM packages to build multiple times (e.g., iOS arm64, iOS x86_64, watchOS arm64), multiplying `SwiftCompile`, `SwiftEmitModule`, and `ScanDependencies` tasks59 60## Modular SDK Migration Caveat61 62Migrating a dependency from a monolithic target to a modular multi-target SDK (e.g., replacing one umbrella library with separate Core, RUM, Logs, Trace modules) does not automatically reduce build time. Modular targets increase the number of `SwiftCompile`, `SwiftEmitModule`, and `ScanDependencies` tasks because each target must be compiled, scanned, and emit its module independently. The build-time trade-off depends on the project's parallelism headroom and how many of the modular targets are actually needed.63 64When considering a modular SDK migration:65 66- Compare the total `SwiftCompile` task count before and after.67- Benchmark both configurations before recommending the migration for build speed.68- If the motivation is API surface reduction (importing only what you use), note that build time may stay flat or increase while import hygiene improves.69- Only recommend modular SDK migration for build speed when the project currently compiles large portions of the monolithic SDK that it does not use, and the modular alternative lets it skip those unused portions entirely.70 71## Explicit Module Dependency Angle72 73When the same module appears multiple times in timing output, investigate whether different package or target options are forcing extra module variants. Uniform options often matter more than shaving a small amount of source code.74 75## Reporting Format76 77For each finding, include:78 79- evidence80- affected package or plugin81- likely clean-build vs incremental-build impact82- CI impact if relevant83- estimated impact84- approval requirement85 86If the main problem is not package-related, hand off to [`xcode-project-analyzer`](../xcode-project-analyzer/SKILL.md) or [`xcode-compilation-analyzer`](../xcode-compilation-analyzer/SKILL.md) by reading the target skill's SKILL.md and applying its workflow to the same project context.87 88## Additional Resources89 90- For the detailed audit checklist, see [references/spm-analysis-checks.md](references/spm-analysis-checks.md)91- For the shared recommendation structure, see [references/recommendation-format.md](references/recommendation-format.md)92- For source citations, see [references/build-optimization-sources.md](references/build-optimization-sources.md)