abbu 0.1.2 → 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.1.2'
+  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.1.2
+  version: 0.4.0
 platform: ruby
 authors:
 - Stan Carver II
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-04-26 00:00:00.000000000 Z
+date: 2026-09-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: sqlite3
@@ -38,6 +38,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: plist
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.7'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.7'
 - !ruby/object:Gem::Dependency
   name: guard
   requirement: !ruby/object:Gem::Requirement
@@ -108,6 +122,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.13'
+- !ruby/object:Gem::Dependency
+  name: ruby-lsp
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
 - !ruby/object:Gem::Dependency
   name: rubocop
   requirement: !ruby/object:Gem::Requirement
@@ -178,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:
@@ -188,17 +216,13 @@ executables:
 extensions: []
 extra_rdoc_files: []
 files:
-- CHANGELOG.md
 - 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
+- docs/TODO.md
 - examples/deduplicate_contacts.rb
 - examples/export_to_api.rb
 - examples/export_to_csv.rb
@@ -209,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
@@ -224,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/CHANGELOG.md
+  changelog_uri: https://github.com/scarver2/abbu/blob/main/docs/CHANGELOG.md
   rubygems_mfa_required: 'true'
 post_install_message:
 rdoc_options: []
@@ -234,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/CHANGELOG.md

@@ -1,67 +0,0 @@
-<!-- CHANGELOG.md -->
-
-# Changelog
-
-All notable changes to `abbu` are documented here.
-
-Format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
-Versioning follows [Semantic Versioning](https://semver.org/).
-
----
-
-## [Unreleased]
-
-## [0.1.2] - 2026-04-26
-
-### Added
-
-- Full Apple Contacts schema support: job title, department, maiden name, phonetic names, pronouns, ringtone, texttone
-- Relational table parsing: URLs, notes, related names (family/business), social profiles (Twitter, etc.)
-- Nickname, prefix, and suffix fields with smart `full_name` formatting
-- Hash-based email/phone data preserving custom labels (e.g. "Direct Line", "Work")
-- Address, group, URL, notes, related names, and social profiles in CSV export
-- Comprehensive JSON export with all contact fields
-- vCard 3.0 export with ADR, URL, NICKNAME, TITLE, NOTE, X-SOCIALPROFILE
-- `rubocop-rspec` plugin integration
-- 100% line coverage across all 44 specs
-
-### Changed
-
-- Refactored `SqliteParser` to use `RECORD_FIELD_MAP` constant for maintainability
-- Refactored `CsvExporter` into `core_fields`/`extended_fields` for cleaner ABC metrics
-- All specs comply with rubocop-rspec conventions
-
-## [0.1.1] - 2026-04-23
-
-### Fixed
-
-- `require 'pathname'` missing in `archive.rb` causing `NameError` in isolation
-- Added regression guard spec for file require isolation
-
-
-## [0.1.0] - 2026-04-12
-
-### Added
-
-- `Abbu.open(path)` entry point returning an `Archive`
-- `Archive#contacts` — reads contacts from SQLite or falls back to plist stub
-- `Archive#sqlite?` — detects modern `.abcddb` bundles
-- `Contact` object with `first_name`, `last_name`, `emails`, `phones`, `company`, `full_name`
-- `Parsers::SqliteParser` — queries `ZABCDRECORD`, `ZABCDEMAILADDRESS`, `ZABCDPHONENUMBER`
-- `Parsers::PlistParser` — stub with warning (legacy `.abcdp` support in v0.2)
-- `Exporters::CsvExporter` — `to_file` and `to_stdout`
-- `Exporters::JsonExporter` — `to_file` and `to_stdout`
-- `Exporters::VcardExporter` — `to_file` and `to_stdout` (vCard 3.0)
-- `Utils::Deduplicator` — groups contacts by first email, returns duplicates hash
-- `bin/abbu` CLI with `--format`, `--output`, `--stats`, `--dedupe`, `--version`
-- Rake tasks: `abbu:export`, `abbu:dedupe`, `abbu:stats`
-- Example scripts: CSV, JSON, vCard, API, CRM sync, stats, dedupe
-- `docs/ABBU.md` — file format reference
-- RSpec test suite with 100% coverage target
-- Guard + RuboCop DX loop
-- GitHub Actions CI (Ruby 3.2 + 3.3)
-
----
-Stan Carver II
-Made in Texas 🤠
-https://stancarver.com

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 "$@"