is_this_used 0.1.3 → 0.1.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 30573cf11b6fec940b4b6f03bc541fa36af22d3188e29e82a5ed7e13233a8ce2
-  data.tar.gz: f6656c296f1edcfe87e9929e1225e0f2b558aa2c92f87d6e5369d705fb70cb9e
+  metadata.gz: 777036cad1719ed293fa2d1807dde0268776149b3d88ffe70e9d1b80a0666eb7
+  data.tar.gz: c837438870b48369ebbd6378f61329c9685225382c3289df5b25b62ab0e1f926
 SHA512:
-  metadata.gz: 51feda93ddd637a4f7f18ea285ff2cc989cb9457c2c3e6cbad1f0b7a0cf6f140e087f3191e25c9bd4b3e326346c12fdb6476cfbce67bf14543bd6042afd7548c
-  data.tar.gz: e4d69c95977e97d6aafd7aa323af7eb40df7735d969f273a4c122777184c30bfe56799a90ddcffc1036294e2d6831571c9b57df449e0d471fb48b058fcee96d7
+  metadata.gz: e1d08ac4789a1208b60cb63f242b26dcf4f79a07cfec9d79bcf9c33d8a30dc20b3b8dcecba5437cee963ea6234d139babb114ceecf406ff8425f50d6207d7022
+  data.tar.gz: 6b4c8f9f86fa53873c02ee650327aa2c824408c92560e9b952b44d3f59c40b62346b72420f742e23a576fbaaad30d0d9d1fd9ddebd822c5dbdd1910e0e8fc385

data/Dockerfile

@@ -0,0 +1,24 @@
+FROM ruby:2.7.5-slim-bullseye
+
+WORKDIR /app
+
+RUN apt-get update -qq \
+  && apt-get install --no-install-recommends -y \
+    less \
+    nano \
+    mariadb-client-10.5 \
+    libmariadb-dev-compat \
+    libmariadb-dev \
+    build-essential \
+    git \
+    shared-mime-info
+
+ARG BUNDLER_VERSION=2.1.4
+
+ENV BUNDLE_PATH /bundle
+ENV GEM_HOME /bundle
+
+RUN gem update --system \
+    && gem install bundler -v ${BUNDLER_VERSION}
+
+CMD /bin/bash

data/README.md

@@ -59,7 +59,6 @@ You're unsure if the `some_old_method` method is actually being used. You only n
 Here's an example:
 
 ```ruby
-
 class SomeOldClass
   include IsThisUsed::CruftTracker
 
@@ -76,7 +75,7 @@ in the `potential_crufts` table that looks like this:
 
 | id  | owner_name   | method_name     | method_type     | invocations | created_at          | updated_at          |
 | --- | ------------ | --------------- | --------------- | ----------- | ------------------- | ------------------- |
-| 1   | SomeOldClass | some_old_method | instance_method | 0           | 2022-01-21 14:07:48 | 2022-01-21 14:07:48 | 
+| 1   | SomeOldClass | some_old_method | instance_method | 0           | 2022-01-21 14:07:48 | 2022-01-21 14:07:48 |
 
 This is easily accessed using the `IsThisUsed::PotentialCruft` model class.
 
@@ -89,7 +88,7 @@ The fields are:
   constants, `IsThisUsed::CruftTracker::INSTANCE_METHOD` and `IsThisUsed::CruftTracker::CLASS_METHOD`.
 - `invocations` - The number of times the method has been invoked.
 - `created_at` - The date/time we started tracking the method.
-- `updated_at` - The last time this record was updated.
+- `updated_at` - The last time this record was updated. IE: the last time the tracked method was invoked.
 
 Looking at this, we can see that the `some_old_method` method has never been invoked. This is nice because it means that
 you can track uses of methods without changing their behavior. A similar record is created for every method you annotate
@@ -98,10 +97,12 @@ with `is_this_used?`.
 Assuming your production application eagerly loads classes, you should always have records for potentially crufty
 methods, even if the class itself is never explicitly used.
 
-So, having annotate the method, you can check this table after a while. If you see that there have been zero invocations
+So, having annotated the method, you can check this table after a while. If you see that there have been zero invocations,
 you have a reasonably good hint that the method may not actually be used. Of course, you should consider that there are
 some processes that are not run frequently at all, so this gem isn't a panacea. Think before you delete!
 
+### Tracking Stacks
+
 In the case that a method _is_ actually invoked, the `invocations` value is incremented and a record is created in
 the `potential_cruft_stacks` table for each unique invocation stacktrace. This can be used to determine which methods
 and blocks are responsible for calling the method and are themselves being used. This is the structure of
@@ -113,11 +114,11 @@ the `potential_cruft_stacks` table:
 - `stack_hash` - This is an MD5 hash of the stack trace for the method's invocation. This is indexed for speedy lookups
   of stacks.
 - `stack` - This is a JSON field that stores an array of hashes (more on this in a sec) that is the stack trace for the
-  method invocation. You can potentially use this to figure out what other methods and blocks involved in calling the
+  method invocation. You can potentially use this to figure out what other methods and blocks are involved in calling the
   not-actually-crufty method.
 - `occurrences` - This is the number of times the method has been invoked with exactly the same stack.
 - `created_at` - The date/time we first saw this stack.
-- `updated_at` - The last time this saw this stack.
+- `updated_at` - The last time we saw this stack.
 
 As a note, if any of the files referenced in the stack are edited sufficiently to change line numbers, the stack will be
 different and a new record will be created.
@@ -146,7 +147,58 @@ The `label` and `base_label` fields come from Ruby's `Thread::Backtrace::Locatio
 difference is, as the docs simply say this about `base_label`: "Usually same as label, without decoration". 🤷 Anyhow,
 it's there if you need it.
 
-The `IsThisUsed::PotentialCruftStack` model is handy for accessing this data.
+### Tracking Arguments
+
+In addition to tracking stacks, you can track details about arguments provided to tracked methods. For example, let's say you have the following method:
+
+```ruby
+def some_old_method(arg1, arg2)
+  # do things
+end
+```
+
+Let's say that, for some reason you want to know what arguments are provided to this method. You could add `track_arguments: true` to your `is_this_used?` invocation like so:
+
+```ruby
+is_this_used? :some_old_method, track_arguments: true
+```
+
+Now, as `some_old_method` is invoked, a record will be created in `potential_cruft_arguments` for each unique set of arguments. Similar to `potential_cruft_stacks`, the record contains a hash of the JSON-serialized arguments, the JSON-serialized arguments, and the number of occurrences of the particular combination of arguments.
+
+Tracking all arguments might be a really bad idea. Let's say your method actually gets invoked a lot and receives lots of different combinations of arguments, you could be writing a lot of potentially useless information into the `potential_cruft_arguments` table. For this reason arguments are not tracked by default.
+
+Instead of tracking all arguments, you can also provide a lambda to `track_arguments` to track only specific details about arguments. The lambda will receive an array of arguments that were provided to the tracked method. Whatever is returned from the lambda is what is tracked in the `potential_cruft_arguments` table. This might be useful in a situation where you have a method that receives an options hash. Maybe you want to know what keys are in that options hash. You could track the unique combination of keys like this:
+
+```ruby
+def ye_olde_method(some_argument, options_hash)
+  # do things
+end
+
+is_this_used? :some_old_method, track_arguments: ->(args) { args.last.keys.sort }
+```
+
+As `ye_olde_method` is invoked is_this_used will track the unique combination of keys in the `options_hash`. Let's say it's invoked as follows:
+
+
+```ruby
+ye_olde_method("Fred", favorite_color: "blue", locality: 'Antartica')
+ye_olde_method("Zelda", locality: 'Hyrule', favorite_color: "green")
+ye_olde_method("Korg", color: 'Rebecca Purple', locality: 'Sakaar')
+ye_olde_method("Liz", status: :favorite_person)
+```
+
+The above would result in the following records in `potential_cruft_arguments` (ignoring the id, potential cruft reference, and timestamps):
+
+| arguments_hash                   | arguments                      | occurrences |
+| -------------------------------- | ------------------------------ | ----------- |
+| d5d98f761a14b1845a74ce3f1a298c98 | ["favorite_color", "locality"] | 2           |
+| 1619ec6af47253461e87ebf1923a8a83 | ["color", "locality"]          | 1           |
+| 88c8205498de97d4ef06b249006bb68b | ["status"]                     | 1           |
+
+
+
+
+## Models
 
 ### `IsThisUsed::PotentialCruft`
 
@@ -158,6 +210,10 @@ invocations of the method, if any.
 This is a model representing potential cruft stacks. Its `potential_cruft` method provides an association back to the
 owning potentially-crufty method.
 
+### `IsThisUsed::PotentialCruftArgument`
+
+This model represents information about arguments provided to a specific `potential_cruft` method. It is conditionally populated when the `track_arguments` method is provided with either true or a lambda.
+
 ## Dependencies
 
 * ActiveRecord - ActiveRecord is used to persist information about potentially crufty methods. This gem should happily
@@ -208,6 +264,37 @@ bundle exec appraisal rails-6.0 rake
 
 bundle exec appraisal rails-6.1 rake
 
+## Developing with Docker
+
+A Docker / docker-compose environment is available to simplify development. Assuming you already have Docker installed, you can spin up a MySQL and open a bash console on a container with Ruby installed like this:
+
+```bash
+docker-compose run --rm ruby bash
+```
+
+The MySQL server has its port exposed as 13306. Note that the first time you spin up these containers it may take a moment for mysql to successfully spin up.
+
+The gem's source is mapped to `/app`, which is also the working directory.
+
+Once you have a bash console open, you can install dependencies with:
+
+```bash
+bundle install
+bundle exec appraisal install
+```
+
+You can copy the provided MySQL DB config file to be the one to use in the test app:
+
+```bash
+cp spec/dummy_app/config/database.mysql.yml spec/dummy_app/config/database.yml
+```
+
+And now you should be able to run tests against whichever version of Rails you wish, like so:
+
+```bash
+bundle exec appraisal rails-6.1 rake
+```
+
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/dhughes/is_this_used.

data/Rakefile

@@ -1,6 +1,5 @@
-require "bundler/gem_tasks"
+# require "bundler/gem_tasks"
 require "rspec/core/rake_task"
-
 RSpec::Core::RakeTask.new(:spec)
 
 task :default => :spec

data/docker-compose.yml

@@ -0,0 +1,39 @@
+version: '3'
+services:
+  mysql:
+    image: mysql:8
+    container_name: square-mysql
+    command: --default-authentication-plugin=mysql_native_password
+    volumes:
+      - db_data:/var/lib/mysql
+    environment:
+      MYSQL_ROOT_PASSWORD: dev
+      MYSQL_DATABASE: is_this_used_test
+    ports:
+      - "13306:3306"
+
+  ruby:
+    build:
+      context: .
+      dockerfile: ./Dockerfile
+    depends_on:
+      - mysql
+    working_dir: /app
+    volumes:
+      - .:/app
+      - bundle:/bundle
+      - ./wait-for-it.sh:/usr/sbin/wait-for-it.sh:ro
+    environment:
+      - IS_THIS_USED_DATABASE=is_this_used_test
+      - IS_THIS_USED_DB_USER=root
+      - IS_THIS_USED_DB_HOST=mysql
+      - IS_THIS_USED_DB_PASSWORD=dev
+    links:
+      - mysql
+    tty: true
+    stdin_open: true
+
+volumes:
+  db_data:
+  bundle:
+

data/gemfiles/rails_5.2.gemfile.lock

@@ -1,49 +1,49 @@
 PATH
   remote: ..
   specs:
-    is_this_used (0.1.2)
+    is_this_used (0.1.5)
       activerecord (>= 5.2)
 
 GEM
   remote: https://rubygems.org/
   specs:
-    actioncable (5.2.4.6)
-      actionpack (= 5.2.4.6)
+    actioncable (5.2.6.2)
+      actionpack (= 5.2.6.2)
       nio4r (~> 2.0)
       websocket-driver (>= 0.6.1)
-    actionmailer (5.2.4.6)
-      actionpack (= 5.2.4.6)
-      actionview (= 5.2.4.6)
-      activejob (= 5.2.4.6)
+    actionmailer (5.2.6.2)
+      actionpack (= 5.2.6.2)
+      actionview (= 5.2.6.2)
+      activejob (= 5.2.6.2)
       mail (~> 2.5, >= 2.5.4)
       rails-dom-testing (~> 2.0)
-    actionpack (5.2.4.6)
-      actionview (= 5.2.4.6)
-      activesupport (= 5.2.4.6)
+    actionpack (5.2.6.2)
+      actionview (= 5.2.6.2)
+      activesupport (= 5.2.6.2)
       rack (~> 2.0, >= 2.0.8)
       rack-test (>= 0.6.3)
       rails-dom-testing (~> 2.0)
       rails-html-sanitizer (~> 1.0, >= 1.0.2)
-    actionview (5.2.4.6)
-      activesupport (= 5.2.4.6)
+    actionview (5.2.6.2)
+      activesupport (= 5.2.6.2)
       builder (~> 3.1)
       erubi (~> 1.4)
       rails-dom-testing (~> 2.0)
       rails-html-sanitizer (~> 1.0, >= 1.0.3)
-    activejob (5.2.4.6)
-      activesupport (= 5.2.4.6)
+    activejob (5.2.6.2)
+      activesupport (= 5.2.6.2)
       globalid (>= 0.3.6)
-    activemodel (5.2.4.6)
-      activesupport (= 5.2.4.6)
-    activerecord (5.2.4.6)
-      activemodel (= 5.2.4.6)
-      activesupport (= 5.2.4.6)
+    activemodel (5.2.6.2)
+      activesupport (= 5.2.6.2)
+    activerecord (5.2.6.2)
+      activemodel (= 5.2.6.2)
+      activesupport (= 5.2.6.2)
       arel (>= 9.0)
-    activestorage (5.2.4.6)
-      actionpack (= 5.2.4.6)
-      activerecord (= 5.2.4.6)
-      marcel (~> 0.3.1)
-    activesupport (5.2.4.6)
+    activestorage (5.2.6.2)
+      actionpack (= 5.2.6.2)
+      activerecord (= 5.2.6.2)
+      marcel (~> 1.0.0)
+    activesupport (5.2.6.2)
       concurrent-ruby (~> 1.0, >= 1.0.2)
       i18n (>= 0.7, < 2)
       minitest (~> 5.1)
@@ -66,27 +66,25 @@ GEM
       railties (>= 3.0.0)
     globalid (1.0.0)
       activesupport (>= 5.0)
-    i18n (1.8.11)
+    i18n (1.10.0)
       concurrent-ruby (~> 1.0)
-    loofah (2.13.0)
+    loofah (2.14.0)
       crass (~> 1.0.2)
       nokogiri (>= 1.5.9)
     mail (2.7.1)
       mini_mime (>= 0.1.1)
-    marcel (0.3.3)
-      mimemagic (~> 0.3.2)
+    marcel (1.0.2)
     method_source (1.0.0)
-    mimemagic (0.3.10)
-      nokogiri (~> 1)
-      rake
     mini_mime (1.1.2)
+    mini_portile2 (2.8.0)
     minitest (5.15.0)
     mysql2 (0.5.3)
     nio4r (2.5.8)
-    nokogiri (1.13.1-x86_64-darwin)
+    nokogiri (1.13.3)
+      mini_portile2 (~> 2.8.0)
       racc (~> 1.4)
     parallel (1.21.0)
-    parser (3.1.0.0)
+    parser (3.1.1.0)
       ast (~> 2.4.1)
     pry (0.13.1)
       coderay (~> 1.1)
@@ -98,47 +96,47 @@ GEM
     rack (2.2.3)
     rack-test (1.1.0)
       rack (>= 1.0, < 3)
-    rails (5.2.4.6)
-      actioncable (= 5.2.4.6)
-      actionmailer (= 5.2.4.6)
-      actionpack (= 5.2.4.6)
-      actionview (= 5.2.4.6)
-      activejob (= 5.2.4.6)
-      activemodel (= 5.2.4.6)
-      activerecord (= 5.2.4.6)
-      activestorage (= 5.2.4.6)
-      activesupport (= 5.2.4.6)
+    rails (5.2.6.2)
+      actioncable (= 5.2.6.2)
+      actionmailer (= 5.2.6.2)
+      actionpack (= 5.2.6.2)
+      actionview (= 5.2.6.2)
+      activejob (= 5.2.6.2)
+      activemodel (= 5.2.6.2)
+      activerecord (= 5.2.6.2)
+      activestorage (= 5.2.6.2)
+      activesupport (= 5.2.6.2)
       bundler (>= 1.3.0)
-      railties (= 5.2.4.6)
+      railties (= 5.2.6.2)
       sprockets-rails (>= 2.0.0)
     rails-dom-testing (2.0.3)
       activesupport (>= 4.2.0)
       nokogiri (>= 1.6)
     rails-html-sanitizer (1.4.2)
       loofah (~> 2.3)
-    railties (5.2.4.6)
-      actionpack (= 5.2.4.6)
-      activesupport (= 5.2.4.6)
+    railties (5.2.6.2)
+      actionpack (= 5.2.6.2)
+      activesupport (= 5.2.6.2)
       method_source
       rake (>= 0.8.7)
       thor (>= 0.19.0, < 2.0)
     rainbow (3.1.1)
     rake (10.5.0)
-    regexp_parser (2.2.0)
+    regexp_parser (2.2.1)
     rexml (3.2.5)
-    rspec (3.10.0)
-      rspec-core (~> 3.10.0)
-      rspec-expectations (~> 3.10.0)
-      rspec-mocks (~> 3.10.0)
-    rspec-core (3.10.1)
-      rspec-support (~> 3.10.0)
-    rspec-expectations (3.10.2)
+    rspec (3.11.0)
+      rspec-core (~> 3.11.0)
+      rspec-expectations (~> 3.11.0)
+      rspec-mocks (~> 3.11.0)
+    rspec-core (3.11.0)
+      rspec-support (~> 3.11.0)
+    rspec-expectations (3.11.0)
       diff-lcs (>= 1.2.0, < 2.0)
-      rspec-support (~> 3.10.0)
-    rspec-mocks (3.10.2)
+      rspec-support (~> 3.11.0)
+    rspec-mocks (3.11.0)
       diff-lcs (>= 1.2.0, < 2.0)
-      rspec-support (~> 3.10.0)
-    rspec-rails (5.0.2)
+      rspec-support (~> 3.11.0)
+    rspec-rails (5.0.3)
       actionpack (>= 5.2)
       activesupport (>= 5.2)
       railties (>= 5.2)
@@ -146,7 +144,7 @@ GEM
       rspec-expectations (~> 3.10)
       rspec-mocks (~> 3.10)
       rspec-support (~> 3.10)
-    rspec-support (3.10.3)
+    rspec-support (3.11.0)
     rubocop (1.22.3)
       parallel (~> 1.10)
       parser (>= 3.0.0.0)
@@ -156,8 +154,8 @@ GEM
       rubocop-ast (>= 1.12.0, < 2.0)
       ruby-progressbar (~> 1.7)
       unicode-display_width (>= 1.4.0, < 3.0)
-    rubocop-ast (1.15.1)
-      parser (>= 3.0.1.1)
+    rubocop-ast (1.16.0)
+      parser (>= 3.1.1.0)
     rubocop-rails (2.12.4)
       activesupport (>= 4.2.0)
       rack (>= 1.1)
@@ -167,7 +165,7 @@ GEM
     rubocop-rspec (2.5.0)
       rubocop (~> 1.19)
     ruby-progressbar (1.11.0)
-    sprockets (4.0.2)
+    sprockets (4.0.3)
       concurrent-ruby (~> 1.0)
       rack (> 1, < 3)
     sprockets-rails (3.4.2)
@@ -188,7 +186,7 @@ PLATFORMS
 
 DEPENDENCIES
   appraisal (~> 2.4.1)
-  bundler (~> 1.17)
+  bundler (~> 2.1)
   generator_spec (~> 0.9.4)
   is_this_used!
   mysql2 (~> 0.5.3)
@@ -203,4 +201,4 @@ DEPENDENCIES
   rubocop-rspec (~> 2.5.0)
 
 BUNDLED WITH
-   1.17.2
+   2.1.4