Skip to content

Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows

17.9 KB
Raw Blame
//! Nested schema-unknown analysis for worktrunk config files.
//!
//! A round-trip through a [`WorktrunkConfig`] type answers "which keys does
//! serde silently drop?": reserializing the parsed config and diffing against
//! the raw TOML identifies every schema-unknown path at any nesting depth.
//!
//! The tree drives unknown-key warnings (`warn_unknown_fields`, `config show`),
//! which emit one message at the shallowest level where a path is unknown.

use std::collections::{BTreeMap, BTreeSet};

use crate::config::WorktrunkConfig;

/// A nested set of schema-unknown paths within a config file.
///
/// `keys` holds unknown keys at the current level, each covering its whole
/// subtree. Entries in `nested` are for keys that are themselves *known* but
/// contain unknown children.
#[derive(Default, Debug, Clone)]
pub struct UnknownTree {
    pub keys: BTreeSet<String>,
    pub nested: BTreeMap<String, UnknownTree>,
}

impl UnknownTree {
    pub fn is_empty(&self) -> bool {
        self.keys.is_empty() && self.nested.is_empty()
    }
}

/// Analyze `contents` against config type `C` by round-tripping through serde.
///
/// `None` when `contents` is unparsable or fails type-checking against `C`
/// (e.g., a hand edit like `commit = "scalar"`): schema-unknown paths can't be
/// told from schema-known-but-wrong-type ones, so warning callers stay silent
/// and leave the error to the regular load path, which reports it with line
/// and column.
///
/// Otherwise the returned tree captures every path in `contents` that
/// reserialization drops — i.e., every schema-unknown path. Top-level keys
/// that serialize away when empty (e.g., `[merge]` with only unknown children
/// leaves `MergeConfig::default()`, which `skip_serializing_if` omits) are
/// rescued by seeding the comparison with the JsonSchema key list: a known
/// section that isn't in the reserialized form is treated as present-but-empty
/// so only its unknown *children* get flagged, not the section itself.
pub fn compute_unknown_tree<C>(contents: &str) -> Option<UnknownTree>
where
    C: WorktrunkConfig,
{
    let raw = contents.parse::<toml::Table>().ok()?;
    let config: C = toml::Value::Table(raw.clone()).try_into().ok()?;

    let mut reserialized: toml::Table = toml::to_string(&config)
        .expect("config type is serializable")
        .parse()
        .expect("serialized config is valid TOML");
    seed_schema_skeleton::<C>(&mut reserialized);
    Some(diff_tables(&raw, &reserialized))
}

/// Seed `reserialized` with every schema-valid top-level key as an empty
/// table so `diff_tables` treats valid-but-omitted sections as known, then do
/// the same one level down inside each entry of the scoped map
/// ([`WorktrunkConfig::valid_scoped_keys`] — `projects` in user config).
///
/// Both levels need it for the same reason: a section equal to its default is
/// skipped during serialization, so it is missing from the round-tripped view
/// `diff_tables` compares against and would be reported as unknown.
fn seed_schema_skeleton<C: WorktrunkConfig>(reserialized: &mut toml::Table) {
    seed_keys(reserialized, C::valid_top_level_keys());

    // The top-level pass above already put `scope_key` in place as an empty
    // table where the round-trip omitted it, so this lookup finds the scoped
    // map whether or not any entry survived serialization.
    if let Some((scope_key, entry_keys)) = C::valid_scoped_keys()
        && let Some(toml::Value::Table(entries)) = reserialized.get_mut(scope_key)
    {
        for (_, entry) in entries.iter_mut() {
            if let toml::Value::Table(entry_table) = entry {
                seed_keys(entry_table, entry_keys);
            }
        }
    }
}

fn seed_keys(table: &mut toml::Table, keys: &[String]) {
    for key in keys {
        table
            .entry(key.clone())
            .or_insert_with(|| toml::Value::Table(toml::Table::new()));
    }
}

/// Walk `raw` against `known` (the schema-projected view) and record keys
/// that exist only in `raw`. Recurses into nested tables so deeply-nested
/// unknown keys are captured at the right level.
fn diff_tables(raw: &toml::Table, known: &toml::Table) -> UnknownTree {
    let mut tree = UnknownTree::default();
    for (key, raw_val) in raw {
        match (known.get(key), raw_val) {
            (Some(toml::Value::Table(known_t)), toml::Value::Table(raw_t)) => {
                let nested = diff_tables(raw_t, known_t);
                if !nested.is_empty() {
                    tree.nested.insert(key.clone(), nested);
                }
            }
            (Some(_), _) => {}
            (None, _) => {
                tree.keys.insert(key.clone());
            }
        }
    }
    tree
}

/// Structured description of a single unknown-key finding. Callers format
/// these into warning strings — the `deprecation` and `config show` paths
/// use different wording, so classification stays here and presentation
/// stays at the call site.
#[derive(Debug)]
pub enum UnknownWarning {
    /// A top-level key that's not in any schema. Fully unknown.
    TopLevelUnknown { key: String },
    /// A top-level key that's valid in the *other* config type (e.g.,
    /// `forge` appearing in user config).
    TopLevelWrongConfig {
        key: String,
        other_description: &'static str,
    },
    /// A top-level key that's deprecated and whose canonical form belongs in
    /// the other config (e.g., `[commit-generation]` in project config).
    TopLevelDeprecatedWrongConfig {
        key: String,
        other_description: &'static str,
        canonical_display: &'static str,
    },
    /// A nested key, valid in the *other* config type, found below a
    /// schema-valid shared section (e.g. `commit.generation.command` in
    /// project config — the `[commit.generation]` section is valid there for
    /// `template-append`, but the LLM command/templates belong in user
    /// config).
    NestedWrongConfig {
        path: String,
        other_description: &'static str,
    },
    /// An unknown path below a schema-valid top-level key — a typo, e.g.
    /// `merge.squas`.
    NestedUnknown { path: String },
}

/// Position within `C::Other`'s unknown tree while walking `C`'s nested
/// unknowns. A nested key that's schema-unknown in `C` but *valid* in
/// `C::Other` (e.g. `list.columns` — a user-config display setting — placed in
/// project config) should redirect there rather than read "unknown field". We
/// answer "is this leaf valid in the other config?" by walking the other
/// config's unknown tree in lockstep: a key valid there never appears in that
/// tree, so its absence is the signal.
#[derive(Clone, Copy)]
enum OtherStatus<'a> {
    /// An ancestor section is absent or wholly unknown in `C::Other`, so
    /// nothing at or below this point is valid there.
    UnknownSection,
    /// Within a section that exists in `C::Other`. Carries the corresponding
    /// node in the other tree, or `None` once no further unknowns are recorded
    /// — i.e. every key at or below here is valid in the other config.
    Known(Option<&'a UnknownTree>),
}

impl<'a> OtherStatus<'a> {
    /// Whether `key` at the current level is a valid key in `C::Other`.
    fn key_is_valid_in_other(self, key: &str) -> bool {
        match self {
            OtherStatus::UnknownSection => false,
            OtherStatus::Known(None) => true,
            OtherStatus::Known(Some(node)) => !node.keys.contains(key),
        }
    }

    /// Descend into `key`, returning the status for its children.
    fn descend(self, key: &str) -> OtherStatus<'a> {
        match self {
            OtherStatus::UnknownSection => OtherStatus::UnknownSection,
            OtherStatus::Known(None) => OtherStatus::Known(None),
            OtherStatus::Known(Some(node)) => {
                if node.keys.contains(key) {
                    // Whole subtree is unknown in the other config too.
                    OtherStatus::UnknownSection
                } else {
                    OtherStatus::Known(node.nested.get(key))
                }
            }
        }
    }
}

/// Collect structured warnings for `raw_contents` under config type `C`.
///
/// Top-level classification reads the *raw* tree (so deprecated top-level
/// sections surface informative messages like "belongs in user config as
/// `[commit.generation]`"). Nested classification reads the *migrated* tree,
/// so patterns the deprecation system already warns about (e.g.,
/// `switch.no-cd`, `merge.no-ff`) don't double-warn here.
///
/// A misplaced *nested* key is redirected to `C::Other` when it's valid there
/// — determined by walking `C::Other`'s own unknown tree for the same content
/// (see the private `OtherStatus` helper). If the content doesn't parse as
/// `C::Other`, the walk falls back to treating nested keys as unknown, so only
/// the hard-coded
/// [`nested_key_belongs_in`](crate::config::nested_key_belongs_in) redirects
/// still fire.
///
/// A deprecated top-level section is left to the deprecation channel only
/// when migration removed it; one that survived non-empty is reported here
/// (see the private `deprecated_key_declined` helper).
///
/// Returns an empty vec if the raw or migrated content doesn't parse as `C` —
/// the load path surfaces parse/type errors elsewhere.
pub fn collect_unknown_warnings<C: WorktrunkConfig>(raw_contents: &str) -> Vec<UnknownWarning> {
    let Some(raw_tree) = compute_unknown_tree::<C>(raw_contents) else {
        return Vec::new();
    };
    let migrated = crate::config::migrate_content(raw_contents);
    let Some(migrated_tree) = compute_unknown_tree::<C>(&migrated) else {
        return Vec::new();
    };
    // `compute_unknown_tree` returned a tree above, so this parse cannot
    // fail; the fallback just keeps the path panic-free.
    let migrated_root = migrated.parse::<toml::Table>().unwrap_or_default();
    // The same content viewed as the *other* config type: a nested key absent
    // from this tree is valid there. No tree → no generalized redirect.
    let other_tree = compute_unknown_tree::<C::Other>(&migrated);
    let other_root = match &other_tree {
        Some(t) => OtherStatus::Known(Some(t)),
        None => OtherStatus::UnknownSection,
    };

    let mut out = Vec::new();
    for key in &raw_tree.keys {
        use crate::config::UnknownKeyKind;
        let warning = match crate::config::classify_unknown_key::<C>(key) {
            UnknownKeyKind::DeprecatedHandled if deprecated_key_declined(&migrated_root, key) => {
                UnknownWarning::TopLevelUnknown { key: key.clone() }
            }
            UnknownKeyKind::DeprecatedHandled => continue,
            UnknownKeyKind::DeprecatedWrongConfig {
                other_description,
                canonical_display,
            } => UnknownWarning::TopLevelDeprecatedWrongConfig {
                key: key.clone(),
                other_description,
                canonical_display,
            },
            UnknownKeyKind::WrongConfig { other_description } => {
                UnknownWarning::TopLevelWrongConfig {
                    key: key.clone(),
                    other_description,
                }
            }
            UnknownKeyKind::Unknown => UnknownWarning::TopLevelUnknown { key: key.clone() },
        };
        out.push(warning);
    }
    for (key, sub) in &migrated_tree.nested {
        if !C::is_valid_key(key) {
            continue; // top-level unknowns were classified above against raw
        }
        walk_nested::<C>(sub, key, other_root.descend(key), &mut out);
    }
    out
}

/// Whether `key` — a registered deprecated section — still carries config
/// after migration.
///
/// [`classify_unknown_key`](crate::config::classify_unknown_key) answers from
/// the registry alone: the name is deprecated, so the deprecation channel owns
/// the message. That holds only when the rewrite actually ran. A migration
/// that declines — a malformed scalar (`select = "x"`), a destination already
/// occupied — deliberately leaves the key in place and emits nothing, and the
/// documented handoff is for the unknown-field message to speak instead. Left
/// suppressed, the setting is read by nobody and reported by no one.
///
/// An empty deprecated section is the one survivor that stays silent: it
/// contributes no config, which is why the migration leaves it alone in the
/// first place.
fn deprecated_key_declined(migrated: &toml::Table, key: &str) -> bool {
    match migrated.get(key) {
        Some(toml::Value::Table(t)) => !t.is_empty(),
        Some(_) => true,
        None => false,
    }
}

fn walk_nested<C: WorktrunkConfig>(
    tree: &UnknownTree,
    prefix: &str,
    other: OtherStatus,
    out: &mut Vec<UnknownWarning>,
) {
    for key in &tree.keys {
        let path = format!("{prefix}.{key}");
        // Hard-coded redirects (commit.generation leaves) take precedence and
        // fire even when the content doesn't parse as the other config; otherwise
        // fall back to the general "valid in the other config" check.
        let belongs = crate::config::nested_key_belongs_in::<C>(&path)
            .or_else(|| other.key_is_valid_in_other(key).then(C::Other::description));
        out.push(match belongs {
            Some(other_description) => UnknownWarning::NestedWrongConfig {
                path,
                other_description,
            },
            None => UnknownWarning::NestedUnknown { path },
        });
    }
    for (key, sub) in &tree.nested {
        let path = format!("{prefix}.{key}");
        walk_nested::<C>(sub, &path, other.descend(key), out);
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::config::{ProjectConfig, UserConfig};

    fn parsed<C: WorktrunkConfig>(contents: &str) -> UnknownTree {
        compute_unknown_tree::<C>(contents).expect("contents should parse as C")
    }

    #[test]
    fn empty_input_has_no_unknowns() {
        let tree = parsed::<UserConfig>("");
        assert!(tree.is_empty());
    }

    #[test]
    fn known_keys_are_not_flagged() {
        let tree = parsed::<UserConfig>(
            r#"
worktree-path = "../test"

[list]
full = true

[commit.generation]
command = "llm"
"#,
        );
        assert!(tree.is_empty(), "tree should be empty, got {tree:?}");
    }

    #[test]
    fn unknown_top_level_key() {
        let tree = parsed::<UserConfig>("unknown-key = \"value\"\n");
        assert!(tree.keys.contains("unknown-key"));
        assert!(tree.nested.is_empty());
    }

    #[test]
    fn nested_unknown_key_under_known_section() {
        let tree = parsed::<UserConfig>(
            r#"
[merge]
future-option = true
"#,
        );
        assert!(tree.keys.is_empty());
        let merge = tree.nested.get("merge").expect("merge subtree");
        assert!(merge.keys.contains("future-option"));
    }

    #[test]
    fn deeply_nested_unknown_key() {
        let tree = parsed::<UserConfig>(
            r#"
[commit.generation]
command = "llm"
future-knob = "x"
"#,
        );
        let commit = tree.nested.get("commit").expect("commit subtree");
        let generation = commit.nested.get("generation").expect("generation subtree");
        assert!(generation.keys.contains("future-knob"));
    }

    #[test]
    fn unknown_whole_subtree_is_marked_at_top_level() {
        // A wholly-unknown section records the key at its parent level,
        // which is what warning emitters want — one message for the whole
        // subtree, not one per descendant.
        let tree = parsed::<UserConfig>(
            r#"
[unknown-section]
a = 1
b = 2
"#,
        );
        assert!(tree.keys.contains("unknown-section"));
    }

    #[test]
    fn project_config_detects_user_only_key() {
        let tree = parsed::<ProjectConfig>("skip-shell-integration-prompt = true\n");
        assert!(tree.keys.contains("skip-shell-integration-prompt"));
    }

    #[test]
    fn empty_per_project_section_is_known() {
        // `[projects."<id>".list]` is valid and accepted on load. It equals
        // its default, so it serializes away and is missing from the
        // round-trip — the skeleton has to put it back one level down too.
        let tree = parsed::<UserConfig>("[projects.\"example.com/org/repo\".list]\n");
        assert!(tree.is_empty(), "unexpected unknown keys: {tree:?}");
        assert!(
            collect_unknown_warnings::<UserConfig>("[projects.\"example.com/org/repo\".list]\n")
                .is_empty()
        );
    }

    #[test]
    fn unknown_key_in_per_project_scope_still_warns() {
        // The skeleton seeds only schema-valid keys, so a genuine unknown in
        // the same scope keeps its warning — as does one nested inside a
        // known section, and a user key that has no per-project form.
        for (content, expected) in [
            (
                "[projects.\"example.com/org/repo\".nonsense]\n",
                "projects.example.com/org/repo.nonsense",
            ),
            (
                "[projects.\"example.com/org/repo\".list]\nbogus = 1\n",
                "projects.example.com/org/repo.list.bogus",
            ),
            (
                "[projects.\"example.com/org/repo\"]\nskip-shell-integration-prompt = true\n",
                "projects.example.com/org/repo.skip-shell-integration-prompt",
            ),
        ] {
            let warnings = collect_unknown_warnings::<UserConfig>(content);
            assert!(
                warnings.iter().any(|w| matches!(
                    w,
                    UnknownWarning::NestedUnknown { path } if path == expected
                )),
                "expected {expected} to warn, got {warnings:?} for:\n{content}"
            );
        }
    }

    #[test]
    fn syntax_error_yields_no_tree() {
        assert!(compute_unknown_tree::<UserConfig>("not valid {{{").is_none());
    }

    #[test]
    fn type_mismatch_yields_no_tree() {
        // A hand-edit like `commit = "scalar"` can't round-trip through
        // UserConfig; the parse error is surfaced elsewhere.
        let tree = compute_unknown_tree::<UserConfig>(
            r#"
commit = "scalar"
skip-shell-integration-prompt = true
"#,
        );
        assert!(tree.is_none());
    }
}