abbu 0.2.0 → 0.4.0

data/lib/abbu/utils/deduplicator.rb

@@ -1,9 +1,61 @@
 # lib/abbu/utils/deduplicator.rb
 # frozen_string_literal: true
 
+require_relative 'contact_identity'
+
 module Abbu
   module Utils
     class Deduplicator
+      class MergePolicyRequired < ArgumentError; end
+
+      class Match
+        attr_reader :left, :right, :evidence, :score, :confidence, :status
+
+        def initialize(left:, right:, evidence:, score:, status:)
+          @left = left
+          @right = right
+          @evidence = evidence.freeze
+          @score = score
+          @confidence = confidence_for(score)
+          @status = status
+          freeze
+        end
+
+        def sources
+          [left.source, right.source].freeze
+        end
+
+        def ambiguous?
+          status == :ambiguous
+        end
+
+        def merge(policy: nil)
+          raise MergePolicyRequired, 'an explicit callable merge policy is required' unless policy.respond_to?(:call)
+
+          policy.call(left, right, evidence: evidence)
+        end
+
+        private
+
+        def confidence_for(value)
+          return :high if value >= 0.8
+          return :medium if value >= 0.6
+
+          :low
+        end
+      end
+
+      WEIGHTS = {
+        email: 0.8,
+        international_phone: 0.65,
+        source_local_phone: 0.45,
+        name: 0.25,
+        organization: 0.15
+      }.freeze
+
+      MINIMUM_SCORE = 0.4
+      PROBABLE_SCORE = 0.6
+
       def initialize(contacts)
         @contacts = contacts
       end
@@ -11,8 +63,84 @@ module Abbu
       def duplicates
         @contacts
           .group_by { |c| c.emails.first }
-          .reject    { |k, _| k.nil? }
-          .select    { |_, v| v.size > 1 }
+          .reject { |k, _| k.nil? }
+          .select { |_, v| v.size > 1 }
+      end
+
+      def matches
+        identities = @contacts.map { |contact| ContactIdentity.new(contact) }
+        candidates = identities.combination(2).filter_map { |left, right| candidate(left, right) }
+        ambiguous_contacts = multiply_matched_contacts(candidates)
+
+        candidates.map do |candidate|
+          build_match(candidate, ambiguous_contacts)
+        end
+      end
+
+      alias identity_matches matches
+
+      private
+
+      def candidate(left, right)
+        evidence = evidence_for(left, right)
+        score = evidence.map { |item| item[:type] }.uniq.sum { |type| WEIGHTS.fetch(type) }.clamp(0.0, 1.0).round(2)
+        return if score < MINIMUM_SCORE
+
+        { left: left.contact, right: right.contact, evidence: evidence, score: score }
+      end
+
+      def evidence_for(left, right)
+        signal_pairs(left, right).flat_map do |left_signals, right_signals, same_source|
+          shared_evidence(left_signals, right_signals, same_source: same_source)
+        end
+      end
+
+      def signal_pairs(left, right)
+        [
+          [left.emails, right.emails, false],
+          [left.phones, right.phones, left.same_source?(right)],
+          [[left.name].compact, [right.name].compact, false],
+          [[left.organization].compact, [right.organization].compact, false]
+        ]
+      end
+
+      def shared_evidence(left_signals, right_signals, same_source: false)
+        left_signals.filter_map do |left|
+          right = right_signals.find { |candidate| comparable?(left, candidate, same_source) }
+          evidence_record(left, right) if right
+        end
+      end
+
+      def comparable?(left, right, same_source)
+        return false unless left.type == right.type && left.normalized == right.normalized
+        return same_source if left.type == :source_local_phone
+
+        true
+      end
+
+      def evidence_record(left, right)
+        {
+          type: left.type,
+          normalized: left.normalized,
+          left_raw: left.raw,
+          right_raw: right.raw
+        }.freeze
+      end
+
+      def multiply_matched_contacts(candidates)
+        counts = Hash.new(0).compare_by_identity
+        candidates.each do |candidate|
+          counts[candidate[:left]] += 1
+          counts[candidate[:right]] += 1
+        end
+        counts.select { |_, count| count > 1 }.keys
+      end
+
+      def build_match(candidate, ambiguous_contacts)
+        ambiguous = candidate[:score] < PROBABLE_SCORE ||
+                    ambiguous_contacts.include?(candidate[:left]) ||
+                    ambiguous_contacts.include?(candidate[:right])
+        Match.new(**candidate, status: ambiguous ? :ambiguous : :probable)
       end
     end
   end

data/lib/abbu/utils/image_resolver.rb

@@ -0,0 +1,59 @@
+# lib/abbu/utils/image_resolver.rb
+# frozen_string_literal: true
+
+require 'pathname'
+
+module Abbu
+  module Utils
+    class ImageResolver
+      EXTENSIONS = %w[jpg jpeg png heic].freeze
+
+      def initialize(bundle_path)
+        @bundle_path = Pathname.new(bundle_path).expand_path
+        @index = build_index
+      end
+
+      def resolve(image_uri, source: nil)
+        return nil if image_uri.nil? || image_uri.to_s.empty?
+
+        candidates = @index.fetch(image_uri.to_s, [])
+        return candidates.first if candidates.one?
+        return if candidates.empty?
+
+        source_local_candidate(candidates, source)
+      end
+
+      def each_image(&)
+        return enum_for(:each_image) unless block_given?
+
+        @index.each_value { |files| files.each(&) }
+      end
+
+      private
+
+      def build_index
+        image_files.each_with_object(Hash.new { |hash, key| hash[key] = [] }) do |file, hash|
+          stem = file.basename('.*').to_s
+          hash[stem] << file
+        end
+      end
+
+      def image_files
+        @bundle_path.glob('**/Images/*').select { |f| f.file? && image_extension?(f) }.sort
+      end
+
+      def image_extension?(file)
+        ext = file.extname.downcase.delete_prefix('.')
+        EXTENSIONS.include?(ext)
+      end
+
+      def source_local_candidate(candidates, source)
+        return unless source
+
+        database = @bundle_path.join(source.fetch(:relative_path, ''))
+        local_images = database.dirname.join('Images').expand_path
+        candidates.find { |candidate| candidate.dirname.expand_path == local_images }
+      end
+    end
+  end
+end

data/lib/abbu/utils/label_normalizer.rb

@@ -0,0 +1,15 @@
+# lib/abbu/utils/label_normalizer.rb
+# frozen_string_literal: true
+
+module Abbu
+  module Utils
+    class LabelNormalizer
+      APPLE_STANDARD_LABEL = /\A_\$!<(?<label>.+)>!\$_\z/
+
+      def self.normalize(label)
+        match = label&.match(APPLE_STANDARD_LABEL)
+        match ? match[:label] : label
+      end
+    end
+  end
+end

data/lib/abbu/utils/source_descriptor.rb

@@ -0,0 +1,35 @@
+# lib/abbu/utils/source_descriptor.rb
+# frozen_string_literal: true
+
+require 'pathname'
+
+module Abbu
+  module Utils
+    class SourceDescriptor
+      def initialize(path, root_path: nil)
+        @path = Pathname.new(path).expand_path
+        @root_path = Pathname.new(root_path).expand_path if root_path
+      end
+
+      def to_h
+        relative_path = relative_path_for(@path)
+        parts = Pathname.new(relative_path).each_filename.to_a
+
+        {
+          path: @path.to_s,
+          relative_path: relative_path,
+          kind: parts.first == 'Sources' ? 'source' : 'root',
+          identifier: parts.first == 'Sources' ? parts[1] : nil
+        }.freeze
+      end
+
+      private
+
+      def relative_path_for(path)
+        return path.basename.to_s unless @root_path
+
+        path.relative_path_from(@root_path).to_s
+      end
+    end
+  end
+end

data/lib/abbu/version.rb

@@ -2,5 +2,5 @@
 # frozen_string_literal: true
 
 module Abbu
-  VERSION = '0.2.0'
+  VERSION = '0.4.0'
 end

data/lib/abbu.rb

@@ -3,16 +3,28 @@
 
 require_relative 'abbu/version'
 require_relative 'abbu/contact'
+require_relative 'abbu/diagnostic'
+require_relative 'abbu/parse_error'
 require_relative 'abbu/archive'
+require_relative 'abbu/live_store'
+require_relative 'abbu/query'
+require_relative 'abbu/schema_inspector'
 require_relative 'abbu/parsers/sqlite_parser'
 require_relative 'abbu/parsers/plist_parser'
 require_relative 'abbu/exporters/csv_exporter'
 require_relative 'abbu/exporters/json_exporter'
 require_relative 'abbu/exporters/vcard_exporter'
+require_relative 'abbu/image_extractor'
+require_relative 'abbu/utils/contact_identity'
 require_relative 'abbu/utils/deduplicator'
+require_relative 'abbu/utils/label_normalizer'
 
 module Abbu
-  def self.open(path)
-    Archive.new(path)
+  def self.open(path, strict: false)
+    Archive.new(path, strict: strict)
+  end
+
+  def self.open_live(path = nil, strict: false)
+    LiveStore.new(path, strict: strict)
   end
 end

data/tasks/abbu.rake

@@ -12,7 +12,7 @@ namespace :abbu do
     CSV.open('contacts.csv', 'w') do |csv|
       csv << %w[Name Email Phone Company]
       archive.contacts.each do |c|
-        csv << [c.full_name, c.emails.first, c.phones.first, c.company]
+        csv << [c.full_name, c.emails.first&.dig(:address), c.phones.first&.dig(:number), c.company]
       end
     end
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: abbu
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Stan Carver II
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-05-03 00:00:00.000000000 Z
+date: 2026-09-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: sqlite3
@@ -206,9 +206,9 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.22'
-description: Parse Apple Address Book Archive (.abbu) files and export contacts to
-  CSV, JSON, or vCard. Supports modern SQLite-backed archives and legacy plist-based
-  records.
+description: Read SQLite and legacy plist .abbu archives or opt into read-only live
+  macOS Contacts access. Query contacts, inspect schemas and diagnostics, compare
+  identity evidence, extract images, and export CSV, JSON, or vCard.
 email:
 - stan@a1webconsulting.com
 executables:
@@ -219,12 +219,6 @@ files:
 - LICENSE
 - README.md
 - bin/abbu
-- bin/cleanse
-- bin/console
-- bin/dev
-- bin/lint
-- bin/outdated
-- bin/test
 - docs/ABBU.md
 - docs/CHANGELOG.md
 - docs/CONTRIBUTING.md
@@ -239,12 +233,22 @@ files:
 - lib/abbu.rb
 - lib/abbu/archive.rb
 - lib/abbu/contact.rb
+- lib/abbu/diagnostic.rb
 - lib/abbu/exporters/csv_exporter.rb
 - lib/abbu/exporters/json_exporter.rb
 - lib/abbu/exporters/vcard_exporter.rb
+- lib/abbu/image_extractor.rb
+- lib/abbu/live_store.rb
+- lib/abbu/parse_error.rb
 - lib/abbu/parsers/plist_parser.rb
 - lib/abbu/parsers/sqlite_parser.rb
+- lib/abbu/query.rb
+- lib/abbu/schema_inspector.rb
+- lib/abbu/utils/contact_identity.rb
 - lib/abbu/utils/deduplicator.rb
+- lib/abbu/utils/image_resolver.rb
+- lib/abbu/utils/label_normalizer.rb
+- lib/abbu/utils/source_descriptor.rb
 - lib/abbu/version.rb
 - tasks/abbu.rake
 homepage: https://github.com/scarver2/abbu
@@ -254,7 +258,7 @@ metadata:
   allowed_push_host: https://rubygems.org
   homepage_uri: https://github.com/scarver2/abbu
   source_code_uri: https://github.com/scarver2/abbu
-  changelog_uri: https://github.com/scarver2/abbu/blob/master/docs/CHANGELOG.md
+  changelog_uri: https://github.com/scarver2/abbu/blob/main/docs/CHANGELOG.md
   rubygems_mfa_required: 'true'
 post_install_message:
 rdoc_options: []
@@ -264,15 +268,15 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '3.2'
+      version: '3.3'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.19
+rubygems_version: 3.5.22
 signing_key:
 specification_version: 4
-summary: Read and process Apple Contacts .abbu archives in Ruby.
+summary: Read-only Apple Contacts toolkit for archives and live macOS stores.
 test_files: []

data/bin/cleanse

@@ -1,7 +0,0 @@
-#!/usr/bin/env bash
-# bin/cleanse
-set -euo pipefail
-
-cd "$(dirname "$0")/.."
-
-exec bundle exec rubocop -A "$@"

data/bin/console

@@ -1,10 +0,0 @@
-#!/usr/bin/env ruby
-# bin/console
-# frozen_string_literal: true
-
-$LOAD_PATH.unshift File.expand_path('../lib', __dir__)
-
-require "irb"
-require "abbu"
-
-IRB.start(__FILE__)

data/bin/dev

@@ -1,7 +0,0 @@
-#!/usr/bin/env bash
-# bin/dev
-set -euo pipefail
-
-cd "$(dirname "$0")/.."
-
-exec bundle exec guard

data/bin/lint

@@ -1,7 +0,0 @@
-#!/usr/bin/env bash
-# bin/lint
-set -euo pipefail
-
-cd "$(dirname "$0")/.."
-
-exec bundle exec rubocop "$@"

data/bin/outdated

@@ -1,7 +0,0 @@
-#!/usr/bin/env bash
-# bin/outdated
-set -euo pipefail
-
-cd "$(dirname "$0")/.."
-
-exec bundle outdated "$@"

data/bin/test

@@ -1,7 +0,0 @@
-#!/usr/bin/env bash
-# bin/test
-set -euo pipefail
-
-cd "$(dirname "$0")/.."
-
-exec bundle exec rspec "$@"