CodeInspector/AGENTS.md

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.