candor 0.1.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c57856ee0508cf6514f57073f0b68462e9cd8fc6f14c22bebe338dd3161558a3
-  data.tar.gz: f121e2ff9a2ca75a812f2e24991e10332ce5a81765f842c22572672928d3f32f
+  metadata.gz: 4f762b3abe3c9761a038e98d5070ac771bada1d677bd84695e34c7ec623091fc
+  data.tar.gz: b2ae106ed934e85f4c55b2a28d070bbb57a1218f0f27e40c6620c23acd6a922d
 SHA512:
-  metadata.gz: cdd277bdb4c503f974ead0e2be03da69361ceee33b586eefd187a761d03654b0084bc42a069d016578d174aa91cbf767f18a5885bdb4a7602a628b5c83f5d4af
-  data.tar.gz: e5275d7788db55cb88d258f391c45d10a4807b44616c332ace2f3a28a51a975357632a481d3974406147cd85a39a557145b377253033e23456a178eb5c2c8431
+  metadata.gz: 60b025033f7e8b208b74eb110b252814c9cabd5272b0c1681fd1d0421e2f48fe3511334c8378a86c4d489ade82ced0a5648b7e48d7da66552cc7bf277682e3f1
+  data.tar.gz: a2984ef22907efc8134743c2e2da12ea0b8bb1c381f6df792a1385a778957c9288a19f4fcfd509095cfd75eff572384d1eff2fbe06ba93d90780196ae7164d17

data/CHANGELOG.md

@@ -4,13 +4,30 @@ 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/).
 
+## [Unreleased]
+
+## [0.2.1] - 2026-07-31
+
+No change to the library.
+
+The gem now ships from a tagged CI run through RubyGems trusted publishing. This release and every later one carries a sigstore attestation. The GitHub release attaches the built gem beside a checksum manifest with build provenance.
+
+## [0.2.0] - 2026-07-10
+
+### Added
+- `Candor.define(..., source_location:)`, the location every fabricated name reports, overriding the body's. A caller whose body is a proc it generated on the user's behalf can now point the wrapper at what the user actually wrote, rather than at the generator. It is also the only way to fabricate from a body carrying no location of its own (a curried proc, a symbol-to-proc, a C-defined method), which is the caller assuming responsibility for the honesty the gem otherwise derives. A `#call` object is not one of them and no `source_location:` rescues it: that refusal is about the kind. A `source_location:` that is not a `[String, Integer]` pair, or whose line is one `eval` will not take, raises `ArgumentError` before the target is touched.
+- `Candor::Signature.source_location!`, the location gate, public beside `method_name!` and `parameters!`. `Signature.compile` calls it, so a consumer installing dispatch itself can no longer forge a location `eval` refuses, nor one it silently misreads. Its line must fit `eval`'s: a C `int`.
+
 ## [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.
+- `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`. That includes 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.
 
+[Unreleased]: https://github.com/svyatov/candor/compare/v0.2.1...HEAD
+[0.2.1]: https://github.com/svyatov/candor/releases/tag/v0.2.1
+[0.2.0]: https://github.com/svyatov/candor/releases/tag/v0.2.0
 [0.1.0]: https://github.com/svyatov/candor/releases/tag/v0.1.0

data/README.md

@@ -1,21 +1,33 @@
-# Candor
+# Candor [![Gem Version](https://img.shields.io/gem/v/candor)](https://rubygems.org/gems/candor) [![Codecov](https://img.shields.io/codecov/c/github/svyatov/candor)](https://app.codecov.io/gh/svyatov/candor) [![CI](https://github.com/svyatov/candor/actions/workflows/main.yml/badge.svg?branch=main)](https://github.com/svyatov/candor/actions?query=workflow%3ACI)
 
-[![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)
+Turn a block or a callable into a real Ruby method that reports the body's own arity, parameters and
+source location.
 
-**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 or newer and nothing else. Tested on 3.2, 3.3, 3.4, 4.0 and
+  `ruby-head`.
+- **Every shape Ruby can express.** All eight parameter kinds wrap at full fidelity, including `end:`,
+  `it`, `_1`, `**nil` and destructuring. There is no degraded fallback.
+- **Faster than the `|*args, **kwargs|` wrapper it replaces.** 52 ns and zero allocations per call
+  against 122 ns and two, on the no-argument shape. Full table below.
+- **RBS signatures shipped.** `sig/` declares the public API, and the test suite pins it against the
+  code in both directions.
 
-Zero runtime dependencies. Ruby >= 3.2.
+## Install
+
+```sh
+bundle add candor
+```
+
+Or drop `gem "candor"` into your Gemfile, or run `gem install candor` without Bundler.
+
+Then, anywhere in your code:
 
 ```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.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
@@ -25,24 +37,18 @@ Greeter.new.greet("bob", grating: "yo")          # => ArgumentError: unknown key
 
 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
+come from an object that already has it. 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.
+right; the reflection lies. `arity` is `-1`, `parameters` reads `[[:rest], [:keyrest], [:block]]`, and a
+wrong-arity call blows up one frame too deep: inside the wrapper, where the library's own error
+handling can swallow it. 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
@@ -61,7 +67,7 @@ Formatter.new.pad("x", 3)  # => "x  "
 
 `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.
+`Candor.body_name`, so it can also choose *not* to run it: memoize, instrument, short-circuit.
 
 ```ruby
 class Memo
@@ -77,7 +83,7 @@ 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
+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).
@@ -102,13 +108,28 @@ dispatch = Candor::Signature.compile(parameters, name: :greet, via: :__call, sou
 klass.define_method(:greet, &dispatch)
 ```
 
+`compile` gates all three of its inputs. `method_name!`, `parameters!` and `source_location!` are public
+for a consumer that wants to fail earlier than the compile does. `Candor::Signature::KINDS` is the frozen
+list of the eight parameter kinds `Method#parameters` can emit, and the only ones `parameters!` and
+`compile` accept.
+
 ## 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.
+**Body kinds.** A block, a `Proc`, a `Method` or an `UnboundMethod`, the three things `define_method`
+takes. A `#call` object raises `TypeError`, and no `source_location:` rescues it: the refusal is about the
+kind. So does 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. An explicit `source_location:` is the
+one way to fabricate from those three, and it is the caller taking responsibility for the honesty the gem
+otherwise derives. Inside a block body, `self` is the receiver.
+
+**Location override.** `source_location:` is what every fabricated name reports, in place of the body's.
+A caller whose body is a proc it generated on the user's behalf points the wrapper at what the user
+actually wrote, rather than at the generator:
+
+```ruby
+Candor.define(App, :fetch, source_location: user_block.source_location, body: proc { ... })
+```
 
 **Reserved prefix.** Compiled bodies are private methods named `#{Candor::BODY_PREFIX}#{name}`.
 Fabricating a name that starts with the prefix raises `ArgumentError`.
@@ -117,8 +138,8 @@ Fabricating a name that starts with the prefix raises `ArgumentError`.
 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.
+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
@@ -135,17 +156,37 @@ serialize. Call-time dispatch takes no lock at all, and never needs one: re-fabr
 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.
+**Failing fast.** Every check runs *before* the target is touched, so a rejected fabrication leaves it
+exactly as it was. A frozen target raises `FrozenError`. A non-Module target, a body that is none of the
+three kinds or carries no location, and a `Method` or `UnboundMethod` whose owner is not an ancestor of
+the target all raise `TypeError`. A name under the reserved prefix, a malformed `parameters:`, a malformed
+`source_location:` or an uncallable `via:` raises `ArgumentError`. A `source_location:` is malformed
+unless it is a `[String, Integer]` pair whose line `eval` will take. 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.
+
+**The `eval`.** The one `eval` runs at definition time, never per call, and never on anything a caller
+passes at runtime. Its source is rendered off the parameter *kinds*, not their names: every positional,
+rest, keyrest and block name becomes a generated one, so the only user text that survives into the source
+is a keyword name. That name is checked before it is rendered, and it cannot shadow the lambda's own
+locals, which all carry a run-of-underscores prefix no keyword name starts with. The two call-site names,
+the body's or `via:`, pass `method_name!` first, so a reserved word or anything `eval` would not call bare
+raises `ArgumentError` before a character is compiled. You can read exactly what it will run: `Signature.render`
+returns the source `compile` would `eval`, without evaluating it.
+
+```ruby
+Candor::Signature.render([%i[req a]], name: :greet, via: :__call)
+# => "__u = ::Object.new.freeze; ->(__p0) { __call(:greet, __p0) }"
+
+Candor::Signature.render([[:req, :name], [:key, :greeting]], name: Candor.body_name(:greet))
+# => "__u = ::Object.new.freeze; ->(__p0, greeting: __u) { __u.equal?(greeting) ? __candor_body_greet(__p0) : __candor_body_greet(__p0, greeting: greeting) }"
+```
 
 **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
+arguments packed into an Array when it is reached through `(name, ...)` forwarding, `send`, or a splat,
+which is the shape an interceptor is usually written in. Candor's own generated call sites name every
+argument, so direct-forward mode is unaffected. Ruby 4.0 fixes it, 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
@@ -168,28 +209,41 @@ optional-argument rows carry a few percent of noise.
 | 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.
+  private body, with the defaults hard-coded. It is 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
+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
+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.
+so the body defaults is the semantics that replaces it.
+
+Definition must happen on the main Ractor. Calling a fabricated method from a non-main Ractor raises, as
+it does for any `define_method`-installed `Proc`, unless both the dispatch and the body are shareable.
+
+## Status and support
+
+Candor is maintained. It is pre-1.0, so the API can still change between minor versions, and only the
+latest release gets fixes.
+
+Ask a question or report a bug in [GitHub issues](https://github.com/svyatov/candor/issues). Report a
+security problem privately through the
+[advisory form](https://github.com/svyatov/candor/security/advisories/new) instead, as
+[SECURITY.md](SECURITY.md) describes.
 
 ## Contributing
 
-Bug reports and pull requests are welcome on [GitHub](https://github.com/svyatov/candor). See
-[CONTRIBUTING.md](CONTRIBUTING.md).
+Pull requests are welcome. [CONTRIBUTING.md](CONTRIBUTING.md) has the setup and test commands, and
+states what an acceptable change has to satisfy. [CHANGELOG.md](CHANGELOG.md) records what changed in
+each release, and the API docs are at [rubydoc.info/gems/candor](https://rubydoc.info/gems/candor).
 
 ## License
 

data/candor.gemspec

@@ -8,8 +8,9 @@ Gem::Specification.new do |spec|
   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 " \
+  spec.summary = "Turn a block or a callable into a real Ruby method that reports the body's own " \
+                 "arity, parameters and source location."
+  spec.description = "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"

data/lib/candor/definer.rb

@@ -12,8 +12,8 @@ module Candor
   #
   # @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.
+    # The only bodies +define_method+ accepts. A +#call+ object is not one of them, and no
+    # +source_location:+ rescues it: the refusal is about the kind, not the location.
     BODY_KINDS = [Proc, Method, UnboundMethod].freeze
 
     # @param target [Module] the module the method is installed onto
@@ -21,13 +21,15 @@ module Candor
     # @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 source_location [Array(String, Integer), nil] a location, overriding the body's
     # @param body [Proc, Method, UnboundMethod]
-    def initialize(target, name, aliases:, via:, parameters:, body:)
+    def initialize(target, name, aliases:, via:, parameters:, source_location:, body:)
       @target = target
       @canonical = name.to_sym
       @names = [@canonical, *aliases.map(&:to_sym)].uniq
       @via = via
       @parameters = parameters
+      @source_location = source_location
       @body = body
       @body_name = Candor.body_name(@canonical)
     end
@@ -56,6 +58,7 @@ module Candor
       raise TypeError, "target must be a Module, got #{@target.inspect}" unless @target.is_a?(Module)
 
       validate_body!
+      validate_location!
       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.
@@ -64,20 +67,37 @@ module Candor
       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?
+      raise TypeError, kind_error unless BODY_KINDS.any? { |kind| @body.is_a?(kind) }
       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
 
+    # A body's +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+. Honouring the body's
+    # location is the product, so a body carrying none is refused — unless the caller names one, which is
+    # the caller assuming responsibility for the honesty. A caller that *rewrites* a location has to be
+    # able to: a wrapper whose body is a proc literal the caller generated should point at what the user
+    # wrote, not at the generator.
+    #
+    # {Signature.compile} gates the location it is handed, but a shape read from the compiled body only
+    # reaches that gate once the body is installed. So an overridden location is gated here too, exactly
+    # as {Signature.method_name!} is: the compiler owns the rule, and the pipeline pays it early enough
+    # that a rejected fabrication still leaves the target untouched.
+    #
+    # @return [void]
+    # @raise [TypeError, ArgumentError]
+    def validate_location!
+      Signature.source_location!(@source_location) if @source_location
+      raise TypeError, no_location_error if location.nil?
+    end
+
+    # @return [Array(String, Integer), nil] the location the fabricated method will report
+    def location = @source_location || @body.source_location
+
     # @return [void]
     # @raise [ArgumentError]
     def validate_names!
@@ -88,9 +108,19 @@ module Candor
     end
 
     # @return [String]
-    def body_error
+    def kind_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"
+        "got #{@body.inspect}; a `#call` object is none of them, and no source_location: rescues it"
+    end
+
+    # Separate from {kind_error} because the remedy differs. Only a body +define_method+ accepts reaches
+    # this, so naming a location really is the fix — where a +#call+ object is refused for its kind, and
+    # naming one buys it nothing.
+    #
+    # @return [String]
+    def no_location_error
+      "#{@body.inspect} carries no source_location: curried procs, symbol-to-procs and C-defined " \
+        "methods have none, so fabricating from one takes an explicit source_location:"
     end
 
     # +define_method+ replaces a method in place, so a re-fabrication is never observable as a missing
@@ -123,8 +153,7 @@ module Candor
     # @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)
+      Signature.compile(shape, name: @via ? @canonical : @body_name, via: @via, source_location: location)
     end
 
     # @param dispatch [Proc]

data/lib/candor/signature.rb

@@ -70,12 +70,16 @@ module Candor
     # Names Ruby reserves for the numbered block parameters; +->(_1: 1) {}+ is a +SyntaxError+.
     NUMBERED_PARAMETERS = (1..9).map { |i| "_#{i}" }.freeze
 
+    # The line numbers +eval+ takes: its +lineno+ is a C +int+, and one outside this range is a
+    # +RangeError+ from inside {compile} rather than an +ArgumentError+ from its gate.
+    LINE_RANGE = (-(2**31))...(2**31)
+
     # 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.
+    # against {compile}, {render}, {method_name!}, {parameters!} and {source_location!} — 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
+                     :METHOD_NAME, :KEYWORD_NAME, :NUMBERED_PARAMETERS, :LINE_RANGE
 
     class << self
       # +eval+'s file and line forge the lambda's — and therefore the compiled method's —
@@ -87,9 +91,10 @@ module Candor
       # @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
+      # @raise [ArgumentError] if the call site's name, the parameter shape or the location is malformed
       def compile(parameters, name:, source_location:, via: nil)
-        eval(render(parameters, name: name, via: via), binding, *source_location) # rubocop:disable Security/Eval
+        source = render(parameters, name: name, via: via)
+        eval(source, binding, *source_location!(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
@@ -139,6 +144,23 @@ module Candor
         parameters
       end
 
+      # Unlike the two gates above, the location is never interpolated into the generated source: +eval+
+      # takes it as a file and a line, not as code. So this is a shape check rather than a trust boundary
+      # — with one edge that bites. +eval+'s line is a C +int+, and one outside {LINE_RANGE} raises
+      # +RangeError+ from inside {compile}. A consumer reading a shape off an already-installed body only
+      # reaches that compile after installing it, so the range is checked here, where it is still cheap.
+      #
+      # @param source_location [Array(String, Integer)]
+      # @return [Array(String, Integer)] the location
+      # @raise [ArgumentError] unless it is a [String, Integer] pair whose line +eval+ will take
+      def source_location!(source_location)
+        file, line = source_location if source_location.is_a?(Array) && source_location.size == 2
+        return source_location if file.is_a?(String) && line.is_a?(Integer) && LINE_RANGE.cover?(line)
+
+        raise ArgumentError, "malformed source_location: #{source_location.inspect}; " \
+                             "expected a [String, Integer] pair, the line within #{LINE_RANGE}"
+      end
+
       private
 
       # @param entry [Object]

data/lib/candor/version.rb

@@ -2,5 +2,5 @@
 
 module Candor
   # The gem version.
-  VERSION = "0.1.0"
+  VERSION = "0.2.1"
 end

data/lib/candor.rb

@@ -40,17 +40,21 @@ module Candor
     # @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 source_location [Array(String, Integer), nil] a location reported instead of the body's, for
+    #   a caller whose body is a proc it generated on the user's behalf; also the only way to fabricate
+    #   from a body carrying no location of its own
     # @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+
+    #   nor an UnboundMethod, or neither it nor +source_location+ carries a location, or the body's 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
+    #   name, or +parameters+ or +source_location+ 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
+    def define(target, name, aliases: [], via: nil, parameters: nil, source_location: nil, body: nil, &block)
+      Definer.new(target, name, aliases: aliases, via: via, parameters: parameters,
+                                source_location: source_location, body: body || block).call
     end
 
     # The private method holding a fabricated method's body. An interceptor calls it with +send+.

data/sig/candor/signature.rbs

@@ -15,6 +15,7 @@ module Candor
     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 self.source_location!: (untyped source_location) -> [ String, Integer ]
 
     def initialize: (Array[parameter] parameters, Symbol name, ?Symbol? via) -> void
     def source: () -> String

data/sig/candor.rbs

@@ -21,6 +21,7 @@ module Candor
     ?aliases: Array[Symbol],
     ?via: Symbol?,
     ?parameters: Array[Signature::parameter]?,
+    ?source_location: [ String, Integer ]?,
     ?body: body?
   ) ?{ (?) -> untyped } -> Symbol
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: candor
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.1
 platform: ruby
 authors:
 - Leonid Svyatov
@@ -9,9 +9,9 @@ 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.'
+description: '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: []
@@ -52,7 +52,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.12
+rubygems_version: 4.0.16
 specification_version: 4
-summary: Turn a block or a callable into a real method with an honest signature.
+summary: Turn a block or a callable into a real Ruby method that reports the body's
+  own arity, parameters and source location.
 test_files: []