switchback_traits/model/
manual.rs

1//! Provenance and source-layer types.
2
3use std::path::PathBuf;
4
5/// Byte span within a source document (1-based line/column coordinates).
6#[derive(Clone, Debug, Default, PartialEq, Eq)]
7pub struct Span {
8    /// Start line (1-based).
9    pub start_line: u32,
10    /// Start column (1-based).
11    pub start_col: u32,
12    /// End line (1-based).
13    pub end_line: u32,
14    /// End column (1-based).
15    pub end_col: u32,
16}
17
18/// Pointer into a [`Document`] by URI plus optional span.
19///
20/// Serialized on the wire on [`Group`](super::contract::Group) and
21/// [`StoredEntity`](super::entity::StoredEntity) provenance fields.
22#[derive(Clone, Debug, PartialEq, Eq)]
23pub struct Source {
24    /// URI of the source [`Document`] in the manual's source layer.
25    pub file: String,
26    /// Optional line/column span within the document.
27    pub span: Option<Span>,
28}
29
30/// Stable provenance for a raw input document.
31///
32/// Serialized on the wire as part of the switchback source layer.
33#[derive(Clone, Debug, PartialEq, Eq)]
34pub struct SourceRef {
35    /// Canonical URI for the input document.
36    pub uri: String,
37    /// Source control commit hash, when known.
38    pub commit: String,
39    /// Content hash for change detection.
40    pub content_hash: String,
41}
42
43/// A single input document carried verbatim in the switchback source layer.
44#[derive(Clone, Debug, PartialEq, Eq)]
45pub struct Document {
46    /// Stable provenance metadata for this document.
47    pub source_ref: SourceRef,
48    /// MIME type of the raw content (e.g. `"application/yaml"`).
49    pub media_type: String,
50    /// Raw input bytes as read from disk or fetched remotely.
51    pub content: Vec<u8>,
52}
53
54/// Top-level switchback artifact every parser emits and every renderer reads.
55#[derive(Clone, Debug, Default, PartialEq, Eq)]
56pub struct ReferenceManual {
57    /// Switchback container format version (distinct from contract spec versions).
58    pub switchback_version: String,
59    /// Human-readable title for the reference manual.
60    pub title: String,
61    /// Verbatim source documents preserved for provenance and re-parse.
62    pub sources: Vec<Document>,
63    /// Top-level documentation modules grouping contracts.
64    pub modules: Vec<Module>,
65}
66
67/// A cohesive documentation unit that may span contract families.
68#[derive(Clone, Debug, PartialEq, Eq)]
69pub struct Module {
70    /// Stable module identifier ([`ModuleId`](crate::ModuleId)).
71    pub id: crate::ids::ModuleId,
72    /// Human-readable module title.
73    pub title: String,
74    /// Overview prose for the module landing page.
75    pub overview: String,
76    /// Contracts belonging to this module.
77    pub contracts: Vec<super::contract::ManualContract>,
78}
79
80/// Parser-side companion file discovered beside contract inputs.
81///
82/// Used during parse and companion discovery; converted to wire [`Companion`](super::contract::Companion)
83/// via [`companion_files_to_stored`](crate::traits::companion_files_to_stored). The
84/// `source_path` field is parser-local and not serialized on the wire.
85#[derive(Clone, Debug, PartialEq, Eq)]
86pub struct CompanionFile {
87    /// Output filename for the companion in the rendered book.
88    pub output_name: String,
89    /// Raw companion file bytes.
90    pub bytes: Vec<u8>,
91    /// Filesystem path where the companion was discovered.
92    ///
93    /// Parser-local provenance only; not serialized on the wire.
94    pub source_path: PathBuf,
95    /// Human nav label (first markdown heading or humanized stem).
96    pub title: String,
97    /// Logical source directory relative to corpus root (slash-separated).
98    pub source_dir: String,
99    /// Source filename stem (e.g. `README`, `MOVING-TO-V2`).
100    pub stem: String,
101}
switchback_traits/model/manual.rs

switchback_traits/model/
manual.rs
