qql_convert/lib.rs
1//! Qdrant REST JSON to QQL statement converter.
2//!
3//! Five input shapes are accepted:
4//!
5//! 1. **Wrapped request** — `{"method", "path", "query"?, "body"?}`; the
6//! collection is derived from the path. `query` recovers `wait` /
7//! `timeout` / `consistency` (also accepted as a `?…` suffix on `path`).
8//! 2. **Bare body** — raw Qdrant REST JSON without path context; the caller
9//! must supply the collection via [`convert`] / [`convert_stmts`].
10//! 3. **JSONL capture** — one wrapped request or bare body per line, as
11//! written by `qql record`. A failing line reports its 1-based number via
12//! [`ConvertError::InvalidLine`].
13//! 4. **HTTP snippet** — a `METHOD /path` line plus a JSON body, as shown in
14//! docs and blogs (full URLs and an `HTTP/x` suffix are accepted).
15//! 5. **`curl` command** — a pasted invocation (`-X`, `-d`, `--header`, …,
16//! multi-line continuations, several commands). Shell-dynamic constructs
17//! (`$VAR`, `@file`, pipes) fail closed;
18//!
19//! Markdown fences around any of the above are stripped as paste noise.
20//!
21//! Conversion is contract-driven and AST-based:
22//!
23//! ```text
24//! OpenAPI request JSON -> qql_core::ast::Stmt -> qql_core::fmt::format_stmt
25//! ```
26//!
27//! The returned strings are **only** produced by the canonical formatter
28//! (the same emitter behind `qql fmt`), so every emitted statement re-parses
29//! and is byte-stable under `format_stmt(parse(emit))`. Decoding fails closed:
30//! shapes the QQL AST cannot express return a typed [`ConvertError`], never a
31//! placeholder or a silently dropped field.
32
33mod bare;
34mod convert;
35mod decode;
36mod endpoint;
37mod json;
38mod request;
39mod shell;
40mod snippet;
41
42pub use convert::{convert, convert_stmts};
43use std::fmt;
44
45/// Typed conversion failure.
46///
47/// Returned by [`convert`] and [`convert_stmts`].
48#[derive(Debug, Clone, PartialEq, Eq)]
49pub enum ConvertError {
50 /// The input is not valid JSON. Holds the underlying parse message.
51 InvalidJson(String),
52 /// A wrapped request targets an endpoint with no QQL mapping.
53 /// Holds `"METHOD path"`.
54 UnsupportedEndpoint(String),
55 /// A bare body was given without a collection name.
56 MissingCollection,
57 /// The body is absent or structurally undecodable for the endpoint.
58 /// Holds a human-readable reason.
59 UndecodableBody {
60 /// Why the body cannot be decoded.
61 detail: String,
62 },
63 /// A structurally recognized body has an invalid or unrepresentable
64 /// field at `path` (e.g. `points[0].vector`).
65 InvalidField {
66 /// Dot/bracket path of the offending field.
67 path: String,
68 /// Why the field is invalid or cannot be represented in QQL.
69 detail: String,
70 },
71 /// A JSONL capture line failed to convert. Holds the 1-based line number
72 /// and the underlying error.
73 InvalidLine {
74 /// 1-based line number of the failing capture entry.
75 line: usize,
76 /// The conversion error raised for that line.
77 source: Box<ConvertError>,
78 },
79}
80
81impl ConvertError {
82 pub(crate) fn invalid(path: impl Into<String>, detail: impl Into<String>) -> Self {
83 Self::InvalidField {
84 path: path.into(),
85 detail: detail.into(),
86 }
87 }
88
89 pub(crate) fn undecodable(detail: impl Into<String>) -> Self {
90 Self::UndecodableBody {
91 detail: detail.into(),
92 }
93 }
94}
95
96impl fmt::Display for ConvertError {
97 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
98 match self {
99 Self::InvalidJson(e) => write!(f, "invalid JSON: {e}"),
100 Self::UnsupportedEndpoint(ep) => write!(f, "unsupported endpoint: {ep}"),
101 Self::MissingCollection => write!(
102 f,
103 "bare request body requires a collection (pass --collection)"
104 ),
105 Self::UndecodableBody { detail } => write!(f, "cannot decode request body: {detail}"),
106 Self::InvalidField { path, detail } => write!(f, "invalid field '{path}': {detail}"),
107 Self::InvalidLine { line, source } => write!(f, "line {line}: {source}"),
108 }
109 }
110}
111
112impl std::error::Error for ConvertError {
113 fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
114 match self {
115 Self::InvalidLine { source, .. } => Some(source.as_ref()),
116 _ => None,
117 }
118 }
119}