leftovers 0.2.3 → 0.4.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 52698685d049f76cfbe3034d85b9de65aec3c06b44434119a6581b399778a648
-  data.tar.gz: daa5a40d80c7a180eb81a4dd59bc841788da04db541cfc93f2ae02577b1fd251
+  metadata.gz: aa735d4aa3320b0225d0d256c296b5b3b284593f285d1257a4b8e6bd74a0dd74
+  data.tar.gz: ebaaa2f4c2e93780788e36d961a623a015b1f8d11c0a9799882e5a21a45552f4
 SHA512:
-  metadata.gz: 98ab99b3d471cdf3d42cf2c2e4940fc985313d68ce6a1ffe7b2f2909b0bcd95c1019a5fccdb306177a8283c0837baf068942a9f390fc38ccdeed9f5ecf8019f7
-  data.tar.gz: 1dcea67041a8afec49b80ff6b168d18fa28fcba7c6bbd546d0f004f76152f12116d9538cc0920e32721228a8a41233ad8788678d77fd55279f79b000e744ac55
+  metadata.gz: 88cf80851cdb71a94a3d5497fa80ab4b020447e6aa23b1a9074ef19789bcdc77b576275aad066ac23170b1d2d18687f0b07322b24792cd31a163f2e70f3d637e
+  data.tar.gz: '0167915df5ad01dcf2368e72a98171cad57b22e4df7d6c8e5bc29b1e8e053b8a9e522746836102d769ca80745105021bbeb297d038ab8cd58410a2d797c34d04'

data/CHANGELOG.md

@@ -1,3 +1,42 @@
+# v0.4.3
+- add --write-todo so you can add this to your project without
+immediately fixing everything.
+
+# v0.4.2
+- Make sorbet happy with this as a dependency
+# v0.4.1
+- add `test_only:` to mark methods/constants/assignments as test_only in the config rather than just with magic comments
+
+# v0.4.0
+- add `requires:` to .leftovers.yml config to e.g. load inflections in a different place than `config/initializers/inflections`
+- REFACTORED EVERYTHING for a codebase i actually can extend
+- Now with a very modified config api. After this i don't intend on every doing a rewrite like this again, so this is correcting all my bad decisions the first time through
+  - `rules.names` with `rules.skip: true` is now `keep.names` (see config/parser.yml)
+  - `rules.calls` and `rules.defines` is now `dynamic.calls` and `dynamic.defines`
+  - `rules.calls/defines.arguments.if` is now `keep/dynamic.calls/defines.has_arguments:` (see config/graphql.yml field)
+  - `rules.calls/defines.arguments.unless` is now `keep/dynamic.unless.has_arguments` (see config/graphql.yml field)
+  - `rules.calls/defines.transforms.replace_with` is now `keep/dynamic.calls/defines.value` (see custom_config_spec.rb html)
+  - `rules.calls/defines.transforms.add_prefix.from_argument/joiner:` is now `dynamic.calls/defines.transforms.add_prefix.argument/add_suffix` (see config/rails.yml delegate)
+  - `rules.calls/defines.transforms.add_suffix.from_argument/joiner:` is now `dynamic.calls/defines.transforms.add_suffix.argument/add_prefix`
+  - `rules.calls/defines.key: true` is now `dynamic.calls/defines.keywords: '**'`
+  - `rules.calls/defines.arguments.if.arguments.value` is now `keep/dynamic.has_arguments.has_value`
+  - `rules.calls/defines.arguments.if.arguments.value.type` is now `keep/dynamic.has_arguments.has_value_type`
+  - `rules.calls/defines.linked_transforms` is now `dynamic.calls/defines.transforms` (see config/rails.yml attribute). For the previous behaviour of the `transforms:` key simply add separate calls/defines entry. (see config/ruby.yml attr_accessor)
+  - `rules.calls/defines.keys: true` is now `dynamic.calls/defines.keywords: '**'` and can be given name patterns (e.g. unless:. see config/rails.yml validates)
+  - argument positions are now 0-indexed rather than 1-indexed
+  - no more automatic recursion, there's now two new keywords:
+    - `dynamic.calls/defines.arguments/keywords` with `dynamic.calls/defines.nested.arguments/keywords` will define the next layer of arguments to collect (see config/rails.yml validates)
+    - `dynamic.calls/defines.arguments/keywords` with `dynamic.calls/defines.recursive: true` will use the arguments & keywords layers recursively (see config/rails.yml permit)
+  - no more automatic splitting on ':' and '.', there's now a `dynamic.calls/defines.transforms.split: '::'` (see config/rails.yml resource)
+
+# v0.3.0
+- Add simplecov, fix a handful of bugs it found
+- update fast_ignore
+
+# v0.2.4
+- use the right name for selenium-webdriver gem, so the bundler magic can work
+- handle yaml syntax errors.
+
 # v0.2.3
 - restore ability to handle syntax errors. I really need to add coverage to this project
 - Fix bug with delete_after on an empty string

data/README.md

@@ -1,16 +1,17 @@
 # Leftovers
-[![travis](https://travis-ci.org/robotdana/leftovers.svg?branch=master)](https://travis-ci.org/robotdana/leftovers)
+[![travis](https://travis-ci.com/robotdana/leftovers.svg?branch=main)](https://travis-ci.com/robotdana/leftovers)
+[![Gem Version](https://badge.fury.io/rb/leftovers.svg)](https://rubygems.org/gems/leftovers)
 
 Find unused `methods`, `Classes`, `CONSTANTS`, `@instance_variables`, `@@class_variables`, and `$global_variables` in your ruby projects.
 
 ## Why?
 
-Code that never gets executed is code that you shouldn't need to maintain.
+Code that never gets executed is code that you shouldn't need to maintain
 
 - Leftovers from refactoring
 - Partially removed features
 - Typos and THIS NEVER WOULD HAVE WORKED code
-- Code that you only keep around because there are tests of it.
+- Code that you only keep around because there are tests of it
 
 Leftovers will use static analysis to find these bits of code for you.
 
@@ -29,7 +30,7 @@ It's aware of how some gems call methods for you, including (still somewhat inco
 Add this line to your application's Gemfile:
 
 ```ruby
-gem 'leftovers'
+gem 'leftovers', require: false
 ```
 
 And then execute:
@@ -42,7 +43,7 @@ Or install it yourself as:
 
 ## Usage
 
-Run `leftovers` in your terminal in the root of your project.
+Run `leftovers` in your command line in the root of your project.
 This will output progress as it collects the calls/references and definitions in your project.
 Then it will output any defined methods (or classes etc) which are not called.
 
@@ -55,11 +56,42 @@ lib/hello_world.rb:18:6 another_tested_unused_method def another_tested_unused_m
 Not directly called at all:
 lib/hello_world.rb:6:6 generated_method= attr_accessor :generated_method
 lib/hello_world.rb:6:6 generated_method attr_accessor :generated_method
+
+how to resolve: https://github.com/robotdana/leftovers/tree/main/Readme.md#how_to_resolve
 ```
 
+if there is an overwhelming number of results, try using [`--write-todo`](#write-todo)
+
+## How to resolve
+
+When running `leftovers` you'll be given a list of method, constant, and variable definitions it thinks are unused. Now what?
+
+they were unintentionally left when removing their calls:
+  - remove their definitions. (they're still there in your git etc history if you want them back)
+
+they are called dynamically:
+  - define how they're called dynamically in the [.leftovers.yml](#configuration-file); or
+  - mark the calls with [`# leftovers:call my_unused_method`](#leftovers-call); or
+  - mark the definition with [`# leftovers:keep`](#leftovers-keep)
+
+they're defined intentionally to only be used by tests:
+  - add [`# leftovers:test_only`](#leftovers-test-only)
+
+they're from a file that shouldn't be checked by leftovers:
+  - add the paths to the [`exclude_paths:`](https://github.com/robotdana/leftovers/tree/main/docs/Configuration.md#exclude_paths) list in the [.leftovers.yml](#configuration-file) file
+
+if there are too many to address when first adding leftovers to your project, try running [`leftovers --write-todo`](#write-todo),
+
+### --write-todo
+
+running `leftovers --write-todo` will generate a supplemental configuration file allowing all the currently detected uncalled definitions, which will be read on subsequent runs of `leftovers` without alerting any of the items mentioned in it.
+
+commit this file so you/your team can gradually address these items while still having leftovers alert you to any newly unused items.
+
 ## Magic comments
 
 ### `# leftovers:keep`
+_aliases `leftovers:keeps`, `leftovers:skip`, `leftovers:skips`, `leftovers:skipped`, `leftovers:allow`, `leftovers:allows`, `leftovers:allowed`_
 To mark a method definition as not unused, add the comment `# leftovers:keep` on the same line as the definition
 
 ```ruby
@@ -70,15 +102,16 @@ class MyClass
 end
 ```
 This would report `MyClass` is unused, but not my_method
-To do this for all definitions of this name, add the name with `skip: true` in the configuration file.
+To do this for all definitions of this name, instead of adding a comment, add the name to the [`keep:`](https://github.com/robotdana/leftovers/tree/main/docs/Configuration.md#keep) list in the [configuration file](#configuration-file).
 
-### `# leftovers:test`
+### `# leftovers:test_only`
+_aliases `leftovers:for_test`, `leftovers:for_tests`, `leftovers:test`, `leftovers:tests`, `leftovers:testing`_
 
-To mark a definition from a non-test dir, as intentionally only used by tests, use `leftovers:test`
+To mark a definition from a non-test dir, as intentionally only used by tests, use `leftovers:test_only`
 ```ruby
 # app/my_class.rb
 class MyClass
-  def my_method # leftovers:test
+  def my_method # leftovers:test_only
     true
   end
 end
@@ -92,61 +125,44 @@ end
 
 This would consider `my_method` to be used, even though it is only called by tests.
 
+To do this for all definitions of this name, instead of adding a comment, add the name to the [`test_only:`](https://github.com/robotdana/leftovers/tree/main/docs/Configuration.md#test_only) list in the [configuration file](#configuration-file).
+
 ### `# leftovers:call`
+_aliases `leftovers:calls`_
 To mark a dynamic call that doesn't use literal values, use `leftovers:call` with the method name listed
 ```ruby
-method = [:puts, :warn].sample
-send(method, 'text') # leftovers:call puts, warn
+method = [:puts, :warn].sample # leftovers:call puts, warn
+send(method, 'text')
 ```
 
 This would consider `puts` and `warn` to both have been called
 
-## Configuration
+## Configuration file
 
 The configuration is read from `.leftovers.yml` in your project root.
-Its presence is optional and all of these settings are optional:
-
-see the [complete config documentation](https://github.com/robotdana/leftovers/tree/master/Configuration.md) for details.
-see the [built in config files](https://github.com/robotdana/leftovers/tree/master/lib/config) for examples.
-
-- [`include_paths:`](https://github.com/robotdana/leftovers/tree/master/Configuration.md#include_paths)
-- [`exclude_paths:`](https://github.com/robotdana/leftovers/tree/master/Configuration.md#exclude_paths)
-- [`test_paths:`](https://github.com/robotdana/leftovers/tree/master/Configuration.md#test_paths)
-- [`gems:`](https://github.com/robotdana/leftovers/tree/master/Configuration.md#gems)
-- [`rules:`](https://github.com/robotdana/leftovers/tree/master/Configuration.md#rules)
-  - [`names:`](https://github.com/robotdana/leftovers/tree/master/Configuration.md#names)
-    - [`has_prefix:`](https://github.com/robotdana/leftovers/tree/master/Configuration.md#has_prefix-has_suffix)
-    - [`has_suffix:`](https://github.com/robotdana/leftovers/tree/master/Configuration.md#has_prefix-has_suffix)
-    - [`matches:`](https://github.com/robotdana/leftovers/tree/master/Configuration.md#matches)
-  - [`paths:`](https://github.com/robotdana/leftovers/tree/master/Configuration.md#paths)
-  - [`skip:`](https://github.com/robotdana/leftovers/tree/master/Configuration.md#skip)
-  - [`calls:`](https://github.com/robotdana/leftovers/tree/master/Configuration.md#calls-defines), [`defines:`](https://github.com/robotdana/leftovers/tree/master/Configuration.md#calls-defines)
-    - [`arguments:`](https://github.com/robotdana/leftovers/tree/master/Configuration.md#arguments), [`keys:`](https://github.com/robotdana/leftovers/tree/master/Configuration.md#keys-), [`itself:`](https://github.com/robotdana/leftovers/tree/master/Configuration.md#itself-true)
-    - [`transforms:`](https://github.com/robotdana/leftovers/tree/master/Configuration.md#transforms), [`linked_transforms:`](https://github.com/robotdana/leftovers/tree/master/Configuration.md#linked_transforms)
-        - `original:`, `add_prefix:`, `add_suffix:`, `delete_prefix:`, `delete_suffix:`, `replace_with:`
-        - `delete_before:`, `delete_after:`, `downcase:`, `upcase:`, `capitalize:`, `swapcase:`
-        - `pluralize`, `singularize`, `camelize`, `underscore`, `demodulize`, `deconstantize`
-    - [`if:`](https://github.com/robotdana/leftovers/tree/master/Configuration.md#if-unless), [`unless:`](https://github.com/robotdana/leftovers/tree/master/Configuration.md#if-unless)
-      - [`has_argument:`](https://github.com/robotdana/leftovers/tree/master/Configuration.md#has_argument)
-        - `keyword:`
-          - [`has_prefix:`](https://github.com/robotdana/leftovers/tree/master/Configuration.md#has_prefix-has_suffix)
-          - [`has_suffix:`](https://github.com/robotdana/leftovers/tree/master/Configuration.md#has_prefix-has_suffix)
-          - [`matches:`](https://github.com/robotdana/leftovers/tree/master/Configuration.md#matches)
-        - `value:`
-          - [`has_prefix:`](https://github.com/robotdana/leftovers/tree/master/Configuration.md#has_prefix-has_suffix)
-          - [`has_suffix:`](https://github.com/robotdana/leftovers/tree/master/Configuration.md#has_prefix-has_suffix)
-          - [`matches:`](https://github.com/robotdana/leftovers/tree/master/Configuration.md#matches)
-          - `type:`
+Its presence is optional and all of these settings are optional.
+
+- [`include_paths:`](https://github.com/robotdana/leftovers/tree/main/docs/Configuration.md#include_paths)
+- [`exclude_paths:`](https://github.com/robotdana/leftovers/tree/main/docs/Configuration.md#exclude_paths)
+- [`test_paths:`](https://github.com/robotdana/leftovers/tree/main/docs/Configuration.md#test_paths)
+- [`requires:`](https://github.com/robotdana/leftovers/tree/main/docs/Configuration.md#requires)
+- [`gems:`](https://github.com/robotdana/leftovers/tree/main/docs/Configuration.md#gems)
+- [`keep:`](https://github.com/robotdana/leftovers/tree/main/docs/Configuration.md#keep)
+- [`test_only:`](https://github.com/robotdana/leftovers/tree/main/docs/Configuration.md#test_only)
+- [`dynamic:`](https://github.com/robotdana/leftovers/tree/main/docs/Configuration.md#dynamic)
+
+see the [complete config documentation](https://github.com/robotdana/leftovers/tree/main/docs/Configuration.md) for details.
+see the [built in config files](https://github.com/robotdana/leftovers/tree/main/lib/config) or [this repo's own config](https://github.com/robotdana/leftovers/tree/main/.leftovers.yml) for examples.
 
 ## Limitations
 
 - Leftovers will report methods/constants you define that are called outside your code (perhaps by gems) as unused
 
-  Add these names to the `rules:` list with `skip: true` in the `.leftovers.yml` or add an inline comment with `# leftovers:allow my_method_name`
-- Leftovers doesn't execute your code so isn't aware of dynamic calls to `send` (e.g. `send(variable_method_name)`). (it is aware of static calls (e.g. `send(:my_method_name)`), so using send to bypass method privacy is "fine")
+  Add these names to the `keep:` list in the `.leftovers.yml` or add an inline comment with `# leftovers:allow my_method_name`
+- Leftovers doesn't execute your code so isn't aware of e.g. variables in calls to `send` (e.g. `send(variable_method_name)`). (it is aware of static calls (e.g. `send(:my_method_name)`), so using send to bypass method privacy is "fine")
 
-  Add the method/pattern to the `rules:` list with `skip: true` in the `.leftovers.yml`, or add an inline comment with the list of possibilities `# leftovers:call my_method_1, my_method_2`.
-- Leftovers compares by name only, so multiple methods with the same name will count as used even if only one is.
+  Add the method/pattern to the `dynamic:` list with `skip: true` in the `.leftovers.yml`, or add an inline comment with the list of possibilities `# leftovers:call my_method_1, my_method_2`.
+- Leftovers compares by name only, so multiple definitions with the same name will count as used even if only one is.
 - haml & erb line and column numbers will be wrong as the files have to be precompiled before checking.
 
 ## Other tools

data/docs/Configuration.md

@@ -0,0 +1,627 @@
+# Configuration
+
+The configuration is read from `.leftovers.yml` in your project root.
+Its presence is optional and all of these settings are optional.
+
+- [`include_paths:`](#include_paths)
+- [`exclude_paths:`](#exclude_paths)
+- [`test_paths:`](#test_paths)
+- [`requires:`](#requires)
+- [`gems:`](#gems)
+- [`keep:`](#keep)
+- [`test_only:](#test_only)
+- [`dynamic:`](#dynamic)
+
+see the [built in config files](https://github.com/robotdana/leftovers/tree/main/lib/config) or [this repo's own config](https://github.com/robotdana/leftovers/tree/main/.leftovers.yml) for examples.
+
+## `include_paths:`
+_alias `include_path:`_
+
+List filenames/paths in the gitignore format of files to be checked
+Defined using the [.gitignore pattern format](https://git-scm.com/docs/gitignore#_pattern_format)
+
+By default leftovers will already check all `*.rb` files, and files with no extension and a shebang containing `ruby` e.g. (`#!/usr/bin/env ruby`)
+Also the config added in [`gems:`](#gems) may add to this list, e.g. `gems: rake` adds `Rakefile` and `*.rake` to be checked.
+
+```yml
+include_paths:
+  - '*.rb'
+  - '*.rake'
+  - Gemfile
+```
+
+Arrays are not necessary for single values
+
+## `exclude_paths:`
+_alias `exclude_path:`_
+
+List filenames/paths that match the above that you might want to exclude
+Defined using the [.gitignore pattern format](https://git-scm.com/docs/gitignore#_pattern_format)
+
+By default leftovers will already read your project's .gitignore file and ignore anything there.
+
+```yml
+exclude_paths:
+  - /some/long/irrelevant/generated/file
+```
+
+Arrays are not necessary for single values
+
+## `requires:` # TODO
+_alias `require`_
+
+List filenames/paths that you want to include
+Unlike other `paths:` configuration, each entry is **not** the gitignore pattern format.
+Instead it is strings that can be passed directly to ruby's `require` method (relative paths should start with `./`).
+
+Missing files/gems will be a warning, but not a LoadError.
+
+By default, the default [`gems: active_support`]() config `require: activesupport` and `gems: rails` will `require: ./config/initializers/inflections`
+
+```yml
+require: ./config/initializers/my_other_inflections_file
+```
+
+Arrays are not necessary for single values
+
+## `test_paths:`
+_alias `test_path:`_
+
+list filenames/paths of test directories that will be used to determine if a method/etc is only tested but not otherwise used.
+Defined using the [.gitignore pattern format](https://git-scm.com/docs/gitignore#_pattern_format)
+
+```yml
+test_paths:
+  - /test/
+  - /spec/
+```
+
+Arrays are not necessary for single values
+
+## `gems:`
+_alias `gem:`_
+
+By default Leftovers will look at your `Gemfile.lock` file to find all gem dependencies
+
+If you don't use bundler, you can still take advantage of the built in handling for certain gems. The arguments should exactly match the gems name. not all gems are supported yet.
+
+```yml
+gems:
+  - rspec
+  - rails
+```
+
+Arrays are not necessary for single values
+
+## `keep:`
+
+This is a list of methods/constants/variables that are ok to be defined and not used, because they're your public api, or called by a gem on your behalf or etc.
+
+Each entry can be a string (an exact match for a method, constant, or variable name that includes the sigil), or have at least one of the following properties:
+- [`names:`](#names)
+  or the properties from `names:`
+  - [`has_prefix:`](#has_prefix)
+  - [`has_suffix:`](#has_suffix)
+  - [`matches:`](#matches) (can't be used in the same entry as `has_prefix:` or `has_suffix:`)
+- [`paths:`](#paths)
+- [`has_arguments:`](#has_arguments)
+- [`unless`](#unless)
+
+Arrays are not necessary for single values
+
+example from rails.yml
+```yml
+keep:
+  - APP_PATH
+  - ssl_configured?
+  - has_suffix: Helper
+    path: /app/helpers
+  ...
+```
+
+Alternatively, you can mark method/constants/variables in-place using [magic comments](https://github.com/robotdana/leftovers/tree/main/README.md#magic-comments).
+
+## `test_only:`
+
+This is a list of methods/constants/variables that are ok to be defined outside of [test paths](#test_paths), but only used within test paths, maybe because they're your public api, or convenience methods for tests etc.
+
+Each entry can be a string (an exact match for a method, constant, or variable name that includes the sigil), or have at least one of the following properties:
+- [`names:`](#names)
+  or the properties from `names:`
+  - [`has_prefix:`](#has_prefix)
+  - [`has_suffix:`](#has_suffix)
+  - [`matches:`](#matches) (can't be used in the same entry as `has_prefix:` or `has_suffix:`)
+- [`paths:`](#paths)
+- [`has_arguments:`](#has_arguments)
+- [`unless`](#unless)
+
+Arrays are not necessary for single values
+
+example from rails.yml
+```yml
+test_only:
+  - APP_PATH
+  - ssl_configured?
+  - has_suffix: Helper
+    path: /app/helpers
+  ...
+```
+
+Alternatively, you can mark method/constants/variables in-place using [magic comments](https://github.com/robotdana/leftovers/tree/main/README.md#magic-comments).
+
+## `dynamic:`
+
+This is a list of methods, constants, or variables whose called arguments or assigned value/s are used to dynamically `call:` or define (`define:`) other methods, constants, or variables
+
+Each entry must have at least one of the following properties to restrict which method/constant/variable this applies to:
+- [`names:`](#names)
+  or the properties from `names:`
+  - [`has_prefix:`](#has_prefix)
+  - [`has_suffix:`](#has_suffix)
+  - [`matches:`](#matches)
+- [`paths:`](#paths)
+- [`has_arguments:`](#has_arguments)
+- [`unless`](#unless)
+
+And must have one or both of
+- ['calls:`](#calls-defines)
+- [`defines:`](#calls-defines)
+
+Arrays are not necessary for single values.
+
+example from the default ruby.yml
+```yml
+dynamic:
+  - name: attr_accessor
+    defines:
+      - arguments: '*'
+        add_suffix: '='
+      - arguments: '*'
+    calls:
+      arguments: '*'
+      add_prefix: '@'
+    ...
+```
+
+## `names:`
+_alias `name:`_
+
+This is a list of methods/constants/variables, and can be used in [`dynamic:`](#dynamic) and [`keep:`](#keep)
+
+Each entry can be a string (an exact match for a method, constant, or variable name that includes the sigil), or have at least one of the following properties:
+- [`has_prefix:`](#has_prefix)
+- [`has_suffix:`](#has_suffix)
+- [`matches:`](#matches) (this can't be used in the same entry as `has_prefix:` or `has_suffix:`)
+
+Arrays are not necessary for single values
+
+example from rails.yml
+```yml
+keep:
+  - APP_PATH
+  - ssl_configured?
+  - names:
+      has_suffix: Helper
+    path: /app/helpers
+  ...
+```
+
+## `has_prefix:`, `has_suffix:`
+
+To match strings other than exact strings, you can use has_suffix or has_prefix or both if you're feeling fancy.
+
+This can be in entries in:
+- [`dynamic:`](#dynamic), [`keep:`](#keep), [`names:`](#names) to match method/constant/variable names
+- [`has_arguments:`](#has_arguments), [`arguments:`](#arguments), [`keywords:`](#keywords), [`at:`](#at) to match keyword argument names (whether they're symbols or strings)
+- [`has_values:`](#has_values) to match argument/assigned values (whether they're symbols or strings)
+
+```yml
+keep:
+  - has_suffix: Helper # will match Helper, LinkHelper FormHelper, etc
+  - has_prefix: be_ # will match be_equal, be_invalid, etc
+  - { has_prefix: is_, has_suffix: '?' } # will match is_invalid?, is_equal? etc
+```
+
+## `matches:`
+_alias `match:`_
+
+if [`has_suffix:`](#has_prefix-has_suffix) and [`has_prefix:`](#has_prefix-has_suffix) isn't enough, you can use `matches:` to supply a regex
+
+This string is converted into an anchored ruby regexp and must match the whole string, see [ruby's regex documentation](https://ruby-doc.org/core-2.7.2/Regexp.html#class-Regexp-label-Metacharacters+and+Escapes) for the syntax.
+
+This can be in used for entries in:
+- [`dynamic:`](#dynamic), [`keep:`](#keep), [`names:`](#names) to match method/constant/variable names
+- [`has_arguments:`](#has_arguments), [`arguments:`](#arguments), [`keywords:`](#keywords) to match keyword argument names (whether they're symbols or strings in the code)
+
+```yml
+dynamic:
+  - names:
+      matches: 'row_\d+' # will match row_1, row_2, row_99, but not row_1a, or crow_1, or etc.
+    calls:
+      argument:
+        matches: 'column_\d+' # will match column_1, column_2, column_99, but not column_first etc
+```
+
+## `paths:`
+_alias `path:`_
+
+An list of paths, defined using the [.gitignore pattern format](https://git-scm.com/docs/gitignore#_pattern_format)
+
+This can be used in entries in [`dynamic:`](#dynamic), [`keep:`](#keep)
+
+Arrays are not necessary for single values
+
+```yml
+keep:
+  - name:
+      - has_suffix: Helper
+    path: /app/helpers
+```
+
+## `calls:`, `defines:`
+_aliases `call:`, `define:`_
+
+At least one of these must be used in each entry in [`dynamic:`](#dynamic)
+
+This is a list of values that are called or defined dynamically by the matched method, or eventually after being assigned to the the matched constant or variable.
+
+Each entry must be have at least one the these properties:
+- [`arguments:`](#arguments)
+- [`keywords:`](#keywords) keyword argument keywords, and assigned hash keys
+- [`itself: true`](#itself-true) the matched name (intended to be used with `transforms:`, as the untransformed matched name will already be tracked)
+- [`value:`](#value) a literal string to be called/defined
+
+also there may be any or all of these properties:
+- [`nested:`](#nested) (only with `arguments:`)
+- [`recursive: true`](#recursive-true) (only with `arguments:`)
+- [`transforms:`](#transforms)
+  - or any these properties for `transform:`
+  - [`add_prefix:`](#add_prefix-add_suffix)
+  - [`add_suffix:`](#add_prefix-add_suffix)
+  - [`delete_prefix:`](#delete_prefix-delete_suffix)
+  - [`delete_suffix:`](#delete_prefix-delete_suffix)
+  - [`delete_before:`](#delete_before-delete_after)
+  - [`delete_after:`](#delete_before-delete_after)
+  - [`split:`](#split)
+  - [`downcase:`](#downcase-upcase-capitalize-swapcase)
+  - [`upcase:`](#downcase-upcase-capitalize-swapcase)
+  - [`capitalize:`](#downcase-upcase-capitalize-swapcase)
+  - [`swapcase:`](#downcase-upcase-capitalize-swapcase)
+  - [`pluralize:`](#pluralize-singularize-camelize-demodulize-deconstantize-parameterize-titleize-underscore)
+  - [`singularize:`](#pluralize-singularize-camelize-demodulize-deconstantize-parameterize-titleize-underscore)
+  - [`camelize:`](#pluralize-singularize-camelize-demodulize-deconstantize-parameterize-titleize-underscore)
+  - [`underscore:`](#pluralize-singularize-camelize-demodulize-deconstantize-parameterize-titleize-underscore)
+  - [`demodulize:`](#pluralize-singularize-camelize-demodulize-deconstantize-parameterize-titleize-underscore)
+  - [`deconstantize:`](#pluralize-singularize-camelize-demodulize-deconstantize-parameterize-titleize-underscore)
+  - [`titleize:`](#pluralize-singularize-camelize-demodulize-deconstantize-parameterize-titleize-underscore)
+  - [`parameterize:`](#pluralize-singularize-camelize-demodulize-deconstantize-parameterize-titleize-underscore)
+
+Arrays are not necessary for single values and if the rule contains only `arguments:` the keyword can be omitted, and everything moved up a level
+
+```yml
+dynamic:
+  - name:
+      - send
+    calls:
+      arguments:
+        - 1
+```
+is equivalent to:
+```yml
+dynamic:
+  name: send
+  calls: 1
+```
+
+## `arguments:`
+_alias `argument:`_
+
+Each entry indicates the position or keyword of the value or values in either a list of method call arguments, or a literal array or hash
+and when used in:
+- [`calls:`](#calls-defines), [`defines:`](#calls-defines) or [`nested:`](#nested) to filter method/constant/variable names are supplied [`transforms:`](#transforms), or [`nested:`](#nested)
+- [`add_prefix:`](#add_prefix), [`add_suffix:`](#add_suffix) the argument value can be used as the prefix/suffix rather than a literal string
+
+It can have any of these properties:
+- [`at:`](#at)
+- [`has_value:`](#has_value)
+- [`has_value_type:`](#has_value_type)
+
+Arrays are not necessary for single values and if the rule contains only `at:` it can be omitted, and the values moved up a level
+
+## `has_arguments:`
+_alias `has_argument:`_
+
+Each entry indicates the position or keyword of the value or values in either a list of method call arguments, or a literal array or hash
+and when used in:
+- [`dynamic:`](#dynamic) it uses the presence of matching arguments to filter which methods calls/constant/variable assignments are processed
+- [`keep:`](#keep) it uses the presence of matching arguments to filter which methods calls/constant/variable assignments are skipped
+
+The method call/constant variable/assignment will be considered matching if it has **any** of these arguments/assigned values.
+
+It can have any of these properties:
+- [`at:`](#at)
+- [`has_value:`](#has_value) # TODO
+- [`has_value_type:`](#has_value_type) # TODO
+
+Arrays are not necessary for single values and if the rule contains only `at:` it can be omitted, and the values moved up a level
+
+## `keywords:`
+When the keyword argument **keywords** are the thing being called.
+
+```yml
+dynamic:
+  - name: validates
+      calls:
+        - arguments: '*'
+        - keywords: '**'
+          camelize: true
+          add_suffix: Validator
+```
+```ruby
+validates :first_name, :surname, presence: true
+```
+will count calls for `validates`, `first_name`, `surname`, and `PresenceValidator`
+
+## `at:`
+
+Each entry indicates the position or keyword of the value or values in either a list of method call arguments, or a literal array or hash.
+
+This can be used in:
+- [`has_arguments`](#has_arguments) to filter method calls/constant/variable assignments by the presence of this argument
+- [`arguments:`](#arguments) to select positional argument values and keyword **values** to be processed
+- [`keywords:`](#keywords) to select **keywords** and hash **keys** to be processed
+
+Each entry can be any of:
+- `'*'`: matches all positional arguments/array positions
+- `'**'`: matches all keyword arguments/hash positions
+- any positive Integer: matches the 1-indexed argument position/array position
+- any other String: matches the keyword argument or hash value, where the keyword/hash key string or symbol
+- or have at least one of the following properties to match the keyword/hash key string or symbol:
+  - [`has_prefix:`](#has_prefix)
+  - [`has_suffix:`](#has_suffix)
+  - [`matches:`](#matches) (this can't be used in the same entry as `has_prefix:` or `has_suffix:`)
+
+Arrays are not necessary for single values
+
+## `has_value:`
+
+filter [`arguments:`](#arguments), [`has_arguments:`](#has_arguments), and [`keywords:`](#keywords), by the argument/assigned value
+
+Each entry can be one of
+- `true`, `false`, `nil`, or an Integer. matches the literal value
+- a String. matches the literal string or symbol value
+- or have at least one of the following properties to match a string or symbol:
+  - [`has_prefix:`](#has_prefix)
+  - [`has_suffix:`](#has_suffix)
+  - [`matches:`](#matches) (this can't be used in the same entry as `has_prefix:` or `has_suffix:`)
+
+## `has_value_type:`
+
+Filter [`arguments:`](#arguments), [`has_arguments:`](#has_arguments), and [`keywords:`](#keywords), by the argument/assigned value
+
+Each entry can be one of
+- `'String'`
+- `'Symbol'`
+- `'Integer'`
+- `'Float'`
+
+Arrays are not necessary for single values
+
+## `nested:`
+
+To process an argument that is an array you will need to supply which entries in the array need processing.
+
+This can be used in [`calls:`](#calls-defines), [`defines:`](#calls-defines) or within a preceding `nested:` entry
+
+Each entry must be have at least one the these properties:
+- [`arguments:`](#arguments)
+- [`keywords:`](#keywords) keyword argument keywords, and assigned hash keys
+And may additionally have any of these properties:
+- [`nested:`](#nested)
+- [`recursive: true`](#recursive-true)
+
+It will filter the arrays/hashes found by its sibling properties `arguments:`, and `keywords:`, using its own child properties.
+
+e.g.
+```yml
+dynamic:
+  - names: my_method
+    calls:
+      argument: 2
+      nested:
+        argument: '*'
+        nested:
+          argument: name
+```
+```ruby
+my_method([{name: :name_1}, {name: :name_2}, [{name: :name_3, value: :value_1}, {name: :name_4, value: :value_2}])
+```
+will count `name_3`, and `name_4` (but not `name_1` and `name_2` because they're within the first positional argument, and not `value_1`, or `value_2`)
+
+Arrays are not necessary for single values
+
+## `recursive: true`
+
+This can be used in [`calls:`](#calls-defines), [`defines:`](#calls-defines) or within a preceding [`nested:`](#nested) entry
+
+Similar to [`nested:`](#nested), this processes arrays hashes found by its sibling [`arguments:`](#arguments) and [`keywords:`](#keywords) properties, with those same properties, recursively.
+
+e.g. rails' ActiveRecord::Base#joins method can call association methods using all positional arguments values, keyword argument keywords and values, and recursively all values arrays and hash keys and values
+```yml
+dynamic:
+  name: [joins, left_joins]
+  calls:
+    arguments: ['*', '**']
+    keywords: '**'
+    recursive: true
+```
+
+## `itself: true`
+
+Will supply the method/constant/variable name itself as the thing to be transformed.
+The original method/constant/variable name will continue to be called/defined as normal
+
+This can be used in [`calls:`](#calls-defines) and [`defines:`](#calls-defines)
+
+```yml
+- name:
+    has_prefix: be_
+  calls:
+    itself: true
+    delete_prefix: be_
+    add_suffix: '?'
+```
+```ruby
+expect(value).to be_empty
+```
+will count `be_empty` as a call to `empty?`
+
+## `value:`
+
+Will supply a literal string value method/constant/variable name itself as the thing to be called/defined.
+This can be used in [`calls:`](#calls-defines) and [`defines:`](#calls-defines).
+
+```yml
+- name: perform_async
+  calls:
+    value: perform
+```
+```ruby
+MyWorker.perform_async
+```
+will count `perform_async` as a call to `perform`
+
+## `transforms:`
+
+Sometimes the method/class being called is modified from the literal argument, sometimes that's just appending an `=` and sometimes it's more complex:
+
+Each entry can have a string that is an argumentless transform (e.g. capitalize) or a hash with transform keywords. This can be in used for entries in:
+- [`defines:`](#calls-defines), [`calls:`](#calls-defines) to modify values filtered by the sibling keys [`arguments:`](#arguments), [`keywords:`](#keywords) and [`itself: true`](#itself-true) (also [`value:`](#value) but as that's a literal value anyway, why would you)
+- [`add_prefix:`](#add_prefix-add_suffix), [`add_suffix:`](#add_prefix-add_suffix) to modify the selected `argument:` or `keyword:` for dynamic prefixes and suffixes
+
+- [`original`](#original) or `original: true`
+- [`add_prefix:`](#add_prefix-add_suffix)
+- [`add_suffix:`](#add_prefix-add_suffix)
+- [`delete_prefix:`](#delete_prefix-delete_suffix)
+- [`delete_suffix:`](#delete_prefix-delete_suffix)
+- [`delete_before:`](#delete_before-delete_after)
+- [`delete_after:`](#delete_before-delete_after)
+- [`split:`](#split)
+- [`downcase`](#downcase-upcase-capitalize-swapcase) or `downcase: true`
+- [`upcase`](#downcase-upcase-capitalize-swapcase) or `upcase: true`
+- [`capitalize`](#downcase-upcase-capitalize-swapcase) or `capitalize: true`
+- [`swapcase`](#downcase-upcase-capitalize-swapcase) or `swapcase: true`
+- Also, if you have the active_support gem available:
+  - [`pluralize`](#pluralize-singularize-camelize-demodulize-deconstantize-parameterize-titleize-underscore) or `pluralize: true`
+  - [`singularize`](#pluralize-singularize-camelize-demodulize-deconstantize-parameterize-titleize-underscore) or `singularize: true`
+  - [`camelize`](#pluralize-singularize-camelize-demodulize-deconstantize-parameterize-titleize-underscore) or `camelize: true`
+  - [`underscore`](#pluralize-singularize-camelize-demodulize-deconstantize-parameterize-titleize-underscore) or `underscore: true`
+  - [`demodulize`](#pluralize-singularize-camelize-demodulize-deconstantize-parameterize-titleize-underscore) or `demodulize: true`
+  - [`deconstantize`](#pluralize-singularize-camelize-demodulize-deconstantize-parameterize-titleize-underscore) or `deconstantize: true`
+  - [`titleize`](#pluralize-singularize-camelize-demodulize-deconstantize-parameterize-titleize-underscore) or `titleize: true`
+  - [`parameterize`](#pluralize-singularize-camelize-demodulize-deconstantize-parameterize-titleize-underscore) or `parameterize: true`
+
+If any one of these `transforms:` entries are used, all count as being used. To have these be counted independently instead, create multiple entries in the `defines:` list.
+
+```yml
+- name: attribute
+    defines:
+      - argument: 1
+        transforms:
+          - original # no transformation
+          - add_suffix: '?'
+          - add_suffix: '='
+```
+```ruby
+attribute :first_name
+```
+will count as a definition of `first_name`, `first_name=` and `first_name?`. `firstname=` wouldn't be reported on, even if only `first_name` and `first_name?` were used.
+
+Arrays are not necessary for single values, and if there is just one set of transforms, the `transforms:` keyword can be omitted and everything moved up a level.
+
+```yml
+- name: attr_writer
+  defines:
+    - argument: '*'
+      add_suffix: '='
+```
+```ruby
+attr_writer :first_name, :surname
+```
+will count as the definition of `first_name=`, and `surname=`
+
+## `original`
+
+Can be used in the [`transforms:`](#transforms) list, if used in a hash `true` can be used as a placeholder value
+
+This performs no change, and is only useful when grouped with other transforms
+
+## `add_prefix:`, `add_suffix:`
+
+Can be used in the [`transforms:`](#transforms) list (or anywhere `transforms:` is able to be omitted).
+
+Each entry is one of:
+- a literal string
+- [`argument:`](#argument) or [`keyword:`](#keyword) matching arguments/assignments from the original method call/method definition
+- Optionally [`transform:`] or any of the `transform:` properties, to transform the value(s) from `argument:` and `keyword:`.
+
+if multiple transform results are possible (from multiple entries, or multiple matching arguments or etc), then all results will be used.
+
+Arrays are not necessary for single values
+
+## `delete_prefix:`, `delete_suffix:`
+
+Can be used in the [`transforms:`](#transforms) list (or anywhere `transforms:` is able to be omitted).
+
+Each entry is a literal string, and _if present_ the matching prefix or suffix will be removed (if it's not present, this transform will continue to the next transform/result unmodified)
+
+if multiple transform results are possible (from multiple entries), then all results will be used.
+
+Arrays are not necessary for single values
+
+## `delete_before:`, `delete_after:`
+
+Can be used in the [`transforms:`](#transforms) list (or anywhere `transforms:` is able to be omitted).
+
+Each entry is a literal string, and _if present_ the string and everything before/after will be removed from the incoming value (if it's not present, this transform will continue to the next transform/result unmodified). if it's present multiple times then it will always be everything before/after the first substring match
+
+if multiple transform results are possible (from multiple entries), then all results will be used.
+
+Arrays are not necessary for single values
+
+## `split:`
+
+Can be used in the [`transforms:`](#transforms) list (or anywhere `transforms:` is able to be omitted).
+
+Each entry is a literal string, and _if present_ the incoming value will string will be split on this value. (if it's not present, this transform will continue to the next transform/result unmodified)
+
+if multiple transform results are possible (from multiple entries), then all results will be used.
+
+Arrays are not necessary for single values
+
+## `downcase`, `upcase`, `capitalize`, `swapcase`
+
+Can be used in the [`transforms:`](#transforms) list (or anywhere `transforms:` is able to be omitted).
+if used in a hash `true` can be used as a placeholder value
+
+the incoming value will be transformed using the [core ruby String method](https://ruby-doc.org/core-2.6/String.html#method-i-capitalize)
+
+## `pluralize`, `singularize`, `camelize`, `demodulize`, `deconstantize`, `parameterize`, `titleize`, `underscore`
+_aliases `camelcase`, `titlecase`_
+
+Can be used in the [`transforms:`](#transforms) list (or anywhere `transforms:` is able to be omitted).
+if used in a hash `true` can be used as a placeholder value
+
+the incoming value will be transformed using the [active_support String core extensions](https://edgeguides.rubyonrails.org/active_support_core_extensions.html#inflections)
+and if using [gems:](#gems) with `active_support` or `rails` then your `config/initializers/inflections.rb` will be loaded. if you have inflections in another file, then supply that to [`requires:`](#requires).
+
+If the `active_support` gem is not available this will raise an error.
+
+## `unless:`
+
+It will filter the values found by its sibling properties, whatever they are, removing anything that matches its own child properties.
+if it has no sibling properties, then it's filtering everything to remove anything that matches it's own child properties.
+
+Each entry is able to have child properties drawn from whatever the unless keyword's sibling properties are able to be
+
+Arrays are not necessary for single values