Best practices for debugging custom compilers

I am writing a custom compiler to cover some methods dynamically generated in a config/initializers file within a Rails application. I am troubleshooting why the following compiler located at sorbet/tapioca/compilers/settings.rb is not running with some puts calls:

# frozen_string_literal: true
# typed: strict

module Tapioca
  module Dsl
    module Compilers
      class Settings < Tapioca::Dsl::Compiler
        extend T::Sig

        ConstantType = type_member { { fixed: T.all(Module, T::Class[T.anything]) } }

        class << self
          extend T::Sig

          sig { override.returns(T::Enumerable[T::Class[T.anything]]) }
          def gather_constants
            puts "Testing gather_constants"
          end
        end

        sig { override.void }
        def decorate
          puts "Testing decorate"
        end
      end
    end
  end
end

The list_compilers output shows that the compiler is recognized and enabled:

Loaded DSL compiler classes:
  Tapioca::Dsl::Compilers::ActionControllerHelpers             disabled
  Tapioca::Dsl::Compilers::ActionMailer                        disabled
  Tapioca::Dsl::Compilers::ActionText                          disabled
  Tapioca::Dsl::Compilers::ActiveJob                           disabled
  Tapioca::Dsl::Compilers::ActiveModelAttributes               disabled
  Tapioca::Dsl::Compilers::ActiveModelSecurePassword           disabled
  Tapioca::Dsl::Compilers::ActiveModelValidationsConfirmation  disabled
  Tapioca::Dsl::Compilers::ActiveRecordAssociations            disabled
  Tapioca::Dsl::Compilers::ActiveRecordColumns                 disabled
  Tapioca::Dsl::Compilers::ActiveRecordDelegatedTypes          disabled
  Tapioca::Dsl::Compilers::ActiveRecordEnum                    disabled
  Tapioca::Dsl::Compilers::ActiveRecordFixtures                disabled
  Tapioca::Dsl::Compilers::ActiveRecordRelations               disabled
  Tapioca::Dsl::Compilers::ActiveRecordScope                   disabled
  Tapioca::Dsl::Compilers::ActiveRecordSecureToken             disabled
  Tapioca::Dsl::Compilers::ActiveRecordStore                   disabled
  Tapioca::Dsl::Compilers::ActiveStorage                       disabled
  Tapioca::Dsl::Compilers::ActiveSupportConcern                disabled
  Tapioca::Dsl::Compilers::ActiveSupportCurrentAttributes      disabled
  Tapioca::Dsl::Compilers::MixedInClassAttributes              disabled
  Tapioca::Dsl::Compilers::Settings                            enabled
  Tapioca::Dsl::Compilers::SidekiqWorker                       disabled
  Tapioca::Dsl::Compilers::UrlHelpers                          disabled

Tapioca config:

dsl:
  list_compilers: true
  workers: 1
  only:
  -  Settings

I am having trouble figuring out why the methods defined in my compiler are not invoked. What are the recommended ways to troubleshoot a custom compiler?

list_compilers option doesn't actually run DSL compilation, it invokes a different code path:

tapioca/lib/tapioca/cli.rb

Line 163 in fff1131

Commands::DslCompilerList.new(**command_args)

You should see your puts statements if you stop supplying that option. Looking at this now this is confusing so I'm happy with it if you want to open a PR to change the conditional so that supplying list_compilers doesn't prevent the actual compilation to run.

I think it would be a viable practice if you fork this project, write your custom compiler and a test file there. Debug your compiler by executing the test file.