whatthegem 0.0.1

data/lib/whatthegem/gem.rb

@@ -0,0 +1,64 @@
+require 'gems'
+require 'octokit'
+require 'base64'
+
+module WhatTheGem
+  class Gem
+    GITHUB_URI_PATTERN = %r{^https?://(www\.)?github\.com/}
+
+    NoGem = Struct.new(:name) do
+      def exists?
+        false
+      end
+    end
+
+    def self.fetch(name)
+      # Empty hash in rubygems info means it does not exist.
+      # FIXME: Could be wrong in case of: a) private gems and b) "local-only" command checks
+      new(name).then { |gem| gem.rubygems.info.empty?  ? NoGem.new(name) : gem }
+    end
+
+    attr_reader :name
+
+    def initialize(name)
+      @name = name
+    end
+
+    def exists?
+      true
+    end
+
+    memoize def rubygems
+      RubyGems.new(name)
+    end
+
+    memoize def github
+      rubygems.info.to_h.values_at(:source_code_uri, :homepage_uri)
+        .then(&method(:detect_repo_id))
+        &.then(&GitHub.method(:new))
+    end
+
+    memoize def specs
+      ::Gem::Specification.select { |s| s.name == name }.sort_by(&:version)
+    end
+
+    memoize def bundled
+      Bundled.fetch(name)
+    end
+
+    private
+
+    # FIXME: active_record's actual path is https://github.com/rails/rails/tree/v5.2.1/activerecord
+    def detect_repo_id(urls)
+      # Octokit can't correctly guess repo slug from https://github.com/bitaxis/annotate_models.git
+      urls.grep(GITHUB_URI_PATTERN).first
+          &.sub(/\.git$/, '')
+          &.then(&Octokit::Repository.method(:from_url))
+          &.slug
+    end
+  end
+end
+
+require_relative 'gem/rubygems'
+require_relative 'gem/github'
+require_relative 'gem/bundled'

data/lib/whatthegem/help.rb

@@ -0,0 +1,31 @@
+module WhatTheGem
+  class Help < Command
+    TEMPLATE = Template.parse(<<~HELP)
+      `whatthegem` is a small tool for fetching information about Ruby gems from various sources.
+
+      **Usage:** `whatthegem <gemname> [<command>]`
+
+      Known commands:
+
+      {% for command in commands %}
+      * `{{command.handle}}`: {{command.description}}{% endfor %}
+    HELP
+
+    def initialize(*)
+    end
+
+    def locals
+      {commands: commands}
+    end
+
+    private
+
+    def full_output
+      markdown output
+    end
+
+    def commands
+      Command.registry.values.map(&:meta).map(&:to_h)
+    end
+  end
+end

data/lib/whatthegem/hobject.rb

@@ -0,0 +1,61 @@
+module WhatTheGem
+  class Hobject
+    class << self
+      def deep(hash_or_array)
+        deep_value(hash_or_array)
+      end
+
+      private
+
+      def deep_value(val)
+        case
+        when val.respond_to?(:to_hash)
+          val.to_hash.transform_values(&method(:deep_value)).then(&method(:new))
+        when val.respond_to?(:to_ary)
+          val.to_ary.map(&method(:deep_value))
+        else
+          val
+        end
+      end
+    end
+
+    def initialize(hash)
+      @hash = hash.transform_keys(&:to_sym).freeze
+      @hash.each do |key, val|
+        define_singleton_method(key) { val }
+        define_singleton_method("#{key}?") { !!val }
+      end
+    end
+
+    def to_h
+      @hash
+    end
+
+    def merge(other)
+      Hobject.new(to_h.merge(other.to_h))
+    end
+
+    def deep_to_h
+      @hash.transform_values(&method(:val_to_h))
+    end
+
+    def inspect
+      '#<Hobject(%s)>' % @hash.map { |k, v| "#{k}: #{v.inspect}" }.join(', ')
+    end
+
+    alias to_s inspect
+
+    private
+
+    def val_to_h(value)
+      case value
+      when Hobject
+        value.deep_to_h
+      when Array
+        value.map(&method(:val_to_h))
+      else
+        value
+      end
+    end
+  end
+end

data/lib/whatthegem/i.rb

@@ -0,0 +1,56 @@
+require 'rdoc'
+require 'kramdown'
+require 'pastel'
+
+# Will be necessary when switching to kramdown-2, but tty-markdown doesn't support it yet.
+# require 'kramdown-parser-gfm'
+
+module WhatTheGem
+  # I for Internal
+  # @private
+  module I
+    extend self
+
+    module Callable
+      def to_proc
+        proc { |*args| call(*args) }
+      end
+    end
+
+    Pastel = ::Pastel.new
+
+    module Kramdowns
+      extend self
+
+      def elements(source)
+        Kramdown::Document.new(source, input: 'GFM').root.children
+      end
+
+      # Somehow there is no saner methods for converting parsed element back to source :shrug:
+      def el2md(el)
+        el.options[:encoding] = 'UTF-8'
+        el.attr.replace({}) # don't render header anchors
+        Kramdown::Converter::Kramdown.convert(el, line_width: 1000).first
+      end
+    end
+
+    module RDocs
+      extend self
+
+      def parts(source)
+        RDoc::Comment.new(source).parse.parts
+      end
+
+      def part2md(part)
+        formatter = RDoc::Markup::ToMarkdown.new
+        RDoc::Markup::Document.new(part).accept(formatter)
+      end
+    end
+
+    def ago_text(tm)
+      diff = TimeMath.measure(tm, Time.now)
+      unit, num = diff.detect { |_, v| !v.zero? }
+      "#{num} #{unit} ago"
+    end
+  end
+end

data/lib/whatthegem/info.rb

@@ -0,0 +1,58 @@
+module WhatTheGem
+  class Info < Command
+    register description: '(default) General information about the gem'
+
+    # About info shortening: It is because minitest pastes their whole README
+    # there, including a quotations of how they are better than RSpec.
+    # (At the same time, RSpec's info reads "BDD for Ruby".)
+
+    TEMPLATE = Template.parse(<<~INFO)
+                Latest version: {{info.version}} ({{age}})
+            Installed versions: {% if specs %}{{ specs | map:"version" | join: ", "}}{% else %}—{% endif %}
+      {% if current %}
+      Most recent installed at: {{current.dir}}
+      {% endif %}
+      {% unless bundled.type == 'nobundle' %}
+                In your bundle: {% if bundled.type == 'notbundled' %}—{% else
+      %}{{ bundled.version }} at {{ bundled.dir }}{% endif %}
+      {% endunless %}
+
+      Try also:
+      {% for command in commands %}
+        `whatthegem {{info.name}} {{command.handle}}` -- {{command.description}}{% endfor %}
+    INFO
+
+    def locals
+      {
+        info: gem.rubygems.info,
+        age: age,
+        specs: specs,
+        current: specs.last,
+        bundled: gem.bundled.to_h,
+        commands: commands
+      }
+    end
+
+    private
+
+    def age
+      gem.rubygems.versions
+        .first&.dig(:created_at)
+        &.then(&Time.method(:parse))&.then(&I.method(:ago_text))
+    end
+
+    def specs
+      gem.specs.map { |spec|
+        {
+          name: spec.name,
+          version: spec.version.to_s,
+          dir: spec.gem_dir
+        }
+      }
+    end
+
+    def commands
+      Command.registry.values.-([self.class]).map(&:meta).map(&:to_h)
+    end
+  end
+end

data/lib/whatthegem/stats/definitions.rb

@@ -0,0 +1,50 @@
+require 'time_math'
+
+module WhatTheGem
+  class Stats
+    module Definitions
+      require_relative 'meters'
+
+      FIFTY_PLUS = proc { |res| res == 50 ? '50+' : res }
+      HAS_REACTION = proc { |i| i[:labels].any? || i[:comments].positive? }
+
+      def self.meters
+        @meters ||= []
+      end
+
+      def self.metric(name, *path, thresholds: nil, &block)
+        meters << Meter.new(name, path, thresholds, block || :itself.to_proc)
+      end
+
+      # TODO: Replace with TimeCalc when it'll be ready.
+      # TimeMath.month.decrease(now) => TimeCalc.now.-(1, :month)
+      T = TimeMath
+      now = Time.now
+
+      metric 'Downloads', :rubygems, :info, :downloads, thresholds: [5_000, 10_000]
+      metric 'Latest version',
+        :rubygems, :versions, 0, :created_at,
+        thresholds: [T.year.decrease(now), T.month.decrease(now, 2)],
+        &Time.method(:parse)
+
+      metric 'Used by', :rubygems, :reverse_dependencies, :count, thresholds: [10, 100]
+
+      metric 'Stars', :github, :repo, :stargazers_count, thresholds: [100, 500]
+      metric 'Forks', :github, :repo, :forks_count, thresholds: [5, 20]
+      metric 'Last commit',
+        :github, :last_commit, :commit, :committer, :date,
+        thresholds: [T.month.decrease(now, 4), T.month.decrease(now)]
+
+      metric('Open issues', :github, :open_issues, :count, &FIFTY_PLUS)
+      metric('...without reaction', :github, :open_issues, thresholds: [-20, -4]) { |issues|
+        issues.reject(&HAS_REACTION).count
+      }
+      metric('...last reaction',
+        :github, :open_issues,
+        thresholds: [T.month.decrease(now), T.week.decrease(now)]
+      ) { |issues| issues.detect(&HAS_REACTION)&.dig(:updated_at) }
+      metric('Closed issues', :github, :closed_issues, :count, &FIFTY_PLUS)
+      metric '...last closed', :github, :closed_issues, 0, :closed_at
+    end
+  end
+end

data/lib/whatthegem/stats/meters.rb

@@ -0,0 +1,78 @@
+require 'pastel'
+
+module WhatTheGem
+  class Stats
+    class Meter < Struct.new(:name, :path, :thresholds, :block)
+      def call(gem)
+        dig(gem, *path)&.then(&block)
+          .then { |val| Metric.new(name, val, *thresholds) }
+      end
+
+      private
+
+      def dig(value, first = nil, *rest)
+        return value unless first
+        case value
+        when nil
+          value
+        when ->(v) { first.is_a?(Symbol) && v.respond_to?(first) }
+          dig(value.public_send(first), *rest)
+        when Hash, Array
+          value.dig(first, *rest)
+        else
+          fail "Can't dig #{first} in #{value}"
+        end
+      end
+    end
+
+    class Metric
+      attr_reader :value, :name, :color
+
+      def initialize(name, value, *thresholds)
+        @name = name
+        @value = value
+        @color = deduce_color(*thresholds)
+      end
+
+      def format
+        '%20s: %s' % [name, colorized_value]
+      end
+
+      private
+
+      def colorized_value
+        Pastel.new.send(color, formatted_value)
+      end
+
+      def formatted_value
+        case value
+        when nil
+          '—'
+        when String
+          value
+        when Numeric
+          # 100000 => 100,000
+          value.to_s.chars.reverse.each_slice(3).to_a.map(&:join).join(',').reverse
+        when Date, Time
+          I.ago_text(value)
+        else
+          fail ArgumentError, "Unformattable #{value.inspect}"
+        end
+      end
+
+      def deduce_color(red = nil, yellow = nil)
+        return :dark if value.nil?
+        return :white if !yellow # no thresholds given
+
+        # special trick to tell "lower is better" from "higher is better" situations
+        val = red.is_a?(Numeric) && red < 0 ? -value : value
+
+        case
+        when val < red then :red
+        when val < yellow then :yellow
+        else :green
+        end
+      end
+    end
+  end
+end

data/lib/whatthegem/stats.rb

@@ -0,0 +1,12 @@
+module WhatTheGem
+  class Stats < Command
+    register description: 'Gem freshness and popularity stats'
+
+    def output
+      Definitions.meters.map { |meter| meter.call(gem).format }.join("\n")
+    end
+  end
+end
+
+require_relative 'stats/meters'
+require_relative 'stats/definitions'

data/lib/whatthegem/template.rb

@@ -0,0 +1,53 @@
+require 'liquid'
+require 'rouge'
+
+module WhatTheGem
+  class Template < Liquid::Template
+    module Filters
+      def paragraphs(text, num)
+        # split on markdown-alike paragraph break (\n\n), or "paragraph, then list" (\n* )
+        text.split(/\n(?:\n|(?= *\*))/).first(num).join("\n\n").gsub(/\n +/, "\n").strip
+      end
+
+      def reflow(text)
+        text.tr("\n", ' ')
+      end
+
+      def nfirst(array, num)
+        array.first(num)
+      end
+
+      # Consistently shift all markdown headers - ### - so they would be at least minlevel deep
+      def md_header_shift(text, minlevel)
+        current_min = text.scan(/^(\#+) /).flatten.map(&:length).min
+        return text if !current_min || current_min > minlevel
+        shift = minlevel - current_min
+        text.gsub(/^(\#+) /, '#' * shift + '\\1 ')
+      end
+
+      def rouge(text)
+        lexer = Rouge::Lexers::Ruby.new
+        Rouge::Formatters::Terminal256.new(Rouge::Themes::Base16::Monokai.new).format(lexer.lex(text))
+      end
+    end
+
+    def self.parse(src)
+      new.parse(src.chomp.gsub(/\n *({%.+?%})\n/, "\\1\n"))
+    end
+
+    def parse(src)
+      super(src, error_mode: :strict)
+    end
+
+    def render(data, **options)
+      super(Hm.(data).transform_keys(&:to_s).to_h, filters: [Filters], **options)
+    end
+
+    alias call render
+
+    def to_proc
+      # proc { |data| render(data) }
+      method(:call).to_proc
+    end
+  end
+end

data/lib/whatthegem/tty-markdown_patch.rb

@@ -0,0 +1,9 @@
+module WhatTheGem
+  module TTYMarkdownPatch
+    def convert_br(el, opts)
+      opts[:result] << "\n"
+    end
+  end
+
+  ::TTY::Markdown::Parser.include TTYMarkdownPatch
+end

data/lib/whatthegem/usage/extractor.rb

@@ -0,0 +1,104 @@
+require 'ripper'
+
+module WhatTheGem
+  class Usage
+    # TODO:
+    # more robustly ignore "installation" section or just remove gem 'foo' / gem install
+    # -> select only ```ruby section from markdown (if they exist)?
+    # -> more removal patterns? Like `rake something`
+    #
+    class Extractor
+      REMOVE_BLOCKS = [
+        %{gem ['"]},      # gem install instructions
+        'gem install',
+        'bundle install',
+        'rake ',
+
+        'rails g ',       # rails generator
+        'git clone',      # instructions to contribute
+
+        '\\$',            # bash command
+        'ruby (\S+)$',    # run one Ruby command
+
+        'Copyright '      # Sometimes they render license in ```
+      ]
+
+      REMOVE_BLOCKS_RE = /^#{REMOVE_BLOCKS.join('|')}/
+
+      extend I::Callable
+
+      class CodeBlock < Struct.new(:body)
+        def initialize(body)
+          super(try_sanitize(body))
+        end
+
+        def ruby?
+          # Ripper returns nil for anything but correct Ruby
+          #
+          # TODO: Unfortunately, Ripper is fixed to current version syntax, so trying this trick on
+          # Ruby 2.4 with something that uses Ruby 2.7 features will unhelpfully return "no, not Ruby"
+          #
+          # Maybe trying parser gem could lead to the same effect
+          !Ripper.sexp(body).nil?
+        end
+
+        def service?
+          body.match?(REMOVE_BLOCKS_RE)
+        end
+
+        def to_h
+          {body: body}
+        end
+
+        private
+
+        def try_sanitize(text)
+          text
+            .gsub(/^>> /, '')                   # Imitating work from IRB, TODO: various IRB/Pry patterns
+            .gsub(/^(=> )/, '# \\1')            # Output in IRB, should be hidden as comment
+            .gsub(/^(Results: )/, '# \\1')      # Output, in some gems
+            .gsub(/^( *)(\.{2,})/, '\\1# \\2')  # "...and so on..." in code examples
+        end
+      end
+
+      def self.call(file)
+        new(file).call
+      end
+
+      def initialize(file)
+        @file = file
+      end
+
+      def call
+        code_blocks(file.read).map(&CodeBlock.method(:new)).reject(&:service?).select(&:ruby?)
+      end
+
+      private
+
+      attr_reader :file
+
+      memoize def format
+        case file.basename.to_s
+        when /\.(md|markdown)$/i
+          :markdown
+        else
+          :rdoc
+        end
+      end
+
+      def code_blocks(content)
+        __send__("#{format}_code_blocks", content)
+      end
+
+      def markdown_code_blocks(content)
+        I::Kramdowns.elements(content)
+          .select { |c| c.type == :codeblock }
+          .map(&:value).map(&:strip)
+      end
+
+      def rdoc_code_blocks(content)
+        I::RDocs.parts(content).grep(RDoc::Markup::Verbatim).map(&:text)
+      end
+    end
+  end
+end

data/lib/whatthegem/usage.rb

@@ -0,0 +1,47 @@
+module WhatTheGem
+  # TODO
+  # use Piotr's markdown formatter
+  #
+  # friendly report of "usage instructions not found"
+  #
+  # If gem not found locally -- fetch from GitHub
+  #
+  class Usage < Command
+    register description: 'Gem usage examples'
+
+    TEMPLATE = Template.parse(<<~USAGE)
+      {% for u in usage %}
+      {{ u.body | rouge }}
+      {% endfor %}
+    USAGE
+
+    README_NOT_FOUND = I::Pastel.red.bold("Can't find `README` locally or in repo to extract usage.")
+
+    def locals
+      {
+        usage: readme.then(&Extractor).first(2).map(&:to_h)
+      }
+    end
+
+    private
+
+    def output
+      return README_NOT_FOUND unless readme
+      super
+    end
+
+    memoize def readme
+      local_readme || github_readme
+    end
+
+    def local_readme
+      gem.specs.last&.gem_dir&.then(&Pathname.method(:new))&.glob('README{,.*}')&.first
+    end
+
+    def github_readme
+      gem.github&.readme
+    end
+  end
+end
+
+require_relative 'usage/extractor'

data/lib/whatthegem.rb

@@ -0,0 +1,12 @@
+require 'hm'
+
+module WhatTheGem
+end
+
+require_relative 'whatthegem/core_ext'
+require_relative 'whatthegem/i'
+
+require_relative 'whatthegem/gem'
+require_relative 'whatthegem/template'
+require_relative 'whatthegem/hobject'
+require_relative 'whatthegem/commands'