hecks 3.5.0 → 3.7.0

data/lib/hecks/query_ir/touchpoints.rb

@@ -0,0 +1,104 @@
+module Hecks
+  module QueryIR
+    # The propagation touchpoints of a construct/field pair, checked in prose and in code. Extended
+    # onto `QueryIR`.
+    module Touchpoints
+      # The two `MetaValidator::Reconstruction` methods written by hand rather than driven by
+      # `Assembly::Contracts`; `impact_preview` checks touchpoint 4 only for these.
+      RECONSTRUCTION_METHODS = { "Aggregate" => :aggregate, "Entity" => :entity }.freeze
+
+      # Checks the six touchpoints of `.claude/skills/bluebook-construct-creator/SKILL.md` for a
+      # construct/field pair. Advisory, not a gate: a `false` can be a legitimate exemption
+      # (`Deviations`, `GUARANTEED_BY_CONSTRUCTION`, or the spec-only `META_DOMAIN_KNOWN_GAPS`).
+      #
+      # @param name [String] a `CONSTRUCTS` key, such as `"Aggregate"`
+      # @param field [String, Symbol] the declared field to check propagation for
+      # @return [Hash{Symbol => Object}] `:name`, `:field`, and `:touchpoints` — an
+      #   `Array<Hash>` of `:touchpoint` (String) and `:present` (Boolean, or nil when the
+      #   touchpoint does not apply to `name`)
+      # @raise [ArgumentError] if `name` is not a `CONSTRUCTS` key
+      def impact_preview(name, field)
+        CONSTRUCTS.fetch(name) { raise ArgumentError, "no such construct #{name.inspect} — known: #{CONSTRUCTS.keys.join(", ")}" }
+        field = field.to_s
+        { name: name, field: field, touchpoints: touchpoints(name, field) }
+      end
+
+      private
+
+      def touchpoints(name, field)
+        [
+          { touchpoint: "meta-domain grammar declares it", present: meta_declared(name).map(&:to_s).include?(field) },
+          { touchpoint: "docs/resolution-rules/ names it", present: resolution_rule_mentions?(field) },
+          { touchpoint: "Assembly::Contracts consumes it", present: contract_consumes?(name, field) },
+          { touchpoint: "Reconstruction's hand-typed method reads it", present: reconstruction_reads?(name, field) },
+          { touchpoint: "fuzzer FEATURE_COVERAGE/GUARANTEED_BY_CONSTRUCTION claims it", present: fuzzer_claims?(name, field) },
+          { touchpoint: "Rust mirror (rust/parser/src/parse/*.rs) mentions it", present: rust_mentions?(field) }
+        ]
+      end
+
+      def resolution_rule_mentions?(field)
+        paths = Dir.glob(File.join(Codemod::ROOT, "docs/resolution-rules/*.md")) +
+                Dir.glob(File.join(Codemod::ROOT, "docs/implemented/resolution-rules/*.md"))
+        paths.any? { |path| File.read(path).include?(field) }
+      end
+
+      def contract_consumes?(name, field)
+        contract = Hecks::Bluebook::Assembly.contract(name)
+        contract.fields.key?(field.to_sym) || contract.derived.key?(field.to_sym)
+      rescue KeyError
+        false
+      end
+
+      # nil, not false, for constructs without a hand-typed method: the touchpoint does not apply.
+      def reconstruction_reads?(name, field)
+        method_name = RECONSTRUCTION_METHODS[name]
+        # rubocop:disable-next Style/ReturnNilInPredicateMethodDefinition -- nil vs
+        # false is a deliberate distinction here: nil means "not applicable" (no
+        # hand-typed method to check), false means "applicable, and it fails" —
+        # see the spec's own "not-applicable (nil), not false" example.
+        return nil unless method_name
+
+        reconstruction_body(method_name).include?("#{field}:")
+      end
+
+      # @return [String] the source of one hand-typed `Reconstruction` method and of the helpers it
+      #   delegates to, which are named `<method>_*`
+      def reconstruction_body(method_name)
+        reconstruction_method_names(method_name).map { |name| reconstruction_method_source(name) }.join
+      end
+
+      # @return [Array<Symbol>] `method_name` followed by its `<method_name>_*` helpers
+      def reconstruction_method_names(method_name)
+        reconstruction = Hecks::Bluebook::MetaValidator::Reconstruction
+        helpers = reconstruction.instance_methods + reconstruction.private_instance_methods
+        [method_name, *helpers.select { |name| name.to_s.start_with?("#{method_name}_") }.sort]
+      end
+
+      # @return [String] the source of one `Reconstruction` method
+      def reconstruction_method_source(method_name)
+        file, start_line = Hecks::Bluebook::MetaValidator::Reconstruction.instance_method(method_name).source_location
+        lines = File.readlines(file)
+        indent = lines[start_line - 1][/\A\s*/]
+
+        lines[start_line..].take_while { |line| inside_method?(line, indent) }.join
+      end
+
+      # @param indent [String] the whitespace the method's `def` line starts with
+      # @return [Boolean] whether the line still belongs to the method: blank, indented deeper, or
+      #   not the next `def`
+      def inside_method?(line, indent)
+        line.strip.empty? || line[/\A\s*/].size > indent.size || !line.lstrip.start_with?("def ")
+      end
+
+      def fuzzer_claims?(name, field)
+        key = "#{name}##{field}"
+        Hecks::Fuzzing::Properties::FEATURE_COVERAGE.values.flatten.include?(key) ||
+          Hecks::Fuzzing::Properties::GUARANTEED_BY_CONSTRUCTION.key?(key)
+      end
+
+      def rust_mentions?(field)
+        Dir.glob(File.join(Codemod::ROOT, "rust/parser/src/parse/*.rs")).any? { |path| File.read(path).include?(field) }
+      end
+    end
+  end
+end

data/lib/hecks/query_ir.rb

@@ -2,10 +2,16 @@ require_relative "bluebook"
 require_relative "codemod"
 require_relative "projections/model"
 require_relative "fuzzing/properties"
+require_relative "query_ir/rules"
+require_relative "query_ir/formatting"
+require_relative "query_ir/touchpoints"
 
 module Hecks
   # Shared core of `hecks ir_constructs` and `hecks serve_query_ir_mcp`.
   # Returns structured data; formatting belongs to each front end.
+  #
+  # The rule collection, the text renderings and the propagation touchpoints live in `Rules`,
+  # `Formatting` and `Touchpoints`, extended onto this module.
   module QueryIR
     Codemod    = Hecks::Codemod
     Deviations = Hecks::Projections::Model::Deviations
@@ -25,6 +31,10 @@ module Hecks
 
     Rule = Struct.new(:kind, :description, :canonical, :location, keyword_init: true)
 
+    extend Rules
+    extend Formatting
+    extend Touchpoints
+
     module_function
 
     # Reads the fields the language declares for one construct kind, from the grammar itself.
@@ -45,27 +55,35 @@ module Hecks
     # @raise [ArgumentError] if `name` is not a `CONSTRUCTS` key
     def construct_diff(name)
       klass = CONSTRUCTS.fetch(name) do
-        raise ArgumentError, "no such construct #{name.inspect} — known: #{CONSTRUCTS.keys.join(', ')}"
+        raise ArgumentError, "no such construct #{name.inspect} — known: #{CONSTRUCTS.keys.join(", ")}"
       end
       declared = meta_declared(name)
       emitted  = klass.ir_spec.keys
 
-      accounted = declared.reject { |field| Deviations.parent_ref?(field) } -
-                  Deviations.judge_only(name) -
-                  Deviations.folded(name).values.flatten -
-                  Deviations.off_the_wire(name) -
-                  Deviations.dynamic_tail(name) -
-                  Deviations.unpacked(name).keys
+      { name: name, declared: declared, emitted: emitted,
+        missing_from_ruby: accounted_fields(name, declared) - emitted,
+        unaccounted_in_ruby: unaccounted_fields(name, declared, emitted) }
+    end
 
-      unaccounted = emitted -
-                    declared -
-                    Deviations.contained(name) -
-                    Deviations.folded(name).keys -
-                    Deviations.computed(name) -
-                    Deviations.unpacked(name).values.flatten
+    # @return [Array<Symbol>] the declared fields the Ruby class must emit: all but the named
+    #   deviations
+    def accounted_fields(name, declared)
+      declared.reject { |field| Deviations.parent_ref?(field) } -
+        Deviations.judge_only(name) -
+        Deviations.folded(name).values.flatten -
+        Deviations.off_the_wire(name) -
+        Deviations.dynamic_tail(name) -
+        Deviations.unpacked(name).keys
+    end
 
-      { name: name, declared: declared, emitted: emitted,
-        missing_from_ruby: accounted - emitted, unaccounted_in_ruby: unaccounted }
+    # @return [Array<Symbol>] the emitted fields the grammar does not declare and no deviation names
+    def unaccounted_fields(name, declared, emitted)
+      emitted -
+        declared -
+        Deviations.contained(name) -
+        Deviations.folded(name).keys -
+        Deviations.computed(name) -
+        Deviations.unpacked(name).values.flatten
     end
 
     # Diffs one or every construct kind at once.
@@ -76,271 +94,5 @@ module Hecks
       targets = names.empty? ? CONSTRUCTS.keys : names
       targets.map { |name| construct_diff(name) }
     end
-
-    # Every given/ensures/invariant reachable from a booted registry, walked recursively.
-    #
-    # Object identity carries no signal: `MetaValidator.call` rebuilds the graph from flat rows,
-    # so a bare `given("x")` reference and its block declaration are distinct objects by then.
-    # @param registry [Runtime::Registry] the booted registry to walk
-    # @param chapter_name [String, nil] one chapter to walk, every booted chapter when nil
-    # @return [Array<Rule>]
-    def collect_rules(registry, chapter_name = nil)
-      rules = []
-      chapters = chapter_name ? [registry.bluebook(chapter_name)] : registry.bluebooks.values
-
-      chapters.each do |chapter|
-        chapter.aggregates.each do |aggregate|
-          walk_construct_rules(aggregate, aggregate.hecks_name, rules)
-          aggregate.value_objects.each do |vo|
-            vo.invariants.each do |rule|
-              rules << Rule.new(kind: "invariant", description: rule.description, canonical: rule.canonical,
-                                location: "#{aggregate.hecks_name}::#{vo.hecks_name} (declared)")
-            end
-          end
-        end
-      end
-      rules
-    end
-
-    # Recursive walk behind `collect_rules`; appends to `rules` in place.
-    def walk_construct_rules(construct, path, rules)
-      (construct.respond_to?(:preconditions) ? construct.preconditions : []).each do |rule|
-        rules << Rule.new(kind: "given", description: rule.description, canonical: rule.canonical,
-                          location: "#{path} (declared)")
-      end
-      (construct.respond_to?(:invariants) ? construct.invariants : []).each do |rule|
-        rules << Rule.new(kind: "invariant", description: rule.description, canonical: rule.canonical,
-                          location: "#{path} (declared)")
-      end
-      construct.commands.each do |command|
-        command.givens.each do |rule|
-          rules << Rule.new(kind: "given", description: rule.description, canonical: rule.canonical,
-                            location: "#{path}.#{command.hecks_name}")
-        end
-        command.ensures.each do |rule|
-          rules << Rule.new(kind: "ensures", description: rule.description, canonical: rule.canonical,
-                            location: "#{path}.#{command.hecks_name}")
-        end
-      end
-      return unless construct.respond_to?(:entities)
-
-      construct.entities.each do |piece|
-        walk_construct_rules(piece, "#{path}.#{piece.hecks_name}", rules)
-      end
-    end
-    private_class_method :walk_construct_rules
-
-    # A rule's owner: the path a "(declared)" location names, or a command-level location
-    # with its trailing `.CommandName` stripped.
-    #
-    # @param location [String] a `Rule#location`
-    # @return [String] the owning construct's path, with `" (declared)"` or a trailing
-    #   `.CommandName` segment stripped
-    def owner_of(location)
-      return location.sub(/ \(declared\)\z/, "") if location.end_with?(" (declared)")
-
-      location.rpartition(".").first
-    end
-
-    # Groups rules by (kind, description, canonical) and reports groups with more than one
-    # real declaration, counted by owner rather than object identity (see `collect_rules`).
-    #
-    # `domains: []` scans the self-hosted meta-domain only; `nil` adds every real example.
-    # @param domains [Array<String>, nil] domain root directories to scan; every real
-    #   example (`Codemod::EXAMPLE_ROOTS`) when nil, none beyond the meta-domain when `[]`
-    # @param include_meta [Boolean] whether to also scan the self-hosted meta-domain
-    # @return [Array<Hash>] one entry per duplicate group: `:kind`, `:description`,
-    #   `:canonical`, and `:locations` (`Array<String>`)
-    def duplicates(domains: nil, include_meta: true)
-      domains ||= Codemod::EXAMPLE_ROOTS
-      all_rules = []
-      all_rules.concat(collect_rules(Codemod.meta_registry)) if include_meta
-
-      domains.each do |domain_dir|
-        bluebook_files = Dir.glob(File.join(domain_dir, "bluebook", "*.bluebook"))
-        next if bluebook_files.empty?
-
-        registry = Codemod.load_bluebook(bluebook_files)
-        all_rules.concat(collect_rules(registry))
-      end
-
-      all_rules.group_by { |r| [r.kind, r.description, r.canonical] }
-               .map { |key, rules| [key, rules, declaration_count(rules)] }
-               .select { |_, _, count| count > 1 }
-               .map do |(kind, description, canonical), rules, _|
-        { kind: kind, description: description, canonical: canonical,
-      locations: rules.map(&:location) }
-      end
-    end
-
-    # A rule owned by a nested entity is also covered by a "(declared)" entry anywhere under the
-    # same root aggregate, matching the DSL's shared given pool.
-    #
-    # Known gap: a bare chapter-wide `given(desc)` reference still shows as its own "(declared)"
-    # owner, because the built IR cannot tell a reference from a declaration. Verify a flagged
-    # group by hand before treating it as fresh duplication.
-    # @param rules [Array<Rule>] one duplicate-key group's own rules
-    # @return [Integer] how many of `rules` are real, independent declarations
-    def declaration_count(rules)
-      declared = rules.select { |r| r.location.end_with?(" (declared)") }
-      declared_owners = declared.to_set { |r| owner_of(r.location) }
-      declared_given_roots = declared.select { |r| r.kind == "given" }
-                                     .to_set { |r| owner_of(r.location).split(".").first }
-
-      standalone = rules.reject do |r|
-        owner = owner_of(r.location)
-        next true if declared_owners.include?(owner)
-        next true if r.kind == "given" && owner.include?(".") && declared_given_roots.include?(owner.split(".").first)
-
-        false
-      end
-
-      declared_owners.size + standalone.size
-    end
-    private_class_method :declaration_count
-
-    # Renders `constructs` output as text, shared by `hecks ir_constructs` and `hecks
-    # serve_query_ir_mcp`.
-    #
-    # @param diffs [Array<Hash>] `constructs`' own output
-    # @return [String] the human-readable rendering
-    def format_constructs(diffs)
-      diffs.map do |diff|
-        lines = ["== #{diff[:name]} =="]
-        lines << "  emits:    #{diff[:emitted].join(', ')}"
-        lines << "  declares: #{diff[:declared].join(', ')}"
-        if diff[:missing_from_ruby].empty? && diff[:unaccounted_in_ruby].empty?
-          lines << "  clean — every declared field is emitted (or a named deviation), nothing emitted is undeclared"
-        else
-          unless diff[:missing_from_ruby].empty?
-            lines << "  MISSING FROM RUBY (declared, not emitted, not a named deviation): " \
-                     "#{diff[:missing_from_ruby].join(', ')}"
-          end
-          unless diff[:unaccounted_in_ruby].empty?
-            lines << "  UNACCOUNTED IN RUBY (emitted, not declared, not a named deviation): " \
-                     "#{diff[:unaccounted_in_ruby].join(', ')}"
-          end
-        end
-        lines.join("\n")
-      end.join("\n\n")
-    end
-
-    # The two `MetaValidator::Reconstruction` methods written by hand rather than driven by
-    # `Assembly::Contracts`; `impact_preview` checks touchpoint 4 only for these.
-    RECONSTRUCTION_METHODS = { "Aggregate" => :aggregate, "Entity" => :entity }.freeze
-
-    # Checks the six touchpoints of `.claude/skills/bluebook-construct-creator/SKILL.md` for a
-    # construct/field pair. Advisory, not a gate: a `false` can be a legitimate exemption
-    # (`Deviations`, `GUARANTEED_BY_CONSTRUCTION`, or the spec-only `META_DOMAIN_KNOWN_GAPS`).
-    #
-    # @param name [String] a `CONSTRUCTS` key, such as `"Aggregate"`
-    # @param field [String, Symbol] the declared field to check propagation for
-    # @return [Hash{Symbol => Object}] `:name`, `:field`, and `:touchpoints` — an
-    #   `Array<Hash>` of `:touchpoint` (String) and `:present` (Boolean, or nil when the
-    #   touchpoint does not apply to `name`)
-    # @raise [ArgumentError] if `name` is not a `CONSTRUCTS` key
-    def impact_preview(name, field)
-      CONSTRUCTS.fetch(name) { raise ArgumentError, "no such construct #{name.inspect} — known: #{CONSTRUCTS.keys.join(', ')}" }
-      field = field.to_s
-
-      {
-        name:        name,
-        field:       field,
-        touchpoints: [
-          { touchpoint: "meta-domain grammar declares it", present: meta_declared(name).map(&:to_s).include?(field) },
-          { touchpoint: "docs/resolution-rules/ names it", present: resolution_rule_mentions?(field) },
-          { touchpoint: "Assembly::Contracts consumes it", present: contract_consumes?(name, field) },
-          { touchpoint: "Reconstruction's hand-typed method reads it", present: reconstruction_reads?(name, field) },
-          { touchpoint: "fuzzer FEATURE_COVERAGE/GUARANTEED_BY_CONSTRUCTION claims it", present: fuzzer_claims?(name, field) },
-          { touchpoint: "Rust mirror (rust/parser/src/parse/*.rs) mentions it", present: rust_mentions?(field) }
-        ]
-      }
-    end
-
-    def resolution_rule_mentions?(field)
-      paths = Dir.glob(File.join(Codemod::ROOT, "docs/resolution-rules/*.md")) +
-              Dir.glob(File.join(Codemod::ROOT, "docs/implemented/resolution-rules/*.md"))
-      paths.any? { |path| File.read(path).include?(field) }
-    end
-    private_class_method :resolution_rule_mentions?
-
-    def contract_consumes?(name, field)
-      contract = Hecks::Bluebook::Assembly.contract(name)
-      contract.fields.key?(field.to_sym) || contract.derived.key?(field.to_sym)
-    rescue KeyError
-      false
-    end
-    private_class_method :contract_consumes?
-
-    # nil, not false, for constructs without a hand-typed method: the touchpoint does not apply.
-    def reconstruction_reads?(name, field)
-      method_name = RECONSTRUCTION_METHODS[name]
-      # rubocop:disable-next Style/ReturnNilInPredicateMethodDefinition -- nil vs
-      # false is a deliberate distinction here: nil means "not applicable" (no
-      # hand-typed method to check), false means "applicable, and it fails" —
-      # see the spec's own "not-applicable (nil), not false" example.
-      return nil unless method_name
-
-      file, start_line = Hecks::Bluebook::MetaValidator::Reconstruction.instance_method(method_name).source_location
-      lines = File.readlines(file)
-      def_line = lines[start_line - 1]
-      indent = def_line[/\A\s*/]
-
-      body = lines[start_line..].take_while do |line|
-        line.strip.empty? || line[/\A\s*/].size > indent.size || !line.lstrip.start_with?("def ")
-      end
-      body.join.include?("#{field}:")
-    end
-    private_class_method :reconstruction_reads?
-
-    def fuzzer_claims?(name, field)
-      key = "#{name}##{field}"
-      Hecks::Fuzzing::Properties::FEATURE_COVERAGE.values.flatten.include?(key) ||
-        Hecks::Fuzzing::Properties::GUARANTEED_BY_CONSTRUCTION.key?(key)
-    end
-    private_class_method :fuzzer_claims?
-
-    def rust_mentions?(field)
-      Dir.glob(File.join(Codemod::ROOT, "rust/parser/src/parse/*.rs")).any? { |path| File.read(path).include?(field) }
-    end
-    private_class_method :rust_mentions?
-
-    # Renders one field's touchpoint checklist as text.
-    #
-    # @param preview [Hash] `impact_preview`'s own output
-    # @return [String] the human-readable rendering
-    def format_impact_preview(preview)
-      lines = ["== #{preview[:name]}##{preview[:field]} =="]
-      preview[:touchpoints].each do |t|
-        mark = if t[:present].nil?
-                 "n/a"
-               else
-                 (t[:present] ? "yes" : "NOT YET")
-               end
-        lines << "  [#{mark.rjust(7)}] #{t[:touchpoint]}"
-      end
-      done = preview[:touchpoints].count { |t| t[:present] == true }
-      total = preview[:touchpoints].count { |t| !t[:present].nil? }
-      lines << ""
-      lines << "#{done}/#{total} applicable touchpoint(s) show signs of this field — advisory, not a gate; " \
-               "a NOT YET can be a legitimate exemption (Deviations, GUARANTEED_BY_CONSTRUCTION, or a spec-only " \
-               "META_DOMAIN_KNOWN_GAPS entry this module deliberately never reads)."
-      lines.join("\n")
-    end
-
-    # Renders the duplicate-rule groups as text.
-    #
-    # @param groups [Array<Hash>] `duplicates`' own output
-    # @return [String] the human-readable rendering
-    def format_duplicates(groups)
-      return "no duplicate given/invariant/ensures rule found" if groups.empty?
-
-      body = groups.map do |group|
-        ["== #{group[:kind]}: #{group[:description].inspect} — #{group[:canonical]} ==",
-         *group[:locations].map { |loc| "  #{loc}" }].join("\n")
-      end.join("\n\n")
-
-      "#{body}\n\n#{groups.size} duplicate group(s), #{groups.sum { |g| g[:locations].size }} declarations total"
-    end
   end
 end

data/lib/hecks/query_ir_mcp/tools.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Hecks
+  module QueryIrMcp
+    # The three tools, as an MCP client lists them.
+    TOOLS = [
+      {
+        name:        "query_ir_constructs",
+        description: "For a bluebook IR construct (Aggregate, Entity, Command, Query, ValueObject, Policy, " \
+                     "ReadModel, ProcessManager, Bluebook) or all of them, the real structural diff between " \
+                     "what the Ruby class emits and what the self-hosted meta-domain declares for it. Use " \
+                     "this instead of reading entity.rb/entity.bluebook (or the equivalent pair for another " \
+                     "construct) by hand to check whether a new IR field has been fully propagated.",
+        inputSchema: {
+          type:       "object",
+          properties: {
+            names: {
+              type:        "array",
+              items:       { type: "string" },
+              description: "Construct names to check (e.g. [\"Entity\"]). Omit or leave empty for all constructs."
+            }
+          }
+        }
+      },
+      {
+        name:        "query_ir_duplicates",
+        description: "Every given/ensures/invariant DECLARATION across the real corpus " \
+                     "(banking/pizzas/compliance) and the self-hosted meta-domain, grouped by (kind, " \
+                     "description, canonical predicate), reporting every group with more than one " \
+                     "independently-declared rule (already-deduped references, which share the same " \
+                     "underlying rule object, are excluded). Use this to find real corpus duplication " \
+                     "before proposing a new 'declared once, referenced by name' resolution rule.",
+        inputSchema: {
+          type:       "object",
+          properties: {
+            domains:      {
+              type:        "array",
+              items:       { type: "string" },
+              description: "Real example domain directories to scan (e.g. [\"examples/banking\"]). Omit for " \
+                           "every real example domain."
+            },
+            include_meta: {
+              type:        "boolean",
+              description: "Include the self-hosted meta-domain (lib/hecks/language/bluebook). Defaults to true."
+            }
+          }
+        }
+      },
+      {
+        name:        "query_ir_impact",
+        description: "For one construct/field pair, which of the six propagation touchpoints " \
+                     ".claude/skills/bluebook-construct-creator/SKILL.md walks in prose already show signs " \
+                     "of it, and which don't: the meta-domain grammar, docs/resolution-rules/, " \
+                     "Assembly::Contracts, Reconstruction's hand-typed aggregate(row)/entity(row) (only " \
+                     "applicable to Aggregate/Entity), the fuzzer's FEATURE_COVERAGE/" \
+                     "GUARANTEED_BY_CONSTRUCTION, and the Rust mirror. Advisory, not a gate.",
+        inputSchema: {
+          type:       "object",
+          properties: {
+            name:  { type: "string", description: "Construct name (e.g. \"Aggregate\")." },
+            field: { type: "string", description: "The field name to check (e.g. \"preconditions\")." }
+          },
+          required:   %w[name field]
+        }
+      }
+    ].freeze
+  end
+end

data/lib/hecks/query_ir_mcp.rb

@@ -3,6 +3,7 @@
 require "json"
 require_relative "mcp_stdio_guard"
 require_relative "query_ir"
+require_relative "query_ir_mcp/tools"
 
 module Hecks
   # The MCP server that exposes `Hecks::QueryIR`'s queries as tools, over newline-delimited
@@ -14,69 +15,6 @@ module Hecks
     # The MCP protocol revision the server speaks.
     PROTOCOL_VERSION = "2024-11-05"
 
-    # The three tools, as an MCP client lists them.
-    TOOLS = [
-      {
-        name:        "query_ir_constructs",
-        description: "For a bluebook IR construct (Aggregate, Entity, Command, Query, ValueObject, Policy, " \
-                     "ReadModel, ProcessManager, Bluebook) or all of them, the real structural diff between " \
-                     "what the Ruby class emits and what the self-hosted meta-domain declares for it. Use " \
-                     "this instead of reading entity.rb/entity.bluebook (or the equivalent pair for another " \
-                     "construct) by hand to check whether a new IR field has been fully propagated.",
-        inputSchema: {
-          type:       "object",
-          properties: {
-            names: {
-              type:        "array",
-              items:       { type: "string" },
-              description: "Construct names to check (e.g. [\"Entity\"]). Omit or leave empty for all constructs."
-            }
-          }
-        }
-      },
-      {
-        name:        "query_ir_duplicates",
-        description: "Every given/ensures/invariant DECLARATION across the real corpus " \
-                     "(banking/pizzas/compliance) and the self-hosted meta-domain, grouped by (kind, " \
-                     "description, canonical predicate), reporting every group with more than one " \
-                     "independently-declared rule (already-deduped references, which share the same " \
-                     "underlying rule object, are excluded). Use this to find real corpus duplication " \
-                     "before proposing a new 'declared once, referenced by name' resolution rule.",
-        inputSchema: {
-          type:       "object",
-          properties: {
-            domains:      {
-              type:        "array",
-              items:       { type: "string" },
-              description: "Real example domain directories to scan (e.g. [\"examples/banking\"]). Omit for " \
-                           "every real example domain."
-            },
-            include_meta: {
-              type:        "boolean",
-              description: "Include the self-hosted meta-domain (lib/hecks/language/bluebook). Defaults to true."
-            }
-          }
-        }
-      },
-      {
-        name:        "query_ir_impact",
-        description: "For one construct/field pair, which of the six propagation touchpoints " \
-                     ".claude/skills/bluebook-construct-creator/SKILL.md walks in prose already show signs " \
-                     "of it, and which don't: the meta-domain grammar, docs/resolution-rules/, " \
-                     "Assembly::Contracts, Reconstruction's hand-typed aggregate(row)/entity(row) (only " \
-                     "applicable to Aggregate/Entity), the fuzzer's FEATURE_COVERAGE/" \
-                     "GUARANTEED_BY_CONSTRUCTION, and the Rust mirror. Advisory, not a gate.",
-        inputSchema: {
-          type:       "object",
-          properties: {
-            name:  { type: "string", description: "Construct name (e.g. \"Aggregate\")." },
-            field: { type: "string", description: "The field name to check (e.g. \"preconditions\")." }
-          },
-          required:   %w[name field]
-        }
-      }
-    ].freeze
-
     module_function
 
     # Checks the process is set up for stdio, prints the startup warning to stderr, and serves
@@ -119,18 +57,26 @@ module Hecks
     # @return [Hash] the MCP tool result
     def call_tool(name, arguments)
       case name
-      when "query_ir_constructs"
-        tool_result(QueryIR.format_constructs(QueryIR.constructs(Array(arguments["names"]))))
+      when "query_ir_constructs" then tool_result(constructs(arguments))
       when "query_ir_duplicates" then tool_result(duplicates(arguments))
-      when "query_ir_impact"
-        tool_result(QueryIR.format_impact_preview(QueryIR.impact_preview(arguments["name"], arguments["field"])))
+      when "query_ir_impact" then tool_result(impact(arguments))
       else
-        tool_result("no such tool: #{name.inspect} - known: #{TOOLS.map { |t| t[:name] }.join(', ')}", error: true)
+        tool_result("no such tool: #{name.inspect} - known: #{TOOLS.map { |t| t[:name] }.join(", ")}", error: true)
       end
     rescue ArgumentError, Runtime::TypeMismatch => e
       tool_result(e.message, error: true)
     end
 
+    # @api private
+    def constructs(arguments)
+      QueryIR.format_constructs(QueryIR.constructs(Array(arguments["names"])))
+    end
+
+    # @api private
+    def impact(arguments)
+      QueryIR.format_impact_preview(QueryIR.impact_preview(arguments["name"], arguments["field"]))
+    end
+
     # @api private
     def duplicates(arguments)
       domains = confined_domains(arguments["domains"])
@@ -170,17 +116,27 @@ module Hecks
     # @api private
     def handle(request, output)
       id = request["id"]
-      params = request["params"] || {}
       case request["method"]
       when "initialize" then result(output, id, initialized)
       when "notifications/initialized" then nil
       when "tools/list" then result(output, id, { tools: TOOLS })
-      when "tools/call" then result(output, id, call_tool(params["name"], params["arguments"] || {}))
+      when "tools/call" then result(output, id, tools_call(request["params"]))
       when "ping" then result(output, id, {})
-      else error(output, id, -32_601, "Method not found: #{request['method']}") unless id.nil?
+      else method_not_found(output, id, request["method"])
       end
     end
 
+    # @api private
+    def tools_call(params)
+      params ||= {}
+      call_tool(params["name"], params["arguments"] || {})
+    end
+
+    # @api private
+    def method_not_found(output, id, method)
+      error(output, id, -32_601, "Method not found: #{method}") unless id.nil?
+    end
+
     # @api private
     def initialized
       { protocolVersion: PROTOCOL_VERSION, capabilities: { tools: {} },