graph_weaver 0.6.1 → 0.7.1

data/lib/graph_weaver/internal/unused.rb

@@ -0,0 +1,287 @@
+# typed: true
+# frozen_string_literal: true
+
+require "set"
+
+require_relative "../internal"
+
+module GraphWeaver
+  module Internal
+    # Which generated props no code in the app reads — the over-fetch that
+    # collects when a template stops using a field and nobody edits the
+    # .graphql. graphql-client catches it at runtime by masking the data it
+    # didn't declare; the structs are checked in here, so it can be recovered
+    # without running anything.
+    #
+    # Name-based on purpose. The generated structs say which props exist; one
+    # sweep of the app's own source says which names it mentions. That makes
+    # this a lint rather than a proof — #report says so in its own footer,
+    # because a finding is a prompt to look, never a verdict.
+    class Unused
+      # Where a prop shows up when it is READ: a method call, a pattern-match
+      # or hash key, a symbol, a string. A bare word in prose matches none of
+      # them, which is what keeps comments and locals out.
+      READ = /[.:"']([a-z_]\w*)|\b([a-z_]\w*):/
+      # Hand a struct to one of these and every prop is read at once, by a
+      # call that names none of them. Caught where the sink line carries the
+      # module's own name, or a local a line above assigned from it.
+      SINKS = /\b(?:to_h|to_json|as_json|serialize|deconstruct_keys)\b|render\s+json:/
+      # `result = PersonQuery.execute!(...)` — the local a response lands in.
+      # Following one is what lets the sink be on the NEXT line, which is how
+      # anyone actually writes a controller. Excludes == and =~.
+      ASSIGN = /\b([a-z_]\w*)\s*=[^=~]/
+      # A graphql-ruby TYPE class NAMES every field the server offers, as
+      # `field :sku` and as a resolver method — which is the server answering,
+      # not this app reading a prop back. Without this an app that serves the
+      # graph it consumes (graphql_in_process) marks every prop read, and the
+      # task reports nothing however much it over-fetches.
+      #
+      # Type kinds only: GraphQL::Schema::Resolver and ::Mutation hold
+      # application logic — in a BFF that is exactly where an upstream graph
+      # gets read — and skipping those files lost every read in them. Both
+      # spellings, because graphql-ruby's own generator emits the app-owned
+      # base class (`< Types::BaseObject`), not the gem's.
+      TYPE_KINDS = "Object|Interface|Union|Enum|Scalar|InputObject"
+      SCHEMA = /^[ \t]*(?:class \w+ < (?:GraphQL::Schema::|Types::Base)(?:#{TYPE_KINDS})\b|include GraphQL::Schema::Interface\b)/
+      # What the sweep can read. A prop read from anywhere else — a .vue, a
+      # .json.erb's sibling JS — is a blind spot, and the footer says so.
+      # .rake and .builder are Ruby too.
+      EXTENSIONS = %w[.rb .rake .builder .erb .slim .haml .jbuilder].freeze
+      # Directories that hold no app source. "generated" covers both a graph's
+      # own output under the convention and a spec/generated fixture dir; a
+      # graph that writes somewhere else is pruned by #outputs.
+      SKIP = Set["vendor", "node_modules", "tmp", "log", "generated"].freeze
+      # enough of the quoted line to judge it by, without wrapping a terminal
+      SNIPPET = 100
+
+      # Measured against real corpora (actionview, activesupport, graphql and
+      # six Rails gems swept together): half to two thirds of genuinely unread
+      # selections go unreported, rising with corpus size. Saying so is the
+      # difference between a lint and a number somebody trusts.
+      FOOTER = "This is a lint, not a proof — it matches prop names as text, so a common name reads " \
+        "as\nused the moment anything says it. It can't see a prop reached by public_send, or a " \
+        "read\nin a file type it doesn't sweep (#{EXTENSIONS.join(", ")}). On a real app half to " \
+        "two\nthirds of genuinely unread selections go unreported; silence is the safe direction."
+
+      # query: the .graphql that selected it. struct/prop: where it landed.
+      # wire: how the query spells that prop, when it differs.
+      Selection = Struct.new(:query, :module_name, :struct, :prop, :wire) do
+        # The GraphQL-side name, which is what you go and delete: the struct's
+        # own name is the response key, so `Person.birthday` reads the way the
+        # query does — and a camelCase field, an alias or a reserved rename
+        # reads the way the query spells it, not the way the prop does.
+        def coordinate = "#{struct.name.split("::").last}.#{wire || prop}"
+
+        # …and the Ruby side, so the report is greppable both ways.
+        def constant = "#{struct.name}##{prop}"
+      end
+
+      # Why a module's props were all counted read, and on what evidence. Via
+      # is the local the value was standing in when it reached the serializer,
+      # nil when the sink line named the module itself.
+      Excuse = Struct.new(:path, :number, :source, :via) do
+        def reason
+          where = "handed whole to a serializer at #{path}:#{number}"
+          via ? "#{where}, as `#{via}`" : where
+        end
+      end
+
+      # What one pass over the files answers.
+      Sweep = Struct.new(:names, :wholly_used, :files)
+
+      # paths: the directories to sweep, defaulting to the whole root. Narrowed
+      # here rather than by the caller, so an empty PATHS= sweeps everything
+      # instead of nothing — nothing would report every prop unread.
+      def initialize(graphs: GraphWeaver.graphs, paths: nil)
+        @graphs = graphs
+        given = Array(paths).map { |path| path.to_s.strip }.reject(&:empty?)
+        @roots = (given.empty? ? ["."] : given).map { |path| Util.resolve(path) }
+        # A root that isn't there sweeps nothing, and sweeping nothing reports
+        # every prop unread — under STRICT, a red build demanding you delete
+        # fields you use. `0 files swept` was the only tell, printed beneath
+        # the accusations.
+        missing = @roots.reject { |root| Dir.exist?(root) }
+        return if missing.empty?
+
+        raise GraphWeaver::Error,
+          "no directory at #{missing.map { |root| Util.relative(root) }.join(", ")} — " \
+          "PATHS= names directories under #{GraphWeaver.root}"
+      end
+
+      # Every selection nothing reads, grouped the way the report prints them.
+      def findings
+        @findings ||= selections
+          .reject { |selection| read?(selection) }
+          .sort_by { |selection| [Util.relative(selection.query), selection.coordinate] }
+      end
+
+      def report
+        # The evidence, not just the verdict: name-matching a serializer call
+        # is the mushiest thing here, and a suppression that was wrong should
+        # be obvious at a glance rather than silently eating the report.
+        lines = wholly_used.flat_map do |name, excuse|
+          ["#{name}: every prop counted as read — #{excuse.reason}", "  #{excuse.source[0, SNIPPET]}"]
+        end
+        lines += findings.map do |selection|
+          "#{Util.relative(selection.query)}: #{selection.coordinate} — selected, never read " \
+            "(#{selection.constant})"
+        end
+        # a run that checked nothing would report "0 unread" whatever the
+        # queries said, which is worse than saying so
+        lines << nothing_loaded if selections.empty?
+        [*lines, "", summary, "", FOOTER].join("\n")
+      end
+
+      # What the summary counts, so the task can phrase its own STRICT abort.
+      def summary
+        "#{selections.size} selections, #{findings.size} unread — " \
+          "#{count(selections.map(&:query).uniq.size, "query", "queries")}, " \
+          "#{count(swept, "file", "files")} swept under #{where}"
+      end
+
+      def count(number, one, many) = "#{number} #{(number == 1) ? one : many}"
+
+      private
+
+      def read?(selection)
+        wholly_used.key?(selection.module_name) || names.include?(selection.prop.to_s)
+      end
+
+      def names = sweep.names
+      def wholly_used = sweep.wholly_used
+      def swept = sweep.files
+
+      # One pass over the files for all three answers — the names anything
+      # reads, the modules something serializes whole, and how many files that
+      # took. Per-prop searching is what makes a tool like this too slow to run.
+      def sweep
+        @sweep ||= begin
+          read = Set.new
+          whole = {}
+          short = selections.to_h { |selection| [selection.module_name, selection.module_name.split("::").last] }
+          files.each do |path|
+            # scrub: a stray non-UTF-8 byte in a template is not a reason to
+            # refuse to lint the other 500 files
+            body = File.read(path).scrub
+            next if SCHEMA.match?(body)
+
+            body.scan(READ) { |method, key| read << (method || key) }
+            next unless SINKS.match?(body)
+
+            # Both substring checks before walking the lines: `to_h` is in
+            # most files and a query module's name is in almost none, so this
+            # is what keeps the line pass off the other 95%.
+            candidates = short.reject { |name, base| whole.key?(name) || !body.include?(base) }
+            next if candidates.empty?
+
+            # ONE line has to carry the module — itself, or a local a line
+            # above assigned from it. Anywhere-in-the-file was the first cut
+            # and it suppressed this gem's whole report: a doc comment naming
+            # PersonQuery three hundred lines above an unrelated to_h counted
+            # as serializing it. Following the local is what the line rule
+            # missed, and it is the shape every Rails controller has:
+            # `result = Q.execute!(...)`, then `render json: result.person`.
+            locals = Hash.new { |hash, key| hash[key] = [] }
+            body.each_line.with_index(1) do |line, number|
+              candidates.each do |name, base|
+                locals[name] << Regexp.last_match(1) if line.include?(base) && ASSIGN.match(line)
+              end
+              next unless SINKS.match?(line)
+
+              candidates.each do |name, base|
+                # the line naming the module is the better evidence; the local
+                # is what it falls back to
+                via = locals[name].find { |local| line.match?(/\b#{Regexp.escape(local)}\b/) } \
+                  unless line.include?(base)
+                next unless via || line.include?(base)
+
+                whole[name] ||= Excuse.new(Util.relative(path), number, line.strip, via)
+              end
+            end
+          end
+          Sweep.new(read, whole, files.size)
+        end
+      end
+
+      # Every generated prop, per query file. Query-driven like everything
+      # else: a struct exists because a query selected it.
+      def selections
+        @selections ||= @graphs.flat_map do |graph|
+          Util.query_files(graph.queries).flat_map do |path|
+            source = File.read(path)
+            name = graph.generated_names(path, source).first
+            next [] unless Object.const_defined?(name)
+
+            result = Object.const_get(name)
+            next [] unless result.const_defined?(:Result, false)
+
+            words = source.scan(/[A-Za-z_]\w*/).uniq
+            props(result.const_get(:Result, false))
+              .map { |struct, prop| Selection.new(path, name, struct, prop, wire_word(words, prop)) }
+          end
+        end
+      end
+
+      # How the query spells a prop, when that isn't the prop's own name — a
+      # camelCase field, an alias, a reserved rename. Read back off the query
+      # text rather than derived from the prop, since no rule inverts an
+      # alias; nil when the query spells it the same way, which is most of
+      # the time.
+      def wire_word(words, prop)
+        words.find { |word| word != prop.to_s && GraphWeaver::Codegen.prop_name(word) == prop.to_s }
+      end
+
+      # Nested structs are nested constants, so the props of a whole response
+      # are one walk down. Reported flat: a parent nothing reads makes its
+      # children unread too, and saying both is the honest count.
+      def props(struct, found = [])
+        struct.props.each_key { |prop| found << [struct, prop] }
+        struct.constants(false).each do |const|
+          nested = struct.const_get(const, false)
+          props(nested, found) if nested.is_a?(Class) && nested < T::Struct
+        end
+        found
+      end
+
+      def files
+        @files ||= @roots.flat_map { |root| collect(root, []) }.uniq.sort
+      end
+
+      # Pruned as it walks rather than globbed and filtered: node_modules is
+      # the directory you most want never to descend into.
+      def collect(dir, found)
+        Dir.children(dir).sort.each do |entry|
+          path = File.join(dir, entry)
+          # lstat, so a symlinked directory can't loop the walk
+          stat = File.lstat(path)
+          if stat.directory?
+            collect(path, found) unless skip_dir?(entry, path)
+          elsif stat.file? && EXTENSIONS.include?(File.extname(entry))
+            found << path
+          end
+        end
+        found
+      rescue SystemCallError
+        found
+      end
+
+      def skip_dir?(entry, path) = entry.start_with?(".") || SKIP.include?(entry) || outputs.include?(path)
+
+      # The generated directories a name check can't catch: a graph that sets
+      # `output` somewhere of its own.
+      def outputs
+        @outputs ||= (Util.generated_dirs + @graphs.map(&:output))
+          .flat_map { |pattern| Dir.glob(Util.resolve(pattern), File::FNM_PATHNAME) }
+          .to_set
+      end
+
+      def where
+        @roots.map { |root| (root == GraphWeaver.root) ? "." : Util.relative(root) }.join(", ")
+      end
+
+      def nothing_loaded
+        "nothing to check: no generated module is loaded for any query here (rake graph_weaver:generate)"
+      end
+    end
+  end
+end

data/lib/graph_weaver/internal/values.rb

@@ -50,6 +50,10 @@ class GraphWeaver::Internal::Values
   # What Codegen.scalar reports for a scalar nobody registered
   UNREGISTERED = "T.untyped"
 
+  # What JSON can hold. Anything else a pin offers is a Ruby object the
+  # registration has to serialize before it can stand in for a response.
+  WIRE = [NilClass, TrueClass, FalseClass, Numeric, String, Symbol, Array, Hash].freeze
+
   # The fallback, for a scalar nobody registered: its prop is T.untyped, so
   # anything holds and a plausible shape beats a placeholder.
   NAMED_SHAPES = {
@@ -71,7 +75,13 @@ class GraphWeaver::Internal::Values
   # pin is resolved against the query, which is the fake's job. Left unsaid
   # they are the suite's, so a scalar only the app can write for is
   # fabricable from the cassette anonymizer too.
-  def initialize(seed: nil, values: nil, pins: nil)
+  # schema: which server is being faked. registry: the registrations the
+  # values have to satisfy — a Money registered for one graph is not a Money
+  # for the next, and only a caller holding the graph can say which. Left
+  # unsaid they are read back off the schema, which is the answer for every
+  # app with one graph running a live class.
+  def initialize(seed: nil, values: nil, pins: nil, schema: nil, registry: nil)
+    @registry = registry || GraphWeaver::Internal::Util.registry_for(schema)
     @rng = Random.new(seed || GraphWeaver::Testing.config.seed || Random.new_seed)
     @pins = (pins || GraphWeaver::Testing.config.overrides).transform_keys(&:to_s)
     @style = resolve_style(values)
@@ -86,7 +96,9 @@ class GraphWeaver::Internal::Values
   # alone. at: where the walk is ("reader.orders.0.total"), for that refusal;
   # a walk that doesn't track one leaves it unsaid.
   def scalar(type_name, field_name, coordinate = nil, at: nil)
-    return GraphWeaver::Internal::Overrides.resolve(@pins[type_name], rng) if @pins.key?(type_name)
+    if @pins.key?(type_name)
+      return wire(type_name, GraphWeaver::Internal::Overrides.resolve(@pins[type_name], rng), coordinate)
+    end
 
     registered, shape = resolve(type_name, coordinate)
     prop = underscore(field_name)
@@ -117,12 +129,31 @@ class GraphWeaver::Internal::Values
     # the plain-notation string BigDecimal() reads and #to_s("F") writes
     when :decimal then format("%.2f", @rng.rand(0.0..10_000.0))
     when :date then (Date.new(2020, 1, 1) + @rng.rand(0..2_000)).iso8601
-    when :time then Time.at(1_600_000_000 + @rng.rand(0..100_000_000)).utc.iso8601
+    # a fraction a quarter of the time: a JS/Apollo server writes milliseconds
+    # on every timestamp, and whole seconds alone can't show a lossy round trip
+    when :time then fake_time.then { |t| t.iso8601(t.subsec.zero? ? 0 : 3) }
     when :unregistered then "#{type_name}-#{@sequence += 1}" # nobody registered it: prop is T.untyped
     else unfakeable!(type_name, field_name, registered, coordinate, at)
     end
   end
 
+  # What the wire would carry for a pinned scalar. A pin may be written as the
+  # Ruby object an app reads back — a Time, a Money — and the registration
+  # says what the server sends for one; a value JSON can already hold stands
+  # as written. Shared with the object-pin door, so both read a pin the same
+  # way.
+  def wire(type_name, value, coordinate = nil)
+    return value if WIRE.any? { |klass| value.is_a?(klass) }
+
+    serialized = @registry.scalar(type_name, coordinate).serialize_value(value)
+    return serialized if WIRE.any? { |klass| serialized.is_a?(klass) }
+
+    article = GraphWeaver::Internal::Util.article(value.class.to_s)
+    raise GraphWeaver::Error, "the pin for #{type_name.inspect} is #{article} #{value.class}, and a pin " \
+      "is what the wire carries — register_scalar(#{type_name.inspect}) has no serialize: that can run " \
+      "against a value (a Proc builds source), so write the pin as the value the server would send"
+  end
+
   # same original id => same fake id, so relationships survive anonymization
   def mapped_id(original)
     @id_map[original] ||= (@sequence += 1).to_s
@@ -130,11 +161,16 @@ class GraphWeaver::Internal::Values
 
   private
 
+  def fake_time
+    usec = @rng.rand(0..3).zero? ? @rng.rand(1..999) * 1_000 : 0
+    Time.at(1_600_000_000 + @rng.rand(0..100_000_000), usec).utc
+  end
+
   # The registration in play and the shape it wants, memoized per scalar (or
   # per coordinate, where a field-level registration overrides it).
   def resolve(type_name, coordinate)
     @resolved[coordinate || type_name] ||= begin
-      registered = GraphWeaver::Codegen.scalar(type_name, coordinate)
+      registered = @registry.scalar(type_name, coordinate)
       [registered, shape_of(type_name, registered.type)]
     end
   end