Proposal: DSL Plugin system for dynamic method-defining DSLs

Motivation

Ruby has many DSLs that define methods or mix in modules dynamically:

• define_method(:hello) { "hi" } adds hello to the receiver.
• Forwardable#def_delegator :@target, :foo generates a delegating method foo.
• Rails' belongs_to :user generates user, user=, build_user, create_user, etc.

TypeProf currently special-cases a few of these in hand-written meta nodes (lib/typeprof/core/ast/meta.rb), but most are not — Rails in particular.

This issue proposes a DSL Plugin system that extends TypeProf to handle these DSLs without touching the core. Third parties can ship support as external gems.

Design

A DSL Plugin fires when a method call resolves to a specific MethodEntity (for example, ActiveRecord::Associations::ClassMethods#belongs_to, not the bare name belongs_to). It then synthesises methods, modules, or mix-in relations as a side effect.

The Registry flow:

1. Each on "X#foo" declaration registers (cpath, mid, singleton) -> PluginClass in TypeProf::Dsl::Registry.
2. Service#new calls Registry.apply(genv) right after Builtin.deploy. For each entry, apply resolves the target MethodEntity and installs a handler into me.builtin.
3. When that method is later called during analysis, the handler builds a Scope and calls plugin.install(scope). It returns false so TypeProf still resolves the call's return type through RBS — the plugin only adds side effects.

Plugins read the AST and type-inference Vertices only — TypeProf never boots the user's app and never evaluates strings. Existing hand-written meta nodes (attr_reader, include, Struct.new, etc.) keep working as is; this plugin layer is a pure addition.

Plugin discovery

Plugins bundled with TypeProf core (lib/typeprof/dsl/ruby/*.rb) are auto-loaded on boot. External plugin gems are enabled via either of:

• CLI: typeprof --dsl typeprof-rails app.rb

• Config: a "dsl" key in typeprof.conf.jsonc:

  {
    "dsl": ["typeprof-rails"]
  }
  

The argument is a gem name. TypeProf requires the gem, which registers its plugins on load.

Plugin authoring

A plugin for Rails' belongs_to. It turns belongs_to :user in Post into def user: -> User? on Post::GeneratedAssociationMethods (a module included by Post).

module TypeProf
  module Dsl
    module ActiveRecord
      class Associations < TypeProf::Dsl::Base
        on "ActiveRecord::Associations::ClassMethods#belongs_to"

        def install(scope)
          # 1. Read the association name.
          name = scope.arg_symbol(0) or return

          # 2. Resolve the associated class by Rails' naming convention.
          klass = scope.resolve_const(default_name_for(name)) or return

          # 3. Locate or create the module to attach methods to.
          mod = scope.find_module("GeneratedAssociationMethods")
          unless mod
            mod = scope.create_module("GeneratedAssociationMethods")
            scope.owner.include_module(mod)
          end

          # 4. Define the method.
          mod.define_method(name, returns: scope.nilable(klass))
        end
      end
    end
  end
end

Triggers

Trigger	Fires when
on "X#foo"	Call resolves to instance method X#foo
on "X.foo"	Call resolves to singleton method X.foo
on_inherit "X"	A class is defined with X in its ancestor chain
on_include "X"	A module body executes include X
on_extend "X"	A module body executes extend X
on_prepend "X"	A module body executes prepend X

Inside an on "X#foo" pattern, # always denotes an instance method and . a singleton method on the definition side.

Scope API

Context

scope.mid          #: () -> Symbol           method name that triggered the plugin
scope.owner        #: () -> ScopeOwner       wrapper for the calling module
scope.has_block?   #: () -> bool             whether a block was passed

Reading arguments

Each helper extracts a single concrete literal from a positional or keyword argument. Returns nil if the argument is missing, isn't a literal, resolves to multiple values, or is untyped.

Only Symbol and true/false literal values are preserved on Vertices today. String / Integer literals flow as types only, so arg_string / kwarg_string are intentionally omitted.

scope.arg_symbol(idx)         #: (Integer) -> Symbol?
scope.arg_symbols_from(idx)   #: (Integer) -> Array[Symbol]?    collect a Symbol rest list

scope.kwarg_symbol(:key)      #: (Symbol) -> Symbol?
scope.kwarg_bool(:key)        #: (Symbol) -> bool?

Constructing types

scope.resolve_const("User")            #: (String) -> Type?         cref-walking lookup
scope.nilable(t)                       #: (Type) -> Type             t | nil
scope.array_of(t)                      #: (Type) -> Type             Array[t]
scope.hash_of(k, v)                    #: (Type, Type) -> Type       Hash[k, v]
scope.method_return_type(:"@x", :foo)  #: (Symbol, Symbol) -> Type   return type of @x.foo
scope.untyped                          #: () -> Type                 fallback

Resolving and creating modules

mod = scope.find_module("ClassMethods")     #: (String) -> ModuleEntity?    nil if missing
mod = scope.create_module("Generated")       #: (String) -> ModuleEntity     raises if exists

mod.include_module(other)                    #: (ModuleEntity) -> void       mix in (idempotent)
mod.extend_module(other)                     #: (ModuleEntity) -> void       extend (idempotent)

Defining methods on a module

mod.define_method(:foo, params: [...], returns: t)            #: (Symbol, params: Array[Type], returns: Type) -> void
mod.define_singleton_method(:bar, params: [...], returns: t)  #: (Symbol, params: Array[Type], returns: Type) -> void
mod.define_method_from_block(:baz)                            #: (Symbol) -> void                                       reuse the passed block as body
mod.define_ivar(:"@count", type: t)                           #: (Symbol, type: Type) -> void

Notes

• This issue describes the target shape. Details may change during implementation.
• The Scope API will land for core-bundled plugins first. The --dsl flag and typeprof.conf.jsonc "dsl" key follow once it stabilizes.

Start with lib/typeprof/core/ast/meta.rb and the Service#new flow after Builtin.deploy. Trace how MethodEntity handlers and existing meta nodes are represented before assessing the proposed Registry and Scope API. Done would require an agreed implementation scope for plugin registration, installation, and discovery, but the proposal does not name tests or a bounded first change.