type-guessr 0.0.2 → 0.0.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fde9ec92176bfee761b076af417d5bd417720c0535f1171ed39005a4dfb7ff5f
-  data.tar.gz: 6c99963862f3304fc4e616c8d823a6df9defd0d5d4a71176d2b5fecee696d14c
+  metadata.gz: 189f36a0b1f14badab35c3ea71b7a93d7de66606378533f087dff92e3d0d3f3d
+  data.tar.gz: b68f73382fb0a2e171f19254c101125c10b83163555c14d8fb4b920c61288555
 SHA512:
-  metadata.gz: bbc08313fbdf2e00d4bcf07bc7208534db02ee4500d3af7ca0fc9f2cb2d501f8365944d8aba549cb4a96112a3217a7d145ee6a6c7e8f21fd2c5b0cde7b5c1902
-  data.tar.gz: 2b0cff3ce05f061d4ff6c6d48da8e34e6ddc5cc60fd7ecfbfc8a455f7ff83551ece15814010329361a7ef13dd4433526ecda84e750db9907f3b36cc21d99ead1
+  metadata.gz: 14029ca04179fed4e548152d6a06303d70069ef27d097ec49f17d969b58c520175de6b3a1130facefc346a9fe302d0897fcdbada1d5087f08e3dfe601cbd88a8
+  data.tar.gz: c11ad3e708e2e7ec2aa0ed7813d18967af11a07462964f5fb8426bd6c12c871a1dbd03069ba2feef6dffe517e0dd5b5c1135080ba8bbe90910533c39ffe19467

data/README.md

@@ -89,7 +89,7 @@ TypeGuessr can run as a standalone [MCP](https://modelcontextprotocol.io/) serve
 Using Claude Code CLI:
 
 ```bash
-claude mcp add type-guessr -- bundle exec ruby /path/to/type-guessr/exe/type-guessr mcp
+claude mcp add type-guessr -- bundle exec type-guessr mcp
 ```
 
 Or add to your project's `.mcp.json` manually:
@@ -99,7 +99,7 @@ Or add to your project's `.mcp.json` manually:
   "mcpServers": {
     "type-guessr": {
       "command": "bundle",
-      "args": ["exec", "ruby", "/path/to/type-guessr/exe/type-guessr", "mcp"]
+      "args": ["exec", "type-guessr", "mcp"]
     }
   }
 }
@@ -108,7 +108,7 @@ Or add to your project's `.mcp.json` manually:
 Or run directly:
 
 ```bash
-bundle exec ruby exe/type-guessr mcp [project_path]
+bundle exec type-guessr mcp [project_path]
 ```
 
 If `project_path` is omitted, the current directory is used.

data/lib/ruby_lsp/type_guessr/addon.rb

@@ -1,7 +1,6 @@
 # frozen_string_literal: true
 
 require "ruby_lsp/addon"
-require_relative "config"
 require_relative "constants"
 require_relative "runtime_adapter"
 require_relative "hover"
@@ -19,7 +18,7 @@ module RubyLsp
       end
 
       def activate(global_state, message_queue)
-        unless Config.enabled?
+        unless ::TypeGuessr::Core::Config.enabled?
           message_queue << RubyLsp::Notification.window_log_message(
             "[TypeGuessr] Disabled via config",
             type: RubyLsp::Constant::MessageType::LOG
@@ -42,9 +41,9 @@ module RubyLsp
         @runtime_adapter.swap_type_inferrer
 
         # Start debug server if enabled
-        start_debug_server if Config.debug_server_enabled?
+        start_debug_server if ::TypeGuessr::Core::Config.debug_server_enabled?
 
-        debug_status = Config.debug? ? " (debug mode enabled)" : ""
+        debug_status = ::TypeGuessr::Core::Config.debug? ? " (debug mode enabled)" : ""
         message_queue << RubyLsp::Notification.window_log_message(
           "[TypeGuessr] Activated#{debug_status}",
           type: RubyLsp::Constant::MessageType::LOG
@@ -100,7 +99,7 @@ module RubyLsp
       end
 
       private def start_debug_server
-        port = Config.debug_server_port
+        port = ::TypeGuessr::Core::Config.debug_server_port
         warn("[TypeGuessr] Starting debug server on port #{port}...")
         @debug_server = DebugServer.new(@global_state, @runtime_adapter, port: port)
         @debug_server.start

data/lib/ruby_lsp/type_guessr/code_index_adapter.rb

@@ -119,7 +119,7 @@ module RubyLsp
                        entries = if @member_index
                                    @member_index[pivot.name.to_s] || []
                                  else
-                                   @index.fuzzy_search(pivot.name.to_s) do |entry|
+                                   @index.fuzzy_search(pivot.name.to_s).select do |entry|
                                      entry.is_a?(RubyIndexer::Entry::Member) && entry.name == pivot.name.to_s
                                    end
                                  end
@@ -247,6 +247,23 @@ module RubyLsp
         nil
       end
 
+      # Inject a custom method into the duck-typing reverse index.
+      # Used by DSL adapters to register framework-generated methods (e.g., AR column accessors).
+      def register_method_class(class_name, method_name)
+        return unless @method_classes
+
+        @method_classes[method_name] ||= Set.new
+        @method_classes[method_name] << class_name
+      end
+
+      # Remove all entries for a class from the duck-typing reverse index.
+      # Used when purging DSL registrations (e.g., schema change).
+      def unregister_method_classes(class_name)
+        return unless @method_classes
+
+        @method_classes.each_value { |set| set.delete(class_name) }
+      end
+
       # Rebuild @method_classes from current @member_index state.
       private def rebuild_method_classes!
         owner_methods = {}

data/lib/ruby_lsp/type_guessr/{graph_builder.rb → debug_graph_builder.rb}

@@ -4,7 +4,7 @@ module RubyLsp
   module TypeGuessr
     # Builds graph data from IR nodes for visualization
     # Uses body_nodes structure with value/receiver/args edges
-    class GraphBuilder
+    class DebugGraphBuilder
       def initialize(runtime_adapter)
         @runtime_adapter = runtime_adapter
       end
@@ -230,9 +230,9 @@ module RubyLsp
 
       # Serialize a node to hash format
       private def serialize_node(node, node_key)
-        warn("[GraphBuilder] serialize_node: #{node_key}") if Config.debug?
+        warn("[DebugGraphBuilder] serialize_node: #{node_key}") if ::TypeGuessr::Core::Config.debug?
         result = @runtime_adapter.infer_type(node)
-        warn("[GraphBuilder] infer_type done for: #{node_key}") if Config.debug?
+        warn("[DebugGraphBuilder] infer_type done for: #{node_key}") if ::TypeGuessr::Core::Config.debug?
 
         {
           key: node_key,

data/lib/ruby_lsp/type_guessr/debug_server.rb

@@ -3,7 +3,7 @@
 require "socket"
 require "json"
 require "cgi"
-require_relative "graph_builder"
+require_relative "debug_graph_builder"
 
 module RubyLsp
   module TypeGuessr
@@ -16,7 +16,7 @@ module RubyLsp
       def initialize(global_state, runtime_adapter, port: DEFAULT_PORT)
         @global_state = global_state
         @runtime_adapter = runtime_adapter
-        @graph_builder = GraphBuilder.new(runtime_adapter)
+        @graph_builder = DebugGraphBuilder.new(runtime_adapter)
         @port = port
         @server = nil
         @thread = nil

data/lib/ruby_lsp/type_guessr/dsl/activerecord_adapter.rb

@@ -0,0 +1,404 @@
+# frozen_string_literal: true
+
+require_relative "ar_type_mapper"
+require_relative "ar_schema_watcher"
+
+module RubyLsp
+  module TypeGuessr
+    module Dsl
+      # ActiveRecord DSL adapter.
+      # Discovers AR models, fetches metadata via ServerAddon,
+      # and registers column/enum/association/scope types.
+      class ActiveRecordAdapter
+        BOOL_TYPE = ::TypeGuessr::Core::Types::Union.new([
+                                                           ::TypeGuessr::Core::Types::ClassInstance.for("TrueClass"),
+                                                           ::TypeGuessr::Core::Types::ClassInstance.for("FalseClass"),
+                                                         ]).freeze
+
+        SERVER_ADDON_NAME = "TypeGuessr"
+
+        def initialize(project_root:, cache_dir: nil)
+          @project_root = project_root
+          @schema_watcher = ArSchemaWatcher.new(project_root, cache_dir: cache_dir)
+          @registered_classes = []
+          @log_callback = nil
+        end
+
+        def on_log(&block)
+          @log_callback = block
+        end
+
+        def applicable?
+          File.directory?(File.join(@project_root, "app", "models"))
+        end
+
+        # Register AR::Base common class methods with SelfType.
+        # Called once. User.where → Relation[User] via SelfType substitution.
+        def register_base_methods(signature_registry:)
+          base = "ActiveRecord::Base"
+          self_type = ::TypeGuessr::Core::Types::SelfType.instance
+          relation_of_self = ::TypeGuessr::Core::Types::ClassInstance.for(
+            "ActiveRecord::Relation", { Elem: self_type }
+          )
+          nullable_self = ::TypeGuessr::Core::Types::Union.new([
+                                                                 self_type,
+                                                                 ::TypeGuessr::Core::Types::ClassInstance.for("NilClass"),
+                                                               ])
+          int_type = ::TypeGuessr::Core::Types::ClassInstance.for("Integer")
+          bool_type = BOOL_TYPE
+          array_of_self = ::TypeGuessr::Core::Types::ClassInstance.for("Array")
+
+          # --- Class methods ---
+
+          # Returning Relation[self]
+          %w[
+            where all order limit offset select distinct group having reorder reverse_order
+            none unscoped reselect extending joins left_joins left_outer_joins
+            includes eager_load preload references readonly lock create_with rewhere
+            or and not invert_where merge
+          ].each do |m|
+            signature_registry.register_gem_class_method(base, m, relation_of_self, force: true)
+          end
+
+          # Returning self?
+          %w[first last second third forty_two take find_by find_sole_by].each do |m|
+            signature_registry.register_gem_class_method(base, m, nullable_self, force: true)
+          end
+
+          # Returning self
+          %w[
+            first! last! take! sole find_by! find
+            create create! new
+            find_or_create_by find_or_create_by! find_or_initialize_by
+            create_or_find_by create_or_find_by!
+          ].each do |m|
+            signature_registry.register_gem_class_method(base, m, self_type, force: true)
+          end
+
+          # Returning Integer
+          %w[count update_all delete_all].each do |m|
+            signature_registry.register_gem_class_method(base, m, int_type, force: true)
+          end
+
+          # Returning Array
+          %w[ids pluck destroy_all].each do |m|
+            signature_registry.register_gem_class_method(base, m, array_of_self, force: true)
+          end
+
+          # Returning bool
+          %w[exists? any? many? none? empty?].each do |m|
+            signature_registry.register_gem_class_method(base, m, bool_type, force: true)
+          end
+
+          # --- Instance methods ---
+
+          # Returning bool
+          %w[
+            save save! update update! toggle! touch
+            new_record? persisted? destroyed? changed? previously_new_record? frozen?
+            has_changes_to_save? saved_changes? valid? invalid?
+          ].each do |m|
+            signature_registry.register_gem_method(base, m, bool_type, force: true)
+          end
+
+          # Returning self
+          %w[destroy destroy! reload toggle increment decrement increment! decrement!].each do |m|
+            signature_registry.register_gem_method(base, m, self_type, force: true)
+          end
+
+          # --- Relation instance methods ---
+          rel = "ActiveRecord::Relation"
+          elem = ::TypeGuessr::Core::Types::TypeVariable.new(:Elem)
+          nullable_elem = ::TypeGuessr::Core::Types::Union.new([
+                                                                 elem,
+                                                                 ::TypeGuessr::Core::Types::ClassInstance.for("NilClass"),
+                                                               ])
+          relation_of_elem = ::TypeGuessr::Core::Types::ClassInstance.for(
+            "ActiveRecord::Relation", { Elem: elem }
+          )
+          array_of_elem = ::TypeGuessr::Core::Types::ArrayType.new(elem)
+
+          # Returning Relation[Elem]
+          %w[
+            where or and not invert_where merge rewhere readonly lock create_with load reload
+          ].each do |m|
+            signature_registry.register_gem_method(rel, m, relation_of_elem, force: true)
+          end
+
+          # Returning Elem?
+          %w[first last second take].each do |m|
+            signature_registry.register_gem_method(rel, m, nullable_elem, force: true)
+          end
+
+          # Returning Integer
+          %w[size length count].each do |m|
+            signature_registry.register_gem_method(rel, m, int_type, force: true)
+          end
+
+          # Returning bool
+          %w[empty? any? many? none?].each do |m|
+            signature_registry.register_gem_method(rel, m, bool_type, force: true)
+          end
+
+          # Returning Array[Elem]
+          %w[to_a to_ary].each do |m|
+            signature_registry.register_gem_method(rel, m, array_of_elem, force: true)
+          end
+
+          # --- CollectionProxy instance methods ---
+          cp = "ActiveRecord::Associations::CollectionProxy"
+          elem_type = ::TypeGuessr::Core::Types::TypeVariable.new(:Elem)
+
+          %w[build create create! new].each do |m|
+            signature_registry.register_gem_method(cp, m, elem_type, force: true)
+          end
+
+          log("Registered AR::Base common methods (SelfType)")
+        end
+
+        # Cache check → cache hit: restore, cache miss + runner_client: fetch → register → save.
+        def register_models(runner_client:, signature_registry:, code_index:)
+          cached = @schema_watcher.load_cache
+          if cached
+            apply_model_data(cached, signature_registry, code_index)
+            log("Loaded #{@registered_classes.size} models from DSL cache (fast path)")
+            return
+          end
+
+          return unless runner_client
+
+          register_server_addon(runner_client)
+          models = discover_models
+          return if models.empty?
+
+          data = fetch_all_metadata(runner_client, models)
+          apply_model_data(data, signature_registry, code_index)
+          @schema_watcher.save_cache(data) unless data.empty?
+          log("Registered #{@registered_classes.size} models via ServerAddon")
+        end
+
+        def changed?
+          @schema_watcher.changed?
+        end
+
+        # Build-then-swap: fetch new data first, then purge old + apply new.
+        def refresh(runner_client:, signature_registry:, code_index:)
+          return unless runner_client
+
+          register_server_addon(runner_client)
+          models = discover_models
+          new_data = fetch_all_metadata(runner_client, models)
+
+          # Swap: purge old, apply new
+          @registered_classes.each { |cn| code_index.unregister_method_classes(cn) }
+          @registered_classes.clear
+          apply_model_data(new_data, signature_registry, code_index)
+          @schema_watcher.save_cache(new_data) unless new_data.empty?
+          log("Refreshed #{@registered_classes.size} models via ServerAddon")
+        end
+
+        private def log(message)
+          @log_callback&.call(message)
+        end
+
+        private def register_server_addon(runner_client)
+          addon_path = File.expand_path("../rails_server_addon", __dir__)
+          runner_client.register_server_addon(addon_path)
+        rescue StandardError => e
+          log("Failed to register ServerAddon: #{e.message}")
+        end
+
+        private def discover_models
+          models_dir = File.join(@project_root, "app", "models")
+          return [] unless File.directory?(models_dir)
+
+          Dir.glob(File.join(models_dir, "**", "*.rb")).filter_map do |path|
+            relative = path.delete_prefix("#{models_dir}/").delete_suffix(".rb")
+            next if relative.start_with?("concerns/")
+            next if relative == "application_record"
+
+            relative.split("/").map { |part| camelize(part) }.join("::")
+          end
+        end
+
+        private def fetch_all_metadata(runner_client, models)
+          data = {}
+
+          models.each do |class_name|
+            result = runner_client.delegate_request(
+              server_addon_name: SERVER_ADDON_NAME,
+              request_name: "model_metadata",
+              name: class_name
+            )
+            next unless result.is_a?(Hash)
+
+            model_data = build_model_data(class_name, result)
+            data[class_name] = model_data unless model_data.empty?
+          rescue StandardError => e
+            log("Failed to fetch metadata for #{class_name}: #{e.message}")
+          end
+
+          data
+        end
+
+        private def build_model_data(class_name, result)
+          methods = {}
+          build_column_methods(methods, result[:columns] || result["columns"] || [])
+          build_enum_methods(methods, class_name, result[:enums] || result["enums"] || {})
+          build_association_methods(methods, result[:associations] || result["associations"] || [])
+          build_scope_methods(methods, class_name, result[:scopes] || result["scopes"] || [])
+          methods
+        end
+
+        private def build_column_methods(methods, columns)
+          columns.each do |col|
+            col_name, col_type, nullable = col
+            col_name = col_name.to_s
+            nullable = true if nullable.nil?
+
+            # Reader: user.name → String?
+            methods[col_name] = { "kind" => "column", "type" => col_type.to_s, "nullable" => nullable }
+
+            # Predicate: user.name? → bool
+            methods["#{col_name}?"] = { "kind" => "column_predicate" }
+
+            # Dirty tracking
+            methods["#{col_name}_changed?"] = { "kind" => "column_predicate" }
+            methods["#{col_name}_previously_changed?"] = { "kind" => "column_predicate" }
+            methods["saved_change_to_#{col_name}?"] = { "kind" => "column_predicate" }
+            methods["will_save_change_to_#{col_name}?"] = { "kind" => "column_predicate" }
+            methods["#{col_name}_was"] = { "kind" => "column", "type" => col_type.to_s, "nullable" => true }
+            methods["#{col_name}_in_database"] = { "kind" => "column", "type" => col_type.to_s, "nullable" => true }
+            methods["#{col_name}_before_last_save"] = { "kind" => "column", "type" => col_type.to_s, "nullable" => true }
+            methods["#{col_name}_will_change!"] = { "kind" => "column_predicate" }
+          end
+        end
+
+        private def build_enum_methods(methods, class_name, enums)
+          enums.each do |attr_name, values|
+            methods[attr_name.to_s] = { "kind" => "enum_reader", "type" => "string", "nullable" => true }
+
+            values.each_key do |value_name|
+              methods["#{value_name}?"] = { "kind" => "enum_predicate" }
+              methods["#{value_name}!"] = { "kind" => "enum_bang" }
+              methods["scope:#{value_name}"] = { "kind" => "enum_scope", "class_name" => class_name }
+              methods["scope:not_#{value_name}"] = { "kind" => "enum_scope", "class_name" => class_name }
+            end
+          end
+        end
+
+        private def build_association_methods(methods, associations)
+          associations.each do |assoc|
+            name = (assoc[:name] || assoc["name"]).to_s
+            macro = (assoc[:macro] || assoc["macro"]).to_s
+            target = assoc[:class_name] || assoc["class_name"]
+
+            # Reader: user.posts / user.profile
+            methods[name] = { "kind" => "association", "macro" => macro, "target" => target }
+
+            # has_many: post_ids → Array[Integer]
+            if %w[has_many has_and_belongs_to_many].include?(macro)
+              singular = name.end_with?("s") ? name[0..-2] : name
+              methods["#{singular}_ids"] = { "kind" => "association_ids" }
+            end
+
+            # Derived methods for singular associations (has_one, belongs_to)
+            next unless %w[has_one belongs_to].include?(macro)
+
+            methods["build_#{name}"] = { "kind" => "association_builder", "target" => target }
+            methods["create_#{name}"] = { "kind" => "association_builder", "target" => target }
+            methods["create_#{name}!"] = { "kind" => "association_builder", "target" => target }
+            methods["reload_#{name}"] = { "kind" => "association", "macro" => macro, "target" => target }
+          end
+        end
+
+        private def build_scope_methods(methods, class_name, scopes)
+          scopes.each do |scope_name|
+            methods["scope:#{scope_name}"] = { "kind" => "scope", "class_name" => class_name }
+          end
+        end
+
+        private def apply_model_data(data, signature_registry, code_index)
+          data.each do |class_name, methods|
+            methods.each do |method_name, info|
+              case info["kind"]
+              when "column"
+                return_type = ArTypeMapper.map(info["type"], nullable: info.fetch("nullable", true))
+                register_instance_method(class_name, method_name, return_type, signature_registry, code_index)
+              when "enum_reader"
+                return_type = ArTypeMapper.map("string", nullable: true)
+                register_instance_method(class_name, method_name, return_type, signature_registry, code_index)
+              when "column_predicate"
+                register_instance_method(class_name, method_name, BOOL_TYPE, signature_registry, code_index)
+              when "enum_predicate"
+                register_instance_method(class_name, method_name, BOOL_TYPE, signature_registry, code_index)
+              when "enum_bang"
+                register_instance_method(
+                  class_name, method_name,
+                  ::TypeGuessr::Core::Types::Unknown.instance,
+                  signature_registry, code_index
+                )
+              when "enum_scope"
+                scope_name = method_name.delete_prefix("scope:")
+                register_class_scope(info["class_name"], scope_name, signature_registry)
+              when "association"
+                register_association(class_name, method_name, info["macro"], info["target"],
+                                     signature_registry, code_index)
+              when "association_builder"
+                target_type = ::TypeGuessr::Core::Types::ClassInstance.for(info["target"])
+                register_instance_method(class_name, method_name, target_type, signature_registry, code_index)
+              when "association_ids"
+                array_type = ::TypeGuessr::Core::Types::ArrayType.new(
+                  ::TypeGuessr::Core::Types::ClassInstance.for("Integer")
+                )
+                register_instance_method(class_name, method_name, array_type, signature_registry, code_index)
+              when "scope"
+                scope_name = method_name.delete_prefix("scope:")
+                register_class_scope(info["class_name"], scope_name, signature_registry)
+              end
+            end
+
+            @registered_classes << class_name
+          end
+        end
+
+        private def register_instance_method(class_name, method_name, return_type, signature_registry, code_index)
+          signature_registry.register_gem_method(class_name, method_name, return_type, force: true)
+          code_index.register_method_class(class_name, method_name)
+        end
+
+        private def register_class_scope(class_name, scope_name, signature_registry)
+          return_type = ::TypeGuessr::Core::Types::ClassInstance.for(
+            "ActiveRecord::Relation",
+            { Elem: ::TypeGuessr::Core::Types::ClassInstance.for(class_name) }
+          )
+          signature_registry.register_gem_class_method(class_name, scope_name, return_type, force: true)
+        end
+
+        private def register_association(class_name, assoc_name, macro, target, signature_registry, code_index)
+          return_type = case macro
+                        when "has_many", "has_and_belongs_to_many"
+                          ::TypeGuessr::Core::Types::ClassInstance.for(
+                            "ActiveRecord::Associations::CollectionProxy",
+                            { Elem: ::TypeGuessr::Core::Types::ClassInstance.for(target) }
+                          )
+                        when "has_one", "belongs_to"
+                          ::TypeGuessr::Core::Types::Union.new([
+                                                                 ::TypeGuessr::Core::Types::ClassInstance.for(target),
+                                                                 ::TypeGuessr::Core::Types::ClassInstance.for("NilClass"),
+                                                               ])
+                        else
+                          ::TypeGuessr::Core::Types::Unknown.instance
+                        end
+
+          register_instance_method(class_name, assoc_name, return_type, signature_registry, code_index)
+        end
+
+        private def camelize(str)
+          str.split("_").map(&:capitalize).join
+        end
+      end
+    end
+  end
+end
+# rubocop:enable Metrics/AbcSize, Metrics/MethodLength

data/lib/ruby_lsp/type_guessr/dsl/ar_schema_watcher.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+require "digest/sha2"
+require "json"
+require "fileutils"
+
+module RubyLsp
+  module TypeGuessr
+    module Dsl
+      # Watches AR schema files (db/schema.rb, db/structure.sql) for changes
+      # and manages a disk cache for DSL-generated type data.
+      #
+      # AR-specific: Mongoid has no schema file concept and needs a different strategy.
+      class ArSchemaWatcher
+        CACHE_VERSION = 1
+
+        def initialize(project_root, cache_dir: nil)
+          @project_root = project_root
+          @cache_dir = cache_dir || default_cache_dir
+          @last_hash = nil
+        end
+
+        def schema_files
+          patterns = [
+            File.join(@project_root, "db", "**", "schema.rb"),
+            File.join(@project_root, "db", "**", "structure.sql"),
+          ]
+          patterns.flat_map { |p| Dir.glob(p) }.sort
+        end
+
+        def current_hash
+          files = schema_files
+          return "empty" if files.empty?
+
+          digest = Digest::SHA256.new
+          files.each do |f|
+            digest.update(f)
+            digest.update(File.read(f))
+          end
+          digest.hexdigest
+        end
+
+        def changed?
+          hash = current_hash
+          changed = @last_hash.nil? || @last_hash != hash
+          @last_hash = hash
+          changed
+        end
+
+        def load_cache
+          path = cache_path
+          return nil unless File.exist?(path)
+
+          data = JSON.parse(File.read(path))
+          return nil unless data["version"] == CACHE_VERSION
+
+          hash = current_hash
+          return nil unless data["schema_hash"] == hash
+
+          @last_hash = hash
+          data["models"]
+        rescue JSON::ParserError, Errno::ENOENT
+          nil
+        end
+
+        def save_cache(models_data)
+          FileUtils.mkdir_p(File.dirname(cache_path))
+
+          hash = current_hash
+          data = {
+            "version" => CACHE_VERSION,
+            "schema_hash" => hash,
+            "models" => models_data
+          }
+
+          File.write(cache_path, JSON.generate(data))
+          @last_hash = hash
+        end
+
+        def clear_cache
+          FileUtils.rm_f(cache_path)
+        end
+
+        private def cache_path
+          project_dir = @project_root.gsub(%r{[/\\]}, "-").gsub(/\A-/, "")
+          File.join(@cache_dir, project_dir, "cache.json")
+        end
+
+        private def default_cache_dir
+          xdg_cache = ENV.fetch("XDG_CACHE_HOME", File.join(Dir.home, ".cache"))
+          File.join(xdg_cache, "type-guessr", "dsl-cache")
+        end
+      end
+    end
+  end
+end