rail_verdict 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 1e670a01af3af01cfa3698b4842130b0a14368bfb08215536233bdd3423ef246
+  data.tar.gz: dae1e03f62fdc014fe37475a6299b1679113ee4ba0bebdadf7d46e883234bd66
+SHA512:
+  metadata.gz: c512dc731422fff707233b0ebfeadd7dd85e6a846f19bfa6958be98905c8946d11ef1d85206e6ec7aa9952b12498ab39ca0c9b2f89d8c7c227ec10be53475fd1
+  data.tar.gz: c4b08aae8dd9e704df651737cb9a96fbe1adfab763c44fe56bb4cabd6fb71dd5fb2211e0cc786e8686dd3b379891f8ca8f0b28064235ae10bc8c118893c003cf

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 RailVerdict Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/NOTICE

@@ -0,0 +1,14 @@
+RailVerdict
+Copyright (c) 2026 Pedro Dalben
+
+This product is licensed under the MIT License. See LICENSE for details.
+Third-party dependencies and analyzer tools retain their own licenses;
+see docs/analyzers.md and the NOTICE of any distributed artifact for details.
+
+Copyright holder: Pedro Dalben
+Trademark/project owner: Pedro Dalben (no registration claimed; qualified review not performed — non-blocking by maintainer decision 2026-08-19, Pedro Dalben — residual risk accepted)
+Security contact: dev@pedrodalben.com.br
+Legal/trademark contact: dev@pedrodalben.com.br
+Repository: https://github.com/pedro-dalben/RailVerdict
+
+Qualified trademark/name review remains NOT PERFORMED — NON-BLOCKING BY MAINTAINER DECISION for initial open-source publication; recommended but not mandatory. Preliminary screen 2026-08-19: no obvious conflict observed; NOT LEGAL CLEARANCE. See docs/foundation.md.

data/README.md

@@ -0,0 +1,192 @@
+# RailVerdict
+
+**Evidence before merge. Deterministic, offline, fail-closed verification for Ruby on Rails.**
+
+[![Gem Version](https://badge.fury.io/rb/rail_verdict.svg)](https://rubygems.org/gems/rail_verdict)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Ruby](https://img.shields.io/badge/ruby-%3E%3D%203.3-CC342D.svg)](https://www.ruby-lang.org)
+
+RailVerdict collects evidence from established Ruby/Rails quality tools, normalizes it into versioned canonical findings, applies repository-owned policy and baselines, and returns a deterministic merge gate for **humans, CI, and coding agents**.
+
+> **One command. One gate.** No SaaS, no accounts, no telemetry, no hosted service. Core verification is fully offline.
+
+---
+
+## Why RailVerdict?
+
+Existing tools give fragmented signals — lint, tests, coverage, dependencies. RailVerdict's value is the **stable verification model** that makes those signals *comparable, policy-addressable, and machine-readable* with one deterministic `PASS / WARN / FAIL / INCOMPLETE`.
+
+| Problem | How RailVerdict helps |
+|---|---|
+| "Passing" CI that hid incomplete evidence | Incomplete required analyzers can never become `PASS` (`INCOMPLETE` / exit 2) |
+| Legacy debt blocks adoption | Versioned fingerprints + baselines + `no_new_debt` — existing debt retained, only regressions block |
+| Untrusted PR code near secrets | `--changed` from trustworthy local Git facts; safe GitHub Actions example with minimum permissions |
+| Agents scraping terminal output | Versioned JSON (`result-v1`) + stable exit codes + canonical ordering |
+| "Where is this finding related?" | Bounded Rails-aware context (models, routes, views, policies, schema, associations) without booting Rails |
+
+---
+
+## Quick Start
+
+```bash
+gem install rail_verdict
+
+# In a Rails (or synthetic) repository:
+railverdict init                          # writes .railverdict.yml (mode: no_new_debt)
+railverdict doctor                        # validates config, probes analyzers
+# no_new_debt without a baseline → INCOMPLETE (baseline_required); create a baseline first:
+railverdict check                         # full verification → console (or INCOMPLETE baseline_required)
+railverdict baseline create               # atomic baseline from a complete run (requires PASS/WARN/FAIL, not INCOMPLETE)
+railverdict check --format json           # versioned JSON on stdout, diagnostics on stderr
+railverdict check --changed --base main   # changed-scope gate from deterministic Git diff
+railverdict findings --format json        # projection of normalized findings
+```
+
+**Exit codes:** `0` PASS/WARN · `1` FAIL · `2` INCOMPLETE/config/tool error · `130` interrupted.
+
+**Notes:** RailVerdict does NOT bundle or install analyzers, boot Rails, update bundler-audit DB, require AI or MCP. Configure/install desired analyzers in the target bundle, then `railverdict doctor` shows status. With `mode: no_new_debt`, `check` returns `INCOMPLETE baseline_required` until you run `baseline create`.
+
+---
+
+## What Runs
+
+All analyzers are **external and target-project-owned** — RailVerdict never installs or bundles them.
+
+| Adapter | What it consumes | Supported versions |
+|---|---|---|
+| **RuboCop** (+ `rubocop-rails` provenance) | `bundle exec rubocop --format json` | RuboCop `>= 1.72, < 2` · `rubocop-rails >= 2, < 3` |
+| **Minitest** | RailVerdict-owned reporter → `minitest-reporter-v1` JSON | `>= 5, < 7` |
+| **RSpec** | `--format json` | `>= 3.13, < 4` |
+| **SimpleCov** | Public `coverage/coverage.json` v1 (never `.resultset.json`/HTML) | `>= 1, < 2` |
+| **bundler-audit** | `check --format json` (never `update`) | `>= 0.9.3, < 1` |
+
+Each adapter maps the full failure corpus (`unavailable`, `unsupported`, `timed_out`, `signaled`, `failed`, `parse_failed`, `truncated`, `malformed`) and records tool provenance.
+
+---
+
+## Core Concepts
+
+```
+AnalyzerResult (what a tool did)
+      │
+      ▼
+   Finding (analyzer-independent, fingerprinted, versioned)
+      │
+      ▼
+  Comparison (introduced / existing / resolved / changed / moved · rename-aware)
+      │
+      ▼
+    Policy (advisory · no_new_debt · strict) ──► GateResult (immutable)
+      │                                              │
+      ▼                                              ▼
+  Console / JSON / SARIF / GitHub Annotations    exit code
+```
+
+- **Fingerprint v1** — canonical payload `sha256:<64hex>` over `{analyzer, rule_id, path, message}` (line/timestamp/path-order agnostic).
+- **Baselines** — versioned, atomic (`fsync` + `rename`), read-only checks never mutate them.
+- **Waivers** — exact-fingerprint, with `owner`, `reason`, `created_at`, UTC `expires_at`, optional `issue_ref`.
+- **Comparison** — `moved` = same rule+message, different path (rename-aware); `changed` = same path+rule, different message; `introduced`/`resolved` are fallback.
+- **Policy** — the *only* gate authority; adapters/reporters/AI can never change it. `required: true` incomplete → `INCOMPLETE`, not `PASS`.
+
+---
+
+## Changed Scope & GitHub
+
+```bash
+railverdict check --changed --base origin/main              # PR-like
+railverdict check --changed --base HEAD~1 --format json     # local diff
+```
+
+- Resolves `HEAD`, `base` (`--base` > `git.base` in `.railverdict.yml`), `merge-base`, NUL-safe changed files/lines, renames, binaries, conflicts.
+- Missing base or shallow/incomplete history → `INCOMPLETE` (`git_scope_failed`) — never guesses.
+- Production changed-line coverage uses the same `changed_line_set` recorded in `RunContext`.
+
+**GitHub Actions** — see [`docs/github-actions.md`](docs/github-actions.md) and [`examples/github/railverdict.yml`](examples/github/railverdict.yml): `pull_request` (never `pull_request_target`), `contents: read`, `fetch-depth: 0` at `head.sha`, same local gate invoked as `bundle exec railverdict check --changed --base ${{ github.event.pull_request.base.sha }}`. SARIF and annotation projections are pure `GateResult` projections.
+
+---
+
+## Rails-Aware Context (Phase 05)
+
+When `--changed` is used, RailVerdict enriches the result with **bounded, deterministic Rails relationships** — without booting the app, loading ActiveRecord, executing `routes.rb`/`schema.rb`, or building a code graph.
+
+For each **changed** file, it classifies `kind` + `constant` and resolves:
+
+- **Related tests** — `test/**/…_test.rb` / `spec/**/…_spec.rb` that physically exist (candidates, not "affected" guarantees).
+- **Policies** — `app/policies/<model>_policy.rb`.
+- **Views** — `app/views/<controller>/…` (bounded, deterministic).
+- **Routes** — literal `resources` / `get … to: '…#…'` mappings from `config/routes.rb` (`draw`/`mount`/`concerns` → `unresolved`).
+- **Schema** — `db/schema.rb` table fragments (`db/structure.sql` → `unresolved`).
+- **Associations** — literal `belongs_to` / `has_one` / `has_many` / `has_and_belongs_to_many`.
+
+Every related item carries `confidence` in `{exact, conventional, inferred, unresolved}` and a `provenance` string. Failures degrade to partial context, never to `INCOMPLETE`. Full details: [`docs/rails-context.md`](docs/rails-context.md).
+
+```json
+"rails_context": {
+  "detected": { "rails_version": "8.0.1", "test_framework": "rspec", "database_adapter": "postgresql" },
+  "scope": "changed",
+  "entries": [{ "source_path": "app/models/user.rb", "kind": "model", "constant": "User", "related": […] }]
+}
+```
+
+---
+
+## Configuration
+
+```yaml
+# .railverdict.yml (v1.3)
+version: 1.3
+mode: no_new_debt          # advisory | no_new_debt | strict
+analyzers:
+  rubocop:       { enabled: true, required: true }
+  minitest:      { enabled: true, required: true }
+  rspec:         { enabled: true, required: false }
+  simplecov:     { enabled: true, required: false, coverage_path: coverage/coverage.json, freshness_window_seconds: 86400 }
+  bundler_audit: { enabled: true, required: false }
+git:
+  base: main               # fallback for --changed when --base is not passed
+```
+
+Strict, versioned schemas: `configuration-v1` … `v1.3`, `finding-v1`, `result-v1`, `baseline-v1`, `waivers-v1`, `coverage-v1`. Unknown fields fail with a property path. See [`docs/contracts.md`](docs/contracts.md).
+
+---
+
+## Documentation
+
+| Topic | File |
+|---|---|
+| Product, philosophy, architecture | [`PROJECT.md`](PROJECT.md) · [`PHILOSOPHY.md`](PHILOSOPHY.md) · [`ARCHITECTURE.md`](ARCHITECTURE.md) |
+| Public contracts & CLI surface | [`docs/contracts.md`](docs/contracts.md) |
+| Analyzers & support proposal | [`docs/analyzers.md`](docs/analyzers.md) |
+| Baselines, comparison, waivers | [`docs/baselines.md`](docs/baselines.md) |
+| GitHub Actions & SARIF | [`docs/github-actions.md`](docs/github-actions.md) |
+| Rails-aware context | [`docs/rails-context.md`](docs/rails-context.md) |
+| MCP (agents) | [`docs/mcp.md`](docs/mcp.md) · [`examples/mcp/client_config.json`](examples/mcp/client_config.json) |
+| AI & privacy | [`docs/ai.md`](docs/ai.md) · [`docs/privacy.md`](docs/privacy.md) |
+| Repair workflow | [`docs/repair-workflow.md`](docs/repair-workflow.md) |
+| Security & information firewall | [`SECURITY.md`](SECURITY.md) |
+| Changelog | [`CHANGELOG.md`](CHANGELOG.md) |
+| Roadmap (Phase 0–9) | [`ROADMAP.md`](ROADMAP.md) |
+| ADRs | [`docs/adr/`](docs/adr/) |
+
+---
+
+## Development
+
+```bash
+bundle install
+bundle exec rake test          # synthetic fixtures only, deterministic
+bundle exec rubocop
+```
+
+- Ruby `>= 3.3`, one gem, one process, `json_schemer` as sole runtime dependency.
+- External execution via `executable + argv` (no shell interpolation), bounded I/O, monotonic timeout, process-group cleanup, minimal env, NFC-normalized paths.
+
+---
+
+## Legal
+
+- **License:** [MIT](LICENSE) — see [NOTICE](NOTICE)
+- **Trademarks:** [TRADEMARKS.md](TRADEMARKS.md)
+- **Foundation:** [docs/foundation.md](docs/foundation.md) — name evidence, identity mapping, preliminary screen (no obvious conflict; NOT LEGAL CLEARANCE), qualified trademark review NOT PERFORMED — NON-BLOCKING BY MAINTAINER DECISION 2026-08-19 (Pedro Dalben)
+- **Schemas:** [finding v1](schemas/finding-v1.schema.json), [configuration v1](schemas/configuration-v1.schema.json), [result v1](schemas/result-v1.schema.json)
+- **Examples:** [finding](examples/finding-v1.json), [configuration](examples/configuration-v1.yml), [result](examples/result-v1.json)

data/exe/railverdict

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "rail_verdict"
+
+exit RailVerdict::CLI.new.run(ARGV)

data/exe/railverdict-minitest-reporter.rb

@@ -0,0 +1,90 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "json"
+require "minitest"
+
+class RailverdictMinitestReporter < Minitest::AbstractReporter
+  def initialize(output_path)
+    @output_path = output_path
+    @results = []
+    @start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+  end
+
+  def record(result)
+    status =
+      if result.skipped?
+        "skipped"
+      elsif result.error?
+        "errored"
+      elsif result.failure
+        "failed"
+      else
+        "passed"
+      end
+
+    failure = result.failure
+    entry = {
+      "class_name" => result.klass.to_s,
+      "method_name" => result.name.to_s,
+      "status" => status,
+      "time_seconds" => result.time.to_f.round(6)
+    }
+    if failure
+      entry["failure_message"] = failure.message.to_s.encode(Encoding::UTF_8, invalid: :replace, undef: :replace, replace: "?")[0, 4096]
+      entry["failure_class"] = failure.class.name.to_s.encode(Encoding::UTF_8, invalid: :replace, undef: :replace, replace: "?")[0, 256]
+      loc = failure.location.to_s
+      captures = loc.match(/\A(.+):(\d+)(\z|:\d+:\z)/)&.captures
+      file = captures && captures[0]
+      line_str = captures && captures[1]
+      if file && line_str
+        line = Integer(line_str, 10) rescue nil
+        if line && line >= 1
+          entry["file"] = file.encode(Encoding::UTF_8, invalid: :replace, undef: :replace, replace: "?")[0, 1024]
+          entry["line"] = line
+        end
+      end
+    end
+    @results << entry
+  end
+
+  def report
+    duration = (Process.clock_gettime(Process::CLOCK_MONOTONIC) - @start_time).round(6)
+    runner = Minitest::VERSION ? "minitest #{Minitest::VERSION}" : "minitest unknown"
+    seed = Minitest.respond_to?(:seed) ? Minitest.seed : nil
+    failures = @results.count { |r| r["status"] == "failed" }
+    errors = @results.count { |r| r["status"] == "errored" }
+    skips = @results.count { |r| r["status"] == "skipped" }
+    assertions = @results.count { |r| %w[passed failed errored].include?(r["status"]) }
+    seed_val = seed && Integer(seed) rescue nil
+    @results.sort_by! { |t| [t["class_name"], t["method_name"]] }
+    document = {
+      "schema_version" => "1.0",
+      "runner" => runner,
+      "seed" => seed_val,
+      "tests_total" => @results.length,
+      "assertions" => assertions,
+      "failures" => failures,
+      "errors" => errors,
+      "skips" => skips,
+      "duration_seconds" => duration,
+      "tests" => @results
+    }
+    File.write(@output_path, JSON.generate(document))
+  end
+end
+
+output_path = ENV["RAILVERDICT_MINITEST_OUTPUT"].to_s
+unless output_path.empty?
+  Minitest.load_plugins
+  Minitest.extensions << :railverdict
+  module Minitest
+    class << self
+      def plugin_railverdict_init(options)
+        self.reporter << RailverdictMinitestReporter.new(ENV["RAILVERDICT_MINITEST_OUTPUT"].to_s)
+      end
+
+      def plugin_railverdict_options(opts, options); end
+    end
+  end
+end

data/lib/rail_verdict/analyzers/_shared.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module RailVerdict
+  module Analyzers
+    module Shared
+      module_function
+
+      def bounded_message(message)
+        message.to_s.encode(Encoding::UTF_8, invalid: :replace, undef: :replace, replace: "?")[0, 4096]
+      end
+
+      def detail_for(run_result)
+        detail = run_result.detail.to_s
+        stderr = run_result.stderr.to_s.lines.first.to_s.strip
+        bounded_message([detail, stderr].reject(&:empty?).join(": "))
+      end
+
+      def execution_message(run_result)
+        message = run_result.stderr.to_s.lines.first.to_s.strip
+        message = "#{run_result.detail}" if message.empty?
+        message = "execution failed with status #{run_result.exit_code}" if message.empty?
+        bounded_message(message)
+      end
+
+      def truncated?(run_result)
+        run_result.stdout_truncated || run_result.stderr_truncated
+      end
+
+      def parse_semver(output)
+        match = output.to_s.match(/\b(\d+\.\d+\.\d+)\b/)
+        match && match[1]
+      end
+
+      def invocation_for(command, arguments)
+        {
+          "executable" => command.fetch(:executable),
+          "argv" => command.fetch(:args_prefix).dup.concat(arguments)
+        }
+      end
+
+      def failure_result(analyzer_id:, invocation:, status:, message:, tool_version: nil)
+        status = status.to_s
+        AnalyzerResult.new(
+          analyzer: analyzer_id,
+          tool_version: tool_version,
+          invocation: invocation,
+          execution_status: status,
+          finding_ids: [],
+          failure: { "code" => status, "message" => bounded_message(message.to_s) }
+        )
+      end
+    end
+  end
+end

data/lib/rail_verdict/analyzers/bundler_audit.rb

@@ -0,0 +1,186 @@
+# frozen_string_literal: true
+
+require "json"
+
+require_relative "_shared"
+
+module RailVerdict
+  module Analyzers
+    class BundlerAudit
+      ANALYZER_ID = "bundler_audit"
+      SUPPORTED_VERSIONS = Gem::Requirement.new(">= 0.9.3", "< 1")
+
+      Probe = Struct.new(:status, :version, :message, :database_updated_at, keyword_init: true)
+
+      class MalformedOutput < StandardError; end
+
+      def initialize(command_resolver: nil)
+        @command_resolver = command_resolver || method(:default_command)
+      end
+
+      def probe(repository_root, runner: ProcessRunner, timeout_seconds: 15.0)
+        command = @command_resolver.call(repository_root)
+        invocation = Shared.invocation_for(command, ["version"])
+        result = runner.run(
+          command.fetch(:executable),
+          invocation.fetch("argv"),
+          chdir: repository_root,
+          timeout_seconds: timeout_seconds
+        )
+
+        return Probe.new(status: "unavailable", message: Shared.detail_for(result)) if result.status == :spawn_failed
+        return Probe.new(status: "timed_out", message: Shared.detail_for(result)) if result.status == :timed_out
+        return Probe.new(status: "signaled", message: Shared.detail_for(result)) if result.status == :signaled
+        return Probe.new(status: "truncated", message: Shared.detail_for(result)) if Shared.truncated?(result)
+        return Probe.new(status: "unavailable", message: Shared.detail_for(result)) unless result.exit_code == 0
+
+        version = Shared.parse_semver(result.stdout)
+        return Probe.new(status: "unsupported", message: "bundler-audit version could not be parsed") unless version
+        return Probe.new(status: "unsupported", version: version, message: "unsupported bundler-audit version #{version}") unless SUPPORTED_VERSIONS.satisfied_by?(Gem::Version.new(version))
+
+        db_updated = parse_database_updated(result.stdout)
+
+        Probe.new(status: "succeeded", version: version, database_updated_at: db_updated)
+      rescue ArgumentError
+        Probe.new(status: "unsupported", message: "bundler-audit reported an invalid version")
+      rescue KeyError, ArgumentError => error
+        Probe.new(status: "malformed", message: Shared.bounded_message(error.message))
+      end
+
+      def run(repository_root, runner: ProcessRunner, timeout_seconds: 30.0, probe_result: nil)
+        command = @command_resolver.call(repository_root)
+        probe_result ||= probe(repository_root, runner: runner, timeout_seconds: timeout_seconds)
+        version_invocation = Shared.invocation_for(command, ["version"])
+
+        unless probe_result.status == "succeeded"
+          return [Shared.failure_result(analyzer_id: ANALYZER_ID, invocation: version_invocation, status: probe_result.status, message: probe_result.message, tool_version: probe_result.version), []]
+        end
+
+        invocation = Shared.invocation_for(command, ["check", "--format", "json"])
+        result = runner.run(
+          command.fetch(:executable),
+          invocation.fetch("argv"),
+          chdir: repository_root,
+          timeout_seconds: timeout_seconds
+        )
+        tool_version = probe_result.version
+
+        return [Shared.failure_result(analyzer_id: ANALYZER_ID, invocation: invocation, status: "unavailable", message: Shared.detail_for(result), tool_version: tool_version), []] if result.status == :spawn_failed
+        return [Shared.failure_result(analyzer_id: ANALYZER_ID, invocation: invocation, status: "truncated", message: Shared.detail_for(result), tool_version: tool_version), []] if Shared.truncated?(result)
+        return [Shared.failure_result(analyzer_id: ANALYZER_ID, invocation: invocation, status: "timed_out", message: Shared.detail_for(result), tool_version: tool_version), []] if result.status == :timed_out
+        return [Shared.failure_result(analyzer_id: ANALYZER_ID, invocation: invocation, status: "signaled", message: Shared.detail_for(result), tool_version: tool_version), []] if result.status == :signaled
+
+        begin
+          document = JSON.parse(result.stdout)
+        rescue JSON::ParserError => error
+          return [Shared.failure_result(analyzer_id: ANALYZER_ID, invocation: invocation, status: "parse_failed", message: Shared.bounded_message(error.message), tool_version: tool_version), []]
+        end
+
+        begin
+          summary, findings = normalize_document(document, tool_version)
+        rescue MalformedOutput => error
+          return [Shared.failure_result(analyzer_id: ANALYZER_ID, invocation: invocation, status: "malformed", message: Shared.bounded_message(error.message), tool_version: tool_version), []]
+        end
+
+        analyzer_result = AnalyzerResult.new(
+          analyzer: ANALYZER_ID,
+          tool_version: tool_version,
+          invocation: invocation,
+          execution_status: "succeeded",
+          finding_ids: findings.map(&:id),
+          evidence_summary: summary
+        )
+        [analyzer_result, findings]
+      end
+
+      private
+
+      def default_command(repository_root)
+        if File.file?(File.join(repository_root, "Gemfile"))
+          { executable: "bundle", args_prefix: ["exec", "bundler-audit"] }
+        else
+          { executable: "bundler-audit", args_prefix: [] }
+        end
+      end
+
+      def parse_database_updated(output)
+        match = output.to_s.match(/database.*?(\d{4}-\d{2}-\d{2})/i)
+        match && match[1]
+      end
+
+      def normalize_document(document, tool_version)
+        raise MalformedOutput, "bundler-audit JSON root must be an object" unless document.is_a?(Hash)
+
+        results = document["results"] || document["vulnerabilities"] || document["advisories"] || []
+        raise MalformedOutput, "bundler-audit results must be an array" unless results.is_a?(Array)
+
+        findings = []
+        results.each_with_index do |entry, index|
+          finding = normalize_entry(entry, index)
+          findings << finding if finding
+        end
+
+        findings = findings.uniq { |f| f.fingerprint }.sort_by(&:sort_key)
+        summary = {
+          "vulnerabilities" => findings.length,
+          "tool_version" => tool_version.to_s[0, 64],
+          "database_updated_at" => parse_database_updated(document.to_s)
+        }
+
+        [summary, findings]
+      end
+
+      def normalize_entry(entry, index)
+        raise MalformedOutput, "bundler-audit entry #{index} must be an object" unless entry.is_a?(Hash)
+
+        advisory = entry["advisory"] || entry
+        id = (advisory["id"] || entry["id"] || "advisory-#{index}").to_s
+        id = "advisory-#{index}" if id.empty?
+        gem_name = (entry["gem"] && entry["gem"]["name"]) || entry["gem_name"] || advisory["gem"] || "unknown"
+        gem_name = "unknown" if gem_name.to_s.empty?
+
+        severity = map_severity(advisory["criticality"] || advisory["severity"] || entry["criticality"] || entry["severity"])
+        message = (advisory["title"] || advisory["description"] || entry["title"] || entry["description"] || "vulnerability in #{gem_name}").to_s
+        message = message.encode(Encoding::UTF_8, invalid: :replace, undef: :replace, replace: "?")[0, 4096]
+        message = "vulnerability in #{gem_name}" if message.empty?
+
+        rule_id = "bundler_audit/advisory:#{id}"
+        category = "dependency"
+
+        path = "Gemfile.lock"
+        fingerprint = Finding.fingerprint_for(
+          analyzer: ANALYZER_ID,
+          rule_id: rule_id,
+          path: path,
+          message: message
+        )
+        Finding.new(
+          fingerprint: fingerprint,
+          origin: "deterministic",
+          analyzer: ANALYZER_ID,
+          rule_id: rule_id,
+          category: category,
+          severity: severity,
+          confidence: "high",
+          state: "observed",
+          evidence_ref: "native:bundler_audit:#{fingerprint.delete_prefix("sha256:")[0, 12]}",
+          location: { "path" => path },
+          message: message
+        )
+      rescue ArgumentError => error
+        raise MalformedOutput, "bundler-audit entry #{index} is malformed: #{error.message}"
+      end
+
+      def map_severity(raw)
+        case raw.to_s.downcase
+        when "critical" then "critical"
+        when "high" then "high"
+        when "medium" then "medium"
+        when "low" then "low"
+        when "info", "unknown", "" then "medium"
+        else "medium"
+        end
+      end
+    end
+  end
+end