abbu 0.2.0 → 0.8.1

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

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,115 +63,172 @@ 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
+          SELECT g.Z_PK, g.ZFIRSTNAME
           FROM Z_ABCDCONTACTGROUP j
           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 do |row|
+          { record_id: row['Z_PK'], name: row['ZFIRSTNAME'] }
+        end
       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])
@@ -166,7 +239,8 @@ module Abbu
         contact.emails           = emails_for(db, record_id)
         contact.phones           = phones_for(db, record_id)
         contact.addresses        = addresses_for(db, record_id)
-        contact.groups           = groups_for(db, record_id)
+        contact.group_memberships = groups_for(db, record_id)
+        contact.groups           = contact.group_memberships.map { |membership| membership[:name] }
         contact.urls             = urls_for(db, record_id)
         contact.notes            = notes_for(db, record_id)
         contact.related_names    = related_names_for(db, record_id)
@@ -175,9 +249,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,92 @@
+# lib/abbu/query.rb
+# frozen_string_literal: true
+
+require_relative 'timestamp_range'
+
+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
+
+    def in_group(group)
+      self.class.new(select { |contact| group.include?(contact) })
+    end
+
+    def modified_since(value)
+      date_range(:modified_at, since: value)
+    end
+
+    def created_since(value)
+      date_range(:created_at, since: value)
+    end
+
+    def date_range(field, since: nil, before: nil)
+      range = TimestampRange.new(field, since: since, before: before)
+      self.class.new(select { |contact| range.include?(contact.public_send(field)) })
+    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