quiet_quality 1.0.2 → 1.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 637f00e52eae2e4b0cee2cf1e4c76b17595e7ac4a59aa2568ae0eee17b4a7d4c
-  data.tar.gz: a45040a9379e05a86e87d01f274ea044084c0af13e65c6d00b7c664dde33afc6
+  metadata.gz: d7372d3c4b395adb2890c54270426bf92b9a2a9e2669ef27d5145eda776d1072
+  data.tar.gz: 5877277009b82e9685e62f8f8a1f17aec823faaad93c3c8e40dcb7f2640d0e7c
 SHA512:
-  metadata.gz: f0666d43b98ea76f55b8dab0d3d38cc786f8c9a750b14dee1eff2c4a13ee7da94f94a83757fe643efa1d448197583864c02c34c0e49b7adda5d790d51eaad0ef
-  data.tar.gz: 3cd316700e1abda994248dbd5959d242ccec0551d2f516212671fee07df1cfa5d36a9b53137ea299cce03b6bbbab9e328ba38132be6148d8626a7e4b1d71e346
+  metadata.gz: 4c860d24410fd6a03390e726fdc699113f3d0c21b722e12ccf564c666b5708690d8ed90a092448f3942496a47331e10b3d3bb7580ba2e0feeafbf74ea60bdb03
+  data.tar.gz: 67b89da10e8fc43370d586d9282776c2f1f23a0fa4fcfbea5bfd596ab6520cca7c9319731fd960c63dc04e36ab7021b83e27497d52f2e10b8cdd9ef8a39ad394

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,155 @@
 # 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
 ```
-# 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
+
+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
+```
+
+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.
+
+### 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)

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/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
@@ -44,7 +53,7 @@ module QuietQuality
       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/version.rb

@@ -1,3 +1,3 @@
 module QuietQuality
-  VERSION = "1.0.2"
+  VERSION = "1.0.3"
 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,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: quiet_quality
 version: !ruby/object:Gem::Version
-  version: 1.0.2
+  version: 1.0.3
 platform: ruby
 authors:
 - Eric Mueller
@@ -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