1use std::collections::BTreeMap;
20use std::path::Path;
21
22use crate::ontology::rdf::{iri_path, Graph, Term, ONT_BASE, RDF_TYPE};
23
24pub const SCHEMA: &str = "apr-cli-surface/v1";
25pub const SCHEMAS: [&str; 2] = [SCHEMA, "apr-cli-surface/v1.1"];
27pub const ROLES: [&str; 8] = [
29 "model",
30 "prompt",
31 "input-file",
32 "backend",
33 "sampling",
34 "mode",
35 "other",
36 "unknown",
37];
38pub const UNSET: &str = "unset";
40
41#[must_use]
43pub fn cli(name: &str) -> String {
44 format!("{ONT_BASE}cli/{name}")
45}
46
47#[derive(Debug, Clone, PartialEq, Eq)]
49pub struct Arg {
50 pub id: String,
51 pub long: Option<String>,
52 pub short: Option<String>,
53 pub positional: bool,
54 pub required: bool,
55 pub value_type: String,
56 pub values: Vec<String>,
57 pub role: String,
58 pub marker: Option<String>,
59 pub hidden: bool,
60 pub conflicts_with: Vec<String>,
61 pub sampling_kind: Option<String>,
64}
65
66impl Arg {
67 #[must_use]
69 pub fn spelling(&self) -> String {
70 match (&self.long, &self.short, self.positional) {
71 (Some(l), _, _) => format!("--{l}"),
72 (None, Some(s), _) => format!("-{s}"),
73 _ => format!("<{}>", self.id),
74 }
75 }
76
77 #[must_use]
80 pub fn levels(&self) -> Vec<String> {
81 if self.role != "mode" {
82 return Vec::new();
83 }
84 let mut out = Vec::new();
85 if !self.required {
86 out.push(UNSET.to_string());
87 }
88 if self.value_type == "flag" || self.value_type == "count" {
89 out.push("true".to_string());
90 } else {
91 out.extend(self.values.iter().cloned());
92 }
93 out
94 }
95}
96
97#[derive(Debug, Clone, PartialEq, Eq)]
99pub struct Command {
100 pub key: String,
101 pub path: Vec<String>,
102 pub leaf: bool,
103 pub hidden: bool,
104 pub foreign: bool,
105 pub generates: Option<bool>,
108 pub args: Vec<Arg>,
109}
110
111impl Command {
112 #[must_use]
113 pub fn takes_model(&self) -> bool {
114 self.args.iter().any(|a| a.role == "model")
115 }
116
117 #[must_use]
119 pub fn input_shapes(&self) -> Vec<&Arg> {
120 self.args
121 .iter()
122 .filter(|a| a.role == "prompt" || a.role == "input-file")
123 .collect()
124 }
125
126 pub fn mode_args<'a>(&'a self, globals: &'a [Arg]) -> impl Iterator<Item = &'a Arg> {
128 self.args
129 .iter()
130 .chain(globals.iter())
131 .filter(|a| a.role == "mode" && !a.levels().is_empty())
132 }
133}
134
135#[derive(Debug, Clone, PartialEq, Eq)]
137pub struct Surface {
138 pub file: String,
139 pub version: String,
140 pub git_sha: String,
141 pub global_args: Vec<Arg>,
142 pub commands: Vec<Command>,
143}
144
145#[derive(Debug, Clone, PartialEq, Eq)]
147pub struct SurfaceError {
148 pub file: String,
149 pub what: String,
150}
151
152impl std::fmt::Display for SurfaceError {
153 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
154 write!(f, "{}: {}", self.file, self.what)
155 }
156}
157
158impl std::error::Error for SurfaceError {}
159
160pub fn read(path: &Path) -> Result<Surface, SurfaceError> {
161 let file = path.display().to_string();
162 let text = std::fs::read_to_string(path).map_err(|e| SurfaceError {
163 file: file.clone(),
164 what: format!("unreadable: {e}"),
165 })?;
166 parse(&file, &text)
167}
168
169fn str_of(v: &serde_json::Value, key: &str) -> Option<String> {
170 v.get(key)
171 .and_then(serde_json::Value::as_str)
172 .map(str::to_string)
173}
174
175fn bool_of(v: &serde_json::Value, key: &str) -> bool {
176 v.get(key)
177 .and_then(serde_json::Value::as_bool)
178 .unwrap_or(false)
179}
180
181fn strings(v: &serde_json::Value, key: &str) -> Vec<String> {
182 v.get(key)
183 .and_then(serde_json::Value::as_array)
184 .into_iter()
185 .flatten()
186 .filter_map(serde_json::Value::as_str)
187 .map(str::to_string)
188 .collect()
189}
190
191pub fn parse(file: &str, text: &str) -> Result<Surface, SurfaceError> {
193 let err = |what: String| SurfaceError {
194 file: file.to_string(),
195 what,
196 };
197 let v: serde_json::Value =
198 serde_json::from_str(text).map_err(|e| err(format!("not JSON: {e}")))?;
199 let schema = v
200 .get("schema")
201 .and_then(serde_json::Value::as_str)
202 .unwrap_or("");
203 if !SCHEMAS.contains(&schema) {
204 return Err(err(format!(
205 "schema {schema:?} is not {} — refused by name",
206 SCHEMAS.join(" or ")
207 )));
208 }
209 let args_of = |node: &serde_json::Value, key: &str, owner: &str| {
210 node.get(key)
211 .and_then(serde_json::Value::as_array)
212 .into_iter()
213 .flatten()
214 .map(|a| parse_arg(a).map_err(|w| err(format!("{owner}: {w}"))))
215 .collect::<Result<Vec<Arg>, SurfaceError>>()
216 };
217 let global_args = args_of(&v, "global_args", "global_args")?;
218 let mut commands = Vec::new();
219 for c in v
220 .get("commands")
221 .and_then(serde_json::Value::as_array)
222 .into_iter()
223 .flatten()
224 {
225 let key = str_of(c, "key").unwrap_or_default();
226 commands.push(Command {
227 path: strings(c, "path"),
228 leaf: bool_of(c, "leaf"),
229 hidden: bool_of(c, "hidden"),
230 foreign: bool_of(c, "foreign"),
231 generates: c.get("generates").and_then(serde_json::Value::as_bool),
232 args: args_of(c, "args", &key)?,
233 key,
234 });
235 }
236 let binary = v.get("binary").cloned().unwrap_or_default();
237 Ok(Surface {
238 file: file.to_string(),
239 version: str_of(&binary, "version").unwrap_or_default(),
240 git_sha: str_of(&binary, "git_sha").unwrap_or_default(),
241 global_args,
242 commands,
243 })
244}
245
246fn parse_arg(a: &serde_json::Value) -> Result<Arg, String> {
247 let id = str_of(a, "id").unwrap_or_default();
248 let role = str_of(a, "role").unwrap_or_default();
249 if !ROLES.contains(&role.as_str()) {
250 return Err(format!(
251 "arg {id:?} has role {role:?}, which apr-cli-surface/v1 does not define — refused by name"
252 ));
253 }
254 Ok(Arg {
255 long: str_of(a, "long"),
256 short: str_of(a, "short"),
257 positional: bool_of(a, "positional"),
258 required: bool_of(a, "required"),
259 value_type: str_of(a, "value_type").unwrap_or_default(),
260 values: strings(a, "values"),
261 role,
262 marker: str_of(a, "marker"),
263 hidden: bool_of(a, "hidden"),
264 conflicts_with: strings(a, "conflicts_with"),
265 sampling_kind: str_of(a, "sampling_kind"),
266 id,
267 })
268}
269
270#[derive(Debug, Clone, Default, PartialEq, Eq, serde::Serialize)]
272pub struct SurfaceStats {
273 pub commands: usize,
274 pub leaves: usize,
275 pub model_commands: usize,
276 pub generating_commands: usize,
277 pub generates_declared: bool,
279 pub by_role: BTreeMap<String, usize>,
280 pub unknown_args: usize,
282 pub unknown_outside_foreign: usize,
283 pub stdin_undeclared: usize,
285}
286
287fn path_of(c: &Command) -> Vec<&str> {
288 c.path.iter().map(String::as_str).collect()
289}
290
291pub fn emit(g: &mut Graph, s: &Surface) -> SurfaceStats {
293 let mut st = SurfaceStats {
294 generates_declared: true,
295 ..SurfaceStats::default()
296 };
297 for a in &s.global_args {
298 emit_arg(g, &["-"], a);
299 }
300 for c in &s.commands {
301 emit_command(g, c, &mut st);
302 }
303 st
304}
305
306fn emit_command(g: &mut Graph, c: &Command, st: &mut SurfaceStats) {
307 st.commands += 1;
308 let path = path_of(c);
309 let n = iri_path("cli-command", &path);
310 g.insert(n.clone(), RDF_TYPE, Term::iri(cli("Command")));
311 g.insert(n.clone(), cli("key"), Term::string(&c.key));
312 g.insert(n.clone(), cli("leaf"), Term::boolean(c.leaf));
313 g.insert(n.clone(), cli("hidden"), Term::boolean(c.hidden));
314 g.insert(n.clone(), cli("foreign"), Term::boolean(c.foreign));
315 if let Some(gen) = c.generates {
316 g.insert(n.clone(), cli("generates"), Term::boolean(gen));
317 }
318 if c.leaf {
319 st.leaves += 1;
320 }
321 if c.takes_model() {
322 st.model_commands += 1;
323 g.insert(n.clone(), RDF_TYPE, Term::iri(cli("ModelCommand")));
324 match c.generates {
325 Some(true) => st.generating_commands += 1,
326 Some(false) => {}
327 None => st.generates_declared = false,
328 }
329 }
330 for a in &c.args {
331 *st.by_role.entry(a.role.clone()).or_default() += 1;
332 if a.role == "unknown" {
333 st.unknown_args += 1;
334 if !c.foreign {
335 st.unknown_outside_foreign += 1;
336 }
337 }
338 let stdin_capable = matches!(a.role.as_str(), "model" | "input-file" | "prompt");
339 if a.positional && stdin_capable {
340 st.stdin_undeclared += 1;
341 }
342 let an = emit_arg(g, &path, a);
343 g.insert(n.clone(), cli("arg"), Term::iri(an));
344 }
345}
346
347fn emit_arg(g: &mut Graph, path: &[&str], a: &Arg) -> String {
348 let mut segs: Vec<&str> = path.to_vec();
349 segs.push(&a.id);
350 let n = iri_path("cli-arg", &segs);
351 g.insert(n.clone(), RDF_TYPE, Term::iri(cli("Arg")));
352 g.insert(n.clone(), cli("id"), Term::string(&a.id));
353 g.insert(n.clone(), cli("spelling"), Term::string(a.spelling()));
354 g.insert(n.clone(), cli("role"), Term::string(&a.role));
355 g.insert(n.clone(), cli("valueType"), Term::string(&a.value_type));
356 g.insert(n.clone(), cli("positional"), Term::boolean(a.positional));
357 g.insert(n.clone(), cli("required"), Term::boolean(a.required));
358 if let Some(m) = &a.marker {
359 g.insert(n.clone(), cli("marker"), Term::string(m));
360 }
361 for c in &a.conflicts_with {
362 g.insert(n.clone(), cli("conflictsWith"), Term::string(c));
363 }
364 for level in a.levels() {
365 let mut s2 = segs.clone();
366 s2.push(&level);
367 let m = iri_path("cli-mode", &s2);
368 g.insert(m.clone(), RDF_TYPE, Term::iri(cli("ModeValue")));
369 g.insert(m.clone(), cli("level"), Term::string(&level));
370 g.insert(n.clone(), cli("modeValue"), Term::iri(m));
371 }
372 if a.role == "prompt" || a.role == "input-file" {
373 let s = iri_path("cli-shape", &segs);
374 g.insert(s.clone(), RDF_TYPE, Term::iri(cli("InputShape")));
375 g.insert(s.clone(), cli("spelling"), Term::string(a.spelling()));
376 g.insert(n.clone(), cli("inputShape"), Term::iri(s));
377 }
378 n
379}
380
381#[must_use]
386pub fn positive_control() -> bool {
387 let typed = |role: &str| {
388 let text = PC_SURFACE.replace("__ROLE__", role);
389 let Ok(s) = parse("__pc_surface__.json", &text) else {
390 return None;
391 };
392 let mut g = Graph::new();
393 let st = emit(&mut g, &s);
394 let run = iri_path("cli-command", &["run"]);
395 let is_model = g
396 .objects(&run, RDF_TYPE)
397 .iter()
398 .any(|t| t.as_iri() == Some(cli("ModelCommand").as_str()));
399 Some((is_model, st.model_commands))
400 };
401 matches!(
402 (typed("model"), typed("other")),
403 (Some((true, 1)), Some((false, 0)))
404 )
405}
406
407const PC_SURFACE: &str = r#"{"schema":"apr-cli-surface/v1","binary":{"name":"apr","version":"0.0.0-pc","git_sha":"pc"},
408"global_args":[{"id":"json","long":"json","value_type":"flag","values":["true","false"],"role":"mode"}],
409"commands":[
410 {"path":["run"],"key":"run","leaf":true,"hidden":false,"foreign":false,"generates":true,"args":[
411 {"id":"model","positional":true,"required":true,"value_type":"path","role":"__ROLE__","marker":"ModelRef"},
412 {"id":"prompt","long":"prompt","value_type":"text","role":"prompt","marker":"PromptText"},
413 {"id":"chat","long":"chat","value_type":"flag","values":["true","false"],"role":"mode"}]},
414 {"path":["list"],"key":"list","leaf":true,"hidden":false,"foreign":false,"args":[]}]}"#;
415
416#[cfg(test)]
417mod tests {
418 use super::*;
419
420 #[test]
421 fn the_control_fires_and_a_foreign_schema_or_role_is_refused_by_name() {
422 assert!(positive_control());
423 let e = parse("x.json", r#"{"schema":"apr-cli-surface/v9"}"#).expect_err("refused");
424 assert!(e.what.contains("v9") && e.what.contains(SCHEMA), "{e}");
425 let bad = PC_SURFACE.replace("__ROLE__", "modelish");
426 let e = parse("x.json", &bad).expect_err("unknown role refused");
427 assert!(e.what.contains("modelish"), "{e}");
428 }
429
430 #[test]
431 fn levels_start_at_unset_and_the_ratchets_count_what_v1_cannot_say() {
432 let s = parse("pc.json", &PC_SURFACE.replace("__ROLE__", "model")).expect("parses");
433 let run = &s.commands[0];
434 let modes: Vec<(String, Vec<String>)> = run
435 .mode_args(&s.global_args)
436 .map(|a| (a.spelling(), a.levels()))
437 .collect();
438 assert_eq!(
439 modes,
440 vec![
441 ("--chat".to_string(), vec!["unset".into(), "true".into()]),
442 ("--json".to_string(), vec!["unset".into(), "true".into()]),
443 ],
444 "the command's own mode args, then the propagated globals"
445 );
446 let mut g = Graph::new();
447 let st = emit(&mut g, &s);
448 assert_eq!(st.model_commands, 1);
449 assert_eq!(st.generating_commands, 1);
450 assert!(st.generates_declared);
451 assert_eq!(st.stdin_undeclared, 1, "the model positional");
452 let no_gen = PC_SURFACE
453 .replace("__ROLE__", "model")
454 .replace(r#""generates":true,"#, "");
455 let st2 = emit(
456 &mut Graph::new(),
457 &parse("pc.json", &no_gen).expect("parses"),
458 );
459 assert!(
460 !st2.generates_declared,
461 "a model command that does not say is named"
462 );
463 }
464
465 const COUNT_SURFACE: &str = r#"{"schema":"apr-cli-surface/v1","binary":{},
466"global_args":[],
467"commands":[
468 {"path":["a"],"key":"a","leaf":true,"hidden":false,"foreign":false,"args":[
469 {"id":"u1","long":"u1","value_type":"text","role":"unknown"},
470 {"id":"p","long":"p","value_type":"text","role":"prompt"},
471 {"id":"f","long":"f","value_type":"path","role":"input-file"},
472 {"id":"o","long":"o","value_type":"text","role":"other"},
473 {"id":"m","positional":true,"value_type":"path","role":"model"}]},
474 {"path":["b"],"key":"b","leaf":false,"hidden":false,"foreign":true,"args":[
475 {"id":"u2","long":"u2","value_type":"text","role":"unknown"},
476 {"id":"u3","long":"u3","value_type":"text","role":"unknown"},
477 {"id":"u5","long":"u5","value_type":"text","role":"unknown"}]},
478 {"path":["c"],"key":"c","leaf":true,"hidden":false,"foreign":false,"args":[
479 {"id":"u4","long":"u4","value_type":"text","role":"unknown"}]}]}"#;
480
481 #[test]
482 fn emit_counts_commands_leaves_roles_and_unknowns_exactly() {
483 let s = parse("c.json", COUNT_SURFACE).expect("parses");
484 let mut g = Graph::new();
485 let st = emit(&mut g, &s);
486 assert_eq!(st.commands, 3);
487 assert_eq!(st.leaves, 2);
488 assert_eq!(st.model_commands, 1);
489 assert_eq!(st.by_role.get("unknown"), Some(&5));
490 assert_eq!(st.by_role.get("prompt"), Some(&1));
491 assert_eq!(st.by_role.get("model"), Some(&1));
492 assert_eq!(st.unknown_args, 5);
493 assert_eq!(st.unknown_outside_foreign, 2, "a and c are not foreign");
494 }
495
496 #[test]
497 fn emit_arg_returns_its_node_and_types_only_prompt_and_input_file_as_shapes() {
498 let s = parse("c.json", COUNT_SURFACE).expect("parses");
499 let mut g = Graph::new();
500 let _ = emit(&mut g, &s);
501 let shape_of = |g: &Graph, id: &str| {
502 g.objects(&iri_path("cli-arg", &["a", id]), &cli("inputShape"))
503 .len()
504 };
505 assert_eq!(shape_of(&g, "p"), 1);
506 assert_eq!(shape_of(&g, "f"), 1);
507 assert_eq!(shape_of(&g, "o"), 0);
508 assert_eq!(shape_of(&g, "m"), 0);
509 let arg = &s.commands[0].args[1];
510 let mut g2 = Graph::new();
511 let n = emit_arg(&mut g2, &["a"], arg);
512 assert_eq!(n, iri_path("cli-arg", &["a", "p"]));
513 assert!(!g2.is_empty());
514 }
515
516 #[test]
517 fn mode_args_drops_a_mode_arg_with_no_levels_and_display_names_file_and_what() {
518 let text = r#"{"schema":"apr-cli-surface/v1","binary":{},"global_args":[],
519"commands":[{"path":["x"],"key":"x","leaf":true,"hidden":false,"foreign":false,"args":[
520 {"id":"empty","long":"empty","required":true,"value_type":"enum","values":[],"role":"mode"},
521 {"id":"ok","long":"ok","value_type":"flag","role":"mode"}]}]}"#;
522 let s = parse("m.json", text).expect("parses");
523 let ids: Vec<&str> = s.commands[0]
524 .mode_args(&s.global_args)
525 .map(|a| a.id.as_str())
526 .collect();
527 assert_eq!(ids, vec!["ok"]);
528 let e = SurfaceError {
529 file: "f.json".into(),
530 what: "broken".into(),
531 };
532 assert_eq!(e.to_string(), "f.json: broken");
533 }
534}