//! Schema preparation for template rendering //! //! This module handles light preparation of the schema before passing it to Tera: //! - Rendering markdown descriptions to HTML //! - Generating anchor IDs for navigation //! - Building the search index use pulldown_cmark::Parser; use pulldown_cmark::html; use serde::Serialize; use serde_json::Map; use serde_json::Value; use std::collections::HashMap; use std::collections::HashSet; /// Prepare a schema value for template rendering /// /// This function: /// 1. Clones the schema value /// 2. Recursively renders all `description` fields as markdown to `description_html` /// 3. Returns the modified value ready for Tera pub fn prepare_for_template(value: &Value) -> Value { let mut prepared = value.clone(); process_value(&mut prepared); prepared } /// Recursively process a value, rendering markdown descriptions fn process_value(value: &mut Value) { match value { Value::Object(map) => { // Render description if present if let Some(Value::String(desc)) = map.get("description") { let html = render_markdown(desc); map.insert("description_html".to_string(), Value::String(html)); } // Recurse into all nested values for v in map.values_mut() { process_value(v); } } Value::Array(arr) => { for v in arr.iter_mut() { process_value(v); } } _ => {} } } /// Render markdown text to HTML pub fn render_markdown(text: &str) -> String { let parser = Parser::new(text); let mut html_output = String::new(); html::push_html(&mut html_output, parser); html_output } /// Strip markdown formatting from text, keeping only the plain text content. /// Useful for HTML tags where markdown syntax shouldn't appear. pub fn strip_markdown(text: &str) -> String { let parser = Parser::new(text); let mut plain_text = String::new(); for event in parser { if let pulldown_cmark::Event::Text(t) | pulldown_cmark::Event::Code(t) = event { plain_text.push_str(&t); } } plain_text } /// Information about a definition for the sidebar navigation #[derive(Debug, Clone, Serialize)] pub struct DefinitionInfo { pub name: String, pub anchor: String, pub description: Option<String>, } /// An outline entry for hierarchical navigation #[derive(Debug, Clone, Serialize)] pub struct OutlineEntry { pub name: String, pub anchor: String, pub children: Vec<OutlineEntry>, } /// A search index entry #[derive(Debug, Clone, Serialize)] pub struct SearchEntry { pub name: String, pub path: String, pub anchor: String, pub entry_type: String, } /// A usage of a type in the Configuration section #[derive(Debug, Clone, Serialize)] pub struct ConfigUsage { /// jq-style path like ".monitors[].workspaces[].layout" pub path: String, /// HTML anchor for linking to the usage location (no leading dash) pub anchor: String, } /// A reference to a type from another type definition #[derive(Debug, Clone, Serialize)] pub struct TypeReference { /// Name of the referencing type, e.g., "IdWithIdentifier" pub type_name: String, /// Anchor to the type definition pub anchor: String, } /// All usages of a type #[derive(Debug, Clone, Serialize)] pub struct TypeUsages { /// Usages in Configuration section pub config_usages: Vec<ConfigUsage>, /// References from other $defs types pub type_references: Vec<TypeReference>, } /// Navigation data extracted from the schema #[derive(Debug, Clone, Serialize)] pub struct NavigationData { pub outline: Vec<OutlineEntry>, pub definitions: Vec<DefinitionInfo>, pub search_index: Vec<SearchEntry>, /// Map from type name to its usages pub usages: HashMap<String, TypeUsages>, } /// Maximum depth for outline tree to prevent infinite recursion const MAX_OUTLINE_DEPTH: usize = 3; /// Build a hierarchical outline tree from schema properties fn build_outline_tree( schema: &Value, defs: Option<&Map<String, Value>>, parent_path: &str, depth: usize, ) -> Vec<OutlineEntry> { if depth >= MAX_OUTLINE_DEPTH { return Vec::new(); } let mut entries = Vec::new(); // Resolve the schema, getting both the effective schema and the anchor base // When we follow a $ref, the anchor base becomes the type name let (effective_schema, anchor_base) = resolve_schema_for_outline(schema, defs, parent_path); // Check if this is a oneOf - show all variants as alternatives if let Some(one_of) = effective_schema.get("oneOf").and_then(|v| v.as_array()) { for (i, variant) in one_of.iter().enumerate() { // Get variant label: prefer title, then look for a const discriminator, then fall back to "Variant N" let variant_label = variant .get("title") .and_then(|t| t.as_str()) .map(String::from) .or_else(|| { // Look for a const property that could serve as a discriminator (e.g., "palette": {"const": "Catppuccin"}) variant .get("properties") .and_then(|p| p.as_object()) .and_then(|props| { props.values().find_map(|prop| { prop.get("const").and_then(|c| c.as_str()).map(String::from) }) }) }) .unwrap_or_else(|| format!("Variant {}", i + 1)); // Build the variant path to match template-generated IDs // Template uses: path ~ ".oneOf[" ~ loop.index0 ~ "]" let variant_path = format!("{}.oneOf[{}]", anchor_base, i); // Build children for this variant let variant_children = build_outline_tree(variant, defs, &variant_path, depth + 1); if !variant_children.is_empty() { entries.push(OutlineEntry { name: format!("⊕ {}", variant_label), // ⊕ indicates "one of" // Link to the type definition since individual variants don't have anchors anchor: make_anchor(&anchor_base), children: variant_children, }); } } return entries; } if let Some(props) = effective_schema .get("properties") .and_then(|v| v.as_object()) { for (name, prop) in props { // Build the anchor path using the resolved anchor base let child_anchor_path = if anchor_base.is_empty() { name.clone() } else { format!("{}.{}", anchor_base, name) }; // Recursively build children let children = build_outline_tree(prop, defs, &child_anchor_path, depth + 1); entries.push(OutlineEntry { name: name.clone(), anchor: make_anchor(&child_anchor_path), children, }); } // Sort alphabetically entries.sort_by(|a, b| a.name.to_lowercase().cmp(&b.name.to_lowercase())); } entries } /// Resolve schema following $refs, arrays, and Option<T>, returning (effective_schema, anchor_base) /// When we follow a $ref, anchor_base becomes the type name so links go to the type definition /// For true union types (anyOf with multiple non-null variants), we stop and treat as leaf fn resolve_schema_for_outline<'a>( schema: &'a Value, defs: Option<&'a Map<String, Value>>, current_path: &str, ) -> (&'a Value, String) { // Handle $ref - use the ref name as anchor base if let Some(ref_path) = schema.get("$ref").and_then(|v| v.as_str()) { let ref_name = ref_path.trim_start_matches("#/$defs/"); if let Some(def) = defs.and_then(|d| d.get(ref_name)) { // Recursively resolve in case the def itself has a $ref or anyOf // Use the ref_name as the new anchor base return resolve_schema_for_outline(def, defs, ref_name); } return (schema, current_path.to_string()); } // Handle array - unwrap to items schema if is_array_type(schema) && let Some(items) = schema.get("items") { return resolve_schema_for_outline(items, defs, current_path); } // Handle anyOf - only unwrap if it's Option<T> (exactly 2 variants, one null) // For true unions (multiple non-null variants), don't unwrap - treat as leaf if let Some(any_of) = schema.get("anyOf").and_then(|v| v.as_array()) && any_of.len() == 2 { let null_count = any_of .iter() .filter(|v| v.get("type").and_then(|t| t.as_str()) == Some("null")) .count(); // Only unwrap if exactly one null variant (Option<T> pattern) if null_count == 1 { for variant in any_of { let is_null = variant.get("type").and_then(|t| t.as_str()) == Some("null"); if !is_null { return resolve_schema_for_outline(variant, defs, current_path); } } } } // For true unions (0 or 2+ null variants, or 3+ total variants), don't unwrap // Inline object or leaf type - keep current path (schema, current_path.to_string()) } /// Check if schema represents an array type fn is_array_type(schema: &Value) -> bool { // Check type: "array" if schema.get("type").and_then(|t| t.as_str()) == Some("array") { return true; } // Check type: ["array", "null"] (Option<Vec<T>>) if let Some(type_arr) = schema.get("type").and_then(|v| v.as_array()) && type_arr.iter().any(|t| t.as_str() == Some("array")) { return true; } false } /// Collect all usages of type definitions ($refs) in the Configuration section /// /// Recursively traverses the schema and records where each type is referenced, /// building jq-style paths for each usage location. Follows $refs transitively /// to collect usages for types nested inside other types. /// /// Parameters: /// - `current_type`: When inside a followed $ref, this is the type name we're inside. /// Used to build correct anchors that point to the type definition's rendered properties. /// - `type_relative_path`: When inside a type, this tracks the path relative to that type /// (e.g., "workspaces" inside MonitorConfig), used for building anchors. fn collect_config_usages( schema: &Value, path: String, usages: &mut HashMap<String, Vec<ConfigUsage>>, defs: Option<&Map<String, Value>>, visited: &mut HashSet<String>, current_type: Option<&str>, type_relative_path: String, ) { // Check for $ref at current level if let Some(ref_path) = schema.get("$ref").and_then(|v| v.as_str()) { let type_name = ref_path.trim_start_matches("#/$defs/").to_string(); // Build the anchor based on whether we're inside a type or at config root let anchor = if let Some(parent_type) = current_type { // Inside a type definition - anchor points to property within that type // e.g., MonitorConfig.workspaces -> "monitorconfig-workspaces" // e.g., KomorebiTheme.oneOf[0].bar_accent -> "komorebitheme-oneof[0]-bar_accent" // Note: Keep [N] for variant indices, but remove empty [] from array notation let clean_path = type_relative_path.replace("[]", ""); if clean_path.is_empty() { make_anchor(parent_type) } else { make_anchor(&format!("{}.{}", parent_type, clean_path)) } } else { // At config root - anchor points to config section property // e.g., .monitors[] -> "monitors" (template IDs don't have []) // Remove all bracket notation for config paths let clean_path = path .trim_start_matches('.') .replace("[]", "") .replace("[", "-") .replace("]", ""); make_anchor(&clean_path) }; let usage = ConfigUsage { path: if path.is_empty() { ".".to_string() } else { path.clone() }, anchor, }; usages.entry(type_name.clone()).or_default().push(usage); // Follow the $ref into the type definition (if not already visited) // When following, we enter the new type with an empty relative path if !visited.contains(&type_name) && let Some(def) = defs.and_then(|d| d.get(&type_name)) { visited.insert(type_name.clone()); collect_config_usages( def, path, usages, defs, visited, Some(&type_name), String::new(), // Reset relative path when entering new type ); visited.remove(&type_name); // Allow revisiting from different paths } return; // $ref schema has no other content to process } // Recurse into properties if let Some(props) = schema.get("properties").and_then(|v| v.as_object()) { for (prop_name, prop_schema) in props { let new_path = if path.is_empty() { format!(".{}", prop_name) } else { format!("{}.{}", path, prop_name) }; let new_type_relative = if type_relative_path.is_empty() { prop_name.clone() } else { format!("{}.{}", type_relative_path, prop_name) }; collect_config_usages( prop_schema, new_path, usages, defs, visited, current_type, new_type_relative, ); } } // Recurse into array items if let Some(items) = schema.get("items") { let new_path = format!("{}[]", path); // For arrays, the relative path stays the same (items are part of the array property) collect_config_usages( items, new_path, usages, defs, visited, current_type, type_relative_path.clone(), ); } // Recurse into prefixItems (tuples) if let Some(prefix_items) = schema.get("prefixItems").and_then(|v| v.as_array()) { for (i, item) in prefix_items.iter().enumerate() { let new_path = format!("{}[{}]", path, i); collect_config_usages( item, new_path, usages, defs, visited, current_type, type_relative_path.clone(), ); } } // Recurse into anyOf/oneOf/allOf variants // Only add variant indices to path when the variant has properties (will render sub-IDs) // For $ref or primitive variants, the template doesn't render separate IDs for key in ["anyOf", "oneOf", "allOf"] { if let Some(variants) = schema.get(key).and_then(|v| v.as_array()) { for (i, variant) in variants.iter().enumerate() { // Only add variant index if: // 1. We're inside a type (current_type.is_some()) // 2. We're at the type root level (type_relative_path.is_empty()) // 3. The variant has properties (will render sub-IDs in template) let variant_has_properties = variant.get("properties").is_some(); let new_type_relative = if current_type.is_some() && type_relative_path.is_empty() && variant_has_properties { format!("{}[{}]", key, i) } else { type_relative_path.clone() }; collect_config_usages( variant, path.clone(), usages, defs, visited, current_type, new_type_relative, ); } } } // Recurse into patternProperties if let Some(patterns) = schema.get("patternProperties").and_then(|v| v.as_object()) { for (_pattern, prop_schema) in patterns { let new_path = format!("{}[*]", path); collect_config_usages( prop_schema, new_path, usages, defs, visited, current_type, type_relative_path.clone(), ); } } // Recurse into additionalProperties if let Some(additional) = schema.get("additionalProperties") && additional.is_object() { let new_path = format!("{}[*]", path); collect_config_usages( additional, new_path, usages, defs, visited, current_type, type_relative_path.clone(), ); } } /// Collect references to types from within $defs /// /// For each type definition, find all $refs it contains and record them /// as references from that type to the target type. fn collect_type_references(defs: &Map<String, Value>) -> HashMap<String, Vec<TypeReference>> { let mut references: HashMap<String, Vec<TypeReference>> = HashMap::new(); for (def_name, def_schema) in defs { collect_refs_in_schema(def_schema, def_name, &mut references); } // Sort and deduplicate references for ref_list in references.values_mut() { ref_list.sort_by(|a, b| a.type_name.cmp(&b.type_name)); ref_list.dedup_by(|a, b| a.type_name == b.type_name); } references } /// Recursively find all $refs in a schema and record them as references fn collect_refs_in_schema( schema: &Value, source_type: &str, references: &mut HashMap<String, Vec<TypeReference>>, ) { if let Some(ref_path) = schema.get("$ref").and_then(|v| v.as_str()) { let target_type = ref_path.trim_start_matches("#/$defs/").to_string(); if target_type != source_type { // Don't self-reference let reference = TypeReference { type_name: source_type.to_string(), anchor: make_anchor(source_type), // Links to type definition }; references.entry(target_type).or_default().push(reference); } } // Recurse into all nested structures if let Some(obj) = schema.as_object() { for value in obj.values() { collect_refs_in_schema(value, source_type, references); } } if let Some(arr) = schema.as_array() { for value in arr { collect_refs_in_schema(value, source_type, references); } } } /// Build navigation data from a schema value pub fn build_navigation(schema: &Value) -> NavigationData { let mut definitions = Vec::new(); let mut search_index = Vec::new(); // Get $defs for resolving references let defs = schema.get("$defs").and_then(|v| v.as_object()); // Build hierarchical outline from top-level properties let outline = build_outline_tree(schema, defs, "", 0); // Also collect for search index if let Some(props) = schema.get("properties").and_then(|v| v.as_object()) { collect_properties(props, "", &mut search_index); } // Extract definitions from $defs if let Some(defs) = schema.get("$defs").and_then(|v| v.as_object()) { for (name, def) in defs { let anchor = make_anchor(name); let description = def.get("description").and_then(|v| v.as_str()).map(|s| { // Truncate long descriptions for the sidebar if s.len() > 100 { format!("{}...", &s[..97]) } else { s.to_string() } }); definitions.push(DefinitionInfo { name: name.clone(), anchor: anchor.clone(), description, }); search_index.push(SearchEntry { name: name.clone(), path: name.clone(), anchor, entry_type: "definition".to_string(), }); } } // Sort definitions alphabetically definitions.sort_by(|a, b| a.name.to_lowercase().cmp(&b.name.to_lowercase())); // Collect configuration usages (from main schema, following $refs transitively) let mut config_usages: HashMap<String, Vec<ConfigUsage>> = HashMap::new(); let mut visited: HashSet<String> = HashSet::new(); collect_config_usages( schema, String::new(), &mut config_usages, defs, &mut visited, None, // not inside any type yet String::new(), // no type-relative path yet ); // Sort config usages alphabetically by path for usage_list in config_usages.values_mut() { usage_list.sort_by(|a, b| a.path.cmp(&b.path)); } // Collect type references from $defs let type_references = if let Some(defs) = schema.get("$defs").and_then(|v| v.as_object()) { collect_type_references(defs) } else { HashMap::new() }; // Merge into TypeUsages for each type let mut usages: HashMap<String, TypeUsages> = HashMap::new(); if let Some(defs) = schema.get("$defs").and_then(|v| v.as_object()) { for type_name in defs.keys() { usages.insert( type_name.clone(), TypeUsages { config_usages: config_usages.remove(type_name).unwrap_or_default(), type_references: type_references.get(type_name).cloned().unwrap_or_default(), }, ); } } NavigationData { outline, definitions, search_index, usages, } } /// Recursively collect properties for the search index fn collect_properties(props: &Map<String, Value>, prefix: &str, index: &mut Vec<SearchEntry>) { for (name, prop) in props { let path = if prefix.is_empty() { name.clone() } else { format!("{}.{}", prefix, name) }; let anchor = make_anchor(&path); index.push(SearchEntry { name: name.clone(), path: path.clone(), anchor, entry_type: "property".to_string(), }); // Recurse into nested properties if let Some(nested_props) = prop.get("properties").and_then(|v| v.as_object()) { collect_properties(nested_props, &path, index); } // Handle anyOf/oneOf which might contain objects with properties for key in ["anyOf", "oneOf", "allOf"] { if let Some(variants) = prop.get(key).and_then(|v| v.as_array()) { for variant in variants { if let Some(nested_props) = variant.get("properties").and_then(|v| v.as_object()) { collect_properties(nested_props, &path, index); } } } } } } /// Create a URL-safe anchor ID from a name pub fn make_anchor(name: &str) -> String { name.chars() .map(|c| { if c.is_alphanumeric() || c == '-' || c == '_' || c == '[' || c == ']' { c.to_ascii_lowercase() } else if c == '.' || c == ' ' { '-' } else { '_' } }) .collect() } #[cfg(test)] mod tests { use super::*; use serde_json::json; #[test] fn test_render_markdown() { let md = "This is **bold** and `code`"; let html = render_markdown(md); assert!(html.contains("<strong>bold</strong>")); assert!(html.contains("<code>code</code>")); } #[test] fn test_render_markdown_with_links() { let md = "See [docs](https://example.com)"; let html = render_markdown(md); assert!(html.contains("<a href=\"https://example.com\">docs</a>")); } #[test] fn test_prepare_for_template() { let schema = json!({ "title": "Test", "description": "A **bold** description", "properties": { "name": { "description": "The `name` field" } } }); let prepared = prepare_for_template(&schema); assert!(prepared.get("description_html").is_some()); assert!( prepared["description_html"] .as_str() .unwrap() .contains("<strong>bold</strong>") ); assert!(prepared["properties"]["name"]["description_html"].is_string()); } #[test] fn test_make_anchor() { assert_eq!(make_anchor("MyType"), "mytype"); assert_eq!(make_anchor("my.nested.prop"), "my-nested-prop"); assert_eq!(make_anchor("with spaces"), "with-spaces"); assert_eq!(make_anchor("with_underscore"), "with_underscore"); } #[test] fn test_build_navigation() { let schema = json!({ "title": "Test", "$defs": { "TypeA": {"type": "object", "description": "Type A description"}, "TypeB": {"type": "string"} }, "properties": { "config": { "properties": { "nested": {"type": "string"} } } } }); let nav = build_navigation(&schema); assert_eq!(nav.definitions.len(), 2); assert!(nav.definitions.iter().any(|d| d.name == "TypeA")); assert!(nav.definitions.iter().any(|d| d.name == "TypeB")); // Check search index includes properties assert!(nav.search_index.iter().any(|e| e.name == "config")); assert!(nav.search_index.iter().any(|e| e.path == "config.nested")); } #[test] fn test_build_navigation_outline() { let schema = json!({ "title": "Test", "properties": { "zebra": { "type": "string" }, "alpha": { "type": "number" }, "beta": { "type": "boolean" } } }); let nav = build_navigation(&schema); // Should have 3 outline entries assert_eq!(nav.outline.len(), 3); // Should be sorted alphabetically assert_eq!(nav.outline[0].name, "alpha"); assert_eq!(nav.outline[1].name, "beta"); assert_eq!(nav.outline[2].name, "zebra"); // Check anchors assert_eq!(nav.outline[0].anchor, "alpha"); assert_eq!(nav.outline[1].anchor, "beta"); assert_eq!(nav.outline[2].anchor, "zebra"); // Primitive types should have no children assert!(nav.outline[0].children.is_empty()); } #[test] fn test_outline_array_shows_item_properties() { let schema = json!({ "title": "Test", "type": "object", "$defs": { "ChildType": { "type": "object", "properties": { "nested_prop": { "type": "string" } } } }, "properties": { "parent": { "type": "array", "items": { "$ref": "#/$defs/ChildType" } } } }); let nav = build_navigation(&schema); assert_eq!(nav.outline.len(), 1); assert_eq!(nav.outline[0].name, "parent"); // Arrays should show their item type's properties assert_eq!(nav.outline[0].children.len(), 1); assert_eq!(nav.outline[0].children[0].name, "nested_prop"); // The anchor should point to the type definition, not the parent path assert_eq!(nav.outline[0].children[0].anchor, "childtype-nested_prop"); } #[test] fn test_outline_union_type_is_leaf() { // Union types (anyOf with multiple non-null variants) should be leaf nodes let schema = json!({ "title": "Test", "type": "object", "$defs": { "Colour": { "anyOf": [ { "$ref": "#/$defs/Rgb" }, { "$ref": "#/$defs/Hex" } ] }, "Rgb": { "type": "object", "properties": { "r": { "type": "integer" }, "g": { "type": "integer" }, "b": { "type": "integer" } } }, "Hex": { "type": "string" } }, "properties": { "color": { "$ref": "#/$defs/Colour" } } }); let nav = build_navigation(&schema); assert_eq!(nav.outline.len(), 1); assert_eq!(nav.outline[0].name, "color"); // Union type should be a leaf - don't drill into its variants assert!(nav.outline[0].children.is_empty()); } #[test] fn test_outline_unwraps_optional() { let schema = json!({ "title": "Test", "type": "object", "$defs": { "InnerType": { "type": "object", "properties": { "value": { "type": "string" } } } }, "properties": { "optional_obj": { "anyOf": [ { "$ref": "#/$defs/InnerType" }, { "type": "null" } ] } } }); let nav = build_navigation(&schema); assert_eq!(nav.outline[0].name, "optional_obj"); // Optional should be transparent - show InnerType's properties as children assert_eq!(nav.outline[0].children.len(), 1); assert_eq!(nav.outline[0].children[0].name, "value"); } #[test] fn test_outline_one_of_shows_variants_with_title() { let schema = json!({ "title": "Test", "type": "object", "$defs": { "ThemeChoice": { "oneOf": [ { "title": "CatppuccinTheme", "type": "object", "properties": { "name": { "type": "string" }, "accent": { "type": "string" } } }, { "title": "CustomTheme", "type": "object", "properties": { "colors": { "type": "object" }, "font": { "type": "string" } } } ] } }, "properties": { "theme": { "$ref": "#/$defs/ThemeChoice" } } }); let nav = build_navigation(&schema); assert_eq!(nav.outline.len(), 1); assert_eq!(nav.outline[0].name, "theme"); // Should have 2 variant children (one for each oneOf variant) assert_eq!(nav.outline[0].children.len(), 2); // First variant should use title assert_eq!(nav.outline[0].children[0].name, "⊕ CatppuccinTheme"); assert_eq!(nav.outline[0].children[0].children.len(), 2); // name, accent // Anchor should point to the type definition assert_eq!(nav.outline[0].children[0].anchor, "themechoice"); // Second variant assert_eq!(nav.outline[0].children[1].name, "⊕ CustomTheme"); assert_eq!(nav.outline[0].children[1].children.len(), 2); // colors, font } #[test] fn test_outline_one_of_uses_const_discriminator() { let schema = json!({ "title": "Test", "type": "object", "$defs": { "ThemeChoice": { "oneOf": [ { "type": "object", "properties": { "palette": { "const": "Catppuccin" }, "name": { "type": "string" } } }, { "type": "object", "properties": { "palette": { "const": "Base16" }, "name": { "type": "string" } } } ] } }, "properties": { "theme": { "$ref": "#/$defs/ThemeChoice" } } }); let nav = build_navigation(&schema); assert_eq!(nav.outline[0].children.len(), 2); // Should use const value as discriminator assert_eq!(nav.outline[0].children[0].name, "⊕ Catppuccin"); assert_eq!(nav.outline[0].children[1].name, "⊕ Base16"); } #[test] fn test_outline_one_of_fallback_to_variant_n() { let schema = json!({ "title": "Test", "type": "object", "$defs": { "Choice": { "oneOf": [ { "type": "object", "properties": { "option_a": { "type": "string" } } }, { "type": "object", "properties": { "option_b": { "type": "number" } } } ] } }, "properties": { "selection": { "$ref": "#/$defs/Choice" } } }); let nav = build_navigation(&schema); assert_eq!(nav.outline[0].name, "selection"); assert_eq!(nav.outline[0].children.len(), 2); // Without title or const, should use "Variant N" assert_eq!(nav.outline[0].children[0].name, "⊕ Variant 1"); assert_eq!(nav.outline[0].children[1].name, "⊕ Variant 2"); } #[test] fn test_outline_depth_limit() { // Create a deeply nested schema let schema = json!({ "title": "Test", "type": "object", "$defs": { "Level1": { "type": "object", "properties": { "level2": { "$ref": "#/$defs/Level2" } } }, "Level2": { "type": "object", "properties": { "level3": { "$ref": "#/$defs/Level3" } } }, "Level3": { "type": "object", "properties": { "level4": { "$ref": "#/$defs/Level4" } } }, "Level4": { "type": "object", "properties": { "deep": { "type": "string" } } } }, "properties": { "root": { "$ref": "#/$defs/Level1" } } }); let nav = build_navigation(&schema); // Should have root assert_eq!(nav.outline.len(), 1); assert_eq!(nav.outline[0].name, "root"); // Should have level2 as child assert_eq!(nav.outline[0].children.len(), 1); assert_eq!(nav.outline[0].children[0].name, "level2"); // Should have level3 as grandchild assert_eq!(nav.outline[0].children[0].children.len(), 1); assert_eq!(nav.outline[0].children[0].children[0].name, "level3"); // Should stop at max depth (3) - level4 should not have children assert!(nav.outline[0].children[0].children[0].children.is_empty()); } #[test] fn test_config_usages_collection() { let schema = json!({ "title": "Test", "type": "object", "$defs": { "Layout": { "type": "string", "enum": ["horizontal", "vertical"] }, "Workspace": { "type": "object" } }, "properties": { "workspaces": { "type": "array", "items": { "$ref": "#/$defs/Workspace" } }, "default_layout": { "$ref": "#/$defs/Layout" }, "alternate_layout": { "$ref": "#/$defs/Layout" } } }); let nav = build_navigation(&schema); // Layout should have 2 config usages assert!(nav.usages.contains_key("Layout")); let layout_usages = &nav.usages["Layout"]; assert_eq!(layout_usages.config_usages.len(), 2); // Check paths are jq-style and sorted let paths: Vec<&str> = layout_usages .config_usages .iter() .map(|u| u.path.as_str()) .collect(); assert!(paths.contains(&".alternate_layout")); assert!(paths.contains(&".default_layout")); // Workspace should have 1 config usage assert!(nav.usages.contains_key("Workspace")); let workspace_usages = &nav.usages["Workspace"]; assert_eq!(workspace_usages.config_usages.len(), 1); assert_eq!(workspace_usages.config_usages[0].path, ".workspaces[]"); } #[test] fn test_config_usages_anchor_format() { let schema = json!({ "title": "Test", "type": "object", "$defs": { "MyType": { "type": "string" } }, "properties": { "my_field": { "$ref": "#/$defs/MyType" } } }); let nav = build_navigation(&schema); let usages = &nav.usages["MyType"]; assert_eq!(usages.config_usages.len(), 1); // Anchor should NOT have leading dash assert_eq!(usages.config_usages[0].anchor, "my_field"); // Path should have leading dot assert_eq!(usages.config_usages[0].path, ".my_field"); } #[test] fn test_config_usages_jq_path_format() { let schema = json!({ "title": "Test", "type": "object", "$defs": { "Config": { "type": "object" } }, "properties": { "monitors": { "type": "array", "items": { "type": "object", "properties": { "workspaces": { "type": "array", "items": { "type": "object", "properties": { "config": { "$ref": "#/$defs/Config" } } } } } } } } }); let nav = build_navigation(&schema); assert!(nav.usages.contains_key("Config")); let config_usages = &nav.usages["Config"]; assert_eq!(config_usages.config_usages.len(), 1); // Should have full jq-style path assert_eq!( config_usages.config_usages[0].path, ".monitors[].workspaces[].config" ); // Anchor should match template ID format (no [] brackets, dots become dashes) assert_eq!( config_usages.config_usages[0].anchor, "monitors-workspaces-config" ); } #[test] fn test_type_references_collected() { let schema = json!({ "title": "Test", "type": "object", "$defs": { "MatchingStrategy": { "type": "string", "enum": ["Equals", "Contains"] }, "IdWithIdentifier": { "type": "object", "properties": { "id": { "type": "string" }, "matching_strategy": { "anyOf": [ { "$ref": "#/$defs/MatchingStrategy" }, { "type": "null" } ] } } } }, "properties": { "rules": { "type": "array", "items": { "$ref": "#/$defs/IdWithIdentifier" } } } }); let nav = build_navigation(&schema); // MatchingStrategy now has transitive config usages (through IdWithIdentifier) let matching_strategy = &nav.usages["MatchingStrategy"]; assert_eq!(matching_strategy.config_usages.len(), 1); assert_eq!( matching_strategy.config_usages[0].path, ".rules[].matching_strategy" ); // It should also have a type reference from IdWithIdentifier assert_eq!(matching_strategy.type_references.len(), 1); assert_eq!( matching_strategy.type_references[0].type_name, "IdWithIdentifier" ); assert_eq!( matching_strategy.type_references[0].anchor, "idwithidentifier" ); // IdWithIdentifier has config usages let id_with_identifier = &nav.usages["IdWithIdentifier"]; assert_eq!(id_with_identifier.config_usages.len(), 1); assert_eq!(id_with_identifier.config_usages[0].path, ".rules[]"); } #[test] fn test_type_with_both_usages() { let schema = json!({ "title": "Test", "type": "object", "$defs": { "Colour": { "type": "object", "properties": { "r": { "type": "integer" }, "g": { "type": "integer" }, "b": { "type": "integer" } } }, "Theme": { "type": "object", "properties": { "primary": { "$ref": "#/$defs/Colour" }, "secondary": { "$ref": "#/$defs/Colour" } } } }, "properties": { "background": { "$ref": "#/$defs/Colour" }, "theme": { "$ref": "#/$defs/Theme" } } }); let nav = build_navigation(&schema); // Colour has config usages: direct (background) and transitive through Theme let colour = &nav.usages["Colour"]; assert_eq!(colour.config_usages.len(), 3); // Find usages by path and verify anchors let background_usage = colour .config_usages .iter() .find(|u| u.path == ".background") .expect("should have .background usage"); // Direct usage at config root -> anchor is "background" assert_eq!(background_usage.anchor, "background"); let primary_usage = colour .config_usages .iter() .find(|u| u.path == ".theme.primary") .expect("should have .theme.primary usage"); // Transitive through Theme -> anchor points to Theme's property: "theme-primary" assert_eq!(primary_usage.anchor, "theme-primary"); let secondary_usage = colour .config_usages .iter() .find(|u| u.path == ".theme.secondary") .expect("should have .theme.secondary usage"); // Transitive through Theme -> anchor points to Theme's property: "theme-secondary" assert_eq!(secondary_usage.anchor, "theme-secondary"); // Also has type reference from Theme assert_eq!(colour.type_references.len(), 1); assert_eq!(colour.type_references[0].type_name, "Theme"); } #[test] fn test_anchor_links_match_property_ids() { // Verify that anchors generated for config usages match the IDs generated by the template // Template uses: id="{{ path | lower | replace(from=".", to="-") }}" let schema = json!({ "title": "Test", "type": "object", "$defs": { "Type1": { "type": "string" }, "Type2": { "type": "string" } }, "properties": { "simple_field": { "$ref": "#/$defs/Type1" }, "nested": { "type": "object", "properties": { "inner_field": { "$ref": "#/$defs/Type2" } } } } }); let nav = build_navigation(&schema); // simple_field: path=simple_field, template ID=simple_field let type1 = &nav.usages["Type1"]; assert_eq!(type1.config_usages[0].anchor, "simple_field"); // nested.inner_field: path=nested.inner_field, template ID=nested-inner_field let type2 = &nav.usages["Type2"]; assert_eq!(type2.config_usages[0].anchor, "nested-inner_field"); } #[test] fn test_transitive_config_usages() { // Types nested inside other types should show their full Configuration path let schema = json!({ "title": "Test", "type": "object", "$defs": { "MonitorConfig": { "type": "object", "properties": { "name": { "type": "string" }, "workspaces": { "type": "array", "items": { "$ref": "#/$defs/WorkspaceConfig" } } } }, "WorkspaceConfig": { "type": "object", "properties": { "name": { "type": "string" }, "layout": { "$ref": "#/$defs/Layout" } } }, "Layout": { "type": "string", "enum": ["horizontal", "vertical"] } }, "properties": { "monitors": { "type": "array", "items": { "$ref": "#/$defs/MonitorConfig" } } } }); let nav = build_navigation(&schema); // MonitorConfig should have direct usage at config root // Anchor points to "monitors" in the Configuration section (no [] in IDs) let monitor_usages = &nav.usages["MonitorConfig"]; assert_eq!(monitor_usages.config_usages.len(), 1); assert_eq!(monitor_usages.config_usages[0].path, ".monitors[]"); assert_eq!(monitor_usages.config_usages[0].anchor, "monitors"); // WorkspaceConfig should have transitive usage through MonitorConfig // Anchor points to "monitorconfig-workspaces" (property in MonitorConfig type definition) let workspace_usages = &nav.usages["WorkspaceConfig"]; assert_eq!(workspace_usages.config_usages.len(), 1); assert_eq!( workspace_usages.config_usages[0].path, ".monitors[].workspaces[]" ); assert_eq!( workspace_usages.config_usages[0].anchor, "monitorconfig-workspaces" ); // Layout should have transitive usage through WorkspaceConfig // Anchor points to "workspaceconfig-layout" (property in WorkspaceConfig type definition) let layout_usages = &nav.usages["Layout"]; assert_eq!(layout_usages.config_usages.len(), 1); assert_eq!( layout_usages.config_usages[0].path, ".monitors[].workspaces[].layout" ); assert_eq!( layout_usages.config_usages[0].anchor, "workspaceconfig-layout" ); } #[test] fn test_recursive_type_no_infinite_loop() { // Recursive types should not cause infinite loops let schema = json!({ "title": "Test", "type": "object", "$defs": { "Node": { "type": "object", "properties": { "value": { "type": "string" }, "children": { "type": "array", "items": { "$ref": "#/$defs/Node" } } } } }, "properties": { "root": { "$ref": "#/$defs/Node" } } }); let nav = build_navigation(&schema); // Should complete without hanging let node_usages = &nav.usages["Node"]; // Node should have at least the direct usage at .root assert!(node_usages.config_usages.len() >= 1); assert!(node_usages.config_usages.iter().any(|u| u.path == ".root")); } #[test] fn test_same_type_multiple_paths() { // A type used in multiple places should show all paths let schema = json!({ "title": "Test", "type": "object", "$defs": { "Colour": { "type": "object", "properties": { "r": { "type": "integer" }, "g": { "type": "integer" }, "b": { "type": "integer" } } }, "Theme": { "type": "object", "properties": { "primary": { "$ref": "#/$defs/Colour" }, "secondary": { "$ref": "#/$defs/Colour" } } } }, "properties": { "background": { "$ref": "#/$defs/Colour" }, "foreground": { "$ref": "#/$defs/Colour" }, "theme": { "$ref": "#/$defs/Theme" } } }); let nav = build_navigation(&schema); // Colour should have 4 config usages: // - .background (direct) // - .foreground (direct) // - .theme.primary (transitive through Theme) // - .theme.secondary (transitive through Theme) let colour_usages = &nav.usages["Colour"]; assert_eq!(colour_usages.config_usages.len(), 4); let paths: Vec<&str> = colour_usages .config_usages .iter() .map(|u| u.path.as_str()) .collect(); assert!(paths.contains(&".background")); assert!(paths.contains(&".foreground")); assert!(paths.contains(&".theme.primary")); assert!(paths.contains(&".theme.secondary")); } #[test] fn test_oneof_with_object_variants_anchor() { // oneOf types where variants have properties should include variant index in anchor // This matches template behavior: KomorebiTheme.oneOf[0].bar_accent -> komorebitheme-oneof[0]-bar_accent let schema = json!({ "title": "Test", "type": "object", "$defs": { "Colour": { "type": "string" }, "Theme": { "oneOf": [ { "type": "object", "properties": { "primary": { "$ref": "#/$defs/Colour" }, "name": { "type": "string", "const": "light" } } }, { "type": "object", "properties": { "primary": { "$ref": "#/$defs/Colour" }, "name": { "type": "string", "const": "dark" } } } ] } }, "properties": { "theme": { "$ref": "#/$defs/Theme" } } }); let nav = build_navigation(&schema); // Colour should have 2 usages - one from each oneOf variant let colour_usages = &nav.usages["Colour"]; assert_eq!(colour_usages.config_usages.len(), 2); // Both should have oneOf[N] in the anchor since variants have properties let anchors: Vec<&str> = colour_usages .config_usages .iter() .map(|u| u.anchor.as_str()) .collect(); assert!(anchors.contains(&"theme-oneof[0]-primary")); assert!(anchors.contains(&"theme-oneof[1]-primary")); } #[test] fn test_anyof_type_union_anchor() { // anyOf types that are pure type unions (no properties in variants) should use type anchor // e.g., Colour = Hex | Rgb - anchor should be "colour", not "colour-anyof[0]" let schema = json!({ "title": "Test", "type": "object", "$defs": { "Hex": { "type": "string", "format": "hex" }, "Rgb": { "type": "object", "properties": { "r": { "type": "integer" }, "g": { "type": "integer" }, "b": { "type": "integer" } } }, "Colour": { "anyOf": [ { "$ref": "#/$defs/Hex" }, { "$ref": "#/$defs/Rgb" } ] } }, "properties": { "background": { "$ref": "#/$defs/Colour" } } }); let nav = build_navigation(&schema); // Hex and Rgb should have usages through Colour // Since Colour's anyOf variants are just $refs (no properties), anchor should be "colour" let hex_usages = &nav.usages["Hex"]; assert_eq!(hex_usages.config_usages.len(), 1); assert_eq!(hex_usages.config_usages[0].path, ".background"); assert_eq!(hex_usages.config_usages[0].anchor, "colour"); let rgb_usages = &nav.usages["Rgb"]; assert_eq!(rgb_usages.config_usages.len(), 1); assert_eq!(rgb_usages.config_usages[0].path, ".background"); assert_eq!(rgb_usages.config_usages[0].anchor, "colour"); } #[test] fn test_nested_oneof_in_property_no_variant_index() { // Properties with anyOf (like optional values) should NOT add variant index // e.g., MonitorConfig.wallpaper which is anyOf[Wallpaper, null] -> anchor is "monitorconfig-wallpaper" let schema = json!({ "title": "Test", "type": "object", "$defs": { "Wallpaper": { "type": "object", "properties": { "path": { "type": "string" } } }, "MonitorConfig": { "type": "object", "properties": { "wallpaper": { "anyOf": [ { "$ref": "#/$defs/Wallpaper" }, { "type": "null" } ] } } } }, "properties": { "monitor": { "$ref": "#/$defs/MonitorConfig" } } }); let nav = build_navigation(&schema); // Wallpaper should have usage through MonitorConfig.wallpaper // The anyOf is within a property, so NO variant index in anchor let wallpaper_usages = &nav.usages["Wallpaper"]; assert_eq!(wallpaper_usages.config_usages.len(), 1); assert_eq!(wallpaper_usages.config_usages[0].path, ".monitor.wallpaper"); assert_eq!( wallpaper_usages.config_usages[0].anchor, "monitorconfig-wallpaper" ); } #[test] fn test_array_path_strips_brackets_in_anchor() { // Array paths like .monitors[] should have anchor "monitors" (no brackets) // Template IDs don't include [] notation let schema = json!({ "title": "Test", "type": "object", "$defs": { "Item": { "type": "string" } }, "properties": { "items": { "type": "array", "items": { "$ref": "#/$defs/Item" } } } }); let nav = build_navigation(&schema); let item_usages = &nav.usages["Item"]; assert_eq!(item_usages.config_usages.len(), 1); assert_eq!(item_usages.config_usages[0].path, ".items[]"); // Anchor should NOT have brackets assert_eq!(item_usages.config_usages[0].anchor, "items"); } }