reference_extractor 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bac9513331865230939596e19a86fb7e446498d4c4f9194dcb68a97b5377a668
-  data.tar.gz: e5db87762acef10e792fb4f56b6cd333ea8f08a43b2f40f9d7c9f5206eb7daa0
+  metadata.gz: 19d808e45b0a49435136cb0813dbc66af70b68f1127c1d40d497b97f77da470c
+  data.tar.gz: 9f7419a764a29617ed8d8e33c3783c527a2854e697c8439a83139dbff16268d7
 SHA512:
-  metadata.gz: 5439eaacdaf0df2b261122de2d5853542b4a51841945197aca3ee04b33dc259348946401598125faea3c7f941a826f06d1ef5dd265ee3a56dece72e944d0a6c8
-  data.tar.gz: 5970480b43f52c8abfe2c4d0a54dfffca9b024113d19a2642b6f93b10e4b5cfbf540dec4b0887ec0380d500846032358f889f96c1cfd70c0399172c57a562ce3
+  metadata.gz: 7adb979d6be9eee24fc653046c46bfd243f4c762e4afc27b639a9b477ea7fa555662f8a3f649300a51294bdd193f6b83959e53877f3ab03bf8ad2d657648f177
+  data.tar.gz: 872d6e9a503e1027bb976a6ec600fc2f1b272f73d5e9fc1fc1dabe8d5300fa59b469fc8562f94904873196fa81b4b6f4d084f33f08108ec687e903b903a58060

data/.tool-versions

@@ -1 +1 @@
-ruby 3.4.7
+ruby 4.0.1

data/CHANGELOG.md

@@ -2,6 +2,11 @@
 
 ## [Unreleased]
 
+## [0.1.1] - 2026-01-24
+
+- added association inspector from Packwerk
+- better tests, docs, and some refactoring
+
 ## [0.1.0] - 2025-10-30
 
 - Initial release

data/IMPLEMENTATION.md

@@ -0,0 +1,43 @@
+# ReferenceExtractor Implementation Notes
+
+## Initial Implementation Plan
+
+Looking back at years of building and using [packwerk](https://github.com/Shopify/packwerk), there are some major things I would like to improve in the next version.
+
+Properties I want from ReferenceExtractor:
+
+- extract the most complex, least specific part into a reusable module. That is, finding all external references from a Ruby file
+- enabled by the above, allow arbitrary (through extension) rules to be expressed over that foundational reference graph
+  - start with layering, the most common architecture rule (_A boundary in software architecture is a line that is crossed by dependencies only in one direction_)
+- optionally and later, future-proof the core
+  - make sure it uses a current version of prism in the canonical way for parsing
+  - remove the dependency on zeitwerk _or_ go all in on zeitwerk and remove constant_resolver
+
+There is a possible version of this where reference_extractor-core is a separate gem.
+
+Also, please note that all names are temporary at this point.
+
+I am not pushing this as a next version of packwerk though due to two reasons:
+
+- Packwerk development has been at a snail's pace for the last few years as Shopify has reduced its ongoing investment to just "keeping the lights on" and I don't have the influence required to change that - I don't want to spend energy arguing, I want to push this out into the world
+- Packwerk's original architecture was based on assumptions that have long been invalidated (e.g. running as a rubocop cop) and it's difficult to remove the remnants of these decisions from its architecture
+  - another outdated assumption is that config validation is slow while the actual reference checking is fast. Nowadays both require bootup of the application, so there is actually no need for a separate `validate` command
+- Packwerk has accumulated a lot of complexity to enable less common use cases and add convenience. Those would slow down iteration towards a different paradigm.
+
+Relevant open PRs on packwerk:
+
+- [packwerk#410](https://github.com/Shopify/packwerk/pull/410) Proof of concept for removing ConstantResolver and using Zeitwerk for ConstantDiscovery
+- [packwerk#397](https://github.com/Shopify/packwerk/pull/397) Allow fetching all references for a file, or all files, using public API
+
+## Implemented Improvements over Packwerk
+
+- Removed dependency on `constant_resolver` by depending directly on zeitwerk for reverse lookup, thanks to @Catsuko ([packwerk#410](https://github.com/Shopify/packwerk/pull/410))
+- Replaced `better_html` with `herb` which comes with a lot less dependencies
+- remove possibly outdated encoding handling from parsers
+- fixed prism deprecation warnings, thanks to @Earlopain ([packwerk#431](https://github.com/Shopify/packwerk/pull/431))
+
+## Ideas
+- Eliminate Rails dependency
+  - would be nice to just depend on zeitwerk, not Rails
+  - instead of reading from `Rails.autoloaders`, can we just get the autoloaders from Zeitwerk?
+- remove association inspector for now? It may cause more problems than it solves

data/lib/reference_extractor/extractor.rb

@@ -26,7 +26,7 @@ module ReferenceExtractor
       ast = parse_ruby_string(snippet)
       return [] unless ast
 
-      extract_references(ast, relative_path: "<snippet>")
+      extract_references(ast, relative_path: Pathname.new("<snippet>"))
     end
 
     # Extract constant references from a Ruby file.
@@ -40,7 +40,7 @@ module ReferenceExtractor
       ast = parse_file(absolute_path)
       return [] unless ast
 
-      relative_path = Pathname.new(absolute_path).relative_path_from(root_path).to_s
+      relative_path = Pathname.new(absolute_path).relative_path_from(root_path)
       extract_references(ast, relative_path:)
     end
 
@@ -66,8 +66,10 @@ module ReferenceExtractor
 
     def ast_reference_extractor
       @ast_reference_extractor ||= Internal::AstReferenceExtractor.new(
-        # TO DO: Add association inspector
-        constant_name_inspectors: [Internal::ConstNodeInspector.new],
+        constant_name_inspectors: [
+          Internal::ConstNodeInspector.new,
+          Internal::AssociationInspector.new
+        ],
         context_provider: @context_provider,
         root_path:
       )

data/lib/reference_extractor/internal/association_inspector.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module ReferenceExtractor
+  module Internal
+    # Extracts the implicit constant reference from an Active Record association
+    class AssociationInspector
+      RAILS_ASSOCIATIONS = [
+        :belongs_to,
+        :has_many,
+        :has_one,
+        :has_and_belongs_to_many
+      ].to_set
+
+      DEFAULT_EXCLUDED_FILES = Set.new([
+        "spec/factories/**",
+        "test/factories/**"
+      ])
+
+      def initialize(
+        inflector: ActiveSupport::Inflector,
+        custom_associations: Set.new,
+        excluded_files: DEFAULT_EXCLUDED_FILES
+      )
+        @inflector = inflector
+        @associations = RAILS_ASSOCIATIONS + custom_associations
+        @excluded_files = excluded_files
+      end
+
+      def constant_name_from_node(node, ancestors:, relative_path:)
+        return unless NodeHelpers.method_call?(node)
+        return if excluded?(relative_path)
+        return unless association?(node)
+
+        arguments = NodeHelpers.method_arguments(node)
+        association_name = association_name(arguments)
+        return unless association_name
+
+        if (class_name_node = custom_class_name(arguments))
+          return unless NodeHelpers.string?(class_name_node)
+
+          NodeHelpers.literal_value(class_name_node)
+        else
+          @inflector.classify(association_name.to_s)
+        end
+      end
+
+      private
+
+      def excluded?(relative_file)
+        @excluded_files.any? do |pattern|
+          relative_file.fnmatch?(pattern, File::FNM_PATHNAME | File::FNM_EXTGLOB)
+        end
+      end
+
+      def association?(node)
+        method_name = NodeHelpers.method_name(node)
+        @associations.include?(method_name)
+      end
+
+      def custom_class_name(arguments)
+        association_options = arguments.detect { |n| NodeHelpers.hash?(n) }
+        return unless association_options
+
+        NodeHelpers.value_from_hash(association_options, :class_name)
+      end
+
+      def association_name(arguments)
+        association_name_node = arguments[0]
+        return unless association_name_node
+        return unless NodeHelpers.symbol?(association_name_node)
+
+        NodeHelpers.literal_value(association_name_node)
+      end
+    end
+  end
+end

data/lib/reference_extractor/internal/ast_reference_extractor.rb

@@ -18,7 +18,7 @@ module ReferenceExtractor
             next if constant.nil?
 
             # Ignore references that resolve to the same file they originate from.
-            next if constant.location.to_s == unresolved_reference.relative_path.to_s
+            next if constant.location == unresolved_reference.relative_path
 
             fully_qualified_references << Reference.new(
               relative_path: unresolved_reference.relative_path,
@@ -57,7 +57,7 @@ module ReferenceExtractor
         constant_name = nil
 
         @constant_name_inspectors.each do |inspector|
-          constant_name = inspector.constant_name_from_node(node, ancestors:)
+          constant_name = inspector.constant_name_from_node(node, ancestors:, relative_path:)
 
           break if constant_name
         end

data/lib/reference_extractor/internal/const_node_inspector.rb

@@ -4,7 +4,7 @@ module ReferenceExtractor
   module Internal
     # Extracts a constant name from an AST node of type :const
     class ConstNodeInspector
-      def constant_name_from_node(node, ancestors:)
+      def constant_name_from_node(node, ancestors:, relative_path: nil)
         return nil unless NodeHelpers.constant?(node)
 
         parent = ancestors.first

data/lib/reference_extractor/internal.rb

@@ -4,6 +4,7 @@ module ReferenceExtractor
   module Internal
     extend ActiveSupport::Autoload
 
+    autoload :AssociationInspector
     autoload :AstReferenceExtractor
     autoload :ConstNodeInspector
     autoload :ConstantDiscovery

data/lib/reference_extractor/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ReferenceExtractor
-  VERSION = "0.1.0"
+  VERSION = "0.1.1"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: reference_extractor
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - Philip Theus
@@ -92,6 +92,7 @@ files:
 - ".tool-versions"
 - CHANGELOG.md
 - CODE_OF_CONDUCT.md
+- IMPLEMENTATION.md
 - LICENSE
 - LICENSE.txt
 - README.md
@@ -101,6 +102,7 @@ files:
 - lib/reference_extractor/constant_context.rb
 - lib/reference_extractor/extractor.rb
 - lib/reference_extractor/internal.rb
+- lib/reference_extractor/internal/association_inspector.rb
 - lib/reference_extractor/internal/ast_reference_extractor.rb
 - lib/reference_extractor/internal/const_node_inspector.rb
 - lib/reference_extractor/internal/constant_discovery.rb
@@ -138,7 +140,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.7.2
+rubygems_version: 4.0.3
 specification_version: 4
 summary: Extracts cross-file references in Ruby projects for architecture and dependency
   analysis.