route_guard 0.1.0

data/lib/route_guard/route_loader.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+require_relative "models/route"
+require_relative "route_tracker"
+
+module RouteGuard
+  class RouteLoader
+    def self.load
+      load_environment!
+
+      RouteTracker.reset!
+      RouteTracker.enable_tracking!
+      RouteTracker.enabled = true
+
+      begin
+        $stderr.puts "RouteGuard Debug: defined?(Rails) = #{defined?(Rails)}"
+        if defined?(Rails)
+          $stderr.puts "RouteGuard Debug: Rails.respond_to?(:application) = #{Rails.respond_to?(:application)}"
+          if Rails.respond_to?(:application) && Rails.application
+            $stderr.puts "RouteGuard Debug: Rails.application = #{Rails.application.class.name}"
+            $stderr.puts "RouteGuard Debug: Routes size before reload = #{Rails.application.routes.routes.size}"
+            Rails.application.reload_routes!
+            $stderr.puts "RouteGuard Debug: Routes size after reload = #{Rails.application.routes.routes.size}"
+          else
+            $stderr.puts "RouteGuard Debug: Rails.application = nil/undefined"
+          end
+        end
+
+        if defined?(Rails) && Rails.respond_to?(:application) && Rails.application
+          load_from_route_set(Rails.application.routes)
+        else
+          []
+        end
+      ensure
+        RouteTracker.enabled = false
+      end
+    end
+
+    def self.load_environment!
+      return if defined?(Rails) && Rails.respond_to?(:application) && Rails.application
+
+      env_file = File.expand_path("config/environment.rb", Dir.pwd)
+      if File.exist?(env_file)
+        original_stdout = $stdout.clone
+        original_stderr = $stderr.clone
+        begin
+          $stdout.reopen(File::NULL, "w")
+          $stderr.reopen(File::NULL, "w")
+          require env_file
+        ensure
+          $stdout.reopen(original_stdout)
+          $stderr.reopen(original_stderr)
+        end
+      end
+    end
+
+    def self.load_from_route_set(route_set)
+      routes = []
+      route_set.routes.each do |r|
+        # Skip internal rails routes if the route itself responds to internal?
+        next if r.respond_to?(:internal?) && r.internal?
+
+        # Extract verb
+        verb = if r.verb.is_a?(Regexp)
+                 r.verb.source.gsub(/[^A-Z|]/, "")
+               else
+                 r.verb.to_s.upcase
+               end
+        verb = "ANY" if verb.empty?
+
+        # Extract path
+        original_path = if r.respond_to?(:path) && r.path.respond_to?(:spec)
+                          r.path.spec.to_s
+                        else
+                          r.path.to_s
+                        end
+
+        path = original_path.gsub(/\(\.\:format\)\z/, "").gsub(/\(\/:format\)\z/, "")
+
+        defaults = r.defaults || {}
+        controller = defaults[:controller]
+        action = defaults[:action]
+        name = r.name
+        constraints = r.requirements || {}
+
+        trace_info = RouteTracker.route_traces[r.object_id] || r.instance_variable_get(:@route_guard_trace)
+        file = trace_info&.[](:file)
+        line = trace_info&.[](:line)
+
+        route = Models::Route.new(
+          verb: verb,
+          path: path,
+          original_path: original_path,
+          controller: controller,
+          action: action,
+          name: name,
+          constraints: constraints,
+          file: file,
+          line: line,
+          defaults: defaults
+        )
+
+        next if route.internal?
+
+        routes << route
+      end
+      routes
+    end
+  end
+end

data/lib/route_guard/route_tracker.rb

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+
+module RouteGuard
+  module RouteTracker
+    class << self
+      attr_accessor :enabled
+
+      def route_traces
+        @route_traces ||= {}
+      end
+
+      def resource_calls
+        @resource_calls ||= []
+      end
+
+      def reset!
+        @route_traces = {}
+        @resource_calls = []
+      end
+
+      def track_route(route_object_id, trace_info)
+        return unless @enabled
+        route_traces[route_object_id] = trace_info
+      end
+
+      def track_resource(type, args, scope, trace_info)
+        return unless @enabled
+        resource_calls << {
+          type: type,
+          args: args,
+          scope: scope,
+          trace: trace_info
+        }
+      end
+
+      def enable_tracking!
+        return if @prepended
+
+        if defined?(ActionDispatch::Routing::RouteSet)
+          ActionDispatch::Routing::RouteSet.prepend(RouteGuard::RouteSetExtension)
+        end
+
+        if defined?(ActionDispatch::Routing::Mapper)
+          ActionDispatch::Routing::Mapper.prepend(RouteGuard::MapperExtension)
+        end
+
+        if defined?(ActionDispatch::Routing::RouteSet::NamedRouteCollection)
+          ActionDispatch::Routing::RouteSet::NamedRouteCollection.prepend(RouteGuard::NamedRouteCollectionExtension)
+        end
+
+        @prepended = true
+      end
+
+      def find_routes_caller(locations)
+        return nil unless locations
+        loc = locations.find do |l|
+          path = l.path
+          path.include?("config/routes") ||
+            path.include?("/routes.rb") ||
+            (defined?(RSpec) && path.include?("_spec.rb"))
+        end
+
+        if loc
+          { file: loc.path, line: loc.lineno }
+        end
+      end
+    end
+  end
+
+  module RouteSetExtension
+    def add_route(*args)
+      route = super
+      if RouteGuard::RouteTracker.enabled
+        trace_info = RouteGuard::RouteTracker.find_routes_caller(caller_locations(1, 25))
+        if trace_info
+          if route.is_a?(Array)
+            route.each do |r|
+              RouteGuard::RouteTracker.track_route(r.object_id, trace_info)
+              r.instance_variable_set(:@route_guard_trace, trace_info)
+            end
+          elsif route
+            RouteGuard::RouteTracker.track_route(route.object_id, trace_info)
+            route.instance_variable_set(:@route_guard_trace, trace_info)
+          end
+        end
+      end
+      route
+    end
+  end
+
+  module MapperExtension
+    def resources(*args, &block)
+      if RouteGuard::RouteTracker.enabled
+        trace_info = RouteGuard::RouteTracker.find_routes_caller(caller_locations(1, 25))
+        if trace_info
+          RouteGuard::RouteTracker.track_resource(:resources, args, scope_info, trace_info)
+        end
+      end
+      super
+    end
+
+    def resource(*args, &block)
+      if RouteGuard::RouteTracker.enabled
+        trace_info = RouteGuard::RouteTracker.find_routes_caller(caller_locations(1, 25))
+        if trace_info
+          RouteGuard::RouteTracker.track_resource(:resource, args, scope_info, trace_info)
+        end
+      end
+      super
+    end
+
+    private
+
+    def scope_info
+      return {} unless defined?(@scope) && @scope
+      {
+        path: @scope[:path],
+        module: @scope[:module],
+        as: @scope[:as]
+      }
+    end
+  end
+
+  module NamedRouteCollectionExtension
+    def [](name)
+      if RouteGuard::RouteTracker.enabled
+        nil
+      else
+        super
+      end
+    end
+
+    def key?(name)
+      if RouteGuard::RouteTracker.enabled
+        false
+      else
+        super
+      end
+    end
+  end
+end

data/lib/route_guard/rules/base.rb

@@ -0,0 +1,163 @@
+# frozen_string_literal: true
+
+module RouteGuard
+  module Rules
+    class Base
+      attr_reader :options
+
+      def initialize(options = {})
+        @options = options
+      end
+
+      def analyze(routes, report)
+        raise NotImplementedError, "#{self.class} must implement #analyze(routes, report)"
+      end
+
+      # Expands optional path segments in route paths
+      # e.g., "/users(.:format)" -> ["/users", "/users.:format"]
+      # "/posts(/:year(/:month))" -> ["/posts", "/posts/:year", "/posts/:year/:month"]
+      def expand_path(path)
+        start_idx = path.index("(")
+        return [path] unless start_idx
+
+        # Find matching ')' at top level
+        depth = 0
+        end_idx = nil
+        path.chars.each_with_index do |char, idx|
+          if char == "("
+            depth += 1
+          elsif char == ")"
+            depth -= 1
+            if depth == 0
+              end_idx = idx
+              break
+            end
+          end
+        end
+
+        raise "Unmatched parenthesis in path: #{path}" unless end_idx
+
+        before = path[0...start_idx]
+        inside = path[(start_idx + 1)...end_idx]
+        after = path[(end_idx + 1)..-1]
+
+        inside_expansions = expand_path(inside)
+        after_expansions = expand_path(after)
+
+        results = []
+        # Case 1: Omit the inside group
+        after_expansions.each do |after_exp|
+          results << (before + after_exp)
+        end
+        # Case 2: Include the inside group
+        inside_expansions.each do |inside_exp|
+          after_expansions.each do |after_exp|
+            results << (before + inside_exp + after_exp)
+          end
+        end
+
+        results.uniq
+      end
+
+      # Splits a path string into segment tokens, handling dots and slashes
+      def split_segments(path)
+        segments = []
+        path.split("/").each do |seg|
+          if seg.include?(".")
+            parts = seg.split(".")
+            segments << parts.first
+            parts[1..-1].each { |p| segments << ".#{p}" }
+          else
+            segments << seg
+          end
+        end
+        segments
+      end
+
+      # Checks if verbA matches verbB (handling ANY/wildcard)
+      def verb_matches?(verbA, verbB)
+        return true if verbA == "ANY" || verbB == "ANY"
+
+        verbsA = verbA.split("|")
+        verbsB = verbB.split("|")
+        (verbsA & verbsB).any?
+      end
+
+      # Checks if Route A matches (shadows) Route B's path representation.
+      def path_shadows?(segA, segB, constraintsA, constraintsB)
+        idxA = 0
+        idxB = 0
+
+        while idxA < segA.length && idxB < segB.length
+          sA = segA[idxA]
+          sB = segB[idxB]
+
+          if sA.start_with?("*")
+            return true
+          end
+
+          if sB.start_with?("*")
+            return false
+          end
+
+          if sA.start_with?(":")
+            param_A = sA[1..-1]
+            constA = constraintsA[param_A.to_sym]
+
+            if sB.start_with?(":")
+              param_B = sB[1..-1]
+              constB = constraintsB[param_B.to_sym]
+
+              if constA
+                if constB
+                  match = if constA.is_a?(Regexp)
+                            if constB.is_a?(Regexp)
+                              constB.source == constA.source || constA.match?(constB.source)
+                            else
+                              constA.match?(constB.to_s)
+                            end
+                          else
+                            if constB.is_a?(Regexp)
+                              constB.match?(constA.to_s)
+                            else
+                              constA.to_s == constB.to_s
+                            end
+                          end
+                  return false unless match
+                else
+                  return false
+                end
+              end
+            else
+              # sB is literal
+              if constA
+                match = if constA.is_a?(Regexp)
+                          constA.match?(sB)
+                        else
+                          constA.to_s == sB
+                        end
+                return false unless match
+              end
+            end
+          else
+            # sA is literal
+            if sB.start_with?(":")
+              return false
+            else
+              return false if sA != sB
+            end
+          end
+
+          idxA += 1
+          idxB += 1
+        end
+
+        if idxA == segA.length && idxB == segB.length
+          true
+        else
+          false
+        end
+      end
+    end
+  end
+end

data/lib/route_guard/rules/complexity.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module RouteGuard
+  module Rules
+    class Complexity < Base
+      def analyze(routes, report)
+        score = 100
+
+        # 1. Penalties based on issues present in the report
+        issues = report.issues || []
+        
+        duplicate_count = issues.count { |i| i.rule_name == :duplicate_routes }
+        shadowed_count = issues.count { |i| i.rule_name == :shadowed_routes }
+        unreachable_count = issues.count { |i| i.rule_name == :unreachable_routes }
+        helper_count = issues.count { |i| i.rule_name == :duplicate_helpers }
+        resource_count = issues.count { |i| i.rule_name == :duplicate_resources }
+
+        score -= duplicate_count * 10
+        score -= shadowed_count * 15
+        score -= unreachable_count * 20
+        score -= helper_count * 5
+        score -= resource_count * 5
+
+        # 2. Nesting depth penalties
+        stats = report.stats || {}
+        max_depth = stats[:maximum_nesting_depth] || 0
+        avg_depth = stats[:average_nesting_depth] || 0.0
+
+        if max_depth > 3
+          score -= (max_depth - 3) * 5
+        end
+
+        if avg_depth > 2.0
+          score -= ((avg_depth - 2.0) * 10).round
+        end
+
+        # 3. Wildcard usage penalty
+        wildcards = stats[:wildcards] || 0
+        score -= wildcards * 2
+
+        # Clamp score between 0 and 100
+        score = [0, [score, 100].min].max
+        report.complexity_score = score
+
+        # Return a warning if the score is critically low (< 70) and verbose is enabled
+        issues_to_return = []
+        if score < 70
+          issues_to_return << Models::Issue.new(
+            rule_name: :complexity,
+            severity: :warning,
+            message: "Route Complexity: Overall route health is low (#{score}/100). Consider refactoring nested resources or namespaces.",
+            route: nil
+          )
+        end
+
+        issues_to_return
+      end
+    end
+  end
+end

data/lib/route_guard/rules/duplicate_helpers.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require_relative "base"
+require_relative "../models/issue"
+
+module RouteGuard
+  module Rules
+    class DuplicateHelpers < Base
+      def analyze(routes, report)
+        issues = []
+
+        groups = Hash.new { |h, k| h[k] = [] }
+        routes.each do |route|
+          next if route.name.nil? || route.name.empty?
+
+          groups[route.name] << route
+        end
+
+        groups.each do |name, grp_routes|
+          paths = grp_routes.map(&:path).uniq
+          next if paths.length <= 1
+
+          primary = grp_routes.first
+          conflicts = grp_routes[1..-1]
+
+          conflicts.each do |conflict|
+            next if conflict.path == primary.path
+
+            issues << Models::Issue.new(
+              rule_name: :duplicate_helpers,
+              severity: :error,
+              message: "Duplicate Named Helper: Helper '#{name}_path' is defined for both '#{primary.path}' and '#{conflict.path}'.",
+              route: conflict,
+              related_routes: [primary]
+            )
+          end
+        end
+
+        issues
+      end
+    end
+  end
+end

data/lib/route_guard/rules/duplicate_resources.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require_relative "base"
+require_relative "../models/issue"
+require_relative "../route_tracker"
+
+module RouteGuard
+  module Rules
+    class DuplicateResources < Base
+      def analyze(routes, report)
+        issues = []
+        calls = RouteTracker.resource_calls
+        return issues if calls.empty?
+
+        groups = Hash.new { |h, k| h[k] = [] }
+
+        calls.each do |call|
+          resource_names = call[:args].take_while { |a| a.is_a?(Symbol) || a.is_a?(String) }
+          scope_path = call[:scope][:path]
+          scope_module = call[:scope][:module]
+
+          resource_names.each do |name|
+            key = [scope_path, scope_module, name.to_sym]
+            groups[key] << call
+          end
+        end
+
+        groups.each do |(scope_path, scope_module, name), grp_calls|
+          next if grp_calls.length <= 1
+
+          primary = grp_calls.first
+          duplicates = grp_calls[1..-1]
+
+          scope_desc = [
+            scope_module ? "module #{scope_module}" : nil,
+            scope_path ? "path '#{scope_path}'" : nil
+          ].compact.join(", ")
+          scope_text = scope_desc.empty? ? "root scope" : "scope [#{scope_desc}]"
+
+          duplicates.each do |dup|
+            issues << Models::Issue.new(
+              rule_name: :duplicate_resources,
+              severity: :warning,
+              message: "Duplicate Resource: Resource ':#{name}' is declared multiple times in #{scope_text}.",
+              route: nil,
+              file: dup[:trace][:file],
+              line: dup[:trace][:line]
+            )
+          end
+        end
+
+        issues
+      end
+    end
+  end
+end

data/lib/route_guard/rules/duplicate_routes.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require_relative "base"
+require_relative "../models/issue"
+
+module RouteGuard
+  module Rules
+    class DuplicateRoutes < Base
+      def analyze(routes, report)
+        issues = []
+
+        groups = Hash.new { |h, k| h[k] = [] }
+        routes.each do |route|
+          route.verb.split("|").each do |v|
+            groups[[v, route.path]] << route
+          end
+        end
+
+        groups.each do |(verb, path), grp_routes|
+          next if grp_routes.length <= 1
+
+          primary = grp_routes.first
+          duplicates = grp_routes[1..-1]
+
+          duplicates.each do |dup|
+            issues << Models::Issue.new(
+              rule_name: :duplicate_routes,
+              severity: :error,
+              message: "Duplicate Route: #{verb} #{path} matches a route defined earlier.",
+              route: dup,
+              related_routes: [primary]
+            )
+          end
+        end
+
+        issues
+      end
+    end
+  end
+end

data/lib/route_guard/rules/shadowed_routes.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require_relative "base"
+require_relative "../models/issue"
+
+module RouteGuard
+  module Rules
+    class ShadowedRoutes < Base
+      def analyze(routes, report)
+        issues = []
+        return issues if routes.empty?
+
+        # Cache segment info and path expansions for all routes
+        route_info = routes.map do |r|
+          segs = split_segments(r.path)
+          {
+            route: r,
+            segs: segs,
+            first: segs[1],
+            is_catch_all: catch_all_wildcard?(r),
+            expansions: (expand_path(r.original_path).map { |p| split_segments(p) } rescue [[r.path]])
+          }
+        end
+
+        route_info.each_with_index do |info_b, idx|
+          next if info_b[:is_catch_all]
+          route_b = info_b[:route]
+          first_b = info_b[:first]
+
+          route_info[0...idx].each do |info_a|
+            next if info_a[:is_catch_all]
+            first_a = info_a[:first]
+
+            # Optimization: Skip comparisons if first literal segment doesn't match
+            if first_a && first_b && !first_a.start_with?(":") && !first_a.start_with?("*")
+              next if first_a != first_b
+            end
+
+            route_a = info_a[:route]
+            next unless verb_matches?(route_a.verb, route_b.verb)
+
+            if shadows_cached?(info_a, info_b)
+              issues << Models::Issue.new(
+                rule_name: :shadowed_routes,
+                severity: :warning,
+                message: "Shadowed Route: #{route_b} is shadowed by #{route_a} defined earlier.",
+                route: route_b,
+                related_routes: [route_a]
+              )
+              break
+            end
+          end
+        end
+
+        issues
+      end
+
+      private
+
+      def catch_all_wildcard?(route)
+        path = route.path
+        path == "/*path" || path == "*path" || path.match?(/\A\/?\*[a-zA-Z_]+\z/)
+      end
+
+      def shadows_cached?(info_a, info_b)
+        route_a = info_a[:route]
+        route_b = info_b[:route]
+        return false if route_a.path == route_b.path
+
+        info_b[:expansions].all? do |seg_b|
+          info_a[:expansions].any? do |seg_a|
+            path_shadows?(seg_a, seg_b, route_a.constraints, route_b.constraints)
+          end
+        end
+      end
+    end
+  end
+end