Skip to content

Plan, apply and roll back changes to a production ontology, with a blast radius report and a proof an auditor can re-check.

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.rs
index 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.rs
index 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 shape
let 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.rs
new file mode 100644
index 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.rs
new file mode 100644
index 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");
+}