needle_in_a_haystack 1.0.7 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 718b7304ea4ef3e86857b3952c4b006e322277d789dcc76a65c8dc17e27b0bd9
-  data.tar.gz: 224dd77d2955d35c4c385bd628e705d131e11700e60de3f4ee785ddb1ca74dd6
+  metadata.gz: e9481dac23d82e6d43e9c796dc66ab30c2082ded78a11591e31946fc6d2dc9fa
+  data.tar.gz: a30f6c7cce478f82b5f22f340a2112a0dc28c8acd7d72ea140010cf78280263e
 SHA512:
-  metadata.gz: d3aa136ace9cebc46612328471e932816ef65e4831ea264ef32e62c9423aaa3c8230c01adbf0ac7cc44c258bd80e3907eb48763c938d0afe3a7a899359188b7f
-  data.tar.gz: 4dcfb4bd59a773d466f050fe00b0d308b309268a59238a2e4b8b9b6a60ae81f0c14934d9d7c54a39ba08ed09d01c13d000e073b952cc6e6951b51caf6981d955
+  metadata.gz: 3a25092104aa31124158fd1010e65bc8cf0fd483ddbfb2627913ca92de36281814f6826c98dcf1746268c9e043bfbbbde09ff9c9ee1d2a4d75a0a6eca6e3be93
+  data.tar.gz: 51c3a084b9d380f9ce5beaecbb671b64e2480a7bac2b09173268d98097328e0ba835acd42e3f95056a6d377408454526f308be7e4bd1d54bc3ee9558da051829

data/README.md

@@ -1,5 +1,40 @@
 # Needle in a Haystack
 
+<img src="storage/logo.jpg" alt="Logo" width="40%">
+
+# Table of Contents
+
+- [Needle in a Haystack](#needle-in-a-haystack)
+  - [Models](#models)
+    - [HaystackTag](#haystacktag)
+      - [Attributes](#attributes)
+      - [Validations](#validations)
+      - [Associations](#associations)
+      - [Methods](#methods)
+      - [Example Usage](#example-usage)
+    - [HaystackTagging](#haystacktagging)
+      - [Associations](#associations-1)
+      - [Example Usage](#example-usage-1)
+  - [Ontology and Factory](#ontology-and-factory)
+    - [HaystackOntology](#haystackontology)
+      - [Key Methods](#key-methods)
+      - [Example Usage](#example-usage-2)
+    - [HaystackFactory](#haystackfactory)
+      - [Key Methods](#key-methods-1)
+      - [How They Work Together](#how-they-work-together)
+      - [Example Usage](#example-usage-3)
+  - [Query Strategies](#query-strategies)
+    - [QueryContext](#querycontext)
+      - [Example Usage](#example-usage-4)
+    - [QueryStrategy](#querystrategy)
+    - [FindByTagsStrategy](#findbytagsstrategy)
+    - [FindPointsWithTagStrategy](#findpointswithtagstrategy)
+  - [HaystackTag Validations and Associations](#haystacktag-validations-and-associations)
+  - [Duplicate Name Validation](#duplicate-name-validation)
+  - [Hierarchy Functionality](#hierarchy-functionality)
+  - [Path Operations](#path-operations)
+  - [Descendant and Sibling Operations](#descendant-and-sibling-operations)
+
 ## Models
 
 ### HaystackTag
@@ -169,3 +204,112 @@ The FindPointsWithTagStrategy class is a concrete implementation of QueryStrateg
 
 
 
+## HaystackTag Validations and Associations
+The HaystackTag model includes comprehensive validations and associations to ensure data integrity and support hierarchical relationships.
+
+``` ruby
+RSpec.describe HaystackTag, type: :model do
+  describe "validations and associations" do
+    subject { build(:haystack_tag) }
+
+    # Validations
+    it { is_expected.to validate_presence_of(:name) }
+    it { is_expected.to validate_presence_of(:description) }
+
+    # Associations
+    it { is_expected.to belong_to(:parent_tag).class_name("HaystackTag").optional }
+    it { is_expected.to have_many(:children).class_name("HaystackTag").with_foreign_key("parent_tag_id").dependent(:destroy).inverse_of(:parent_tag) }
+    it { is_expected.to have_many(:haystack_taggings).dependent(:destroy) }
+    it { is_expected.to have_many(:taggables).through(:haystack_taggings).source(:taggable) }
+  end
+```
+
+# Duplicate Name Validation
+HaystackTag ensures unique tag names within the same parent but allows identical names across different parents.
+
+``` ruby
+  context "when creating duplicate names" do
+    it "validates uniqueness within the same parent" do
+      parent = create(:haystack_tag)
+      create(:haystack_tag, name: "test", parent_tag: parent)
+      duplicate = build(:haystack_tag, name: "test", parent_tag: parent)
+
+      expect(duplicate).not_to be_valid
+      expect(duplicate.errors[:name]).to include("Must be unique in same category")
+    end
+
+    it "allows the same name under different parents" do
+      parent1 = create(:haystack_tag)
+      parent2 = create(:haystack_tag)
+      create(:haystack_tag, name: "test", parent_tag: parent1)
+      tag2 = build(:haystack_tag, name: "test", parent_tag: parent2)
+
+      expect(tag2).to be_valid
+    end
+  end
+```
+
+# Hierarchy Functionality
+The HaystackTag model supports hierarchical operations such as identifying roots, leaves, depth, and ancestor relationships.
+
+``` ruby
+  describe "hierarchy functionality" do
+    let(:root) { create(:haystack_tag, name: "root") }
+    let(:child) { create(:haystack_tag, name: "child", parent_tag: root) }
+    let(:grandchild) { create(:haystack_tag, name: "grandchild", parent_tag: child) }
+
+    context "basic hierarchy methods" do
+      it "identifies root and leaf nodes correctly" do
+        expect(root.root?).to be true
+        expect(child.root?).to be false
+        expect(grandchild.leaf?).to be true
+        expect(child.leaf?).to be false
+      end
+
+      it "calculates depth accurately" do
+        expect(root.depth).to eq(0)
+        expect(child.depth).to eq(1)
+        expect(grandchild.depth).to eq(2)
+      end
+
+      it "returns correct ancestors" do
+        expect(grandchild.ancestors).to eq([child, root])
+        expect(child.ancestors).to eq([root])
+        expect(root.ancestors).to be_empty
+      end
+    end
+  end
+```
+
+# Path Operations
+HaystackTag provides methods for finding tags based on hierarchical paths.
+
+``` ruby
+  context "path operations" do
+    it "retrieves tags by valid paths" do
+      expect(HaystackTag.find_by_path("root")).to eq(root)
+      expect(HaystackTag.find_by_path("root.child")).to eq(child)
+      expect(HaystackTag.find_by_path("root.child.grandchild")).to eq(grandchild)
+    end
+
+    it "handles invalid paths gracefully" do
+      expect(HaystackTag.find_by_path("invalid")).to be_nil
+      expect(HaystackTag.find_by_path("root.invalid")).to be_nil
+    end
+  end
+```
+
+# Descendant and Sibling Operations
+The HaystackTag model supports efficient retrieval of descendants and siblings.
+
+``` ruby
+  context "sibling and descendant operations" do
+    let(:sibling) { create(:haystack_tag, name: "sibling", parent_tag: root) }
+
+    it "returns all descendants correctly" do
+      expect(root.descendants).to contain_exactly(child, grandchild, sibling)
+      expect(child.descendants).to contain_exactly(grandchild)
+      expect(grandchild.descendants).to be_empty
+    end
+  end
+```

data/lib/needle_in_a_haystack/concerns/taggable.rb

@@ -1,3 +1,4 @@
+# This model represents an entity that can be tagged with HaystackTags through HaystackTaggings.
 class Taggable < ApplicationRecord
   has_many :haystack_taggings, as: :taggable, dependent: :destroy
   has_many :haystack_tags, through: :haystack_taggings

data/lib/needle_in_a_haystack/factories/haystack_factory.rb

@@ -16,11 +16,7 @@ class HaystackFactory < BaseFactory
 
   def find_or_create_tag(name, attributes = {})
     tag = HaystackTag.find_or_create_by(name: name)
-    if tag.persisted?
-      @tag_strategy.update_tag(tag, attributes)
-    else
-      tag.update(attributes)
-    end
+    tag.persisted? ? @tag_strategy.update_tag(tag, attributes) : tag.update(attributes)
     tag
   end
 
@@ -30,9 +26,7 @@ class HaystackFactory < BaseFactory
 
       tag = find_or_create_tag(name, description: data["description"], haystack_marker: data["marker"])
       tag.update(parent_tag_id: parent_tag&.id)
-
       Rails.logger.info("Created tag: #{tag.name}, Parent: #{parent_tag&.name}, Parent ID: #{parent_tag&.id}")
-
       create_tags(data["children"], tag) if data["children"]
     end
   end

data/lib/needle_in_a_haystack/models/haystack_ontology.rb

@@ -6,35 +6,24 @@ class HaystackOntology < ApplicationRecord
   def self.find_tag(path)
     return nil if path.nil?
 
-    path.include?(".") ? find_tag_in_hierarchy(tags, path.split(".").last) : find_tag_in_hierarchy(tags, path)
+    path.include?(".") ? find_tag_in_hierarchy(tags, path.split(".")) : find_tag_in_hierarchy(tags, [path])
   end
 
-  def self.find_tag_in_hierarchy(current_hash, target_key, path = [])
-    return nil unless current_hash.is_a?(Hash)
+  # This method recursively searches for a tag in a nested hash structure.
+  # - `current_hash`: The current level of the hash being searched.
+  # - `keys`: An array of keys representing the path to the desired tag.
+  # - `path`: An array to keep track of the current path (used for constructing the full path of the tag).
+  def self.find_tag_in_hierarchy(current_hash, keys, path = [])
+    return nil unless current_hash.is_a?(Hash) && keys.any?
 
-    result = current_hash[target_key]
-    return result.is_a?(Hash) ? result.merge("path" => path.push(target_key).join(".")) : result if result
+    if current_hash[keys.first].is_a?(Hash)
+      path.push(keys.shift)
+      return current_hash[path.last].merge("path" => path.join(".")) if keys.empty?
 
-    children = current_hash["children"]
-    if children.is_a?(Hash)
-      children.each do |key, value|
-        new_path = path + [key]
-        return value.merge("path" => new_path.join(".")) if key == target_key
-
-        result = find_tag_in_hierarchy(value, target_key, new_path)
-        return result if result
-      end
+      find_tag_in_hierarchy(current_hash[path.last], keys, path)
+    else
+      current_hash[keys.shift]
     end
-
-    current_hash.each do |key, value|
-      next if %w[description children].include?(key) || !value.is_a?(Hash)
-
-      new_path = path + [key]
-      result = find_tag_in_hierarchy(value, target_key, new_path)
-      return result if result
-    end
-
-    nil
   end
 
   def self.create_tags

data/lib/needle_in_a_haystack/models/haystack_tag.rb

@@ -1,6 +1,8 @@
 require "yaml"
-
 class HaystackTag < BaseTag
+  # PATH_ONTOLOGY = "/Users/frans/Documents/fouriq/fouriq_haystack/config/haystack_ontology.yml"
+  PATH_ONTOLOGY = "/Users/frans/Documents/fouriq/fouriq_haystack/config/haystack_ontology.yml"
+
   belongs_to :parent_tag, class_name: "HaystackTag", optional: true
   has_many :children, class_name: "HaystackTag", foreign_key: "parent_tag_id", dependent: :destroy, inverse_of: :parent_tag
   has_many :haystack_taggings, dependent: :destroy
@@ -11,13 +13,13 @@ class HaystackTag < BaseTag
   validate :prevent_circular_reference
   validate :ensure_identity
 
-  CATEGORIES = YAML.load_file("/Users/frans/Documents/fouriq/fouriq_haystack/lib/haystack_ontology.yml")
+  CATEGORIES = YAML.load_file(PATH_ONTOLOGY)
 
   def ancestors
     ancestors = []
     current = self
     while current.parent_tag
-      break if ancestors.include?(current.parent_tag) # Voorkom oneindige lus
+      break if ancestors.include?(current.parent_tag)
 
       ancestors << current.parent_tag
       current = current.parent_tag

data/lib/needle_in_a_haystack/version.rb

@@ -1 +1 @@
-VERSION = "1.0.7".freeze
+VERSION = "1.1.0".freeze

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: needle_in_a_haystack
 version: !ruby/object:Gem::Version
-  version: 1.0.7
+  version: 1.1.0
 platform: ruby
 authors:
 - Frans Verberne
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-12-11 00:00:00.000000000 Z
+date: 2024-12-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: dotenv-rails
@@ -80,7 +80,8 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-description: haystack ontology implementation for FourIQ projects.
+description: A Ruby gem for implementing the Haystack ontology, providing a structured
+  way to manage and interact with building and equipment data.
 email:
 - frans.verberne@fouriq.nl
 executables: []
@@ -112,14 +113,12 @@ files:
 - lib/needle_in_a_haystack/strategies/query_strategy.rb
 - lib/needle_in_a_haystack/strategies/tag_strategy.rb
 - lib/needle_in_a_haystack/version.rb
-- lib/tasks/location_create.rake
 - spec/models/haystack_tag_spec.rb
-- spec/strategies/find_by_tags_strategy_spec.rb
-homepage: https://www.fouriq.nl
+homepage: https://github.com/Fransver/needle_in_a_haystack
 licenses:
-- Nonstandard
+- MIT
 metadata:
-  homepage_uri: https://www.fouriq.nl
+  homepage_uri: https://github.com/Fransver/needle_in_a_haystack
 post_install_message:
 rdoc_options: []
 require_paths:
@@ -138,5 +137,5 @@ requirements: []
 rubygems_version: 3.5.18
 signing_key:
 specification_version: 4
-summary: Models and dependencies shared across our projects.
+summary: haystack ontology implementation for FourIQ projects.
 test_files: []

data/lib/tasks/location_create.rake

@@ -1,7 +0,0 @@
-namespace :locations do
-  desc "Interactive location creator"
-  task create: :environment do
-    load "app/services/location_creator.rb"
-    LocationCreator.start
-  end
-end

data/spec/strategies/find_by_tags_strategy_spec.rb

@@ -1,38 +0,0 @@
-require "rails_helper"
-
-RSpec.describe FindByTagsStrategy, type: :strategy do
-  let(:bedroom) { HaystackTag.create(name: "bedRoom", description: "A Bedroom") }
-  let(:lora) { HaystackTag.create(name: "loraMeter", description: "A Lora Meter") }
-  let(:indoor_temp) { HaystackTag.create(name: "tempIndoor", description: "A Indoor temperature sensor") }
-  let(:device) { Device.create(name: "Device1") }
-  let(:point) { Point.create }
-
-  before do
-    device.haystack_tags << [bedroom, lora]
-    folder = device.folders.create(name: "Folder1")
-    folder.points << point
-    point.haystack_tags << [indoor_temp, bedroom]
-  end
-
-  describe "#execute" do
-    context "when finding devices by tags" do
-      it "returns devices with the specified tags" do
-        strategy = described_class.new(Device, [bedroom, lora])
-        context = QueryContext.new(strategy)
-        result = context.execute
-
-        expect(result).to include(device)
-      end
-    end
-
-    context "when finding points by tags" do
-      it "returns points with the specified tags" do
-        strategy = described_class.new(Point, [indoor_temp])
-        context = QueryContext.new(strategy)
-        result = context.execute
-
-        expect(result).to include(point)
-      end
-    end
-  end
-end