use super::face_field::*;
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub enum FaceFieldRole {
Required,
Derived,
ReadOnly,
Optional,
Conditional,
}
impl FaceFieldRole {
pub const fn marker(self) -> &'static str {
match self {
Self::Required => "*",
Self::Derived => "◇",
Self::ReadOnly => "↳",
Self::Optional => "·",
Self::Conditional => "?",
}
}
pub const fn label(self) -> &'static str {
match self {
Self::Required => "REQUIRED",
Self::Derived => "DERIVED",
Self::ReadOnly => "DERIVED / READ ONLY",
Self::Optional => "OPTIONAL",
Self::Conditional => "WHEN USED",
}
}
}
#[derive(Clone, Copy, Debug)]
pub struct FaceFieldPresentation {
pub group: &'static str,
pub label: &'static str,
pub role: FaceFieldRole,
pub default: &'static str,
pub help: &'static str,
}
pub fn face_field_presentation(index: usize) -> FaceFieldPresentation {
let field = |group, label, role, default, help| FaceFieldPresentation {
group,
label,
role,
default,
help,
};
match index {
PARENT => field(
"IDENTITY",
"parent registry",
FaceFieldRole::Required,
"selected tree node",
"Registry that receives this face: the selected tree node, or a path/node identity typed here.",
),
MODULE => field(
"IDENTITY",
"module name",
FaceFieldRole::Required,
"none",
"Rust module directory and file name. Use snake_case.",
),
NEEDS_REGISTRY => field(
"REGISTRY",
"owns child registry",
FaceFieldRole::Optional,
"false",
"Create the same Registry type below this face so children can register recursively.",
),
TREE_SLOT => field(
"REGISTRY",
"tree slot",
FaceFieldRole::ReadOnly,
"module name",
"Name this face shows in the registration tree. It follows the declaring module, so it is shown rather than authored.",
),
REGISTRY_RULE => field(
"REGISTRY",
"child structure rule",
FaceFieldRole::Conditional,
"ANY",
"Minimum structure required from children. Used only when this face owns a Registry.",
),
ADMISSION => field(
"REGISTRY",
"allowed dependencies",
FaceFieldRole::Conditional,
"ANY",
"External registration branches that descendants may consume. This is not a construction rule.",
),
PARTS => field(
"IMPLEMENTATION",
"parts type",
FaceFieldRole::Optional,
"NoParts",
"Concrete state/parts type supplied by this face.",
),
EXPORTS => field(
"CAPABILITIES",
"exports",
FaceFieldRole::Optional,
"none",
"Interfaces exposed at the registration seam. A parent structure rule may require them.",
),
KIND => field(
"IDENTITY",
"Rust type",
FaceFieldRole::Optional,
"PascalCase(module)",
"Kind used by Rust and registration identity. It is derived from module name unless overridden.",
),
NAME_ZH => field(
"IDENTITY",
"display name zh",
FaceFieldRole::Optional,
"Rust type",
"Chinese display name. It defaults to the Rust type.",
),
NAME_EN => field(
"IDENTITY",
"display name en",
FaceFieldRole::Optional,
"Rust type",
"English display name. It defaults to the Rust type.",
),
SUMMARY_ZH => field(
"IDENTITY",
"summary zh",
FaceFieldRole::Optional,
"none",
"Short Chinese description shown to people and AI tools.",
),
SUMMARY_EN => field(
"IDENTITY",
"summary en",
FaceFieldRole::Optional,
"none",
"Short English description shown to people and AI tools.",
),
PRESET => field(
"IMPLEMENTATION",
"preset type",
FaceFieldRole::Optional,
"NoPreset",
"Preset contract that states which parts the implementation expects.",
),
STABLE_NAME => field(
"IDENTITY",
"stable identity",
FaceFieldRole::Optional,
"source identity",
"Explicit identity preserved across source moves. Leave empty unless external plans must survive a move.",
),
GETTING_FROM_OTHER_REGISTRY => field(
"REGISTRY",
"dependency registry",
FaceFieldRole::Optional,
"none",
"Registry whose providers this face's requires edges may draw on. It names a resolution source; admission is what grants the access.",
),
REGISTRY_RULE_PATH => field(
"REGISTRY",
"rule source",
FaceFieldRole::ReadOnly,
"registry_rule/registry_rule.rs",
"Canonical rule file beside a face that owns a Registry. It follows the face's own location.",
),
HANDLE_TRAITS => field(
"CONTRACTS",
"handle trait labels",
FaceFieldRole::ReadOnly,
"trait path names",
"Searchable trait labels derived from the handle contract paths. They are not typed separately.",
),
HANDLE_CONTRACTS => field(
"CONTRACTS",
"handle trait paths",
FaceFieldRole::Optional,
"none",
"Rust trait paths implemented by the handle and checked by the compiler.",
),
PART_TRAITS => field(
"CONTRACTS",
"parts trait labels",
FaceFieldRole::ReadOnly,
"trait path names",
"Searchable parts-trait labels derived from the parts contract paths. They are not typed separately.",
),
REQUIRES => field(
"CAPABILITIES",
"requires",
FaceFieldRole::Optional,
"none",
"Capabilities consumed from named providers, written as capability=>provider.",
),
PROVIDES => field(
"CAPABILITIES",
"provides",
FaceFieldRole::Optional,
"none",
"Capabilities advertised to dependency resolution. Unlike exports, these satisfy requires edges.",
),
RUNTIME_CHECKS => field(
"DEBUG",
"runtime checks",
FaceFieldRole::Optional,
"none",
"Named checks the host runs when a value crosses a boundary.",
),
FLOW => field(
"DATA FLOW",
"graft flow contract",
FaceFieldRole::Optional,
"none",
"Versioned input/output seam used to validate replacement grafts.",
),
FLOW_PROVIDER => field(
"DATA FLOW",
"flow provider type",
FaceFieldRole::Conditional,
"none",
"Rust provider type for the declared flow contract.",
),
PART_CONTRACTS => field(
"CONTRACTS",
"parts trait paths",
FaceFieldRole::Optional,
"none",
"Rust trait paths implemented by Parts and checked by the compiler.",
),
_ => field(
"OTHER",
"unknown",
FaceFieldRole::Optional,
"none",
"Unknown registration field.",
),
}
}
pub fn face_field_default(values: &[String], index: usize) -> String {
let module = values.get(MODULE).map_or("", String::as_str).trim();
let rust_type = values.get(KIND).map_or("", String::as_str).trim();
let kind = if rust_type.is_empty() {
pascal_case(module)
} else {
rust_type.to_owned()
};
match index {
MODULE => "<required>".to_owned(),
TREE_SLOT => auto_value(module),
KIND | NAME_ZH | NAME_EN => auto_value(&kind),
STABLE_NAME => "<source identity>".to_owned(),
REGISTRY_RULE_PATH => "<canonical beside face>".to_owned(),
HANDLE_TRAITS => {
derived_trait_names(values.get(HANDLE_CONTRACTS).map_or("", String::as_str))
}
PART_TRAITS => derived_trait_names(values.get(PART_CONTRACTS).map_or("", String::as_str)),
index => {
let default = face_field_presentation(index).default;
if default == "none" {
"—".to_owned()
} else {
format!("<{default}>")
}
}
}
}
pub fn pascal_case(module: &str) -> String {
module
.split(|character: char| !character.is_ascii_alphanumeric())
.filter(|part| !part.is_empty())
.map(|part| {
let mut characters = part.chars();
characters
.next()
.map(|first| first.to_ascii_uppercase().to_string() + characters.as_str())
.unwrap_or_default()
})
.collect()
}
fn auto_value(value: &str) -> String {
if value.is_empty() {
"<auto>".to_owned()
} else {
format!("<auto: {value}>")
}
}
#[cfg_attr(not(feature = "syntax"), allow(unused_variables))]
fn derived_trait_names(paths: &str) -> String {
#[cfg(feature = "syntax")]
let names = crate::registry_core::authoring::parse::trait_names_from_paths(paths)
.map_err(|error| error.to_string());
#[cfg(not(feature = "syntax"))]
let names: Result<String, String> =
Err("trait labels are derived by the `syntax` feature".to_owned());
let Ok(names) = names else {
return "—".to_owned();
};
if names.is_empty() {
"—".to_owned()
} else {
format!("<derived: {}>", names.replace(',', ", "))
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn the_displayed_trait_label_is_the_derived_one() {
let displayed = derived_trait_names("crate::ControlHandle<u8, u16>");
#[cfg(feature = "syntax")]
{
let expected = crate::registry_core::authoring::parse::trait_names_from_paths(
"crate::ControlHandle<u8, u16>",
)
.expect("the shared derivation reads this path");
assert_eq!(
displayed,
format!("<derived: {expected}>"),
"one derivation, so the editor and the file agree"
);
assert_eq!(
displayed.matches('<').count(),
1,
"the generic arguments are not part of the label: {displayed}"
);
}
#[cfg(not(feature = "syntax"))]
assert_eq!(displayed, "—");
}
#[test]
fn the_runtime_checks_help_describes_the_field() {
let help = face_field_presentation(RUNTIME_CHECKS).help;
assert!(help.contains("host"), "these checks are the host's: {help}");
assert!(
!help.to_ascii_lowercase().contains("trace mode"),
"the trace mode is a different knob: {help}"
);
}
#[test]
fn plain_and_empty_lists_are_unchanged() {
#[cfg(feature = "syntax")]
assert_eq!(
derived_trait_names("crate::a::Fast, crate::b::Slow"),
"<derived: Fast, Slow>"
);
assert_eq!(derived_trait_names(""), "—");
#[cfg(feature = "syntax")]
assert_eq!(derived_trait_names("not a path"), "—");
#[cfg(not(feature = "syntax"))]
assert_eq!(derived_trait_names("not a path"), "—");
}
}