candor 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: c57856ee0508cf6514f57073f0b68462e9cd8fc6f14c22bebe338dd3161558a3
+  data.tar.gz: f121e2ff9a2ca75a812f2e24991e10332ce5a81765f842c22572672928d3f32f
+SHA512:
+  metadata.gz: cdd277bdb4c503f974ead0e2be03da69361ceee33b586eefd187a761d03654b0084bc42a069d016578d174aa91cbf767f18a5885bdb4a7602a628b5c83f5d4af
+  data.tar.gz: e5275d7788db55cb88d258f391c45d10a4807b44616c332ace2f3a28a51a975357632a481d3974406147cd85a39a557145b377253033e23456a178eb5c2c8431

data/.yardopts

@@ -0,0 +1,6 @@
+--no-private
+--readme README.md
+lib/**/*.rb
+-
+CHANGELOG.md
+LICENSE.txt

data/CHANGELOG.md

@@ -0,0 +1,16 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html) and to [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/).
+
+## [0.1.0] - 2026-07-10
+
+### Added
+- `Candor.define(target, name, aliases:, via:, parameters:, body:)` — fabricates a real method whose arity, `parameters` kinds and `source_location` are the body's. Bodies may be a block, a `Proc`, a `Method` or an `UnboundMethod`; a `#call` object or any body with a `nil` `source_location` (a curried proc, a C-defined method) raises `TypeError`. With `via:` every call routes to that interceptor, which reaches the body through `Candor.body_name`; without it the wrapper forwards straight to the body. A wrong-arity call or an unknown keyword raises `ArgumentError` at the wrapper, before the interceptor or the body runs. An unpassed optional is dropped from the forwarded arguments, so the body applies its own default.
+- `Candor::Signature` — the low-level compiler, public on its own: a parameter shape, a call-site name and a `source_location` in, a dispatch lambda out. Renders off a parameter's kind, never its name, so `end:`, `it`, `_1`, `**nil` and destructuring parameters all wrap at full fidelity. Both call-site names are validated against a strict method-name pattern, and a malformed `parameters` shape raises `ArgumentError` rather than a `SyntaxError` from inside `eval` — including a shape whose entries are each legal but whose combination Ruby's parser rejects, which is compiled before the target is mutated so a rejected fabrication cannot destroy the method it was replacing.
+- Dispatch allocates nothing for shapes up to `Candor::Signature::KEYWORD_BRANCH_LIMIT` (2) optional keywords; beyond it, exactly one Hash per call. Past the limit a body's keyrest *is* that Hash, so a `**kw` in the signature costs only the capture and re-splat Ruby charges any wrapper. Exact from Ruby 3.4: on earlier Rubies the VM charges a `define_method`-created method for arguments crossing into it, and both the wrapper and the body are ones. A call carrying no keyword allocates nothing on every supported Ruby.
+- Fabrication is thread-safe through one global `Monitor`; call-time dispatch takes no lock and never needs one. Re-fabricating a name overwrites the wrapper and the body in place, so it is warning-free under `ruby -w`, leaves no orphaned body, and a concurrent caller sees the old method or the new one, never a `NoMethodError`. A frozen target, an unbindable `Method`/`UnboundMethod` body, a name under the reserved `Candor::BODY_PREFIX`, an uncallable `via:` and a malformed `parameters:` all raise before the target is touched.
+- `sig/` ships RBS for the public API: `Candor.define`, `Candor.body_name`, `BODY_PREFIX`, and `Candor::Signature` with `KINDS` and `KEYWORD_BRANCH_LIMIT`. Everything else is `private_constant`, which RBS cannot express and therefore does not declare.
+
+[0.1.0]: https://github.com/svyatov/candor/releases/tag/v0.1.0

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Leonid Svyatov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,196 @@
+# Candor
+
+[![Gem Version](https://img.shields.io/gem/v/candor)](https://rubygems.org/gems/candor)
+[![CI](https://github.com/svyatov/candor/actions/workflows/main.yml/badge.svg)](https://github.com/svyatov/candor/actions/workflows/main.yml)
+[![codecov](https://codecov.io/gh/svyatov/candor/branch/main/graph/badge.svg)](https://codecov.io/gh/svyatov/candor)
+
+**Ruby's missing `functools.wraps`.** Turn a block or a callable into a real method that reports the
+*body's* arity, the *body's* `parameters` and the *body's* `source_location` — and rejects a bad call
+before anything of yours runs.
+
+Zero runtime dependencies. Ruby >= 3.2.
+
+```ruby
+Candor.define(Greeter, :greet) { |name, greeting: "hi"| "#{greeting}, #{name}" }
+
+Greeter.instance_method(:greet).arity            # => -2
+Greeter.instance_method(:greet).parameters       # => [[:req, :__p0], [:key, :greeting]]
+Greeter.instance_method(:greet).source_location  # => ["app/greeter.rb", 3]  ← the block, not the gem
+
+Greeter.new.greet                                # => ArgumentError: wrong number of arguments (given 0, expected 1)
+Greeter.new.greet("bob", grating: "yo")          # => ArgumentError: unknown keyword: :grating
+```
+
+## The problem
+
+Ruby gives you no way to hand a generated wrapper the signature of the callable it wraps.
+`define_method` accepts only a `Proc`, a `Method` or an `UnboundMethod`, so a wrapper's arity has to
+come from an object that already has it — and the only source of such an object is a literal parameter
+list, hand-typed or generated as text.
+
+So libraries that wrap user-supplied callables retreat to `|*args, **kwargs, &block|`. The results are
+right; the reflection lies. `arity` is `-1`, `parameters` reads `[[:rest], [:keyrest], [:block]]`, a
+wrong-arity call blows up one frame too deep — inside the wrapper, where the library's own error
+handling can swallow it — and every call allocates an Array and a Hash.
+
+Candor generates the parameter list as source and `eval`s it, once, at definition time. There is no
+degraded fallback: every shape Ruby can express wraps at full fidelity, including `end:`, `it`, `_1`,
+`**nil`, and destructuring parameters.
+
+## Install
+
+```ruby
+gem "candor"
+```
+
+## Use
+
+### Direct forward
+
+With no interceptor, the wrapper forwards straight to the body. An unpassed optional is **dropped** from
+the forwarded arguments, so the body applies its own default.
+
+```ruby
+Candor.define(Formatter, :pad) { |string, width = 8| string.ljust(width) }
+
+Formatter.new.pad("x")     # => "x       "   the body's own default
+Formatter.new.pad("x", 3)  # => "x  "
+```
+
+### Through an interceptor
+
+`via:` names a method on the target, resolved per call. Every call routes to it and to it alone. It
+receives the canonical name and the arguments exactly as passed, and reaches the body through
+`Candor.body_name`, so it can also choose *not* to run it — memoize, instrument, short-circuit.
+
+```ruby
+class Memo
+  def initialize = @cache = {}
+
+  private
+
+  def __call(name, ...)
+    @cache[name] ||= send(Candor.body_name(name), ...)
+  end
+end
+
+Candor.define(Memo, :catalog, parameters: [], via: :__call) { Catalog.build }
+```
+
+A wrong-arity call raises at the wrapper, before `__call` is ever entered — so an interceptor that
+rescues broadly never sees a caller's mistake as a body's failure. An alias left behind by an *earlier*
+fabrication is the exception: it keeps the wrapper it was built with, so its gate is that fabrication's
+signature and not the current body's. See [Re-fabrication](#the-contract).
+
+### Aliases and shape overrides
+
+```ruby
+Candor.define(App, :configuration, aliases: %i[config c], via: :__call) { |scope| ... }
+Candor.define(App, :catalog, parameters: []) { |page = 1| ... }  # advertise zero parameters
+```
+
+`aliases:` share one dispatch, and the interceptor always receives the *canonical* name.
+`parameters:` overrides what the wrapper advertises; it is **not** validated against the body, so a
+mismatch surfaces as the body's own `ArgumentError`.
+
+### The compiler on its own
+
+`Candor::Signature` is public for consumers that install methods themselves:
+
+```ruby
+dispatch = Candor::Signature.compile(parameters, name: :greet, via: :__call, source_location: loc)
+klass.define_method(:greet, &dispatch)
+```
+
+## The contract
+
+**Body kinds.** A block, a `Proc`, a `Method` or an `UnboundMethod` — the three things `define_method`
+takes. A `#call` object is rejected. So is any body whose `source_location` is `nil`: a curried proc, a
+`Symbol#to_proc`, a C-defined method. Ruby exposes no `curried?` predicate, and a nil `source_location`
+is the one reliable discriminator — without it the honest-`source_location` guarantee cannot be kept, and
+that guarantee is the product. Inside a block body, `self` is the receiver.
+
+**Reserved prefix.** Compiled bodies are private methods named `#{Candor::BODY_PREFIX}#{name}`.
+Fabricating a name that starts with the prefix raises `ArgumentError`.
+
+**Allocation.** Dispatch allocates **nothing** for every shape up to two optional keywords. Ruby fills
+optional positionals left to right, so `n` of them have `n + 1` states, enumerated as call sites rather
+than accumulated into an Array. Optional keywords are independent, so `n` of them would cost `2**n` call
+sites; past `Candor::Signature::KEYWORD_BRANCH_LIMIT` (2) they go through one Hash instead, and
+dispatch allocates exactly one Hash per call. That shape — three or more optional keywords — is the one
+case where candor is slower than the variadic wrapper it replaces. It is measured, and accepted.
+
+Those counts are what the *wrapper* adds. A body that declares a **keyrest** (`**kw`) costs Ruby one Hash
+to capture it and one to re-splat it into the body, on any wrapper you could write by hand; candor adds
+none of its own, because past the branch limit the captured keyrest *is* the Hash the keywords accumulate
+into.
+
+Exactly as stated from **Ruby 3.4**. Below that, Ruby itself charges a `define_method`-created method for
+arguments crossing into it, and both the wrapper and the body are ones: on 3.3 the hashed path costs one
+Hash more, and on 3.2 a keyword-carrying call costs one Hash per hop. Nothing in the gem can reach that,
+and no call that carries no keyword ever allocates, on any supported Ruby.
+
+**Thread safety.** Fabrication takes one global `Monitor`; concurrent `Candor.define` calls
+serialize. Call-time dispatch takes no lock at all, and never needs one: re-fabrication replaces a
+method in place rather than removing and reinstalling it, so a caller racing a `Candor.define` gets
+the old method or the new one, never a `NoMethodError`.
+
+**Failing fast.** A frozen target raises `FrozenError`, an `UnboundMethod` whose owner is not an
+ancestor of the target raises `TypeError`, and a malformed `parameters:` or an uncallable `via:` raises
+`ArgumentError` — all *before* the target is touched. A rejected fabrication leaves the target exactly
+as it was. A hand-written `parameters:` never passed Ruby's parser, so it is compiled before the first
+mutation: a shape whose *combination* is illegal — two rests, a duplicate keyword — is an `ArgumentError`
+too. Nothing ever surfaces as a `SyntaxError` from inside `eval`, which a `rescue` would not catch.
+
+**A Ruby 3.4 wrinkle.** On 3.4 alone, a body written with the implicit `it` parameter receives its
+arguments packed into an Array when it is reached through `(name, ...)` forwarding, `send`, or a splat —
+the shape an interceptor is usually written in. Candor's own generated call sites name every
+argument, so direct-forward mode is unaffected; fixed in Ruby 4.0, and `_1` and named parameters never
+had it.
+
+**Re-fabrication.** Redefining a name overwrites candor's own prior wrapper and body in place, so a
+second `Candor.define` is warning-free under `ruby -w` and orphans nothing. It rewrites only the
+names passed to the *current* call: an alias installed by an earlier fabrication stays installed and
+rebinds to the replacement body while still advertising its original signature. Last write wins. A
+hand-written method of the same name is replaced cleanly; an inherited one is shadowed, not removed.
+
+## Benchmarks
+
+`bundle exec rake bench`, on ruby 4.0.5 (arm64-darwin23). Nanoseconds per call, lower is better; the
+optional-argument rows carry a few percent of noise.
+
+| shape | candor | hand-written wrapper | bare method | variadic wrapper |
+|---|---|---|---|---|
+| no arguments | 52 ns · 0 alloc | 47 ns · 0 | 27 ns · 0 | 122 ns · 2 |
+| required + optional, omitted | 107 ns · 0 alloc | 82 ns · 0 | 43 ns · 0 | 140 ns · 2 |
+| required + optional, passed | 81 ns · 0 alloc | 63 ns · 0 | 36 ns · 0 | 149 ns · 2 |
+| two optional keywords | 112 ns · 0 alloc | 79 ns · 0 | 46 ns · 0 | 170 ns · 2 |
+| three optional keywords | 251 ns · 1 alloc | 99 ns · 0 | 46 ns · 0 | 185 ns · 2 |
+
+- **hand-written wrapper** is the ceiling: a real `def` with the same signature forwarding to the same
+  private body, with the defaults hard-coded — what you would write by hand if you knew the shape *and*
+  the default expressions. Candor is within ~10–40% of it, and allocates the same nothing.
+- **bare method** is a single `def` doing the work inline. It is roughly twice as fast as any wrapper,
+  because it is one method call rather than two. That is the price of wrapping at all, not of candor.
+- **variadic wrapper** is the `|*args, **kwargs, &block|` retreat: slower than candor on every shape
+  below the keyword branch limit, faster on the hashed one, and dishonest about its signature everywhere.
+
+Definition time is ~40 µs per fabricated method — one `eval` — against ~1.3 µs for a bare
+`define_method`. It runs once, at boot.
+
+## What it is not
+
+Candor routes calls. It does not rescue, memoize, delegate or instrument; it is the method-fabrication
+layer those features stand on. It does not recover an optional's default expression — that is
+[permanently closed upstream](https://bugs.ruby-lang.org/issues/8629), and dropping the unpassed optional
+so the body defaults is the semantics that replaces it. Fabricated methods are not Ractor-shareable, and
+the gem needs `eval`, so it does not run on eval-restricted platforms.
+
+## Contributing
+
+Bug reports and pull requests are welcome on [GitHub](https://github.com/svyatov/candor). See
+[CONTRIBUTING.md](CONTRIBUTING.md).
+
+## License
+
+MIT. See [LICENSE.txt](LICENSE.txt).

data/candor.gemspec

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require_relative "lib/candor/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "candor"
+  spec.version = Candor::VERSION
+  spec.authors = ["Leonid Svyatov"]
+  spec.email = ["leonid@svyatov.com"]
+
+  spec.summary = "Turn a block or a callable into a real method with an honest signature."
+  spec.description = "Ruby's missing functools.wraps. Candor fabricates real methods from blocks and " \
+                     "callables: same arity, same parameters, source_location pointing at your code, and " \
+                     "allocation-free dispatch. Zero runtime dependencies."
+  spec.homepage = "https://github.com/svyatov/candor"
+  spec.license = "MIT"
+
+  spec.required_ruby_version = ">= 3.2.0"
+
+  spec.require_paths = ["lib"]
+  spec.files = Dir["lib/**/*.rb"] + Dir["sig/**/*"] +
+               %w[.yardopts CHANGELOG.md LICENSE.txt README.md candor.gemspec]
+
+  spec.metadata["rubygems_mfa_required"] = "true"
+  spec.metadata["documentation_uri"] = "https://rubydoc.info/gems/candor"
+  spec.metadata["source_code_uri"] = "https://github.com/svyatov/candor"
+  spec.metadata["changelog_uri"] = "https://github.com/svyatov/candor/blob/main/CHANGELOG.md"
+  spec.metadata["bug_tracker_uri"] = "https://github.com/svyatov/candor/issues"
+end

data/lib/candor/definer.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+module Candor
+  # Fabricates a real method from a block or a callable: compile the body strictly, read its true
+  # parameter shape, render a signature-identical wrapper, install it.
+  #
+  # The pipeline is an order, not a sequence of conveniences. Every check runs before the first
+  # mutation, so a rejected fabrication leaves the target exactly as it was — a frozen target, an
+  # unbindable +Method+, a name under the reserved prefix and a malformed shape all raise before the
+  # prior wrapper is replaced. The parameter shape is then read from the *compiled* method, never from
+  # the Proc, which reports every positional as +:opt+ and would silently destroy arity strictness.
+  #
+  # @api private
+  class Definer
+    # The only bodies +define_method+ accepts. A +#call+ object is not one of them, and converting it
+    # would forge a +source_location+ nobody wrote.
+    BODY_KINDS = [Proc, Method, UnboundMethod].freeze
+
+    # @param target [Module] the module the method is installed onto
+    # @param name [Symbol] the canonical name
+    # @param aliases [Array<Symbol>] further names sharing the one dispatch
+    # @param via [Symbol, nil] an interceptor method on +target+, resolved per call
+    # @param parameters [Array<Array>, nil] an explicit shape, overriding the body's
+    # @param body [Proc, Method, UnboundMethod]
+    def initialize(target, name, aliases:, via:, parameters:, body:)
+      @target = target
+      @canonical = name.to_sym
+      @names = [@canonical, *aliases.map(&:to_sym)].uniq
+      @via = via
+      @parameters = parameters
+      @body = body
+      @body_name = Candor.body_name(@canonical)
+    end
+
+    # @return [Symbol] the canonical name
+    def call
+      validate!
+      # An overridden shape never passed Ruby's parser, so it is compiled before the first mutation: a
+      # combination {Signature.parameters!} cannot see — two rests, a duplicate keyword — must not fail once
+      # the body is already installed. A shape read from the compiled body always renders.
+      dispatch = compile(@parameters) if @parameters
+      # Definition is a boot-time operation, so one global lock is the whole answer to concurrency;
+      # the dispatch it installs takes no lock at all.
+      MONITOR.synchronize do
+        install_body
+        install(dispatch || compile(@target.instance_method(@body_name).parameters))
+      end
+      @canonical
+    end
+
+    private
+
+    # @return [void]
+    # @raise [TypeError, ArgumentError, FrozenError]
+    def validate!
+      raise TypeError, "target must be a Module, got #{@target.inspect}" unless @target.is_a?(Module)
+
+      validate_body!
+      validate_names!
+      # Both call-site names are interpolated into `eval`'d source. Without `via` the body's own name is
+      # the call site, so the canonical name has to survive being one.
+      Signature.method_name!(@via || @body_name)
+      Signature.parameters!(@parameters) if @parameters
+      raise FrozenError.new("can't fabricate a method on frozen #{@target}", receiver: @target) if @target.frozen?
+    end
+
+    # +source_location+ is the one reliable discriminator: Ruby exposes no +curried?+ predicate, and a
+    # curried proc, a symbol-to-proc and a C-defined method all report +nil+. R5 cannot be honoured for
+    # any of them, and honouring R5 is the product.
+    #
+    # @return [void]
+    # @raise [TypeError]
+    def validate_body!
+      raise TypeError, body_error unless BODY_KINDS.any? { |kind| @body.is_a?(kind) }
+      raise TypeError, body_error if @body.source_location.nil?
+      return unless @body.is_a?(Method) || @body.is_a?(UnboundMethod)
+      # `define_method` would raise this itself — after the prior wrapper was already removed.
+      raise TypeError, "#{@body.owner} is not an ancestor of #{@target}" unless @target <= @body.owner
+    end
+
+    # @return [void]
+    # @raise [ArgumentError]
+    def validate_names!
+      offender = @names.find { |name| name.to_s.start_with?(BODY_PREFIX) }
+      return unless offender
+
+      raise ArgumentError, "#{offender.inspect} starts with the reserved prefix #{BODY_PREFIX.inspect}"
+    end
+
+    # @return [String]
+    def body_error
+      "body must be a block, a Proc, a Method or an UnboundMethod with a source_location, " \
+        "got #{@body.inspect}; curried procs, `#call` objects and C-defined methods have none"
+    end
+
+    # +define_method+ replaces a method in place, so a re-fabrication is never observable as a missing
+    # one. Calling +remove_method+ first — the obvious way to reinstall a name — leaves it undefined for
+    # as long as the install takes, and a concurrent caller sees +NoMethodError+. Removal only ever bought
+    # silence from the +-w+ redefinition warning, so buy that here instead.
+    #
+    # +$VERBOSE+ is process-global, and that is the ceiling: {MONITOR} serializes fabricators, so two of
+    # them cannot interleave these assignments, but a thread warning about something else while one holds
+    # the lock loses that warning. An install is microseconds, and this runs at boot.
+    #
+    # @return [void]
+    def silently
+      verbose = $VERBOSE
+      $VERBOSE = nil
+      yield
+    ensure
+      $VERBOSE = verbose
+    end
+
+    # An inherited method of the same name is shadowed by the install, never removed.
+    #
+    # @return [void]
+    def install_body
+      silently { @target.define_method(@body_name, @body) }
+      @target.send(:private, @body_name)
+    end
+
+    # @param shape [Array<Array>]
+    # @return [Proc] the dispatch lambda
+    # @raise [ArgumentError] if the shape does not render to legal source
+    def compile(shape)
+      Signature.compile(shape, name: @via ? @canonical : @body_name, via: @via,
+                               source_location: @body.source_location)
+    end
+
+    # @param dispatch [Proc]
+    # @return [void]
+    def install(dispatch) = silently { @names.each { |name| @target.define_method(name, &dispatch) } }
+  end
+end

data/lib/candor/signature.rb

@@ -0,0 +1,332 @@
+# frozen_string_literal: true
+
+module Candor
+  # Compiles a method's +parameters+ into a dispatch lambda carrying the same parameter kinds, in the
+  # same order, and therefore the same +arity+.
+  #
+  # Rendering switches on a parameter's *kind*, never its name. +Method#parameters+ reports names that
+  # cannot be used as parameters (+:_1+), names that are reserved words (+:end+), and entries with no
+  # name at all — +[[:req]]+, for both +it+ and a destructuring parameter. A renderer that echoed names
+  # would die on most real shapes, and on +it+ it would fail *silently*, emitting arity 0. So every
+  # positional, rest, keyrest and block parameter gets a generated name; only keyword names survive,
+  # because a keyword name is the calling convention.
+  #
+  # Those surviving names are the only user input in the generated source, and Ruby lets a parameter
+  # shadow anything the source would otherwise reach. So the lambda closes over nothing it could lose:
+  # the canonical name is a Symbol literal, +binding()+ is called with parentheses a local cannot
+  # shadow, and every generated local is prefixed with a run of underscores no keyword name starts
+  # with. Only the sentinel survives as a free variable, and it is created by the rendered source
+  # itself, under that same collision-free prefix.
+  #
+  # The lambda is rendered on one line, so +eval+'s line forges its +source_location+ exactly.
+  #
+  # The call site it forwards to is one of two shapes. With +via+ it is +via(:name, args…)+, an
+  # interceptor that receives the canonical name; without, it is +name(args…)+, calling the body
+  # directly. Either way the target is a method name interpolated into +eval+'d source, so
+  # {method_name!} gates it first.
+  #
+  #   Candor::Signature.compile([%i[req a]], name: :greet, via: :__call, source_location: loc)
+  #   # => ->(__p0) { __call(:greet, __p0) }
+  class Signature
+    # Reserved words that are legal keyword parameter names but illegal as a bare reference:
+    # +__k[:end] = end+ is a +SyntaxError+.
+    RESERVED_WORDS = %w[
+      __ENCODING__ __FILE__ __LINE__ alias and begin break case class def do else elsif end ensure
+      false for if in module next nil not or redo rescue retry return self super then true undef
+      unless until when while yield
+    ].freeze
+
+    # Kinds whose reported name is the calling convention and must be preserved.
+    NAMED_KINDS = %i[keyreq key].freeze
+
+    # Kinds that may have to be dropped from the forwarded arguments, so the body applies its own default.
+    OPTIONAL_KINDS = %i[opt key].freeze
+
+    # The generated local's name, after the collision-free prefix and before the parameter's index.
+    SUFFIXES = { req: "p", opt: "p", rest: "r", keyrest: "kr", block: "b" }.freeze
+
+    # How many optional keywords still dispatch through call sites rather than a Hash. Each one doubles
+    # the sites, so four is where a shape nobody writes stops paying for one everybody does.
+    KEYWORD_BRANCH_LIMIT = 2
+
+    # The lambda's parameter declaration, per kind: the name, then the sentinel. Filled with `sub`, not
+    # `%`: +:nokey+ takes neither, and `format` warns about the unused arguments under +-w+.
+    DECLARATIONS = {
+      req: "%s", opt: "%s = %s", rest: "*%s", keyreq: "%s:", key: "%s: %s",
+      keyrest: "**%s", nokey: "**nil", block: "&%s"
+    }.freeze
+
+    # Every kind +Method#parameters+ can emit, and the only ones {render} accepts.
+    KINDS = DECLARATIONS.keys.freeze
+
+    # A name the generated source may call with parentheses. Operators, spaces and everything else a
+    # +Symbol+ can hold are rejected before they reach +eval+.
+    METHOD_NAME = /\A[a-zA-Z_][a-zA-Z0-9_]*[?!]?\z/
+
+    # A name the generated source may declare as a keyword parameter. Reserved words qualify — the
+    # source reads them back through +binding()+ — but a numbered parameter does not.
+    KEYWORD_NAME = /\A[a-zA-Z_][a-zA-Z0-9_]*\z/
+
+    # Names Ruby reserves for the numbered block parameters; +->(_1: 1) {}+ is a +SyntaxError+.
+    NUMBERED_PARAMETERS = (1..9).map { |i| "_#{i}" }.freeze
+
+    # How the source is spelled, and what the two name gates happen to be spelled as. A consumer builds
+    # against {compile}, {method_name!} and {parameters!} — which raise — not against the patterns and
+    # tables they are written in terms of. Only {KINDS} and {KEYWORD_BRANCH_LIMIT} name something a
+    # caller has to know to use the compiler, so only those two stay public.
+    private_constant :RESERVED_WORDS, :NAMED_KINDS, :OPTIONAL_KINDS, :SUFFIXES, :DECLARATIONS,
+                     :METHOD_NAME, :KEYWORD_NAME, :NUMBERED_PARAMETERS
+
+    class << self
+      # +eval+'s file and line forge the lambda's — and therefore the compiled method's —
+      # +source_location+ onto the body the caller supplied.
+      #
+      # @param parameters [Array<Array>] a *compiled* method's +parameters+; a Proc's would report every
+      #   positional as +:opt+ and silently destroy arity strictness
+      # @param name [Symbol] the method to call, or — with +via+ — the canonical name handed to it
+      # @param source_location [Array(String, Integer)] the body's
+      # @param via [Symbol, nil] an interceptor method taking +(name, ...)+; omit to call +name+ directly
+      # @return [Proc] a lambda taking the body's parameter kinds and forwarding to the call site
+      # @raise [ArgumentError] if the call site's name or the parameter shape is malformed
+      def compile(parameters, name:, source_location:, via: nil)
+        eval(render(parameters, name: name, via: via), binding, *source_location) # rubocop:disable Security/Eval
+      rescue SyntaxError => e
+        # {parameters!} sees one entry at a time; only the parser sees the combination — two rests, a
+        # duplicate keyword, a block before a positional. A +SyntaxError+ is a +ScriptError+, which a
+        # consumer's +rescue+ never catches.
+        raise ArgumentError, "malformed parameters: #{parameters.inspect} (#{e.message.lines.first.strip})"
+      end
+
+      # @param parameters [Array<Array>]
+      # @param name [Symbol]
+      # @param via [Symbol, nil]
+      # @return [String] single-line source for a lambda forwarding to the call site
+      # @raise [ArgumentError] if the call site's name or the parameter shape is malformed
+      def render(parameters, name:, via: nil) = new(parameters, name, via).source
+
+      # The call site is interpolated into +eval+'d source, so its name is a trust boundary rather than
+      # a typo check.
+      #
+      # @param name [Symbol, String]
+      # @return [Symbol] the name
+      # @raise [ArgumentError] unless the name can be called with parentheses
+      def method_name!(name)
+        string = name.to_s
+        # +:class+ is callable on a receiver and useless here: the generated source calls the site bare,
+        # and a bare +class(…)+ is a +SyntaxError+. Say that, rather than "not a callable method name".
+        if RESERVED_WORDS.include?(string)
+          raise ArgumentError, "#{name.inspect} is a reserved word: the generated source would call it bare"
+        end
+        raise ArgumentError, "not a callable method name: #{name.inspect}" unless METHOD_NAME.match?(string)
+
+        string.to_sym
+      end
+
+      # A parameter shape reaching {render} from a consumer's override never passed Ruby's parser, so
+      # every kind and every keyword name is checked here rather than discovered as a +SyntaxError+.
+      #
+      # @param parameters [Array<Array>]
+      # @return [Array<Array>] the shape
+      # @raise [ArgumentError] unless every entry is a known kind, with a usable name where one is required
+      def parameters!(parameters)
+        raise ArgumentError, "malformed parameters: #{parameters.inspect}" unless parameters.is_a?(Array)
+
+        # +index+, not +find+: a +nil+ entry is malformed, and +find+ would hand back the same +nil+ it
+        # returns when every entry is fine. The caller passed the Array; naming the offender saves a bisect.
+        index = parameters.index { |entry| !valid_entry?(entry) }
+        raise ArgumentError, "malformed parameters: entry #{index} is #{parameters[index].inspect}" if index
+
+        parameters
+      end
+
+      private
+
+      # @param entry [Object]
+      # @return [Boolean]
+      def valid_entry?(entry)
+        return false unless entry.is_a?(Array) && KINDS.include?(entry.first)
+
+        case entry.size
+        when 1 then !NAMED_KINDS.include?(entry.first)
+        when 2 then valid_name?(entry.first, entry[1])
+        else false
+        end
+      end
+
+      # A keyword name is the one piece of the shape the source carries verbatim; every other name is
+      # replaced by a generated one and so may be anything, or nothing.
+      #
+      # @param kind [Symbol]
+      # @param name [Object]
+      # @return [Boolean]
+      def valid_name?(kind, name)
+        return false unless name.is_a?(Symbol)
+        return true unless NAMED_KINDS.include?(kind)
+
+        string = name.to_s
+        KEYWORD_NAME.match?(string) && !NUMBERED_PARAMETERS.include?(string)
+      end
+    end
+
+    # @param parameters [Array<Array>]
+    # @param name [Symbol]
+    # @param via [Symbol, nil]
+    def initialize(parameters, name, via = nil)
+      self.class.parameters!(parameters)
+      @target = self.class.method_name!(via || name)
+      # With an interceptor the canonical name leads the argument list, as a literal rather than a free
+      # variable a keyword could capture.
+      @literal = via ? name.to_sym.inspect : nil
+      @prefix = collision_free_prefix(parameters)
+      @unset = "#{@prefix}u"
+      @hash = "#{@prefix}k"
+      @entries = entries(parameters)
+      @optionals = @entries.select { |entry| OPTIONAL_KINDS.include?(entry.first) }
+    end
+
+    # The sentinel marking an unpassed optional is a local, not a constant: +Module#const_get+ pierces
+    # +private_constant+, so a caller could obtain the sentinel and pass it as an argument, silently
+    # defeating an optional's default.
+    #
+    # @return [String]
+    def source = "#{@unset} = ::Object.new.freeze; ->(#{declarations}) { #{dispatch} }"
+
+    private
+
+    # @param parameters [Array<Array>]
+    # @return [Array<Array(Symbol, String)>] each kind paired with the local the lambda gives it
+    def entries(parameters)
+      parameters.each_with_index.map { |(kind, given), index| [kind, local(kind, given, index)] }
+    end
+
+    # No keyword name starts with the returned prefix, so no generated local can be shadowed by one.
+    #
+    # @param parameters [Array<Array>]
+    # @return [String]
+    def collision_free_prefix(parameters)
+      keywords = parameters.filter_map { |kind, given| given.to_s if NAMED_KINDS.include?(kind) }
+      prefix = "__"
+      prefix += "_" while keywords.any? { |keyword| keyword.start_with?(prefix) }
+      prefix
+    end
+
+    # @param kind [Symbol]
+    # @param given [Symbol, nil]
+    # @param index [Integer]
+    # @return [String]
+    def local(kind, given, index) = NAMED_KINDS.include?(kind) ? given.to_s : "#{@prefix}#{SUFFIXES[kind]}#{index}"
+
+    # @return [String] the lambda's parameter list
+    def declarations
+      @entries.map { |kind, name| DECLARATIONS[kind].sub("%s", name).sub("%s", @unset) }.join(", ")
+    end
+
+    # An optional's default expression is unrecoverable from +parameters+, so an unpassed optional is
+    # dropped from the forwarded arguments and the body applies its own default. Which ones were passed
+    # is a runtime fact, and {#branch} enumerates it as call sites rather than an Array: nothing is
+    # allocated, and every kind around the optionals forwards straight through — a rest as `*r`, a
+    # keyrest as `**kw`.
+    #
+    # Optional *keywords* are independently passed, so enumerating them costs +2**n+ call sites rather
+    # than +n + 1+. Past {KEYWORD_BRANCH_LIMIT} of them the source would balloon, so they go through a
+    # Hash instead and the branching sees only the positionals.
+    #
+    # @return [String] the lambda's body
+    def dispatch
+      keywords = @optionals.select { |entry| entry.first == :key }
+      hash = keywords.size > KEYWORD_BRANCH_LIMIT
+      statements = hash ? keyword_setup : []
+      statements << branch(hash ? @optionals - keywords : @optionals, [], hash)
+      statements.join("; ")
+    end
+
+    # Ruby fills optional positionals left to right, so an unpassed one guarantees every optional
+    # positional after it went unpassed too. The states are a chain of +n + 1+ call sites, not the
+    # +2**n+ a subset would need.
+    #
+    # @param optionals [Array<Array(Symbol, String)>] those still to be decided
+    # @param dropped [Array<Array(Symbol, String)>] those already known unpassed
+    # @param hash [Boolean]
+    # @return [String] a call site, or a ternary choosing between two of them
+    def branch(optionals, dropped, hash)
+      return call(@entries - dropped, hash) if optionals.empty?
+
+      first, *rest = optionals
+      trailing = first.first == :opt ? rest.select { |entry| entry.first == :opt } : []
+      unpassed = branch(rest - trailing, dropped + [first] + trailing, hash)
+      "#{@unset}.equal?(#{value(first)}) ? #{unpassed} : #{branch(rest, dropped, hash)}"
+    end
+
+    # The target takes parentheses and, usually, an argument — neither of which a local of the same name
+    # can shadow.
+    #
+    # @param entries [Array<Array(Symbol, String)>]
+    # @param hash [Boolean]
+    # @return [String]
+    def call(entries, hash) = "#{@target}(#{[*@literal, *forward(entries, hash)].join(", ")})"
+
+    # @param entry [Array(Symbol, String)]
+    # @return [String] source reading that parameter's value
+    def value(entry) = entry.first == :key ? reference(entry.last) : entry.last
+
+    # A keyrest is the accumulator rather than a source to merge in: +**+ capture already allocated a Hash the
+    # lambda alone owns, and Ruby routes a declared keyword to its own parameter, never into the keyrest — so
+    # seeding from it and assigning after is what +{}+ plus +update+ was, one Hash cheaper.
+    #
+    # @return [Array<String>]
+    def keyword_setup
+      keyrest = @entries.find { |kind, _name| kind == :keyrest }
+      @entries.filter_map do |kind, name|
+        case kind
+        when :keyreq then "#{@hash}[:#{name}] = #{reference(name)}"
+        when :key then "#{@hash}[:#{name}] = #{reference(name)} unless #{@unset}.equal?(#{reference(name)})"
+        end
+      end.unshift("#{@hash} = #{keyrest ? keyrest.last : "{}"}")
+    end
+
+    # @param entries [Array<Array(Symbol, String)>]
+    # @param hash [Boolean]
+    # @return [Array<String>] the forwarded arguments
+    def forward(entries, hash)
+      args = positional_args(entries)
+      args.concat(hash ? ["**#{@hash}"] : keyword_args(entries))
+      args.concat(block_arg(entries))
+    end
+
+    # An +:opt+ appears here only on a call site that passes it: {#dispatch} drops it from the entries
+    # of the call site that does not.
+    #
+    # @param entries [Array<Array(Symbol, String)>]
+    # @return [Array<String>] in declaration order, so a rest keeps its place among the required
+    def positional_args(entries)
+      entries.filter_map do |kind, name|
+        case kind
+        when :req, :opt then name
+        when :rest then "*#{name}"
+        end
+      end
+    end
+
+    # @param entries [Array<Array(Symbol, String)>]
+    # @return [Array<String>]
+    def keyword_args(entries)
+      entries.filter_map do |kind, name|
+        case kind
+        when :keyreq, :key then "#{name}: #{reference(name)}"
+        when :keyrest then "**#{name}"
+        end
+      end
+    end
+
+    # @param entries [Array<Array(Symbol, String)>]
+    # @return [Array<String>] at most one element
+    def block_arg(entries) = entries.filter_map { |kind, name| "&#{name}" if kind == :block }
+
+    # +binding()+, never bare +binding+: a keyword named +binding+ is a local, and a local shadows the
+    # very method this reaches for.
+    #
+    # @param name [String] a keyword parameter's name
+    # @return [String] source reading that keyword's value
+    def reference(name) = RESERVED_WORDS.include?(name) ? "binding().local_variable_get(:#{name})" : name
+  end
+end

data/lib/candor/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module Candor
+  # The gem version.
+  VERSION = "0.1.0"
+end

data/lib/candor.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require "monitor"
+
+require "candor/version"
+require "candor/signature"
+require "candor/definer"
+
+# Turns a block or a callable into a real method with an honest signature: the body's arity, the body's
+# +parameters+, the body's +source_location+, and allocation-free dispatch.
+#
+#   Candor.define(MyClass, :greet) { |name, greeting: "hi"| "#{greeting}, #{name}" }
+#   MyClass.instance_method(:greet).parameters # => [[:req, :__p0], [:key, :greeting]]
+#
+# A wrong-arity call and an unknown keyword raise +ArgumentError+ at the fabricated method, before
+# anything of yours runs.
+module Candor
+  # Prefix of the private methods holding compiled bodies. Fabricated names may not start with it, and
+  # an interceptor reaches its body through {Candor.body_name}.
+  BODY_PREFIX = "__candor_body_"
+
+  # Fabrication is a boot-time operation, so one global lock serializes it; nothing is taken at call time.
+  MONITOR = Monitor.new
+  private_constant :MONITOR
+
+  class << self
+    # Defines a real method on +target+ whose signature is the body's.
+    #
+    # With +via+, every call routes to that method on the target as +via(canonical_name, ...)+, and it
+    # alone decides whether to run the body — which it reaches under {body_name}. Without +via+, the
+    # wrapper forwards straight to the body.
+    #
+    # An unpassed optional is dropped from the forwarded arguments, so the body applies its own default.
+    #
+    #   Candor.define(App.singleton_class, :fetch, aliases: [:get], via: :__call) { |id, ttl: 60| ... }
+    #
+    # @param target [Module] the module — often a +singleton_class+ — to install onto
+    # @param name [Symbol] the canonical name, passed to the interceptor and used for the body method
+    # @param aliases [Array<Symbol>] further names sharing the one dispatch and the one canonical name
+    # @param via [Symbol, nil] an interceptor method on +target+, resolved per call
+    # @param parameters [Array<Array>, nil] an explicit shape advertised instead of the body's; not
+    #   validated against the body, so a mismatch surfaces as the body's own +ArgumentError+
+    # @param body [Proc, Method, UnboundMethod, nil] the body, when it is not given as a block
+    # @yield the body, when it is not given as +body+; +self+ inside it is the receiver
+    # @return [Symbol] the canonical name
+    # @raise [TypeError] if +target+ is not a Module, or the body is neither a block, a Proc, a Method
+    #   nor an UnboundMethod, or its +source_location+ is +nil+, or its owner is not an ancestor of
+    #   +target+
+    # @raise [ArgumentError] if a name starts with {BODY_PREFIX}, or +via+ is not a callable method
+    #   name, or +parameters+ is malformed
+    # @raise [FrozenError] if +target+ is frozen
+    def define(target, name, aliases: [], via: nil, parameters: nil, body: nil, &block)
+      Definer.new(target, name, aliases: aliases, via: via, parameters: parameters, body: body || block).call
+    end
+
+    # The private method holding a fabricated method's body. An interceptor calls it with +send+.
+    #
+    # @param name [Symbol] a canonical name
+    # @return [Symbol]
+    def body_name(name) = :"#{BODY_PREFIX}#{name}"
+  end
+
+  private_constant :Definer
+end

data/sig/candor/signature.rbs

@@ -0,0 +1,22 @@
+module Candor
+  # Compiles a method's `parameters` into a dispatch lambda with the same parameter kinds, and
+  # therefore the same `arity`. Switches on the kind, never the name.
+  class Signature
+    # Every kind `Method#parameters` can emit, and the only ones `render` accepts.
+    KINDS: Array[Symbol]
+
+    # How many optional keywords still dispatch through call sites rather than a Hash.
+    KEYWORD_BRANCH_LIMIT: Integer
+
+    # One entry of `Method#parameters`: a kind, and a name the body may not have given.
+    type parameter = [ Symbol ] | [ Symbol, Symbol ]
+
+    def self.compile: (Array[parameter] parameters, name: Symbol, source_location: [ String, Integer ], ?via: Symbol?) -> Proc
+    def self.render: (Array[parameter] parameters, name: Symbol, ?via: Symbol?) -> String
+    def self.method_name!: (Symbol | String name) -> Symbol
+    def self.parameters!: (untyped parameters) -> Array[parameter]
+
+    def initialize: (Array[parameter] parameters, Symbol name, ?Symbol? via) -> void
+    def source: () -> String
+  end
+end

data/sig/candor.rbs

@@ -0,0 +1,28 @@
+# Turns a block or a callable into a real method with an honest signature.
+#
+# Fabricated methods are compiled at runtime, so RBS cannot see them. Declare the ones you rely on in
+# your own `sig/`.
+#
+# These files declare the public API and nothing else. `Candor::Definer` and the compiler's internal
+# constants are `private_constant` in Ruby, and RBS has no syntax for that — declaring them here would
+# advertise a surface that raises NameError on use.
+module Candor
+  VERSION: String
+
+  # Prefix of the private methods holding compiled bodies.
+  BODY_PREFIX: String
+
+  # A body `define_method` accepts, with a `source_location` to forge onto the wrapper.
+  type body = Proc | Method | UnboundMethod
+
+  def self.define: (
+    Module target,
+    Symbol name,
+    ?aliases: Array[Symbol],
+    ?via: Symbol?,
+    ?parameters: Array[Signature::parameter]?,
+    ?body: body?
+  ) ?{ (?) -> untyped } -> Symbol
+
+  def self.body_name: (Symbol name) -> Symbol
+end

metadata

@@ -0,0 +1,58 @@
+--- !ruby/object:Gem::Specification
+name: candor
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Leonid Svyatov
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: 'Ruby''s missing functools.wraps. Candor fabricates real methods from
+  blocks and callables: same arity, same parameters, source_location pointing at your
+  code, and allocation-free dispatch. Zero runtime dependencies.'
+email:
+- leonid@svyatov.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".yardopts"
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- candor.gemspec
+- lib/candor.rb
+- lib/candor/definer.rb
+- lib/candor/signature.rb
+- lib/candor/version.rb
+- sig/candor.rbs
+- sig/candor/signature.rbs
+homepage: https://github.com/svyatov/candor
+licenses:
+- MIT
+metadata:
+  rubygems_mfa_required: 'true'
+  documentation_uri: https://rubydoc.info/gems/candor
+  source_code_uri: https://github.com/svyatov/candor
+  changelog_uri: https://github.com/svyatov/candor/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/svyatov/candor/issues
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.12
+specification_version: 4
+summary: Turn a block or a callable into a real method with an honest signature.
+test_files: []