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