abbu 0.2.0 → 0.4.0

data/lib/abbu/parsers/sqlite_parser.rb

@@ -3,10 +3,16 @@
 
 require 'sqlite3'
 require_relative '../contact'
+require_relative '../diagnostic'
+require_relative '../parse_error'
+require_relative '../utils/label_normalizer'
+require_relative '../utils/source_descriptor'
 
 module Abbu
   module Parsers
     class SqliteParser # rubocop:disable Metrics/ClassLength
+      APPLE_EPOCH_OFFSET = 978_307_200
+
       # Column-name → attr_accessor mapping for flat fields on ZABCDRECORD
       RECORD_FIELD_MAP = {
         'ZFIRSTNAME' => :first_name, 'ZMIDDLENAME' => :middle_name,
@@ -21,11 +27,20 @@ module Abbu
         'ZPHONETICORGANIZATION' => :phonetic_company,
         'ZPRONOUNS' => :pronouns,
         'ZRINGTONE' => :ringtone, 'ZTEXTTONE' => :texttone,
-        'ZVERIFICATIONCODE' => :verification_code
+        'ZVERIFICATIONCODE' => :verification_code,
+        'ZIMAGEURI' => :image_uri
       }.freeze
 
-      def initialize(db_paths)
+      attr_reader :diagnostics
+
+      def initialize(db_paths, root_path: nil, readonly: false, diagnostics: nil, strict: false)
         @db_paths = Array(db_paths)
+        @readonly = readonly
+        @root_path = root_path
+        @diagnostics = diagnostics || []
+        @missing_optional_tables = {}
+        @strict = strict
+        @table_presence = {}
       end
 
       def contacts
@@ -37,9 +52,10 @@ module Abbu
       private
 
       def parse_db(db_path)
-        db = SQLite3::Database.new(db_path.to_s)
+        @active_db_path = db_path
+        db = SQLite3::Database.new(db_path.to_s, readonly: @readonly)
         db.results_as_hash = true
-        records(db).map { |row| build_contact(db, row) }
+        records(db).filter_map { |row| build_contact(db, row, db_path) }
       ensure
         db&.close
       end
@@ -47,38 +63,46 @@ module Abbu
       def records(db)
         # Exclude groups (typically Z_ENT = 15 in this schema version)
         db.execute('SELECT * FROM ZABCDRECORD WHERE Z_ENT != 15')
+      rescue SQLite3::Exception
+        fail_required_schema(@active_db_path)
       end
 
       def emails_for(db, record_id)
-        db.execute(
-          'SELECT ZADDRESSNORMALIZED, ZLABEL FROM ZABCDEMAILADDRESS WHERE ZOWNER = ?',
-          record_id
-        ).map { |row| { address: row['ZADDRESSNORMALIZED'], label: row['ZLABEL'] } }
+        query = 'SELECT ZADDRESSNORMALIZED, ZLABEL FROM ZABCDEMAILADDRESS WHERE ZOWNER = ?'
+        optional_rows(db, record_id, 'ZABCDEMAILADDRESS', query).map do |row|
+          { address: row['ZADDRESSNORMALIZED'], **label_fields(row['ZLABEL']) }
+        end
       end
 
       def phones_for(db, record_id)
-        db.execute(
-          'SELECT ZFULLNUMBER, ZLABEL FROM ZABCDPHONENUMBER WHERE ZOWNER = ?',
-          record_id
-        ).map { |row| { number: row['ZFULLNUMBER'], label: row['ZLABEL'] } }
+        query = 'SELECT ZFULLNUMBER, ZLABEL FROM ZABCDPHONENUMBER WHERE ZOWNER = ?'
+        optional_rows(db, record_id, 'ZABCDPHONENUMBER', query).map do |row|
+          { number: row['ZFULLNUMBER'], **label_fields(row['ZLABEL']) }
+        end
       end
 
       def addresses_for(db, record_id) # rubocop:disable Metrics/MethodLength
-        db.execute(
-          'SELECT ZSTREET, ZCITY, ZSTATE, ZZIPCODE, ZCOUNTRYNAME, ZLABEL FROM ZABCDPOSTALADDRESS WHERE ZOWNER = ?',
-          record_id
-        ).map do |row|
+        query = 'SELECT ZSTREET, ZCITY, ZSTATE, ZZIPCODE, ZCOUNTRYNAME, ZLABEL ' \
+                'FROM ZABCDPOSTALADDRESS WHERE ZOWNER = ?'
+        optional_rows(db, record_id, 'ZABCDPOSTALADDRESS', query).map do |row|
           {
             street: row['ZSTREET'],
             city: row['ZCITY'],
             state: row['ZSTATE'],
             zip: row['ZZIPCODE'],
             country: row['ZCOUNTRYNAME'],
-            label: row['ZLABEL']
+            **label_fields(row['ZLABEL'])
           }
         end
       end
 
+      def table_exists?(db, table_name)
+        key = [@active_db_path.to_s, table_name]
+        @table_presence.fetch(key) do
+          @table_presence[key] = db.table_info(table_name).any?
+        end
+      end
+
       def groups_for(db, record_id)
         query = <<-SQL
           SELECT g.ZFIRSTNAME
@@ -86,76 +110,123 @@ module Abbu
           JOIN ZABCDRECORD g ON j.Z_GROUP = g.Z_PK
           WHERE j.Z_CONTACT = ?
         SQL
-        db.execute(query, record_id).map { |row| row['ZFIRSTNAME'] }
-      rescue SQLite3::SQLException
-        []
+        optional_rows(db, record_id, 'Z_ABCDCONTACTGROUP', query).map { |row| row['ZFIRSTNAME'] }
       end
 
       def urls_for(db, record_id)
-        db.execute(
-          'SELECT ZURL, ZLABEL FROM ZABCDURLADDRESS WHERE ZOWNER = ?',
-          record_id
-        ).map { |row| { url: row['ZURL'], label: row['ZLABEL'] } }
-      rescue SQLite3::SQLException
-        []
+        query = 'SELECT ZURL, ZLABEL FROM ZABCDURLADDRESS WHERE ZOWNER = ?'
+        optional_rows(db, record_id, 'ZABCDURLADDRESS', query).map do |row|
+          { url: row['ZURL'], **label_fields(row['ZLABEL']) }
+        end
       end
 
       def notes_for(db, record_id)
-        db.execute(
-          'SELECT ZTEXT FROM ZABCDNOTE WHERE ZCONTACT = ?',
-          record_id
-        ).filter_map { |row| row['ZTEXT'] }
-      rescue SQLite3::SQLException
-        []
+        query = 'SELECT ZTEXT FROM ZABCDNOTE WHERE ZCONTACT = ?'
+        optional_rows(db, record_id, 'ZABCDNOTE', query).filter_map { |row| row['ZTEXT'] }
       end
 
       def related_names_for(db, record_id)
-        db.execute(
-          'SELECT ZNAME, ZLABEL FROM ZABCDRELATEDNAME WHERE ZOWNER = ?',
-          record_id
-        ).map { |row| { name: row['ZNAME'], label: row['ZLABEL'] } }
-      rescue SQLite3::SQLException
-        []
+        query = 'SELECT ZNAME, ZLABEL FROM ZABCDRELATEDNAME WHERE ZOWNER = ?'
+        optional_rows(db, record_id, 'ZABCDRELATEDNAME', query).map do |row|
+          { name: row['ZNAME'], **label_fields(row['ZLABEL']) }
+        end
       end
 
       def social_profiles_for(db, record_id)
-        db.execute(
-          'SELECT ZSERVICENAME, ZUSERNAME FROM ZABCDSOCIALPROFILE WHERE ZOWNER = ?',
-          record_id
-        ).map { |row| { service: row['ZSERVICENAME'], username: row['ZUSERNAME'] } }
-      rescue SQLite3::SQLException
-        []
+        query = 'SELECT ZSERVICENAME, ZUSERNAME FROM ZABCDSOCIALPROFILE WHERE ZOWNER = ?'
+        optional_rows(db, record_id, 'ZABCDSOCIALPROFILE', query).map do |row|
+          { service: row['ZSERVICENAME'], username: row['ZUSERNAME'] }
+        end
       end
 
       def dates_for(db, record_id)
-        db.execute(
-          'SELECT ZYEAR, ZMONTH, ZDAY, ZLABEL FROM ZABCDDATECOMPONENTS WHERE ZOWNER = ?',
-          record_id
-        ).map do |row|
-          { year: row['ZYEAR'], month: row['ZMONTH'], day: row['ZDAY'], label: row['ZLABEL'] }
-        end
-      rescue SQLite3::SQLException
-        []
+        query = 'SELECT ZYEAR, ZMONTH, ZDAY, ZLABEL FROM ZABCDDATECOMPONENTS WHERE ZOWNER = ?'
+        optional_rows(db, record_id, 'ZABCDDATECOMPONENTS', query).map { |row| date_from(row) }
       end
 
       def instant_messages_for(db, record_id)
-        db.execute(
-          'SELECT ZADDRESS, ZLABEL, ZSERVICENAME FROM ZABCDMESSAGINGADDRESS WHERE ZOWNER = ?',
-          record_id
-        ).map do |row|
-          { address: row['ZADDRESS'], label: row['ZLABEL'], service: row['ZSERVICENAME'] }
+        query = 'SELECT ZADDRESS, ZLABEL, ZSERVICENAME FROM ZABCDMESSAGINGADDRESS WHERE ZOWNER = ?'
+        optional_rows(db, record_id, 'ZABCDMESSAGINGADDRESS', query).map do |row|
+          { address: row['ZADDRESS'], service: row['ZSERVICENAME'], **label_fields(row['ZLABEL']) }
         end
-      rescue SQLite3::SQLException
-        []
       end
 
-      def build_contact(db, row)
+      def optional_rows(db, record_id, table, query)
+        return missing_optional_table(table) unless table_exists?(db, table)
+
+        db.execute(query, record_id)
+      end
+
+      def missing_optional_table(table)
+        key = [@active_db_path.to_s, table]
+        return [] if @missing_optional_tables[key]
+
+        @missing_optional_tables[key] = true
+        recover(optional_diagnostic(table), fallback: [])
+      end
+
+      def optional_diagnostic(table)
+        Diagnostic.new(
+          category: :missing_optional_data,
+          message: 'Optional SQLite table is unavailable',
+          parser: :sqlite,
+          source: @active_db_path,
+          context: { table: table }.freeze
+        )
+      end
+
+      def fail_required_schema(db_path)
+        diagnostic = Diagnostic.new(
+          category: :required_schema,
+          message: 'Required SQLite contact schema is unavailable',
+          parser: :sqlite,
+          source: db_path,
+          context: { table: 'ZABCDRECORD' }.freeze
+        )
+        diagnostics << diagnostic
+        raise ParseError, diagnostic
+      end
+
+      def build_contact(db, row, db_path)
         contact = Contact.new
         assign_flat_fields(contact, row)
         assign_relational_fields(contact, db, row['Z_PK'])
+        assign_metadata(contact, row, db_path)
         contact
       end
 
+      def recover(diagnostic, fallback:)
+        diagnostics << diagnostic
+        raise ParseError, diagnostic if @strict
+
+        fallback
+      end
+
+      def assign_metadata(contact, row, db_path)
+        contact.created_at = apple_time(row['ZCREATIONDATE'])
+        contact.modified_at = apple_time(row['ZMODIFICATIONDATE'])
+        contact.source = Utils::SourceDescriptor.new(db_path, root_path: @root_path).to_h
+      end
+
+      def apple_time(value)
+        return if value.nil?
+
+        Time.at(Float(value) + APPLE_EPOCH_OFFSET).utc
+      rescue ArgumentError, RangeError, TypeError
+        nil
+      end
+
+      def label_fields(raw_label)
+        { label: Utils::LabelNormalizer.normalize(raw_label), raw_label: raw_label }
+      end
+
+      def date_from(row)
+        {
+          year: row['ZYEAR'], month: row['ZMONTH'], day: row['ZDAY'],
+          **label_fields(row['ZLABEL'])
+        }
+      end
+
       def assign_flat_fields(contact, row)
         RECORD_FIELD_MAP.each do |column, attr|
           contact.public_send(:"#{attr}=", row[column])
@@ -175,9 +246,9 @@ module Abbu
 
         all_dates = dates_for(db, record_id)
         contact.dates = all_dates
-        contact.birthday    = all_dates.find { |d| d[:label] == '_$!<Birthday>!$_' }
-        contact.anniversary = all_dates.find { |d| d[:label] == '_$!<Anniversary>!$_' }
-        contact.lunar_birthday = all_dates.find { |d| d[:label] == '_$!<LunarBirthday>!$_' }
+        contact.birthday    = all_dates.find { |d| d[:label] == 'Birthday' }
+        contact.anniversary = all_dates.find { |d| d[:label] == 'Anniversary' }
+        contact.lunar_birthday = all_dates.find { |d| d[:label] == 'LunarBirthday' }
       end
     end
   end

data/lib/abbu/query.rb

@@ -0,0 +1,73 @@
+# lib/abbu/query.rb
+# frozen_string_literal: true
+
+module Abbu
+  class Query
+    include Enumerable
+
+    def initialize(contacts)
+      @contacts = contacts.to_a.freeze
+    end
+
+    def each(&)
+      @contacts.each(&)
+    end
+
+    def where(criteria)
+      self.class.new(select { |contact| matches_criteria?(contact, criteria) })
+    end
+
+    def search(term)
+      normalized_term = normalize_email(term)
+      return self.class.new([]) if normalized_term.empty?
+
+      self.class.new(select do |contact|
+        normalize_text(contact.full_name).include?(normalized_term) ||
+          contact.emails.any? { |email| normalize_email(email[:address]).include?(normalized_term) }
+      end)
+    end
+
+    def find_by_email(email)
+      normalized_email = normalize_email(email)
+      return self.class.new([]) if normalized_email.empty?
+
+      self.class.new(select do |contact|
+        contact.emails.any? { |entry| normalize_email(entry[:address]) == normalized_email }
+      end)
+    end
+
+    def find_by_phone(phone)
+      normalized_phone = normalize_phone(phone)
+      return self.class.new([]) if normalized_phone.empty?
+
+      self.class.new(select do |contact|
+        contact.phones.any? { |entry| normalize_phone(entry[:number]) == normalized_phone }
+      end)
+    end
+
+    def to_a
+      @contacts.dup
+    end
+
+    private
+
+    def matches_criteria?(contact, criteria)
+      criteria.all? do |field, expected|
+        actual = contact.public_send(field)
+        actual.is_a?(Array) ? actual.include?(expected) : actual == expected
+      end
+    end
+
+    def normalize_email(value)
+      normalize_text(value).strip
+    end
+
+    def normalize_phone(value)
+      value.to_s.gsub(/[^0-9]/, '')
+    end
+
+    def normalize_text(value)
+      value.to_s.unicode_normalize(:nfc).downcase
+    end
+  end
+end

data/lib/abbu/schema_inspector.rb

@@ -0,0 +1,133 @@
+# lib/abbu/schema_inspector.rb
+# frozen_string_literal: true
+
+require 'pathname'
+# Explicit ownership keeps SchemaInspector independent of Ruby's Set autoload behavior.
+require 'set' # rubocop:disable Lint/RedundantRequireStatement
+require 'sqlite3'
+require_relative 'utils/source_descriptor'
+
+module Abbu
+  class SchemaInspector
+    RECORD_COLUMNS = %w[
+      Z_PK Z_ENT ZFIRSTNAME ZMIDDLENAME ZLASTNAME ZNICKNAME ZTITLE ZSUFFIX
+      ZORGANIZATION ZJOBTITLE ZDEPARTMENT ZMAIDENNAME ZPHONETICFIRSTNAME
+      ZPHONETICMIDDLENAME ZPHONETICLASTNAME ZPHONETICORGANIZATION ZPRONOUNS
+      ZRINGTONE ZTEXTTONE ZVERIFICATIONCODE ZIMAGEURI ZCREATIONDATE
+      ZMODIFICATIONDATE
+    ].freeze
+
+    KNOWN_SCHEMA = {
+      'Z_ABCDCONTACTGROUP' => %w[Z_CONTACT Z_GROUP],
+      'ZABCDDATECOMPONENTS' => %w[Z_PK ZOWNER ZYEAR ZMONTH ZDAY ZLABEL],
+      'ZABCDEMAILADDRESS' => %w[Z_PK ZOWNER ZADDRESSNORMALIZED ZLABEL],
+      'ZABCDMESSAGINGADDRESS' => %w[Z_PK ZOWNER ZADDRESS ZLABEL ZSERVICENAME],
+      'ZABCDNOTE' => %w[Z_PK ZCONTACT ZTEXT],
+      'ZABCDPHONENUMBER' => %w[Z_PK ZOWNER ZFULLNUMBER ZLABEL],
+      'ZABCDPOSTALADDRESS' => %w[Z_PK ZOWNER ZSTREET ZCITY ZSTATE ZZIPCODE ZCOUNTRYNAME ZLABEL],
+      'ZABCDRECORD' => RECORD_COLUMNS,
+      'ZABCDRELATEDNAME' => %w[Z_PK ZOWNER ZNAME ZLABEL],
+      'ZABCDSOCIALPROFILE' => %w[Z_PK ZOWNER ZSERVICENAME ZUSERNAME],
+      'ZABCDURLADDRESS' => %w[Z_PK ZOWNER ZURL ZLABEL]
+    }.transform_values { |columns| columns.to_set.freeze }.freeze
+    REQUIRED_TABLES = %w[ZABCDRECORD].freeze
+
+    def initialize(db_paths, root_path: nil)
+      @db_paths = Array(db_paths).map { |path| Pathname.new(path) }.sort
+      @root_path = root_path && Pathname.new(root_path)
+    end
+
+    def report
+      {
+        archive_path: @root_path&.expand_path&.to_s,
+        databases: @db_paths.map { |db_path| inspect_database(db_path) }
+      }
+    end
+
+    private
+
+    def inspect_database(db_path)
+      db = SQLite3::Database.new(db_path.to_s)
+      table_names = user_table_names(db)
+      tables = table_names.map { |table_name| inspect_table(db, table_name) }
+      source = Utils::SourceDescriptor.new(db_path, root_path: @root_path).to_h
+      database_report(source, tables, KNOWN_SCHEMA.keys - table_names)
+    ensure
+      db&.close
+    end
+
+    def database_report(source, tables, missing_tables)
+      {
+        path: source[:path],
+        relative_path: source[:relative_path],
+        source: source.slice(:kind, :identifier),
+        tables: tables,
+        unknown_tables: tables.reject { |table| table[:known] }.map { |table| table[:name] },
+        missing_known_tables: missing_tables,
+        missing_required_tables: REQUIRED_TABLES & missing_tables,
+        schema_drift: schema_drift?(tables, missing_tables)
+      }
+    end
+
+    def user_table_names(db)
+      db.execute(<<~SQL).flatten.sort
+        SELECT name
+        FROM sqlite_master
+        WHERE type = 'table' AND name NOT LIKE 'sqlite_%'
+        ORDER BY name
+      SQL
+    end
+
+    def inspect_table(db, table_name)
+      known_columns = KNOWN_SCHEMA[table_name]
+      columns = table_columns(db, table_name, known_columns)
+      {
+        name: table_name,
+        known: !known_columns.nil?,
+        columns: columns,
+        missing_known_columns: missing_known_columns(known_columns, columns),
+        unknown_columns: columns.reject { |column| column[:known] }.map { |column| column[:name] },
+        contact_link_candidates: contact_link_candidates(columns)
+      }
+    end
+
+    def missing_known_columns(known_columns, columns)
+      return [] unless known_columns
+
+      known_columns.to_a - columns.map { |column| column[:name] }
+    end
+
+    def contact_link_candidates(columns)
+      columns.filter_map { |column| column[:name] if column[:contact_link_candidate] }
+    end
+
+    def table_columns(db, table_name, known_columns)
+      db.table_info(table_name).sort_by { |column| column['name'] }.map do |column|
+        column_report(column, known_columns)
+      end
+    end
+
+    def column_report(column, known_columns)
+      name = column['name']
+      {
+        name: name,
+        declared_type: column['type'],
+        nullable: column['notnull'].zero?,
+        primary_key: column['pk'].positive?,
+        known: known_columns&.include?(name) || false,
+        contact_link_candidate: contact_link_candidate?(name)
+      }
+    end
+
+    def contact_link_candidate?(column_name)
+      %w[OWNER CONTACT].include?(column_name.delete_prefix('Z').delete('_').upcase)
+    end
+
+    def schema_drift?(tables, missing_tables)
+      table_drift = tables.any? do |table|
+        !table[:known] || table[:missing_known_columns].any? || table[:unknown_columns].any?
+      end
+      missing_tables.any? || table_drift
+    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