# Ruby Quality Report

## Installation

```sh
gem install quality_report
```

## Usage

Change to a project directory that contains `*.rb` files. Then:

```sh
ruby-quality-report
```

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 in the repo. 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)

Then, using git, it 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 create a lot of commits. But they also create a lot of bugs. Their 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

- [x] Colorize the output to separate high, medium, and low warning percentages.
- [x] Fix the numerical alignment.
- [ ] --add-column option.
- [ ] --skip option.
- [ ] Add a progress bar.
- [ ] Speed up the scan.
- [ ] Refactor from script-style coding to a more standard Ruby project.
- [ ] Make the filters configurable.
- [ ] Add a `--csv` option.


## Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/dogweather/ruby-quality-report.