1 files changed, 68 insertions, 19 deletions

diff --git a/mingling_macros/src/lib.rs b/mingling_macros/src/lib.rs
index 2271e21..1aaedb1 100644
--- a/mingling_macros/src/lib.rs
+++ b/mingling_macros/src/lib.rs
@@ -20,6 +20,9 @@ mod derive;
 mod func;
 mod systems;
 
+#[cfg(any(feature = "comp", feature = "pathf"))]
+mod build;
+
 mod extensions;
 mod utils;
 
@@ -689,31 +692,32 @@ pub fn renderer(attr: TokenStream, item: TokenStream) -> TokenStream {
 /// 2. Registering the completion mapping for the specified entry type.
 /// 3. Keeping the original function for direct calls.
 ///
-/// # Syntax
-///
-/// The completion function accepts a relaxed signature:
+/// # Signature rules
 ///
-/// - **Context parameter (optional):** the first parameter may be `&ShellContext`,
-///   an owned `ShellContext`, or any type implementing `From<&ShellContext>`.
-///   With no parameters at all, the shell context is ignored.
-/// - **Return type:** anything implementing `Into<Suggest>`, e.g. `Suggest`,
-///   `Vec<String>`, `Vec<(String, String)>` (suggestion + description), or a
-///   set of [`SuggestItem`](https://docs.rs/mingling/latest/mingling/struct.SuggestItem.html)s.
-/// - **Resource injection:** remaining parameters are injected resources
-///   (only when a context parameter is present).
+/// - **Owned (non-reference) parameters** are *shell sources*: each one is derived
+///   from `&ShellContext` via `From<&ShellContext>`. This covers `ShellContext`
+///   itself (via its `Clone`-based `From` impl), framework state types, and any
+///   user-defined state derived from the shell context.
+/// - **`&T` / `&mut T` parameters** are resource injections (same as `#[chain]`).
+/// - **`&ShellContext` is rejected** — use the owned `ShellContext` instead, since
+///   reference parameters are reserved for resources.
+/// - The return type can be anything implementing `Into<Suggest>`: `Suggest`,
+///   `Vec<String>`, `Vec<&str>`, `Vec<(String, String)>` (suggestion + description),
+///   a set of [`SuggestItem`](https://docs.rs/mingling/latest/mingling/struct.SuggestItem.html)s,
+///   or `()` / no return type for "no suggestions".
 ///
 /// ```rust,ignore
 /// // No context, return simple suggestions
 /// #[completion(EntryType)]
-/// fn complete_static() -> Vec<String> { vec!["a", "b"].into_iter().map(str::to_string).collect() }
+/// fn complete_static() -> Vec<&str> { vec!["a", "b"] }
 ///
-/// // Owned context (via `From<&ShellContext>`), suggestions with descriptions
+/// // Multiple shell-derived states + resource injection
 /// #[completion(EntryType)]
-/// fn complete_owned(ctx: ShellContext) -> Vec<(String, String)> { /* ... */ }
+/// fn complete_mixed(pos: PositionState, flags: FlagState, db: &ResDb) -> Vec<(String, String)> { /* ... */ }
 ///
-/// // Borrowed context (classic form)
+/// // Empty function: this command needs no completion
 /// #[completion(EntryType)]
-/// fn complete_borrowed(ctx: &ShellContext) -> Suggest { /* ... */ }
+/// fn complete_nothing() {}
 /// ```
 ///
 /// # Example
@@ -723,7 +727,7 @@ pub fn renderer(attr: TokenStream, item: TokenStream) -> TokenStream {
 /// use mingling::{ShellContext, Suggest};
 ///
 /// #[completion(MyEntry)]
-/// fn complete_my_command(ctx: &ShellContext) -> Suggest {
+/// fn complete_my_command(ctx: ShellContext) -> Suggest {
 ///     if ctx.previous_word == "--type" {
 ///         return suggest!();
 ///     }
@@ -740,8 +744,9 @@ pub fn renderer(attr: TokenStream, item: TokenStream) -> TokenStream {
 /// # Requirements
 ///
 /// - The `comp` feature must be enabled.
-/// - The first parameter (if any) must implement `From<&ShellContext>`.
-/// - The return type must implement `Into<Suggest>`.
+/// - Owned parameters must implement `From<&ShellContext>`.
+/// - Reference parameters are resource injections; `&ShellContext` is not allowed.
+/// - The return type must implement `Into<Suggest>` (or be `()`).
 /// - The function cannot be async.
 #[cfg(feature = "comp")]
 #[proc_macro_attribute]
@@ -1651,6 +1656,50 @@ pub fn gen_program(input: TokenStream) -> TokenStream {
     func::gen_program::gen_program_impl(input)
 }
 
+/// Executes the completion-script build at compile time and expands to nothing.
+///
+/// **This macro is only available with the `comp` feature.**
+///
+/// The completion scripts are written to `{target_directory}/mingling/` (the
+/// target directory is resolved via `cargo metadata`).
+///
+/// `gen_program!()` calls this macro automatically when the `comp` feature is
+/// enabled. It can also be invoked manually to customize the binary name:
+///
+/// - `build_comp!()` — uses the current package name (`CARGO_PKG_NAME`).
+/// - `build_comp!("mybin")` — uses the given binary name.
+///
+/// ```rust,ignore
+/// mingling::macros::build_comp!();
+/// // or:
+/// mingling::macros::build_comp!("mybin");
+/// ```
+#[cfg(feature = "comp")]
+#[proc_macro]
+pub fn build_comp(input: TokenStream) -> TokenStream {
+    build::comp_build_impl(input)
+}
+
+/// Executes the pathf type-mapping build at compile time and expands to nothing.
+///
+/// **This macro is only available with the `pathf` feature.**
+///
+/// The mapping files are written to `{target_directory}/mingling/{CARGO_PKG_NAME}/`
+/// (the target directory is resolved via `cargo metadata`), and are consumed by
+/// `gen_program!()` so that types defined in submodules are resolved automatically.
+///
+/// `gen_program!()` calls this macro automatically when the `pathf` feature is
+/// enabled.
+///
+/// ```rust,ignore
+/// mingling::macros::build_pathf!();
+/// ```
+#[cfg(feature = "pathf")]
+#[proc_macro]
+pub fn build_pathf(input: TokenStream) -> TokenStream {
+    build::pathf_build_impl(input)
+}
+
 /// Internal macro used by `gen_program!` to generate the completion infrastructure for
 /// shell completion support.
 ///