polariscope 0.3.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1c891a85ae5f5fed5a3cba46ddb78c81657baedfac15bcf31de9002fdae9c6df
-  data.tar.gz: 3864c4ecf3833289fb1cb1af30df8316a646f62714962f034e60ab42d0ab11f9
+  metadata.gz: 70b3d555c09bbe2378d8771d0975b34427f089700b9e7852917ffe80e6a79259
+  data.tar.gz: 1e87403b8f56622b02b11b5aab0439d503ae6410c88dcb4fa7213464be2e7ffe
 SHA512:
-  metadata.gz: c008254c44678d2a936e027e33bba206ac12f48f7350d5aa63f5105e8897713fc851664d46afa02f665f11d53ad4459094b6795e3ba4caefaf58b3918d74fd47
-  data.tar.gz: 8e123d4cc077831e1fc252d846655b0994e3f78836affdc11af73ad9df9ae87bedf3c5ead5012be77f6b010d38585172d7e31800f23f86241f68b74cae3c97d2
+  metadata.gz: 19874d31ca4475d6f3976935270d7c80816f12094b5fc31f25fa80571ddc161ca61a3645b250d91ce8b8bed4b6fbb73e057c90fc2fc15c6b8c99bce4e34b0dda
+  data.tar.gz: 8e71615763f0a844074a2b8c214b6c2b7698344d238774c9c2245fe118808cdeed9be611e54c2d723678a03208f6a5c1e77497cb7962e2dc281fea9a71beefa0

data/.rubocop.yml

@@ -21,8 +21,5 @@ Style/FrozenStringLiteralComment:
   Exclude:
     - 'exe/polariscope'
 
-Rails/TimeZone:
-  Enabled: false
-
-Rails/Date:
+Rails:
   Enabled: false

data/CHANGELOG.md

@@ -1,5 +1,15 @@
 ## [Unreleased]
 
+## [0.5.0] - 2024-10-30
+
+- Fix regression for standalone installation
+- Raise `Polariscope::Error` on unparseable Gemfile
+
+## [0.4.0] - 2024-10-25
+
+- Count Ruby versions towards health score
+- Update audit database if older than one day
+
 ## [0.3.0] - 2024-10-17
 
 - Count Ruby advisories towards health score

data/README.md

@@ -1,74 +1,204 @@
-# Polariscope
+# Polariscope 🔬
 
-Polariscope is a Ruby gem designed to evaluate the overall health of your Ruby application by analyzing its dependencies. It calculates a health score based on how many dependencies are outdated, meaning there are newer versions available. Keeping dependencies up-to-date is crucial for maintaining application security, performance, and compatibility. This gem provides a quick and easy way to gauge the state of your project's dependencies and take proactive measures to improve its health.
+Polariscope is a Ruby gem to evaluate the overall health of your Ruby application by analyzing its dependencies. It calculates a [health score](#health-score-formula) based on which dependencies are outdated and vulnerable to security issues.
 
-### Health Score Algorithm
+Keeping dependencies up-to-date is crucial for maintaining application security, performance, and compatibility. This gem provides a quick and easy way to gauge the state of your project's dependencies and take measures to improve its health (more on this in the [Motivation section](#motivation)).
 
-The health score calculation is based on the following mathematical formula:
-
-![Health Score Algorithm](docs/algorithm.png)
+Think of this gem as a way to score outputs of `bundle outdated` and `bundle-audit check`.
 
 ## Installation
 
-Install the gem and add to the application's Gemfile by executing:
+Add it to your Gemfile:
 
     $ bundle add polariscope
 
-If bundler is not being used to manage dependencies, install the gem by executing:
+or install standalone:
 
     $ gem install polariscope
 
-### Known issue
-
-If your default Ruby version is 3.1.2, you might get this error when installing polariscope:
-
-```bash
-.rbenv/versions/3.1.2/lib/ruby/gems/3.1.0/gems/rdoc-6.7.0/lib/rdoc/version.rb:8: warning: already initialized constant RDoc::VERSION
-ERROR:  While executing gem ... (NameError)
-    uninitialized constant RDoc::Markdown
+## Usage
 
-    'markdown' => RDoc::Markdown,
-                      ^^^^^^^^^^
-```
+Polariscope can be used on the CLI and in code.
 
-You can ignore this error. It doesn't occur in other Ruby versions and it doesn't prevent you from using polariscope.
+### CLI
 
-## Usage
+Position yourself at the root of your Ruby application and run:
 
-Polariscope can be used in 2 ways.
+    $ [bundle exec] polariscope scan
+    => 87.4
 
-### CLI
+The command will read the contents of `Gemfile`, `Gemfile.lock` and [`.bundler-audit.yml`](https://github.com/rubysec/bundler-audit?tab=readme-ov-file#configuration-file) (optional, to ignore advisories) in the current directory and output the calculated health score.
 
-Position yourself in a Ruby application and run:
+### In code
 
-```bash
-polariscope scan
+```ruby
+health_score = Polariscope.scan
 ```
 
-### IRB / Rails
+Without arguments, it will do the same as above. Optionally, you can override various parameters:
 
 ```ruby
-Polariscope.scan
+Polariscope.scan(
+  gemfile_content: '', # e.g. File.read('Gemfile')
+  gemfile_lock_content: '', # e.g. File.read('Gemfile.lock')
+  bundler_audit_config_content: '', # e.g. File.read('.bundler-audit.yml')
+  spec_type: :latest, # see https://docs.ruby-lang.org/en/master/Gem/SpecFetcher.html#method-i-available_specs
+  dependency_priorities: { ruby: 5.0, devise: 10.0 }, # hash of dependency priorities
+  group_priorities: { default: 5.0, test: 2.0 }, # hash of bundler group priorities
+  default_dependency_priority: 2.0,
+  advisory_severity: 1.09, # number >= 1
+  advisory_penalties: { medium: 2.0, critical: 5.0 }, # hash of advisory penalties by criticality
+  fallback_advisory_penalty: 2.0, # used if value not found in previous hash
+  major_version_penalty: 0.5, # number in range [0, 1]
+  new_versions_severity: 1.09, # number >= 1
+  segment_severities: [1.7, 1.15, 1.01], # ordered by segments: [major, minor, patch]
+  fallback_segment_severity: 1.01, # in case dependency versions have more segments than in segment_severities
+)
 ```
 
-The return value will indicate how healthy your project is on a scale from 0 to 100.
+For details on what these parameters mean, consult [this section](#health-score-formula).
 
 #### Additional features
 
-##### Gem versions
-
 Get the released or latest version of gems with:
 
 ```ruby
 # released versions
-gem_specs = Polariscope.gem_versions(['gem_name_1', 'gem_name_2'])
-gem_specs.versions_for('gem_name_1') # => returns potentially many versions
+gem_specs = Polariscope.gem_versions(['devise', 'pundit'])
+gem_specs.versions_for('devise')
+# => returns potentially many versions
 
 # latest version
-gem_specs = Polariscope.gem_versions(['gem_name_1', 'gem_name_2'], spec_type: :latest)
-gem_specs.versions_for('gem_name_1') # => returns latest version
+gem_specs = Polariscope.gem_versions(['devise', 'punt'], spec_type: :latest)
+gem_specs.versions_for('pundit')
+# => returns only the latest version
 ```
 
+## Health Score Formula
+
+Health score is calculated with a formula that takes the contents of `Gemfile` and `Gemfile.lock` and produces a decimal number in the $[0,100]$ range. 100 means everything is up-to-date and there are no security issues, and it lowers as newer versions are released or security issues are discovered.
+
+By design, health score is most useful as a relative measure of application health: if your health score suddenly drops one day from 100 to 90, it signals a serious issue (e.g. a new vulnerability in your Ruby version). If it drops from 100 to 95, it may signal that a new minor version of Rails has been released, for example. If it drops from 100 to 99.5, it may mean a gem like Pundit has a new patch version with a bug fix.
+
+How much the score changes depends on various factors:
+- dependency priority (by default, [Ruby and Rails have a higher priority](https://github.com/infinum/polariscope/blob/master/lib/polariscope/scanner/calculation_context.rb#L6) than other dependencies)
+- [bundler group](https://bundler.io/guides/groups.html) priority (by default, [`:default` and `:production` groups have a higher priority](https://github.com/infinum/polariscope/blob/master/lib/polariscope/scanner/calculation_context.rb#L7))
+- number of versions between the current and the latest version of a dependency
+- the kind of outdatedness according to [SemVer](https://semver.org/); if there's a new major version, that will cause a sharper drop in the score than a new minor version
+- the number of active security advisories
+- [advisory severity](https://nvd.nist.gov/vuln-metrics/cvss) (e.g. a High severity advisory will cause a sharper drop in score than one that is Low)
+
+### Formula
+
+[This is the complete formula](https://github.com/infinum/polariscope/blob/master/lib/polariscope/scanner/gemfile_health_score.rb#L22) (it's simpler than it may seem):
+```math
+{HS}_G =
+100
+\cdot
+\underbrace{\left(1-\frac{\sum_{d \in G_{dd}}w_d \cdot mp_d}{\sum_{d \in G_{dd}}w_d}\right)}_{\text{major versions score}}
+\cdot
+\underbrace{\left(\frac{\sum_{d \in G_{dd}}w_d \cdot {dhs}_d}{\sum_{d \in G_{dd}}w_d}\right)}_{\text{versions score}}
+\cdot
+\underbrace{\left(1 +\sum_{d \in G} \sum_{a \in d} p_a\right)^{-\ln{S_A}}}_{\text{advisories score}}
+```
+
+```math
+\begin{array}{ll}
+G & \text{Gemfile} \\
+G_{dd} & \text{subset of Gemfile with direct dependencies only} \\
+d & \text{dependency} \\
+\dotso & \text{see below for other symbols}
+\end{array}
+```
+
+It's comprised of several scores in the $[0,1]$ range multiplied together and then finally by 100 to produce the final score. Score formulas are described in the following sections.
+
+Note that, by design, health score can never be higher than the lowest of its scores. For example, if your major versions score is 0.75, then health score can never be higher than 75, regardless of other scores being 1.
+
+### Major versions score
+
+Score that signals how many dependencies have outdated major versions (it doesn't care about minor or patch versions). Score 1 means no dependency has an outdated major while score 0 means all have an outdated major. Other combinations fall in between those extremes.
+
+[The formula](https://github.com/infinum/polariscope/blob/master/lib/polariscope/scanner/gemfile_health_score.rb#L30-L36) $1-\frac{\sum_{d \in G_{dd}}w_d \cdot mp_d}{\sum_{d \in G_{dd}}w_d}$ starts with score 1 and is subtracted by the [weighted arithmetic mean](https://en.wikipedia.org/wiki/Weighted_arithmetic_mean) of major version penalties for all direct dependencies (only dependencies specified in the `Gemfile` and not dependencies of dependencies present in `Gemfile.lock`). The penalty controls how much the score drops when the major of a dependency is outdated, and the priority proportions that penalty in relation to other dependencies.
+
+[Dependency priority (weight)](https://github.com/infinum/polariscope/blob/master/lib/polariscope/scanner/calculation_context.rb#L40-L44) $w_d$ is set to either a custom dependency priority, bundler group priority if dependency doesn't have a custom priority, or default priority if dependency's group doesn't have a defined priority ([default values](https://github.com/infinum/polariscope/blob/master/lib/polariscope/scanner/calculation_context.rb#L6-L8)).
+
+[Major version penalty](https://github.com/infinum/polariscope/blob/master/lib/polariscope/scanner/gem_health_score.rb#L21-L23) ${mp}_d$ is a number in range $[0,1]$; [by default](https://github.com/infinum/polariscope/blob/master/lib/polariscope/scanner/calculation_context.rb#L20) it equals 1. When the major isn't outdated, there is no penalty (penalty equals 0).
+
+### Versions score
+
+Score that represents how outdated direct dependencies are based on the number of new versions and the kind of outdatedness. Score 1 means all dependencies are up-to-date. As dependencies get outdated, it starts to lower. Unlike major versions score, this score can never reach 0, it only gravitates towards it.
+
+[The formula](https://github.com/infinum/polariscope/blob/master/lib/polariscope/scanner/gemfile_health_score.rb#L38-L40) $`\frac{\sum_{d \in G_{dd}}w_d \cdot {dhs}_d}{\sum_{d \in G_{dd}}w_d}`$ is a weighted arithmetic mean of dependency health scores. Same dependency priority $w_d$ is used as for major versions score.
+
+[Dependency health score](https://github.com/infinum/polariscope/blob/master/lib/polariscope/scanner/gem_health_score.rb#L15-L18) ${dhs}_d$ is calculated with the following formula:
+```math
+{dhs}_d=
+\underbrace{(1+{sp}_d)^{-\ln{{ss}_d}}}_{\text{segment subscore}}
+\cdot
+\underbrace{(1+{vp}_d)^{-\ln{S_{V}}}}_{\text{versions subscore}}
+```
+
+Both subscores use a version of the power function. See [this section](#penalty-and-severity-function) for more details on its interpretation.
+
+#### Segment subscore
+
+[Score](https://github.com/infinum/polariscope/blob/master/lib/polariscope/scanner/gem_health_score.rb#L16) in the $(0,1]$ range that represents how outdated is the **first** outdated segment (major, minor or patch) of a dependency. When the current version is also the latest, the score equals 1, and it starts to drop towards 0 with the release of new versions.
+
+[Segment penalty](https://github.com/infinum/polariscope/blob/master/lib/polariscope/scanner/gem_health_score.rb#L43-L45) ${sp}_d$ is defined as the number of new versions for the first outdated segment. Take this example: your dependency is on `v1.0.0`, but `v1.1.0`, `v2.0.0` and `v3.0.0` have been released in the meantime. The first outdated segment is major (minor is also outdated, but it comes after major, so it's not the first). ${sp}_d$ is then the number of new majors, in this case 2.
+
+[Segment severity](https://github.com/infinum/polariscope/blob/master/lib/polariscope/scanner/gem_health_score.rb#L35-L37) ${ss}_d$ is a number selected based on the first outdated segment. Default list of severities can be found [here](https://github.com/infinum/polariscope/blob/master/lib/polariscope/scanner/calculation_context.rb#L22) (order `[major, minor, patch]`). For example, if major is outdated, first value in the list is used.
+
+#### Versions subscore
+
+[Score](https://github.com/infinum/polariscope/blob/master/lib/polariscope/scanner/gem_health_score.rb#L17) in the $(0,1]$ range that represents how many new versions have been released for the dependency since the current version.  When the current version is also the latest, the score equals 1, and it lowers with every new version.
+
+Penalty $`{vp}_d`$ is defined as the total number of versions between the current and the latest version (inclusive). Severity $`S_{V}`$ is a constant ([default value](https://github.com/infinum/polariscope/blob/master/lib/polariscope/scanner/calculation_context.rb#L21)).
+
+### Advisories score
+
+Score in the $(0,1]$ range that represents how many security advisories impact your dependencies, taking into account their severities. Unlike previous scores, this score looks at all dependencies, direct or indirect (basically, everything in `Gemfile.lock`). Score 1 means no dependency has an active advisory, and it drops with each new advisory.
+
+[The formula](https://github.com/infinum/polariscope/blob/master/lib/polariscope/scanner/advisories_health_score.rb#L12) $\left(1 +\sum_{d \in G} \sum_{a \in d} p_a\right)^{-\ln{S_A}}$ in essence sums advisory penalties $p_a$ for all advisories of all dependencies (+1) and raises it to some power. See the next section for a detailed explanation.
+
+[Advisory penalty](https://github.com/infinum/polariscope/blob/master/lib/polariscope/scanner/calculation_context.rb#L46-L48) $p_a$ is a number selected based on the criticality (severity score mapped to a name) of the advisory ([default mapping](https://github.com/infinum/polariscope/blob/master/lib/polariscope/scanner/calculation_context.rb#L11-L17)). Generally, a higher criticality results in a higher penalty. If criticality is unknown, fallback penalty is used ([default value](https://github.com/infinum/polariscope/blob/master/lib/polariscope/scanner/calculation_context.rb#L18)). Severity $S_A$ is a constant ([default value](https://github.com/infinum/polariscope/blob/master/lib/polariscope/scanner/calculation_context.rb#L10)).
+
+### Penalty and severity function
+
+Function used for several scores is of type $f(x)=(1+x)^{-S}$, where $S$ is some positive constant.
+
+See this graph for various values $S$ (we'll focus on case $x\ge0$):
+![graph plots f(x) for three values of S: 0.05, 0.17, 0.5](./docs/severity_function_graph.png)
+and notice several interesting properties:
+1. $f(0)=1$
+2. $f(x+1) \lt f(x)$
+3. $\lim_{x \to \infty} f(x)=0$
+4. bigger $S$ -> more severe "drop"
+
+The function returns values in range $(0,1]$ (props 1-3). It begins with value 1 (prop 1) which drops the further away we move from $x=0$ (prop 2). Property 4 allows us to control how quickly the value drops.
+
+This can be used as a simple but an okay way to model certain scores. For scoring purposes we will refer to $x$ as penalty and $S$ as severity. Take for example the [versions subscore](#versions-subscore), which uses this function: penalty is the number of new versions for a dependency, so the more new versions there are, the lower the score.
+
+$^*$ In all formulas, severity is a natural logarithm $ln$ of some constant greater than 1. This is purely because actual constants $S$ need to be small enough (smaller than 0.1) to not cause too sharp a drop in the score too fast. It's easier to work with bigger numbers, so instead of $(1+x)^{-S}$ we work with $(1+x)^{-\ln(S)}$.
+
+## Motivation
+
+Who is this tool for? What does it accomplish?
+
+Agencies like [Infinum](https://infinum.com/) are at any point in time working on multiple projects, e.g. multiple Ruby applications. Without a monitoring process, it would be necessary to manually check each project for security vulnerabilities and new dependency versions (e.g. a new major version with a breaking change). With scale, this becomes time-consuming.
+
+Health score is a way to monitor these things. Instead of manually checking each project for outdated dependencies (output of `bundle outdated`) and security advisories (output of `bundle-audit check`), health score informs you whether those outputs require immediate action.
+
+As was said above, health score is most useful as a relative measure. It starts at value 100 and it drops as new versions/security issues arise. Your project might have a score of 99 one day, but suddenly drop to 90 the next — this signals something significant happened, probably a security advisory in an important dependency like Rails, or a new major version of Ruby. On the other hand, if it drops from 99 to 97, it could mean some dependency has a new minor version.
+
+It's up to you to decide when to take action: either when the score drops suddenly (to fix immediate issues) or when it drops below a certain threshold (to update multiple dependencies in one go).
+
+At Infinum, Polariscope is used as part of a monitoring tool that (among other things) calculates health scores for all Ruby projects daily. Part of the project table looks like this:<br />
+<img src="./docs/health_score_table.png" alt="table with project health scores" width="450">
+
+The health score is also shown as a badge on the repository README:<br />
+<img src="./docs/health_score_badge.png" alt="repo readme with health score badge" width="300">
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.

data/lib/polariscope/scanner/advisories_health_score.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Polariscope
+  module Scanner
+    class AdvisoriesHealthScore
+      def initialize(dependency_context, calculation_context)
+        @dependency_context = dependency_context
+        @calculation_context = calculation_context
+      end
+
+      def health_score
+        (1 + advisories_penalty)**-Math.log(calculation_context.advisory_severity)
+      end
+
+      private
+
+      attr_reader :dependency_context
+      attr_reader :calculation_context
+
+      def advisories_penalty
+        dependency_context
+          .advisories
+          .map(&:criticality)
+          .sum { |criticality| calculation_context.advisory_penalty_for(criticality) }
+      end
+    end
+  end
+end

data/lib/polariscope/scanner/audit_database.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require 'bundler/audit/database'
+
+module Polariscope
+  module Scanner
+    module AuditDatabase
+      extend self
+
+      ONE_DAY = 24 * 60 * 60
+
+      def update_if_necessary
+        update_audit_database! if database_outdated?
+      end
+
+      private
+
+      def update_audit_database!
+        Bundler::Audit::Database.update!(quiet: true)
+      end
+
+      def database_outdated?
+        audit_db_missing? || audit_db_stale?
+      end
+
+      def audit_db_missing?
+        !Bundler::Audit::Database.exists?
+      end
+
+      def audit_db_stale?
+        ((Time.now - Bundler::Audit::Database.new.last_updated_at) / ONE_DAY) > 1.0
+      end
+    end
+  end
+end

data/lib/polariscope/scanner/calculation_context.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module Polariscope
+  module Scanner
+    class CalculationContext
+      DEPENDENCY_PRIORITIES = { ruby: 10.0, rails: 10.0 }.freeze
+      GROUP_PRIORITIES = { default: 2.0, production: 2.0 }.freeze
+      DEFAULT_DEPENDENCY_PRIORITY = 1.0
+
+      ADVISORY_SEVERITY = 1.09
+      ADVISORY_PENALTIES = {
+        none: 0.0,
+        low: 0.5,
+        medium: 1.0,
+        high: 3.0,
+        critical: 5.0
+      }.freeze
+      FALLBACK_ADVISORY_PENALTY = 0.5
+
+      MAJOR_VERSION_PENALTY = 1
+      NEW_VERSIONS_SEVERITY = 1.07
+      SEGMENT_SEVERITIES = [1.7, 1.15, 1.01].freeze
+      FALLBACK_SEGMENT_SEVERITY = 1.0
+
+      def initialize(**opts)
+        @dependency_priorities = opts.fetch(:dependency_priorities, DEPENDENCY_PRIORITIES)
+        @group_priorities = opts.fetch(:group_priorities, GROUP_PRIORITIES)
+        @default_dependency_priority = opts.fetch(:default_dependency_priority, DEFAULT_DEPENDENCY_PRIORITY)
+
+        @advisory_severity = opts.fetch(:advisory_severity, ADVISORY_SEVERITY)
+        @advisory_penalties = opts.fetch(:advisory_penalties, ADVISORY_PENALTIES)
+        @fallback_advisory_penalty = opts.fetch(:fallback_advisory_penalty, FALLBACK_ADVISORY_PENALTY)
+
+        @major_version_penalty = opts.fetch(:major_version_penalty, MAJOR_VERSION_PENALTY)
+        @new_versions_severity = opts.fetch(:new_versions_severity, NEW_VERSIONS_SEVERITY)
+        @segment_severities = opts.fetch(:segment_severities, SEGMENT_SEVERITIES)
+        @fallback_segment_severity = opts.fetch(:fallback_segment_severity, FALLBACK_SEGMENT_SEVERITY)
+      end
+
+      def priority_for(dependency)
+        dependency_priorities[dependency.name.to_sym] ||
+          group_priorities[dependency.groups.first] ||
+          default_dependency_priority
+      end
+
+      def advisory_penalty_for(criticality)
+        advisory_penalties.fetch(criticality, fallback_advisory_penalty)
+      end
+
+      def segment_severity(segment)
+        return 1.0 unless segment
+
+        segment_severities.fetch(segment, fallback_segment_severity)
+      end
+
+      attr_reader :advisory_severity
+      attr_reader :new_versions_severity
+      attr_reader :major_version_penalty
+
+      private
+
+      attr_reader :dependency_priorities
+      attr_reader :default_dependency_priority
+      attr_reader :group_priorities
+      attr_reader :advisory_penalties
+      attr_reader :fallback_advisory_penalty
+      attr_reader :segment_severities
+      attr_reader :fallback_segment_severity
+    end
+  end
+end

data/lib/polariscope/scanner/dependency_context.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+require_relative 'ruby_scanner'
+
+require 'tempfile'
+require 'bundler/audit/configuration'
+
+module Polariscope
+  module Scanner
+    class DependencyContext
+      DEFAULT_SPEC_TYPE = :released
+
+      def initialize(**opts)
+        @gemfile_content = opts.fetch(:gemfile_content, nil)
+        @gemfile_lock_content = opts.fetch(:gemfile_lock_content, nil)
+        @bundler_audit_config_content = opts.fetch(:bundler_audit_config_content, '')
+        @spec_type = opts.fetch(:spec_type, DEFAULT_SPEC_TYPE)
+      end
+
+      def no_dependencies?
+        blank_value?(gemfile_content) || blank_value?(gemfile_lock_content) || dependencies.empty?
+      end
+
+      def dependencies
+        @dependencies ||= dependencies_with_ruby
+      end
+
+      def dependency_versions(dependency)
+        [current_dependency_version(dependency), gem_versions.versions_for(dependency.name)]
+      end
+
+      def advisories
+        specs
+          .flat_map { |gem| audit_database.check_gem(gem).to_a }
+          .concat(ruby_scanner.vulnerable_advisories)
+          .reject { |advisory| ignored_advisories.intersect?(advisory.identifiers.to_set) }
+      end
+
+      private
+
+      attr_reader :gemfile_content
+      attr_reader :gemfile_lock_content
+      attr_reader :bundler_audit_config_content
+      attr_reader :spec_type
+
+      def ruby_scanner
+        @ruby_scanner ||= RubyScanner.new(bundle_definition.locked_ruby_version_object)
+      end
+
+      def gem_versions
+        @gem_versions ||= GemVersions.new(dependencies.map(&:name), spec_type: spec_type)
+      end
+
+      def bundle_definition # rubocop:disable Metrics/MethodLength
+        @bundle_definition ||=
+          ::Tempfile.create do |gemfile|
+            ::Tempfile.create do |gemfile_lock|
+              gemfile.puts parseable_gemfile_content
+              gemfile.rewind
+
+              gemfile_lock.puts gemfile_lock_content
+              gemfile_lock.rewind
+
+              Bundler::Definition.build(gemfile.path, gemfile_lock.path, false)
+            end
+          end
+      rescue Bundler::Dsl::DSLError => e
+        raise Polariscope::Error, "Unable to parse the provided Gemfile/Gemfile.lock: #{e.message}"
+      end
+
+      def current_dependency_version(dependency)
+        return ruby_scanner.version if dependency.name == GemVersions::RUBY_NAME
+
+        specs.find { |spec| dependency.name == spec.name }.version
+      end
+
+      def dependencies_with_ruby
+        return installed_dependencies unless ruby_scanner.version
+
+        installed_dependencies + [Bundler::Dependency.new(GemVersions::RUBY_NAME, false)]
+      end
+
+      def installed_dependencies
+        spec_names = specs.to_set(&:name)
+
+        bundle_definition.dependencies.select { |dependency| spec_names.include?(dependency.name) }
+      end
+
+      def specs
+        bundle_definition.locked_gems.specs
+      end
+
+      def ignored_advisories
+        audit_configuration.ignore
+      end
+
+      def audit_configuration
+        @audit_configuration ||= Tempfile.create do |file|
+          file.puts bundler_audit_config_content
+          file.rewind
+
+          Bundler::Audit::Configuration.load(file.path)
+        rescue StandardError
+          Bundler::Audit::Configuration.new
+        end
+      end
+
+      def audit_database
+        @audit_database ||= Bundler::Audit::Database.new
+      end
+
+      def parseable_gemfile_content
+        gemfile_content.gsub("gemspec\n", '').gsub(/^ruby.*$\R/, '')
+      end
+
+      def blank_value?(value)
+        value.nil? || value.empty?
+      end
+    end
+  end
+end

data/lib/polariscope/scanner/gem_health_score.rb

@@ -3,29 +3,37 @@
 module Polariscope
   module Scanner
     class GemHealthScore
-      def initialize(all_versions:, current_version:, severities: [])
-        @all_versions = all_versions
-        @current_version = current_version
-        @severities = severities
+      def initialize(dependency_context, calculation_context, dependency)
+        @calculation_context = calculation_context
+
+        @current_version, @all_versions = dependency_context.dependency_versions(dependency)
       end
 
       def health_score
-        return 100 if up_to_date?
+        return 1.0 if up_to_date?
 
-        score = 100
-        score *= (1.0 + first_outdated_segment)**-Math.log(first_outdated_segment_severity)
-        score *= (1.0 + new_versions.count)**-Math.log(1.07)
+        score = 1.0
+        score *= (1 + first_outdated_segment)**-Math.log(first_outdated_segment_severity)
+        score *= (1 + new_versions.count)**-Math.log(calculation_context.new_versions_severity)
         score
       end
 
+      def major_version_penalty
+        major_version_outdated? ? calculation_context.major_version_penalty : 0
+      end
+
+      private
+
+      attr_reader :calculation_context
+      attr_reader :current_version
+      attr_reader :all_versions
+
       def up_to_date?
         current_version == latest_version
       end
 
       def first_outdated_segment_severity
-        return 1 if first_outdated_segment_index.nil?
-
-        severities[first_outdated_segment_index]
+        calculation_context.segment_severity(first_outdated_segment_index)
       end
 
       def first_outdated_segment_index
@@ -36,17 +44,15 @@ module Polariscope
         segments_delta.find(&:positive?) || 0
       end
 
-      def segments_delta
-        current_version.segments.grep(Integer).zip(latest_version.segments.grep(Integer))
-                       .map { |current, latest| current && latest ? latest - current : 0 }
+      def major_version_outdated?
+        segments_delta.first.positive?
       end
 
-      def major_version_penalty
-        major_outdated? ? 1 : 0
-      end
-
-      def major_outdated?
-        latest_version.segments[0] > current_version.segments[0]
+      def segments_delta
+        @segments_delta ||=
+          version_segments(latest_version)
+          .zip(version_segments(current_version))
+          .map { |latest, current| latest && current ? latest - current : 0 }
       end
 
       def latest_version
@@ -57,11 +63,9 @@ module Polariscope
         @new_versions ||= all_versions.select { |version| version > current_version }
       end
 
-      private
-
-      attr_reader :all_versions
-      attr_reader :current_version
-      attr_reader :severities
+      def version_segments(version)
+        version.segments.grep(Integer)
+      end
     end
   end
 end

data/lib/polariscope/scanner/gem_versions.rb

@@ -1,30 +1,43 @@
 # frozen_string_literal: true
 
+require_relative 'ruby_versions'
+
 require 'set'
 
 module Polariscope
   module Scanner
     class GemVersions
+      RUBY_NAME = 'ruby'
+
       def initialize(dependency_names, spec_type:)
         @dependency_names = dependency_names.to_set
         @spec_type = spec_type
-        @gem_versions = Hash.new { |h, k| h[k] = [] }
+        @gem_versions = Hash.new { |h, k| h[k] = Set.new }
 
         fetch_gems
+        fetch_ruby_versions if dependency_names.include?(RUBY_NAME)
       end
 
       def versions_for(gem_name)
-        @gem_versions[gem_name]
+        gem_versions[gem_name]
       end
 
       private
 
+      attr_reader :dependency_names
+      attr_reader :spec_type
+      attr_reader :gem_versions
+
+      def fetch_ruby_versions
+        gem_versions[RUBY_NAME] = RubyVersions.available_versions
+      end
+
       def fetch_gems
-        gem_tuples = Gem::SpecFetcher.fetcher.detect(@spec_type) do |name_tuple|
-          @dependency_names.include?(name_tuple.name)
-        end
+        gem_tuples.each { |(name_tuple, _)| gem_versions[name_tuple.name] << name_tuple.version }
+      end
 
-        gem_tuples.each { |gem_tuple| @gem_versions[gem_tuple.first.name] << gem_tuple.first.version }
+      def gem_tuples
+        Gem::SpecFetcher.fetcher.detect(spec_type) { |name_tuple| dependency_names.include?(name_tuple.name) }
       end
     end
   end

data/lib/polariscope/scanner/gemfile_health_score.rb

@@ -1,147 +1,68 @@
 # frozen_string_literal: true
 
-require 'bundler'
-require 'bundler/audit/configuration'
-require 'bundler/audit/database'
-require 'set'
-require_relative 'gem_versions'
+require_relative 'advisories_health_score'
+require_relative 'audit_database'
+require_relative 'calculation_context'
+require_relative 'dependency_context'
 require_relative 'gem_health_score'
-require_relative 'ruby_scanner'
 
 module Polariscope
   module Scanner
-    class GemfileHealthScore # rubocop:disable Metrics/ClassLength
-      GEM_PRIORITIES = { rails: 10.0 }.freeze
-      DEFAULT_PRIORITY = 1.0
-      GROUP_PRIORITIES = { default: 2.0, production: 2.0 }.freeze
-      SEVERITIES = [1.7, 1.15, 1.01, 1.005].freeze
-      FALLBACK_ADVISORY_PENALTY = 0.5
-      ADVISORY_PENALTY_MAP = {
-        none: 0.0,
-        low: 0.5,
-        medium: 1.0,
-        high: 3.0,
-        critical: 5.0
-      }.freeze
-
-      def initialize( # rubocop:disable Metrics/ParameterLists, Metrics/MethodLength
-        gemfile_path:, gemfile_lock_content:, gem_priorities: GEM_PRIORITIES, default_priority: DEFAULT_PRIORITY,
-        group_priorities: GROUP_PRIORITIES, severities: SEVERITIES, spec_type: :released,
-        advisory_penalty_map: ADVISORY_PENALTY_MAP, fallback_advisory_penalty: FALLBACK_ADVISORY_PENALTY,
-        update_audit_database: false, bundler_audit_config_path: ''
-      )
-        @lockfile_parser = Bundler::LockfileParser.new(gemfile_lock_content)
-        @ruby_scanner = RubyScanner.new(@lockfile_parser)
-        @gemfile_path = gemfile_path
-        @dependencies = installed_dependencies
-        @gem_priorities = gem_priorities
-        @default_priority = default_priority
-        @group_priorities = group_priorities
-        @severities = severities
-        @spec_type = spec_type
-        @advisory_penalty_map = advisory_penalty_map
-        @fallback_advisory_penalty = fallback_advisory_penalty
-        @bundler_audit_config_path = bundler_audit_config_path
-
-        update_audit_database! if update_audit_database
+    class GemfileHealthScore
+      def initialize(**opts)
+        @dependency_context = DependencyContext.new(**opts)
+        @calculation_context = CalculationContext.new(**opts)
+
+        AuditDatabase.update_if_necessary
       end
 
       def health_score
-        return nil if dependencies.empty?
+        return nil if dependency_context.no_dependencies?
 
-        ((1.0 - major_version_penalty_score) * weighted_gem_health_score * advisories_score).round(2)
+        (100.0 * weighted_major_version_score * weighted_dependency_health_score * advisories_score).round(2)
       end
 
       private
 
-      attr_reader :dependencies
-      attr_reader :lockfile_parser
-      attr_reader :ruby_scanner
-      attr_reader :advisory_penalty_map
-      attr_reader :fallback_advisory_penalty
-      attr_reader :bundler_audit_config_path
-
-      def major_version_penalties
-        dependencies.map do |dependency|
-          current_version, all_versions = dependency_versions(dependency)
+      attr_reader :dependency_context
+      attr_reader :calculation_context
 
-          GemHealthScore.new(all_versions: all_versions, current_version: current_version).major_version_penalty
-        end
+      def weighted_major_version_score
+        1.0 - weighted_major_version_penalty
       end
 
-      def major_version_penalty_score
-        dependency_priorities.zip(major_version_penalties).sum { |a| a.inject(:*) } / dependency_priorities.sum
-      end
-
-      def weighted_gem_health_score
-        dependency_priorities.zip(dependency_health_scores).sum { |a| a.inject(:*) } / dependency_priorities.sum
-      end
-
-      def dependency_health_scores
-        dependencies.map do |dependency|
-          current_version, all_versions = dependency_versions(dependency)
-
-          GemHealthScore.new(
-            all_versions: all_versions,
-            current_version: current_version,
-            severities: @severities
-          ).health_score
-        end
-      end
-
-      def dependency_priorities
-        @dependency_priorities ||= dependencies.map { |dependency| dependency_priority(dependency) }
+      def weighted_major_version_penalty
+        dependency_priorities.zip(major_version_penalties).sum { |a, b| a * b } / dependency_priorities.sum
       end
 
-      def dependency_priority(dependency)
-        @gem_priorities[dependency.name.to_sym] || @group_priorities[dependency.groups.first] || @default_priority
+      def weighted_dependency_health_score
+        dependency_priorities.zip(dependency_health_scores).sum { |a, b| a * b } / dependency_priorities.sum
       end
 
-      def dependency_versions(dependency)
-        [current_dependency_version(dependency), gem_versions.versions_for(dependency.name)]
+      def major_version_penalties
+        gem_health_scores.map(&:major_version_penalty)
       end
 
-      def current_dependency_version(dependency)
-        lockfile_parser.specs.find { |spec| dependency.name == spec.name }.version
+      def dependency_health_scores
+        gem_health_scores.map(&:health_score)
       end
 
-      def installed_dependencies
-        spec_names = @lockfile_parser.specs.to_set(&:name)
-        dependencies = Bundler::Definition.build(@gemfile_path, nil, nil).dependencies
-
-        dependencies.select { |dependency| spec_names.include?(dependency.name) }
+      def gem_health_scores
+        @gem_health_scores ||= dependencies.map do |dependency|
+          GemHealthScore.new(dependency_context, calculation_context, dependency)
+        end
       end
 
-      def gem_versions
-        @gem_versions ||= GemVersions.new(dependencies.map(&:name), spec_type: @spec_type)
+      def dependency_priorities
+        @dependency_priorities ||= dependencies.map { |dependency| calculation_context.priority_for(dependency) }
       end
 
       def advisories_score
-        (1 + advisories_penalty)**-Math.log(1.09)
-      end
-
-      def advisories_penalty
-        advisories.map(&:criticality)
-                  .sum { |criticality| advisory_penalty_map.fetch(criticality, fallback_advisory_penalty) }
-      end
-
-      def advisories
-        database = Bundler::Audit::Database.new
-
-        lockfile_parser.specs
-                       .flat_map { |gem| database.check_gem(gem).to_a }
-                       .concat(ruby_scanner.vulnerable_advisories)
-                       .reject { |advisory| ignored_advisories.intersect?(advisory.identifiers.to_set) }
-      end
-
-      def ignored_advisories
-        @ignored_advisories ||= Bundler::Audit::Configuration.load(bundler_audit_config_path).ignore.to_set
-      rescue Bundler::Audit::Configuration::FileNotFound, Bundler::Audit::Configuration::InvalidConfigurationError
-        @ignored_advisories = Set.new
+        AdvisoriesHealthScore.new(dependency_context, calculation_context).health_score
       end
 
-      def update_audit_database!
-        Bundler::Audit::Database.update!(quiet: true)
+      def dependencies
+        dependency_context.dependencies
       end
     end
   end

data/lib/polariscope/scanner/ruby_scanner.rb

@@ -1,17 +1,16 @@
 # frozen_string_literal: true
 
-require 'bundler'
 require 'bundler/audit/database'
 
 module Polariscope
   module Scanner
     class RubyScanner
-      def initialize(lockfile_parser)
-        @lockfile_parser = lockfile_parser
+      def initialize(bundler_ruby_version)
+        @bundler_ruby_version = bundler_ruby_version
       end
 
       def version
-        lockfile_ruby_version&.gem_version
+        bundler_ruby_version&.gem_version
       end
 
       def vulnerable_advisories
@@ -20,8 +19,7 @@ module Polariscope
 
       private
 
-      attr_reader :lockfile_parser
-      attr_reader :bundler_audit_database
+      attr_reader :bundler_ruby_version
 
       def advisories
         cve_paths.map { |path| Bundler::Audit::Advisory.load(path) }
@@ -34,11 +32,7 @@ module Polariscope
       end
 
       def engine
-        lockfile_ruby_version.engine
-      end
-
-      def lockfile_ruby_version
-        @lockfile_ruby_version ||= Bundler::RubyVersion.from_string(@lockfile_parser.ruby_version)
+        bundler_ruby_version.engine
       end
     end
   end

data/lib/polariscope/scanner/ruby_versions.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require 'open-uri'
+
+module Polariscope
+  module Scanner
+    module RubyVersions
+      VERSIONS_INDEX_FILE_URL = 'https://cache.ruby-lang.org/pub/ruby/index.txt'
+      MINIMUM_RUBY_VERSION = Gem::Version.new('1.0.0')
+      OPEN_TIMEOUT = 5
+      READ_TIMEOUT = 5
+
+      module_function
+
+      def available_versions # rubocop:disable Metrics/AbcSize
+        URI
+          .parse(VERSIONS_INDEX_FILE_URL)
+          .open(open_timeout: OPEN_TIMEOUT, read_timeout: READ_TIMEOUT, &:readlines)
+          .drop(1) # header row
+          .map { |line| line.split("\t").first.sub('ruby-', 'ruby ') } # ruby-2.3.4 -> ruby 2.3.4
+          .filter_map { |ruby_version| Bundler::RubyVersion.from_string(ruby_version)&.gem_version }
+          .select { |gem_version| gem_version >= MINIMUM_RUBY_VERSION && gem_version.segments.size == 3 }
+          .to_set
+      rescue Timeout::Error
+        Set.new
+      end
+    end
+  end
+end

data/lib/polariscope/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Polariscope
-  VERSION = '0.3.0'
+  VERSION = '0.5.0'
 end

data/lib/polariscope.rb

@@ -1,7 +1,9 @@
 # frozen_string_literal: true
 
+require 'bundler'
+
 require_relative 'polariscope/version'
-require_relative 'polariscope/scanner/codebase_health_score'
+require_relative 'polariscope/scanner/gemfile_health_score'
 require_relative 'polariscope/scanner/gem_versions'
 require_relative 'polariscope/file_content'
 
@@ -9,15 +11,15 @@ module Polariscope
   Error = Class.new(StandardError)
 
   class << self
-    def scan(gemfile_content: nil, gemfile_lock_content: nil, bundler_audit_config_content: nil)
-      Scanner::CodebaseHealthScore.new(
-        gemfile_content: gemfile_content || FileContent.for('Gemfile'),
-        gemfile_lock_content: gemfile_lock_content || FileContent.for('Gemfile.lock'),
-        bundler_audit_config_content: bundler_audit_config_content || FileContent.for('.bundler-audit.yml')
-      ).health_score
+    def scan(**opts)
+      Scanner::GemfileHealthScore.new(**opts.merge(
+        gemfile_content: opts.fetch(:gemfile_content, FileContent.for('Gemfile')),
+        gemfile_lock_content: opts.fetch(:gemfile_lock_content, FileContent.for('Gemfile.lock')),
+        bundler_audit_config_content: opts.fetch(:bundler_audit_config_content, FileContent.for('.bundler-audit.yml'))
+      )).health_score
     end
 
-    def gem_versions(dependency_names, spec_type: :released)
+    def gem_versions(dependency_names, spec_type: Scanner::DependencyContext::DEFAULT_SPEC_TYPE)
       Scanner::GemVersions.new(dependency_names, spec_type: spec_type)
     end
   end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: polariscope
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Rails team
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-10-17 00:00:00.000000000 Z
+date: 2024-10-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -56,11 +56,15 @@ files:
 - exe/polariscope
 - lib/polariscope.rb
 - lib/polariscope/file_content.rb
-- lib/polariscope/scanner/codebase_health_score.rb
+- lib/polariscope/scanner/advisories_health_score.rb
+- lib/polariscope/scanner/audit_database.rb
+- lib/polariscope/scanner/calculation_context.rb
+- lib/polariscope/scanner/dependency_context.rb
 - lib/polariscope/scanner/gem_health_score.rb
 - lib/polariscope/scanner/gem_versions.rb
 - lib/polariscope/scanner/gemfile_health_score.rb
 - lib/polariscope/scanner/ruby_scanner.rb
+- lib/polariscope/scanner/ruby_versions.rb
 - lib/polariscope/version.rb
 - polariscope.gemspec
 homepage: https://github.com/infinum/polariscope

data/lib/polariscope/scanner/codebase_health_score.rb

@@ -1,69 +0,0 @@
-# frozen_string_literal: true
-
-require 'tempfile'
-require_relative 'gemfile_health_score'
-
-module Polariscope
-  module Scanner
-    class CodebaseHealthScore
-      def initialize(gemfile_content:, gemfile_lock_content:, bundler_audit_config_content:)
-        @gemfile_content = gemfile_content
-        @gemfile_lock_content = gemfile_lock_content
-        @bundler_audit_config_content = bundler_audit_config_content
-      end
-
-      def health_score
-        return nil if blank?(gemfile_content) || blank?(gemfile_lock_content)
-
-        begin
-          GemfileHealthScore.new(gemfile_path: gemfile_file.path, gemfile_lock_content: gemfile_lock_content,
-                                 bundler_audit_config_path: bundler_audit_config_file.path,
-                                 update_audit_database: update_audit_database?).health_score
-        ensure
-          gemfile_file.unlink
-          bundler_audit_config_file.unlink
-        end
-      end
-
-      private
-
-      attr_reader :gemfile_content
-      attr_reader :gemfile_lock_content
-      attr_reader :bundler_audit_config_content
-
-      def gemfile_file
-        @gemfile_file ||= begin
-          file = Tempfile.new('Gemfile')
-          file.write(gemfile_content.gsub("gemspec\n", '').gsub(/^ruby.*$\R/, ''))
-          file.close
-          file
-        end
-      end
-
-      def bundler_audit_config_file
-        @bundler_audit_config_file ||= begin
-          file = Tempfile.new('.bundler-audit.yml')
-          file.write(bundler_audit_config_content)
-          file.close
-          file
-        end
-      end
-
-      def blank?(value)
-        value.nil? || value == ''
-      end
-
-      def update_audit_database?
-        audit_db_missing? || audit_db_stale?
-      end
-
-      def audit_db_missing?
-        !Bundler::Audit::Database.exists?
-      end
-
-      def audit_db_stale?
-        ((Time.now - Bundler::Audit::Database.new.last_updated_at) / 86_400) > 7
-      end
-    end
-  end
-end