txray 0.1.0

data/lib/txray/cli.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+require "optparse"
+
+module Txray
+  class CLI
+    EXIT_CLEAN = 0
+    EXIT_OFFENSES = 1
+    EXIT_ERROR = 2
+
+    def self.start(argv, io: $stdout) = new(io: io).run(argv)
+
+    def initialize(io: $stdout)
+      @io = io
+      @options = {}
+    end
+
+    def run(argv)
+      paths = parser.parse(argv)
+      return init_config if @options[:init]
+      return watch if paths.first == "watch"
+
+      config = Config.load(@options[:config]).merge(
+        "fail_level" => @options[:fail_level],
+        "disabled_rules" => @options[:disabled_rules],
+        "max_depth" => @options[:max_depth]
+      )
+
+      result = Scanner.new(config, paths: paths).run
+      result = filter(result)
+      Reporters.build(@options.fetch(:format, "text"), io: @io).report(result)
+      result.failing?(config.fail_level) ? EXIT_OFFENSES : EXIT_CLEAN
+    rescue OptionParser::ParseError, Error => e
+      @io.puts "txray: #{e.message}"
+      EXIT_ERROR
+    end
+
+    private
+
+    def filter(result)
+      return result unless @options[:only]
+
+      Result.new(offenses: result.offenses.select { |offense| @options[:only].include?(offense.id) },
+                 files: result.files, skipped: result.skipped)
+    end
+
+    def watch
+      runtime = Config.load(@options[:config]).runtime
+      WatchCommand.new(
+        path: @options[:file] || runtime["log_path"],
+        threshold_ms: (@options[:threshold] || runtime["threshold_ms"]).to_i,
+        io: @io,
+        from_start: @options[:from_start] == true
+      ).run
+      EXIT_CLEAN
+    end
+
+    def init_config
+      if File.exist?(Config::FILENAME)
+        @io.puts "#{Config::FILENAME} already exists"
+        return EXIT_ERROR
+      end
+
+      File.write(Config::FILENAME, YAML.dump(Config::DEFAULTS))
+      @io.puts "created #{Config::FILENAME}"
+      EXIT_CLEAN
+    end
+
+    def parser
+      OptionParser.new do |opts|
+        opts.banner = "Usage: txray [options] [paths]\n       txray watch [options]"
+        opts.on("-f", "--format FORMAT", "text, json, sarif or github (default: text)") { |v| @options[:format] = v }
+        opts.on("-c", "--config PATH", "path to a .txray.yml file") { |v| @options[:config] = v }
+        opts.on("--fail-level LEVEL", "low, medium, high or none (default: low)") { |v| @options[:fail_level] = v }
+        opts.on("--only RULES", Array, "report only these rule ids") { |v| @options[:only] = v }
+        opts.on("--except RULES", Array, "skip these rule ids") { |v| @options[:disabled_rules] = v }
+        opts.on("--depth N", Integer, "how far to follow method calls (default: 3)") { |v| @options[:max_depth] = v }
+        opts.on("--rules", "list every rule and exit") { list_rules }
+        opts.on("--init", "write a default .txray.yml") { @options[:init] = true }
+        opts.on("--file PATH", "watch: event log written by the runtime guard") { |v| @options[:file] = v }
+        opts.on("--threshold MS", Integer, "watch: slow transaction threshold") { |v| @options[:threshold] = v }
+        opts.on("--from-start", "watch: replay the existing log first") { @options[:from_start] = true }
+        opts.on("-v", "--version", "print the version") { print_and_exit(VERSION) }
+        opts.on("-h", "--help", "print this help") { print_and_exit(opts.to_s) }
+      end
+    end
+
+    def list_rules
+      Rules.all.each_value { |rule| @io.puts "#{rule.id.ljust(34)} #{rule.severity.to_s.ljust(7)} #{rule.remedy}" }
+      exit EXIT_CLEAN
+    end
+
+    def print_and_exit(text)
+      @io.puts text
+      exit EXIT_CLEAN
+    end
+  end
+end

data/lib/txray/client_index.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+module Txray
+  class ClientIndex
+    RETURN_WRITES = [
+      Prism::InstanceVariableOrWriteNode, Prism::InstanceVariableWriteNode,
+      Prism::LocalVariableOrWriteNode, Prism::LocalVariableWriteNode,
+      Prism::ConstantOrWriteNode, Prism::ConstantWriteNode
+    ].freeze
+
+    def initialize(classifier)
+      @classifier = classifier
+      @locals = {}
+      @ivars = {}
+      @constants = {}
+      @methods = {}
+      @delegations = {}
+    end
+
+    def index(source)
+      Namespaces.each(source.root) do |namespace, node|
+        case node
+        when Prism::LocalVariableWriteNode then bind(@locals, source.path, node.name, node.value)
+        when Prism::InstanceVariableWriteNode, Prism::InstanceVariableOrWriteNode
+          bind(@ivars, namespace, node.name, node.value)
+        when Prism::ConstantWriteNode then bind_constant(namespace, node)
+        when Prism::DefNode then bind_method(namespace, node)
+        when Prism::CallNode then bind_delegation(namespace, node)
+        end
+      end
+    end
+
+    def kind_of(node, context, depth = 0)
+      return nil if node.nil? || depth > 4
+
+      case node
+      when Prism::LocalVariableReadNode then @locals.dig(context.path, node.name)
+      when Prism::InstanceVariableReadNode then @ivars.dig(context.namespace, node.name)
+      when Prism::ConstantReadNode, Prism::ConstantPathNode then constant_kind(node, context.namespace)
+      when Prism::CallNode then call_kind(node, context, depth)
+      end
+    end
+
+    def delegated_kind(namespace, name, depth = 0)
+      target = @delegations.dig(namespace, name)
+      return nil if target.nil? || depth > 4
+
+      @methods.dig(namespace, target) || delegated_kind(namespace, target, depth + 1)
+    end
+
+    private
+
+    def call_kind(node, context, depth)
+      return @methods.dig(context.namespace, node.name) if node.receiver.nil?
+
+      constructed_kind(node) || kind_of(node.receiver, context, depth + 1)
+    end
+
+    def constructed_kind(node)
+      @classifier.constructor?(node) ? @classifier.constant_rule(NodeHelpers.constant_name(node.receiver)) : nil
+    end
+
+    def constant_kind(node, namespace)
+      name = NodeHelpers.constant_name(node).to_s
+      @constants[qualify(namespace, name)] || @constants[name]
+    end
+
+    def qualify(namespace, name) = namespace.to_s.empty? ? name.to_s : "#{namespace}::#{name}"
+
+    def bind(table, scope, name, value)
+      kind = source_kind(value)
+      (table[scope] ||= {})[name] = kind if kind
+    end
+
+    def bind_constant(namespace, node)
+      kind = source_kind(node.value)
+      @constants[qualify(namespace, node.name)] = kind if kind
+    end
+
+    def bind_method(namespace, node)
+      kind = returned_kind(node.body)
+      (@methods[namespace] ||= {})[node.name] = kind if kind
+    end
+
+    def returned_kind(body)
+      node = body.is_a?(Prism::StatementsNode) ? body.body.last : body
+      return source_kind(node.value) if RETURN_WRITES.any? { |type| node.is_a?(type) }
+
+      source_kind(node)
+    end
+
+    def bind_delegation(namespace, call)
+      return unless call.name == :delegate && call.receiver.nil?
+
+      target = delegation_target(call)
+      return if target.nil?
+
+      NodeHelpers.symbol_arguments(call).each { |name| (@delegations[namespace] ||= {})[name] = target }
+    end
+
+    def delegation_target(call)
+      hash = NodeHelpers.positional_arguments(call).grep(Prism::KeywordHashNode).first
+      return nil if hash.nil?
+
+      value = hash.elements.grep(Prism::AssocNode).find { |element| key_name(element) == "to" }&.value
+      value.unescaped.to_sym if value.is_a?(Prism::SymbolNode)
+    end
+
+    def key_name(element)
+      element.key.unescaped if element.key.respond_to?(:unescaped)
+    end
+
+    def source_kind(node)
+      return nil unless node.is_a?(Prism::CallNode) && @classifier.constructor?(node)
+
+      @classifier.constant_rule(NodeHelpers.constant_name(node.receiver))
+    end
+  end
+end

data/lib/txray/config.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require "yaml"
+require "pathname"
+
+module Txray
+  class Config
+    FILENAME = ".txray.yml"
+
+    DEFAULTS = {
+      "include" => [ "app", "lib", "db/migrate" ],
+      "exclude" => %w[spec test vendor node_modules tmp log .git],
+      "max_depth" => 3,
+      "fail_level" => "low",
+      "disabled_rules" => [],
+      "external_clients" => [],
+      "severities" => {},
+      "runtime" => {
+        "enabled" => false,
+        "threshold_ms" => 250,
+        "on_violation" => "log",
+        "log_path" => "tmp/txray.ndjson",
+        "ignore" => [],
+        "guard_http" => true,
+        "guard_jobs" => true,
+        "guard_mail" => true
+      }
+    }.freeze
+
+    def self.discover(from = Dir.pwd)
+      Pathname.new(from).ascend do |directory|
+        candidate = directory.join(FILENAME)
+        return candidate.to_s if candidate.file?
+      end
+      nil
+    end
+
+    def self.load(path = nil)
+      raise Error, "no such config file: #{path}" if path && !File.exist?(path)
+
+      path ||= discover
+      data = path ? YAML.safe_load_file(path) : {}
+      new(data.is_a?(Hash) ? data : {})
+    end
+
+    def initialize(data = {})
+      @data = DEFAULTS.merge(data) { |_key, default, given| default.is_a?(Hash) ? default.merge(given.to_h) : given }
+    end
+
+    def includes = Array(@data["include"])
+    def excludes = Array(@data["exclude"])
+    def max_depth = Integer(@data["max_depth"])
+    def external_clients = Array(@data["external_clients"]).map(&:to_s)
+    def disabled_rules = Array(@data["disabled_rules"]).map(&:to_s)
+    def runtime = @data["runtime"].transform_keys(&:to_s)
+
+    def fail_level = @data["fail_level"].to_s.to_sym
+
+    def rule_enabled?(id) = !disabled_rules.include?(id.to_s)
+
+    def rule(id)
+      severity = @data["severities"].to_h[id.to_s]
+      base = Rules[id]
+      return base unless severity
+
+      base.dup.tap { |copy| copy.severity = severity.to_sym }
+    end
+
+    def merge(overrides)
+      self.class.new(@data.merge(overrides.compact.transform_keys(&:to_s)))
+    end
+
+    def to_h = @data
+  end
+end

data/lib/txray/error.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Txray
+  class Error < StandardError; end
+end

data/lib/txray/method_index.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+module Txray
+  MethodEntry = Struct.new(:namespace, :name, :node, :source, :singleton, keyword_init: true) do
+    def label = "#{namespace}#{singleton ? "." : "#"}#{name}"
+    def line = node.location.start_line
+    def path = source.path
+  end
+
+  class MethodIndex
+    MAX_RESOLUTION_DEPTH = 4
+
+    def initialize
+      @instance = {}
+      @singleton = {}
+      @includes = {}
+    end
+
+    def index(source)
+      Namespaces.each(source.root) do |namespace, node|
+        case node
+        when Prism::DefNode then add_method(namespace, node, source)
+        when Prism::CallNode
+          add_include(namespace, node)
+          add_defined_method(namespace, node, source)
+        end
+      end
+    end
+
+    def unique(name)
+      matches = @instance.each_value.filter_map { |methods| methods[name] }
+      matches.first if matches.size == 1
+    end
+
+    def lookup(namespace, name, singleton: false, depth: 0)
+      return nil if namespace.nil? || namespace.empty? || depth > MAX_RESOLUTION_DEPTH
+
+      table = singleton ? @singleton : @instance
+      direct = table.dig(namespace, name)
+      return direct if direct
+
+      from_modules(namespace, name, singleton, depth) || from_lexical_parent(namespace, name, singleton, depth)
+    end
+
+    private
+
+    def add_method(namespace, node, source)
+      singleton = !node.receiver.nil?
+      table = singleton ? @singleton : @instance
+      entry = MethodEntry.new(namespace: namespace, name: node.name.to_sym, node: node, source: source,
+                              singleton: singleton)
+      (table[namespace] ||= {})[entry.name] ||= entry
+    end
+
+    def add_defined_method(namespace, call, source)
+      return unless call.receiver.nil? && call.name == :define_method && call.block.is_a?(Prism::BlockNode)
+
+      name = NodeHelpers.symbol_arguments(call).first
+      return if name.nil?
+
+      entry = MethodEntry.new(namespace: namespace, name: name, node: call.block, source: source, singleton: false)
+      (@instance[namespace] ||= {})[name] ||= entry
+    end
+
+    def add_include(namespace, node)
+      return unless node.receiver.nil? && %i[include prepend extend].include?(node.name)
+
+      NodeHelpers.positional_arguments(node).each do |argument|
+        name = NodeHelpers.constant_name(argument)
+        (@includes[namespace] ||= []) << name if name
+      end
+    end
+
+    def from_modules(namespace, name, singleton, depth)
+      @includes.fetch(namespace, []).each do |mod|
+        resolved = resolve_namespace(namespace, mod)
+        entry = resolved && lookup(resolved, name, singleton: singleton, depth: depth + 1)
+        return entry if entry
+      end
+      nil
+    end
+
+    def from_lexical_parent(namespace, name, singleton, depth)
+      parent = namespace.split("::")[0..-2].join("::")
+      parent.empty? ? nil : lookup(parent, name, singleton: singleton, depth: depth + 1)
+    end
+
+    def resolve_namespace(from, mod)
+      segments = from.split("::")
+      candidates = segments.each_index.map { |i| (segments[0..i] + [ mod ]).join("::") }.reverse
+      (candidates + [ mod ]).find { |candidate| known?(candidate) }
+    end
+
+    def known?(namespace)
+      @instance.key?(namespace) || @singleton.key?(namespace) || @includes.key?(namespace)
+    end
+  end
+
+  module Namespaces
+    module_function
+
+    def each(node, namespace = "", &block)
+      return if node.nil?
+
+      case node
+      when Prism::ClassNode, Prism::ModuleNode
+        child = join(namespace, NodeHelpers.constant_name(node.constant_path))
+        block.call(child, node)
+        each(node.body, child, &block)
+      when Prism::SingletonClassNode
+        each(node.body, namespace, &block)
+      else
+        block.call(namespace, node)
+        node.compact_child_nodes.each { |c| each(c, namespace, &block) }
+      end
+    end
+
+    def join(namespace, name)
+      return namespace if name.nil?
+
+      namespace.empty? ? name : "#{namespace}::#{name}"
+    end
+  end
+end

data/lib/txray/monitor.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Txray
+  class Monitor
+    CAP = 2000
+
+    attr_reader :transactions, :violations, :started_at
+
+    def initialize(threshold_ms: 250)
+      @threshold_ms = threshold_ms
+      @transactions = []
+      @violations = []
+      @recent = []
+      @started_at = Time.now
+    end
+
+    def absorb(line)
+      event = JSON.parse(line, symbolize_names: true)
+      case event[:type]
+      when "transaction" then add(@transactions, event)
+      when "violation" then add(@violations, event)
+      else return nil
+      end
+      @recent.unshift(event)
+      @recent.pop while @recent.size > 40
+      event
+    rescue JSON::ParserError
+      nil
+    end
+
+    def recent(limit) = @recent.first(limit)
+    def durations = @transactions.map { |event| event[:duration_ms].to_f }
+    def slow = @transactions.count { |event| event[:duration_ms].to_f >= @threshold_ms }
+    def flagged = @transactions.count { |event| event[:violations].to_a.any? }
+    def uptime = Time.now - @started_at
+    def empty? = @transactions.empty? && @violations.empty?
+
+    def percentile(fraction)
+      values = durations.sort
+      return 0.0 if values.empty?
+
+      values[[ (values.size * fraction).ceil - 1, 0 ].max]
+    end
+
+    def findings
+      nested = @transactions.flat_map { |event| event[:violations].to_a }
+      slow = @transactions.select { |event| event[:duration_ms].to_f >= @threshold_ms }
+                          .map { |event| { rule: "slow-transaction", source: event[:source] } }
+      @violations + nested + slow
+    end
+
+    def hotspots(limit)
+      findings.group_by { |event| [ event[:rule], event[:source] ] }
+              .map { |(rule, source), events| { rule: rule, source: source, count: events.size } }
+              .sort_by { |entry| -entry[:count] }
+              .first(limit)
+    end
+
+    private
+
+    def add(collection, event)
+      collection << event
+      collection.shift while collection.size > CAP
+    end
+  end
+end

data/lib/txray/node_helpers.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Txray
+  module NodeHelpers
+    module_function
+
+    def each_node(node, &block)
+      return if node.nil?
+
+      block.call(node)
+      node.compact_child_nodes.each { |child| each_node(child, &block) }
+    end
+
+    def constant_name(node)
+      case node
+      when Prism::ConstantReadNode
+        node.name.to_s
+      when Prism::ConstantPathNode
+        [ constant_name(node.parent), constant_path_child(node) ].compact.reject(&:empty?).join("::")
+      when Prism::SelfNode
+        "self"
+      end
+    end
+
+    def constant_path_child(node)
+      return node.name.to_s if node.respond_to?(:name) && node.name
+      return constant_name(node.child) if node.respond_to?(:child)
+
+      nil
+    end
+
+    def symbol_arguments(call)
+      positional_arguments(call).grep(Prism::SymbolNode).map { |symbol| symbol.unescaped.to_sym }
+    end
+
+    def positional_arguments(call)
+      call.arguments&.arguments.to_a
+    end
+
+    def block_body(call)
+      call.block.body if call.block.is_a?(Prism::BlockNode)
+    end
+
+    def receiver_name(call)
+      constant_name(call.receiver) || dynamic_receiver_name(call.receiver)
+    end
+
+    def dynamic_receiver_name(node)
+      case node
+      when Prism::CallNode
+        [ receiver_name(node), node.name ].compact.join(".")
+      when Prism::InstanceVariableReadNode, Prism::GlobalVariableReadNode, Prism::LocalVariableReadNode
+        node.name.to_s
+      end
+    end
+
+    def snippet(node, limit = 90)
+      text = node.slice.to_s.lines.first.to_s.strip
+      text.length > limit ? "#{text[0, limit - 3]}..." : text
+    end
+  end
+end

data/lib/txray/offense.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Txray
+  Frame = Struct.new(:label, :path, :line, keyword_init: true) do
+    def to_s = "#{label} (#{path}:#{line})"
+  end
+
+  class Offense
+    SEVERITIES = %i[low medium high].freeze
+
+    attr_reader :rule, :path, :line, :column, :snippet, :scope, :trace
+
+    def initialize(rule:, path:, line:, column:, snippet:, scope:, trace: [])
+      @rule = rule
+      @path = path
+      @line = line
+      @column = column
+      @snippet = snippet
+      @scope = scope
+      @trace = trace
+    end
+
+    def id = rule.id
+    def severity = rule.severity
+    def severity_rank = SEVERITIES.index(severity) || 0
+    def location = "#{path}:#{line}:#{column}"
+    def message = format(rule.message, snippet: snippet, scope: scope.label)
+
+    def key = [ rule.id, path, line, column ]
+
+    def sort_key = [ -severity_rank, path, line, column ]
+
+    def to_h
+      {
+        rule: rule.id,
+        severity: severity,
+        category: rule.category,
+        path: path,
+        line: line,
+        column: column,
+        message: message,
+        snippet: snippet,
+        scope: { kind: scope.kind, label: scope.label, path: scope.path, line: scope.line },
+        trace: trace.map { |frame| { label: frame.label, path: frame.path, line: frame.line } },
+        remedy: rule.remedy
+      }
+    end
+  end
+end

data/lib/txray/railtie.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Txray
+  class Railtie < ::Rails::Railtie
+    config.txray = ActiveSupport::OrderedOptions.new
+
+    rake_tasks { load File.expand_path("tasks.rake", __dir__) }
+
+    initializer "txray.runtime" do |app|
+      settings = Config.load.runtime.merge(app.config.txray.to_h.transform_keys(&:to_s))
+      next unless settings["enabled"]
+
+      ActiveSupport.on_load(:active_record) do
+        Txray::Runtime.install(
+          threshold_ms: settings["threshold_ms"],
+          on_violation: settings["on_violation"],
+          guard_http: settings["guard_http"],
+          guard_jobs: settings["guard_jobs"],
+          guard_mail: settings["guard_mail"],
+          log_path: settings["log_path"],
+          ignore: settings["ignore"]
+        )
+      end
+    end
+  end
+end

data/lib/txray/reporters/github.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Txray
+  module Reporters
+    class Github
+      LEVELS = { high: "error", medium: "warning", low: "notice" }.freeze
+
+      def initialize(io: $stdout)
+        @io = io
+      end
+
+      def report(result)
+        result.offenses.each do |offense|
+          level = LEVELS.fetch(offense.severity, "warning")
+          title = "txray: #{offense.id}"
+          @io.puts "::#{level} file=#{offense.path},line=#{offense.line},col=#{offense.column},title=#{title}::#{offense.message}"
+        end
+      end
+    end
+  end
+end

data/lib/txray/reporters/json.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Txray
+  module Reporters
+    class Json
+      def initialize(io: $stdout)
+        @io = io
+      end
+
+      def report(result)
+        @io.puts JSON.pretty_generate(
+          version: Txray::VERSION,
+          summary: { files: result.files.size, offenses: result.offenses.size, severities: result.counts,
+                     skipped: result.skipped.to_a },
+          offenses: result.offenses.map(&:to_h)
+        )
+      end
+    end
+  end
+end