primitives comparison results

Comparison results

Active contributors: Douwe de Vries

Purpose

Comparison results describe how each matched, unmatched, ignored, or duplicate row group was classified. The backend emits RowComparisonResult values, summarizes them with ComparisonSummary, and converts them into API response DTOs consumed by the frontend result table and exporters.

See also comparison config, results and export, and comparison engine.

Directory layout

Area	Source paths
Result primitives	/Users/vriesd/projects/csv-align/src/data/types.rs
Engine result generation and summary	/Users/vriesd/projects/csv-align/src/comparison/engine.rs
Value differences	/Users/vriesd/projects/csv-align/src/comparison/value_compare.rs
Response DTOs and conversions	/Users/vriesd/projects/csv-align/src/presentation/responses.rs
Frontend API types	/Users/vriesd/projects/csv-align/frontend/src/types/api.ts
Result presentation	/Users/vriesd/projects/csv-align/frontend/src/features/results/presentation.ts
CSV export	/Users/vriesd/projects/csv-align/src/data/export.rs

Key abstractions

• RowComparisonResult is the backend enum for each result row group.
• ResultType is the serializable result-type enum exposed to API clients.
• ValueDifference records a differing File A column/value and File B column/value.
• ComparisonSummary stores total rows and result counters.
• ResultResponse is the response DTO for one result row.
• SummaryResponse is the response DTO for summary counts.
• CompareResponse wraps success, results, and summary.

How it works

1. The comparison engine splits rows by selected key.
2. Unusable keys become unkeyed results before keyed matching.
3. Exact or flexible matching pairs key groups across File A and File B.
4. Single-row paired groups compare selected values and produce match or mismatch.
5. Unmatched File A groups produce missing-right results.
6. Unmatched File B groups produce missing-left results.
7. Duplicate key groups produce one duplicate result and do not also emit a match or mismatch for the same key.
8. generate_summary counts result categories and keeps total source row counts.
9. /Users/vriesd/projects/csv-align/src/presentation/responses.rs converts results into API DTOs.

Result types

Backend result	API result type	User-facing meaning
Match	match	A paired row has no value differences after normalization.
Mismatch	mismatch	A paired row has one or more ValueDifference entries.
MissingLeft	missing_left	The selected key exists only in File B.
MissingRight	missing_right	The selected key exists only in File A.
UnkeyedLeft	unkeyed_left	A File B row was ignored because its selected key normalized to missing.
UnkeyedRight	unkeyed_right	A File A row was ignored because its selected key normalized to missing.
Duplicate	duplicate_file_a, duplicate_file_b, or duplicate_both	One or both files contain multiple rows with the same selected key.

For paired results, the engine uses File A's display key as the canonical result key. This preserves stable output when flexible matching pairs different key shapes.

Summary

ComparisonSummary contains:

• total_rows_a,
• total_rows_b,
• matches,
• mismatches,
• missing_left,
• missing_right,
• unkeyed_left,
• unkeyed_right,
• duplicates_a,
• duplicates_b.

Duplicate results are counted by duplicate source. A duplicate that occurs on both sides increments both duplicate counters.

Response DTOs

ResultResponse includes:

• result_type,
• key,
• values_a,
• values_b,
• duplicate_values_a,
• duplicate_values_b,
• differences.

For non-duplicate rows, values_a and values_b contain the display values for the selected comparison columns. For duplicate rows, duplicate_values_a and duplicate_values_b contain row sets for each duplicated side, while the flat values fall back to the first duplicate row for display helpers.

DifferenceResponse mirrors ValueDifference with column_a, column_b, value_a, and value_b.

Integration points

• Results and export builds filters, search text, summaries, detail panels, CSV export, and HTML export from ResultResponse and SummaryResponse.
• Saved work persists result DTO-compatible shapes inside comparison snapshots.
• Comparison config provides selected column labels and mappings used to compute differences.
• Flexible row-key matching can produce paired results where File A and File B keys differ.
• API exposes CompareResponse to both browser and desktop callers.

Entry points for modification

• Change result enum variants or helper methods in /Users/vriesd/projects/csv-align/src/data/types.rs.
• Change row classification in /Users/vriesd/projects/csv-align/src/comparison/engine.rs.
• Change value-difference detection in /Users/vriesd/projects/csv-align/src/comparison/value_compare.rs.
• Change response shapes in /Users/vriesd/projects/csv-align/src/presentation/responses.rs.
• Change frontend result contract types in /Users/vriesd/projects/csv-align/frontend/src/types/api.ts.
• Change result rendering in /Users/vriesd/projects/csv-align/frontend/src/features/results/presentation.ts.

Key source files

File	Purpose
/Users/vriesd/projects/csv-align/src/data/types.rs	Defines result enums, differences, duplicate source, and summary structs.
/Users/vriesd/projects/csv-align/src/comparison/engine.rs	Emits result variants, handles duplicates/unkeyed rows, and generates summaries.
/Users/vriesd/projects/csv-align/src/comparison/value_compare.rs	Computes normalized value differences.
/Users/vriesd/projects/csv-align/src/presentation/responses.rs	Converts backend results and summaries into API DTOs.
/Users/vriesd/projects/csv-align/frontend/src/types/api.ts	Defines frontend CompareResultType, ResultResponse, SummaryResponse, and CompareResponse.
/Users/vriesd/projects/csv-align/frontend/src/features/results/presentation.ts	Converts DTOs into UI view models.