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.collapse_trivial_inlines();
26//! raw.inline_tagged_variants();
27//! raw.inline_untagged_variants();
28//! let graph = raw.cook();
29//!
30//! for view in graph.schemas() { /* ... */ }
31//! for view in graph.operations() { /* ... */ }
32//! # Ok(())
33//! # }
34//! ```
35//!
36//! # Arena
37//!
38//! An [`Arena`] is a bump allocator that owns all long-lived data.
39//! Types throughout the pipeline hold borrowed references to other
40//! arena-allocated types, making them cheaply copyable. Callers
41//! create an arena at the start, and pass it to each constructor.
42//!
43//! # Named vs. inline types
44//!
45//! The IR distinguishes two kinds of types:
46//!
47//! - **Named schema types** originate from `components/schemas`
48//! in the OpenAPI document. Each carries a [`SchemaTypeInfo`] with
49//! the schema name and additional metadata.
50//! - **Inline types** are anonymous schemas nested inside other types.
51//! Each carries an [`InlineTypeId`](ir::InlineTypeId) for identity,
52//! and a [canonical path](ir::InlineTypePathView).
53//!
54//! The two kinds carry different metadata, but share the same structural
55//! shapes: [any], [containers], [enums], [primitives], [structs],
56//! [tagged unions], and [untagged unions].
57//!
58//! # Using the graph
59//!
60//! A [`RawGraph`] represents types and references as they exist in the
61//! OpenAPI document. Transformations on this graph rewrite it in-place.
62//! The transformed graph is then "cooked" into a [`CookedGraph`] that's
63//! ready for codegen.
64//!
65//! [`CookedGraph::schemas()`] yields [`SchemaTypeView`]s. Match on the variant
66//! to get the specific shape (e.g., `SchemaTypeView::Struct`) for generating
67//! type models.
68//!
69//! [`CookedGraph::operations()`] yields [`OperationView`]s. Use these to
70//! access paths, methods, query parameters, and request and response types
71//! for generating client endpoints.
72//!
73//! See the [`ir::views`] module for all view types and traversal methods.
74//!
75//! [`Arena`]: arena::Arena
76//! [`SchemaTypeInfo`]: ir::SchemaTypeInfo
77//! [any]: ir::views::any
78//! [containers]: ir::views::container
79//! [enums]: ir::views::enum_
80//! [primitives]: ir::views::primitive
81//! [structs]: ir::views::struct_
82//! [tagged unions]: ir::views::tagged
83//! [untagged unions]: ir::views::untagged
84//! [`RawGraph`]: ir::RawGraph
85//! [`CookedGraph`]: ir::CookedGraph
86//! [`CookedGraph::schemas()`]: ir::CookedGraph::schemas
87//! [`SchemaTypeView`]: ir::SchemaTypeView
88//! [`CookedGraph::operations()`]: ir::CookedGraph::operations
89//! [`OperationView`]: ir::OperationView
90
91#[macro_use]
92mod macros;
93
94pub mod arena;
95pub mod codegen;
96pub mod error;
97pub mod ir;
98pub mod parse;
99
100#[cfg(test)]
101mod tests;