49 lines
3.6 KiB
Markdown
49 lines
3.6 KiB
Markdown
# CodeInspector Development Guidelines & Project Invariants
|
|
|
|
## 1. Build System & Architecture (RAD Debugger Style)
|
|
- **Zero CMake**: Do not add CMake or CMake-generated project files.
|
|
- **Unity Build**: All source modules in `src/` must be included into a unified translation unit (`src/main.cpp`). Keep compilation times sub-second to 2 seconds.
|
|
- **Build Script (`build.bat`)**:
|
|
- Auto-detects Visual Studio installations using `vswhere.exe` and calls `vcvars64.bat` if `cl.exe` is not in `%PATH%`.
|
|
- Caches precompiled vendor objects (`vendor_imgui.obj`, `rlImGui.obj`) in `build/` to maximize iteration speed.
|
|
- Supports `debug`, `release`, `run`, and `clean` modes.
|
|
|
|
## 2. MSVC Output Routing Invariant (Zero Root Pollution)
|
|
Whenever compiling with MSVC (`cl.exe`) in `build.bat`:
|
|
- Always route **all** outputs strictly into the `build/` directory:
|
|
- Object files: `/Fo:"build\"` or `/Fo:"build\<name>.obj"`
|
|
- Compiler PDBs: `/Fd:"build\"`
|
|
- Binaries: `/Fe:"build\<name>.exe"`
|
|
- Linker PDBs: `/link /PDB:"build\<name>.pdb"`
|
|
- Never let `cl.exe` drop `vc*.pdb`, `*.obj`, `*.lib`, or `*.exp` into the project root.
|
|
- Keep `imgui.ini` and compiler intermediates ignored in `.gitignore`.
|
|
|
|
## 3. General-Purpose Clang AST Execution Engine (Inspect ANY Code)
|
|
- **No DLL Compilation / No Subprocess Execution**: Never invoke external compilers (`cl.exe`) at runtime to load code as DLLs.
|
|
- **No Ad-Hoc Token Regexes**: Never use pattern matching or token scanning to guess function behavior.
|
|
- **Recursive AST Evaluation**:
|
|
- All code inspection, evaluation, and call tracing are driven directly by the `libclang` AST tree (`CXCursor`).
|
|
- The AST interpreter (`Runner`) must support standard C constructs:
|
|
- Control flow: `IfStmt`, `CompoundStmt`, `WhileStmt`, `ForStmt`, `ReturnStmt`.
|
|
- Expressions: `ConditionalOperator` (ternary `? :`), `BinaryOperator` (comparison, arithmetic, bitwise, assignment), `UnaryOperator` (`-`, `!`, `~`, `++`, `--`).
|
|
- Values: `IntegerLiteral`, `CharacterLiteral`, `FloatingLiteral`, `DeclRefExpr`, `VarDecl`.
|
|
- Every function invocation (`CallExpr`) records a `TraceFrame` capturing timestamps, arguments, return values, depth, and child calls for the flamegraph and call tree.
|
|
- Recursion and loop guard limits (e.g. max depth 60, max calls 50,000) must protect against infinite execution.
|
|
|
|
## 4. Working Directory & Path Safety
|
|
- On startup, the application must immediately call `ensure_project_root()` to detect if it was launched from `build/` or an external shortcut, resetting `std::filesystem::current_path` to the repository root.
|
|
- Always load existing files from disk on launch. Never overwrite the user's buffer with hardcoded sample strings.
|
|
- Always ensure parent directories exist (`std::filesystem::create_directories`) before saving or creating files.
|
|
|
|
## 5. Live Synchronization Architecture
|
|
- `SourceManager` maintains a monotonic `revision_` counter incremented upon every AST reparse, load, edit, or save.
|
|
- UI panels observe `revision_` and re-evaluate parameters and flamegraphs automatically live as the user types.
|
|
|
|
## 6. UI Ergonomics & Clipboard Export
|
|
- Log and console panels must always support easy copying:
|
|
- Provide a "Copy All Logs" button using `ImGui::SetClipboardText`.
|
|
- Provide right-click context menus (`Copy Line`, `Copy Message Only`).
|
|
- Provide a "Raw Text (Selectable)" tab with mouse selection and native `Ctrl+C`.
|
|
- **AST Debug Export**:
|
|
- Provide a one-click "Copy AST & Debug Dump to Clipboard" button in the inspector, in the AST Explorer view, and via global shortcut `Ctrl+D` (`export_ast_dump`) to facilitate instant debugging in pair-programming workflows.
|