[soareschen]

This PR rebuilds CGP's three extra-feature macros, #[cgp_computer], #[cgp_producer], and
#[cgp_auto_dispatch], on the same foundation as the core macros, and fixes the defects that review
of them turned up. The macros now generate fully qualified code that works without
use cgp::prelude::*. #[cgp_auto_dispatch] accepts supertraits and the lifetime shapes it used to
reject, and inputs that previously miscompiled or crashed the macro now fail with an error on the
code the user wrote.

What changes for users

Most users need to change nothing. Code that reaches these macros through cgp::prelude keeps
compiling, and the generated code behaves the same apart from the fixes below. Three consequences are
visible, and all are deliberate.

The macro crates are renamed. cgp-extra-macro and cgp-extra-macro-lib become
cgp-macro-extra and cgp-macro-extra-lib, matching the cgp-macro* family they belong to, and a
new cgp-macro-extra-core sits beside cgp-macro-core. Only a crate that depends on
cgp-extra-macro directly, rather than through cgp, has to change its manifest and its
cgp_extra_macro:: paths.

The generated per-variant computers of #[cgp_auto_dispatch] change shape where a method elides
lifetimes, because each elided argument lifetime now gets its own name (see the lifetime fix
below). Each computer's impl becomes more general rather than less, so code that wires a
Compute{Method} provider by name should keep compiling; the computer_by_name test wires one
this way.

An import that existed only for the old expansion becomes unused. The old expansion named CGP
items without a path, so a module using #[cgp_auto_dispatch] sometimes had to import a matcher or
the prelude just to make the generated code compile. The new expansion qualifies every name, so those
imports now trigger the unused_imports lint. Seven test files in this repository had such imports,
and this PR removes them.

Why the macros were rebuilt

The extra macros were written as single functions that assembled their output with quote! and
emitted other macros for the compiler to expand later. #[cgp_computer] produced a
#[cgp_new_provider] impl and a delegate_components! block, and #[cgp_auto_dispatch] produced a
#[cgp_computer] function per method:

// What #[cgp_computer] fn add(a: u64, b: u64) -> u64 used to emit, after the function:
#[cgp_new_provider]
impl<__Context__, __Code__> Computer<__Context__, __Code__, (u64, u64)> for Add {
    type Output = u64;
    fn compute(_context: &__Context__, _code: PhantomData<__Code__>, (arg_0, arg_1): (u64, u64)) -> Self::Output {
        add(arg_0, arg_1)
    }
}

delegate_components! {
    Add {
        [ComputerRefComponent, TryComputerComponent, /* … */] -> PromoteComputer<Self>,
    }
}

Every name in that output, cgp_new_provider, delegate_components!, Computer, PhantomData,
PromoteComputer, resolved through whatever the caller's module happened to import. So the macros
worked only where cgp::prelude::* was in scope, and a local item with a matching name could take
the place of a CGP one. The core macros avoid both problems by routing every name through
cgp-macro-core's exports markers and building their output from typed AST nodes. The extra macros
already depended on cgp-macro-core, but used it only for a case-conversion helper, so none of that
machinery reached them.

The new structure

The extra macros now mirror the core ones. Each layer has one job:

• cgp-macro-extra is the proc-macro entry crate. It forwards to the lib crate and now carries
  rustdoc for each macro.
• cgp-macro-extra-lib holds one thin entry function per macro: parse the input, run the
  stages, and lower the result.
• cgp-macro-extra-core (new) holds the parsing and code generation. It depends on
  cgp-macro-core and reuses its exports markers, parse_internal!, merge_generics,
  override_item_span, and AST types.

Each macro is a staged pipeline in the core crate's style, Item… → preprocess() →
Preprocessed… → eval(). The difference from the old code is what eval() returns. Instead of
tokens that invoke another macro, it returns the AST nodes that macro would have parsed its input
into: an intermediate representation, or IR. A computer evaluates to a cgp-macro-core
ItemCgpProvider (what #[cgp_new_provider] impl … parses into) and a DelegateTable (what
delegate_components! { … } parses into). The entry function then lowers them with those types'
own methods:

pub fn cgp_computer(attr: TokenStream, body: TokenStream) -> syn::Result<TokenStream> {
    let item_fn: ItemFn = parse2(body)?;
    let ident: Option<Ident> = parse2(attr)?;

    let evaluated = ItemCgpComputer { ident, item_fn }.preprocess()?.eval()?;

    lower_handler_fn(&evaluated) // item_fn, provider.lower()?, delegate_table.eval()?
}

#[cgp_auto_dispatch] goes one level further: its IR holds one ItemCgpComputer per method, which
the entry function runs through the computer pipeline instead of emitting #[cgp_computer]. The
result is that the expansion is the final code in a single pass, every CGP name in it is a full
::cgp::macro_prelude::… path, and the core macros' rules (struct declaration, IsProviderFor
derivation, wiring) apply unchanged because the same types do the work.

Along the way the code adopts the core crate's other conventions:

• Validation as check_* methods with Error::new_spanned, so an error underlines the whole
  offending parameter list or generic list rather than its first token.
• Visitors for type rewriting: ElaborateElidedLifetimes (a VisitMut), collect_lifetimes,
  and find_impl_trait.
• Spans aimed at the user's code: generated provider impls are re-spanned onto the function or
  method name with override_item_span.
• Commented generic insertions and merge_generics in place of hand-merged generics.

The repository's AGENTS.md and cgp-macro-core/AGENTS.md now describe the extra crates, and the
new crate carries its own AGENTS.md recording the lower-through-IR pattern for future macros.

How the refactor was kept safe

The tests came first. Before any macro code changed, the branch added three snapshot macros,
snapshot_cgp_computer!, snapshot_cgp_producer!, and snapshot_cgp_auto_dispatch!, and pinned
the expansion of every shape each macro distinguishes: sync and async, value and Result<T, E>,
named providers, zero and one parameters, generics, lifetimes, const generics, every receiver form,
generic traits, and raw method names. The rejection tests now pin each error's message, through a new
assert_macro_rejects_with, so an input cannot start failing for some unrelated reason unnoticed.

The refactor then moved one macro per commit. Each commit changed only that macro's snapshots, and
the change was the expected one: the nested #[cgp_new_provider], delegate_components!, or
#[cgp_computer] call replaced by the code it expands to. The #[cgp_auto_dispatch] commit also
removes the seven imports that only the old expansion used. As an independent check, companion
fixtures in cargo-cgp record the fully expanded code, nested macros included, through
cargo cgp expand. Those expansions stayed identical across the whole refactor apart from
PhantomData becoming ::core::marker::PhantomData, which confirms the new pipeline generates the
same final code as the old one.

Defects fixed

Each fix below shows input that failed before, what the compiler said, and what happens now. Every
fix has a regression test.

The expansion depended on the caller's imports

Any of the three macros failed when invoked by path in a module without the prelude:

#[cgp::prelude::cgp_computer]
fn add(a: u64, b: u64) -> u64 {
    a + b
}

error: cannot find attribute `cgp_new_provider` in this scope
error: cannot find macro `delegate_components` in this scope
error[E0405]: cannot find trait `Computer` in this scope
error[E0425]: cannot find type `PhantomData` in this scope

A module that imported the prelude but declared its own Computer failed differently, because the
local struct captured the bare name: error[E0404]: expected trait, found struct `Computer` .

The new expansion qualifies every name, so both programs compile. The macros_without_prelude and
without_prelude tests invoke all three macros by path, beside local items named Computer and
HasExtractor.

#[cgp_auto_dispatch] rejected valid lifetime shapes

The macro copies each method's signature into a matcher bound and a helper function, and both need
every lifetime named. It used to give each top-level &T one shared lifetime, '__a__, and to
quantify only the last lifetime it collected in the bound's for<…>. Several ordinary traits
failed as a result:

#[cgp_auto_dispatch]
pub trait HasSides {
    fn sides<'a>(&'a self) -> u8;             // E0261: use of undeclared lifetime name `'a`
}

#[cgp_auto_dispatch]
pub trait CanLookup {
    fn lookup<'a>(&'a self, key: &str) -> &'a str; // E0261: undeclared lifetime `'__a__`
}

#[cgp_auto_dispatch]
pub trait CanPrefix<'a> {
    fn prefix(&self, prefix: &'a str) -> &'a str;  // E0496: lifetime `'a` shadows one in scope
}

#[cgp_auto_dispatch]
pub trait HasTitle {
    fn title<'a>(&'a self) -> &str;           // E0261, E0207, and E0582 in the generated code
}

#[cgp_auto_dispatch]
pub trait CanFind {
    fn find(&self, key: Option<&str>) -> Option<&str>;
    // E0637: `&` without an explicit lifetime name cannot be used here
}

Sharing one lifetime also changed what a signature meant, even where it compiled. Rust gives each
elided argument its own lifetime and ties an elided return to &self, so this method promises that
the returned borrow comes from the receiver and outlives suffix:

#[cgp_auto_dispatch]
pub trait CanLabel {
    fn label(&self, suffix: &str) -> &str;
}

With self and suffix forced onto one lifetime, the generated blanket impl could not keep that
promise and failed with lifetime may not live long enough.

DispatchMethod now names a method's lifetimes once, by the compiler's elision rules, and both the
bound and the helper read the result:

• A borrowed receiver keeps its own lifetime, or gets '__a__ when elided.
• Each elided lifetime in an argument, at any depth, gets its own fresh '__a1__, '__a2__, and so
  on. The ElaborateElidedLifetimes visitor does this, and leaves fn(&T) types and Fn(&T)
  bounds alone, since they bind their own lifetimes.
• An elided lifetime in the return type takes the receiver's lifetime, or, for a by-value self,
  the one lifetime the arguments use.
• The bound quantifies the method's own lifetimes plus the introduced ones in a single for<…>, and
  never the trait's lifetimes, which the impl already declares.

For label, the generated helper and bound are now:

fn __compute_label__<'__a__, '__a1__, __Variants__: CanLabel>(
    __Variants__: &'__a__ __Variants__,
    (arg_0): (&'__a1__ str),
) -> &'__a__ str {
    __Variants__.label(arg_0)
}

// in the blanket impl's where clause:
MatchFirstWithValueHandlersRef<ComputeLabel>:
    for<'__a__, '__a1__> Computer<(), (), (&'__a__ __Variants__, (&'__a1__ str)), Output = &'__a__ str>,

The named_lifetimes and elided_lifetimes tests cover every trait above.

#[cgp_auto_dispatch] ignored supertraits

The blanket impl implemented the trait for every __Variants__ but never required the trait's
supertraits, so any dispatch trait with a supertrait failed to compile:

#[cgp_auto_dispatch]
pub trait HasName {
    fn name(&self) -> &'static str;
}

#[cgp_auto_dispatch]
pub trait CanGreet: HasName {
    fn greet(&self) -> String;
}
// error[E0277]: the trait bound `__Variants__: HasName` is not satisfied

The blanket impl now adds __Variants__: HasName to its where clause, so the enum has to provide
the supertrait, here by dispatching it too. The supertrait test pins the expansion.

A typed receiver miscompiled instead of being rejected

#[cgp_auto_dispatch] read self: Box<Self> as a by-value self and passed the box to a matcher
that expects the enum:

#[cgp_auto_dispatch]
pub trait HasArea {
    fn area(self: Box<Self>) -> f64;
}
// error[E0308]: mismatched types
// error[E0599]: no method named `area` found for type parameter `__Variants__`

It now rejects the method, pointing at the receiver:

error: Dispatcher method receiver must be `self`, `&self`, or `&mut self`

Attribute arguments were silently ignored

#[cgp_auto_dispatch(AreaDispatcher)] expanded exactly like #[cgp_auto_dispatch], so a reader
could believe the argument meant something. It is now rejected with
`#[cgp_auto_dispatch]` takes no arguments.

A raw function name crashed the macro

#[cgp_computer] and #[cgp_producer] built the default provider name from the raw spelling of the
function name:

#[cgp_computer]
fn r#type(value: u64) -> u64 {
    value + 1
}
// error: custom attribute panicked
//   = help: message: `"R#type"` is not a valid identifier

The name is now read without its r# prefix, as #[cgp_auto_dispatch] already did for its
computers, so this defines the provider Type. All three macros share one helper for it.

impl Trait produced an error inside generated code

A computer's parameter types become a provider impl's trait arguments, and its return type becomes
the impl's Output, and neither position accepts impl Trait:

#[cgp_computer]
fn describe(value: impl core::fmt::Display) -> String {
    value.to_string()
}
// error[E0562]: `impl Trait` is not allowed in traits

Both macros now reject it at the impl Trait the user wrote:

error: Computer function parameters cannot use `impl Trait`; declare a generic parameter instead
error: Computer functions cannot return `impl Trait`
error: Producer functions cannot return `impl Trait`

A one-argument Result<T> gave a cryptic parse error

#[cgp_computer] treats only a bare Result<T, E> return type as fallible, deciding from the tokens
rather than the type. That rule is deliberate and unchanged. But an alias such as anyhow::Result's
Result<u64> failed with a bare expected `,` , which did not say what was wrong. It now fails
with:

error: A `Result` return type must be written as `Result<T, E>`, naming its error type

Errors pointed at the whole attribute

Two span changes make errors land on the code the user wrote. Rejections now use
Error::new_spanned, so fn magic_number(seed: u64) underlines seed: u64 rather than seed
alone. And generated provider impls are spanned on the name they derive from: when two dispatch
traits in one module share a method name, the conflicting Computer and IsProviderFor impls now
point at the second method's name instead of at the whole #[cgp_auto_dispatch] attribute. The
remaining conflicts, on the promotion wiring, still underline the attribute, but rustc now says they
originate in cgp_auto_dispatch, the macro the user wrote, rather than in an internal
cgp_computer.

Known issues left in place

Four limitations are documented in the knowledge base's Known issues and pinned by a test rather than
fixed, because each fix is larger than this PR's scope or changes a public name:

• Two dispatch traits in one module cannot share a method name. Both emit
  __compute_area__ and ComputeArea. The fix folds the trait name into those names, but
  Compute{Method} is a public provider that code outside the macro wires by name, so renaming it
  needs its own decision. A cargo-cgp UI fixture pins it.
• A computer's type parameter used only in its return type is unconstrained.
  fn parse<T: FromStr>(value: String) -> Option<T> fails with E0207, because the provider struct
  would have to carry T. A cargo-cgp UI fixture pins it.
• A lifetime hidden in a path is not named. Cow<str> in a dispatch method fails with E0726
  or E0106, since a macro cannot tell that Cow carries a lifetime. Writing Cow<'_, str> works. A compile-fail
  fixture in the website's example-code crate pins it.
• #[cgp_fn] panics on a raw function name, the same defect fixed here for the extra macros.
  It lives in cgp-macro-core, outside this refactor, and a #[should_panic] test now pins it.