woods 1.1.0 → 1.3.0

data/lib/woods/extractors/view_template_extractor.rb

@@ -1,16 +1,25 @@
 # frozen_string_literal: true
 
+require 'set'
+require_relative 'route_helper_resolver'
+require_relative 'view_engines/base'
+require_relative 'view_engines/erb'
+
 module Woods
   module Extractors
-    # ViewTemplateExtractor handles ERB view template extraction.
+    # ViewTemplateExtractor orchestrates view-template extraction across
+    # per-engine implementations under {ViewEngines}.
     #
-    # Scans `app/views/` for `.html.erb` and `.erb` files and produces
-    # one ExtractedUnit per template. Extracts render calls (partials),
-    # instance variables, and helper method usage. Links partials via
-    # dependencies and infers the owning controller from directory structure.
+    # For each configured view directory the orchestrator walks every
+    # extension any registered engine handles, finds the first engine
+    # whose {ViewEngines::Base#handles?} returns true for a given file,
+    # and delegates parsing, scanning, and partial-identifier resolution
+    # to that engine. The orchestrator itself owns filesystem walking,
+    # identifier construction, controller inference, route-helper edge
+    # resolution, and dependency assembly.
     #
-    # This is an ERB-only MVP — HAML, Slim, and layout inheritance
-    # are not yet supported.
+    # Engines are registered via {ENGINES}. Add a new engine by creating
+    # a {ViewEngines::Base} subclass and appending it to that list.
     #
     # @example
     #   extractor = ViewTemplateExtractor.new
@@ -18,67 +27,55 @@ module Woods
     #   index = units.find { |u| u.identifier == "users/index.html.erb" }
     #
     class ViewTemplateExtractor
-      # Directories to scan for view templates
+      include RouteHelperResolver
+
+      # Directories to scan for view templates.
       VIEW_DIRECTORIES = %w[
         app/views
       ].freeze
 
-      # Common Rails view helper methods to detect
-      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
+      # Registered view-template engines, in precedence order. The first
+      # engine whose {ViewEngines::Base#handles?} returns true for a file
+      # wins — place more specific engines before more general ones if
+      # overlap is ever introduced.
+      ENGINES = [ViewEngines::Erb].freeze
+
+      # Template engine names the extraction pipeline currently
+      # understands — aggregated from {ENGINES} so the list stays honest
+      # as engines are added or removed. Surfaced through the MCP
+      # `structure` tool.
+      #
+      # @return [Array<Symbol>]
+      def self.supported_template_engines
+        ENGINES.map { |klass| klass.new.name }.uniq.freeze
+      end
 
       def initialize
         @directories = VIEW_DIRECTORIES.map { |d| Rails.root.join(d) }
                                        .select(&:directory?)
+        @engines = self.class::ENGINES.map(&:new)
+        build_route_helper_map
       end
 
-      # Extract all ERB view templates
+      # Extract all view templates across the registered engines.
       #
       # @return [Array<ExtractedUnit>] List of view template units
       def extract_all
+        extensions = @engines.flat_map(&:extensions).uniq
         @directories.flat_map do |dir|
-          erb_files = Dir[dir.join('**/*.html.erb')] + Dir[dir.join('**/*.erb')]
-          erb_files.uniq.filter_map do |file|
-            extract_view_template_file(file)
-          end
+          files = extensions.flat_map { |ext| Dir[dir.join("**/*#{ext}")] }
+          files.uniq.filter_map { |file| extract_view_template_file(file) }
         end
       end
 
-      # Extract a single view template file
+      # Extract a single view template file.
       #
-      # @param file_path [String] Path to the ERB template file
-      # @return [ExtractedUnit, nil] The extracted unit or nil if not ERB
+      # @param file_path [String] Path to the template file
+      # @return [ExtractedUnit, nil] The extracted unit, or nil if no
+      #   registered engine handles the file
       def extract_view_template_file(file_path)
-        return nil unless file_path.end_with?('.erb')
+        engine = engine_for(file_path)
+        return nil unless engine
 
         source = File.read(file_path)
         identifier = build_identifier(file_path)
@@ -92,8 +89,9 @@ module Woods
 
         unit.namespace = namespace
         unit.source_code = source
-        unit.metadata = build_metadata(source, file_path)
-        unit.dependencies = build_dependencies(source, file_path, identifier)
+        partials = engine.scan_partials(source)
+        unit.metadata = build_metadata(engine, source, file_path, partials)
+        unit.dependencies = build_dependencies(engine, source, file_path, identifier, partials)
 
         unit
       rescue StandardError => e
@@ -103,6 +101,14 @@ module Woods
 
       private
 
+      # Find the registered engine that handles the given file, if any.
+      #
+      # @param file_path [String]
+      # @return [ViewEngines::Base, nil]
+      def engine_for(file_path)
+        @engines.find { |e| e.handles?(file_path) }
+      end
+
       # Build a readable identifier from the file path.
       #
       # @param file_path [String] Absolute path to the template
@@ -124,16 +130,18 @@ module Woods
 
       # Build metadata hash for the template.
       #
+      # @param engine [ViewEngines::Base] Engine that matched this file
       # @param source [String] Template source code
       # @param file_path [String] Path to the template
+      # @param partials [Array<String>] Pre-extracted partial names
       # @return [Hash]
-      def build_metadata(source, file_path)
+      def build_metadata(engine, source, file_path, partials)
         {
-          template_engine: 'erb',
+          template_engine: engine.name.to_s,
           is_partial: partial?(file_path),
-          partials_rendered: extract_rendered_partials(source),
-          instance_variables: extract_instance_variables(source),
-          helpers_called: extract_helpers(source),
+          partials_rendered: partials,
+          instance_variables: engine.scan_instance_variables(source),
+          helpers_called: engine.scan_helpers(source),
           loc: source.lines.count { |l| l.strip.length.positive? }
         }
       end
@@ -146,98 +154,51 @@ module Woods
         File.basename(file_path).start_with?('_')
       end
 
-      # Extract partial names from render calls.
-      #
-      # Matches:
-      # - render partial: 'foo/bar'
-      # - render 'foo/bar'
-      # - render :foo
-      #
-      # @param source [String] Template source code
-      # @return [Array<String>] Partial names
-      def extract_rendered_partials(source)
-        partials = Set.new
-
-        # render partial: 'path/to/partial'
-        source.scan(/render\s+partial:\s*['"]([^'"]+)['"]/).each do |match|
-          partials << match[0]
-        end
-
-        # render 'path/to/partial' (string without keyword)
-        source.scan(/render\s+['"]([^'"]+)['"]/).each do |match|
-          partials << match[0]
-        end
-
-        # render :symbol
-        source.scan(/render\s+:(\w+)/).each do |match|
-          partials << match[0]
-        end
-
-        partials.to_a
-      end
-
-      # Extract instance variables used in the template.
-      #
-      # @param source [String] Template source code
-      # @return [Array<String>] Instance variable names
-      def extract_instance_variables(source)
-        source.scan(/@[a-zA-Z_]\w*/).uniq.sort
-      end
-
-      # Extract common Rails helper calls from the template.
-      #
-      # @param source [String] Template source code
-      # @return [Array<String>] Helper method names
-      def extract_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
-
       # Build dependencies for the template.
       #
+      # @param engine [ViewEngines::Base] Engine that matched this file
       # @param source [String] Template source code
       # @param file_path [String] Path to the template
       # @param identifier [String] Template identifier
+      # @param partials [Array<String>] Pre-extracted partial names
       # @return [Array<Hash>]
-      def build_dependencies(source, file_path, identifier)
+      def build_dependencies(engine, source, file_path, identifier, partials)
         deps = []
 
-        # Rendered partials
-        extract_rendered_partials(source).each do |partial_name|
-          partial_identifier = resolve_partial_identifier(partial_name, identifier)
+        partials.each do |partial_name|
+          partial_identifier = engine.resolve_partial_identifier(partial_name, identifier)
           deps << { type: :view_template, target: partial_identifier, via: :render }
         end
 
-        # Inferred controller
         controller = infer_controller(file_path)
         deps << { type: :controller, target: controller, via: :view_render } if controller
 
-        deps
+        deps.concat(resolve_navigation_candidates(engine, source))
+
+        deps.uniq { |d| [d[:type], d[:target], d[:via]] }
       end
 
-      # Resolve a partial name to its file identifier.
+      # Ask the engine for route-helper candidates and resolve each to a
+      # controller target via {RouteHelperResolver}. Gated by
+      # +Woods.configuration.extract_navigation_edges+ so the config
+      # toggle still applies.
       #
-      # Given a render call like `render 'comments/comment'`, resolves to
-      # `comments/_comment.html.erb`.
-      #
-      # @param partial_name [String] The partial name from the render call
-      # @param current_identifier [String] The current template's identifier
-      # @return [String] Resolved 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
+      # @param engine [ViewEngines::Base]
+      # @param source [String]
+      # @return [Array<Hash>]
+      def resolve_navigation_candidates(engine, source)
+        return [] unless Woods.configuration&.extract_navigation_edges
+
+        seen = Set.new
+        engine.scan_navigation_candidates(source).filter_map do |cand|
+          resolved = resolve_route_helper(cand[:helper])
+          next unless resolved
+
+          key = [resolved[:controller], cand[:via]]
+          next if seen.include?(key)
+
+          seen.add(key)
+          { type: :controller, target: resolved[:controller], via: cand[:via] }
         end
       end
 
@@ -248,8 +209,6 @@ module Woods
       def infer_controller(file_path)
         namespace = extract_view_namespace(file_path)
         return nil unless namespace
-
-        # Skip layout-only directories
         return nil if namespace == 'layouts'
 
         parts = namespace.split('/')

data/lib/woods/flow_assembler.rb

@@ -253,7 +253,11 @@ module Woods
 
       filenames.each do |filename|
         Dir[File.join(@extracted_dir, '*', filename)].each do |path|
-          return JSON.parse(File.read(path), symbolize_names: true)
+          # Force UTF-8: the extractor writes the routes-comment header in
+          # source_code using Unicode box-drawing characters; reading under
+          # the platform default (US-ASCII on some CIs) raises
+          # InvalidByteSequenceError before JSON parsing.
+          return JSON.parse(File.read(path, encoding: 'UTF-8'), symbolize_names: true)
         rescue JSON::ParserError
           next
         end
@@ -263,28 +267,32 @@ module Woods
     end
 
     # Extract route information from controller metadata.
+    #
+    # Handles two on-disk shapes:
+    # - Hash keyed by action (what ControllerExtractor writes):
+    #     { "create" => [{ verb:, path:, ... }, ...] }
+    # - Array of route hashes (older / test fixture shape):
+    #     [{ action:, verb:, path: }, ...]
     def extract_route(entry_point)
       unit_id, method_name = parse_identifier(entry_point)
       unit_data = load_unit(unit_id)
       return nil unless unit_data
 
       metadata = unit_data[:metadata] || {}
-      routes = metadata[:routes]
-      return nil unless routes.is_a?(Array)
-
-      # Find route matching the method name
-      route = if method_name
-                routes.find { |r| r[:action]&.to_s == method_name }
-              else
-                routes.first
-              end
-
+      route = resolve_route_entry(metadata[:routes], method_name)
       return nil unless route
 
-      {
-        verb: route[:verb],
-        path: route[:path]
-      }
+      { verb: route[:verb], path: route[:path] }
+    end
+
+    def resolve_route_entry(routes, method_name)
+      case routes
+      when Hash
+        action_routes = method_name ? routes[method_name.to_s] || routes[method_name.to_sym] : routes.values.first
+        Array(action_routes).first
+      when Array
+        method_name ? routes.find { |r| r[:action]&.to_s == method_name } : routes.first
+      end
     end
   end
 end

data/lib/woods/flow_precomputer.rb

@@ -83,7 +83,7 @@ module Woods
       filename = "#{controller_id.gsub('::', '__')}_#{action}.json"
       flow_path = File.join(@flows_dir, filename)
 
-      File.write(flow_path, JSON.pretty_generate(flow.to_h))
+      File.write(flow_path, canonical_json(flow.to_h))
 
       flow_path
     rescue StandardError => e
@@ -96,7 +96,26 @@ module Woods
     # @param flow_map [Hash{String => String}]
     def write_flow_index(flow_map)
       index_path = File.join(@flows_dir, 'flow_index.json')
-      File.write(index_path, JSON.pretty_generate(flow_map))
+      File.write(index_path, canonical_json(flow_map))
+    end
+
+    # Emit deterministic pretty JSON — keys recursively sorted so two runs
+    # over identical input produce byte-identical output. Without this,
+    # diff-based tooling (snapshot review, flow-change detection) flags
+    # spurious churn from incidental key-order differences in `flow.to_h`.
+    #
+    # @param value [Hash, Array, Object]
+    # @return [String]
+    def canonical_json(value)
+      JSON.pretty_generate(sort_keys_deep(value))
+    end
+
+    def sort_keys_deep(value)
+      case value
+      when Hash  then value.keys.sort_by(&:to_s).to_h { |k| [k, sort_keys_deep(value[k])] }
+      when Array then value.map { |v| sort_keys_deep(v) }
+      else value
+      end
     end
   end
 end

data/lib/woods/graph_analyzer.rb

@@ -154,6 +154,52 @@ module Woods
         end
     end
 
+    # Group units into semantic domains using namespace prefixes and graph connectivity.
+    #
+    # Strategy:
+    # 1. Seed clusters from top-level namespace prefixes (e.g., ShippingProfile::*, Order::*)
+    # 2. Assign unnamespaced units to their most-connected cluster
+    # 3. Merge small clusters (< min_size) into their most-connected neighbor
+    # 4. For each cluster, identify the hub (highest PageRank) and entry points
+    # 5. Compute boundary edges between clusters
+    #
+    # @param min_size [Integer] Minimum units per cluster before merging (default: 3)
+    # @param types [Array<String>, nil] Filter to these unit types (default: all)
+    # @return [Array<Hash>] Clusters sorted by member count descending.
+    #   Each hash: { name:, hub:, members:, member_count:, entry_points:, boundary_edges:, types: }
+    def domain_clusters(min_size: 3, types: nil)
+      nodes = graph_nodes
+      return [] if nodes.empty?
+
+      # Filter by types if specified
+      filtered_ids = if types
+                       type_set = types.map(&:to_s)
+                       nodes.select { |_, meta| type_set.include?(meta[:type].to_s) }.keys
+                     else
+                       nodes.keys
+                     end
+
+      return [] if filtered_ids.empty?
+
+      # Step 1: Seed clusters from namespace prefixes
+      clusters = seed_namespace_clusters(filtered_ids, nodes)
+
+      # Step 2: Assign unnamespaced/root units to most-connected cluster
+      assign_orphaned_units(clusters, filtered_ids, nodes)
+
+      # Step 3: Merge small clusters
+      merge_small_clusters(clusters, min_size)
+
+      # Step 4: Enrich each cluster with hub, entry points, boundary edges
+      pagerank_scores = @graph.pagerank
+      enrich_clusters(clusters, nodes, pagerank_scores)
+
+      # Sort by member count descending
+      clusters.values
+              .select { |c| c[:members].any? }
+              .sort_by { |c| -c[:member_count] }
+    end
+
     # Full analysis report combining all structural metrics.
     #
     # @return [Hash] Complete analysis with :orphans, :dead_ends, :hubs,
@@ -182,6 +228,170 @@ module Woods
 
     private
 
+    # ──────────────────────────────────────────────────────────────────────
+    # Domain Cluster Helpers
+    # ──────────────────────────────────────────────────────────────────────
+
+    # Extract the top-level namespace prefix for clustering.
+    # "ShippingProfile::Setting" => "ShippingProfile"
+    # "Order::Transactions::Refund" => "Order"
+    # "Account" => nil (no namespace)
+    def cluster_prefix(identifier)
+      parts = identifier.to_s.split('::')
+      parts.size > 1 ? parts.first : nil
+    end
+
+    # Seed initial clusters from namespace prefixes.
+    def seed_namespace_clusters(filtered_ids, _nodes)
+      clusters = {}
+
+      filtered_ids.each do |id|
+        prefix = cluster_prefix(id)
+        next unless prefix
+
+        clusters[prefix] ||= { name: prefix, members: [], member_set: Set.new }
+        clusters[prefix][:members] << id
+        clusters[prefix][:member_set].add(id)
+      end
+
+      clusters
+    end
+
+    # Assign units with no namespace prefix to their most-connected cluster.
+    def assign_orphaned_units(clusters, filtered_ids, _nodes)
+      return if clusters.empty?
+
+      unassigned = filtered_ids.select { |id| cluster_prefix(id).nil? }
+
+      unassigned.each do |id|
+        best_cluster = find_most_connected_cluster(id, clusters)
+        next unless best_cluster
+
+        clusters[best_cluster][:members] << id
+        clusters[best_cluster][:member_set].add(id)
+      end
+    end
+
+    # Find which cluster a unit has the most connections to.
+    def find_most_connected_cluster(identifier, clusters)
+      connections = Hash.new(0)
+
+      # Check forward edges (dependencies)
+      @graph.dependencies_of(identifier).each do |dep|
+        clusters.each do |name, cluster|
+          connections[name] += 1 if cluster[:member_set].include?(dep)
+        end
+      end
+
+      # Check reverse edges (dependents)
+      @graph.dependents_of(identifier).each do |dep|
+        clusters.each do |name, cluster|
+          connections[name] += 1 if cluster[:member_set].include?(dep)
+        end
+      end
+
+      return nil if connections.empty?
+
+      connections.max_by { |_, count| count }.first
+    end
+
+    # Merge clusters smaller than min_size into their most-connected neighbor.
+    def merge_small_clusters(clusters, min_size)
+      loop do
+        small = clusters.select { |_, c| c[:members].size < min_size }
+        break if small.empty?
+
+        # Merge the smallest cluster first
+        name, cluster = small.min_by { |_, c| c[:members].size }
+
+        # Find which other cluster this one connects to most
+        target = find_merge_target(cluster, clusters, name)
+
+        break unless target
+
+        clusters[target][:members].concat(cluster[:members])
+        cluster[:members].each { |id| clusters[target][:member_set].add(id) }
+        clusters.delete(name)
+      end
+    end
+
+    # Find the best cluster to merge into (most cross-cluster edges).
+    def find_merge_target(cluster, all_clusters, exclude_name)
+      connections = Hash.new(0)
+
+      cluster[:members].each do |id|
+        (@graph.dependencies_of(id) + @graph.dependents_of(id)).each do |connected|
+          all_clusters.each do |name, other|
+            next if name == exclude_name
+
+            connections[name] += 1 if other[:member_set].include?(connected)
+          end
+        end
+      end
+
+      return nil if connections.empty?
+
+      connections.max_by { |_, count| count }.first
+    end
+
+    # Enrich clusters with hub, entry points, boundary edges, and type breakdown.
+    def enrich_clusters(clusters, nodes, pagerank_scores)
+      clusters.each_value do |cluster|
+        members = cluster[:members]
+        member_set = cluster[:member_set]
+
+        # Hub: highest PageRank within the cluster
+        hub_id = members.max_by { |id| pagerank_scores[id] || 0 }
+        cluster[:hub] = hub_id
+
+        # Entry points: controllers and GraphQL resolvers in the cluster's dependents
+        entry_types = %w[controller graphql_resolver graphql_mutation graphql_query]
+        entry_points = Set.new
+        members.each do |id|
+          @graph.dependents_of(id).each do |dep|
+            meta = nodes[dep]
+            entry_points.add(dep) if meta && entry_types.include?(meta[:type].to_s)
+          end
+        end
+        cluster[:entry_points] = entry_points.to_a
+
+        # Boundary edges: connections that cross cluster boundaries
+        boundary = []
+        members.each do |id|
+          @graph.dependencies_of(id).each do |dep|
+            next if member_set.include?(dep)
+
+            dep_meta = nodes[dep]
+            next unless dep_meta
+
+            boundary << { from: id, to: dep, via: 'dependency' }
+          end
+
+          @graph.dependents_of(id).each do |dep|
+            next if member_set.include?(dep)
+
+            dep_meta = nodes[dep]
+            next unless dep_meta
+
+            boundary << { from: dep, to: id, via: 'dependent' }
+          end
+        end
+        # Deduplicate and limit boundary edges
+        cluster[:boundary_edges] = boundary.uniq { |e| [e[:from], e[:to]] }.first(20)
+
+        # Type breakdown
+        type_counts = members.each_with_object(Hash.new(0)) do |id, counts|
+          meta = nodes[id]
+          counts[meta[:type].to_s] += 1 if meta
+        end
+        cluster[:types] = type_counts
+
+        # Final shape
+        cluster[:member_count] = members.size
+        cluster.delete(:member_set) # Internal tracking, not part of output
+      end
+    end
+
     # ──────────────────────────────────────────────────────────────────────
     # Graph Accessors
     # ──────────────────────────────────────────────────────────────────────