Metadata-Version: 2.4
Name: repo-contract
Version: 0.2.1
Summary: A governance layer for AI coding agents: enforceable, machine-checkable rules for plans and diffs
Author-email: Yash Shah <72321363+dager23@users.noreply.github.com>
License: MIT License
        
        Copyright (c) 2026 Yash Shah
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://github.com/dager23/RepoContract
Project-URL: Repository, https://github.com/dager23/RepoContract
Project-URL: Issues, https://github.com/dager23/RepoContract/issues
Keywords: ai-agents,governance,policy,architecture,linter,static-analysis,mcp,code-review
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: Software Development :: Testing
Classifier: Typing :: Typed
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: click>=8.0.0
Requires-Dist: pyyaml>=6.0.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Dynamic: license-file

# repo-contract — AI Agent Governance Layer

[![PyPI](https://img.shields.io/pypi/v/repo-contract.svg)](https://pypi.org/project/repo-contract/)
[![Python versions](https://img.shields.io/pypi/pyversions/repo-contract.svg)](https://pypi.org/project/repo-contract/)
[![CI](https://github.com/dager23/RepoContract/actions/workflows/ci.yml/badge.svg)](https://github.com/dager23/RepoContract/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/license-MIT-yellow.svg)](LICENSE)

`repo-contract` is a lightweight, portable Python package and command-line tool that acts as an **enforceable governance layer** for AI coding agents (such as Claude Code, Cursor, Codex, Windsurf, Aider, etc.). 

It allows repositories to declare machine-checkable architectural, safety, and workflow rules. The engine deterministically validates proposed agent plans (pre-edit) and git diff patches (post-edit) to ensure compliance before code is modified or merged.

## Why Governance?
AI agents are excellent at generating edits, but often fail to respect repository-specific constraints:
* **Scope Creep**: Editing unrelated components or refactoring large sub-systems.
* **Architectural Regressions**: Importing internal database handlers directly into view controllers.
* **Workflow Breaches**: Editing crucial functionality without adding corresponding tests.
* **Safety Violations**: Reading/modifying forbidden files (`.env`, `secrets/`) or sensitive directories.

Rather than trying to help agents "understand more code" or storing synthetic meaning, `repo-contract` focuses on **enforcing negative constraints**, which empirical studies show is the most effective way to shape safe agent workflows.

---

## Key Features
* **YAML/TOML Contracts**: Declarative policy schema containing architecture layers, safety paths, agent limits, and test mappings.
* **Python Module Inspector**: AST-based import resolution (both absolute and relative package paths).
* **Plan Validation**: Pre-checks an agent's text/markdown plan block, extracting planned files and verifying safety boundaries before edits begin.
* **Diff Validation**: Analyzes git patches/diffs to catch forbidden imports, path violations, test gaps, and file counts.
* **Dependency Guard**: Warns when a diff adds imports of external packages that are not declared in `pyproject.toml` / `requirements.txt` / `setup.py` — a common AI-agent failure mode.
* **Unrelated Refactor Detection**: Identifies whether modifications span disjoint, unconnected modules in the import graph (connected components analysis).
* **Deterministic Engine**: 100% deterministic rules with clear, human-readable explanations and JSON-RPC outputs.
* **MCP Server Integration**: Stdio-based Model Context Protocol (MCP) server wrapper that exposes validators directly as tools for AI assistants.

---

## Installation

```bash
pip install repo-contract
```

Requires Python 3.11 or newer. This installs the `repo-contract` command along with the MCP server.

<details>
<summary>Installing from source (for development)</summary>

```bash
git clone https://github.com/dager23/RepoContract.git
cd RepoContract
pip install -e ".[dev]"
pytest
```

</details>

---

## Quick Start

### 1. Initialize the Contract
Create a default configuration file in your repository:
```bash
repo-contract init
# Generates repo-contract.yaml
```

### 2. Configure Rules
Modify `repo-contract.yaml` (or TOML equivalent) to define your rules:

```yaml
version: 1

project:
  name: my-app
  src_root: "my_app"  # Directory containing python package modules

architecture:
  layers:
    - name: ui
      paths: ["my_app/ui/**"]
      # Entries may be layer names ("db"), dotted module prefixes ("my_app.db"),
      # or path prefixes ("my_app/db") — all three are equivalent.
      cannot_import: ["my_app/db"] # UI layer cannot import DB layer directly
    - name: db
      paths: ["my_app/db/**"]
      cannot_import: ["my_app/ui"]

workflow:
  required_tests:
    # Require corresponding test file to be modified when source is modified
    - when_paths_match: ["my_app/**/*.py"]
      require: ["tests/**/test_*.py"]

safety:
  forbidden_paths:
    - ".env"
    - "secrets/**"
  approval_required_for:
    - "my_app/auth/**"

agent:
  max_files_per_change: 6
  forbid_unrelated_refactors: true

dependencies:
  # Warn when a diff adds imports of packages not declared in the
  # project's dependency files (pyproject.toml / requirements.txt / setup.py)
  check_undeclared: true
```

### 3. Run Validation

#### Scan Codebase
Scan the entire repository for static layer boundary violations or missing tests:
```bash
repo-contract scan
```

#### Validate Agent Plan (Pre-edit)
Pass the agent's proposed plan (as raw text or from a file) to ensure they aren't touching forbidden files or planning changes that are too broad:
```bash
repo-contract check-plan "I will edit my_app/auth/login.py and .env to configure authentication."
# Fails because .env is forbidden and auth/ requires approval.

# Or validate a plan saved to a file:
repo-contract check-plan plan.md
```
If the argument is a path to an existing file it is read as a plan file; otherwise it is treated as raw plan text (use `--text` to force raw-text interpretation).

#### Validate Git Diff (Post-edit / CI Gate)
Check uncommitted working tree edits, a specific git commit range, or a patch file:
```bash
# Validate local uncommitted edits
repo-contract check-diff

# Validate staging changes
repo-contract check-diff --staged

# Validate range (e.g. CI run)
repo-contract check-diff HEAD~1..HEAD

# Validate a patch file
repo-contract check-diff my-change.patch
```

---

## Model Context Protocol (MCP) Integration
You can run `repo-contract` as a stdio-based MCP Server in your favorite editor (like Cursor, Claude Desktop, or Windsurf) by adding this command to your configuration:

```json
{
  "mcpServers": {
    "repo-contract": {
      "command": "python",
      "args": ["-m", "repo_contract.mcp.server"],
      "cwd": "/path/to/your/project"
    }
  }
}
```

### Exposed Tools
* `scan_repository`: Runs structural checks on the current workspace.
* `check_plan`: Analyzes the agent's textual/markdown plan, extracting planned files and validating bounds before edits begin.
* `check_diff`: Checks current uncommitted working directory edits.

---

## License
[MIT](LICENSE) © Yash Shah
