generated from McMassiveNZ/blank-slate
wilmc
a0fbb9f50e
CI / build (debug, map[compiler:appleclang os:macos-latest]) (push) Canceled after 0s
CI / build (debug, map[compiler:clang os:ubuntu-latest]) (push) Canceled after 0s
CI / build (debug, map[compiler:gcc os:ubuntu-latest]) (push) Canceled after 0s
CI / build (debug, map[compiler:msvc os:windows-latest]) (push) Canceled after 0s
CI / build (release, map[compiler:appleclang os:macos-latest]) (push) Canceled after 0s
CI / build (release, map[compiler:clang os:ubuntu-latest]) (push) Canceled after 0s
CI / build (release, map[compiler:gcc os:ubuntu-latest]) (push) Canceled after 0s
CI / build (release, map[compiler:msvc os:windows-latest]) (push) Canceled after 0s
CI / build (sanitizers, map[compiler:appleclang os:macos-latest]) (push) Canceled after 0s
CI / build (sanitizers, map[compiler:clang os:ubuntu-latest]) (push) Canceled after 0s
CI / build (sanitizers, map[compiler:gcc os:ubuntu-latest]) (push) Canceled after 0s
CI / build (sanitizers, map[compiler:msvc os:windows-latest]) (push) Canceled after 0s
- Add map, find, and around commands with repository root discovery - Stream literal ripgrep searches with match counts and result limits - Add direct subprocess execution and explicit error returns - Disable C++ exceptions and add navigation tests - Support CMake installation and document builds and deployment - Add a reusable agent skill and document skill discovery
77 lines
4.6 KiB
Markdown
77 lines
4.6 KiB
Markdown
# 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.
|