leftovers 0.7.0 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f27830ef42bcbcec33a78126a3b47582fa394714e1d137e802cd5ab166e35df5
-  data.tar.gz: a111ed33a8345fe8dc5d43cb92206d52cbc47a03bc8e961baee8558d677542b6
+  metadata.gz: f2cb691dc74d8b0d43765f899ea718a4d06c1ba8fa36ea3a68c44ece27531920
+  data.tar.gz: e24ade3f01a888de2e9438736d71b0e4f2d159a6783b3278e8ec7e58e7c8c626
 SHA512:
-  metadata.gz: e14c6c1b74d4c13ebcbb4d1184d50257d6aacaf05e8e6708282633f61ea1988374156880d66bb26a037bf4b67b58381246f12357bdaa99ff9248db620d94c152
-  data.tar.gz: 34e766e6ca2374858ee6da35e924287641bc4441d8f642e4d08285a0066185aa865724567b90f91de34b17f340f3f182e9b3f326c5fc63bf6abc414c0dc058b3
+  metadata.gz: a734ec1916762c5bc51fc212bfc254eb3d4083c968e6bcd128aa0c10ee9085762c6edbd86eb8afd3dd17ac5fa8b883d343bf34df3a3caaea1b84db5bc720bfaa
+  data.tar.gz: 7b80b90518a6a3e45aa3739394c18f4c7884ea07d75021dc919c62d23d6d110714c9969ab78b8078d6c219bfd9289a821bb4b828bc4e248a82a63f235cb7758f

data/CHANGELOG.md

@@ -1,3 +1,42 @@
+# v0.10.0
+- Fixed an issue with t.belongs_to (within the migration generated by rails active_storage:install - thanks @veganstraightedge)
+  - this was two issues:
+    1. it was raising an error because the DefinitionNode didn't act enough like an AST::Node, now it does
+    2. this should never have been defining anything anyway as the activerecord method was being assumed to be used, now if there's an explicit receiver for belongs_to/has_many etc, don't consider them the active record association methods.
+
+- now `has_receiver: true` and `has_receiver: false/nil` act differently, they refer to the presence or absence of any receiver, instead of the receiver being literally true or false or nil.
+- to have the previous behaviour, use the new `has_receiver: { literal: true }` or `literal: false` or `literal: null`
+
+# v0.9.0
+- Automatically test the config examples in the documentation, and fix the errors
+- simplify the `type: Proc` matcher
+- Update FastIgnore dependency, make fewer filesystem calls
+- Comprehensively describe all of ruby core and rails
+  This required/revealed a number of additions to the config
+  - Improve the performance of large config files by squash the config matching more
+  - Add `names:` and `has_arguments:` to `has_value:`.
+  - Fix error when positional `has_arguments:`/`has_value: at:` checks a node without arguments
+  - Add `eval` as a processing type, alongside `calls:` and `defines:`, this will process allow processing literal calls to instance_eval etc.
+  - Allow calling or defining based on the `receiver:`
+  - `all: []` & `any: []` arguments to dynamic/keep/test_only
+  - add `arguments: 1+` or `has_arguments: { at: 1+, has_value: true }` to match arguments from that position onward
+  - allow `has_arguments:` and `has_receiver:` (and `unless:` and `all:` and `any:` of those) to go within `calls:`,`defines:`,`set_privacy:`,`add_prefix:`,`add_suffix:` for cases like the `delegate prefix: true` vs `delegate prefix: :value` without having to redefine everything.
+  - allow `has_arguments.at` and `arguments:` to have a `type:` to distinguish between e.g. symbol keys and string keys.
+- Add a way to test custom precompilers with --view-compiled [PATH_PATTERNS...]
+
+# v0.8.0
+- Allow custom precompilers
+  ```yml
+    require: './path/to/my_precompiler'
+    precompile:
+      - paths: '*.myCustomFormat'
+        format: { custom: 'MyPrecompiler' }
+  ```
+  the built in precompilers have moved into this system too, with `format: haml` etc. `haml_paths` etc are now deprecated
+- a lot of refactoring, which revealed some edge cases i was handling
+  - collect a call to :my_method= with receiver&.my_method ||= (and += etc)
+  - if `add_prefix:` or `add_suffix:` points to another argument for a name that we can't use because it's a variable, it now just don't return the value, rather than returning the value but without the affix
+
 # v0.7.0
 - Rewrite the config parser/validation
   - to provide clearer error messages with line numbers and everything

data/README.md

@@ -15,7 +15,7 @@ Code that never gets executed is code that you shouldn't need to maintain
 
 Leftovers will use static analysis to find these bits of code for you.
 
-It's aware of how some gems call methods for you, including (still somewhat incomplete) support for rails.
+It's aware of how some gems call methods for you, including support for much of rails.
 
 ## Features
 
@@ -141,21 +141,21 @@ This would consider `puts` and `warn` to both have been called
 To mark a dynamic call for literal hash and array values without enumerating everything in the comment again, use `leftovers:dynamic:`  on the same line as the beginning of the array or hash
 
 ```ruby
-[ # leftovers:dynamic:call_login
+[ # leftovers:dynamic:call_attributes
   :user,
   :admin
-].each { |method| send("#{method}_login") }
+].map { |method| send("#{method}_attributes") }
 ```
 
 with the following configuration matching the `name: value` to the `leftovers:dynamic:process_name`
 
 ```yaml
 dynamic:
-  name: call_login
+  name: call_attributes
   arguments: '*'
-  add_suffix: '_login'
+  add_suffix: '_attributes'
 ```
-This would consider `user_login` and `admin_login` to both have been called.
+This would consider `user_attributes` and `admin_attributes` to both have been called.
 
 ## Configuration file
 
@@ -166,6 +166,7 @@ Its presence is optional and all of these settings are optional.
 - [`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)
+- [`precompile:`](https://github.com/robotdana/leftovers/tree/main/docs/Configuration.md#precompile)
 - [`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)
@@ -200,7 +201,7 @@ To install this gem onto your local machine, run `bundle exec rake install`.
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/robotdana/leftovers.
 
-I especially encourage issues and improvements to the default config, whether expanding the existing config/*.yml (rails.yml is particularly incomplete) or adding new gems.
+I especially encourage issues and improvements to the default config, whether expanding the existing config/*.yml or adding new gems.
 The file should be named `[rubygems name].yml` and its structure is identical to the [project config](#configuration)
 
 ## License

data/docs/Configuration.md

@@ -6,11 +6,7 @@ Its presence is optional and all of these settings are optional.
 - [`include_paths:`](#include_paths)
 - [`exclude_paths:`](#exclude_paths)
 - [`test_paths:`](#test_paths)
-- [`haml_paths:`](#haml_paths)
-- [`slim_paths:`](#slim_paths)
-- [`erb_paths:`](#erb_paths)
-- [`yaml_paths:`](#yaml_paths)
-- [`json_paths:`](#json_paths)
+- [`precompile:`](#precompile)
 - [`requires:`](#requires)
 - [`gems:`](#gems)
 - [`keep:`](#keep)
@@ -88,59 +84,36 @@ test_paths:
 
 Arrays are not necessary for single values
 
-## `haml_paths:`
-
-list filenames/paths of test directories that are in the haml format
-Defined using the [.gitignore pattern format](https://git-scm.com/docs/gitignore#_pattern_format)
+## `precompile:`
 
 ```yml
-haml_paths:
-  - '*.haml'
+  require: './path/my_project/my_precompiler'
+  precompile:
+    - paths: '*.myCustomFormat'
+      format: { custom: 'MyProject::MyPrecompiler' }
+    - paths: '*.my.json'
+      format: json
 ```
 
-Arrays are not necessary for single values. `*.haml` is recognized by default
+Define any precompilers and the paths they affect.
 
-## `slim_paths:`
-
-list filenames/paths of test directories that are in the slim format
-Defined using the [.gitignore pattern format](https://git-scm.com/docs/gitignore#_pattern_format)
-
-```yml
-slim_paths:
-  - '*.slim'
-```
-
-Arrays are not necessary for single values. `*.slim` is recognized by default
-
-## `erb_paths:`
-
-list filenames/paths of test directories that are in the erb format
-Defined using the [.gitignore pattern format](https://git-scm.com/docs/gitignore#_pattern_format)
-
-```yml
-erb_paths:
-  - '*.erb'
-```
+`paths:` are defined using the [.gitignore pattern format](https://git-scm.com/docs/gitignore#_pattern_format)
 
-Arrays are not necessary for single values. `*.erb` is recognized by default
+`format:` must be one of the predefined precompilers (erb, haml, [json](#format-json), slim, [yaml](#format-yaml)), or `custom:` with the name of a [custom precompiler](https://github.com/robotdana/leftovers/blob/main/docs/Custom-Precompilers.md) module.
+(use [`require:`](#requires) to have leftovers load its file)
 
-## `yaml_paths:`
+See [Custom precompilers](https://github.com/robotdana/leftovers/blob/main/docs/Custom-Precompilers.md) for more details on the custom precompiler class
 
-list filenames/paths of test directories that are in the yaml format
-Defined using the [.gitignore pattern format](https://git-scm.com/docs/gitignore#_pattern_format)
+Arrays are not necessary for single values.
 
-```yml
-include:
-  - 'config/*.yml'
-yaml_paths:
-  - '*.yml'
-```
+### `format: yaml`
 
-These documents will consider yaml tags like `!ruby/class 'MyClass'` to be a call to `MyClass` and render the structure of the yaml as arguments for the [`document:true`](#document-true) rule.
+The yaml precompiler considers yaml tags like `!ruby/class 'MyClass'` to be a call to `MyClass`.
+and renders the structure of the yaml document as arguments for the [`document:true`](#document-true) rule.
 
 so you could, e.g. read the class name out of a yaml document like:
 
-```yml
+```
 class_name: MyClass
 ```
 
@@ -159,21 +132,11 @@ dynamic:
 
 [`nested:`](#nested) may be useful for more complex yaml structures
 
-## `json_paths:`
-
-list filenames/paths of test directories that are in the json format
-Defined using the [.gitignore pattern format](https://git-scm.com/docs/gitignore#_pattern_format)
-
-```yml
-include:
-  - 'config/*.json'
-json_paths:
-  - '*.json'
-```
+### `format: json`
 
-These documents render the structure of the yaml as arguments for the [`document:true`](#document-true) rule.
+The json precompiler renders the structure of the json document as arguments for the [`document:true`](#document-true) rule.
 
-so you could, e.g. read the class name out of a yaml document like:
+so you could, e.g. read the class name out of a json document like:
 
 ```json
 { "class_name": "MyClass" }
@@ -224,7 +187,9 @@ Each entry can be a string (an exact match for a method, constant, or variable n
 - [`has_receiver:`](#has_receiver)
 - [`type:`](#type)
 - [`privacy:`](#privacy)
-- [`unless`](#unless)
+- [`unless:`](#unless)
+- [`all:`](#any-all)
+- [`any:`](#any-all)
 
 Arrays are not necessary for single values
 
@@ -235,7 +200,6 @@ keep:
   - 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).
@@ -252,7 +216,12 @@ Each entry can be a string (an exact match for a method, constant, or variable n
   - [`matches:`](#matches)
 - [`paths:`](#paths)
 - [`has_arguments:`](#has_arguments)
+- [`has_receiver:`](#has_receiver)
+- [`type:`](#type)
+- [`privacy:`](#privacy)
 - [`unless`](#unless)
+- [`all:`](#any-all)
+- [`any:`](#any-all)
 
 Arrays are not necessary for single values
 
@@ -263,7 +232,6 @@ test_only:
   - 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).
@@ -278,17 +246,22 @@ Each entry must have at least one of the following properties to restrict which
   - [`has_prefix:`](#has_prefix)
   - [`has_suffix:`](#has_suffix)
   - [`matches:`](#matches)
+- [`document: true`](#document-true)
 - [`paths:`](#paths)
 - [`has_arguments:`](#has_arguments)
 - [`has_receiver:`](#has_receiver)
+- [`type:`](#type)
+- [`privacy:`](#privacy)
 - [`unless:`](#unless)
-- [`document: true`](#document-true)
+- [`all:`](#any-all)
+- [`any:`](#any-all)
 
 And must have at least one of
 - ['calls:`](#calls-defines)
 - [`defines:`](#calls-defines)
 - [`set_privacy:](#set-privacy)
 - [`set_default_privacy:`](#set-default-privacy)
+- [`eval:`](#eval)
 
 Arrays are not necessary for single values.
 
@@ -303,7 +276,6 @@ dynamic:
     calls:
       arguments: '*'
       add_prefix: '@'
-    ...
 ```
 
 ## `names:`
@@ -326,7 +298,6 @@ keep:
   - names:
       has_suffix: Helper
     path: /app/helpers
-  ...
 ```
 
 ## `has_prefix:`, `has_suffix:`
@@ -388,7 +359,7 @@ Instructs to consider the whole document. this is useful when parsing [YAML](#ya
 e.g.
 
 ```yml
-includes: /config/roles.yml
+include_paths: /config/roles.yml
 dynamic:
   - document: true
     path: /config/roles.yml
@@ -399,7 +370,7 @@ dynamic:
 ```
 
 will parse "config/roles.yml"
-```yml
+```
 - build_house
 - drive_car
 ```
@@ -430,8 +401,10 @@ also there may be any or all of these properties:
   - [`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)
+  - [`delete_before:`](#delete_before-delete_after--delete_before_last-delete_after_last)
+  - [`delete_after:`](#delete_before-delete_after--delete_before_last-delete_after_last)
+  - [`delete_before_last:`](#delete_before-delete_after-delete_before_last-delete_after_last)
+  - [`delete_after_last:`](#delete_before-delete_after-delete_before_last-delete_after_last)
   - [`split:`](#split)
   - [`downcase:`](#downcase-upcase-capitalize-swapcase)
   - [`upcase:`](#downcase-upcase-capitalize-swapcase)
@@ -454,13 +427,13 @@ dynamic:
       - send
     calls:
       arguments:
-        - 1
+        - 0
 ```
 is equivalent to:
 ```yml
 dynamic:
   name: send
-  calls: 1
+  calls: 0
 ```
 
 ## `set_privacy:`
@@ -500,6 +473,27 @@ dynamic:
 
 these methods could then be filtered using the [`privacy:`](#privacy) method in another [`dynamic:`](#dynamic) or [`keep:`](#keep) rule.
 
+## `eval:`
+
+Eval has the same requirements as [`calls:` & `defines:`](#calls-defines).
+
+it parses a string or transformed string as ruby, using the same rules as the containing file
+For example:
+
+```yml
+dynamic:
+  name: eval_later
+  eval:
+    argument: my_ruby_string
+```
+
+with the ruby:
+```ruby
+eval_later(delay: 1000, my_ruby_string: "MyClass.puts 'shenanigans'")
+```
+
+would consider `MyClass`, and `puts` to have been called.
+
 ## `arguments:`
 _alias `argument:`_
 
@@ -510,7 +504,7 @@ and when used in:
 
 It can have any of these properties:
 - [`at:`](#at)
-- [`has_value:`](#has_value_has_receiver)
+- [`has_value:`](#has_value)
 
 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.
 
@@ -528,7 +522,7 @@ The method call/constant variable/assignment will be considered matching if it h
 
 It can have any of these properties:
 - [`at:`](#at)
-- [`has_value:`](#has_value_has_receiver)
+- [`has_value:`](#has_value)
 
 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
 
@@ -540,11 +534,11 @@ When the keyword argument **keywords** are the thing being called.
 ```yml
 dynamic:
   - name: validates
-      calls:
-        - arguments: '*'
-        - keywords: '**'
-          camelize: true
-          add_suffix: Validator
+    calls:
+      - arguments: '*'
+      - keywords: '**'
+        camelize: true
+        add_suffix: Validator
 ```
 ```ruby
 validates :first_name, :surname, presence: true
@@ -563,7 +557,9 @@ This can be used in:
 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
+- `1+`, `2+`, etc: matches all positional arguments/array elements at or greater than the 0-indexed position
+- any Integer: matches the 0-indexed argument position/array position
+- negative values match positions counting from the end, e.g. `-1` is the last item
 - 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)
@@ -572,9 +568,44 @@ Each entry can be any of:
 
 Arrays are not necessary for single values
 
-## `has_value:`, `has_receiver:`
+## `any:`, `all:`
 
-filter [`arguments:`](#arguments), [`has_arguments:`](#has_arguments), and [`keywords:`](#keywords), by the argument/assigned/receiver value
+filter by `any:` or `all:` of the argument filters
+
+by default array values match any of the values,
+and hash values are match all of the values
+
+```yml
+dynamic:
+  name: my_method
+  has_receiver: MyReceiver
+  has_arguments:
+    - part_a
+    - part_b
+  calls: 0
+```
+
+will match the first argument of anything named my_method, with the receiver MyReceiver that has the keyword argument part_a and/or part_b.
+
+to avoid this default use `all:` and/or `any:`
+
+```yml
+dynamic:
+  any:
+    - name: my_method
+    - has_receiver: MyReceiver
+  all:
+    - has_argument: part_a
+    - has_argument: part_b
+  calls: 0
+```
+
+will match the first argument of anything named my_method or with the receiver MyReceiver, that have both the keyword arguments part_a and part_b
+
+
+## `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
@@ -585,11 +616,33 @@ Each entry can be one of
   - [`matches:`](#matches)
 - or have at least one of the following properties to match within an array or hash:
   - [`at`](#at)
-  - [`has_value`](#has_value_has_receiver)
+  - [`has_value`](#has_value)
 - or have the following property to match the value type
   - [`type`](#type)
 - or have the following property to match the receiver
-  - [`has_receiver`](#has_value_has_receiver)
+  - [`has_receiver`](#has_receiver)
+
+## `has_receiver:`
+
+filter [`dynamic:`](#dynamic), and [`keep:`](#keep), by the receiver presence or value
+
+Each entry can be one of
+- `true`, `false`, matches the presence of any receiver or not
+- 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 the name:
+  - [`has_prefix:`](#has_prefix)
+  - [`has_suffix:`](#has_suffix)
+  - [`matches:`](#matches)
+- or have at least one of the following properties to match the literal value or match within an array or hash:
+  - [`at`](#at)
+  - [`has_value`](#has_value)
+- or have the following property to match the value type
+  - [`type`](#type)
+- or have the following property to match the receiver of the receiver
+  - [`has_receiver`](#has_receiver)
+- or have the following property to match a literal true, false, or nil value:
+  - `literal: true`, or `literal: false`, or `literal: nil`
 
 ## `privacy:`
 
@@ -643,7 +696,7 @@ e.g.
 dynamic:
   - names: my_method
     calls:
-      argument: 2
+      argument: 1
       nested:
         argument: '*'
         nested:
@@ -680,6 +733,7 @@ The original method/constant/variable name will continue to be called/defined as
 This can be used in [`calls:`](#calls-defines) and [`defines:`](#calls-defines)
 
 ```yml
+dynamic:
 - name:
     has_prefix: be_
   calls:
@@ -698,6 +752,7 @@ Will supply a literal string value method/constant/variable name itself as the t
 This can be used in [`calls:`](#calls-defines) and [`defines:`](#calls-defines).
 
 ```yml
+dynamic:
 - name: perform_async
   calls:
     value: perform
@@ -720,8 +775,10 @@ Each entry can have a string that is an argumentless transform (e.g. capitalize)
 - [`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)
+- [`delete_before:`](#delete_before-delete_after-delete_before_last-delete_after_last)
+- [`delete_after:`](#delete_before-delete_after-delete_before_last-delete_after_last)
+- [`delete_before_last:`](#delete_before-delete_after-delete_before_last-delete_after_last)
+- [`delete_after_last:`](#delete_before-delete_after-delete_before_last-delete_after_last)
 - [`split:`](#split)
 - [`downcase`](#downcase-upcase-capitalize-swapcase) or `downcase: true`
 - [`upcase`](#downcase-upcase-capitalize-swapcase) or `upcase: true`
@@ -736,26 +793,43 @@ Each entry can have a string that is an argumentless transform (e.g. capitalize)
   - [`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`
+  - `transforms:`
 
 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
+dynamic:
 - name: attribute
-    defines:
-      - argument: 1
-        transforms:
-          - original # no transformation
-          - add_suffix: '?'
-          - add_suffix: '='
+  defines:
+    - argument: 0
+      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.
 
+```yml
+dynamic:
+- name: attr_accessor
+  defines:
+    - argument: '*'
+    - argument: '*'
+      transforms:
+        add_suffix: '='
+```
+```ruby
+attr_accessor :first_name
+```
+will count the calls to `first_name` and `first_name=` separately, with the understand it can be swapped to attr_reader or attr_writer if one or other isn't 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
+dynamic:
 - name: attr_writer
   defines:
     - argument: '*'
@@ -766,6 +840,21 @@ attr_writer :first_name, :surname
 ```
 will count as the definition of `first_name=`, and `surname=`
 
+Multiple transform arguments will be applied sequentially
+```yml
+dynamic:
+- name: has_many
+  calls:
+    - argument: 0
+      singularize: true
+      camelize: true
+      split: '::'
+```
+```ruby
+has_many :users
+```
+counts as a call to `User`
+
 ## `original`
 
 Can be used in the [`transforms:`](#transforms) list, if used in a hash `true` can be used as a placeholder value
@@ -795,11 +884,16 @@ if multiple transform results are possible (from multiple entries), then all res
 
 Arrays are not necessary for single values
 
-## `delete_before:`, `delete_after:`
+## `delete_before:`, `delete_after:`, `delete_before_last:`, `delete_after_last:`
 
 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
+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).
+
+- `delete_before:` will delete everything before and including the _first_ occurrence
+- `delete_after:` will delete everything after and including the _first_ occurrence
+- `delete_before_last:` will delete everything before and including the _last_ occurrence
+- `delete_after_last:` will delete everything after and including the _last_ occurrence
 
 if multiple transform results are possible (from multiple entries), then all results will be used.
 

data/docs/Custom-Precompilers.md

@@ -0,0 +1,44 @@
+# Custom Precompilers
+
+In addition to the built in precompilers, it's possible to add a custom precompiler
+
+It must be a class or module with a singleton method `precompile`. take a string of whatever code it likes, and return a string of valid ruby.
+
+```ruby
+require 'not_ruby' # require the gem that does the actual transformation
+
+module MyNotRubyPrecompiler
+  def self.precompile(not_ruby_content)
+    # not_ruby_content is a string of (hopefully) valid precompilable code
+    NotRuby::Parser.parse(not_ruby_content).to_ruby # output a string of valid ruby
+  end
+end
+```
+
+See the [build in precompilers](https://github.com/robotdana/leftovers/tree/main/lib/precompilers) for other examples.
+
+To configure the precompiler to be used by leftovers, add something similar to this to the `.leftovers.yml` file
+
+```yml
+  include_paths:
+    - 'lib/**/*.not_rb'
+  require: './path/to/my_not_ruby_precompiler'
+  precompile:
+    - paths: '*.not_rb'
+      format: { custom: MyNotRubyPrecompiler }
+```
+
+Ensure any necessary extension patterns are added to to [`include_paths:`](https://github.com/robotdana/leftovers/tree/main/docs/Configuration.md#include_paths) for those particular files you wish to check.
+
+Require the custom precompiler using [`require:`](https://github.com/robotdana/leftovers/tree/main/docs/Configuration.md#requires)
+
+Define which paths use the custom precompiler using [`precompile:`](https://github.com/robotdana/leftovers/tree/main/docs/Configuration.md#precompile),
+reference the name of the precompiler with `format: { custom: MyNotRubyPrecompiler }`
+
+If the `precompile` method raises any errors while precompiling, a warning will be printed to stderr and the file will be skipped
+
+To test the output of the precompiler you can use the `--view-compiled` flag with a list of paths or path patterns, like so:
+
+`bundle exec leftovers --view-compiled '*.not_rb'`
+
+