quality_report 1.2.2 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a54ad55acc9cb09976954e805eb8c7136d5f81e76ca0d23b732739b629b43b77
-  data.tar.gz: 4ba83e201032c764ef7077187d267f9fba8f29c682e4087b893eb0ab92ecfae6
+  metadata.gz: f18d81f9fa7d9dca4e114657e18e06fed11bed99df6746c0438bf2bf9b625441
+  data.tar.gz: 19578513e16b8457a2e388e326834f31f1dd17876c822cf6f509349a2ae261e3
 SHA512:
-  metadata.gz: 295733e297b006cca1f68d5689f44422060f689aa44f10ecca0903fa4acca34fbd098df986edbceae908aa90b228e3e076eda2c5e324a8542015d2688e9118c4
-  data.tar.gz: acfe8e8f47c38ec7fe118a6ead137b11083ac7288b94882cf1b9980c1ae8b797ec4fc124dc470374591ba3871c471039fb9894481e2bfc4c91b34d5ff94cc160
+  metadata.gz: '03793a5b452e7f3ecc1b3c805eb273ff60f5619dceb902d0f19fc7c1272da7b60751ee737602671b364c00f2a2894568b8cf9c09b6e707feed5029b195c00952'
+  data.tar.gz: 0da7cd9be8337214421ee9ed709dc5a6119fdc48611c4648c70b211e8df0aee85b39c65d24c30dc77be690237f205c34c788176d22e49db38467368c6a9fe9f5

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

@@ -17,13 +17,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
 
@@ -52,13 +48,12 @@ def generate_table(combined_stats)
     table << [stats[:label], "#{stats[:percent]}%", stats[:part_count], stats[:whole_count]]
   end
 
-  table.render(:unicode)
+  table.render(:unicode, alignments: %i[left right right right])
 end
 
 def generate_data(combined_stats)
   combined_stats
     .sort_by { |s| s[:percent] }
-    .reverse
 end
 
 def should_skip?(stats)

data/lib/quality_report/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: quality_report
 version: !ruby/object:Gem::Version
-  version: 1.2.2
+  version: 1.3.0
 platform: ruby
 authors:
 - Robb Shecter
@@ -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: