Plan, apply and roll back changes to a production ontology, with a blast radius report and a proof an auditor can re-check.
Rust ai-nativedescription-logicsformal-verificationinfrastructure-as-codeisabelle-languageknowledge-graphleanlean4mcpmcp-serverontologyowlowl2reasoningrustshaclsparqltheorem-proving
fix(shacl): report focus-node counts so a run that matched nothing cannot read as a pass
FABIOTESS8586abcf3e6c
diff --git a/src/main.rs b/src/main.rsindex e2392185..e752be2a 100644--- a/src/main.rs+++ b/src/main.rs@@ -577,6 +577,19 @@ fn setup(data_dir: &str) -> anyhow::Result<(StateDb, Arc<GraphStore>)> {Ok((db, graph))}+/// Whether the resolved storage backend keeps the graph in RAM only.+///+/// One-shot CLI subcommands each build their own store, so in this mode nothing+/// a command loads is visible to the next one.+fn is_memory_storage(data_dir: &str) -> bool {+ use open_ontologies::config::{resolve_storage_mode, StorageMode};+ let data_path = std::path::PathBuf::from(expand_tilde(data_dir));+ let storage_cfg = open_ontologies::config::Config::load(&data_path.join("config.toml"))+ .map(|c| c.storage)+ .unwrap_or_default();+ matches!(resolve_storage_mode(&storage_cfg), StorageMode::Memory)+}+/// Build the singleton main graph using the configured storage backend.////// In-memory: returns an empty `GraphStore`.@@ -1436,10 +1449,24 @@ async fn async_main() -> anyhow::Result<()> {Commands::Load { path } => {let (_db, graph) = setup(&cli.data_dir)?;match graph.load_file(&path) {- Ok(count) => output_json(- &serde_json::json!({"ok": true, "triples_loaded": count, "path": path}),- cli.pretty,- ),+ Ok(count) => {+ let mut report =+ serde_json::json!({"ok": true, "triples_loaded": count, "path": path});+ // In-memory is the default backend, so a one-shot `load`+ // fills a store that dies with the process. Saying only+ // "triples_loaded" here reads as durable, and the next+ // command reporting zero reads as data loss.+ if is_memory_storage(&cli.data_dir) {+ report["warning"] = serde_json::Value::String(+ "storage mode is 'memory', so this load did not persist: \+ a following command starts from an empty store. Set \+ [storage] mode = \"persistent\" or OPEN_ONTOLOGIES_STORAGE_MODE=persistent \+ to chain CLI commands."+ .to_string(),+ );+ }+ output_json(&report, cli.pretty)+ }Err(e) => {output_json(&serde_json::json!({"error": e.to_string()}), cli.pretty);std::process::exit(1);diff --git a/src/shacl.rs b/src/shacl.rsindex b53e7477..ebae90fa 100644--- a/src/shacl.rs+++ b/src/shacl.rs@@ -45,6 +45,8 @@ impl ShaclValidator {let mut violations: Vec<serde_json::Value> = Vec::new();let mut skipped: Vec<serde_json::Value> = Vec::new();+ let mut unmatched: Vec<serde_json::Value> = Vec::new();+ let mut focus_nodes_total: u64 = 0;for shape in &shapes {let target_class = match shape.get("targetClass") {@@ -52,6 +54,22 @@ impl ShaclValidator {None => continue,};+ // How many nodes does this shape actually apply to? A shape whose+ // target class appears nowhere in the data evaluates every one of+ // its constraints against the empty set and contributes no+ // violations, which is indistinguishable in the report from a shape+ // that checked its nodes and found them sound.+ let focus_count = count_focus_nodes(graph, &target_class)?;+ focus_nodes_total += focus_count;+ if focus_count == 0 {+ unmatched.push(serde_json::json!({+ "shape": strip_angle_brackets(+ shape.get("shape").map(|s| s.as_str()).unwrap_or_default()+ ),+ "target_class": target_class,+ }));+ }+// 3. Find property constraints for this shapelet shape_iri = match shape.get("shape") {Some(s) => s.clone(),@@ -412,11 +430,24 @@ impl ShaclValidator {}}+ let nothing_matched = !shapes.is_empty() && focus_nodes_total == 0;+let mut report = serde_json::json!({"violation_count": violations.len(),"violations": violations,+ "focus_nodes": focus_nodes_total,+ "unmatched_shapes": unmatched,});- if skipped.is_empty() {+ if nothing_matched && skipped.is_empty() {+ // Every shape targeted a class with no instances in the data, so+ // nothing was checked. Reporting `conforms: true` here would be the+ // same lie as reporting it for a constraint that never ran.+ report["conforms"] = serde_json::Value::Null;+ report["warning"] = serde_json::Value::String(format!(+ "no focus nodes matched: all {} shape(s) target classes absent from the data, so conformance is undetermined. See unmatched_shapes.",+ shapes.len()+ ));+ } else if skipped.is_empty() {report["conforms"] = serde_json::Value::Bool(violations.is_empty());} else {// Some constraints in this shapes graph were not evaluated, so no@@ -698,6 +729,23 @@ fn is_recognised_xsd_datatype(iri: &str) -> bool {}/// Trim angle brackets from IRI strings like `<http://example.org/foo>`.+/// Count the distinct nodes a `sh:targetClass` shape applies to.+///+/// Used to tell "checked and clean" apart from "checked nothing": a shape whose+/// target class has no instances passes every constraint vacuously.+fn count_focus_nodes(graph: &Arc<GraphStore>, target_class: &str) -> anyhow::Result<u64> {+ let query = format!(+ r#"SELECT (COUNT(DISTINCT ?focus) AS ?cnt) WHERE {{ ?focus a <{target_class}> }}"#+ );+ let rows = graph_sparql_select(graph, &query)?;+ Ok(rows+ .first()+ .and_then(|row| row.get("cnt"))+ .map(|c| strip_quotes(c))+ .and_then(|c| c.parse::<u64>().ok())+ .unwrap_or(0))+}+fn strip_angle_brackets(s: &str) -> String {let s = s.trim();if s.starts_with('<') && s.ends_with('>') {diff --git a/tests/cli_load_ephemeral_test.rs b/tests/cli_load_ephemeral_test.rsnew file mode 100644index 00000000..3140581d--- /dev/null+++ b/tests/cli_load_ephemeral_test.rs@@ -0,0 +1,74 @@+//! `load` in one-shot CLI mode must say when nothing was kept.+//!+//! With the default in-memory storage backend every CLI invocation builds a+//! fresh store, so `open-ontologies load data.ttl` populates a graph that is+//! dropped when the process exits. It reported `{"ok": true, "triples_loaded": N}`+//! and the very next `stats` reported zero, which reads as data loss rather than+//! as the documented consequence of the storage mode.+//!+//! Same rule as the SHACL reports: a success-shaped answer must not stand in for+//! something that did not persist.++use std::process::Command;++fn oo(dir: &tempfile::TempDir) -> Command {+ let mut cmd = Command::new(env!("CARGO_BIN_EXE_open-ontologies"));+ cmd.arg("--data-dir").arg(dir.path());+ cmd+}++fn write_ttl(dir: &tempfile::TempDir) -> std::path::PathBuf {+ let path = dir.path().join("data.ttl");+ std::fs::write(+ &path,+ "@prefix ex: <http://example.org/> .\nex:alice a ex:Person .\n",+ )+ .unwrap();+ path+}++#[test]+fn load_in_memory_mode_warns_that_the_store_is_not_persisted() {+ let dir = tempfile::tempdir().unwrap();+ let ttl = write_ttl(&dir);++ let out = oo(&dir)+ .env("OPEN_ONTOLOGIES_STORAGE_MODE", "memory")+ .arg("load")+ .arg(&ttl)+ .output()+ .unwrap();+ let report: serde_json::Value =+ serde_json::from_slice(&out.stdout).expect("load emits JSON");++ assert_eq!(report["ok"], serde_json::json!(true));+ assert_eq!(report["triples_loaded"], serde_json::json!(1));+ let warning = report["warning"]+ .as_str()+ .expect("in-memory load must carry a warning");+ assert!(+ warning.contains("persist"),+ "warning should say the load did not persist, got: {warning}"+ );+}++#[test]+fn load_in_persistent_mode_carries_no_warning() {+ let dir = tempfile::tempdir().unwrap();+ let ttl = write_ttl(&dir);++ let out = oo(&dir)+ .env("OPEN_ONTOLOGIES_STORAGE_MODE", "persistent")+ .arg("load")+ .arg(&ttl)+ .output()+ .unwrap();+ let report: serde_json::Value =+ serde_json::from_slice(&out.stdout).expect("load emits JSON");++ assert_eq!(report["triples_loaded"], serde_json::json!(1));+ assert!(+ report["warning"].is_null(),+ "a persisted load has nothing to warn about"+ );+}diff --git a/tests/shacl_vacuous_target_test.rs b/tests/shacl_vacuous_target_test.rsnew file mode 100644index 00000000..95af8f26--- /dev/null+++ b/tests/shacl_vacuous_target_test.rs@@ -0,0 +1,122 @@+//! Vacuous conformance: shapes that matched no focus nodes.+//!+//! A SHACL run whose shapes target classes that appear nowhere in the data+//! produces `conforms: true, violation_count: 0` — byte-for-byte the report of a+//! run where every constraint was checked and passed. The caller cannot tell the+//! two apart, so a pipeline that validates before publishing gets a green light+//! on data nothing looked at.+//!+//! This is the same failure the `sh:sparql` fix (#98) pinned down from the other+//! direction: there, constraints were never executed; here, they execute against+//! an empty target set. `ShaclValidator`'s stated contract is that reporting+//! success for rules that were never run is the one failure mode it must not+//! have, so these tests pin:+//!+//! 1. shapes matching zero focus nodes report which shapes matched nothing;+//! 2. a run where nothing at all matched does not claim conformance;+//! 3. an ordinary passing run still reports `conforms: true`, with the count;+//! 4. a partial match keeps a real verdict but still names the empty shape.++use open_ontologies::graph::GraphStore;+use open_ontologies::shacl::ShaclValidator;+use std::sync::Arc;++fn store_with_people() -> Arc<GraphStore> {+ let store = Arc::new(GraphStore::new());+ let ttl = r#"+ @prefix ex: <http://example.org/> .+ ex:alice a ex:Person ; ex:fullName "Alice" .+ "#;+ store.load_turtle(ttl, None).unwrap();+ store+}++fn report(store: &Arc<GraphStore>, shapes: &str) -> serde_json::Value {+ serde_json::from_str(&ShaclValidator::validate(store, shapes).unwrap()).unwrap()+}++/// Shapes minted in one namespace, data in another: the exact shape of the+/// mismatch that makes generated shapes silently target nothing.+const SHAPES_WRONG_NAMESPACE: &str = r#"+ @prefix sh: <http://www.w3.org/ns/shacl#> .+ @prefix ex: <http://example.org/shapes/> .+ ex:PersonShape a sh:NodeShape ;+ sh:targetClass ex:Person ;+ sh:property [ sh:path ex:fullName ; sh:minCount 1 ] .+"#;++const SHAPES_RIGHT_NAMESPACE: &str = r#"+ @prefix sh: <http://www.w3.org/ns/shacl#> .+ @prefix ex: <http://example.org/> .+ ex:PersonShape a sh:NodeShape ;+ sh:targetClass ex:Person ;+ sh:property [ sh:path ex:fullName ; sh:minCount 1 ] .+"#;++#[test]+fn shapes_that_match_nothing_are_named_in_the_report() {+ let r = report(&store_with_people(), SHAPES_WRONG_NAMESPACE);++ assert_eq!(+ r["focus_nodes"],+ serde_json::json!(0),+ "a report that hides a zero target count cannot be distinguished from a real pass"+ );+ let unmatched = r["unmatched_shapes"]+ .as_array()+ .expect("unmatched_shapes must be present");+ assert_eq!(unmatched.len(), 1);+ assert_eq!(+ unmatched[0]["target_class"],+ "http://example.org/shapes/Person"+ );+}++#[test]+fn a_run_that_matched_nothing_does_not_claim_conformance() {+ let r = report(&store_with_people(), SHAPES_WRONG_NAMESPACE);++ assert_eq!(+ r["conforms"],+ serde_json::Value::Null,+ "nothing was evaluated, so there is no conformance verdict to give"+ );+ assert_eq!(r["violation_count"], 0);+}++#[test]+fn an_ordinary_passing_run_still_conforms() {+ let r = report(&store_with_people(), SHAPES_RIGHT_NAMESPACE);++ assert_eq!(r["conforms"], serde_json::json!(true));+ assert_eq!(r["focus_nodes"], serde_json::json!(1));+ assert!(+ r["unmatched_shapes"].as_array().unwrap().is_empty(),+ "the shape matched a focus node, so nothing is unmatched"+ );+}++#[test]+fn a_partial_match_keeps_its_verdict_and_still_names_the_empty_shape() {+ let shapes = r#"+ @prefix sh: <http://www.w3.org/ns/shacl#> .+ @prefix ex: <http://example.org/> .+ ex:PersonShape a sh:NodeShape ;+ sh:targetClass ex:Person ;+ sh:property [ sh:path ex:fullName ; sh:minCount 1 ] .+ ex:GadgetShape a sh:NodeShape ;+ sh:targetClass ex:Gadget ;+ sh:property [ sh:path ex:serial ; sh:minCount 1 ] .+ "#;+ let r = report(&store_with_people(), shapes);++ assert_eq!(+ r["conforms"],+ serde_json::json!(true),+ "one shape did evaluate, so the verdict stands"+ );+ assert_eq!(r["focus_nodes"], serde_json::json!(1));+ let unmatched = r["unmatched_shapes"].as_array().unwrap();+ assert_eq!(unmatched.len(), 1);+ assert_eq!(unmatched[0]["target_class"], "http://example.org/Gadget");+}