fast_cov 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c1319e05ab0d7a740626e94ed880dacb09b980dfc0ededc6b1c0259383fb0667
-  data.tar.gz: dd7af260d917264ab2f30affbc3dd2dfa44f5ddba03bc8d1f8dd222e29a9817e
+  metadata.gz: 4a8e169598d457f54b52e872c65d55a9e87164bcac66654d7b21d9497aeba43a
+  data.tar.gz: 678150e27c7fb664bc5786764b063c1abb75218048f226b39495bc97c012ce75
 SHA512:
-  metadata.gz: 6b594da4510ba6bb43767030b4d25e3f7787e22923b6e76b48616f2a085c030d22c1d870976570f7ac74fe921fe2c1eabbeeb16471ec8a533588f9d5b9974fef
-  data.tar.gz: 98f1b25e2565a56af55e472096a4c3159110b27117b99682cd031888083ec68d5aef8788aeff7a2538af9a5287f588653f8717ee30160e1126f127a0316191ea
+  metadata.gz: 68e671eab2e3583313b60e408f179006d77aa0d571d1b258b971916b38642fcedae05b8b728ff0588000bd69ada0183a3502b8f6b4e90a37fda3847be3dd6fcd
+  data.tar.gz: d4531b99a2ca2cfb1a566f63bed51444a91bedfd0356a33d50101f18aafa0020ed40d652199de538cb351c6ac2e5e6a7185c1a3aaef316bc444779767a19ad23

data/README.md

@@ -121,6 +121,48 @@ cov = FastCov::Coverage.new(
 
 This API is mainly useful for internal use and low-level tests. `CoverageMap` is the intended public orchestration API.
 
+## StaticMap
+
+`FastCov::StaticMap` is a build-time API for static dependency mapping. It parses Ruby files with Prism, resolves literal constant references, and builds a direct dependency graph. Transitive closures are computed lazily on demand.
+
+```ruby
+static_map = FastCov::StaticMap.new(root: Rails.root)
+static_map.build("spec/**/*_spec.rb")
+
+# Direct dependencies for a single file
+static_map.dependencies("/app/spec/models/user_spec.rb")
+# => ["/app/app/models/user.rb"]
+
+# Transitive closure (computed and cached on first call)
+static_map.transitive_dependencies("/app/spec/models/user_spec.rb")
+# => ["/app/app/models/account.rb", "/app/app/models/user.rb"]
+
+# Raw direct graph
+static_map.direct_graph
+# => { "/app/spec/models/user_spec.rb" => ["/app/app/models/user.rb"], ... }
+```
+
+The instance caches constant resolution results, so reusing the same instance across multiple `build` calls is efficient.
+
+#### Options
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `root` | String or Pathname | required | Absolute project root. Only resolved files under this path are included. |
+| `ignored_paths` | String or Array<String> | `[]` | Files or directories to exclude from the graph and recursive traversal. |
+| `*patterns` (on `build`) | String(s) or Array | required | File paths or globs to traverse. Relative paths are expanded against `root`. |
+
+#### How it works
+
+- `build` traverses reachable files and stores a direct dependency graph
+- `dependencies` returns direct dependencies for a file
+- `transitive_dependencies` computes and caches the transitive closure lazily
+- Constant resolution results are cached and reused across `build` calls
+- Resolves each reference from most-specific lexical candidate to least-specific
+- Uses `const_defined?` and `const_source_location` to resolve literal constant references to source files
+
+This is intended for a booted application process. It requires constants to be eager-loaded. It will not see dynamic constant lookups that are not expressed as literal constants in the source.
+
 ## Writing custom trackers
 
 There are two approaches: a minimal custom tracker, or inheriting from `AbstractTracker`.
@@ -167,7 +209,7 @@ class MyTracker < FastCov::AbstractTracker
 
   module MyPatch
     def some_method(...)
-      MyTracker.record(some_file_path)
+      MyTracker.record { some_file_path }
       super
     end
   end

data/lib/fast_cov/coverage_map.rb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require "pathname"
-
 module FastCov
   class CoverageMap
     class ConfigurationError < StandardError; end
@@ -54,11 +52,21 @@ module FastCov
       self
     end
 
-    def start
-      if @started
-        raise "CoverageMap is already started" if block_given?
-        return self
+    def build
+      raise ArgumentError, "build requires a block" unless block_given?
+      raise "CoverageMap is already started" if @started
+
+      start
+      begin
+        yield
+      ensure
+        result = stop
       end
+      result
+    end
+
+    def start
+      return self if @started
 
       begin
         @native_coverage = Coverage.new(
@@ -74,17 +82,7 @@ module FastCov
         raise
       end
 
-      if block_given?
-        result = nil
-        begin
-          yield
-        ensure
-          result = stop
-        end
-        result
-      else
-        self
-      end
+      self
     end
 
     def stop
@@ -144,7 +142,7 @@ module FastCov
     end
 
     def absolute_path?(path)
-      Pathname.new(path).absolute?
+      File.absolute_path?(path)
     end
 
     def normalize_path(path)

data/lib/fast_cov/static_map/reference_extractor.rb

@@ -0,0 +1,156 @@
+# frozen_string_literal: true
+
+require "prism"
+
+module FastCov
+  class StaticMap
+    module ReferenceExtractor
+      class << self
+        def extract(filename)
+          result = Prism.parse_file(filename)
+          return FastCov::StaticMap::EMPTY_ARRAY unless result.success?
+
+          reference_groups = []
+          seen_groups = {}
+          collect_constants(result.value, reference_groups, seen_groups, [])
+
+          reference_groups.map do |group|
+            group.map { |const_name| -const_name }.freeze
+          end.freeze
+        end
+
+        private
+
+        def collect_constants(node, reference_groups, seen_groups, nesting_prefixes)
+          case node
+          when Prism::ModuleNode
+            module_name = constant_name_for_nesting(node.constant_path)
+            next_prefixes = next_nesting_prefixes(nesting_prefixes, module_name)
+            node.body&.compact_child_nodes&.each do |child|
+              collect_constants(child, reference_groups, seen_groups, next_prefixes)
+            end
+            return
+          when Prism::ClassNode
+            class_name = constant_name_for_nesting(node.constant_path)
+            next_prefixes = next_nesting_prefixes(nesting_prefixes, class_name)
+            add_with_nesting(node.superclass, reference_groups, seen_groups, nesting_prefixes) if node.superclass
+            node.body&.compact_child_nodes&.each do |child|
+              collect_constants(child, reference_groups, seen_groups, next_prefixes)
+            end
+            return
+          when Prism::SingletonClassNode
+            node.body&.compact_child_nodes&.each do |child|
+              collect_constants(child, reference_groups, seen_groups, nesting_prefixes)
+            end
+            return
+          when Prism::ConstantPathNode
+            add_with_nesting(node, reference_groups, seen_groups, nesting_prefixes)
+            return
+          when Prism::ConstantReadNode
+            add_reference_group(
+              expand_with_nesting(node.name.to_s, nesting_prefixes),
+              reference_groups,
+              seen_groups
+            )
+            return
+          end
+
+          node.compact_child_nodes.each do |child|
+            collect_constants(child, reference_groups, seen_groups, nesting_prefixes)
+          end
+        end
+
+        def add_with_nesting(node, reference_groups, seen_groups, nesting_prefixes)
+          candidates = candidates_for_node(node, nesting_prefixes)
+          add_reference_group(candidates, reference_groups, seen_groups)
+        end
+
+        def candidates_for_node(node, nesting_prefixes)
+          case node
+          when Prism::ConstantPathNode
+            path = resolve_constant_path(node)
+            return FastCov::StaticMap::EMPTY_ARRAY unless path
+
+            if path.start_with?("::")
+              [path.delete_prefix("::")]
+            else
+              expand_with_nesting(path, nesting_prefixes)
+            end
+          when Prism::ConstantReadNode
+            expand_with_nesting(node.name.to_s, nesting_prefixes)
+          else
+            FastCov::StaticMap::EMPTY_ARRAY
+          end
+        end
+
+        def add_reference_group(candidates, reference_groups, seen_groups)
+          return if candidates.empty?
+
+          key = candidates.join("\0")
+          return if seen_groups[key]
+
+          seen_groups[key] = true
+          reference_groups << candidates
+        end
+
+        def expand_with_nesting(const_name, nesting_prefixes)
+          candidates = []
+          seen_candidates = {}
+
+          nesting_prefixes.reverse_each do |prefix|
+            add_unique("#{prefix}::#{const_name}", candidates, seen_candidates)
+          end
+
+          add_unique(const_name, candidates, seen_candidates)
+          candidates
+        end
+
+        def next_nesting_prefixes(nesting_prefixes, nested_name)
+          return nesting_prefixes unless nested_name
+
+          if nesting_prefixes.empty?
+            [nested_name]
+          else
+            nesting_prefixes + ["#{nesting_prefixes.last}::#{nested_name}"]
+          end
+        end
+
+        def constant_name_for_nesting(node)
+          case node
+          when Prism::ConstantPathNode
+            resolve_constant_path(node)&.delete_prefix("::")
+          when Prism::ConstantReadNode
+            node.name.to_s
+          end
+        end
+
+        def add_unique(const_name, constants, seen)
+          return if seen[const_name]
+
+          seen[const_name] = true
+          constants << const_name
+        end
+
+        def resolve_constant_path(node)
+          parts = []
+          current = node
+
+          while current.is_a?(Prism::ConstantPathNode)
+            parts.unshift(current.name.to_s)
+            current = current.parent
+          end
+
+          if current.is_a?(Prism::ConstantReadNode)
+            parts.unshift(current.name.to_s)
+          elsif current.nil?
+            return "::#{parts.join("::")}"
+          else
+            return nil
+          end
+
+          parts.join("::")
+        end
+      end
+    end
+  end
+end

data/lib/fast_cov/static_map.rb

@@ -0,0 +1,257 @@
+# frozen_string_literal: true
+
+module FastCov
+  class StaticMap
+    EMPTY_ARRAY = [].freeze
+
+    autoload :ReferenceExtractor, File.expand_path("static_map/reference_extractor", __dir__)
+
+    def initialize(root:, ignored_paths: [], concurrency: Etc.nprocessors)
+      @root = share_path(root)
+      @root_prefix = -"#{@root}/"
+      @ignored_paths = normalize_ignored_paths(ignored_paths)
+      @concurrency = concurrency
+      @resolved_file_by_const = {}
+      @closure_by_file = {}
+      @graph = {}
+    end
+
+    def build(*patterns)
+      input_files = expand_files(patterns.flatten).select { |file| processable_file?(file) }
+
+      queue = input_files.dup
+      processed = {}
+
+      until queue.empty?
+        to_process = queue.reject { |f| processed[f] }
+        break if to_process.empty?
+
+        to_process.each { |f| processed[f] = true }
+        queue.clear
+
+        # Stage 1: Parse files (parallel)
+        parsed = parse_files(to_process)
+
+        # Stage 2: Resolve unique constants (sequential — GVL-bound)
+        resolve_candidates(parsed)
+
+        # Stage 3: Build graph edges, discover new files
+        parsed.each do |file, groups|
+          deps = resolve_dependencies(file, groups)
+          relative_file = relativize(file)
+          @graph[relative_file] = deps.empty? ? EMPTY_ARRAY : deps.map { |d| relativize(d) }.freeze
+
+          deps.each do |dep|
+            queue << dep unless processed[dep]
+          end
+        end
+      end
+
+      input_files.flat_map { |file| dependencies(file) }.uniq
+    end
+
+    def direct_graph
+      @graph
+    end
+
+    def direct_dependencies(file)
+      @graph.fetch(relativize_input(file), EMPTY_ARRAY)
+    end
+
+    def dependencies(file)
+      file = relativize_input(file)
+      resolve_transitive_dependencies(file)
+    end
+
+    private
+
+    attr_reader :closure_by_file, :ignored_paths, :resolved_file_by_const, :root
+
+    def parse_files(files)
+      if @concurrency > 1 && files.size > 1
+        parse_files_parallel(files)
+      else
+        parse_files_sequential(files)
+      end
+    end
+
+    def parse_files_sequential(files)
+      parsed = {}
+      files.each { |f| parsed[f] = ReferenceExtractor.extract(f) }
+      parsed
+    end
+
+    def parse_files_parallel(files)
+      parsed = {}
+      mutex = Mutex.new
+      slice_size = [files.size / @concurrency + 1, 1].max
+
+      files.each_slice(slice_size).map do |slice|
+        Thread.new(slice) do |thread_files|
+          local = {}
+          thread_files.each { |f| local[f] = ReferenceExtractor.extract(f) }
+          mutex.synchronize { parsed.merge!(local) }
+        end
+      end.each(&:join)
+
+      parsed
+    end
+
+    def resolve_candidates(parsed)
+      parsed.each_value do |groups|
+        groups.each do |candidates|
+          candidates.each do |const_name|
+            next if resolved_file_by_const.key?(const_name)
+
+            resolve_constant_file(const_name)
+          end
+        end
+      end
+    end
+
+    def resolve_dependencies(file, groups)
+      deps = {}
+
+      groups.each do |candidates|
+        resolved_file = resolve_reference_group(candidates)
+        next unless resolved_file
+        next if resolved_file == file
+
+        deps[resolved_file] = true
+      end
+
+      deps.empty? ? EMPTY_ARRAY : deps.keys.sort.freeze
+    end
+
+    def resolve_reference_group(candidates)
+      candidates.each do |const_name|
+        file = resolved_file_by_const[const_name]
+        return file if file && include_path?(file)
+      end
+
+      nil
+    end
+
+    def resolve_transitive_dependencies(file)
+      cached = closure_by_file[file]
+      return cached if cached
+
+      visiting = {}
+      stack = [[file, :enter]]
+
+      until stack.empty?
+        current_file, state = stack.pop
+
+        if state == :exit
+          dependencies = {}
+
+          @graph.fetch(current_file, EMPTY_ARRAY).each do |dependency_file|
+            dependencies[dependency_file] = true
+
+            closure_by_file.fetch(dependency_file, EMPTY_ARRAY).each do |transitive_dependency|
+              dependencies[transitive_dependency] = true
+            end
+          end
+
+          dependencies.delete(current_file)
+          closure_by_file[current_file] = dependencies.empty? ? EMPTY_ARRAY : dependencies.keys.sort.freeze
+          visiting.delete(current_file)
+          next
+        end
+
+        next if closure_by_file.key?(current_file)
+        next if visiting[current_file]
+
+        visiting[current_file] = true
+        stack << [current_file, :exit]
+
+        @graph.fetch(current_file, EMPTY_ARRAY).reverse_each do |dependency_file|
+          next if closure_by_file.key?(dependency_file)
+          next if visiting[dependency_file]
+
+          stack << [dependency_file, :enter]
+        end
+      end
+
+      closure_by_file.fetch(file, EMPTY_ARRAY)
+    end
+
+    def resolve_constant_file(const_name)
+      return nil unless constant_defined?(const_name)
+
+      source_location = Object.const_source_location(const_name)
+      file = source_location&.first
+      return nil unless file && File.file?(file)
+
+      resolved_file_by_const[const_name] = share_path(file)
+    rescue StandardError
+      nil
+    end
+
+    def constant_defined?(const_name)
+      current = Object
+
+      const_name.split("::").each do |segment|
+        return false unless current.const_defined?(segment, false)
+
+        current = current.const_get(segment, false)
+      end
+
+      true
+    rescue StandardError
+      false
+    end
+
+    def include_path?(path)
+      return false unless FastCov::Utils.path_within?(path, root)
+
+      ignored_paths.none? { |ignored_path| FastCov::Utils.path_within?(path, ignored_path) }
+    end
+
+    def processable_file?(file)
+      File.file?(file) && include_path?(file)
+    end
+
+    def expand_files(patterns)
+      Array(patterns)
+        .flat_map do |pattern|
+          pattern = pattern.to_s
+          pattern = File.expand_path(pattern, root) unless File.absolute_path?(pattern)
+          Dir.glob(pattern)
+        end
+        .map { |path| share_path(path) }
+        .uniq
+        .sort
+    end
+
+    def normalize_ignored_paths(ignored_paths)
+      Array(ignored_paths)
+        .compact
+        .map { |path| share_path(File.expand_path(path, root)) }
+        .uniq
+        .sort
+        .freeze
+    end
+
+    def relativize(absolute_path)
+      share_string(absolute_path.delete_prefix(@root_prefix))
+    end
+
+    def relativize_input(file)
+      path = file.to_s
+      if File.absolute_path?(path)
+        relativize(path)
+      else
+        share_string(path)
+      end
+    end
+
+    def share_path(path)
+      share_string(File.expand_path(path.to_s))
+    end
+
+    def share_string(string)
+      -string.to_s
+    end
+  end
+end

data/lib/fast_cov/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module FastCov
-  VERSION = "0.2.0"
+  VERSION = "0.3.0"
 end

data/lib/fast_cov.rb

@@ -10,4 +10,5 @@ module FastCov
   autoload :FileTracker, File.expand_path("fast_cov/trackers/file_tracker", __dir__)
   autoload :FactoryBotTracker, File.expand_path("fast_cov/trackers/factory_bot_tracker", __dir__)
   autoload :ConstGetTracker, File.expand_path("fast_cov/trackers/const_get_tracker", __dir__)
+  autoload :StaticMap, File.expand_path("fast_cov/static_map", __dir__)
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: fast_cov
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Ngan Pham
@@ -85,6 +85,8 @@ files:
 - lib/fast_cov/connected_dependencies.rb
 - lib/fast_cov/coverage_map.rb
 - lib/fast_cov/dev.rb
+- lib/fast_cov/static_map.rb
+- lib/fast_cov/static_map/reference_extractor.rb
 - lib/fast_cov/trackers/abstract_tracker.rb
 - lib/fast_cov/trackers/const_get_tracker.rb
 - lib/fast_cov/trackers/factory_bot_tracker.rb