switchback_traits/
lib.rs

1#![forbid(unsafe_code)]
2#![warn(missing_docs)]
3#![allow(async_fn_in_trait)] // ADR 0002: native async fn in trait at the seam
4
5//! The seam of the switchback-rs toolchain.
6//!
7//! `switchback-traits` owns the trait spine and the in-memory model that every
8//! parser and every renderer depends on. See the workspace
9//! [Glossary](https://github.com/canardleteer/switchback-rs/blob/main/docs/GLOSSARY.md)
10//! for terminology.
11//!
12//! **Protocol vs contract family:** contract family describes spec grammar
13//! (OpenAPI, Protobuf, AsyncAPI); [protocol](https://github.com/canardleteer/switchback-rs/blob/main/docs/GLOSSARY.md#protocol)
14//! describes invocation and transport semantics (`http`, `grpc`, custom). Entity
15//! and contract nodes carry [`ProtocolAttachment`] lists populated by family
16//! parsers and decoded by [`switchback-protocols`](https://docs.rs/switchback-protocols).
17//! Structured HTTP method/path and gRPC streaming facts live in attachments, not
18//! in [`OperationBody::signature`] alone.
19//!
20//! # Traits
21//!
22//! - [`ContractFamily`] and [`Contract`] — parser-side identity and loaded views
23//! - [`ProtocolAttachment`] — transport envelope on contract and entity nodes
24//! - [`Renderer`] / [`SyncRenderer`] — target-format rendering (async primary)
25//! - [`SwitchbackCodec`] / [`SyncSwitchbackCodec`] — binary switchback I/O
26//! - [`LinkExtractor`] / [`AsyncLinkExtractor`] — intra-link extraction
27//! - [`LinkFormatter`] — resolved link string formatting
28//! - [`CompanionStrategy`] / [`AsyncCompanionStrategy`] — companion discovery
29//!
30//! I/O traits follow [ADR 0002](https://github.com/canardleteer/switchback-rs/blob/main/docs/adr/0002-async-first-traits-with-synchronous-secondary-apis-in-switchback-traits.md):
31//! async-primary with sync-secondary APIs for external compatibility. All seam
32//! types must traverse async task boundaries (`Send` / `Sync` as appropriate).
33//!
34//! Helper implementations (slug, link check, paths, companion discovery, prose
35//! escaping) are partially centralized; companion nav metadata and ancestor
36//! discovery live in [`companion`](crate::companion). Remaining helpers deferred.
37
38mod companion;
39mod error;
40mod ids;
41mod intra_links;
42mod layout_paths;
43mod link_context;
44mod model;
45mod options;
46mod paths;
47mod response_severity;
48mod traits;
49
50pub use companion::{
51    companion_output_name_from_path, companion_output_name_from_segments,
52    discover_ancestors_companions, module_path_from_output, normalize_rel_dir,
53    source_dir_from_output, source_dir_string, title_from_markdown,
54};
55pub use error::{Result, SwitchbackError};
56pub use ids::{EntityId, GroupId, ModuleId, SpecVersion};
57pub use intra_links::{anchor, apply_intra_links, links_for_field};
58pub use layout_paths::{
59    LayoutEntityKey, ProtobufEntityKind, decode_markdown_link_path, encode_markdown_link_path,
60    heading_slug, layout_entity_rel_path, package_index_rel, package_page_rel,
61    relative_path_from_dir, unique_heading_ids,
62};
63pub use link_context::LinkContext;
64pub use model::{
65    Anchor, ChannelBody, Companion, ContractRef, Document, EntityBody, EntityRef, ExtensionBody,
66    ExternalUrl, Group, GroupRef, IndexedEntity, IntraLink, LinkTarget, ManualContract, ManualRef,
67    ManualRefInner, MessageBody, Module, ModuleRef, OperationBody, OperationRequestBodyRef,
68    ParameterBody, ParameterRef, Property, ProtocolAttachment, RefKind, Reference, ReferenceManual,
69    RequestBodyBody, ResolvedManual, ResponseBody, ResponseRef, SchemaBody, SecuritySchemeBody,
70    ServiceBody, Source, SourceRef, Span, StoredEntity,
71};
72pub use options::{EscapeTags, Layout, OpenApiOperationSource, OpenApiSummaryLabel, Options};
73pub use paths::{entity_category_dir, entity_rel_path};
74pub use response_severity::ResponseSeverity;
75pub use traits::{
76    AsyncCompanionStrategy, AsyncContractLoader, AsyncLinkExtractor, CompanionDiscovery,
77    CompanionStrategy, Contract, ContractFamily, Entity, EntityCategory, GenericCategory,
78    LinkExtractor, LinkFormatter, OutputFile, RawDoc, Renderer, SupportedVersion, SwitchbackCodec,
79    SyncRenderer, SyncSwitchbackCodec, VersionStatus, companion_files_to_stored,
80};
81
82pub use model::CompanionFile;
83
84#[cfg(test)]
85mod tests;
switchback_traits/lib.rs

switchback_traits/
lib.rs
