Proposal: DSL Plugin system for dynamic method-defining DSLs

从 lib/typeprof/core/ast/meta.rb 开始，并跟踪 Builtin.deploy 之后的 Service#new 流程。在评估提议的 Registry 和 Scope API 之前，追踪 MethodEntity 处理器和现有 meta 节点是如何表示的。要视为完成，需要就插件注册、安装和发现的实现范围达成一致，但该提案没有指明测试，也没有界定首次更改的范围。

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.