woods 1.6.1 → 2.0.0.beta2

data/lib/woods/extractors/test_mapping_extractor.rb

@@ -28,6 +28,16 @@ module Woods
       RSPEC_GLOB = 'spec/**/*_spec.rb'
       MINITEST_GLOB = 'test/**/*_test.rb'
 
+      # Constant-form describe: `describe User do`, `RSpec.describe User, type: :model do`.
+      # The constant must start uppercase (quoted strings can't sneak in) and may be
+      # followed by whitespace OR a comma — the rspec-rails generator default is
+      # `RSpec.describe User, type: :model do` (B-082 / #194).
+      RSPEC_CONSTANT_DESCRIBE = /^\s*(?:RSpec\.)?describe\s+([A-Z][\w:]*)(?=[\s,]|$)/
+
+      # String-form describe: `describe 'User' do`, `RSpec.describe 'GET /users', type: :request do`.
+      # The closing quote delimits the subject, so nothing is required after it.
+      RSPEC_STRING_DESCRIBE = /^\s*(?:RSpec\.)?describe\s+['"]([^'"]+)['"]/
+
       def initialize
         @rails_root = Rails.root
       end
@@ -114,21 +124,28 @@ module Woods
         framework == :rspec ? extract_rspec_subject(source) : extract_minitest_subject(source)
       end
 
-      # Extract subject class from top-level describe in an RSpec file.
+      # Extract subject class from the first describe in an RSpec file.
       #
-      # Tries constant reference first (describe User do), then string/symbol
-      # form (describe 'User' do). Handles both RSpec.describe and bare describe.
+      # Scans line by line and takes the file's FIRST describe, whatever its
+      # form — constant reference (describe User do, RSpec.describe User,
+      # type: :model do) or string (describe 'User' do). An inner
+      # `describe 'validations'` nested under a constant-form outer describe
+      # must never become the subject: it would mint a phantom graph node and
+      # lose the real coverage edge. Handles both RSpec.describe and bare
+      # describe.
       #
       # @param source [String] RSpec file source code
       # @return [String, nil]
       def extract_rspec_subject(source)
-        # Constant reference: describe User do, RSpec.describe UsersController do
-        match = source.match(/^\s*(?:RSpec\.)?describe\s+([\w:]+)\s/)
-        return match[1] if match
+        source.each_line do |line|
+          constant = line.match(RSPEC_CONSTANT_DESCRIBE)
+          return constant[1] if constant
 
-        # String/symbol form: describe 'User' do
-        match = source.match(/^\s*(?:RSpec\.)?describe\s+['"]([^'"]+)['"]\s/)
-        match ? match[1] : nil
+          string = line.match(RSPEC_STRING_DESCRIBE)
+          return string[1] if string
+        end
+
+        nil
       end
 
       # Extract subject class from Minitest test class name.

data/lib/woods/extractors/view_component_extractor.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require_relative 'component_discovery'
 require_relative 'shared_utility_methods'
 require_relative 'shared_dependency_scanner'
 require_relative 'route_helper_resolver'
@@ -25,6 +26,7 @@ module Woods
     #   card = units.find { |u| u.identifier == "CardComponent" }
     #
     class ViewComponentExtractor
+      include ComponentDiscovery
       include SharedUtilityMethods
       include SharedDependencyScanner
       include RouteHelperResolver
@@ -38,13 +40,36 @@ module Woods
       #
       # @return [Array<ExtractedUnit>] List of view component units
       def extract_all
-        return [] unless @component_base
-
-        @component_base.descendants.map do |component|
+        discoverable_classes.map do |component|
           extract_component(component)
         end.compact
       end
 
+      # The component classes this extractor would extract from the running
+      # app. Shared with the incremental path's class reconciliation (#164).
+      #
+      # @return [Array<Class>]
+      def discoverable_classes
+        return [] unless @component_base
+
+        # Same reason PhlexExtractor walks first: `descendants` cannot see a
+        # component the eager load never reached (B-184). Skipped entirely
+        # when ViewComponent::Base is undefined, since @component_base is then
+        # nil and this app has no view components to find.
+        load_component_files
+
+        # Previews are filtered here rather than only in {#extract_component},
+        # because this set is also the incremental path's reconciliation input.
+        # A preview class is never in the graph — `extract_component` rejects it
+        # — so leaving it in made every incremental run recompute the same
+        # "addition", extract it, get nil, and dirty the dependents pass for
+        # nothing. Anonymous classes go too: `extract_component` rejects a nil
+        # name for the same reason.
+        @component_base.descendants.reject do |component|
+          component.name.nil? || preview_class?(component)
+        end
+      end
+
       # Extract a single ViewComponent component
       #
       # @param component [Class] The component class

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

@@ -19,8 +19,9 @@ module Woods
         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}.
+        # template source. Same shape as
+        # {SharedDependencyScanner::ROUTE_HELPER_PATTERN}, but this engine
+        # has no dependency on that module, so it keeps its own copy.
         ROUTE_HELPER_PATTERN = /\b(\w+)_(path|url)\b/
 
         # Matches form_with / form_for calls whose action is a named
@@ -72,8 +73,17 @@ module Woods
           EXTENSIONS
         end
 
+        # Render option keys that are never themselves a partial name. The
+        # bare `render :foo` shorthand pattern below cannot tell `render
+        # :partial => 'shared/header'` (the pre-Ruby-3.0 hash-rocket form of
+        # the `partial:` option) from an actual `render :partial_name` call,
+        # so it must exclude these explicitly rather than record the option
+        # key as a partial.
+        RESERVED_RENDER_OPTIONS = %w[partial template layout].freeze
+
         # Matches:
         # - `render partial: 'foo/bar'`
+        # - `render :partial => 'foo/bar'` (hash-rocket form)
         # - `render 'foo/bar'`
         # - `render :foo`
         #
@@ -85,12 +95,16 @@ module Woods
             partials << match[0]
           end
 
+          source.scan(/render\s+:partial\s*=>\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]
+            partials << match[0] unless RESERVED_RENDER_OPTIONS.include?(match[0])
           end
 
           partials.to_a

data/lib/woods/feedback/gap_detector.rb

@@ -53,15 +53,21 @@ module Woods
         end
       end
 
-      # Count keyword occurrences across low-scoring query texts.
+      # Count how many low-scoring *queries* mention each keyword.
+      #
+      # Deliberately one vote per query, not per occurrence: counting
+      # occurrences let a single query reading "user user user user" clear a
+      # threshold of four on its own, and made every reported count larger
+      # than the number of queries it summarized — which is what the
+      # description string claims to be reporting.
       #
       # @param ratings [Array<Hash>] Low-score rating entries
-      # @return [Hash<String, Integer>] Keyword => occurrence count
+      # @return [Hash<String, Integer>] Keyword => number of queries mentioning it
       def count_keywords(ratings)
         counts = Hash.new(0)
         ratings.each do |rating|
           words = rating['query'].to_s.downcase.split(/\W+/).reject { |w| w.length < 3 }
-          words.each { |w| counts[w] += 1 }
+          words.uniq.each { |w| counts[w] += 1 }
         end
         counts
       end

data/lib/woods/feedback/store.rb

@@ -2,6 +2,7 @@
 
 require 'json'
 require 'fileutils'
+require 'time'
 
 module Woods
   module Feedback
@@ -68,7 +69,12 @@ module Woods
         return [] unless File.exist?(@path)
 
         entries = []
-        File.foreach(@path) do |line|
+        # Explicit UTF-8: `record_*` appends raw UTF-8 bytes, so a bare read
+        # would tag every line with the process default external encoding and
+        # the first non-ASCII entry would raise under LANG=C — permanently,
+        # since the poison line stays in the file (INF-3). Same contract as
+        # AtomicFile.read.
+        File.foreach(@path, encoding: Encoding::UTF_8) do |line|
           entry = JSON.parse(line.strip)
           entries << entry
           break if limit && entries.size >= limit

data/lib/woods/filename_utils.rb

@@ -30,12 +30,40 @@ module Woods
     # (the writer previously left the action raw while the reader allow-listed
     # it, so such flows were written under one name and never found).
     #
+    # A SHA256 digest (the same disambiguation {#collision_safe_filename}
+    # already uses) is appended whenever either segment's transform was
+    # lossy — e.g. `bar.baz` and `bar_baz` both {.safe_segment} to `bar_baz`,
+    # so writing them under one name means the second write clobbers the
+    # first and `flow_index.json` points both entries at that one file. The
+    # namespace transform keeps its legacy spelling. Literal underscores in
+    # either input are digested, preventing both namespace and separator
+    # collisions, including an action that resembles another file's digest.
+    #
     # @param controller_id [String] e.g. "Admin::UsersController"
     # @param action [String] e.g. "index"
     # @return [String] e.g. "Admin__UsersController_index.json"
     def self.flow_filename(controller_id, action)
-      "#{safe_segment(controller_id)}_#{safe_segment(action)}.json"
+      base = "#{safe_segment(controller_id)}_#{safe_segment(action)}"
+      ambiguous = controller_id.to_s.include?('_') || action.to_s.include?('_')
+      return "#{base}.json" unless ambiguous || lossy_segment?(controller_id) || lossy_segment?(action)
+
+      digest = Digest::SHA256.hexdigest("#{controller_id}##{action}")[0, 8]
+      "#{base}_#{digest}.json"
+    end
+
+    # Whether {.safe_segment} discarded information for +value+ beyond the
+    # `::` → `__` namespace transform — i.e. whether some OTHER character
+    # got folded to `_`. That residual loss is what makes two different
+    # inputs land on the same segment (`bar.baz` and `bar_baz` both become
+    # `bar_baz`). Literal underscores are handled separately by flow_filename.
+    #
+    # @param value [String]
+    # @return [Boolean]
+    def self.lossy_segment?(value)
+      namespaced = value.to_s.gsub('::', '__')
+      namespaced.gsub(/[^a-zA-Z0-9_-]/, '_') != namespaced
     end
+    private_class_method :lossy_segment?
 
     # Convert an identifier to a safe filename (legacy format).
     #

data/lib/woods/flow_analysis/operation_extractor.rb

@@ -139,16 +139,10 @@ module Woods
 
         return if then_ops.empty? && else_ops.empty?
 
-        condition_text = if children[0].is_a?(Ast::Node)
-                           children[0].to_source
-                         elsif children[0].is_a?(String)
-                           children[0]
-                         end
-
         operations << {
           type: :conditional,
           kind: 'if',
-          condition: condition_text || node.source,
+          condition: condition_source(children[0]) || node.source,
           line: node.line,
           then_ops: then_ops,
           else_ops: else_ops
@@ -156,23 +150,41 @@ module Woods
       end
 
       # Handle :case nodes as a conditional variant.
+      #
+      # A case node is `(case predicate when… else)`, so children[0] is the
+      # predicate and the branches follow it. Walking *all* children counted
+      # any call in the predicate — `case user.role` — as an operation
+      # performed inside a branch, and reporting `node.source` as the condition
+      # meant the whole multi-line statement stood in for the one expression
+      # being switched on. Mirrors {#handle_conditional}.
       def handle_case(node, operations)
-        # Treat case as a conditional - extract ops from all branches
+        children = node.children || []
         branch_ops = []
-        walk_children(node, branch_ops)
+        children.drop(1).each { |child| walk(child, branch_ops) if child.is_a?(Ast::Node) }
 
         return if branch_ops.empty?
 
         operations << {
           type: :conditional,
           kind: 'case',
-          condition: node.source,
+          condition: condition_source(children[0]) || node.source,
           line: node.line,
           then_ops: branch_ops,
           else_ops: []
         }
       end
 
+      # Source text for a conditional's predicate child, which the parser may
+      # hand back as a node or as an already-rendered string.
+      #
+      # @param child [Ast::Node, String, nil]
+      # @return [String, nil]
+      def condition_source(child)
+        return child.to_source if child.is_a?(Ast::Node)
+
+        child if child.is_a?(String)
+      end
+
       # Detect transaction/with_lock calls.
       def transaction_call?(node)
         TRANSACTION_METHODS.include?(node.method_name)

data/lib/woods/flow_assembler.rb

@@ -4,7 +4,6 @@ require 'digest'
 require 'json'
 require 'set'
 require_relative 'ast/parser'
-require_relative 'ast/method_extractor'
 require_relative 'flow_analysis/operation_extractor'
 require_relative 'flow_document'
 
@@ -25,14 +24,25 @@ module Woods
   #   puts flow.to_markdown
   #
   class FlowAssembler
+    # How many entries each per-instance memo holds before the oldest is
+    # dropped. One assembler serves a whole precompute run (every controller,
+    # every action), so an unbounded memo would hold the source and the parsed
+    # AST of every unit the run ever reached. A thousand covers the shared
+    # services a large app's flows keep landing on without pinning the whole
+    # index in memory.
+    MEMO_LIMIT = 1_000
+
     # @param graph [DependencyGraph] The dependency graph for resolving targets
     # @param extracted_dir [String] Directory containing extracted unit JSON files
     def initialize(graph:, extracted_dir:)
       @graph = graph
       @extracted_dir = extracted_dir
       @parser = Ast::Parser.new
-      @method_extractor = Ast::MethodExtractor.new(parser: @parser)
       @operation_extractor = FlowAnalysis::OperationExtractor.new
+      @resolved_targets = {}
+      @unit_cache = {}
+      @ast_cache = {}
+      @method_node_cache = {}
     end
 
     # Assemble an execution flow from the given entry point.
@@ -72,11 +82,17 @@ module Woods
     # @param depth [Integer] Current recursion depth
     # @param max_depth [Integer] Maximum recursion depth
     # @param path [Set<String>] Identifiers on the current recursion path
-    def expand(identifier, steps, visited, depth:, max_depth:, path: Set.new)
+    # @param method_name [String, nil] The method the caller actually invoked
+    #   (from the triggering operation's `op[:method]`), for callers that
+    #   resolve to a bare unit id and so cannot encode it in +identifier+
+    #   itself. `identifier`'s own `#method` suffix (entry points) wins when
+    #   both are present.
+    def expand(identifier, steps, visited, depth:, max_depth:, path: Set.new, method_name: nil)
       return if depth > max_depth
 
       # Parse identifier into unit name and optional method
-      unit_id, method_name = parse_identifier(identifier)
+      unit_id, parsed_method = parse_identifier(identifier)
+      method_name = parsed_method || method_name
 
       if path.include?(unit_id)
         # Genuine cycle — the unit is an ancestor of itself on this path.
@@ -107,7 +123,7 @@ module Woods
         file_path = unit_data[:file_path]
 
         # Extract operations from the relevant method
-        operations = extract_operations(source_code, method_name, metadata, unit_type)
+        operations = extract_operations(unit_id, source_code, method_name, metadata, unit_type)
 
         step = {
           unit: identifier,
@@ -129,28 +145,83 @@ module Woods
       end
     end
 
-    # Extract operations from source code for a specific method.
-    def extract_operations(source_code, method_name, metadata, unit_type)
+    # Extract operations from source code for a specific method — or, when no
+    # method is named or the unit does not define one by that name, from the
+    # entire source.
+    #
+    # A named method that isn't found falls back to the whole unit rather
+    # than yielding no operations: {#expand_operation} now threads the
+    # calling operation's `op[:method]` through, and that method need not be
+    # one the callee actually defines locally (inherited, dynamically
+    # defined, or metaprogrammed) — losing the trace entirely would be worse
+    # than over-including it.
+    def extract_operations(unit_id, source_code, method_name, metadata, unit_type)
       operations = []
 
       # For controllers, prepend before_action callbacks
       prepend_callbacks(operations, metadata, method_name) if unit_type == 'controller'
 
-      if method_name
-        # Extract specific method
-        method_node = @method_extractor.extract_method(source_code, method_name)
-        if method_node
-          ops = @operation_extractor.extract(method_node)
-          operations.concat(ops)
+      scope_node = method_node(unit_id, source_code, method_name)
+      scope_node ||= parsed_source(unit_id, source_code)
+      operations.concat(@operation_extractor.extract(scope_node))
+
+      operations
+    end
+
+    # The unit's whole parsed source, parsed once per assembler instance.
+    #
+    # A unit reached from several controllers used to be re-parsed once per
+    # action of every controller that reached it, and Prism dominates the
+    # flow run's cost on a large app.
+    #
+    # @param unit_id [String] cache key; a unit's source is fixed for a run
+    # @param source_code [String] the unit's source
+    # @return [Ast::Node] root node
+    def parsed_source(unit_id, source_code)
+      memoize(@ast_cache, unit_id) { @parser.parse(source_code) }
+    end
+
+    # The `def` node for +method_name+, from a per-unit index built off the
+    # memoized parse.
+    #
+    # First definition wins for a name defined more than once, matching
+    # {Ast::MethodExtractor#extract_method}'s first-match lookup.
+    #
+    # @param unit_id [String] cache key
+    # @param source_code [String] the unit's source
+    # @param method_name [String, nil] the method the caller invoked
+    # @return [Ast::Node, nil] nil when no method was named, or the unit does
+    #   not define one by that name
+    def method_node(unit_id, source_code, method_name)
+      return nil unless method_name
+
+      nodes = memoize(@method_node_cache, unit_id) do
+        parsed_source(unit_id, source_code).find_all(:def).each_with_object({}) do |node, index|
+          index[node.method_name] ||= node
         end
-      else
-        # No specific method - parse entire source
-        root = @parser.parse(source_code)
-        ops = @operation_extractor.extract(root)
-        operations.concat(ops)
       end
 
-      operations
+      nodes[method_name.to_s]
+    end
+
+    # Read +key+ from +cache+, computing and storing it on a miss.
+    #
+    # Least-recently-used, using the fact that a Ruby Hash iterates in
+    # insertion order: a hit re-inserts the key at the young end, and
+    # +Hash#shift+ drops the old end once the cache is over {MEMO_LIMIT}.
+    # A nil value is a real answer (most call targets are not units) and is
+    # cached like any other.
+    #
+    # @param cache [Hash]
+    # @param key [Object]
+    # @return [Object] the cached or freshly computed value
+    def memoize(cache, key)
+      return cache[key] = cache.delete(key) if cache.key?(key)
+
+      value = yield
+      cache[key] = value
+      cache.shift while cache.size > MEMO_LIMIT
+      value
     end
 
     # Prepend before_action callbacks from controller metadata.
@@ -189,6 +260,15 @@ module Woods
 
     # Recursively expand an operation's target if it resolves to a known unit.
     #
+    # `op[:method]` is threaded into the recursive {#expand} call so the
+    # callee is scoped to the method actually invoked, not its whole source.
+    # When {#resolve_target} answers with an ambiguity marker (several
+    # namespaces share the target's short name) this does not recurse at
+    # all — it mutates +op+ in place with `:ambiguous_candidates` so the
+    # unresolved call is still visible in the flow output, naming every
+    # candidate instead of silently expanding whichever one the graph's
+    # suffix index happened to pick.
+    #
     # @param op [Hash] The operation to potentially expand
     # @param current_unit [String] The identifier of the unit containing this operation
     # @param steps [Array<Hash>] Accumulator for step hashes
@@ -201,10 +281,21 @@ module Woods
         target = op[:target]
         return unless target
 
-        candidate = resolve_target(target)
-        return unless candidate
+        resolution = resolve_target(target)
+        return unless resolution
 
-        expand(candidate, steps, visited, depth: depth + 1, max_depth: max_depth, path: path)
+        if resolution.is_a?(Hash)
+          # Several namespaces share this short name (Tier 1 suffix match) —
+          # record which ones rather than silently expanding whichever the
+          # graph's deterministic-but-arbitrary suffix index picked.
+          op[:ambiguous_candidates] = resolution[:candidates]
+          return
+        end
+
+        expand(
+          resolution, steps, visited,
+          depth: depth + 1, max_depth: max_depth, path: path, method_name: op[:method]
+        )
       when :transaction
         (op[:nested] || []).each do |nested_op|
           expand_operation(nested_op, current_unit, steps, visited, depth: depth, max_depth: max_depth, path: path)
@@ -229,12 +320,28 @@ module Woods
     #
     # @param target [String] The call target name to resolve
     # @return [String, nil] The resolved unit identifier, or nil if not found
+    # Memoized per assembler instance, and negative results are cached too
+    # (`nil` is a real answer — most call targets are not units). Resolution
+    # used to run a linear suffix scan over every graph node *and*, on a miss,
+    # a set of disk globs, once per operation encountered. A flow touching a
+    # few hundred operations on a host with tens of thousands of nodes paid
+    # that every time, including for the same target repeatedly.
     def resolve_target(target)
+      return @resolved_targets[target] if @resolved_targets.key?(target)
+
+      @resolved_targets[target] = compute_resolved_target(target)
+    end
+
+    # @return [String, Hash, nil] a resolved unit identifier; a
+    #   `{ ambiguous: true, candidates: }` marker when several namespaces
+    #   share +target+'s short name; or nil when nothing resolves
+    def compute_resolved_target(target)
       # Tier 1: Graph-wide lookup
       return target if @graph.node_exists?(target)
 
-      graph_match = @graph.find_node_by_suffix(target)
-      return graph_match if graph_match
+      suffix_matches = @graph.find_all_by_suffix(target)
+      return suffix_matches.first if suffix_matches.size == 1
+      return { ambiguous: true, candidates: suffix_matches } if suffix_matches.size > 1
 
       # Tier 2: Disk fallback (unit JSON exists but isn't in the graph)
       unit_data = load_unit(target)
@@ -254,13 +361,27 @@ module Woods
       end
     end
 
-    # Load an ExtractedUnit's data from its JSON file on disk.
+    # Load an ExtractedUnit's data from its JSON file on disk, memoized per
+    # assembler instance.
+    #
+    # The glob and the JSON parse used to run once per expansion, so a unit
+    # reached from many controllers paid for both once per action of every one
+    # of them. The memo also makes {#extract_route} free: the entry unit it
+    # asks for is the one {#expand} just loaded.
+    #
+    # @param unit_id [String] Unit identifier
+    # @return [Hash, nil] symbolized unit data, or nil when no file matched
+    def load_unit(unit_id)
+      memoize(@unit_cache, unit_id) { read_unit(unit_id) }
+    end
+
+    # The disk half of {#load_unit}.
     #
     # Uses {Extractor#collision_safe_filename} convention (with SHA256 digest suffix).
     # Falls back to legacy {Extractor#safe_filename} for older indexes.
     # Searches across type subdirectories since the extractor writes to
     # `<output_dir>/<type>/<filename>.json`.
-    def load_unit(unit_id)
+    def read_unit(unit_id)
       base = unit_id.gsub('::', '__').gsub(/[^a-zA-Z0-9_-]/, '_')
       digest = Digest::SHA256.hexdigest(unit_id)[0, 8]
       filenames = [

data/lib/woods/flow_document.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require 'json'
+require 'time' # Time#iso8601 — the file is loadable standalone (EXTB-13)
 
 module Woods
   # Value object representing an assembled execution flow trace.