csvops 0.3.0.alpha → 0.4.0.alpha

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9663c50901b31a8073c4a5a0524e9e30c81c20bbe1b736af71649e60a7150a0e
-  data.tar.gz: a622dad35eb52afeded279726d2575db0cd210c8ed4aa07650506bfd2e2b6de5
+  metadata.gz: 9c5a0c00272c2d10751b234384ac50ee8caa90681860906419ccdec7a6e3c110
+  data.tar.gz: 849d377bec9acd507c0fd37a75e823bb9458295e12a31a5000b9ba599084092d
 SHA512:
-  metadata.gz: 28726bb66d05881caead074ce529d79db5424b85a7552f8b56cca44e891b3bb0c34cd850ff22351d6d93a5ef725e3891ccc8b7ac7e1e62d24d4e4c4d7d9b344d
-  data.tar.gz: 0fb96011d8737fb757b30e6226b9086453aa3ef6e5def1e95b77bb8bdbd414e25b72adfe6a8e65ee0498bbb88f2a809777a0d2405057689d00b3858c73014b93
+  metadata.gz: ba96ce18b4e6d2fd8eb018f406c17e7b810010a788a6be1acb51a714b87dad614d822edb97f780e2c745e257bbc68c89266427876fcc4b3fee57fadb29232630
+  data.tar.gz: 378c4a47b96cf210b28f689d9ef0aa1056c95777d3128d4044d8462cf802eeb53ca148062f4244182105e4b760bbf7dcf48d19705f69f18dfb78e3fc2e935413

data/README.md

@@ -35,11 +35,13 @@ bundle exec csvtool menu
 CSV Tool Menu
 1. Extract column
 2. Extract rows (range)
-3. Exit
+3. Randomize rows
+4. Dedupe using another CSV
+5. Exit
 >
 ```
 
-Select `1` to run extraction.
+Select `1` for column extraction, `2` for row-range extraction, `3` for row randomization, or `4` for cross-CSV dedupe.
 
 ### 3. Follow prompts
 
@@ -111,6 +113,53 @@ With Bundler:
 bundle exec csvtool column /path/to/file.csv column_name
 ```
 
+### 7. Dedupe interaction example
+
+Legend: ` ` = prompt/menu, `+` = user input, `-` = tool output
+
+```diff
+ CSV Tool Menu
+ 1. Extract column
+ 2. Extract rows (range)
+ 3. Randomize rows
+ 4. Dedupe using another CSV
+ 5. Exit
++> 4
+ CSV file path: /tmp/source.csv
+ Source CSV separator:
+ Choose separator:
+ 1. comma (,)
+ 2. tab (\t)
+ 3. semicolon (;)
+ 4. pipe (|)
+ 5. custom
++Separator choice [1]: 1
+ Source headers present? [Y/n]:
+ Reference CSV file path: /tmp/reference.csv
+ Reference CSV separator:
+ Choose separator:
+ 1. comma (,)
+ 2. tab (\t)
+ 3. semicolon (;)
+ 4. pipe (|)
+ 5. custom
++Separator choice [1]: 1
+ Reference headers present? [Y/n]:
+ Source key column name: customer_id
+ Reference key column name: external_id
+ Trim whitespace before matching? [Y/n]:
+ Case-insensitive matching? [y/N]:
+ Output destination:
+ 1. console
+ 2. file
++Output destination [1]: 1
+-
+-customer_id,name
+-1,Alice
+-3,Cara
+-Summary: source_rows=5 removed_rows=3 kept_rows=2
+```
+
 ## Testing
 
 Run tests:
@@ -127,7 +176,7 @@ bundle exec rake test
 
 ## Alpha release
 
-Current prerelease version: `0.3.0.alpha`
+Current prerelease version: `0.4.0.alpha`
 
 Install prerelease from RubyGems:
 
@@ -137,146 +186,11 @@ gem install csvops --pre
 
 Release runbook:
 
-- `docs/release-v0.3.0-alpha.md`
-
-## Architecture
-
-The codebase follows a DDD-lite layered structure:
-
-- `domain/`: core domain models and invariants (`ColumnSession`, `RowSession`, and `RandomizationSession` aggregates + supporting entities/value objects).
-- `application/`: use-case orchestration (`RunExtraction`, `RunRowExtraction`, `RunRowRandomization`).
-- `infrastructure/`: CSV reading/streaming and output adapters (console/file).
-- `interface/cli/`: menu, prompts, and user-facing error presentation.
-- `Csvtool::CLI`: entrypoint wiring from command args to interface/application flow.
-
-## Domain model
-
-Bounded contexts: `Column Extraction`, `Row Extraction`, and `Row Randomization`.
-
-### Column Extraction
-
-- Aggregate root: `ColumnSession`
-  - Controls extraction state transitions (`start`, `with_preview`, `confirm!`, `with_output_destination`).
-  - Enforces session-level invariants.
-- Entities:
-  - `CsvSource` (file path + `Separator`)
-  - `ColumnSelection` (chosen header)
-- Value objects:
-  - `Separator`
-  - `ExtractionOptions` (`skip_blanks`, `preview_limit`)
-  - `Preview` (list of `ExtractionValue`)
-  - `ExtractionValue`
-  - `OutputDestination` (`console` or `file(path)`)
-- Application service:
-  - `Application::UseCases::RunExtraction` orchestrates one extraction request.
-- Infrastructure adapters:
-  - `Infrastructure::CSV::HeaderReader`
-  - `Infrastructure::CSV::ValueStreamer`
-  - `Infrastructure::Output::ConsoleWriter`
-  - `Infrastructure::Output::CsvFileWriter`
-- Interface adapters:
-  - `Interface::CLI::MenuLoop`
-  - `Interface::CLI::Prompts::*`
-  - `Interface::CLI::Errors::Presenter`
-
-```mermaid
-flowchart LR
-  UI["Interface CLI\n(Menu + Prompts + Errors)"] --> APP["Application Use Case\nRunExtraction"]
-  APP --> AGG["Domain Aggregate\nColumnSession"]
-
-  AGG --> E1["Entity\nCsvSource"]
-  AGG --> E2["Entity\nColumnSelection"]
-  AGG --> V1["Value Objects\nSeparator / ExtractionOptions / Preview / OutputDestination / ExtractionValue"]
-
-  APP --> INFCSV["Infrastructure CSV\nHeaderReader + ValueStreamer"]
-  APP --> INFOUT["Infrastructure Output\nConsoleWriter + CsvFileWriter"]
-```
+- `docs/release-v0.4.0-alpha.md`
 
-### Row Extraction
-
-Core DDD structure:
-
-- Aggregate root: `RowSession`
-  - Captures one row-range extraction request.
-  - Holds selected source, requested range, and output destination.
-- Entity:
-  - `RowSource` (file path + separator)
-- Value objects:
-  - `RowRange` (`start_row`, `end_row`) plus row-range validation errors
-  - `RowOutputDestination` (`console` or `file(path)`)
-- Application service:
-  - `Application::UseCases::RunRowExtraction` orchestrates row-range extraction.
-- Infrastructure adapters:
-  - `Infrastructure::CSV::HeaderReader`
-  - `Infrastructure::CSV::RowStreamer`
-  - `Infrastructure::Output::CsvRowConsoleWriter`
-  - `Infrastructure::Output::CsvRowFileWriter`
-- Interface adapters:
-  - `Interface::CLI::MenuLoop`
-  - `Interface::CLI::Prompts::*`
-  - `Interface::CLI::Errors::Presenter`
-
-```mermaid
-flowchart LR
-  UI2["Interface CLI\n(Menu + Prompts + Errors)"] --> APP2["Application Use Case\nRunRowExtraction"]
-  APP2 --> AGG2["Domain Aggregate\nRowSession"]
-
-  AGG2 --> E3["Entity\nRowSource"]
-  AGG2 --> V2["Value Objects\nRowRange / RowOutputDestination"]
-
-  APP2 --> INFCSV2["Infrastructure CSV\nHeaderReader + RowStreamer"]
-  APP2 --> INFOUT2["Infrastructure Output\nCsvRowConsoleWriter + CsvRowFileWriter"]
-```
 
-### Row Randomization
-
-Core DDD structure:
-
-- Aggregate root: `RandomizationSession`
-  - Captures one randomization request from source + options + output destination.
-- Entity:
-  - `RandomizationSource` (file path + separator + header mode)
-- Value objects:
-  - `RandomizationOptions` (optional deterministic `seed`)
-  - `RandomizationOutputDestination` (`console` or `file(path)`)
-- Application service:
-  - `Application::UseCases::RunRowRandomization` orchestrates row randomization.
-- Infrastructure adapters:
-  - `Infrastructure::CSV::HeaderReader`
-  - `Infrastructure::CSV::RowRandomizer` (external chunked `RAND + sort` + merge)
-- Interface adapters:
-  - `Interface::CLI::MenuLoop`
-  - `Interface::CLI::Prompts::*`
-  - `Interface::CLI::Errors::Presenter`
-
-```mermaid
-flowchart LR
-  UI3["Interface CLI\n(Menu + Prompts + Errors)"] --> APP3["Application Use Case\nRunRowRandomization"]
-  APP3 --> AGG3["Domain Aggregate\nRandomizationSession"]
-
-  AGG3 --> E4["Entity\nRandomizationSource"]
-  AGG3 --> V3["Value Objects\nRandomizationOptions / RandomizationOutputDestination"]
-
-  APP3 --> INFCSV3["Infrastructure CSV\nHeaderReader + RowRandomizer"]
-```
+## Architecture
 
-## Project layout
+Full architecture and domain documentation lives in:
 
-```text
-bin/tool              # CLI entrypoint
-lib/csvtool/cli.rb
-lib/csvtool/domain/column_session/*
-lib/csvtool/domain/row_session/*
-lib/csvtool/domain/row_randomization_session/*
-lib/csvtool/application/use_cases/run_extraction.rb
-lib/csvtool/application/use_cases/run_row_extraction.rb
-lib/csvtool/application/use_cases/run_row_randomization.rb
-lib/csvtool/infrastructure/csv/*
-lib/csvtool/infrastructure/output/*
-lib/csvtool/interface/cli/menu_loop.rb
-lib/csvtool/interface/cli/prompts/*
-lib/csvtool/interface/cli/errors/presenter.rb
-test/csvtool/cli_test.rb         # end-to-end workflow tests
-test/csvtool/**/*_test.rb        # focused unit tests by component folder
-test/test_helper.rb
-```
+- [`docs/architecture.md`](docs/architecture.md)

data/docs/architecture.md

@@ -0,0 +1,266 @@
+# Architecture
+
+The codebase follows a DDD-lite layered structure:
+
+- `domain/`: core domain models and invariants (`ColumnSession`, `RowSession`, `RandomizationSession`, and `CrossCsvDedupeSession` aggregates + supporting entities/value objects).
+- `application/`: use-case orchestration (`RunExtraction`, `RunRowExtraction`, `RunRowRandomization`, `RunCrossCsvDedupe`).
+- `infrastructure/`: CSV reading/streaming and output adapters (console/file), plus cross-CSV dedupe adapter.
+- `interface/cli/`: menu, prompts, workflows, and user-facing error presentation.
+- `Csvtool::CLI`: entrypoint wiring from command args to interface/application flow.
+
+## Domain model
+
+Bounded contexts: `Column Extraction`, `Row Extraction`, `Row Randomization`, and `Cross-CSV Dedupe`.
+
+### Cross-CSV Dedupe (Large-file behavior)
+
+- Workflow: remove rows from a source CSV when source key matches a key from a reference CSV.
+- Scaling strategy:
+  - Reference CSV keys are loaded into a `Set` for fast membership checks.
+  - Source CSV rows are streamed directly to the selected output destination (console or file).
+- Memory tradeoff:
+  - Memory is dominated by the number of unique keys in the reference CSV.
+  - Source-row memory stays bounded because retained rows are not accumulated in memory before writing.
+
+### Column Extraction
+
+- Aggregate root: `ColumnSession`
+  - Controls extraction state transitions (`start`, `with_preview`, `confirm!`, `with_output_destination`).
+  - Enforces session-level invariants.
+- Entities:
+  - `CsvSource` (file path + `Separator`)
+  - `ColumnSelection` (chosen header)
+- Value objects:
+  - `Separator`
+  - `ExtractionOptions` (`skip_blanks`, `preview_limit`)
+  - `Preview` (list of `ExtractionValue`)
+  - `ExtractionValue`
+  - Shared `OutputDestination` (`console` or `file(path)`)
+- Application service:
+  - `Application::UseCases::RunExtraction` orchestrates one extraction request.
+- Infrastructure adapters:
+  - `Infrastructure::CSV::HeaderReader`
+  - `Infrastructure::CSV::ValueStreamer`
+  - `Infrastructure::Output::ConsoleWriter`
+  - `Infrastructure::Output::CsvFileWriter`
+- Interface adapters:
+  - `Interface::CLI::MenuLoop`
+  - `Interface::CLI::Prompts::*`
+  - `Interface::CLI::Errors::Presenter`
+
+```mermaid
+classDiagram
+  direction LR
+  class MenuLoop
+  class Prompts
+  class Errors
+  class RunExtraction
+  class ColumnSession
+  class CsvSource
+  class ColumnSelection
+  class ExtractionOptions
+  class Preview
+  class ExtractionValue
+  class OutputDestination
+  class HeaderReader
+  class ValueStreamer
+  class ConsoleWriter
+  class CsvFileWriter
+
+  MenuLoop --> RunExtraction : invokes
+  Prompts --> RunExtraction : provides input
+  RunExtraction --> Errors : reports failures
+  RunExtraction --> ColumnSession : orchestrates
+  ColumnSession o-- CsvSource
+  ColumnSession o-- ColumnSelection
+  ColumnSession o-- ExtractionOptions
+  ColumnSession o-- Preview
+  Preview o-- ExtractionValue
+  ColumnSession o-- OutputDestination
+  RunExtraction --> HeaderReader
+  RunExtraction --> ValueStreamer
+  RunExtraction --> ConsoleWriter
+  RunExtraction --> CsvFileWriter
+```
+
+### Row Extraction
+
+Core DDD structure:
+
+- Aggregate root: `RowSession`
+  - Captures one row-range extraction request.
+  - Holds selected source, requested range, and output destination.
+- Entity:
+  - `RowSource` (file path + separator)
+- Value objects:
+  - `RowRange` (`start_row`, `end_row`) plus row-range validation errors
+  - Shared `OutputDestination` (`console` or `file(path)`)
+- Application service:
+  - `Application::UseCases::RunRowExtraction` orchestrates row-range extraction.
+- Infrastructure adapters:
+  - `Infrastructure::CSV::HeaderReader`
+  - `Infrastructure::CSV::RowStreamer`
+  - `Infrastructure::Output::CsvRowConsoleWriter`
+  - `Infrastructure::Output::CsvRowFileWriter`
+- Interface adapters:
+  - `Interface::CLI::MenuLoop`
+  - `Interface::CLI::Prompts::*`
+  - `Interface::CLI::Errors::Presenter`
+
+```mermaid
+classDiagram
+  direction LR
+  class MenuLoop
+  class Prompts
+  class Errors
+  class RunRowExtraction
+  class RowSession
+  class RowSource
+  class RowRange
+  class OutputDestination
+  class HeaderReader
+  class RowStreamer
+  class CsvRowConsoleWriter
+  class CsvRowFileWriter
+
+  MenuLoop --> RunRowExtraction : invokes
+  Prompts --> RunRowExtraction : provides input
+  RunRowExtraction --> Errors : reports failures
+  RunRowExtraction --> RowSession : orchestrates
+  RowSession o-- RowSource
+  RowSession o-- RowRange
+  RowSession o-- OutputDestination
+  RunRowExtraction --> HeaderReader
+  RunRowExtraction --> RowStreamer
+  RunRowExtraction --> CsvRowConsoleWriter
+  RunRowExtraction --> CsvRowFileWriter
+```
+
+### Row Randomization
+
+Core DDD structure:
+
+- Aggregate root: `RandomizationSession`
+  - Captures one randomization request from source + options + output destination.
+- Entity:
+  - `RandomizationSource` (file path + separator + header mode)
+- Value objects:
+  - `RandomizationOptions` (optional deterministic `seed`)
+  - Shared `OutputDestination` (`console` or `file(path)`)
+- Application service:
+  - `Application::UseCases::RunRowRandomization` orchestrates row randomization.
+- Infrastructure adapters:
+  - `Infrastructure::CSV::HeaderReader`
+  - `Infrastructure::CSV::RowRandomizer` (external chunked `RAND + sort` + merge)
+- Interface adapters:
+  - `Interface::CLI::MenuLoop`
+  - `Interface::CLI::Prompts::*`
+  - `Interface::CLI::Errors::Presenter`
+
+```mermaid
+classDiagram
+  direction LR
+  class MenuLoop
+  class Prompts
+  class Errors
+  class RunRowRandomization
+  class RandomizationSession
+  class RandomizationSource
+  class RandomizationOptions
+  class OutputDestination
+  class HeaderReader
+  class RowRandomizer
+
+  MenuLoop --> RunRowRandomization : invokes
+  Prompts --> RunRowRandomization : provides input
+  RunRowRandomization --> Errors : reports failures
+  RunRowRandomization --> RandomizationSession : orchestrates
+  RandomizationSession o-- RandomizationSource
+  RandomizationSession o-- RandomizationOptions
+  RandomizationSession o-- OutputDestination
+  RunRowRandomization --> HeaderReader
+  RunRowRandomization --> RowRandomizer
+```
+
+### Cross-CSV Dedupe
+
+Core DDD structure:
+
+- Aggregate root: `CrossCsvDedupeSession`
+  - Captures one dedupe request with source/reference profiles, key mapping, match options, and output destination.
+- Entities:
+  - `CsvProfile` (path + separator + header mode) for source and reference CSVs.
+  - `KeyMapping` (source selector + reference selector).
+- Value objects:
+  - `ColumnSelector` (header name or 1-based index mode)
+  - `MatchOptions` (`trim_whitespace`, `case_insensitive`, plus normalization behavior)
+  - Shared `OutputDestination` (`console` or `file(path)`)
+- Application service:
+  - `Application::UseCases::RunCrossCsvDedupe` orchestrates dedupe workflow.
+- Infrastructure adapters:
+  - `Infrastructure::CSV::HeaderReader`
+  - `Infrastructure::CSV::SelectorValidator`
+  - `Infrastructure::CSV::CrossCsvDeduper` (streams source rows while checking membership against reference key set)
+- Interface adapters:
+  - `Interface::CLI::MenuLoop`
+  - `Interface::CLI::Workflows::RunCrossCsvDedupeWorkflow`
+  - `Interface::CLI::Prompts::*`
+  - `Interface::CLI::Errors::Presenter`
+
+```mermaid
+classDiagram
+  direction LR
+  class MenuLoop
+  class RunCrossCsvDedupeWorkflow
+  class Prompts
+  class Errors
+  class RunCrossCsvDedupe
+  class CrossCsvDedupeSession
+  class CsvProfile
+  class KeyMapping
+  class ColumnSelector
+  class MatchOptions
+  class OutputDestination
+  class HeaderReader
+  class SelectorValidator
+  class CrossCsvDeduper
+
+  MenuLoop --> RunCrossCsvDedupeWorkflow : invokes
+  Prompts --> RunCrossCsvDedupeWorkflow : provides input
+  RunCrossCsvDedupeWorkflow --> Errors : reports failures
+  RunCrossCsvDedupeWorkflow --> RunCrossCsvDedupe : calls
+  RunCrossCsvDedupe --> CrossCsvDedupeSession : orchestrates
+  CrossCsvDedupeSession o-- CsvProfile
+  CrossCsvDedupeSession o-- KeyMapping
+  KeyMapping o-- ColumnSelector
+  CrossCsvDedupeSession o-- MatchOptions
+  CrossCsvDedupeSession o-- OutputDestination
+  RunCrossCsvDedupe --> HeaderReader
+  RunCrossCsvDedupe --> SelectorValidator
+  RunCrossCsvDedupe --> CrossCsvDeduper
+```
+
+## Project layout
+
+```text
+bin/tool              # CLI entrypoint
+lib/csvtool/cli.rb
+lib/csvtool/domain/column_session/*
+lib/csvtool/domain/row_session/*
+lib/csvtool/domain/row_randomization_session/*
+lib/csvtool/domain/cross_csv_dedupe_session/*
+lib/csvtool/domain/shared/output_destination.rb
+lib/csvtool/application/use_cases/run_extraction.rb
+lib/csvtool/application/use_cases/run_row_extraction.rb
+lib/csvtool/application/use_cases/run_row_randomization.rb
+lib/csvtool/application/use_cases/run_cross_csv_dedupe.rb
+lib/csvtool/infrastructure/csv/*
+lib/csvtool/infrastructure/output/*
+lib/csvtool/interface/cli/menu_loop.rb
+lib/csvtool/interface/cli/workflows/*
+lib/csvtool/interface/cli/prompts/*
+lib/csvtool/interface/cli/errors/presenter.rb
+test/csvtool/cli_test.rb         # end-to-end workflow tests
+test/csvtool/**/*_test.rb        # focused unit tests by component folder
+test/test_helper.rb
+```

data/docs/release-v0.4.0-alpha.md

@@ -0,0 +1,87 @@
+# Release Checklist: v0.4.0-alpha
+
+## 1. Verify environment
+
+```bash
+ruby -v
+bundle -v
+```
+
+Expected:
+- Ruby `3.3.0`
+
+## 2. Install dependencies
+
+```bash
+bundle install
+```
+
+## 3. Run quality checks
+
+```bash
+bundle exec rake test
+```
+
+## 4. Smoke test CLI commands
+
+```bash
+bundle exec csvtool menu
+bundle exec csvtool column test/fixtures/sample_people.csv name
+```
+
+## 5. Smoke test workflows
+
+### Row randomization workflow
+
+Use menu option `3` (`Randomize rows`) and verify:
+- headered CSV output keeps header in first row
+- seeded mode is reproducible
+- file output path writes valid CSV
+- headerless mode randomizes all rows
+
+### Cross-CSV dedupe workflow
+
+Use menu option `4` (`Dedupe using another CSV`) and verify:
+- headered + comma happy path produces expected retained rows
+- headerless + index selectors work
+- TSV separators work
+- normalization toggles (`trim`, `case-insensitive`) behave as expected
+- diagnostics render for `no matches` and `all removed`
+- file output mode writes expected CSV
+
+## 6. Build and validate gem package
+
+```bash
+gem build csvops.gemspec
+gem install ./csvops-0.4.0.alpha.gem
+csvtool menu
+```
+
+## 7. Commit release prep
+
+```bash
+git add -A
+git commit -m "chore(release): prepare v0.4.0-alpha"
+```
+
+## 8. Tag release
+
+```bash
+git tag -a v0.4.0-alpha -m "v0.4.0-alpha"
+git push origin main --tags
+```
+
+## 9. Publish gem (optional for alpha)
+
+```bash
+gem push csvops-0.4.0.alpha.gem
+```
+
+## 10. Create GitHub release
+
+Create release `v0.4.0-alpha` with:
+- Cross-CSV dedupe workflow with normalization options and large-file streaming behavior
+- Dedupe domain model (`CrossCsvDedupeSession`) with stronger invariants
+- Shared-kernel `OutputDestination` value object across workflows
+- Architecture/docs split (`README` + `docs/architecture.md`) with UML diagrams
+- Dedupe boundary cleanup: CLI workflow (`RunCrossCsvDedupeWorkflow`) and application use-case separation

data/lib/csvtool/application/use_cases/run_cross_csv_dedupe.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+require "csv"
+require "csvtool/infrastructure/csv/header_reader"
+require "csvtool/infrastructure/csv/cross_csv_deduper"
+require "csvtool/infrastructure/csv/selector_validator"
+
+module Csvtool
+  module Application
+    module UseCases
+      class RunCrossCsvDedupe
+        Result = Struct.new(:ok, :error, :data, keyword_init: true) do
+          def ok?
+            ok
+          end
+        end
+
+        def initialize(
+          header_reader: Infrastructure::CSV::HeaderReader.new,
+          deduper: Infrastructure::CSV::CrossCsvDeduper.new,
+          selector_validator: Infrastructure::CSV::SelectorValidator.new(header_reader: header_reader)
+        )
+          @header_reader = header_reader
+          @deduper = deduper
+          @selector_validator = selector_validator
+        end
+
+        def call(session:, on_header: nil, on_row: nil)
+          current_read_path = session.source.path
+          return failure(:column_not_found) unless @selector_validator.valid?(profile: session.source, selector: session.key_mapping.source_selector)
+
+          current_read_path = session.reference.path
+          return failure(:column_not_found) unless @selector_validator.valid?(profile: session.reference, selector: session.key_mapping.reference_selector)
+
+          source_headers = session.source.headers_present? ? @header_reader.call(file_path: session.source.path, col_sep: session.source.separator) : nil
+          current_read_path = session.source.path
+
+          if session.output_destination.file?
+            write_file(session: session, source_headers: source_headers)
+          else
+            on_header.call(source_headers) if on_header && source_headers
+            stats = @deduper.each_retained(**dedupe_options(session)) do |fields|
+              on_row.call(fields) if on_row
+            end
+            success(stats: stats)
+          end
+        rescue CSV::MalformedCSVError
+          failure(:could_not_parse_csv)
+        rescue Errno::EACCES
+          failure(:cannot_read_file, path: current_read_path || session.source.path)
+        end
+
+        private
+
+        def write_file(session:, source_headers:)
+          stats = nil
+          ::CSV.open(
+            session.output_destination.path,
+            "w",
+            write_headers: !source_headers.nil?,
+            headers: source_headers,
+            col_sep: session.source.separator
+          ) do |csv|
+            stats = @deduper.each_retained(**dedupe_options(session)) { |fields| csv << fields }
+          end
+          success(stats: stats, output_path: session.output_destination.path)
+        rescue Errno::EACCES, Errno::ENOENT => e
+          failure(:cannot_write_output_file, path: session.output_destination.path, error_class: e.class)
+        end
+
+        def dedupe_options(session)
+          {
+            source_path: session.source.path,
+            reference_path: session.reference.path,
+            source_selector: session.key_mapping.source_selector,
+            reference_selector: session.key_mapping.reference_selector,
+            source_col_sep: session.source.separator,
+            reference_col_sep: session.reference.separator,
+            match_options: session.match_options
+          }
+        end
+
+        def success(data)
+          Result.new(ok: true, error: nil, data: data)
+        end
+
+        def failure(code, data = {})
+          Result.new(ok: false, error: code, data: data)
+        end
+      end
+    end
+  end
+end