use serde_json::{json, Value};
#[must_use]
pub fn inputs_of(root: &clap::Command, wanted: &str) -> Value {
let Some(leaf) = leaf_of(root, wanted) else {
return Value::Array(Vec::new());
};
let mut inputs: Vec<Value> = leaf
.get_arguments()
.filter(|arg| !arg.is_global_set())
.map(|arg| {
let positional = arg.is_positional();
json!({
"name": arg.get_long().unwrap_or_else(|| arg.get_id().as_str()),
"kind": if positional {
"positional"
} else if matches!(
arg.get_action(),
clap::ArgAction::Set | clap::ArgAction::Append
) {
"option"
} else {
"flag"
},
"required": arg.is_required_set(),
"repeats": matches!(arg.get_action(), clap::ArgAction::Append),
"about": arg.get_help().map(ToString::to_string).unwrap_or_default(),
})
})
.collect();
inputs.sort_by(|left, right| left["name"].as_str().cmp(&right["name"].as_str()));
Value::Array(inputs)
}
#[must_use]
pub fn leaf_of<'tree>(root: &'tree clap::Command, wanted: &str) -> Option<&'tree clap::Command> {
let mut here = root;
for step in wanted.split(' ') {
here = here.get_subcommands().find(|sub| sub.get_name() == step)?;
}
Some(here)
}
const EFFECTS: &[(&str, &str)] = &[
("config doctor", "local"),
("config get", "local"),
("config list", "local"),
("config path", "local"),
("config set", "local"),
("config unset", "local"),
("conn add", "local"),
("conn default", "local"),
("conn edit", "local"),
("conn list", "local"),
("conn remove", "local"),
("conn show", "local"),
("conn test", "reads"),
("data export", "reads"),
("data import", "may_change"),
("history as-of", "reads"),
("history between", "reads"),
("history tables", "reads"),
("meta commands", "local"),
("meta completions", "local"),
("meta manual", "local"),
("meta schema", "local"),
("meta version", "local"),
("query analyze", "reads"),
("query call", "may_change"),
("query explain", "reads"),
("query file", "may_change"),
("query lineage", "local"),
("query named list", "local"),
("query named remove", "local"),
("query named run", "may_change"),
("query named save", "local"),
("query plan", "reads"),
("query run", "may_change"),
("query sample", "reads"),
("query tx", "may_change"),
("schema columns", "reads"),
("schema checks", "reads"),
("schema count", "reads"),
("schema databases", "reads"),
("schema ddl", "reads"),
("schema events", "reads"),
("schema grants", "reads"),
("schema indexes", "reads"),
("schema keys", "reads"),
("schema map", "reads"),
("schema partitions", "reads"),
("schema routines", "reads"),
("schema search", "reads"),
("schema sequences", "reads"),
("schema size", "reads"),
("schema stats", "reads"),
("schema tables", "reads"),
("schema triggers", "reads"),
("schema views", "reads"),
("server capabilities", "reads"),
("server kill", "may_change"),
("server locks", "reads"),
("server processes", "reads"),
("server queries", "reads"),
("server replica", "reads"),
("server status", "reads"),
("server variables", "reads"),
];
#[must_use]
pub fn effect_of(command: &str) -> &'static str {
EFFECTS
.iter()
.find(|(name, _)| *name == command)
.map_or("unpublished", |(_, effect)| *effect)
}
mod payload;
pub use payload::{
commands_whose_data_varies, commands_with_published_data, conditional_fields, data_shape_of,
field_is_conditional,
};
const MARKS_ABSENCE: &[(&str, &[&str])] = &[
("conn list", &["default"]),
("conn remove", &["default"]),
("schema tables", &["comment"]),
("schema views", &["comment"]),
("schema indexes", &["comment"]),
("schema routines", &["comment"]),
];
#[must_use]
pub fn marks_absence(command: &str) -> &'static [&'static str] {
MARKS_ABSENCE
.iter()
.find(|(name, _)| *name == command)
.map_or(&[], |(_, fields)| *fields)
}
#[must_use]
pub fn failure_shape() -> Value {
use crate::error::Category;
let categories: Vec<Value> = Category::ALL
.iter()
.map(|category| {
json!({
"category": category.as_str(),
"exit": category.exit_number().code(),
"retryable": category.is_retryable(),
})
})
.collect();
json!({
"channel": "the auxiliary channel; the primary channel carries data only",
"shape": {
"category": "string, one of the thirteen below, and the field to branch on",
"code": "string, stable identifier, finer than the category",
"message": "string, prose for a person, in the reader's language",
"hint": "string, present only when a concrete next action exists",
"retryable": "boolean, whether repeating unchanged may succeed",
"exit": "number, the exit number this failure produces",
"causes": "array of strings, present only when a dependency explained itself",
"conditions": "array of strings, present only when the server reported more than one",
},
"causes_are_diagnosis_only": "each entry is another library's own sentence, kept verbatim, \
so it stays in the language of its origin and is never branched on",
"categories": categories,
"declared_limit": "which of these categories this command can reach is not published \
per command; the closed set above is what any command may answer with",
})
}
#[must_use]
pub fn envelope_shape() -> Value {
json!({
"command": "string",
"schema_version": "number",
"target_resolved": "object, the destination this answer was served from",
"target_source": "string, how that destination was chosen: `argv` when the call named \
a profile, `dsn` when the call carried the whole destination, `config` when it \
was inherited from the stored default; a change refuses to run on an inherited \
destination unless `conn.require_explicit_target` is turned off",
"data": "object, the answer of this command; its fields are described under `data` in \
the contract of the command itself, which either names them or states there that \
this build does not describe them",
"gaps": "array, present only when something was not delivered",
"applied": "object, present only when the output pipeline acted",
"checksum": "string, present only when a signature was asked for",
"closing_record": closing_record_shape(),
})
}
fn closing_record_shape() -> Value {
use crate::output::format::{END_OF_STREAM_KEY, GAPS_KEY, ROW_COUNT_KEY};
json!({
"when": "the last record of a continuous flow, and absent when the flow was cut",
(END_OF_STREAM_KEY): "true, the mark that the set ended on its own",
(ROW_COUNT_KEY): "number, the rows this flow emitted",
(GAPS_KEY): "array, present only when something was left out",
})
}