Skip to content

Latest commit

 

History

History
 
 

README.md

spmgraph - SwiftPM dependency graph management

CI status Swift Package Manager

A CLI tool that unlocks Swift dependency graphs, giving you extra information and capabilities.
With it, you can visualize your dependency graph, run selective tests, and enforce architectural rules for an optimal modular setup.
spmgraph can be run for any local Package.swift.

Visualize

Generate an image that visually represents your dependency graph. Open the map!

spmgraph visualize <package-path> --help

Tests

Selective testing based on git changes or a given list of changed files.
The output is a comma-separated list of test targets that can be fed into xcodebuild's -only-testing:TEST-IDENTIFIER or fastlane scan's only_testing

spmgraph tests <package-path> --help

Lint

Verifies whether the dependency graph follows the team-defined best practices.

It's built on top of a user-defined SPMGraphConfig.swift, which allows teams to configure their own dependency graph rules leveraging Swift and the SwiftPM library.

SPMGraphConfig.default provides the standard definition with built-in rules and extensible rules that can also be used on custom configurations.

For that, the steps are:

Config & Load

1. Config

Init or edit your spmgraph config

spmgraph config <package-path> --help
  • if none, it creates an initial SPMGraphConfig.swift on the same path as your Package.swift
  • spmgraph opens up a temporary Swift Package where you configure spmgraph in Swift and build to check that everything is correct

Examples

For example, enforce that

  • Feature modules don't depend on each other
  • Linked dependencies are imported (used) at least once
  • Base modules don't depend on feature modules
  • The dependency graph isn't too deep

All possible using Swift. Below is an example of creating your own lint rule by traversing the dependency graph:

extension SPMGraphConfig.Lint.Rule {
  static let unregisteredLiveModules = Self(
    id: "unregisteredLiveModules",
    name: "Unregistered Live modules",
    abstract: "Live modules need to be added to the app target/feature module as dependencies.",
    validate: { package, excludedSuffixes in
      let liveModules = package
        .modules
        .compactMap { module -> Module? in
          guard !module.containsOneOf(suffixes: excludedSuffixes), module.isLiveModule else {
            return nil
          }
          return module
        }

      guard
        let featureModule = package
          .modules
          .first(where: { $0.name == "GetYourGuideFeature" }),
        case let featureModuleDependencies = featureModule
          .dependencies
          .compactMap(\.module)
      else {
        return [LintError.missingFeatureModule]
      }

      return liveModules.compactMap { liveModule in
        if !featureModuleDependencies.contains(liveModule) {
          return LintError.unregisteredLiveModules(
            moduleName: liveModule.name,
            appModule: featureModule.name
          )
        }

        return nil
      }
    }
  )
}

2. Load

Load the latest SPMGraphConfig.swift into spmgraph

spmgraph load <package-path> --help

Run the linter

spmgraph lint <package-path> --help

Fail on warnings

spmgraph lint <package-path> --strict <other-options>

Allowed warnings count

Bypass the strict mode on a given number of allowed warnings

spmgraph lint <package-path> --strict --warningsCount 3 <other-options>

CI

Custom GitHub actions are available for running the different spmgraph commands in CI environments.

When using multiple runners AND to speed up builds:

  • Pass a custom config build directory via the --config-build-directory option
  • It allows caching and pre-warming the config package
  • It will make loading the config into spmgraph much faster

Requirements

  • graphviz (available via brew install graphviz)
  • Xcode 16+ and the Swift 6.0+ toolchain

Installation

Mint

mint install getyourguide/spmgraph
  • For optimal build times, make sure ~/.mint/bin/spmgraph is cached on your CI runner.

Acknowledgments

  • Inspired by the work that the Tuist team does for the Apple developers community and their focus on leveraging the dependency graph to provide amazing features for engineers. Also, a source of inspiration for our shell abstraction layer.

Open roadmap

  • Cover the core logic of Lint, Map, and Visualize libs with tests
  • Improve the unusedDependencies lint rule to cover products with multiple targets
  • Support macros (to become a GitHub issue)

Ideas

  • Add fix-it suggestion to lint errors
  • Create Danger plugin for the linter functionality

Contributing

Check the CONTRIBUTING.md file.