woods 1.2.0 → 1.3.0

data/lib/woods/extractors/shared_dependency_scanner.rb

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 
+require 'set'
 require_relative '../model_name_cache'
+require_relative 'route_helper_resolver'
 
 module Woods
   module Extractors
@@ -28,13 +30,69 @@ module Woods
     module SharedDependencyScanner
       # Scan for ActiveRecord model references using the precomputed regex.
       #
+      # Three passes:
+      # 1. Fully-qualified names via the main `\b(?:Foo|Bar::Baz)\b` regex.
+      # 2. `.constantize` / `const_get(...)` string-literal arguments —
+      #    a `"Library::Book".constantize` used to return zero edges
+      #    because the scan ran over raw source and the regex didn't pick
+      #    up the quoted constant. Now we extract the string argument and
+      #    resolve it.
+      # 3. Bare short names (e.g. `Book` inside `module Library`)
+      #    resolved through {ModelNameCache.resolve_short_name} when
+      #    unambiguous.
+      #
       # @param source [String] Ruby source code to scan
       # @param via [Symbol] Relationship label (default: :code_reference)
       # @return [Array<Hash>] Dependency hashes with :type, :target, :via
       def scan_model_dependencies(source, via: :code_reference)
-        source.scan(ModelNameCache.model_names_regex).uniq.map do |model_name|
-          { type: :model, target: model_name, via: via }
+        targets = Set.new
+        source.scan(ModelNameCache.model_names_regex).each { |m| targets << m }
+        extract_constantize_targets(source).each { |t| targets << t }
+
+        # Short-name + constantize resolution are additive passes guarded
+        # by `respond_to?` so partial test doubles that only stub
+        # `model_names_regex` still work. Real extraction runs always
+        # have the full API.
+        if ModelNameCache.respond_to?(:short_names_regex) && ModelNameCache.respond_to?(:resolve_short_name)
+          # Strip `#` line comments before scanning so references inside
+          # YARD docstrings / TODO comments don't generate ghost edges.
+          # The negative lookahead `(?!\{)` keeps Ruby's `#{...}` string
+          # interpolation intact — stripping blindly would eat every model
+          # reference inside `"Book: #{Library::Book.new}"` etc., which
+          # is a common ERB/Phlex/string pattern.
+          scannable = source.gsub(/#(?!\{)[^\n]*/, '')
+          scannable.scan(ModelNameCache.short_names_regex).each do |short|
+            resolved = ModelNameCache.resolve_short_name(short)
+            targets << resolved if resolved
+          end
+        end
+
+        targets.map { |model_name| { type: :model, target: model_name, via: via } }
+      end
+
+      # Extract string-literal arguments passed to `.constantize` or
+      # `const_get(...)`. Matches both `"Library::Book".constantize`
+      # and `Object.const_get("Library::Book")` / `const_get("...")`.
+      # Only returns names actually present in {ModelNameCache.model_names}
+      # so non-model uses (e.g. `"String".constantize` in infra code) do
+      # not produce ghost edges.
+      #
+      # @param source [String]
+      # @return [Array<String>]
+      def extract_constantize_targets(source)
+        return [] unless ModelNameCache.respond_to?(:model_names)
+
+        known = ModelNameCache.model_names.to_set
+        return [] if known.empty?
+
+        targets = []
+        source.scan(/(["'])([A-Z][\w:]*)\1\s*\.\s*constantize\b/) do |_quote, name|
+          targets << name if known.include?(name)
+        end
+        source.scan(/const_get\s*\(\s*(["'])([A-Z][\w:]*)\1/) do |_quote, name|
+          targets << name if known.include?(name)
         end
+        targets
       end
 
       # Scan for service object references (e.g., FooService.call, FooService::new).
@@ -86,6 +144,76 @@ module Woods
         deps.concat(scan_mailer_dependencies(source))
         deps.uniq { |d| [d[:type], d[:target]] }
       end
+
+      # Match _path/_url route helpers anywhere in source.
+      # This intentionally matches all usages (assignments, string interpolation, etc.)
+      # not just link_to/redirect_to calls — any reference to a route helper indicates
+      # a dependency on that controller. False positives from non-route _path/_url
+      # suffixes (file_path, base_url, etc.) are filtered by RouteHelperResolver::IGNORED_HELPER_PREFIXES.
+      # Requires the including class to also include RouteHelperResolver
+      # and call build_route_helper_map in its initializer.
+      ROUTE_HELPER_PATTERN = /\b(\w+)_(path|url)\b/
+
+      # Match form_with/form_for with a named route helper as the action/url.
+      # Scans only within the form opening tag (up to the first `do`, `%>`, or `end`)
+      # to avoid matching unrelated _path/_url helpers that appear after the form.
+      FORM_ACTION_HELPER = /form_(with|for)\b[^%]*?(\w+)_(path|url)/
+
+      # Scan source for named route helpers and resolve them to controller targets.
+      #
+      # Gated by +Woods.configuration.extract_navigation_edges+.
+      # Requires {RouteHelperResolver} to be included and initialized.
+      #
+      # @param source [String] Ruby/ERB/HAML source code to scan
+      # @param via_type [Symbol] Relationship label (default: :link_to)
+      # @return [Array<Hash>] Dependency hashes with :type, :target, :via
+      def scan_navigation_dependencies(source, via_type: :link_to)
+        return [] unless Woods.configuration&.extract_navigation_edges
+
+        seen_helpers = Set.new
+        seen_targets = Set.new
+        deps = []
+        source.scan(ROUTE_HELPER_PATTERN).each do |route_name, suffix|
+          helper = "#{route_name}_#{suffix}"
+          next if seen_helpers.include?(helper)
+
+          seen_helpers.add(helper)
+          resolved = resolve_route_helper(helper)
+          next unless resolved
+
+          target = resolved[:controller]
+          next if seen_targets.include?(target)
+
+          seen_targets.add(target)
+          deps << { type: :controller, target: target, via: via_type }
+        end
+        deps
+      end
+
+      # Scan source for form_with/form_for calls targeting named route helpers.
+      #
+      # Gated by +Woods.configuration.extract_navigation_edges+.
+      # Requires {RouteHelperResolver} to be included and initialized.
+      #
+      # @param source [String] Template/Ruby source code
+      # @return [Array<Hash>] Dependency hashes with via: :form_action
+      def scan_form_dependencies(source)
+        return [] unless Woods.configuration&.extract_navigation_edges
+
+        seen = Set.new
+        deps = []
+        source.scan(FORM_ACTION_HELPER).each do |_, route_name, suffix|
+          resolved = resolve_route_helper("#{route_name}_#{suffix}")
+          next unless resolved
+
+          target = resolved[:controller]
+          next if seen.include?(target)
+
+          seen.add(target)
+          deps << { type: :controller, target: target, via: :form_action }
+        end
+        deps
+      end
     end
   end
 end

data/lib/woods/extractors/view_component_extractor.rb

@@ -2,6 +2,7 @@
 
 require_relative 'shared_utility_methods'
 require_relative 'shared_dependency_scanner'
+require_relative 'route_helper_resolver'
 
 module Woods
   module Extractors
@@ -26,9 +27,11 @@ module Woods
     class ViewComponentExtractor
       include SharedUtilityMethods
       include SharedDependencyScanner
+      include RouteHelperResolver
 
       def initialize
         @component_base = find_component_base
+        build_route_helper_map
       end
 
       # Extract all ViewComponent components
@@ -299,8 +302,16 @@ module Woods
           deps << { type: :stimulus_controller, target: controller, via: :html_attribute }
         end
 
-        # URL helpers
+        # Navigation edges — resolve _path / _url helpers to real controllers
+        # via RouteHelperResolver (wired through the include + build_route_helper_map
+        # call in #initialize). Replaces the older unresolved-route emission.
+        deps.concat(scan_navigation_dependencies(source))
+        deps.concat(scan_form_dependencies(source))
+        # Keep the raw-helper fallback for helpers that don't resolve (e.g.,
+        # engine-mounted routes outside the main routes table).
         source.scan(/(\w+)_(?:path|url)/).flatten.uniq.each do |route|
+          next if route.match?(/\A(file|base|asset|image|javascript|stylesheet|font|video|audio)\z/)
+
           deps << { type: :route, target: route, via: :url_helper }
         end
 

data/lib/woods/extractors/view_engines/base.rb

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+
+module Woods
+  module Extractors
+    module ViewEngines
+      # Abstract base class documenting the TemplateEngine contract that
+      # {ViewTemplateExtractor} dispatches to.
+      #
+      # Concrete engines (e.g. {Erb}, and future HAML / Slim / Turbo
+      # implementations) subclass Base and override the abstract methods.
+      # The orchestrator consults the engine collection via
+      # {ViewTemplateExtractor::ENGINES}, finds the first engine whose
+      # {#handles?} returns true for a file, and delegates scanning and
+      # partial-identifier resolution to that engine.
+      #
+      # {#parse} is an optional per-engine memoization seam: engines whose
+      # parse step is expensive (e.g. HAML / Slim compiling through
+      # Temple) can override it to return an internal IR and call it once
+      # before the three scan operations. ERB and Turbo Streams, whose
+      # scanners regex raw source, leave the identity default in place.
+      # The orchestrator does not invoke {#parse} — engines opt in
+      # internally when it pays off.
+      #
+      # @abstract Subclass and override the abstract methods ({#name},
+      #   {#extensions}, {#scan_partials}, {#scan_instance_variables},
+      #   {#scan_helpers}, {#resolve_partial_identifier}).
+      class Base
+        # Stable engine identifier surfaced through
+        # {ViewTemplateExtractor.supported_template_engines} and the MCP
+        # `structure` tool.
+        #
+        # @return [Symbol]
+        def name
+          raise NotImplementedError, "#{self.class.name} must implement #name"
+        end
+
+        # File extensions this engine handles, each including the leading
+        # dot (e.g. `.html.erb`).
+        #
+        # @return [Array<String>]
+        def extensions
+          raise NotImplementedError, "#{self.class.name} must implement #extensions"
+        end
+
+        # Whether this engine handles the given file path. The default
+        # implementation suffix-matches against {#extensions}; engines
+        # with more elaborate discrimination (e.g. looking at file
+        # content) can override.
+        #
+        # @param file_path [String]
+        # @return [Boolean]
+        def handles?(file_path)
+          extensions.any? { |ext| file_path.end_with?(ext) }
+        end
+
+        # Optional memoization hook for engines whose parse step is
+        # expensive. Default is identity — returns the source string
+        # unchanged — so engines that scan raw source (ERB, Turbo
+        # Streams) pay no overhead. HAML/Slim implementations can
+        # override to compile once and cache an internal IR, then call
+        # {#parse} inside their own {#scan_partials} /
+        # {#scan_instance_variables} / {#scan_helpers}.
+        #
+        # The orchestrator does not invoke this method; it is a
+        # convention for engine-internal reuse.
+        #
+        # @param source [String] Template source code
+        # @return [Object] An engine-private IR, or the source itself
+        def parse(source)
+          source
+        end
+
+        # Partial names referenced by render calls in the given source.
+        # Returns the raw partial names as they appear in render calls
+        # (e.g. `'comments/comment'`, `'sidebar'`, `'header'`); the
+        # orchestrator calls {#resolve_partial_identifier} per entry to
+        # translate each into a canonical file identifier.
+        #
+        # @param source [String] Template source code
+        # @return [Array<String>]
+        def scan_partials(_source)
+          raise NotImplementedError, "#{self.class.name} must implement #scan_partials"
+        end
+
+        # Instance-variable names referenced in the template source,
+        # returned sorted and deduplicated (including the leading `@`).
+        #
+        # @param source [String] Template source code
+        # @return [Array<String>]
+        def scan_instance_variables(_source)
+          raise NotImplementedError, "#{self.class.name} must implement #scan_instance_variables"
+        end
+
+        # Helper method names detected in the template source, returned
+        # sorted. The set of "helpers" is engine-defined — ERB scans for
+        # the common Rails view-helper vocabulary, HAML/Slim would scan
+        # the same vocabulary in their own syntaxes.
+        #
+        # @param source [String] Template source code
+        # @return [Array<String>]
+        def scan_helpers(_source)
+          raise NotImplementedError, "#{self.class.name} must implement #scan_helpers"
+        end
+
+        # Resolve a partial name (as it appeared in a render call) to the
+        # file identifier of the partial template. Engines own this
+        # because the filename convention is engine-specific: ERB looks
+        # for `_foo.html.erb`, HAML for `_foo.html.haml`, etc.
+        #
+        # @param partial_name [String] The partial name from the render call
+        # @param current_identifier [String] Identifier of the template
+        #   issuing the render, used to anchor relative partial names
+        # @return [String]
+        def resolve_partial_identifier(_partial_name, _current_identifier)
+          raise NotImplementedError,
+                "#{self.class.name} must implement #resolve_partial_identifier"
+        end
+
+        # Route-helper references found in the template source. Each
+        # candidate is a hash shaped `{ helper: 'posts_path', via: Symbol }`
+        # where `via` is typically `:link_to` or `:form_action`. The
+        # orchestrator resolves each candidate's `helper` to a controller
+        # target via {RouteHelperResolver} — engines do NOT need to know
+        # about Rails route state, they only surface raw helper calls
+        # from the source in whatever way their syntax requires.
+        #
+        # Engines matter here because form-call syntax differs across
+        # engines (e.g. ERB's `<%= form_with ... %>` vs. HAML's
+        # `= form_with ...`); returning candidates rather than resolved
+        # edges keeps Rails-coupled logic off the engine.
+        #
+        # @param source [String] Template source code
+        # @return [Array<Hash>]
+        def scan_navigation_candidates(_source)
+          raise NotImplementedError,
+                "#{self.class.name} must implement #scan_navigation_candidates"
+        end
+      end
+    end
+  end
+end

data/lib/woods/extractors/view_engines/erb.rb

@@ -0,0 +1,145 @@
+# frozen_string_literal: true
+
+require 'set'
+require_relative 'base'
+
+module Woods
+  module Extractors
+    module ViewEngines
+      # ERB implementation of the {Base} template-engine contract. Owns
+      # the ERB-specific parsing surface that {ViewTemplateExtractor}
+      # delegates to — extension list, partial filename convention, and
+      # the three scan operations (partials, instance variables, helper
+      # calls).
+      class Erb < Base
+        # File extensions this engine handles.
+        EXTENSIONS = %w[.html.erb .erb].freeze
+
+        # Stable engine identifier — see Base#name.
+        ENGINE_NAME = :erb
+
+        # Matches named route helpers (e.g. `posts_path`, `user_url`) in
+        # template source. Identical shape across ERB / plain Ruby, so
+        # shared with {SharedDependencyScanner}.
+        ROUTE_HELPER_PATTERN = /\b(\w+)_(path|url)\b/
+
+        # Matches form_with / form_for calls whose action is a named
+        # route helper. ERB-flavored (`[^%]*?` stops at the next `%`
+        # which appears at ERB tag terminators and HAML tag starts) —
+        # when HAML/Slim land they will define their own form pattern.
+        FORM_ACTION_HELPER = /form_(with|for)\b[^%]*?(\w+)_(path|url)/
+
+        # Common Rails view helper methods to detect in template source.
+        COMMON_HELPERS = %w[
+          link_to
+          button_to
+          form_for
+          form_with
+          form_tag
+          image_tag
+          stylesheet_link_tag
+          javascript_include_tag
+          content_for
+          yield
+          render
+          redirect_to
+          truncate
+          pluralize
+          number_to_currency
+          number_to_percentage
+          number_with_delimiter
+          time_ago_in_words
+          distance_of_time_in_words
+          simple_format
+          sanitize
+          raw
+          safe_join
+          content_tag
+          tag
+          mail_to
+          url_for
+          asset_path
+          asset_url
+        ].freeze
+
+        # @see Base#name
+        def name
+          ENGINE_NAME
+        end
+
+        # @see Base#extensions
+        def extensions
+          EXTENSIONS
+        end
+
+        # Matches:
+        # - `render partial: 'foo/bar'`
+        # - `render 'foo/bar'`
+        # - `render :foo`
+        #
+        # @see Base#scan_partials
+        def scan_partials(source)
+          partials = Set.new
+
+          source.scan(/render\s+partial:\s*['"]([^'"]+)['"]/).each do |match|
+            partials << match[0]
+          end
+
+          source.scan(/render\s+['"]([^'"]+)['"]/).each do |match|
+            partials << match[0]
+          end
+
+          source.scan(/render\s+:(\w+)/).each do |match|
+            partials << match[0]
+          end
+
+          partials.to_a
+        end
+
+        # @see Base#scan_instance_variables
+        def scan_instance_variables(source)
+          source.scan(/@[a-zA-Z_]\w*/).uniq.sort
+        end
+
+        # @see Base#scan_helpers
+        def scan_helpers(source)
+          found = Set.new
+          COMMON_HELPERS.each do |helper|
+            found << helper if source.match?(/\b#{Regexp.escape(helper)}\b/)
+          end
+          found.to_a.sort
+        end
+
+        # Given `render 'comments/comment'` from a template at
+        # `posts/show.html.erb`, resolves to `comments/_comment.html.erb`.
+        #
+        # @see Base#resolve_partial_identifier
+        def resolve_partial_identifier(partial_name, current_identifier)
+          if partial_name.include?('/')
+            dir = File.dirname(partial_name)
+            base = File.basename(partial_name)
+            "#{dir}/_#{base}.html.erb"
+          else
+            dir = File.dirname(current_identifier)
+            if dir == '.'
+              "_#{partial_name}.html.erb"
+            else
+              "#{dir}/_#{partial_name}.html.erb"
+            end
+          end
+        end
+
+        # @see Base#scan_navigation_candidates
+        def scan_navigation_candidates(source)
+          link_to_candidates = source.scan(ROUTE_HELPER_PATTERN).map do |route_name, suffix|
+            { helper: "#{route_name}_#{suffix}", via: :link_to }
+          end
+          form_candidates = source.scan(FORM_ACTION_HELPER).map do |_form_kind, route_name, suffix|
+            { helper: "#{route_name}_#{suffix}", via: :form_action }
+          end
+          link_to_candidates + form_candidates
+        end
+      end
+    end
+  end
+end