woods 1.0.0

data/lib/woods/storage/vector_store.rb

@@ -0,0 +1,167 @@
+# frozen_string_literal: true
+
+module Woods
+  module Storage
+    # VectorStore provides an interface for storing and searching embedding vectors.
+    #
+    # All vector store adapters must include the {Interface} module and implement
+    # its methods. The {InMemory} adapter is provided for development and testing.
+    #
+    # @example Using the in-memory adapter
+    #   store = Woods::Storage::VectorStore::InMemory.new
+    #   store.store("User", [0.1, 0.2, 0.3], { type: "model" })
+    #   results = store.search([0.1, 0.2, 0.3], limit: 5)
+    #
+    module VectorStore
+      # Interface that all vector store adapters must implement.
+      module Interface
+        # Store a vector with associated metadata.
+        #
+        # @param id [String] Unique identifier for the vector
+        # @param vector [Array<Float>] The embedding vector
+        # @param metadata [Hash] Optional metadata to store alongside the vector
+        # @raise [NotImplementedError] if not implemented by adapter
+        def store(id, vector, metadata = {})
+          raise NotImplementedError
+        end
+
+        # Store multiple vectors in a single batch operation.
+        #
+        # Default implementation falls back to individual store calls.
+        # Adapters should override for bulk-optimized behavior (e.g.,
+        # multi-row INSERT for pgvector, batch upsert for Qdrant).
+        #
+        # @param entries [Array<Hash>] Each entry has :id, :vector, :metadata keys
+        def store_batch(entries)
+          entries.each { |e| store(e[:id], e[:vector], e[:metadata] || {}) }
+        end
+
+        # Search for similar vectors using cosine similarity.
+        #
+        # @param query_vector [Array<Float>] The query embedding vector
+        # @param limit [Integer] Maximum number of results to return
+        # @param filters [Hash] Optional metadata filters to apply
+        # @return [Array<SearchResult>] Results sorted by descending similarity
+        # @raise [NotImplementedError] if not implemented by adapter
+        def search(query_vector, limit: 10, filters: {})
+          raise NotImplementedError
+        end
+
+        # Delete a vector by ID.
+        #
+        # @param id [String] The identifier to delete
+        # @raise [NotImplementedError] if not implemented by adapter
+        def delete(id)
+          raise NotImplementedError
+        end
+
+        # Delete vectors matching metadata filters.
+        #
+        # @param filters [Hash] Metadata key-value pairs to match
+        # @raise [NotImplementedError] if not implemented by adapter
+        def delete_by_filter(filters)
+          raise NotImplementedError
+        end
+
+        # Return the number of stored vectors.
+        #
+        # @return [Integer] Total count
+        # @raise [NotImplementedError] if not implemented by adapter
+        def count
+          raise NotImplementedError
+        end
+      end
+
+      # Value object representing a single search result.
+      SearchResult = Struct.new(:id, :score, :metadata, keyword_init: true)
+
+      # In-memory vector store using hash storage and cosine similarity.
+      #
+      # Suitable for development and testing. Not intended for production use
+      # with large datasets.
+      #
+      # @example
+      #   store = InMemory.new
+      #   store.store("doc1", [1.0, 0.0], { type: "model" })
+      #   store.store("doc2", [0.0, 1.0], { type: "service" })
+      #   store.search([1.0, 0.0], limit: 1)
+      #   # => [#<SearchResult id="doc1", score=1.0, metadata={type: "model"}>]
+      #
+      class InMemory
+        include Interface
+
+        def initialize
+          @entries = {} # id => { vector:, metadata: }
+        end
+
+        # @see Interface#store
+        def store(id, vector, metadata = {})
+          @entries[id] = { vector: vector, metadata: metadata }
+        end
+
+        # @see Interface#search
+        def search(query_vector, limit: 10, filters: {})
+          candidates = filter_entries(filters)
+
+          scored = candidates.map do |id, entry|
+            score = cosine_similarity(query_vector, entry[:vector])
+            SearchResult.new(id: id, score: score, metadata: entry[:metadata])
+          end
+          scored.sort_by { |r| -r.score }.first(limit)
+        end
+
+        # @see Interface#delete
+        def delete(id)
+          @entries.delete(id)
+        end
+
+        # @see Interface#delete_by_filter
+        def delete_by_filter(filters)
+          @entries.reject! do |_id, entry|
+            filters.all? { |key, value| entry[:metadata][key] == value }
+          end
+        end
+
+        # @see Interface#count
+        def count
+          @entries.size
+        end
+
+        private
+
+        # Filter entries by metadata key-value pairs.
+        #
+        # @param filters [Hash] Metadata filters
+        # @return [Hash] Filtered entries
+        def filter_entries(filters)
+          return @entries if filters.empty?
+
+          @entries.select do |_id, entry|
+            filters.all? { |key, value| entry[:metadata][key] == value }
+          end
+        end
+
+        # Compute cosine similarity between two vectors.
+        #
+        # @param vec_a [Array<Float>] First vector
+        # @param vec_b [Array<Float>] Second vector
+        # @return [Float] Cosine similarity between -1.0 and 1.0
+        # @raise [ArgumentError] if vectors have different dimensions
+        def cosine_similarity(vec_a, vec_b)
+          unless vec_a.length == vec_b.length
+            raise ArgumentError,
+                  "Vector dimension mismatch (#{vec_a.length} vs #{vec_b.length})"
+          end
+
+          dot = vec_a.zip(vec_b).sum { |x, y| x * y }
+          mag_a = Math.sqrt(vec_a.sum { |x| x**2 })
+          mag_b = Math.sqrt(vec_b.sum { |x| x**2 })
+
+          return 0.0 if mag_a.zero? || mag_b.zero?
+
+          dot / (mag_a * mag_b)
+        end
+      end
+    end
+  end
+end

data/lib/woods/temporal/json_snapshot_store.rb

@@ -0,0 +1,245 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'time'
+require 'digest'
+
+module Woods
+  module Temporal
+    # JSON-file-based snapshot store for temporal tracking without SQLite.
+    #
+    # Stores snapshots as individual JSON files in a `snapshots/` subdirectory
+    # of the index output directory. Each file is named by git SHA and contains
+    # manifest metadata plus per-unit content hashes.
+    #
+    # Implements the same public interface as SnapshotStore so the MCP server
+    # tools work identically.
+    #
+    # @example
+    #   store = JsonSnapshotStore.new(dir: '/app/tmp/woods')
+    #   store.capture(manifest, unit_hashes)
+    #   store.list                    # => [{ git_sha: "abc123", ... }]
+    #   store.diff("abc123", "def456") # => { added: [...], modified: [...], deleted: [...] }
+    #
+    class JsonSnapshotStore # rubocop:disable Metrics/ClassLength
+      def initialize(dir:)
+        @dir = File.join(dir, 'snapshots')
+        FileUtils.mkdir_p(@dir)
+      end
+
+      def capture(manifest, unit_hashes)
+        git_sha = mget(manifest, 'git_sha')
+        return nil unless git_sha
+
+        previous = find_latest
+        snapshot = build_snapshot(manifest, git_sha, unit_hashes)
+
+        if previous
+          diff_result = compute_diff(previous[:units], index_units(unit_hashes))
+          snapshot[:units_added] = diff_result[:added].size
+          snapshot[:units_modified] = diff_result[:modified].size
+          snapshot[:units_deleted] = diff_result[:deleted].size
+        end
+
+        write_snapshot(git_sha, snapshot)
+        snapshot.except(:units)
+      end
+
+      def list(limit: 20, branch: nil)
+        snapshots = load_all_summaries
+        snapshots.select! { |s| s[:git_branch] == branch } if branch
+        snapshots.sort_by { |s| s[:extracted_at] || '' }.reverse.first(limit)
+      end
+
+      def find(git_sha)
+        path = snapshot_path(git_sha)
+        return nil unless File.exist?(path)
+
+        data = JSON.parse(File.read(path))
+        symbolize_snapshot(data).except(:units)
+      end
+
+      def diff(sha_a, sha_b)
+        snap_a = load_snapshot_with_units(sha_a)
+        snap_b = load_snapshot_with_units(sha_b)
+
+        return { added: [], modified: [], deleted: [] } unless snap_a && snap_b
+
+        compute_diff(snap_a[:units], snap_b[:units])
+      end
+
+      def unit_history(identifier, limit: 20)
+        snapshots = load_all_with_units
+                    .sort_by { |s| s[:extracted_at] || '' }
+                    .reverse
+                    .first(limit)
+
+        entries = snapshots.filter_map do |snap|
+          unit = snap[:units]&.[](identifier)
+          next unless unit
+
+          {
+            git_sha: snap[:git_sha],
+            extracted_at: snap[:extracted_at],
+            git_branch: snap[:git_branch],
+            unit_type: unit[:unit_type],
+            source_hash: unit[:source_hash],
+            metadata_hash: unit[:metadata_hash],
+            dependencies_hash: unit[:dependencies_hash]
+          }
+        end
+
+        mark_changed_entries(entries)
+      end
+
+      private
+
+      def mget(hash, key)
+        hash[key] || hash[key.to_sym]
+      end
+
+      def build_snapshot(manifest, git_sha, unit_hashes)
+        {
+          git_sha: git_sha,
+          git_branch: mget(manifest, 'git_branch'),
+          extracted_at: mget(manifest, 'extracted_at') || Time.now.iso8601,
+          rails_version: mget(manifest, 'rails_version'),
+          ruby_version: mget(manifest, 'ruby_version'),
+          total_units: mget(manifest, 'total_units') || unit_hashes.size,
+          unit_counts: mget(manifest, 'counts') || {},
+          gemfile_lock_sha: mget(manifest, 'gemfile_lock_sha'),
+          schema_sha: mget(manifest, 'schema_sha'),
+          units_added: 0,
+          units_modified: 0,
+          units_deleted: 0,
+          units: index_units(unit_hashes)
+        }
+      end
+
+      def index_units(unit_hashes)
+        unit_hashes.filter_map do |uh|
+          id = mget(uh, 'identifier')
+          next if id.nil?
+
+          [id, {
+            unit_type: mget(uh, 'type').to_s,
+            source_hash: mget(uh, 'source_hash'),
+            metadata_hash: mget(uh, 'metadata_hash'),
+            dependencies_hash: mget(uh, 'dependencies_hash')
+          }]
+        end.to_h
+      end
+
+      def compute_diff(units_a, units_b) # rubocop:disable Metrics/CyclomaticComplexity,Metrics/PerceivedComplexity
+        added = []
+        modified = []
+        deleted = []
+
+        units_b.each do |identifier, data_b|
+          if units_a.key?(identifier)
+            data_a = units_a[identifier]
+            if data_a[:source_hash] != data_b[:source_hash] ||
+               data_a[:metadata_hash] != data_b[:metadata_hash] ||
+               data_a[:dependencies_hash] != data_b[:dependencies_hash]
+              modified << { identifier: identifier, unit_type: data_b[:unit_type] }
+            end
+          else
+            added << { identifier: identifier, unit_type: data_b[:unit_type] }
+          end
+        end
+
+        units_a.each do |identifier, data_a|
+          deleted << { identifier: identifier, unit_type: data_a[:unit_type] } unless units_b.key?(identifier)
+        end
+
+        { added: added, modified: modified, deleted: deleted }
+      end
+
+      def mark_changed_entries(entries)
+        entries.each_with_index do |entry, i|
+          entry[:changed] = if i == entries.size - 1
+                              true
+                            else
+                              entry[:source_hash] != entries[i + 1][:source_hash]
+                            end
+        end
+        entries
+      end
+
+      def snapshot_path(git_sha)
+        raise ArgumentError, "Invalid git SHA: #{git_sha}" unless git_sha.match?(/\A[0-9a-f]+\z/i)
+
+        File.join(@dir, "#{git_sha}.json")
+      end
+
+      def write_snapshot(git_sha, data)
+        File.write(snapshot_path(git_sha), JSON.pretty_generate(data))
+      end
+
+      def load_snapshot_with_units(git_sha)
+        path = snapshot_path(git_sha)
+        return nil unless File.exist?(path)
+
+        symbolize_snapshot(JSON.parse(File.read(path)))
+      end
+
+      def load_all_summaries
+        Dir.glob(File.join(@dir, '*.json')).filter_map do |path|
+          data = JSON.parse(File.read(path))
+          symbolize_snapshot(data).except(:units)
+        rescue JSON::ParserError => e
+          warn "[Woods] Skipping corrupt snapshot #{File.basename(path)}: #{e.message}"
+          nil
+        end
+      end
+
+      def load_all_with_units
+        Dir.glob(File.join(@dir, '*.json')).filter_map do |path|
+          symbolize_snapshot(JSON.parse(File.read(path)))
+        rescue JSON::ParserError => e
+          warn "[Woods] Skipping corrupt snapshot #{File.basename(path)}: #{e.message}"
+          nil
+        end
+      end
+
+      def find_latest
+        snapshots = load_all_summaries
+        return nil if snapshots.empty?
+
+        latest = snapshots.max_by { |s| s[:extracted_at] || '' }
+        load_snapshot_with_units(latest[:git_sha])
+      end
+
+      def symbolize_snapshot(data)
+        {
+          git_sha: data['git_sha'],
+          git_branch: data['git_branch'],
+          extracted_at: data['extracted_at'],
+          rails_version: data['rails_version'],
+          ruby_version: data['ruby_version'],
+          total_units: data['total_units'],
+          unit_counts: data['unit_counts'] || {},
+          gemfile_lock_sha: data['gemfile_lock_sha'],
+          schema_sha: data['schema_sha'],
+          units_added: data['units_added'],
+          units_modified: data['units_modified'],
+          units_deleted: data['units_deleted'],
+          units: symbolize_units(data['units'])
+        }
+      end
+
+      def symbolize_units(units)
+        return {} unless units
+
+        units.transform_values do |v|
+          {
+            unit_type: v['unit_type'],
+            source_hash: v['source_hash'],
+            metadata_hash: v['metadata_hash'],
+            dependencies_hash: v['dependencies_hash']
+          }
+        end
+      end
+    end
+  end
+end