1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
//! Language-agnostic intermediate representation and type graph
//! for OpenAPI code generation.
//!
//! **ploidy-core** transforms a parsed OpenAPI document into a
//! typed dependency graph that **ploidy-codegen-\*** backends
//! traverse to emit code.
//!
//! # Pipeline
//!
//! ```rust
//! # fn main() -> Result<(), Box<dyn std::error::Error>> {
//! # let source = indoc::indoc! {"
//! # openapi: 3.0.0
//! # info:
//! # title: Test API
//! # version: 1.0
//! # "};
//! use ploidy_core::{arena::Arena, ir::{RawGraph, Spec}, parse::Document};
//!
//! let doc = Document::from_yaml(&source)?;
//!
//! let arena = Arena::new();
//! let spec = Spec::from_doc(&arena, &doc)?;
//! let mut raw = RawGraph::new(&arena, &spec);
//! raw.inline_tagged_variants();
//! let graph = raw.cook();
//!
//! for view in graph.schemas() { /* ... */ }
//! for view in graph.operations() { /* ... */ }
//! # Ok(())
//! # }
//! ```
//!
//! # Arena
//!
//! An [`Arena`] is a bump allocator that owns all long-lived data.
//! Types throughout the pipeline hold borrowed references to other
//! arena-allocated types, making them cheaply copyable. Callers
//! create an arena at the start, and pass it to each constructor.
//!
//! # Named vs. inline types
//!
//! The IR distinguishes two kinds of types:
//!
//! - **Named schema types** originate from `components/schemas`
//! in the OpenAPI document. Each carries a [`SchemaTypeInfo`] with
//! the schema name and additional metadata.
//! - **Inline types** are anonymous schemas nested inside other types.
//! Each carries an [`InlineTypePath`](ir::InlineTypePath) that
//! encodes the type's position in the document.
//!
//! The two kinds carry different metadata, but share the same structural
//! shapes: [any], [containers], [enums], [primitives], [structs],
//! [tagged unions], and [untagged unions].
//!
//! # Using the graph
//!
//! A [`RawGraph`] represents types and references as they exist in the
//! OpenAPI document. Transformations on this graph rewrite it in-place.
//! The transformed graph is then "cooked" into a [`CookedGraph`] that's
//! ready for codegen.
//!
//! [`CookedGraph::schemas()`] yields [`SchemaTypeView`]s. Match on the variant
//! to get the specific shape (e.g., `SchemaTypeView::Struct`) for generating
//! type models.
//!
//! [`CookedGraph::operations()`] yields [`OperationView`]s. Use these to
//! access paths, methods, query parameters, and request and response types
//! for generating client endpoints.
//!
//! See the [`ir::views`] module for all view types and traversal methods.
//!
//! [`Arena`]: arena::Arena
//! [`SchemaTypeInfo`]: ir::SchemaTypeInfo
//! [any]: ir::views::any
//! [containers]: ir::views::container
//! [enums]: ir::views::enum_
//! [primitives]: ir::views::primitive
//! [structs]: ir::views::struct_
//! [tagged unions]: ir::views::tagged
//! [untagged unions]: ir::views::untagged
//! [`RawGraph`]: ir::RawGraph
//! [`CookedGraph`]: ir::CookedGraph
//! [`CookedGraph::schemas()`]: ir::CookedGraph::schemas
//! [`SchemaTypeView`]: ir::SchemaTypeView
//! [`CookedGraph::operations()`]: ir::CookedGraph::operations
//! [`OperationView`]: ir::OperationView