ingraph-codegen 0.1.0

The emission engine behind ingraph-derive: a plain declaration model in, the ingraph framework faces out.
Documentation
//! The MIRROR emitter's acceptance, over models built BY HAND.
//!
//! No declaration is parsed here, for the reason [`crate::tests`] states: the split that lets a
//! front end other than the attribute reach this emitter only exists while the emitter can be driven
//! from a plain model.
//!
//! What this suite watches is the TWO-MODE law and the three things the axis emits. The law is
//! checked as a TOKEN claim rather than a description — a declaration naming no upstream emits what
//! it always did, and a mirror emits that same stream with one block behind it — because a fork
//! written as *the mirror also emits …* is exactly the kind of claim that quietly stops being true.

use quote::ToTokens as _;

use super::super::{BitWidth, FlagBit, FlagsModel};

/// The declaration the module is measured against: three bits, one of them naming an upstream
/// `const` spelled differently, at the widest width this kind carries.
fn mirror() -> FlagsModel {
  FlagsModel {
    remote: Some(syn::parse_quote!(upstream::Disposition)),
    ..declared()
  }
}

/// The SAME declaration with no upstream — the control for every two-mode claim.
fn declared() -> FlagsModel {
  FlagsModel {
    krate: syn::parse_quote!(::ingraph),
    vis: syn::parse_quote!(pub),
    name: ident("Disposition"),
    width: BitWidth::U32,
    bits: vec![
      bit("Default", None, 0x1),
      bit("Forced", None, 0x2),
      bit("Hi", Some("HEARING_IMPAIRED"), 0x4),
    ],
    attrs: vec![syn::parse_quote!(#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)])],
    remote: None,
    wire_name: None,
  }
}

/// The same mirror at the NARROWEST width, which is what the width obligation is measured over.
fn narrow() -> FlagsModel {
  FlagsModel {
    width: BitWidth::U8,
    ..mirror()
  }
}

fn bit(name: &str, upstream: Option<&str>, value: u128) -> FlagBit {
  FlagBit {
    ident: ident(name),
    rename: None,
    upstream: upstream.map(ident),
    value,
    attrs: Vec::new(),
  }
}

fn ident(name: &str) -> syn::Ident {
  syn::Ident::new(name, proc_macro2::Span::call_site())
}

/// The whole expansion as one string, with the spacing removed, so a claim about it can be a
/// substring.
fn rendered(model: &FlagsModel) -> String {
  model.emit().to_token_stream().to_string().replace(' ', "")
}

/// **TWO MODES, ONE WORD, AND NO POLLUTION.** A declaration naming no upstream emits exactly the
/// stream it emitted before this axis existed, and a mirror emits that stream with one block behind
/// it.
///
/// A PREFIX claim rather than a pair of substrings, and that is the whole point: it is false the
/// moment the mirror mode moves one token in front of it. The two-mode law is written into the
/// emitter's shape — `emit` appends `mirror` and forks nothing — and this is what holds it there.
#[test]
fn a_declaration_naming_no_upstream_emits_what_it_always_did() {
  let plain = rendered(&declared());
  let mirrored = rendered(&mirror());

  assert!(
    mirrored.starts_with(&plain),
    "the mirror is the declared expansion plus a block, not a different expansion"
  );
  assert!(
    !plain.contains("__IngraphMirrorWidth"),
    "and a declaration with no upstream carries not one token of the axis"
  );
  assert!(!plain.contains("::core::convert::From"));
}

/// **BOTH LEGS ARE `from_bits_retain`**, which is the absorption law: a bit the declaration never
/// named survives the crossing rather than being truncated away.
///
/// `from_bits` is the emission this pin exists to refuse — it would make an upstream release that
/// grows a bit a runtime failure at the crossing, which is the failure the whole mode prevents.
#[test]
fn the_crossing_retains_a_bit_this_declaration_never_named() {
  let emitted = rendered(&mirror());

  assert!(emitted.contains("impl::core::convert::From<upstream::Disposition>forDisposition"));
  assert!(emitted.contains("impl::core::convert::From<Disposition>forupstream::Disposition"));
  assert_eq!(
    emitted.matches("from_bits_retain(").count(),
    2,
    "one CALL per leg, and no other constructor — the trailing `(` is what keeps the width \
     obligation's own prose, which quotes the word, out of the count"
  );
  assert!(
    !emitted.contains("from_bits_truncate"),
    "nothing truncates a bit on the way through"
  );
}

/// **ONE DRIFT PIN PER RESTATED BIT**, comparing this declaration's number against the `const` it
/// restates.
///
/// The cast to `u128` is part of the claim: it is what keeps a width fault from becoming one
/// `E0308` per bit beside the one named refusal the width obligation already produces.
#[test]
fn every_restated_bit_is_pinned_against_its_upstream_const() {
  let emitted = rendered(&mirror());

  assert_eq!(
    emitted.matches("::core::assert!").count(),
    3,
    "one per bit and no more"
  );
  assert!(emitted.contains("Disposition::DEFAULT.bits()as::core::primitive::u128"));
  assert!(emitted.contains("upstream::Disposition::DEFAULT.bits()as::core::primitive::u128"));
  assert!(
    emitted.contains("upstream::Disposition::HEARING_IMPAIRED.bits()"),
    "the renamed bit is pinned against the upstream `const` it names"
  );
  assert!(
    emitted.contains("Disposition::HI.bits()"),
    "and against its OWN word, which the rename did not move"
  );
}

/// **The WIDTH obligation is implemented for exactly one primitive** — the declared one — which is
/// what makes an upstream carrying another width an unsatisfied bound with this framework's sentence
/// on it rather than an `E0308` inside the expansion.
#[test]
fn the_width_obligation_admits_the_declared_width_and_no_other() {
  for (model, primitive, other) in [(mirror(), "u32", "u8"), (narrow(), "u8", "u32")] {
    let emitted = rendered(&model);
    assert!(emitted.contains(&format!(
      "impl__IngraphMirrorWidthfor::core::primitive::{primitive}"
    )));
    assert!(
      !emitted.contains(&format!(
        "impl__IngraphMirrorWidthfor::core::primitive::{other}"
      )),
      "one width is admitted, and it is the declared one"
    );
    assert!(
      emitted.contains("diagnostic::on_unimplemented"),
      "and it reports itself"
    );
  }
}

/// **A mirror emits no materialization gate and no reference family.**
///
/// The vocabulary mirror emits `remote()` because its escape holds a WORD and turning one back into
/// an upstream value is real work. Here the crossing is a number and `From` is total in both
/// directions, so a gate beside it would be a second name for one conversion — and `AsRef`/`Deref`
/// over a restatement could not be sound in either mode.
#[test]
fn a_mirror_has_no_gate_beside_its_conversions() {
  let emitted = rendered(&mirror());

  assert!(!emitted.contains("fnremote"));
  assert!(!emitted.contains("AsRef"));
  assert!(!emitted.contains("Deref"));
  assert!(!emitted.contains("Borrow"));
}