group_by_match_type 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 5202086856b91a26669f161ea8edc6982fd6dd8fc6e62e375e4bd334727de16c
+  data.tar.gz: 4b3c5911103ed26e80ffb6ddff7bc77dd3c9b83d7ba19ab0a787c652def1f407
+SHA512:
+  metadata.gz: f5167852ae2269c04129ad5a859af81a2e2addaf90db7db1ca72cbf417df91dac9327f263de05e9a8151e9be8dbd587551693b69875558caf8dec4cdb16ffa30
+  data.tar.gz: 27809eb8566ecc18b886fa35fa300725323db17bb51bda0153c72c99df36ba4acb675a644213a1f756421d95da98700774d67f2855501b1ecf173a00871b1fa5

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 TODO: Write your name
+
+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,65 @@
+# Group By Match Type
+
+A Ruby gem for identifying and grouping CSV records based on matching email or phone number columns.
+
+## Installation
+
+Install the gem by running:
+
+```bash
+gem install group_by_match_type
+```
+
+Or add this line to your application's Gemfile:
+
+```ruby
+gem 'group_by_match_type'
+```
+
+And then execute:
+
+```bash
+bundle install
+```
+
+## Usage
+
+```bash
+group_by_match_type INPUT_FILE MATCHING_TYPE [OUTPUT_FILE]
+```
+
+Available matching types:
+- `same_email`: Groups records with matching email addresses
+- `same_phone`: Groups records with matching phone numbers
+- `same_email_or_phone`: Groups records that share either email or phone number
+
+### Examples:
+```bash
+# Match by email, default output
+ group_by_match_type contacts.csv same_email
+
+# Match by phone, default output
+ group_by_match_type contacts.csv same_phone
+
+# Match by either email or phone, default output
+ group_by_match_type contacts.csv same_email_or_phone
+
+# Specify a custom output file location
+ group_by_match_type contacts.csv same_email ~/Downloads/my_grouped_contacts.csv
+```
+
+## Output
+
+The gem creates a new CSV file with all the original columns plus a new "group_id" column at the end. Records that are considered to be the same person based on the provided matching_type will have the same group_id. If you specify an `OUTPUT_FILE`, the grouped CSV will be written to that location; otherwise, it will be written as `*_grouped.csv` next to your input file.
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](CODE_OF_CONDUCT.md).
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](LICENSE.txt).

data/exe/group_by_match_type

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+
+require 'group_by_match_type'
+require 'group_by_match_type/cli'
+
+GroupByMatchType::CLI.start(ARGV)

data/lib/group_by_match_type/cli.rb

@@ -0,0 +1,57 @@
+require 'optparse'
+require_relative 'matcher'
+
+module GroupByMatchType
+  class CLI
+    VALID_TYPES = %w[same_email same_phone same_email_or_phone]
+
+    def self.start(args)
+      if args.empty? || args.include?('-h') || args.include?('--help')
+        show_help
+        exit(args.empty? ? 1 : 0)
+      end
+
+      if args.length < 2 || args.length > 3
+        puts 'Error: Please provide the input file, matching type, and optionally an output file path'
+        show_help
+        exit 1
+      end
+
+      input_file, matching_type, output_file = args
+
+      unless VALID_TYPES.include?(matching_type)
+        puts "Error: Invalid matching type '#{matching_type}'"
+        show_help
+        exit 1
+      end
+
+      unless File.exist?(input_file)
+        puts "Error: File '#{input_file}' does not exist"
+        exit 1
+      end
+
+      begin
+        matcher = Matcher.new(input_file, matching_type)
+        output = matcher.process(output_file)
+        puts "Processing complete. Output written to: #{output}"
+      rescue StandardError => e
+        puts "Error: #{e.message}"
+        exit 1
+      end
+    end
+
+    def self.show_help
+      puts <<~HELP_MESSAGE
+        Usage: group_by_match_type INPUT_FILE MATCHING_TYPE [OUTPUT_FILE]
+
+        Arguments:
+          INPUT_FILE    Path to the CSV file to process
+          MATCHING_TYPE One of: same_email, same_phone, same_email_or_phone
+          OUTPUT_FILE   (Optional) Path to save the grouped CSV output
+
+        Example:
+          group_by_match_type contacts.csv same_email ~/Downloads/contacts_grouped.csv
+      HELP_MESSAGE
+    end
+  end
+end

data/lib/group_by_match_type/matcher.rb

@@ -0,0 +1,83 @@
+require 'csv'
+require_relative 'union_find'
+
+module GroupByMatchType
+  class Matcher
+    def initialize(input_file, match_type)
+      @input_file = input_file
+      @match_type = match_type
+      @union_find = UnionFind.new
+    end
+
+    def process(output_file = nil)
+      rows = CSV.read(@input_file, headers: true)
+      match_keys = build_match_keys(rows)
+
+      # First pass: create groupings
+      match_keys.each_with_index do |keys, index|
+        @union_find.find_or_create(keys + [index.to_s]) # Ensure uniqueness
+      end
+
+      # Second pass: assign group_ids
+      group_id_map = {}
+      rows.each_with_index do |_, index|
+        root = @union_find.find(index.to_s)
+        group_id_map[root] ||= group_id_map.size + 1
+      end
+
+      # Determine output file path
+      output_file ||= @input_file.sub(/\.csv$/, '_grouped.csv')
+      CSV.open(output_file, 'w') do |csv|
+        csv << rows.headers + ['group_id']
+        rows.each_with_index do |row, index|
+          root = @union_find.find(index.to_s)
+          group_id = group_id_map[root]
+          csv << row.fields + [group_id]
+        end
+      end
+
+      output_file
+    end
+
+    private
+
+    def build_match_keys(rows)
+      rows.map do |row|
+        case @match_type
+        when 'same_email'
+          emails = extract_emails(row)
+          emails.compact.uniq.map(&:downcase).sort
+        when 'same_phone'
+          phones = extract_phones(row)
+          phones.compact.uniq.map { |phone| sanitize_phone(phone) }.compact.sort
+        when 'same_email_or_phone'
+          (extract_emails(row) + extract_phones(row))
+            .compact
+            .map { |value| value.include?('@') ? value.downcase : sanitize_phone(value) }
+            .compact.uniq.sort
+        else
+          raise ArgumentError, "Unknown match type: #{@match_type}"
+        end
+      end
+    end
+
+    def extract_emails(row)
+      row.headers.grep(/email/i).map { |header| row[header]&.strip }
+    end
+
+    def extract_phones(row)
+      row.headers.grep(/phone/i).map { |header| row[header]&.strip }
+    end
+
+    def sanitize_phone(phone)
+      return nil if phone.nil?
+
+      digits = phone.gsub(/\D/, '')
+      if digits.length == 11 && digits.start_with?('1')
+        digits[1..]
+      else
+        digits
+      end
+    end
+  end
+end

data/lib/group_by_match_type/union_find.rb

@@ -0,0 +1,27 @@
+module GroupByMatchType
+  class UnionFind
+    def initialize
+      @parent = {}
+    end
+
+    def find(x)
+      @parent[x] = find(@parent[x]) if @parent[x] && @parent[x] != x
+      @parent[x] ||= x
+    end
+
+    def union(x, y)
+      root_x = find(x)
+      root_y = find(y)
+      @parent[root_x] = root_y unless root_x == root_y
+    end
+
+    def find_or_create(items)
+      return nil if items.empty?
+      items.map!(&:to_s)
+      roots = items.map { |item| find(item) }
+      main_root = roots.first
+      roots[1..].each { |r| union(main_root, r) }
+      main_root
+    end
+  end
+end

data/lib/group_by_match_type/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module GroupByMatchType
+  VERSION = '0.1.0'
+end

data/lib/group_by_match_type.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require_relative 'group_by_match_type/version'
+require_relative 'group_by_match_type/matcher'
+require_relative 'group_by_match_type/cli'
+
+module GroupByMatchType
+  class Error < StandardError; end
+  # Your code goes here...
+end

metadata

@@ -0,0 +1,126 @@
+--- !ruby/object:Gem::Specification
+name: group_by_match_type
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Justin Boltz
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2025-04-19 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: csv
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.21'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.21'
+description: This gem processes CSV files and groups records that might represent
+  the same person based on matching email addresses, phone numbers, or both
+email:
+- boltz.justin@gmail.com
+executables:
+- group_by_match_type
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- README.md
+- exe/group_by_match_type
+- lib/group_by_match_type.rb
+- lib/group_by_match_type/cli.rb
+- lib/group_by_match_type/matcher.rb
+- lib/group_by_match_type/union_find.rb
+- lib/group_by_match_type/version.rb
+homepage: https://github.com/justinboltz/group_by_match_type
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/justinboltz/group_by_match_type
+  source_code_uri: https://github.com/justinboltz/group_by_match_type
+  changelog_uri: https://github.com/justinboltz/group_by_match_type/blob/master/CHANGELOG.md
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.6.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.3
+signing_key:
+specification_version: 4
+summary: A gem for matching and grouping CSV records based on different criteria
+test_files: []