How cyanheads/repo-map works
1. Project shape
- repo-map is a Python CLI package that analyzes a target repository and produces a Markdown “map” of its structure and files.
- The architecture is pipeline-oriented: discover files, parse them, enrich findings with an LLM, cache results, then render a report.
2. Entry points and command handling
- src/repo_map/main.py is the top-level entry point.
- cli_handler.py likely owns argument parsing, prompt/disclaimer flow, and wiring of CLI options such as target path, model selection, concurrency, and confirmation flags.
3. Repository discovery boundary
- file_scanner.py is the local filesystem boundary.
- It walks the repository tree, applies ignore rules, and determines which files and directories should be included in the analysis.
- The README emphasizes respect for the root .gitignore plus default ignore patterns, so scanning is intentionally selective rather than exhaustive.
4. Code understanding layer
- code_parser.py is the static-analysis layer.
- It extracts structural signals from source files such as imports, classes, functions, and possibly language-specific cues across Python and other supported languages.
- This layer turns raw file contents into a normalized representation suitable for downstream summarization.
5. LLM enrichment boundary
- llm_service.py is the external-service integration boundary.
- It talks to OpenRouter for model-backed descriptions, developer considerations, and other narrative metadata.
- The README indicates an API key environment variable and model selection, so this subsystem is the main network dependency and the most failure-prone external boundary.
6. Caching and incremental behavior
- cache_manager.py provides the persistence layer for incremental runs.
- The project uses SQLite to avoid reprocessing unchanged files, which is a key architectural optimization.
- This makes the tool suitable for repeated use on evolving repositories and reduces LLM/API cost.
7. Report assembly
- report_generator.py is the output composition layer.
- It combines scanned structure, parsed metadata, and LLM-generated annotations into the final Markdown repository map.
- The report appears tree-like, with per-file summaries and assessments embedded beneath each path.
8. Shared domain model
- models.py likely defines the data contracts passed between subsystems: file metadata, parsed code summaries, cache entries, report sections, and LLM output.
- This is the main internal boundary that keeps scanning, parsing, caching, and rendering decoupled.
9. Configuration and operational concerns
- config.py centralizes runtime settings such as defaults for ignore patterns, model choice, concurrency, and environment-based configuration.
- logging_utils.py handles operational visibility across the pipeline, which matters because the tool spans filesystem traversal, parsing, caching, and network calls.
10. Execution flow
- The end-to-end flow is: CLI input → repository scan → file parsing → cache lookup/update → LLM enrichment for selected items → Markdown report generation.
- The cache likely short-circuits unchanged files, while concurrency is used around API-bound enrichment work.
11. Technology stack and packaging
- This is a typed Python package (src/ layout with py.typed) managed with Poetry, as shown by pyproject.toml and the docs.
- The repo also includes examples and documentation, but they are supporting artifacts rather than runtime subsystems.
12. Architectural summary
- The core design separates local analysis from remote intelligence: filesystem scanning and parsing stay local, while narrative enrichment is delegated to OpenRouter.
- The result is a modular, incremental pipeline that produces a human-readable Markdown artifact from a source repository.
Main entry points: main.py Main · models.py Models · code_parser.py Parser · cli_handler.py CLI
Components 15
Core pipeline
CLI entrypoint and the local-analysis-to-report pipeline.
- Main · Top-level CLI entry that starts the repo mapping run.
src/repo_map/main.py - CLI · Parses options and wires user input into the pipeline.
src/repo_map/cli_handler.py - Scanner · Walks the target repo and applies ignore rules to select files.
src/repo_map/file_scanner.py - Parser · Extracts structural signals such as imports, classes, and functions.
src/repo_map/code_parser.py - Cache · Persists analysis results to skip unchanged files on later runs.
src/repo_map/cache_manager.py - LLM · Fetches narrative metadata and descriptions from the remote model API.
src/repo_map/llm_service.py - Report · Combines scan, parse, cache, and LLM outputs into the final map.
src/repo_map/report_generator.py - Models · Shared data contracts passed between scanning, parsing, caching, and rendering.
src/repo_map/models.py - Config · Centralizes defaults and environment-driven configuration.
src/repo_map/config.py - Logging · Provides logging setup and operational visibility across the pipeline.
src/repo_map/logging_utils.py
Support
Packaging, docs, examples, and auxiliary project files.
- Pyproject · Poetry-managed project metadata and dependency definition.
pyproject.toml - README · Primary user-facing overview of usage and behavior.
README.md - Docs · Supplementary documentation and cheatsheets.
docs/poetry_cheatsheet.md - Example · Example repository map output used to illustrate the tool.
examples/example.md - Scripts · Auxiliary project-level scripting utilities.
scripts.py
Connections 20
- Main → CLI: invokes · Main hands execution to CLI handling.
- CLI → Config: loads · CLI resolves runtime settings and defaults.
- CLI → Scanner: starts · CLI triggers repository discovery.
- Scanner → Models: emits · Scanner produces normalized file metadata.
- Scanner → Parser: feeds · Selected files flow into parsing.
- Parser → Models: normalizes · Parser turns source structure into shared contracts.
- Parser → Cache: checks · Parser work is skipped or reused via cache state.
- Cache → Models: stores · Cache persists analysis records in a shared schema.
- Parser → LLM: enriches · Parsed files can be sent for model-backed description.
- LLM → Config: uses · LLM client reads API and model configuration.
- LLM → Models: returns · LLM responses are mapped into internal data objects.
- Main → Report: orchestrates · Main coordinates final report assembly.
- Report → Models: consumes · Renderer reads scan, parse, cache, and LLM results.
- Report → Logging: logs · Report generation emits operational messages.
- Main → Logging: initializes · Startup configures logging for the whole run.
- Pyproject → Main: packages · Project metadata defines the typed Python package layout.
- README → CLI: documents · README explains CLI usage and the analysis flow.
- Docs → Pyproject: supports · Documentation includes Poetry-related guidance.
- Example → Report: illustrates · Example output shows the shape of generated maps.
- Scripts → Main: assists · Auxiliary scripts support running or maintaining the tool.