scythe_core/parser/
mod.rs

1use sqlparser::parser::Parser;
2
3use crate::dialect::SqlDialect;
4use crate::errors::ScytheError;
5
6#[derive(Debug, Clone, PartialEq, Eq)]
7pub enum QueryCommand {
8    One,
9    Opt,
10    Many,
11    Exec,
12    ExecResult,
13    ExecRows,
14    Batch,
15    Grouped,
16}
17
18impl std::fmt::Display for QueryCommand {
19    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
20        match self {
21            QueryCommand::One => write!(f, "one"),
22            QueryCommand::Opt => write!(f, "opt"),
23            QueryCommand::Many => write!(f, "many"),
24            QueryCommand::Exec => write!(f, "exec"),
25            QueryCommand::ExecResult => write!(f, "exec_result"),
26            QueryCommand::ExecRows => write!(f, "exec_rows"),
27            QueryCommand::Batch => write!(f, "batch"),
28            QueryCommand::Grouped => write!(f, "grouped"),
29        }
30    }
31}
32
33impl QueryCommand {
34    fn from_str(s: &str) -> Result<Self, ScytheError> {
35        match s {
36            "one" => Ok(QueryCommand::One),
37            "opt" => Ok(QueryCommand::Opt),
38            "many" => Ok(QueryCommand::Many),
39            "exec" => Ok(QueryCommand::Exec),
40            "exec_result" => Ok(QueryCommand::ExecResult),
41            "exec_rows" => Ok(QueryCommand::ExecRows),
42            "batch" => Ok(QueryCommand::Batch),
43            "grouped" => Ok(QueryCommand::Grouped),
44            other => Err(ScytheError::invalid_annotation(format!(
45                "invalid @returns value: {other}"
46            ))),
47        }
48    }
49}
50
51#[derive(Debug, Clone, PartialEq, Eq)]
52pub struct ParamDoc {
53    pub name: String,
54    pub description: String,
55}
56
57#[derive(Debug, Clone, PartialEq, Eq)]
58pub struct JsonMapping {
59    pub column: String,
60    pub rust_type: String,
61}
62
63#[derive(Debug, Clone, PartialEq, Eq)]
64pub struct Annotations {
65    pub name: String,
66    pub command: QueryCommand,
67    pub param_docs: Vec<ParamDoc>,
68    pub nullable_overrides: Vec<String>,
69    pub nonnull_overrides: Vec<String>,
70    pub json_mappings: Vec<JsonMapping>,
71    pub deprecated: Option<String>,
72    pub optional_params: Vec<String>,
73    pub group_by: Option<String>,
74}
75
76#[derive(Debug)]
77pub struct Query {
78    pub name: String,
79    pub command: QueryCommand,
80    pub sql: String,
81    pub stmt: sqlparser::ast::Statement,
82    pub annotations: Annotations,
83}
84
85/// Parse a single annotated SQL query into a `Query` using the PostgreSQL dialect.
86pub fn parse_query(query_sql: &str) -> Result<Query, ScytheError> {
87    parse_query_with_dialect(query_sql, &SqlDialect::PostgreSQL)
88}
89
90/// Parse a single annotated SQL query into a `Query` using the specified dialect.
91pub fn parse_query_with_dialect(
92    query_sql: &str,
93    dialect: &SqlDialect,
94) -> Result<Query, ScytheError> {
95    let mut name: Option<String> = None;
96    let mut command: Option<QueryCommand> = None;
97    let mut param_docs = Vec::new();
98    let mut nullable_overrides = Vec::new();
99    let mut nonnull_overrides = Vec::new();
100    let mut json_mappings = Vec::new();
101    let mut deprecated: Option<String> = None;
102    let mut optional_params = Vec::new();
103    let mut group_by: Option<String> = None;
104
105    let mut sql_lines = Vec::new();
106
107    for line in query_sql.lines() {
108        let trimmed = line.trim();
109
110        // Check for annotation: "-- @..." or "--@..."
111        let annotation_body = if let Some(rest) = trimmed.strip_prefix("--") {
112            let rest = rest.trim_start();
113            rest.strip_prefix('@')
114        } else {
115            None
116        };
117
118        if let Some(body) = annotation_body {
119            // Parse the annotation keyword and value
120            let (keyword, value) = match body.find(|c: char| c.is_whitespace()) {
121                Some(pos) => (&body[..pos], body[pos..].trim()),
122                None => (body, ""),
123            };
124
125            match keyword.to_ascii_lowercase().as_str() {
126                "name" => {
127                    name = Some(value.to_string());
128                }
129                "returns" => {
130                    let cmd_str = value.strip_prefix(':').unwrap_or(value);
131                    command = Some(QueryCommand::from_str(cmd_str)?);
132                }
133                "param" => {
134                    // format: "<name>: <description>" or "<name>:<description>"
135                    if let Some(colon_pos) = value.find(':') {
136                        let param_name = value[..colon_pos].trim().to_string();
137                        let description = value[colon_pos + 1..].trim().to_string();
138                        param_docs.push(ParamDoc {
139                            name: param_name,
140                            description,
141                        });
142                    } else {
143                        param_docs.push(ParamDoc {
144                            name: value.to_string(),
145                            description: String::new(),
146                        });
147                    }
148                }
149                "nullable" => {
150                    for col in value.split(',') {
151                        let col = col.trim();
152                        if !col.is_empty() {
153                            nullable_overrides.push(col.to_string());
154                        }
155                    }
156                }
157                "nonnull" => {
158                    for col in value.split(',') {
159                        let col = col.trim();
160                        if !col.is_empty() {
161                            nonnull_overrides.push(col.to_string());
162                        }
163                    }
164                }
165                "json" => {
166                    // format: "<col> = <Type>"
167                    if let Some(eq_pos) = value.find('=') {
168                        let column = value[..eq_pos].trim().to_string();
169                        let rust_type = value[eq_pos + 1..].trim().to_string();
170                        json_mappings.push(JsonMapping { column, rust_type });
171                    }
172                }
173                "deprecated" => {
174                    deprecated = Some(value.to_string());
175                }
176                "group_by" => {
177                    group_by = Some(value.to_string());
178                }
179                "optional" => {
180                    for param in value.split(',') {
181                        let param = param.trim();
182                        if !param.is_empty() {
183                            optional_params.push(param.to_string());
184                        }
185                    }
186                }
187                _ => {
188                    // Unknown annotation — ignore or could error
189                }
190            }
191        } else {
192            sql_lines.push(line);
193        }
194    }
195
196    let name = name.ok_or_else(|| ScytheError::missing_annotation("name"))?;
197    let command = command.ok_or_else(|| ScytheError::missing_annotation("returns"))?;
198
199    if command == QueryCommand::Grouped && group_by.is_none() {
200        return Err(ScytheError::invalid_annotation(
201            "@returns :grouped requires a @group_by annotation (e.g. @group_by users.id)",
202        ));
203    }
204
205    let sql = sql_lines.join("\n").trim().to_string();
206
207    if sql.is_empty() {
208        return Err(ScytheError::syntax("empty SQL body"));
209    }
210
211    let parser_dialect = dialect.to_sqlparser_dialect();
212    let statements = Parser::parse_sql(parser_dialect.as_ref(), &sql)
213        .map_err(|e| ScytheError::syntax(format!("syntax error: {}", e)))?;
214
215    if statements.len() != 1 {
216        // sqlparser may produce an extra empty statement from a trailing semicolon —
217        // filter those out by checking for exactly one non-empty statement.
218        let non_empty: Vec<_> = statements
219            .into_iter()
220            .filter(|s| {
221                !matches!(s, sqlparser::ast::Statement::Flush { .. }) && format!("{s}") != ""
222            })
223            .collect();
224        if non_empty.len() != 1 {
225            return Err(ScytheError::syntax("expected exactly one SQL statement"));
226        }
227        let stmt = non_empty
228            .into_iter()
229            .next()
230            .expect("filtered to exactly one statement");
231        let annotations = Annotations {
232            name: name.clone(),
233            command: command.clone(),
234            param_docs,
235            nullable_overrides,
236            nonnull_overrides,
237            json_mappings,
238            deprecated,
239            optional_params,
240            group_by: group_by.clone(),
241        };
242        return Ok(Query {
243            name,
244            command,
245            sql,
246            stmt,
247            annotations,
248        });
249    }
250
251    let stmt = statements
252        .into_iter()
253        .next()
254        .expect("filtered to exactly one statement");
255
256    let annotations = Annotations {
257        name: name.clone(),
258        command: command.clone(),
259        param_docs,
260        nullable_overrides,
261        nonnull_overrides,
262        json_mappings,
263        deprecated,
264        optional_params,
265        group_by,
266    };
267
268    Ok(Query {
269        name,
270        command,
271        sql,
272        stmt,
273        annotations,
274    })
275}
276
277#[cfg(test)]
278mod tests {
279    use super::*;
280    use crate::errors::ErrorCode;
281
282    fn parse(sql: &str) -> Result<Query, ScytheError> {
283        parse_query(sql)
284    }
285
286    #[test]
287    fn test_basic_parse() {
288        let input = "-- @name GetUsers\n-- @returns :many\nSELECT * FROM users;";
289        let q = parse(input).unwrap();
290        assert_eq!(q.name, "GetUsers");
291        assert_eq!(q.command, QueryCommand::Many);
292        assert!(q.sql.contains("SELECT"));
293    }
294
295    #[test]
296    fn test_all_command_types() {
297        let cases = vec![
298            (":one", QueryCommand::One),
299            (":many", QueryCommand::Many),
300            (":exec", QueryCommand::Exec),
301            (":exec_result", QueryCommand::ExecResult),
302            (":exec_rows", QueryCommand::ExecRows),
303        ];
304        for (tag, expected) in cases {
305            let input = format!("-- @name Q\n-- @returns {}\nSELECT 1", tag);
306            let q = parse(&input).unwrap();
307            assert_eq!(q.command, expected, "failed for {}", tag);
308        }
309    }
310
311    #[test]
312    fn test_case_insensitive_keywords() {
313        let input = "-- @Name GetUsers\n-- @RETURNS :many\nSELECT 1";
314        let q = parse(input).unwrap();
315        assert_eq!(q.name, "GetUsers");
316        assert_eq!(q.command, QueryCommand::Many);
317    }
318
319    #[test]
320    fn test_missing_name_errors() {
321        let input = "-- @returns :many\nSELECT 1";
322        let err = parse(input).unwrap_err();
323        assert_eq!(err.code, ErrorCode::MissingAnnotation);
324        assert!(err.message.contains("name"));
325    }
326
327    #[test]
328    fn test_missing_returns_errors() {
329        let input = "-- @name Foo\nSELECT 1";
330        let err = parse(input).unwrap_err();
331        assert_eq!(err.code, ErrorCode::MissingAnnotation);
332        assert!(err.message.contains("returns"));
333    }
334
335    #[test]
336    fn test_invalid_returns_value() {
337        let input = "-- @name Foo\n-- @returns :invalid\nSELECT 1";
338        let err = parse(input).unwrap_err();
339        assert_eq!(err.code, ErrorCode::InvalidAnnotation);
340    }
341
342    #[test]
343    fn test_empty_name_value() {
344        // An empty name is accepted by the parser (it stores "")
345        let input = "-- @name\n-- @returns :one\nSELECT 1";
346        let q = parse(input).unwrap();
347        assert_eq!(q.name, "");
348    }
349
350    #[test]
351    fn test_param_annotation() {
352        let input = "-- @name Foo\n-- @returns :one\n-- @param id: the user ID\nSELECT 1";
353        let q = parse(input).unwrap();
354        assert_eq!(q.annotations.param_docs.len(), 1);
355        assert_eq!(q.annotations.param_docs[0].name, "id");
356        assert_eq!(q.annotations.param_docs[0].description, "the user ID");
357    }
358
359    #[test]
360    fn test_param_no_description() {
361        let input = "-- @name Foo\n-- @returns :one\n-- @param id\nSELECT 1";
362        let q = parse(input).unwrap();
363        assert_eq!(q.annotations.param_docs.len(), 1);
364        assert_eq!(q.annotations.param_docs[0].name, "id");
365        assert_eq!(q.annotations.param_docs[0].description, "");
366    }
367
368    #[test]
369    fn test_nullable_annotation() {
370        let input = "-- @name Foo\n-- @returns :one\n-- @nullable col1, col2\nSELECT 1";
371        let q = parse(input).unwrap();
372        assert_eq!(q.annotations.nullable_overrides, vec!["col1", "col2"]);
373    }
374
375    #[test]
376    fn test_nonnull_annotation() {
377        let input = "-- @name Foo\n-- @returns :one\n-- @nonnull col1\nSELECT 1";
378        let q = parse(input).unwrap();
379        assert_eq!(q.annotations.nonnull_overrides, vec!["col1"]);
380    }
381
382    #[test]
383    fn test_json_annotation() {
384        let input = "-- @name Foo\n-- @returns :one\n-- @json data = EventData\nSELECT 1";
385        let q = parse(input).unwrap();
386        assert_eq!(q.annotations.json_mappings.len(), 1);
387        assert_eq!(q.annotations.json_mappings[0].column, "data");
388        assert_eq!(q.annotations.json_mappings[0].rust_type, "EventData");
389    }
390
391    #[test]
392    fn test_deprecated_annotation() {
393        let input = "-- @name Foo\n-- @returns :one\n-- @deprecated Use V2\nSELECT 1";
394        let q = parse(input).unwrap();
395        assert_eq!(q.annotations.deprecated, Some("Use V2".to_string()));
396    }
397
398    #[test]
399    fn test_sql_syntax_error() {
400        let input = "-- @name Foo\n-- @returns :one\nSELCT * FROM users";
401        let err = parse(input).unwrap_err();
402        assert_eq!(err.code, ErrorCode::SyntaxError);
403    }
404
405    #[test]
406    fn test_trailing_semicolon() {
407        let input = "-- @name Foo\n-- @returns :one\nSELECT 1;";
408        let q = parse(input).unwrap();
409        assert_eq!(q.name, "Foo");
410    }
411
412    #[test]
413    fn test_multiple_statements_error() {
414        let input = "-- @name Foo\n-- @returns :one\nSELECT 1; SELECT 2;";
415        let err = parse(input).unwrap_err();
416        assert_eq!(err.code, ErrorCode::SyntaxError);
417    }
418
419    #[test]
420    fn test_sql_preserved_without_annotations() {
421        let input = "-- @name Foo\n-- @returns :one\nSELECT id, name FROM users WHERE id = $1";
422        let q = parse(input).unwrap();
423        assert_eq!(q.sql, "SELECT id, name FROM users WHERE id = $1");
424    }
425
426    #[test]
427    fn test_returns_without_colon_prefix() {
428        let input = "-- @name Foo\n-- @returns many\nSELECT 1";
429        let q = parse(input).unwrap();
430        assert_eq!(q.command, QueryCommand::Many);
431    }
432
433    #[test]
434    fn test_batch_command() {
435        let input = "-- @name Foo\n-- @returns :batch\nSELECT 1";
436        let q = parse(input).unwrap();
437        assert_eq!(q.command, QueryCommand::Batch);
438    }
439
440    #[test]
441    fn test_grouped_command_with_group_by() {
442        let input = "-- @name GetUsersWithOrders\n-- @returns :grouped\n-- @group_by users.id\nSELECT u.id, u.name FROM users u JOIN orders o ON o.user_id = u.id";
443        let q = parse(input).unwrap();
444        assert_eq!(q.command, QueryCommand::Grouped);
445        assert_eq!(q.annotations.group_by, Some("users.id".to_string()));
446    }
447
448    #[test]
449    fn test_grouped_command_without_group_by_errors() {
450        let input = "-- @name Foo\n-- @returns :grouped\nSELECT 1";
451        let err = parse(input).unwrap_err();
452        assert_eq!(err.code, ErrorCode::InvalidAnnotation);
453        assert!(err.message.contains("@group_by"));
454    }
455
456    #[test]
457    fn test_group_by_without_grouped_is_ignored() {
458        let input = "-- @name Foo\n-- @returns :many\n-- @group_by users.id\nSELECT 1";
459        let q = parse(input).unwrap();
460        assert_eq!(q.command, QueryCommand::Many);
461        assert_eq!(q.annotations.group_by, Some("users.id".to_string()));
462    }
463}
scythe_core/parser/mod.rs

scythe_core/parser/
mod.rs
