woods 1.6.1 → 2.0.0.beta2

data/lib/woods/extractors/job_extractor.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require_relative 'reference_patterns'
 require_relative 'shared_utility_methods'
 require_relative 'shared_dependency_scanner'
 
@@ -52,22 +53,36 @@ module Woods
         end
 
         # Also try class-based discovery for ActiveJob
-        if defined?(ApplicationJob)
-          seen = units.to_set(&:identifier)
-          ApplicationJob.descendants.each do |job_class|
-            next if seen.include?(job_class.name)
-
-            unit = extract_job_class(job_class)
-            if unit
-              units << unit
-              seen << unit.identifier
-            end
+        seen = units.to_set(&:identifier)
+        discoverable_classes.each do |job_class|
+          next if seen.include?(job_class.name)
+
+          unit = extract_job_class(job_class)
+          if unit
+            units << unit
+            seen << unit.identifier
           end
         end
 
         units.compact
       end
 
+      # Job classes the runtime vouches for beyond the job-directory scan:
+      # every named ApplicationJob descendant. A job nested inside a class
+      # that lives elsewhere (a model file) is reachable only this way.
+      #
+      # Shared with the incremental path, which re-extracts a job by class
+      # when re-deriving it from its file names a different constant — the
+      # file's governed name is then the enclosing class, not the job.
+      #
+      # @return [Array<Class>] named ApplicationJob descendants, or [] when
+      #   the app defines no ApplicationJob
+      def discoverable_classes
+        return [] unless defined?(ApplicationJob)
+
+        ApplicationJob.descendants.reject { |job_class| job_class.name.nil? }
+      end
+
       # Extract a job from its file
       #
       # @param file_path [String] Path to the job file
@@ -130,11 +145,9 @@ module Woods
       # ──────────────────────────────────────────────────────────────────────
 
       def extract_class_name(file_path, source)
-        # Try to extract from source
-        return ::Regexp.last_match(1) if source =~ /^\s*class\s+([\w:]+)/
-
-        # Fall back to convention
-        file_path
+        # Zeitwerk-governed naming (G-1), then position-aware (#174), then
+        # convention.
+        governed_class_name(file_path, source) || qualified_first_class_name(source) || file_path
           .sub("#{Rails.root}/", '')
           .sub(%r{^app/(jobs|workers|sidekiq)/}, '')
           .sub('.rb', '')
@@ -150,18 +163,27 @@ module Woods
           source.match?(/def perform/)
       end
 
-      # Locate the source file for a job class.
+      # Locate the source file for a job class (class-discovery path only).
       #
       # Convention path first, then introspection via {#resolve_source_location}
       # which filters out vendor/node_modules paths.
       #
+      # Returns nil rather than a fabricated convention path when nothing
+      # resolves — the GraphQL precedent (B-070/#171). `ApplicationJob.descendants`
+      # includes gem- and engine-defined classes; registering
+      # `app/jobs/<name>.rb` for one puts a nonexistent, rule-claimed path in
+      # the graph's file_map, and the next incremental run's safety-net sweep
+      # prunes the unit a full extraction still emits (EXTA-3). A nil path
+      # never enters file_map, so the sweep cannot reach it;
+      # {#extract_job_class} already reads source only when the path exists.
+      #
       # @param job_class [Class]
       # @return [String, nil]
       def source_file_for(job_class)
         convention_path = Rails.root.join("app/jobs/#{job_class.name.underscore}.rb").to_s
         return convention_path if File.exist?(convention_path)
 
-        resolve_source_location(job_class, app_root: Rails.root.to_s, fallback: convention_path)
+        resolve_source_location(job_class, app_root: Rails.root.to_s, fallback: nil)
       end
 
       # ──────────────────────────────────────────────────────────────────────
@@ -262,8 +284,13 @@ module Woods
       def extract_retry_config(source)
         config = {}
 
-        # ActiveJob retry_on
-        source.scan(/retry_on\s+(\w+)(?:,\s*wait:\s*([^,\n]+))?(?:,\s*attempts:\s*(\d+))?/) do |error, wait, attempts|
+        # ActiveJob retry_on. The error capture spans `::` (matching the
+        # sibling `extract_retry_on`): `\w+` alone recorded `Net` for
+        # `Net::OpenTimeout` and, because the wait/attempts tail is matched
+        # against the same token run, dropped both of them (EXTA-10).
+        source.scan(
+          /retry_on\s+(\w+(?:::\w+)*)(?:,\s*wait:\s*([^,\n]+))?(?:,\s*attempts:\s*(\d+))?/
+        ) do |error, wait, attempts|
           config[:retry_on] ||= []
           config[:retry_on] << {
             error: error,
@@ -359,12 +386,15 @@ module Woods
 
       # Scan source for job class enqueue calls and return the list of enqueued job names.
       #
+      # Shares {ReferencePatterns::JOB_ENQUEUE} with the scanner and
+      # CallbackAnalyzer so all three sites agree on what an enqueue looks
+      # like — `*Worker` classes and namespaced jobs included (EXTA-2/EXTA-4).
+      #
       # @param source [String] The job source code
       # @param current_class_name [String, nil] The current job class name (excluded from results)
       # @return [Array<String>] Unique list of enqueued job class names
       def extract_enqueued_jobs(source, current_class_name = nil)
-        pattern = /(\w+Job)\.(?:perform_later|perform_async|perform_in|perform_at|set\b)/
-        job_names = source.scan(pattern).flatten.uniq
+        job_names = source.scan(ReferencePatterns::JOB_ENQUEUE).flatten.uniq
         job_names.reject { |name| name == current_class_name }
       end
     end

data/lib/woods/extractors/lib_extractor.rb

@@ -2,6 +2,7 @@
 
 require_relative 'shared_utility_methods'
 require_relative 'shared_dependency_scanner'
+require_relative 'source_nesting'
 
 module Woods
   module Extractors
@@ -32,6 +33,7 @@ module Woods
     class LibExtractor
       include SharedUtilityMethods
       include SharedDependencyScanner
+      include SourceNesting
 
       # Root directory to scan
       LIB_DIRECTORY = 'lib'
@@ -107,10 +109,14 @@ module Woods
 
       # Infer the primary constant name from source or fall back to file path.
       #
-      # For files with a class definition, combines outer module namespaces
-      # with the class name. For module-only files, uses the outermost module
-      # name (joined with inner modules). Falls back to path-based camelize
-      # when neither is present.
+      # For files with a class definition, the position-aware nesting scan
+      # (SourceNesting) qualifies the first `class` declaration with the
+      # modules actually open at that position — a helper module nested
+      # inside the class, or a sibling module that closed before the class
+      # opened, no longer pollutes the identifier (#174). For module-only
+      # files, uses the outer module chain (namespace wrappers joined),
+      # ignoring inner modules declared after body content. Falls back to
+      # path-based camelize when neither is present.
       #
       # @param file_path [String] Absolute path to the file
       # @param source [String] Ruby source code
@@ -118,19 +124,19 @@ module Woods
       def infer_class_name(file_path, source)
         return nil if source.strip.empty?
 
-        # Class definition — combine outer modules + class name
-        class_match = source.match(/^\s*class\s+([\w:]+)/)
-        if class_match
-          base = class_match[1]
-          return base if base.include?('::')
-
-          namespaces = source.scan(/^\s*module\s+([\w:]+)/).flatten
-          return namespaces.any? ? "#{namespaces.join('::')}::#{base}" : base
-        end
-
-        # Module-only file — use the outermost module chain
-        modules = source.scan(/^\s*module\s+([\w:]+)/).flatten
-        return modules.join('::') if modules.any?
+        # Class definition — Zeitwerk-governed naming first (G-1), then the
+        # position-aware nesting scan, which qualifies the first `class`
+        # declaration with the modules actually open at that position — a
+        # helper module nested inside the class, or a sibling module that
+        # closed before the class opened, no longer pollutes the identifier
+        # (#174). lib/ files are typically unmanaged, so the governed lookup
+        # returns nil and the source scan decides.
+        qualified = governed_class_name(file_path, source) || qualified_first_class_name(source)
+        return qualified if qualified
+
+        # Module-only file — the outer module chain
+        module_name = qualified_outer_module_name(source)
+        return module_name if module_name
 
         # Fall back to path-based naming
         path_based_class_name(file_path)

data/lib/woods/extractors/line_neutralizer.rb

@@ -0,0 +1,171 @@
+# frozen_string_literal: true
+
+module Woods
+  module Extractors
+    # Quote-aware line preprocessing shared by Woods' line-based parsers.
+    #
+    # Several extractors (and the chunkers' sibling heuristic) classify a line
+    # by matching keywords against it: does it open a block, does it close one,
+    # does it declare a constant. Run against raw source those matchers read
+    # prose as code — `x.to_s # pad for display` opens a `for` block that
+    # nothing closes, `title { "things to do" }` opens a `do` block, and
+    # `module Api # rename at the end` looks self-terminated because the
+    # comment ends in the word "end".
+    #
+    # This module centralizes the walker that removes those false signals. The
+    # quote-aware comment stripper originated in
+    # {SharedDependencyScanner#strip_line_comment}; the string-blanking and
+    # heredoc-aware variants are the same walk with the literal bodies erased.
+    #
+    # Known limitations (deliberate — this is a scanner, not a parser):
+    # `%`-literals (`%w[]`, `%q{}`), regular-expression literals, and character
+    # literals whose char is a quote (`?'`) are not modeled. Mis-reading one
+    # only risks an unstripped comment or an over-blanked line, never a crash.
+    #
+    # @example Neutralizing a line before a block-opener check
+    #   LineNeutralizer.neutralize_line('title { "things to do" } # for now')
+    #   # => "title { \"              \" } "
+    #
+    module LineNeutralizer
+      # Start of a heredoc: `<<~SQL`, `<<-EOS`, `<<'RAW'`, `<<~"TEXT"`.
+      # The bare (unquoted) form requires the identifier to follow `<<`
+      # immediately and start uppercase, which is how Ruby itself
+      # distinguishes `x <<HEREDOC` from the `<<` shift operator.
+      HEREDOC_START = /<<[~-]?(?:(["'`])([A-Za-z_]\w*)\1|([A-Z_]\w*))/
+
+      module_function
+
+      # Strip a trailing `#` comment from a single line, ignoring `#`
+      # characters inside string literals. Preserves the trailing newline.
+      #
+      # @param line [String]
+      # @return [String]
+      def strip_line_comment(line)
+        walk(line, blank_strings: false).first
+      end
+
+      # Strip a trailing `#` comment AND blank the contents of string
+      # literals, so keywords inside prose cannot be read as code. The
+      # delimiters survive (`"…"` stays a string-shaped token); only the
+      # bytes between them become spaces. Preserves the trailing newline.
+      #
+      # @param line [String]
+      # @return [String]
+      def neutralize_line(line)
+        walk(line, blank_strings: true).first
+      end
+
+      # Remove `#` line comments from a whole source without touching `#`
+      # characters inside string literals.
+      #
+      # @param source [String] Ruby source code
+      # @return [String]
+      def strip_comments(source)
+        source.each_line.map { |line| strip_line_comment(line) }.join
+      end
+
+      # Neutralize a whole source line by line, additionally blanking heredoc
+      # bodies (which a single-line walk cannot see). The result has exactly
+      # as many lines as the input, so callers can index the two in lockstep:
+      # match keywords against the neutralized line, read content from the
+      # original.
+      #
+      # @param source [String] Ruby source code
+      # @return [Array<String>] One neutralized line per input line
+      def neutralize_lines(source)
+        pending = []
+
+        source.each_line.map do |line|
+          if pending.any?
+            pending.shift if heredoc_terminator?(line, pending.first)
+            blank_line(line)
+          else
+            neutralized, heredocs = walk(line, blank_strings: true)
+            pending.concat(heredocs)
+            neutralized
+          end
+        end
+      end
+
+      # Walk one line tracking string state.
+      #
+      # @param line [String]
+      # @param blank_strings [Boolean] Replace literal bodies with spaces
+      # @return [Array(String, Array<String>)] Processed line and the heredoc
+      #   identifiers the line opens
+      def walk(line, blank_strings:)
+        out = +''
+        heredocs = []
+        quote = nil
+        index = 0
+        length = line.length
+
+        while index < length
+          char = line[index]
+
+          if quote
+            if char == '\\'
+              pair = line[index, 2].to_s
+              out << (blank_strings ? blank(pair) : pair)
+              index += 2
+              next
+            end
+
+            quote = nil if char == quote
+            out << (quote && blank_strings ? blank(char) : char)
+          elsif char == '#'
+            break
+          elsif char == '<' && (heredoc = match_heredoc(line, index))
+            heredocs << (heredoc[2] || heredoc[3])
+            out << heredoc[0]
+            index += heredoc[0].length
+            next
+          else
+            quote = char if ['"', "'"].include?(char)
+            out << char
+          end
+
+          index += 1
+        end
+
+        out << "\n" if index < length && line.end_with?("\n")
+        [out, heredocs]
+      end
+      private_class_method :walk
+
+      # Replace every character with a space, keeping newlines so a
+      # neutralized line still ends where the original did.
+      #
+      # @param text [String]
+      # @return [String]
+      def blank(text)
+        text.gsub(/[^\n]/, ' ')
+      end
+      private_class_method :blank
+
+      # @param line [String]
+      # @param index [Integer] Offset of the `<` character
+      # @return [MatchData, nil] Heredoc opener anchored at +index+
+      def match_heredoc(line, index)
+        match = HEREDOC_START.match(line, index)
+        match if match && match.begin(0) == index
+      end
+      private_class_method :match_heredoc
+
+      # @param line [String]
+      # @param identifier [String] Heredoc terminator being waited on
+      # @return [Boolean]
+      def heredoc_terminator?(line, identifier)
+        line.strip == identifier
+      end
+      private_class_method :heredoc_terminator?
+
+      # @param line [String]
+      # @return [String] The line's newline, or an empty string
+      def blank_line(line)
+        line.end_with?("\n") ? "\n" : ''
+      end
+      private_class_method :blank_line
+    end
+  end
+end

data/lib/woods/extractors/mailer_extractor.rb

@@ -35,11 +35,19 @@ module Woods
       #
       # @return [Array<ExtractedUnit>] List of mailer units
       def extract_all
-        @mailer_base.descendants.map do |mailer|
+        discoverable_classes.map do |mailer|
           extract_mailer(mailer)
         end.compact
       end
 
+      # The mailer classes this extractor would extract from the running app.
+      # Shared with the incremental path's class reconciliation (#164).
+      #
+      # @return [Array<Class>]
+      def discoverable_classes
+        @mailer_base.descendants
+      end
+
       # Extract a single mailer
       #
       # @param mailer [Class] The mailer class

data/lib/woods/extractors/manager_extractor.rb

@@ -126,12 +126,12 @@ module Woods
         return ::Regexp.last_match(1) if source =~ /< DelegateClass\((\w+)\)/
 
         # super(model) in initialize
-        return ::Regexp.last_match(1).capitalize if source =~ /super\((\w+)\)/
+        return constant_name_for(::Regexp.last_match(1)) if source =~ /super\((\w+)\)/
 
         # @model = model; super(model) — look for param name
         if source =~ /def\s+initialize\s*\((\w+)/
           param = ::Regexp.last_match(1)
-          return param.capitalize unless %w[args options params attributes].include?(param)
+          return constant_name_for(param) unless %w[args options params attributes].include?(param)
         end
 
         # Infer from class name: OrderManager -> Order
@@ -143,6 +143,23 @@ module Woods
         inferred
       end
 
+      # Turn a local variable / parameter name into the model constant it
+      # stands for.
+      #
+      # `String#capitalize` only upcases the first character and downcases the
+      # rest, so `order_item` became `Order_item` — a constant no model has,
+      # producing a dangling dependency edge instead of one to `OrderItem`.
+      #
+      # Falls back to `capitalize` only when ActiveSupport's `camelize` is
+      # unavailable, which it never is in a booted host but can be in an
+      # isolated unit spec.
+      #
+      # @param name [String] a snake_case variable or parameter name
+      # @return [String] the camelized constant name
+      def constant_name_for(name)
+        name.respond_to?(:camelize) ? name.camelize : name.split('_').map(&:capitalize).join
+      end
+
       def detect_delegation_type(source)
         return :delegate_class if source.match?(/< DelegateClass\(/)
         return :simple_delegator if source.match?(/< SimpleDelegator/)

data/lib/woods/extractors/migration_extractor.rb

@@ -36,6 +36,7 @@ module Woods
       # DDL operations that take a table name as the first symbol argument
       TABLE_OPERATIONS = %w[
         create_table
+        change_table
         drop_table
         rename_table
         add_column
@@ -56,7 +57,12 @@ module Woods
         change_column_null
       ].freeze
 
-      # Column type methods used inside create_table blocks
+      # Block-form DDL openers whose `do |t|` body declares columns. Only
+      # `create_table` was scanned, so a `change_table :orders do |t|` block
+      # contributed neither a table nor a column (EXTB-18).
+      TABLE_BLOCK_OPENERS = '(?:create_table|change_table)'
+
+      # Column type methods used inside create_table and change_table blocks
       COLUMN_TYPE_METHODS = %w[
         string integer float decimal boolean binary text
         date datetime time timestamp
@@ -146,10 +152,15 @@ module Woods
 
       # Check whether the source defines an ActiveRecord::Migration subclass.
       #
+      # `[\w:]+`, matching {#extract_class_name}'s class-name pattern — a
+      # compact-form declaration (`class Billing::AddFoo < ...`) satisfies
+      # extract_class_name but failed the plain `\w+` here, so the file was
+      # silently skipped even though it had a resolvable identifier.
+      #
       # @param source [String] Ruby source code
       # @return [Boolean]
       def migration_class?(source)
-        source.match?(/class\s+\w+\s*<\s*ActiveRecord::Migration/)
+        source.match?(/class\s+[\w:]+\s*<\s*ActiveRecord::Migration/)
       end
 
       # ──────────────────────────────────────────────────────────────────────
@@ -260,7 +271,7 @@ module Woods
           { table: table, column: column, type: type }
         end
 
-        # t.type :column inside create_table blocks
+        # t.type :column inside create_table/change_table blocks
         extract_block_columns(source, columns)
 
         # t.column :name, :type
@@ -316,7 +327,7 @@ module Woods
           { table: table, reference: reference }
         end
 
-        # t.references :ref inside create_table blocks
+        # t.references :ref inside create_table/change_table blocks
         extract_block_references(source, refs)
 
         refs
@@ -336,14 +347,14 @@ module Woods
       # Block Column / Reference Parsing
       # ──────────────────────────────────────────────────────────────────────
 
-      # Extract t.type :column declarations inside create_table blocks.
+      # Extract t.type :column declarations inside create_table/change_table blocks.
       #
       # @param source [String] Ruby source code
       # @param columns [Array<Hash>] Accumulator array
       # @return [void]
       def extract_block_columns(source, columns)
-        # Find create_table blocks and parse t.type :column patterns
-        source.scan(/create_table\s+:(\w+).*?do\s*\|(\w+)\|(.+?)^\s*end/m).each do |table, var, block|
+        # Find create_table/change_table blocks and parse t.type :column patterns
+        source.scan(/#{TABLE_BLOCK_OPENERS}\s+:(\w+).*?do\s*\|(\w+)\|(.+?)^\s*end/m).each do |table, var, block|
           type_pattern = COLUMN_TYPE_METHODS.join('|')
           block.scan(/#{var}\.(#{type_pattern})\s+:(\w+)/).each do |type, column|
             columns << { table: table, column: column, type: type }
@@ -351,26 +362,26 @@ module Woods
         end
       end
 
-      # Extract t.column :name, :type declarations inside create_table blocks.
+      # Extract t.column :name, :type declarations inside create_table/change_table blocks.
       #
       # @param source [String] Ruby source code
       # @param columns [Array<Hash>] Accumulator array
       # @return [void]
       def extract_explicit_column_calls(source, columns)
-        source.scan(/create_table\s+:(\w+).*?do\s*\|(\w+)\|(.+?)^\s*end/m).each do |table, var, block|
+        source.scan(/#{TABLE_BLOCK_OPENERS}\s+:(\w+).*?do\s*\|(\w+)\|(.+?)^\s*end/m).each do |table, var, block|
           block.scan(/#{var}\.column\s+:(\w+)\s*,\s*:(\w+)/).each do |column, type|
             columns << { table: table, column: column, type: type }
           end
         end
       end
 
-      # Extract t.references declarations inside create_table blocks.
+      # Extract t.references declarations inside create_table/change_table blocks.
       #
       # @param source [String] Ruby source code
       # @param refs [Array<Hash>] Accumulator array
       # @return [void]
       def extract_block_references(source, refs)
-        source.scan(/create_table\s+:(\w+).*?do\s*\|(\w+)\|(.+?)^\s*end/m).each do |table, var, block|
+        source.scan(/#{TABLE_BLOCK_OPENERS}\s+:(\w+).*?do\s*\|(\w+)\|(.+?)^\s*end/m).each do |table, var, block|
           block.scan(/#{var}\.references\s+:(\w+)/).each do |reference,|
             refs << { table: table, reference: reference }
           end