//! The staged twin of a declaration.
//!
//! A shape marked `#[staged]` gets a second function beside it, which is the
//! same description evaluated with no request: every value is a sentinel, every
//! guard is a bool a [`Plan`](quasi_router::stage::Plan) chooses, and every
//! loop runs as many times as the plan says. Handing its result to the ordinary
//! renderer produces the screen's markup with sentinels where the data would
//! be, and that string is the residual a request later fills.
//!
//! # Why this is a rewrite and not a second emitter
//!
//! Nothing here emits Rust. It rewrites the parsed [`Declaration`] into another
//! [`Declaration`] and hands that to [`crate::emit`], so the staged function is
//! built by the same code that builds the ordinary one.
//!
//! That is the whole reason to do it this way. The residual's literals have to
//! be the renderer's own output, or the staged path is a second renderer
//! wearing the first one's name, and a second emitter here would be the same
//! mistake one level up: two spellings of every production, drifting apart one
//! conversion at a time. A rewrite over a closed grammar cannot drift, because
//! a production it does not know about is a production it cannot silently
//! mistranslate -- it refuses instead.
//!
//! # What it refuses, and why refusing is right
//!
//! `#[staged]` is a request, so a shape that cannot be staged is a compile
//! error naming the construct rather than a silently unstaged shape. Three
//! things are refused today, each because the value it needs has no sentinel:
//!
//! - a region whose kind comes from a supplier, which needs a `RegionKind`
//! - a dispatch with no `otherwise`, whose arms become integers and would stop
//!   being exhaustive
//! - a value hole in a position that is not a string, which rustc reports
//!   against the generated call rather than here
//!
//! The flag is opt-in for exactly this reason: a shape is staged when someone
//! has looked at it, and the rest keep the runtime renderer, which is how the
//! two paths coexist during the migration without a switch.

use proc_macro2::Span;
use quote::format_ident;
use syn::{Ident, Result};

use crate::ast::{
    Arg, Declaration, Emission, Guard, Hole, HoleRoot, Interpolated, Item, Param, Predicate,
    RegionKind, Source, StrPart,
};

/// The flag that asks for a staged twin.
pub const FLAG: &str = "staged";

/// The flag that says a shape answers the same thing every time.
///
/// A promise about the body, made where the body is, which is the only place
/// anybody can check it. See [`constant_name`] for how a caller in another
/// `declare!` (and possibly another crate) is held to it without the two macros
/// ever seeing each other.
pub const CONSTANT: &str = "constant";

/// The shim a `#[constant]` shape gets, which is how a caller opts in.
///
/// A proc macro sees one invocation and no other, so a caller cannot read the
/// callee's flags: two `declare!`s are two separate expansions, often in two
/// crates. The flag therefore has to leave something behind that a call site
/// can name and that does not exist otherwise.
///
/// That is this function. It takes the shape's own parameters and calls the
/// shape, so it is the shape under a second name, and it is emitted only under
/// the flag. An `include` whose arguments are all literals calls it instead of
/// opening a staged scope; against a shape that made no such promise the call
/// does not resolve, and rustc names the function it could not find. The word
/// in that name is the word to go and write.
pub fn constant_name(name: &Ident) -> Ident {
    format_ident!("{}_constant", name, span = name.span())
}

/// Whether an argument is settled where it is written.
///
/// A literal, or a list of them, and nothing else. A hole is a read, and a
/// borrow of one is the same read with an ampersand in front, so neither is
/// fixed however constant it looks: `&SECTIONS` names a path this macro cannot
/// evaluate. An interpolated string counts only when it interpolates nothing.
fn fixed(arg: &Arg) -> bool {
    match arg {
        Arg::Str(text) => text
            .parts
            .iter()
            .all(|part| matches!(part, StrPart::Lit(_))),
        Arg::Int(_) | Arg::Bool(_) => true,
        Arg::List(items) => items.iter().all(fixed),
        Arg::Hole(_) | Arg::Borrow(_) => false,
    }
}

/// Whether this declaration promised to answer the same thing every time.
pub fn constant(declaration: &Declaration) -> bool {
    declaration.flags.iter().any(|flag| flag == CONSTANT)
}

/// The shim, or nothing where no promise was made.
pub fn promise(declaration: &Declaration) -> proc_macro2::TokenStream {
    if !constant(declaration) {
        return proc_macro2::TokenStream::new();
    }
    let name = &declaration.name;
    let shim = constant_name(name);
    let vis = declaration
        .vis
        .clone()
        .unwrap_or(syn::Visibility::Inherited);
    let params: Vec<_> = declaration
        .params
        .iter()
        .map(|param| {
            let name = &param.name;
            let ty = &param.ty;
            quote::quote!(#name: #ty)
        })
        .collect();
    let arguments = declaration.params.iter().map(|param| &param.name);
    let Ok(returns) = crate::emit::returns_type(&declaration.returns) else {
        // A return type this crate does not know is refused by `emit` with a
        // message naming it, and that error is the one worth reporting. Emit no
        // shim rather than a second complaint about the same line.
        return proc_macro2::TokenStream::new();
    };
    let doc = format!(
        " [`{name}`], and the promise that it answers the same thing every time.\n\n         Emitted by `#[constant]`. A staged `include` whose arguments are all\n         literals calls this rather than opening a scope, so what this returns is\n         built once while a residual is derived instead of once per request. A\n         shape that made no such promise has no function here, and the call site\n         fails to resolve rather than quietly baking one evaluation in forever."
    );
    quote::quote! {
        #[doc = #doc]
        #[allow(dead_code)]
        #vis fn #shim(#(#params),*) -> #returns {
            #name(#(#arguments),*)
        }
    }
}

/// The parameter the staged function takes in place of the request's reads.
pub(crate) const PLAN: &str = "plan";

/// The staged twin of `name`, which is what an `include` retargets to.
pub fn staged_name(name: &Ident) -> Ident {
    format_ident!("{}_staged", name, span = name.span())
}

/// The const holding the shape's counts, beside the staged function.
fn counts_name(name: &Ident) -> Ident {
    format_ident!(
        "{}_STAGED",
        name.to_string().to_uppercase(),
        span = name.span()
    )
}

/// Whether this declaration asked to be staged.
pub fn wanted(declaration: &Declaration) -> bool {
    declaration.flags.iter().any(|flag| flag == FLAG)
}

/// One instruction of the fill program: what a request writes, and where.
///
/// Collected by the same traversal that numbers the holes, so the filler and
/// the residual cannot disagree about order. Written as a second traversal they
/// would drift the first time a production was added to one and not the other.
pub enum Fill {
    /// One value, at the hole with this number.
    ///
    /// Numbered rather than positioned because render order and declaration
    /// order genuinely differ: a cell's `activate` address is written after the
    /// cell's value and renders before it, inside the anchor that wraps it.
    Hole { id: u16, hole: Hole },
    /// What one guard places, and the predicate that decides it.
    Branch { guard: Guard, body: Vec<Fill> },
    /// One loop, over the collection the declaration named.
    Repeat {
        dereferenced: bool,
        binder: Ident,
        iterable: Hole,
        body: Vec<Fill>,
    },
    /// Two markups at one position, and the predicate that picks between them.
    ///
    /// What a guarded SETTLING setting compiles to. `chosen`, `here` and
    /// `latched` change the markup the member their own statement produces was
    /// going to write anyway, so there is no run of members for a branch to
    /// cover; the member is built both ways instead and a request picks one.
    ///
    /// Arm 0 is the setting made, matching [`Plan::swap`][swap], which is what
    /// the twin reads to decide both which arm it is drawing and whether to
    /// make the setting. No body, for [`Arms`](Self::Arms)'s reason: both arms'
    /// holes are numbered at the level around them.
    ///
    /// [swap]: quasi_router::stage::Plan::swap
    Swap { guard: Guard },
    /// One dispatch, and which arm the request takes.
    ///
    /// No bodies. Every arm's holes are staged at the level around the
    /// dispatch, so the closure that fills the stretch these arms sit in is the
    /// one that fills the arm -- the same arrangement a guard that swaps markup
    /// uses, and for the same reason: one arm carries holes another does not,
    /// so an arm cannot number its own.
    Arms {
        scrutinee: Hole,
        /// One pattern per written arm, in the order they were written. The
        /// index a pattern maps to is its position, and anything unmatched
        /// takes the last one, which is `otherwise`.
        patterns: Vec<crate::ast::Pattern>,
    },
    /// Another shape's filler, called where its markup was spliced in.
    ///
    /// `site` is the include's ordinal in the shape that holds it, which is
    /// what the staged twin hands `Plan::enter`. The filler passes the same
    /// number to `Cursor::enter`, so a caller's walk stops at the boundary
    /// rather than answering the callee's holes with its own.
    Include {
        callee: syn::Path,
        args: Vec<Arg>,
        site: u16,
    },
}

/// Numbering, one counter per thing a plan answers.
///
/// Shape-local on purpose. A residual is derived per shape and composed by
/// reference, so an included shape's holes are never renumbered against its
/// caller's, which is what keeps the derivation linear in the tree rather than
/// in the tree's expansion.
#[derive(Default)]
struct Counters {
    guards: u16,
    loops: u16,
    holes: u16,
    /// One per `include`, which is what scopes the shape it reaches.
    sites: u16,
    /// One per dispatch, which is what the plan answers with an arm index.
    arms: u16,
    /// The fill program under construction, innermost body last.
    stack: Vec<Vec<Fill>>,
    /// The arm site of the member currently being built both ways, if any.
    ///
    /// Set while a member carrying a guarded settling setting is staged, and
    /// read by that setting: its guard becomes a read of this site's arm rather
    /// than a refusal, and it writes no fill of its own because the wrapper
    /// already wrote one.
    swapping: Option<u16>,
}

impl Counters {
    /// Start a body: a loop's, or what a guard places.
    fn enter(&mut self) {
        self.stack.push(Vec::new());
    }

    /// Finish the innermost body.
    fn exit(&mut self) -> Vec<Fill> {
        self.stack.pop().unwrap_or_default()
    }

    /// Add one instruction to the innermost body.
    fn wrote(&mut self, fill: Fill) {
        if let Some(body) = self.stack.last_mut() {
            body.push(fill);
        }
    }
}

/// A hole reading the plan: `plan.<method>(<id>)`.
fn plan_read(method: &str, id: u16) -> Hole {
    Hole {
        root: HoleRoot::Binding(Ident::new(PLAN, Span::call_site())),
        steps: vec![crate::ast::Step::Method {
            name: Ident::new(method, Span::call_site()),
            args: vec![Arg::Int(i64::from(id))],
        }],
    }
}

/// A hole answering with one sentinel: `plan.hole(<id>)`.
///
/// Through the plan rather than a free function because a sentinel carries the
/// scope it was read at, and the plan is what knows the scope. Two tables on
/// one screen each number their holes from zero, so without the scope they
/// would both claim hole 0 and the residual would fill one from the other.
fn sentinel(id: u16) -> Hole {
    plan_read("hole", id)
}

/// Which arm a dispatch takes: `plan.arm(<id>, <count>)`.
///
/// The count rides along so a traced render records it. See
/// `quasi_router::stage::Plan::arm`.
fn plan_arm(id: u16, count: usize) -> Hole {
    Hole {
        root: HoleRoot::Binding(Ident::new(PLAN, Span::call_site())),
        steps: vec![crate::ast::Step::Method {
            name: Ident::new("arm", Span::call_site()),
            args: vec![Arg::Int(i64::from(id)), Arg::Int(count as i64)],
        }],
    }
}

/// A hole answering with one numeric stand-in: `plan.number(<id>)`.
///
/// See `quasi_router::stage::number_at`. A number has no `ZQH` to carry, so a
/// slot typed `usize` was refused a hole until this existed, and a pager is
/// three of them.
fn counted(id: u16) -> Hole {
    plan_read("number", id)
}

/// The staged declaration, and the counts a plan needs to drive it.
pub struct Staged {
    pub declaration: Declaration,
    /// What a request writes into the residual, in declaration order.
    pub fill: Vec<Fill>,
    pub counts: (u16, u16, u16, u16),
    pub counts_ident: Ident,
}

/// Rewrite one declaration into its staged twin.
pub fn stage(declaration: &Declaration) -> Result<Staged> {
    let mut counters = Counters::default();
    counters.enter();
    let items = items(&declaration.items, &mut counters)?;
    let fill = counters.exit();

    let name = staged_name(&declaration.name);
    let doc = format!(
        " The staged twin of [`{}`], evaluated with no request.",
        declaration.name
    );

    Ok(Staged {
        fill,
        counts: (
            counters.guards,
            counters.loops,
            counters.holes,
            counters.sites,
        ),
        counts_ident: counts_name(&declaration.name),
        declaration: Declaration {
            docs: vec![doc],
            // `must_use` and `inline` carry over; the flag that asked for this
            // does not, or the twin would ask for a twin of its own.
            flags: declaration
                .flags
                .iter()
                .filter(|flag| *flag != FLAG)
                .cloned()
                .collect(),
            vis: declaration.vis.clone(),
            name,
            params: vec![Param {
                name: Ident::new(PLAN, Span::call_site()),
                ty: syn::parse_quote!(&::quasi_router::stage::Plan),
            }],
            // A shape answering a bare list answers `Staged<Vec<_>>` here: a
            // `Vec` has nowhere to keep a mark, so the marks ride beside the
            // value until whatever splices its members in absorbs them. Free to
            // do, because nothing but the derivation calls a twin.
            returns: listed(&declaration.returns),
            items,
        },
    })
}

/// A twin's return type: a bare list gains its marks, everything else is itself.
///
/// Read syntactically rather than through `emit`'s reader, because this runs
/// before the twin is emitted and the answer is one shape of type. A container
/// keeps its own marks inside it and needs nothing here.
fn listed(returns: &syn::Type) -> syn::Type {
    let syn::Type::Path(path) = returns else {
        return returns.clone();
    };
    match path.path.segments.last() {
        Some(last) if last.ident == "Vec" => {
            syn::parse_quote!(::quasi_router::stage::Staged<#returns>)
        }
        _ => returns.clone(),
    }
}

fn items(items: &[Item], counters: &mut Counters) -> Result<Vec<Item>> {
    items
        .iter()
        .map(|item| self::item(item, counters))
        .collect()
}

fn item(item: &Item, counters: &mut Counters) -> Result<Item> {
    Ok(match item {
        Item::Bind { name, source } => Item::Bind {
            name: name.clone(),
            source: self::source(source, counters)?,
        },
        // Nothing an author wrote. A twin is built from a declaration, and a
        // declaration cannot carry one of these, so meeting one means the
        // rewrite has been run over its own output.
        Item::Marked { .. } => {
            return Err(syn::Error::new(
                Span::call_site(),
                "a staged twin cannot be staged again",
            ));
        }
        // A setting is one of two things, and which one decides whether a
        // guard on it can be a mark at all. See [`PLACING`].
        Item::Attribute {
            name,
            args,
            guard,
            body,
        } => {
            if let Some(guard) = guard {
                // The member around this one is being built both ways, and this
                // setting is what differs between them. Its guard becomes the
                // arm the plan asks for; the wrapper wrote the fill.
                if !placing(name)
                    && let Some(site) = counters.swapping
                {
                    return Ok(Item::Attribute {
                        name: name.clone(),
                        args: staged_args(name, args, counters)?,
                        guard: Some(Guard {
                            negated: false,
                            predicate: Predicate::Truth(plan_read("swap", site)),
                            span: guard.span,
                        }),
                        body: items(body, counters)?,
                    });
                }
                if !placing(name) {
                    return Err(syn::Error::new(
                        guard.span,
                        "a staged shape cannot guard a settling setting: it varies \
                         markup INSIDE the member its own statement produces, and \
                         a mark covers a run of members. The answer is two arms \
                         over that member -- built with the setting and without it \
                         -- which is the shape `given` already compiles to",
                    ));
                }
                // A placing setting is a member in all but name, so its guard
                // is an ordinary mark over the run it places. The setting is
                // made unconditionally and the mark says what a request
                // decides, exactly as for a guarded member.
                let site = counters.guards;
                counters.guards += 1;
                counters.enter();
                let args = staged_args(name, args, counters)?;
                // Inside the branch, because a setting that is not made places
                // none of what its body would have settled either.
                let inner = items(body, counters)?;
                let recorded = counters.exit();
                counters.wrote(Fill::Branch {
                    guard: (*guard).clone(),
                    body: recorded,
                });
                return Ok(Item::Marked {
                    site,
                    varies: crate::ast::Varies::Absent,
                    body: vec![Item::Attribute {
                        name: name.clone(),
                        args,
                        guard: None,
                        body: inner,
                    }],
                });
            }
            // A body may settle the argument under a guard, and that guard
            // is the settling case: `chosen` is ` selected` inside the
            // `<option>` this same statement produces, so what varies is the
            // markup of this member rather than a run of members beside it.
            // The member becomes two arms of itself.
            let settling: Vec<&Guard> = body
                .iter()
                .filter_map(|item| match item {
                    Item::Attribute {
                        guard: Some(guard),
                        name,
                        ..
                    } if !placing(name) => Some(guard),
                    _ => None,
                })
                .collect();
            if let Some(guard) = settling.first() {
                if settling.len() > 1 {
                    return Err(syn::Error::new(
                        guard.span,
                        "two settling settings on one member would be four arms of \
                         it, and nothing has wanted that: say one of them another \
                         way, or teach the twin the combinations",
                    ));
                }
                let site = counters.arms;
                counters.arms += 1;

                // No scope of its own, for `Fill::Arms`'s reason: both arms'
                // holes are numbered at the level around them, so the closure
                // filling the stretch these arms sit in is the one that fills
                // the arm. That is what lets one arm carry a hole the other
                // does not.
                let args = staged_args(name, args, counters)?;
                let inner = swapped(body, site, counters)?;
                counters.wrote(Fill::Swap {
                    guard: (*guard).clone(),
                });

                return Ok(Item::Marked {
                    site,
                    varies: crate::ast::Varies::Arm {
                        of: 2,
                        taken: plan_arm(site, 2),
                    },
                    body: vec![Item::Attribute {
                        name: name.clone(),
                        args,
                        guard: None,
                        body: inner,
                    }],
                });
            }

            // The argument's own holes render where the argument does, and
            // the body's settings render inside the markup the argument
            // builds. So the args are staged first and the body follows.
            Item::Attribute {
                name: name.clone(),
                args: staged_args(name, args, counters)?,
                guard: None,
                body: items(body, counters)?,
            }
        }
        // The binder is never read: every hole rooted at it was rewritten to a
        // sentinel above, so the loop runs for its count and nothing else. It
        // keeps its name with an underscore so a reader can still see which
        // loop this was.
        Item::For {
            binder,
            body,
            dereferenced,
            iterable,
        } => {
            let id = counters.loops;
            counters.loops += 1;
            counters.enter();
            let staged = items(body, counters)?;
            let inner = counters.exit();
            counters.wrote(Fill::Repeat {
                dereferenced: *dereferenced,
                binder: binder.clone(),
                iterable: iterable.clone(),
                body: inner,
            });
            Item::Marked {
                site: id,
                varies: crate::ast::Varies::Repeated,
                body: vec![Item::For {
                    dereferenced: false,
                    binder: format_ident!("_{}", binder, span = binder.span()),
                    iterable: plan_read("rows", id),
                    body: staged,
                }],
            }
        }
        // A guarded member is placed unconditionally and marked instead.
        //
        // The guard is what named the members it controls, so the twin says so
        // and the renderer records where they landed. Rendering the screen a
        // second time with the guard off, to see what went missing, is the
        // thing this replaces.
        Item::Emit(Emission::Guarded { guard, inner }) => {
            let site = counters.guards;
            counters.guards += 1;
            counters.enter();
            let inner = self::emission(inner, counters)?;
            let body = counters.exit();
            counters.wrote(Fill::Branch {
                guard: (*guard).clone(),
                body,
            });
            Item::Marked {
                site,
                varies: crate::ast::Varies::Absent,
                body: vec![Item::Emit(inner)],
            }
        }
        // A dispatch draws the arm the plan asks for, and says how many there
        // are. The derivation renders it once per arm and reads each arm's own
        // cover, so an arm may hold loops and guards of its own -- which is
        // what "the arms are flat" used to be about.
        Item::Emit(Emission::Given {
            scrutinee,
            arms,
            otherwise,
        }) => {
            let Some(otherwise) = otherwise else {
                return Err(syn::Error::new(
                    scrutinee.span(),
                    "a staged dispatch says what it does when nothing matches: \
                     a residual holds one arm per position and there has to be \
                     one to hold",
                ));
            };
            let site = counters.arms;
            counters.arms += 1;

            // Every arm's holes are numbered at THIS level rather than inside
            // the arm, which is what lets one arm carry a hole another does not.
            // See `Fill::Arms`.
            let staged = arms
                .iter()
                .map(|(pattern, arm)| {
                    Ok((pattern.clone(), Box::new(self::emission(arm, counters)?)))
                })
                .collect::<Result<Vec<_>>>()?;
            let last = Box::new(self::emission(otherwise, counters)?);

            counters.wrote(Fill::Arms {
                scrutinee: (*scrutinee).clone(),
                patterns: arms.iter().map(|(pattern, _)| pattern.clone()).collect(),
            });

            let of = staged.len() + 1;
            let taken = plan_arm(site, of);
            Item::Marked {
                site,
                varies: crate::ast::Varies::Arm {
                    of,
                    taken: taken.clone(),
                },
                body: vec![Item::Emit(Emission::Given {
                    scrutinee: taken,
                    arms: staged
                        .into_iter()
                        .enumerate()
                        .map(|(at, (_, arm))| (crate::ast::Pattern::Int(at as i64), arm))
                        .collect(),
                    otherwise: Some(last),
                })],
            }
        }
        // A member whose own body settles it under a guard: `latched when x`
        // inside a chip, which is `chosen`'s case one production over. Built
        // both ways and marked as two arms of itself, exactly as a settling
        // setting on an argument is.
        Item::Emit(emission) if settling_guard(emission).is_some() => {
            let guard = settling_guard(emission).expect("just asked");
            let site = counters.arms;
            counters.arms += 1;

            // No scope of its own, for `Fill::Arms`'s reason: both arms' holes
            // are numbered at the level around them.
            let held = counters.swapping.replace(site);
            let staged = self::emission(emission, counters)?;
            counters.swapping = held;
            counters.wrote(Fill::Swap {
                guard: guard.clone(),
            });

            Item::Marked {
                site,
                varies: crate::ast::Varies::Arm {
                    of: 2,
                    taken: plan_arm(site, 2),
                },
                body: vec![Item::Emit(staged)],
            }
        }
        Item::Emit(emission) => Item::Emit(self::emission(emission, counters)?),
    })
}

/// The one guarded settling setting in a member's own body, if it has one.
///
/// A member may settle itself under a guard, which is what `latched when x`
/// inside a chip is: what varies is the markup this statement produces rather
/// than a run of members beside it, so the member becomes two arms of itself.
///
/// Shallow on purpose. It reads the body this emission owns and no deeper: a
/// guard further in belongs to whatever member IS further in, and that member
/// is staged in its own right when the walk reaches it.
fn settling_guard(emission: &Emission) -> Option<&Guard> {
    body_of(emission)?.iter().find_map(|item| match item {
        Item::Attribute {
            guard: Some(guard),
            name,
            ..
        } if !placing(name) => Some(guard),
        _ => None,
    })
}

/// The items a member's own body holds, for the emissions that have one.
///
/// The three placement wrappers carry no body of their own and pass the
/// question to what they place, which is the same reading every other pass over
/// this grammar takes of them.
fn body_of(emission: &Emission) -> Option<&[Item]> {
    Some(match emission {
        Emission::Simple { body, .. }
        | Emission::Chip { body, .. }
        | Emission::Screen { body, .. }
        | Emission::Row { body, .. }
        | Emission::Form { body, .. }
        | Emission::Field { body, .. }
        | Emission::Act { body, .. }
        | Emission::Offers { body, .. }
        | Emission::Column { body, .. }
        | Emission::Cell { body, .. }
        | Emission::Offering { body, .. }
        | Emission::Removes { body, .. }
        | Emission::Repeats { body, .. }
        | Emission::Region { body, .. }
        | Emission::Across { body, .. } => body,
        Emission::List(body) | Emission::Table(body) | Emission::Cells(body) => body,
        Emission::Framed { inner, .. }
        | Emission::Beside { inner, .. }
        | Emission::At { inner, .. } => {
            return body_of(inner);
        }
        Emission::Guarded { .. }
        | Emission::Given { .. }
        | Emission::Activate(_)
        | Emission::Include(_)
        | Emission::IncludeEach(_)
        | Emission::Link { .. } => return None,
    })
}

/// One member's body, with its settling guard reading the plan's arm.
///
/// Arm 0 is the setting made, which is [`Plan::swap`][swap]'s own reading and
/// the one `Fill::Swap` fills against. Everything else in the body is staged
/// the ordinary way.
///
/// [swap]: quasi_router::stage::Plan::swap
fn swapped(body: &[Item], site: u16, counters: &mut Counters) -> Result<Vec<Item>> {
    body.iter()
        .map(|item| match item {
            Item::Attribute {
                name,
                args,
                guard: Some(_),
                body,
            } if !placing(name) => Ok(Item::Attribute {
                name: name.clone(),
                args: staged_args(name, args, counters)?,
                guard: Some(Guard {
                    negated: false,
                    predicate: Predicate::Truth(plan_read("swap", site)),
                    span: Span::call_site(),
                }),
                body: items(body, counters)?,
            }),
            other => self::item(other, counters),
        })
        .collect()
}

/// A guard becomes one read of the plan, and stops being negated.
///
/// `unless x` and `when not x` are the same question asked twice, and the plan
/// answers the emission rather than the predicate, so the twin keeps neither
/// spelling. The predicate's own holes are dropped: R9 says they are evaluated
/// whether or not the emission is placed, and a sentinel evaluated for a guard
/// nobody reads is a cost with no output.
fn guard(guard: &Guard, counters: &mut Counters) -> Guard {
    let id = counters.guards;
    counters.guards += 1;
    Guard {
        negated: false,
        predicate: Predicate::Truth(plan_read("guard", id)),
        span: guard.span,
    }
}

fn source(source: &Source, counters: &mut Counters) -> Result<Source> {
    Ok(match source {
        Source::Str(text) => Source::Str(interpolated(text, counters)),
        Source::Hole(hole) => Source::Hole(value(hole, counters)),
        // A dispatch has no residual, and staging one bakes an arm. The
        // `Emission::Given` arm below carries the whole reason.
        Source::Choose { scrutinee, .. } => {
            return Err(syn::Error::new(
                scrutinee.span(),
                "a staged shape cannot dispatch: only one arm reaches the \
                 residual, so the others are lost rather than compiled. Say \
                 the arms as guards -- `A when x; B unless x` -- which renders \
                 the same and derives a branch for each",
            ));
        }
    })
}

/// A value a request would have brought, which becomes one sentinel.
///
/// A hole rooted at a path is left alone. `REGION` and `PATH` are consts, so
/// they are the same string for every request and belong in the literal rather
/// than in a hole: staging them would spend a sentinel to reproduce a value the
/// renderer already baked in.
fn value(hole: &Hole, counters: &mut Counters) -> Hole {
    stand_in(hole, counters, false)
}

/// The same, for a slot that counts rather than reads. See [`counted`].
fn number(hole: &Hole, counters: &mut Counters) -> Hole {
    stand_in(hole, counters, true)
}

fn stand_in(hole: &Hole, counters: &mut Counters, counting: bool) -> Hole {
    if matches!(hole.root, HoleRoot::Path(_)) && hole.steps.is_empty() {
        return Hole {
            root: match &hole.root {
                HoleRoot::Path(path) => HoleRoot::Path(path.clone()),
                _ => unreachable!("checked above"),
            },
            steps: Vec::new(),
        };
    }
    let id = counters.holes;
    counters.holes += 1;
    counters.wrote(Fill::Hole {
        id,
        hole: hole.clone(),
    });
    // One `Fill::Hole` either way: what differs is only the alphabet the
    // stand-in is written in, and by the time the filler sees a residual a hole
    // is a hole.
    if counting { counted(id) } else { sentinel(id) }
}

fn interpolated(text: &Interpolated, counters: &mut Counters) -> Interpolated {
    Interpolated {
        parts: text
            .parts
            .iter()
            .map(|part| match part {
                StrPart::Lit(literal) => StrPart::Lit(literal.clone()),
                StrPart::Hole(hole) => StrPart::Hole(value(hole, counters)),
            })
            .collect(),
        span: text.span,
    }
}

/// The slots whose value is a structure the description builds, not a string a
/// request brings.
///
/// A hole in one of these is a constructor call: `token Tag::badge(kind)`,
/// `option Choice::new(id, name)`, `stats [Figure::new(count, "Items")]`. What
/// the slot takes is a `Tag`, a `Choice`, a `Figure` -- none of which has a
/// sentinel, so the call cannot become one, and staging it as a value fails
/// with `the trait bound Tag: Fill is not satisfied` against generated code.
///
/// The arguments are a different matter. Each of those is an ordinary value a
/// request brings, and each does have a sentinel. So the call is kept and
/// staged **through**: the derivation builds the tag with a sentinel in it, the
/// renderer draws the tag's markup around the sentinel, and the residual holds
/// the markup as a literal with the word as a hole. That is the same trade
/// [`value`] makes for a `const` path, one level down.
///
/// Slot-directed rather than a rule about calls, and that is not a shortcut.
/// `text tier_line(profile.priced, prices)` is a supplier answering a string,
/// where the whole call is the value and staging through it would hand
/// `tier_line` a sentinel where it wants a `&TierPrices`. Only the slot knows
/// which of the two it is looking at.
const STRUCTURED: &[&str] = &[
    "token", "meter", "stats", "option", "figure", "more", "back", "forward", "jumping", "chart",
    "bar",
];

/// The settings that place a member rather than settling one.
///
/// A setting is one of two things, and the vocabulary spelled both the same
/// way for a long time.
///
/// A **placing** setting adds markup at a position of its own. `more` draws a
/// pager after the rows; `figure` accretes onto a strip; `bar` onto a chart;
/// `back`, `forward` and `jumping` each draw their own control inside the
/// pager. Each is a member in all but name, each counts in its container's
/// index space, and a guard on one is an ordinary mark over the run it places.
///
/// A **settling** setting changes the markup the member its own statement
/// produces was going to write anyway: `chosen` is ` selected` inside an
/// `<option>`, `here` and `latched` are classes inside a tag. There is no run
/// of members to cover, so a guard on one is two arms over that member instead
/// -- quasicoherent `62739b91`.
///
/// Everything not here is settling, which is the safe default: a setting
/// wrongly called placing marks members its container never drew, and the
/// renderer refuses that by name.
const PLACING: &[&str] = &[
    "figure", "bar", "more", "back", "forward", "jumping", "option",
];

/// Whether a guard on this setting is a mark rather than two arms.
fn placing(name: &Ident) -> bool {
    PLACING.contains(&name.to_string().as_str())
}

/// One setting's arguments, staged the way its slot asks for.
///
/// The three answers a slot can give, in the order they are asked: a structure
/// is staged through its constructor, a count stands in as a number, and
/// anything else is an ordinary value.
fn staged_args(name: &Ident, args: &[Arg], counters: &mut Counters) -> Result<Vec<Arg>> {
    if structured(name) {
        through(args, counters)
    } else if numbered(name) {
        counting_args(args, counters)
    } else {
        self::args(args, counters)
    }
}

/// Whether this slot takes a structure rather than a value.
fn structured(name: &Ident) -> bool {
    STRUCTURED.contains(&name.to_string().as_str())
}

/// The slots whose plain arguments are numbers.
///
/// Slot-directed for [`STRUCTURED`]'s reason, and it is the same reason: only
/// the slot knows whether the value it wants is a word or a count. A pager is
/// where this arose -- `Rest::page(from, per)`, `of total`, `Jump::new(page, ..)` --
/// and every one of those is a `usize`, which has no sentinel.
///
/// Only a PLAIN argument counts: an argument that is itself a call is a
/// structure and is staged through, which is what leaves
/// `Jump::new(<page>, <action>)` with a number in the first position and an
/// `Action` in the second.
const NUMBERED: &[&str] = &["of"];

/// The constructors whose plain arguments are numbers.
///
/// Written as `Type::method` rather than as a bare method name, because `new`
/// is every constructor's name and only some of them count. A call is matched
/// on its last two segments, so a path written out in full matches too.
const NUMBERED_CALLS: &[&str] = &[
    "Rest::page",
    "Rest::showing",
    "Rest::more",
    "Jump::new",
    // A chart's axis is one number and nothing else, which is what lets the
    // whole constructor count. A bar is the case that could not: it carries a
    // place AND a magnitude, so `Bar::at` takes the place and `of` -- already
    // counted, as a pager's total is -- takes the number.
    "Chart::new",
];

/// Whether this slot's plain arguments stand in as numbers.
fn numbered(name: &Ident) -> bool {
    NUMBERED.contains(&name.to_string().as_str())
}

/// Whether this call's plain arguments stand in as numbers.
fn numbered_call(path: &syn::Path) -> bool {
    let mut tail = path
        .segments
        .iter()
        .rev()
        .take(2)
        .map(|segment| segment.ident.to_string())
        .collect::<Vec<_>>();
    tail.reverse();
    NUMBERED_CALLS.contains(&tail.join("::").as_str())
}

/// Stage a structured slot's arguments, keeping the calls that build them.
///
/// See [`STRUCTURED`]. A call is kept and its own arguments staged; anything
/// else is an ordinary value and goes through [`arg`].
fn through(args: &[Arg], counters: &mut Counters) -> Result<Vec<Arg>> {
    args.iter().map(|one| one_through(one, counters)).collect()
}

fn one_through(arg: &Arg, counters: &mut Counters) -> Result<Arg> {
    Ok(match arg {
        Arg::List(items) => Arg::List(through(items, counters)?),
        Arg::Borrow(inner) => Arg::Borrow(Box::new(one_through(inner, counters)?)),
        Arg::Hole(hole) => match &hole.root {
            HoleRoot::Call { path, args } => Arg::Hole(Hole {
                root: HoleRoot::Call {
                    path: path.clone(),
                    args: if numbered_call(path) {
                        counting_args(args, counters)?
                    } else {
                        self::args(args, counters)?
                    },
                },
                // A builder chain on the constructor -- `Tag::badge(kind).tone(..)`
                // -- carries values of its own, and they are staged the same way.
                steps: hole
                    .steps
                    .iter()
                    .map(|step| {
                        Ok(match step {
                            crate::ast::Step::Field(name) => crate::ast::Step::Field(name.clone()),
                            crate::ast::Step::Method { name, args } => crate::ast::Step::Method {
                                name: name.clone(),
                                args: if numbered(name) {
                                    counting_args(args, counters)?
                                } else {
                                    self::args(args, counters)?
                                },
                            },
                        })
                    })
                    .collect::<Result<Vec<_>>>()?,
            }),
            // Not a constructor, so there is nothing to stage through and the
            // slot is being handed a value from somewhere else. Left as
            // written: a path is a const the renderer bakes in, and a binding
            // or a method chain is refused by rustc against the slot's own
            // type, which names the site.
            _ => Arg::Hole(hole.clone()),
        },
        other => self::arg(other, counters)?,
    })
}

fn args(args: &[Arg], counters: &mut Counters) -> Result<Vec<Arg>> {
    args.iter().map(|arg| self::arg(arg, counters)).collect()
}

/// The same, for a slot [`NUMBERED`] names: a plain argument counts.
fn counting_args(args: &[Arg], counters: &mut Counters) -> Result<Vec<Arg>> {
    args.iter()
        .map(|arg| match arg {
            // A call in a counted slot is still a structure, so it is staged
            // through rather than counted. `jumping <page> <action>` is the
            // site, and the action is the second half of it.
            Arg::Hole(hole) if matches!(hole.root, HoleRoot::Call { .. }) => {
                one_through(arg, counters)
            }
            Arg::Hole(hole) => Ok(Arg::Hole(number(hole, counters))),
            other => self::arg(other, counters),
        })
        .collect()
}

fn arg(arg: &Arg, counters: &mut Counters) -> Result<Arg> {
    Ok(match arg {
        Arg::Str(text) => Arg::Str(interpolated(text, counters)),
        Arg::Hole(hole) => Arg::Hole(value(hole, counters)),
        Arg::List(items) => Arg::List(args(items, counters)?),
        Arg::Borrow(inner) => Arg::Borrow(Box::new(self::arg(inner, counters)?)),
        Arg::Int(value) => Arg::Int(*value),
        Arg::Bool(value) => Arg::Bool(*value),
    })
}

/// An action's target and its modifiers both carry addresses, and an address is
/// a value a request brings. Rewriting them is what puts every `href` and every
/// `hx-delete` into the residual as a hole rather than baking one request's
/// into the literal.
fn action(action: &crate::ast::Action, counters: &mut Counters) -> Result<crate::ast::Action> {
    Ok(crate::ast::Action {
        verb: action.verb.clone(),
        target: action
            .target
            .as_ref()
            .map(|target| arg(target, counters))
            .transpose()?,
        modifiers: action
            .modifiers
            .iter()
            .map(|modifier| {
                Ok(crate::ast::Modifier {
                    name: modifier.name.clone(),
                    args: args(&modifier.args, counters)?,
                })
            })
            .collect::<Result<Vec<_>>>()?,
    })
}

fn emission(emission: &Emission, counters: &mut Counters) -> Result<Emission> {
    Ok(match emission {
        Emission::Simple { member, args, body } => Emission::Simple {
            member: member.clone(),
            args: if structured(member) {
                through(args, counters)?
            } else {
                self::args(args, counters)?
            },
            body: items(body, counters)?,
        },
        Emission::Chip {
            value,
            action,
            removable,
            body,
        } => Emission::Chip {
            value: arg(value, counters)?,
            action: self::action(action, counters)?,
            removable: *removable,
            body: items(body, counters)?,
        },
        Emission::Screen {
            arrangement,
            args,
            body,
        } => Emission::Screen {
            arrangement: arrangement.clone(),
            args: self::args(args, counters)?,
            body: items(body, counters)?,
        },
        Emission::Row { primary, body } => Emission::Row {
            primary: arg(primary, counters)?,
            body: items(body, counters)?,
        },
        Emission::Form { action, body } => Emission::Form {
            action: self::action(action, counters)?,
            body: items(body, counters)?,
        },
        Emission::Field {
            kind,
            name,
            label,
            body,
        } => Emission::Field {
            kind: kind.clone(),
            name: arg(name, counters)?,
            label: arg(label, counters)?,
            body: items(body, counters)?,
        },
        Emission::List(body) => Emission::List(items(body, counters)?),
        Emission::Act {
            label,
            action,
            body,
        } => Emission::Act {
            label: arg(label, counters)?,
            action: self::action(action, counters)?,
            body: items(body, counters)?,
        },
        Emission::Offers {
            label,
            action,
            body,
        } => Emission::Offers {
            label: arg(label, counters)?,
            action: self::action(action, counters)?,
            body: items(body, counters)?,
        },
        Emission::Table(body) => Emission::Table(items(body, counters)?),
        Emission::Column { name, body } => Emission::Column {
            name: arg(name, counters)?,
            body: items(body, counters)?,
        },
        Emission::Cells(body) => Emission::Cells(items(body, counters)?),
        Emission::Cell {
            column,
            value,
            body,
        } => Emission::Cell {
            column: column.as_ref().map(|it| arg(it, counters)).transpose()?,
            value: arg(value, counters)?,
            body: items(body, counters)?,
        },
        Emission::Offering {
            label,
            action,
            body,
        } => Emission::Offering {
            label: arg(label, counters)?,
            action: self::action(action, counters)?,
            body: items(body, counters)?,
        },
        Emission::Removes {
            label,
            action,
            body,
        } => Emission::Removes {
            label: arg(label, counters)?,
            action: self::action(action, counters)?,
            body: items(body, counters)?,
        },
        Emission::Repeats {
            one,
            label,
            action,
            body,
        } => Emission::Repeats {
            one: arg(one, counters)?,
            label: arg(label, counters)?,
            action: self::action(action, counters)?,
            body: items(body, counters)?,
        },
        Emission::Activate(action) => Emission::Activate(self::action(action, counters)?),
        Emission::Link { text, action } => Emission::Link {
            text: arg(text, counters)?,
            action: self::action(action, counters)?,
        },
        Emission::Include(hole) => Emission::Include(include(hole, counters)?),
        // The plural, staged the same way: the callee has a twin of its own and
        // a filler of its own, and the caller splices a reference to both.
        Emission::IncludeEach(hole) => Emission::IncludeEach(include(hole, counters)?),
        Emission::Region { name, kind, body } => Emission::Region {
            name: arg(name, counters)?,
            kind: match kind {
                RegionKind::Variant(variant) => RegionKind::Variant(variant.clone()),
                // A `RegionKind` has no sentinel, so a supplied one is refused
                // -- unless nothing about it is supplied. `RegionKind::ceded("revenue-chart")`
                // names a path and passes a literal, which is the same value on
                // every request, so it is evaluated once while the residual is
                // derived. That is `#[constant]`'s rule one level down, and it
                // is the same test: every argument fixed where it is written.
                RegionKind::Supplied(hole) => {
                    let fixed_kind = match &hole.root {
                        HoleRoot::Path(_) => hole.steps.is_empty(),
                        HoleRoot::Call { args, .. } => {
                            hole.steps.is_empty() && args.iter().all(fixed)
                        }
                        HoleRoot::Binding(_) => false,
                    };
                    if !fixed_kind {
                        return Err(syn::Error::new(
                            hole.span(),
                            "a staged shape cannot take its region kind from a supplier \
                             that reads the request: a `RegionKind` has no sentinel to \
                             stand in for it",
                        ));
                    }
                    RegionKind::Supplied(hole.clone())
                }
            },
            body: items(body, counters)?,
        },
        Emission::Across { fallback, body } => Emission::Across {
            fallback: fallback.clone(),
            body: items(body, counters)?,
        },
        // The name of a frame is written where the member is placed and is not
        // a value a request brings, so staging walks through it and leaves it
        // alone.
        Emission::Framed { label, inner } => Emission::Framed {
            label: label.clone(),
            inner: Box::new(self::emission(inner, counters)?),
        },
        Emission::Beside {
            priority,
            width,
            inner,
        } => Emission::Beside {
            priority: arg(priority, counters)?,
            width: width.as_ref().map(|held| arg(held, counters)).transpose()?,
            inner: Box::new(self::emission(inner, counters)?),
        },
        Emission::At { at, inner } => Emission::At {
            at: arg(at, counters)?,
            inner: Box::new(self::emission(inner, counters)?),
        },
        Emission::Guarded { guard, inner } => {
            let staged = self::guard(guard, counters);
            counters.enter();
            let inner = Box::new(self::emission(inner, counters)?);
            let body = counters.exit();
            counters.wrote(Fill::Branch {
                guard: (*guard).clone(),
                body,
            });
            Emission::Guarded {
                guard: staged,
                inner,
            }
        }
        // A dispatch has no residual, and staging one is silently wrong.
        //
        // The derivation finds a branch by rendering the screen twice with one
        // guard changed and reading the difference, and it finds a loop the same
        // way with a row count. A dispatch is neither: its arms replace each
        // other at one position, so there is no insertion to measure and no
        // deletion to put back, and every arm would claim the same bytes.
        //
        // What happened instead was worse than a refusal. The staged twin reads
        // `plan.arm(id)`, which answers zero, so exactly one arm rendered and
        // the residual held it as a literal with the others simply gone. MNW's
        // forum settings pane compiled to "You haven't joined any forum
        // communities yet." and would have served that to every reader.
        //
        // Refused rather than modelled. `Op::Arms` and a derivation that renders
        // once per arm is the general answer and is a feature rather than a fix;
        // every dispatch in the tree today is two-way over a bool, which is two
        // guards, which the residual already has a shape for.
        Emission::Given {
            scrutinee,
            arms,
            otherwise,
        } => {
            let Some(otherwise) = otherwise else {
                return Err(syn::Error::new(
                    scrutinee.span(),
                    "a staged dispatch says what it does when nothing matches: \
                     a residual holds one arm per position and there has to be \
                     one to hold",
                ));
            };
            let id = counters.arms;
            counters.arms += 1;

            // Every arm's holes are numbered at THIS level rather than inside
            // the arm, which is what lets one arm carry a hole another does not.
            // See `Fill::Arms`.
            let staged = arms
                .iter()
                .map(|(pattern, arm)| {
                    Ok((pattern.clone(), Box::new(self::emission(arm, counters)?)))
                })
                .collect::<Result<Vec<_>>>()?;
            let last = Box::new(self::emission(otherwise, counters)?);

            counters.wrote(Fill::Arms {
                scrutinee: (*scrutinee).clone(),
                patterns: arms.iter().map(|(pattern, _)| pattern.clone()).collect(),
            });

            let count = staged.len() + 1;
            Emission::Given {
                // The twin asks the plan which arm to render, and the plan is
                // told how many there are so a traced render can say so: the
                // derivation renders this site once per arm and nothing else
                // counts them.
                scrutinee: plan_arm(id, count),
                arms: staged
                    .into_iter()
                    .enumerate()
                    .map(|(at, (_, arm))| (crate::ast::Pattern::Int(at as i64), arm))
                    .collect(),
                otherwise: Some(last),
            }
        }
    })
}

/// An `include` retargets to the callee's staged twin, and drops its arguments.
///
/// This is what makes a residual compose. The callee is staged in its own
/// right, numbered in its own namespace, so a caller splices a reference rather
/// than inlining a body, and a screen's guards do not multiply through its
/// parts.
///
/// The arguments go because the twin takes the plan and nothing else, scoped by
/// this include's ordinal so the shape it reaches numbers its holes without
/// colliding with its caller's or its siblings'.
///
/// The old note: That the
/// callee has a twin at all is decided by ordinary name resolution: an
/// `include` of a shape that is not declared, or is declared without
/// `#[staged]`, is a compile error naming the function that does not exist,
/// which is the honest report and the one a reader can act on.
fn include(hole: &Hole, counters: &mut Counters) -> Result<Hole> {
    let HoleRoot::Call { path, .. } = &hole.root else {
        return Err(syn::Error::new(
            hole.span(),
            "a staged `include` names a shape to call: a value supplied from a \
             binding has no sentinel to stand in for it",
        ));
    };
    if !hole.steps.is_empty() {
        return Err(syn::Error::new(
            hole.span(),
            "a staged `include` calls a shape and reads nothing off it",
        ));
    }

    let HoleRoot::Call { args, .. } = &hole.root else {
        unreachable!("checked above");
    };

    // Every argument a literal, so there is nothing here a request decides and
    // no scope worth opening. The call is rewritten to the callee's
    // `#[constant]` shim and evaluated where it stands: the markup it produces
    // is derived once into the residual rather than built and rendered on every
    // request. `/policy` is the site, six times -- each section's prose is
    // `own_prose` of a literal, and before this the literal was dropped at the
    // boundary and the twin put a sentinel through docengine instead.
    //
    // A shape that made no promise has no shim, so the rewritten call does not
    // resolve and rustc names it. That is the whole enforcement: the macro
    // cannot read another `declare!`'s flags, and inlining on the arguments
    // alone would bake one evaluation of a shape that reads a clock into the
    // residual and serve it forever.
    if args.iter().all(fixed) {
        let mut path = path.clone();
        let last = path
            .segments
            .last_mut()
            .ok_or_else(|| syn::Error::new(hole.span(), "an empty path"))?;
        last.ident = constant_name(&last.ident);
        return Ok(Hole {
            root: HoleRoot::Call {
                path,
                args: args.clone(),
            },
            steps: Vec::new(),
        });
    }

    // The filler calls the shape's own name, not the twin's: the twin renders
    // markup and the filler fills it, and they are two different functions
    // beside one declaration.
    let site = counters.sites;
    counters.sites += 1;

    counters.wrote(Fill::Include {
        callee: path.clone(),
        args: args.clone(),
        site,
    });

    let mut path = path.clone();
    let last = path
        .segments
        .last_mut()
        .ok_or_else(|| syn::Error::new(hole.span(), "an empty path"))?;
    last.ident = staged_name(&last.ident);

    Ok(Hole {
        root: HoleRoot::Call {
            path,
            args: vec![Arg::Borrow(Box::new(Arg::Hole(Hole {
                root: HoleRoot::Binding(Ident::new(PLAN, Span::call_site())),
                steps: vec![crate::ast::Step::Method {
                    name: Ident::new("enter", Span::call_site()),
                    args: vec![Arg::Int(i64::from(site))],
                }],
            })))],
        },
        steps: Vec::new(),
    })
}

impl Hole {
    /// Where to report a refusal, which is the root the hole was written at.
    pub(crate) fn span(&self) -> Span {
        match &self.root {
            HoleRoot::Binding(name) => name.span(),
            HoleRoot::Path(path) | HoleRoot::Call { path, .. } => syn::spanned::Spanned::span(path),
        }
    }
}