Metadata-Version: 2.3
Name: recon-lsp
Version: 0.2.0
Summary: LSP-powered code reconnaissance CLI — semantic code intelligence for AI agents and humans.
Author: atharvsp189
Author-email: atharvsp189 <atharvsp189@gmail.com>
License: MIT
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Build Tools
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Dist: multilspy>=0.0.15
Requires-Dist: typer>=0.9.0
Requires-Dist: rich>=13.0.0
Requires-Dist: toml>=0.10.2
Requires-Dist: psutil>=5.9.0
Requires-Python: >=3.10
Description-Content-Type: text/markdown

<p align="center">
  <img src="assets/recon-readme-banner-v2.png" alt="Recon Banner" width="100%" />
</p>

# Recon — LSP-Powered Code Reconnaissance

[![PyPI version](https://badge.fury.io/py/recon-lsp.svg)](https://badge.fury.io/py/recon-lsp)
[![Python Versions](https://img.shields.io/pypi/pyversions/recon-lsp.svg)](https://pypi.org/project/recon-lsp/)

**Context Engineering for your Codebase.** Semantic code intelligence CLI for AI agents and developers.

Recon turns Language Server Protocol superpowers into simple terminal commands. No IDE required. 

---

## Why Recon? (LSP vs Grep)

When autonomous AI agents navigate large codebases, reading whole files doesn't make sense. The standard fallback is `grep` or `ripgrep`. While great for text matching, text search can be incredibly noisy—analyzing many fragments without context wastes tokens, increases tool calls, and risks missing the right context.

**Enter LSP (Language Server Protocol)**
LSP builds a structural (AST) understanding of your code, powering the Intellisense in your IDE. Recon exposes all of these capabilities directly to the terminal, including:
- **Go to Definition**
- **Find References**
- **Document Symbols (Classes, Functions, Variables)**
- **Workspace Symbol Search**
- **Hover (Types, Signatures, Docstrings)**
- **Context-Aware Completions**

Recon equips AI agents with **semantic code search**. Recent benchmarks comparing **LSP vs. grep** show clear advantages for AI coding agents:

- **Exact Precision & Completeness**: Eliminate the 90%+ noise typical of text search. LSP understands scope and finds exact references that `grep` misses.
- **2–34× Less Token Usage**: Structured, symbol-aware data drastically reduces context window bloat compared to raw file chunks.
- **33% Faster & Cheaper**: Agents resolve definitions in a single tool call, cutting LLM execution time and inference costs.
- **Agent-Agnostic**: Recon is the CLI bridge. It equips ANY coding agent framework with LSP superpowers, entirely independent of an IDE.

---

## Documentation
Detailed documentation is available in the [docs](docs/) directory:
- [Introduction & Philosophy](docs/index.md)
- [Installation](docs/installation.md)
- [Usage Guide](docs/usage.md)
- [Agent Integration](docs/agent_integration.md)

---

## Installation

Recon is officially published on PyPI.

### Option 1: Install globally via `uv` or `pipx` (Recommended)
This makes `recon` accessible from anywhere in your terminal:
```bash
uv tool install recon-lsp
# or
pipx install recon-lsp
```

### Option 2: Install into active environment / venv
```bash
pip install recon-lsp
# or with uv:
uv pip install recon-lsp
```

---

## Quick Start

```bash
# 1. Interactive setup (creates .recon.toml in current repo)
recon init

# Or manually configure your workspace:
recon config --lang python --repo-path /path/to/your/repo

# 2. Check language server diagnostics & auto-install if needed:
recon setup                        # Diagnostic status overview of all 12 languages
recon setup python                 # Diagnose & verify Python LSP
recon setup php --install          # Automatically install / download LSP

# 3. Start querying your codebase:
recon symbols -f src/main.py --human
recon definition -f src/main.py -L 10 -s MyClass --context 3 --human
recon references -f src/main.py -L 10 -s MyClass --human
recon hover -f src/main.py -L 10 -s MyClass
```

---

## Commands Reference

### LSP Queries

| Command | Description |
|---|---|
| `recon definition -f <file> -L <line> -s <sym>` | Jump to symbol definition |
| `recon references -f <file> -L <line> -s <sym>` | Find all references across codebase |
| `recon hover -f <file> -L <line> -s <sym>` | Extract docstrings, type signatures, hover details |
| `recon symbols -f <file>` | List all classes, functions, variables in a file |
| `recon workspace-symbols -q <query>` | Search symbols across the entire workspace |
| `recon completions -f <file> -L <line> -s <sym>` | Get context-aware autocompletions |
| `recon batch <file.json>` | Run multiple LSP queries from a JSON file in one go |

### Setup & Configuration

| Command | Description |
|---|---|
| `recon init` | Interactive setup wizard (TUI with language picker & auto-verification) |
| `recon setup` | Real-time diagnostic table for all 12 supported languages |
| `recon setup <lang> -i` | Automatically install / download the language server |
| `recon config --lang <l>` | View or set configuration defaults |
| `recon info` | Show project info, daemon status, and config paths |

### Daemon Management & AI

| Command | Description |
|---|---|
| `recon daemon start/stop/status/restart` | Manage the background LSP daemon |
| `recon agent-skill` | Print the recon-skills reconnaissance workflow for AI agents |

*For full details and examples, view the [Usage Guide](docs/usage.md).*

---

## Output Formats

```bash
# JSON (default, ideal for AI agents and automated scripts)
recon symbols -f main.py

# Human-readable (compact file:line format with syntax-highlighted snippets)
recon symbols -f main.py --human

# Rich table (styled terminal table view)
recon symbols -f main.py --table
```

---

## Core Flags

| Flag | Short | Description |
|---|---|---|
| `--file-path` | `-f` | Relative path to the file |
| `--line` | `-L` | Line number (0-indexed) |
| `--symbol` | `-s` | Symbol name (auto-calculates column) |
| `--column` | `-c` | Column number (alternative to `--symbol`) |
| `--context <N>` | | Number of surrounding lines to fetch for matched locations |
| `--human` | `-H` | Human-readable formatted output |
| `--table` | `-T` | Rich table terminal output |

---

## Supported Languages & Tools

| Language | Language Server | Setup Support |
|---|---|---|
| **Python** | jedi-language-server | `pip install jedi-language-server` |
| **Rust** | rust-analyzer | Auto-download / `rustup component add rust-analyzer` |
| **Java** | Eclipse JDT.LS | Auto-download (Requires Java 17+) |
| **TypeScript / JS** | typescript-language-server | Auto-install via npm / multilspy |
| **Go** | gopls | `go install golang.org/x/tools/gopls@latest` |
| **Ruby** | solargraph | `gem install solargraph` |
| **C#** | OmniSharp | Auto-download (Requires .NET 6+) |
| **C / C++** | clangd | System package manager (`apt install clangd`, `brew install llvm`) |
| **Dart** | dart language-server | Built into Dart SDK / `dart pub global activate` |
| **PHP** | intelephense | Auto-install via npm |
| **Elixir** | elixir-ls | Auto-download (Requires Elixir 1.13+, Erlang 24+) |
| **Kotlin** | kotlin-language-server | Auto-download (Requires Java 11+) |

Run `recon setup` to see real-time toolchain and installation diagnostics for all languages on your system.

---

## Language Specific Notes & Troubleshooting

Since `recon` leverages real Language Servers, it expects your project to be in a buildable/analyzable state. Here are the requirements for accurate results across all supported languages:

* **Python**: Ensure third-party dependencies are installed in your active environment (`venv`, `poetry`, `uv`) so the language server can resolve external imports.
* **TypeScript / JavaScript**: You must run `npm install`, `yarn`, or `pnpm install`. The compiler cannot build an accurate AST without `node_modules` present.
* **C / C++**: You must generate a `compile_commands.json` at the root of your project (e.g., using `cmake -DCMAKE_EXPORT_COMPILE_COMMANDS=1`). Without this, `clangd` degrades into a basic, less-accurate parser.
* **Go**: Ensure the `go` binary is installed in your `PATH`. Running `go mod tidy` or `go mod download` is highly recommended before querying to resolve all external packages.
* **Rust**: Ensure your code successfully checks (`cargo check`). The `rust-analyzer` needs a valid `Cargo.toml` to index macros and dependencies properly.
* **Java**: The project must be properly configured with `pom.xml` (Maven) or `build.gradle` (Gradle). Note: The Eclipse JDT.LS backend requires Java 17+ installed on your system.
* **C#**: Requires the .NET 6+ SDK. Ensure you have restored your `.sln` or `.csproj` files (e.g., `dotnet restore`) so NuGet packages are resolved.
* **Ruby**: Run `bundle install` and `yard gems` to ensure documentation and gem dependencies are available to the `solargraph` server.
* **PHP**: Run `composer install` to download dependencies for accurate symbol resolution via `intelephense`.
* **Elixir**: Requires Elixir 1.13+ and Erlang 24+. Run `mix deps.get` to fetch dependencies for `elixir-ls`.
* **Kotlin**: Requires Java 11+. Ensure your Gradle/Maven wrappers are functional and dependencies are synced.
* **Dart**: Run `dart pub get` or `flutter pub get` to resolve packages for the built-in Dart analysis server.

---

## Contributing

Contributions to Recon are warmly welcomed! Whether you want to report an issue, improve documentation, optimize performance, or add support for additional language servers, we appreciate your help.

### Getting Started

1. **Fork and clone the repository**:
   ```bash
   git clone https://github.com/atharvsp189/recon-lsp.git
   cd recon-lsp
   ```

2. **Set up the development environment**:
   Make sure you have [uv](https://docs.astral.sh/uv/) installed.
   ```bash
   make install
   # or directly with uv:
   uv sync
   ```

3. **Run the test suite**:
   ```bash
   make test        # Run tests with coverage report
   make test-fast   # Fast run without coverage
   ```

4. **Code style & quality**:
   We use [Ruff](https://docs.astral.sh/ruff/) for linting and formatting.
   ```bash
   make lint        # Check for lint violations
   make format      # Auto-format code
   make check       # Run lint, format check, and tests
   ```

5. **Submitting changes**:
   - Create a feature branch (`git checkout -b feature/your-feature-name` or `fix/your-bug-fix`).
   - Write clear, concise commit messages.
   - Ensure all tests pass before submitting (`make test`).
   - Open a Pull Request against the `develop` branch with a clear description of your changes.

---

## License

This project is licensed under the MIT License — see the [LICENSE](LICENSE) file for details.

