docs: simplify developer command reference guide

2026-05-26 16:21:51 +05:30
parent 5e5404c330
commit 876c13c089
1 changed files with 61 additions and 213 deletions
@@ -1,239 +1,87 @@
-# PDF Engine — Developer Command Reference
+# Developer Command Reference
 This guide lists the exact commands each developer needs for their day-to-day workflow. All compiler environments, presets, and path configs are handled automatically under the hood by the scripts.
 ---
-## ⚠️ Windows — Activate MSVC Before Anything Else
+## 🛠️ Dev 1 — C++ Core Engine Developer
-
+Use these when writing C++ code (`engine/`), modifying PDFium layers, or changing binding structures.
 Run this once per terminal session before any `cmake` command:
 **Option A — Open a new PowerShell with MSVC loaded**
 ### 1. Build C++ Engine & Python Bindings
 Run this after changing C++ source code to update the local binaries and the Python extension:
 ```powershell
-cmd /c '"C:\Program Files (x86)\Microsoft Visual Studio\18\BuildTools\VC\Auxiliary\Build\vcvars64.bat" && powershell'
+powershell -ExecutionPolicy Bypass -File scripts/build_cpp.ps1
 ```
 *(On first execution, this will automatically generate your local `CMakeUserPresets.json` file).*
 ### 2. Run C++ Unit Tests
 Runs all C++ document, rendering, and lifecycle unit tests:
 ```powershell
 powershell -ExecutionPolicy Bypass -File scripts/test_cpp.ps1
 ```
-**Option B — Load MSVC into your current PowerShell window**
+### 3. Check PDFium API Boundary
-
+Verifies no raw `FPDF_*` calls exist outside the `engine/src/parser/` abstraction layer (Rule R2):
 ```powershell
-cmd /c '"C:\Program Files (x86)\Microsoft Visual Studio\18\BuildTools\VC\Auxiliary\Build\vcvars64.bat" && set' |
+powershell -ExecutionPolicy Bypass -File scripts/check_pdfium_boundary.ps1
  Where-Object { $_ -match '=' } |
  ForEach-Object {
    $name, $value = $_ -split '=', 2
    [System.Environment]::SetEnvironmentVariable($name, $value, 'Process')
  }
 $env:VCPKG_ROOT = "C:\Users\furqa\vcpkg"
 ```
 If you skip this step, cmake will fail with:
 `CMake Error: No CMAKE_CXX_COMPILER could be found.`
 ---
 ## One-Time Setup (new machine only)
 ```powershell
 pwsh scripts/bootstrap.ps1
 ```
 ```sh
 ./scripts/bootstrap.sh
 ```
 ---
-## Component 1 — C++ Engine
+## 🐍 Dev 3 — Backend API Developer (Python / FastAPI)
-
+Use these when writing FastAPI routes, managing Python services, or testing endpoint integrations.
 ### Configure
 Run on first setup, after adding `.cpp` files, or after changing `CMakeLists.txt`.
 ```powershell
 cmake --preset windows-debug
 ```
 ### Build
 Run after changing any C++ source file.
 ```powershell
 cmake --build --preset windows-debug
 ```
 ### Test
 ```powershell
 ctest --preset windows-debug
 ```
 Expected output: `100% tests passed`
 ### Fresh / Clean Rebuild
 Use when you see cache errors or strange Ninja errors.
 ```powershell
 cmake --preset windows-debug --fresh
 cmake --build --preset windows-debug
 ```
 ### Rule R2 Boundary Check
 Verifies no raw `FPDF_*` calls exist outside `engine/src/parser/`.
 ```powershell
 pwsh scripts/check_pdfium_boundary.ps1
 ```
 ---
 ## Component 2 — Gateway (FastAPI / Python)
 ### 1. Environment Setup (One-Time)
 Run this once to create the virtual environment and install dependencies:
 ```powershell
 cd gateway
-python -m pip install -e ".[dev]"
+python -m venv .venv
-python -m ruff check .
+.venv\Scripts\Activate.ps1
-python -m ruff format --check .
+pip install -e ".[dev]"
-python -m pytest
+cd ..
 ```
 ### 2. Start Dev Server
 Launches the FastAPI gateway locally on port `8000` (reloads automatically on file save):
 ```powershell
 powershell -ExecutionPolicy Bypass -File scripts/start_gateway.ps1
 ```
 ### 3. Run Gateway Integration Tests
 Runs all pytest integration tests checking route responses and document modifications:
 ```powershell
 powershell -ExecutionPolicy Bypass -File scripts/test_gateway.ps1
 ```
 ---
-## Component 3 — Frontend (React / TypeScript)
+## ⚛️ Dev 2 — Frontend Developer (React / WASM)
 Use these when building the React UI, annotation toolbar, and client-side WASM engine components.
 ### 1. Project Setup (One-Time)
 Run once to install Node dependencies:
 ```powershell
 cd frontend
 npm install
 cd ..
 ```
 ### 2. Build WebAssembly Module
 Compiles the C++ engine to WebAssembly, runs smoke tests, and deploys `.wasm` and `.mjs` assets directly to `frontend/public/` for local loading:
 ```powershell
 powershell -ExecutionPolicy Bypass -File scripts/build_wasm.ps1
 ```
 ### 3. Start Frontend Dev Server
 Launches the local Vite web server:
 ```powershell
 cd frontend
 npm run dev
 ```
 ### 4. Build for Production
 Validates TypeScript and generates static build files for deployment:
 ```powershell
 cd frontend
 npm run build
 npm run lint
 ```
 ---
 ## Component 4 — WASM (Emscripten)
 Activate Emscripten first (one-time install):
 ```powershell
 Get-Content wasm/emsdk.pinned
 ./emsdk install <version>
 ./emsdk activate <version>
 ./emsdk_env.ps1
 ```
 Build and test:
 ```powershell
 cmake --preset wasm
 cmake --build --preset wasm
 node wasm/hello.test.mjs
 ```
 Expected output:
 ```
 [wasm-smoke] OK — add(2,3)=5, hello_version()=1, cwrap add(40,2)=42
 ```
 Browser test (optional):
 ```powershell
 npx serve .
 ```
 Open `http://localhost:3000/test.html` and check the browser console (F12).
 ---
 ## C++ Code Style (clang-format)
 Install once (CI is pinned to 22.1.5):
 ```powershell
 pip install clang-format==22.1.5
 ```
 Check formatting:
 ```powershell
 Get-ChildItem -Recurse engine -Include *.cpp,*.cc,*.h,*.hpp |
  ForEach-Object { clang-format --dry-run --Werror $_.FullName }
 ```
 Auto-format in place:
 ```powershell
 Get-ChildItem -Recurse engine -Include *.cpp,*.cc,*.h,*.hpp |
  ForEach-Object { clang-format -i $_.FullName }
 ```
 ---
 ## Run Everything at Once
 Runs all components and prints one pass/fail per component.
 ```powershell
 pwsh scripts/test_phase0.ps1 -Preset windows-debug
 pwsh scripts/test_phase0.ps1 -Preset windows-debug -SkipWasm
 ```
 ```sh
 ./scripts/test_phase0.sh
 SKIP_WASM=1 ./scripts/test_phase0.sh
 ```
 ---
 ## Automated Convenience Scripts
 We have created several PowerShell scripts in the `scripts/` directory to automate setting up the MSVC compiler environments, building, running tests, and starting the FastAPI gateway server. You can run these from the project root:
 *   **Build C++ Engine & Python Bindings**:
    ```powershell
    powershell -ExecutionPolicy Bypass -File scripts/build_cpp.ps1
    ```
 *   **Run C++ Core Unit Tests**:
    ```powershell
    powershell -ExecutionPolicy Bypass -File scripts/test_cpp.ps1
    ```
 *   **Run Gateway pytest Integration Tests**:
    ```powershell
    powershell -ExecutionPolicy Bypass -File scripts/test_gateway.ps1
    ```
 *   **Start the Local FastAPI Dev Server**:
    ```powershell
    powershell -ExecutionPolicy Bypass -File scripts/start_gateway.ps1
    ```
 ---
 ## Quick Reference
 ```powershell
 cmake --preset windows-debug
 cmake --build --preset windows-debug
 ctest --preset windows-debug
 ```
 ```powershell
 cd gateway
 python -m pip install -e ".[dev]"
 python -m pytest
 ```
 ```powershell
 cd frontend
 npm install
 npm run dev
 ```
 ```powershell
 cmake --preset wasm
 cmake --build --preset wasm
 node wasm/hello.test.mjs
 ```
 ```powershell
 pwsh scripts/check_pdfium_boundary.ps1
 ```