Skip to content

Building from Source

vibecoder880 edited this page Nov 19, 2026 · 1 revision

Building from Source

DiffLens builds as a standard Tauri 2 workspace: a Rust workspace with the core/ library and src-tauri/ shell, plus a Vite/React frontend at the repo root.

Prerequisites

  • Rust via rustup — stable channel. The MSRV is 1.88 (enforced by the workspace rust-version; a current stable is fine).
  • Node.js 24 + npm (CI uses Node 24).
  • Linux only: the Tauri system libraries — the same line CI uses (Ubuntu 24.04):
sudo apt-get update && sudo apt-get install -y \
  libwebkit2gtk-4.1-dev build-essential curl wget file libxdo-dev \
  libssl-dev libayatana-appindicator3-dev librsvg2-dev pkg-config

Add tesseract-ocr tesseract-ocr-vie if you want the OCR integration tests to run locally (they are #[ignore]d without it).

Build and run

git clone https://github.com/vibecoder880/difflens
cd difflens
npm ci             # frontend deps + @tauri-apps/cli

npm run tauri dev  # desktop app with hot reload
npm run tauri build # full release bundle (per-OS installers)

Note: npm run dev/test/build each run scripts/export-labels.mjs first — it exports the core's i18n label keys so the frontend parity tests compare against the live backend list, not a stale copy.

Feature flags

  • embeddings-ort (off by default): compiles the real ONNX e5 embedder (ort downloads prebuilt ONNX Runtime at build time). With the feature on but model files absent, the pipeline logs a warning and falls back to the deterministic fake hash embedder — this keeps cargo test hermetic. The choice is surfaced honestly via DiffResult::embeddings_used and the UI's embeddings indicator.
  • Model fetch scripts: scripts/fetch-models.sh (--test for the CI-sized e5 model, --bundle for release resources) and scripts/fetch-pdfium.sh stage the pinned PDFium build. CI sets DIFFLENS_PDFIUM_PATH + DIFFLENS_PDFIUM_STRICT=1 so PDF tests must run, not silently skip.

Test suites

cargo fmt --check -p difflens-core                        # formatting gate
cargo clippy -p difflens-core --all-targets -- -D warnings # lints gate (CI: with and without features)
cargo test -p difflens-core                               # core suite (fake embedder)
npm test                                                  # vitest + EN/VI i18n parity
npm run build                                             # tsc -b && vite build
scripts/audit-egress.sh                                   # egress invariant

Test tiers, all exercised in CI:

Tier What Locally
Core unit + integration ~241 unit + ~53 integration #[test] fns (extraction, alignment, deltas, download/ archive red-team suites, store, report escaping goldens) runs
Gold alignment gates precision ≥ 0.85 / recall ≥ 0.80 over the gold corpus (core/tests/gold/) runs (fake embedder in default tier)
PDF extraction real pinned PDFium (fetch-pdfium.sh, DIFFLENS_PDFIUM_STRICT=1) #[ignore]d without PDFium
Real e5 embeddings embeddings-ort feature + ONNX model #[ignore]d
OCR e2e real tesseract + vie (ocr-ci-ok assertion) #[ignore]d
LLM roundtrip pinned llama-server + Qwen3-0.6B GGUF through the download manager (llm_real_roundtrip) #[ignore]d
Frontend vitest (52 cases: filters, row building, formatting, EN/VI parity vs backend label keys) + typecheck/build runs

"Assert tests actually ran" greps in CI (e.g. pdf-extraction-ok, ocr-ci-ok) defeat silent skipping.

Project structure

See Architecture for the annotated tree and the Tauri command/event surface table.

Disk notes

A Tauri/Rust target/ directory routinely grows to 10–20 GB across debug/release and feature combinations. On smaller machines: build one platform locally (release/3-OS builds belong in CI anyway), use cargo clean between long gaps, or relocate CARGO_TARGET_DIR. The ort feature adds a one-time ~100–300 MB build-time download of ONNX Runtime binaries.

Conventions

  • Conventional Commits (feat:, fix:, docs:, …) — see CONTRIBUTING.md.
  • The egress rule: any new network code must live in core/src/download/ and pass scripts/audit-egress.sh; PRs that break the invariant will not merge.
  • Keep UI strings in both src/i18n/en.json and src/i18n/vi.json — the parity test fails otherwise.
  • LLM code paths must never alter diff results or severity bands.

Clone this wiki locally