woods 2.0.0.beta1 → 2.0.0.beta3

data/lib/woods/extractors/service_extractor.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative '../source_inputs/consumer_errors'
+
 require_relative 'shared_utility_methods'
 require_relative 'shared_dependency_scanner'
 require_relative 'source_nesting'
@@ -83,7 +85,7 @@ module Woods
 
         unit
       rescue StandardError => e
-        Rails.logger.error("Failed to extract service #{file_path}: #{e.message}")
+        SourceInputs::ConsumerErrors.log(self, "Failed to extract service #{file_path}: #{e.message}")
         nil
       end
 

data/lib/woods/extractors/shared_dependency_scanner.rb

@@ -204,8 +204,8 @@ module Woods
       # 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.
+      # a dependency on that controller. RouteHelperResolver accepts only names
+      # present in the live controller/action route map, excluding unknown helpers.
       # 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/

data/lib/woods/extractors/shared_utility_methods.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative 'source_nesting'
+require_relative 'method_parameters'
 
 module Woods
   module Extractors
@@ -221,6 +222,29 @@ module Woods
         actions.to_a
       end
 
+      # Rails 6 exposes a numeric Proc identity through #filter, and the
+      # callable through #raw_filter. Newer Rails exposes the callable directly.
+      def callback_filter(callback)
+        stable_filter(callback.respond_to?(:raw_filter) ? callback.raw_filter : callback.filter)
+      end
+
+      # Proc#to_s embeds a process-local address. Model and controller filters
+      # share source-site labels, so metadata and derived chunks agree across
+      # boots. Preserve symbols and other application-defined callback values.
+      def stable_filter(filter)
+        return filter unless filter.is_a?(Proc)
+
+        location = filter.source_location
+        site = if location
+                 path, line = location
+                 "#{path.delete_prefix("#{Rails.root}/")}:#{line}"
+               else
+                 'native'
+               end
+        "#<#{filter.lambda? ? 'lambda' : 'Proc'} #{site}>"
+      end
+      private :callback_filter, :stable_filter
+
       # Human-readable label for a non-ActionFilter condition.
       #
       # @param condition [Object] A proc, symbol, or other condition
@@ -292,7 +316,7 @@ module Woods
         source.scan(/def\s+self\.(\w+[?!=]?)/).flatten
       end
 
-      # Extract initialize parameters from source code via regex.
+      # Extract initialize parameters from source syntax without evaluating defaults.
       #
       # Parses the parameter list of the initialize method to determine
       # parameter names, defaults, and whether they are keyword arguments.
@@ -304,21 +328,9 @@ module Woods
       # @param source [String] Ruby source code
       # @return [Array<Hash>] Parameter info hashes with :name, :has_default, :keyword
       def extract_initialize_params(source)
-        init_match = source.match(/def\s+initialize\s*\((.*?)\)/m)
-        return [] unless init_match
-
-        params_str = init_match[1]
-        params = []
-
-        params_str.scan(/(\w+)(?::\s*([^,\n]+))?/) do |name, default|
-          params << {
-            name: name,
-            has_default: !default.nil?,
-            keyword: params_str.include?("#{name}:")
-          }
+        MethodParameters.extract(source, :initialize).map do |parameter|
+          parameter.slice(:name, :has_default, :keyword)
         end
-
-        params
       end
     end
   end

data/lib/woods/extractors/source_nesting.rb

@@ -245,7 +245,7 @@ module Woods
       # The constant path the active main loader expects for +file_path+,
       # asked through the loader's own API so its inflector, namespace
       # collapse, and ignore rules decide (a custom `api => API` inflection
-      # must win over the local camelizer). Available on Zeitwerk 2.6.4+;
+      # must win over the local camelizer). Available on Zeitwerk 2.6.9+;
       # nil — unmanaged — when the loader's API is older, declines the
       # file, or cannot derive a name. A decline is authoritative: the
       # local camelizer must not rescue it.

data/lib/woods/extractors/state_machine_extractor.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative '../source_inputs/consumer_errors'
+
 require_relative 'shared_utility_methods'
 require_relative 'shared_dependency_scanner'
 require_relative 'source_nesting'
@@ -58,7 +60,7 @@ module Woods
         units.concat(extract_state_machines_units(source, class_name, file_path))
         units
       rescue StandardError => e
-        Rails.logger.error("Failed to extract state machines from #{file_path}: #{e.message}")
+        SourceInputs::ConsumerErrors.log(self, "Failed to extract state machines from #{file_path}: #{e.message}")
         []
       end
 

data/lib/woods/extractors/test_mapping_extractor.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative '../source_inputs/consumer_errors'
+
 require_relative 'shared_utility_methods'
 require_relative 'shared_dependency_scanner'
 
@@ -70,7 +72,7 @@ module Woods
 
         unit
       rescue StandardError => e
-        Rails.logger.error("Failed to extract test mapping from #{file_path}: #{e.message}")
+        SourceInputs::ConsumerErrors.log(self, "Failed to extract test mapping from #{file_path}: #{e.message}")
         nil
       end
 

data/lib/woods/extractors/validator_extractor.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative '../source_inputs/consumer_errors'
+
 require_relative 'shared_utility_methods'
 require_relative 'shared_dependency_scanner'
 
@@ -70,7 +72,7 @@ module Woods
 
         unit
       rescue StandardError => e
-        Rails.logger.error("Failed to extract validator #{file_path}: #{e.message}")
+        SourceInputs::ConsumerErrors.log(self, "Failed to extract validator #{file_path}: #{e.message}")
         nil
       end
 

data/lib/woods/extractors/view_component_extractor.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative '../source_inputs/consumer_errors'
+
 require_relative 'component_discovery'
 require_relative 'shared_utility_methods'
 require_relative 'shared_dependency_scanner'
@@ -95,7 +97,7 @@ module Woods
 
         unit
       rescue StandardError => e
-        Rails.logger.error("Failed to extract view component #{component.name}: #{e.message}")
+        SourceInputs::ConsumerErrors.log(self, "Failed to extract view component #{component.name}: #{e.message}")
         nil
       end
 

data/lib/woods/extractors/view_template_extractor.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative '../source_inputs/consumer_errors'
+
 require 'set'
 require_relative 'route_helper_resolver'
 require_relative 'view_engines/base'
@@ -95,7 +97,7 @@ module Woods
 
         unit
       rescue StandardError => e
-        Rails.logger.error("Failed to extract view template #{file_path}: #{e.message}")
+        SourceInputs::ConsumerErrors.log(self, "Failed to extract view template #{file_path}: #{e.message}")
         nil
       end
 

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,15 +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.
@@ -114,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,
@@ -146,19 +155,75 @@ module Woods
     # 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(source_code, method_name, metadata, unit_type)
+    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'
 
-      scope_node = method_name && @method_extractor.extract_method(source_code, method_name)
-      scope_node ||= @parser.parse(source_code)
+      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
+      end
+
+      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.
     #
     # Handles two metadata formats:
@@ -296,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_precomputer.rb

@@ -89,11 +89,17 @@ module Woods
     #   controller units, rehydrated from the payload this run seeded
     # @param removed_identifiers [Array<String>] controller identifiers
     #   whose unit the run pruned
+    # @param carried_identifiers [Array<String>] controllers the run
+    #   re-extracted whose flows it established cannot have changed. Their
+    #   index entries stay as they are and their annotation is read back out
+    #   of those entries, because a re-extracted unit lost the annotation
+    #   whether or not its flows moved. Skipping the assembly is the whole
+    #   saving; skipping the annotation would diverge from a full run.
     # @return [Hash{String => Hash{String => String}}] per-controller
     #   annotation (action => relative flow path) to write into the units'
     #   metadata; an empty hash means "no flows", which clears any
     #   annotation a previous run had written
-    def recompute_delta(touched_units:, removed_identifiers: [])
+    def recompute_delta(touched_units:, removed_identifiers: [], carried_identifiers: [])
       FileUtils.mkdir_p(@flows_dir)
 
       assembler = FlowAssembler.new(graph: @graph, extracted_dir: @output_dir)
@@ -110,8 +116,13 @@ module Woods
         delta.merge!(entries)
       end
 
+      previous = previous_flow_index
+      Array(carried_identifiers).each do |identifier|
+        annotations[identifier] = carried_annotation(previous, identifier)
+      end
+
       replaced = touched_units.map(&:identifier) + Array(removed_identifiers)
-      carried = previous_flow_index.reject { |entry_point, _path| replaced.include?(controller_of(entry_point)) }
+      carried = previous.reject { |entry_point, _path| replaced.include?(controller_of(entry_point)) }
 
       write_flow_index(carried.merge(delta))
 
@@ -156,6 +167,18 @@ module Woods
       [entries, unit_flow_paths]
     end
 
+    # One controller's annotation, rebuilt from the index entries it keeps.
+    #
+    # @param previous [Hash{String => String}] the previous flow index
+    # @param identifier [String] controller identifier
+    # @return [Hash{String => String}] action to relative flow path
+    def carried_annotation(previous, identifier)
+      previous.each_with_object({}) do |(entry_point, path), annotation|
+        controller, action = entry_point.to_s.split('#', 2)
+        annotation[action] = path if action && controller == identifier
+      end
+    end
+
     # The controller part of a flow index entry point.
     #
     # @param entry_point [String]
@@ -183,9 +206,10 @@ module Woods
 
     # Assemble a flow for one entry point and write the JSON file.
     #
-    # Written via {Woods::AtomicFile} (temp + fsync + rename) like every
-    # other index artifact — a plain +File.write+ interrupted mid-write left
-    # a torn partial for the MCP read side to trip over.
+    # Written via {Woods::AtomicFile} (temp + rename) like every other index
+    # artifact. A plain +File.write+ interrupted mid-write left a torn
+    # partial for the MCP read side to trip over. Not durable by default: see
+    # {#durable_writes?}.
     #
     # @param assembler [FlowAssembler]
     # @param entry_point [String]
@@ -199,7 +223,7 @@ module Woods
 
       filename = Woods::FilenameUtils.flow_filename(controller_id, action)
 
-      Woods::AtomicFile.write(File.join(@flows_dir, filename), canonical_json(flow.to_h))
+      Woods::AtomicFile.write(File.join(@flows_dir, filename), canonical_json(flow.to_h), durable: durable_writes?)
 
       # Relative — this value is persisted (flow_index.json and the unit's
       # metadata[:flow_paths]), so it must not carry this machine's root.
@@ -213,7 +237,20 @@ module Woods
     # @param flow_map [Hash{String => String}]
     def write_flow_index(flow_map)
       index_path = File.join(@flows_dir, 'flow_index.json')
-      Woods::AtomicFile.write(index_path, canonical_json(flow_map))
+      Woods::AtomicFile.write(index_path, canonical_json(flow_map), durable: durable_writes?)
+    end
+
+    # Whether a flow document pays for its own fsync as it is written.
+    #
+    # False by default. A flow document is a payload file: nothing reads it
+    # until +generation.json+ names the payload, and
+    # {Woods::AtomicFile.sync_directory_tree} flushes the whole payload before
+    # that pointer is written. `durable_payload_writes = true` buys the
+    # per-file fsync back for a host that wants it.
+    #
+    # @return [Boolean]
+    def durable_writes?
+      Woods.configuration&.durable_payload_writes ? true : false
     end
 
     # Emit deterministic pretty JSON — keys recursively sorted so two runs

data/lib/woods/gem_mapper.rb

@@ -7,6 +7,7 @@ require 'pathname'
 require 'time'
 
 require_relative 'atomic_file'
+require_relative 'version'
 require_relative 'coordination/pipeline_lock'
 require_relative 'dependency_graph'
 require_relative 'extracted_unit'
@@ -267,6 +268,7 @@ module Woods
       end
       manifest = {
         extracted_at: Time.now.utc.iso8601, rails_version: nil, ruby_version: RUBY_VERSION,
+        woods_version: Woods::VERSION,
         counts: counts, total_units: @units.size, total_chunks: 0, git_sha: nil, git_branch: nil,
         provenance: GemMapper::PROVENANCE.merge(source_checksum: @checksum),
         graph_nodes: @graph.to_h.dig(:stats, :node_count), graph_edges: @graph.to_h.dig(:stats, :edge_count)

data/lib/woods/git_history.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+require 'open3'
+require 'time'
+require_relative 'git_command'
+
+module Woods
+  # Stream HEAD-reachable touched-path events without pathspec simplification.
+  # Raw NUL records keep filenames separate from commit fields; only requested
+  # paths are retained. Merge diffs compare against the first parent, while
+  # traversal still visits every parent. Requires Git 2.31 or newer.
+  class GitHistory
+    class ReadError < StandardError; end
+
+    FORMAT = '%x00%H%x00%an%x00%cI%x00%s%x00'
+    private_constant :FORMAT
+
+    def initialize(root:, logger:)
+      @root = root
+      @logger = logger
+    end
+
+    # @return [Hash, nil] raw per-path aggregates, or nil on any incomplete read
+    def read(paths, recent_after:)
+      requested = paths.to_h { |path| [repository_prefix + path.b, path] }
+      result = paths.to_h { |path| [path, {}] }
+      stream { |stdout| parse(stdout, requested, result, recent_after) }
+      result
+    rescue StandardError => e
+      @logger.warn('[Woods] Git enrichment omitted: history could not be read completely. ' \
+                   'Git 2.31 or newer is required; check the application repository and git installation. ' \
+                   "(#{e.class})")
+      nil
+    end
+
+    private
+
+    def repository_prefix
+      return @repository_prefix if defined?(@repository_prefix)
+
+      prefix, _error, status = Open3.capture3(*GitCommand.argv(@root, 'rev-parse', '--show-prefix'))
+      raise ReadError, 'cannot resolve application path in repository' unless status.success?
+
+      @repository_prefix = prefix.delete_suffix("\n").b
+    end
+
+    def stream
+      argv = GitCommand.argv(@root, '-c', 'log.showSignature=false', 'log', 'HEAD',
+                             '--since=365 days ago', '--root', '--raw', '-z', '--no-renames',
+                             '--no-relative', '--no-ext-diff', '--encoding=UTF-8',
+                             '--diff-merges=first-parent', "--format=#{FORMAT}")
+      Open3.popen3(*argv) do |stdin, stdout, stderr, wait|
+        stdin.close
+        stdout.binmode
+        # Drain stderr without retaining a potentially unbounded diagnostic.
+        drain = Thread.new { stderr.read(16_384) until stderr.eof? }
+        begin
+          yield stdout
+          raise ReadError, "history command exited #{wait.value.exitstatus}" unless wait.value.success?
+        ensure
+          stdout.close
+          drain.join
+        end
+      end
+    end
+
+    def token(io)
+      value = io.gets("\0")
+      return nil unless value
+      raise ReadError, 'unterminated history record' unless value.end_with?("\0")
+
+      value.delete_suffix("\0")
+    end
+
+    def parse(io, requested, result, recent_after)
+      commit = nil
+      while (field = token(io))
+        next if field.empty?
+
+        if field.match?(/\A[0-9a-f]{40}(?:[0-9a-f]{24})?\z/)
+          commit = read_commit(io, field, recent_after)
+        elsif field.match?(/\A\n?:[0-7]{6} [0-7]{6} [0-9a-f]+ [0-9a-f]+ [A-Z]\z/)
+          record_path(io, requested, result, commit)
+        else
+          raise ReadError, 'unexpected history record'
+        end
+      end
+    end
+
+    def read_commit(io, sha, recent_after)
+      author, date, message = Array.new(3) { token(io) }
+      raise ReadError, 'incomplete commit header' unless author && date && message
+
+      { sha: sha, author: author.force_encoding(Encoding::UTF_8),
+        date: date, message: message.force_encoding(Encoding::UTF_8), recent: Time.iso8601(date) > recent_after }
+    end
+
+    def record_path(io, requested, result, commit)
+      path = token(io)
+      raise ReadError, 'incomplete path record' unless commit && path
+
+      relative = requested[path]
+      record(result[relative], commit) if relative
+    end
+
+    def record(data, commit)
+      data[:last_modified] ||= commit[:date]
+      data[:last_author] ||= commit[:author]
+      data[:commit_count] = data.fetch(:commit_count, 0) + 1
+      data[:recent_count] = data.fetch(:recent_count, 0) + (commit[:recent] ? 1 : 0)
+      commits = (data[:commits] ||= [])
+      commits << commit if commits.size < 5
+      (data[:contributors] ||= Hash.new(0))[commit[:author]] += 1
+    end
+  end
+end