quality_report 1.2.2 → 1.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a54ad55acc9cb09976954e805eb8c7136d5f81e76ca0d23b732739b629b43b77
-  data.tar.gz: 4ba83e201032c764ef7077187d267f9fba8f29c682e4087b893eb0ab92ecfae6
+  metadata.gz: c36b81a22b99492d9995e4446769315fe3a01df58e39ed71a3a1050bc05f1791
+  data.tar.gz: ebc3e1150b528d795fd72e926a462a93aca6311f4a232a3d94c04416bc0a7a7e
 SHA512:
-  metadata.gz: 295733e297b006cca1f68d5689f44422060f689aa44f10ecca0903fa4acca34fbd098df986edbceae908aa90b228e3e076eda2c5e324a8542015d2688e9118c4
-  data.tar.gz: acfe8e8f47c38ec7fe118a6ead137b11083ac7288b94882cf1b9980c1ae8b797ec4fc124dc470374591ba3871c471039fb9894481e2bfc4c91b34d5ff94cc160
+  metadata.gz: 1e9379b163149edcab1180868a320b7b5529f6c73b5a8c90cc2ffe3292fa818ccc1a48a1cfef9fb6a319fd9dbdf348fc9e6f66749d9b82e4886f2f4a42a50d4d
+  data.tar.gz: f9911d996413da6cf9264b34749e318d01a1c64e85925c76dae7da609966495341e7fc9d5956866b32c477cc7adbf9f0fbbe50bd0422773242b69e16a122003f

data/README.md

@@ -1,12 +1,82 @@
 # Ruby Quality Report
 
+## Installation
+
+```sh
+gem install quality-report
+```
+
 ## Usage
 
 ```sh
 ruby-quality-report
 ```
 
-This outputs a CSV report to stdout.
+After a bit of a wait, it outputs a report in table form:
+
+![Screenshot](screenshot-1@2x.webp)
+
+This is showing, for each author, the percentage of problematic lines of code. Lower is better.
+
+
+### For improved relevance, it has two filters.
+
+It excludes:
+
+- authors with fewer than 200 lines of code
+- authors with no commits in the previous 60 days
+
+
+### In Rails Projects
+
+This works great in Rails projects. It examines code recursively starting in the current directory. In my testing,
+I like the results best when run from `/app`. This is how I generated the report, above.
+
+
+## How it works
+
+It runs a subset of [Rubocop Metrics cops](https://docs.rubocop.org/rubocop/cops_metrics.html) on `*.rb` files that flag single lines or methods:
+
+- [ABC Size](https://docs.rubocop.org/rubocop/cops_metrics.html#metricsabcsize)
+- [Block Length](https://docs.rubocop.org/rubocop/cops_metrics.html#metricsblocklength)
+- [Block Nesting](https://docs.rubocop.org/rubocop/cops_metrics.html#metricsblocknesting)
+- [Cyclomatic Complexity](https://docs.rubocop.org/rubocop/cops_metrics.html#metricscyclomaticcomplexity)
+- [Method Length](https://docs.rubocop.org/rubocop/cops_metrics.html#metricsmethodlength)
+- [Perceived Complexity](https://docs.rubocop.org/rubocop/cops_metrics.html#metricsperceivedcomplexity)
+
+It then calculates the percentage of warnings per line written, per author. Each failing check is another warning.
+
+
+## Intent
+
+This is a team management tool to:
+
+- understand the quality of the code your team is producing
+- identify programmers who'd benefit from mentorship and education
+
+## Foundational Research
+
+Diving a little deeper, I've seen the phenomenon of micro-economies of bug-creation and bug-fixing develop within teams. Some developers appear to be extremely productive. They write a lot of code. But they also introduce a lot of bugs. The productivity is illusory.
+
+This code quality report doesn't track **bugs** per se. But it does report **quality and complexity**. Researchers have found a strong correlation between complexity and bug rate [1]. This link is reflected, _e.g.,_ in international safety standards that mandate low software complexity to reduce failures [2].
+
+Complex code introduces bugs in a second, more subtle way. This is because code complexity is the killer of understandability. Studies have found that developers devote 64% of their time to understanding code, while only 5% is spent on actually modifying it [3].
+
+1. De Silva, Dilshan, et al. The Relationship between Code Complexity and Software Quality: An Empirical Study. 2023, https://www.researchgate.net/publication/370761578_The_Relationship_between_Code_Complexity_and_Software_Quality_An_Empirical_Study.
+2.  See e.g., ISO 26262-1:2018(En), Road Vehicles — Functional Safety — Part 1: Vocabulary. https://www.iso.org/obp/ui/en/#iso:std:iso:26262:-1:ed-2:v1:en. Accessed 29 Sept. 2024.
+3.  Feitelson, Dror G. “From Code Complexity Metrics to Program Comprehension.” Communications of the ACM, vol. 66, no. 5, May 2023, pp. 52–61. DOI.org (Crossref), https://doi.org/10.1145/3546576.
+
+
+## Roadmap
+
+- [ ] Colorize the output to separate high, medium, and low warning percentages.
+- [ ] Fix the numerical alignment.
+- [ ] Add a `--csv` option.
+- [ ] Make the filters configurable.
+- [ ] Speed up the scan.
+- [ ] Add a progress bar.
+- [ ] Refactor from script-style coding to a more standard Ruby project.
+
 
 ## Contributing
 

data/exe/ruby-quality-report

@@ -2,6 +2,7 @@
 # frozen_string_literal: true
 
 require 'tty-table'
+require 'pastel'
 
 #
 # ruby-quality-report
@@ -10,6 +11,9 @@ require 'tty-table'
 # of lines of code written by each author that have been flagged as
 # having too high of a complexity.
 #
+#
+
+SIXTY_DAYS_IN_SECONDS = 60 * 24 * 60 * 60
 
 def create_combined_stats(part_stats, whole_stats)
   part_data  = make_data_set(part_stats)
@@ -17,13 +21,9 @@ def create_combined_stats(part_stats, whole_stats)
 
   whole_data.map do |label, whole_count|
     part_count = part_data[label] || 0
+    percent    = float_to_percent(part_count.to_f / whole_count)
 
-    {
-      label:,
-      part_count:,
-      whole_count:,
-      percent: float_to_percent(part_count.to_f / whole_count)
-    }
+    { label:, part_count:, whole_count:, percent: }
   end
 end
 
@@ -44,21 +44,47 @@ def generate_csv(combined_stats)
 end
 
 def generate_table(combined_stats)
-  table = TTY::Table.new(header: ['Author', 'Percent Flagged', 'Flagged Lines', 'All Lines'])
+  table      = TTY::Table.new(header: %W[Author Percent\nFlagged Flagged\nLines All\nLines])
+  table_data = generate_data(combined_stats).reject { should_skip?(_1) }
+
+  table_data.each do |stats|
+    table << [
+      { value: stats[:label],         alignment: :left },
+      { value: "#{stats[:percent]}%", alignment: :right },
+      { value: stats[:part_count],    alignment: :right },
+      { value: stats[:whole_count],   alignment: :right }
+    ]
+  end
 
-  generate_data(combined_stats).each do |stats|
-    next if should_skip?(stats)
+  render_table(table, table_data)
+end
 
-    table << [stats[:label], "#{stats[:percent]}%", stats[:part_count], stats[:whole_count]]
+def render_table(table, table_data)
+  pastel = Pastel.new
+
+  table.render(:unicode, alignment: :center, padding: [0, 1], multiline: true) do |renderer|
+    renderer.border.style = :dim
+    renderer.filter = lambda { |val, row_index, _col_index|
+      if row_index <= 0
+        # Header row
+        val
+      else
+        case table_data[row_index - 1][:percent]
+        when 0...40
+          val
+        when 40...50
+          pastel.bold.yellow(val)
+        else
+          pastel.bold.red(val)
+        end
+      end
+    }
   end
-
-  table.render(:unicode)
 end
 
 def generate_data(combined_stats)
   combined_stats
     .sort_by { |s| s[:percent] }
-    .reverse
 end
 
 def should_skip?(stats)
@@ -78,7 +104,7 @@ def no_commits_in_last_60_days?(stats)
 
   # Convert Unix timestamp to Time object
   last_commit_time = Time.at(last_commit.to_i)
-  sixty_days_ago   = Time.now - (60 * 24 * 60 * 60) # 60 days in seconds
+  sixty_days_ago   = Time.now - SIXTY_DAYS_IN_SECONDS
 
   last_commit_time < sixty_days_ago
 end

data/lib/quality_report/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module QualityReport
-  VERSION = '1.2.2'
+  VERSION = '1.4.0'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: quality_report
 version: !ruby/object:Gem::Version
-  version: 1.2.2
+  version: 1.4.0
 platform: ruby
 authors:
 - Robb Shecter
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-11-08 00:00:00.000000000 Z
+date: 2024-11-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rubocop
@@ -75,6 +75,7 @@ files:
 - exe/ruby-quality-report
 - lib/quality_report.rb
 - lib/quality_report/version.rb
+- screenshot-1@2x.webp
 - sig/quality_report.rbs
 homepage: https://github.com/dogweather/ruby-quality-report
 licenses: