rail_verdict 1.0.0

data/lib/rail_verdict/process_runner.rb

@@ -0,0 +1,292 @@
+# frozen_string_literal: true
+
+module RailVerdict
+  class ProcessRunner
+    class DirectoryError < RailVerdict::Error; end
+
+    DEFAULT_TIMEOUT_SECONDS = 30.0
+    DEFAULT_MAX_STDOUT_BYTES = 4 * 1024 * 1024
+    DEFAULT_MAX_STDERR_BYTES = 64 * 1024
+    READ_CHUNK_BYTES = 64 * 1024
+    TERM_GRACE_SECONDS = 0.1
+    REAP_POLL_SECONDS = 0.01
+
+    ENV_ALLOWLIST = %w[
+      PATH HOME GEM_HOME GEM_PATH LANG RAILVERDICT_MINITEST_OUTPUT
+    ].freeze
+    FORCED_ENV = { "LC_ALL" => "C.UTF-8", "TZ" => "UTC" }.freeze
+
+    RunResult = Struct.new(
+      :status, :exit_code, :signal, :stdout, :stderr,
+      :stdout_truncated, :stderr_truncated, :detail,
+      keyword_init: true
+    )
+
+    class << self
+      def run(executable, argv, chdir:, timeout_seconds: DEFAULT_TIMEOUT_SECONDS,
+              max_stdout_bytes: DEFAULT_MAX_STDOUT_BYTES, max_stderr_bytes: DEFAULT_MAX_STDERR_BYTES)
+        directory = verify_directory(chdir)
+        argv = argv.map { |element| validate_argv_element(element) }
+        env = build_env
+
+        stdout_read, stdout_write = IO.pipe
+        stderr_read, stderr_write = IO.pipe
+        pid = nil
+
+        begin
+          pid = Process.spawn(
+            env,
+            [executable, File.basename(executable)],
+            *argv,
+            chdir: directory,
+            pgroup: true,
+            in: :close,
+            out: stdout_write,
+            err: stderr_write
+          )
+        rescue Errno::ENOENT, Errno::EACCES, Errno::ENOTDIR, ArgumentError => error
+          return spawn_failure_result(error)
+        end
+
+        registry.register(pid)
+        stdout_write.close
+        stderr_write.close
+
+        execute_child(pid, stdout_read, stderr_read, timeout_seconds, max_stdout_bytes, max_stderr_bytes)
+      ensure
+        registry.unregister(pid) if pid
+        [stdout_read, stdout_write, stderr_read, stderr_write].compact.each do |io|
+          io.close unless io.closed?
+        end
+      end
+
+      def registry
+        @registry ||= Registry.new
+      end
+
+      def build_env
+        env = ENV.keys.to_h { |key| [key, nil] }
+        ENV_ALLOWLIST.each do |key|
+          value = ENV[key]
+          env[key] = value unless value.nil?
+        end
+        env.merge(FORCED_ENV)
+      end
+
+      private
+
+      def spawn_failure_result(error)
+        RunResult.new(
+          status: :spawn_failed,
+          exit_code: nil,
+          signal: nil,
+          stdout: String.new(encoding: Encoding::UTF_8),
+          stderr: String.new(encoding: Encoding::UTF_8),
+          stdout_truncated: false,
+          stderr_truncated: false,
+          detail: "#{error.class}: #{error.message}"
+        )
+      end
+
+      def verify_directory(chdir)
+        directory = File.realpath(chdir)
+        raise DirectoryError, "working directory is not a usable directory: #{chdir}" unless File.directory?(directory)
+
+        directory
+      rescue Errno::ENOENT, Errno::EACCES, Errno::ENOTDIR
+        raise DirectoryError, "working directory is not usable: #{chdir}"
+      end
+
+      def validate_argv_element(element)
+        raise ArgumentError, "argv elements must be strings" unless element.is_a?(String)
+        raise ArgumentError, "argv elements cannot contain NUL bytes" if element.include?("\u0000")
+
+        element
+      end
+
+      def execute_child(pid, stdout_read, stderr_read, timeout_seconds, max_stdout_bytes, max_stderr_bytes)
+        deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout_seconds
+        output = { buffer: String.new(encoding: Encoding::BINARY), cap: max_stdout_bytes, truncated: false }
+        errors = { buffer: String.new(encoding: Encoding::BINARY), cap: max_stderr_bytes, truncated: false }
+        streams = { stdout_read => output, stderr_read => errors }
+
+        timed_out = drain_streams(streams, deadline) == :timed_out
+        status, timed_out = await_child(pid, deadline, timed_out)
+        build_result(status, timed_out, output, errors, timeout_seconds)
+      end
+
+      def drain_streams(streams, deadline)
+        open_streams = streams.keys
+
+        until open_streams.empty?
+          remaining = deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          return :timed_out if remaining <= 0
+
+          ready = IO.select(open_streams, nil, nil, remaining)
+          next unless ready
+
+          ready.first.each do |io|
+            next unless read_stream(io, streams.fetch(io))
+
+            io.close
+            open_streams.delete(io)
+          end
+        end
+
+        nil
+      end
+
+      def read_stream(io, stream_state)
+        loop do
+          chunk = io.read_nonblock(READ_CHUNK_BYTES, exception: false)
+          return true if chunk.nil?
+          return false if chunk == :wait_readable
+
+          stream_state[:buffer] << chunk
+          if stream_state[:buffer].bytesize > stream_state.fetch(:cap)
+            stream_state[:truncated] = true
+            return true
+          end
+        end
+      end
+
+      def await_child(pid, deadline, already_timed_out)
+        loop do
+          if already_timed_out || Process.clock_gettime(Process::CLOCK_MONOTONIC) >= deadline
+            terminate_process_group(pid)
+            _, status = Process.waitpid2(pid)
+            return [status, true]
+          end
+
+          reaped_pid, status = Process.waitpid2(pid, Process::WNOHANG)
+          return [status, false] if reaped_pid
+
+          sleep REAP_POLL_SECONDS
+        end
+      end
+
+      def build_result(status, timed_out, output, errors, timeout_seconds)
+        if timed_out
+          return RunResult.new(
+            status: :timed_out,
+            exit_code: nil,
+            signal: nil,
+            stdout: encode_output(output[:buffer]),
+            stderr: encode_output(errors[:buffer]),
+            stdout_truncated: output[:truncated],
+            stderr_truncated: errors[:truncated],
+            detail: "process exceeded the #{timeout_seconds}s monotonic timeout and was terminated"
+          )
+        end
+
+        if status.exited?
+          RunResult.new(
+            status: :exited,
+            exit_code: status.exitstatus,
+            signal: nil,
+            stdout: encode_output(output[:buffer]),
+            stderr: encode_output(errors[:buffer]),
+            stdout_truncated: output[:truncated],
+            stderr_truncated: errors[:truncated],
+            detail: nil
+          )
+        else
+          signal_name = signal_name_for(status)
+          RunResult.new(
+            status: :signaled,
+            exit_code: nil,
+            signal: signal_name,
+            stdout: encode_output(output[:buffer]),
+            stderr: encode_output(errors[:buffer]),
+            stdout_truncated: output[:truncated],
+            stderr_truncated: errors[:truncated],
+            detail: "process terminated by signal #{signal_name}"
+          )
+        end
+      end
+
+      def signal_name_for(status)
+        return nil unless status.signaled?
+
+        Signal.signame(status.termsig)
+      rescue RuntimeError
+        "SIG#{status.termsig}"
+      end
+
+      def encode_output(bytes)
+        bytes.dup.force_encoding(Encoding::UTF_8).scrub("\uFFFD").freeze
+      end
+
+      def terminate_process_group(pid)
+        signal_group(pid, "TERM")
+        grace_deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + TERM_GRACE_SECONDS
+        while process_group_alive?(pid) && Process.clock_gettime(Process::CLOCK_MONOTONIC) < grace_deadline
+          sleep REAP_POLL_SECONDS
+        end
+        signal_group(pid, "KILL") if process_group_alive?(pid)
+      end
+
+      def signal_group(pid, signal)
+        Process.kill(signal, -pid)
+      rescue Errno::ESRCH, Errno::EINVAL
+        begin
+          Process.kill(signal, pid)
+        rescue Errno::ESRCH
+          nil
+        end
+      end
+
+      def process_group_alive?(pid)
+        Process.kill(0, -pid)
+        true
+      rescue Errno::ESRCH
+        false
+      end
+    end
+
+    class Registry
+      def initialize
+        @pids = {}
+      end
+
+      def register(pid)
+        @pids[pid] = true
+      end
+
+      def unregister(pid)
+        @pids.delete(pid)
+      end
+
+      def size
+        @pids.size
+      end
+
+      def terminate_all
+        pids = @pids.keys
+        return if pids.empty?
+
+        pids.each { |pid| signal_group(pid, "TERM") }
+        deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + ProcessRunner::TERM_GRACE_SECONDS
+        sleep 0.01 while Process.clock_gettime(Process::CLOCK_MONOTONIC) < deadline
+        pids.each do |pid|
+          signal_group(pid, "KILL")
+        end
+        # The active runner owns waitpid; the signal path must not reap the
+        # child before its normal cleanup resumes.
+        @pids.clear
+      end
+
+      private
+
+      def signal_group(pid, signal)
+        Process.kill(signal, -pid)
+      rescue Errno::ESRCH, Errno::EINVAL, Errno::EPERM
+        begin
+          Process.kill(signal, pid)
+        rescue Errno::ESRCH, Errno::EPERM
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/rail_verdict/rails_context/classifier.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module RailVerdict
+  module RailsContext
+    module Classifier
+      KINDS = %w[model controller job mailer helper service policy component view route schema migration test spec config lib unknown].freeze
+
+      PREFIX_MAP = {
+        "app/models/" => "model",
+        "app/controllers/" => "controller",
+        "app/jobs/" => "job",
+        "app/mailers/" => "mailer",
+        "app/helpers/" => "helper",
+        "app/services/" => "service",
+        "app/policies/" => "policy",
+        "app/components/" => "component",
+        "app/views/" => "view"
+      }.freeze
+
+      def self.classify(path)
+        normalized = normalize(path)
+        return "unknown" if normalized.empty?
+
+        PREFIX_MAP.each do |prefix, kind|
+          return kind if normalized.start_with?(prefix)
+        end
+
+        case normalized
+        when "config/routes.rb"
+          "route"
+        when "db/schema.rb"
+          "schema"
+        when /\Adb\/migrate\//
+          "migration"
+        when /\Atest\//
+          "test"
+        when /\Aspec\//
+          "spec"
+        when /\Aconfig\//
+          "config"
+        when /\Alib\//
+          "lib"
+        else
+          "unknown"
+        end
+      end
+
+      def self.normalize(path)
+        raw = path.to_s.encode(Encoding::UTF_8, invalid: :replace, undef: :replace, replace: "?").strip
+        raw = raw.delete_prefix("./").delete_prefix("/")
+        raw = raw.unicode_normalize(:nfc) if raw.respond_to?(:unicode_normalize)
+        raw.gsub(%r{//+}, "/")
+      end
+      private_class_method :normalize
+    end
+  end
+end

data/lib/rail_verdict/rails_context/confidence.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module RailVerdict
+  module RailsContext
+    module Confidence
+      VALUES = %w[exact conventional inferred unresolved].freeze
+
+      def self.valid?(value)
+        VALUES.include?(value.to_s)
+      end
+    end
+  end
+end

data/lib/rail_verdict/rails_context/constant_inferencer.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module RailVerdict
+  module RailsContext
+    module ConstantInferencer
+      def self.infer(kind:, path:)
+        normalized = path.to_s.encode(Encoding::UTF_8, invalid: :replace, undef: :replace, replace: "?").strip
+        normalized = normalized.delete_prefix("./").delete_prefix("/")
+        normalized = normalized.unicode_normalize(:nfc) if normalized.respond_to?(:unicode_normalize)
+
+        internal = case kind
+                   when "model"
+                     strip_prefix(normalized, "app/models/")
+                   when "controller"
+                     strip_prefix(normalized, "app/controllers/")
+                   when "job"
+                     strip_prefix(normalized, "app/jobs/")
+                   when "mailer"
+                     strip_prefix(normalized, "app/mailers/")
+                   when "helper"
+                     strip_prefix(normalized, "app/helpers/")
+                   when "service"
+                     strip_prefix(normalized, "app/services/")
+                   when "policy"
+                     strip_prefix(normalized, "app/policies/")
+                   when "component"
+                     strip_prefix(normalized, "app/components/")
+                   else
+                     return nil
+                   end
+        return nil if internal.nil? || internal.empty?
+        return nil unless internal.end_with?(".rb")
+
+        bare = internal.delete_suffix(".rb")
+        parts = bare.split("/").reject(&:empty?)
+        return nil if parts.empty?
+
+        parts.map { |segment| camelize(segment) }.join("::")
+      rescue StandardError
+        nil
+      end
+
+      def self.strip_prefix(path, prefix)
+        return nil unless path.start_with?(prefix)
+
+        path[prefix.length..]
+      end
+      private_class_method :strip_prefix
+
+      def self.camelize(segment)
+        segment.split("_").map { |word| word.empty? ? "" : word[0].upcase + word[1..].to_s }.join
+      end
+      private_class_method :camelize
+    end
+  end
+end

data/lib/rail_verdict/rails_context/context.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+module RailVerdict
+  module RailsContext
+    class Context
+      attr_reader :detected, :scope, :entries, :unresolved
+
+      def self.build(repository_root:, git_context: nil)
+        root = File.realpath(repository_root.to_s) rescue repository_root.to_s
+        detected = Detector.detect(repository_root: root)
+        scope = git_context ? "changed" : "full"
+
+        if git_context.nil?
+          return new(detected: detected, scope: scope, entries: [], unresolved: [])
+        end
+
+        changed = git_context.changed_files.map(&:path).compact.sort
+        rails_changed = changed.select { |path| Classifier.classify(path) != "unknown" }
+        rails_changed = rails_changed.reject do |path|
+          full = File.join(root, path)
+          File.file?(full) && File.size(full) > Limits::MAX_FILE_BYTES rescue false
+        end.first(Limits::MAX_FILES)
+
+        entries = rails_changed.map do |source_path|
+          kind = Classifier.classify(source_path)
+          constant = ConstantInferencer.infer(kind: kind, path: source_path)
+          related = []
+          unresolved = []
+
+          related.concat(Resolvers::TestCandidates.for(repository_root: root, kind: kind, path: source_path))
+          related.concat(Resolvers::PolicyResolver.for(repository_root: root, kind: kind, path: source_path, constant: constant))
+          related.concat(Resolvers::ViewResolver.for(repository_root: root, kind: kind, path: source_path, constant: constant))
+          related.concat(Resolvers::SchemaResolver.for(repository_root: root, kind: kind, constant: constant, path: source_path))
+          if kind == "model"
+            assocs = Resolvers::AssociationExtractor.extract(repository_root: root, path: source_path)
+            assocs.each do |assoc|
+              related << { "path" => source_path, "relationship" => "association:#{assoc['macro']} :#{assoc['name']}", "confidence" => assoc["confidence"], "provenance" => assoc["provenance"] }
+            end
+          end
+          if kind == "controller" || source_path == "config/routes.rb"
+            related.concat(Resolvers::RouteResolver.for(repository_root: root, kind: kind, constant: constant))
+          end
+
+          related = related.first(Limits::MAX_RELATED).sort_by { |item| [item["path"], item["relationship"]] }
+
+          scan = kind == "controller" ? Resolvers::RouteScanner.scan(repository_root: root) : nil
+          if scan && scan[:unresolved]
+            unresolved << { "source_path" => source_path, "reason" => "dynamic_route" }
+          end
+
+          {
+            "source_path" => source_path,
+            "kind" => kind,
+            "constant" => constant,
+            "confidence" => constant ? "exact" : "conventional",
+            "provenance" => "path:#{source_path}",
+            "related" => related,
+            "unresolved" => unresolved
+          }
+        end.sort_by { |entry| entry["source_path"] }
+
+        unresolved_global = []
+        route_scan = Resolvers::RouteScanner.scan(repository_root: root)
+        if route_scan[:unresolved]
+          unresolved_global << { "source_path" => "config/routes.rb", "reason" => "dynamic_dsl" }
+        end
+        has_structure = File.file?(File.join(root, "db/structure.sql"))
+        if has_structure
+          unresolved_global << { "source_path" => "db/structure.sql", "reason" => "structure_sql_not_parsed" }
+        end
+
+        new(detected: detected, scope: scope, entries: entries, unresolved: unresolved_global)
+      rescue StandardError
+        fallback_detected = begin; Detector.detect(repository_root: root); rescue StandardError; {}; end
+        new(detected: fallback_detected, scope: git_context ? "changed" : "full", entries: [], unresolved: [])
+      end
+
+      def initialize(detected:, scope:, entries:, unresolved:)
+        @detected = deep_freeze(detected)
+        @scope = scope.dup.freeze
+        @entries = deep_freeze(entries)
+        @unresolved = deep_freeze(unresolved)
+        freeze
+      end
+
+      def to_h
+        result = {
+          "detected" => detected,
+          "scope" => scope,
+          "entries" => entries
+        }
+        result["unresolved"] = unresolved unless unresolved.empty?
+        result
+      end
+
+      private
+
+      def deep_freeze(value)
+        case value
+        when Hash
+          value.each { |key, child| key.freeze if key.is_a?(String); deep_freeze(child) }
+          value.freeze
+        when Array
+          value.each { |child| deep_freeze(child) }
+          value.freeze
+        when String
+          value.freeze
+        else
+          value
+        end
+        value
+      end
+    end
+  end
+end

data/lib/rail_verdict/rails_context/detector.rb

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+
+module RailVerdict
+  module RailsContext
+    module Detector
+      def self.detect(repository_root:)
+        root = File.realpath(repository_root.to_s) rescue repository_root.to_s
+        lockfile = read_text(File.join(root, "Gemfile.lock"), Limits::MAX_FILE_BYTES)
+        ruby_version = lockfile ? lockfile[RunContext::GEMFILE_LOCK_RUBY, 1] : nil
+        rails_version = lockfile ? lockfile[RunContext::GEMFILE_LOCK_RAILS, 1] : nil
+        {
+          "ruby_version" => ruby_version,
+          "target_ruby_version" => ruby_version,
+          "rails_version" => rails_version,
+          "test_framework" => detect_test_framework(root, lockfile),
+          "database_adapter" => detect_database_adapter(root, lockfile),
+          "dependencies" => parse_dependencies(lockfile),
+          "structure" => detect_structure(root)
+        }
+      end
+
+      def self.detect_test_framework(root, lockfile)
+        has_spec_dir = File.directory?(File.join(root, "spec"))
+        has_test_dir = File.directory?(File.join(root, "test"))
+        lock = lockfile.to_s
+        has_rspec = lock.include?("rspec-rails (") || lock.include?("rspec-core (")
+        has_minitest = lock.include?("minitest (")
+        if has_rspec && (has_spec_dir || lock.include?("rspec"))
+          return has_test_dir && has_minitest ? "both" : "rspec"
+        end
+        if has_test_dir
+          return "minitest"
+        end
+        if has_spec_dir
+          return "rspec"
+        end
+        "unknown"
+      end
+      private_class_method :detect_test_framework
+
+      def self.detect_database_adapter(root, lockfile)
+        db_yml = read_text(File.join(root, "config/database.yml"), Limits::DATABASE_YML_MAX_BYTES)
+        if db_yml
+          begin
+            data = StrictYaml.parse(db_yml, File.join(root, "config/database.yml"))
+            adapter = extract_adapter(data)
+            return adapter if adapter
+          rescue StandardError
+            nil
+          end
+        end
+        lock = lockfile.to_s
+        return "postgresql" if lock.include?("pg (")
+        return "mysql2" if lock.include?("mysql2 (")
+        return "sqlite3" if lock.include?("sqlite3 (")
+        return "trilogy" if lock.include?("trilogy (")
+
+        nil
+      end
+      private_class_method :detect_database_adapter
+
+      def self.extract_adapter(data)
+        return nil unless data.is_a?(Hash)
+
+        %w[development test production].each do |env|
+          section = data[env]
+          next unless section.is_a?(Hash)
+
+          adapter = section["adapter"]
+          return adapter.to_s.strip if adapter.is_a?(String) && !adapter.strip.empty?
+        end
+        default = data["default"]
+        if default.is_a?(Hash)
+          adapter = default["adapter"]
+          return adapter.to_s.strip if adapter.is_a?(String) && !adapter.strip.empty?
+        end
+        nil
+      end
+      private_class_method :extract_adapter
+
+      def self.parse_dependencies(lockfile)
+        return [] unless lockfile
+
+        gems = []
+        lockfile.each_line do |line|
+          next unless line.match?(/\A\s{4}[a-z0-9_\-]+\s+\(/)
+
+          match = line.match(/\A\s{4}([a-z0-9_\-]+)\s+\(([^)]+)\)/)
+          next unless match
+
+          gems << { "name" => match[1], "version" => match[2].strip }
+          break if gems.length >= Limits::DEPENDENCIES_MAX
+        end
+        gems
+      end
+      private_class_method :parse_dependencies
+
+      def self.detect_structure(root)
+        counts = {}
+        counts["app_models"] = count_files(root, "app/models/**/*.rb")
+        counts["app_controllers"] = count_files(root, "app/controllers/**/*.rb")
+        counts["app_jobs"] = count_files(root, "app/jobs/**/*.rb")
+        counts["app_mailers"] = count_files(root, "app/mailers/**/*.rb")
+        counts["app_helpers"] = count_files(root, "app/helpers/**/*.rb")
+        counts["app_views"] = count_files(root, "app/views/**/*")
+        counts["has_routes"] = File.file?(File.join(root, "config/routes.rb"))
+        counts["has_schema"] = File.file?(File.join(root, "db/schema.rb"))
+        counts["has_structure_sql"] = File.file?(File.join(root, "db/structure.sql"))
+        counts["has_app"] = File.directory?(File.join(root, "app"))
+        counts
+      rescue StandardError
+        {}
+      end
+      private_class_method :detect_structure
+
+      def self.count_files(root, pattern)
+        paths = Dir.glob(File.join(root, pattern))
+        paths.count { |path| File.file?(path) }
+      rescue StandardError
+        0
+      end
+      private_class_method :count_files
+
+      def self.read_text(path, max_bytes)
+        return nil unless File.file?(path)
+        return nil if File.size(path) > max_bytes rescue nil
+
+        text = File.binread(path)
+        return nil if text.bytesize > max_bytes
+
+        text.force_encoding(Encoding::UTF_8)
+        return nil unless text.valid_encoding?
+
+        text
+      rescue StandardError
+        nil
+      end
+      private_class_method :read_text
+    end
+  end
+end

data/lib/rail_verdict/rails_context/limits.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module RailVerdict
+  module RailsContext
+    module Limits
+      MAX_FILE_BYTES = 1_048_576
+      MAX_FILES = 500
+      MAX_RELATED = 20
+      MAX_SCHEMA_TABLES = 100
+      MAX_COLUMNS_PER_TABLE = 500
+      MAX_ASSOCIATIONS = 50
+      ROUTES_MAX_BYTES = 524_288
+      DATABASE_YML_MAX_BYTES = 16_384
+      DEPENDENCIES_MAX = 200
+    end
+  end
+end