lex-cognitive-map 0.1.0

data/spec/legion/extensions/cognitive_map/client_spec.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/cognitive_map/client'
+
+RSpec.describe Legion::Extensions::CognitiveMap::Client do
+  subject(:client) { described_class.new }
+
+  it 'responds to all runner methods' do
+    expect(client).to respond_to(:add_location)
+    expect(client).to respond_to(:connect_locations)
+    expect(client).to respond_to(:visit_location)
+    expect(client).to respond_to(:find_path)
+    expect(client).to respond_to(:explore_neighborhood)
+    expect(client).to respond_to(:map_clusters)
+    expect(client).to respond_to(:familiar_locations)
+    expect(client).to respond_to(:switch_context)
+    expect(client).to respond_to(:update_cognitive_map)
+    expect(client).to respond_to(:cognitive_map_stats)
+  end
+
+  it 'accepts an injected map_store' do
+    custom_store = Legion::Extensions::CognitiveMap::Helpers::CognitiveMapStore.new
+    custom_store.add_location(id: 'pre_existing')
+    client2 = described_class.new(map_store: custom_store)
+    result = client2.cognitive_map_stats
+    expect(result[:location_count]).to eq(1)
+  end
+
+  describe 'integration: add and navigate' do
+    it 'adds locations, connects them, and finds a path' do
+      client.add_location(id: 'start', domain: :space)
+      client.add_location(id: 'mid', domain: :space)
+      client.add_location(id: 'end', domain: :space)
+      client.connect_locations(from: 'start', to: 'mid', distance: 1.0)
+      client.connect_locations(from: 'mid', to: 'end', distance: 1.0)
+
+      result = client.find_path(from: 'start', to: 'end')
+      expect(result[:success]).to be true
+      expect(result[:path]).to eq(%w[start mid end])
+      expect(result[:distance]).to eq(2.0)
+    end
+
+    it 'builds familiarity through visits' do
+      client.add_location(id: 'hub')
+      5.times { client.visit_location(id: 'hub') }
+      familiar = client.familiar_locations(limit: 1)
+      expect(familiar[:locations].first[:id]).to eq('hub')
+      expect(familiar[:locations].first[:visit_count]).to eq(5)
+    end
+
+    it 'explores neighborhood up to a distance threshold' do
+      client.add_location(id: 'center')
+      client.add_location(id: 'near')
+      client.add_location(id: 'far')
+      client.connect_locations(from: 'center', to: 'near', distance: 1.0)
+      client.connect_locations(from: 'near', to: 'far', distance: 5.0)
+
+      result = client.explore_neighborhood(id: 'center', max_distance: 2.0)
+      ids = result[:reachable].map { |r| r[:id] }
+      expect(ids).to include('near')
+      expect(ids).not_to include('far')
+    end
+
+    it 'detects disconnected clusters' do
+      client.add_location(id: 'a')
+      client.add_location(id: 'b')
+      client.connect_locations(from: 'a', to: 'b')
+      client.add_location(id: 'island1')
+      client.add_location(id: 'island2')
+      client.connect_locations(from: 'island1', to: 'island2')
+
+      result = client.map_clusters
+      expect(result[:count]).to eq(2)
+    end
+
+    it 'isolates context maps from each other' do
+      client.add_location(id: 'shared_name', domain: :ctx_a)
+      client.switch_context(context_id: :ctx_b)
+      client.add_location(id: 'shared_name', domain: :ctx_b)
+
+      result_b = client.cognitive_map_stats
+      expect(result_b[:location_count]).to eq(1)
+
+      client.switch_context(context_id: :default)
+      result_default = client.cognitive_map_stats
+      expect(result_default[:location_count]).to eq(1)
+    end
+  end
+end

data/spec/legion/extensions/cognitive_map/helpers/cognitive_map_store_spec.rb

@@ -0,0 +1,321 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::CognitiveMap::Helpers::CognitiveMapStore do
+  subject(:store) { described_class.new }
+
+  def add_triangle
+    store.add_location(id: 'a')
+    store.add_location(id: 'b')
+    store.add_location(id: 'c')
+    store.connect(from: 'a', to: 'b', distance: 1.0)
+    store.connect(from: 'b', to: 'c', distance: 1.0)
+    store.connect(from: 'a', to: 'c', distance: 3.0)
+  end
+
+  describe '#add_location' do
+    it 'adds a location and returns true' do
+      expect(store.add_location(id: 'loc1')).to be true
+    end
+
+    it 'is idempotent for duplicate ids' do
+      store.add_location(id: 'loc1')
+      store.add_location(id: 'loc1', domain: :other)
+      expect(store.location_count).to eq(1)
+    end
+
+    it 'stores domain and properties' do
+      store.add_location(id: 'loc1', domain: :science, properties: { weight: 0.9 })
+      loc = store.location('loc1')
+      expect(loc.domain).to eq(:science)
+      expect(loc.properties[:weight]).to eq(0.9)
+    end
+
+    it 'enforces MAX_LOCATIONS' do
+      max = Legion::Extensions::CognitiveMap::Helpers::Constants::MAX_LOCATIONS
+      max.times { |i| store.add_location(id: "loc_#{i}") }
+      result = store.add_location(id: 'overflow')
+      expect(result).to be false
+    end
+  end
+
+  describe '#remove_location' do
+    it 'removes an existing location' do
+      store.add_location(id: 'loc1')
+      expect(store.remove_location('loc1')).to be true
+      expect(store.location('loc1')).to be_nil
+    end
+
+    it 'returns false for unknown location' do
+      expect(store.remove_location('nonexistent')).to be false
+    end
+
+    it 'removes edges pointing to removed location' do
+      store.add_location(id: 'a')
+      store.add_location(id: 'b')
+      store.connect(from: 'a', to: 'b')
+      store.remove_location('b')
+      expect(store.neighbors_of(id: 'a')).to be_empty
+    end
+  end
+
+  describe '#connect' do
+    before do
+      store.add_location(id: 'a')
+      store.add_location(id: 'b')
+    end
+
+    it 'creates a directed edge' do
+      expect(store.connect(from: 'a', to: 'b')).to be true
+    end
+
+    it 'creates bidirectional edges by default' do
+      store.connect(from: 'a', to: 'b', distance: 2.0)
+      a_neighbors = store.neighbors_of(id: 'a')
+      b_neighbors = store.neighbors_of(id: 'b')
+      expect(a_neighbors.map { |n| n[:id] }).to include('b')
+      expect(b_neighbors.map { |n| n[:id] }).to include('a')
+    end
+
+    it 'creates unidirectional edges when bidirectional: false' do
+      store.connect(from: 'a', to: 'b', bidirectional: false)
+      a_neighbors = store.neighbors_of(id: 'a')
+      b_neighbors = store.neighbors_of(id: 'b')
+      expect(a_neighbors.map { |n| n[:id] }).to include('b')
+      expect(b_neighbors.map { |n| n[:id] }).not_to include('a')
+    end
+
+    it 'returns false if a location is missing' do
+      expect(store.connect(from: 'a', to: 'missing')).to be false
+    end
+  end
+
+  describe '#disconnect' do
+    it 'removes an edge' do
+      store.add_location(id: 'a')
+      store.add_location(id: 'b')
+      store.connect(from: 'a', to: 'b')
+      store.disconnect(from: 'a', to: 'b')
+      expect(store.neighbors_of(id: 'a')).to be_empty
+    end
+
+    it 'returns false for unknown location' do
+      expect(store.disconnect(from: 'ghost', to: 'b')).to be false
+    end
+  end
+
+  describe '#visit' do
+    it 'marks location as visited' do
+      store.add_location(id: 'loc1')
+      result = store.visit(id: 'loc1')
+      expect(result[:found]).to be true
+      expect(result[:visit_count]).to eq(1)
+    end
+
+    it 'returns found: false for unknown location' do
+      result = store.visit(id: 'ghost')
+      expect(result[:found]).to be false
+    end
+
+    it 'boosts familiarity' do
+      store.add_location(id: 'loc1')
+      before = store.location('loc1').familiarity
+      store.visit(id: 'loc1')
+      expect(store.location('loc1').familiarity).to be > before
+    end
+  end
+
+  describe '#shortest_path' do
+    before { add_triangle }
+
+    it 'finds direct path between neighbors' do
+      result = store.shortest_path(from: 'a', to: 'b')
+      expect(result[:found]).to be true
+      expect(result[:path]).to eq(%w[a b])
+      expect(result[:distance]).to eq(1.0)
+    end
+
+    it 'finds shortest path avoiding longer direct edge' do
+      result = store.shortest_path(from: 'a', to: 'c')
+      expect(result[:found]).to be true
+      # a->b->c = 2.0, a->c = 3.0, so Dijkstra should pick a->b->c
+      expect(result[:distance]).to be <= 2.0
+    end
+
+    it 'returns trivial path for same start and end' do
+      result = store.shortest_path(from: 'a', to: 'a')
+      expect(result[:found]).to be true
+      expect(result[:path]).to eq(['a'])
+      expect(result[:distance]).to eq(0.0)
+    end
+
+    it 'returns found: false for missing start' do
+      result = store.shortest_path(from: 'ghost', to: 'a')
+      expect(result[:found]).to be false
+    end
+
+    it 'returns found: false for disconnected locations' do
+      store.add_location(id: 'island')
+      result = store.shortest_path(from: 'a', to: 'island')
+      expect(result[:found]).to be false
+    end
+
+    it 'caches repeated queries' do
+      store.shortest_path(from: 'a', to: 'c')
+      result2 = store.shortest_path(from: 'a', to: 'c')
+      expect(result2[:found]).to be true
+    end
+  end
+
+  describe '#neighbors_of' do
+    it 'returns direct neighbors' do
+      store.add_location(id: 'a')
+      store.add_location(id: 'b')
+      store.connect(from: 'a', to: 'b', distance: 1.5)
+      neighbors = store.neighbors_of(id: 'a')
+      expect(neighbors.size).to eq(1)
+      expect(neighbors.first[:id]).to eq('b')
+      expect(neighbors.first[:distance]).to eq(1.5)
+    end
+
+    it 'returns empty array for unknown location' do
+      expect(store.neighbors_of(id: 'ghost')).to be_empty
+    end
+
+    it 'includes distance category' do
+      store.add_location(id: 'a')
+      store.add_location(id: 'b')
+      store.connect(from: 'a', to: 'b', distance: 0.3)
+      neighbor = store.neighbors_of(id: 'a').first
+      expect(neighbor[:category]).to eq(:adjacent)
+    end
+  end
+
+  describe '#reachable_from' do
+    before { add_triangle }
+
+    it 'returns locations within max_distance' do
+      reachable = store.reachable_from(id: 'a', max_distance: 1.5)
+      ids = reachable.map { |r| r[:id] }
+      expect(ids).to include('b')
+    end
+
+    it 'excludes start location from results' do
+      reachable = store.reachable_from(id: 'a', max_distance: 5.0)
+      expect(reachable.map { |r| r[:id] }).not_to include('a')
+    end
+
+    it 'returns empty for isolated location' do
+      store.add_location(id: 'island')
+      expect(store.reachable_from(id: 'island', max_distance: 10.0)).to be_empty
+    end
+
+    it 'sorts results by distance' do
+      reachable = store.reachable_from(id: 'a', max_distance: 5.0)
+      distances = reachable.map { |r| r[:distance] }
+      expect(distances).to eq(distances.sort)
+    end
+  end
+
+  describe '#clusters' do
+    it 'returns one cluster for a connected graph' do
+      add_triangle
+      expect(store.clusters.size).to eq(1)
+    end
+
+    it 'returns multiple clusters for disconnected graph' do
+      store.add_location(id: 'a')
+      store.add_location(id: 'b')
+      store.add_location(id: 'island')
+      store.connect(from: 'a', to: 'b')
+      clusters = store.clusters
+      expect(clusters.size).to eq(2)
+    end
+
+    it 'returns empty array for empty map' do
+      expect(store.clusters).to be_empty
+    end
+  end
+
+  describe '#most_familiar' do
+    it 'returns top N locations by familiarity' do
+      5.times { |i| store.add_location(id: "loc_#{i}") }
+      3.times { store.visit(id: 'loc_0') }
+      store.visit(id: 'loc_1')
+      result = store.most_familiar(n: 2)
+      expect(result.size).to eq(2)
+      expect(result.first[:id]).to eq('loc_0')
+    end
+
+    it 'returns fewer results than n when map has fewer locations' do
+      store.add_location(id: 'only_one')
+      result = store.most_familiar(n: 10)
+      expect(result.size).to eq(1)
+    end
+  end
+
+  describe '#decay_all' do
+    it 'decays familiarity of all locations' do
+      store.add_location(id: 'a')
+      store.visit(id: 'a')
+      before = store.location('a').familiarity
+      store.decay_all
+      expect(store.location('a').familiarity).to be < before
+    end
+
+    it 'prunes faded locations' do
+      store.add_location(id: 'fresh')
+      store.add_location(id: 'faded')
+      # faded has floor familiarity and 0 visits — already qualifies as faded
+      result = store.decay_all
+      expect(result[:pruned]).to be >= 0
+    end
+
+    it 'returns decay and prune counts' do
+      store.add_location(id: 'a')
+      store.visit(id: 'a')
+      result = store.decay_all
+      expect(result).to include(:decayed, :pruned)
+    end
+  end
+
+  describe '#context_switch' do
+    it 'switches to a new context' do
+      result = store.context_switch(context_id: :work)
+      expect(result[:switched]).to be true
+      expect(result[:context]).to eq(:work)
+    end
+
+    it 'new context starts empty' do
+      store.add_location(id: 'default_loc')
+      store.context_switch(context_id: :new_context)
+      expect(store.location_count).to eq(0)
+    end
+
+    it 'preserves locations in original context' do
+      store.add_location(id: 'default_loc')
+      store.context_switch(context_id: :other)
+      store.context_switch(context_id: :default)
+      expect(store.location('default_loc')).not_to be_nil
+    end
+
+    it 'returns failure when MAX_CONTEXTS exceeded' do
+      max = Legion::Extensions::CognitiveMap::Helpers::Constants::MAX_CONTEXTS
+      max.times { |i| store.context_switch(context_id: :"ctx_#{i}") }
+      result = store.context_switch(context_id: :overflow)
+      expect(result[:switched]).to be false
+    end
+  end
+
+  describe '#to_h' do
+    it 'returns stats hash with expected keys' do
+      stats = store.to_h
+      expect(stats).to include(:context, :context_count, :location_count, :edge_count, :visit_history, :cached_paths)
+    end
+
+    it 'reflects current location count' do
+      store.add_location(id: 'a')
+      store.add_location(id: 'b')
+      expect(store.to_h[:location_count]).to eq(2)
+    end
+  end
+end

data/spec/legion/extensions/cognitive_map/helpers/location_spec.rb

@@ -0,0 +1,165 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::CognitiveMap::Helpers::Location do
+  subject(:location) { described_class.new(id: 'concept:ruby', domain: :programming) }
+
+  describe '#initialize' do
+    it 'sets id and domain' do
+      expect(location.id).to eq('concept:ruby')
+      expect(location.domain).to eq(:programming)
+    end
+
+    it 'starts with floor familiarity' do
+      expect(location.familiarity).to eq(Legion::Extensions::CognitiveMap::Helpers::Constants::FAMILIARITY_FLOOR)
+    end
+
+    it 'starts with zero visit count' do
+      expect(location.visit_count).to eq(0)
+    end
+
+    it 'starts with no neighbors' do
+      expect(location.neighbors).to be_empty
+    end
+
+    it 'starts with no last_visited' do
+      expect(location.last_visited).to be_nil
+    end
+  end
+
+  describe '#visit' do
+    it 'increments visit count' do
+      location.visit
+      expect(location.visit_count).to eq(1)
+    end
+
+    it 'sets last_visited' do
+      before = Time.now.utc
+      location.visit
+      expect(location.last_visited).to be >= before
+    end
+
+    it 'boosts familiarity' do
+      before = location.familiarity
+      location.visit
+      expect(location.familiarity).to be > before
+    end
+
+    it 'clamps familiarity at 1.0' do
+      20.times { location.visit }
+      expect(location.familiarity).to be <= 1.0
+    end
+
+    it 'accumulates multiple visits' do
+      3.times { location.visit }
+      expect(location.visit_count).to eq(3)
+    end
+  end
+
+  describe '#add_neighbor' do
+    it 'adds a neighbor with default distance' do
+      location.add_neighbor('concept:python')
+      expect(location.neighbors).to have_key('concept:python')
+      expect(location.neighbors['concept:python']).to eq(Legion::Extensions::CognitiveMap::Helpers::Constants::DEFAULT_DISTANCE)
+    end
+
+    it 'adds a neighbor with custom distance' do
+      location.add_neighbor('concept:java', distance: 2.5)
+      expect(location.neighbors['concept:java']).to eq(2.5)
+    end
+
+    it 'enforces distance floor' do
+      location.add_neighbor('concept:c', distance: 0.0)
+      expect(location.neighbors['concept:c']).to eq(Legion::Extensions::CognitiveMap::Helpers::Constants::DISTANCE_FLOOR)
+    end
+
+    it 'updates existing neighbor distance' do
+      location.add_neighbor('concept:python', distance: 1.0)
+      location.add_neighbor('concept:python', distance: 0.5)
+      expect(location.neighbors['concept:python']).to eq(0.5)
+    end
+
+    it 'respects MAX_EDGES_PER_LOCATION limit' do
+      max = Legion::Extensions::CognitiveMap::Helpers::Constants::MAX_EDGES_PER_LOCATION
+      (max + 5).times { |i| location.add_neighbor("neighbor_#{i}") }
+      expect(location.neighbors.size).to be <= max
+    end
+  end
+
+  describe '#remove_neighbor' do
+    it 'removes an existing neighbor' do
+      location.add_neighbor('concept:python')
+      location.remove_neighbor('concept:python')
+      expect(location.neighbors).not_to have_key('concept:python')
+    end
+
+    it 'is a no-op for unknown neighbors' do
+      expect { location.remove_neighbor('nonexistent') }.not_to raise_error
+    end
+  end
+
+  describe '#decay' do
+    it 'reduces familiarity' do
+      location.visit # raise above floor first
+      before = location.familiarity
+      location.decay
+      expect(location.familiarity).to be < before
+    end
+
+    it 'does not go below FAMILIARITY_FLOOR' do
+      10.times { location.decay }
+      expect(location.familiarity).to be >= Legion::Extensions::CognitiveMap::Helpers::Constants::FAMILIARITY_FLOOR
+    end
+  end
+
+  describe '#faded?' do
+    it 'is true for a new location at floor familiarity with zero visits' do
+      expect(location.familiarity).to eq(Legion::Extensions::CognitiveMap::Helpers::Constants::FAMILIARITY_FLOOR)
+      expect(location.visit_count).to eq(0)
+      expect(location.faded?).to be true
+    end
+
+    it 'is false after visiting' do
+      location.visit
+      expect(location.faded?).to be false
+    end
+
+    it 'is false when familiarity is above floor even with zero visits' do
+      # familiarity raised manually above floor
+      2.times { location.visit }
+      # simulate decay back but not below floor — visit_count > 0 so still false
+      10.times { location.decay }
+      expect(location.faded?).to be false
+    end
+  end
+
+  describe '#label' do
+    it 'returns a familiarity level symbol' do
+      expect(location.label).to be_a(Symbol)
+    end
+
+    it 'returns :unknown for low familiarity' do
+      # familiarity_floor is 0.05, which is in the :unknown range (0.0...0.2)
+      expect(location.label).to eq(:unknown)
+    end
+
+    it 'returns :intimate for high familiarity' do
+      10.times { location.visit }
+      expect(location.label).to eq(:intimate)
+    end
+  end
+
+  describe '#to_h' do
+    it 'returns a hash with expected keys' do
+      h = location.to_h
+      expect(h).to include(:id, :domain, :properties, :familiarity, :label, :visit_count, :neighbor_ids, :edge_count)
+    end
+
+    it 'reflects current state' do
+      location.visit
+      location.add_neighbor('other')
+      h = location.to_h
+      expect(h[:visit_count]).to eq(1)
+      expect(h[:edge_count]).to eq(1)
+    end
+  end
+end