mcp_diff 0.1.0

data/lib/mcp_diff/core/schema_diff.rb

@@ -0,0 +1,145 @@
+# frozen_string_literal: true
+
+require "set"
+require "json"
+require_relative "canonical"
+
+module McpDiff
+  module Core
+    # Pragmatic structural diff of a JSON-Schema object schema (D9). Recognizes
+    # type / enum / required / properties / description / default; anything it
+    # cannot prove compatible surfaces as an `*-opaque` change so the incompatible
+    # catch-all rules fire loudly instead of silently passing. Port of
+    # core/src/schema-diff.ts. SchemaChange hashes use symbol keys (internal).
+    module SchemaDiff
+      module_function
+
+      PARAM_HANDLED = %w[type enum description default title].freeze
+      TOP_HANDLED = %w[properties required description title $schema].freeze
+
+      def as_obj(value)
+        value.is_a?(Hash) ? value : nil
+      end
+
+      def required_set(schema)
+        req = schema["required"]
+        Set.new(req.is_a?(Array) ? req.select { |r| r.is_a?(String) } : [])
+      end
+
+      # `type` as a set of names; nil = unspecified (accepts anything).
+      def type_set(schema)
+        t = schema["type"]
+        return Set[t] if t.is_a?(String)
+        return Set.new(t.select { |x| x.is_a?(String) }) if t.is_a?(Array)
+
+        nil
+      end
+
+      def type_label(set)
+        set.nil? ? "(any)" : set.to_a.sort.join("|")
+      end
+
+      def subset?(a, b)
+        a.all? { |x| b.include?(x) }
+      end
+
+      def enum_values(schema)
+        e = schema["enum"]
+        e.is_a?(Array) ? e : nil
+      end
+
+      def strip_keys(obj, keys)
+        obj.reject { |k, _| keys.include?(k) }
+      end
+
+      def diff_param(param, before_raw, after_raw, changes)
+        return if Canonical.deep_equal(before_raw, after_raw)
+
+        before = as_obj(before_raw)
+        after = as_obj(after_raw)
+        unless before && after
+          changes << { kind: "param-changed-opaque", param: param }
+          return
+        end
+
+        diff_param_type(param, before, after, changes)
+        diff_param_enum(param, before, after, changes)
+
+        changes << { kind: "description-changed", param: param } if before["description"] != after["description"]
+        changes << { kind: "default-changed", param: param } unless Canonical.deep_equal(before["default"], after["default"])
+
+        unless Canonical.deep_equal(strip_keys(before, PARAM_HANDLED), strip_keys(after, PARAM_HANDLED))
+          changes << { kind: "param-changed-opaque", param: param }
+        end
+      end
+
+      def diff_param_type(param, before, after, changes)
+        b_t = type_set(before)
+        a_t = type_set(after)
+        types_equal = (b_t.nil? && a_t.nil?) ||
+                      (!b_t.nil? && !a_t.nil? && subset?(b_t, a_t) && subset?(a_t, b_t))
+        return if types_equal
+
+        label = { before: type_label(b_t), after: type_label(a_t) }
+        if b_t.nil? || (!a_t.nil? && subset?(a_t, b_t))
+          changes << { kind: "type-narrowed", param: param }.merge(label)
+        elsif a_t.nil? || subset?(b_t, a_t)
+          changes << { kind: "type-widened", param: param }.merge(label)
+        else
+          changes << { kind: "param-changed-opaque", param: param }
+        end
+      end
+
+      def diff_param_enum(param, before, after, changes)
+        b_e = enum_values(before)
+        a_e = enum_values(after)
+        if !b_e.nil? && !a_e.nil?
+          removed = b_e.reject { |v| a_e.any? { |w| Canonical.deep_equal(v, w) } }
+          added = a_e.reject { |v| b_e.any? { |w| Canonical.deep_equal(v, w) } }
+          changes << { kind: "enum-value-removed", param: param, values: removed } unless removed.empty?
+          changes << { kind: "enum-value-added", param: param, values: added } unless added.empty?
+        elsif !b_e.nil? && a_e.nil?
+          changes << { kind: "enum-constraint-removed", param: param }
+        elsif b_e.nil? && !a_e.nil?
+          changes << { kind: "enum-constraint-added", param: param }
+        end
+      end
+
+      def diff_object_schema(before_raw, after_raw)
+        return [] if Canonical.deep_equal(before_raw, after_raw)
+
+        before = as_obj(before_raw)
+        after = as_obj(after_raw)
+        return [{ kind: "schema-changed-opaque" }] unless before && after
+
+        changes = []
+        b_props = as_obj(before["properties"]) || {}
+        a_props = as_obj(after["properties"]) || {}
+        b_req = required_set(before)
+        a_req = required_set(after)
+
+        b_props.keys.sort.each { |p| changes << { kind: "param-removed", param: p } unless a_props.key?(p) }
+        a_props.keys.sort.each do |p|
+          changes << { kind: "param-added", param: p, required: a_req.include?(p) } unless b_props.key?(p)
+        end
+        a_req.to_a.sort.each do |p|
+          changes << { kind: "required-added", param: p, existed_before: b_props.key?(p) } unless b_req.include?(p)
+        end
+        b_req.to_a.sort.each do |p|
+          changes << { kind: "required-removed", param: p } if !a_req.include?(p) && a_props.key?(p)
+        end
+        b_props.keys.sort.each { |p| diff_param(p, b_props[p], a_props[p], changes) if a_props.key?(p) }
+
+        unless Canonical.deep_equal(strip_keys(before, TOP_HANDLED), strip_keys(after, TOP_HANDLED))
+          changes << { kind: "schema-changed-opaque" }
+        end
+
+        changes
+      end
+
+      def format_values(values)
+        values.map(&:to_json).join(", ")
+      end
+    end
+  end
+end

data/lib/mcp_diff/render.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+require "json"
+
+module McpDiff
+  # Output renderers: pretty (default), --json, --md. Findings always ordered
+  # most-severe first, then rule, then target. Port of cli/src/render.ts.
+  module Render
+    GLYPHS = { "breaking" => "✗", "behavior" => "⚠", "compat" => "✓", "info" => "ℹ" }.freeze
+    COLORS = { "breaking" => 31, "behavior" => 33, "compat" => 32, "info" => 34 }.freeze
+    SEVERITY_RANK = { "breaking" => 0, "behavior" => 1, "compat" => 2, "info" => 3 }.freeze
+
+    module_function
+
+    def color?
+      ENV["NO_COLOR"].nil? && $stdout.tty?
+    end
+
+    def paint(code, str)
+      color? ? "\e[#{code}m#{str}\e[39m" : str
+    end
+
+    def bold(str)
+      color? ? "\e[1m#{str}\e[22m" : str
+    end
+
+    def dim(str)
+      color? ? "\e[2m#{str}\e[22m" : str
+    end
+
+    def sort_findings(findings)
+      findings.sort_by { |f| [SEVERITY_RANK[f["class"]], f["ruleId"], f["target"]] }
+    end
+
+    def render(format, findings, exit_code)
+      sorted = sort_findings(findings)
+      case format
+      when "json" then render_json(sorted, exit_code)
+      when "md" then render_markdown(sorted, exit_code)
+      else render_pretty(sorted, exit_code)
+      end
+    end
+
+    def render_pretty(findings, exit_code)
+      return paint(COLORS["compat"], "✓ contract unchanged") if findings.empty?
+
+      rule_width = findings.map { |f| f["ruleId"].length }.max + 2
+      lines = findings.map do |f|
+        code = COLORS[f["class"]]
+        [
+          paint(code, GLYPHS[f["class"]]),
+          paint(code, f["class"].upcase.ljust(9)),
+          f["ruleId"].ljust(rule_width),
+          "#{bold(f['target'])}: #{f['message']}"
+        ].join(" ")
+      end
+      lines << dim("exit code #{exit_code}")
+      lines.join("\n")
+    end
+
+    def render_json(findings, exit_code)
+      count = ->(cls) { findings.count { |f| f["class"] == cls } }
+      JSON.pretty_generate(
+        "findings" => findings,
+        "summary" => {
+          "breaking" => count.call("breaking"),
+          "behavior" => count.call("behavior"),
+          "compat" => count.call("compat"),
+          "info" => count.call("info")
+        },
+        "exitCode" => exit_code
+      )
+    end
+
+    def render_markdown(findings, exit_code)
+      return "✅ **mcp-diff**: contract unchanged" if findings.empty?
+
+      rows = findings.map do |f|
+        "| #{GLYPHS[f['class']]} #{f['class'].upcase} | `#{f['ruleId']}` | `#{f['target']}` | #{f['message']} |"
+      end
+      header =
+        case exit_code
+        when 1 then "❌ **mcp-diff**: breaking contract changes"
+        when 2 then "⚠️ **mcp-diff**: behavior-level contract changes"
+        else "✅ **mcp-diff**: compatible contract changes"
+        end
+      [header, "", "| Severity | Rule | Target | Change |", "|---|---|---|---|", *rows].join("\n")
+    end
+  end
+end

data/lib/mcp_diff/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module McpDiff
+  VERSION = "0.1.0"
+end

data/lib/mcp_diff.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require_relative "mcp_diff/version"
+require_relative "mcp_diff/core/canonical"
+require_relative "mcp_diff/core/normalize"
+require_relative "mcp_diff/core/schema_diff"
+require_relative "mcp_diff/core/diff"
+require_relative "mcp_diff/core/rule"
+require_relative "mcp_diff/core/rules"
+require_relative "mcp_diff/core/classify"
+require_relative "mcp_diff/client"
+require_relative "mcp_diff/config"
+require_relative "mcp_diff/render"
+require_relative "mcp_diff/cli"
+
+# mcp-diff — a lockfile + CI gate for an MCP server's contract (Ruby port).
+#
+# Module layout mirrors the TS package boundaries so the "core is pure (zero
+# I/O)" architecture rule survives the port:
+#   McpDiff::Core   — normalize → diff → classify + the rule catalog. Pure.
+#   McpDiff::Client — capture over the official `mcp` gem (the ONLY I/O to servers).
+#   McpDiff::Cli    — init/snapshot/check/update/diff/explain, exit codes 0/1/2.
+module McpDiff
+  # Populated as the port lands, stream by stream (see context/STREAMS.md).
+end

metadata

@@ -0,0 +1,75 @@
+--- !ruby/object:Gem::Specification
+name: mcp_diff
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Serhii Leniv
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2026-07-24 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: mcp
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+description: Snapshots an MCP server's public surface (tools, resources, prompts,
+  capabilities) into a committed mcp.lock.json and fails CI when the contract changes
+  in a breaking way.
+email:
+executables:
+- mcp-diff
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- exe/mcp-diff
+- lib/mcp_diff.rb
+- lib/mcp_diff/cli.rb
+- lib/mcp_diff/client.rb
+- lib/mcp_diff/config.rb
+- lib/mcp_diff/core/canonical.rb
+- lib/mcp_diff/core/classify.rb
+- lib/mcp_diff/core/diff.rb
+- lib/mcp_diff/core/normalize.rb
+- lib/mcp_diff/core/rule.rb
+- lib/mcp_diff/core/rules.rb
+- lib/mcp_diff/core/schema_diff.rb
+- lib/mcp_diff/render.rb
+- lib/mcp_diff/version.rb
+homepage: https://github.com/Serhii-Leniv/mcp-diff
+licenses:
+- MIT
+metadata: {}
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: Lockfile + CI gate for your MCP server's contract — CI goes red when you
+  silently break it.
+test_files: []