rail_verdict 1.0.0

data/lib/rail_verdict/mcp/tools/list_findings.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+module RailVerdict
+  module MCP
+    module Tools
+      class ListFindings
+        def initialize(server:)
+          @server = server
+        end
+
+        def tool_name
+          "list_findings"
+        end
+
+        def tool_title
+          "List findings"
+        end
+
+        def tool_description
+          "List deterministic findings from the last verification. Supports filtering by severity/state/blocking and pagination via limit/offset. Stable ordering by path/start_line/analyzer/rule/fingerprint/id. Truncated flag is explicit."
+        end
+
+        def tool_input_schema
+          {
+            type: "object",
+            properties: {
+              limit: { type: "integer", description: "Max findings to return (1..100, default 50)" },
+              offset: { type: "integer", description: "Offset (default 0)" },
+              severity: { type: "string", enum: %w[info low medium high critical], description: "Filter by severity" },
+              state: { type: "string", enum: %w[observed introduced existing resolved changed moved suppressed waived], description: "Filter by state" },
+              blocking: { type: "boolean", description: "Filter by blocking" }
+            },
+            additionalProperties: false
+          }
+        end
+
+        def tool_output_schema
+          {
+            type: "object",
+            properties: {
+              findings: { type: "array" },
+              total: { type: "integer" },
+              limit: { type: "integer" },
+              offset: { type: "integer" },
+              truncated: { type: "boolean" },
+              gate: { type: "string" },
+              completion_status: { type: "string" }
+            },
+            required: %w[findings total limit offset truncated]
+          }
+        end
+
+        def tool_annotations
+          { read_only_hint: true, destructive_hint: false, idempotent_hint: true, open_world_hint: false, title: tool_title }
+        end
+
+        def call(limit: nil, offset: nil, severity: nil, state: nil, blocking: nil, **_rest)
+          begin
+            limit_v = Validators.validate_limit(limit, default: 50, max: 100)
+            offset_v = Validators.validate_offset(offset)
+            severity_v = Validators.validate_severity(severity)
+            state_v = Validators.validate_state(state)
+
+            outcome = @server.cache.fetch_outcome
+            unless outcome
+              outcome = run_verify
+              @server.cache.store_outcome(outcome)
+            end
+
+            findings = outcome.findings || []
+            if severity_v
+              findings = findings.select { |f| f.severity == severity_v }
+            end
+            if state_v
+              gate_findings = outcome.result.findings
+              allowed_fps = gate_findings.select { |h| h["state"] == state_v }.map { |h| h["fingerprint"] }.to_set
+              findings = findings.select { |f| allowed_fps.include?(f.fingerprint) }
+            end
+            unless blocking.nil?
+              gate_findings = outcome.result.findings
+              allowed_fps = gate_findings.select { |h| h["blocking"] == blocking }.map { |h| h["fingerprint"] }.to_set
+              findings = findings.select { |f| allowed_fps.include?(f.fingerprint) }
+            end
+
+            findings = findings.sort_by(&:sort_key)
+            total = findings.length
+            if offset_v > total
+              return Serializers.error_response("offset exceeds total (#{total})", code: "invalid_arguments")
+            end
+            slice = findings.slice(offset_v, limit_v) || []
+            truncated = (offset_v + limit_v) < total
+
+            structured = {
+              "findings" => slice.map(&:to_schema_h),
+              "total" => total,
+              "limit" => limit_v,
+              "offset" => offset_v,
+              "truncated" => truncated,
+              "gate" => outcome.result.gate,
+              "completion_status" => outcome.result.completion_status
+            }
+            structured = Serializers.scrub(structured)
+            Serializers.tool_response(structured, error: false)
+          rescue ArgumentError => e
+            Serializers.error_response(e.message, code: "invalid_arguments")
+          rescue StandardError => e
+            Serializers.error_response("list_findings failed: #{e.message}", code: "internal_error")
+          end
+        end
+
+        private
+
+        def run_verify
+          Check.execute(repository_root: @server.repository_root, config_path: File.join(@server.repository_root, ".railverdict.yml"))
+        end
+      end
+    end
+  end
+end

data/lib/rail_verdict/mcp/tools/verify.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+module RailVerdict
+  module MCP
+    module Tools
+      class Verify
+        def initialize(server:)
+          @server = server
+        end
+
+        def tool_name
+          "verify"
+        end
+
+        def tool_title
+          "Verify repository"
+        end
+
+        def tool_description
+          "Deterministic read-only verification. Runs RailVerdict Check and returns GateResult (PASS/WARN/FAIL/INCOMPLETE). FAIL is a successful result (isError false) — not a protocol error. Works offline with no network. Requires no AI."
+        end
+
+        def tool_input_schema
+          {
+            type: "object",
+            properties: {
+              changed: { type: "boolean", description: "Use Git changed scope (--changed)" },
+              base: { type: "string", description: "Base revision for --changed (hex SHA 7..64)" },
+              config_path: { type: "string", description: "Path to .railverdict.yml relative to repository root" },
+              baseline_path: { type: "string", description: "Override baseline path" },
+              waiver_path: { type: "string", description: "Override waivers path" }
+            },
+            additionalProperties: false
+          }
+        end
+
+        def tool_output_schema
+          {
+            type: "object",
+            properties: {
+              schema_version: { type: "string" },
+              completion_status: { type: "string" },
+              gate: { type: "string" },
+              policy_status: { type: "string" },
+              findings: { type: "array" },
+              analyzer_results: { type: "array" },
+              operational_failures: { type: "array" },
+              decision_reasons: { type: "array" }
+            },
+            required: %w[schema_version completion_status gate policy_status findings]
+          }
+        end
+
+        def tool_annotations
+          { read_only_hint: true, destructive_hint: false, idempotent_hint: true, open_world_hint: false, title: tool_title }
+        end
+
+        def call(changed: nil, base: nil, config_path: nil, baseline_path: nil, waiver_path: nil, **_rest)
+          begin
+            changed = changed == true
+            base_validated = Validators.validate_base_revision(base)
+            if base_validated && !changed
+              return Serializers.error_response("--base requires --changed", code: "invalid_arguments")
+            end
+            config_file = resolve_config_path(config_path)
+            if changed
+              base_for_check = base_validated || configuration_git_base(config_file)
+              if base_for_check.nil? || base_for_check.strip.empty?
+                # Let Check handle git_scope_failed as INCOMPLETE — still need a base, but we try check anyway
+              end
+            end
+
+            outcome = @server.synchronized_verification { run_check(changed: changed, base: base_validated, config_path: config_file, baseline_path: baseline_path, waiver_path: waiver_path) }
+            @server.cache.store_outcome(outcome)
+            structured = Serializers.gate_result_to_structured(outcome)
+            structured = Validators.scrub_text(structured) if structured.is_a?(String)
+            structured = Serializers.scrub(structured)
+            Serializers.tool_response(structured, error: false)
+          rescue ArgumentError => e
+            Serializers.error_response(e.message, code: "invalid_arguments")
+          rescue StandardError => e
+            Serializers.error_response("verify failed: #{e.message}", code: "internal_error")
+          end
+        end
+
+        private
+
+        def run_check(changed:, base:, config_path:, baseline_path:, waiver_path:)
+          root = @server.repository_root
+          opts = { repository_root: root, config_path: config_path }
+          opts[:changed] = true if changed
+          opts[:base] = base if base
+          baseline_resolved = resolve_contained_path(baseline_path, "baseline_path") if baseline_path && !baseline_path.to_s.strip.empty?
+          waiver_resolved = resolve_contained_path(waiver_path, "waiver_path") if waiver_path && !waiver_path.to_s.strip.empty?
+          opts[:baseline_path_override] = baseline_resolved if baseline_resolved
+          opts[:waiver_path_override] = waiver_resolved if waiver_resolved
+          Check.execute(**opts)
+        end
+
+        def resolve_contained_path(raw_path, field_name)
+          raw = raw_path.to_s.strip
+          raise ArgumentError, "#{field_name} contains NUL byte" if raw.include?("\u0000")
+
+          expanded = File.expand_path(raw, @server.repository_root)
+          unless RepositoryRoot.contained?(@server.repository_root, expanded)
+            raise ArgumentError, "#{field_name} escapes repository root"
+          end
+          expanded
+        end
+
+        def resolve_config_path(config_path)
+          return File.join(@server.repository_root, ".railverdict.yml") if config_path.nil? || config_path.to_s.strip.empty?
+
+          raw = config_path.to_s.strip
+          raise ArgumentError, "config_path contains NUL byte" if raw.include?("\u0000")
+
+          expanded = File.expand_path(raw, @server.repository_root)
+          unless RepositoryRoot.contained?(@server.repository_root, expanded)
+            raise ArgumentError, "config_path escapes repository root"
+          end
+          expanded
+        end
+
+        def configuration_git_base(config_file)
+          return nil unless File.file?(config_file)
+
+          begin
+            cfg = Configuration.load(config_file)
+            cfg.git_base
+          rescue StandardError
+            nil
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rail_verdict/mcp/tools/verify_repair.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+module RailVerdict
+  module MCP
+    module Tools
+      class VerifyRepair
+        def initialize(server:)
+          @server = server
+        end
+
+        def tool_name
+          "verify_repair"
+        end
+
+        def tool_title
+          "Verify repair"
+        end
+
+        def tool_description
+          "Verify whether a prior RepairPacket target is fixed. Re-runs verification and classifies target_status (fixed/still_present/changed/moved/regressed/incomplete) plus verification_boundary_changed and gate. Never trusts agent-provided fixed claim."
+        end
+
+        def tool_input_schema
+          {
+            type: "object",
+            properties: {
+              packet_id: { type: "string", description: "Packet id (sha256:...); must match a prior build_repair_packet packet_id in this server session" },
+              changed: { type: "boolean", description: "Re-verify with Git changed scope" },
+              base: { type: "string", description: "Base revision for re-verify (hex SHA) when changed is true" }
+            },
+            required: ["packet_id"],
+            additionalProperties: false
+          }
+        end
+
+        def tool_output_schema
+          {
+            type: "object",
+            properties: {
+              target_status: { type: "string" },
+              gate: { type: "string" },
+              completion_status: { type: "string" },
+              overall_status: { type: "string" },
+              new_blocking_findings: { type: "integer" },
+              verification_boundary_changed: { type: ["object", "boolean"] },
+              regressed: { type: "boolean" },
+              gate_result: { type: "object" }
+            },
+            required: %w[target_status gate completion_status]
+          }
+        end
+
+        def tool_annotations
+          { read_only_hint: true, destructive_hint: false, idempotent_hint: true, open_world_hint: false, title: tool_title }
+        end
+
+        def call(packet_id: nil, changed: nil, base: nil, **_rest)
+          begin
+            pid = Validators.validate_packet_id(packet_id)
+            changed_v = changed == true
+            base_v = Validators.validate_base_revision(base)
+            if base_v && !changed_v
+              return Serializers.error_response("--base requires --changed", code: "invalid_arguments")
+            end
+
+            packet_h = @server.cache.fetch_packet(pid)
+            unless packet_h
+              return Serializers.error_response("packet not found for packet_id: #{pid}; call build_repair_packet first", code: "stale_target")
+            end
+
+            fresh_outcome = @server.synchronized_verification { fresh_check(changed: changed_v, base: base_v) }
+            result = Repair::Verifier.verify(packet: packet_h, new_outcome: fresh_outcome)
+
+            structured = {
+              "target_status" => result.target_status,
+              "gate" => result.gate,
+              "completion_status" => result.completion_status,
+              "overall_status" => result.overall_status,
+              "new_blocking_findings" => result.new_blocking_findings,
+              "verification_boundary_changed" => result.verification_boundary_changed,
+              "regressed" => result.regressed,
+              "gate_result" => fresh_outcome.result.to_schema_h
+            }
+            structured = Serializers.scrub(structured)
+            Serializers.tool_response(structured, error: false)
+          rescue ArgumentError => e
+            Serializers.error_response(e.message, code: "invalid_arguments")
+          rescue StandardError => e
+            Serializers.error_response("verify_repair failed: #{e.message}", code: "internal_error")
+          end
+        end
+
+        private
+
+        def fresh_check(changed:, base:)
+          root = @server.repository_root
+          opts = { repository_root: root, config_path: File.join(root, ".railverdict.yml") }
+          opts[:changed] = true if changed
+          opts[:base] = base if base
+          Check.execute(**opts)
+        end
+      end
+    end
+  end
+end

data/lib/rail_verdict/mcp/validators.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module RailVerdict
+  module MCP
+    module Validators
+      FINDING_REF_PATTERN = /\A(?:rv:[0-9a-f]{20}|sha256:[0-9a-f]{64})\z/
+      BASE_REVISION_PATTERN = /\A[0-9a-f]{7,64}\z/
+      MAX_FINDING_REF_BYTES = 512
+
+      def self.validate_finding_ref(value)
+        raise ArgumentError, "finding_ref must be a non-empty string" unless value.is_a?(String) && !value.strip.empty?
+        raise ArgumentError, "finding_ref exceeds #{MAX_FINDING_REF_BYTES} bytes" if value.bytesize > MAX_FINDING_REF_BYTES
+        raise ArgumentError, "finding_ref contains NUL byte" if value.include?("\u0000")
+        raise ArgumentError, "finding_ref has invalid format" unless value.strip.match?(FINDING_REF_PATTERN)
+
+        value.strip
+      end
+
+      def self.validate_limit(value, default: 50, max: 100)
+        return default if value.nil?
+
+        raise ArgumentError, "limit must be an integer" unless value.is_a?(Integer)
+        raise ArgumentError, "limit must be between 1 and #{max}" unless value.between?(1, max)
+
+        value
+      end
+
+      def self.validate_offset(value)
+        return 0 if value.nil?
+
+        raise ArgumentError, "offset must be an integer >= 0" unless value.is_a?(Integer) && value >= 0
+
+        value
+      end
+
+      def self.validate_base_revision(value)
+        return nil if value.nil?
+        str = value.to_s.strip
+        return nil if str.empty?
+        raise ArgumentError, "base revision contains NUL byte" if str.include?("\u0000")
+        raise ArgumentError, "base revision has invalid format" unless str.match?(BASE_REVISION_PATTERN)
+
+        str
+      end
+
+      def self.validate_boolean(value, name)
+        return false if value.nil?
+        return value if value == true || value == false
+
+        raise ArgumentError, "#{name} must be a boolean"
+      end
+
+      def self.validate_severity(value)
+        return nil if value.nil?
+        allowed = %w[info low medium high critical]
+        raise ArgumentError, "severity must be one of #{allowed.join(', ')}" unless allowed.include?(value)
+
+        value
+      end
+
+      def self.validate_state(value)
+        return nil if value.nil?
+        allowed = %w[observed introduced existing resolved changed moved suppressed waived]
+        raise ArgumentError, "state must be one of #{allowed.join(', ')}" unless allowed.include?(value)
+
+        value
+      end
+
+      def self.validate_packet_id(value)
+        raise ArgumentError, "packet_id must be a non-empty string" unless value.is_a?(String) && !value.strip.empty?
+        raise ArgumentError, "packet_id has invalid format" unless value.strip.match?(/\Asha256:[0-9a-f]{64}\z/)
+
+        value.strip
+      end
+
+      def self.scrub_text(value)
+        value.to_s.encode(Encoding::UTF_8, invalid: :replace, undef: :replace, replace: "\uFFFD").gsub(/[\x00-\x08\x0B\x0C\x0E-\x1F\x7F]/, "?")
+      end
+    end
+  end
+end

data/lib/rail_verdict/mcp.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+require_relative "mcp/repository_root"
+require_relative "mcp/validators"
+require_relative "mcp/serializers"
+require_relative "mcp/cache"
+require_relative "mcp/server"