job_grapher 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: cd41d58ef6c11f7e0b6c1989b75434a0e9bc410010350608619e413c4aa3999c
+  data.tar.gz: 8e7456d73ccf71b53b8861d4ea6e2d9e40614c42db13b59c0476448be1c0b14a
+SHA512:
+  metadata.gz: 7277bedcf1fdc757958dbe4eb311e2c5a95f81b45960dbbe50be52262381ad2a6e51385df445f5c7f2332a3dfa39b57bc77c2b5cb216b3b2dca04f93a30fe377
+  data.tar.gz: 399aae0f3e25ce96fed12fa6d1ca2b75aaa9fde7dd9c8dfed9ad9105326141560837fd26783a895fe5e3559c8948808aacf05648f4e9637723b79fe0a6a721c6

data/Gemfile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+# Specify your gem's dependencies in job_grapher.gemspec
+gemspec
+
+gem "rake", "~> 13.0"

data/LICENSE

@@ -0,0 +1,14 @@
+Copyright 2022 Jeremy Friesen
+Additional copyright may be held by others, as reflected in the commit history.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+   http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

data/README.md

@@ -0,0 +1,49 @@
+# JobGrapher
+
+While looking through multiple gems and applications, I needed a little tool to help me.
+
+This gem outputs a [PlantUML](https://plantuml.com) diagram of class/location's that perform a job.  The parser and logic were built while exploring [Samvera](https://samvera.org)'s ActiveJob implementations.
+
+This gem requires [Ripgrep](https://github.com/BurntSushi/ripgrep).
+
+## Installation
+
+Install the gem and add to the application's Gemfile by executing:
+
+    $ bundle add job_grapher
+
+If bundler is not being used to manage dependencies, install the gem by executing:
+
+    $ gem install job_grapher
+
+## Usage
+
+This gem came about as a thought experiment.  Here's the command line:
+
+```shell
+job_grapher ~/path/to/repo ~/path/to/other-repo
+```
+
+### From Ruby
+
+At present, the command-line only allows you to specify directories.  However, you can call the underlying Ruby class and provide additional parameters.
+
+```ruby
+require "job_grapher"
+
+JobGrapher.plantuml_for(
+  dirs: [
+    "~/git/hyrax",
+    "~/git/bulkrax",
+    "~/git/hyku",
+    "~/git/newspaper_works/"
+  ],
+  filter: ->(job) do
+    job.include?("Permission") || job.include?("Ingest")
+  end
+)
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/jeremyf/job_grapher.

data/Rakefile

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+task default: %i[]

data/exe/job_grapher

@@ -0,0 +1,9 @@
+#!/usr/bin/env ruby -U
+
+require_relative File.expand_path("../lib/job_grapher", __dir__)
+
+if ARGV.size == 0
+  $STDERR.puts "You must provide at least one directory"
+  exit!(1)
+end
+JobGrapher.plantuml_for(dirs: ARGV)

data/job_grapher.gemspec

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require_relative "lib/job_grapher/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "job_grapher"
+  spec.version = JobGrapher::VERSION
+  spec.authors = ["Jeremy Friesen"]
+  spec.email = ["jeremy.n.friesen@gmail.com"]
+
+  spec.summary = "A naive graph generator for ActiveJob's declared and called across projects."
+  spec.description = "A naive graph generator for ActiveJob's declared and called across projects."
+  spec.homepage = "https://github.com/jeremyf/job_grapher"
+  spec.required_ruby_version = ">= 2.6.0"
+
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] =  spec.homepage
+  spec.metadata["changelog_uri"] = spec.homepage
+
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      (f == __FILE__) || f.match(%r{\A(?:(?:bin|test|spec|features)/|\.(?:git|travis|circleci)|appveyor)})
+    end
+  end
+  spec.bindir = "exe"
+  spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+end

data/lib/job_grapher/version.rb

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

data/lib/job_grapher.rb

@@ -0,0 +1,228 @@
+require "set"
+
+# @see .plant_uml
+module JobGrapher
+  DEFAULT_FILTER = ->(job) { true }
+  DEFAULT_PATH_FORMATTER = -> (path) { path.sub(ENV['HOME'], "~") }
+  # @api public
+  #
+  # Generate a PlantUML diagram
+  #
+  # @param dirs [Array<String>] the directories to check for jobs and
+  #        performance.
+  # @param path_formatter [String] for file names, remove this from
+  #        the beginning of that path.
+  # @param filter [#call] the filter to call which when true means to
+  #        include the given job's class name in the generated graph.
+  #        When false, skip this job.
+  # @param buffer [#puts] the buffer to which we'll "#puts" the graph.
+  #
+  # @see https://plantuml.com
+  def self.plantuml_for(dirs:, path_formatter: DEFAULT_PATH_FORMATTER, filter: DEFAULT_FILTER, buffer: STDOUT)
+    graph = Graph.new(filter: filter)
+    Array(dirs).each do |dir|
+      PerformInformation.each_from(dir) do |info|
+        graph.add_perform_info(info)
+      end
+
+      JobDeclaration.each_from(dir) do |declaration|
+        graph.add_declaration(declaration)
+      end
+    end
+    graph.to_plantuml(path_formatter: path_formatter, buffer: buffer)
+    true
+  end
+
+  class Graph
+    def initialize(filter:)
+      @performances = []
+      @declarations = []
+      @filter = filter
+    end
+
+    def add_declaration(declaration)
+      @declarations << declaration
+    end
+
+    def add_perform_info(info)
+      @performances << info
+    end
+
+    def to_plantuml(buffer:, path_formatter:)
+      buffer.puts "@startuml"
+      resolver = Resolver.new(
+        declarations: @declarations,
+        performances: @performances,
+        filter: @filter,
+        path_formatter: path_formatter
+      )
+
+      resolver.edges.each do |edge|
+        buffer.puts "(#{edge.from}) --> (#{edge.to})"
+      end
+      buffer.puts "@enduml"
+    end
+  end
+
+  class Resolver
+    def initialize(declarations:, performances:, filter:, path_formatter:)
+      @declarations = declarations
+      @performances = performances
+      @filter = filter
+      @path_formatter = path_formatter
+      compile!
+    end
+
+    attr_reader :edges, :filter, :path_formatter
+
+    Edge = Struct.new(:from, :to, keyword_init: true)
+
+    # For each performance's job_class_name_candidates find the corresponding constant.
+    def compile!
+      @edges = Set.new
+      jobs = @declarations.map(&:job_class_name)
+      @performances.each do |perf|
+        from = path_formatter.call(perf.invoking_constant)
+        to = perf.job_class_name_candidates.find do |cand|
+          jobs.include?(cand)
+        end
+        next unless filter.call(to)
+        @edges << Edge.new(from: from, to: to)
+      end
+    end
+  end
+
+  # This module extracts the qualified constant name for a declared
+  # class/module.
+  module QualifiedConstantNameExtractor
+    NAMESPACE_REGEXP = %r{^(?<padding> *)(class|module) +(?<namespace>[\w:]+)[ \n]}
+    # @param path [String]
+    # @param line_number [Integer, #to_i]
+    # @return [String]
+    def self.call(path:, line_number:)
+      declarations = module_delcarations_for(path: path, line_number: line_number.to_i)
+      determine_namespace_from(declarations: declarations)
+    end
+
+    def self.module_delcarations_for(path:, line_number:)
+      declarations = []
+
+      # Should we read this in reverse order?
+      File.readlines(path).each_with_index do |line, index|
+        break if index + 1 > line_number
+        match = NAMESPACE_REGEXP.match(line)
+        next unless match
+        declarations << match
+      end
+      declarations
+    end
+    private_class_method :module_delcarations_for
+
+    def self.determine_namespace_from(declarations:)
+      # Based on convention, this would be a 40 deep module; gods have
+      # mercy.
+      current_padding_size = 80
+      qualified_module_name = []
+      # This will be easier to do if we reverse things; Because we can
+      # handle files that have multiple module declarations.
+      declarations.reverse.each do |dec|
+        if dec[:padding].length < current_padding_size
+          current_padding_size = dec[:padding].length
+          qualified_module_name.unshift(dec[:namespace])
+        end
+      end
+      qualified_module_name.join("::")
+    end
+    private_class_method :determine_namespace_from
+  end
+
+  class PerformInformation
+    def self.each_from(dir)
+      command = %(rg "^ *[^#]*Job\\.perform" #{dir} -g '!spec/' -n)
+      `#{command}`.split("\n").each do |line|
+        parser = Parser.new(line)
+        info = new(
+          path: parser.path,
+          invoking_constant: parser.invoking_constant,
+          job_class_name_candidates: parser.job_class_name_candidates
+        )
+        yield(info)
+      end
+    end
+
+    def initialize(path:, invoking_constant:, job_class_name_candidates:)
+      @path = path
+      @invoking_constant = invoking_constant
+      @job_class_name_candidates = job_class_name_candidates
+    end
+
+    attr_reader :path, :invoking_constant, :job_class_name_candidates
+
+    class Parser
+      LINE_REGEXP = %r{(?<path>[^:]*):(?<line_number>[^:]*):(?<content>.*)}
+      JOB_REGEXP = %r{(?<job>[\w:]+Job)\.perform}
+      def initialize(grep_result_line)
+        @grep_result_line = grep_result_line
+        match = LINE_REGEXP.match(grep_result_line)
+        @path = match[:path].strip
+        @line_number = match[:line_number].to_i
+        @content = match[:content]
+        @invoking_constant = QualifiedConstantNameExtractor.call(path: @path, line_number: @line_number)
+
+        @job = JOB_REGEXP.match(@content)[:job]
+
+        if @invoking_constant.length == 0
+          @job_class_name_candidates = [@job]
+          @invoking_constant = @path
+        else
+          @job_class_name_candidates = determine_job_candidates_from(job: @job, namespace: @invoking_constant)
+        end
+      end
+
+      attr_reader :path
+      attr_reader :invoking_constant
+      attr_reader :job_class_name_candidates
+
+      private
+      def determine_job_candidates_from(job:, namespace:)
+        candidates = [job]
+        slugs = namespace.split("::")
+        slugs.each_with_index do |mod, i|
+          candidates << slugs[0..i].join("::") + "::" + job
+        end
+        candidates
+      end
+    end
+
+  end
+
+  # This class is responsible for parsing where we found a job and building the possible name space of
+  # the job.
+  class JobDeclaration
+    def self.each_from(dir)
+      command = %(rg "^ *class ([\\w:]+)Job <" #{dir} -g '!spec/' -n)
+      `#{command}`.split("\n").each do |line|
+        yield(new(line))
+      end
+    end
+
+    include Comparable
+    def <=>(other)
+      job_class_name <=> other.job_class_name
+    end
+
+    LINE_REGEXP = %r{(?<path>[^:]*):(?<line_number>[^:]*):(?<content>.*)}
+    JOB_REGEXP = %r{(?<job>[\w:]+Job) \<}
+    def initialize(grep_result_line)
+      @grep_result_line = grep_result_line
+      match = LINE_REGEXP.match(grep_result_line)
+      @path = match[:path].strip
+      @line_number = match[:line_number].to_i
+      @content = match[:content]
+      @job = JOB_REGEXP.match(@content)[:job]
+      @job_class_name = QualifiedConstantNameExtractor.call(path: @path, line_number: @line_number)
+    end
+
+    attr_reader :job_class_name
+  end
+end

metadata

@@ -0,0 +1,54 @@
+--- !ruby/object:Gem::Specification
+name: job_grapher
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Jeremy Friesen
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2022-10-22 00:00:00.000000000 Z
+dependencies: []
+description: A naive graph generator for ActiveJob's declared and called across projects.
+email:
+- jeremy.n.friesen@gmail.com
+executables:
+- job_grapher
+extensions: []
+extra_rdoc_files: []
+files:
+- Gemfile
+- LICENSE
+- README.md
+- Rakefile
+- exe/job_grapher
+- job_grapher.gemspec
+- lib/job_grapher.rb
+- lib/job_grapher/version.rb
+homepage: https://github.com/jeremyf/job_grapher
+licenses: []
+metadata:
+  homepage_uri: https://github.com/jeremyf/job_grapher
+  source_code_uri: https://github.com/jeremyf/job_grapher
+  changelog_uri: https://github.com/jeremyf/job_grapher
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.6.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.3.7
+signing_key:
+specification_version: 4
+summary: A naive graph generator for ActiveJob's declared and called across projects.
+test_files: []