ingraph-derive 0.1.0

The attribute and derive macros for ingraph: the words a record, node, key, filter and vocabulary declaration is written in.
Documentation
//! **THE PAGE WORDS ARE STRING-KIND** — what a `rename` is allowed to say depends on what it NAMES,
//! and this is the file that draws the line.
//!
//! The user's ruling of 2026-08-13: *graphql 和 db 那边 type 和其他的 rust 关键词都不是问题, 所以我们
//! 应该想办法支持*. `connection(rename = "…")` and `edge(rename = "…")` name types in GraphQL's own
//! flat namespace and nothing in Rust, so a Rust KEYWORD is an ordinary word to them and an ident
//! parse was refusing it for a reason no schema has.
//!
//! # The classification, which this round makes exception-free
//!
//! | what the word names | kind | the fence |
//! |---|---|---|
//! | an emitted RUST type — `output`, `key`, `filter`, `order_by`, `graphql(rename)` | ident | `syn::Ident`, because a Rust type name has to be one |
//! | a SCHEMA entity — `connection`, `edge`, `plural` | string | GraphQL's Name grammar, and nothing else |
//!
//! `#244` wrote that law for the plural and left the page words on the other side of it. They cross
//! here, and the two contrasting rows —
//! [`a_rust_keyword_is_an_ordinary_page_word`] beside
//! [`a_rust_types_rename_is_still_held_to_rusts_own_alphabet`] — are the whole statement: one word,
//! two blocks, two answers, each right for what its block names.
//!
//! # The alphabets are not one another's subsets, and both directions are real declarations
//!
//! Rust accepts `débit` where GraphQL does not; GraphQL accepts `type` where a Rust ident parse did
//! not. So the string kind is not the LOOSER fence — it is a DIFFERENT one, and
//! [`the_graphql_name_grammar_is_the_only_fence_and_it_still_bites`] is what says the crossing bought
//! no laxity.
//!
//! The executed half — that a schema with a type called `type` builds, exports readable SDL and
//! answers — is `ingraph/tests/wire_page_keyword.rs`. This file is about the grammar.

use ingraph_codegen::prelude::*;

use crate::host;

/// A record with a `graphql(…)` block spelled however a case wants it.
fn model(block: &str) -> Result<RecordModel, Vec<String>> {
  let input: syn::DeriveInput = syn::parse_str(&format!(
    "#[ingraph(sqlite, graphql({block}))]
     struct Reel {{
       #[ingraph(id)] id: i64,
       #[ingraph(string)] title: String,
     }}"
  ))
  .expect("a parseable declaration");
  let (host, options) = host::split(&input);
  crate::parse::parse(&host, &options, NodeKind::Record)
    .map_err(|e| e.into_iter().map(|e| e.to_string()).collect())
}

/// The two page words of a settled model.
fn words(block: &str) -> (Option<String>, Option<String>) {
  let model = model(block).expect("the declaration settles");
  let graphql = model.graphql.expect("the wire face");
  (graphql.connection, graphql.edge)
}

/// Every refusal a declaration earns, as one string to look inside.
fn refusal(block: &str) -> String {
  model(block)
    .expect_err("the declaration is refused")
    .join(" | ")
}

/// **A RUST KEYWORD IS AN ORDINARY PAGE WORD** — the ruling's own example, at both hooks.
///
/// `type` is the sharpest of them: it is a keyword in Rust AND the word GraphQL's own SDL uses to
/// introduce an object definition. It is still a legal `Name`, because GraphQL's keywords are
/// CONTEXTUAL — the specification's `Name` production excludes nothing at all.
#[test]
fn a_rust_keyword_is_an_ordinary_page_word() {
  assert_eq!(
    words(r#"async_graphql, connection(rename = "type"), edge(rename = "where")"#),
    (Some("type".to_owned()), Some("where".to_owned()))
  );
}

/// **EVERY SHAPE OF RUST KEYWORD PASSES**, and the list is chosen for the ways a parse could still
/// have refused one.
///
/// A strict keyword (`fn`), a keyword that is also a GraphQL SDL word (`type`, `enum`, `input`,
/// `union`), one that only a raw identifier can spell in Rust (`crate`, `self`, `Self`, `super`), a
/// reserved-for-the-future one (`become`, `typeof`), and the wildcard `_` — which is a legal GraphQL
/// `Name` by the grammar's own first alternative and is not an identifier in Rust at all.
#[test]
fn every_shape_of_rust_keyword_is_accepted() {
  for word in [
    "type", "where", "fn", "impl", "move", "enum", "input", "union", "crate", "self", "Self",
    "super", "become", "typeof", "async", "dyn", "_",
  ] {
    assert_eq!(
      words(&format!(r#"async_graphql, connection(rename = "{word}")"#)).0,
      Some(word.to_owned()),
      "`{word}` names a schema type and nothing in Rust"
    );
  }
}

/// **A RUST TYPE'S `rename` IS STILL HELD TO RUST'S OWN ALPHABET** — the contrast that makes the
/// classification a law rather than a loosening.
///
/// The same word, in a block that names an emitted RUST type, is still refused: `output(rename =
/// "type")` would have to become a `struct type`, which is not a thing that can exist. So the two
/// kinds disagree about one word, and each is right about the thing its block names.
#[test]
fn a_rust_types_rename_is_still_held_to_rusts_own_alphabet() {
  for block in ["output", "key", "filter", "order_by"] {
    let refused = refusal(&format!(r#"async_graphql, {block}(rename = "type")"#));
    assert!(
      refused.contains("must be a valid identifier"),
      "`{block}(rename = \"type\")` names a Rust type: {refused}"
    );
  }
  // And the record's own flat `rename`, which is the base the emitted Rust types suffix.
  let refused = refusal(r#"async_graphql, rename = "type""#);
  assert!(refused.contains("must be a valid identifier"), "{refused}");
}

/// **THE GraphQL NAME GRAMMAR IS THE ONLY FENCE, AND IT STILL BITES** — the crossing to string-kind
/// bought no laxity, only a different alphabet.
///
/// `débit` is the fixture the knob shipped with and is still refused, which is the direction of the
/// mismatch a Rust ident parse would have MISSED: Rust accepts a non-ASCII identifier and GraphQL
/// does not. The rest are the shapes no alphabet accepts.
#[test]
fn the_graphql_name_grammar_is_the_only_fence_and_it_still_bites() {
  for word in ["débit", "", "9lives", "bit-rate", "bit rate", "$where"] {
    let refused = refusal(&format!(r#"async_graphql, connection(rename = "{word}")"#));
    assert!(
      refused.contains("is not a GraphQL name"),
      "`{word}`: {refused}"
    );
  }
}

/// **THE EDGE IS FENCED SEPARATELY**, because the two hooks are independent all the way down and a
/// check wired to one of them would be invisible on the other.
#[test]
fn the_edge_word_is_fenced_by_the_same_grammar() {
  let refused = refusal(r#"async_graphql, edge(rename = "débit")"#);
  assert!(refused.contains("is not a GraphQL name"), "{refused}");
}

/// **THE VALUE IS STILL A STRING LITERAL** — the kind changed, the SHAPE did not, so a bare word is
/// refused as it always was.
///
/// The sentence is the string kind's own and deliberately does not say *a valid identifier*: a
/// reader told that would conclude a Rust keyword is illegal, which is the belief this round
/// corrected.
#[test]
fn a_bare_word_is_still_refused_and_the_sentence_does_not_say_identifier() {
  let refused = refusal("async_graphql, connection(rename = Page)");
  assert!(
    refused.contains("string literal"),
    "the shape is still a literal: {refused}"
  );
  assert!(
    !refused.contains("valid identifier"),
    "and the sentence does not teach the fence this round removed: {refused}"
  );
}