has_helpers 5.0.2

data/spec/importers/cards/importer_spec.rb

@@ -0,0 +1,861 @@
+# frozen_string_literal: true
+
+require "rails_helper"
+
+describe HasHelpers::Cards::Importer do
+  ::HasHelpers::Resource.reset_column_information
+
+  # Small helper test class to act as a DSL card builder.
+  # We stub HasHelpers::Cards::CardBuilder::Base.descendants to only return this one
+  # so that tests are isolated from other card builders defined in the app.
+  class TestCardBuilder < HasHelpers::Cards::CardBuilder::Base
+    define do
+      resources do
+        add Advisor
+      end
+
+      card "Test Card",
+           relationship: "test_emails",
+           identifier: HasHelpers::Cards::CardIdentifier::ADVISOR_BASIC_INFO,
+           layout: HasHelpers::Cards::CardLayoutType::LIST,
+           variant: HasHelpers::Cards::CardVariantType::EMAILS do
+        description "Test card for importer specs"
+        field :email, data_type: HasHelpers::Cards::CardDataType::STRING
+      end
+    end
+  end
+
+  let(:base_args) do
+    {
+      application: "AgenciesHQ",
+      resources: nil,
+      mode: :apply,
+      audit: true
+    }
+  end
+
+  let(:app_record) { 
+    instance_double(HasHelpers::Application, 
+    id: 1,
+    name: "AgenciesHQ")
+  }
+
+  subject(:importer) do
+    described_class.new(**base_args)
+  end
+
+  before do
+    allow(HasHelpers::Application)
+      .to receive(:find_by!)
+      .and_return(app_record)
+    # Isolate DSL discovery to this test builder.
+    allow(HasHelpers::Cards::CardBuilder::Base)
+      .to receive(:descendants)
+      .and_return([TestCardBuilder])
+  end
+
+  # .normalize_run_arguments
+  describe ".normalize_run_arguments" do
+    def normalize(args, opts)
+      described_class.send(:normalize_run_arguments, args, opts)
+    end
+
+    it "defaults to mode :apply and audit true when not given" do
+      resources, mode, audit = normalize([], {})
+
+      expect(resources).to be_nil
+      expect(mode).to eq(:apply)
+      expect(audit).to eq(true)
+    end
+
+    it "accepts resources via positional argument" do
+      resources, mode, audit = normalize([:advisor], {})
+
+      expect(resources).to eq(:advisor)
+      expect(mode).to eq(:apply)
+      expect(audit).to eq(true)
+    end
+
+    it "prefers keyword resources over positional" do
+      resources, mode, audit = normalize([:advisor], { resources: [:client] })
+
+      expect(resources).to eq([:client])
+      expect(mode).to eq(:apply)
+      expect(audit).to eq(true)
+    end
+
+    it "allows explicit mode and audit flags" do
+      resources, mode, audit = normalize([], { resources: [:advisor], mode: :dry_run, audit: false })
+
+      expect(resources).to eq([:advisor])
+      expect(mode).to eq(:dry_run)
+      expect(audit).to eq(false)
+    end
+  end
+
+  # normalize_definition
+  describe "#normalize_definition" do
+    # We pass a symbolized hash to mirror what discover_card_definitions does
+    # (it uses defn.deep_symbolize_keys before normalization).
+    let(:raw_definition) do
+      {
+        application: "AgenciesHQ",
+        name: "Test Card",
+        identifier: HasHelpers::Cards::CardIdentifier::ADVISOR_BASIC_INFO,
+        relationship: "test_emails",
+        layout_type: HasHelpers::Cards::CardLayoutType::LIST,
+        variant: HasHelpers::Cards::CardVariantType::EMAILS,
+        description: "Test card for importer specs",
+        is_customizable: nil,
+        default_position: 20,
+        resources: [
+          { class_name: "Advisor", is_mandatory: false }
+        ],
+        fields: [
+          {
+            kind: :resource,
+            data_type: HasHelpers::Cards::CardDataType::STRING,
+            default_visibility: true,
+            default_position: 10,
+            is_required: false,
+            ref: :email
+          }
+        ]
+      }
+    end
+
+    it "returns a deterministic, symbolized structure" do
+      normalized = importer.send(:normalize_definition, raw_definition)
+
+      expect(normalized[:application]).to eq("AgenciesHQ")
+      expect(normalized[:name]).to eq("Test Card")
+      expect(normalized[:identifier]).to eq("AdvisorBasicInfo")
+      expect(normalized[:layout_type]).to eq("List")
+      expect(normalized[:variant]).to eq("Emails")
+      expect(normalized[:description]).to eq("Test card for importer specs")
+      expect(normalized[:is_customizable]).to eq(false)
+      expect(normalized[:default_position]).to eq(20)
+
+      expect(normalized[:resources]).to eq(
+        [{ class_name: "Advisor", is_mandatory: false }]
+      )
+
+      expect(normalized[:fields].size).to eq(1)
+      field = normalized[:fields].first
+      expect(field[:kind]).to eq(:resource)
+      expect(field[:ref]).to eq("email")
+      expect(field[:data_type]).to eq(:string)
+      expect(field[:default_visibility]).to eq(true)
+      expect(field[:default_position]).to eq(10)
+      expect(field[:is_required]).to eq(false)
+    end
+  end
+
+  # checksum_for
+  describe "#checksum_for" do
+    let(:normalized) do
+      importer.send(:normalize_definition, {
+        name: "Test Card",
+        identifier: "AdvisorBasicInfo",
+        layout_type: "List",
+        variant: "Emails",
+        description: "Test",
+        is_customizable: true,
+        default_position: 10,
+        resources: [{ class_name: "Advisor", is_mandatory: true }],
+        fields: [
+          {
+            kind: :resource,
+            ref: "email",
+            data_type: :string,
+            default_visibility: true,
+            default_position: 10,
+            is_required: false
+          }
+        ]
+      })
+    end
+
+    it "returns a deterministic checksum" do
+      checksum_1 = importer.send(:checksum_for, normalized)
+      checksum_2 = importer.send(:checksum_for, normalized)
+
+      expect(checksum_1).to eq(checksum_2)
+      expect(checksum_1).to be_a(String)
+      expect(checksum_1.size).to eq(64) # SHA256 hex length
+    end
+
+    it "changes the checksum when definition changes" do
+      checksum_1 = importer.send(:checksum_for, normalized)
+
+      modified = normalized.deep_dup
+      modified[:description] = "Changed description"
+      checksum_2 = importer.send(:checksum_for, modified)
+
+      expect(checksum_2).not_to eq(checksum_1)
+    end
+
+    it "changes the checksum when hover_only changes" do
+      checksum_1 = importer.send(:checksum_for, normalized)
+
+      modified = normalized.deep_dup
+      modified[:is_hover_only] = true
+      checksum_2 = importer.send(:checksum_for, modified)
+
+      expect(checksum_2).not_to eq(checksum_1)
+    end
+  end
+
+  # compute_diff
+  describe "#compute_diff" do
+    let(:code_view) do
+      {
+        application: "AgenciesHQ",
+        name: "Test Card",
+        identifier: "AdvisorBasicInfo",
+        relationship: "test_emails",
+        layout_type: "List",
+        variant: "Emails",
+        description: "Test card",
+        is_customizable: true,
+        default_position: 10,
+        resources: [
+          { class_name: "Advisor", is_mandatory: false }
+        ],
+        fields: [
+          {
+            kind: :resource,
+            ref: "email",
+            data_type: :string,
+            default_visibility: true,
+            default_position: 10,
+            is_required: false
+          }
+        ]
+      }.then { |h| importer.send(:normalize_definition, h) }
+    end
+
+    context "when db_view is nil (brand new card)" do
+      it "classifies as :new and treats all fields/resources as added" do
+        diff = importer.send(:compute_diff, code_view, nil)
+
+        expect(diff.card_changes).to eq(:new)
+        expect(diff.fields_added.size).to eq(1)
+        expect(diff.fields_removed).to be_empty
+        expect(diff.fields_changed).to be_empty
+        expect(diff.resources_added.size).to eq(1)
+        expect(diff.resources_removed).to be_empty
+      end
+    end
+
+    context "when db_view matches code_view exactly" do
+      it "classifies as :same and no diffs" do
+        db_view = code_view.deep_dup
+        diff = importer.send(:compute_diff, code_view, db_view)
+
+        expect(diff.card_changes).to eq(:same)
+        expect(diff.fields_added).to be_empty
+        expect(diff.fields_removed).to be_empty
+        expect(diff.fields_changed).to be_empty
+        expect(diff.resources_added).to be_empty
+        expect(diff.resources_removed).to be_empty
+      end
+    end
+
+    context "when a resource is removed from code" do
+      it "marks that resource as resources_removed" do
+        db_view = code_view.deep_dup
+        db_view[:resources] << { class_name: "Client", is_mandatory: false }
+
+        diff = importer.send(:compute_diff, code_view, db_view)
+
+        expect(diff.resources_removed.size).to eq(1)
+        expect(diff.resources_removed.first[:class_name]).to eq("Client")
+      end
+    end
+
+    context "when a new field is added in code" do
+      it "marks it as fields_added" do
+        db_view = code_view.deep_dup
+        db_view[:fields] = []
+
+        diff = importer.send(:compute_diff, code_view, db_view)
+
+        expect(diff.fields_added.size).to eq(1)
+        expect(diff.fields_added.first[:ref]).to eq("email")
+      end
+    end
+
+    context "when a field changes type or required flag" do
+      it "marks it as fields_changed" do
+        db_view = code_view.deep_dup
+        db_view[:fields].first[:data_type] = :numeric
+
+        diff = importer.send(:compute_diff, code_view, db_view)
+
+        expect(diff.fields_changed.size).to eq(1)
+        change = diff.fields_changed.first
+        expect(change[:identity]).to eq([:resource, "email"])
+        expect(change[:db][:data_type]).to eq(:numeric)
+        expect(change[:code][:data_type]).to eq(:string)
+      end
+    end
+  end
+
+  # classify_and_raise_if_breaking!
+  describe "#classify_and_raise_if_breaking!" do
+    let(:code_view) do
+      {
+        name: "Test Card",
+        identifier: "AdvisorBasicInfo"
+      }
+    end
+
+    def build_diff(attrs = {})
+      HasHelpers::Cards::Importer::Diff.new(
+        {
+          card_changes: :same,
+          fields_added: [],
+          fields_removed: [],
+          fields_changed: [],
+          resources_added: [],
+          resources_removed: []
+        }.merge(attrs)
+      )
+    end
+
+    it "does nothing when there are no breaking changes" do
+      diff = build_diff
+
+      expect do
+        importer.send(:classify_and_raise_if_breaking!, TestCardBuilder, code_view, diff)
+      end.not_to raise_error
+    end
+
+    it "raises when card level attributes changed" do
+      diff = build_diff(card_changes: :changed)
+
+      expect do
+        importer.send(:classify_and_raise_if_breaking!, TestCardBuilder, code_view, diff)
+      end.to raise_error(described_class::AuditError, /attributes changed/)
+    end
+
+    it "raises when fields are removed from DB not present in code" do
+      diff = build_diff(
+        fields_removed: [
+          { kind: :resource, ref: "email", data_type: :string }
+        ]
+      )
+
+      expect do
+        importer.send(:classify_and_raise_if_breaking!, TestCardBuilder, code_view, diff)
+      end.to raise_error(
+        described_class::AuditError,
+        /field 'resource:email' is persisted but not in code/
+      )
+    end
+
+    it "raises when fields have changed structural attributes" do
+      diff = build_diff(
+        fields_changed: [
+          {
+            identity: [:resource, "email"],
+            code: { data_type: :string },
+            db:   { data_type: :numeric }
+          }
+        ]
+      )
+
+      expect do
+        importer.send(:classify_and_raise_if_breaking!, TestCardBuilder, code_view, diff)
+      end.to raise_error(
+        described_class::AuditError,
+        /field 'resource:email' changed/
+      )
+    end
+
+    it "raises when resources are removed" do
+      diff = build_diff(
+        resources_removed: [
+          { class_name: "Client", is_mandatory: false }
+        ]
+      )
+
+      expect do
+        importer.send(:classify_and_raise_if_breaking!, TestCardBuilder, code_view, diff)
+      end.to raise_error(described_class::AuditError, /resource 'Client' is persisted but not present in code/)
+    end
+  end
+
+  describe "#validate_hover_cards!" do
+    def card_definition(identifier:, hover_only: nil, fields: [])
+      {
+        name: identifier,
+        identifier: identifier,
+        layout_type: "List",
+        hover_only: hover_only,
+        resources: [{ class_name: "Advisor", is_mandatory: false }],
+        fields: fields
+      }
+    end
+
+    def hover_field(hover_card: "AdvisorHover", hover_record_source: { from: :advisor, key: :id })
+      {
+        kind: :virtual,
+        ref: :advisor_link,
+        name: "Advisor",
+        data_type: :hover_card,
+        hover_card: hover_card,
+        hover_record_source: hover_record_source
+      }
+    end
+
+    it "rejects a hover-card field whose target identifier does not exist" do
+      pairs = [
+        [TestCardBuilder, card_definition(identifier: "Parent", fields: [hover_field(hover_card: "MissingHover")])]
+      ]
+
+      expect {
+        importer.send(:validate_hover_cards!, pairs)
+      }.to raise_error(described_class::AuditError, /field 'advisor_link'.*MissingHover.*no card with that identifier/)
+    end
+
+    it "rejects a hover-card field whose target is not hover_only" do
+      pairs = [
+        [TestCardBuilder, card_definition(identifier: "Parent", fields: [hover_field])],
+        [TestCardBuilder, card_definition(identifier: "AdvisorHover", hover_only: nil)]
+      ]
+
+      expect {
+        importer.send(:validate_hover_cards!, pairs)
+      }.to raise_error(described_class::AuditError, /field 'advisor_link'.*AdvisorHover.*not hover_only/)
+    end
+
+    it "rejects a hover-card field without hover_record_source" do
+      pairs = [
+        [TestCardBuilder, card_definition(identifier: "Parent", fields: [hover_field(hover_record_source: nil)])],
+        [TestCardBuilder, card_definition(identifier: "AdvisorHover", hover_only: true)]
+      ]
+
+      expect {
+        importer.send(:validate_hover_cards!, pairs)
+      }.to raise_error(described_class::AuditError, /field 'advisor_link'.*missing hover_record_source/)
+    end
+
+    it "rejects nested hover-card fields on the hover-only target" do
+      pairs = [
+        [TestCardBuilder, card_definition(identifier: "Parent", fields: [hover_field])],
+        [TestCardBuilder, card_definition(identifier: "AdvisorHover", hover_only: true, fields: [hover_field(hover_card: "NestedHover")])],
+        [TestCardBuilder, card_definition(identifier: "NestedHover", hover_only: true)]
+      ]
+
+      expect {
+        importer.send(:validate_hover_cards!, pairs)
+      }.to raise_error(described_class::AuditError, /AdvisorHover.*nested HoverCard field 'advisor_link'/)
+    end
+
+    it "accepts a valid hover-card field when parent and target are in the same import" do
+      pairs = [
+        [TestCardBuilder, card_definition(identifier: "Parent", fields: [hover_field])],
+        [TestCardBuilder, card_definition(identifier: "AdvisorHover", hover_only: true)]
+      ]
+
+      expect {
+        importer.send(:validate_hover_cards!, pairs)
+      }.not_to raise_error
+    end
+  end
+
+  describe "hover_only definitions" do
+    # Hover-only cards are no longer persisted; they live in-memory and are
+    # assembled from the registry by the HoverCardData resolver. The importer
+    # skips them at run-time.
+    it "treats hover_only definitions as skip-at-import" do
+      hover_only_def = { name: "Advisor Hover", identifier: "AdvisorHover", hover_only: true }
+      regular_def    = { name: "Demographics", identifier: "Demographics" }
+
+      expect(importer.send(:hover_only_definition?, hover_only_def)).to eq(true)
+      expect(importer.send(:hover_only_definition?, regular_def)).to eq(false)
+    end
+  end
+
+  # find_field_resource (tests comentados a propósito, mantengo tu decisión)
+  describe "#find_field_resource" do
+    subject(:importer_with_parents) do
+      described_class.new(application: "AgenciesHQ", resources: :advisor, mode: :apply, audit: true)
+    end
+
+    let(:field_name) { "location_id" }
+    let(:parent_ids) { %w[parent-1 parent-2] }
+    let(:application) { instance_double("Application") }
+    let(:base_resource) do
+      instance_double(
+        HasHelpers::Resource,
+        id:   parent_ids.first,
+        name: "Advisor",
+        application: application
+      )
+    end
+    let(:field_class_name) { "Advisor" }
+    let(:parent_resource) { base_resource }
+
+    def call_find(field = field_name, parents = parent_ids)
+      importer_with_parents.send(:find_field_resource, field, parents)
+    end
+
+    let(:scope)   { instance_double(ActiveRecord::Relation) }
+    let(:matches) { [] }
+
+    before do
+      allow(HasHelpers::Resource)
+        .to receive(:find)
+        .with(parent_ids.first)
+        .and_return(base_resource)
+
+      allow(HasHelpers::Resource)
+        .to receive(:find_by)
+        .and_return(nil)
+
+      allow(importer_with_parents)
+        .to receive(:inspect_field_and_association)
+        .and_return([:field, field_class_name])
+
+      # Scope por nombre + parent_resource + field_class_name
+      allow(HasHelpers::Resource)
+        .to receive(:where)
+        .with(name: field_name.to_s, parent: parent_resource, field_class_name: field_class_name)
+        .and_return(scope)
+
+      # includes(:field_resource)
+      allow(scope)
+        .to receive(:includes)
+        .with(:field_resource)
+        .and_return(scope)
+
+      # order(:created_at, :id)
+      allow(scope)
+        .to receive(:order)
+        .with(:created_at, :id)
+        .and_return(scope)
+
+      # to_a devuelve la colección simulada
+      allow(scope)
+        .to receive(:to_a)
+        .and_return(matches)
+    end
+
+    context "when there is a single match with compatible field_resource" do
+      let(:resource) do
+        instance_double(
+          HasHelpers::Resource,
+          id:              "res-1",
+          parent_id:       "parent-1",
+          application_id:  "app-1",
+          field_resource:  nil
+        )
+      end
+
+      let(:matches) { [resource] }
+
+      it "returns that resource" do
+        expect(call_find).to eq(resource)
+      end
+    end
+
+    context "when there are no matches" do
+      let(:matches) { [] }
+
+      it "raises ActiveRecord::RecordNotFound with a helpful message" do
+        expect do
+          call_find
+        end.to raise_error(
+          ActiveRecord::RecordNotFound,
+          "No field found with name=#{field_name} for parent_ids=#{parent_ids.inspect}"
+        )
+      end
+    end
+
+    context "when multiple matches remain after filtering by application" do
+      let(:resource_1) do
+        instance_double(
+          HasHelpers::Resource,
+          id:              "field-1",
+          parent_id:       "parent-A",
+          application_id:  1,
+          field_resource:  nil
+        )
+      end
+
+      let(:resource_2) do
+        instance_double(
+          HasHelpers::Resource,
+          id:              "field-2",
+          parent_id:       "parent-B",
+          application_id:  1,
+          field_resource:  nil
+        )
+      end
+
+      let(:matches) { [resource_1, resource_2] }
+
+      it "raises AuditError indicating real ambiguity" do
+        expect do
+          call_find
+        end.to raise_error(
+          described_class::AuditError,
+          /Ambiguous field 'location_id'/
+        )
+      end
+    end
+
+    context "when some matches are filtered out by application_id and only one remains" do
+      let(:good_fr) do
+        instance_double(
+          HasHelpers::Resource,
+          application_id:  1
+        )
+      end
+
+      let(:bad_fr) do
+        instance_double(
+          HasHelpers::Resource,
+          application_id:  2
+        )
+      end
+
+      let(:good_resource) do
+        instance_double(
+          HasHelpers::Resource,
+          id:              "good",
+          parent_id:       "parent-1",
+          application_id:  1,
+          field_resource:  good_fr
+        )
+      end
+
+      let(:bad_resource) do
+        instance_double(
+          HasHelpers::Resource,
+          id:              "bad",
+          parent_id:       "parent-1",
+          application_id:  1,
+          field_resource:  bad_fr
+        )
+      end
+
+      # Ambos vienen del scope, pero el filtro debe descartar el "bad"
+      let(:matches) { [good_resource, bad_resource] }
+
+      it "returns the only remaining compatible resource" do
+        expect(call_find).to eq(good_resource)
+      end
+    end
+  end
+
+  # run (orchestration)
+  describe "#run" do
+    context "in :apply mode with audit" do
+      it "audits (via classify_and_raise_if_breaking!) and then calls upsert methods when diff is non-breaking" do
+        importer = described_class.new(application: "AgenciesHQ", resources: :advisor, mode: :apply, audit: true)
+
+        raw_def = { name: "Test Card" }
+
+        normalized = importer.send(:normalize_definition, {
+          application: "AgenciesHQ",
+          name: "Test Card",
+          identifier: "AdvisorBasicInfo",
+          layout_type: "List",
+          variant: "Emails",
+          resources: [],
+          fields: []
+        })
+
+        diff = HasHelpers::Cards::Importer::Diff.new(
+          card_changes: :same,
+          fields_added: [],
+          fields_removed: [],
+          fields_changed: [],
+          resources_added: [],
+          resources_removed: []
+        )
+
+        card_def = instance_double(
+          HasHelpers::Cards::CardDefinition,
+          id: "card-id",
+          card_definition_resources: double(pluck: [])
+        )
+
+        allow(importer).to receive(:discover_card_definitions).and_return([[TestCardBuilder, raw_def]])
+        allow(importer).to receive(:normalize_definition).and_return(normalized)
+        allow(importer).to receive(:checksum_for).and_return("checksum")
+        allow(importer).to receive(:identifier_option_for).and_return(double(id: "identifier-id"))
+        allow(HasHelpers::Cards::CardDefinition).to receive_message_chain(:lock, :find_by).and_return(nil)
+        allow(importer).to receive(:compute_diff).and_return(diff)
+        allow(importer).to receive(:classify_and_raise_if_breaking!)
+        allow(importer).to receive(:upsert_card_definition!).and_return(card_def)
+        allow(importer).to receive(:upsert_card_resources!)
+        allow(importer).to receive(:upsert_card_fields!)
+
+        result = importer.run
+
+        expect(importer).to have_received(:classify_and_raise_if_breaking!).once
+        expect(importer).to have_received(:upsert_card_definition!).once
+        expect(importer).to have_received(:upsert_card_resources!).once
+        expect(importer).to have_received(:upsert_card_fields!).once
+        expect(result.skipped_cards).to eq(0)
+      end
+    end
+
+    context "in :dry_run mode" do
+      it "does not perform DB writes and marks cards as skipped" do
+        importer = described_class.new(application: "AgenciesHQ", resources: :advisor, mode: :dry_run, audit: true)
+
+        raw_def = { name: "Test Card" }
+
+        normalized = importer.send(:normalize_definition, {
+          application: "AgenciesHQ",
+          name: "Test Card",
+          identifier: "AdvisorBasicInfo",
+          layout_type: "List",
+          variant: "Emails",
+          resources: [],
+          fields: []
+        })
+
+        diff = HasHelpers::Cards::Importer::Diff.new(
+          card_changes: :same,
+          fields_added: [],
+          fields_removed: [],
+          fields_changed: [],
+          resources_added: [],
+          resources_removed: []
+        )
+
+        allow(importer).to receive(:discover_card_definitions).and_return([[TestCardBuilder, raw_def]])
+        allow(importer).to receive(:normalize_definition).and_return(normalized)
+        allow(importer).to receive(:checksum_for).and_return("checksum")
+        # clave: no dejamos que llegue a la DB de Options
+        allow(importer).to receive(:identifier_option_for).and_return(double(id: "identifier-id"))
+        allow(HasHelpers::Cards::CardDefinition).to receive_message_chain(:lock, :find_by).and_return(nil)
+        allow(importer).to receive(:compute_diff).and_return(diff)
+        allow(importer).to receive(:classify_and_raise_if_breaking!)
+
+        allow(importer).to receive(:upsert_card_definition!)
+        allow(importer).to receive(:upsert_card_resources!)
+        allow(importer).to receive(:upsert_card_fields!)
+
+        result = importer.run
+
+        expect(result.skipped_cards).to eq(1)
+        expect(importer).not_to have_received(:upsert_card_definition!)
+        expect(importer).not_to have_received(:upsert_card_resources!)
+        expect(importer).not_to have_received(:upsert_card_fields!)
+      end
+    end
+  end
+
+  # audit_removed_cards!
+  describe "#audit_removed_cards!" do
+    let(:code_pairs) do
+      # DSL only defines a card with identifier "AdvisorBasicInfo"
+      normalized = importer.send(
+        :normalize_definition,
+        {
+          name: "Test Card",
+          identifier: "AdvisorBasicInfo",
+          layout_type: "List",
+          variant: "Emails",
+          is_customizable: true,
+          default_position: 10,
+          resources: [],
+          fields: []
+        }
+      )
+      [[TestCardBuilder, normalized]]
+    end
+
+    context "when there is no resource filter (global import)" do
+      it "raises AuditError if a card exists in DB but not in code" do
+        importer = described_class.new(application: "AgenciesHQ", resources: nil, mode: :apply, audit: true)
+
+        orphan_identifier = double(name: "OrphanIdentifier")
+        orphan_resource   = double(name: "OrphanResource")
+        orphan_link       = double(resource: orphan_resource)
+        orphan_card       = double(
+          name: "Orphan Card",
+          identifier: orphan_identifier,
+          card_definition_resources: [orphan_link]
+        )
+
+        # Stub CardDefinition.includes(:identifier, card_definition_resources: :resource).find_each to yield an orphan card.
+        relation = double
+        allow(HasHelpers::Cards::CardDefinition)
+          .to receive(:joins)
+          .with(card_definition_resources: { resource: :application })
+          .and_return(relation)
+
+        allow(relation)
+          .to receive(:where)
+          .with(applications: { id: app_record.id })
+          .and_return(relation)
+
+        allow(relation)
+          .to receive(:includes)
+          .with(:identifier, card_definition_resources: :resource)
+          .and_return(relation)
+
+        allow(relation).to receive(:find_each).and_yield(orphan_card)
+
+        expect do
+          importer.send(:audit_removed_cards!, code_pairs)
+        end.to raise_error(
+          described_class::AuditError,
+          /Card 'Orphan Card' \(identifier=OrphanIdentifier, resource=OrphanResource\) exists in DB but not in the DSL/
+        )
+      end
+    end
+
+    context "when a resource filter is present" do
+      it "is not invoked from #run (it only runs when resource_filter is nil)" do
+        importer = described_class.new(application: "AgenciesHQ", resources: :advisor, mode: :apply, audit: true)
+
+        expect(importer.send(:resource_filter)).to eq([:advisor])
+        # The behavior that audit_removed_cards! is skipped when resource_filter
+        # is non-nil is covered indirectly in the #run specs by the condition:
+        #   audit && resource_filter.nil?
+      end
+    end
+  end
+
+  # log_summary
+  describe "#log_summary" do
+    it "logs a structured summary" do
+      importer = described_class.new(application: "AgenciesHQ", resources: :advisor, mode: :apply, audit: true)
+      importer_result = importer.send(:result)
+      importer_result.created_cards = 1
+      importer_result.updated_cards = 2
+      importer_result.created_fields = 3
+      importer_result.updated_fields = 4
+      importer_result.created_resources = 5
+      importer_result.updated_resources = 6
+      importer_result.skipped_cards = 7
+
+      expect(Rails.logger).to receive(:info).with(
+        hash_including(
+          event: "cards_importer.summary",
+          created_cards: 1,
+          updated_cards: 2,
+          created_fields: 3,
+          updated_fields: 4,
+          created_resources: 5,
+          updated_resources: 6,
+          skipped_cards: 7,
+          mode: :apply,
+          resource_filter: [:advisor]
+        )
+      )
+
+      importer.send(:log_summary)
+    end
+  end
+end