# 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:
```console
rustup component add rust-analyzer rust-src
cargo install source-mesh --locked
```
Before the first crates.io release, install directly from GitHub:
```console
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:
```console
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:
```console
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.
```yaml
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`](crates/source-mesh-core/README.md) 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.
```console
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:
```powershell
./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:
```console
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](crates/source-mesh-core/src/fixtures/README.md) 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](crates/source-mesh/tests/expected/README.md).
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](LICENSE).