depermaid

1.1.0

Effortlessly visualize dependencies in Swift projects. This tool generates Mermaid-format graphs, representing the architecture and connections between modules in your Swift package. Quickly understand your project's structure, dependencies, and gain valuable development insights.
daikimat/depermaid

What's New

1.1.0

2024-02-04T23:48:49Z

What's Changed

Breaking Change

  • The graph will now be output alphabetically sorted. Prior to this version, the order written in "Package.swift" was output as-is. (#14)
  • Default direction changed to LR (Left to Right) from TD (Top Down). (#15)

New Feature

  • Introducing the --minimal option to display simplified graphs. This option is useful for packages with a deep hierarchy of direct and transitive dependencies. The resulting Mermaid diagram will provide a clearer representation by omitting duplicate arrows. (#14)

    Before:
    When dealing with packages having a complex hierarchy of direct and transitive dependencies:
    complex

    After (using --minimal option):
    To simplify the graph and focus solely on essential dependencies, run the following command:

    $ swift package plugin depermaid --minimal

    The resulting Mermaid diagram will show a clearer representation by omitting duplicate arrows:
    minimal

Other Change

Full Changelog: 1.0.1...1.1.0

depermaid - Swift Package Plugin

depermaid is a Swift Package Manager plugin that generates Mermaid diagrams representing dependencies within your Swift package.

Why Use Depermaid?

Using depermaid allows you to continuously visualize the up-to-date state of your project's dependencies. It provides a means to face your project's structure visually, gaining insights into your dependencies. It's recommended to run depermaid whenever the content of your Package.swift file is updated and reflect the generated diagrams in your README or documentation.

Requirements

//swift-tools-version:5.9

Usage

  1. Add the following line to your Package.swift file in the dependencies section:

    dependencies: [
        .package(url: "https://github.com/daikimat/depermaid.git", from: "1.0.1")
    ],
  2. Run the following command in the same directory as your Package.swift file:

    $ swift package plugin depermaid

    The generated Mermaid diagram illustrates the dependencies between modules within your Swift package:

flowchart LR
    AnimalClient
    Cat-->AnimalClient
    Dog-->AnimalClient
    Example-->Cat
    Example-->Dog

Command Options

You can customize the command options according to your specific use case:

Including Test Targets

Run the following command to include test targets in the generated Mermaid diagram:

$ swift package plugin depermaid --test
flowchart LR
    AnimalClient
    AnimalClientTests{{AnimalClientTests}}-->AnimalClient
    Cat-->AnimalClient
    Dog-->AnimalClient
    Example-->Cat
    Example-->Dog

Including Executable Targets

Run the following command to include executable targets in the generated Mermaid diagram:

$ swift package plugin depermaid --executable
flowchart LR
    AnimalClient
    Cat-->AnimalClient
    Dog-->AnimalClient
    Example-->Cat
    Example-->Dog
    ExecutableExample([ExecutableExample])-->Dog

Including Products

Run the following command to include products in the generated Mermaid diagram:

$ swift package plugin depermaid --product
flowchart LR
    AnimalClient-->LifeCore[[LifeCore]]
    Cat-->AnimalClient
    Dog-->AnimalClient
    Example-->Cat
    Example-->Dog

Including All

Run the following command to include test targets, executable targets, and products in the generated Mermaid diagram:

$ swift package plugin depermaid --test --executable --product
flowchart LR
    AnimalClient-->LifeCore[[LifeCore]]
    AnimalClientTests{{AnimalClientTests}}-->AnimalClient
    Cat-->AnimalClient
    Dog-->AnimalClient
    Example-->Cat
    Example-->Dog
    ExecutableExample([ExecutableExample])-->Dog

Direction

You have the option to define the orientation of the generated Mermaid diagram by utilizing the --direction parameter. The available orientations are TD, TB(same as TD), BT, RL, LR. By default, it's set to LR."

$ swift package plugin depermaid --direction TD --test --executable --product
flowchart TD
    AnimalClient-->LifeCore[[LifeCore]]
    AnimalClientTests{{AnimalClientTests}}-->AnimalClient
    Cat-->AnimalClient
    Dog-->AnimalClient
    Example-->Cat
    Example-->Dog
    ExecutableExample([ExecutableExample])-->Dog

Minimal Dependencies

For packages with a deep hierarchy of direct and transitive dependencies, the generated graph may appear complex, as illustrated below:

flowchart LR
    A-->B
    A-->C
    A-->D
    A-->E
    B-->C
    B-->D
    B-->E
    C-->D
    C-->E
    D
    E

To simplify the graph and focus solely on essential dependencies, run the following command:

$ swift package plugin depermaid --minimal

The resulting Mermaid diagram will show a clearer representation by omitting duplicate arrows:

flowchart LR
    A-->B
    B-->C
    C-->D
    C-->E
    D
    E

Examples

To demonstrate the capabilities of Depermaid, a sample project is provided in the ./Example/ExampleDepermaid.xcodeproj.

Expected Behavior

Upon successful build and run, Depermaid will analyze the Swift package dependencies in the example project and generate a Mermaid-format graph. This graph will be automatically reflected in this README file, demonstrating the integration of Depermaid to visualize Swift package dependencies. Please refer to this README file when reviewing the generated graph.

The mechanism behind the automatic update of the README file during the build process is implemented using a custom script added to the Xcode project's Build Phases.

Build and Run the Example

Follow these steps to build and run the example project:

  1. Open the Xcode project:

    open ./Example/ExampleDepermaid.xcodeproj
  2. Make changes to the ./Example/Package.swift file as needed.

  3. Build and run the project from Xcode.

After the build process, please review this README file to see the updated graph reflecting the changes made to the Swift package dependencies.

License

Depermaid is released under the MIT License.

Description

  • Swift Tools 5.9.0
View More Packages from this Author

Dependencies

  • None
Last updated: Mon Feb 26 2024 16:26:59 GMT-1000 (Hawaii-Aleutian Standard Time)