klee 0.1.1 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b40d9febee207cdff655e91d94f0f719188454fa98592a5cb9fa7b54521ed0c7
-  data.tar.gz: 701294ca8f65152b881f6492caa4e51979e4de81dec22735989829ae87b8a015
+  metadata.gz: c8efdb5e1472295c0778a374828e8af7cb49e741a281d4d7558790863221ee0b
+  data.tar.gz: 99c547540505671159ace42750ba0ba6708aeb16f2888276a60426fc11316176
 SHA512:
-  metadata.gz: 57dc53e9ff93189272b0a5ad5d203e9921f21376c1142db3f37d5b1074808dd92f57b4b2bc2181e43f4ca0df64a9c75e467f40efaf61b0b0bc380e4aa1830a7a
-  data.tar.gz: 07a3b7c9588044077452430f1ebb9dba9a5f23443d141fcb7bb6b6b2ec4f32182cd1cd024178f9b87850aacdabe1d778ec9dc9f18d8ddd972ccaafa40993365f
+  metadata.gz: 4009d050d3439f95c2d451f7ec9a5c56f407c0fe95b269fb802335c2262886cb2bb0e159d71f7068aaa4f35c87836c366ee8745421d55e425e5791d110530df0
+  data.tar.gz: 68ffb23b66ae05b66874e677ca47bc3ed96274f681d9d0e9f3f1c84726db35851cb2f3657404690b80189284c8b1460a96d57339b9106175146f3200dae97016

data/CHANGELOG.md

@@ -5,27 +5,38 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](http://keepachangelog.com/)
 and this project adheres to [Semantic Versioning](http://semver.org/).
 
-## [0.1.1] - 2026-01-29
+## [1.0.0] - 2026-09-19
+
+### Added
+
+- Shared Words tokenizer with acronym splitting and predicate stripping (acff7d2)
+- Nested class names, attr_* methods, and constant collaborators (18d27de)
+- Klee.scan(profile: :rails) for models/lib globs and English stopwords (801fab2)
+- ConceptIndex#catalog, #gaps, and #units (801fab2)
 
 ### Changed
 
-- Switch to supporting ruby 3.4 and up. (84fdd9c)
-- Require ruby 3.4 and above (067ec87)
+- Concepts#[] returns a Hash of concept words to method names (acff7d2)
+- FileAnalyzer records each message receiver, not only locals and ivars (18d27de)
+- Klee::Collaborators wraps FileAnalyzer instead of lexing the file (18d27de)
 
-### Added
+### Fixed
 
-- Reissue for version and release support. (885fe28)
-- SimpleCov for coverage reporting (889d169)
-- Coverage comment from PRs (067ec87)
-- Klee.scan() method for codebase-wide analysis with glob patterns (3e509a1)
-- ConceptIndex for aggregating domain concepts across files (3e509a1)
-- CollaboratorIndex for pairwise co-occurrence and clustering (3e509a1)
-- FileAnalyzer using Prism AST to extract classes, methods, and collaborators (3e509a1)
-- Configurable threshold and ignore list for filtering noise (3e509a1)
-- Method-level scope option for tighter coupling analysis (3e509a1)
+- Klee.concepts now forwards the modifiers: keyword (acff7d2)
+- Operator messages, block params, and conversion chains are ignored (18d27de)
 
-## [0.1.0] - 2022-05-01
+## [0.1.2] - 2026-02-01
 
 ### Added
 
-- Initial release
+- MCP server support via klee-mcp executable (requires gem install mcp) (08c2294)
+- discover_vocabulary tool for extracting domain language (08c2294)
+- find_concept_clusters tool for identifying related concepts (08c2294)
+- explore_concept tool for deep-diving into specific concepts (08c2294)
+- find_collaborators tool for finding co-occurring objects (08c2294)
+- check_naming_consistency tool for detecting naming deviations (08c2294)
+- codebase_summary tool for high-level vocabulary overview (08c2294)
+
+### Changed
+
+- README now includes MCP server setup and available tools (f84bdc5)

data/README.md

@@ -45,11 +45,14 @@ end
 
 concept = Klee.object_concepts(Something)
 
-concept[4] #=> Set of words that appear at least 4 times
-concept[2] #=> larger Set of words that appear at least 2 times
+concept[4]
+# => { banana: [:banana_berry, :banana_boat, :banana_bunch, :banana_hammock], ... }
+
+concept[3][:address]
+# => [:address_informal_name, :address_street, :address_zip]
 
 filtered = Klee.object_concepts(Something, modifiers: %i[fill_in_ hover_over_ _message])
-filtered[4] #=> Set of concepts excluding any common modifiers
+filtered[4] # modifiers stripped before words are counted
 ```
 
 ### Scan a codebase for domain concepts
@@ -77,6 +80,31 @@ codebase = Klee.scan("app/**/*.rb",
                      threshold: 3)
 ```
 
+### Rails profile
+
+Skip views, drop English function words, and get the extract-type read model:
+
+```ruby
+cb = Klee.scan(profile: :rails) # app/models/**/*.rb + lib/**/*.rb from cwd
+
+cb.concepts.catalog.first
+# => #<data Klee::ConceptIndex::Entry word="intensity" class_count=71 method_count=29 bias=:type>
+
+cb.concepts.gaps
+# => { "seconds" => { classes: 0, methods: 95, names: #<Set: {"trailing_rest_seconds", ...}> }, ... }
+
+cb.concepts.units
+# => { "seconds" => ["cap_clock_seconds", "trailing_rest_seconds", ...], "minutes" => [...], "kg" => [...] }
+```
+
+`catalog` bias is `:type` (class-heavy), `:verb` (`build`/`calculate`/`extract`/…), `:gap` (many methods, almost no classes), or `:mixed`.
+
+Pass explicit globs with the profile to keep the stopwords:
+
+```ruby
+Klee.scan("app/models/**/*.rb", profile: :rails, threshold: 4)
+```
+
 ### Find collaborator clusters
 
 Discover which objects frequently work together across your codebase.
@@ -101,6 +129,38 @@ codebase.collaborators.clusters
 # => [Set["user", "account", "session"], Set["order", "payment", "invoice"]]
 ```
 
+### MCP Server for Claude Code
+
+Expose klee's vocabulary analysis to Claude Code or other MCP clients.
+
+```bash
+# Install the mcp gem (optional dependency)
+gem install mcp
+
+# Run the server
+klee-mcp
+```
+
+Configure Claude Code in `~/.claude.json`:
+
+```json
+{
+  "mcpServers": {
+    "klee": {
+      "command": "klee-mcp"
+    }
+  }
+}
+```
+
+Available tools:
+- `discover_vocabulary` - Extract domain language from a codebase
+- `find_concept_clusters` - Identify groups of related concepts
+- `explore_concept` - Deep-dive into a specific concept
+- `find_collaborators` - Find objects that work together
+- `check_naming_consistency` - Detect naming pattern deviations
+- `codebase_summary` - High-level vocabulary overview
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.

data/exe/klee-mcp

@@ -0,0 +1,21 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+begin
+  require "mcp"
+rescue LoadError
+  warn <<~ERROR
+    klee-mcp requires the 'mcp' gem for MCP server support.
+
+    Install it with:
+      gem install mcp
+
+    Then run klee-mcp again.
+  ERROR
+  exit 1
+end
+
+require "klee"
+require "klee/mcp"
+
+Klee::MCP::Server.new.run

data/lib/klee/codebase.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Klee
+  class Codebase
+    def initialize(*patterns, ignore: [], threshold: 2)
+      @patterns = patterns
+      @ignore = ignore
+      @threshold = threshold
+    end
+
+    def concepts
+      @concepts ||= build_concept_index
+    end
+
+    def collaborators
+      @collaborators ||= build_collaborator_index
+    end
+
+    private
+
+    def files
+      @patterns.flat_map { |p| Dir.glob(p) }
+        .uniq
+        .select { |f| File.file?(f) && f.end_with?(".rb") }
+    end
+
+    def analyzers
+      @analyzers ||= files.map { |path| FileAnalyzer.new(path) }
+    end
+
+    def build_concept_index
+      index = ConceptIndex.new(ignore: @ignore, threshold: @threshold)
+      analyzers.each { |a| index.add(a) }
+      index
+    end
+
+    def build_collaborator_index
+      index = CollaboratorIndex.new(ignore: @ignore, threshold: @threshold)
+      analyzers.each { |a| index.add(a) }
+      index
+    end
+  end
+end

data/lib/klee/collaborator_index.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module Klee
+  class CollaboratorIndex
+    def initialize(ignore: [], threshold: 2)
+      @ignore = Set.new(ignore.map(&:to_s))
+      @threshold = threshold
+      @file_pairs = Hash.new(0)
+      @method_pairs = Hash.new(0)
+    end
+
+    def add(file_analyzer)
+      # File-level pairs
+      collabs = filter(file_analyzer.collaborators.uniq)
+      each_pair(collabs) { |pair| @file_pairs[pair] += 1 }
+
+      # Method-level pairs
+      file_analyzer.method_collaborators.each_value do |method_collabs|
+        filtered = filter(method_collabs.uniq)
+        each_pair(filtered) { |pair| @method_pairs[pair] += 1 }
+      end
+    end
+
+    def pairs(scope: :file)
+      source = (scope == :method) ? @method_pairs : @file_pairs
+      source.select { |_, count| count >= @threshold }
+        .sort_by { |_, count| -count }.to_h
+    end
+
+    def for(collaborator)
+      name = collaborator.to_s
+      pairs.select { |pair, _| pair.include?(name) }
+        .transform_keys { |pair| (pair - [name]).first }
+    end
+
+    def clusters
+      build_clusters(pairs)
+    end
+
+    private
+
+    def filter(names)
+      names.map(&:to_s).reject { |n| @ignore.include?(n) }
+    end
+
+    def each_pair(items)
+      items.combination(2).each { |pair| yield pair.sort }
+    end
+
+    def build_clusters(pair_data)
+      graph = Hash.new { |h, k| h[k] = Set.new }
+      pair_data.each_key do |(a, b)|
+        graph[a] << b
+        graph[b] << a
+      end
+
+      visited = Set.new
+      clusters = []
+
+      graph.each_key do |node|
+        next if visited.include?(node)
+
+        cluster = Set.new
+        stack = [node]
+
+        while stack.any?
+          current = stack.pop
+          next if visited.include?(current)
+
+          visited << current
+          cluster << current
+          stack.concat(graph[current].to_a)
+        end
+
+        clusters << cluster if cluster.size > 1
+      end
+
+      clusters.sort_by { |c| -c.size }
+    end
+  end
+end

data/lib/klee/collaborators.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Klee
+  class Collaborators
+    def initialize(const)
+      unless const.is_a?(Module)
+        raise ArgumentError, "expected a class or module, got #{const.inspect}"
+      end
+
+      path = Object.const_source_location(const.name)&.first
+      unless path && File.file?(path)
+        raise Error, "cannot locate source for #{const}"
+      end
+
+      @const = const
+      @analyzer = FileAnalyzer.new(path)
+    end
+    attr_reader :const
+
+    def tally
+      @analyzer.collaborators.tally
+    end
+
+    def rank
+      tally.group_by { |_, count| count }
+        .sort.reverse.to_h
+        .transform_values { |value| value.map(&:first) }
+        .reject { |key, _value| key < 3 }
+    end
+  end
+end

data/lib/klee/concept_index.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+require_relative "words"
+
+module Klee
+  class ConceptIndex
+    include Enumerable
+
+    Entry = Data.define(:word, :class_count, :method_count, :class_names, :method_names, :bias)
+
+    VERBS = %w[
+      build calculate extract apply compute detect update create find get set
+      add ensure render save destroy validate serialize
+      parse process fetch refresh call fill infer display generate
+      normalize coerce prepare predict split sanitize mark
+    ].freeze
+
+    UNIT_PATTERNS = {
+      "seconds" => /_seconds\z/,
+      "minutes" => /_minutes\z/,
+      "kg" => /_kg\z/,
+      "m" => /_m\z/,
+      "reps" => /_reps\z/
+    }.freeze
+
+    def initialize(ignore: [], threshold: 2)
+      @ignore = Set.new(ignore.map(&:to_s))
+      @threshold = threshold
+      @data = Hash.new { |h, k| h[k] = {classes: Set.new, methods: Set.new} }
+    end
+
+    def add(file_analyzer)
+      file_analyzer.class_names.each do |name|
+        words_from(name).each { |word| @data[word][:classes] << name }
+      end
+
+      file_analyzer.method_names.each do |name|
+        words_from(name).each { |word| @data[word][:methods] << name }
+      end
+    end
+
+    def [](concept)
+      @data[concept.to_s]
+    end
+
+    def each(&block)
+      filtered.each(&block)
+    end
+
+    def rank
+      filtered.sort_by { |word, locs| -(locs[:classes].size + locs[:methods].size) }.to_h
+    end
+
+    def catalog
+      rank.map do |word, locs|
+        Entry.new(
+          word: word,
+          class_count: locs[:classes].size,
+          method_count: locs[:methods].size,
+          class_names: locs[:classes],
+          method_names: locs[:methods],
+          bias: bias_for(word, locs)
+        )
+      end
+    end
+
+    def gaps(min_methods: 8, max_classes: 3)
+      filtered.each_with_object({}) do |(word, locs), acc|
+        next if VERBS.include?(word)
+        next if locs[:methods].size < min_methods
+        next if locs[:classes].size > max_classes
+
+        acc[word] = {
+          classes: locs[:classes].size,
+          methods: locs[:methods].size,
+          names: locs[:methods]
+        }
+      end
+    end
+
+    def units
+      names = @data.each_value.flat_map { |locs| locs[:methods].to_a }.uniq
+      UNIT_PATTERNS.each_with_object({}) do |(unit, pattern), acc|
+        matched = names.grep(pattern)
+        acc[unit] = matched.sort if matched.size >= @threshold
+      end
+    end
+
+    private
+
+    def words_from(name)
+      Words.from(name, ignore: @ignore)
+    end
+
+    def filtered
+      @data.select { |_, locs| (locs[:classes].size + locs[:methods].size) >= @threshold }
+    end
+
+    def bias_for(word, locs)
+      return :verb if VERBS.include?(word)
+
+      class_count = locs[:classes].size
+      method_count = locs[:methods].size
+      return :type if class_count > method_count
+      return :gap if method_count >= 8 && class_count <= 3
+
+      :mixed
+    end
+  end
+end

data/lib/klee/concepts.rb

@@ -1,26 +1,24 @@
+# frozen_string_literal: true
+
+require_relative "words"
+
 module Klee
   class Concepts
     include Enumerable
 
     def initialize(*method_names, modifiers: [])
       @method_names = method_names
-      @modifiers = modifiers
+      @modifiers = Array(modifiers).map(&:to_s)
     end
     attr_reader :method_names, :modifiers
 
     def call(threshold)
-      warn "threshold is beyond the max count of #{max}" if threshold > max
-      warn "threshold is below the min count of #{min}" if threshold < min
-      clear
-      @ideas = Set.new samples
-        .select { |key, value|
-          if value.to_i >= threshold
-            key
-          end
-        }
-        .compact
-        .transform_keys(&:to_sym)
-        .keys
+      unless samples.empty?
+        warn "threshold is beyond the max count of #{max}" if threshold > max
+        warn "threshold is below the min count of #{min}" if threshold < min
+      end
+
+      method_groups.select { |_, methods| methods.size >= threshold }
     end
     alias_method :[], :call
 
@@ -38,10 +36,14 @@ module Klee
     end
 
     def max
+      return 0 if samples.empty?
+
       max_by { |_, v| v }.last
     end
 
     def min
+      return 0 if samples.empty?
+
       min_by { |_, v| v }.last
     end
 
@@ -51,22 +53,22 @@ module Klee
 
     private
 
+    def method_groups
+      groups = Hash.new { |h, k| h[k] = [] }
+      method_names.each do |name|
+        words(name).uniq.each { |word| groups[word.to_sym] << name.to_sym }
+      end
+      groups
+    end
+
     def modifier_matcher
-      @modifier_matcher ||= Regexp.new modifiers.map { Regexp.quote(it) }.join("|")
+      @modifier_matcher ||= Regexp.new(modifiers.map { Regexp.quote(it) }.join("|"))
     end
 
     def words(method_name)
-      method_name.to_s
-        .then do |string|
-          if modifiers.empty?
-            string
-          else
-            string.gsub(modifier_matcher, "")
-          end
-        end
-        .gsub(/\s/, "")
-        .split("_")
-        .delete_if { it.empty? }
+      string = method_name.to_s
+      string = string.gsub(modifier_matcher, "") unless modifiers.empty?
+      Words.from(string)
     end
   end
 end

data/lib/klee/file_analyzer.rb

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+
+require "prism"
+
+module Klee
+  class FileAnalyzer
+    ATTR_METHODS = %i[attr attr_reader attr_writer attr_accessor].freeze
+    INDEX_OPERATORS = Set[:[], :[]=].freeze
+    OPERATORS = Set.new(
+      %i[! != !~ + +@ - -@ * / % ** << >> & | ^ ~ <=> > >= < <= == === =~] +
+      INDEX_OPERATORS.to_a
+    ).freeze
+    CHAIN_NOISE = %w[
+      to_s to_str to_i to_int to_a to_ary to_h to_hash to_f to_sym to_proc
+      intern itself dup clone freeze tap new
+      where includes joins order limit offset eager_load preload
+      unscope merge distinct group having lock reselect reorder
+      first last take count map select collect compact flatten uniq
+      sort sort_by reverse each
+      Hash Array Set Rails Data Logger Kernel Object
+    ].to_set.freeze
+
+    attr_reader :path, :class_names, :method_names, :collaborators, :method_collaborators
+
+    def initialize(path)
+      @path = path
+      @class_names = []
+      @method_names = []
+      @collaborators = []
+      @method_collaborators = Hash.new { |h, k| h[k] = [] }
+      parse
+    end
+
+    private
+
+    def parse
+      result = Prism.parse_file(@path)
+      visit(result.value, current_method: nil, namespace: [], block_params: Set.new)
+    end
+
+    def visit(node, current_method:, namespace:, block_params:)
+      case node
+      when Prism::ClassNode, Prism::ModuleNode
+        full_name = qualified_name(node, namespace)
+        @class_names << full_name
+        nested = full_name.split("::")
+        node.child_nodes.compact.each do |child|
+          visit(child, current_method: current_method, namespace: nested, block_params: block_params)
+        end
+        return
+      when Prism::DefNode
+        @method_names << node.name.to_s
+        current_method = node.name.to_s
+      when Prism::BlockNode, Prism::LambdaNode
+        nested_params = block_params | Array(node.locals).map(&:to_s)
+        node.child_nodes.compact.each do |child|
+          visit(child, current_method: current_method, namespace: namespace, block_params: nested_params)
+        end
+        return
+      when Prism::CallNode
+        # Walk the receiver first so `user.account` records left-to-right.
+        if (receiver = node.receiver)
+          visit(receiver, current_method: current_method, namespace: namespace, block_params: block_params)
+        end
+        record_call(node, current_method, block_params)
+        node.child_nodes.compact.each do |child|
+          next if child.equal?(receiver)
+
+          visit(child, current_method: current_method, namespace: namespace, block_params: block_params)
+        end
+        return
+      end
+
+      node.child_nodes.compact.each do |child|
+        visit(child, current_method: current_method, namespace: namespace, block_params: block_params)
+      end
+    end
+
+    def record_call(node, current_method, block_params)
+      if attr_call?(node)
+        @method_names.concat(attr_names(node))
+        return
+      end
+
+      return if skip_operator_call?(node)
+
+      name = extract_collaborator(node)
+      return if skip_collaborator?(name, block_params)
+
+      @collaborators << name
+      @method_collaborators[current_method] << name if current_method
+    end
+
+    def skip_operator_call?(node)
+      OPERATORS.include?(node.name) && !INDEX_OPERATORS.include?(node.name)
+    end
+
+    def skip_collaborator?(name, block_params)
+      return true if name.nil? || block_params.include?(name)
+
+      key = name.to_sym
+      OPERATORS.include?(key) || CHAIN_NOISE.include?(name)
+    end
+
+    def attr_call?(node)
+      node.receiver.nil? && ATTR_METHODS.include?(node.name)
+    end
+
+    def attr_names(node)
+      args = node.arguments&.arguments || []
+      args.filter_map { |arg| attr_name_from(arg) }.map do |name|
+        (node.name == :attr_writer) ? "#{name}=" : name
+      end
+    end
+
+    def attr_name_from(arg)
+      case arg
+      when Prism::SymbolNode, Prism::StringNode
+        arg.unescaped
+      end
+    end
+
+    # A collaborator is the immediate receiver of a non-operator message.
+    def extract_collaborator(call_node)
+      case (receiver = call_node.receiver)
+      when Prism::LocalVariableReadNode
+        receiver.name.to_s
+      when Prism::InstanceVariableReadNode
+        receiver.name.to_s.delete_prefix("@")
+      when Prism::CallNode
+        receiver.name.to_s
+      when Prism::ConstantReadNode, Prism::ConstantPathNode
+        constant_name(receiver)
+      end
+    end
+
+    def qualified_name(node, namespace)
+      path = constant_name(node.constant_path)
+      return path if node.constant_path.is_a?(Prism::ConstantPathNode)
+
+      [*namespace, path].join("::")
+    end
+
+    def constant_name(node)
+      node.slice.delete_prefix("::")
+    end
+  end
+end

data/lib/klee/gestalt.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Klee
   class Gestalt
     def initialize(object, patterns:, ignored:)
@@ -33,7 +35,7 @@ module Klee
       end
 
       plot["unusual"].merge(unusual_set(threshold))
-      plot["concepts"].merge(concepts(modifiers: modifiers, threshold: concept_threshold))
+      plot["concepts"].merge(concepts(modifiers: modifiers, threshold: concept_threshold).keys)
 
       self
     end