abbu 0.2.0 → 0.4.0

data/lib/abbu/archive.rb

@@ -2,26 +2,62 @@
 # frozen_string_literal: true
 
 require 'pathname'
-require_relative 'parsers/sqlite_parser'
+require_relative 'diagnostic'
+require_relative 'image_extractor'
+require_relative 'parse_error'
 require_relative 'parsers/plist_parser'
+require_relative 'parsers/sqlite_parser'
+require_relative 'query'
+require_relative 'schema_inspector'
+require_relative 'utils/image_resolver'
 
 module Abbu
   class Archive
-    attr_reader :path
+    attr_reader :diagnostics, :path
 
-    def initialize(path)
+    def initialize(path, strict: false)
       @path = Pathname.new(path)
+      @strict = strict
+      @diagnostics = []
       validate!
     end
 
     def contacts
-      parser.contacts
+      @contacts ||= parser.contacts.tap { |cs| attach_images(cs) }
+    end
+
+    def query
+      Query.new(contacts)
+    end
+
+    def where(criteria)
+      query.where(criteria)
+    end
+
+    def search(term)
+      query.search(term)
+    end
+
+    def find_by_email(email)
+      query.find_by_email(email)
+    end
+
+    def find_by_phone(phone)
+      query.find_by_phone(phone)
     end
 
     def sqlite?
       db_paths.any?
     end
 
+    def extract_images(output_dir)
+      ImageExtractor.new(contacts).extract(output_dir)
+    end
+
+    def schema_report
+      SchemaInspector.new(db_paths, root_path: @path).report
+    end
+
     private
 
     def validate!
@@ -39,10 +75,34 @@ module Abbu
 
     def parser
       if sqlite?
-        Parsers::SqliteParser.new(db_paths)
+        Parsers::SqliteParser.new(db_paths, root_path: @path, diagnostics: diagnostics, strict: @strict)
       else
-        Parsers::PlistParser.new(plist_paths)
+        Parsers::PlistParser.new(plist_paths, root_path: @path, diagnostics: diagnostics, strict: @strict)
       end
     end
+
+    def attach_images(contacts)
+      return if contacts.empty?
+
+      resolver = Utils::ImageResolver.new(@path)
+      contacts.each do |contact|
+        next unless contact.image_uri
+
+        contact.image_path = resolver.resolve(contact.image_uri, source: contact.source)
+        record_missing_image(contact) unless contact.image_path
+      end
+    end
+
+    def record_missing_image(contact)
+      diagnostic = Diagnostic.new(
+        category: :missing_image,
+        message: 'Referenced contact image was not found',
+        parser: :archive,
+        source: contact.source&.fetch(:path, @path.to_s) || @path.to_s,
+        context: {}
+      )
+      diagnostics << diagnostic
+      raise ParseError, diagnostic if @strict
+    end
   end
 end

data/lib/abbu/contact.rb

@@ -10,7 +10,9 @@ module Abbu
                   :phonetic_company, :pronouns, :ringtone, :texttone,
                   :urls, :notes, :related_names, :social_profiles,
                   :birthday, :anniversary, :dates, :instant_messages,
-                  :verification_code, :lunar_birthday
+                  :verification_code, :lunar_birthday,
+                  :image_uri, :image_path,
+                  :created_at, :modified_at, :source
 
     def initialize
       @emails = []

data/lib/abbu/diagnostic.rb

@@ -0,0 +1,27 @@
+# lib/abbu/diagnostic.rb
+# frozen_string_literal: true
+
+module Abbu
+  class Diagnostic
+    attr_reader :category, :context, :message, :parser, :source
+
+    def initialize(category:, message:, parser:, source:, context: {})
+      @category = category.to_sym
+      @context = context.freeze
+      @message = message.to_s.freeze
+      @parser = parser.to_sym
+      @source = source.to_s.freeze
+      freeze
+    end
+
+    def to_h
+      {
+        category: category,
+        message: message,
+        parser: parser,
+        source: source,
+        context: context
+      }
+    end
+  end
+end

data/lib/abbu/exporters/csv_exporter.rb

@@ -28,7 +28,7 @@ module Abbu
 
       def headers
         %w[Name First Middle Last Email Phone Company Address Groups URLs Notes RelatedNames SocialProfiles Birthday
-           Anniversary InstantMessages VerificationCode LunarBirthday]
+           Anniversary InstantMessages VerificationCode LunarBirthday ImagePath]
       end
 
       def row(contact)
@@ -50,7 +50,7 @@ module Abbu
           format_related_names(contact.related_names), format_social_profiles(contact.social_profiles),
           format_date(contact.birthday), format_date(contact.anniversary),
           format_instant_messages(contact.instant_messages), contact.verification_code,
-          format_date(contact.lunar_birthday)
+          format_date(contact.lunar_birthday), contact.image_path.to_s
         ]
       end
 

data/lib/abbu/exporters/json_exporter.rb

@@ -2,6 +2,7 @@
 # frozen_string_literal: true
 
 require 'json'
+require 'time'
 
 module Abbu
   module Exporters
@@ -52,7 +53,12 @@ module Abbu
           dates: contact.dates,
           instant_messages: contact.instant_messages,
           verification_code: contact.verification_code,
-          lunar_birthday: contact.lunar_birthday
+          lunar_birthday: contact.lunar_birthday,
+          image_uri: contact.image_uri,
+          image_path: contact.image_path&.to_s,
+          created_at: contact.created_at&.iso8601,
+          modified_at: contact.modified_at&.iso8601,
+          source: contact.source
         }.compact
       end
     end

data/lib/abbu/exporters/vcard_exporter.rb

@@ -1,6 +1,8 @@
 # lib/abbu/exporters/vcard_exporter.rb
 # frozen_string_literal: true
 
+require 'uri'
+
 module Abbu
   module Exporters
     class VcardExporter
@@ -35,6 +37,7 @@ module Abbu
         append_instant_messages(lines, contact)
         append_verification_code(lines, contact)
         append_notes(lines, contact)
+        append_photo(lines, contact)
 
         lines << 'END:VCARD'
         lines.join("\n")
@@ -75,6 +78,17 @@ module Abbu
         lines << "X-VERIFICATION-CODE:#{contact.verification_code}" if contact.verification_code
       end
 
+      def append_photo(lines, contact)
+        return unless contact.image_path
+
+        lines << "PHOTO;VALUE=URI:#{file_uri(contact.image_path)}"
+      end
+
+      def file_uri(path)
+        escaped_path = URI::DEFAULT_PARSER.escape(path.to_s)
+        URI::Generic.build(scheme: 'file', path: escaped_path)
+      end
+
       def append_notes(lines, contact)
         contact.notes.each { |n| lines << "NOTE:#{n}" }
       end
@@ -125,7 +139,11 @@ module Abbu
         return unless contact.anniversary
 
         lines << "X-ABDATE;type=pref:#{format_vcard_date(contact.anniversary)}"
-        lines << 'X-ABLABEL:_$!<Anniversary>!$_'
+        lines << "X-ABLABEL:#{anniversary_label(contact.anniversary)}"
+      end
+
+      def anniversary_label(anniversary)
+        anniversary[:raw_label] || anniversary[:label] || 'Anniversary'
       end
 
       def format_vcard_date(date)

data/lib/abbu/image_extractor.rb

@@ -0,0 +1,134 @@
+# lib/abbu/image_extractor.rb
+# frozen_string_literal: true
+
+require 'digest'
+require 'fileutils'
+require 'pathname'
+
+module Abbu
+  class ImageExtractor
+    Result = Struct.new(:files, :diagnostics, keyword_init: true)
+
+    SIGNATURES = {
+      jpeg: { extension: 'jpg', media_type: 'image/jpeg' },
+      png: { extension: 'png', media_type: 'image/png' },
+      gif: { extension: 'gif', media_type: 'image/gif' },
+      heic: { extension: 'heic', media_type: 'image/heic' }
+    }.freeze
+
+    def initialize(contacts)
+      @contacts = contacts
+    end
+
+    def extract(output_dir)
+      destination = Pathname.new(output_dir).expand_path
+      FileUtils.mkdir_p(destination)
+      destination = destination.realpath
+      files = []
+      diagnostics = []
+      used_names = Hash.new(0)
+
+      @contacts.each do |contact|
+        extract_contact(contact, destination, files, diagnostics, used_names)
+      end
+
+      Result.new(files: files.freeze, diagnostics: diagnostics.freeze).freeze
+    end
+
+    private
+
+    def extract_contact(contact, destination, files, diagnostics, used_names)
+      return unless contact.image_uri
+
+      source = contact.image_path
+      return add_diagnostic(diagnostics, :missing_image, contact, source) unless source&.file?
+
+      type = detect_type(source)
+      return add_diagnostic(diagnostics, :unsupported_image, contact, source) unless type
+
+      target = destination.join(unique_filename(contact, source, type[:extension], used_names))
+      return add_diagnostic(diagnostics, :destination_exists, contact, source) unless copy_image(source, target)
+
+      files << file_record(contact, source, target, type)
+    rescue IOError, SystemCallError => e
+      add_diagnostic(diagnostics, :unreadable_image, contact, source, e.message)
+    end
+
+    def copy_image(source, target)
+      File.open(target, File::WRONLY | File::CREAT | File::EXCL, 0o600) do |output|
+        source.open('rb') { |input| IO.copy_stream(input, output) }
+      end
+      true
+    rescue Errno::EEXIST
+      false
+    end
+
+    def detect_type(path)
+      header = path.open('rb') { |file| file.read(32) }.to_s.b
+      SIGNATURES[kind_for(header)]
+    end
+
+    def kind_for(header)
+      return :jpeg if header.start_with?("\xFF\xD8\xFF".b)
+      return :png if header.start_with?("\x89PNG\r\n\x1A\n".b)
+      return :gif if header.start_with?('GIF87a', 'GIF89a')
+
+      :heic if heic?(header)
+    end
+
+    def heic?(header)
+      header.byteslice(4, 4) == 'ftyp' && %w[heic heix hevc hevx mif1 msf1].include?(header.byteslice(8, 4))
+    end
+
+    def unique_filename(contact, source, extension, used_names)
+      readable = sanitize(contact.full_name)
+      readable = 'contact' if readable.empty?
+      identifier = sanitize(contact.image_uri.to_s)
+      identifier = 'image' if identifier.empty?
+      fingerprint = Digest::SHA256.hexdigest(provenance_key(contact, source))[0, 10]
+      base = [readable, identifier, fingerprint].join('--')
+      used_names[base] += 1
+      suffix = used_names[base] == 1 ? '' : "-#{used_names[base]}"
+      "#{base}#{suffix}.#{extension}"
+    end
+
+    def sanitize(value)
+      value.unicode_normalize(:nfc)
+           .gsub(%r{[\\/:*?"<>|\p{Cntrl}]+}u, '-')
+           .gsub(/[^\p{Alnum}\p{Mark}_ -]+/u, '-')
+           .strip
+           .gsub(/[ .-]+\z/, '')
+           .gsub(/\s+/, '-')
+           .squeeze('-')
+           .then { |name| name[0, 80] }
+    end
+
+    def provenance_key(contact, source)
+      [contact.source&.fetch(:relative_path, nil), source.expand_path, contact.full_name, contact.image_uri].join("\0")
+    end
+
+    def file_record(contact, source, target, type)
+      {
+        contact: contact,
+        image_uri: contact.image_uri,
+        source_path: source.expand_path,
+        path: target,
+        media_type: type[:media_type]
+      }.freeze
+    end
+
+    def diagnostic(code, contact, source, detail = nil)
+      {
+        code: code,
+        contact_name: contact.full_name,
+        image_uri: contact.image_uri,
+        source_path: source&.expand_path,
+        detail: detail
+      }.compact.freeze
+    end
+
+    def add_diagnostic(diagnostics, code, contact, source, detail = nil)
+      diagnostics << diagnostic(code, contact, source, detail)
+    end
+  end
+end

data/lib/abbu/live_store.rb

@@ -0,0 +1,104 @@
+# lib/abbu/live_store.rb
+# frozen_string_literal: true
+
+require 'pathname'
+require 'sqlite3'
+require_relative 'parsers/sqlite_parser'
+
+module Abbu
+  class LiveStore
+    DATABASE_GLOB = 'AddressBook-v*.abcddb'
+    DEFAULT_RELATIVE_PATH = 'Library/Application Support/AddressBook'
+
+    class Error < StandardError; end
+    class NotFoundError < Error; end
+    class PermissionError < Error; end
+    class UnsupportedPlatformError < Error; end
+
+    attr_reader :diagnostics, :path
+
+    def self.default_path(home: Dir.home, platform: RUBY_PLATFORM)
+      unless platform.include?('darwin')
+        raise UnsupportedPlatformError,
+              'Automatic live Contacts discovery is available only on macOS; supply an AddressBook directory path.'
+      end
+
+      Pathname.new(home).join(DEFAULT_RELATIVE_PATH)
+    end
+
+    def initialize(path = nil, strict: false)
+      @strict = strict
+      @diagnostics = []
+      @path = Pathname.new(path || self.class.default_path).expand_path
+      validate!
+    end
+
+    def contacts
+      @contacts ||= Parsers::SqliteParser.new(
+        database_paths, root_path: @path, readonly: true, diagnostics: diagnostics, strict: @strict
+      ).contacts
+    rescue SQLite3::CantOpenException, Errno::EACCES => e
+      raise permission_error(e.message)
+    end
+
+    def database_paths
+      @database_paths ||= discover_database_paths.tap do |paths|
+        raise NotFoundError, missing_database_message if paths.empty?
+      end
+    end
+
+    private
+
+    def validate!
+      stat = @path.stat
+      raise NotFoundError, "Live Contacts store is not a directory: #{@path}" unless stat.directory?
+
+      ensure_readable_directory!(@path)
+    rescue Errno::ENOENT
+      raise NotFoundError, "Live Contacts store not found: #{@path}"
+    rescue Errno::EACCES => e
+      raise permission_error(e.message)
+    end
+
+    def discover_database_paths
+      paths = @path.glob(DATABASE_GLOB)
+      sources_path = @path.join('Sources')
+      paths.concat(source_database_paths(sources_path)) if sources_path.exist?
+      paths.sort.each { |db_path| ensure_readable_file!(db_path) }
+    rescue Errno::EACCES => e
+      raise permission_error(e.message)
+    end
+
+    def source_database_paths(sources_path)
+      ensure_readable_directory!(sources_path)
+      sources_path.children.sort.select(&:directory?).flat_map do |source_path|
+        ensure_readable_directory!(source_path)
+        source_path.glob(DATABASE_GLOB)
+      end
+    end
+
+    def ensure_readable_directory!(path)
+      return if path.readable? && path.executable?
+
+      raise permission_error("directory is not readable: #{path}")
+    end
+
+    def ensure_readable_file!(path)
+      return if path.file? && path.readable?
+
+      raise permission_error("database is not readable: #{path}")
+    end
+
+    def missing_database_message
+      "No #{DATABASE_GLOB} databases found in live Contacts store: #{@path}"
+    end
+
+    def permission_error(detail)
+      PermissionError.new(
+        "Cannot read live Contacts store at #{@path} (#{detail}). " \
+        'Grant Full Disk Access to the terminal or application running abbu in ' \
+        'System Settings > Privacy & Security > Full Disk Access, then retry.'
+      )
+    end
+  end
+end

data/lib/abbu/parse_error.rb

@@ -0,0 +1,13 @@
+# lib/abbu/parse_error.rb
+# frozen_string_literal: true
+
+module Abbu
+  class ParseError < StandardError
+    attr_reader :diagnostic
+
+    def initialize(diagnostic)
+      @diagnostic = diagnostic
+      super("#{diagnostic.message} (#{diagnostic.source})")
+    end
+  end
+end

data/lib/abbu/parsers/plist_parser.rb

@@ -3,6 +3,10 @@
 
 require 'plist'
 require_relative '../contact'
+require_relative '../diagnostic'
+require_relative '../parse_error'
+require_relative '../utils/label_normalizer'
+require_relative '../utils/source_descriptor'
 
 module Abbu
   module Parsers
@@ -21,8 +25,13 @@ module Abbu
       }.freeze
 
       # Accepts either a directory path (scans for *.abcdp) or an array of file paths
-      def initialize(paths)
+      attr_reader :diagnostics
+
+      def initialize(paths, root_path: nil, diagnostics: nil, strict: false)
         @paths = resolve_paths(paths)
+        @root_path = root_path
+        @diagnostics = diagnostics || []
+        @strict = strict
       end
 
       def contacts
@@ -45,15 +54,32 @@ module Abbu
 
       def parse_file(file)
         data = Plist.parse_xml(file.to_s)
-        return nil unless data
+        return recover(file) unless data.is_a?(Hash)
+
+        build_contact(data, file)
+      rescue ParseError
+        raise
+      rescue ArgumentError, EOFError, Plist::UnimplementedElementError, SystemCallError, TypeError
+        recover(file)
+      end
 
-        build_contact(data)
+      def recover(file)
+        diagnostic = Diagnostic.new(
+          category: :malformed_record,
+          message: 'Unable to parse plist contact record',
+          parser: :plist,
+          source: file,
+          context: {}
+        )
+        diagnostics << diagnostic
+        raise ParseError, diagnostic if @strict
       end
 
-      def build_contact(data)
+      def build_contact(data, file)
         contact = Contact.new
         assign_flat_fields(contact, data)
         assign_multi_value_fields(contact, data)
+        contact.source = Utils::SourceDescriptor.new(file, root_path: @root_path).to_h
         contact
       end
 
@@ -76,14 +102,14 @@ module Abbu
         contact.birthday = extract_birthday(data)
         contact.lunar_birthday = extract_lunar_birthday(data)
         contact.dates = extract_dates(data)
-        contact.anniversary = contact.dates.find { |d| d[:label] == '_$!<Anniversary>!$_' }
+        contact.anniversary = contact.dates.find { |d| d[:label] == 'Anniversary' }
       end
 
       def extract_labeled_values(data, key, value_key)
         return [] unless data[key]&.dig('values')
 
         data[key]['values'].map do |entry|
-          { value_key => entry['value'], label: entry['label'] }
+          { value_key => entry['value'], **label_fields(entry['label']) }
         end
       end
 
@@ -98,7 +124,7 @@ module Abbu
             state: addr['State'],
             zip: addr['ZIP'],
             country: addr['Country'],
-            label: entry['label']
+            **label_fields(entry['label'])
           }
         end
       end
@@ -122,7 +148,7 @@ module Abbu
 
         data['InstantMessage']['values'].map do |entry|
           msg = entry['value'] || {}
-          { address: msg['address'], label: entry['label'], service: msg['serviceName'] }
+          { address: msg['address'], service: msg['serviceName'], **label_fields(entry['label']) }
         end
       end
 
@@ -130,14 +156,14 @@ module Abbu
         val = data['Birthday']
         return nil unless val.respond_to?(:year)
 
-        { year: val.year, month: val.month, day: val.day, label: '_$!<Birthday>!$_' }
+        { year: val.year, month: val.month, day: val.day, label: 'Birthday', raw_label: nil }
       end
 
       def extract_lunar_birthday(data)
         val = data['LunarBirthday']
         return nil unless val.respond_to?(:year)
 
-        { year: val.year, month: val.month, day: val.day, label: '_$!<LunarBirthday>!$_' }
+        { year: val.year, month: val.month, day: val.day, label: 'LunarBirthday', raw_label: nil }
       end
 
       def extract_dates(data)
@@ -147,9 +173,13 @@ module Abbu
           val = entry['value']
           next unless val.respond_to?(:year)
 
-          { year: val.year, month: val.month, day: val.day, label: entry['label'] }
+          { year: val.year, month: val.month, day: val.day, **label_fields(entry['label']) }
         end
       end
+
+      def label_fields(raw_label)
+        { label: Utils::LabelNormalizer.normalize(raw_label), raw_label: raw_label }
+      end
     end
   end
 end