feat(workspace): add mingling_pathf crate and pathf feature

5 files changed, 59 insertions, 0 deletions

diff --git a/mingling_pathf/Cargo.toml b/mingling_pathf/Cargo.toml
new file mode 100644
index 0000000..90d94da
--- /dev/null
+++ b/mingling_pathf/Cargo.toml
@@ -0,0 +1,8 @@
+[package]
+name = "mingling_pathf"
+version.workspace = true
+edition.workspace = true
+license.workspace = true
+repository.workspace = true
+
+[dependencies]
diff --git a/mingling_pathf/LICENSE-APACHE b/mingling_pathf/LICENSE-APACHE
new file mode 120000
index 0000000..965b606
--- /dev/null
+++ b/mingling_pathf/LICENSE-APACHE
@@ -0,0 +1 @@
+../LICENSE-APACHE
\ No newline at end of file
diff --git a/mingling_pathf/LICENSE-MIT b/mingling_pathf/LICENSE-MIT
new file mode 120000
index 0000000..76219eb
--- /dev/null
+++ b/mingling_pathf/LICENSE-MIT
@@ -0,0 +1 @@
+../LICENSE-MIT
\ No newline at end of file
diff --git a/mingling_pathf/README.md b/mingling_pathf/README.md
new file mode 100644
index 0000000..9706083
--- /dev/null
+++ b/mingling_pathf/README.md
@@ -0,0 +1,49 @@
+<p align="center">
+    <a href="https://github.com/mingling-rs/mingling">
+        <img alt="Mingling" src="https://github.com/mingling-rs/mingling/raw/main/docs/res/pixel_icon_core_1024.png" width="30%">
+    </a>
+</p>
+<h1 align="center">Mìng Lìng - Module PathFinder</h1>
+
+## Overview
+
+`mingling_pathf` provides the `pathf` feature for Mingling. It automatically analyzes the full module paths of all Mingling types in a crate at build-time (types defined via `pack!`, `#[derive(Groupped)]`, `#[chain]`, `#[renderer]`, etc.), and generates a mapping from type names to module paths for consumption by `gen_program!()` at compile-time.
+
+When enabled, `gen_program!()` uses full module paths for type references in the generated dispatch code (e.g., `downcast::<myapp::sub::ResultMyName>()`), eliminating the need to `use` all types in the module where `gen_program!()` is called. This allows for a more flexible module organization without the constraint of centralized `use` statements.
+
+## Usage
+
+Enable the `pathf` feature in `Cargo.toml`:
+
+```toml
+[dependencies.mingling]
+# Used to modify the generation behavior of `gen_program!`
+features = ["pathf"] 
+
+[build-dependencies.mingling]
+# Provides the `analyze_and_build_type_mapping` function
+features = ["builds", "pathf"] 
+```
+
+Create a `build.rs` in the project root:
+
+```rust
+fn main() {
+    mingling::build::analyze_and_build_type_mapping();
+}
+```
+
+> [!TIP]
+> If you already have a `build.rs` (e.g., using `builds` + `comp` features to generate completion scripts), simply add this function call.
+
+## How It Works
+
+1. **Build-time scanning**: `build.rs` traverses all `.rs` source files under `src/`, locating macro invocations such as `pack!`, `#[chain]`, `#[renderer]`, etc., via pattern matching.
+2. **Module inference**: The module path is inferred from the file's directory path (e.g., `src/app/sub.rs` → `app::sub`).
+3. **Reference tracking**: Following the chain of `mod use` re-exports (i.e., paths re-exported via `pub use` or `use`), the type name is resolved to the module path under which it is ultimately referenced.
+4. **Mapping output**: The mapping from type names to their final referenceable module paths is written to `$OUT_DIR/CRATE_NAME/type-mapping.rs`.
+5. **Compile-time consumption**: `gen_program!()` reads this mapping file and uses the full paths for downcasting in the generated dispatch code.
+
+## Constraints
+
+- Does not penetrate secondary indirect expansions of macros (i.e., cannot analyze Mingling type definitions indirectly generated by other macros).
diff --git a/mingling_pathf/src/lib.rs b/mingling_pathf/src/lib.rs
new file mode 100644
index 0000000..e69de29
--- /dev/null
+++ b/mingling_pathf/src/lib.rs