Metadata-Version: 2.4
Name: depmesh
Version: 0.1.2
Summary: Unified, deterministic CLI for coding agents to discover relationships between project files and artifacts.
Project-URL: Homepage, https://github.com/Tiendil/depmesh
Project-URL: Repository, https://github.com/Tiendil/depmesh
Project-URL: Issues, https://github.com/Tiendil/depmesh/issues
Project-URL: Changelog, https://github.com/Tiendil/depmesh/blob/main/CHANGELOG.md
Author-email: Aliaksei Yaletski <a.eletsky@gmail.com>
License-Expression: BSD-3-Clause
License-File: LICENSE
Keywords: ai-agents,cli,code-analysis,codebase-intelligence,codebase-navigation,coding-agents,dependency-analysis,dependency-graph,impact-analysis,llm
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: BSD License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Build Tools
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Utilities
Requires-Python: <4.0,>=3.12
Requires-Dist: pydantic~=2.13.3
Requires-Dist: tomli>=2.4.0
Requires-Dist: typer~=0.25.1
Description-Content-Type: text/markdown

# depmesh

`depmesh` is a CLI tool that helps agents and developers investigate how project artifacts depend on each other.

Use it to explore a codebase, find related files, inspect the impact of a possible change, locate tests or specifications, and follow project-specific relationships that are hard to remember or discover manually.

`depmesh` gives one stable interface for navigating dependency relationships, while each project decides how dependencies are discovered exactly: path patterns, fixed lists, filesystem searches, static-analysis commands, or project-specific scripts.

## Example

Before changing a CLI module, ask `depmesh` for the specifications and tests connected to it:

```bash
> depmesh -p llm dependencies -r governed_by -r tested_by ./depmesh/cli/application.py

## governed_by

Specifications that apply to the artifact.

- @/specs/architecture/entities.md
- @/specs/architecture/errors.md
- @/specs/architecture/modules_layout.md
- @/specs/architecture/naming.md
- @/specs/architecture/static_analysis.md
- @/specs/architecture/tests.md
- @/specs/behavior/cli.md
- @/specs/behavior/file_paths.md

## tested_by

Tests that verify the artifact.

- @/depmesh/cli/tests/test_application.py

```

## Rationale

Coding agents often need to answer practical questions before editing:

- Which tests should be read before changing this file?
- Which specifications govern this module?
- Which files import this shared helper?
- Which artifacts are affected by this specification change?

`depmesh` answers those questions through configured relations.

For example, a project can define relations such as:

- `tested_by` — tests that verify an artifact.
- `governed_by` — specifications that apply to an artifact.
- `imports` — Python files imported by an artifact.
- `imported_by` — Python files that import an artifact.

## Features

- Unified interface for discovering project dependencies.
- Configurable ways to detect dependencies behind the scenes: path patterns, fixed lists, calling CLI commands, or running project-specific scripts.

## Quick Usage

List available relations first:

```bash
depmesh relations
```

Query dependencies for an artifact:

```bash
depmesh dependencies ./src/app.py
```

Query selected relations:

```bash
depmesh dependencies --relation governed_by --relation tested_by ./src/app.py
```

Initialize a starter configuration:

```bash
depmesh init
```

Read detailed agent-oriented usage:

```bash
depmesh skill usage
```

Other built-in docs:

```bash
depmesh skill configuration
depmesh skill initialization
```

## Installation

Install `depmesh` from PyPI in the environment where your agent or tools run:

```bash
uv tool install depmesh

# or
pip install depmesh
```

Then initialize a starter configuration in the project root:

```bash
depmesh init
```

The starter `depmesh.toml` is valid, but it is only a starting point. Edit it so it describes the dependency relations that matter in your project.

Tell agents to use `depmesh` by adding a short note to `AGENTS.md`:

```markdown
Use `depmesh` to discover dependencies between project artifacts.
Agents MUST use `depmesh` for dependency types supported by its configuration.
At the start of each work session, run `depmesh skill usage`.
```

You can ask a coding agent to help fill the configuration. A good prompt is:

```text
Inspect this project and update depmesh.toml with useful dependency relations.
Start by reading output of `depmesh skill initialization` and `depmesh skill configuration`.
```

This repository uses `depmesh` for its own dependency mapping. See [depmesh.toml](./depmesh.toml) for a real configuration example.

## Configuration

`depmesh` is useful only when the project has a meaningful `depmesh.toml`.

The configuration declares:

- relations that can be queried.
- rules that match queried artifacts.
- sources that produce dependency artifacts.

Minimal relation example:

```toml
version = 1

[[relations]]
id = "tested_by"
description = "Tests that verify the artifact."

[[rules]]
relation = "tested_by"
input = { type = "glob", pattern = "./src/{*module}.py" }
output = { type = "files", pattern = "./tests/test_{module}.py" }
```

This defines one relation named `tested_by`. The rule matches source files like `./src/app.py`, captures `app` as `module`, and looks for `./tests/test_app.py` as the dependency.

Run `depmesh skill configuration` for the agent-oriented configuration guide.

For the full configuration contract, see [the configuration specification](./specs/behavior/config.md).

## Specifications

Project behavior and architecture are specified in [./specs](./specs). Start with [./specs/intro.md](./specs/intro.md) when looking for the source of truth.

## Development

Development commands run through Docker:

```bash
./bin/dev.sh uv run -- pytest
./bin/dev.sh uv run -- depmesh relations
```

Build development containers only after approved Docker or dependency changes:

```bash
./bin/dev-build-containers.sh
```
