quiet_quality 1.0.2 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 637f00e52eae2e4b0cee2cf1e4c76b17595e7ac4a59aa2568ae0eee17b4a7d4c
-  data.tar.gz: a45040a9379e05a86e87d01f274ea044084c0af13e65c6d00b7c664dde33afc6
+  metadata.gz: b6aea488d2026da63fdf9483d1df9bd4e2363270d7b441cbca384cd803cab803
+  data.tar.gz: 0536d6eb0b8cdd1c4678f49058be4d37017b7ff6156d363afa71df8a979d30aa
 SHA512:
-  metadata.gz: f0666d43b98ea76f55b8dab0d3d38cc786f8c9a750b14dee1eff2c4a13ee7da94f94a83757fe643efa1d448197583864c02c34c0e49b7adda5d790d51eaad0ef
-  data.tar.gz: 3cd316700e1abda994248dbd5959d242ccec0551d2f516212671fee07df1cfa5d36a9b53137ea299cce03b6bbbab9e328ba38132be6148d8626a7e4b1d71e346
+  metadata.gz: 766f24f8211b83610c05e57b0f81d77bbf2d4bf8c206cc5e9af1d4e302adc9fee6425c506b344850a1421b7a30f18b6dfa6a23132aaa64dc3e6fbeb5e59c4c0b
+  data.tar.gz: 7b72dcf22a6696b2ff88a5efb08fb0338d2d4f0b43f506f147a2d5cb0ed7186328157ff4b8ded7198fff3785f6636b32d8b1ecd1102cd462b341f28c57dfd429

data/.github/workflows/linters.yml

@@ -29,3 +29,6 @@ jobs:
 
       - name: Run rubocop (complexity checks)
         run: bundle exec rubocop --parallel
+
+      - name: Run markdownlint
+        run: bundle exec mdl .

data/.mdl_rules.rb

@@ -0,0 +1,2 @@
+all
+rule "MD013", ignore_code_blocks: true

data/.mdlrc

@@ -0,0 +1,2 @@
+style File.expand_path("../.mdl_rules.rb", __FILE__)
+git_recurse true

data/README.md

@@ -1,34 +1,172 @@
 # QuietQuality
 
-Work in Progress
+There are a lot of different tools that you need to run as you work - possibly
+before you commit, or before you make a pull request, or after you make changes
+to a class.. style checkers, tests, complexity metrics, static analyzers, etc.
+QuietQuality can make that simpler and faster!
 
-But essentially, QuietQuality is intended for two purposes:
+Or you may have a huge existing project, that's not _fully_ in compliance with
+your style guides, but you want to avoid introducing _new_ issues, without
+having to first resolve all of the existing ones. QuietQuality can help with
+that too.
 
-1. Let you conveniently run tools like rubocop, rspec, and standard against the _relevant_
-   files locally (the files that have changed locally relative to the default branch)
-2. Let you run those tools in CI (probably github actions) and annotate any issues found
-   with _new or modified_ code, without bothering you about existing issues that you didn't
-   touch.
+## Tool Support
 
+So far, we have support for the following tools:
 
-Basic usage examples:
+* rubocop
+* standardrb
+* rspec
+* haml-lint
+* brakeman (though there's no way to run this against only changed files)
 
+Supporting more tools is relatively straightforward - they're implemented by
+wrapping cli invocations and parsing output files (which overall seem to be much
+more stable interfaces than the code interfaces to the various tools), and each
+tool's support is built orthogonally to the others, in a
+`QuietQuality::Tools::[Something]` namespace, with a `Runner` and a `Parser`.
+
+## Local Usage Examples
+
+Working locally, you'll generally want to commit a `.quiet_quality.yml`
+configuration file into the root of your repository - it'll specify which tools
+to run by default, and how to run them (whether you want to only run each tool
+against the _changed files_, whether to _filter_ the resulting _messages_ down
+to only those targeting lines that have been changed), and allows you to specify
+the _comparison branch_, so you don't have to make a request to your origin
+server every time you run the tool to see whether you're comparing against
+`master` or `main` in this project.
+
+If you have a configuration set up like that, you might have details specified
+for `rubocop`, `rspec`, `standardrb`, and `brakeman`, but have only `rubocop`,
+`standardrb`, and `rspec` set to run by default. That configuration file would
+look like this (you can copy it from [here](docs/example-config.yml)):
+
+```yaml
+---
+default_tools: ["standardrb", "rubocop", "rspec"]
+executor: concurrent
+comparison_branch: main
+changed_files: true
+filter_messages: true
+brakeman:
+  changed_files: false
+  filter_messages: true
+```
+
+Then if you invoke `qq`, you'll see output like this:
+
+```bash
+❯ qq
+--- Passed: standardrb
+--- Passed: rubocop
+--- Passed: rspec
+```
+
+But if you want to run brakeman, you could call `qq brakeman`:
+
+```bash
+❯ qq brakeman
+--- Failed: brakeman
+
+
+2 messages:
+  app/controllers/articles_controller.rb:3  [SQL Injection]  Possible SQL injection
+  app/controllers/articles_controller.rb:11  [Remote Code Execution]  `YAML.load` called with parameter value
+
+```
+
+## CI Usage Examples
+
+Currently, QuietQuality is most useful from GitHub Actions - in that context, it's
+possible to generate nice annotations for the analyzed commit (using Workflow
+Actions). But it can be used from other CI systems as well, you just won't get
+nice annotations out of it (yet).
+
+For CI systems, you can either configure your execution entirely through
+command-line arguments, or you can create additional configuration files and
+specify them on the command-line.
+
+Here is an invocation that executes rubocop and standardrb, expecting the full
+repository to pass the latter, but not the former:
+
+```bash
+qq rubocop standardrb \
+  --all-files --changed-files rubocop \
+  --unfiltered --filter-messages rubocop \
+  --comparison-branch main \
+  --no-config \
+  --executor serial \
+  --annotate-github-stdout
 ```
-# you have five commits in your feature branch and 3 more files changes but not committed.
-# this will run rubocop against all of those files.
-qq rubocop
-
-# run rspec against the changed specs, and annotate any failing specs (well, the first 10
-# of them) against the commit using github's inline output-based annotation approach. Which
-# will of course only produce actual annotations if this happens to have been run in a
-# github action.
-qq rspec --annotate=github_stdout
-
-# run standardrb against all of the files (not just the changed ones). Still only print out
-# problems to lines that have changed, so not particularly useful :-)
-qq standard --all --incremental
-
-# run all of the tools against the entire repository, and print the first three messages
-# out for each tool.
-qq all --all --full --limit-per-tool=3
+
+Note the use of `--no-config`, to cause it to _not_ automatically load the
+`.quiet_quality.yml` config included in the repository.
+
+Alternatively, we could have put all of that configuration into a config file
+like this:
+
+```yaml
+# config/quiet_quality/linters_workflow.yml
+---
+default_tools: ["standardrb", "rubocop"]
+executor: serial
+comparison_branch: main
+changed_files: false
+filter_messages: false
+
+rubocop:
+  changed_files: true
+  filter_messages: true
 ```
+
+And then run `qq -C config/quiet_quality/linters_workflow.yml`
+
+## Available Options
+
+The configuration file supports the following _global_ options (top-level keys):
+
+* `executor`: 'serial' or 'concurrent' (the latter is the default)
+* `annotator`: none set by default, and `github_stdout` is the only supported
+  value so far.
+* `comparison_branch`: by default, this will be _fetched_ from git, but that
+  does require a remote request. You should set this, it saves about half a
+  second. This is normally 'main' or 'master', but it could be 'trunk', or
+  'develop' - it is the branch that PR diffs are _against_.
+* `changed_files`: defaults to false - should tools be run against only the
+  files that have changed, or against the entire repository? This is the global
+  setting, but it is also settable per tool.
+* `filter_messages`: defaults to false - should the resulting messages that do
+  not refer to lines that were changed or added relative to the comparison
+  branch be skipped? Also possible to set for each tool.
+
+And then each tool can have an entry, within which `changed_files` and
+`filter_messages` can be specified - the tool-specific settings override the
+global ones.
+
+The tools have one additional setting that is not available at a global level:
+`file_filter`. This is a string that will be turned into a _ruby regex_, and
+used to limit what file paths are passed to the tool. For example, if you are
+working in a rails engine `engines/foo/`, and you touch one of the rspec tests
+there, you would not want `qq` in the root of the repository to run
+`rspec engines/foo/spec/foo/thing_spec.rb` - that probably won't work, as your
+engine will have its own test setup code and Gemfile. This setting is mostly
+intended to be used like this:
+
+```yaml
+rspec:
+  changed_files: true
+  filter_messages: false
+  file_filter: "^spec/"
+```
+
+### CLI Options
+
+The same options are all available on the CLI, plus some additional ones - run
+`qq --help` for a detailed list of the options, but the notable additions are:
+
+* `--help/-H`: See a list of the options
+* `--no-config/-N`: Do _not_ load a config file, even if present.
+* `--config/-C`: load the supplied config file (instead of the detected one, if
+  found)
+* `--version/-V`: what version of the gem are you using?

data/docs/example-config.yml

@@ -0,0 +1,9 @@
+---
+default_tools: ["standardrb", "rubocop", "rspec"]
+executor: concurrent
+comparison_branch: main
+changed_files: true
+filter_messages: true
+brakeman:
+  changed_files: false
+  filter_messages: true

data/lib/quiet_quality/cli/arg_parser.rb

@@ -76,6 +76,10 @@ module QuietQuality
         parser.on("-h", "--help", "Prints this help") do
           @parsed_options.helping = true
         end
+
+        parser.on("-V", "--version", "Print the current version of the gem") do
+          @parsed_options.printing_version = true
+        end
       end
 
       def setup_config_options(parser)

data/lib/quiet_quality/cli/entrypoint.rb

@@ -10,6 +10,10 @@ module QuietQuality
       def execute
         if helping?
           log_help_text
+        elsif printing_version?
+          log_version_text
+        elsif no_tools?
+          log_no_tools_text
         else
           executed
           log_outcomes
@@ -21,7 +25,9 @@ module QuietQuality
       end
 
       def successful?
-        helping? || !executed.any_failure?
+        return true if helping? || printing_version?
+        return false if no_tools?
+        !executed.any_failure?
       end
 
       private
@@ -40,10 +46,29 @@ module QuietQuality
         parsed_options.helping?
       end
 
+      def printing_version?
+        parsed_options.printing_version?
+      end
+
+      def no_tools?
+        options.tools.empty?
+      end
+
       def log_help_text
         error_stream.puts(arg_parser.help_text)
       end
 
+      def log_version_text
+        error_stream.puts(QuietQuality::VERSION)
+      end
+
+      def log_no_tools_text
+        error_stream.puts(<<~TEXT)
+          You must specify one or more tools to run, either on the command-line or in the
+          default_tools key in a configuration file.
+        TEXT
+      end
+
       def options
         return @_options if defined?(@_options)
         builder = Config::Builder.new(parsed_cli_options: parsed_options)

data/lib/quiet_quality/config/builder.rb

@@ -28,7 +28,7 @@ module QuietQuality
         elsif config_file&.tools&.any?
           config_file.tools
         else
-          Tools::AVAILABLE.keys
+          []
         end
       end
 
@@ -109,6 +109,7 @@ module QuietQuality
           options.tools.each do |tool_options|
             update_tool_option(tool_options, :limit_targets)
             update_tool_option(tool_options, :filter_messages)
+            update_tool_option(tool_options, :file_filter)
           end
         end
 

data/lib/quiet_quality/config/parsed_options.rb

@@ -5,16 +5,20 @@ module QuietQuality
         @tools = []
         @tool_options = {}
         @global_options = {}
-        @helping = false
+        @helping = @printing_version = false
       end
 
       attr_accessor :tools
-      attr_writer :helping
+      attr_writer :helping, :printing_version
 
       def helping?
         @helping
       end
 
+      def printing_version?
+        @printing_version
+      end
+
       def set_global_option(name, value)
         @global_options[name.to_sym] = value
       end

data/lib/quiet_quality/config/parser.rb

@@ -38,11 +38,14 @@ module QuietQuality
       end
 
       def store_global_options(opts)
-        read_global_option(opts, :executor, as: :symbol, validate_from: Executors::AVAILABLE)
-        read_global_option(opts, :annotator, as: :symbol, validate_from: Annotators::ANNOTATOR_TYPES)
-        read_global_option(opts, :comparison_branch, as: :string)
-        read_global_option(opts, :changed_files, as: :boolean)
-        read_global_option(opts, :filter_messages, as: :boolean)
+        read_global_option(opts, :executor, :executor, as: :symbol, validate_from: Executors::AVAILABLE)
+        read_global_option(opts, :annotator, :annotator, as: :symbol, validate_from: Annotators::ANNOTATOR_TYPES)
+        read_global_option(opts, :annotate, :annotator, as: :symbol, validate_from: Annotators::ANNOTATOR_TYPES)
+        read_global_option(opts, :comparison_branch, :comparison_branch, as: :string)
+        read_global_option(opts, :changed_files, :changed_files, as: :boolean)
+        read_global_option(opts, :all_files, :changed_files, as: :reversed_boolean)
+        read_global_option(opts, :filter_messages, :filter_messages, as: :boolean)
+        read_global_option(opts, :unfiltered, :filter_messages, as: :reversed_boolean)
       end
 
       def store_tool_options(opts)
@@ -54,8 +57,12 @@ module QuietQuality
       def store_tool_options_for(opts, tool_name)
         entries = data.fetch(tool_name, nil)
         return if entries.nil?
-        read_tool_option(opts, tool_name, :filter_messages, as: :boolean)
-        read_tool_option(opts, tool_name, :changed_files, as: :boolean)
+
+        read_tool_option(opts, tool_name, :filter_messages, :filter_messages, as: :boolean)
+        read_tool_option(opts, tool_name, :unfiltered, :filter_messages, as: :reversed_boolean)
+        read_tool_option(opts, tool_name, :changed_files, :changed_files, as: :boolean)
+        read_tool_option(opts, tool_name, :all_files, :changed_files, as: :reversed_boolean)
+        read_tool_option(opts, tool_name, :file_filter, :file_filter, as: :string)
       end
 
       def invalid!(message)
@@ -70,27 +77,28 @@ module QuietQuality
         [true, false].include?(value)
       end
 
-      def read_global_option(opts, name, as:, validate_from: nil)
+      def read_global_option(opts, name, into, as:, validate_from: nil)
         parsed_value = data.fetch(name.to_sym, nil)
         return if parsed_value.nil?
 
         validate_value(name, parsed_value, as: as, from: validate_from)
         coerced_value = coerce_value(parsed_value, as: as)
-        opts.set_global_option(name, coerced_value)
+        opts.set_global_option(into, coerced_value)
       end
 
-      def read_tool_option(opts, tool, name, as:)
+      def read_tool_option(opts, tool, name, into, as:)
         parsed_value = data.dig(tool.to_sym, name.to_sym)
         return if parsed_value.nil?
 
         validate_value("#{tool}.#{name}", parsed_value, as: as)
         coerced_value = coerce_value(parsed_value, as: as)
-        opts.set_tool_option(tool, name, coerced_value)
+        opts.set_tool_option(tool, into, coerced_value)
       end
 
       def validate_value(name, value, as:, from: nil)
         case as
         when :boolean then validate_boolean(name, value)
+        when :reversed_boolean then validate_boolean(name, value)
         when :symbol then validate_symbol(name, value, from: from)
         when :string then validate_string(name, value)
         else
@@ -123,6 +131,7 @@ module QuietQuality
       def coerce_value(value, as:)
         case as
         when :boolean then !!value
+        when :reversed_boolean then !value
         when :string then value.to_s
         when :symbol then value.to_sym
         else

data/lib/quiet_quality/config/tool_options.rb

@@ -1,14 +1,15 @@
 module QuietQuality
   module Config
     class ToolOptions
-      def initialize(tool, limit_targets: true, filter_messages: true)
+      def initialize(tool, limit_targets: true, filter_messages: true, file_filter: nil)
         @tool_name = tool.to_sym
         @limit_targets = limit_targets
         @filter_messages = filter_messages
+        @file_filter = file_filter
       end
 
       attr_reader :tool_name
-      attr_writer :limit_targets, :filter_messages
+      attr_writer :limit_targets, :filter_messages, :file_filter
 
       def limit_targets?
         @limit_targets
@@ -29,6 +30,11 @@ module QuietQuality
       def parser_class
         tool_namespace::Parser
       end
+
+      def file_filter
+        return nil if @file_filter.nil?
+        Regexp.new(@file_filter)
+      end
     end
   end
 end

data/lib/quiet_quality/executors/pipeline.rb

@@ -11,11 +11,16 @@ module QuietQuality
       end
 
       def outcome
-        @_outcome ||= runner.invoke!
+        @_outcome ||= Tools::Outcome.new(
+          tool: runner_outcome.tool,
+          output: runner_outcome.output,
+          logging: runner_outcome.logging,
+          failure: messages.any?
+        )
       end
 
       def failure?
-        messages.any?
+        outcome.failure?
       end
 
       def messages
@@ -30,6 +35,10 @@ module QuietQuality
 
       attr_reader :changed_files, :tool_options
 
+      def runner_outcome
+        @_runner_outcome ||= runner.invoke!
+      end
+
       def limit_targets?
         tool_options.limit_targets?
       end
@@ -39,12 +48,14 @@ module QuietQuality
       end
 
       def runner
-        @_runner ||= tool_options.runner_class
-          .new(changed_files: limit_targets? ? changed_files : nil)
+        @_runner ||= tool_options.runner_class.new(
+          changed_files: limit_targets? ? changed_files : nil,
+          file_filter: tool_options.file_filter
+        )
       end
 
       def parser
-        @_parser ||= tool_options.parser_class.new(outcome.output)
+        @_parser ||= tool_options.parser_class.new(runner_outcome.output)
       end
 
       def relevance_filter

data/lib/quiet_quality/tools/brakeman/runner.rb

@@ -6,8 +6,12 @@ module QuietQuality
         #   https://github.com/presidentbeef/brakeman/blob/main/lib/brakeman.rb#L6-L25
         KNOWN_EXIT_STATUSES = [3, 4, 5, 6, 7, 8].to_set
 
-        def initialize(changed_files: nil)
+        # brakeman does not support being run against a portion of the project, so neither
+        # changed_files nor file_filter is actually used. But they are accepted here because
+        # that is what Runner initializers are required to accept.
+        def initialize(changed_files: nil, file_filter: nil)
           @changed_files = changed_files
+          @file_filter = file_filter
         end
 
         def invoke!

data/lib/quiet_quality/tools/haml_lint/runner.rb

@@ -11,8 +11,9 @@ module QuietQuality
         # encountered"
         FAILURE_STATUS = 65
 
-        def initialize(changed_files: nil)
+        def initialize(changed_files: nil, file_filter: nil)
           @changed_files = changed_files
+          @file_filter = file_filter
         end
 
         def invoke!
@@ -21,7 +22,7 @@ module QuietQuality
 
         private
 
-        attr_reader :changed_files
+        attr_reader :changed_files, :file_filter
 
         def skip_execution?
           changed_files && relevant_files.empty?
@@ -29,7 +30,9 @@ module QuietQuality
 
         def relevant_files
           return nil if changed_files.nil?
-          changed_files.paths.select { |path| path.end_with?(".haml") }
+          changed_files.paths
+            .select { |path| path.end_with?(".haml") }
+            .select { |path| file_filter.nil? || file_filter.match?(path) }
         end
 
         def target_files

data/lib/quiet_quality/tools/rspec/runner.rb

@@ -5,8 +5,9 @@ module QuietQuality
         MAX_FILES = 100
         NO_FILES_OUTPUT = '{"examples": [], "summary": {"failure_count": 0}}'
 
-        def initialize(changed_files: nil)
+        def initialize(changed_files: nil, file_filter: nil)
           @changed_files = changed_files
+          @file_filter = file_filter
         end
 
         def invoke!
@@ -15,7 +16,7 @@ module QuietQuality
 
         private
 
-        attr_reader :changed_files
+        attr_reader :changed_files, :file_filter
 
         def skip_execution?
           changed_files && relevant_files.empty?
@@ -23,7 +24,9 @@ module QuietQuality
 
         def relevant_files
           return nil if changed_files.nil?
-          changed_files.paths.select { |path| path.end_with?("_spec.rb") }
+          changed_files.paths
+            .select { |path| path.end_with?("_spec.rb") }
+            .select { |path| file_filter.nil? || file_filter.match?(path) }
         end
 
         def target_files

data/lib/quiet_quality/tools/rubocop/runner.rb

@@ -10,8 +10,9 @@ module QuietQuality
         end
 
         # Supplying changed_files: nil means "run against all files".
-        def initialize(changed_files: nil)
+        def initialize(changed_files: nil, file_filter: nil)
           @changed_files = changed_files
+          @file_filter = file_filter
         end
 
         def invoke!
@@ -20,7 +21,7 @@ module QuietQuality
 
         private
 
-        attr_reader :changed_files
+        attr_reader :changed_files, :file_filter
 
         # If we were told that _no files changed_ (which is distinct from not being told that
         # any files changed - a [] instead of a nil), then we shouldn't run rubocop at all.
@@ -38,7 +39,9 @@ module QuietQuality
 
         def relevant_files
           return nil if changed_files.nil?
-          changed_files.paths.select { |path| path.end_with?(".rb") }
+          changed_files.paths
+            .select { |path| path.end_with?(".rb") }
+            .select { |path| file_filter.nil? || file_filter.match?(path) }
         end
 
         def target_files

data/lib/quiet_quality/version.rb

@@ -1,3 +1,3 @@
 module QuietQuality
-  VERSION = "1.0.2"
+  VERSION = "1.1.0"
 end

data/quiet_quality.gemspec

@@ -41,4 +41,5 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency "standard", "~> 1.28"
   spec.add_development_dependency "rubocop", "~> 1.50"
   spec.add_development_dependency "debug"
+  spec.add_development_dependency "mdl", "~> 0.12"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: quiet_quality
 version: !ruby/object:Gem::Version
-  version: 1.0.2
+  version: 1.1.0
 platform: ruby
 authors:
 - Eric Mueller
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-05-24 00:00:00.000000000 Z
+date: 2023-05-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: git
@@ -136,6 +136,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: mdl
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.12'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.12'
 description: |
   Allow your CI to notice and/or annotate new quality issues, despite the presences of
   many pre-existing issues in your codebase.
@@ -150,6 +164,8 @@ files:
 - ".github/workflows/linters.yml"
 - ".github/workflows/rspec.yml"
 - ".gitignore"
+- ".mdl_rules.rb"
+- ".mdlrc"
 - ".quiet_quality.yml"
 - ".rspec"
 - ".rubocop.yml"
@@ -157,6 +173,7 @@ files:
 - LICENSE
 - README.md
 - bin/qq
+- docs/example-config.yml
 - lib/quiet_quality.rb
 - lib/quiet_quality/annotation_locator.rb
 - lib/quiet_quality/annotators.rb
@@ -224,7 +241,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.1.6
+rubygems_version: 3.3.7
 signing_key:
 specification_version: 4
 summary: A system for comparing quality tool outputs against the forward diffs