use crate::Intent;

// Names this module's prose links to, resolved for rustdoc.
#[allow(unused_imports)]
use crate::Column;

/// What a run of source code is, once something has classified it.
///
/// The description carries the classification and never the source, which is
/// the whole of decision `19d7602d` (2026-09-02, option d). An app that browses
/// source already has a lexer; a renderer does not and should not grow one, and
/// three renderers each growing their own would disagree about the same file.
///
/// # Why the app classifies and the renderer colours
///
/// Measured on MNW's source browser, which is the only consumer in the tree.
/// It highlights server-side with syntect and had already reduced syntect's
/// scope space to seven colours held fixed across all 31 themes, because a
/// reader recognises a highlighting palette and re-tinting it per theme costs
/// that recognition to gain nothing. So the classification existed on the app
/// side already: the only question was whether to throw it away at the seam and
/// have each renderer redo it. This is the answer.
///
/// The precedent is `docengine`'s `Emphasis`, which crosses the same seam the
/// same way: `quasi-tui` maps its four flags onto terminal modifiers, a webview
/// maps them onto elements, and neither parses markdown to do it.
///
/// # The eight, and why these eight
///
/// The seven MNW's palette fixes, plus [`Plain`](Self::Plain) for a run nothing
/// claimed. `Plain` is not an absence: a lexer that ran and found ordinary code
/// is saying something a renderer wants, and an `Option<Syntax>` would have made
/// "unclassified" and "not classified yet" one value.
///
/// `#[non_exhaustive]` from the first commit, deliberately. A ninth class is the
/// obvious next request and it must not be a breaking release across three
/// renderers and five apps.
///
/// # What it is not
///
/// A token type in a grammar. These are display classes, coarse on purpose:
/// the distinctions a reader uses at a glance, not the ones a parser makes.
/// A renderer wanting more has `language` on the node beside this and may do
/// whatever it likes with it.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default)]
#[non_exhaustive]
pub enum Syntax {
    /// Ordinary code nothing else claimed.
    ///
    /// The default, and a real answer rather than a missing one. See the type's
    /// docs for why this is not an `Option`.
    #[default]
    Plain,
    /// A language keyword, and the storage and modifier words with it.
    Keyword,
    /// A string or character literal.
    String,
    /// A comment.
    Comment,
    /// A literal that is not a string: a number, a boolean, a constant name.
    Constant,
    /// A name being defined: a function, a type, a module.
    Entity,
    /// A name being used: a variable, a parameter, a field.
    Variable,
    /// Something the language or its library provides rather than this file.
    Support,
}

impl Syntax {
    /// The stable lowercase name, for a renderer keying its own palette off it.
    ///
    /// Named here rather than agreed between each renderer and each host, for
    /// the reason every other spelling in this crate is: that is how one
    /// renderer ends up calling it `str` and the next `string`, and a theme
    /// written against one stops working under the other.
    ///
    /// Not an [`Intent`] token, and the difference is worth stating. An intent
    /// resolves against a `makeover` theme token, and there are none for syntax
    /// colours: a highlighting palette is deliberately outside the theme, held
    /// fixed while everything around it changes. So this is a name a renderer
    /// maps however it can, and a renderer with no colours to spend maps every
    /// one of them onto the same face and is not wrong.
    #[must_use]
    pub const fn name(self) -> &'static str {
        match self {
            Self::Plain => "plain",
            Self::Keyword => "keyword",
            Self::String => "string",
            Self::Comment => "comment",
            Self::Constant => "constant",
            Self::Entity => "entity",
            Self::Variable => "variable",
            Self::Support => "support",
            // Exhaustive rather than wildcarded, which is `State`'s rule one
            // type up: within this crate `#[non_exhaustive]` does not apply, so
            // a class added here has to be given a spelling rather than
            // inheriting "plain" in silence. Consumers outside the crate take
            // the wildcard, and for them "plain" is the right degradation.
        }
    }
}

/// What one line of a diff is: added, removed, or neither.
///
/// The other half of decision `19d7602d`. A diff is a table of lines and the
/// only thing the vocabulary was missing was a way for a line to say which side
/// of the change it is on, so this rides on [`Column`] rather than arriving as a
/// `Node::Diff` carrying git's data model.
///
/// # Why three and not two
///
/// [`Context`](Self::Context) is a line that did not change, and it is most of
/// a diff. Said as `Option<Change>` with `None` for context, a renderer could
/// not tell an unchanged line from a line nobody marked, which is the same
/// argument [`Syntax::Plain`] makes one type up.
///
/// `#[non_exhaustive]` for [`Syntax`]'s reason. A fourth kind -- a moved line, a
/// conflict side -- is a plausible request and must not be a breaking release.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default)]
#[non_exhaustive]
pub enum Change {
    /// The line is in both sides and did not change.
    #[default]
    Context,
    /// The line is only in the new side.
    Added,
    /// The line is only in the old side.
    Removed,
}

impl Intent for Change {
    fn token(self) -> &'static str {
        match self {
            // The status axis, reused rather than given a palette of its own.
            // A diff's green and red mean exactly what success and danger mean
            // everywhere else in the system, and an app that wants them held
            // fixed across themes says so in its own sheet, which is what MNW's
            // `--diff-add` / `--diff-del` pair already does.
            Self::Added => "success",
            Self::Removed => "danger",
            // Context is the bulk of a diff and is ordinary content. Muting it
            // would be the axis deciding that unchanged lines are less worth
            // reading, which is a renderer's call about a particular view.
            //
            // Exhaustive for `Syntax::name`'s reason: a fourth kind must answer
            // this rather than inherit an answer.
            Self::Context => "content",
        }
    }
}