abbu 0.2.0 → 0.8.1

data/lib/abbu/source.rb

@@ -0,0 +1,53 @@
+# lib/abbu/source.rb
+# frozen_string_literal: true
+
+require_relative 'group_catalog'
+require_relative 'query'
+
+module Abbu
+  # An observed input container, not an inferred Apple account or provider.
+  # Metadata and membership are frozen; contacts retain their existing mutability.
+  class Source
+    attr_reader :path, :relative_path, :kind, :identifier, :files, :contacts, :group_names, :groups
+
+    def initialize(path:, relative_path:, identifier:, files:, contacts:)
+      @path = copy_string(path)
+      @relative_path = copy_string(relative_path)
+      @identifier = copy_string(identifier)
+      @kind = identifier.nil? ? 'root' : 'source'
+      @files = snapshot_files(files)
+      @contacts = Query.new(contacts.to_a.dup).freeze
+      @group_names = snapshot_group_names
+      @groups = GroupCatalog.new(@contacts).groups
+      freeze
+    end
+
+    # No currently supported evidence identifies an account provider.
+    def provider
+      nil
+    end
+
+    def groups_for(contact)
+      groups.select { |group| group.include?(contact) }
+    end
+
+    def to_h
+      { path: path, relative_path: relative_path, kind: kind, identifier: identifier,
+        provider: provider, files: files, contact_count: contacts.count, group_names: group_names }
+    end
+
+    private
+
+    def copy_string(value)
+      value&.dup&.freeze
+    end
+
+    def snapshot_files(files)
+      files.map { |file| file.transform_values { |value| copy_string(value) }.freeze }.freeze
+    end
+
+    def snapshot_group_names
+      @contacts.flat_map(&:groups).compact.uniq.sort.map { |name| copy_string(name) }.freeze
+    end
+  end
+end

data/lib/abbu/source_catalog.rb

@@ -0,0 +1,32 @@
+# lib/abbu/source_catalog.rb
+# frozen_string_literal: true
+
+require 'pathname'
+require_relative 'source'
+require_relative 'utils/source_descriptor'
+
+module Abbu
+  # Internal adapter over the same file descriptors used by the parsers.
+  class SourceCatalog
+    def initialize(paths, root_path:, contacts:)
+      @root_path = Pathname.new(root_path).expand_path
+      @files = paths.map { |path| Utils::SourceDescriptor.new(path, root_path: root_path).to_h }
+                    .sort_by { |file| file.fetch(:relative_path) }
+      @contacts_by_path = contacts.group_by { |contact| contact.source&.fetch(:path, nil) }
+    end
+
+    def sources
+      @files.group_by { |file| file.fetch(:identifier) }.map do |identifier, files|
+        relative_path = identifier.nil? ? '.' : "Sources/#{identifier}"
+        Source.new(path: @root_path.join(relative_path).to_s, relative_path: relative_path,
+                   identifier: identifier, files: files, contacts: contacts_for(files))
+      end.sort_by(&:relative_path).freeze
+    end
+
+    private
+
+    def contacts_for(files)
+      files.flat_map { |file| @contacts_by_path.fetch(file.fetch(:path), []) }
+    end
+  end
+end

data/lib/abbu/timestamp_range.rb

@@ -0,0 +1,40 @@
+# lib/abbu/timestamp_range.rb
+# frozen_string_literal: true
+
+require 'date'
+
+module Abbu
+  # Internal filter over observed timestamps, never a claim about human edits.
+  class TimestampRange
+    FORMAT = /\A\d{4}-\d{2}-\d{2}T(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|[+-](?:[01]\d|2[0-3]):[0-5]\d)\z/
+
+    def initialize(field, since: nil, before: nil)
+      raise ArgumentError, 'field must be :created_at or :modified_at' unless %i[created_at modified_at].include?(field)
+      raise ArgumentError, 'at least one timestamp bound is required' if since.nil? && before.nil?
+
+      @since = parse(since) unless since.nil?
+      @before = parse(before) unless before.nil?
+      validate_order
+    end
+
+    def include?(value)
+      !value.nil? && (@since.nil? || value >= @since) && (@before.nil? || value < @before)
+    end
+
+    private
+
+    def validate_order
+      raise ArgumentError, 'since must be earlier than before' if @since && @before && @since >= @before
+    end
+
+    def parse(value)
+      return value if value.is_a?(Time)
+
+      unless value.is_a?(String) && FORMAT.match?(value)
+        raise ArgumentError, 'timestamp must be a Time or ISO 8601 datetime with explicit timezone'
+      end
+
+      DateTime.iso8601(value, Date::GREGORIAN).to_time
+    end
+  end
+end

data/lib/abbu/utils/contact_identity.rb

@@ -0,0 +1,97 @@
+# lib/abbu/utils/contact_identity.rb
+# frozen_string_literal: true
+
+module Abbu
+  module Utils
+    class ContactIdentity
+      Signal = Struct.new(:type, :normalized, :raw, keyword_init: true)
+
+      attr_reader :contact
+
+      def initialize(contact)
+        @contact = contact
+      end
+
+      def emails
+        contact.emails.filter_map do |entry|
+          raw = entry.is_a?(Hash) ? entry[:address] : entry
+          normalized = normalize_email(raw)
+          Signal.new(type: :email, normalized: normalized, raw: raw).freeze if valid_email?(normalized)
+        end
+      end
+
+      def phones
+        contact.phones.filter_map do |entry|
+          raw = entry.is_a?(Hash) ? entry[:number] : entry
+          normalized = normalize_phone(raw)
+          Signal.new(type: phone_type(normalized), normalized: normalized, raw: raw).freeze if normalized
+        end
+      end
+
+      def name
+        signal(:name, contact.full_name)
+      end
+
+      def organization
+        signal(:organization, contact.company)
+      end
+
+      def source
+        contact.source
+      end
+
+      def same_source?(other)
+        source_key = source&.fetch(:relative_path, nil)
+        source_key && source_key == other.source&.fetch(:relative_path, nil)
+      end
+
+      private
+
+      def signal(type, raw)
+        normalized = normalize_text(raw)
+        Signal.new(type: type, normalized: normalized, raw: raw).freeze unless normalized.empty?
+      end
+
+      def normalize_text(value)
+        value.to_s.unicode_normalize(:nfkc).downcase
+             .gsub(/[^\p{Alnum}\p{Mark}]+/u, ' ')
+             .strip
+             .gsub(/\s+/, ' ')
+      end
+
+      def normalize_email(value)
+        value.to_s.unicode_normalize(:nfkc).strip.downcase
+      end
+
+      def valid_email?(value)
+        value.match?(/\A[^@\s]+@[^@\s]+\.[^@\s]+\z/)
+      end
+
+      def normalize_phone(value)
+        raw = value.to_s.strip
+        extension = raw[/\b(?:ext\.?|x)\s*(\d+)\z/i, 1]
+        core = raw.sub(/\b(?:ext\.?|x)\s*\d+\z/i, '')
+        digits = core.gsub(/\D/, '')
+        international = international?(core)
+        digits = digits.delete_prefix('00') if core.start_with?('00')
+        return unless valid_phone_length?(digits, international)
+
+        prefix = international ? '+' : 'national:'
+        normalized = "#{prefix}#{digits}"
+        extension ? "#{normalized};ext=#{extension}" : normalized
+      end
+
+      def valid_phone_length?(digits, international)
+        international ? digits.length.between?(8, 15) : digits.length >= 7
+      end
+
+      def international?(raw)
+        raw.start_with?('+', '00')
+      end
+
+      def phone_type(normalized)
+        normalized.start_with?('+') ? :international_phone : :source_local_phone
+      end
+    end
+  end
+end

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.8.1'
 end

data/lib/abbu.rb

@@ -3,16 +3,29 @@
 
 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/source'
 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/sig/group.rbs

@@ -0,0 +1,36 @@
+# sig/group.rbs
+module Abbu
+  class Contact
+    attr_accessor group_memberships: Array[{ record_id: Integer, name: String? }]
+  end
+
+  class Group
+    attr_reader record_id: Integer
+    attr_reader name: String?
+    attr_reader source: Hash[Symbol, String?]
+    attr_reader contacts: Query
+    def initialize: (record_id: Integer, name: String?, source: Hash[Symbol, String?],
+                     contacts: Enumerable[Contact]) -> void
+    def include?: (Contact contact) -> bool
+    def to_h: () -> Hash[Symbol, untyped]
+  end
+
+  class Source
+    attr_reader groups: Array[Group]
+    def groups_for: (Contact contact) -> Array[Group]
+  end
+
+  class Archive
+    def groups: () -> Array[Group]
+    def groups_for: (Contact contact) -> Array[Group]
+  end
+
+  class LiveStore
+    def groups: () -> Array[Group]
+    def groups_for: (Contact contact) -> Array[Group]
+  end
+
+  class Query
+    def in_group: (Group group) -> Query
+  end
+end

data/sig/query.rbs

@@ -0,0 +1,21 @@
+# sig/query.rbs
+module Abbu
+  class Contact
+  end
+
+  class Query
+    include Enumerable[Contact]
+
+    def initialize: (Enumerable[Contact] contacts) -> void
+    def each: () { (Contact) -> void } -> Array[Contact]
+            | () -> Enumerator[Contact, Array[Contact]]
+    def where: (Hash[Symbol, untyped] criteria) -> Query
+    def search: (String term) -> Query
+    def find_by_email: (String email) -> Query
+    def find_by_phone: (String phone) -> Query
+    def to_a: () -> Array[Contact]
+    def created_since: (Time | String value) -> Query
+    def modified_since: (Time | String value) -> Query
+    def date_range: (:created_at | :modified_at field, ?since: Time | String | nil, ?before: Time | String | nil) -> Query
+  end
+end

data/sig/source.rbs

@@ -0,0 +1,25 @@
+# sig/source.rbs
+module Abbu
+  class Source
+    attr_reader path: String
+    attr_reader relative_path: String
+    attr_reader kind: String
+    attr_reader identifier: String?
+    attr_reader files: Array[Hash[Symbol, String?]]
+    attr_reader contacts: Query
+    attr_reader group_names: Array[String]
+
+    def initialize: (path: String, relative_path: String, identifier: String?,
+                     files: Array[Hash[Symbol, String?]], contacts: Enumerable[Contact]) -> void
+    def provider: () -> nil
+    def to_h: () -> Hash[Symbol, untyped]
+  end
+
+  class Archive
+    def sources: () -> Array[Source]
+  end
+
+  class LiveStore
+    def sources: () -> Array[Source]
+  end
+end

data/sig/vcard_exporter.rbs

@@ -0,0 +1,10 @@
+# sig/vcard_exporter.rbs
+module Abbu
+  module Exporters
+    class VcardExporter
+      def initialize: (Enumerable[Contact] contacts) -> void
+      def to_file: (String | Pathname path) -> Integer
+      def to_stdout: () -> nil
+    end
+  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