ingraph-codegen 0.1.0

The emission engine behind ingraph-derive: a plain declaration model in, the ingraph framework faces out.
Documentation
//! **THE NAMING TOWER** — three tiers over ONE word, measured tier by tier.
//!
//! The ruling of 2026-08-13, in the user's own words: *跟着复数走, 有层级关系, 如果用户主动 rename
//! connection 的名字, 那么 connection 的名字用用户指定的, 我们是 tiered, 一层覆盖一层*. The page
//! names follow the PLURAL, and each layer covers the one below it:
//!
//! | tier | written by | this file's rows |
//! |---|---|---|
//! | the derived plural | the pluraliser | [`the_base_tier_is_the_records_own_plural`] |
//! | `graphql(plural = "…")` | the declaration, once | [`one_declared_plural_moves_the_field_the_page_and_the_edge`] |
//! | `connection(rename)` / `edge(rename)` | the declaration, per name | [`a_rename_covers_the_plural_for_the_one_name_it_writes`] |
//!
//! # What the middle tier is FOR, and the assertion that would fail without it
//!
//! *一起跟* — one override point. A declaration correcting English writes `plural = "corpora"` and
//! gets `corpora(…): CorporaConnection` with `CorporaEdge` beside it, never
//! `corpora(…): CorpusesConnection`. The property that buys it is not a rule stated three times but
//! ONE resolved value read three times: `emit::wire::published_plural` is the authority, the field
//! lowers its initial and the two type names raise it, and
//! [`one_declared_plural_moves_the_field_the_page_and_the_edge`] asks all three of those spellings
//! about one declaration in one assertion. A second derivation anywhere — a marker that re-pluralised
//! the record's name rather than reading the resolved word — makes that row red.
//!
//! # Why the WORD is read out of the marker's BODY
//!
//! Each marker carries the word twice: in the `type_name` body, which is what a schema reads, and in
//! the doc prose above it. This file reads the BODY. A test matching the prose would pass on a doc
//! that had drifted from the code under it, which is the one failure a naming test exists to catch.
//!
//! The FACE's side of the tower — that these markers land inside the wire face's anonymous const and
//! that both paged legs close on them — is executed against a real schema in
//! `ingraph/tests/wire_page_tower.rs`, where the SDL is read rather than the tokens.

use quote::ToTokens as _;

use super::{page_type, root_field};
use crate::model::{Graphql, RecordModel};

/// The fixture — `VideoTrack`, whose derived plural is `VideoTracks` — with the tower set however a
/// case wants it.
fn record(knob: impl FnOnce(&mut Graphql)) -> RecordModel {
  let mut model = crate::tests::wired();
  knob(model.graphql.as_mut().expect("the fixture has a wire face"));
  model
}

/// The word ONE marker hands a schema: the string literal its `type_name` body returns.
fn word(tokens: &str, marker: &str) -> String {
  let at = tokens
    .find(&format!("for {marker}"))
    .unwrap_or_else(|| panic!("`{marker}` is minted:\n{tokens}"));
  let body = &tokens[at..];
  let opened = body
    .find("to_owned (\"")
    .unwrap_or_else(|| panic!("`{marker}`'s body hands a literal back:\n{body}"))
    + "to_owned (\"".len();
  let rest = &body[opened..];
  let closed = rest
    .find('"')
    .unwrap_or_else(|| panic!("`{marker}`'s literal closes:\n{rest}"));
  rest[..closed].to_owned()
}

/// The page and the edge, as a schema will read them.
fn published(model: &RecordModel) -> (String, String) {
  let graphql = model.graphql.as_ref().expect("the wire face");
  let tokens = model
    .page_names(graphql, true)
    .to_token_stream()
    .to_string();
  (
    word(&tokens, "VideoTrackConnectionName"),
    word(&tokens, "VideoTrackEdgeName"),
  )
}

/// The LIST FIELD's own name, spelled the way `list_leg` spells it — the one resolved plural with a
/// lowered initial.
fn list_field(model: &RecordModel) -> String {
  let graphql = model.graphql.as_ref().expect("the wire face");
  root_field(&crate::emit::wire::published_plural(graphql, model))
}

/// **THE TYPE SPELLING IS THE FIELD SPELLING'S EXACT INVERSE** — one initial, in the other direction,
/// and not one other letter touched.
///
/// The pair is what lets a declaration write its plural in either case and reach one field and one
/// pair of type names. The last two rows are why this is not `heck`: `UpperCamelCase` re-cases the
/// WHOLE word, so an acronym a declaration wrote would come back mangled, and `super::super::wire`'s
/// `wire_type` states the law that forbids that — a name a declaration chose is a name it chose.
#[test]
fn a_page_type_is_a_root_fields_exact_inverse() {
  assert_eq!(page_type("corpora"), "Corpora");
  assert_eq!(page_type("Corpora"), "Corpora");
  assert_eq!(page_type(&root_field("VideoTracks")), "VideoTracks");
  assert_eq!(root_field(&page_type("videoTracks")), "videoTracks");

  // `heck` would answer `IptcRecords` and `XmlDocs` here, which is a second casing opinion over a
  // word nobody asked it about.
  assert_eq!(page_type("IPTCRecords"), "IPTCRecords");
  assert_eq!(page_type("xmlDocs"), "XmlDocs");

  // Degenerate inputs are answered rather than panicked on, exactly as `root_field` answers them.
  assert_eq!(page_type(""), "");
  // A multi-scalar raising is carried whole — `fi` upper-cases to two characters — which
  // `chars().next()` alone would have lost.
  assert_eq!(page_type("\u{fb01}les"), "FIles");
}

/// **TIER 1 — the base is the record's own DERIVED PLURAL**, and the singular the Relay
/// specification would have spelled is nowhere.
#[test]
fn the_base_tier_is_the_records_own_plural() {
  let model = record(|_| {});

  assert_eq!(
    published(&model),
    (
      "VideoTracksConnection".to_owned(),
      "VideoTracksEdge".to_owned()
    )
  );
  assert_eq!(
    list_field(&model),
    "videoTracks",
    "the same word the field is named from"
  );
}

/// **TIER 2 — ONE DECLARED PLURAL MOVES THREE NAMES**, which is the whole of *一起跟*.
///
/// `plural = "corpora"` is written once, and the field, the page and the edge all say it. The
/// contrast the user gave is the assertion's real subject: a page named `CorpusesConnection` beside a
/// field named `corpora` is precisely what a SECOND derivation produces, and it is what this row
/// refuses. Nothing here re-pluralises `VideoTrack`; every spelling comes back from the one word.
///
/// The declared word is deliberately unrelated to the record's name, so a marker that had ignored the
/// declaration and pluralised `VideoTrack` for itself answers `VideoTracksConnection` and fails
/// visibly rather than coincidentally agreeing.
#[test]
fn one_declared_plural_moves_the_field_the_page_and_the_edge() {
  let model = record(|graphql| graphql.plural = Some("corpora".to_owned()));

  assert_eq!(
    (list_field(&model), published(&model).0, published(&model).1),
    (
      "corpora".to_owned(),
      "CorporaConnection".to_owned(),
      "CorporaEdge".to_owned()
    ),
    "one declaration, one word, three names"
  );
}

/// **THE MIDDLE TIER IS CASE-BLIND**, because the two spellings are inverses of one act: a
/// declaration may write its plural as a word or as a type name and reaches the same three names.
#[test]
fn a_declared_plural_reaches_one_pair_of_names_however_it_was_cased() {
  let lower = record(|graphql| graphql.plural = Some("corpora".to_owned()));
  let upper = record(|graphql| graphql.plural = Some("Corpora".to_owned()));

  assert_eq!(published(&lower), published(&upper));
  assert_eq!(list_field(&lower), list_field(&upper));
}

/// **TIER 3 — A RENAME COVERS THE PLURAL, FOR THE ONE NAME IT WRITES.**
///
/// The declaration corrects English AND names its page: the page takes the written word outright, and
/// the two names the rename did not touch stay on the tier below it. That is *一层覆盖一层* — a
/// covering rather than a replacement, and the edge is what proves the covering is per name.
#[test]
fn a_rename_covers_the_plural_for_the_one_name_it_writes() {
  let model = record(|graphql| {
    graphql.plural = Some("corpora".to_owned());
    graphql.connection = Some("CorpusPage".to_owned());
  });

  assert_eq!(
    published(&model),
    ("CorpusPage".to_owned(), "CorporaEdge".to_owned()),
    "the page is the user's word; the edge is still the plural's"
  );
  assert_eq!(
    list_field(&model),
    "corpora",
    "and a page rename says nothing about the field"
  );
}

/// **THE EDGE RIDES THE SAME TOWER** — the user's *1 是*, asserted as its own three rows rather than
/// inferred from the page's.
#[test]
fn the_edge_rides_the_same_tower_the_page_does() {
  let base = record(|_| {});
  let plural = record(|graphql| graphql.plural = Some("corpora".to_owned()));
  let renamed = record(|graphql| {
    graphql.plural = Some("corpora".to_owned());
    graphql.edge = Some("CorpusItem".to_owned());
  });

  assert_eq!(published(&base).1, "VideoTracksEdge");
  assert_eq!(published(&plural).1, "CorporaEdge");
  assert_eq!(published(&renamed).1, "CorpusItem");
  assert_eq!(
    published(&renamed).0,
    "CorporaConnection",
    "and an edge rename leaves the page on the tier below it"
  );
}

/// **THE TOP TIER WINS OVER BOTH BELOW IT, ON BOTH NAMES** — the whole tower written at once, and the
/// two words below it visible nowhere.
#[test]
fn the_top_tier_wins_over_every_tier_below_it() {
  let model = record(|graphql| {
    graphql.plural = Some("corpora".to_owned());
    graphql.connection = Some("CorpusPage".to_owned());
    graphql.edge = Some("CorpusItem".to_owned());
  });

  assert_eq!(
    published(&model),
    ("CorpusPage".to_owned(), "CorpusItem".to_owned())
  );

  let graphql = model.graphql.as_ref().expect("the wire face");
  let tokens = model
    .page_names(graphql, true)
    .to_token_stream()
    .to_string();
  for covered in ["CorporaConnection", "CorporaEdge", "VideoTracksConnection"] {
    assert!(
      !tokens.contains(covered),
      "`{covered}` is a tier the declaration covered, and it survives nowhere — not even in the \
       prose:\n{tokens}"
    );
  }
}