# 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.