how to contribute patterns and conventions

Patterns and conventions

The codebase keeps product logic in the Rust core, desktop access in Tauri, and interaction state in React hooks. A good change usually follows those boundaries instead of duplicating detection, selection, or file-access policy in the UI.

Layering rules

Rule	Why it matters	Source
Put anonymization behavior in the core crate.	crates/csv-anonymizer-core is reused by both the Tauri app and CLI harness.	crates/csv-anonymizer-core/src/lib.rs, crates/csv-anonymizer-app/src/cli.rs
Keep Tauri commands thin.	Commands validate desktop access, offload blocking work, and call the core service.	src-tauri/src/commands/csv.rs, src-tauri/src/commands/shared.rs
Keep React wrappers typed.	frontend/src/tauri.ts is the single frontend surface for invoking commands.	frontend/src/tauri.ts
Mirror Rust and TypeScript DTOs deliberately.	The repo uses checked manual contracts rather than generated bindings.	crates/csv-anonymizer-core/src/types.rs, frontend/src/types.ts, scripts/check-contracts.mjs
Treat release packaging as product code.	Installers, icons, Linux metadata, and signing checks are validated in CI.	scripts/check-release-metadata.mjs, .github/workflows/release.yml

Error handling

Rust core errors use AnonymizerError in crates/csv-anonymizer-core/src/error.rs. Tauri commands convert errors to strings before they cross the invoke boundary, for example in src-tauri/src/commands/csv.rs. Frontend display paths should sanitize unknown values through frontend/src/utils/errors.ts before showing them to users.

When adding a failure mode:

1. Add the source error close to the invariant it protects.
2. Preserve enough context for the UI to tell the user what to fix.
3. Avoid logging or returning source data values unless the user already supplied them in the visible UI.

Privacy-sensitive guards

Some code looks verbose because it protects privacy or data loss:

• src-tauri/src/path_access.rs canonicalizes granted input files and normalizes output files.
• src-tauri/src/commands/shared.rs validates output suffixes and confirms file access when paths are typed manually.
• crates/csv-anonymizer-core/src/csv_io.rs validates CSV inputs, handles ragged rows, and neutralizes spreadsheet formula prefixes.
• crates/csv-anonymizer-core/src/smart.rs rejects unsafe or incomplete Smart replacement responses before storing them in SmartReplacementMap.

Do not simplify these paths without adding tests for the exact invariant.

Frontend state

React workflow state is organized around hooks:

• frontend/src/hooks/useAnonymizerWorkflow.ts composes CSV workflow state.
• frontend/src/hooks/useCsvAnalysis.ts loads and analyzes the selected CSV.
• frontend/src/hooks/useColumnSelection.ts owns selected columns and strategy controls.
• frontend/src/hooks/usePreviewWorkflow.ts owns preview calls.
• frontend/src/hooks/useAnonymizeJob.ts starts and polls background jobs.
• frontend/src/hooks/usePersistentSettings.ts loads, sanitizes, and saves settings.

Prefer adding a small hook or helper near the owning workflow over expanding frontend/src/App.tsx.

Detection and transformation

Detection is staged in crates/csv-anonymizer-core/src/detection.rs: header rules and strong validators run before generic numeric/name/enum fallbacks. Transformation dispatch lives in crates/csv-anonymizer-core/src/strategies/mod.rs, while in-run consistency and reporting live in crates/csv-anonymizer-core/src/strategies/state.rs.

When changing detector behavior, update the relevant tests under crates/csv-anonymizer-core/src/detection/tests and consider the maintained taxonomy in crates/csv-anonymizer-core/src/detection/header_taxonomy.json.

Testing pattern

The root checks in package.json are the canonical gates. Unit tests live next to frontend components and Rust modules. Browser workflow and accessibility tests live under frontend/e2e, and release/package smoke tests live under scripts.

See Testing for exact commands and Tooling for release and audit scripts.