graphql_tag_pluck 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fcbca0ff3be0816489e30ce795f1be443b956469afb4510b00cf8ccdf1a8245e
-  data.tar.gz: d51b601e49320c4a13e79ba371d2e169f8d7b93f231db025fe2e2fa0d89f7203
+  metadata.gz: ba2b33d369224dd7521d95c6cd1cae8839bf350694d10343872e4e98e153d5dd
+  data.tar.gz: 3f5a2db373cff91ceb6916be998f6ad3082dee1f4cc1124505e6db68ace3ff73
 SHA512:
-  metadata.gz: 50fe1a5bc7e76a7b542bfb30ef080e3eb4a9c64aa5eb6bddce88d53814cbe7a94ea4b1221dea60ba0a2cd3f183e91721eb343503ae6367fee8aa635945d44e5d
-  data.tar.gz: 6c449f2a1901ce559208e27b1ef99e696ffab4209f7d55d2f763a23da84fb7d47fe1c027b56c72b30c7821da335917baa142973cc73432f5dce71ebad047c644
+  metadata.gz: a93e45d44f8b3f9f89449447962ae3380fe4b0bcdd34528bf58c5b62b8a0f0e840d4eb423bc2e41032c6a0e5c047e571e31740f3928f888f8bb043477f1e467a
+  data.tar.gz: 171fccfe0c3775df5cd4917fea80567ad41c14509c79036ec56c0e8361348e772165d23af5ac994a9171d5f79e799424546bd565cd61b110cb13f3e8375b0181

data/CHANGELOG.md

@@ -7,6 +7,32 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.3.0] - 2026-11-03
+
+### Added
+
+- Each exported entry now records where it was defined: `file` (relative to
+  the current directory, or absolute for files outside it), `line` (the line
+  the definition starts on, also correct for several definitions in one
+  heredoc), and `constant` (the fully qualified constant the heredoc is
+  assigned to, such as `Clients::UserClient::USER_QUERY`, or `null`).
+  ([#16](https://github.com/indigolain/graphql_tag_pluck/pull/16))
+
+### Changed
+
+- **Breaking:** unnamed operations are keyed by their location, such as
+  `"app/clients/user_client.rb:4"`, instead of `unnamed_operation_N`. The old
+  counter depended on the order files were read in.
+  ([#16](https://github.com/indigolain/graphql_tag_pluck/pull/16))
+- **Breaking:** any definition name that appears more than once, even with an
+  identical definition, now raises `GraphqlTagPluck::Error` naming both
+  locations, and no output file is written. 0.2.0 only warned and kept the
+  last definition.
+  ([#16](https://github.com/indigolain/graphql_tag_pluck/pull/16))
+- Files are processed in sorted order, so output no longer depends on file
+  system order. Warnings for invalid GraphQL now include the `path:line`.
+  ([#16](https://github.com/indigolain/graphql_tag_pluck/pull/16))
+
 ## [0.2.0] - 2026-11-03
 
 ### Changed
@@ -65,7 +91,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Configuration through `.graphqltagpluckconfig.yaml`
   (`graphql_heredoc_identifiers`, `file_glob_pattern`, `output_path`).
 
-[Unreleased]: https://github.com/indigolain/graphql_tag_pluck/compare/v0.2.0...HEAD
+[Unreleased]: https://github.com/indigolain/graphql_tag_pluck/compare/v0.3.0...HEAD
+[0.3.0]: https://github.com/indigolain/graphql_tag_pluck/compare/v0.2.0...v0.3.0
 [0.2.0]: https://github.com/indigolain/graphql_tag_pluck/compare/v0.1.1...v0.2.0
 [0.1.1]: https://github.com/indigolain/graphql_tag_pluck/compare/v0.1.0...v0.1.1
 [0.1.0]: https://github.com/indigolain/graphql_tag_pluck/releases/tag/v0.1.0

data/README.md

@@ -32,11 +32,26 @@ will output json file like: (following json content is formatted)
   "SampleQuery": {
     "name": "SampleQuery",
     "source": "query SampleQuery {\n  hoge\n  fuga {\n    piyo\n  }\n}",
-    "type": "query"
+    "type": "query",
+    "file": "app/clients/sample_client.rb",
+    "line": 2,
+    "constant": "SAMPLE_QUERY"
   }
 }
 ```
 
+Each entry contains:
+
+- `name`: the operation / fragment name (`null` for unnamed operations)
+- `source`: the normalized GraphQL document of the definition
+- `type`: `query`, `mutation`, `subscription`, or `fragment`
+- `file`: the file the definition was found in, relative to the current directory
+- `line`: the line the definition starts on
+- `constant`: the fully qualified constant the heredoc is assigned to (e.g. `Clients::UserClient::USER_QUERY`), or `null` when the heredoc is not assigned to a constant
+
+Entries are keyed by definition name. Unnamed operations are keyed by their location (e.g. `"app/clients/sample_client.rb:2"`).
+Definition names must be unique: any name defined more than once, even identically, raises `GraphqlTagPluck::Error` and no file is written.
+
 by executing
 
 ```sh

data/VERSION

@@ -1 +1 @@
-0.2.0
+0.3.0

data/lib/graphql_tag_pluck/graphql_tag_pluck.rb

@@ -5,8 +5,6 @@ module GraphqlTagPluck
   class Error < StandardError; end
 
   class << self
-    using GraphqlTagPluck::Parser::AST::NodeExt
-
     attr_accessor :options
 
     def default_options
@@ -18,9 +16,9 @@ module GraphqlTagPluck
     end
 
     def get_graphql_heredocs
-      files = Dir.glob(GraphqlTagPluck.options[:file_glob_pattern])
-      unnamed_operation_count = 0
-      origin_files = {}
+      # Sorted so the output, and which duplicate wins, does not depend on file system order.
+      files = Dir.glob(GraphqlTagPluck.options[:file_glob_pattern]).sort
+      collector = HeredocCollector.new
 
       {}.tap do |hash|
         files.each do |file|
@@ -30,40 +28,53 @@ module GraphqlTagPluck
             warn "graphql_tag_pluck: skipping #{file}, which could not be parsed as Ruby: #{e.message}"
             next
           end
-          parsed_node_array = node&.parse_node_recursively
-          next if parsed_node_array.nil?
+          next if node.nil?
+
+          path = relative_path(file)
 
-          parsed_node_array.flatten.compact.each do |graphql_doc_string|
-            parsed_graphql_doc_string = begin
-              GraphQL.parse(graphql_doc_string)
+          collector.collect(node).each do |heredoc|
+            document = begin
+              GraphQL.parse(heredoc.source)
             rescue GraphQL::ParseError => e
-              warn "graphql_tag_pluck: skipping invalid GraphQL heredoc in #{file}: #{e.message}"
+              warn "graphql_tag_pluck: skipping invalid GraphQL heredoc in #{path}:#{heredoc.line}: #{e.message}"
               next
             end
-            parsed_graphql_doc_string.definitions.each do |definition|
-              key = if definition.name.nil?
-                unnamed_operation_count += 1
-                "unnamed_operation_#{unnamed_operation_count}"
-              else
-                definition.name
-              end
 
+            document.definitions.each do |definition|
+              line = heredoc.line + definition.line - 1
+              # Unnamed operations are keyed by their location so keys stay stable across runs.
+              key = definition.name || "#{path}:#{line}"
               source = definition.to_query_string
-              if hash.key?(key) && hash[key][:source] != source
-                warn "graphql_tag_pluck: #{key} in #{file} overwrites a different definition with the same name in #{origin_files[key]}"
+
+              # Operation names must be unique, even for identical copies, so the
+              # generated list never silently depends on which definition wins.
+              if (existing = hash[key])
+                raise Error, "Duplicate GraphQL definition name `#{key}`: " \
+                  "defined at #{existing[:file]}:#{existing[:line]} and #{path}:#{line}"
               end
-              origin_files[key] = file
 
               hash[key] = {
                 name: definition.name,
                 source: source,
-                type: definition.instance_of?(GraphQL::Language::Nodes::FragmentDefinition) ? 'fragment' : definition.operation_type 
+                type: definition.instance_of?(GraphQL::Language::Nodes::FragmentDefinition) ? 'fragment' : definition.operation_type,
+                file: path,
+                line: line,
+                constant: heredoc.constant
               }
             end
           end
         end
       end
     end
+
+    private
+
+    # Relative to the current directory when the file is inside it, absolute otherwise.
+    def relative_path(file)
+      absolute = File.realpath(file)
+      prefix = "#{File.realpath(Dir.pwd)}/"
+      absolute.start_with?(prefix) ? absolute.delete_prefix(prefix) : absolute
+    end
   end
 
   self.options = default_options.merge(Config.load)

data/lib/graphql_tag_pluck/heredoc_collector.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module GraphqlTagPluck
+  # Walks a Ruby AST and collects GraphQL heredocs together with
+  # the line their body starts on and the constant they are assigned to.
+  class HeredocCollector
+    using GraphqlTagPluck::Parser::AST::NodeExt
+
+    Heredoc = Struct.new(:source, :line, :constant, keyword_init: true)
+
+    def collect(node)
+      [].tap { |result| visit(node, [], nil, result) }
+    end
+
+    private
+
+    # namespace: lexical module / class nesting, e.g. ["Clients", "UserClient"]
+    # constant:  fully qualified constant name the current node is assigned to, if any
+    def visit(node, namespace, constant, result)
+      return unless node.is_a?(::Parser::AST::Node)
+
+      if node.is_graphql_heredoc_node?
+        if node.interpolated?
+          warn "graphql_tag_pluck: skipping GraphQL heredoc with Ruby interpolation at #{node.loc.expression.source_buffer.name}:#{node.loc.line}"
+        else
+          body = node.loc.heredoc_body
+          result << Heredoc.new(source: body.source, line: body.line, constant: constant)
+        end
+        return
+      end
+
+      case node.type
+      when :module, :class
+        name_node, *rest = node.children
+        inner_namespace = nest(namespace, const_name(name_node))
+        rest.each { |child| visit(child, inner_namespace, nil, result) }
+      when :casgn
+        scope, name, value = node.children
+        visit(value, namespace, assigned_constant(namespace, scope, name), result)
+      when :send, :csend
+        # Keep the constant for receivers so `FOO = <<~GRAPHQL.freeze` is still attributed to FOO,
+        # but not for arguments: `FOO = wrap(<<~GRAPHQL)` does not assign the heredoc itself.
+        receiver, _method_name, *args = node.children
+        visit(receiver, namespace, constant, result)
+        args.each { |child| visit(child, namespace, nil, result) }
+      else
+        node.children.each { |child| visit(child, namespace, nil, result) }
+      end
+    end
+
+    # Returns e.g. "Foo::Bar", "::Foo", or nil when the constant path is dynamic (e.g. `self::Foo`).
+    def const_name(node)
+      return nil unless node.is_a?(::Parser::AST::Node) && node.type == :const
+
+      scope, name = node.children
+      case scope&.type
+      when nil then name.to_s
+      when :cbase then "::#{name}"
+      when :const
+        prefix = const_name(scope)
+        prefix && "#{prefix}::#{name}"
+      end
+    end
+
+    def nest(namespace, name)
+      return namespace if name.nil?
+      return [name.delete_prefix("::")] if name.start_with?("::")
+
+      namespace + [name]
+    end
+
+    def assigned_constant(namespace, scope, name)
+      return (namespace + [name.to_s]).join("::") if scope.nil?
+      return name.to_s if scope.type == :cbase
+
+      prefix = const_name(scope)
+      prefix && nest(nest(namespace, prefix), name.to_s).join("::")
+    end
+  end
+end

data/lib/graphql_tag_pluck/parser/ast/node_ext.rb

@@ -9,19 +9,6 @@ module GraphqlTagPluck
             type == :dstr && children.any? { |child| child.type != :str && !(child.type == :dstr && !child.interpolated?) }
           end
 
-          def parse_node_recursively
-            return nil unless respond_to?(:loc)
-            if is_graphql_heredoc_node?
-              return loc.heredoc_body.source unless interpolated?
-
-              warn "graphql_tag_pluck: skipping GraphQL heredoc with Ruby interpolation at #{loc.expression.source_buffer.name}:#{loc.line}"
-              return nil
-            end
-            if respond_to?(:children)
-              children.map {|child| child.respond_to?(:parse_node_recursively) ? child.parse_node_recursively : nil }
-            end
-          end
-
           def is_graphql_heredoc_node?
             loc.instance_of?(::Parser::Source::Map::Heredoc) &&
               GraphqlTagPluck.options[:graphql_heredoc_identifiers].include?(heredoc_identifier)

data/lib/graphql_tag_pluck.rb

@@ -7,6 +7,7 @@ require "yaml"
 require_relative "graphql_tag_pluck/version"
 require_relative "graphql_tag_pluck/config"
 require_relative "graphql_tag_pluck/parser/ast/node_ext"
+require_relative "graphql_tag_pluck/heredoc_collector"
 require_relative "graphql_tag_pluck/railtie" if defined?(Rails)
 
 require_relative 'graphql_tag_pluck/graphql_tag_pluck'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: graphql_tag_pluck
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - indigolain
@@ -91,6 +91,7 @@ files:
 - lib/graphql_tag_pluck/Rakefile
 - lib/graphql_tag_pluck/config.rb
 - lib/graphql_tag_pluck/graphql_tag_pluck.rb
+- lib/graphql_tag_pluck/heredoc_collector.rb
 - lib/graphql_tag_pluck/parser/ast/node_ext.rb
 - lib/graphql_tag_pluck/railtie.rb
 - lib/graphql_tag_pluck/rake_tasks.rb