csvops 0.4.0.alpha → 0.5.0.alpha

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9c5a0c00272c2d10751b234384ac50ee8caa90681860906419ccdec7a6e3c110
-  data.tar.gz: 849d377bec9acd507c0fd37a75e823bb9458295e12a31a5000b9ba599084092d
+  metadata.gz: b96fb7e03fa0629d3412a97d3abff5414492ac46ad08ede2c872e2176fcbfc62
+  data.tar.gz: 856b7735a472b5810d5f19dff6371a565a7fcc538ce5b6eba52260fff0028760
 SHA512:
-  metadata.gz: ba96ce18b4e6d2fd8eb018f406c17e7b810010a788a6be1acb51a714b87dad614d822edb97f780e2c745e257bbc68c89266427876fcc4b3fee57fadb29232630
-  data.tar.gz: 378c4a47b96cf210b28f689d9ef0aa1056c95777d3128d4044d8462cf802eeb53ca148062f4244182105e4b760bbf7dcf48d19705f69f18dfb78e3fc2e935413
+  metadata.gz: 5f643d331c6b54cb5feb0fe5db4ff7f8f7bc5c28461f74e3bfca5cf93d25703b84f497e72377302874b2b6302ef0fb542995c72d2d21798e3a998f6d5b294704
+  data.tar.gz: 0e254fa75780ce0605054c24b28301d8786535a0f2bbff7adfb45a75f09e60e5315e950648208fa5772d08cdd6abce95ea382838f568947af05ceaa77ba1888f

data/README.md

@@ -45,14 +45,20 @@ Select `1` for column extraction, `2` for row-range extraction, `3` for row rand
 
 ### 3. Follow prompts
 
-Prompt flow:
+Each menu action runs through a dedicated CLI workflow (`interface/cli/workflows/*`) that handles prompts/output and delegates execution to an interface-agnostic application use case.
 
-- CSV file path
-- Separator (`comma`, `tab`, `semicolon`, `pipe`, or `custom`)
-- Optional header filter + column selection
-- Skip blanks (`Y/n`, default `Y`)
-- Preview + confirmation
-- Output destination (`console` or `file`)
+Workflow internals are split into small composable parts:
+
+- `workflows/builders/*` for session construction
+- `workflows/support/*` for shared mapping/dispatch utilities
+- `workflows/presenters/*` for output formatting and summaries
+
+Prompt flow by action:
+
+- `Extract column`: file path, separator, optional header filter + column select, skip blanks, preview/confirm, output destination.
+- `Extract rows (range)`: file path, separator, start row, end row, output destination.
+- `Randomize rows`: file path, separator, headers present, optional seed, output destination.
+- `Dedupe using another CSV`: source/reference files, separators, header modes, key selectors, match options, output destination.
 
 ### 4. Example interaction (console output)
 
@@ -176,7 +182,7 @@ bundle exec rake test
 
 ## Alpha release
 
-Current prerelease version: `0.4.0.alpha`
+Current prerelease version: `0.5.0.alpha`
 
 Install prerelease from RubyGems:
 
@@ -186,7 +192,7 @@ gem install csvops --pre
 
 Release runbook:
 
-- `docs/release-v0.4.0-alpha.md`
+- `docs/release-v0.5.0-alpha.md`
 
 
 ## Architecture

data/docs/architecture.md

@@ -8,6 +8,103 @@ The codebase follows a DDD-lite layered structure:
 - `interface/cli/`: menu, prompts, workflows, and user-facing error presentation.
 - `Csvtool::CLI`: entrypoint wiring from command args to interface/application flow.
 
+## Workflow boundary (standardized)
+
+For all interactive domains (`Column Extraction`, `Row Extraction`, `Row Randomization`, `Cross-CSV Dedupe`), the boundary is:
+
+- `interface/cli/workflows/*`: owns prompts, stdout rendering, and user-facing error presentation.
+- `interface/cli/workflows/builders/*`: builds domain sessions/aggregates from prompt results.
+- `interface/cli/workflows/support/*`: shared workflow utilities (error routing, output destination mapping).
+- `interface/cli/workflows/presenters/*`: workflow-level output/summary rendering.
+- `interface/cli/workflows/steps/*`: optional step-pipeline units for complex workflow orchestration.
+- `application/use_cases/*`: interface-agnostic orchestration with request/result style contracts.
+- `domain/*`: invariants and domain policies.
+- `infrastructure/*`: CSV mechanics and output adapters.
+
+Write-boundary rule:
+- Use cases coordinate write paths but do not perform direct file writes.
+- Direct write APIs (`CSV.open`, writable `File.open`, `File.write`, `IO.write`) are infrastructure-only.
+- File output behavior is implemented in `infrastructure/output/*` writer adapters.
+
+Current usage:
+
+- `RunExtractionWorkflow` uses `WorkflowStepPipeline` + `Steps::Extraction::*`.
+- `RunRowExtractionWorkflow` uses `WorkflowStepPipeline` + `Steps::RowExtraction::*`.
+- `RunRowRandomizationWorkflow` uses `WorkflowStepPipeline` + `Steps::RowRandomization::*`.
+- `RunCrossCsvDedupeWorkflow` uses `WorkflowStepPipeline` + `Steps::CrossCsvDedupe::*`.
+
+## Adding New Concepts
+
+Use this checklist when introducing a new capability (for example: a new transformation function, validator, comparer, or exporter).
+
+### 1) Classify the concept first
+
+- `Workflow concept`: interactive flow and prompt sequence.
+- `Domain concept`: business rule/invariant and core vocabulary.
+- `Application concept`: use-case orchestration and request/result contract.
+- `Infrastructure concept`: file/CSV mechanics, streaming, persistence, or external IO.
+
+If it does not clearly fit one layer, split it until each part has one responsibility.
+
+### 2) Add the feature vertically (thin slice)
+
+Implement in this order:
+
+1. `interface/cli/workflows/*`: new workflow entry or new branch in an existing workflow.
+2. `interface/cli/prompts/*`: prompts for user inputs.
+3. `interface/cli/workflows/builders/*`: build domain session/request objects.
+4. `application/use_cases/*`: interface-agnostic use case with `Result` success/failure.
+5. `domain/*`: new entities/value objects/aggregate changes for invariants.
+6. `infrastructure/*`: adapters needed by the use case.
+7. `interface/cli/workflows/presenters/*`: output and summaries.
+
+Keep each step testable on its own before moving to the next.
+
+### 3) Function type patterns
+
+For a new function type, prefer one of these patterns:
+
+- `Transform` (changes output rows/values):
+  - Domain: transformation options/value objects.
+  - Application: orchestrate transform over streamed rows.
+  - Infrastructure: stream reader/writer implementation.
+- `Validate` (checks and reports findings):
+  - Domain: validation policy and finding model.
+  - Application: run checks and return findings in result data.
+  - Presenter: format findings and summary.
+- `Compare` (source vs reference logic):
+  - Domain: mapping/selectors/match options.
+  - Application: compare strategy and stats.
+  - Infrastructure: dual-source readers and selector helpers.
+- `Export` (destination-focused):
+  - Domain: output destination value object.
+  - Application: orchestrate write path only.
+  - Infrastructure: writer adapter.
+
+### 4) Required boundaries and rules
+
+- Workflows do not contain business rules.
+- Use cases do not prompt or print.
+- Domain does not depend on interface or infrastructure.
+- Infrastructure does not own workflow decisions.
+- Shared workflow helpers belong under `workflows/support/*`.
+- Reusable construction logic belongs under `workflows/builders/*`.
+- Rendering/summary formatting belongs under `workflows/presenters/*`.
+
+### 5) Minimum tests for each new concept
+
+- Prompt tests for each new prompt class.
+- Builder tests for each new builder class.
+- Use-case tests for request/result behavior.
+- Workflow behavior tests for prompt + output integration.
+- One end-to-end CLI test for the happy path.
+
+### 6) Naming and structure guidance
+
+- Prefer domain-first names (`RowRange`, `ColumnSelection`, `MatchOptions`) over technical names.
+- Use `Run<Concept>` for use cases and `Run<Concept>Workflow` for workflows.
+- Keep one file per class and mirror structure under `test/csvtool/...`.
+
 ## Domain model
 
 Bounded contexts: `Column Extraction`, `Row Extraction`, `Row Randomization`, and `Cross-CSV Dedupe`.
@@ -37,7 +134,7 @@ Bounded contexts: `Column Extraction`, `Row Extraction`, `Row Randomization`, an
   - `ExtractionValue`
   - Shared `OutputDestination` (`console` or `file(path)`)
 - Application service:
-  - `Application::UseCases::RunExtraction` orchestrates one extraction request.
+  - `Application::UseCases::RunExtraction` is interface-agnostic and exposes request/result operations.
 - Infrastructure adapters:
   - `Infrastructure::CSV::HeaderReader`
   - `Infrastructure::CSV::ValueStreamer`
@@ -45,6 +142,12 @@ Bounded contexts: `Column Extraction`, `Row Extraction`, `Row Randomization`, an
   - `Infrastructure::Output::CsvFileWriter`
 - Interface adapters:
   - `Interface::CLI::MenuLoop`
+  - `Interface::CLI::Workflows::RunExtractionWorkflow`
+  - `Interface::CLI::Workflows::Builders::ColumnSessionBuilder`
+  - `Interface::CLI::Workflows::Steps::WorkflowStepPipeline`
+  - `Interface::CLI::Workflows::Steps::Extraction::*`
+  - `Interface::CLI::Workflows::Presenters::ColumnExtractionPresenter`
+  - `Interface::CLI::Workflows::Support::{OutputDestinationMapper,ResultErrorHandler}`
   - `Interface::CLI::Prompts::*`
   - `Interface::CLI::Errors::Presenter`
 
@@ -52,6 +155,7 @@ Bounded contexts: `Column Extraction`, `Row Extraction`, `Row Randomization`, an
 classDiagram
   direction LR
   class MenuLoop
+  class RunExtractionWorkflow
   class Prompts
   class Errors
   class RunExtraction
@@ -64,12 +168,12 @@ classDiagram
   class OutputDestination
   class HeaderReader
   class ValueStreamer
-  class ConsoleWriter
   class CsvFileWriter
 
-  MenuLoop --> RunExtraction : invokes
-  Prompts --> RunExtraction : provides input
-  RunExtraction --> Errors : reports failures
+  MenuLoop --> RunExtractionWorkflow : invokes
+  RunExtractionWorkflow --> Prompts : uses
+  RunExtractionWorkflow --> Errors : reports failures
+  RunExtractionWorkflow --> RunExtraction : calls
   RunExtraction --> ColumnSession : orchestrates
   ColumnSession o-- CsvSource
   ColumnSession o-- ColumnSelection
@@ -79,7 +183,6 @@ classDiagram
   ColumnSession o-- OutputDestination
   RunExtraction --> HeaderReader
   RunExtraction --> ValueStreamer
-  RunExtraction --> ConsoleWriter
   RunExtraction --> CsvFileWriter
 ```
 
@@ -96,14 +199,19 @@ Core DDD structure:
   - `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.
+  - `Application::UseCases::RunRowExtraction` is interface-agnostic and exposes request/result operations.
 - Infrastructure adapters:
   - `Infrastructure::CSV::HeaderReader`
   - `Infrastructure::CSV::RowStreamer`
-  - `Infrastructure::Output::CsvRowConsoleWriter`
   - `Infrastructure::Output::CsvRowFileWriter`
 - Interface adapters:
   - `Interface::CLI::MenuLoop`
+  - `Interface::CLI::Workflows::RunRowExtractionWorkflow`
+  - `Interface::CLI::Workflows::Builders::RowExtractionSessionBuilder`
+  - `Interface::CLI::Workflows::Presenters::RowExtractionPresenter`
+  - `Interface::CLI::Workflows::Support::{OutputDestinationMapper,ResultErrorHandler}`
+  - `Interface::CLI::Workflows::Steps::WorkflowStepPipeline`
+  - `Interface::CLI::Workflows::Steps::RowExtraction::*`
   - `Interface::CLI::Prompts::*`
   - `Interface::CLI::Errors::Presenter`
 
@@ -111,6 +219,7 @@ Core DDD structure:
 classDiagram
   direction LR
   class MenuLoop
+  class RunRowExtractionWorkflow
   class Prompts
   class Errors
   class RunRowExtraction
@@ -120,19 +229,17 @@ classDiagram
   class OutputDestination
   class HeaderReader
   class RowStreamer
-  class CsvRowConsoleWriter
   class CsvRowFileWriter
-
-  MenuLoop --> RunRowExtraction : invokes
-  Prompts --> RunRowExtraction : provides input
-  RunRowExtraction --> Errors : reports failures
+  MenuLoop --> RunRowExtractionWorkflow : invokes
+  RunRowExtractionWorkflow --> Prompts : uses
+  RunRowExtractionWorkflow --> Errors : reports failures
+  RunRowExtractionWorkflow --> RunRowExtraction : calls
   RunRowExtraction --> RowSession : orchestrates
   RowSession o-- RowSource
   RowSession o-- RowRange
   RowSession o-- OutputDestination
   RunRowExtraction --> HeaderReader
   RunRowExtraction --> RowStreamer
-  RunRowExtraction --> CsvRowConsoleWriter
   RunRowExtraction --> CsvRowFileWriter
 ```
 
@@ -148,12 +255,19 @@ Core DDD structure:
   - `RandomizationOptions` (optional deterministic `seed`)
   - Shared `OutputDestination` (`console` or `file(path)`)
 - Application service:
-  - `Application::UseCases::RunRowRandomization` orchestrates row randomization.
+  - `Application::UseCases::RunRowRandomization` is interface-agnostic and exposes request/result operations.
 - Infrastructure adapters:
   - `Infrastructure::CSV::HeaderReader`
   - `Infrastructure::CSV::RowRandomizer` (external chunked `RAND + sort` + merge)
+  - `Infrastructure::Output::CsvRandomizedRowFileWriter`
 - Interface adapters:
   - `Interface::CLI::MenuLoop`
+  - `Interface::CLI::Workflows::RunRowRandomizationWorkflow`
+  - `Interface::CLI::Workflows::Builders::RowRandomizationSessionBuilder`
+  - `Interface::CLI::Workflows::Steps::WorkflowStepPipeline`
+  - `Interface::CLI::Workflows::Steps::RowRandomization::*`
+  - `Interface::CLI::Workflows::Presenters::RowRandomizationPresenter`
+  - `Interface::CLI::Workflows::Support::{OutputDestinationMapper,ResultErrorHandler}`
   - `Interface::CLI::Prompts::*`
   - `Interface::CLI::Errors::Presenter`
 
@@ -161,6 +275,7 @@ Core DDD structure:
 classDiagram
   direction LR
   class MenuLoop
+  class RunRowRandomizationWorkflow
   class Prompts
   class Errors
   class RunRowRandomization
@@ -170,16 +285,19 @@ classDiagram
   class OutputDestination
   class HeaderReader
   class RowRandomizer
+  class CsvRandomizedRowFileWriter
 
-  MenuLoop --> RunRowRandomization : invokes
-  Prompts --> RunRowRandomization : provides input
-  RunRowRandomization --> Errors : reports failures
+  MenuLoop --> RunRowRandomizationWorkflow : invokes
+  RunRowRandomizationWorkflow --> Prompts : uses
+  RunRowRandomizationWorkflow --> Errors : reports failures
+  RunRowRandomizationWorkflow --> RunRowRandomization : calls
   RunRowRandomization --> RandomizationSession : orchestrates
   RandomizationSession o-- RandomizationSource
   RandomizationSession o-- RandomizationOptions
   RandomizationSession o-- OutputDestination
   RunRowRandomization --> HeaderReader
   RunRowRandomization --> RowRandomizer
+  RunRowRandomization --> CsvRandomizedRowFileWriter
 ```
 
 ### Cross-CSV Dedupe
@@ -201,9 +319,15 @@ Core DDD structure:
   - `Infrastructure::CSV::HeaderReader`
   - `Infrastructure::CSV::SelectorValidator`
   - `Infrastructure::CSV::CrossCsvDeduper` (streams source rows while checking membership against reference key set)
+  - `Infrastructure::Output::CsvCrossCsvDedupeFileWriter`
 - Interface adapters:
   - `Interface::CLI::MenuLoop`
   - `Interface::CLI::Workflows::RunCrossCsvDedupeWorkflow`
+  - `Interface::CLI::Workflows::Builders::CrossCsvDedupeSessionBuilder`
+  - `Interface::CLI::Workflows::Steps::WorkflowStepPipeline`
+  - `Interface::CLI::Workflows::Steps::CrossCsvDedupe::*`
+  - `Interface::CLI::Workflows::Presenters::CrossCsvDedupePresenter`
+  - `Interface::CLI::Workflows::Support::{OutputDestinationMapper,ResultErrorHandler}`
   - `Interface::CLI::Prompts::*`
   - `Interface::CLI::Errors::Presenter`
 
@@ -224,6 +348,7 @@ classDiagram
   class HeaderReader
   class SelectorValidator
   class CrossCsvDeduper
+  class CsvCrossCsvDedupeFileWriter
 
   MenuLoop --> RunCrossCsvDedupeWorkflow : invokes
   Prompts --> RunCrossCsvDedupeWorkflow : provides input
@@ -238,6 +363,7 @@ classDiagram
   RunCrossCsvDedupe --> HeaderReader
   RunCrossCsvDedupe --> SelectorValidator
   RunCrossCsvDedupe --> CrossCsvDeduper
+  RunCrossCsvDedupe --> CsvCrossCsvDedupeFileWriter
 ```
 
 ## Project layout
@@ -258,6 +384,10 @@ lib/csvtool/infrastructure/csv/*
 lib/csvtool/infrastructure/output/*
 lib/csvtool/interface/cli/menu_loop.rb
 lib/csvtool/interface/cli/workflows/*
+lib/csvtool/interface/cli/workflows/builders/*
+lib/csvtool/interface/cli/workflows/support/*
+lib/csvtool/interface/cli/workflows/presenters/*
+lib/csvtool/interface/cli/workflows/steps/*
 lib/csvtool/interface/cli/prompts/*
 lib/csvtool/interface/cli/errors/presenter.rb
 test/csvtool/cli_test.rb         # end-to-end workflow tests

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

@@ -4,6 +4,7 @@ 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
@@ -18,11 +19,15 @@ module Csvtool
         def initialize(
           header_reader: Infrastructure::CSV::HeaderReader.new,
           deduper: Infrastructure::CSV::CrossCsvDeduper.new,
-          selector_validator: Infrastructure::CSV::SelectorValidator.new(header_reader: header_reader)
+          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)
@@ -46,26 +51,24 @@ module Csvtool
           end
         rescue CSV::MalformedCSVError
           failure(:could_not_parse_csv)
-        rescue Errno::EACCES
-          failure(:cannot_read_file, path: current_read_path || session.source.path)
+        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 = nil
-          ::CSV.open(
-            session.output_destination.path,
-            "w",
-            write_headers: !source_headers.nil?,
+          stats = @csv_cross_csv_dedupe_file_writer.call(
+            path: session.output_destination.path,
             headers: source_headers,
-            col_sep: session.source.separator
-          ) do |csv|
-            stats = @deduper.each_retained(**dedupe_options(session)) { |fields| csv << fields }
-          end
+            col_sep: session.source.separator,
+            dedupe_options: dedupe_options(session)
+          )
           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)