moult 0.1.0

data/lib/moult/gate/evaluation.rb

@@ -0,0 +1,172 @@
+# frozen_string_literal: true
+
+module Moult
+  module Gate
+    # The pure verdict engine: given already-scoped observations and a {Policy},
+    # it decides each rule's outcome and the single top-level verdict. No IO, no
+    # git, no analysis objects — just the policy applied to hand-buildable facts —
+    # so it is pinned in test/test_gate_policy.rb. Drift is a bug.
+    #
+    # The verdict is an auditable APPLICATION of a recorded policy over
+    # confidence-graded candidates; it never claims code is certainly wrong or
+    # dead. A rule whose backing analysis didn't run is marked `evaluated: false`
+    # and never fails the gate (a broken tool is a tool-error concern, surfaced by
+    # the CLI exit code, not a policy violation).
+    module Evaluation
+      SEVERITY_SCALE = Boundaries::Severity::SCALE
+
+      # ---- observation inputs (one row per scoped finding) ----------------------
+      DeadCodeObs = Struct.new(:symbol_id, :path, :line, :confidence)
+      BoundaryObs = Struct.new(:symbol_id, :path, :line, :severity, :violation_type)
+      ComplexityObs = Struct.new(:symbol_id, :path, :line, :abc)
+      DuplicationObs = Struct.new(:symbol_id, :path, :line, :mass)
+
+      # The full input. Each analysis's list is nil when that analysis was skipped
+      # (errored, or not applicable — e.g. a non-packwerk repo for boundaries);
+      # +diagnostics+ maps a skipped analysis to its reason.
+      Observations = Struct.new(:dead_code, :boundaries, :complexity, :duplication, :diagnostics) do
+        def initialize(dead_code: nil, boundaries: nil, complexity: nil, duplication: nil, diagnostics: {})
+          super
+        end
+      end
+
+      # ---- output ---------------------------------------------------------------
+      Reason = Struct.new(:rule, :detail) do
+        def to_h
+          {rule: rule.to_s, detail: detail}
+        end
+      end
+
+      # One contributing finding behind a rule outcome. Stays confidence-graded:
+      # +value+ is the observed signal (confidence/abc/mass/severity), never a
+      # claim of certainty.
+      Contribution = Struct.new(:category, :path, :symbol_id, :line, :value) do
+        def to_h
+          {category: category, path: path, symbol_id: symbol_id, line: line, value: value}
+        end
+      end
+
+      RuleOutcome = Struct.new(:rule, :evaluated, :observed, :threshold, :passed, :reasons, :findings) do
+        def to_h
+          {
+            rule: rule,
+            evaluated: evaluated,
+            observed: observed,
+            threshold: threshold,
+            passed: passed,
+            reasons: reasons.map(&:to_h),
+            findings: findings.map(&:to_h)
+          }
+        end
+      end
+
+      Verdict = Struct.new(:verdict, :reasons, :rules)
+
+      module_function
+
+      # @param observations [Observations]
+      # @param policy [Policy]
+      # @return [Verdict]
+      def evaluate(observations:, policy:)
+        diags = observations.diagnostics || {}
+        rules = [
+          dead_code_rule(observations.dead_code, policy, diags[:dead_code]),
+          boundary_rule(observations.boundaries, policy, diags[:boundaries]),
+          complexity_rule(observations.complexity, policy, diags[:complexity]),
+          duplication_rule(observations.duplication, policy, diags[:duplication])
+        ]
+
+        failed = rules.select { |r| r.evaluated && r.passed == false }
+        verdict = failed.empty? ? "pass" : "fail"
+        Verdict.new(verdict: verdict, reasons: verdict_reasons(verdict, failed), rules: rules)
+      end
+
+      # ---- rules ----------------------------------------------------------------
+      #
+      # Each rule names the threshold and the genuinely varying bits — which
+      # observations violate it, the worst observed value, the per-finding value,
+      # and a noun phrase for the detail — and hands them to {outcome}, which owns
+      # the shared RuleOutcome construction.
+
+      def dead_code_rule(obs, policy, diagnostic)
+        t = policy.dead_code_max_confidence
+        outcome("no_new_dead_code", "< #{t}", obs, diagnostic, "dead_code") do |list|
+          violating = list.select { |o| o.confidence >= t }
+          detail = phrase(violating, "no new dead-code candidate reaches confidence #{t} on changed lines",
+            "new dead-code candidate(s) at or above confidence #{t} on changed lines")
+          [violating, list.map(&:confidence).max, detail, ->(o) { o.confidence }]
+        end
+      end
+
+      def boundary_rule(obs, policy, diagnostic)
+        t = policy.boundary_max_severity
+        ti = SEVERITY_SCALE.index(t) || 0
+        outcome("no_new_high_severity_boundary", "<= #{t}", obs, diagnostic, "architecture_boundary") do |list|
+          violating = list.select { |o| (SEVERITY_SCALE.index(o.severity) || 0) > ti }
+          detail = phrase(violating, "no new boundary violation exceeds #{t} severity in changed files",
+            "new boundary violation(s) above #{t} severity in changed files")
+          [violating, list.map(&:severity).max_by { |s| SEVERITY_SCALE.index(s) || -1 }, detail, ->(o) { o.severity }]
+        end
+      end
+
+      def complexity_rule(obs, policy, diagnostic)
+        t = policy.complexity_ceiling
+        outcome("new_code_complexity_ceiling", "<= #{t}", obs, diagnostic, "complexity") do |list|
+          violating = list.select { |o| o.abc > t }
+          detail = phrase(violating, "no changed method exceeds ABC complexity #{t}",
+            "changed method(s) exceed ABC complexity #{t}")
+          [violating, list.map(&:abc).max, detail, ->(o) { o.abc }]
+        end
+      end
+
+      def duplication_rule(obs, policy, diagnostic)
+        t = policy.duplication_max_mass
+        outcome("new_code_duplication_ceiling", "<= #{t}", obs, diagnostic, "structural_duplication") do |list|
+          violating = list.select { |o| o.mass > t }
+          detail = phrase(violating, "no clone group touching the diff exceeds mass #{t}",
+            "clone group(s) touching the diff exceed mass #{t}")
+          [violating, list.map(&:mass).max, detail, ->(o) { o.mass }]
+        end
+      end
+
+      # ---- shared construction --------------------------------------------------
+
+      # Build a rule's outcome. The block, given the (non-nil) observation list,
+      # returns [violating, observed, detail, value_extractor]; a nil list means the
+      # backing analysis was skipped, so the rule is not evaluated and cannot fail.
+      def outcome(rule, threshold, obs, diagnostic, category)
+        return skipped(rule, threshold, diagnostic) if obs.nil?
+
+        violating, observed, detail, value = yield(obs)
+        RuleOutcome.new(
+          rule: rule, evaluated: true, observed: observed, threshold: threshold,
+          passed: violating.empty?,
+          reasons: [Reason.new(rule: rule.to_sym, detail: detail)],
+          findings: violating.map { |o| Contribution.new(category: category, path: o.path, symbol_id: o.symbol_id, line: o.line, value: value.call(o)) }
+        )
+      end
+
+      def skipped(rule, threshold, diagnostic)
+        RuleOutcome.new(
+          rule: rule, evaluated: false,
+          observed: nil, threshold: threshold, passed: nil,
+          reasons: [Reason.new(rule: :skipped, detail: diagnostic || "backing analysis did not run; rule not evaluated")],
+          findings: []
+        )
+      end
+
+      # "no X ..." when nothing violates, "<n> X ..." otherwise.
+      def phrase(violating, none, some)
+        violating.empty? ? none : "#{violating.size} #{some}"
+      end
+
+      def verdict_reasons(verdict, failed)
+        if verdict == "pass"
+          [Reason.new(rule: :clean_as_you_code, detail: "all evaluated policy rules passed on the scoped changes")]
+        else
+          failed.map { |r| Reason.new(rule: r.rule.to_sym, detail: r.reasons.first.detail) }
+        end
+      end
+    end
+  end
+end

data/lib/moult/gate/policy.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+module Moult
+  module Gate
+    # The explicit, recorded set of thresholds the gate enforces — the realisation
+    # of "Clean as You Code" for Moult. A Policy is a plain value object; the
+    # thresholds it carries are serialized into every gate report so the verdict is
+    # auditable (never a hidden heuristic) and reproducible.
+    #
+    # The {DEFAULTS} are judgement-based heuristics in the spirit of the health
+    # knees — calibrated against a real corpus (Moult's own codebase: a default
+    # must let a clean, well-tested gem pass). They are pinned in
+    # test/test_gate_policy.rb; drift is a bug. Teams override them via the `gate:`
+    # section of .moult.yml.
+    class Policy
+      DEFAULTS = {
+        # A dead-code candidate on changed lines at or above this confidence fails
+        # the gate. Public symbols base well below this; the rule bites freshly
+        # added unused private methods — the canonical "new dead code" smell.
+        dead_code_max_confidence: 0.8,
+
+        # The highest boundary severity allowed to appear in a changed file. With
+        # "medium", a new HIGH-severity packwerk violation (dependency/layer) fails.
+        boundary_max_severity: "medium",
+
+        # A changed method whose ABC complexity exceeds this ceiling fails the gate.
+        complexity_ceiling: 30.0,
+
+        # A clone group touching the diff whose flay mass exceeds this fails. Set to
+        # roughly a fully duplicated ~10-line method: below it lies idiomatic
+        # parallelism (sibling guard clauses, similar small methods) that a clean
+        # codebase legitimately has, so a lower bar produces noise, not signal.
+        duplication_max_mass: 100,
+
+        # Path prefixes excluded from gating. Test/spec code is legitimately
+        # repetitive (parallel cases, shared setup), so — like SonarQube and
+        # CodeScene — the gate judges production code. Findings under these prefixes
+        # are dropped from every rule. Override to [] to gate everything.
+        exclude_paths: ["test", "spec"]
+      }.freeze
+
+      KEYS = DEFAULTS.keys.freeze
+
+      attr_reader :dead_code_max_confidence, :boundary_max_severity,
+        :complexity_ceiling, :duplication_max_mass, :exclude_paths, :source
+
+      def initialize(dead_code_max_confidence:, boundary_max_severity:,
+        complexity_ceiling:, duplication_max_mass:, exclude_paths:, source:)
+        @dead_code_max_confidence = dead_code_max_confidence
+        @boundary_max_severity = boundary_max_severity
+        @complexity_ceiling = complexity_ceiling
+        @duplication_max_mass = duplication_max_mass
+        @exclude_paths = exclude_paths
+        @source = source
+      end
+
+      class << self
+        # The pinned defaults, recorded with source "default".
+        # @return [Policy]
+        def default
+          load({}, source: "default")
+        end
+
+        # Merge a (string- or symbol-keyed) overrides hash onto {DEFAULTS}. Unknown
+        # keys are ignored so a stray .moult.yml entry can't silently weaken the gate.
+        # @param overrides [Hash]
+        # @param source [String] provenance for the report (e.g. ".moult.yml")
+        # @return [Policy]
+        def load(overrides, source:)
+          new(**DEFAULTS.merge(sanitize(overrides)), source: source)
+        end
+
+        private
+
+        def sanitize(overrides)
+          (overrides || {}).each_with_object({}) do |(key, value), acc|
+            sym = key.to_sym
+            acc[sym] = value if KEYS.include?(sym)
+          end
+        end
+      end
+
+      # Is +path+ (root-relative) outside the gate's scope — i.e. under an excluded
+      # prefix like test/ or spec/?
+      def excluded?(path)
+        segment = path.to_s.split("/").first
+        exclude_paths.include?(segment)
+      end
+
+      # The auditable record of every applied threshold.
+      def to_h
+        {
+          source: source,
+          dead_code_max_confidence: dead_code_max_confidence,
+          boundary_max_severity: boundary_max_severity,
+          complexity_ceiling: complexity_ceiling,
+          duplication_max_mass: duplication_max_mass,
+          exclude_paths: exclude_paths
+        }
+      end
+    end
+  end
+end

data/lib/moult/gate.rb

@@ -0,0 +1,199 @@
+# frozen_string_literal: true
+
+module Moult
+  # Orchestrates the diff-aware PR risk gate — the capstone of the static layer and
+  # the gem-level core of what later becomes the GitHub App.
+  #
+  # It reuses {Health}'s composer discipline: each signal analysis runs inside its
+  # own rescue so one failure degrades that rule (evaluated: false) rather than
+  # crashing the gate. It then scopes every finding to the diff (via {Diff}),
+  # extracts pure observations, and hands them to the pinned {Gate::Evaluation}
+  # model together with the recorded {Gate::Policy}. This file is the only layer
+  # that does IO and knows where the signals come from; Policy/Evaluation stay pure
+  # functions so they can be pinned in isolation.
+  #
+  # The gate consumes signals and renders a verdict; it never mutates a signal
+  # contract, and the two protected APIs are untouched. The verdict is an auditable
+  # application of an explicit policy over confidence-graded candidates — never a
+  # claim that code is certainly wrong or dead.
+  module Gate
+    # Fixed component order so the provenance block is stable.
+    KNOWN_COMPONENTS = %w[complexity dead_code duplication boundaries].freeze
+
+    # The outcome of one isolated analysis run (mirrors {Health::Run}).
+    Run = Struct.new(:value, :error) do
+      def ok?
+        error.nil? && !value.nil?
+      end
+    end
+
+    module_function
+
+    # @param root [String] absolute analysis root (should be the repo root)
+    # @param files [Array<String>] absolute Ruby file paths to analyse
+    # @param index [Index] resolved definition/reference index (drives dead code)
+    # @param rails [RailsConventions] Rails entrypoint awareness for dead code
+    # @param base_ref [String] base ref for the diff (e.g. "origin/main")
+    # @param scope [Symbol] :diff (default) or :all
+    # @param policy [Gate::Policy] the thresholds to apply
+    # @param churn_since [String, nil] churn window for the complexity analysis
+    # @return [GateReport]
+    def build_report(root:, files:, index:, rails:, base_ref:, scope:, policy:,
+      git_ref: nil, generated_at: nil, churn_since: nil)
+      diff = Diff.compute(root: root, base_ref: base_ref, scope: scope)
+      runs = run_analyses(root: root, files: files, index: index, rails: rails, churn_since: churn_since)
+      observations = observe(runs, diff, policy)
+
+      GateReport.new(
+        root: root,
+        base_ref: diff.base_ref,
+        merge_base: diff.merge_base,
+        scope: diff.scope,
+        components: component_views(runs),
+        policy: policy,
+        evaluation: Evaluation.evaluate(observations: observations, policy: policy),
+        git_ref: git_ref,
+        generated_at: generated_at
+      )
+    end
+
+    # Run each signal analysis in isolation (the composer discipline).
+    def run_analyses(root:, files:, index:, rails:, churn_since:)
+      # Churn is only collected to satisfy {Scoring}; the complexity rule reads
+      # each method's ABC + span, which are churn-independent.
+      churn = Churn.collect(root: root, since: churn_since || Churn::DEFAULT_SINCE)
+      {
+        "complexity" => run { Scoring.build_report(root: root, files: files, churn: churn) },
+        "dead_code" => run { DeadCode.build_report(root: root, files: files, index: index, rails: rails) },
+        "duplication" => run { Duplication.build_report(root: root, files: files) },
+        "boundaries" => run { Boundaries.build_report(root: root) }
+      }
+    end
+
+    # Scope every analysis's findings to the diff, into pure observations, then drop
+    # any under an excluded path (test/spec) so the gate judges production code.
+    def observe(runs, diff, policy)
+      Evaluation::Observations.new(
+        complexity: gated(scope_complexity(runs["complexity"], diff), policy),
+        dead_code: gated(scope_dead_code(runs["dead_code"], diff), policy),
+        duplication: gated(scope_duplication(runs["duplication"], diff), policy),
+        boundaries: gated(scope_boundaries(runs["boundaries"], diff), policy),
+        diagnostics: diagnostics(runs)
+      )
+    end
+
+    # Drop excluded-path observations; nil (a skipped analysis) passes through.
+    def gated(observations, policy)
+      return nil if observations.nil?
+
+      observations.reject { |o| policy.excluded?(o.path) }
+    end
+
+    # Run one analysis in isolation (mirrors {Health.run}).
+    def run
+      Run.new(value: yield, error: nil)
+    rescue => e
+      Run.new(value: nil, error: e.message)
+    end
+
+    # ---- scoping (analysis findings -> pure, diff-filtered observations) -------
+
+    # nil signals a skipped analysis (errored): its rule is not evaluated.
+    def scope_complexity(run, diff)
+      return nil unless run.ok?
+
+      run.value.hotspots.flat_map do |hotspot|
+        hotspot.methods.filter_map do |method|
+          next unless diff.in_diff?(path: hotspot.path, start_line: method.span.start_line, end_line: method.span.end_line)
+
+          Evaluation::ComplexityObs.new(
+            symbol_id: method.symbol_id, path: hotspot.path,
+            line: method.span.start_line, abc: method.abc
+          )
+        end
+      end
+    end
+
+    def scope_dead_code(run, diff)
+      return nil unless run.ok?
+
+      run.value.findings.filter_map do |finding|
+        next unless diff.in_diff?(path: finding.path, start_line: finding.span.start_line, end_line: finding.span.end_line)
+
+        Evaluation::DeadCodeObs.new(
+          symbol_id: finding.symbol_id, path: finding.path,
+          line: finding.span.start_line, confidence: finding.confidence
+        )
+      end
+    end
+
+    # One observation per clone GROUP touching the diff (mass is a group property);
+    # attributed to its first in-diff occurrence.
+    def scope_duplication(run, diff)
+      return nil unless run.ok?
+
+      run.value.findings.filter_map do |finding|
+        occ = finding.occurrences.find { |o| diff.in_diff?(path: o.path, start_line: o.line, end_line: o.line) }
+        next unless occ
+
+        Evaluation::DuplicationObs.new(
+          symbol_id: occ.symbol_id, path: occ.path, line: occ.line, mass: finding.mass
+        )
+      end
+    end
+
+    # Boundaries are file-keyed (null symbol_id), so they scope at PATH granularity.
+    # Skipped unless the project is actually packwerk-configured.
+    def scope_boundaries(run, diff)
+      return nil unless boundaries_contributes?(run)
+
+      run.value.findings.flat_map do |finding|
+        finding.occurrences.filter_map do |occ|
+          next unless diff.includes_path?(occ.path)
+
+          Evaluation::BoundaryObs.new(
+            symbol_id: nil, path: occ.path, line: nil,
+            severity: finding.severity, violation_type: finding.violation_type
+          )
+        end
+      end
+    end
+
+    def boundaries_contributes?(run)
+      run.ok? && run.value.configured
+    end
+
+    # ---- provenance -----------------------------------------------------------
+
+    def diagnostics(runs)
+      diags = {}
+      %w[complexity dead_code duplication].each do |name|
+        diags[name.to_sym] = runs[name].error if runs[name].error
+      end
+      unless boundaries_contributes?(runs["boundaries"])
+        diags[:boundaries] = runs["boundaries"].error || "not a packwerk project (no packwerk.yml)"
+      end
+      diags
+    end
+
+    def component_views(runs)
+      KNOWN_COMPONENTS.map do |name|
+        present = (name == "boundaries") ? boundaries_contributes?(runs[name]) : runs[name].ok?
+        diagnostic = present ? nil : component_diagnostic(name, runs[name])
+        GateReport::Component.new(name: name, present: present, diagnostic: diagnostic)
+      end
+    end
+
+    def component_diagnostic(name, run)
+      return run.error if run.error
+      return "not a packwerk project (no packwerk.yml)" if name == "boundaries"
+
+      "analysis produced no result"
+    end
+  end
+end
+
+require_relative "gate/policy"
+require_relative "gate/evaluation"
+require_relative "gate/config"
+require_relative "gate_report"

data/lib/moult/gate_report.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+module Moult
+  # The serialized result model for `moult gate` (schema/gate.schema.json), sibling
+  # to {HealthReport} and {BoundariesReport}. It owns its own JSON envelope and
+  # leaves every signal contract — and the two protected APIs — untouched.
+  #
+  # This is the FIRST and ONLY Moult contract that renders a VERDICT. Every other
+  # analysis emits a confidence-graded / classified SIGNAL with no pass/fail; the
+  # gate consumes those signals, applies an explicit recorded {Gate::Policy}, and
+  # reports one top-level verdict. The verdict is an auditable application of that
+  # policy over confidence-graded candidates — never a claim that code is certainly
+  # wrong or dead. The words "verdict"/"pass"/"fail" live here and nowhere else.
+  class GateReport
+    # Bump only on a breaking change to the serialized shape.
+    SCHEMA_VERSION = 1
+
+    # Provenance for one signal analysis the gate composed: did it contribute, and
+    # if not, why (errored, or not applicable — e.g. a non-packwerk repo).
+    Component = Struct.new(:name, :present, :diagnostic) do
+      def to_h
+        {name: name, present: present, diagnostic: diagnostic}
+      end
+    end
+
+    attr_reader :root, :git_ref, :generated_at, :base_ref, :merge_base, :scope,
+      :components, :policy, :evaluation
+
+    # @param root [String] absolute analysis root
+    # @param base_ref [String, nil] requested base ref (nil under :all scope)
+    # @param merge_base [String, nil] resolved merge-base sha (nil under :all scope)
+    # @param scope [Symbol] :diff or :all
+    # @param components [Array<Component>] which signal analyses ran/were skipped
+    # @param policy [Gate::Policy] the applied policy (recorded in full)
+    # @param evaluation [Gate::Evaluation::Verdict] verdict + per-rule outcomes
+    def initialize(root:, base_ref:, merge_base:, scope:, components:, policy:, evaluation:,
+      git_ref: nil, generated_at: nil)
+      @root = root
+      @base_ref = base_ref
+      @merge_base = merge_base
+      @scope = scope
+      @components = components
+      @policy = policy
+      @evaluation = evaluation
+      @git_ref = git_ref
+      @generated_at = generated_at
+    end
+
+    # The top-level verdict, "pass" or "fail". The CLI maps this to its exit code.
+    def verdict
+      evaluation.verdict
+    end
+
+    def rules
+      evaluation.rules
+    end
+
+    def reasons
+      evaluation.reasons
+    end
+
+    # Contributing findings flattened across all rules (for CI projections).
+    def findings
+      rules.flat_map(&:findings)
+    end
+
+    def summary
+      {
+        rules: rules.size,
+        evaluated: rules.count(&:evaluated),
+        failed: rules.count { |r| r.evaluated && r.passed == false },
+        findings: findings.size
+      }
+    end
+
+    def to_h
+      {
+        schema_version: SCHEMA_VERSION,
+        tool: {name: "moult", version: Moult::VERSION},
+        analysis: {
+          root: root,
+          git_ref: git_ref,
+          generated_at: generated_at,
+          base_ref: base_ref,
+          merge_base: merge_base,
+          scope: scope.to_s,
+          components: components.map(&:to_h)
+        },
+        policy: policy.to_h,
+        verdict: verdict,
+        reasons: reasons.map(&:to_h),
+        summary: summary,
+        rules: rules.map(&:to_h)
+      }
+    end
+  end
+end

data/lib/moult/git.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+require "open3"
+
+module Moult
+  # Thin, injection-safe wrapper over the git CLI. All commands run with an
+  # explicit working directory and argument array (never a shell string), and
+  # failures surface as nil/false rather than exceptions so callers can degrade
+  # gracefully outside a repository.
+  module Git
+    module_function
+
+    # @return [Boolean] whether +dir+ is inside a git work tree
+    def repo?(dir)
+      out, _, status = Open3.capture3("git", "rev-parse", "--is-inside-work-tree", chdir: dir)
+      status.success? && out.strip == "true"
+    rescue SystemCallError
+      false
+    end
+
+    # @return [String, nil] the HEAD commit sha, or nil outside a repo
+    def head_ref(dir)
+      out = capture(dir, "rev-parse", "HEAD")
+      out&.strip
+    end
+
+    # @return [Array<String>] tracked + untracked-but-not-ignored files,
+    #   relative to +dir+, respecting .gitignore. Empty outside a repo.
+    def listed_files(dir)
+      out = capture(dir, "ls-files", "--cached", "--others", "--exclude-standard", "-z")
+      return [] unless out
+
+      out.split("\x0").reject(&:empty?)
+    end
+
+    # Raw `git log` file listing for churn: one path per line, blank lines
+    # between commits. Each commit lists a touched path at most once.
+    # @return [String, nil] nil outside a repo
+    def log_name_only(dir, since:)
+      capture(dir, "log", "--since=#{since}", "--name-only", "--pretty=format:")
+    end
+
+    # ---- diff adapter (drives the PR risk gate's diff scoping) ----------------
+    #
+    # These three are the ONLY git calls behind the diff-aware gate. They return
+    # raw text (or nil/false on failure); {Diff} owns all parsing, so this file
+    # stays the single shell gateway and the parser can be pinned in isolation.
+
+    # The common ancestor of +base_ref+ and HEAD — the "new code" boundary, the
+    # same merge-base semantics SonarQube/CodeScene use to scope a diff.
+    # @return [String, nil] the merge-base sha, or nil if it can't be resolved
+    #   (base_ref unknown, shallow clone with no common history, outside a repo)
+    def merge_base(dir, base_ref)
+      out = capture(dir, "merge-base", base_ref, "HEAD")
+      out&.strip
+    end
+
+    # `git diff --name-status REF`: one "<status>\t<path>" line per changed file
+    # between +ref+ and the working tree (renames carry two paths). Empty string
+    # when nothing changed; nil on failure.
+    # @return [String, nil]
+    def diff_name_status(dir, ref)
+      capture(dir, "diff", "--name-status", ref)
+    end
+
+    # `git diff --unified=0 REF`: a context-free unified diff between +ref+ and the
+    # working tree. Zero context means each hunk header's new-side range
+    # (`@@ -a,b +c,d @@`) is exactly the changed/added lines — what the gate needs
+    # to scope findings to the diff. Empty string when nothing changed; nil on failure.
+    # @return [String, nil]
+    def diff_unified_zero(dir, ref)
+      capture(dir, "diff", "--unified=0", ref)
+    end
+
+    # Run a git subcommand, returning stdout, or nil on any failure.
+    def capture(dir, *args)
+      out, _, status = Open3.capture3("git", *args, chdir: dir)
+      status.success? ? out : nil
+    rescue SystemCallError
+      nil
+    end
+  end
+end