helm-schema-ir 0.0.7

//! Projection: contract claims read off the fragment tree.
//!
//! A value use is one `(values_path, yaml_path, condition)` claim: splices and
//! taint attribute at their tree position with the root-to-leaf conditions
//! projected to the contract predicate vocabulary; pathless reads
//! (conditions, assignment right-hand sides, helper-internal guard reads)
//! carry the condition recorded at their read site. Row facts beyond the
//! claim triple come from the
//! render-site stamps: the containing resource (kept on placed rows, and on
//! site-scoped reads exactly like the previous emission terminal), List-item
//! path rebasing, and source provenance.

use crate::contract::ContractIr;
use crate::{ContractProvenance, ContractUse, Guard, ValueKind, YamlPath};
use helm_schema_core::{GuardDnf, Predicate, dynamic_mapping_value_path, sequence_item_path};

use super::domain::{
    AbstractFragment, AbstractString, EntryKey, Guarded, SiteFacts, Splice, StringPart,
};
use super::eval::EvaluatedDocument;

/// Project an evaluated document into the contract graph.
#[must_use]
pub(crate) fn contract_ir_from_document(document: &EvaluatedDocument) -> ContractIr {
    let mut contract = ContractIr::default();
    let mut conditions = Vec::new();
    walk_guarded(
        &document.root,
        &YamlPath(Vec::new()),
        &mut conditions,
        &mut contract,
        &std::collections::BTreeSet::new(),
        &[],
    );
    for read in &document.reads {
        if read.condition.is_never() {
            continue;
        }
        let row = ContractUse::with_condition_and_provenances(
            read.values_path.clone(),
            YamlPath(Vec::new()),
            read.kind,
            read.condition.clone(),
            read.resource.clone(),
            read.provenance.iter().cloned(),
        );
        if read.dependency {
            contract.push_dependency_use(row);
        } else {
            contract.push(row);
        }
    }
    contract.absorb_observed_facts(&document.observed_facts);
    contract
}

fn walk_guarded(
    guarded: &Guarded<AbstractFragment>,
    path: &YamlPath,
    conditions: &mut Vec<Predicate>,
    contract: &mut ContractIr,
    member_sibling_keys: &std::collections::BTreeSet<String>,
    structural_sibling_conditions: &[Predicate],
) {
    // Sibling MAPPING arms of the same guarded position contribute literal
    // keys to the object a member-level splice completes (`- name: tmp`
    // above a `toYaml .Values.tmpVolume | nindent` action): the splice's
    // provider slot must know them so its object requiredness does not
    // re-demand template-supplied members. Conditional siblings widen the
    // set, which can only relax requiredness, never reject.
    // The presence-abort lane below is different: each sibling retains its
    // execution predicate because `toYaml nil` cannot continue a mapping or
    // sequence that the template already began on that arm.
    let mut sibling_keys = member_sibling_keys.clone();
    for (_, node) in &guarded.arms {
        if let AbstractFragment::Mapping(mapping) = node {
            sibling_keys.extend(mapping.entries.iter().filter_map(|entry| match &entry.key {
                EntryKey::Literal(key) if !key.is_empty() => Some(key.clone()),
                _ => None,
            }));
        }
    }
    let mut sibling_conditions = structural_sibling_conditions.to_vec();
    for (sibling_condition, sibling) in &guarded.arms {
        match sibling {
            AbstractFragment::Mapping(mapping) => {
                for entry in &mapping.entries {
                    if !matches!(&entry.key, EntryKey::Literal(key) if !key.is_empty()) {
                        continue;
                    }
                    if entry.value.arms.is_empty() {
                        sibling_conditions.push(sibling_condition.clone());
                        continue;
                    }
                    sibling_conditions.extend(entry.value.arms.iter().map(
                        |(value_condition, _)| {
                            Predicate::all(vec![sibling_condition.clone(), value_condition.clone()])
                                .normalize_boolean()
                        },
                    ));
                }
            }
            AbstractFragment::Sequence(sequence) => {
                for item in &sequence.items {
                    sibling_conditions.extend(item.arms.iter().map(|(item_condition, _)| {
                        Predicate::all(vec![sibling_condition.clone(), item_condition.clone()])
                            .normalize_boolean()
                    }));
                }
            }
            AbstractFragment::Scalar(_)
            | AbstractFragment::Splice(_)
            | AbstractFragment::Opaque(_) => {}
        }
    }
    sibling_conditions.retain(|condition| !matches!(condition, Predicate::False));
    sibling_conditions.sort();
    sibling_conditions.dedup();
    let minimal_sibling_conditions = sibling_conditions
        .iter()
        .filter(|condition| {
            !sibling_conditions.iter().any(|other| {
                other != *condition && predicate_is_conjunctive_subset(other, condition)
            })
        })
        .cloned()
        .collect::<Vec<_>>();
    for (condition, node) in &guarded.arms {
        if *condition == Predicate::False {
            continue;
        }
        let pushed = *condition != Predicate::True;
        if pushed {
            conditions.push(condition.clone());
        }
        walk_node(
            node,
            path,
            conditions,
            contract,
            &sibling_keys,
            &minimal_sibling_conditions,
        );
        if pushed {
            conditions.pop();
        }
    }
}

fn predicate_is_conjunctive_subset(subset: &Predicate, superset: &Predicate) -> bool {
    fn collect(predicate: &Predicate, out: &mut std::collections::BTreeSet<Predicate>) {
        match predicate {
            Predicate::True => {}
            Predicate::And(predicates) => {
                for predicate in predicates {
                    collect(predicate, out);
                }
            }
            other => {
                out.insert(other.clone());
            }
        }
    }

    let mut subset_conjuncts = std::collections::BTreeSet::new();
    let mut superset_conjuncts = std::collections::BTreeSet::new();
    collect(subset, &mut subset_conjuncts);
    collect(superset, &mut superset_conjuncts);
    subset_conjuncts.is_subset(&superset_conjuncts)
}

#[expect(
    clippy::too_many_lines,
    reason = "the recursive fragment variant match keeps each node kind under one shared path and condition invariant"
)]
fn walk_node(
    node: &AbstractFragment,
    path: &YamlPath,
    conditions: &mut Vec<Predicate>,
    contract: &mut ContractIr,
    member_sibling_keys: &std::collections::BTreeSet<String>,
    structural_sibling_conditions: &[Predicate],
) {
    let no_siblings = std::collections::BTreeSet::new();
    match node {
        AbstractFragment::Mapping(mapping) => {
            // Literal keys the template itself writes into this mapping: a
            // member-contributing fragment splice's provider slot already
            // holds them, so its object requiredness must not re-demand
            // them from the user value (metrics-server's `- name: tmp`
            // beside `toYaml .Values.tmpVolume`).
            let literal_keys: std::collections::BTreeSet<String> = mapping
                .entries
                .iter()
                .filter_map(|entry| match &entry.key {
                    EntryKey::Literal(key) if !key.is_empty() => Some(key.clone()),
                    _ => None,
                })
                .collect();
            let mut literal_key_conditions = mapping
                .entries
                .iter()
                .filter(|entry| matches!(&entry.key, EntryKey::Literal(key) if !key.is_empty()))
                .flat_map(|entry| {
                    if entry.value.arms.is_empty() {
                        vec![Predicate::True]
                    } else {
                        entry
                            .value
                            .arms
                            .iter()
                            .map(|(condition, _)| condition.clone())
                            .collect()
                    }
                })
                .collect::<Vec<_>>();
            literal_key_conditions.sort();
            literal_key_conditions.dedup();
            for entry in &mapping.entries {
                match &entry.key {
                    EntryKey::Literal(key) if !key.is_empty() => {
                        let mut child = path.clone();
                        child.0.push(key.clone());
                        walk_guarded(
                            &entry.value,
                            &child,
                            conditions,
                            contract,
                            &no_siblings,
                            &[],
                        );
                    }
                    EntryKey::Literal(_) => {
                        walk_guarded(
                            &entry.value,
                            path,
                            conditions,
                            contract,
                            &literal_keys,
                            &literal_key_conditions,
                        );
                    }
                    EntryKey::Dynamic(_) => {
                        // Templated keys: the key's reads were recorded at
                        // the eval site, where range/branch predicates were
                        // still ambient. The structural member segment lets
                        // provider lookup descend through the container's
                        // additionalProperties schema without guessing the
                        // rendered key.
                        let child = dynamic_mapping_value_path(path);
                        walk_guarded(
                            &entry.value,
                            &child,
                            conditions,
                            contract,
                            &no_siblings,
                            &[],
                        );
                    }
                }
            }
        }
        AbstractFragment::Sequence(sequence) => {
            let item_path = sequence_item_path(path);
            for item in &sequence.items {
                walk_guarded(item, &item_path, conditions, contract, &no_siblings, &[]);
            }
        }
        AbstractFragment::Scalar(scalar) => {
            // Render-suppressed blobs (block scalar bodies) influence their
            // text without sink-typing the document position.
            let effective_path = if scalar.suppressed {
                YamlPath(Vec::new())
            } else {
                path.clone()
            };
            project_parts(scalar, &effective_path, conditions, contract);
        }
        AbstractFragment::Splice(splice) => {
            let row = splice_row(splice, path, conditions, member_sibling_keys);
            if !row.condition.is_never() {
                if row.kind == ValueKind::YamlSerialized
                    && !structural_sibling_conditions.is_empty()
                    && !row.source_expr.encode().contains('*')
                    && !splice.meta.defaulted
                    && !splice.meta.merge_operand
                    && splice.meta.merge_layers.is_none()
                {
                    // A direct serialized value continues structural YAML the
                    // template already began. If its source is absent,
                    // `toYaml` writes `null` where another mapping member or
                    // sequence item must begin and Helm cannot parse the
                    // document. Computed merge/default results do not preserve
                    // this identity.
                    let mut conjunctions = std::collections::BTreeSet::new();
                    for sibling_condition in structural_sibling_conditions {
                        let condition = Predicate::all(
                            conditions
                                .iter()
                                .cloned()
                                .chain(std::iter::once(sibling_condition.clone()))
                                .collect(),
                        )
                        .normalize_boolean();
                        let conjunction = match condition {
                            Predicate::False => continue,
                            Predicate::True => Vec::new(),
                            Predicate::And(predicates) => predicates,
                            predicate => vec![predicate],
                        };
                        conjunctions.insert(conjunction);
                    }
                    let mut observed_facts = crate::observed_facts::ObservedFacts::default();
                    observed_facts
                        .captures
                        .extend(conjunctions.into_iter().map(|conjunction| {
                            crate::eval_effect::FailCapture {
                                conjunction,
                                ranged: crate::range_modes::RangeModes::default(),
                                kind: crate::eval_effect::CaptureKind::AbsenceAborts {
                                    path: row.source_expr.clone(),
                                },
                            }
                        }));
                    contract.absorb_observed_facts(&observed_facts);
                }
                contract.push(row);
            }
        }
        AbstractFragment::Opaque(opaque) => {
            for taint_path in &opaque.taint {
                if taint_path.segments().next().is_none() {
                    continue;
                }
                contract.push(placed_row(
                    taint_path.clone(),
                    path,
                    opaque.kind,
                    GuardDnf::from_conjunction(conditions.iter().cloned()),
                    opaque.site.as_deref(),
                    &opaque.provenance,
                ));
            }
        }
    }
}

fn project_parts(
    scalar: &AbstractString,
    path: &YamlPath,
    conditions: &[Predicate],
    contract: &mut ContractIr,
) {
    for part in &scalar.parts {
        match part {
            StringPart::Text(_) => {}
            StringPart::Splice(splice) => {
                let mut row =
                    splice_row(splice, path, conditions, &std::collections::BTreeSet::new());
                if scalar.suppressed {
                    row.kind = ValueKind::Serialized;
                }
                if !row.condition.is_never() {
                    contract.push(row);
                }
            }
            StringPart::Taint(taint) => {
                if !taint.claims_value_kind {
                    continue;
                }
                for taint_path in &taint.paths {
                    if taint_path.segments().next().is_none() {
                        continue;
                    }
                    contract.push(placed_row(
                        taint_path.clone(),
                        path,
                        if scalar.suppressed {
                            ValueKind::Serialized
                        } else {
                            ValueKind::PartialScalar
                        },
                        GuardDnf::from_conjunction(conditions.iter().cloned()),
                        taint.site.as_deref(),
                        &taint.provenance,
                    ));
                }
            }
        }
    }
}

fn splice_row(
    splice: &Splice,
    path: &YamlPath,
    conditions: &[Predicate],
    member_sibling_keys: &std::collections::BTreeSet<String>,
) -> ContractUse {
    let mut condition = GuardDnf::from_conjunction(conditions.iter().cloned());
    if splice.meta.defaulted {
        let default_guard = Guard::Default {
            path: splice.values_path.clone(),
        };
        condition = condition.conjoined_with_guards([default_guard.clone()]);
    }
    if splice.meta.is_input_identity()
        && !splice.meta.defaulted
        && !path.0.is_empty()
        && splice
            .meta
            .site
            .as_ref()
            .and_then(|site| site.resource.as_ref())
            .is_some()
    {
        // An approximate execution predicate can still expose a sound live
        // subset. It is safe to retain that subset for an identity splice:
        // the provider sees this input value there. Derived scalar influence
        // stays opaque and therefore keeps the approximation.
        condition = GuardDnf::from_disjunction(condition.disjuncts().iter().map(|conjunction| {
            conjunction.iter().map(|predicate| match predicate {
                Predicate::Approximate {
                    role: helm_schema_core::ApproximationRole::OutputSelection,
                    sound_subset: Some(sound_subset),
                    ..
                } if predicate.value_paths().contains(&splice.values_path) => {
                    sound_subset.as_ref().clone()
                }
                other => other.clone(),
            })
        }));
    }
    // Serialization and encoding transforms don't expose the input shape to
    // the sink schema. Fragment serialization stays distinguishable from a
    // scalar text transform so provider resolution cannot recover its shape.
    // A total stringification (`quote`, `toString`, `join`) erases shape at
    // every position: unlike `b64enc`, its input is not required to be text.
    let kind = if splice.meta.digest || splice.meta.shape_erased {
        ValueKind::Serialized
    } else if splice.meta.encoded {
        if splice.kind == ValueKind::Fragment {
            ValueKind::Serialized
        } else {
            ValueKind::PartialScalar
        }
    } else if splice.meta.templated_yaml {
        ValueKind::TemplatedYamlSerialized
    } else if splice.meta.yaml_serialized {
        ValueKind::YamlSerialized
    } else {
        splice.kind
    };
    let mut row = placed_row(
        splice.values_path.clone(),
        path,
        kind,
        condition,
        splice.meta.site.as_deref(),
        &splice.meta.provenance,
    );
    row.stringified = splice.meta.stringified;
    row.template_supplied_member_keys = member_sibling_keys.clone();
    row.split_segment = splice.meta.split_segment.clone();
    row.range_key = splice.meta.range_key;
    row.nil_omitting = splice.meta.nil_omitted;
    row.merge_layers = splice.meta.merge_layers.clone();
    row.omitted_members = splice.meta.omitted_members.clone();
    row.digest = splice.meta.digest;
    row.merge_operand = splice.meta.merge_operand;
    row
}

/// One placed row with the shared site policy applied: List-item path
/// rebasing, partial-scalar normalization at pathless positions, the site's
/// resource scope, and site-then-helper provenance.
fn placed_row(
    values_path: helm_schema_core::ValuesPath,
    path: &YamlPath,
    kind: ValueKind,
    condition: GuardDnf,
    site: Option<&SiteFacts>,
    helper_provenance: &[ContractProvenance],
) -> ContractUse {
    let mut path = path.clone();
    if let Some(site) = site
        && !site.path_prefix.is_empty()
        && path.0.starts_with(&site.path_prefix)
    {
        path = YamlPath(
            path.0
                .get(site.path_prefix.len()..)
                .unwrap_or_default()
                .to_vec(),
        );
    }
    let mut kind = kind;
    if kind == ValueKind::PartialScalar && path.0.is_empty() {
        kind = ValueKind::Scalar;
    }
    let mut provenance: Vec<ContractProvenance> = site
        .and_then(|site| site.provenance.clone())
        .into_iter()
        .collect();
    crate::helper_meta::merge_provenance_sites(&mut provenance, helper_provenance);
    ContractUse::with_condition_and_provenances(
        values_path,
        path,
        kind,
        condition,
        site.and_then(|site| site.resource.clone()),
        provenance,
    )
}