Metadata-Version: 2.4
Name: fearmap
Version: 0.3.0
Summary: Analyse git repos and produce FEARMAP.md — a plain-English map of dangerous files
Project-URL: Homepage, https://github.com/LalwaniPalash/fearmap
Project-URL: Repository, https://github.com/LalwaniPalash/fearmap
Author-email: Palash Lalwani <palashlalwani.r@gmail.com>
License: MIT
License-File: LICENSE
Keywords: ai,claude,code-analysis,developer-tools,git
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
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 :: Libraries :: Python Modules
Classifier: Topic :: Software Development :: Version Control :: Git
Requires-Python: >=3.11
Requires-Dist: anthropic>=0.40.0
Requires-Dist: pydriller>=2.5
Requires-Dist: rich>=13.0.0
Requires-Dist: typer[all]>=0.12.0
Description-Content-Type: text/markdown

# fearmap

![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)
![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue.svg)
![Version](https://img.shields.io/badge/version-0.3.0-green.svg)

Analyse any git repository and produce `FEARMAP.md` — a plain-English map of which files are dangerous to change, what breaks if you touch them, and what the original developer intended.

> **fearmap does one thing: it turns git history into understanding.**

---

## Example output

```markdown
## Load-bearing files — do not touch without a plan

| File | Heat | Coupling Partners | Confidence |
|------|------|-------------------|------------|
| `src/flask/app.py` | 90/100 | ctx.py, templating.py, sessions.py, ... | HIGH |

### `src/flask/app.py`
**Intent:** The Flask class — the WSGI application object every Flask app instantiates.
Extends sansio/app.py with the I/O layer: request context push/pop, full WSGI dispatch loop.

**Danger:** The __init_subclass__ hook silently wraps overridden methods to add or strip
the AppContext argument. A method that matches neither old nor new signature will get a
deprecation warning and may behave unexpectedly.

**Ripple:** Changes to wsgi_app or full_dispatch_request break every request the framework
handles. Changes to default_config break any app relying on implicit config defaults.
```

---

## Use inside Claude Code (recommended)

No pip install. No API key. No Python. Just type `/fearmap` inside a Claude Code session.

```bash
# Install once per repo
mkdir -p .claude/commands
curl -o .claude/commands/fearmap.md https://raw.githubusercontent.com/LalwaniPalash/fearmap/main/slash-command/fearmap.md

# Or install globally (works in all your repos)
mkdir -p ~/.claude/agents
curl -o ~/.claude/agents/fearmap.md https://raw.githubusercontent.com/LalwaniPalash/fearmap/main/agent/fearmap.md
```

Then open Claude Code and type:

```
/fearmap              # analyse entire repo
/fearmap src/         # scope to a directory (great for monorepos)
```

Claude Code mines your git history, reads your dangerous files, and writes `FEARMAP.md` directly. No external API calls — Claude Code **is** the reasoning engine.

See [slash-command/README.md](slash-command/README.md) and [agent/README.md](agent/README.md) for details.

---

## Use as a CLI tool

For automation, CI, or when you prefer a terminal workflow:

```bash
pip install fearmap
```

> ⚠ **fearmap sends file contents to the Claude API.** Use `--local` mode if your code cannot leave your machine.

### Setup

```bash
export ANTHROPIC_API_KEY=your_key_here
```

### Commands

```bash
# Analyse current repo (asks for confirmation before API calls)
fearmap run

# With options
fearmap run --scope ./src --budget 1.50 --output FEARMAP.md --yes

# Local mode — no Claude calls, metrics only (no API key needed)
fearmap run --local

# Preview — show what would be analysed and estimated cost, don't run
fearmap preview

# Deep-dive on a single file
fearmap explain path/to/file.py

# Show coupling partners for a file
fearmap couples path/to/file.py

# Validate your fearmap.toml
fearmap config check
```

---

## What you get

`FEARMAP.md` contains:

1. **Onboarding path** — the 7 best files to read if you're new to the codebase
2. **Load-bearing files** — files that must not be touched without a plan, with intent/danger/ripple analysis
3. **Risky files** — files that need careful handling
4. **Dead files** — candidates for removal (with a warning to verify no external callers)
5. **Safe files** — the ones you can change with confidence
6. **Coupling map** — which files always change together and why

### Classifications

| Classification | Meaning |
|---|---|
| `LOAD-BEARING` | Heat ≥ 70 AND 3+ coupling partners. If this breaks, a lot breaks. |
| `RISKY` | Heat ≥ 40 OR 2+ coupling partners. Change with care. |
| `DEAD` | No changes in 18+ months, no callers detected. Probably removable. |
| `SAFE` | Everything else. Change freely. |

### Heat score formula

```
heat = churn × 0.40 + coupling × 0.35 + authors × 0.15 + size × 0.10
```

All components are min-max normalised across the repo, giving a 0–100 score.

---

## Configuration

### fearmap.toml

```toml
[fearmap]
months = 12              # git history window
budget = 2.00            # max API spend per run (CLI only)
model = "claude-sonnet-4-20250514"
output = "FEARMAP.md"
scope = "."              # great for monorepos: set to "src/myservice"

[thresholds]
load_bearing_heat = 70
load_bearing_coupling = 3
risky_heat = 40
dead_months = 18
```

fearmap searches for `fearmap.toml` starting at the current directory and walking up to the git root. This lets monorepos have per-service configs.

### .fearmapignore

```
**/generated/**
**/migrations/**
**/*.lock
```

---

## Why fearmap, not [existing tool]?

| Tool | What it does | What it lacks |
|---|---|---|
| CodeScene | Churn metrics, coupling charts | Paid, cloud, no plain-English explanations |
| code-maat | Same methodology | Requires JVM, no explanations |
| wily | Python complexity trends | Python only, no coupling, no explanations |
| GitStats | Commit statistics | No per-file danger analysis |

**fearmap** is the only tool that reads your actual code and explains, in plain English, *why* a file is dangerous and *what will break* if you touch it.

---

## Privacy

The CLI (`fearmap run`) sends file contents to the Anthropic API. Use `--local` mode if your code cannot leave your machine:

```bash
fearmap run --local
```

Local mode produces a metrics-only `FEARMAP.md` with classifications but no intent/danger explanations.

Mode 2 (Claude Code native) makes no external API calls beyond your normal Claude Code session.

---

## Commit FEARMAP.md

`FEARMAP.md` is meant to be committed and versioned alongside your code. It's documentation, not a build artifact. It helps every engineer who clones your repo understand which files to fear.

---

## Contributing

See [docs/contributing.md](docs/contributing.md).

---

## License

MIT — see [LICENSE](LICENSE).
