[allmonday]

Summary

Closes #316.

graphql/type_mapping.py had no Literal handling: every Literal annotation fell through map_scalar_type's lenient string-matching fallback and became String — int/bool literals got a wrong type in SDL/introspection, and Literal[..., None] was forced NON_NULL although the Python type allows null.

The compose path already validated Literals (_literal_info, backported in #313). This PR extracts those rules into graphql/type_mapping.py as the single source for both paths (compose_schema already imports from graphql.type_mapping; utils/ would have inverted the layering):

• Shared helpers: literal_info / literal_is_nullable / literal_allowed_values / describe_literal_values live in graphql/type_mapping.py; compose_schema's local copies removed (behavior unchanged — all 385 existing use_case/graphql tests green).
• One choke point: map_scalar_type itself now recognizes Literal and maps it to the scalar shared by its values, raising for mixed-type / enum-member / all-None Literals. This fixes the four direct map_scalar_type call sites in introspection_generator and the TypeMapper scalar branch with zero changes there.
• Nullability: map_python_to_graphql and TypeMapper.map_to_sdl treat a None member (Literal['open', None]) like Optional for the ! suffix; input-side fields render nullable, matching the Optional[T] treatment.
• Allowed values: ... now surfaces on the entity-first path: introspection entity fields, input fields, and method args carry it in their descriptions; SDL emits docstring blocks on Literal fields. Only Literal fields are affected — schemas without Literals are byte-identical.

Before / after

map_python_to_graphql(Literal[1, 2])          # String! → Int!
map_python_to_graphql(Literal[True, False])   # String! → Boolean!
map_python_to_graphql(Literal['open', None])  # String! → String

Entity SDL gains the constraint docs:

type TaskLiteEntity {
  """Allowed values: 1, 2, 3"""
  priority: Int!
  """Allowed values: open, closed"""
  status: String!
}

Tests

25 new tests in tests/graphql/test_literal_type_mapping.py (scalar mapping, nullability, wrappers, validation rejections, SDL, introspection via GraphQLHandler). Full suite: 988 passed, 1 skipped.

Note: the same shared-rules extraction is a backport candidate for KLR-Pattern/nexusx#153.

🤖 Generated with Claude Code