aboutsummaryrefslogtreecommitdiff
path: root/mingling_pathf/src
diff options
context:
space:
mode:
Diffstat (limited to 'mingling_pathf/src')
-rw-r--r--mingling_pathf/src/config.rs6
-rw-r--r--mingling_pathf/src/error.rs37
-rw-r--r--mingling_pathf/src/lib.rs3
-rw-r--r--mingling_pathf/src/module_pathf.rs16
-rw-r--r--mingling_pathf/src/pattern_analyzer.rs14
-rw-r--r--mingling_pathf/src/patterns.rs6
-rw-r--r--mingling_pathf/src/patterns/basic_struct.rs4
-rw-r--r--mingling_pathf/src/patterns/chain.rs13
-rw-r--r--mingling_pathf/src/patterns/completion.rs13
-rw-r--r--mingling_pathf/src/patterns/dispatcher.rs13
-rw-r--r--mingling_pathf/src/patterns/dispatcher_clap.rs14
-rw-r--r--mingling_pathf/src/patterns/group.rs4
-rw-r--r--mingling_pathf/src/patterns/groupped_derive.rs5
-rw-r--r--mingling_pathf/src/patterns/help.rs13
-rw-r--r--mingling_pathf/src/patterns/pack.rs26
-rw-r--r--mingling_pathf/src/patterns/renderer.rs13
-rw-r--r--mingling_pathf/src/type_mapping_builder.rs4
17 files changed, 148 insertions, 56 deletions
diff --git a/mingling_pathf/src/config.rs b/mingling_pathf/src/config.rs
index 6758264..1199b2c 100644
--- a/mingling_pathf/src/config.rs
+++ b/mingling_pathf/src/config.rs
@@ -1,3 +1,9 @@
+//! Configuration for the module pathfinder analysis.
+//!
+//! This module defines [`PathfinderConfig`], which controls behavior such as
+//! whether dispatch-tree related types (`__internal_dispatcher_*`) should be
+//! extracted.
+
/// Configuration for the module pathfinder analysis.
///
/// Controls behavior such as whether dispatch-tree related types
diff --git a/mingling_pathf/src/error.rs b/mingling_pathf/src/error.rs
index 025ceed..70a8f6e 100644
--- a/mingling_pathf/src/error.rs
+++ b/mingling_pathf/src/error.rs
@@ -1,3 +1,9 @@
+//! Errors that can occur during the pathfinding process for Rust module resolution.
+//!
+//! This module defines all possible failure modes when traversing the module graph
+//! of a Rust project, including I/O failures, missing modules, invalid path
+//! attributes, missing entry points, and syntax parsing errors.
+
use std::fmt;
use std::path::PathBuf;
@@ -24,10 +30,7 @@ pub enum MinglingPathfinderError {
///
/// `file` is the file containing the invalid attribute.
/// `path_attr` is the value of the `#[path]` attribute.
- PathPointsOutside {
- file: PathBuf,
- path_attr: String,
- },
+ PathPointsOutside { file: PathBuf, path_attr: String },
/// No entry point file (`main.rs`, `lib.rs`, or any file under `bin/`) was found.
NoEntryPointFound,
@@ -36,23 +39,33 @@ pub enum MinglingPathfinderError {
///
/// `path` is the file that failed to parse.
/// `message` contains details from the parser.
- SynError {
- path: PathBuf,
- message: String,
- },
+ SynError { path: PathBuf, message: String },
}
impl fmt::Display for MinglingPathfinderError {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
match self {
Self::IoError(e) => write!(f, "IO error: {e}"),
- Self::ModuleNotFound { parent, module_name } => {
- write!(f, "Module `{module_name}` not found relative to {}", parent.display())
+ Self::ModuleNotFound {
+ parent,
+ module_name,
+ } => {
+ write!(
+ f,
+ "Module `{module_name}` not found relative to {}",
+ parent.display()
+ )
}
Self::PathPointsOutside { file, path_attr } => {
- write!(f, "#[path = \"{path_attr}\"] in {} points outside the project", file.display())
+ write!(
+ f,
+ "#[path = \"{path_attr}\"] in {} points outside the project",
+ file.display()
+ )
+ }
+ Self::NoEntryPointFound => {
+ write!(f, "No entry point found (main.rs, lib.rs, or bin/*.rs)")
}
- Self::NoEntryPointFound => write!(f, "No entry point found (main.rs, lib.rs, or bin/*.rs)"),
Self::SynError { path, message } => {
write!(f, "Failed to parse {}: {message}", path.display())
}
diff --git a/mingling_pathf/src/lib.rs b/mingling_pathf/src/lib.rs
index 81b2df6..557ae45 100644
--- a/mingling_pathf/src/lib.rs
+++ b/mingling_pathf/src/lib.rs
@@ -1,3 +1,6 @@
+#![allow(clippy::needless_doctest_main)]
+#![doc = include_str!("../README.md")]
+
pub mod config;
pub mod error;
pub mod module_pathf;
diff --git a/mingling_pathf/src/module_pathf.rs b/mingling_pathf/src/module_pathf.rs
index d06be9b..f0a06d1 100644
--- a/mingling_pathf/src/module_pathf.rs
+++ b/mingling_pathf/src/module_pathf.rs
@@ -1,3 +1,9 @@
+//! A module for mapping Rust module paths to source files.
+//!
+//! This module provides functionality to analyze the module structure of a Rust crate
+//! and determine the effective module path for each source file, taking into account
+//! `pub use` re-exports that can cause modules to be hoisted to parent paths.
+
use std::collections::HashMap;
use std::path::{Path, PathBuf};
use syn::{Item, UseTree};
@@ -10,7 +16,6 @@ use crate::error::MinglingPathfinderError;
/// effective module path (e.g., `crate::foo::bar`).
#[derive(Debug, Clone)]
pub struct MappingItem {
-
/// The path of the source file (relative to the crate root, with `./` prefix).
file_path: PathBuf,
@@ -349,11 +354,7 @@ fn propagate_children(parent_file: &Path, ctx: &mut Context) {
.cloned()
.unwrap_or_else(|| "crate".to_string());
- let reexported = ctx
- .reexports
- .get(parent_file)
- .cloned()
- .unwrap_or_default();
+ let reexported = ctx.reexports.get(parent_file).cloned().unwrap_or_default();
let Some(children) = ctx.children.get(parent_file).cloned() else {
return;
@@ -367,8 +368,7 @@ fn propagate_children(parent_file: &Path, ctx: &mut Context) {
format!("{}::{}", parent_effective, child.name)
};
- ctx.effective_paths
- .insert(child.file.clone(), effective);
+ ctx.effective_paths.insert(child.file.clone(), effective);
propagate_children(&child.file, ctx);
}
}
diff --git a/mingling_pathf/src/pattern_analyzer.rs b/mingling_pathf/src/pattern_analyzer.rs
index c4b1971..3765971 100644
--- a/mingling_pathf/src/pattern_analyzer.rs
+++ b/mingling_pathf/src/pattern_analyzer.rs
@@ -1,3 +1,17 @@
+//! This module defines the core pattern analysis system used to parse and extract
+//! importable/referenceable items (like structs, enums, functions, etc.) from Rust source files.
+//!
+//! It provides a pluggable architecture via the `AnalyzePattern` trait, allowing different
+//! syntactic patterns to be registered and applied. Built-in patterns cover common structures
+//! such as basic structs, packs, groups, derives, chains, renderers, help, completion, and
+//! dispatch patterns (both standard and clap-based).
+//!
+//! The entry points are:
+//! - [`init()`] — creates a default `PatternAnalyzer` with all built-in patterns.
+//! - [`init_with_config()`] — creates a `PatternAnalyzer` with a given `PathfinderConfig`.
+//! - [`PatternAnalyzer::analyze_file()`] / [`PatternAnalyzer::analyze_file_items()`] — run
+//! analysis on a single file.
+
use std::collections::HashSet;
use std::path::Path;
diff --git a/mingling_pathf/src/patterns.rs b/mingling_pathf/src/patterns.rs
index b3e0cd3..9801e9b 100644
--- a/mingling_pathf/src/patterns.rs
+++ b/mingling_pathf/src/patterns.rs
@@ -1,10 +1,12 @@
+//! Mingling path matching patterns for command routing and field mapping.
+
pub use basic_struct::*;
pub use chain::*;
pub use completion::*;
pub use dispatcher::*;
pub use dispatcher_clap::*;
-pub use groupped_derive::*;
pub use group::*;
+pub use groupped_derive::*;
pub use help::*;
pub use pack::*;
pub use renderer::*;
@@ -14,8 +16,8 @@ mod chain;
mod completion;
mod dispatcher;
mod dispatcher_clap;
-mod groupped_derive;
mod group;
+mod groupped_derive;
mod help;
mod pack;
mod renderer;
diff --git a/mingling_pathf/src/patterns/basic_struct.rs b/mingling_pathf/src/patterns/basic_struct.rs
index eeb665a..09e8e70 100644
--- a/mingling_pathf/src/patterns/basic_struct.rs
+++ b/mingling_pathf/src/patterns/basic_struct.rs
@@ -1,3 +1,7 @@
+//! The `BasicStructPattern` matches `struct` definitions in Rust source code.
+//! It identifies root-level structs and structs nested inside inline modules,
+//! returning their names and optional module path for analysis.
+
use syn::Item;
use crate::pattern_analyzer::{AnalyzeItem, AnalyzePattern};
diff --git a/mingling_pathf/src/patterns/chain.rs b/mingling_pathf/src/patterns/chain.rs
index 10d698e..6393440 100644
--- a/mingling_pathf/src/patterns/chain.rs
+++ b/mingling_pathf/src/patterns/chain.rs
@@ -1,3 +1,7 @@
+//! The `ChainPattern` matches functions annotated with `#[chain]` and
+//! extracts the generated internal struct name (e.g., `__internal_chain_<fn_name>`).
+//! This is used to track chained handler functions for code generation or analysis.
+
use syn::Item;
use crate::pattern_analyzer::{AnalyzeItem, AnalyzePattern};
@@ -63,10 +67,7 @@ fn collect_from_item(item: &Item, current_mod: &str, items: &mut Vec<AnalyzeItem
}
fn has_attr(attrs: &[syn::Attribute], name: &str) -> bool {
- attrs.iter().any(|a| {
- a.path()
- .segments
- .last()
- .is_some_and(|s| s.ident == name)
- })
+ attrs
+ .iter()
+ .any(|a| a.path().segments.last().is_some_and(|s| s.ident == name))
}
diff --git a/mingling_pathf/src/patterns/completion.rs b/mingling_pathf/src/patterns/completion.rs
index 7e4cd09..5427b93 100644
--- a/mingling_pathf/src/patterns/completion.rs
+++ b/mingling_pathf/src/patterns/completion.rs
@@ -1,3 +1,7 @@
+//! The `CompletionPattern` matches functions annotated with `#[completion(T)]` and
+//! extracts the generated internal struct name (e.g., `__internal_completion_<fn_name>`).
+//! This is used to track completion handler functions for code generation or analysis.
+
use syn::Item;
use crate::pattern_analyzer::{AnalyzeItem, AnalyzePattern};
@@ -56,10 +60,7 @@ fn collect_from_item(item: &Item, current_mod: &str, items: &mut Vec<AnalyzeItem
}
fn has_attr(attrs: &[syn::Attribute], name: &str) -> bool {
- attrs.iter().any(|a| {
- a.path()
- .segments
- .last()
- .is_some_and(|s| s.ident == name)
- })
+ attrs
+ .iter()
+ .any(|a| a.path().segments.last().is_some_and(|s| s.ident == name))
}
diff --git a/mingling_pathf/src/patterns/dispatcher.rs b/mingling_pathf/src/patterns/dispatcher.rs
index b9f147d..6796a2c 100644
--- a/mingling_pathf/src/patterns/dispatcher.rs
+++ b/mingling_pathf/src/patterns/dispatcher.rs
@@ -1,3 +1,16 @@
+//! The `DispatcherPattern` matches invocations of the `dispatcher!` macro and
+//! extracts the generated type names from its arguments. It supports:
+//! - `Entry*` — the entry type (always generated)
+//! - `CMD*` — the dispatcher struct (always generated)
+//! - `__internal_dispatcher_*` — the dispatch tree static (when `use_dispatch_tree` is `true`)
+//!
+//! Supported forms:
+//! - Explicit: `dispatcher!("greet", CMDGreet => EntryGreet)`
+//! - Implicit: `dispatcher!("greet")` — infers `CMDGreet` and `EntryGreet`
+//! - With braces: `dispatcher! { ... }`
+//!
+//! This pattern is used to track dispatcher types for code generation or analysis.
+
use syn::Item;
use crate::pattern_analyzer::{AnalyzeItem, AnalyzePattern};
diff --git a/mingling_pathf/src/patterns/dispatcher_clap.rs b/mingling_pathf/src/patterns/dispatcher_clap.rs
index 2e1ec6c..1a86ad5 100644
--- a/mingling_pathf/src/patterns/dispatcher_clap.rs
+++ b/mingling_pathf/src/patterns/dispatcher_clap.rs
@@ -1,3 +1,17 @@
+//! The `DispatcherClapPattern` matches structs annotated with `#[dispatcher_clap(...)]` and
+//! extracts key items for code generation or analysis:
+//! - The entry struct name (always)
+//! - The dispatcher command struct (`CMD*`, always)
+//! - The error type, if `error = ErrorType` is specified
+//! - The help internal struct, if `help = true` is specified
+//! - The `__internal_dispatcher_*` dispatch tree static, if `use_dispatch_tree` is enabled
+//!
+//! Supported forms:
+//! - `#[dispatcher_clap("greet", CMDGreet)] struct EntryGreet { ... }`
+//! - `#[dispatcher_clap("greet", CMDGreet, error = ErrorGreet)] struct EntryGreet { ... }`
+//! - `#[dispatcher_clap("greet", CMDGreet, help = true)] struct EntryGreet { ... }`
+//! - `#[dispatcher_clap("greet", CMDGreet, error = ErrorGreet, help = true)] struct EntryGreet { ... }`
+
use syn::Item;
use crate::pattern_analyzer::{AnalyzeItem, AnalyzePattern};
diff --git a/mingling_pathf/src/patterns/group.rs b/mingling_pathf/src/patterns/group.rs
index 99d1137..0e4b50d 100644
--- a/mingling_pathf/src/patterns/group.rs
+++ b/mingling_pathf/src/patterns/group.rs
@@ -1,3 +1,7 @@
+//! The `GroupPattern` matches the `group!` and `group_structural!` macros and
+//! extracts the type name or alias defined within them.
+//! This is used to track type groups for code generation or analysis.
+
use syn::Item;
use crate::pattern_analyzer::{AnalyzeItem, AnalyzePattern};
diff --git a/mingling_pathf/src/patterns/groupped_derive.rs b/mingling_pathf/src/patterns/groupped_derive.rs
index 8491121..91daaef 100644
--- a/mingling_pathf/src/patterns/groupped_derive.rs
+++ b/mingling_pathf/src/patterns/groupped_derive.rs
@@ -1,3 +1,8 @@
+//! The `GrouppedDerivePattern` matches structs, enums, and unions annotated with
+//! `#[derive(Groupped)]` or `#[derive(GrouppedSerialize)]` (or any combination
+//! with other derives). It also recurses into `mod` items to find nested types.
+//! This is used to track grouped items for code generation or analysis.
+
use syn::Item;
use crate::pattern_analyzer::{AnalyzeItem, AnalyzePattern};
diff --git a/mingling_pathf/src/patterns/help.rs b/mingling_pathf/src/patterns/help.rs
index 357626b..628f4ac 100644
--- a/mingling_pathf/src/patterns/help.rs
+++ b/mingling_pathf/src/patterns/help.rs
@@ -1,3 +1,7 @@
+//! The `HelpPattern` matches functions annotated with `#[help]` and
+//! extracts the generated internal struct name (e.g., `__internal_help_<fn_name>`).
+//! This is used to track help functions for code generation or analysis.
+
use syn::Item;
use crate::pattern_analyzer::{AnalyzeItem, AnalyzePattern};
@@ -56,10 +60,7 @@ fn collect_from_item(item: &Item, current_mod: &str, items: &mut Vec<AnalyzeItem
}
fn has_attr(attrs: &[syn::Attribute], name: &str) -> bool {
- attrs.iter().any(|a| {
- a.path()
- .segments
- .last()
- .is_some_and(|s| s.ident == name)
- })
+ attrs
+ .iter()
+ .any(|a| a.path().segments.last().is_some_and(|s| s.ident == name))
}
diff --git a/mingling_pathf/src/patterns/pack.rs b/mingling_pathf/src/patterns/pack.rs
index f025f7d..c80fb65 100644
--- a/mingling_pathf/src/patterns/pack.rs
+++ b/mingling_pathf/src/patterns/pack.rs
@@ -1,3 +1,7 @@
+//! The `PackPattern` matches types defined by `pack!`, `pack_err!`, `pack_structural!`, and `pack_err_structural!` macros.
+//! It extracts the registered type name (e.g., `TypeName` from `pack!(TypeName = InnerType)`).
+//! This is used to track packed type definitions for code generation or analysis.
+
use syn::Item;
use crate::pattern_analyzer::{AnalyzeItem, AnalyzePattern};
@@ -40,12 +44,13 @@ impl AnalyzePattern for PackPattern {
if let Some((_, nested)) = &item_mod.content {
for n in nested {
if let Item::Macro(m) = n
- && let Some(name) = try_extract_pack_name(m) {
- items.push(AnalyzeItem {
- module: item_mod.ident.to_string(),
- item_name: name,
- });
- }
+ && let Some(name) = try_extract_pack_name(m)
+ {
+ items.push(AnalyzeItem {
+ module: item_mod.ident.to_string(),
+ item_name: name,
+ });
+ }
}
}
}
@@ -89,10 +94,11 @@ fn try_extract_pack_name(m: &syn::ItemMacro) -> Option<String> {
// Check if `=` follows
if let Some(proc_macro2::TokenTree::Punct(p)) = iter.next()
- && p.as_char() == '=' {
- // pack!(TypeName = InnerType)
- return Some(type_name);
- }
+ && p.as_char() == '='
+ {
+ // pack!(TypeName = InnerType)
+ return Some(type_name);
+ }
// pack_err!(TypeName) — only a single ident
return Some(type_name);
diff --git a/mingling_pathf/src/patterns/renderer.rs b/mingling_pathf/src/patterns/renderer.rs
index 410ae14..c2e9ca9 100644
--- a/mingling_pathf/src/patterns/renderer.rs
+++ b/mingling_pathf/src/patterns/renderer.rs
@@ -1,3 +1,7 @@
+//! The `RendererPattern` matches functions annotated with `#[renderer]` and
+//! extracts the generated internal struct name (e.g., `__internal_renderer_<fn_name>`).
+//! This is used to track rendering functions for code generation or analysis.
+
use syn::Item;
use crate::pattern_analyzer::{AnalyzeItem, AnalyzePattern};
@@ -56,10 +60,7 @@ fn collect_from_item(item: &Item, current_mod: &str, items: &mut Vec<AnalyzeItem
}
fn has_attr(attrs: &[syn::Attribute], name: &str) -> bool {
- attrs.iter().any(|a| {
- a.path()
- .segments
- .last()
- .is_some_and(|s| s.ident == name)
- })
+ attrs
+ .iter()
+ .any(|a| a.path().segments.last().is_some_and(|s| s.ident == name))
}
diff --git a/mingling_pathf/src/type_mapping_builder.rs b/mingling_pathf/src/type_mapping_builder.rs
index 3422af8..0965b47 100644
--- a/mingling_pathf/src/type_mapping_builder.rs
+++ b/mingling_pathf/src/type_mapping_builder.rs
@@ -1,3 +1,7 @@
+//! This module contains the matching patterns for `mingling_pathf`.
+//! It provides the core logic for analyzing crate types and generating
+//! type mapping files used by the pathfinder system.
+
use std::collections::HashSet;
use std::path::Path;
generated by cgit (git 2.34.1) at 2026-07-17 14:55:03 +0000