ingraph-codegen 0.1.0

The emission engine behind ingraph-derive: a plain declaration model in, the ingraph framework faces out.
Documentation
//! The two naming acts, measured as pure functions — a field's, and a type's.

use proc_macro2::Span;
use quote::format_ident;

use super::{lower_camel, wire_field, wire_type};
use crate::{
  model::{default_key_output_name, default_order_by_name, default_output_name},
  name::RustSafeName,
};

/// A record ident, at the one width these rows need.
fn record(name: &str) -> syn::Ident {
  format_ident!("{name}")
}

/// The name a declaration wrote — or the framework's fallback, which [`RustSafeName`] stores as the
/// name itself, which is what makes the comparison in `wire_type` exact.
fn declared(name: &syn::Ident) -> RustSafeName {
  RustSafeName::new(name.to_string(), Span::call_site())
}

/// **THE RULED RULE, read at the OUTPUT carriers.** `GraphqlOutput` is a Rust carrier's convention
/// and a client has no business reading it, so a type still carrying the framework's default is
/// published under the record's own name.
#[test]
fn an_output_carrier_publishes_the_records_type_name() {
  let track = record("VideoTrack");

  assert_eq!(
    wire_type(
      &declared(&default_output_name(&track)),
      &default_output_name(&track),
      &track,
    ),
    "VideoTrack",
    "`VideoTrackGraphqlOutput` is the carrier's name and `VideoTrack` is the record's"
  );

  // The ADDRESS object keeps its own word, because `Key` is part of what the type IS and only
  // `Output` is the carrier's convention. What is published is the name the framework picked for the
  // schema, whatever the Rust carrier is called.
  assert_eq!(
    wire_type(
      &declared(&default_key_output_name(&track)),
      &default_key_output_name(&track),
      &format_ident!("VideoTrackKey"),
    ),
    "VideoTrackKey"
  );
}

/// **A DECLARED RENAME IS PUBLISHED VERBATIM**, which is the half of the rule that is one sentence
/// over both readings: a name a declaration chose is a name it chose, and no convention of this
/// emitter may move it.
#[test]
fn a_declared_rename_reaches_the_schema_exactly_as_written() {
  let track = record("VideoTrack");

  assert_eq!(
    wire_type(
      &RustSafeName::new("Track", Span::call_site()),
      &default_output_name(&track),
      &track,
    ),
    "Track",
    "the rename wins over both the carrier's name and the record's"
  );

  // …including a rename whose spelling is not a Rust identifier: the SDL name is the external face,
  // which `RustSafeName` keeps verbatim however it had to mangle the Rust one.
  let awkward = RustSafeName::new("Video_Track", Span::call_site());
  assert_eq!(
    wire_type(&awkward, &default_output_name(&track), &track),
    "Video_Track"
  );
}

/// **THE INPUT TYPES ARE THE IDENTITY READING**, and the order-by is the one this build emits.
/// `<T>OrderBy` and `<T>Filter` are the names the design's own SDL is written in — there is nothing
/// on them a schema does not read — so the published form IS the framework's default.
#[test]
fn an_input_type_publishes_the_name_the_framework_gave_it() {
  let track = record("VideoTrack");
  let default = default_order_by_name(&track);

  assert_eq!(
    wire_type(&declared(&default), &default, &default),
    "VideoTrackOrderBy"
  );

  // A rename still wins, which is why the order door routes through this function rather than
  // reading the external name directly: `graphql(order_by(rename = "…"))` is a schema commitment.
  assert_eq!(
    wire_type(
      &RustSafeName::new("TrackOrder", Span::call_site()),
      &default,
      &default,
    ),
    "TrackOrder"
  );
}

/// A declaration that renames a type to the string the framework would have picked lands in the
/// DEFAULT arm — and the answer is the same either way, which is what makes the comparison an
/// implementation detail rather than a behaviour.
#[test]
fn a_rename_to_the_default_is_the_default() {
  let track = record("VideoTrack");
  let default = default_output_name(&track);

  assert_eq!(
    wire_type(
      &RustSafeName::new("VideoTrackGraphqlOutput", Span::call_site()),
      &default,
      &track,
    ),
    "VideoTrack",
    "indistinguishable from writing nothing, and it publishes the same name"
  );
}

/// The FIELD rule, beside the type one: camelCase where the framework fell back on the Rust field's
/// own name, and verbatim where a declaration wrote one.
#[test]
fn a_field_takes_camel_case_only_where_nothing_was_declared() {
  let member = format_ident!("media_id");
  assert_eq!(wire_field("media_id", &member), "mediaId");
  assert_eq!(wire_field("mediaIdentifier", &member), "mediaIdentifier");
  assert_eq!(lower_camel("begins_at"), "beginsAt");
}

/// **A LEADING UNDERSCORE IS EATEN, and it has to be** — this function's own note claimed the
/// opposite and the code always did this, which is the divergence these rows exist to pin.
///
/// The answer is async-graphql's: it renames a field through `Inflector::to_camel_case`, whose loop
/// skips every non-alphanumeric character before the first real one, so an `#[Object]` method named
/// `_id` publishes `id` as well. Keeping the underscore would spell ONE column two ways — `_id` on
/// this hand-written face and `id` on a derived one — which is the collision the old note feared,
/// arrived at from the other direction.
#[test]
fn a_leading_underscore_is_eaten_exactly_as_the_library_eats_it() {
  assert_eq!(lower_camel("_id"), "id");
  assert_eq!(lower_camel("__at"), "at");
  assert_eq!(lower_camel("_begins_at"), "beginsAt");

  // The one DELIBERATE difference, at the degenerate input: a name that is all separator leaves
  // nothing to render, and this answers with the name itself where `to_camel_case` answers with the
  // empty string. An empty GraphQL field name is invalid SDL, so the fallback is the safer answer.
  assert_eq!(lower_camel("_"), "_");
  assert_eq!(lower_camel("__"), "__");
}