Clarify constructor failures and borrowed API contracts

crates/ferese-config/src/activities.rs

@@ -77,7 +77,7 @@ pub struct Matched {
     pub group: Option<String>,
 }
 impl Matcher {
-    pub fn new(settings: &Settings) -> Result<Self, String> {
+    pub fn try_new(settings: &Settings) -> Result<Self, String> {
         let mut rules = Vec::new();
         for rule in &settings.rules {
             let regex = regex::RegexBuilder::new(&rule.pattern)
@@ -167,6 +167,7 @@ fn validate_rule(rule: &Rule, regex: &Regex) -> Result<(), String> {
     Ok(())
 }
 impl Settings {
+    #[must_use]
     pub fn limits(&self) -> ferese_activities::Limits {
         ferese_activities::Limits {
             max_visible: self.max_visible,
@@ -191,7 +192,7 @@ impl Settings {
         if self.rules.iter().any(|rule| !names.insert(&rule.name)) {
             return Err("duplicate activity rule".into());
         }
-        Matcher::new(self).map(|_| ())
+        Matcher::try_new(self).map(|_| ())
     }
 }
 
@@ -397,7 +398,7 @@ mod tests {
         let settings = Settings::default();
         assert!(!settings.sources.shell_hook);
         assert!(!settings.sources.process_watch);
-        let matcher = Matcher::new(&settings).unwrap();
+        let matcher = Matcher::try_new(&settings).unwrap();
         assert!(matcher.matches("secret command", "/tmp", &[]).is_none());
         let matched = matcher.matches("cargo test", "/tmp", &[]).unwrap();
         assert_eq!(matched.title, "cargo test");

crates/ferese-config/src/document.rs

@@ -33,10 +33,12 @@ pub fn config_path() -> Option<PathBuf> {
         .map(|p| p.join("ferese/config.kdl"))
 }
 
+#[must_use]
 pub fn default_wallpaper() -> &'static str {
     default_wallpaper_for(theme::Appearance::Dark)
 }
 
+#[must_use]
 pub fn default_wallpaper_for(appearance: theme::Appearance) -> &'static str {
     static LIGHT: std::sync::OnceLock<String> = std::sync::OnceLock::new();
     static DARK: std::sync::OnceLock<String> = std::sync::OnceLock::new();
@@ -292,11 +294,13 @@ impl Document {
         Ok(Self { doc, value })
     }
 
+    #[must_use]
     pub fn value(&self) -> &Value {
         &self.value
     }
 
     /// A runtime view; the original KDL remains available for comment-preserving edits.
+    #[must_use]
     pub fn with_theme(&self, theme: &theme::ResolvedTheme) -> Self {
         let mut document = self.clone();
         document.value["theme"] =
@@ -305,6 +309,7 @@ impl Document {
         document
     }
 
+    #[must_use]
     pub fn get(&self, path: &str) -> Option<&Value> {
         let mut value = &self.value;
 

crates/ferese-config/src/families.rs

@@ -30,6 +30,7 @@ pub const BUILTINS: [(&str, &str, &str, &str); 6] = [
     ),
 ];
 
+#[must_use]
 pub fn family_id(preset: &str) -> &str {
     BUILTINS
         .iter()
@@ -37,6 +38,7 @@ pub fn family_id(preset: &str) -> &str {
         .map_or(preset, |row| row.0)
 }
 
+#[must_use]
 pub fn variant(id: &str, appearance: Appearance) -> Option<&'static str> {
     if let Some(row) = BUILTINS.iter().find(|row| row.0 == id) {
         return Some(if appearance == Appearance::Light {
@@ -54,6 +56,7 @@ pub fn variant(id: &str, appearance: Appearance) -> Option<&'static str> {
     }
 }
 
+#[must_use]
 pub fn builtins() -> Vec<Family> {
     BUILTINS
         .iter()

crates/ferese-config/src/file.rs

@@ -58,6 +58,7 @@ impl ConfigFile {
         Ok(file)
     }
 
+    #[must_use]
     pub fn source(&self) -> &str {
         &self.source
     }

crates/ferese-config/src/theme.rs

@@ -208,6 +208,7 @@ impl Default for Policy {
     }
 }
 
+#[must_use]
 pub fn default_tokens() -> Tokens {
     serde_json::from_value(json!({
             "colors": {"surface_base":"#111821", "surface_raised":"#1E2530", "application_background":"#171E27", "text_primary":"#F4F7FB", "text_muted":"#8793A2",
@@ -224,6 +225,7 @@ pub fn default_tokens() -> Tokens {
         .expect("valid built-in theme")
 }
 
+#[must_use]
 pub fn default_theme() -> ResolvedTheme {
     let mut tokens = default_tokens();
     resolve_gradients(&mut tokens, None);
@@ -527,6 +529,7 @@ pub fn resolve_with_context(
     })
 }
 
+#[must_use]
 pub fn theme_path(directory: &Path, path: &Path) -> PathBuf {
     let path = if let Some(tail) = path.to_str().and_then(|path| path.strip_prefix("~/")) {
         std::env::var_os("HOME")
@@ -690,6 +693,7 @@ pub fn preset(name: &str, appearance: Appearance) -> Result<Tokens, String> {
     Ok(t)
 }
 
+#[must_use]
 pub fn authored_warnings(tokens: &Tokens) -> Vec<String> {
     if let Err(error) = validate(tokens) {
         return vec![error];