From 69250e8f99c16c70ffe04fccf3192eb648f6e4f5 Mon Sep 17 00:00:00 2001
From: 魏曹先生 <1992414357@qq.com>
Date: Sun, 28 Jun 2026 04:10:24 +0800
Subject: feat(workspace): add mingling_pathf crate and pathf feature

---
 mingling_pathf/README.md | 49 ++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 49 insertions(+)
 create mode 100644 mingling_pathf/README.md

(limited to 'mingling_pathf/README.md')

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).
-- 
cgit