ingraph-codegen 0.1.0

The emission engine behind ingraph-derive: a plain declaration model in, the ingraph framework faces out.
Documentation
//! The AGGREGATE's emission: the record it mounts, and the fold that fills it.
//!
//! # It emits a RECORD, and that is most of the design
//!
//! [`Mounted`] holds the two halves the front end built: the `(group…, measure…)` row parsed by the
//! ORDINARY record pass, and the declaration that says how the row is filled. So a mounted
//! aggregate has the `*Key` type, the per-database rows, the `find_<db>` / `upsert_<db>` doors, the
//! order-by vocabulary, the cursor, the `<Node>Due` clock vocabulary and the polling apparatus that
//! every declared record has — because it IS one — and this file adds exactly the one thing a
//! record cannot say: what a group's rows fold into.
//!
//! That is `#[ingraph::journal]`'s shape verbatim, one kind over. The two differ in what they mint:
//! a journal mints the WHOLE row and refuses an author who wrote a field, and an aggregate mints
//! none of it — the author declared every column — and mints the KEY instead, which is the one
//! thing about the shape their two role words decide rather than write.
//!
//! # The RECOMPUTE is a fold and TWO REACHES, not three emissions
//!
//! The closed design's trigger reads the upstream's rows, groups them, folds each group and upserts
//! one row per group. Two of those four steps are the record machinery's own and arrive with the
//! mount above — `Upstream::find_<db>(…).fetch()` is the read and `Self::upsert_<db>(…)` is the
//! keyed replace, both emitted by the record pass for both nodes — so what is written HERE is the
//! middle: [`AggregateModel::fold`], every row in, one row per group out.
//!
//! **The keyed replace is why duplicates cannot accumulate, and the immunity is structural rather
//! than checked.** A recompute consumes a TABLE: running it twice over one table state writes the
//! same rows to the same addresses, and a row the upstream no longer holds simply stops being
//! counted. Nothing dedups, nothing retracts, and there is no tombstone contract — see the kind's
//! own note in [`super`].
//!
//! # WHY THE PARTITION IS A LINEAR PROBE OVER [`PartialEq`]
//!
//! A group key is a tuple of the declaration's own group columns, whose types are the AUTHOR's.
//! Hashing would demand `Hash + Eq` of every one of them and sorting would demand `Ord`, and both
//! are a bound this fold does not need: the answer is the same either way, and the cost is a walk
//! over the groups a table HAS rather than over its rows. A codec census has a dozen groups and a
//! per-language duration has a hundred, so the quadratic term is over the small number — and what
//! it buys is that a column keyed by a type with an equality and no ordering is declarable at all.
//!
//! # THE MEASURE CALLS ARE STATIC, and the item type is written rather than inferred
//!
//! A declaration names its measure at compile time, so every fold is a monomorphized call on a
//! concrete citizen: no wire enum, no visitor, no dynamic dispatch. Each is spelled
//! `<F as Measure<T>>::fold(…)` in fully qualified form with `T` written out, because [`Counting`]
//! implements the trait at EVERY item type there is — an inferred call over it is `E0282`, which is
//! the measurement its own `NAME` const records one crate over.
//!
//! [`Counting`]: ../../../ingraph/measure/struct.Counting.html
//! [`Measure`]: ../../../ingraph/measure/trait.Measure.html

use proc_macro2::TokenStream;
use quote::{format_ident, quote, quote_spanned};
use syn::spanned::Spanned as _;

use super::{AggregateModel, Measure, Measured, Owed};
use crate::{
  emit::{framework, leading},
  model::RecordModel,
};

#[cfg(test)]
mod tests;

/// A MOUNTED aggregate: the record it IS, and the declaration that folds into it.
///
/// PLAIN, for the reason every model in this crate has plain fields: the derive today and a
/// manifest front end later reach the same emitter.
///
/// Two models rather than one flattened, which is `JournalModel`'s own shape: the record half is
/// the record pass's output and is not this grammar's to edit, and the aggregate half is every word
/// the record grammar has no seat for. A reader of either knows which authority wrote it.
#[derive(Debug, Clone)]
pub struct Mounted {
  /// The record this aggregate IS — the author's columns, keyed by the group projection, parsed by
  /// the ordinary record pass under [`NodeKind::Aggregate`](crate::model::NodeKind::Aggregate).
  pub record: RecordModel,
  /// The declaration that fills it: the upstream, the group projection and the measures.
  pub aggregate: AggregateModel,
}

impl Mounted {
  /// The record's own expansion, and the fold over it.
  #[must_use]
  pub fn emit(&self) -> TokenStream {
    let record = self.record.emit();
    let fold = self.aggregate.fold();
    quote! {
      #record
      #fold
    }
  }
}

impl AggregateModel {
  /// `fn fold(rows: &[Upstream]) -> Vec<Self>` — the recompute's whole arithmetic.
  ///
  /// An INHERENT method inside the anonymous const, which is where every inherent item this crate
  /// emits lands: it binds no framework trait, it is reached as `<Aggregate>::fold`, and a name that
  /// leaked into the declarer's scope would be a second thing the declaration brought into being
  /// without saying so.
  ///
  /// # The signature is the declaration's two ends and nothing between them
  ///
  /// `&[Upstream]` in, because the read is the record machinery's — an aggregate's upstream is a
  /// record, so `Upstream::find_<db>(pool).fetch()` is already emitted at ITS declaration and this
  /// one would be a second door onto one lane. `Vec<Self>` out, because the write is too: each row
  /// goes to `Self::upsert_<db>`, whose keyed replace is what makes a whole recompute safe to run
  /// on every tick.
  ///
  /// Nothing here is `async` and nothing here fails. A fold over values in memory has no await to
  /// spend and no refusal to make — the two ends that can are the two the record pass owns — so the
  /// answer is a `Vec` rather than a `Result` a caller would `?` over unconditionally.
  pub(crate) fn fold(&self) -> TokenStream {
    let (aggregate, vis) = (&self.aggregate, &self.vis);
    let upstream = &self.upstream;
    let measure = framework(&self.krate, &["measure"], "Measure");

    let held = quote!(::std::vec::Vec<&#upstream>);
    let key_types = self.groups.iter().map(|grouped| &grouped.ty);
    let key_reads = self
      .groups
      .iter()
      .map(|grouped| read(upstream, &grouped.from));
    let key_binds: Vec<&syn::Ident> = self.groups.iter().map(|grouped| &grouped.field).collect();
    let filled = self
      .measures
      .iter()
      .map(|measured| self.measured(measured, &measure));

    let doc = leading(&format!(
      "Fold every row `{upstream}` holds into one [`{aggregate}`] per group.",
      upstream = path_text(upstream),
    ));
    let whole = leading(
      "The recompute's ARITHMETIC, and the recompute is WHOLE: it consumes the upstream's rows as a \
       TABLE rather than as messages, so running it twice over one table state writes the same rows \
       to the same addresses, and a row the upstream no longer holds simply stops being counted. \
       Duplicate delivery cannot reach it and deletion needs no retraction — both fall out of the \
       shape rather than being checked.",
    );
    let ends = leading(&format!(
      "The two ENDS are the record machinery's, reached rather than restated: read the upstream's \
       table with its own `find_<db>(…).fetch()`, hand the rows here, and write each answer back \
       through [`{aggregate}`]'s `upsert_<db>`, whose KEYED REPLACE is what makes running this on \
       every tick safe."
    ));
    let ordering = leading(
      "The rows come back in FIRST-SEEN group order — the order the upstream's rows presented the \
       groups in — which is not a sort and is not promised to be one: a caller that wants an order \
       reads the table back through the query lane, where an order is written.",
    );

    quote! {
      impl #aggregate {
        #[doc = #doc]
        #[doc = ""]
        #[doc = #whole]
        #[doc = ""]
        #[doc = #ends]
        #[doc = ""]
        #[doc = #ordering]
        #[must_use]
        // EVERY COLUMN READ IS A CLONE, and a macro cannot know which of them is a `Copy`. The
        // borrowing accessor is the one every column has, so the read is `Clone::clone` over its
        // answer — and over a `Copy` column that is `clone_on_copy`, a default-on lint, reported
        // inside an expansion its author cannot edit and fatal to any consumer building under
        // `-D warnings`. The record's own conversions dodge it by call FORM, taking a reference to
        // a PLACE; there is no place here, the value arriving from a call, so the lint is answered
        // where it fires. `allow` and not `expect` for `wide_signature`'s reason: an unfulfilled
        // `expect` is itself a warning, so a declaration whose every column is non-`Copy` would
        // fail on the silencer.
        #[allow(clippy::clone_on_copy)]
        #vis fn fold(__ig_rows: &[#upstream]) -> ::std::vec::Vec<Self> {
          let mut __ig_groups: ::std::vec::Vec<((#(#key_types,)*), #held)> =
            ::std::vec::Vec::new();
          for __ig_row in __ig_rows {
            let __ig_key = (#(#key_reads,)*);
            match __ig_groups
              .iter_mut()
              .find(|(__ig_seen, _)| *__ig_seen == __ig_key)
            {
              ::core::option::Option::Some((_, __ig_held)) => __ig_held.push(__ig_row),
              ::core::option::Option::None => {
                let mut __ig_first: #held = ::std::vec::Vec::new();
                __ig_first.push(__ig_row);
                __ig_groups.push((__ig_key, __ig_first));
              }
            }
          }
          __ig_groups
            .into_iter()
            .map(|((#(#key_binds,)*), __ig_held)| Self {
              #(#key_binds,)*
              #(#filled)*
            })
            .collect()
        }
      }
    }
  }

  /// ONE measure column, as the field it fills and the static call that fills it.
  ///
  /// # `Owed` decides WHAT THE SLICE IS, which is the whole of what this position asks it
  ///
  /// The axis the grammar checked the `from` seat against answers the emission's own question one
  /// step later. A fold that owes its entry a COLUMN is handed that column's values, cloned out of
  /// each row of the group; a fold that owes NOTHING is handed the group's ROWS, which is what
  /// `counting` wants — it answers how many there are about items of every type there is. A fold the
  /// declaring crate wrote takes whichever its entry named, because what it reads is its author's
  /// knowledge and the grammar refused neither spelling.
  ///
  /// # The CITIZEN is `Default`-constructed, and a shipped word and a quoted path meet there
  ///
  /// The elected-fold seat one kind over resolves its shorthand into a path and constructs both the
  /// same way, and this is that law read at the second position that has it: a bare word names a
  /// framework citizen, a quoted path names the declaring crate's own type, and neither is
  /// privileged at the construction. A fold with no [`Default`] is `E0277` at the entry that named
  /// it, which is where its author can act on it.
  fn measured(&self, measured: &Measured, measure: &TokenStream) -> TokenStream {
    let field = &measured.field;
    let at = field.span();
    let fold = self.citizen(&measured.by);
    let built = quote_spanned!(at=> <#fold as ::core::default::Default>::default());
    let upstream = &self.upstream;

    let value = match (measured.by.owed(), measured.from.as_ref()) {
      // THE COLUMN: the fold reads one, so the slice is that column's values. Cloned rather than
      // borrowed because a fold takes `&[T]` over items and the values live one field inside rows
      // this walk does not own.
      (Owed::Column | Owed::Theirs, Some(from)) => {
        let read = read(upstream, from);
        quote_spanned! {from.span()=>
          {
            let __ig_column: ::std::vec::Vec<_> = __ig_held
              .iter()
              .map(|__ig_row| #read)
              .collect();
            <#fold as #measure<_>>::fold(&#built, &__ig_column)
          }
        }
      }
      // THE ROWS: the fold reads no column, so the items ARE the group's rows. The item type is
      // WRITTEN — `Counting` implements the trait at every type there is, so an inferred call over
      // it is `E0282`.
      (Owed::Nothing | Owed::Theirs, _) => {
        quote_spanned!(at=> <#fold as #measure<&#upstream>>::fold(&#built, &__ig_held))
      }
      // Unreachable through the grammar: `Owed::Column` without a `from` is the entry the front end
      // refuses by name. Spelled as the rows so a model built by hand still emits something that
      // compiles or says why, rather than a `todo!` a reader has to trust nobody reaches.
      (Owed::Column, None) => {
        quote_spanned!(at=> <#fold as #measure<&#upstream>>::fold(&#built, &__ig_held))
      }
    };
    quote_spanned!(at=> #field: #value,)
  }

  /// The TYPE a measure entry named — a shipped citizen through the shelf, or the path as written.
  ///
  /// The shorthand resolves HERE, which is the one place that knows where the shelf is. It is the
  /// elected fold's own line one kind over, and both arms arrive at one construction.
  fn citizen(&self, by: &Measure) -> TokenStream {
    match by {
      Measure::Counting => framework(&self.krate, &["measure"], "Counting"),
      Measure::Summing => framework(&self.krate, &["measure"], "Summing"),
      Measure::Declared(path) => quote_spanned!(path.span()=> #path),
    }
  }
}

/// READ ONE COLUMN out of an upstream row, by value.
///
/// The borrowing accessor and a clone, at the span of the STRING that named the column — so a
/// column the upstream has not got is `E0599` where the author wrote its name rather than somewhere
/// inside an expansion. `<field>_ref` is the one accessor every column has: `copy` ADDS `<field>()`
/// beside it and renames nothing, which is what makes reading through the borrow safe whatever the
/// upstream declared.
///
/// Fully qualified through the upstream's own path rather than as a method call, so the read cannot
/// pick up an inherent method of some other type that happens to be in scope.
fn read(upstream: &syn::Path, from: &syn::Ident) -> TokenStream {
  let reader = format_ident!("{from}_ref", span = from.span());
  quote_spanned!(from.span()=> ::core::clone::Clone::clone(#upstream::#reader(__ig_row)))
}

/// The upstream's path as the declaration wrote it, for a doc line.
fn path_text(path: &syn::Path) -> String {
  path
    .segments
    .iter()
    .map(|segment| segment.ident.to_string())
    .collect::<Vec<_>>()
    .join("::")
}