BREP_render 0.5.0

//! Turning a Transform Face refusal into a sentence about the user's model.
//!
//! Move Face and Rotate Face refuse BY DESIGN — a motion that carries the
//! selection off the body it belongs to has no answer, and the kernel says so
//! rather than building something unsound. What it says, though, is written for
//! the lane that raised it:
//!
//! ```text
//! TF1: move_faces: the translation inverts the solid (signed volume changed sign) — refusing
//! ```
//!
//! `move_faces` is a function name, and "signed volume changed sign" is the
//! kernel's own criterion, not a statement about the part on screen. Worse, the
//! message never names the face the user picked and is dragging: the rotation
//! refusal names `Box_NZ` and `Box_PY`, which are the NEIGHBOURS that could not
//! follow, so the two faces it does name are both the wrong answer to "which
//! one did I break?".
//!
//! This module re-says it. It reads the kernel's text, recognises WHICH refusal
//! it is from the few stable phrases each one is built on, and rebuilds the
//! sentence around the face the user actually selected — which the app knows
//! from `params.faces` and the kernel message does not carry.
//!
//! One thing the sentences here must get right, because it is what the user is
//! looking at: a REFUSED Transform Face contributes NOTHING. The feature drops
//! out of the build entirely rather than falling back to its last good motion,
//! so the face springs back to where it was before the feature ran — measured
//! 2026-09-21, a block lifted to z = 17.9188 by a good drag snapped back to
//! z = 14 the moment a later drag refused. A hint that said the part was "still
//! exactly as it was" would be describing a different app.
//!
//! **The kernel text is never thrown away.** [`FaceTransformRefusal::kernel`]
//! keeps it verbatim, and an unrecognised message becomes the reason unchanged:
//! when the kernel lane rewords a refusal under us, this degrades to exactly
//! the message the app showed before this module existed, rather than losing
//! it. That is the whole reason the match is on phrases rather than on a
//! prefix — nothing here can make a refusal less legible than it was.

/// A Transform Face refusal, said three ways: what happened, why, and what to
/// do — plus the kernel's own words, kept.
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct FaceTransformRefusal {
    /// Which motion refused: `"Move Face"` or `"Rotate Face"`, named for the
    /// half of the feature the user was actually driving. Transform Face is
    /// both, and a user who dragged a rotation ring should not be told
    /// something about a translation.
    pub motion: &'static str,
    /// The refusal in one sentence, naming the selected face.
    pub reason: String,
    /// What to do instead. Always something the user can do from where they
    /// are — the model is at its last good answer, so every hint is a smaller
    /// value away rather than a restart.
    pub hint: String,
    /// The kernel's message, verbatim and unabridged.
    pub kernel: String,
}

impl FaceTransformRefusal {
    /// The reason and the hint as one line, for a chip.
    pub fn one_line(&self) -> String {
        format!("{} — {}", self.reason, self.hint)
    }
}

/// How the selection reads inside a sentence: the one face's name, or a count.
fn subject(faces: &[String]) -> String {
    match faces {
        [] => "the selected face".to_string(),
        [one] => format!("`{one}`"),
        many => format!("the {} selected faces", many.len()),
    }
}

/// Every \`backticked\` name in `message` that is not already in `faces` — the
/// NEIGHBOURS a refusal names, which are the faces that could not follow the
/// motion rather than the ones the user picked.
fn neighbours(message: &str, faces: &[String]) -> Vec<String> {
    let mut out: Vec<String> = Vec::new();
    // `split('`')` alternates outside/inside starting outside, so the odd
    // indices are the quoted spans.
    for (index, span) in message.split('`').enumerate() {
        if index % 2 == 1
            && !span.is_empty()
            && !faces.iter().any(|f| f == span)
            && !out.iter().any(|n| n == span)
        {
            out.push(span.to_string());
        }
    }
    out
}

/// Render `names` as `` `a` and `b` `` / `` `a`, `b` and `c` ``.
fn and_list(names: &[String]) -> String {
    match names {
        [] => String::new(),
        [one] => format!("`{one}`"),
        [rest @ .., last] => format!(
            "{} and `{last}`",
            rest.iter()
                .map(|n| format!("`{n}`"))
                .collect::<Vec<_>>()
                .join(", ")
        ),
    }
}

/// The face names in a Transform Face's `faces` param, as the kernel resolves
/// them — re-exported here so the APP can name the selection in a refusal
/// without taking a dependency on the kernel of its own.
pub fn selected_face_names(faces: Option<&serde_json::Value>) -> Vec<String> {
    brep_kernel::reference_names(faces)
}

/// Explain a Transform Face refusal.
///
/// `message` is the kernel's text for the feature WITHOUT the `"<id>: "` prefix
/// (what `feature_error_message` already returns); `faces` is the feature's
/// `params.faces`, which is where the selected face's name comes from — the
/// kernel message does not carry it.
pub fn explain_refusal(message: &str, faces: &[String]) -> FaceTransformRefusal {
    let kernel = message.to_string();
    let lower = message.to_ascii_lowercase();
    let subject = subject(faces);

    // WHICH HALF of Transform Face refused. A combined motion names its step
    // ("the ROTATION step of this rotate-then-translate motion"), and that
    // naming is what decides it — the user turned a ring or pulled an arrow and
    // must be told about the one they touched. Checked before the bare
    // `rotate_faces` / `move_faces` test, because a combined message contains
    // both words.
    let motion = if lower.contains("rotation step") {
        "Rotate Face"
    } else if lower.contains("translation step") {
        "Move Face"
    } else if lower.contains("rotate_faces") || lower.contains("the rotation") {
        "Rotate Face"
    } else {
        "Move Face"
    };
    let turning = motion == "Rotate Face";
    let motion_noun = if turning { "turn" } else { "move" };

    // The neighbours the kernel named, said as what they are.
    let blocked = neighbours(message, faces);
    let by_neighbour = if blocked.is_empty() {
        String::new()
    } else {
        format!(" {} could not follow it", and_list(&blocked))
    };

    // The refusals, by the phrase each is built on. The ORDER matters: the
    // whole-solid inversion is the more specific reading of an "inverts", so it
    // is tested first.
    let (reason, hint) = if lower.contains("signed volume changed sign")
        || lower.contains("inverts the solid")
    {
        (
            format!(
                "That {motion_noun} carries {subject} clean through the far side of the body, \
                 leaving it inside out."
            ),
            "Ease it back until the model follows again — while it refuses the feature builds \
             nothing at all, so the face springs back to where it started."
                .to_string(),
        )
    } else if lower.contains("inverts edge") || lower.contains("passes beyond its neighbour") {
        (
            format!(
                "That {motion_noun} carries {subject} past a face it has to meet, so{} \
                 without turning a corner of the body inside out.",
                if by_neighbour.is_empty() {
                    " its neighbour could not follow it".to_string()
                } else {
                    by_neighbour
                }
            ),
            if turning {
                "Ease the angle back, or move the Pivot — the turn happens about it, so a pivot \
                 nearer the blocked corner asks less of it."
                    .to_string()
            } else {
                "Ease the distance back until the model follows again, or select the blocked \
                 neighbours too so they move with it."
                    .to_string()
            },
        )
    } else if lower.contains("parallel") {
        (
            format!(
                "That turn lays {subject} parallel to a face it has to meet, and two parallel \
                 faces never make a corner."
            ),
            "Stop short of the angle that flattens it — while it refuses the feature builds \
             nothing at all, so the face springs back unturned."
                .to_string(),
        )
    } else if lower.contains("transform.scale") {
        (
            format!("A face transform carries {subject} rigidly, so it cannot scale."),
            "Clear the scale back to 1, 1, 1 and move or turn the face instead.".to_string(),
        )
    } else if lower.contains("centre a pivot on") || lower.contains("center a pivot on") {
        (
            format!("{subject} has no geometry to turn about."),
            "Pick the face again, or type a Pivot to turn about.".to_string(),
        )
    } else {
        // UNRECOGNISED — the kernel's own words, unchanged. This is the branch
        // that makes a reworded refusal degrade to what the app showed before
        // rather than to nothing.
        (
            kernel.clone(),
            "Ease the value back until the model follows again — while it refuses the feature \
             builds nothing at all, so the face springs back to where it started."
                .to_string(),
        )
    };

    FaceTransformRefusal {
        motion,
        reason,
        hint,
        kernel,
    }
}