source-mesh 1.0.0

Dependency diagrams for Rust projects, powered by rust-analyzer SCIP
source-mesh-1.0.0 is not a library.

source-mesh

CI status Linux CI macOS CI Windows CI

Draw dependencies between physical folders in a Rust project. Export GraphML for yEd, Mermaid, or DOT, highlight cycles, and report cycles between folders or files.

Install

Install the analysis components, then install the latest published release:

rustup component add rust-analyzer rust-src
cargo install source-mesh --locked

Before the first crates.io release, install directly from GitHub:

cargo install --git https://github.com/GeneralGDA/source-mesh --locked source-mesh

Cargo installs an optimized release build. Keep Cargo and rust-analyzer on PATH; install rust-analyzer and rust-src for the toolchain selected by the project you analyze. source-mesh checks both prerequisites before starting analysis.

Run

From the Rust project you want to analyze:

source-mesh . --root src --format graphml --exclude-tests --output folders.graphml

Open folders.graphml in yEd and apply a layout. To find and highlight cycles:

source-mesh . --root src --format graphml --exclude-tests --highlight-cycles --cycles-output folder-cycles.md --file-cycles-output file-cycles.md --output folders.graphml
Option Effect
--depth 1 Only folders immediately below --root (default: all depths)
--group-folders Show subfolders inside their parent groups
--format dot / --format mermaid Export another diagram format
--exclude-tests Omit dependencies found only with test configuration enabled
--highlight-cycles Give each connected group of cycles a distinct color
--fail-on-cycles Exit unsuccessfully when file or folder cycle groups are found, after writing requested outputs
--cycles-output FILE Write folder cycle chains to Markdown
--file-cycles-output FILE Write file cycle chains before folder aggregation
--verbose / -v Include diagnostic details and timings

A → B means a file in A refers to a symbol defined in B. Edge labels count distinct file pairs. Folder aggregation can introduce cycles even when the file graph is acyclic.

Analysis of large projects can take several minutes. Use --verbose for diagnostic details and source-mesh --help for all options.

GitHub Actions

--fail-on-cycles turns file or folder dependency cycles into a failing CI step. The diagram and requested reports are written before the failure, so the artifact is available for diagnosis. Adjust --root src for the source layout of the repository being checked.

jobs:
  dependency-cycles:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7.0.1
        with:
          persist-credentials: false
      - run: rustup component add rust-analyzer rust-src
      - uses: Swatinem/rust-cache@v2.9.2
      - name: Install source-mesh
        run: cargo install --git https://github.com/GeneralGDA/source-mesh --locked source-mesh
      - name: Check dependency cycles
        run: |

          mkdir -p target/source-mesh
          source-mesh . --root src --format graphml --exclude-tests --highlight-cycles --fail-on-cycles --cycles-output target/source-mesh/folder-cycles.md --file-cycles-output target/source-mesh/file-cycles.md --output target/source-mesh/folder-dependencies.graphml
      - name: Upload cycle diagnostics
        if: ${{ failure() }}
        uses: actions/upload-artifact@v7.0.1
        with:
          name: source-mesh-cycle-diagnostics
          path: target/source-mesh
          if-no-files-found: warn

Reusing analysis

Save analysis with --save-scip analysis.scip; reuse it with --from-scip analysis.scip to change formats, depth, or filters without analyzing the source again.

Development

The repository root is a virtual workspace with two sibling crates:

  • source-mesh in crates/source-mesh owns argument parsing, help, and process exit handling. It installs the source-mesh executable.
  • source-mesh-core owns analysis, graph processing, exports, output validation, and cycle checks. Its typed API can be used without the CLI or clap.

The root Cargo.toml contains only workspace configuration, shared package metadata, dependencies, and lints; it does not define a package.

cargo test --release --locked --workspace
cargo clippy --release --all-targets --locked --workspace -- -D warnings

The test command above skips slow tests that run rust-analyzer. To run all workspace tests in release mode, including ignored tests and documentation tests, use PowerShell from the repository root:

./Test-All.ps1

The full run requires Cargo, rust-analyzer, and rust-src and can take several minutes. The script runs tests sequentially to avoid competing analyzer processes, continues with other test targets after a test failure, and returns Cargo's exit code. It resolves the workspace from the script location, so it can also be invoked by path from another directory.

Both crates are default workspace members. Run the CLI from the repository root with cargo run -p source-mesh -- ..., or install it locally with cargo install --path crates/source-mesh --locked. Installation from crates.io remains cargo install source-mesh --locked.

With PowerShell (pwsh) and Cargo on PATH, install the optional agent tools on Linux, macOS, or Windows:

pwsh -File ./Install-AgentTools.ps1

The script installs missing rg, fd, jaq, and ast-grep through Cargo without replacing commands already on PATH.

Unit and component tests live under each crate's src; normal runs use synthetic data and a bundled SCIP fixture without launching rust-analyzer. Component tests that run rust-analyzer index fixture projects during execution and require rust-src. Integration tests under crates/source-mesh/tests enforce the virtual workspace boundary and run the compiled application on the whole repository to check expected exports and dependency cycles.

Repository integration tests and their expected outputs remain in the checkout and are not included in the published CLI archive.

CI checks release builds, Clippy, unit and component tests, documentation tests, and repository integration tests on Linux, macOS, and Windows for every push and pull request.

License

MIT.