Crate switchback_traits

Expand description

The seam of the switchback-rs toolchain.

switchback-traits owns the trait spine and the in-memory model that every parser and every renderer depends on. See the workspace Glossary for terminology.

Protocol vs contract family: contract family describes spec grammar (OpenAPI, Protobuf, AsyncAPI); protocol describes invocation and transport semantics (http, grpc, custom). Entity and contract nodes carry ProtocolAttachment lists populated by family parsers and decoded by switchback-protocols. Structured HTTP method/path and gRPC streaming facts live in attachments, not in OperationBody::signature alone.

§Traits

ContractFamily and Contract — parser-side identity and loaded views
ProtocolAttachment — transport envelope on contract and entity nodes
Renderer / SyncRenderer — target-format rendering (async primary)
SwitchbackCodec / SyncSwitchbackCodec — binary switchback I/O
LinkExtractor / AsyncLinkExtractor — intra-link extraction
LinkFormatter — resolved link string formatting
CompanionStrategy / AsyncCompanionStrategy — companion discovery

I/O traits follow ADR 0002: async-primary with sync-secondary APIs for external compatibility. All seam types must traverse async task boundaries (Send / Sync as appropriate).

Helper implementations (slug, link check, paths, companion discovery, prose escaping) are partially centralized; companion nav metadata and ancestor discovery live in companion. Remaining helpers deferred.

Structs§

Anchor: Byte span within a prose field (doc, fence_body, etc.).
ChannelBody: Channel entity body (async messaging endpoint).
Companion: Companion document embedded in the switchback.
CompanionFile: Parser-side companion file discovered beside contract inputs.
ContractRef: Address of a contract within a manual.
Document: A single input document carried verbatim in the switchback source layer.
Entity: Parser-side entity with a family-typed category.
EntityId: Entity address within a manual: group + category + name.
EntityRef: Address of an entity within a manual.
ExtensionBody: Opaque family-specific extension entity body.
ExternalUrl: External URL link target (not resolved to an in-manual entity).
Group: Intra-contract grouping unit (package, tag group, application, etc.).
GroupId: Intra-contract grouping identifier (protobuf package, OpenAPI tag, etc.).
GroupRef: Address of a group within a manual.
IndexedEntity: Flat index entry for one entity in a resolved manual.
IntraLink: Prose-level link with anchor, resolved target, and raw author text.
LayoutEntityKey: Layout entity key for path indexing (protobuf package + kind + name).
LinkContext: Entity output path index used by LinkFormatter.
ManualContract: Serialized contract within a ReferenceManual.
ManualRef: Cross-manual reference by URI with optional inner target.
MessageBody: Message entity body (payload type excerpt).
Module: A cohesive documentation unit that may span contract families.
ModuleId: Top-level module identifier within a reference manual.
ModuleRef: Address of a module within a manual.
OperationBody: Operation entity body (RPC signature, parameters, responses).
OperationRequestBodyRef: Request body attachment on an OperationBody.
Options: Spine options shared across renderers (subset ported from protobuf-mdbook).
OutputFile: One rendered output file (path relative to book root unless absolute).
ParameterBody: Parameter entity body (location, requirement, schema excerpt).
ParameterRef: Parameter attachment on an OperationBody, referencing a schema entity.
Property: One property on a schema-like entity, pointing at another entity via Reference.
ProtocolAttachment: Opaque protocol binding stored on contract and entity IR nodes.
RawDoc: Raw document bytes before full parse, used for version detection.
Reference: Structural cross-reference in an entity body (schema $ref, protobuf FQN, etc.).
ReferenceManual: Top-level switchback artifact every parser emits and every renderer reads.
RequestBodyBody: Request body entity (requirement flag and schema excerpt).
ResolvedManual: Whole-manual address space used by LinkExtractor.
ResponseBody: Response entity body (status, media type, schema excerpt).
ResponseRef: Response attachment on an OperationBody, referencing a schema entity.
SchemaBody: Schema entity body (type definition with optional properties).
SecuritySchemeBody: Security scheme entity body.
ServiceBody: Service definition entity body.
Source: Pointer into a Document by URI plus optional span.
SourceRef: Stable provenance for a raw input document.
Span: Byte span within a source document (1-based line/column coordinates).
SpecVersion: Contract-family spec version string (e.g. "3.1.1", "2.6.0").
StoredEntity: One entity as stored in a serialized switchback Group.
SupportedVersion: One supported spec version entry in a family’s version matrix.

Enums§

CompanionDiscovery: Where a family searches for companion documents relative to contract inputs.
EntityBody: Discriminated entity payload mirroring the proto oneof body.
EscapeTags: How to rewrite HTML-like tags in leading-comment prose.
GenericCategory: Categories renderers know how to format specially.
Layout: Page layout for generated markdown.
LinkTarget: Resolved intra-link destination.
ManualRefInner: Inner target of a ManualRef cross-manual link.
OpenApiOperationSource: How to render the raw OpenAPI operation YAML/JSON on operation pages.
OpenApiSummaryLabel: How to label OpenAPI operations in SUMMARY and package index links.
ProtobufEntityKind: Protobuf entity kind for layout path indexing.
RefKind: Classification of a structural reference in source.
ResponseSeverity: Cross-family outcome severity for a response or RPC result.
SwitchbackError: Error type for seam operations (codec, render, load, link extraction).
VersionStatus: Lifecycle status of a supported contract spec version.

Traits§

AsyncCompanionStrategy: Async companion fetch (remote registries, URL-backed docs).
AsyncContractLoader: Async loading of remote or multi-document contracts (I/O primary API).
AsyncLinkExtractor: Extract intra-links with async cross-manual or remote resolution.
CompanionStrategy: How a family discovers, names, and places companion docs (sync, local).
Contract: A loaded, resolved contract ready to render or serialize.
ContractFamily: Identity and capability metadata for one contract family.
EntityCategory: Typed entity category owned by each contract family.
LinkExtractor: Extract intra-links from entity prose (sync, in-memory resolution).
LinkFormatter: Format a resolved link target for one output format (sync, no I/O).
Renderer: Async renderer for service-side and streaming pipelines.
SwitchbackCodec: Async codec for I/O-backed serialize/deserialize of ReferenceManual artifacts.
SyncRenderer: Synchronous compatibility API for callers that cannot wrap Renderer.
SyncSwitchbackCodec: Synchronous compatibility API for callers that cannot wrap SwitchbackCodec.

Functions§

anchor: Builds an anchor for a byte span within a named field.
apply_intra_links: Applies resolved intra-links to a prose field, replacing anchored spans with formatted link strings.
companion_files_to_stored: Convert parser-side companions into stored switchback companions.
companion_output_name_from_path: Dot-separated output filename from a relative directory path and stem.
companion_output_name_from_segments: Dot-separated output filename for a companion under source_dir segments.
decode_markdown_link_path: Decode a percent-encoded Markdown link path back to a filesystem path.
discover_ancestors_companions: Discover companion markdown by walking ancestor directories from each anchor.
encode_markdown_link_path: Percent-encode a relative path for use inside Markdown ](...) link targets.
entity_category_dir: Relative output directory segment for a stored entity category slug.
entity_rel_path: Relative output path for an entity page under a group’s markdown tree.
heading_slug: Heading anchor id compatible with mdBook HTML output.
layout_entity_rel_path: Relative entity page path for entity/split layouts.
links_for_field: Returns intra-links whose anchor targets field.
module_path_from_output: Dot-separated module path implied by a companion output filename.
normalize_rel_dir: Normalize a relative directory path to normal components only.
package_index_rel: Relative path to a package index page (entity/split layouts).
package_page_rel: Relative path to a package rollup page under markdown_root.
relative_path_from_dir: Relative POSIX path from from_dir to target (mdBook link form).
source_dir_from_output: Inverse of dot-encoded output name for legacy artifacts missing source_dir.
source_dir_string: Slash-separated source directory string for wire nav metadata.
title_from_markdown: Title from the first # heading in markdown, else humanized stem.
unique_heading_ids: Assigns mdBook-style unique heading ids in document order (appends -1, -2, … on collision).

Type Aliases§

Result: Result alias for seam operations that surface SwitchbackError.