mcp_diff 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: d20d7f13aa54a40862cb9ea199572103518e6eabf8b5c02aa4933577f5d6b892
+  data.tar.gz: b02ae4c511d28b2ce69d5f08940fc51469747f869bab4ec8d947c97507b0dd6f
+SHA512:
+  metadata.gz: 33bf269d6727eb2d17267aca121692e1a520cc590ac5d4489a6f198d5a605342064704081ac6bf78b1bed661fc4b905c374cda0f443abdc7fe801f2657e5b25d
+  data.tar.gz: d69c25fa290c62f9ec81fd315029c377a3ac2b8e7aeee29444212c40e61f0ab76a22df3b6cb8a6eed8ad0fb1e43da5a60961af8c25b79530a50971b0ba232af9

data/README.md

@@ -0,0 +1,81 @@
+# mcp-diff — Ruby port (in progress)
+
+Parallel port of mcp-diff to Ruby, on the `ruby-port` branch. The TypeScript
+packages under `../packages` stay the shippable version until this reaches
+feature parity (24 rules + CLI + Action + green tests).
+
+## Decisions driving this port
+
+- **Language: Ruby** (user decision, supersedes the TS default for this branch).
+- **MCP SDK: the official `mcp` gem** (`modelcontextprotocol/ruby-sdk`) — honors
+  the project's "anchor only to the official SDK" rule. Its client subsystem
+  (`MCP::Client` + `MCP::Client::Stdio` / `http`) covers the full capture
+  surface: connect/InitializeResult (capabilities, protocolVersion, serverInfo,
+  instructions), `#tools` / `#resources` / `#resource_templates` / `#prompts`,
+  all auto-paginated.
+- **Distribution: RubyGems** (`gem install`) + a Ruby-based GitHub Action —
+  replaces the TS `npx` flow. (Verify the gem name `mcp_diff` / `mcp-diff` on
+  RubyGems, mirroring the npm-naming saga.)
+
+## Module boundaries (mirror the TS split; keep core pure)
+
+- `McpDiff::Core` — normalize → diff → classify + rule catalog. **Zero I/O.**
+- `McpDiff::Client` — capture over the official `mcp` gem. The only server I/O.
+- `McpDiff::Cli` — init/snapshot/check/update/diff/explain; exit codes 0/1/2.
+
+## Spike result (verified — Ruby 3.3.12, `mcp` 1.0.0)
+
+Capture works and is faithful. **Gotcha found & handled:** the gem's public
+`#tools`/`#resources`/… wrappers deserialize into objects that DROP `annotations`
+and `title` — both part of mcp-diff's contract (BEHAVIOR class). The capture
+layer reads the raw JSON one layer down via `MCP::Client`'s own private
+`request` (full JSON-RPC envelope + id correlation), so nothing is lost.
+`capture_test.rb` locks this in (asserts `add_doc`'s annotations survive).
+
+## Done on this branch (green — 35 tests / 94 assertions)
+
+- `McpDiff::Core::Canonical` + `Normalize` — deterministic snapshot + contractHash.
+- `McpDiff::Client.capture` — capability-gated, cursor-paginated capture over the
+  official gem (stdio verified against two real servers; HTTP wired via
+  `MCP::Client::HTTP`, not yet exercised by a test).
+- `Core::Diff` + `Classify` + `SchemaDiff` (D9) + the **full 24-rule catalog** —
+  verified against the SAME fixtures the TS suite uses (`test/fixtures/`).
+- `Cli` — init/snapshot/check/update/diff/explain/rules, exit codes 0/1/2,
+  pretty/JSON/MD. Output is byte-identical to the TS CLI (verified on the demo).
+- `exe/mcp-diff`, gemspec builds clean (`mcp_diff-0.1.0.gem`).
+
+## Done since (green — full suite: 45 tests / 157 assertions)
+
+- `test/schema_diff_test.rb` — the D9 variance primitives (port of the TS units).
+- `test/catalog_test.rb` — D8 no-drift: the catalog vs context/RULES.md.
+- `action/action.yml` — Ruby-native composite Action (setup-ruby → `gem install
+  mcp_diff` → `mcp-diff --md check` → PR comment + gate).
+- `.github/workflows/ruby-ci.yml` — runs the Ruby suite on CI.
+
+## Release artifact validated
+
+Built + installed the gem and ran the **installed** `mcp-diff` binary end-to-end:
+`init` (live capture) wrote config + lockfile, `check` returned "✓ contract
+unchanged" (exit 0). So `gem install mcp_diff` yields a working CLI.
+
+## Standalone
+
+`test/fixtures/server.rb` is a hand-rolled MCP stdio server mirroring the TS
+fixture — the whole suite runs with **only Ruby** (no Node), and `ruby-ci.yml`
+reflects that.
+
+## Remaining before a Ruby release
+
+- **Publish to RubyGems** — the name `mcp_diff` (and `mcp-diff`) is FREE on
+  RubyGems (verified), so no npm-style workaround. The release is wired:
+  `.github/workflows/ruby-release.yml` builds + `gem push` on a `v*` tag. It
+  needs the repo secret **`RUBYGEMS_API_KEY`** (your RubyGems API key — the
+  analogue of NPM_TOKEN). To ship: add the secret, then `git tag v0.1.0 && git push --tags`.
+- Nice-to-have: split rules into one-file-per-rule (contributor funnel); an
+  HTTP-transport capture test.
+
+## Port stream tracking
+
+Mirrors `../context/STREAMS.md` S1–S5. Formal D-decisions land in `context/`
+once the spike validates the foundation (not before — the rewrite isn't final
+until capture is proven in Ruby).

data/exe/mcp-diff

@@ -0,0 +1,10 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+begin
+  require "mcp_diff"
+rescue LoadError
+  require_relative "../lib/mcp_diff"
+end
+
+exit McpDiff::Cli.run(ARGV)

data/lib/mcp_diff/cli.rb

@@ -0,0 +1,269 @@
+# frozen_string_literal: true
+
+require "json"
+require "uri"
+require_relative "config"
+require_relative "render"
+
+module McpDiff
+  # Command dispatcher: init/snapshot/check/update/diff/explain/rules, with
+  # pretty/JSON/MD output and the 0/1/2 exit-code contract. Port of
+  # cli/src/index.ts. run() returns the process exit code.
+  module Cli
+    module_function
+
+    def run(argv)
+      globals, command, args, opts = parse(argv)
+      return 0 if globals[:handled]
+
+      dispatch(command, args, globals, opts)
+    rescue StandardError => e
+      warn "✗ #{e.message}"
+      1
+    end
+
+    def parse(argv)
+      globals = { config: Config::DEFAULT_CONFIG_PATH, profile: nil, json: false, md: false, handled: false }
+      opts = {}
+      command = nil
+      args = []
+      i = 0
+      while i < argv.length
+        a = argv[i]
+        case a
+        when "-c", "--config" then globals[:config] = argv[i += 1]
+        when "-p", "--profile" then globals[:profile] = argv[i += 1]
+        when "--json" then globals[:json] = true
+        when "--md" then globals[:md] = true
+        when "--stdio" then opts[:stdio] = argv[i += 1]
+        when "--url" then opts[:url] = argv[i += 1]
+        when "-V", "--version" then (puts VERSION; globals[:handled] = true)
+        when "-h", "--help" then (puts help_text; globals[:handled] = true)
+        else
+          if command.nil? && !a.start_with?("-")
+            command = a
+          else
+            args << a
+          end
+        end
+        i += 1
+      end
+      [globals, command, args, opts]
+    end
+
+    def dispatch(command, args, globals, opts)
+      case command
+      when "init" then cmd_init(globals, opts)
+      when "snapshot" then cmd_snapshot(globals)
+      when "check" then return cmd_check(globals)
+      when "update" then cmd_update(globals)
+      when "diff" then return cmd_diff(globals, args[0], args[1])
+      when "explain" then cmd_explain(args[0])
+      when "rules" then cmd_rules(globals)
+      when nil then (puts help_text)
+      else raise "unknown command \"#{command}\" — run: mcp-diff --help"
+      end
+      0
+    end
+
+    # ── shared helpers ──────────────────────────────────────────────
+
+    def globals_config(globals)
+      Config.load_config(globals[:config], globals[:profile])
+    end
+
+    def output_format(globals)
+      raise "choose one output format — pass --json or --md, not both" if globals[:json] && globals[:md]
+      return "json" if globals[:json]
+      return "md" if globals[:md]
+
+      "pretty"
+    end
+
+    def lockfile_path(cfg)
+      cfg["lockfile"] || Config::DEFAULT_LOCKFILE
+    end
+
+    def capture_options_from(cfg)
+      server = cfg["server"] || {}
+      opts = {}
+      opts[:timeout_ms] = cfg["timeoutMs"] if cfg["timeoutMs"]
+      if server["stdio"]
+        parts = Config.shell_split(server["stdio"])
+        command = parts.shift
+        raise "config server.stdio is empty" if command.nil?
+
+        opts[:stdio] = { command: command, args: parts }
+        opts[:stdio][:env] = cfg["env"] if cfg["env"]
+      elsif server["url"]
+        opts[:url] = server["url"]
+      else
+        raise "config has no server target — set server.stdio or server.url"
+      end
+      opts
+    end
+
+    def live_snapshot(cfg)
+      raw = Client.capture(**capture_options_from(cfg))
+      Core::Normalize.normalize(raw, ignore: cfg["ignore"] || [])
+    end
+
+    def read_lockfile(path, verify: true)
+      text = begin
+        File.read(path)
+      rescue SystemCallError
+        raise "cannot read lockfile \"#{path}\" — run: npx @mcp-diff/cli snapshot"
+      end
+      data = begin
+        JSON.parse(text)
+      rescue JSON::ParserError => e
+        raise "lockfile \"#{path}\" is not valid JSON (#{e.message}) — run: npx @mcp-diff/cli snapshot"
+      end
+      snapshot = Core::Normalize.parse_snapshot(data)
+      if verify
+        body = snapshot.reject { |k, _| k == "contractHash" }
+        if Core::Canonical.contract_hash_of(body) != snapshot["contractHash"]
+          raise "lockfile \"#{path}\" does not match its contractHash (hand-edited or bad merge?) — " \
+                "run: npx @mcp-diff/cli update"
+        end
+      end
+      snapshot
+    end
+
+    def read_snapshot_file(path)
+      text = begin
+        File.read(path)
+      rescue SystemCallError
+        raise "cannot read snapshot file \"#{path}\""
+      end
+      begin
+        Core::Normalize.parse_snapshot(JSON.parse(text))
+      rescue JSON::ParserError => e
+        raise "snapshot file \"#{path}\": #{e.message}"
+      end
+    end
+
+    def write_lockfile(path, snapshot)
+      File.write(path, Core::Canonical.canonical_stringify(snapshot))
+    end
+
+    # ── commands ────────────────────────────────────────────────────
+
+    def cmd_init(globals, opts)
+      config_path = globals[:config]
+      raise "#{config_path} already exists — delete it first to re-init" if File.exist?(config_path)
+
+      server = init_server_target(opts)
+      cfg = { "server" => server, "strict" => "breaking" }
+      write_lockfile(config_path, cfg)
+      puts "wrote #{config_path}"
+      snapshot = live_snapshot(cfg)
+      write_lockfile(lockfile_path(cfg), snapshot)
+      puts "wrote #{lockfile_path(cfg)} (#{snapshot['tools'].length} tools) — commit both files"
+    end
+
+    def init_server_target(opts)
+      if opts[:url]
+        valid = begin
+          u = URI.parse(opts[:url])
+          u.scheme && u.host
+        rescue URI::InvalidURIError
+          false
+        end
+        raise "\"#{opts[:url]}\" is not a valid URL — expected e.g. http://localhost:3000/mcp" unless valid
+
+        { "url" => opts[:url] }
+      elsif opts[:stdio]
+        { "stdio" => opts[:stdio] }
+      else
+        detected = Config.detect_mcp_json
+        raise "no server target — pass --stdio \"<command>\" or --url <url> (no .mcp.json found to auto-detect)" if detected.nil?
+
+        puts "detected server from .mcp.json: #{detected['stdio']}"
+        detected
+      end
+    end
+
+    def cmd_snapshot(globals)
+      cfg = globals_config(globals)
+      snapshot = live_snapshot(cfg)
+      write_lockfile(lockfile_path(cfg), snapshot)
+      puts "wrote #{lockfile_path(cfg)} (#{snapshot['tools'].length} tools)"
+    end
+
+    def cmd_check(globals)
+      cfg = globals_config(globals)
+      locked = read_lockfile(lockfile_path(cfg))
+      live = live_snapshot(cfg)
+      if locked["contractHash"] == live["contractHash"]
+        puts Render.render(output_format(globals), [], 0)
+        return 0
+      end
+      findings = Core::Classify.classify(Core::Diff.diff(locked, live))
+      exit_code = Core::Classify.compute_exit_code(findings, cfg["strict"] || "breaking")
+      puts Render.render(output_format(globals), findings, exit_code)
+      if findings.empty?
+        puts "ℹ contract hash changed but no rule classified the change (compatible) — run: mcp-diff update"
+      end
+      exit_code
+    end
+
+    def cmd_update(globals)
+      cfg = globals_config(globals)
+      path = lockfile_path(cfg)
+      live = live_snapshot(cfg)
+      if File.exist?(path)
+        locked = read_lockfile(path, verify: false)
+        findings = Core::Classify.classify(Core::Diff.diff(locked, live))
+        puts Render.render(output_format(globals), findings, 0) unless findings.empty?
+      end
+      write_lockfile(path, live)
+      puts "updated #{path}"
+    end
+
+    def cmd_diff(globals, before_path, after_path)
+      raise "diff needs two snapshot files: mcp-diff diff <before> <after>" if before_path.nil? || after_path.nil?
+
+      before = read_snapshot_file(before_path)
+      after = read_snapshot_file(after_path)
+      findings = Core::Classify.classify(Core::Diff.diff(before, after))
+      exit_code = Core::Classify.compute_exit_code(findings)
+      puts Render.render(output_format(globals), findings, exit_code)
+      exit_code
+    end
+
+    def cmd_explain(rule_id)
+      entry = Core::Rules::CATALOG.find { |r| r["id"] == rule_id }
+      unless entry
+        known = Core::Rules::CATALOG.map { |r| r["id"] }.join("\n  ")
+        raise "unknown rule \"#{rule_id}\" — known rules:\n  #{known}"
+      end
+      puts "#{entry['id']} [#{entry['class'].upcase}]\n\n#{entry['description']}"
+    end
+
+    def cmd_rules(globals)
+      if globals[:json]
+        puts JSON.pretty_generate(Core::Rules::CATALOG)
+        return
+      end
+      Core::Rules::CATALOG.each { |r| puts "#{r['class'].upcase.ljust(9)} #{r['id']}" }
+    end
+
+    def help_text
+      <<~HELP
+        mcp-diff — lockfile + CI gate for your MCP server's contract
+
+        Usage: mcp-diff [--config <path>] [--profile <name>] [--json|--md] <command>
+
+        Commands:
+          init [--stdio "<cmd>" | --url <url>]   write config + first lockfile (auto-detects .mcp.json)
+          snapshot                               (re)write mcp.lock.json
+          check                                  live server vs lockfile; exit 0/1/2
+          update                                 accept changes, rewrite lockfile
+          diff <a.json> <b.json>                 compare two snapshots
+          explain <rule-id>                      explain one rule
+          rules                                  list the rule catalog
+      HELP
+    end
+  end
+end

data/lib/mcp_diff/client.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+require "timeout"
+require "mcp"
+
+module McpDiff
+  # Capture an MCP server's complete public surface over the official `mcp` gem.
+  # The ONLY component that talks to servers (keeps Core pure). Port of
+  # client/src/index.ts.
+  #
+  # Note: the gem's `MCP::Client#tools/#resources/...` wrap results into objects
+  # that DROP `annotations` and `title`. Those are part of the contract (BEHAVIOR
+  # class), so we read the raw JSON one layer down via the client's own private
+  # `request` (full JSON-RPC envelope + id correlation, nothing dropped). This is
+  # covered by capture_test.rb — if a future `mcp` version changes it, that fails.
+  module Client
+    DEFAULT_TIMEOUT_MS = 30_000
+
+    module_function
+
+    # stdio: { command:, args: [], env: {} } | url: "http://…/mcp"
+    # Returns a RawCapture Hash (string keys) matching Core's normalize input.
+    def capture(stdio: nil, url: nil, timeout_ms: DEFAULT_TIMEOUT_MS)
+      transport = make_transport(stdio: stdio, url: url)
+      client = MCP::Client.new(transport: transport)
+
+      Timeout.timeout(timeout_ms / 1000.0, nil, "server did not respond within #{timeout_ms}ms") do
+        client.connect
+        info = as_hash(client.server_info)
+        caps = as_hash(info["capabilities"])
+
+        {
+          "protocolVersion" => info["protocolVersion"],
+          "serverInfo" => info["serverInfo"],
+          "capabilities" => caps,
+          "instructions" => info["instructions"],
+          "tools" => caps["tools"] ? raw_list(client, "tools/list", "tools") : [],
+          "resources" => caps["resources"] ? raw_list(client, "resources/list", "resources") : [],
+          "resourceTemplates" => caps["resources"] ? raw_list(client, "resources/templates/list", "resourceTemplates") : [],
+          "prompts" => caps["prompts"] ? raw_list(client, "prompts/list", "prompts") : []
+        }
+      end
+    rescue Timeout::Error
+      raise
+    rescue StandardError => e
+      raise "cannot capture server (#{target_desc(stdio, url)}) — #{e.message} — " \
+            "check the command/URL and that the server builds & starts"
+    ensure
+      transport.close if transport.respond_to?(:close)
+    end
+
+    # Follow nextCursor to the end, reading raw hashes. Guards against a server
+    # that returns a repeating cursor (would loop forever).
+    def raw_list(client, method, key)
+      items = []
+      cursor = nil
+      seen = {}
+      loop do
+        params = cursor ? { cursor: cursor } : {}
+        result = as_hash(client.send(:request, method: method, params: params)["result"])
+        items.concat(result[key] || [])
+        cursor = result["nextCursor"]
+        break if cursor.nil?
+        raise "server returned a repeating pagination cursor" if seen[cursor]
+
+        seen[cursor] = true
+      end
+      items
+    end
+
+    def make_transport(stdio:, url:)
+      if stdio
+        MCP::Client::Stdio.new(command: stdio[:command], args: stdio[:args] || [], env: stdio[:env])
+      elsif url
+        MCP::Client::HTTP.new(url: url)
+      else
+        raise "no server target: provide either stdio or url"
+      end
+    end
+
+    def target_desc(stdio, url)
+      if stdio
+        %(stdio: "#{[stdio[:command], *(stdio[:args] || [])].join(' ')}")
+      else
+        url || "no target"
+      end
+    end
+
+    def as_hash(value)
+      value.is_a?(Hash) ? value : {}
+    end
+  end
+end

data/lib/mcp_diff/config.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+require "json"
+require "uri"
+
+module McpDiff
+  # Config loading + validation (port of cli/src/config.ts). Actionable error
+  # messages: every failure says how to fix it. Config uses string keys (JSON).
+  module Config
+    DEFAULT_CONFIG_PATH = "mcp-diff.config.json"
+    DEFAULT_LOCKFILE = "mcp.lock.json"
+
+    module_function
+
+    def load_config(path, profile = nil)
+      text = read_config_text(path)
+      begin
+        config = JSON.parse(text)
+      rescue JSON::ParserError => e
+        raise "config \"#{path}\" is not valid JSON: #{e.message}"
+      end
+      config = apply_profile(config, profile) unless profile.nil?
+      validate_config(path, config)
+      config
+    end
+
+    def read_config_text(path)
+      File.read(path)
+    rescue SystemCallError
+      raise "cannot read config \"#{path}\" — run: npx @mcp-diff/cli init"
+    end
+
+    def apply_profile(config, profile)
+      overlay = (config["profiles"] || {})[profile]
+      if overlay.nil?
+        known = (config["profiles"] || {}).keys.join(", ")
+        known = "none defined" if known.empty?
+        raise "unknown profile \"#{profile}\" — known profiles: #{known}"
+      end
+      merged = config.merge(overlay)
+      merged["env"] = (config["env"] || {}).merge(overlay["env"] || {})
+      merged["server"] = overlay["server"] || config["server"]
+      merged
+    end
+
+    def validate_config(path, config)
+      invalid = ->(msg) { raise "config \"#{path}\": #{msg}" }
+      validate_server(config["server"], invalid) if config.key?("server")
+      invalid.call('"lockfile" must be a string path') if config.key?("lockfile") && !config["lockfile"].is_a?(String)
+      validate_timeout(config["timeoutMs"], invalid) if config.key?("timeoutMs")
+      validate_ignore(config["ignore"], invalid) if config.key?("ignore")
+      if config.key?("strict") && !%w[breaking behavior].include?(config["strict"])
+        invalid.call('"strict" must be "breaking" or "behavior"')
+      end
+      validate_env(config["env"], invalid) if config.key?("env")
+    end
+
+    def validate_server(server, invalid)
+      invalid.call('"server" must be an object with "stdio" or "url"') unless server.is_a?(Hash)
+      if server.key?("stdio") && !server["stdio"].is_a?(String)
+        invalid.call('"server.stdio" must be a string command line')
+      end
+      return unless server.key?("url")
+
+      invalid.call('"server.url" must be a string') unless server["url"].is_a?(String)
+      begin
+        u = URI.parse(server["url"])
+        invalid.call("\"server.url\" is not a valid URL: #{server['url']}") unless u.scheme && u.host
+      rescue URI::InvalidURIError
+        invalid.call("\"server.url\" is not a valid URL: #{server['url']}")
+      end
+    end
+
+    def validate_timeout(value, invalid)
+      invalid.call('"timeoutMs" must be a positive number') unless value.is_a?(Numeric) && value.finite? && value.positive?
+    end
+
+    def validate_ignore(value, invalid)
+      invalid.call('"ignore" must be an array of string patterns') unless value.is_a?(Array) && value.all?(String)
+    end
+
+    def validate_env(value, invalid)
+      ok = value.is_a?(Hash) && value.values.all?(String)
+      invalid.call('"env" must be an object of string values') unless ok
+    end
+
+    # Split a command line into argv, honoring single/double quotes.
+    def shell_split(command)
+      command.scan(/"([^"]*)"|'([^']*)'|(\S+)/).map { |dq, sq, bare| dq || sq || bare }
+    end
+
+    def detect_mcp_json
+      return nil unless File.exist?(".mcp.json")
+
+      parsed = JSON.parse(File.read(".mcp.json"))
+      servers = parsed["mcpServers"] || {}
+      _name, server = servers.first
+      return nil unless server.is_a?(Hash) && server["command"].is_a?(String)
+
+      args = (server["args"] || []).map { |a| a.match?(/\s/) ? "\"#{a}\"" : a }.join(" ")
+      { "stdio" => args.empty? ? server["command"] : "#{server['command']} #{args}" }
+    rescue StandardError
+      nil
+    end
+  end
+end

data/lib/mcp_diff/core/canonical.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require "json"
+require "digest"
+
+module McpDiff
+  module Core
+    # Deterministic serialization: sorted keys, array order preserved (it is
+    # meaningful), sha256 contract hash. Port of core/src/canonical.ts (D11).
+    module Canonical
+      module_function
+
+      # Recursively sort object keys; stringify keys so string/symbol inputs
+      # canonicalize identically. Array order is preserved.
+      def sort_keys_deep(value)
+        case value
+        when Array
+          value.map { |v| sort_keys_deep(v) }
+        when Hash
+          value.map { |k, v| [k.to_s, sort_keys_deep(v)] }.sort_by(&:first).to_h
+        else
+          value
+        end
+      end
+
+      # Canonical lockfile text: sorted keys, 2-space indent, trailing newline.
+      def canonical_stringify(value)
+        "#{JSON.pretty_generate(sort_keys_deep(value))}\n"
+      end
+
+      # Structural equality via canonical serialization (array order preserved).
+      def deep_equal(a, b)
+        JSON.generate(sort_keys_deep(a)) == JSON.generate(sort_keys_deep(b))
+      end
+
+      # sha256 of the snapshot's canonical (compact) form, hash field excluded.
+      def contract_hash_of(snapshot_without_hash)
+        compact = JSON.generate(sort_keys_deep(snapshot_without_hash))
+        "sha256-#{Digest::SHA256.hexdigest(compact)}"
+      end
+    end
+  end
+end

data/lib/mcp_diff/core/classify.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require_relative "rules"
+
+module McpDiff
+  module Core
+    # Apply the ruleset to a set of changes, then compute the exit code.
+    # Port of core/src/classify.ts.
+    module Classify
+      module_function
+
+      CLASS_RANK = { "breaking" => 0, "behavior" => 1, "compat" => 2, "info" => 3 }.freeze
+
+      # Sorted worst-first, then by rule, target, message (deterministic order).
+      def classify(changes, rules = Rules::ALL)
+        findings = []
+        changes.each do |change|
+          rules.each do |rule|
+            matched = rule.match(change)
+            next if matched.nil?
+
+            findings.concat(matched.is_a?(Array) ? matched : [matched])
+          end
+        end
+        findings.sort_by { |f| [CLASS_RANK[f["class"]], f["ruleId"], f["target"], f["message"]] }
+      end
+
+      # Exit-code contract (D4): 0 clean/compat/info, 1 breaking, 2 behavior-only.
+      # strict: "behavior" promotes behavior findings to exit 1.
+      def compute_exit_code(findings, strict = "breaking")
+        has_breaking = findings.any? { |f| f["class"] == "breaking" }
+        has_behavior = findings.any? { |f| f["class"] == "behavior" }
+        return 1 if has_breaking || (strict == "behavior" && has_behavior)
+        return 2 if has_behavior
+
+        0
+      end
+    end
+  end
+end