olai_codegen/parsing/
mod.rs

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

olai_codegen/parsing/
mod.rs
