source-mesh
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-meshincrates/source-meshowns argument parsing, help, and process exit handling. It installs thesource-meshexecutable.source-mesh-coreowns analysis, graph processing, exports, output validation, and cycle checks. Its typed API can be used without the CLI orclap.
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.