csvops 0.3.0.alpha → 0.5.0.alpha

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/docs/release-v0.5.0-alpha.md

@@ -0,0 +1,89 @@
+# Release Checklist: v0.5.0-alpha
+
+## 1. Verify environment
+
+```bash
+ruby -v
+bundle -v
+```
+
+Expected:
+- Ruby `3.3.x`
+
+## 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 extraction workflow
+
+Use menu option `2` (`Extract rows (range)`) and verify:
+- headered CSV rows print correctly in console mode
+- out-of-bounds row range shows friendly message
+- file output mode writes expected CSV rows
+
+### Row randomization workflow
+
+Use menu option `3` (`Randomize rows`) and verify:
+- seeded mode is reproducible
+- headered and headerless modes both work
+- file output path writes valid randomized CSV
+
+### Cross-CSV dedupe workflow
+
+Use menu option `4` (`Dedupe using another CSV`) and verify:
+- expected retained rows for headered source/reference files
+- separator/header-mode combinations still work
+- file output mode writes expected deduped CSV
+
+## 6. Build and validate gem package
+
+```bash
+gem build csvops.gemspec
+gem install ./csvops-0.5.0.alpha.gem
+csvtool menu
+```
+
+## 7. Commit release prep
+
+```bash
+git add -A
+git commit -m "chore(release): prepare v0.5.0-alpha"
+```
+
+## 8. Tag release
+
+```bash
+git tag -a v0.5.0-alpha -m "v0.5.0-alpha"
+git push origin main --tags
+```
+
+## 9. Publish gem (optional for alpha)
+
+```bash
+gem push csvops-0.5.0.alpha.gem
+```
+
+## 10. Create GitHub release
+
+Create release `v0.5.0-alpha` with:
+- Use-case file-write boundary cleanup across all workflows
+- New infrastructure file-writer adapters for row randomization and cross-CSV dedupe
+- Final architecture boundary audit with guard test for direct write APIs in use cases
+- Updated architecture diagrams to reflect current writer adapter dependencies

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

@@ -0,0 +1,96 @@
+# 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"
+require "csvtool/infrastructure/output/csv_cross_csv_dedupe_file_writer"
+
+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),
+          csv_cross_csv_dedupe_file_writer: nil
+        )
+          @header_reader = header_reader
+          @deduper = deduper
+          @selector_validator = selector_validator
+          @csv_cross_csv_dedupe_file_writer = csv_cross_csv_dedupe_file_writer || Infrastructure::Output::CsvCrossCsvDedupeFileWriter.new(
+            deduper: @deduper
+          )
+        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, Errno::ENOENT => e
+          if session.output_destination.file?
+            failure(:cannot_write_output_file, path: session.output_destination.path, error_class: e.class)
+          else
+            failure(:cannot_read_file, path: current_read_path || session.source.path)
+          end
+        end
+
+        private
+
+        def write_file(session:, source_headers:)
+          stats = @csv_cross_csv_dedupe_file_writer.call(
+            path: session.output_destination.path,
+            headers: source_headers,
+            col_sep: session.source.separator,
+            dedupe_options: dedupe_options(session)
+          )
+          success(stats: stats, output_path: session.output_destination.path)
+        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

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

@@ -1,64 +1,47 @@
 # frozen_string_literal: true
 
 require "csv"
-require "csvtool/interface/cli/errors/presenter"
-require "csvtool/interface/cli/prompts/file_path_prompt"
-require "csvtool/interface/cli/prompts/separator_prompt"
-require "csvtool/interface/cli/prompts/column_selector_prompt"
-require "csvtool/interface/cli/prompts/skip_blanks_prompt"
-require "csvtool/interface/cli/prompts/confirm_prompt"
-require "csvtool/interface/cli/prompts/output_destination_prompt"
 require "csvtool/infrastructure/csv/header_reader"
 require "csvtool/infrastructure/csv/value_streamer"
-require "csvtool/services/preview_builder"
-require "csvtool/infrastructure/output/console_writer"
 require "csvtool/infrastructure/output/csv_file_writer"
-require "csvtool/domain/column_session/separator"
-require "csvtool/domain/column_session/csv_source"
-require "csvtool/domain/column_session/column_selection"
-require "csvtool/domain/column_session/extraction_options"
-require "csvtool/domain/column_session/extraction_value"
-require "csvtool/domain/column_session/preview"
-require "csvtool/domain/column_session/output_destination"
-require "csvtool/domain/column_session/column_session"
+require "csvtool/services/preview_builder"
 
 module Csvtool
   module Application
     module UseCases
       class RunExtraction
-        def initialize(stdin:, stdout:)
-          @stdin = stdin
-          @stdout = stdout
-          @errors = Interface::CLI::Errors::Presenter.new(stdout: stdout)
-          @header_reader = Infrastructure::CSV::HeaderReader.new
-          @value_streamer = Infrastructure::CSV::ValueStreamer.new
-          @preview_builder = Services::PreviewBuilder.new(value_streamer: @value_streamer)
+        Result = Struct.new(:ok, :error, :data, keyword_init: true) do
+          def ok?
+            ok
+          end
         end
 
-        def call
-          file_path = Interface::CLI::Prompts::FilePathPrompt.new(stdin: @stdin, stdout: @stdout).call
-          return @errors.file_not_found(file_path) unless File.file?(file_path)
-
-          col_sep = Interface::CLI::Prompts::SeparatorPrompt.new(stdin: @stdin, stdout: @stdout, errors: @errors).call
-          return if col_sep.nil?
-          separator = Domain::ColumnSession::Separator.new(col_sep)
+        def initialize(
+          header_reader: Infrastructure::CSV::HeaderReader.new,
+          value_streamer: Infrastructure::CSV::ValueStreamer.new,
+          preview_builder: nil,
+          csv_file_writer: nil
+        )
+          @header_reader = header_reader
+          @value_streamer = value_streamer
+          @preview_builder = preview_builder || Services::PreviewBuilder.new(value_streamer: value_streamer)
+          @csv_file_writer = csv_file_writer || Infrastructure::Output::CsvFileWriter.new(value_streamer: @value_streamer)
+        end
 
-          source = Domain::ColumnSession::CsvSource.new(path: file_path, separator: separator)
-          headers = @header_reader.call(file_path: source.path, col_sep: source.separator.value)
-          return @errors.no_headers if headers.empty?
+        def read_headers(file_path:, col_sep:)
+          return failure(:file_not_found, path: file_path) unless File.file?(file_path)
 
-          column_name = Interface::CLI::Prompts::ColumnSelectorPrompt.new(stdin: @stdin, stdout: @stdout, errors: @errors).call(headers)
-          return if column_name.nil?
-          column_selection = Domain::ColumnSession::ColumnSelection.new(name: column_name)
+          headers = @header_reader.call(file_path: file_path, col_sep: col_sep)
+          return failure(:no_headers) if headers.empty?
 
-          skip_blanks = Interface::CLI::Prompts::SkipBlanksPrompt.new(stdin: @stdin, stdout: @stdout).call
-          options = Domain::ColumnSession::ExtractionOptions.new(skip_blanks: skip_blanks, preview_limit: 10)
-          session = Domain::ColumnSession::ColumnSession.start(
-            source: source,
-            column_selection: column_selection,
-            options: options
-          )
+          success(headers: headers)
+        rescue CSV::MalformedCSVError
+          failure(:could_not_parse_csv)
+        rescue Errno::EACCES
+          failure(:cannot_read_file, path: file_path)
+        end
 
+        def preview(session:)
           preview_values = @preview_builder.call(
             file_path: session.source.path,
             column_name: session.column_selection.name,
@@ -66,58 +49,50 @@ module Csvtool
             skip_blanks: session.options.skip_blanks?,
             limit: session.options.preview_limit
           )
-          preview = Domain::ColumnSession::Preview.new(
-            values: preview_values.map { |value| Domain::ColumnSession::ExtractionValue.new(value) }
-          )
-          session = session.with_preview(preview)
-
-          confirmed = Interface::CLI::Prompts::ConfirmPrompt.new(stdin: @stdin, stdout: @stdout, errors: @errors).call(session.preview.to_strings)
-          return unless confirmed
-          session = session.confirm!
-
-          output_destination = Interface::CLI::Prompts::OutputDestinationPrompt.new(stdin: @stdin, stdout: @stdout, errors: @errors).call
-          return if output_destination.nil?
-          domain_destination =
-            if output_destination[:mode] == :file
-              Domain::ColumnSession::OutputDestination.file(path: output_destination[:path])
-            else
-              Domain::ColumnSession::OutputDestination.console
-            end
-          session = session.with_output_destination(domain_destination)
-
-          write_output(
-            session.output_destination,
-            file_path: session.source.path,
-            column_name: session.column_selection.name,
-            col_sep: session.source.separator.value,
-            skip_blanks: session.options.skip_blanks?
-          )
+          success(preview_values: preview_values)
         rescue CSV::MalformedCSVError
-          @errors.could_not_parse_csv
+          failure(:could_not_parse_csv)
         rescue Errno::EACCES
-          @errors.cannot_read_file(file_path)
+          failure(:cannot_read_file, path: session.source.path)
         end
 
-        private
-
-        def writer_for(output_destination)
-          if output_destination.file?
-            Infrastructure::Output::CsvFileWriter.new(stdout: @stdout, errors: @errors, value_streamer: @value_streamer)
+        def extract(session:, on_value: nil)
+          if session.output_destination.file?
+            @csv_file_writer.call(
+              output_path: session.output_destination.path,
+              file_path: session.source.path,
+              column_name: session.column_selection.name,
+              col_sep: session.source.separator.value,
+              skip_blanks: session.options.skip_blanks?
+            )
+            success(output_path: session.output_destination.path)
           else
-            Infrastructure::Output::ConsoleWriter.new(stdout: @stdout, value_streamer: @value_streamer)
+            @value_streamer.each(
+              file_path: session.source.path,
+              column_name: session.column_selection.name,
+              col_sep: session.source.separator.value,
+              skip_blanks: session.options.skip_blanks?
+            ) { |value| on_value.call(value) if on_value }
+            success({})
           end
+        rescue CSV::MalformedCSVError
+          failure(:could_not_parse_csv)
+        rescue Errno::EACCES, Errno::ENOENT => e
+          if session.output_destination.file?
+            failure(:cannot_write_output_file, path: session.output_destination.path, error_class: e.class)
+          else
+            failure(:cannot_read_file, path: session.source.path)
+          end
+        end
+
+        private
+
+        def success(data)
+          Result.new(ok: true, error: nil, data: data)
         end
 
-        def write_output(output_destination, file_path:, column_name:, col_sep:, skip_blanks:)
-          writer = writer_for(output_destination)
-          args = {
-            file_path: file_path,
-            column_name: column_name,
-            col_sep: col_sep,
-            skip_blanks: skip_blanks
-          }
-          args[:output_path] = output_destination.path if output_destination.file?
-          writer.call(**args)
+        def failure(code, data = {})
+          Result.new(ok: false, error: code, data: data)
         end
       end
     end

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

@@ -1,74 +1,46 @@
 # frozen_string_literal: true
 
 require "csv"
-require "csvtool/interface/cli/errors/presenter"
-require "csvtool/interface/cli/prompts/file_path_prompt"
-require "csvtool/interface/cli/prompts/separator_prompt"
-require "csvtool/interface/cli/prompts/output_destination_prompt"
 require "csvtool/infrastructure/csv/header_reader"
 require "csvtool/infrastructure/csv/row_streamer"
-require "csvtool/infrastructure/output/csv_row_console_writer"
 require "csvtool/infrastructure/output/csv_row_file_writer"
-require "csvtool/domain/row_session/row_range"
-require "csvtool/domain/row_session/row_source"
-require "csvtool/domain/row_session/row_output_destination"
-require "csvtool/domain/row_session/row_session"
 
 module Csvtool
   module Application
     module UseCases
       class RunRowExtraction
-        def initialize(stdin:, stdout:)
-          @stdin = stdin
-          @stdout = stdout
-          @errors = Interface::CLI::Errors::Presenter.new(stdout: stdout)
-          @header_reader = Infrastructure::CSV::HeaderReader.new
-          @row_streamer = Infrastructure::CSV::RowStreamer.new
+        Result = Struct.new(:ok, :error, :data, keyword_init: true) do
+          def ok?
+            ok
+          end
         end
 
-        def call
-          file_path = Interface::CLI::Prompts::FilePathPrompt.new(stdin: @stdin, stdout: @stdout).call
-          return @errors.file_not_found(file_path) unless File.file?(file_path)
-
-          col_sep = Interface::CLI::Prompts::SeparatorPrompt.new(stdin: @stdin, stdout: @stdout, errors: @errors).call
-          return if col_sep.nil?
-          source = Domain::RowSession::RowSource.new(path: file_path, separator: col_sep)
-
-          @stdout.print "Start row (1-based, inclusive): "
-          start_row_input = @stdin.gets&.strip.to_s
-          @stdout.print "End row (1-based, inclusive): "
-          end_row_input = @stdin.gets&.strip.to_s
+        def initialize(
+          header_reader: Infrastructure::CSV::HeaderReader.new,
+          row_streamer: Infrastructure::CSV::RowStreamer.new,
+          csv_row_file_writer: nil
+        )
+          @header_reader = header_reader
+          @row_streamer = row_streamer
+          @csv_row_file_writer = csv_row_file_writer || Infrastructure::Output::CsvRowFileWriter.new(row_streamer: @row_streamer)
+        end
 
-          headers = @header_reader.call(file_path: source.path, col_sep: source.separator)
-          return @errors.no_headers if headers.empty?
+        def read_headers(file_path:, col_sep:)
+          return failure(:file_not_found, path: file_path) unless File.file?(file_path)
 
-          row_range = Domain::RowSession::RowRange.from_inputs(
-            start_row_input: start_row_input,
-            end_row_input: end_row_input
-          )
-          session = Domain::RowSession::RowSession.start(source: source, row_range: row_range)
+          headers = @header_reader.call(file_path: file_path, col_sep: col_sep)
+          return failure(:no_headers) if headers.empty?
 
-          output_destination = Interface::CLI::Prompts::OutputDestinationPrompt.new(
-            stdin: @stdin,
-            stdout: @stdout,
-            errors: @errors
-          ).call
-          return if output_destination.nil?
-          destination =
-            if output_destination[:mode] == :file
-              Domain::RowSession::RowOutputDestination.file(path: output_destination[:path])
-            else
-              Domain::RowSession::RowOutputDestination.console
-            end
-          session = session.with_output_destination(destination)
+          success(headers: headers)
+        rescue CSV::MalformedCSVError
+          failure(:could_not_parse_csv)
+        rescue Errno::EACCES
+          failure(:cannot_read_file, path: file_path)
+        end
 
-          stats =
+        def extract(session:, headers:, on_row: nil)
           if session.output_destination.file?
-            Infrastructure::Output::CsvRowFileWriter.new(
-              stdout: @stdout,
-              errors: @errors,
-              row_streamer: @row_streamer
-            ).call(
+            stats = @csv_row_file_writer.call(
               output_path: session.output_destination.path,
               file_path: session.source.path,
               col_sep: session.source.separator,
@@ -76,35 +48,35 @@ module Csvtool
               start_row: session.row_range.start_row,
               end_row: session.row_range.end_row
             )
+            success(stats.merge(output_path: session.output_destination.path))
           else
-            Infrastructure::Output::CsvRowConsoleWriter.new(stdout: @stdout, row_streamer: @row_streamer).call(
+            stats = @row_streamer.each_in_range(
               file_path: session.source.path,
               col_sep: session.source.separator,
-              headers: headers,
               start_row: session.row_range.start_row,
               end_row: session.row_range.end_row
-            )
+            ) { |fields| on_row.call(fields) if on_row }
+            success(stats)
           end
-          return if stats.nil?
-
-          @errors.row_range_out_of_bounds(stats[:row_count]) unless stats[:matched]
-        rescue Domain::RowSession::InvalidStartRowError
-          @errors.invalid_start_row
-        rescue Domain::RowSession::InvalidEndRowError
-          @errors.invalid_end_row
-        rescue Domain::RowSession::InvalidRowRangeOrderError
-          @errors.invalid_row_range_order
-        rescue ArgumentError => e
-          return @errors.empty_output_path if e.message == "file output path cannot be empty"
-
-          raise e
         rescue CSV::MalformedCSVError
-          @errors.could_not_parse_csv
-        rescue Errno::EACCES
-          @errors.cannot_read_file(file_path)
+          failure(:could_not_parse_csv)
+        rescue Errno::EACCES, Errno::ENOENT => e
+          if session.output_destination.file?
+            failure(:cannot_write_output_file, path: session.output_destination.path, error_class: e.class)
+          else
+            failure(:cannot_read_file, path: session.source.path)
+          end
         end
-        
+
         private
+
+        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