parcels_challenge 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 493fe29181c73db866981d412582161bbb11314081a73bfd1c33e23786ea0ef9
+  data.tar.gz: e74595e138bc4235b8ed9eca5b1dd785278be6fcc84f5689e1ca8e28c151985e
+SHA512:
+  metadata.gz: dd09ab8024cd5ae6dd70656f84e11dec9393b1f41858e624895d6ced520d7a7d6d23d128ba2346e741b02de3e2e50a1bdbe05231e8889bd77778c17632446dfd
+  data.tar.gz: 91a0502416e5833b7289955442b7de3264a91e2cbbac8fe19bb5c262d63ff516b58b9cbbe2af4c69d1b6fe313c24e7b466bf773f7174e4634d1378a99ba692a1

data/.gitignore

@@ -0,0 +1,58 @@
+*.gem
+*.rbc
+/.config
+/coverage/
+/InstalledFiles
+/pkg/
+/spec/reports/
+/spec/examples.txt
+/test/tmp/
+/test/version_tmp/
+/tmp/
+
+# Used by dotenv library to load environment variables.
+# .env
+
+# Ignore Byebug command history file.
+.byebug_history
+
+## Specific to RubyMotion:
+.dat*
+.repl_history
+build/
+*.bridgesupport
+build-iPhoneOS/
+build-iPhoneSimulator/
+
+## Specific to RubyMotion (use of CocoaPods):
+#
+# We recommend against adding the Pods directory to your .gitignore. However
+# you should judge for yourself, the pros and cons are mentioned at:
+# https://guides.cocoapods.org/using/using-cocoapods.html#should-i-check-the-pods-directory-into-source-control
+#
+# vendor/Pods/
+
+## Documentation cache and generated files:
+/.yardoc/
+/_yardoc/
+/doc/
+/rdoc/
+
+## Environment normalization:
+/.bundle/
+/vendor/bundle
+/lib/bundler/man/
+
+# for a library or gem, you might want to ignore these files since the code is
+# intended to run in multiple environments; otherwise, check them in:
+# Gemfile.lock
+# .ruby-version
+# .ruby-gemset
+
+# unless supporting rvm < 1.11.0 or doing something fancy, ignore this:
+.rvmrc
+
+# Used by RuboCop. Remote config files pulled in from inherit_from directive.
+# .rubocop-https?--*
+
+.rspec_status

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/Gemfile

@@ -0,0 +1,5 @@
+source 'https://rubygems.org'
+
+git_source(:github) {|repo_name| "https://github.com/sbaus42/#{repo_name}" }
+
+gemspec

data/Gemfile.lock

@@ -0,0 +1,42 @@
+PATH
+  remote: .
+  specs:
+    parcels_challenge (0.1.0)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    coderay (1.1.3)
+    diff-lcs (1.5.0)
+    method_source (1.0.0)
+    pry (0.14.2)
+      coderay (~> 1.1)
+      method_source (~> 1.0)
+    rake (13.1.0)
+    rspec (3.12.0)
+      rspec-core (~> 3.12.0)
+      rspec-expectations (~> 3.12.0)
+      rspec-mocks (~> 3.12.0)
+    rspec-core (3.12.2)
+      rspec-support (~> 3.12.0)
+    rspec-expectations (3.12.3)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.12.0)
+    rspec-mocks (3.12.6)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.12.0)
+    rspec-support (3.12.1)
+
+PLATFORMS
+  ruby
+  x86_64-linux
+
+DEPENDENCIES
+  bundler (~> 2.5.1)
+  parcels_challenge!
+  pry (~> 0.14.2)
+  rake (~> 13.1.0)
+  rspec (~> 3.12.0)
+
+BUNDLED WITH
+   2.5.1

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 Santiago Baus
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,70 @@
+# parcels
+Like the [band](https://www.youtube.com/watch?v=hznxLHB0oy8) but not really
+
+## Assignment
+
+Given a CSV file that contains a list of parcels and their respective weight and client's name. You'll need to write a program that will efficiently group these parcels into shipments. The conditions are:
+
+- A shipment has a maximum weight of 2311 kg
+- One client's parcels may not be in multiple shipments
+- A shipment may contain parcels from multiple clients
+- A single parcel may not be split between shipments
+- The code must be written in Ruby
+- Units of weight don't matter, since there's no need for conversion or split, but for the sake of the exercise, all weight units can be assumed to be in kilograms.
+
+## Dev Comments
+
+This assigment holds as part of its challenge a very complex problem that is fairly well known in the world of combinatronics. I decided to go for a greedy algorithm that simply sorts the clients into a group whenever the maximum weight is reached.
+
+My main focus has been testing and decent packaging of the assignment code. This challenge will be exported as a gem and can be required in existing projects or run independently to generate the output csv.
+
+## Installation
+Add the following line to your application's Gemfile:
+```bash
+gem 'parcels_challenge'
+```
+And then run:
+```bash
+bundle install
+```
+Now in your project, you'll be able to require 'parcels'. The `ShipmentGrouper` is the class you'll want to use.
+
+Alternatively, you can install it globally and it will come with an executable.
+```bash
+gem install parcels_challenge
+```
+
+## Usage
+After installing, you can run in terminal:
+```bash
+parcels_challenge [path_to_csv_file]
+```
+Ensure the CSV conforms to the expected format and file will generated with the default name `shipment_assignment.csv`
+
+To test from an Interactive Ruby session, try the following:
+```Ruby
+3.2.2 :001 > require 'parcels'
+ => true
+
+3.2.2 :003 > Parcels::ShipmentGrouper.new('spec/fixtures/good_input.csv')
+ =>
+#<Parcels::ShipmentGrouper:0x00007f2791aad808                                                         
+ @file_path="spec/fixtures/good_input.csv",                                                           
+ @output_file_path="shipment_assignment.csv",                                                         
+ @shipment_max_weight=2311,                                                                           
+ @validate_csv=false>                                                 
+3.2.2 :004 > grouper = _
+ =>
+#<Parcels::ShipmentGrouper:0x00007f2791aad808
+...                                
+3.2.2 :005 > file_location = grouper.perform!
+Output file generated at: /home/santi/Personal/parcels/shipment_assignment.csv
+ => "shipment_assignment.csv"                        
+3.2.2 :006 >
+
+```
+
+All the above assuming you're in the root of the repository's directory. If you have a file you'll like to test, make sure to pass the relative path as an argument.
+
+## License
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/license/mit/)

data/bin/parcels_challenge

@@ -0,0 +1,10 @@
+#!/usr/bin/env ruby
+require 'parcels_challenge'
+
+# TODO: Improve me with 'optparse'
+
+if ARGV.empty?
+  puts 'I will need a csv file path, relative path will do just fine.'
+else
+  ParcelsChallenge.group_shipments(ARGV[0])
+end

data/lib/parcels_challenge/shipment_grouper.rb

@@ -0,0 +1,124 @@
+require 'pathname'
+require 'csv'
+
+module ParcelsChallenge
+  class ShipmentGrouper
+    def initialize(
+      file_path,
+      output_file_path = 'shipment_assignment.csv',
+      shipment_max_weight = 2311,
+      validate_csv = false
+    )
+      @shipment_max_weight = shipment_max_weight
+      @validate_csv = validate_csv
+      @output_file_path = output_file_path
+      @file_path = check_file(file_path)
+    end
+
+    def perform!
+      """
+      The perform method is where the magic happens. I've mentally
+      divided this method into the grouping of the clients, assignment
+      of the clients into shipments base on previous groupings and
+      generating the output file.
+      I tried to use CSV's #foreach method as much as possible since
+      it doesn't load the full file into memory. This should be performant
+      in terms of memory but as files get larger and more shipments are
+      possible, so will the amount of client_shipment_assignments grow.
+      """
+      grouped_sum = {}
+
+      CSV.foreach(file_path, headers: true) do |parcel|
+        Integer(parcel['weight']) rescue raise 'Weight is not an Integer'
+        if grouped_sum[parcel['client_name']].nil?
+          grouped_sum[parcel['client_name']] = parcel['weight'].to_i
+        else
+          grouped_sum[parcel['client_name']] += parcel['weight'].to_i
+        end
+      end
+
+      client_shipment_assignment = assign_client_to_shipment(grouped_sum)
+
+      CSV.open(output_file_path, 'wb') do |csv|
+        csv << %i[parcel_ref client_name weight shipment_ref]
+        CSV.foreach(file_path, headers: true) do |parcel|
+          csv << [
+            parcel['parcel_ref'],
+            parcel['client_name'],
+            parcel['weight'],
+            client_shipment_assignment[parcel['client_name']]
+          ]
+        end
+      end
+
+      puts "Output file generated at: #{Pathname.pwd.to_s}/#{output_file_path}"
+
+      output_file_path
+    end
+
+    private
+
+    attr_reader :file_path, :shipment_max_weight, :validate_csv, :output_file_path
+
+    def assign_client_to_shipment(client_grouped_sum)
+      """
+      Assigning clients to shipments is the truly complex part of this project in
+      terms of optimization techniques for the algorithm.
+      Grouping values into shipments base on an upper bound is a form of the
+      subset sum problem. This is an NP-Complete problem and I decided in this case
+      to go for a greedy approach.
+      I extracted this method and tested it separately in case another developer
+      is interested in applying a better heuristic.
+      """
+      raise 'Argument is expected to be a hash' unless client_grouped_sum.is_a?(Hash)
+      client_grouped_sum.each do |key, value|
+        String(key) rescue raise 'Key is not a string'
+        Integer(value) rescue raise 'Value is not an integer'
+      end
+
+      client_shipment_assignment = Hash.new(0)
+      current_shipment = 1
+      current_shipment_value = 0
+
+      client_grouped_sum.each do |name, value|
+        if current_shipment_value + value > shipment_max_weight
+          current_shipment += 1
+          current_shipment_value = 0
+        end
+
+        client_shipment_assignment[name] = "shipment #{current_shipment}"
+        current_shipment_value += value
+      end
+
+      client_shipment_assignment
+    end
+
+    def check_file(file_path)
+      """
+      This is a very generic check where we ensure the file provided
+      exists and the headers those we expect.
+      It also includes an optional validation for the CSV but didn't
+      go deeper into that validation since it can get ugly.
+      """
+      pn = Pathname.new(file_path)
+      raise 'File does not exist' unless pn.exist?
+
+      unless CSV.foreach(file_path).first == ['parcel_ref', 'client_name', 'weight']
+        raise 'Invalid csv headers'
+      end
+
+      # This validation is optional because otherwise it would be one more pass
+      # through the file
+      if validate_csv
+        CSV.foreach(file_path).each do |row|
+          raise 'Invalid number of columns' unless row.length == 3
+          if row[2] != 'weight'
+            Integer(row[2]) rescue raise 'Weight is not an integer (it should be!)'
+          end
+        end
+      end
+
+      file_path
+    end
+  end
+end

data/lib/parcels_challenge/version.rb

@@ -0,0 +1,3 @@
+module ParcelsChallenge
+  VERSION = '0.1.0'
+end

data/lib/parcels_challenge.rb

@@ -0,0 +1,8 @@
+require 'parcels_challenge/version'
+require 'parcels_challenge/shipment_grouper'
+
+module ParcelsChallenge
+  def self.group_shipments(file_path)
+    ShipmentGrouper.new(file_path).perform!
+  end
+end

data/parcels_challenge.gemspec

@@ -0,0 +1,27 @@
+lib = File.expand_path("../lib", __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require "parcels_challenge/version"
+
+Gem::Specification.new do |spec|
+  spec.name          = "parcels_challenge"
+  spec.version       = ParcelsChallenge::VERSION
+  spec.authors       = ["Santiago Baus"]
+  spec.email         = ["sbaus87@gmail.com"]
+
+  spec.summary       = %q{Given a CSV file that contains a list of parcels and their respective weight and client's name, group such parcels into shipments}
+  spec.homepage      = "https://github.com/sbaus42/parcels"
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files -z`.split("\x0").reject do |f|
+    f.match(%r{^(test|spec|features)/})
+  end
+
+  spec.bindir        = "bin"
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "bundler", "~> 2.5.1"
+  spec.add_development_dependency "rake", "~> 13.1.0"
+  spec.add_development_dependency "rspec", "~> 3.12.0"
+  spec.add_development_dependency "pry", "~> 0.14.2"
+end

metadata

@@ -0,0 +1,112 @@
+--- !ruby/object:Gem::Specification
+name: parcels_challenge
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Santiago Baus
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2023-12-22 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 2.5.1
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 2.5.1
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 13.1.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 13.1.0
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 3.12.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 3.12.0
+- !ruby/object:Gem::Dependency
+  name: pry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.14.2
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.14.2
+description: 
+email:
+- sbaus87@gmail.com
+executables:
+- parcels_challenge
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".rspec"
+- Gemfile
+- Gemfile.lock
+- LICENSE
+- README.md
+- bin/parcels_challenge
+- lib/parcels_challenge.rb
+- lib/parcels_challenge/shipment_grouper.rb
+- lib/parcels_challenge/version.rb
+- parcels_challenge.gemspec
+homepage: https://github.com/sbaus42/parcels
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.10
+signing_key: 
+specification_version: 4
+summary: Given a CSV file that contains a list of parcels and their respective weight
+  and client's name, group such parcels into shipments
+test_files: []