olai_codegen/parsing/
mod.rs

1//! Parsing stage: compiled descriptor → [`CodeGenMetadata`].
2//!
3//! This is the first stage of the code-generation pipeline. It walks every
4//! message, enum, and service in a [`FileDescriptorSet`] and extracts the
5//! annotations that drive generation into a structured, runtime-friendly form.
6//!
7//! The generator reads **standard Google API extensions only** — there are no
8//! custom Trestle proto extensions. The recognized extensions and their field
9//! numbers are the `*_EXTENSION` module constants below (`google.api.http`,
10//! `google.api.resource`, `google.api.field_behavior`,
11//! `google.api.resource_reference`, and `gnostic.openapi.v3.operation`), plus the
12//! core `debug_redact` option (`google.protobuf.FieldOptions` field 16, handled
13//! in the `message` submodule). [`parse_file_descriptor_set`] is the entry point.
14
15use std::collections::HashMap;
16
17pub use self::http::{HttpPattern, UrlSegment, extract_http_rule_pattern, extract_path_parameters};
18pub use self::models::*;
19use protobuf::descriptor::{FileDescriptorProto, FileDescriptorSet, SourceCodeInfo};
20pub mod types;
21use crate::Result;
22
23mod enum_parser;
24pub mod http;
25mod message;
26mod models;
27mod service;
28
29/// Extract documentation text for a protobuf element at the given source path.
30///
31/// Scans `SourceCodeInfo.location` for an entry whose path matches `path`,
32/// prefers leading comments over trailing comments, and returns the trimmed text.
33pub(super) fn extract_documentation(sci: Option<&SourceCodeInfo>, path: &[i32]) -> Option<String> {
34    let sci = sci?;
35    for location in &sci.location {
36        if location.path.as_slice() == path {
37            let text = if location.has_leading_comments() {
38                location.leading_comments().trim().to_string()
39            } else if location.has_trailing_comments() {
40                location.trailing_comments().trim().to_string()
41            } else {
42                String::new()
43            };
44            if !text.is_empty() {
45                return Some(text);
46            }
47        }
48    }
49    None
50}
51
52// Known extension field numbers
53const GOOGLE_API_HTTP_EXTENSION: u32 = 72295728; // google.api.http
54const GNOSTIC_OPERATION_EXTENSION: u32 = 1143; // gnostic.openapi.v3.operation
55const GOOGLE_API_RESOURCE_EXTENSION: u32 = 1053; // google.api.resource
56const GOOGLE_API_FIELD_BEHAVIOR_EXTENSION: u32 = 1052; // google.api.field_behavior
57const GOOGLE_API_RESOURCE_REFERENCE_EXTENSION: u32 = 1055; // google.api.resource_reference
58
59/// Parse a compiled protobuf [`FileDescriptorSet`] into [`CodeGenMetadata`].
60///
61/// This is the first stage of the code-generation pipeline. It walks every
62/// message, enum, and service in the descriptor set and extracts the annotations
63/// that drive generation (`google.api.http`, `google.api.resource`,
64/// `field_behavior`, `debug_redact`, …) into a structured form.
65///
66/// The full pipeline is three stages:
67///
68/// ```text
69/// FileDescriptorSet
70///   │  parse_file_descriptor_set
71///   ▼
72/// CodeGenMetadata
73///   │  analyze_metadata          (analysis/mod.rs)
74///   ▼
75/// GenerationPlan
76///   │  generate_code             (codegen/mod.rs)
77///   ▼
78/// Rust / Python / TypeScript source written to disk
79/// ```
80///
81/// Typical usage from a build script:
82///
83/// ```ignore
84/// let fds = prost_types::FileDescriptorSet::decode(&bytes[..])?;
85/// let metadata = parse_file_descriptor_set(&fds)?;
86/// let config = CodeGenConfig::new(/* … */);
87/// generate_code(&metadata, &config)?;
88/// ```
89///
90/// Methods without HTTP annotations are not an error here; they are recorded later,
91/// during [`analyze_metadata`](crate::analyze_metadata).
92///
93/// # Errors
94///
95/// Returns:
96///
97/// - [`Error::InvalidAnnotation`](crate::Error::InvalidAnnotation) if a `google.api.http`,
98///   `google.api.resource`, or `field_behavior` annotation is present but malformed (e.g. a
99///   resource pattern or HTTP rule that cannot be interpreted).
100/// - [`Error::Build`](crate::Error::Build) if an annotation extension cannot be decoded from its
101///   raw descriptor bytes.
102pub fn parse_file_descriptor_set(
103    file_descriptor_set: &FileDescriptorSet,
104) -> Result<CodeGenMetadata> {
105    let mut codegen_metadata = CodeGenMetadata {
106        messages: HashMap::new(),
107        enums: HashMap::new(),
108        services: HashMap::new(),
109    };
110
111    // Process each file descriptor
112    for file_descriptor in &file_descriptor_set.file {
113        process_file_descriptor(file_descriptor, &mut codegen_metadata)?;
114    }
115
116    Ok(codegen_metadata)
117}
118
119/// Process a single protobuf file descriptor
120///
121/// Extracts all messages, services, and annotations from the file.
122/// Collects metadata for code generation.
123pub fn process_file_descriptor(
124    file_desc: &FileDescriptorProto,
125    codegen_metadata: &mut CodeGenMetadata,
126) -> Result<()> {
127    // Extract source code info for documentation
128    let source_code_info = file_desc.source_code_info.as_ref();
129
130    let package_name = file_desc.package();
131    let type_prefix = if package_name.is_empty() {
132        String::new()
133    } else {
134        format!(".{package_name}")
135    };
136
137    // Process enums in the file
138    for (enum_index, enum_desc) in file_desc.enum_type.iter().enumerate() {
139        enum_parser::process_enum(
140            enum_desc,
141            codegen_metadata,
142            &type_prefix,
143            source_code_info,
144            &[5, enum_index as i32], // enum_type is field 5 in FileDescriptorProto
145        )?;
146    }
147
148    // Process messages in the file
149    for (message_index, message) in file_desc.message_type.iter().enumerate() {
150        message::process_message(
151            message,
152            codegen_metadata,
153            &type_prefix,
154            source_code_info,
155            &[4, message_index as i32], // message_type is field 4 in FileDescriptorProto
156        )?;
157    }
158
159    // Process services in the file
160    for (service_index, service) in file_desc.service.iter().enumerate() {
161        service::process_service(
162            service,
163            package_name,
164            codegen_metadata,
165            source_code_info,
166            service_index,
167        )?;
168    }
169
170    Ok(())
171}
olai_codegen/parsing/mod.rs

olai_codegen/parsing/
mod.rs
