radius-spec 0.2.0 → 0.6.0

data/benchmarks/max_ternary.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+# Run from the command line: bundle exec ruby benchmarks/max_ternary.rb
+require_relative 'bm_setup'
+
+display_benchmark_header
+
+section "Min First" do |bench|
+  x = 1
+  y = 2
+
+  bench.report("max") do
+    [x, y].max
+  end
+
+  bench.report("ternary") do
+    (x < y) ? y : x
+  end
+end
+
+section "Max First" do |bench|
+  x = 2
+  y = 1
+
+  bench.report("max") do
+    [x, y].max
+  end
+
+  bench.report("ternary") do
+    (x < y) ? y : x
+  end
+end
+
+section "Equal values" do
+  x = 2
+  y = 2
+
+  bench.report("max") do
+    [x, y].max
+  end
+
+  bench.report("ternary") do
+    (x < y) ? y : x
+  end
+end
+
+__END__
+
+### Environment
+
+ruby 2.5.1p57 (2018-03-29 revision 63029) [x86_64-darwin16]
+GC Disabled: false
+
+### Test Cases
+
+#### Min First
+
+```
+Warming up --------------------------------------
+                 max   349.454k i/100ms
+             ternary   349.128k i/100ms
+Calculating -------------------------------------
+                 max     12.628M (± 0.9%) i/s -     62.902M in   5.000232s
+             ternary     12.853M (± 0.8%) i/s -     64.240M in   5.015540s
+                   with 95.0% confidence
+
+Comparison:
+             ternary: 12852607.6 i/s
+                 max: 12628052.1 i/s - 1.02x  (± 0.01) slower
+                   with 95.0% confidence
+```
+
+#### Max First
+
+```
+Warming up --------------------------------------
+                 max   346.104k i/100ms
+             ternary   344.003k i/100ms
+Calculating -------------------------------------
+                 max     12.788M (± 0.7%) i/s -     64.029M in   5.022073s
+             ternary     12.607M (± 0.7%) i/s -     62.953M in   5.006764s
+                   with 95.0% confidence
+
+Comparison:
+                 max: 12787891.5 i/s
+             ternary: 12606659.1 i/s - same-ish: difference falls within error
+                   with 95.0% confidence
+```
+
+#### Equal values
+
+```
+Warming up --------------------------------------
+                 max   340.468k i/100ms
+             ternary   343.788k i/100ms
+Calculating -------------------------------------
+                 max     12.278M (± 0.9%) i/s -     61.284M in   5.010572s
+             ternary     12.703M (± 0.9%) i/s -     63.601M in   5.026552s
+                   with 95.0% confidence
+
+Comparison:
+             ternary: 12702775.1 i/s
+                 max: 12277915.1 i/s - 1.03x  (± 0.01) slower
+                   with 95.0% confidence
+```

data/benchmarks/max_ternary_micro.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+# Run from the command line: bundle exec ruby benchmarks/max_ternary_micro.rb
+require_relative 'bm_setup'
+
+display_benchmark_header
+
+section "Min First" do |bench|
+  x = 1
+  y = 2
+
+  bench.report("max") do |times|
+    i = 0
+    while i < times
+      [x, y].max
+      i += 1
+    end
+  end
+
+  bench.report("ternary") do |times|
+    i = 0
+    while i < times
+      (x < y) ? y : x
+      i += 1
+    end
+  end
+end
+
+section "Max First" do |bench|
+  x = 2
+  y = 1
+
+  bench.report("max") do |times|
+    i = 0
+    while i < times
+      [x, y].max
+      i += 1
+    end
+  end
+
+  bench.report("ternary") do |times|
+    i = 0
+    while i < times
+      (x < y) ? y : x
+      i += 1
+    end
+  end
+end
+
+section "Equal values" do |bench|
+  x = 2
+  y = 2
+
+  bench.report("max") do |times|
+    i = 0
+    while i < times
+      [x, y].max
+      i += 1
+    end
+  end
+
+  bench.report("ternary") do |times|
+    i = 0
+    while i < times
+      (x < y) ? y : x
+      i += 1
+    end
+  end
+end
+
+__END__
+
+### Environment
+
+ruby 2.5.1p57 (2018-03-29 revision 63029) [x86_64-darwin16]
+GC Disabled: false
+
+### Test Cases
+
+#### Min First
+
+```
+Warming up --------------------------------------
+                 max   318.262k i/100ms
+             ternary   330.711k i/100ms
+Calculating -------------------------------------
+                 max     38.997M (± 0.6%) i/s -    193.822M in   5.001947s
+             ternary     48.280M (± 0.5%) i/s -    240.096M in   5.002313s
+                   with 95.0% confidence
+
+Comparison:
+             ternary: 48279773.6 i/s
+                 max: 38996762.1 i/s - 1.24x  (± 0.01) slower
+                   with 95.0% confidence
+```
+
+#### Max First
+
+```
+Warming up --------------------------------------
+                 max   336.333k i/100ms
+             ternary   344.267k i/100ms
+Calculating -------------------------------------
+                 max     38.699M (± 0.7%) i/s -    192.046M in   5.000931s
+             ternary     50.601M (± 0.6%) i/s -    251.315M in   5.002150s
+                   with 95.0% confidence
+
+Comparison:
+             ternary: 50601023.9 i/s
+                 max: 38699482.7 i/s - 1.31x  (± 0.01) slower
+                   with 95.0% confidence
+```
+
+#### Equal values
+
+```
+Warming up --------------------------------------
+                 max   331.543k i/100ms
+             ternary   342.686k i/100ms
+Calculating -------------------------------------
+                 max     39.661M (± 0.6%) i/s -    197.268M in   5.004271s
+             ternary     47.147M (± 0.5%) i/s -    234.740M in   5.006089s
+                   with 95.0% confidence
+
+Comparison:
+             ternary: 47147208.6 i/s
+                 max: 39660659.9 i/s - 1.19x  (± 0.01) slower
+                   with 95.0% confidence
+```

data/benchmarks/unfreeze_string.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+# Run from the command line: bundle exec ruby benchmarks/unfreeze_string.rb
+require_relative 'bm_setup'
+
+display_benchmark_header
+
+# rubocop:disable Performance/UnfreezeString
+section "Unfreezing empty string" do |bench|
+  bench.report("String.new") do
+    String.new
+  end
+
+  bench.report("+") do
+    +""
+  end
+
+  bench.report("dup") do
+    "".dup
+  end
+end
+
+STRING = "Any String"
+section "Unfreezing string" do |bench|
+  bench.report("String.new") do
+    String.new(STRING)
+  end
+
+  bench.report("+") do
+    +STRING
+  end
+
+  bench.report("dup") do
+    STRING.dup
+  end
+end
+# rubocop:enable Performance/UnfreezeString
+
+__END__
+
+### Environment
+
+ruby 2.5.1p57 (2018-03-29 revision 63029) [x86_64-darwin16]
+GC Disabled: false
+
+### Test Cases
+
+#### Unfreezing empty string
+
+```
+Warming up --------------------------------------
+          String.new   262.027k i/100ms
+                   +   286.997k i/100ms
+                 dup   217.963k i/100ms
+Calculating -------------------------------------
+          String.new      6.791M (± 0.9%) i/s -     34.064M in   5.029927s
+                   +      8.811M (± 1.1%) i/s -     43.911M in   5.011455s
+                 dup      4.627M (± 1.0%) i/s -     23.104M in   5.007394s
+                   with 95.0% confidence
+
+Comparison:
+                   +:  8810714.9 i/s
+          String.new:  6791074.6 i/s - 1.30x  (± 0.02) slower
+                 dup:  4626875.0 i/s - 1.90x  (± 0.03) slower
+                   with 95.0% confidence
+```
+
+#### Unfreezing string
+
+```
+Warming up --------------------------------------
+          String.new   220.258k i/100ms
+                   +   287.795k i/100ms
+                 dup   214.192k i/100ms
+Calculating -------------------------------------
+          String.new      4.624M (± 0.8%) i/s -     23.127M in   5.010887s
+                   +      8.946M (± 0.9%) i/s -     44.608M in   5.001680s
+                 dup      4.513M (± 0.9%) i/s -     22.704M in   5.041383s
+                   with 95.0% confidence
+
+Comparison:
+                   +:  8946340.5 i/s
+          String.new:  4624267.9 i/s - 1.93x  (± 0.02) slower
+                 dup:  4513230.8 i/s - 1.98x  (± 0.02) slower
+                   with 95.0% confidence
+```

data/benchmarks/unpack_first.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+# Run from the command line: bundle exec ruby benchmarks/unpack_first.rb
+require_relative 'bm_setup'
+
+display_benchmark_header
+
+PACKED_STRING = "foo"
+PACKED_FORMAT = "h*"
+
+# rubocop:disable Style/UnpackFirst
+section "Unpacking strings" do |bench|
+  bench.report("unpack.first") do
+    PACKED_STRING.unpack(PACKED_FORMAT).first
+  end
+
+  bench.report("unpack[0]") do
+    PACKED_STRING.unpack(PACKED_FORMAT)[0]
+  end
+
+  bench.report("unpack1") do
+    PACKED_STRING.unpack1(PACKED_FORMAT)
+  end
+end
+# rubocop:enable Style/UnpackFirst
+
+__END__
+
+### Environment
+
+ruby 2.5.1p57 (2018-03-29 revision 63029) [x86_64-darwin16]
+GC Disabled: false
+
+### Test Cases
+
+#### Unpacking strings
+
+```
+Warming up --------------------------------------
+        unpack.first   228.848k i/100ms
+           unpack[0]   225.375k i/100ms
+             unpack1   254.431k i/100ms
+Calculating -------------------------------------
+        unpack.first      5.074M (± 1.0%) i/s -     25.402M in   5.021645s
+           unpack[0]      5.412M (± 1.0%) i/s -     27.045M in   5.012499s
+             unpack1      7.185M (± 0.9%) i/s -     35.875M in   5.011588s
+                   with 95.0% confidence
+
+Comparison:
+             unpack1:  7184877.9 i/s
+           unpack[0]:  5412005.1 i/s - 1.33x  (± 0.02) slower
+        unpack.first:  5074389.3 i/s - 1.42x  (± 0.02) slower
+                   with 95.0% confidence
+```

data/bin/ci

@@ -15,9 +15,9 @@ bin/rspec
 # bundle-audit provides patch-level verification for Bundler
 # https://github.com/rubysec/bundler-audit.
 echo " ---> Running bundler-audit"
-gem install --no-rdoc --no-ri bundler-audit
+gem install --no-document bundler-audit
 bundle-audit check --update
 
 # Run style checker
 echo " ---> Running rubocop"
-bin/rubocop --extra-details --display-style-guide
+bin/rubocop --extra-details --display-style-guide --lint

data/bin/ci-code-review

@@ -0,0 +1,28 @@
+#!/bin/bash
+
+# See:
+#   - https://docs.travis-ci.com/user/environment-variables/#Convenience-Variables
+#   - https://docs.travis-ci.com/user/environment-variables/#Default-Environment-Variables
+#   - https://docs.travis-ci.com/user/pull-requests/#Pull-Requests-and-Security-Restrictions
+if [[ "$TRAVIS_PULL_REQUEST" = "false" ]] || [[ "$TRAVIS_BRANCH" = "production" ]]; then
+  exit
+fi
+
+set -e
+cd "$(dirname "$0")/.."
+
+REVIEWDOG_VERSION="0.9.9"
+
+if ! [ "$(./bin/reviewdog -version)" = "$REVIEWDOG_VERSION" ]; then
+  echo "Installing reviewdog version ${REVIEWDOG_VERSION}..."
+  curl -fsSL https://github.com/haya14busa/reviewdog/releases/download/$REVIEWDOG_VERSION/reviewdog_linux_amd64 \
+    -o ./bin/reviewdog
+  chmod +x ./bin/reviewdog
+fi
+
+echo Rubocop Version: $(./bin/rubocop --version)
+echo Review Dog Version: $(./bin/reviewdog -version)
+
+# Add `-diff="git diff master"` to reviewdog args when running locally
+./bin/rubocop --config .rubocop.yml --extra-details --display-style-guide --rails | \
+  ./bin/reviewdog -f=rubocop -reporter=github-pr-check

data/common_rubocop.yml

@@ -4,26 +4,63 @@ AllCops:
     # Exclude generated binstubs
     - 'bin/bundle'
     - 'bin/bundler-travis'
+    - 'bin/pronto'
     - 'bin/pry'
+    - 'bin/radius-cli'
     - 'bin/rake'
     - 'bin/rspec'
     - 'bin/rubocop'
     - 'bin/travis'
+    - 'bin/webpack'
+    - 'bin/webpack-dev-server'
     - 'bin/yard'
+    - 'bin/yarn'
     # Exclude vendored content
     - 'vendor/**/*'
-  Include:
-    - '**/Brewfile'
-    - '**/Rakefile'
 
-# Modifiers should be indented as deep as method definitions, or as deep as the
-# class/module keyword, depending on configuration.
+# We prefer outdented access modifiers as we feel they provide demarcation of
+# the class similar to `rescue` and `ensure` in a method.
 #
-# Configuration parameters: EnforcedStyle, SupportedStyles, IndentationWidth.
+# Configuration parameters: EnforcedStyle, IndentationWidth.
 # SupportedStyles: outdent, indent
 Layout/AccessModifierIndentation:
+  Details: |
+
+    Prefer outdented access modifiers to provide demarcation of the class
+    similar to `rescue` and `ensure` in a method.
   EnforcedStyle: outdent
 
+# Rubocop 0.60.0 changed how it handled value alignments in this cop. This
+# breaks our preference for wanting keys to be aligned, but allowing values to
+# either use the `key` or `table` style:
+#
+#     key_style = {
+#       key: :value,
+#       another: :value,
+#       yet_another: :value
+#     }
+#     table_style = {
+#       key:         :value,
+#       another:     :value
+#       yet_another: :value
+#     }
+#
+# This is logged with Rubocop: https://github.com/rubocop-hq/rubocop/issues/6410
+#
+# Until Rubocop resolves this we've decided to enforce the key style so that we
+# do not lose all associated formatting checks. Additionally, in response to
+# the referenced issue the Rubocop disables the alignment check by default. To
+# continue using it we force enable it here.
+#
+# Configuration parameters: EnforcedHashRocketStyle, EnforcedColonStyle, EnforcedLastArgumentHashStyle.
+# SupportedHashRocketStyles: key, separator, table
+# SupportedColonStyles: key, separator, table
+# SupportedLastArgumentHashStyles: always_inspect, always_ignore, ignore_implicit, ignore_explicit
+Layout/AlignHash:
+  Enabled: true
+  EnforcedHashRocketStyle: key
+  EnforcedColonStyle: key
+
 # Disabling this until it is fixed to support multi-line block chains using the
 # semantic style.
 #
@@ -37,17 +74,11 @@ Layout/BlockAlignment:
 # Disabling this until it is fixed to handle multi-line method chains where the
 # first method call is multi-line.
 #
-# See # https://github.com/bbatsov/rubocop/issues/5650
-Layout/ClosingParenthesisIndentation:
-  Enabled: false
-
-# Disabling this until it is fixed to handle multi-line method chains where the
-# first method call is multi-line.
-#
-# See # https://github.com/bbatsov/rubocop/issues/5650
+# See https://github.com/bbatsov/rubocop/issues/5650
 #
 # Configuration parameters: EnforcedStyle, IndentationWidth.
-# SupportedStyles: consistent, special_for_inner_method_call, special_for_inner_method_call_in_parentheses
+# SupportedStyles: consistent, consistent_relative_to_receiver,
+#                  special_for_inner_method_call, special_for_inner_method_call_in_parentheses
 Layout/FirstParameterIndentation:
   Enabled: false
 
@@ -60,14 +91,15 @@ Layout/FirstParameterIndentation:
 Layout/IndentHeredoc:
   EnforcedStyle: squiggly
 
-# We tend to indent multi-line operation statements. I think this is because
-# it's tends to be the default style auto-formatted by VIM (which many of us
-# use). It also helps show the continuation of the statement instead of it
+# We tend to indent multi-line operation statements. I think this is because it
+# tends to be the default style auto-formatted by VIM (which many of us use).
+# It also helps show the continuation of the statement instead of it
 # potentially blending in with the start of the next statement.
 #
 # Configuration parameters: EnforcedStyle, IndentationWidth.
 # SupportedStyles: aligned, indented
 Layout/MultilineOperationIndentation:
+  Details: "This helps show expression continuation setting it apart from the following LOC."
   EnforcedStyle: indented
 
 # In our specs Rubocop inconsistently complains when using the block form of
@@ -92,7 +124,7 @@ Lint/AmbiguousBlockAssociation:
   Exclude:
     - 'spec/**/*_spec.rb'
 
-# Often with benchmarking we don't explictly "use" a variable or return value.
+# Often with benchmarking we don't explicitly "use" a variable or return value.
 # We simply need to perform the operation which generates said value for the
 # benchmark.
 #
@@ -102,6 +134,7 @@ Lint/Void:
     - 'benchmarks/**/*'
 
 # Configuration parameters: CountComments, ExcludedMethods, Max.
+# ExcludedMethods: refine
 Metrics/BlockLength:
   Exclude:
     - '**/Rakefile'
@@ -109,6 +142,13 @@ Metrics/BlockLength:
     - 'spec/spec_helper.rb'
     - 'spec/**/*_spec.rb'
     - 'spec/support/model_factories.rb'
+  ExcludedMethods:
+    - 'chdir'
+    - 'refine'
+    - 'Capybara.register_driver'
+    - 'Gem::Specification.new'
+    - 'RSpec.configure'
+    - 'VCR.configure'
 
 # We generally prefer to use the default line length of 80. Though sometimes
 # we just need a little extra space because it makes it easier to read.
@@ -142,6 +182,16 @@ Metrics/LineLength:
     # Attempt at trailing comments
     - '\A.{1,78}\s#\s.*\z'
   Max: 100
+  Exclude:
+    - '**/*.gemspec'
+
+# This is overly pedantic (only allowing `other` as the parameter name). Ruby
+# core doesn't follow this consistently either. Looking at several classes
+# throughout Ruby core we do often see `other`, but also often `obj` or
+# `other_*`. In some cases, the parameter is named more meaningfully with names
+# like `real`, `numeric`, or `str`.
+Naming/BinaryOperatorParameterName:
+  Enabled: false
 
 # Configuration parameters: ExpectMatchingDefinition, Regex, IgnoreExecutableScripts, AllowedAcronyms.
 # AllowedAcronyms: CLI, DSL, ACL, API, ASCII, CPU, CSS, DNS, EOF, GUID, HTML, HTTP, HTTPS, ID, IP, JSON, LHS, QPS, RAM, RHS, RPC, SLA, SMTP, SQL, SSH, TCP, TLS, TTL, UDP, UI, UID, UUID, URI, URL, UTF8, VM, XML, XMPP, XSRF, XSS
@@ -157,11 +207,33 @@ Naming/FileName:
 # for those heredocs which represent "file" text.
 #
 # Configuration parameters: Blacklist.
-# Blacklist: END, (?-mix:EO[A-Z]{1})
+# Blacklist: (?-mix:(^|\s)(EO[A-Z]{1}|END)(\s|$))
 Naming/HeredocDelimiterNaming:
+  Details: |
+
+    Use meaningful delimiter names to provide context to the text. The only
+    allowed `EO*` variant if `EOF` which has specific meaning for file content.
   Blacklist:
-    - 'END'
-    - '(?-mix:EO[A-EG-Z]{1})'
+    - !ruby/regexp '/(^|\s)(EO[A-EG-Z]{1}|END)(\s|$)/'
+
+# It is generally a good idea to match the instance variable names with their
+# methods to keep consistent with the attribute reader / writer pattern.
+# However, this can pose an issue in Rails. Most notably, when writing modules
+# that will be used as controller plugins. The reason is that the Rails
+# controllers-to-view interface is ivars. Using a leading underscore can help
+# avoid accidental controller ivar naming conflicts.
+#
+# Configuration parameters: EnforcedStyleForLeadingUnderscores.
+# SupportedStylesForLeadingUnderscores: disallowed, required, optional
+Naming/MemoizedInstanceVariableName:
+  Details: |
+
+    It is generally a good idea to match the instance variable names with their
+    methods to keep consistent with the attribute reader / writer pattern. An
+    exception can be made for modules that want to avoid naming conflicts with
+    classes that include them. In this case a single leading underscore is
+    acceptable.
+  EnforcedStyleForLeadingUnderscores: optional
 
 # `alias` behavior changes on scope. In general we expect the behavior to be
 # that which is defined by `alias_method`.
@@ -171,8 +243,35 @@ Naming/HeredocDelimiterNaming:
 # Configuration parameters: EnforcedStyle.
 # SupportedStyles: prefer_alias, prefer_alias_method
 Style/Alias:
+  Details: |
+
+    Prefer `alias_method` because `alias` behavior changes based on scope.
+
+    See:
+      - https://stackoverflow.com/questions/4763121/should-i-use-alias-or-alias-method
+      - https://blog.bigbinary.com/2012/01/08/alias-vs-alias-method.html
   EnforcedStyle: prefer_alias_method
 
+# Keeping with our semantic style we allow use of `and` / `or` conditionals
+# when it is used for control flow:
+#
+#     system("some command") or system("another command")
+#
+# Used in this manner it provides additional semantic clues to the intent of
+# the code. However, when there is a conditional, or the intent is to perform
+# a boolean comparison, the `&&` / `||` style should be used.
+#
+# Configuration parameters: EnforcedStyle.
+# SupportedStyles: always, conditionals
+Style/AndOr:
+  Details: |
+
+    Use `&&` / `||` for conditionals or general comparison. Use `and` / `or`
+    for control flow to provide additional semantic hints:
+
+        system("some command") or system("another command")
+  EnforcedStyle: conditionals
+
 # These days most people have editors which support unicode and other
 # non-ASCII characters.
 #
@@ -187,11 +286,11 @@ Style/AsciiComments:
 # When the return value of the method receiving the block is important prefer
 # `{..}` over `do..end`.
 #
-# Configuration parameters: EnforcedStyle, SupportedStyles, ProceduralMethods,
-#   FunctionalMethods, IgnoredMethods.
+# Configuration parameters: EnforcedStyle, ProceduralMethods, FunctionalMethods, IgnoredMethods.
 # SupportedStyles: line_count_based, semantic, braces_for_chaining
 Style/BlockDelimiters:
   Details: |
+
     Use semantic style for blocks:
       - Prefer `do...end` over `{...}` for procedural blocks.
       - Prefer `{...}` over `do...end` for functional blocks.
@@ -208,7 +307,14 @@ Style/BlockDelimiters:
     - realtime
     - with_object
   FunctionalMethods:
+    - create
+    - create!
+    - build
+    - build!
+    - default_scope
     - each_with_object
+    - filter_sensitive_data
+    - find
     - git_source
     - let
     - let!
@@ -221,6 +327,64 @@ Style/BlockDelimiters:
     - proc
     - it
 
+# Prefer `Time` over `DateTime`.
+#
+# While these are not necessarily interchangeable we prefer `Time`. According
+# to the Ruby docs `DateTime` is meant more for historical dates; it also does
+# not consider leap seconds or summer time rules.
+#
+# Lastly, `DateTime` is part of the stdlib which is written in Ruby; where as
+# `Time` is part of core and written in C.
+#
+# Configuration parameters: AllowCoercion
+Style/DateTime:
+  Enabled: true
+
+# The double negation idiom is a common Ruby-ism. All languages have various
+# idioms and part of learning the language is learning the common idioms. Once
+# learning the meaning it is not cryptic as Rubocop implies.
+#
+#   > Double negation converts converts a value to boolean.
+#   >
+#   > It converts "truthy" values to `true` and "falsey" values, `nil` and
+#   > `false`, to `false`.
+#
+# The [Rubocop style guide](https://github.com/rubocop-hq/ruby-style-guide#no-bang-bang)
+# does have a valid complaint about it's use in a conditional:
+#
+#   > you don't need this explicit conversion in the condition of a control
+#   > expression; using it only obscures your intention...
+#   >
+#   > ```ruby
+#   > # bad
+#   > x = 'test'
+#   > # obscure nil check
+#   > if !!x
+#   >   # body omitted
+#   > end
+#   >
+#   > # good
+#   > x = 'test'
+#   > if x
+#   >   # body omitted
+#   > end
+#   > ```
+#
+# This is true and we completely agree. However the check isn't limited to just
+# conditional control expressions. It affects any use of the idiom.
+#
+# We believe using the idiom is completely valid for predicate methods to
+# ensure either a `true` or `false` return, instead of just a "truthy" or
+# "falsey" response. As it is an op it is a bit faster than the alternative of
+# sending `nil?` to the object and more concise than using `obj == nil`. It
+# also works with something that is potentially `false` as expected.
+#
+# As we cannot customize this to only limit it to the conditional control
+# expressions, or instances which may be better replaced with something else
+# (like `blank?`), we are disabling it.
+Style/DoubleNegation:
+  Enabled: false
+
 # Using `case` instead of an `if` expression when the case condition is empty
 # can be more expressive of intent. Using multiple "cases" informs the reader
 # that all of the conditions are related or coupled in a meaningful way.
@@ -253,6 +417,7 @@ Style/EmptyMethod:
 # SupportedStyles: ruby19, hash_rockets, no_mixed_keys, ruby19_no_mixed_keys
 Style/HashSyntax:
   Details: |
+
     Prefer symbol keys using the 1.9 hash syntax. However, when keys are mixed
     use a consistent mapping style; which generally means using hash rockets.
   EnforcedStyle: ruby19_no_mixed_keys
@@ -266,6 +431,7 @@ Style/HashSyntax:
 # SupportedStyles: line_count_dependent, lambda, literal
 Style/Lambda:
   Details: |
+
     As part of our semantic style we generally use the literal `-> { }` format
     to indicate this is a function with a return value we care about. As this
     cop doesn't have a more flexible setting we prefer the literal syntax to
@@ -285,9 +451,10 @@ Style/MethodCalledOnDoEndBlock:
 Style/MultilineBlockChain:
   Enabled: false
 
-# Context for this cop is too dependent. Often using the numeric comparision is
-# faster. An in certain contexts, Also, depending on the context a numeric
-# comparison is more consistent and can even be more natural:
+# Context for this cop is too dependent.
+#
+# Often using the numeric comparison is faster. Also, depending on the context
+# a numeric comparison may produce a more consistent style:
 #
 #     # numeric comparison is more natural and consistent
 #     if n < 0
@@ -300,12 +467,55 @@ Style/MultilineBlockChain:
 Style/NumericPredicate:
   Enabled: false
 
+# In Ruby every method returns a value. Implicitly this is the value of the
+# last line of the method. This means using `return` is often redundant.
+# However, there isn't anything inherently wrong about doing so. In fact, in
+# some cases it can help with a consistent style in a method:
+#
+#     def transform(value)
+#       return value.call if value.is_a?(Proc)
+#       return value if value.frozen?
+#       return value.dup
+#     end
+#
+# Other times it can add context to a seemingly oddly place value:
+#
+#     def munge(data)
+#       data.slice! 5
+#       return nil
+#     end
+#
+# We often omit the explicit `return` in our code. Though sometimes we include
+# it for improved contextual clues and we don't want Rubocop to complain for
+# those cases.
+#
+# Configuration parameters: AllowMultipleReturnValues.
+Style/RedundantReturn:
+  Enabled: false
+
 # Prefer slashes for simple expressions. For multi-line use percent literal
-# to support comments and other advanced features.
+# to support comments and other advanced features. By using the mixed style we
+# are choosing to use `%r{}` for multi-line regexps. In general we are not a
+# fan of single vs multi-line dictating a style. We do make an exception in
+# this case because of the parity the braces give to general code block
+# grouping:
+#
+#     regex = %r{
+#       foo
+#       (bar)
+#       (baz)
+#     }x
 #
 # Configuration parameters: EnforcedStyle, AllowInnerSlashes.
 # SupportedStyles: slashes, percent_r, mixed
 Style/RegexpLiteral:
+  Details: |
+
+    Prefer slashes for simple expressions. Use `%r` for expressions containing
+    slashes and for complex expressions so then can be written across multiple
+    lines (allowing advanced features such as comments). Use of `%r` for
+    expressions spanning multiple lines provides some comprehension parity with
+    general code blocks.
   EnforcedStyle: mixed
 
 # If you only need to rescue a single, or predefined set of exceptions, then
@@ -347,17 +557,41 @@ Style/RegexpLiteral:
 # Configuration parameters: EnforcedStyle.
 # SupportedStyles: implicit, explicit
 Style/RescueStandardError:
+  Details: |
+
+    If you only need to rescue a single, or predefined set of exceptions, then
+    catch each exception explicitly. When you need to include a general error
+    handler or "catch-all" use the "unspecified rescue":
+
+        begin
+          # do something that may cause a standard error
+        rescue TypeError
+          handle_type_error
+        rescue => e
+          handle_error e
+        end
+
+    Avoid rescuing `Exception` as this may hide system errors.
   EnforcedStyle: implicit
 
 # We generally prefer double quotes but many generators use single quotes. We
 # don't view the performance difference to be all that much so we don't care
 # if the style is mixed or double quotes are used for static strings.
 #
-# Configuration parameters: EnforcedStyle, SupportedStyles, ConsistentQuotesInMultiline.
+# Configuration parameters: EnforcedStyle, ConsistentQuotesInMultiline.
 # SupportedStyles: single_quotes, double_quotes
 Style/StringLiterals:
   Enabled: false
 
+# As with regular string literals we have no real preference for this. Forcing
+# one style of strings over others for this case just adds to Rubocop noise and
+# in our experience developer frustration.
+#
+# Configuration parameters: EnforcedStyle.
+# SupportedStyles: single_quotes, double_quotes
+Style/StringLiteralsInInterpolation:
+  Enabled: false
+
 # We don't feel too strongly about percent vs bracket array style. We tend to
 # use the percent style, which also happens to be Rubocop's default. So for
 # pedantic consistency we'll enforce this.
@@ -371,7 +605,7 @@ Style/SymbolArray:
   MinSize: 3
 
 # When ternaries become complex they can be difficult to read due to increased
-# cognative load parsing the expression. Cognative load can increase further
+# cognitive load parsing the expression. Cognitive load can increase further
 # when assignment is involved.
 #
 # Configuration parameters: EnforcedStyle, AllowSafeAssignment.
@@ -379,9 +613,10 @@ Style/SymbolArray:
 Style/TernaryParentheses:
   AllowSafeAssignment: false
   Details: |
+
     When ternaries become complex they can be difficult to read due to
-    increased cognative load parsing the expression. Cognative load can
-    increase further when assignment is involved. To help reduce this cognative
+    increased cognitive load parsing the expression. Cognitive load can
+    increase further when assignment is involved. To help reduce this cognitive
     use parentheses for complex expressions.
   EnforcedStyle: require_parentheses_when_complex
 
@@ -397,6 +632,7 @@ Style/TernaryParentheses:
 # SupportedStylesForMultiline: comma, consistent_comma, no_comma
 Style/TrailingCommaInArguments:
   Details: |
+
     Always use trailing commas for multiline arguments. This makes git diffs
     easier to read by cutting down on noise when commas are appended. It also
     simplifies adding, removing, and swapping argument orders.
@@ -411,6 +647,7 @@ Style/TrailingCommaInArguments:
 # SupportedStylesForMultiline: comma, consistent_comma, no_comma
 Style/TrailingCommaInArrayLiteral:
   Details: |
+
     Always use trailing commas for multiline arrays. This makes git diffs
     easier to read by cutting down on noise when commas are appended. It also
     simplifies adding, removing, and re-arranging the elements.
@@ -423,6 +660,7 @@ Style/TrailingCommaInArrayLiteral:
 # SupportedStylesForMultiline: comma, consistent_comma, no_comma
 Style/TrailingCommaInHashLiteral:
   Details: |
+
     Always use trailing commas for multiline hashes. This makes git diffs
     easier to read by cutting down on noise when commas are appended. It also
     simplifies adding, removing, and re-arranging the elements.