wilmc
a0fbb9f50e
- 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
4.6 KiB
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):
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.