Skip to main content

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}