# Project map

This is a routing table: **where should an agent look?** It is not an architecture manual. Start here, then inspect only the source or documentation relevant to the task.

The repository contains a functional C++ CLI with bounded `map`, `find`, and `around` commands, native compiler presets, and navigation tests. The bookmarks below route to existing build invariants, not implemented navigation features.

## Current routes

### Purpose and direction
Path: `README.md`
Entry: project purpose, scope, implemented CLI, and measurement goals.
Related: `AGENTS.md` for agent operating instructions.

### CLI parsing and dispatch
Path: `src/main.cpp`
Entry: `main`
Important symbols: `print_usage`
Flow: argv views -> `find`/`map`/`around` dispatch -> tool `execute`.
Related: `src/CMakeLists.txt` lists all executable sources.

### Tool interface and implementations
Path: `include/repo_tool_*.hpp`, `src/repo_tool_*.cpp`
Entry: `include/repo_tool_interface.hpp`
Important symbols: `rl::IRepoLensTool`, `rl::exit_code`, `rl::RepoLensToolFind`, `rl::RepoLensToolMap`, `rl::RepoLensToolAround`
Related: `AGENTS.md` for trailing return types and the `[[nodiscard]]`/`noexcept` execution contract.
Tests: `test/navigation_test.cpp` covers parsing, ranges, map ranking/limits, and subprocess/search behavior.

### Repository navigation and subprocess support
Path: `include/navigation.hpp`, `src/navigation.cpp`, `include/process.hpp`, `src/process.cpp`
Entry: `rl::repository_root`, `rl::parse_location`, `rl::map_sections`, `rl::run_process`
Flow: discover nearest `.git` ancestor -> query root-relative map/source or stream ripgrep output.
Related: `src/repo_tool_find.cpp` limits occurrence locations; `src/repo_tool_around.cpp` reads the requested window; `src/repo_tool_map.cpp` queries map sections.
Tests: `test/navigation_test.cpp` uses temporary repositories and a subprocess fixture in `test/test_main.cpp`.

### Native build and compiler settings
Path: `CMakeLists.txt`, `CMakePresets.json`, `cmake/`, `src/CMakeLists.txt`
Entry: `CMakePresets.json` for matching configure/build/test presets; `cmake/toolchains/` for GCC, Clang, AppleClang, and MSVC selection.
Important symbols: `target_enable_warnings`, `target_warnings_as_errors`, `target_enable_sanitizers`
Related: `cmake/compilerwarnings.cmake` for diagnostics; `cmake/sanitizers.cmake` for capability checks and target settings; `cmake/staticanalysis.cmake` is an inherited Visual Studio generator helper.
Bookmarks: `OPTIONAL_TEST_DEPENDENCY_BOUNDARY` in root `CMakeLists.txt` separates the offline application build from test dependencies.
Ignore normally: generated `build/` and `.build/` trees; build helpers unless the task concerns tooling. Use the selected build's `compile_commands.json` when compilation context is needed.

### Test dependencies and validation
Path: `test/`, `cmake/gtest.cmake`
Entry: `test/CMakeLists.txt`; `test/navigation_test.cpp` contains navigation tests; `test/test_main.cpp` supplies the test runner and subprocess fixture.
Flow: `ENABLE_TESTS` -> FetchContent GoogleTest -> `repo-lens-test` -> CTest discovery.
Bookmarks: `MSVC_SANITIZER_ANNOTATION_ALIGNMENT` in `test/CMakeLists.txt` keeps STL annotations consistent across the instrumented test and its dependencies.
Related: `<compiler>-sanitizers` presets; `README.md` for local dependency overrides and build instructions.

### CI and formatting
Path: `.github/workflows/`, `.clang-format`, `.clang-tidy`
Entry: `.github/workflows/ci.yml` configures/builds/tests Debug, Release, and sanitizer presets on native hosts.
Related: `.github/workflows/auto-clang-format.yml` is inherited formatting automation; `.clang-tidy` is configuration, not evidence that analysis runs with Ninja.
Ignore normally: workflows unless the task concerns validation or automation.

## Maintaining the map

Update routes when actual source structure or useful entry points materially change. Add only existing areas; do not predeclare hypothetical subsystems. Keep entries short and omit fields that add no routing value.

Suggested entry shape (fields are optional):

```text
Subsystem
Path:
Entry:
Important symbols:
Flow:
Tests:
Bookmarks:
Related:
Ignore normally:
```

Use `Flow` for a short sequence of entry points, not an implementation explanation. List bookmarks only for stable semantic or architectural locations where ordinary searchable symbols are insufficient.

Locate bookmark declarations cheaply with `rg -n '@ai-bookmark' CMakeLists.txt test cmake src include`, then inspect a bounded range around the relevant marker. repo-lens bookmark commands are not implemented yet. Prefer symbols for ordinary functions and classes.