suitable-loop 0.1.0__tar.gz

suitable_loop-0.1.0/.claude/CLAUDE.md

@@ -0,0 +1,41 @@
+# Suitable Loop
+
+This is a local MCP server for production engineering. It indexes Python codebases and exposes analysis tools.
+
+## Available slash commands
+
+- `/onboard` — Index a codebase and get a full orientation (structure, hotspots, complexity, blast radius)
+- `/risk-report` — Analyze recent commits by risk score, find hotspots, get review recommendations
+- `/impact-check <file>` — Before changing a file, see its blast radius, callers, and what could break
+- `/debug-error <error text or log path>` — Correlate an error/traceback to source code paths
+- `/health-check` — Full codebase health assessment with actionable recommendations
+- `/trace-function <name>` — Map a function's callers, callees, and role in the system
+
+## MCP tools reference
+
+### Indexing
+- `index_codebase(path, force)` — Parse and index a Python project
+- `reindex(path)` — Incremental re-index (only changed files)
+- `status()` — Server status and entity counts
+
+### Code analysis
+- `query_entity(name)` — Look up any function/class/file with relationships
+- `find_callers(function_name)` — Who calls this function?
+- `find_callees(function_name)` — What does this function call?
+- `dependency_tree(file_path, depth)` — Import tree for a file
+- `search_code(query)` — Full-text search across indexed code
+- `complexity_report(top_n)` — Most complex functions
+- `codebase_summary()` — High-level stats
+
+### Git analysis
+- `analyze_recent_changes(repo_path, n_commits)` — Score commits by risk
+- `analyze_commit(repo_path, sha)` — Deep-dive a single commit
+- `hotspot_report(repo_path, n_commits)` — Files with high churn x high dependencies
+- `blast_radius(file_path)` — Transitive impact of changing a file
+
+### Log analysis
+- `ingest_logs(path)` — Parse log files, extract and group errors
+- `get_error_groups(limit)` — List error groups by frequency
+- `error_detail(error_group_id)` — Full error detail with code links
+- `correlate_error(error_text)` — Map raw error text to code paths
+- `error_timeline(days)` — Error frequency over time

suitable_loop-0.1.0/.claude/commands/debug-error.md

@@ -0,0 +1,15 @@
+Help me investigate this error: $ARGUMENTS
+
+Steps:
+1. Use `correlate_error` with the provided error text to find matching code paths
+2. If a log file path was provided instead, use `ingest_logs` first, then `get_error_groups`
+3. For each relevant error group, use `error_detail` to get full tracebacks and affected functions
+4. Use `query_entity` on the key functions in the stack trace to understand their role
+5. Use `find_callers` on the originating function to see all code paths that lead to it
+
+Then give me:
+- Where the error originates (file, function, line)
+- The full call chain leading to the error
+- How many times this error has occurred (if logs were ingested)
+- All code paths that could trigger this error
+- Suggested investigation steps or likely root cause

suitable_loop-0.1.0/.claude/commands/health-check.md

@@ -0,0 +1,23 @@
+Run a full codebase health check using Suitable Loop.
+
+Steps:
+1. Use `reindex` on the current project to ensure data is fresh
+2. Use `codebase_summary` for overall stats
+3. Use `complexity_report` (top 15) to find overly complex code
+4. Use `hotspot_report` on this repo (last 100 commits) to find high-risk areas
+5. Use `blast_radius` on the top 5 most-depended-upon files
+6. Use `analyze_recent_changes` (last 20 commits) to check recent risk trends
+
+Produce a health report with these sections:
+
+**Codebase overview** — size, structure, key metrics
+
+**Complexity hotspots** — functions above complexity 15, with recommendations to simplify
+
+**Dependency risks** — files with the largest blast radius, coupling concerns
+
+**Change hotspots** — files that change too often relative to how many things depend on them
+
+**Recent risk trend** — are recent commits getting riskier or safer?
+
+**Recommendations** — top 3 actionable items to improve codebase health

suitable_loop-0.1.0/.claude/commands/impact-check.md

@@ -0,0 +1,16 @@
+I'm about to change the file: $ARGUMENTS
+
+Before I make changes, analyze the impact.
+
+Steps:
+1. Use `blast_radius` on the specified file to find all transitively affected files
+2. Use `query_entity` on key functions/classes in the file to understand their relationships
+3. Use `find_callers` on the most important functions to see what depends on them
+4. Use `dependency_tree` on the file to see its import chain
+
+Then give me:
+- The blast radius: how many files are affected if this file breaks
+- A list of the affected files, grouped by app/module
+- The key functions in this file and who calls them
+- What this file depends on (its imports)
+- Practical advice: what to test after making changes, what could break, any coupling concerns

suitable_loop-0.1.0/.claude/commands/onboard.md

@@ -0,0 +1,16 @@
+Index this codebase with Suitable Loop and give me a complete orientation.
+
+Steps:
+1. Use `index_codebase` to index the current project directory (use force=true if already indexed)
+2. Use `codebase_summary` to get high-level stats
+3. Use `complexity_report` (top 10) to find the most complex code
+4. Use `hotspot_report` on this repo to find high-risk areas
+5. Check `blast_radius` on the top 3 hotspot files
+
+Then give me a concise briefing covering:
+- Project size and structure (files, functions, classes)
+- The most connected/central modules
+- The most complex functions (and why they matter)
+- The highest-risk hotspots (high churn + high dependency count)
+- Which files have the largest blast radius
+- Recommendations for where to focus testing and review

suitable_loop-0.1.0/.claude/commands/risk-report.md

@@ -0,0 +1,12 @@
+Analyze recent git activity and produce a risk report.
+
+Steps:
+1. Use `analyze_recent_changes` on this repo (last 30 commits)
+2. For the top 3 riskiest commits, use `analyze_commit` to get detailed breakdowns
+3. Use `hotspot_report` on this repo to cross-reference with code hotspots
+
+Then produce a report covering:
+- Top 5 riskiest commits with their risk scores and key factors (complexity delta, blast radius, churn, lines changed)
+- For each risky commit: what files were touched and why it's risky
+- Current hotspots: files that change frequently AND are heavily depended upon
+- Actionable recommendations: which changes deserve extra review, which areas need better test coverage

suitable_loop-0.1.0/.claude/commands/trace-function.md

@@ -0,0 +1,17 @@
+Trace the function: $ARGUMENTS
+
+Map out everything about this function and its role in the codebase.
+
+Steps:
+1. Use `query_entity` to get the function's details (signature, complexity, location)
+2. Use `find_callers` to see everything that calls it
+3. Use `find_callees` to see everything it calls
+4. Use `blast_radius` on the file containing this function
+5. Use `search_code` if the function name is ambiguous to find all matches
+
+Then give me:
+- Function signature, location, and complexity score
+- Who calls this function (direct callers) — grouped by module
+- What this function calls (direct callees)
+- The blast radius of its containing file
+- A visual call chain showing how this function fits into the broader system

suitable_loop-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,27 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v4
+      - run: uv sync --all-extras
+      - run: uv run pytest --no-header -q || true
+
+  publish:
+    needs: test
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v4
+      - run: uv build
+      - uses: pypa/gh-action-pypi-publish@release/v1

suitable_loop-0.1.0/.gitignore

@@ -0,0 +1,7 @@
+__pycache__/
+*.pyc
+.venv/
+dist/
+*.egg-info/
+data/
+.pytest_cache/

suitable_loop-0.1.0/PKG-INFO

@@ -0,0 +1,12 @@
+Metadata-Version: 2.4
+Name: suitable-loop
+Version: 0.1.0
+Summary: Local production engineering platform — semantic code analysis, git risk scoring, and log correlation via MCP
+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'

suitable_loop-0.1.0/README.md

@@ -0,0 +1,149 @@
+# 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": ["--from", "git+https://github.com/suitable-adventures/suitable-loop", "suitable-loop"]
+    }
+  }
+}
+```
+
+That's it. `uvx` handles cloning, caching, and running 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)
+
+Copy the commands into your project for workflow shortcuts:
+
+```bash
+mkdir -p .claude/commands
+cp -r /path/to/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 |
+
+## 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
+```

suitable_loop-0.1.0/pyproject.toml

@@ -0,0 +1,24 @@
+[project]
+name = "suitable-loop"
+version = "0.1.0"
+description = "Local production engineering platform — semantic code analysis, git risk scoring, and log correlation via MCP"
+requires-python = ">=3.11"
+dependencies = [
+    "mcp>=1.0.0",
+    "networkx>=3.0",
+    "gitpython>=3.1",
+    "radon>=6.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.23",
+]
+
+[project.scripts]
+suitable-loop = "suitable_loop.server:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"

suitable_loop-0.1.0/suitable_loop/__init__.py

@@ -0,0 +1,3 @@
+"""Suitable Loop — Local Production Engineering Platform."""
+
+__version__ = "0.1.0"

suitable_loop-0.1.0/suitable_loop/__main__.py

@@ -0,0 +1,5 @@
+"""Entry point for `python -m suitable_loop`."""
+
+from .server import main
+
+main()

suitable_loop-0.1.0/suitable_loop/analyzers/__init__.py

@@ -0,0 +1 @@
+"""Suitable Loop analysis engines."""