Metadata-Version: 2.5
Name: errd
Version: 0.2.0
Summary: Debug with less context. Automatically capture errors or analyze tracebacks across Python, JS/TS, Java, and Go to generate minimal AI-ready context.
Project-URL: Homepage, https://github.com/reyan/errd
Project-URL: Repository, https://github.com/reyan/errd
Project-URL: Issues, https://github.com/reyan/errd/issues
Author-email: Reyan <reyan@errd.dev>
License: Apache-2.0
License-File: LICENSE
Keywords: ai,cli,context,debugging,llm,traceback
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Debuggers
Requires-Python: >=3.11
Requires-Dist: rich>=13.7.0
Requires-Dist: tiktoken>=0.7.0
Requires-Dist: tree-sitter-go>=0.23.0
Requires-Dist: tree-sitter-java>=0.23.0
Requires-Dist: tree-sitter-javascript>=0.23.0
Requires-Dist: tree-sitter-python>=0.23.0
Requires-Dist: tree-sitter-typescript>=0.23.0
Requires-Dist: tree-sitter>=0.23.0
Requires-Dist: typer>=0.12.0
Provides-Extra: dev
Requires-Dist: mypy>=1.10.0; extra == 'dev'
Requires-Dist: pytest-cov>=5.0.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: ruff>=0.5.0; extra == 'dev'
Description-Content-Type: text/markdown

# errd

**Debug with less context.**

`errd` is a local-first CLI that analyzes error logs and stack traces, finds the code most relevant to a failure, and generates a focused debugging context for AI coding assistants.

Instead of giving an AI your entire repository, `errd` extracts the code most relevant to the error.

```bash
pip install errd

# Option 1: Run your application command directly with automatic error capture
errd run -- python app.py
errd run -- npm start

# Option 2: Analyze an existing log/traceback file
errd analyze error.log
```

> **No LLM. No API key. No cloud. Your code stays local during analysis.**

---

## What's New in V0.2

- **`errd run` Automatic Error Capture**: Run commands directly (`errd run -- python app.py`, `errd run -- npm start`). Stdout/stderr pass through in real-time; on failure, `errd` automatically captures the error, discovers the repo, and creates `errd-context.md`.
- **Multi-Language Support**: Full AST parsing, symbol extraction, and stack trace parsing for **Python**, **JavaScript**, **TypeScript**, **Java**, and **Go** via Tree-sitter.
- **Framework Auto-Detection**: Heuristic detection for **FastAPI**, **Django**, **Flask**, **Express**, **Next.js**, **NestJS**, **Spring Boot**, **Gin**, **Echo**, and **net/http**.
- **Relevance & Noise Penalties**: Downranks standard libraries, external dependencies (`node_modules`, `vendor`, `site-packages`), and framework internal routing files while preserving crash-site guarantees.
- **Clipboard Support**: Copy debugging context directly with `--copy`.

---

## Installation

Requires **Python 3.11+**.

```bash
pip install errd
```

Verify:

```bash
errd --version
```

---

## The Problem

When an error occurs in a large codebase, developers often give an AI coding assistant a large portion of the repository to provide enough context.

This creates two problems:

- **Unnecessary context** — most of the repository is unrelated to the failure.
- **Context cost** — larger prompts consume more tokens and can make debugging harder by introducing irrelevant information.

The challenge isn't simply giving an AI **more code**.

It's giving it **the right code**.

---

## What errd Does

```text
Application Crash / Stack Trace (Python, JS, TS, Java, Go)
       │
       ▼
     errd
       │
       ├── Parse stack trace / diagnostics
       ├── Discover repository root
       ├── Detect application framework
       ├── Extract AST symbols (Tree-sitter)
       ├── Follow multi-language import dependencies
       ├── Rank relevant symbols & apply noise penalties
       ├── Apply token budget with structural elision
       └── Redact obvious secrets
       │
       ▼
errd-context.md
       │
       ▼
Claude / GPT / Gemini / Cursor
```

`errd` does not try to fix the bug itself.

It prepares the **smallest useful debugging context** for the AI tool you already use.

---

## Usage

### Run an Application Command (`errd run`)

Wrap any command with `errd run -- <cmd>`. `errd` preserves stdout/stderr passthrough and exit codes. If the process crashes with a supported error, `errd-context.md` is generated automatically:

```bash
# Python applications
errd run -- python app.py
errd run -- uvicorn main:app --port 8000

# Node.js / JavaScript / TypeScript
errd run -- npm start
errd run -- node dist/server.js
errd run -- npx ts-node src/index.ts

# Go applications
errd run -- go run main.go

# Java applications
errd run -- java -jar target/app.jar

# With token budget and clipboard copy
errd run --copy --budget 8000 -- python app.py
```

*Note: Clean exits (`code 0`) and user interrupts (`Ctrl+C`) never generate false debugging contexts.*

### Analyze an Existing Log File (`errd analyze`)

```bash
# Analyze a traceback file
errd analyze error.log

# Set a custom token budget
errd analyze error.log --budget 8000

# Copy context directly to system clipboard
errd analyze error.log --copy

# Specify custom output path
errd analyze error.log --output debug-context.md

# Specify repository root explicitly
errd analyze error.log --repo /path/to/my-project
```

---

## Supported Languages & Ecosystems

| Language | Extensions | Frameworks Detected | AST Engine |
|---|---|---|---|
| **Python** | `.py`, `.pyi` | FastAPI, Django, Flask | Tree-sitter |
| **JavaScript** | `.js`, `.mjs`, `.cjs`, `.jsx` | Express | Tree-sitter |
| **TypeScript** | `.ts`, `.tsx`, `.mts`, `.cts` | Next.js, NestJS, Express | Tree-sitter |
| **Java** | `.java` | Spring Boot | Tree-sitter |
| **Go** | `.go` | Gin, Echo, net/http | Tree-sitter |

---

## How It Works

### 1. Multi-Language Traceback & Error Parsing
Extracts exception types, messages, file paths, line numbers, and function names from Python tracebacks, V8/Node.js stack traces, TypeScript compiler diagnostics, Java stack traces (with chained `Caused by:` blocks), and Go panics/runtime errors.

### 2. Multi-Ecosystem Repository Discovery
Auto-detects project root using `.git`, `pyproject.toml`, `package.json`, `tsconfig.json`, `pom.xml`, `build.gradle`, and `go.mod`.

### 3. Fault-Tolerant Tree-sitter Analysis
Extracts functions, classes, interfaces, methods, and import declarations even from syntactically incomplete files.

### 4. Dependency Graph & Distance Scoring
Scores symbols based on:
- Crash site proximity (innermost user-code frame)
- Call-stack distance decay ($0.85^{\text{hop}}$)
- BFS import dependency traversal ($0.55^{\text{depth}}$)
- Git modification signals ($1.5\times$ multiplier)
- **Noise downranking**: $0.2\times$ for stdlib, $0.3\times$ for external dependencies (`node_modules`, `vendor`), $0.4\times$ for framework internal packages, with a $0.8$ crash-site floor.

### 5. Greedy Knapsack Token Budgeting
Fits the highest-ranked symbols into the requested budget. Large symbols are structurally elided (signature + docstring + `...`).

### 6. Secret Redaction
Lightweight pattern redaction for AWS keys, API tokens, JWTs, Bearer tokens, passwords, and private keys.

---

## Benchmarks

A benchmark suite is included under `benchmarks/`:

```bash
python -m benchmarks.bench_runner
python -m benchmarks.bench_runner --json
```

---

## Development

Clone and install in development mode:

```bash
git clone https://github.com/Das-R10/errd.git
cd errd
pip install -e ".[dev]"
```

Run test suite:

```bash
pytest --cov=src/errd
```

Run linter & type checker:

```bash
ruff check .
mypy --strict src/errd tests benchmarks
```

---

## License

Apache License 2.0.
