depermaid - Swift Package Plugin

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

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.

//swift-tools-version:5.9

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

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

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

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

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

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

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

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

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

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.

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.

Depermaid is released under the MIT License.