Struct TypeRef 

pub struct TypeRef {
    pub name: String,
    pub inner: Option<Box<TypeRef>>,
    pub choices: Option<Vec<String>>,
    pub variants: Option<Vec<TypeRef>>,
    pub span: Span,
}

Fields

name: String

inner: Option<Box<TypeRef>>

choices: Option<Vec<String>>

Populated only for string-literal union types; in that case name is the sentinel "choice" and choices holds the variant strings in declaration order. None for every other type. Variant validation (non-empty, unique, ≥2) is the analyzer’s job, not the parser’s.

variants: Option<Vec<TypeRef>>

Populated only for discriminated-union types (general A | B | ... including the binary T | Unable special case). When Some, name is the sentinel "variant_union" (mirroring "choice"), both inner and choices are None, and variants holds every arm in source order with length in [2, MAX_UNION_ARMS]. The analyzer enforces arm-record-only, ≤8, no duplicates, and return-position-only usage in v1.

span: Span

Source span covering the type reference’s surface text. Populated by the parser for every TypeRef it constructs; synthesized refs (stdlib signatures, analyzer alias substitutions, test fixtures, …) default to Span::default().

For composite types (list[T]), the OUTER TypeRef’s span covers the whole list[T] text and the INNER T’s span covers just the inner identifier. For optional sentinels (T?), the inner T’s span is the pre-? text and the outer sentinel’s span includes the ?. For variant unions (A | B | ...) and choice strings ("a" | "b"), each arm carries its own span and the outer sentinel spans the whole union text.

#[serde(default)] so AST payloads serialized before this field existed (older SDK clients, durable execution caches) keep deserializing cleanly.

Implementations

impl TypeRef

pub fn primitive(name: impl Into<String>) -> TypeRef

Build a primitive or named type reference (no generic inner, no choice variants). Use this in preference to a struct literal so the choices field stays consistently None at non-choice sites.

The resulting span is Span::default() — appropriate for synthesized refs (stdlib signatures, analyzer substitutions, test fixtures). Parser sites that have a concrete source span should use TypeRef::primitive_with_span instead so hover / goto-definition land on the right text range.

pub fn primitive_with_span(name: impl Into<String>, span: Span) -> TypeRef

Build a primitive or named type reference with an explicit source span. Parser-facing companion to TypeRef::primitive.

pub fn optional(inner: TypeRef) -> TypeRef

Build an optional type T? wrapping inner (D2). Idempotent: applying this to a type that is already optional returns the same shape (no double-wrap), matching most languages’ T?? collapse.

The outer sentinel’s span is Span::default() — parser sites that have the postfix ? location should use TypeRef::optional_with_span so the outer sentinel covers the whole T? text (the inner T’s span stays at its own range).

pub fn optional_with_span(inner: TypeRef, span: Span) -> TypeRef

Build an optional type T? with an explicit source span covering the whole T? text (inner T’s span is preserved). Parser-facing companion to TypeRef::optional.

pub fn is_optional(&self) -> bool

true iff this TypeRef is an Optional[T] sentinel.

pub fn optional_inner(&self) -> Option<&TypeRef>

Borrow the wrapped T from an Optional[T]; None for non-optional.

pub fn variant_union(arms: Vec<TypeRef>) -> TypeRef

Build a discriminated union from an ordered arm list. Grammar guarantees arms.len() >= 2; arm-count caps are analyzer-enforced (AKRIBES-E-UNION-009) so oversized unions reach the analyzer as parsed ASTs instead of panicking in the parser. The binary T | Unable case is just variant_union(vec![T, Unable]).

pub fn variant_union_with_span(arms: Vec<TypeRef>, span: Span) -> TypeRef

Build a discriminated union with an explicit outer span covering the whole A | B | ... text. Each arm’s TypeRef keeps its own span (arms come from the parser already populated). Parser-facing companion to TypeRef::variant_union.

pub fn union_with_unable(success: TypeRef) -> TypeRef

Build a binary union success | Unable. Kept as a named constructor because every #157 call site uses it; internally delegates to [variant_union] with [success, Unable] in canonical source order.

pub fn is_variant_union(&self) -> bool

Return true iff this TypeRef is a discriminated-union sentinel (any arm count).

pub fn union_arms(&self) -> Option<&[TypeRef]>

Slice over the declared arms in source order (or None for non-union types).

pub fn is_union_with_unable(&self) -> bool

Return true iff this TypeRef is a binary union whose two arms are exactly one non-Unable record and one Unable. Used by every #157 call site that gates on “this is a T | Unable return type” — kept for backwards compatibility and cheap pattern-matching.

pub fn unwrap_union_success(&self) -> Option<&TypeRef>

Return the non-Unable branch of a binary T | Unable, or None if this is not exactly such a union. N-ary unions and unions without an Unable arm return None — callers that need the general arm list should use [union_arms].

pub fn union_success_arm(&self) -> Option<&TypeRef>

Return the declared success arm of any discriminated union — the first arm in source order. Used for retry gating and on <variant> default type-checking. Returns None for non-union types.

pub fn display(&self) -> String

Render a TypeRef as a source-level fragment for error messages, LSP labels, and user-facing diagnostics. Union types render as A | B | ...; choice types render as "a" | "b" | ...; generics render as list[str]; primitives render as their name.

Trait Implementations

impl Clone for TypeRef

fn clone(&self) -> TypeRef

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for TypeRef

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl Default for TypeRef

fn default() -> TypeRef

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for TypeRef

fn deserialize<__D>( __deserializer: __D, ) -> Result<TypeRef, <__D as Deserializer<'de>>::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Display for TypeRef

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl Serialize for TypeRef

fn serialize<__S>( &self, __serializer: __S, ) -> Result<<__S as Serializer>::Ok, <__S as Serializer>::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.