# 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 C++ CLI skeleton, native compiler presets, and a sample test. Navigation implementations remain TODOs. The bookmarks below route to existing build invariants, not implemented navigation features.

## Current routes

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

### CLI parsing and dispatch skeleton
Path: `src/main.cpp`
Entry: `main`
Important symbols: `print_usage`, `extract_tool_name`, `extract_tool_arguments`
Flow: placeholder parsing -> `find`/`map` dispatch -> tool `execute`; parsing and usage remain TODOs.
Related: `src/CMakeLists.txt` lists all executable sources. `around` has a stub but is not dispatched yet.

### 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. Tool bodies remain TODOs.
Tests: no navigation behavior tests yet.

### 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/test_main.cpp` is only a sample assertion.
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.