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