mcp_diff 0.1.0

data/lib/mcp_diff/core/diff.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require_relative "canonical"
+
+module McpDiff
+  module Core
+    # Structural diff between two snapshots. Emits typed Change hashes (symbol
+    # keys); no severities. Port of core/src/diff.ts. Entity payloads (before/
+    # after) keep their string-keyed entry shape.
+    module Diff
+      module_function
+
+      def diff(before, after)
+        changes = []
+        changes.concat(entity_changes(before["tools"], after["tools"], "name",
+                                      { added: "tool-added", removed: "tool-removed", modified: "tool-modified" }, :name))
+        changes.concat(entity_changes(before["resources"], after["resources"], "uri",
+                                      { added: "resource-added", removed: "resource-removed", modified: "resource-modified" }, :uri))
+        changes.concat(entity_changes(before["resourceTemplates"], after["resourceTemplates"], "uriTemplate",
+                                      { added: "resource-template-added", removed: "resource-template-removed", modified: "resource-template-modified" }, :uriTemplate))
+        changes.concat(entity_changes(before["prompts"], after["prompts"], "name",
+                                      { added: "prompt-added", removed: "prompt-removed", modified: "prompt-modified" }, :name))
+        changes.concat(capability_changes(before["capabilities"] || {}, after["capabilities"] || {}))
+        changes.concat(scalar_changes(before, after))
+        changes
+      end
+
+      def entity_changes(before, after, key, kinds, key_field)
+        before ||= []
+        after ||= []
+        before_map = before.to_h { |item| [item[key], item] }
+        after_map = after.to_h { |item| [item[key], item] }
+        changes = []
+
+        before_map.each do |k, item|
+          nxt = after_map[k]
+          if nxt.nil? && !after_map.key?(k)
+            changes << { kind: kinds[:removed], key_field => k, before: item }
+          elsif !Canonical.deep_equal(item, nxt)
+            changes << { kind: kinds[:modified], key_field => k, before: item, after: nxt }
+          end
+        end
+        after_map.each do |k, item|
+          changes << { kind: kinds[:added], key_field => k, after: item } unless before_map.key?(k)
+        end
+        changes
+      end
+
+      def capability_changes(before_caps, after_caps)
+        changes = []
+        (before_caps.keys | after_caps.keys).sort.each do |k|
+          b_present = before_caps.key?(k)
+          a_present = after_caps.key?(k)
+          if !b_present && a_present
+            changes << { kind: "capability-added", capability: k, after: after_caps[k] }
+          elsif b_present && !a_present
+            changes << { kind: "capability-removed", capability: k, before: before_caps[k] }
+          elsif b_present && a_present && !Canonical.deep_equal(before_caps[k], after_caps[k])
+            changes << { kind: "capability-modified", capability: k, before: before_caps[k], after: after_caps[k] }
+          end
+        end
+        changes
+      end
+
+      def scalar_changes(before, after)
+        changes = []
+        unless before["instructions"] == after["instructions"]
+          changes << { kind: "instructions-changed", before: before["instructions"], after: after["instructions"] }
+        end
+        unless Canonical.deep_equal(before["server"], after["server"])
+          changes << { kind: "server-info-changed", before: before["server"], after: after["server"] }
+        end
+        unless before["protocolVersion"] == after["protocolVersion"]
+          changes << { kind: "protocol-version-changed", before: before["protocolVersion"], after: after["protocolVersion"] }
+        end
+        changes
+      end
+    end
+  end
+end

data/lib/mcp_diff/core/normalize.rb

@@ -0,0 +1,170 @@
+# frozen_string_literal: true
+
+require_relative "canonical"
+
+module McpDiff
+  module Core
+    # Canonicalize a raw capture into a deterministic snapshot Hash: known fields
+    # only, stable sort order, sorted keys, contractHash. Pure — same input, same
+    # output. Port of core/src/normalize.ts. Keys are strings throughout to match
+    # the lockfile shape.
+    module Normalize
+      module_function
+
+      # `*`-only wildcard, anchored both ends. `split("*", -1)` keeps trailing
+      # empties so "foo*" matches like the TS RegExp does.
+      def wildcard_match(pattern, value)
+        re = Regexp.new("^#{pattern.split('*', -1).map { |p| Regexp.escape(p) }.join('.*')}$")
+        re.match?(value)
+      end
+
+      def ignored?(name, patterns)
+        patterns.any? { |p| wildcard_match(p, name) }
+      end
+
+      def as_record(value)
+        value.is_a?(Hash) ? value : {}
+      end
+
+      def str_or_null(value)
+        value.is_a?(String) ? value : nil
+      end
+
+      def json_or_null(value)
+        value.nil? ? nil : Canonical.sort_keys_deep(value)
+      end
+
+      def tool_entry(raw)
+        r = as_record(raw)
+        return nil unless r["name"].is_a?(String)
+
+        {
+          "name" => r["name"],
+          "title" => str_or_null(r["title"]),
+          "description" => str_or_null(r["description"]),
+          "inputSchema" => json_or_null(r["inputSchema"]),
+          "outputSchema" => json_or_null(r["outputSchema"]),
+          "annotations" => json_or_null(r["annotations"])
+        }
+      end
+
+      def resource_entry(raw)
+        r = as_record(raw)
+        return nil unless r["uri"].is_a?(String)
+
+        {
+          "uri" => r["uri"],
+          "name" => str_or_null(r["name"]),
+          "title" => str_or_null(r["title"]),
+          "description" => str_or_null(r["description"]),
+          "mimeType" => str_or_null(r["mimeType"])
+        }
+      end
+
+      def resource_template_entry(raw)
+        r = as_record(raw)
+        return nil unless r["uriTemplate"].is_a?(String)
+
+        {
+          "uriTemplate" => r["uriTemplate"],
+          "name" => str_or_null(r["name"]),
+          "title" => str_or_null(r["title"]),
+          "description" => str_or_null(r["description"]),
+          "mimeType" => str_or_null(r["mimeType"])
+        }
+      end
+
+      def prompt_entry(raw)
+        r = as_record(raw)
+        return nil unless r["name"].is_a?(String)
+
+        args = (r["arguments"].is_a?(Array) ? r["arguments"] : [])
+               .map { |a| prompt_argument(a) }
+               .compact
+               .sort_by { |a| a["name"] }
+
+        {
+          "name" => r["name"],
+          "title" => str_or_null(r["title"]),
+          "description" => str_or_null(r["description"]),
+          "arguments" => args
+        }
+      end
+
+      def prompt_argument(raw)
+        ar = as_record(raw)
+        return nil unless ar["name"].is_a?(String)
+
+        {
+          "name" => ar["name"],
+          "description" => str_or_null(ar["description"]),
+          "required" => ar["required"] == true
+        }
+      end
+
+      def normalize(raw, ignore: [])
+        raw = as_record(raw)
+        server_info = raw["serverInfo"] ? as_record(raw["serverInfo"]) : nil
+
+        body = {
+          "lockfileVersion" => 1,
+          "protocolVersion" => raw["protocolVersion"] || nil,
+          "server" => server_block(server_info),
+          "capabilities" => Canonical.sort_keys_deep(as_record(raw["capabilities"])),
+          "instructions" => raw["instructions"] || nil,
+          "tools" => (raw["tools"] || []).map { |t| tool_entry(t) }
+                                         .compact.reject { |t| ignored?(t["name"], ignore) }
+                                         .sort_by { |t| t["name"] },
+          "resources" => (raw["resources"] || []).map { |r| resource_entry(r) }
+                                                 .compact.reject { |r| ignored?(r["uri"], ignore) }
+                                                 .sort_by { |r| r["uri"] },
+          "resourceTemplates" => (raw["resourceTemplates"] || []).map { |r| resource_template_entry(r) }
+                                                                 .compact.sort_by { |r| r["uriTemplate"] },
+          "prompts" => (raw["prompts"] || []).map { |p| prompt_entry(p) }
+                                             .compact.reject { |p| ignored?(p["name"], ignore) }
+                                             .sort_by { |p| p["name"] }
+        }
+
+        body.merge("contractHash" => Canonical.contract_hash_of(body))
+      end
+
+      # Parse and lightly validate a lockfile read from disk.
+      def parse_snapshot(data)
+        r = as_record(data)
+        raise "unsupported lockfileVersion #{r['lockfileVersion'].inspect} — expected 1" unless r["lockfileVersion"] == 1
+
+        %w[tools resources resourceTemplates prompts].each do |key|
+          raise "invalid lockfile: \"#{key}\" must be an array" unless r[key].is_a?(Array)
+        end
+        data
+      end
+
+      # Build a complete snapshot from a partial one (fixtures, tests). Entries
+      # are taken as-is; only top-level defaults + contractHash are filled.
+      def make_snapshot(partial = {})
+        body = {
+          "lockfileVersion" => 1,
+          "protocolVersion" => partial["protocolVersion"],
+          "server" => partial["server"],
+          "capabilities" => partial["capabilities"] || {},
+          "instructions" => partial["instructions"],
+          "tools" => partial["tools"] || [],
+          "resources" => partial["resources"] || [],
+          "resourceTemplates" => partial["resourceTemplates"] || [],
+          "prompts" => partial["prompts"] || []
+        }
+        body.merge("contractHash" => Canonical.contract_hash_of(body))
+      end
+
+      def server_block(server_info)
+        return nil unless server_info && server_info["name"].is_a?(String)
+
+        {
+          "name" => server_info["name"],
+          "version" => server_info["version"].is_a?(String) ? server_info["version"] : "",
+          "title" => str_or_null(server_info["title"])
+        }
+      end
+    end
+  end
+end

data/lib/mcp_diff/core/rule.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module McpDiff
+  module Core
+    # A single classification rule. The match block is instance_exec'd on the
+    # rule so it can call `finding(...)` and read `id`/`severity` — mirroring the
+    # TS `this.id` / `this.class` shape. Returns a Finding hash, an array of
+    # them, or nil. Findings use string keys to match the --json output shape.
+    class Rule
+      attr_reader :id, :severity, :description
+
+      def initialize(id:, severity:, description:, &match)
+        @id = id
+        @severity = severity
+        @description = description
+        @match = match
+      end
+
+      def match(change)
+        instance_exec(change, &@match)
+      end
+
+      def finding(target, message)
+        { "ruleId" => @id, "class" => @severity, "target" => target, "message" => message }
+      end
+    end
+  end
+end

data/lib/mcp_diff/core/rules.rb

@@ -0,0 +1,299 @@
+# frozen_string_literal: true
+
+require_relative "rule"
+require_relative "schema_diff"
+require_relative "canonical"
+
+module McpDiff
+  module Core
+    # The v1 rule catalog (24 rules), faithful port of packages/core/src/rules/*.
+    # NOTE: the TS project uses one-folder-per-rule as the contributor funnel;
+    # the Ruby port keeps them in one file for the parity milestone. Splitting
+    # into per-rule files is a follow-up (see ruby/README.md).
+    module Rules
+      module_function
+
+      def keys_of(value)
+        value.is_a?(Hash) ? value : {}
+      end
+
+      def schema_findings(rule, change, schema_key)
+        SchemaDiff.diff_object_schema(change[:before][schema_key], change[:after][schema_key])
+      end
+
+      # rubocop:disable Metrics/MethodLength, Metrics/AbcSize
+      def build
+        [
+          # ───────────────── breaking ─────────────────
+          Rule.new(id: "tool-removed", severity: "breaking",
+                   description: "A tool that existed in the lockfile is no longer exposed by the server.") do |c|
+            next nil unless c[:kind] == "tool-removed"
+
+            finding(c[:name], "tool was removed")
+          end,
+
+          Rule.new(id: "tool-param-required-added", severity: "breaking",
+                   description: "A tool input parameter is now required (newly required existing param, or new required param). Calls that previously validated are now rejected.") do |c|
+            next nil unless c[:kind] == "tool-modified"
+
+            f = []
+            SchemaDiff.diff_object_schema(c[:before]["inputSchema"], c[:after]["inputSchema"]).each do |sc|
+              next unless sc[:kind] == "required-added"
+
+              f << finding(c[:name], sc[:existed_before] ? %(param "#{sc[:param]}" is now required) : %(new required param "#{sc[:param]}"))
+            end
+            f.empty? ? nil : f
+          end,
+
+          Rule.new(id: "tool-param-removed", severity: "breaking",
+                   description: "A tool input parameter was removed. Callers still sending it may be rejected (additionalProperties) or silently ignored.") do |c|
+            next nil unless c[:kind] == "tool-modified"
+
+            f = []
+            SchemaDiff.diff_object_schema(c[:before]["inputSchema"], c[:after]["inputSchema"]).each do |sc|
+              f << finding(c[:name], %(param "#{sc[:param]}" was removed)) if sc[:kind] == "param-removed"
+            end
+            f.empty? ? nil : f
+          end,
+
+          Rule.new(id: "tool-param-type-narrowed", severity: "breaking",
+                   description: "A tool input parameter accepts fewer types or values than before (type set shrank, or an enum constraint appeared). Inputs that used to validate are now rejected.") do |c|
+            next nil unless c[:kind] == "tool-modified"
+
+            f = []
+            SchemaDiff.diff_object_schema(c[:before]["inputSchema"], c[:after]["inputSchema"]).each do |sc|
+              case sc[:kind]
+              when "type-narrowed"
+                f << finding(c[:name], %(param "#{sc[:param]}" type narrowed (#{sc[:before]} → #{sc[:after]})))
+              when "enum-constraint-added"
+                f << finding(c[:name], %(param "#{sc[:param]}" is now restricted to an enum))
+              end
+            end
+            f.empty? ? nil : f
+          end,
+
+          Rule.new(id: "tool-enum-value-removed", severity: "breaking",
+                   description: "An enum value was removed from a tool input parameter. Calls sending the removed value are now rejected.") do |c|
+            next nil unless c[:kind] == "tool-modified"
+
+            f = []
+            SchemaDiff.diff_object_schema(c[:before]["inputSchema"], c[:after]["inputSchema"]).each do |sc|
+              next unless sc[:kind] == "enum-value-removed"
+
+              f << finding(c[:name], %(param "#{sc[:param]}": enum value(s) removed: #{SchemaDiff.format_values(sc[:values])}))
+            end
+            f.empty? ? nil : f
+          end,
+
+          Rule.new(id: "tool-input-schema-incompatible", severity: "breaking",
+                   description: "Catch-all: the tool's input schema changed in a way mcp-diff cannot prove compatible (nested or unrecognized JSON-Schema constructs). Fails loud rather than silently passing (D9).") do |c|
+            next nil unless c[:kind] == "tool-modified"
+
+            f = []
+            SchemaDiff.diff_object_schema(c[:before]["inputSchema"], c[:after]["inputSchema"]).each do |sc|
+              case sc[:kind]
+              when "param-changed-opaque"
+                f << finding(c[:name], %(param "#{sc[:param]}" schema changed — cannot prove compatibility))
+              when "schema-changed-opaque"
+                f << finding(c[:name], "input schema changed — cannot prove compatibility")
+              end
+            end
+            f.empty? ? nil : f
+          end,
+
+          Rule.new(id: "tool-output-schema-incompatible", severity: "breaking",
+                   description: "The tool's output schema no longer keeps its promise: a field was removed, made optional, widened, or changed unrecognizably. Outputs may no longer validate against what consumers expect (covariant, D9).") do |c|
+            next nil unless c[:kind] == "tool-modified"
+
+            f = []
+            SchemaDiff.diff_object_schema(c[:before]["outputSchema"], c[:after]["outputSchema"]).each do |sc|
+              msg =
+                case sc[:kind]
+                when "param-removed" then %(output field "#{sc[:param]}" was removed)
+                when "required-removed" then %(output field "#{sc[:param]}" is no longer guaranteed)
+                when "type-widened" then %(output field "#{sc[:param]}" type widened (#{sc[:before]} → #{sc[:after]}))
+                when "enum-value-added" then %(output field "#{sc[:param]}": new enum value(s) old consumers don't expect: #{SchemaDiff.format_values(sc[:values])})
+                when "enum-constraint-removed" then %(output field "#{sc[:param]}" is no longer enum-constrained)
+                when "param-changed-opaque" then %(output field "#{sc[:param]}" schema changed — cannot prove compatibility)
+                when "schema-changed-opaque" then "output schema changed — cannot prove compatibility"
+                end
+              f << finding(c[:name], msg) if msg
+            end
+            f.empty? ? nil : f
+          end,
+
+          Rule.new(id: "capability-removed", severity: "breaking",
+                   description: "A server capability (tools, resources, prompts, logging, …) is no longer advertised. Clients relying on it will fail.") do |c|
+            next nil unless c[:kind] == "capability-removed"
+
+            finding(c[:capability], "capability was removed")
+          end,
+
+          Rule.new(id: "resource-removed", severity: "breaking",
+                   description: "A resource that existed in the lockfile is no longer exposed (matched by uri).") do |c|
+            next nil unless c[:kind] == "resource-removed"
+
+            finding(c[:uri], "resource was removed")
+          end,
+
+          Rule.new(id: "prompt-removed", severity: "breaking",
+                   description: "A prompt that existed in the lockfile is no longer exposed (matched by name).") do |c|
+            next nil unless c[:kind] == "prompt-removed"
+
+            finding(c[:name], "prompt was removed")
+          end,
+
+          # ───────────────── behavior ─────────────────
+          Rule.new(id: "tool-description-changed", severity: "behavior",
+                   description: "A tool's description text changed. For MCP the description is the prompt surface steering the LLM — a change can alter when and how agents call the tool.") do |c|
+            next nil unless c[:kind] == "tool-modified"
+            next nil if c[:before]["description"] == c[:after]["description"]
+
+            finding(c[:name], "description text changed (LLM prompt surface)")
+          end,
+
+          Rule.new(id: "tool-param-description-changed", severity: "behavior",
+                   description: "A tool input parameter's description changed. Param descriptions are read by the LLM when filling arguments — a change can alter what agents pass.") do |c|
+            next nil unless c[:kind] == "tool-modified"
+
+            f = []
+            SchemaDiff.diff_object_schema(c[:before]["inputSchema"], c[:after]["inputSchema"]).each do |sc|
+              next unless sc[:kind] == "description-changed"
+
+              f << finding(c[:name], %(param "#{sc[:param]}" description changed (LLM prompt surface)))
+            end
+            f.empty? ? nil : f
+          end,
+
+          Rule.new(id: "tool-annotation-changed", severity: "behavior",
+                   description: "Tool annotations changed (readOnlyHint, destructiveHint, idempotentHint, …). Clients use these to decide confirmation prompts and parallelism — a change alters agent behavior.") do |c|
+            next nil unless c[:kind] == "tool-modified"
+            next nil if Canonical.deep_equal(c[:before]["annotations"], c[:after]["annotations"])
+
+            before = Rules.keys_of(c[:before]["annotations"])
+            after = Rules.keys_of(c[:after]["annotations"])
+            changed = (before.keys | after.keys).reject { |k| Canonical.deep_equal(before[k], after[k]) }.sort
+            finding(c[:name], "annotations changed: #{changed.join(', ')}")
+          end,
+
+          Rule.new(id: "server-instructions-changed", severity: "behavior",
+                   description: "The server's instructions text changed. Instructions are injected into the client's system context — the LLM prompt surface for the whole server.") do |c|
+            next nil unless c[:kind] == "instructions-changed"
+
+            detail = c[:before].nil? ? "added" : (c[:after].nil? ? "removed" : "changed")
+            finding("server", "instructions #{detail} (LLM prompt surface)")
+          end,
+
+          Rule.new(id: "default-value-changed", severity: "behavior",
+                   description: "A tool input parameter's default value changed. Calls that omit the param now behave differently.") do |c|
+            next nil unless c[:kind] == "tool-modified"
+
+            f = []
+            SchemaDiff.diff_object_schema(c[:before]["inputSchema"], c[:after]["inputSchema"]).each do |sc|
+              next unless sc[:kind] == "default-changed"
+
+              f << finding(c[:name], %(param "#{sc[:param]}" default value changed))
+            end
+            f.empty? ? nil : f
+          end,
+
+          # ───────────────── compat ─────────────────
+          Rule.new(id: "tool-added", severity: "compat",
+                   description: "A new tool is exposed by the server.") do |c|
+            next nil unless c[:kind] == "tool-added"
+
+            finding(c[:name], "new tool")
+          end,
+
+          Rule.new(id: "tool-param-optional-added", severity: "compat",
+                   description: "A new optional input parameter was added. Existing calls keep working.") do |c|
+            next nil unless c[:kind] == "tool-modified"
+
+            f = []
+            SchemaDiff.diff_object_schema(c[:before]["inputSchema"], c[:after]["inputSchema"]).each do |sc|
+              next unless sc[:kind] == "param-added" && !sc[:required]
+
+              f << finding(c[:name], %(new optional param "#{sc[:param]}"))
+            end
+            f.empty? ? nil : f
+          end,
+
+          Rule.new(id: "tool-enum-value-added", severity: "compat",
+                   description: "An enum value was added to a tool input parameter. Existing calls keep working; new inputs are accepted.") do |c|
+            next nil unless c[:kind] == "tool-modified"
+
+            f = []
+            SchemaDiff.diff_object_schema(c[:before]["inputSchema"], c[:after]["inputSchema"]).each do |sc|
+              next unless sc[:kind] == "enum-value-added"
+
+              f << finding(c[:name], %(param "#{sc[:param]}": enum value(s) added: #{SchemaDiff.format_values(sc[:values])}))
+            end
+            f.empty? ? nil : f
+          end,
+
+          Rule.new(id: "tool-output-field-added", severity: "compat",
+                   description: "The tool's output schema gained a field. Old consumers ignore fields they don't know (covariant, D9).") do |c|
+            next nil unless c[:kind] == "tool-modified"
+
+            f = []
+            SchemaDiff.diff_object_schema(c[:before]["outputSchema"], c[:after]["outputSchema"]).each do |sc|
+              next unless sc[:kind] == "param-added"
+
+              f << finding(c[:name], %(output schema gained field "#{sc[:param]}"))
+            end
+            f.empty? ? nil : f
+          end,
+
+          Rule.new(id: "resource-added", severity: "compat",
+                   description: "A new resource is exposed by the server.") do |c|
+            next nil unless c[:kind] == "resource-added"
+
+            finding(c[:uri], "new resource")
+          end,
+
+          Rule.new(id: "prompt-added", severity: "compat",
+                   description: "A new prompt is exposed by the server.") do |c|
+            next nil unless c[:kind] == "prompt-added"
+
+            finding(c[:name], "new prompt")
+          end,
+
+          Rule.new(id: "capability-added", severity: "compat",
+                   description: "The server advertises a new capability.") do |c|
+            next nil unless c[:kind] == "capability-added"
+
+            finding(c[:capability], "new capability")
+          end,
+
+          # ───────────────── info ─────────────────
+          Rule.new(id: "server-version-changed", severity: "info",
+                   description: "The server's reported version changed. Informational — not a contract change by itself.") do |c|
+            next nil unless c[:kind] == "server-info-changed"
+
+            before = (c[:before] || {})["version"] || "(none)"
+            after = (c[:after] || {})["version"] || "(none)"
+            next nil if before == after
+
+            finding("server", "version #{before} → #{after}")
+          end,
+
+          Rule.new(id: "title-changed", severity: "info",
+                   description: "A display title changed (server, tool, resource, or prompt). Titles are for humans, not the model — informational.") do |c|
+            case c[:kind]
+            when "tool-modified", "prompt-modified"
+              c[:before]["title"] != c[:after]["title"] ? finding(c[:name], "title changed") : nil
+            when "resource-modified"
+              c[:before]["title"] != c[:after]["title"] ? finding(c[:uri], "title changed") : nil
+            when "server-info-changed"
+              (c[:before] || {})["title"] != (c[:after] || {})["title"] ? finding("server", "title changed") : nil
+            end
+          end
+        ]
+      end
+      # rubocop:enable Metrics/MethodLength, Metrics/AbcSize
+
+      ALL = build
+      CATALOG = ALL.map { |r| { "id" => r.id, "class" => r.severity, "description" => r.description } }.freeze
+    end
+  end
+end