Metadata-Version: 2.4
Name: suitable-loop
Version: 0.1.2
Summary: Local production engineering platform — semantic code analysis, git risk scoring, and log correlation via MCP
Project-URL: Homepage, https://github.com/suitable-adventures/suitable-loop
Project-URL: Repository, https://github.com/suitable-adventures/suitable-loop
Project-URL: Bug Tracker, https://github.com/suitable-adventures/suitable-loop/issues
Author-email: Johan Valentini Jensen <johan@valentini.dk>
License-Expression: MIT
License-File: LICENSE
Keywords: code-analysis,git,mcp,production-engineering,python
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: Software Development :: Testing
Requires-Python: >=3.11
Requires-Dist: gitpython>=3.1
Requires-Dist: mcp>=1.0.0
Requires-Dist: networkx>=3.0
Requires-Dist: radon>=6.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Description-Content-Type: text/markdown

# Suitable Loop

Local production engineering platform — semantic code analysis, git risk scoring, and log correlation via MCP.

## What it does

Suitable Loop indexes your Python codebase and exposes deep analysis through MCP tools that AI assistants can call:

- **Code Analysis** — AST-based parsing, function/class extraction, call graph construction, cyclomatic complexity
- **Git Risk Scoring** — Weighted risk scores per commit (complexity delta × blast radius × churn × size)
- **Log Correlation** — Parse logs, group errors by signature, map stack frames to indexed code
- **Dependency Graph** — NetworkX-powered call graphs, import trees, blast radius analysis

## Quick Start

### 1. Add MCP server to your project

Create `.mcp.json` in your project root:

```json
{
  "mcpServers": {
    "suitable-loop": {
      "command": "uvx",
      "args": ["suitable-loop"]
    }
  }
}
```

That's it. `uvx` fetches the package from PyPI automatically — no manual install needed.

> **Local development?** Point to a local checkout instead:
> ```json
> "args": ["--from", "/path/to/suitable-loop", "suitable-loop"]
> ```

### 2. Install slash commands (optional)

Clone the repo and copy the commands into your project:

```bash
git clone https://github.com/suitable-adventures/suitable-loop.git /tmp/suitable-loop
mkdir -p .claude/commands
cp /tmp/suitable-loop/.claude/commands/* .claude/commands/
```

### 3. Restart Claude Code and start using it

```
/onboard                          # Get a full codebase orientation
/risk-report                      # Analyze recent commits by risk
/impact-check models.py           # Check blast radius before changing a file
/debug-error "ConnectionResetError in db/pool.py"
/health-check                     # Full codebase health assessment
/trace-function my_function       # Map a function's callers and callees
```

## Slash Commands

| Command | What it does |
|---------|-------------|
| `/onboard` | Index the codebase and produce a full orientation: structure, hotspots, complexity, blast radius |
| `/risk-report` | Score recent commits by risk, find hotspots, recommend where to focus review |
| `/impact-check <file>` | Before changing a file: blast radius, who calls what, what could break |
| `/debug-error <error or log path>` | Correlate an error/traceback to source code paths |
| `/health-check` | Full assessment: complexity, coupling, churn trends, actionable recommendations |
| `/trace-function <name>` | Map a function's callers, callees, complexity, and role in the system |
| `/release [patch\|minor\|major]` | Bump version, tag, and publish a new release to PyPI |

## MCP Tools

### Code Analysis
| Tool | Description |
|------|-------------|
| `index_codebase` | Index a Python project — parse AST, extract entities, build call graph |
| `query_entity` | Look up a function/class/file by name with all relationships |
| `find_callers` | Find all functions that call a given function |
| `find_callees` | Find all functions called by a given function |
| `dependency_tree` | Get import dependency tree for a file |
| `search_code` | Full-text search across indexed functions and classes |
| `complexity_report` | Top N most complex functions |
| `codebase_summary` | High-level stats and most-connected modules |

### Git Analysis
| Tool | Description |
|------|-------------|
| `analyze_recent_changes` | Score recent commits by risk |
| `analyze_commit` | Deep-dive a single commit |
| `hotspot_report` | Files with high churn × high dependency count |
| `blast_radius` | Transitive impact of changing a file |

### Log Analysis
| Tool | Description |
|------|-------------|
| `ingest_logs` | Parse log files, extract errors, group by signature |
| `get_error_groups` | List distinct error groups by frequency |
| `error_detail` | Full detail on an error group with code links |
| `correlate_error` | Map raw error text to code paths |
| `error_timeline` | Error frequency over time |

### Utility
| Tool | Description |
|------|-------------|
| `status` | Server status and entity counts |
| `reindex` | Incremental re-index (only changed files) |

## Architecture

```
suitable_loop/
├── __init__.py          # Package root
├── __main__.py          # Entry point (python -m suitable_loop)
├── server.py            # MCP server setup (FastMCP) + main() entry point
├── config.py            # Configuration dataclasses
├── models.py            # Data models (entities, edges)
├── db.py                # SQLite database layer
├── analyzers/
│   ├── code_analyzer.py # AST parsing, call resolution
│   ├── git_analyzer.py  # Commit analysis, risk scoring
│   └── log_analyzer.py  # Log parsing, error grouping
├── graph/
│   └── engine.py        # NetworkX graph engine
└── tools/
    ├── code_tools.py    # MCP code analysis tools
    ├── git_tools.py     # MCP git analysis tools
    ├── log_tools.py     # MCP log analysis tools
    └── util_tools.py    # MCP utility tools
```

## Configuration

Environment variables:

| Variable | Default | Description |
|----------|---------|-------------|
| `SUITABLE_LOOP_DB_PATH` | `~/.suitable-loop/suitable-loop.db` | SQLite database path |
| `SUITABLE_LOOP_LOG_LEVEL` | `INFO` | Logging level |

Default exclude patterns (files skipped during indexing):
- `.venv/`, `venv/`, `node_modules/`, `__pycache__/`, `migrations/`, `.git/`

## Development

For working on Suitable Loop itself:

```bash
cd suitable-loop
uv venv && uv pip install -e ".[dev]"
uv run pytest
```
