csvops 0.2.0.alpha → 0.3.0.alpha

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5a04bb138984be7581485f1db2ac6b145ca446846d54179e47ee42f28e4bcf48
-  data.tar.gz: 2cb0f7ae0e9dea000f9422c922bae2842649eec253752c362cd4301ecf60a29d
+  metadata.gz: 9663c50901b31a8073c4a5a0524e9e30c81c20bbe1b736af71649e60a7150a0e
+  data.tar.gz: a622dad35eb52afeded279726d2575db0cd210c8ed4aa07650506bfd2e2b6de5
 SHA512:
-  metadata.gz: ea2610440ae2db2052b4e317ad6ec066ed7641fe5a09cf3b5e9a5ea8e80249474f636d3899cf5cc99ae07f23da279148c301296a5f0a24af61aae2d35605717c
-  data.tar.gz: 60da56d279491e8e3b9401d2bca7910beac884eb9bab38ee67b18dc48e3880caf1c9a82454905eb0d4d2dd71611ad6141b2b708bd962e13045faf569bd67540c
+  metadata.gz: 28726bb66d05881caead074ce529d79db5424b85a7552f8b56cca44e891b3bb0c34cd850ff22351d6d93a5ef725e3891ccc8b7ac7e1e62d24d4e4c4d7d9b344d
+  data.tar.gz: 0fb96011d8737fb757b30e6226b9086453aa3ef6e5def1e95b77bb8bdbd414e25b72adfe6a8e65ee0498bbb88f2a809777a0d2405057689d00b3858c73014b93

data/README.md

@@ -127,7 +127,7 @@ bundle exec rake test
 
 ## Alpha release
 
-Current prerelease version: `0.2.0.alpha`
+Current prerelease version: `0.3.0.alpha`
 
 Install prerelease from RubyGems:
 
@@ -137,21 +137,21 @@ gem install csvops --pre
 
 Release runbook:
 
-- `docs/release-v0.2.0-alpha.md`
+- `docs/release-v0.3.0-alpha.md`
 
 ## Architecture
 
 The codebase follows a DDD-lite layered structure:
 
-- `domain/`: core domain models and invariants (`ColumnSession` and `RowSession` aggregates + supporting entities/value objects).
-- `application/`: use-case orchestration (`RunExtraction`, `RunRowExtraction`).
+- `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` and `Row Extraction`.
+Bounded contexts: `Column Extraction`, `Row Extraction`, and `Row Randomization`.
 
 ### Column Extraction
 
@@ -228,6 +228,38 @@ flowchart LR
   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"]
+```
+
 ## Project layout
 
 ```text
@@ -235,8 +267,10 @@ 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

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

@@ -0,0 +1,74 @@
+# Release Checklist: v0.3.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 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
+
+## 6. Build and validate gem package
+
+```bash
+gem build csvops.gemspec
+gem install ./csvops-0.3.0.alpha.gem
+csvtool menu
+```
+
+## 7. Commit release prep
+
+```bash
+git add -A
+git commit -m "chore(release): prepare v0.3.0-alpha"
+```
+
+## 8. Tag release
+
+```bash
+git tag -a v0.3.0-alpha -m "v0.3.0-alpha"
+git push origin main --tags
+```
+
+## 9. Publish gem (optional for alpha)
+
+```bash
+gem push csvops-0.3.0.alpha.gem
+```
+
+## 10. Create GitHub release
+
+Create release `v0.3.0-alpha` with:
+- Randomize rows workflow support
+- Seeded deterministic randomization
+- External chunked randomization strategy for large files
+- Updated domain model (`RowRandomizationSession`)

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

@@ -0,0 +1,105 @@
+# 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/headers_present_prompt"
+require "csvtool/interface/cli/prompts/seed_prompt"
+require "csvtool/interface/cli/prompts/output_destination_prompt"
+require "csvtool/infrastructure/csv/header_reader"
+require "csvtool/infrastructure/csv/row_randomizer"
+require "csvtool/domain/row_randomization_session/randomization_source"
+require "csvtool/domain/row_randomization_session/randomization_options"
+require "csvtool/domain/row_randomization_session/randomization_output_destination"
+require "csvtool/domain/row_randomization_session/randomization_session"
+
+module Csvtool
+  module Application
+    module UseCases
+      class RunRowRandomization
+        def initialize(stdin:, stdout:)
+          @stdin = stdin
+          @stdout = stdout
+          @errors = Interface::CLI::Errors::Presenter.new(stdout: stdout)
+          @header_reader = Infrastructure::CSV::HeaderReader.new
+          @row_randomizer = Infrastructure::CSV::RowRandomizer.new
+        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?
+
+          headers_present = Interface::CLI::Prompts::HeadersPresentPrompt.new(stdin: @stdin, stdout: @stdout).call
+          source = Domain::RowRandomizationSession::RandomizationSource.new(
+            path: file_path,
+            separator: col_sep,
+            headers_present: headers_present
+          )
+          headers = source.headers_present? ? @header_reader.call(file_path: source.path, col_sep: source.separator) : nil
+          return @errors.no_headers if source.headers_present? && headers.empty?
+
+          seed = Interface::CLI::Prompts::SeedPrompt.new(stdin: @stdin, stdout: @stdout, errors: @errors).call
+          return if seed == Interface::CLI::Prompts::SeedPrompt::INVALID
+          options = Domain::RowRandomizationSession::RandomizationOptions.new(seed: seed)
+          session = Domain::RowRandomizationSession::RandomizationSession.start(source: source, options: options)
+
+          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::RowRandomizationSession::RandomizationOutputDestination.file(path: output_destination[:path])
+            else
+              Domain::RowRandomizationSession::RandomizationOutputDestination.console
+            end
+          session = session.with_output_destination(destination)
+
+          randomized_rows = @row_randomizer.each(
+            file_path: session.source.path,
+            col_sep: session.source.separator,
+            headers: session.source.headers_present?,
+            seed: session.options.seed
+          )
+
+          if session.output_destination.file?
+            write_output_file(session.output_destination.path, headers, randomized_rows, col_sep: session.source.separator)
+          else
+            print_to_console(headers, randomized_rows, col_sep: session.source.separator)
+          end
+        rescue CSV::MalformedCSVError
+          @errors.could_not_parse_csv
+        rescue ArgumentError => e
+          return @errors.empty_output_path if e.message == "file output path cannot be empty"
+
+          raise e
+        rescue Errno::EACCES
+          @errors.cannot_read_file(file_path)
+        end
+
+        private
+
+        def print_to_console(headers, rows, col_sep:)
+          @stdout.puts
+          @stdout.puts ::CSV.generate_line(headers, row_sep: "", col_sep: col_sep).chomp if headers
+          rows.each { |fields| @stdout.puts ::CSV.generate_line(fields, row_sep: "", col_sep: col_sep).chomp }
+        end
+
+        def write_output_file(path, headers, rows, col_sep:)
+          ::CSV.open(path, "w", write_headers: !headers.nil?, headers: headers, col_sep: col_sep) do |csv|
+            rows.each { |fields| csv << fields }
+          end
+          @stdout.puts "Wrote output to #{path}"
+        rescue Errno::EACCES, Errno::ENOENT => e
+          @errors.cannot_write_output_file(path, e.class)
+        end
+      end
+    end
+  end
+end

data/lib/csvtool/cli.rb

@@ -4,6 +4,7 @@ require "csv"
 require "csvtool/interface/cli/menu_loop"
 require "csvtool/application/use_cases/run_extraction"
 require "csvtool/application/use_cases/run_row_extraction"
+require "csvtool/application/use_cases/run_row_randomization"
 require "csvtool/interface/cli/errors/presenter"
 require "csvtool/infrastructure/csv/header_reader"
 require "csvtool/infrastructure/csv/value_streamer"
@@ -14,6 +15,7 @@ module Csvtool
     MENU_OPTIONS = [
       "Extract column",
       "Extract rows (range)",
+      "Randomize rows",
       "Exit"
     ].freeze
 
@@ -45,12 +47,14 @@ module Csvtool
     def run_menu_loop
       extract_column_action = -> { Application::UseCases::RunExtraction.new(stdin: @stdin, stdout: @stdout).call }
       extract_rows_action = -> { Application::UseCases::RunRowExtraction.new(stdin: @stdin, stdout: @stdout).call }
+      randomize_rows_action = -> { Application::UseCases::RunRowRandomization.new(stdin: @stdin, stdout: @stdout).call }
       Interface::CLI::MenuLoop.new(
         stdin: @stdin,
         stdout: @stdout,
         menu_options: MENU_OPTIONS,
         extract_column_action: extract_column_action,
-        extract_rows_action: extract_rows_action
+        extract_rows_action: extract_rows_action,
+        randomize_rows_action: randomize_rows_action
       ).run
     end
 

data/lib/csvtool/domain/row_randomization_session/randomization_options.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Csvtool
+  module Domain
+    module RowRandomizationSession
+      class RandomizationOptions
+        attr_reader :seed
+
+        def initialize(seed:)
+          raise ArgumentError, "seed must be an integer or nil" unless seed.nil? || seed.is_a?(Integer)
+
+          @seed = seed
+        end
+      end
+    end
+  end
+end

data/lib/csvtool/domain/row_randomization_session/randomization_output_destination.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Csvtool
+  module Domain
+    module RowRandomizationSession
+      class RandomizationOutputDestination
+        attr_reader :mode, :path
+
+        def self.console
+          new(mode: :console)
+        end
+
+        def self.file(path:)
+          new(mode: :file, path: path)
+        end
+
+        def initialize(mode:, path: nil)
+          raise ArgumentError, "invalid output mode" unless %i[console file].include?(mode)
+          raise ArgumentError, "file output path cannot be empty" if mode == :file && path.to_s.empty?
+
+          @mode = mode
+          @path = path
+        end
+
+        def file?
+          @mode == :file
+        end
+      end
+    end
+  end
+end

data/lib/csvtool/domain/row_randomization_session/randomization_session.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Csvtool
+  module Domain
+    module RowRandomizationSession
+      class RandomizationSession
+        attr_reader :source, :options, :output_destination
+
+        def self.start(source:, options:)
+          new(source: source, options: options)
+        end
+
+        def initialize(source:, options:, output_destination: nil)
+          @source = source
+          @options = options
+          @output_destination = output_destination
+        end
+
+        def with_output_destination(destination)
+          self.class.new(source: @source, options: @options, output_destination: destination)
+        end
+      end
+    end
+  end
+end

data/lib/csvtool/domain/row_randomization_session/randomization_source.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Csvtool
+  module Domain
+    module RowRandomizationSession
+      class RandomizationSource
+        attr_reader :path, :separator
+
+        def initialize(path:, separator:, headers_present:)
+          raise ArgumentError, "separator cannot be empty" if separator.to_s.empty?
+
+          @path = path
+          @separator = separator
+          @headers_present = headers_present
+        end
+
+        def headers_present?
+          @headers_present
+        end
+      end
+    end
+  end
+end

data/lib/csvtool/infrastructure/csv/row_randomizer.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+require "csv"
+require "tempfile"
+
+module Csvtool
+  module Infrastructure
+    module CSV
+      class RowRandomizer
+        DEFAULT_CHUNK_SIZE = 10_000
+
+        def call(file_path:, col_sep:, headers:, seed: nil)
+          each(file_path: file_path, col_sep: col_sep, headers: headers, seed: seed).to_a
+        end
+
+        def each(file_path:, col_sep:, headers:, seed: nil, chunk_size: DEFAULT_CHUNK_SIZE)
+          chunk_paths = []
+          return enum_for(:each, file_path: file_path, col_sep: col_sep, headers: headers, seed: seed, chunk_size: chunk_size) unless block_given?
+
+          rng = seed.nil? ? Random.new : Random.new(seed)
+          sequence = 0
+          chunk_entries = []
+
+          ::CSV.foreach(file_path, headers: headers, col_sep: col_sep) do |row|
+            fields = headers ? row.fields : row
+            chunk_entries << [rng.rand, sequence, fields]
+            sequence += 1
+            flush_chunk(chunk_entries, chunk_paths) if chunk_entries.length >= chunk_size
+          end
+
+          flush_chunk(chunk_entries, chunk_paths) unless chunk_entries.empty?
+          merge_chunks(chunk_paths) { |fields| yield fields }
+        ensure
+          cleanup_chunks(chunk_paths)
+        end
+
+        private
+
+        def flush_chunk(entries, chunk_paths)
+          entries.sort_by! { |rand_key, seq, _fields| [rand_key, seq] }
+          file = Tempfile.new("csvtool-row-randomizer-chunk")
+          file.binmode
+          entries.each { |entry| Marshal.dump(entry, file) }
+          file.close
+          chunk_paths << file.path
+          entries.clear
+        end
+
+        def merge_chunks(chunk_paths)
+          readers = chunk_paths.map { |path| File.open(path, "rb") }
+          heads = readers.map { |reader| next_entry(reader) }
+
+          loop do
+            indexed = heads.each_with_index.select { |entry, _i| !entry.nil? }
+            break if indexed.empty?
+
+            min_entry, min_index = indexed.min_by { |entry, _i| [entry[0], entry[1]] }
+            yield min_entry[2]
+            heads[min_index] = next_entry(readers[min_index])
+          end
+        ensure
+          readers&.each(&:close)
+        end
+
+        def next_entry(reader)
+          Marshal.load(reader)
+        rescue EOFError
+          nil
+        end
+
+        def cleanup_chunks(chunk_paths)
+          return if chunk_paths.nil?
+
+          chunk_paths.each do |path|
+            File.delete(path) if File.exist?(path)
+          rescue Errno::EACCES, Errno::ENOENT
+            nil
+          end
+        end
+      end
+    end
+  end
+end

data/lib/csvtool/interface/cli/errors/presenter.rb

@@ -49,6 +49,10 @@ module Csvtool
             @stdout.puts "Invalid separator choice."
           end
 
+          def invalid_seed
+            @stdout.puts "Seed must be an integer."
+          end
+
           def canceled
             @stdout.puts "Canceled."
           end

data/lib/csvtool/interface/cli/menu_loop.rb

@@ -4,12 +4,13 @@ module Csvtool
   module Interface
     module CLI
       class MenuLoop
-        def initialize(stdin:, stdout:, menu_options:, extract_column_action:, extract_rows_action:)
+        def initialize(stdin:, stdout:, menu_options:, extract_column_action:, extract_rows_action:, randomize_rows_action:)
           @stdin = stdin
           @stdout = stdout
           @menu_options = menu_options
           @extract_column_action = extract_column_action
           @extract_rows_action = extract_rows_action
+          @randomize_rows_action = randomize_rows_action
         end
 
         def run
@@ -25,9 +26,11 @@ module Csvtool
             when "2"
               @extract_rows_action.call
             when "3"
+              @randomize_rows_action.call
+            when "4"
               return 0
             else
-              @stdout.puts "Please choose 1, 2, or 3."
+              @stdout.puts "Please choose 1, 2, 3, or 4."
             end
           end
         end

data/lib/csvtool/interface/cli/prompts/headers_present_prompt.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Csvtool
+  module Interface
+    module CLI
+      module Prompts
+        class HeadersPresentPrompt
+          def initialize(stdin:, stdout:)
+            @stdin = stdin
+            @stdout = stdout
+          end
+
+          def call
+            @stdout.print "Headers present? [Y/n]: "
+            answer = @stdin.gets&.strip.to_s.downcase
+            !%w[n no].include?(answer)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/csvtool/interface/cli/prompts/seed_prompt.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Csvtool
+  module Interface
+    module CLI
+      module Prompts
+        class SeedPrompt
+          INVALID = :invalid
+
+          def initialize(stdin:, stdout:, errors:)
+            @stdin = stdin
+            @stdout = stdout
+            @errors = errors
+          end
+
+          def call
+            @stdout.print "Random seed (optional integer): "
+            raw = @stdin.gets&.strip.to_s
+            return nil if raw.empty?
+            return raw.to_i if /\A-?\d+\z/.match?(raw)
+
+            @errors.invalid_seed
+            INVALID
+          end
+        end
+      end
+    end
+  end
+end

data/lib/csvtool/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Csvtool
-  VERSION = "0.2.0.alpha"
+  VERSION = "0.3.0.alpha"
 end