gem_dating 0.1.0 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 240b4b51a3ff7ea51e8f5133c5980b857656499d37cb9dca2e427f084f5d8e9f
-  data.tar.gz: 3bee7a49cb6cff56b5ca793cd49103c2e16f60a74dcb8c98313e83c4c3bde008
+  metadata.gz: 50f8a606d682704f10a2ac5378c25a792d4c336ad08e05319e28333dc8ddfcb1
+  data.tar.gz: e8bc47b72796b1db95d67de3602d4bc6f27907807f80ad441b9f31faa7409596
 SHA512:
-  metadata.gz: 350ac78f61900661889eeb66bb3f4ccf9d54d752d8d9034aa910e40827aa3faf0ff8e96c67db75df8a67413e8f18dcdae3359685a45a48d26e68f67133228962
-  data.tar.gz: b03e680f2824c6e8a6a67bc3a8664946e00e5bf881ce1a4977b9e851b5a0596806b55abd6c6272ce737e43c5e499e276e2bb7f3784001c5533c1ad3ffa3cef86
+  metadata.gz: abe1fdb44e970f1b0f0ae005104109da3f4cceb8124e081f81b4fc8a4727df70d0f51186879f96e7451c575aad4449fdeec2b9ef37790e695a1a0f5fe3f14839
+  data.tar.gz: f07e00ddc9906d3a5e378971bc09bbc709b2ba131b9740cbe0cb329c055a1283fb4536be6dbf110255d56860d72d0ac79f1768cab62763116472c511a806821b

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    gem_dating (0.1.0)
+    gem_dating (0.1.2)
       bundler
       table_print
 
@@ -57,6 +57,8 @@ GEM
 
 PLATFORMS
   arm64-darwin-22
+  arm64-darwin-23
+  arm64-darwin-24
   x86_64-linux
 
 DEPENDENCIES

data/README.md

@@ -1,47 +1,68 @@
 # GemDating
 
-GemDating is a library for determining the relative age of a set of gems.
+`gem_dating` is a library for determining the relative age of a set of gems.
 
-The primary use case is when evaluating a codebase for upgrades - a gem from 2017 may effectively be abandoned and could
-cause trouble if you're targeting an upgrade to Ruby 4.1
+The primary use case is when evaluating a codebase for upgrades - a gem from 2017 may effectively be abandoned and could cause trouble if you're targeting an upgrade to Ruby 4.1
 
 ## Usage
 
-### Installation
+If you have rubygems 3.4.8 or later installed, you can skip installation and just run via `gem exec gem_dating [[path/to/Gemfile]`
+
+
+### Gem Installation
 
 `gem install gem_dating` or add it to your Gemfile:
 
 ```ruby
-gem 'gem_dating', group: [:development]
+gem 'gem_dating', group: [:development], require: false
 ```
 
-### Running GemDating
+### Command Line Options
 
-This gem provides a *very* limited command line interface. It may be invoked with:
+GemDating supports several command line options to customize its behavior:
 
-```bash
-$ gem_dating [path/to/Gemfile]
 ```
+gem_dating [OPTIONS] [<GEMFILE_FILEPATH>]
+```
+
+#### Available Options:
 
-Given a path to a Gemfile, GemDating will output a list of gems and their relative ages to the stdout stream.
+- `--help`, `-h`, `-?`: Show the help message
+- `--older-than=<AGE>`, `--ot=<AGE>`: Filter gems updated within the last X time period
+  - Examples: `--older-than=2y` (2 years), `--ot=1m` (1 month), `--ot=4w` (4 weeks), `--ot=10d` (10 days)
+- `--sort-by=<FIELD>`: Sort by field
+  - Available fields: `name` or `date`
+  - Default: `name`
+- `--order=<DIRECTION>`: Sort direction
+  - Available directions: `asc` (ascending) or `desc` (descending)
+  - Default: `asc`
+- `--json`: Output results as JSON instead of table format
 
-For example:
+#### Examples:
 
 ```bash
-$ gem_dating ~/code/my_app/Gemfile
-``` 
-to read the output in your terminal.
+# Show gems older than 1 year
+$ gem_dating --older-than=1y
+
+# Sort gems by date in descending order (newest first)
+$ gem_dating --sort-by=date --order=desc
 
-Or you can run
+# Output results as JSON
+$ gem_dating --json
+
+# Combine multiple options
+$ gem_dating ~/code/my_app/Gemfile --older-than=6m --sort-by=date --order=desc
+```
+
+GemDating leans on `$stdout`, so you can pipe the output to a file if you'd like:
 ```bash
 $ gem_dating ~/code/my_app/Gemfile > ~/code/my_app/gem_ages.txt
 ```
-which will pipe the output into a text file. 
 
-The command line output will look something like this:
+[TablePrint](https://github.com/arches/table_print) formats the output to something like this:
 
 ```bash
-NAME        | VERSION | DATE      
+NAME        | VERSION | DATE
 ------------|---------|-----------
 rest-client | 2.1.0   | 2019-08-21
 rails       | 7.0.5   | 2023-05-24
@@ -53,7 +74,7 @@ passing in a string of a gem name, or a path to a Gemfile. You can then parse th
 a minimal hash, or the Table output you'd see in the CLI.
 
 ```ruby
-# irb 
+# irb
 # #:001 >
 
 require "gem_dating"
@@ -64,22 +85,32 @@ more_dating = GemDating.from_file("path/to/Gemfile")
 
 
 dating.to_a
-# => [Gem::Specification.new do |s|                               
+# => [Gem::Specification.new do |s|
 # s.name = "rails"
 # s.version = Gem::Version.new("7.0.5")
 # s.installed_by_version = Gem::Version.new("0") ...etc
 
 dating.to_h
-# =>  {"rails"=>{"name"=>"rails", "version"=>"7.0.5", "date"=>"2023-05-24"}} 
+# =>  {"rails"=>{"name"=>"rails", "version"=>"7.0.5", "date"=>"2023-05-24"}}
 
 more_dating.table_print
-# => 
+# =>
 # NAME        | VERSION | DATE
 # ------------|---------|-----------
 # rails       | 7.0.5   | 2023-05-24
 # ...etc
 ```
 
+### Caveats
+
+`gem_dating` avoids utilizing Bundler, and intends to be useful where you want to evaluate a set of gems without
+the overhead of a full bundle install. If you've got a valid bundle you should consider the built in
+[bundle-outdated](https://bundler.io/v2.4/man/bundle-outdated.1.html), or other available tools for interacting
+with your Gemfile, like [libyear-bundler](https://github.com/jaredbeck/libyear-bundler).
+
+Sometimes we [get incorrect dates](https://github.com/testdouble/gem_dating/issues/10). 
+TLDR; sometimes GemSpecs are built in an environment where the date gets overwritten. That'll be up to the gem
+owner(s) to determine if they'd like to adjust it to provide accurate dates.
 
 
 ## Code of Conduct

data/Rakefile

@@ -7,4 +7,4 @@ Rake::TestTask.new(:test) do |t|
   t.test_files = FileList["test/**/*_test.rb"]
 end
 
-task :default => :test
+task default: :test

data/gem_dating.gemspec

@@ -1,27 +1,26 @@
-
 lib = File.expand_path("../lib", __FILE__)
 $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
 require "gem_dating/version"
 
 Gem::Specification.new do |spec|
-  spec.name          = "gem_dating"
-  spec.version       = GemDating::VERSION
-  spec.authors       = ["Steve Jackson", "Daniel Huss"]
-  spec.email         = ["steve@testdouble.com"]
+  spec.name = "gem_dating"
+  spec.version = GemDating::VERSION
+  spec.authors = ["Steve Jackson", "Daniel Huss"]
+  spec.email = ["steve@testdouble.com"]
 
-  spec.summary       = "How old is that anyway?"
-  spec.homepage      = "https://github.com/testdouble/gem_dating"
-  spec.license       = "MIT"
+  spec.summary = "How old is that anyway?"
+  spec.homepage = "https://github.com/testdouble/gem_dating"
+  spec.license = "MIT"
 
   spec.metadata["homepage_uri"] = spec.homepage
   spec.metadata["source_code_uri"] = spec.homepage
   spec.metadata["changelog_uri"] = "#{spec.homepage}/blob/main/CHANGELOG.md"
 
-  spec.files         = Dir.chdir(File.expand_path('..', __FILE__)) do
+  spec.files = Dir.chdir(File.expand_path("..", __FILE__)) do
     `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
   end
-  spec.bindir        = "exe"
-  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.bindir = "exe"
+  spec.executables = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = ["lib"]
 
   spec.add_dependency "bundler"

data/lib/gem_dating/cli.rb

@@ -3,21 +3,73 @@ module GemDating
     SUCCESS = 0
     GENERAL_ERROR = 1
 
-    def initialize(argv)
-      @argv = argv
+    HELP_TEXT =
+      <<~HELP
+        gem_dating [--help | -h] [<GEMFILE_FILEPATH>]
+
+        GEMFILE_FILEPATH defaults to ./Gemfile if not provided.
+
+        Options:
+          --help, -h, -?  Show this help message
+          --older-than=<AGE>, --ot=<AGE>    Filter gems updated within the last X (e.g. 2y, 1m, 4w, 10d)
+          --sort-by=<FIELD>                 Sort by field (name or date), defaults to name
+          --order=<DIRECTION>               Sort direction (asc or desc), defaults to asc
+          --json                            Output results as JSON
+      HELP
+
+    def initialize(argv = [])
+      args, file_path = argv.partition { |arg| (arg =~ /--\w+/) || (arg =~ /(-[a-z])/) }
+
+      @args = args
+      @file_path = file_path.first
+      @options = parse_args
     end
 
     def run
-      if @argv.empty?
-        $stdout << "Usage: gem_dating [GEMFILE_FILEPATH]\n"
-        return GENERAL_ERROR
+      if @options[:help]
+        $stdout << HELP_TEXT
+        return SUCCESS
       end
 
-      path = @argv.first
+      unless @file_path
+        current_directory = Dir.pwd
+        file_path = File.join(current_directory, "Gemfile")
 
-      $stdout << GemDating.from_file(path).table_print << "\n"
+        if File.exist?(file_path)
+          @file_path = file_path
+        else
+          $stdout << HELP_TEXT
+          return GENERAL_ERROR
+        end
+      end
+
+      result = GemDating.from_file(@file_path, @options)
+      output = @options[:json] ? result.to_json : result.table_print
+      $stdout << output << "\n"
 
       SUCCESS
     end
+
+    private
+
+    def parse_args(args = @args)
+      options = {}
+      options[:help] = true if (args & %w[-h --help -?]).any?
+      options[:json] = true if args.include?("--json")
+
+      if (older_than = args.find { |arg| arg.start_with?("--older-than=", "--ot=") })
+        options[:older_than] = older_than.split("=").last
+      end
+
+      if (sort_by = args.find { |arg| arg.start_with?("--sort-by=") })
+        options[:sort_by] = sort_by.split("=").last
+      end
+
+      if (order = args.find { |arg| arg.start_with?("--order=") })
+        options[:order] = order.split("=").last
+      end
+
+      options
+    end
   end
 end

data/lib/gem_dating/input.rb

@@ -19,17 +19,18 @@ module GemDating
       lines.each_with_object([]) do |line, gems|
         line = gem_line(line.strip)
         gems << cleanup(line) if line
-      end
+      end.uniq
     end
 
     def gem_line(line)
-      return if line.strip == "end"
+      single_word_ruby_statements = %w[end else # gemspec]
+      return if single_word_ruby_statements.include? line.strip
 
       if line.start_with? "gem("
         line.split("(")[1].split(",")[0]
       elsif line.start_with? "gem"
         line.split[1].split(",")[0]
-      elsif line.split.length == 1
+      elsif line.split.length == 1 # match "just" gemname
         line
       end
     end

data/lib/gem_dating/result.rb

@@ -1,4 +1,5 @@
 require "table_print"
+require "json"
 
 module GemDating
   class Result
@@ -24,5 +25,57 @@ module GemDating
     def table_print
       TablePrint::Printer.table_print(specs, [:name, :version, {date: {time_format: "%Y-%m-%d", width: 10}}]).encode("utf-8")
     end
+
+    def to_json
+      JSON.generate(to_h)
+    end
+
+    def older_than(date)
+      specs.select! { |spec| spec.date.to_date < cut_off(date) }
+      self
+    end
+
+    def sort(options = {})
+      field = options[:sort_by] || "name"
+      direction = options[:order] || "asc"
+
+      @specs = @specs.sort_by do |spec|
+        case field
+        when "name"
+          spec.name.downcase
+        when "date"
+          spec.date
+        else
+          spec.name.downcase
+        end
+      end
+
+      @specs = @specs.reverse if direction.downcase == "desc"
+
+      self
+    end
+
+    private
+
+    def cut_off(date)
+      return unless date
+      curr_date = Date.today
+
+      number = date[0..-2].to_i
+      unit = date[-1]
+
+      case unit
+      when "y"
+        curr_date << (12 * number)
+      when "m"
+        curr_date << number
+      when "w"
+        curr_date - (number * 7)
+      when "d"
+        curr_date - number
+      else
+        raise ArgumentError, "Invalid date format: #{date}"
+      end
+    end
   end
 end

data/lib/gem_dating/version.rb

@@ -1,3 +1,3 @@
 module GemDating
-  VERSION = "0.1.0"
+  VERSION = "0.1.2"
 end

data/lib/gem_dating.rb

@@ -5,15 +5,23 @@ require_relative "gem_dating/result"
 require_relative "gem_dating/cli"
 
 module GemDating
-  def self.from_string(s)
+  def self.from_string(s, options = {})
     gems = Input.string(s).gems
-    specs = Rubygems.fetch(gems)
-    Result.new(specs)
+    fetch_specs(gems, options)
   end
 
-  def self.from_file(path)
+  def self.from_file(path, options = {})
     gems = Input.file(path).gems
+    fetch_specs(gems, options)
+  end
+
+  def self.fetch_specs(gems, options)
     specs = Rubygems.fetch(gems)
-    Result.new(specs)
+    results = Result.new(specs)
+    results.older_than(options[:older_than]) if options[:older_than]
+    results.sort(options)
+    results
   end
+
+  private_class_method :fetch_specs
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: gem_dating
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.2
 platform: ruby
 authors:
 - Steve Jackson
@@ -9,7 +9,7 @@ authors:
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2023-07-19 00:00:00.000000000 Z
+date: 2025-06-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -88,7 +88,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.6
+rubygems_version: 3.4.10
 signing_key:
 specification_version: 4
 summary: How old is that anyway?