woods 1.6.1 → 2.0.0.beta2

data/lib/woods/extractors/event_extractor.rb

@@ -57,7 +57,12 @@ module Woods
       # @param event_map [Hash] Mutable map of event_name => {publishers:, subscribers:, pattern:}
       # @return [void]
       def scan_file(file_path, event_map)
-        source = File.read(file_path)
+        source = cached_source(file_path)
+        unless source
+          Rails.logger.error("Failed to scan #{file_path} for events: file unreadable")
+          return
+        end
+
         scan_active_support_notifications(source, file_path, event_map)
         scan_wisper_patterns(source, file_path, event_map)
       rescue StandardError => e
@@ -97,16 +102,43 @@ module Woods
       # @return [void]
       def scan_wisper_patterns(source, file_path, event_map)
         if source.match?(/include\s+Wisper/)
-          source.scan(/\b(?:publish|broadcast)\s+:(\w+)/) do |m|
+          # `\s*\(?\s*` accepts both call styles. Requiring whitespace before
+          # the symbol missed `broadcast(:order_created, order)` — Wisper's
+          # README-canonical form — so no publisher was registered and, with
+          # no subscriber naming the event either, the event unit did not
+          # exist at all (EXTB-3). The AS::Notifications and `.on(` scans
+          # already accept parens.
+          source.scan(/\b(?:publish|broadcast)\s*\(?\s*:(\w+)/) do |m|
             register_publisher(event_map, m[0], file_path, :wisper)
           end
         end
 
+        # `.on(:sym)` is far too common a shape to treat as evidence on its own:
+        # `socket.on(:message)`, `emitter.on(:close)`, and every other
+        # callback-registration API in the ecosystem match it, each minting a
+        # phantom event unit and its edges. Publishers were already gated on
+        # Wisper context in the file; subscribers were not. Require the file to
+        # mention Wisper somewhere before believing a bare `.on`.
+        return unless wisper_context?(source)
+
         source.scan(/\.on\s*\(\s*:(\w+)/) do |m|
           register_subscriber(event_map, m[0], file_path, :wisper)
         end
       end
 
+      # Does this file give any indication it is using Wisper?
+      #
+      # Deliberately broader than the publisher gate's `include Wisper` —
+      # subscribers commonly live in files that reference Wisper without
+      # including it (`Wisper.subscribe(listener)`, `extend
+      # Wisper::Publisher`, a global-listener initializer).
+      #
+      # @param source [String] Ruby source code
+      # @return [Boolean]
+      def wisper_context?(source)
+        source.match?(/\bWisper\b/)
+      end
+
       # ──────────────────────────────────────────────────────────────────────
       # Event Map Mutation
       # ──────────────────────────────────────────────────────────────────────
@@ -179,11 +211,30 @@ module Woods
       # @param file_paths [Array<String>] File paths to read
       # @return [String] Combined source
       def load_source_files(file_paths)
-        file_paths.filter_map do |path|
+        file_paths.filter_map { |path| cached_source(path) }.join("\n")
+      end
+
+      # One read per distinct path per extractor instance (audit P2).
+      #
+      # Pass 2 ({#build_unit}) recombines the same publisher/subscriber files
+      # for every event that references them, so a widely-shared file was
+      # re-read once per event on top of the pass-1 {#scan_file} read. The
+      # bytes cannot change mid-run, so the first read answers the rest.
+      #
+      # A failed read is memoized as nil, matching the per-event skip it
+      # produced before; the output is identical either way.
+      #
+      # @param path [String] File path
+      # @return [String, nil] File contents, or nil when unreadable
+      def cached_source(path)
+        cache = (@source_files ||= {})
+        return cache[path] if cache.key?(path)
+
+        cache[path] = begin
           File.read(path)
         rescue StandardError
           nil
-        end.join("\n")
+        end
       end
 
       # Build annotated source annotation for the event unit.

data/lib/woods/extractors/factory_extractor.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require_relative 'line_neutralizer'
 require_relative 'shared_utility_methods'
 require_relative 'shared_dependency_scanner'
 
@@ -64,6 +65,13 @@ module Woods
       # transient attributes. Each factory block (including nested factories within
       # a parent factory) produces one entry in the returned array.
       #
+      # Block accounting runs against the {LineNeutralizer}-neutralized line —
+      # comment, string, and heredoc bodies blanked — while names are still
+      # read from the raw line, where their literals live. Counting keywords in
+      # raw source meant `title { "things to do" }` opened a `do` block nothing
+      # closed; two such attributes left the factory on the stack at EOF and
+      # the unit was dropped entirely (EXTB-2).
+      #
       # @param source [String] Factory file source code
       # @return [Array<Hash>] Parsed factory data hashes
       def parse_factories(source)
@@ -72,26 +80,38 @@ module Woods
         depth = 0
         in_transient = false
         transient_depth = nil
+        scannable = LineNeutralizer.neutralize_lines(source)
 
         source.lines.each_with_index do |line, index|
           stripped = line.strip
-
-          # Factory definition — push new factory onto stack
+          code = scannable[index].to_s.strip
+          next if code.empty?
+
+          # Factory definition. A factory with a block goes on the stack and is
+          # completed when its `end` brings depth back; a blockless one —
+          # `factory :admin, parent: :user` — has nothing to wait for and is
+          # complete as soon as it is parsed. Requiring a block used to drop
+          # those silently, which is the very shape the parent-inheritance
+          # parsing below exists to support.
           if (factory_data = match_factory(stripped, depth, index + 1))
-            factory_stack.push(factory_data)
-            depth += 1
+            if opens_block?(code)
+              factory_stack.push(factory_data)
+              depth += 1
+            else
+              completed << factory_data
+            end
             next
           end
 
           # Trait definition — record trait in current factory, open block
-          if (trait_match = stripped.match(/\Atrait\s+:(\w+)\s+do/))
+          if (trait_match = code.match(/\Atrait\s+:(\w+)\s+do/))
             factory_stack.last[:traits] << trait_match[1] if factory_stack.any?
             depth += 1
             next
           end
 
           # Transient block — start collecting transient attributes
-          if stripped.match?(/\Atransient\s+do/)
+          if code.match?(/\Atransient\s+do/)
             in_transient = true
             transient_depth = depth
             depth += 1
@@ -119,12 +139,12 @@ module Woods
           end
 
           # Generic block openers — factory/trait/transient already handled above with next
-          if block_opener?(stripped)
+          if block_opener?(code)
             depth += 1
             next
           end
 
-          next unless stripped == 'end'
+          next unless code == 'end'
 
           depth -= 1
 
@@ -150,13 +170,17 @@ module Woods
       #   factory :name, class: ClassName do
       #   factory :name, class: 'ClassName' do
       #   factory :name, parent: :other do
+      #   factory :name, parent: :other        # blockless
+      #
+      # Whether the line opens a block is the caller's concern — see
+      # {#parse_factories}.
       #
       # @param line [String] Stripped source line
       # @param depth [Integer] Current block depth when factory would be opened
       # @param line_number [Integer] 1-based line number
       # @return [Hash, nil] Initialized factory data or nil if not a factory line
       def match_factory(line, depth, line_number)
-        return nil unless line.match?(/\Afactory\s+:/) && line.match?(/\bdo\b/)
+        return nil unless line.match?(/\Afactory\s+:/)
 
         name_match = line.match(/\Afactory\s+:(\w+)/)
         return nil unless name_match
@@ -194,6 +218,19 @@ module Woods
         name.split('_').map(&:capitalize).join
       end
 
+      # Does this factory line open a `do` block?
+      #
+      # Separate from {#block_opener?}, which deliberately excludes factory
+      # lines so they can carry their own depth bookkeeping. A factory without
+      # a block (`factory :admin, parent: :user`) is complete on the line it
+      # appears and must not push a frame nothing will pop.
+      #
+      # @param stripped [String] Stripped line content
+      # @return [Boolean]
+      def opens_block?(stripped)
+        stripped.match?(/\bdo\b/)
+      end
+
       # Check if a stripped line opens a new block.
       #
       # Excludes factory, trait, and transient lines — those are handled
@@ -207,7 +244,7 @@ module Woods
         return false if stripped.match?(/\Atransient\s+do/)
         return true if stripped.match?(/\b(do|def|case|begin|class|module|while|until|for)\b.*(?<!\bend)\s*$/)
 
-        stripped.match?(/\A(if|unless)\b/)
+        stripped.match?(/(?:\A|=\s*)(?:if|unless)\b.*(?<!\bend)\s*$/)
       end
 
       # Build an ExtractedUnit from parsed factory data.
@@ -254,7 +291,8 @@ module Woods
           sequences: factory_data[:sequences],
           parent_factory: factory_data[:parent_factory],
           callbacks: factory_data[:callbacks].uniq,
-          transient_attributes: factory_data[:transient_attributes]
+          transient_attributes: factory_data[:transient_attributes],
+          line_number: factory_data[:line_number]
         }
       end
 

data/lib/woods/extractors/graphql_extractor.rb

@@ -2,6 +2,7 @@
 
 require_relative 'shared_utility_methods'
 require_relative 'shared_dependency_scanner'
+require_relative 'source_nesting'
 
 module Woods
   module Extractors
@@ -30,6 +31,7 @@ module Woods
     class GraphQLExtractor
       include SharedUtilityMethods
       include SharedDependencyScanner
+      include SourceNesting
 
       # Standard directory for graphql-ruby applications
       GRAPHQL_DIRECTORY = 'app/graphql'
@@ -43,14 +45,46 @@ module Woods
         @runtime_types = load_runtime_types
       end
 
+      # The type classes runtime introspection can reach.
+      #
+      # Shared with the incremental path's class reconciliation (#167), which
+      # uses it for **additions only**. A runtime-defined type — built by a
+      # schema builder or a DSL rather than a literal `class ... <
+      # Types::BaseObject` — has no source file, so no changed path ever
+      # dispatches to it and `extract_graphql_file` cannot reproduce it. Only a
+      # full extraction emitted such units, which meant an incremental run
+      # could never create them and an index built incrementally from empty
+      # never had them at all.
+      #
+      # Empty when graphql-ruby is not loaded or the app has no schema, which is
+      # why the reconciliation must not read absence here as deletion — see
+      # `reconcile_removals: false` in {Extractor::CLASS_BASED_DISCOVERY}.
+      #
+      # @return [Array<Class>]
+      def discoverable_classes
+        @runtime_types.values.reject { |type_class| type_class.name.nil? }
+      end
+
       # Extract all GraphQL types, mutations, queries, and resolvers
       #
-      # Returns an empty array if graphql-ruby is not installed or
-      # no GraphQL files are found.
+      # Returns an empty array when the app has neither an `app/graphql`
+      # directory nor a loadable schema class.
+      #
+      # Deliberately **not** gated on graphql-ruby being loaded. The file pass
+      # is static — a regex over source plus a `safe_constantize` that is
+      # allowed to fail — so it works perfectly well without the gem, and
+      # `app/graphql/*.rb` is real source an agent wants indexed either way.
+      # Gating it produced a genuine full-vs-incremental divergence: the
+      # `PathDispatcher` rule routes those paths at `extract_graphql_file`,
+      # which never had the gate, so an app whose GraphQL gem was not loaded at
+      # extraction time got its types indexed incrementally and dropped by a
+      # full run. Runtime introspection stays optional and additive — it makes
+      # the units richer when the gem is there, it does not decide whether they
+      # exist.
       #
       # @return [Array<ExtractedUnit>] List of GraphQL units
       def extract_all
-        return [] unless graphql_available?
+        return [] unless graphql_source_present?
 
         units = []
         seen_identifiers = Set.new
@@ -94,8 +128,14 @@ module Woods
         return nil unless class_name
         return nil unless graphql_class?(source)
 
-        unit_type = classify_unit_type(file_path, source)
         runtime_class = class_name.safe_constantize
+        # Classify from the resolved runtime class first, matching
+        # {#extract_from_runtime_type}'s classifier. Keeps the two passes
+        # from disagreeing on a type's unit_type (a mutation that looks like
+        # a type by path/regex) and leaving a stale duplicate unit behind.
+        # Falls back to the source/path heuristic when nothing resolves
+        # (gem not loaded, autoloading not booted).
+        unit_type = runtime_class ? classify_runtime_type(runtime_class) : classify_unit_type(file_path, source)
 
         unit = ExtractedUnit.new(
           type: unit_type,
@@ -115,20 +155,62 @@ module Woods
         nil
       end
 
+      # Extract a unit from a runtime-loaded GraphQL type class.
+      #
+      # Public because {Extractor::CLASS_BASED_DISCOVERY} names it as the
+      # graphql entry's `method:` and the reconciler invokes it with
+      # `public_send` (#167). Private, it raised NoMethodError for every
+      # candidate — swallowed by the reconciler's `rescue StandardError` into a
+      # warn — so the incremental path silently added nothing, which is exactly
+      # what #167 set out to fix. `spec/extractor_spec.rb` asserts every
+      # CLASS_BASED_DISCOVERY method is publicly callable on its real
+      # extractor so no future entry can regress the same way.
+      #
+      # @param type_class [Class] A graphql-ruby type class
+      # @return [ExtractedUnit, nil]
+      def extract_from_runtime_type(type_class)
+        return nil unless type_class.respond_to?(:name) && type_class.name
+        # Skip anonymous or internal graphql-ruby classes
+        return nil if type_class.name.start_with?('GraphQL::')
+
+        file_path = source_file_for_class(type_class)
+        source = file_path && File.exist?(file_path) ? File.read(file_path) : ''
+        unit_type = classify_runtime_type(type_class)
+
+        unit = ExtractedUnit.new(
+          type: unit_type,
+          identifier: type_class.name,
+          file_path: file_path
+        )
+
+        unit.namespace = extract_namespace(type_class.name)
+        unit.source_code = build_annotated_source(source, type_class.name, unit_type, type_class)
+        unit.metadata = build_metadata(source, type_class.name, unit_type, type_class)
+        unit.dependencies = extract_dependencies(source, type_class.name)
+        unit.chunks = build_chunks(unit, type_class) if unit.needs_chunking?(threshold: CHUNK_THRESHOLD)
+
+        unit
+      rescue StandardError => e
+        Rails.logger.error("Failed to extract GraphQL type #{type_class.name}: #{e.message}") if defined?(Rails)
+        nil
+      end
+
       private
 
       # ──────────────────────────────────────────────────────────────────────
       # Schema and Runtime Discovery
       # ──────────────────────────────────────────────────────────────────────
 
-      # Check if graphql-ruby is available at runtime
+      # Does this app have GraphQL source to extract?
+      #
+      # Note what this does *not* ask: whether graphql-ruby is loaded. See
+      # {#extract_all} — the gem enriches the units, it does not gate them.
       #
       # @return [Boolean]
-      def graphql_available?
-        return false unless defined?(GraphQL::Schema)
-        return false unless @graphql_dir&.directory? || @schema_class
+      def graphql_source_present?
+        return true if @graphql_dir&.directory?
 
-        true
+        !@schema_class.nil?
       end
 
       # Find the application's schema class (descendant of GraphQL::Schema)
@@ -164,54 +246,34 @@ module Woods
         {}
       end
 
-      # ──────────────────────────────────────────────────────────────────────
-      # Runtime Type Extraction
-      # ──────────────────────────────────────────────────────────────────────
-
-      # Extract a unit from a runtime-loaded GraphQL type class
+      # Locate the file this type was defined in, or nil when there is none.
       #
-      # @param type_class [Class] A graphql-ruby type class
-      # @return [ExtractedUnit, nil]
-      def extract_from_runtime_type(type_class)
-        return nil unless type_class.respond_to?(:name) && type_class.name
-        # Skip anonymous or internal graphql-ruby classes
-        return nil if type_class.name.start_with?('GraphQL::')
-
-        file_path = source_file_for_class(type_class)
-        source = file_path && File.exist?(file_path) ? File.read(file_path) : ''
-        unit_type = classify_runtime_type(type_class)
-
-        unit = ExtractedUnit.new(
-          type: unit_type,
-          identifier: type_class.name,
-          file_path: file_path
-        )
-
-        unit.namespace = extract_namespace(type_class.name)
-        unit.source_code = build_annotated_source(source, type_class.name, unit_type, type_class)
-        unit.metadata = build_metadata(source, type_class.name, unit_type, type_class)
-        unit.dependencies = extract_dependencies(source, type_class.name)
-        unit.chunks = build_chunks(unit, type_class) if unit.needs_chunking?(threshold: CHUNK_THRESHOLD)
-
-        unit
-      rescue StandardError => e
-        Rails.logger.error("Failed to extract GraphQL type #{type_class.name}: #{e.message}") if defined?(Rails)
-        nil
-      end
-
-      # Determine the source file for a runtime-loaded class, validating that
-      # paths are within Rails.root to avoid returning graphql gem internals.
+      # nil, not a fabricated convention path. A runtime-defined type
+      # (built by a schema builder or DSL) has no file, and inventing
+      # `app/graphql/<constant>.rb` for it created a unit indistinguishable from a
+      # file-defined one whose file had since been deleted. That ambiguity is
+      # unresolvable downstream: the conventional location of `Types::FooType`
+      # *is* `app/graphql/types/foo_type.rb`, so no path comparison can separate
+      # "never had a file" from "file was deleted".
       #
-      # Convention path first, then introspection via {#resolve_source_location}
-      # which filters out vendor/node_modules paths.
+      # Returning nil resolves it at the only point where the answer is known.
+      # `DependencyGraph#register` skips nil paths, so such a unit never enters
+      # `file_map` and the deletion sweep — which walks registered paths — cannot
+      # reach it. No predicate required, and a full extraction produces the same
+      # nil, so the two paths still agree.
+      #
+      # `resolve_source_location` is tried first and has three tiers of real
+      # discovery (`const_source_location`, then instance and singleton method
+      # locations). It reaches its fallback only when Ruby cannot place the class
+      # in app source at all, which is precisely the no-file case.
       #
       # @param klass [Class]
-      # @return [String] Absolute path to the source file
+      # @return [String, nil]
       def source_file_for_class(klass)
         convention_path = Rails.root.join("#{GRAPHQL_DIRECTORY}/#{klass.name.underscore}.rb").to_s
         return convention_path if File.exist?(convention_path)
 
-        resolve_source_location(klass, app_root: Rails.root.to_s, fallback: convention_path)
+        resolve_source_location(klass, app_root: Rails.root.to_s, fallback: nil)
       end
 
       # ──────────────────────────────────────────────────────────────────────
@@ -286,19 +348,32 @@ module Woods
 
       # Extract the fully-qualified class name from source or file path
       #
+      # The identifier is the *outermost* class: the first `class` declaration
+      # qualified by the modules actually open at that position, via the
+      # position-aware nesting scanner ({SourceNesting}, #174). Declarations
+      # after the first `class` are nested — joining every declaration in the
+      # file made a mutation with an inner `class InvalidInput < StandardError`
+      # identify as `Mutations::CreateUser::InvalidInput`, so the file-pass
+      # unit never deduped against the runtime unit in {#extract_all}:
+      # double-indexing with graphql-ruby loaded, dangling edges without it
+      # (#202). Tracking nesting by position also stops a sibling module that
+      # closed *before* the class opened from polluting the prefix — the old
+      # end-blind scan turned `module Helpers ... end; module Mutations; class
+      # CreateUser` into `Helpers::Mutations::CreateUser`. Module-only files
+      # (e.g. interfaces) keep their identifier via the outer module chain.
+      #
       # @param file_path [String]
       # @param source [String]
       # @return [String, nil]
       def extract_class_name(file_path, source)
-        # Build from nested module/class declarations
-        modules = source.scan(/^\s*(?:module|class)\s+([\w:]+)/).flatten
-        return nil if modules.empty?
-
-        # If first token is a fully-qualified name, use it directly
-        return modules.first if modules.first.include?('::')
-
-        # Otherwise join the nesting
-        modules.join('::')
+        # Zeitwerk-governed naming first (G-1) — managed graphql/ files are
+        # named for the constant their path spells, and the expected path can
+        # only match the outer, file-named declaration, so the #202
+        # outermost-class contract below is preserved by construction. Then
+        # the position-aware nesting scan (#174), then the outer module
+        # chain for module-only files (interfaces).
+        governed_class_name(file_path, source) ||
+          qualified_first_class_name(source) || qualified_outer_module_name(source)
       rescue StandardError
         # Fall back to convention from file path
         return nil unless defined?(Rails)
@@ -636,13 +711,20 @@ module Woods
       def extract_complexity(source)
         complexities = []
 
-        source.scan(/field\s+:(\w+).*?complexity:\s*(\d+|->.*?(?:end|\}))/m) do |name, value|
+        # `[^\n]*?` keeps the field name and its `complexity:` on one
+        # declaration line. With `.*?` under /m the match crossed
+        # declarations, so a field with no complexity absorbed the *next*
+        # field's — and the real owner lost it, because `scan` resumes after
+        # the match (EXTB-8). The lambda value may still span lines.
+        source.scan(/field\s+:(\w+)[^\n]*?complexity:\s*(\d+|->.*?(?:end|\}))/m) do |name, value|
           complexities << { field: name, complexity: value.strip }
         end
 
-        # Max complexity on schema level
-        if source.match?(/max_complexity\s+(\d+)/)
-          complexities << { field: :schema, complexity: ::Regexp.last_match(1).to_i }
+        # Max complexity on schema level. `match`, not `match?` — the latter
+        # never populates `$~`/`Regexp.last_match`, so the capture always
+        # read back as 0 (or a stale match from elsewhere in the method).
+        if (schema_match = source.match(/max_complexity\s+(\d+)/))
+          complexities << { field: :schema, complexity: schema_match[1].to_i }
         end
 
         complexities
@@ -750,15 +832,29 @@ module Woods
           deps << { type: :model, target: model_ref, via: :code_reference }
         end
 
-        source.scan(/\b([A-Z][a-z][a-zA-Z]*)\b/).flatten.uniq.each do |const_ref|
+        # The per-constant follow-up check used to run one full-source scan
+        # for every unique capitalized constant (audit P9c). One combined
+        # scan collects the constants that are actually followed by a model
+        # call; only the exact word at a position can match (each candidate
+        # is a maximal word in this source and `\.` must immediately follow),
+        # so the collected set is identical. Candidate order drives emission
+        # below, unchanged.
+        candidates = source.scan(/\b([A-Z][a-z][a-zA-Z]*)\b/).flatten.uniq
+        model_callers = if candidates.empty?
+                          {}
+                        else
+                          source.scan(
+                            /\b(#{candidates.map { |c| Regexp.escape(c) }.join('|')})\.(?:find|where|find_by|create|new|first|last|all)\b/
+                          ).flatten.to_h { |const| [const, true] }
+                        end
+
+        candidates.each do |const_ref|
           if const_ref.match?(/\A(Types|Mutations|Resolvers|GraphQL|Base|String|Integer|Float|Boolean|Array|Hash|Set|Struct|Module|Class|Object|ID|Int|ISO8601)\z/)
             next
           end
           next if deps.any? { |d| d[:target] == const_ref }
 
-          if source.match?(/\b#{Regexp.escape(const_ref)}\.(?:find|where|find_by|create|new|first|last|all)\b/)
-            deps << { type: :model, target: const_ref, via: :code_reference }
-          end
+          deps << { type: :model, target: const_ref, via: :code_reference } if model_callers.key?(const_ref)
         end
 
         deps.concat(scan_service_dependencies(source))

data/lib/woods/extractors/i18n_extractor.rb

@@ -45,7 +45,12 @@ module Woods
       # @return [ExtractedUnit, nil] The extracted unit or nil on failure
       def extract_i18n_file(file_path)
         source = File.read(file_path)
-        data = YAML.safe_load(source, permitted_classes: [Symbol, Date, Time, Regexp])
+        # aliases: true — locale files commonly share defaults via anchors
+        # (`<<: *defaults`); without it Psych 4+ raises AliasesNotEnabled and
+        # the whole file is silently dropped (#203). Alias expansion only
+        # re-references the scalar/hash types already permitted, so it adds
+        # no deserialization risk.
+        data = YAML.safe_load(source, permitted_classes: [Symbol, Date, Time, Regexp], aliases: true)
 
         return nil unless data.is_a?(Hash) && data.any?