klee 0.1.1 → 1.0.0

data/lib/klee/mcp/path_validator.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Klee
+  module MCP
+    class PathValidator
+      def initialize(allowed_roots: [Dir.pwd])
+        @allowed_roots = allowed_roots.map { |r| File.expand_path(r) }
+      end
+
+      def validate!(patterns)
+        patterns.each do |pattern|
+          expanded = expand_pattern_root(pattern)
+          unless allowed?(expanded)
+            raise SecurityError, "Pattern '#{pattern}' resolves to '#{expanded}' which is outside allowed roots: #{@allowed_roots.join(", ")}"
+          end
+        end
+      end
+
+      private
+
+      def expand_pattern_root(pattern)
+        base = pattern.split(/[*?\[{]/).first || "."
+        base = "." if base.empty?
+        File.expand_path(base)
+      end
+
+      def allowed?(path)
+        @allowed_roots.any? { |root| path.start_with?(root) }
+      end
+    end
+  end
+end

data/lib/klee/mcp/server.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require "mcp"
+require_relative "tools/discover_vocabulary"
+require_relative "tools/find_concept_clusters"
+require_relative "tools/explore_concept"
+require_relative "tools/find_collaborators"
+require_relative "tools/check_naming_consistency"
+require_relative "tools/codebase_summary"
+
+module Klee
+  module MCP
+    class Server
+      TOOLS = [
+        Tools::DiscoverVocabulary,
+        Tools::FindConceptClusters,
+        Tools::ExploreConcept,
+        Tools::FindCollaborators,
+        Tools::CheckNamingConsistency,
+        Tools::CodebaseSummary
+      ].freeze
+
+      def initialize
+        @server = ::MCP::Server.new(
+          name: "klee",
+          version: Klee::MCP::VERSION,
+          tools: TOOLS
+        )
+      end
+
+      def run
+        transport = ::MCP::Server::Transports::StdioTransport.new(@server)
+        transport.open
+      end
+    end
+  end
+end

data/lib/klee/mcp/tools/check_naming_consistency.rb

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+
+module Klee
+  module MCP
+    module Tools
+      class CheckNamingConsistency < ::MCP::Tool
+        description "Find methods that deviate from established naming patterns. Identifies unusual names and suggests alternatives based on common conventions in the codebase."
+
+        input_schema(
+          properties: {
+            patterns: {
+              type: "array",
+              items: {type: "string"},
+              description: "Glob patterns to match Ruby files, e.g. ['app/**/*.rb']"
+            },
+            conventions: {
+              type: "object",
+              properties: {
+                prefixes: {
+                  type: "array",
+                  items: {type: "string"},
+                  description: "Expected method prefixes, e.g. ['find_', 'create_', 'update_', 'delete_']"
+                },
+                suffixes: {
+                  type: "array",
+                  items: {type: "string"},
+                  description: "Expected method suffixes, e.g. ['?', '!', '_at', '_by']"
+                }
+              },
+              description: "Naming conventions to check against"
+            },
+            threshold: {
+              type: "integer",
+              description: "Levenshtein distance threshold for similarity suggestions (default: 6)"
+            },
+            ignore: {
+              type: "array",
+              items: {type: "string"},
+              description: "Method names to ignore"
+            }
+          },
+          required: ["patterns"]
+        )
+
+        class << self
+          def call(patterns:, conventions: {}, threshold: 6, ignore: [], server_context: nil)
+            validator = Klee::MCP::PathValidator.new
+            validator.validate!(patterns)
+
+            codebase = Klee.scan(*patterns, ignore: ignore, threshold: 1)
+            all_methods = codebase.concepts.flat_map { |_, locs| locs[:methods].to_a }.uniq
+
+            prefixes = conventions["prefixes"] || conventions[:prefixes] || []
+            suffixes = conventions["suffixes"] || conventions[:suffixes] || []
+
+            conforming = {}
+            unusual = []
+
+            prefixes.each do |prefix|
+              matched = all_methods.select { |m| m.start_with?(prefix) }
+              conforming["#{prefix}*"] = matched.sort if matched.any?
+            end
+
+            suffixes.each do |suffix|
+              matched = all_methods.select { |m| m.end_with?(suffix) }
+              conforming["*#{suffix}"] = matched.sort if matched.any?
+            end
+
+            conforming_methods = conforming.values.flatten.uniq
+            non_conforming = all_methods - conforming_methods
+
+            non_conforming.each do |method|
+              suggestion = find_similar(method, conforming_methods, threshold)
+              unusual << if suggestion
+                {
+                  method: method,
+                  suggestion: suggestion[:name],
+                  similarity: suggestion[:distance]
+                }
+              else
+                {method: method, suggestion: nil, similarity: nil}
+              end
+            end
+
+            unusual.sort_by! { |u| u[:similarity] || Float::INFINITY }
+
+            result = {
+              conforming: conforming,
+              unusual: unusual.first(50)
+            }
+
+            ::MCP::Tool::Response.new([{
+              type: "text",
+              text: JSON.pretty_generate(result)
+            }])
+          end
+
+          private
+
+          def find_similar(method, candidates, max_distance)
+            best = nil
+            best_distance = max_distance + 1
+
+            candidates.each do |candidate|
+              distance = levenshtein_distance(method, candidate)
+              if distance < best_distance
+                best = candidate
+                best_distance = distance
+              end
+            end
+
+            best ? {name: best, distance: best_distance} : nil
+          end
+
+          def levenshtein_distance(a, b)
+            return b.length if a.empty?
+            return a.length if b.empty?
+
+            matrix = Array.new(a.length + 1) { Array.new(b.length + 1) }
+
+            (0..a.length).each { |i| matrix[i][0] = i }
+            (0..b.length).each { |j| matrix[0][j] = j }
+
+            (1..a.length).each do |i|
+              (1..b.length).each do |j|
+                cost = (a[i - 1] == b[j - 1]) ? 0 : 1
+                matrix[i][j] = [
+                  matrix[i - 1][j] + 1,
+                  matrix[i][j - 1] + 1,
+                  matrix[i - 1][j - 1] + cost
+                ].min
+              end
+            end
+
+            matrix[a.length][b.length]
+          end
+        end
+      end
+    end
+  end
+end

data/lib/klee/mcp/tools/codebase_summary.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module Klee
+  module MCP
+    module Tools
+      class CodebaseSummary < ::MCP::Tool
+        description "Get a high-level vocabulary overview of a Ruby codebase for quick onboarding. Shows top domain concepts, concept clusters, and vocabulary metrics."
+
+        input_schema(
+          properties: {
+            patterns: {
+              type: "array",
+              items: {type: "string"},
+              description: "Glob patterns to match Ruby files, e.g. ['app/**/*.rb', 'lib/**/*.rb']"
+            },
+            threshold: {
+              type: "integer",
+              description: "Minimum occurrences for concepts (default: 2)"
+            },
+            ignore: {
+              type: "array",
+              items: {type: "string"},
+              description: "Words to ignore"
+            }
+          },
+          required: ["patterns"]
+        )
+
+        class << self
+          def call(patterns:, threshold: 2, ignore: [], server_context: nil)
+            validator = Klee::MCP::PathValidator.new
+            validator.validate!(patterns)
+
+            codebase = Klee.scan(*patterns, ignore: ignore, threshold: threshold)
+
+            ranked = codebase.concepts.rank
+            top_concepts = ranked.first(15).map(&:first)
+
+            clusters = codebase.collaborators.clusters
+
+            total_classes = Set.new
+            total_methods = Set.new
+            total_identifiers = 0
+
+            codebase.concepts.each do |_, locs|
+              total_classes.merge(locs[:classes])
+              total_methods.merge(locs[:methods])
+              total_identifiers += locs[:classes].size + locs[:methods].size
+            end
+
+            unique_concepts = ranked.keys.size
+            vocabulary_richness = total_identifiers.zero? ? 0 : (unique_concepts.to_f / total_identifiers).round(2)
+
+            result = {
+              top_concepts: top_concepts,
+              concept_clusters: clusters.size,
+              total_classes: total_classes.size,
+              total_methods: total_methods.size,
+              vocabulary_richness: vocabulary_richness,
+              cluster_preview: clusters.first(3).map { |c| c.to_a.sort }
+            }
+
+            ::MCP::Tool::Response.new([{
+              type: "text",
+              text: JSON.pretty_generate(result)
+            }])
+          end
+        end
+      end
+    end
+  end
+end

data/lib/klee/mcp/tools/discover_vocabulary.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Klee
+  module MCP
+    module Tools
+      class DiscoverVocabulary < ::MCP::Tool
+        description "Extract the domain language vocabulary from a Ruby codebase. Returns words that appear frequently in class and method names, revealing the key domain concepts."
+
+        input_schema(
+          properties: {
+            patterns: {
+              type: "array",
+              items: {type: "string"},
+              description: "Glob patterns to match Ruby files, e.g. ['app/**/*.rb', 'lib/**/*.rb']"
+            },
+            threshold: {
+              type: "integer",
+              description: "Minimum occurrences for a word to be included (default: 3)"
+            },
+            limit: {
+              type: "integer",
+              description: "Maximum number of vocabulary terms to return (default: 30)"
+            },
+            ignore: {
+              type: "array",
+              items: {type: "string"},
+              description: "Words to ignore, e.g. common terms like 'get', 'set', 'new'"
+            }
+          },
+          required: ["patterns"]
+        )
+
+        class << self
+          def call(patterns:, threshold: 3, limit: 30, ignore: [], server_context: nil)
+            validator = Klee::MCP::PathValidator.new
+            validator.validate!(patterns)
+
+            codebase = Klee.scan(*patterns, ignore: ignore, threshold: threshold)
+            ranked = codebase.concepts.rank
+
+            vocabulary = ranked.first(limit).map do |word, locations|
+              {
+                word: word,
+                frequency: locations[:classes].size + locations[:methods].size,
+                in_classes: locations[:classes].to_a,
+                in_methods: locations[:methods].to_a
+              }
+            end
+
+            ::MCP::Tool::Response.new([{
+              type: "text",
+              text: JSON.pretty_generate({vocabulary: vocabulary})
+            }])
+          end
+        end
+      end
+    end
+  end
+end

data/lib/klee/mcp/tools/explore_concept.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module Klee
+  module MCP
+    module Tools
+      class ExploreConcept < ::MCP::Tool
+        description "Deep-dive into a specific domain concept to see everywhere it appears in the codebase, what it co-occurs with, and naming patterns used."
+
+        input_schema(
+          properties: {
+            patterns: {
+              type: "array",
+              items: {type: "string"},
+              description: "Glob patterns to match Ruby files, e.g. ['app/**/*.rb']"
+            },
+            concept: {
+              type: "string",
+              description: "The domain concept word to explore, e.g. 'subscription', 'user', 'order'"
+            },
+            threshold: {
+              type: "integer",
+              description: "Minimum occurrences threshold (default: 1)"
+            },
+            ignore: {
+              type: "array",
+              items: {type: "string"},
+              description: "Words to ignore"
+            }
+          },
+          required: ["patterns", "concept"]
+        )
+
+        class << self
+          def call(patterns:, concept:, threshold: 1, ignore: [], server_context: nil)
+            validator = Klee::MCP::PathValidator.new
+            validator.validate!(patterns)
+
+            codebase = Klee.scan(*patterns, ignore: ignore, threshold: threshold)
+            concept_data = codebase.concepts[concept]
+
+            collaborator_pairs = codebase.collaborators.for(concept)
+            co_occurs_with = collaborator_pairs.keys.sort_by { |k| -collaborator_pairs[k] }
+
+            methods = concept_data[:methods].to_a
+            naming_patterns = methods.group_by { |m| extract_pattern(m, concept) }
+              .transform_values(&:sort)
+
+            result = {
+              concept: concept,
+              appears_in: {
+                classes: concept_data[:classes].to_a.sort,
+                methods: methods.sort
+              },
+              co_occurs_with: co_occurs_with,
+              naming_patterns: naming_patterns
+            }
+
+            ::MCP::Tool::Response.new([{
+              type: "text",
+              text: JSON.pretty_generate(result)
+            }])
+          end
+
+          private
+
+          def extract_pattern(method_name, concept)
+            case method_name
+            when /^#{concept}_/ then "#{concept}_*"
+            when /_#{concept}$/ then "*_#{concept}"
+            when /_#{concept}_/ then "*_#{concept}_*"
+            when /#{concept}\?$/ then "#{concept}?"
+            when /#{concept}!$/ then "#{concept}!"
+            else "other"
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/klee/mcp/tools/find_collaborators.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module Klee
+  module MCP
+    module Tools
+      class FindCollaborators < ::MCP::Tool
+        description "Discover which objects conceptually belong together by analyzing co-occurrence patterns. Shows what a given object typically works with."
+
+        input_schema(
+          properties: {
+            patterns: {
+              type: "array",
+              items: {type: "string"},
+              description: "Glob patterns to match Ruby files, e.g. ['app/**/*.rb']"
+            },
+            object: {
+              type: "string",
+              description: "The object/variable name to find collaborators for, e.g. 'User', 'order', 'cart'"
+            },
+            threshold: {
+              type: "integer",
+              description: "Minimum co-occurrences to be considered a collaborator (default: 2)"
+            },
+            scope: {
+              type: "string",
+              enum: ["file", "method"],
+              description: "Scope for finding collaborators: 'file' (default) or 'method' level"
+            },
+            ignore: {
+              type: "array",
+              items: {type: "string"},
+              description: "Object names to ignore"
+            }
+          },
+          required: ["patterns", "object"]
+        )
+
+        class << self
+          def call(patterns:, object:, threshold: 2, scope: "file", ignore: [], server_context: nil)
+            validator = Klee::MCP::PathValidator.new
+            validator.validate!(patterns)
+
+            codebase = Klee.scan(*patterns, ignore: ignore, threshold: threshold)
+            pairs = codebase.collaborators.pairs(scope: scope.to_sym)
+
+            relevant_pairs = pairs.select { |pair, _| pair.include?(object) }
+
+            collaborators = relevant_pairs.map do |pair, count|
+              other = (pair - [object]).first
+              {
+                name: other,
+                co_occurrences: count,
+                scope: scope
+              }
+            end.sort_by { |c| -c[:co_occurrences] }
+
+            result = {
+              object: object,
+              collaborators: collaborators
+            }
+
+            ::MCP::Tool::Response.new([{
+              type: "text",
+              text: JSON.pretty_generate(result)
+            }])
+          end
+        end
+      end
+    end
+  end
+end

data/lib/klee/mcp/tools/find_concept_clusters.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Klee
+  module MCP
+    module Tools
+      class FindConceptClusters < ::MCP::Tool
+        description "Identify groups of domain concepts that frequently appear together in code, suggesting logical module boundaries or related functionality."
+
+        input_schema(
+          properties: {
+            patterns: {
+              type: "array",
+              items: {type: "string"},
+              description: "Glob patterns to match Ruby files, e.g. ['app/**/*.rb']"
+            },
+            threshold: {
+              type: "integer",
+              description: "Minimum co-occurrences for concepts to be considered related (default: 2)"
+            },
+            ignore: {
+              type: "array",
+              items: {type: "string"},
+              description: "Collaborator names to ignore"
+            }
+          },
+          required: ["patterns"]
+        )
+
+        class << self
+          def call(patterns:, threshold: 2, ignore: [], server_context: nil)
+            validator = Klee::MCP::PathValidator.new
+            validator.validate!(patterns)
+
+            codebase = Klee.scan(*patterns, ignore: ignore, threshold: threshold)
+            raw_clusters = codebase.collaborators.clusters
+
+            clusters = raw_clusters.map do |cluster_set|
+              {
+                concepts: cluster_set.to_a.sort,
+                size: cluster_set.size
+              }
+            end
+
+            ::MCP::Tool::Response.new([{
+              type: "text",
+              text: JSON.pretty_generate({clusters: clusters})
+            }])
+          end
+        end
+      end
+    end
+  end
+end

data/lib/klee/mcp/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Klee
+  module MCP
+    VERSION = "0.1.0"
+  end
+end

data/lib/klee/mcp.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require_relative "mcp/version"
+require_relative "mcp/path_validator"
+require_relative "mcp/server"
+
+module Klee
+  module MCP
+  end
+end

data/lib/klee/profile.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Klee
+  class Profile
+    RAILS_GLOBS = %w[app/models/**/*.rb lib/**/*.rb].freeze
+
+    STOPWORDS = %w[
+      a an the and or not to for from of in on at by as
+      is are was were been being have has had do does did
+      will would could should may might must can
+      this that these those it its they them we our you your
+      if else then when
+      with without via into over per vs all any
+      id ids key keys current value values
+    ].freeze
+
+    def self.resolve(name, patterns:, ignore:, threshold:)
+      case name&.to_sym
+      when nil
+        {patterns: patterns, ignore: Array(ignore), threshold: threshold}
+      when :rails
+        globs = patterns.empty? ? RAILS_GLOBS : patterns
+        {
+          patterns: globs,
+          ignore: (STOPWORDS + Array(ignore).map(&:to_s)).uniq,
+          threshold: threshold
+        }
+      else
+        raise ArgumentError, "unknown profile #{name.inspect}"
+      end
+    end
+  end
+end

data/lib/klee/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Klee
-  VERSION = "0.1.1"
+  VERSION = "1.0.0"
 end

data/lib/klee/words.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Klee
+  module Words
+    def self.from(name, ignore: [])
+      ignored = ignore.map(&:to_s)
+      tokenize(name).reject { |word| word.empty? || ignored.include?(word) }
+    end
+
+    def self.tokenize(name)
+      name.to_s
+        .gsub("::", "_")
+        .gsub(/([a-z\d])([A-Z])/, '\1_\2')
+        .gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2')
+        .downcase
+        .gsub(/[?!=]/, "")
+        .split(/[_\s]+/)
+    end
+  end
+end

data/lib/klee.rb

@@ -2,13 +2,15 @@
 
 # require "classifier-reborn"
 require_relative "klee/version"
+require_relative "klee/words"
 require_relative "klee/patterns"
 require_relative "klee/gestalt"
 require_relative "klee/concepts"
-require_relative "klee/collaborators"
 require_relative "klee/file_analyzer"
+require_relative "klee/collaborators"
 require_relative "klee/concept_index"
 require_relative "klee/collaborator_index"
+require_relative "klee/profile"
 require_relative "klee/codebase"
 
 module Klee
@@ -27,7 +29,7 @@ module Klee
   end
 
   def self.concepts(*method_names, modifiers: [])
-    Concepts.new(*method_names, modifiers: [])
+    Concepts.new(*method_names, modifiers: modifiers)
   end
 
   # def self.classifier
@@ -53,7 +55,8 @@ module Klee
     Klee::Collaborators.new(const)
   end
 
-  def self.scan(*patterns, ignore: [], threshold: 2)
-    Codebase.new(*patterns, ignore: ignore, threshold: threshold)
+  def self.scan(*patterns, ignore: [], threshold: 2, profile: nil)
+    spec = Profile.resolve(profile, patterns: patterns, ignore: ignore, threshold: threshold)
+    Codebase.new(*spec[:patterns], ignore: spec[:ignore], threshold: spec[:threshold])
   end
 end

data/sig/klee.rbs

@@ -0,0 +1,4 @@
+module Klee
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end