how to contribute debugging

Debugging

Most CSV Align failures fall into four buckets: frontend workflow state, transport parity, backend validation, or packaging metadata. Start by locating which runtime saw the problem.

Local web app

src/main.rs initializes tracing_subscriber from RUST_LOG and logs the resolved frontend path plus listen URL. If cargo run fails before serving, check that frontend/dist/index.html exists because src/api/app.rs requires built frontend assets.

cd frontend && npm run build
cd ..
RUST_LOG=debug cargo run

Frontend workflow issues

State changes flow through frontend/src/hooks/useComparisonWorkflow.reducer.ts. Async actions are guarded by generation and mutation tokens in frontend/src/hooks/useComparisonWorkflow.ts, frontend/src/hooks/useWorkflowComparisonActions.ts, and frontend/src/hooks/useWorkflowPersistenceActions.ts. If stale results appear after file changes or pair-order loads, inspect those tokens first.

API and validation errors

Backend errors are shaped by src/backend/error.rs into { code, error }. Request validation for comparisons lives in src/backend/validation.rs; file parsing errors often originate in src/data/csv_loader.rs; snapshot validation errors come from src/backend/persistence/v1/mod.rs.

Desktop-only issues

Tauri command registration is split across src-tauri/src/commands.rs and src-tauri/src/main.rs. If a frontend invoke does nothing, compare frontend/src/services/tauriCommands.ts with the tauri_commands! macro. Raw CSV upload metadata is sent through headers in frontend/src/services/tauri.ts and read by load_csv_bytes in src-tauri/src/commands.rs.

Packaging and release issues

Linux package metadata checks are implemented by scripts/validate_linux_deb_metadata.py and exercised by tests/linux_package_metadata_integration.rs. Release version alignment is checked by scripts/check_release_metadata.py.

More workflow details are in tooling, and runtime boundaries are in architecture.