Metadata-Version: 2.1
Name: repo-map
Version: 0.8.1
Summary: Generate a comprehensive summary and visualization of a repository structure, enhanced with AI-powered descriptions and developer considerations.
License: Apache-2.0
Author: Cyanheads
Author-email: casey@caseyjhand.com
Requires-Python: >=3.12,<4.0
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Dist: aiohttp (>=3.13.3,<4.0.0)
Requires-Dist: certifi (>=2026.2.25,<2027.0.0)
Requires-Dist: pathspec (>=1.0.4,<2.0.0)
Requires-Dist: pydantic (>=2.12.5,<3.0.0)
Requires-Dist: pydantic-settings (>=2.13.1,<3.0.0)
Requires-Dist: tqdm (>=4.67.3,<5.0.0)
Project-URL: Homepage, https://github.com/cyanheads/repo-map
Description-Content-Type: text/markdown

<div align="center">
  <h1>repo-map</h1>
  <p>
    <a href="https://pypi.org/project/repo-map/"><img src="https://img.shields.io/pypi/v/repo-map.svg" alt="PyPI version"></a>
    <a href="https://pypi.org/project/repo-map/"><img src="https://img.shields.io/pypi/pyversions/repo-map.svg" alt="Python versions"></a>
    <a href="https://pypi.org/project/repo-map/"><img src="https://img.shields.io/pypi/l/repo-map.svg" alt="PyPI license"></a>
    <a href="https://pypi.org/project/repo-map/"><img src="https://img.shields.io/pypi/dm/repo-map.svg" alt="PyPI downloads"></a>
  </p>
  <p>Generate a repository tree with AI-authored file summaries and maintenance notes.</p>
</div>

repo-map scans a repository, extracts structural metadata, and asks an OpenRouter model to document eligible files. It writes a Markdown tree at the repository root and stores results in SQLite so unchanged files do not need another API call.

## Features

- Markdown and console repository trees
- Python AST extraction plus lightweight Java, JavaScript, TypeScript, and C# structure parsing
- Structured descriptions, developer considerations, maintenance flags, dependency notes, architectural roles, refactoring suggestions, and security assessments
- Root `.gitignore` support plus built-in exclusions for caches, dependencies, build output, and repo-map artifacts
- SHA-256-based SQLite cache for unchanged files

See [`examples/example.md`](examples/example.md) for a full sample report.

## Install

Install the published CLI with [uv](https://docs.astral.sh/uv/):

```bash
uv tool install repo-map
```

For development, clone the repository and install its Poetry environment:

```bash
git clone https://github.com/cyanheads/repo-map.git
cd repo-map
poetry install
```

repo-map requires Python 3.12 or newer.

## Configure

Set an [OpenRouter](https://openrouter.ai/) API key in the environment or a project-root `.env` file:

```bash
export OPENROUTER_API_KEY=your_api_key_here
```

Optional environment variables:

| Variable | Default | Purpose |
|:---|:---|:---|
| `OPENROUTER_MODEL_NAME` | `anthropic/claude-sonnet-4.6` | OpenRouter model |
| `API_SEMAPHORE_LIMIT` | `3` | Maximum concurrent API calls |

repo-map sends repository paths, languages, imports, symbols, and existing descriptions to OpenRouter. Review the target repository and its ignore rules before approving a run. Do not analyze secrets or source you are not authorized to disclose.

## Use

With the published tool installed:

```bash
repo-map /path/to/repository
```

From a source checkout:

```bash
poetry run repo-map /path/to/repository
```

Options:

| Option | Purpose |
|:---|:---|
| `-y`, `--yes` | Skip the disclosure confirmation |
| `--model MODEL` | Override `OPENROUTER_MODEL_NAME` |
| `--concurrency INT` | Override `API_SEMAPHORE_LIMIT` |

Examples:

```bash
poetry run repo-map /path/to/repository --model anthropic/claude-sonnet-4.6
poetry run repo-map /path/to/repository --concurrency 3 -y
```

Each run creates these files inside the target repository:

- `<repository>_repo_map.md`: generated Markdown report
- `.repo-map-cache.db`: source hashes and cached LLM metadata
- `.repo_map_structure.json`: pre-enhancement structural data

Add them to the target repository's ignore rules if needed. Delete `.repo-map-cache.db` to force a complete reprocessing pass.

## How it works

1. Load built-in exclusions and the target repository's root `.gitignore`.
2. Walk the directory tree and extract supported structural metadata.
3. Compare file hashes with the SQLite cache.
4. Request structured JSON metadata from OpenRouter for eligible changed files.
5. Update the cache and write the console, JSON, and Markdown outputs.

## Development

Run the local gate and build both distribution artifacts before submitting a change:

```bash
poetry run python scripts.py check
poetry build
```

Focused commands:

```bash
poetry run python scripts.py format
poetry run python scripts.py lint
poetry run python scripts.py test
poetry run python scripts.py list-skills
```

Project workflows live under [`skills/`](skills/). Bugs and feature requests use the forms on the [issues page](https://github.com/cyanheads/repo-map/issues).

## License

Apache-2.0. See [`LICENSE`](LICENSE).

