From 39ea93741fd79f2a52bd12d562861fdc6af2e3f6 Mon Sep 17 00:00:00 2001 From: Agent IX Date: Sun, 15 Nov 2026 23:58:30 -0800 Subject: [PATCH 1/4] PLAT-1756: add health-data-flows relation mode --- src/commands/relations.rs | 402 ++++++++++++++++++++++++++++ tests/cli_health_data_flows.rs | 460 +++++++++++++++++++++++++++++++++ 2 files changed, 862 insertions(+) create mode 100644 tests/cli_health_data_flows.rs diff --git a/src/commands/relations.rs b/src/commands/relations.rs index 70ec2db..3144dff 100644 --- a/src/commands/relations.rs +++ b/src/commands/relations.rs @@ -17,6 +17,8 @@ use quire_rs::{ design_join, relation_report, LinkedEntry, RelationReport, RelationReportMember, RelationRow, RowDocument, RowState, Verification, }; +use serde::Serialize; +use serde_json::Value; use super::corpus_input::{parse_repo, Corpus, RepoArg}; use super::Ctx; @@ -46,6 +48,15 @@ pub struct Args { #[arg(long, value_name = "NAME", conflicts_with = "design")] pub relation: Vec, + /// Emit the health-data-flow projection of the generic relation report. + #[arg(long)] + pub health_data_flows: bool, + + /// Reserved flow mode selector, used here to report an incompatible + /// combination with `--health-data-flows` (FR-046). + #[arg(long)] + pub flow: bool, + /// Render the design-element join (FR-041) instead of the relation /// selection: for each requirement the design elements that realize it, and /// a gap when there are none. Which relations are design relations is the @@ -66,6 +77,28 @@ pub struct Args { } pub fn run(ctx: &Ctx, args: Args) -> anyhow::Result<()> { + if args.health_data_flows { + let mut conflicting = Vec::new(); + if !args.relation.is_empty() { + conflicting.push("--relation"); + } + if args.design { + conflicting.push("--design"); + } + if args.flow { + conflicting.push("--flow"); + } + if !conflicting.is_empty() { + invalid_request!( + "--health-data-flows conflicts with {}", + conflicting.join(", ") + ); + } + } + if args.flow && !args.health_data_flows { + invalid_request!("--flow is not available in this quire build"); + } + let corpus = if args.repo.is_empty() { let raw = args.scope.as_deref().unwrap_or("."); let scope = safety::validate_dir_path("--scope", raw) @@ -130,6 +163,22 @@ pub fn run(ctx: &Ctx, args: Args) -> anyhow::Result<()> { } .map_err(|e| invalid_error!("{e}"))?; + if args.health_data_flows { + let projected = project_health_data_flows(&report, args.repo.is_empty())?; + if args.json { + primary_line!("{}", ix_cli_kit::json::encode(&projected, ctx.pretty)?); + } else { + primary!("{}", render_health_human(&projected)); + } + if args.strict && !projected.gaps.is_empty() { + partial_report!( + "{} health-data-flow gap(s) (--strict)", + projected.gaps.len() + ); + } + return Ok(()); + } + if args.json { primary_line!("{}", ix_cli_kit::json::encode(&report, ctx.pretty)?); } else { @@ -145,6 +194,359 @@ pub fn run(ctx: &Ctx, args: Args) -> anyhow::Result<()> { Ok(()) } +#[derive(Debug, Serialize)] +struct HealthOutput { + name: &'static str, + kind: &'static str, + description: &'static str, +} + +#[derive(Debug, Serialize)] +struct HealthReport { + schema: &'static str, + output: HealthOutput, + flows: Vec, + gaps: Vec, +} + +#[derive(Debug, Clone, Serialize)] +struct ModelDocument { + repo: Option, + id: String, + archetype: String, + path: String, +} + +#[derive(Debug, Clone, Serialize)] +struct DeclaredReference { + repo: Option, + id: String, + archetype: String, + declared_by: ModelDocument, +} + +#[derive(Debug, Clone, Serialize)] +struct HealthCrossing { + boundary: ModelDocument, + trust_level: String, +} + +#[derive(Debug, Clone, Serialize)] +struct HealthFlow { + connection: ModelDocument, + source: DeclaredReference, + destination: DeclaredReference, + classifications: Vec, + crossings: Vec, +} + +#[derive(Debug, Clone, Serialize)] +struct MissingReference { + field: &'static str, + reference: Option, +} + +#[derive(Debug, Clone, Serialize)] +struct HealthGap { + connection: ModelDocument, + missing: Vec, +} + +#[derive(Default)] +struct ConnectionFacts { + document: Option, + source: Option, + destination: Option, + endpoint_facts_seen: bool, + classifications: Vec, + crossings: Vec, + missing: Vec, + health_classified: bool, +} + +const HEALTH_OUTPUT: HealthOutput = HealthOutput { + name: "health-data-flows", + kind: "record", + description: "Health-data flow records; PLAT-1756 in the Data-Flow Model project owns the producer definition.", +}; + +/// Build the FR-046 view from the generic FR-084 relation report. No corpus +/// documents are read here; every input is a selected relation fact. +fn project_health_data_flows(report: &RelationReport, scope: bool) -> anyhow::Result { + let mut connections = + std::collections::BTreeMap::<(Option, String), ConnectionFacts>::new(); + + for section in &report.relations { + let relation_name = section.name.to_ascii_lowercase(); + let section_is_crossing = + relation_name.contains("trust") && relation_name.contains("boundary"); + for row in §ion.rows { + let key = (row.document.repo.clone(), row.document.id.clone()); + let facts = connections.entry(key).or_default(); + let connection = model_document(&row.document)?; + facts.document = Some(connection.clone()); + + if let Some(record) = row.document.record.as_ref() { + let source = endpoint(record.get("sourceEnd"), &connection, scope); + let destination = endpoint(record.get("targetEnd"), &connection, scope); + if source.is_some() + || destination.is_some() + || record.contains_key("sourceEnd") + || record.contains_key("targetEnd") + { + facts.endpoint_facts_seen = true; + facts.source = source; + facts.destination = destination; + } + } + + let mut has_boundary_link = false; + for entry in &row.linked { + let LinkedEntry::Resolved { document, .. } = entry else { + continue; + }; + if is_health_classification(document) { + facts.health_classified = true; + facts.classifications.push(model_document(document)?); + } + if let Some(trust_level) = document + .record + .as_ref() + .and_then(|record| record.get("trust_level")) + .and_then(Value::as_str) + { + has_boundary_link = true; + facts.crossings.push(HealthCrossing { + boundary: model_document(document)?, + trust_level: trust_level.to_owned(), + }); + } else if is_trust_boundary(document) { + has_boundary_link = true; + facts.missing.push(MissingReference { + field: "trust_level", + reference: Some(declared_document_reference(document, &connection)?), + }); + } + } + + if section_is_crossing || has_boundary_link { + for entry in &row.dangling { + let reference = parse_declared_reference( + &entry.reference, + &connection, + scope, + "TrustBoundary", + ); + facts.missing.push(MissingReference { + field: "crossing", + reference, + }); + } + } + } + } + + let mut flows = Vec::new(); + let mut gaps = Vec::new(); + for (_, mut facts) in connections { + if !facts.health_classified { + continue; + } + let connection = facts + .document + .take() + .ok_or_else(|| anyhow::anyhow!("health flow has no connection document"))?; + if !facts.endpoint_facts_seen || facts.source.is_none() { + facts.missing.push(MissingReference { + field: "source", + reference: None, + }); + } + if !facts.endpoint_facts_seen || facts.destination.is_none() { + facts.missing.push(MissingReference { + field: "destination", + reference: None, + }); + } + sort_dedup_documents(&mut facts.classifications); + sort_dedup_crossings(&mut facts.crossings); + sort_missing(&mut facts.missing); + facts.missing.dedup_by(|left, right| { + left.field == right.field + && left.reference.as_ref().map(|r| (&r.repo, &r.id)) + == right.reference.as_ref().map(|r| (&r.repo, &r.id)) + }); + + if facts.missing.is_empty() { + if let (Some(source), Some(destination)) = (facts.source, facts.destination) { + flows.push(HealthFlow { + connection, + source, + destination, + classifications: facts.classifications, + crossings: facts.crossings, + }); + } + } else { + gaps.push(HealthGap { + connection, + missing: facts.missing, + }); + } + } + + flows.sort_by(|left, right| { + document_key(&left.connection).cmp(&document_key(&right.connection)) + }); + gaps.sort_by(|left, right| { + document_key(&left.connection).cmp(&document_key(&right.connection)) + }); + Ok(HealthReport { + schema: "quire.health-data-flows/v1", + output: HEALTH_OUTPUT, + flows, + gaps, + }) +} + +fn model_document(document: &RowDocument) -> anyhow::Result { + let archetype = document.archetype.clone().ok_or_else(|| { + anyhow::anyhow!( + "relation report document '{}' has no archetype", + document.id + ) + })?; + Ok(ModelDocument { + repo: document.repo.clone(), + id: document.id.clone(), + archetype, + path: document.path.clone(), + }) +} + +fn endpoint( + value: Option<&Value>, + connection: &ModelDocument, + scope: bool, +) -> Option { + let id = value?.get("type")?.as_str()?; + parse_declared_reference(id, connection, scope, "port") +} + +fn parse_declared_reference( + target: &str, + declared_by: &ModelDocument, + scope: bool, + archetype: &str, +) -> Option { + let (id, target_repo) = if let Some(uri) = target.strip_prefix("ix://") { + let parts: Vec<&str> = uri.split('/').collect(); + if parts.len() < 2 { + return None; + } + let id = *parts.last()?; + let repo = (parts.len() >= 3).then(|| format!("{}/{}", parts[0], parts[1])); + (id, repo) + } else { + (target, declared_by.repo.clone()) + }; + if id.is_empty() { + return None; + } + Some(DeclaredReference { + repo: if scope { None } else { target_repo }, + id: id.to_owned(), + archetype: archetype.to_owned(), + declared_by: declared_by.clone(), + }) +} + +fn declared_document_reference( + document: &RowDocument, + declared_by: &ModelDocument, +) -> anyhow::Result { + Ok(DeclaredReference { + repo: document.repo.clone(), + id: document.id.clone(), + archetype: document + .archetype + .clone() + .ok_or_else(|| anyhow::anyhow!("boundary '{}' has no archetype", document.id))?, + declared_by: declared_by.clone(), + }) +} + +fn is_health_classification(document: &RowDocument) -> bool { + document + .record + .as_ref() + .and_then(|record| record.get("regulatedCategories")) + .and_then(Value::as_array) + .is_some_and(|categories| { + categories + .iter() + .any(|category| category.as_str() == Some("health")) + }) +} + +fn is_trust_boundary(document: &RowDocument) -> bool { + document.archetype.as_deref().is_some_and(|archetype| { + let lower = archetype.to_ascii_lowercase(); + lower.contains("trust") && lower.contains("boundary") + }) +} + +fn document_key(document: &ModelDocument) -> (Option<&str>, &str) { + (document.repo.as_deref(), &document.id) +} + +fn sort_dedup_documents(documents: &mut Vec) { + documents.sort_by(|left, right| document_key(left).cmp(&document_key(right))); + documents.dedup_by(|left, right| document_key(left) == document_key(right)); +} + +fn sort_dedup_crossings(crossings: &mut Vec) { + crossings + .sort_by(|left, right| document_key(&left.boundary).cmp(&document_key(&right.boundary))); + crossings.dedup_by(|left, right| document_key(&left.boundary) == document_key(&right.boundary)); +} + +fn sort_missing(missing: &mut [MissingReference]) { + missing.sort_by(|left, right| { + let left_key = left + .reference + .as_ref() + .map(|reference| (reference.repo.as_deref(), reference.id.as_str())); + let right_key = right + .reference + .as_ref() + .map(|reference| (reference.repo.as_deref(), reference.id.as_str())); + left.field + .cmp(right.field) + .then_with(|| left_key.cmp(&right_key)) + }); +} + +fn render_health_human(report: &HealthReport) -> String { + let mut out = String::new(); + for flow in &report.flows { + out.push_str(&format!( + "{}: {} -> {}\n", + flow.connection.id, flow.source.id, flow.destination.id + )); + } + for gap in &report.gaps { + let fields = gap + .missing + .iter() + .map(|missing| missing.field) + .collect::>() + .join(", "); + out.push_str(&format!("{}: missing {fields}\n", gap.connection.id)); + } + out +} + /// Why `--strict` fails this report, one entry per distinct cause. fn strict_problems(report: &RelationReport) -> Vec { let rows: Vec<&RelationRow> = report.relations.iter().flat_map(|s| &s.rows).collect(); diff --git a/tests/cli_health_data_flows.rs b/tests/cli_health_data_flows.rs new file mode 100644 index 0000000..1146de5 --- /dev/null +++ b/tests/cli_health_data_flows.rs @@ -0,0 +1,460 @@ +//! FR-046 — health-data-flow reports project only selected FR-084 facts. +mod common; + +use std::fs; +use std::path::Path; +use std::process::Output; + +use ix_trace_rs::trace; +use serde_json::{json, Value}; +use tempfile::TempDir; + +const MANIFEST: &str = "\ +name: health-flow-fixture +manifest_version: 1.0.0 +version: 0.1.0 +artifact_types: +- name: Connection + data_schema: + schema: schemas/Connection.json +- name: Classification + data_schema: + schema: schemas/Classification.json +- name: TrustBoundary + data_schema: + schema: schemas/TrustBoundary.json +semantic: + contract_version: 1.0.0 + package: agent-ix/health-flow-fixture + exports: [Connection, Classification, TrustBoundary] + targets: [json-schema, markdown] +traceability: + required_relations: + - name: connection-carries-classification + from: Connection + edges: [classified-as] + to: [Classification] + direction: outgoing + check: connection-unclassified + record_keys: [sourceEnd, targetEnd, regulatedCategories] + - name: connection-crosses-trust-boundary + from: Connection + edges: [crosses] + to: [TrustBoundary] + direction: outgoing + check: connection-crossing-unknown + record_keys: [trust_level] +"; + +const CONNECTION_SCHEMA: &str = r#"{ + "$schema":"https://json-schema.org/draft/2020-12/schema", + "type":"object", + "properties":{ + "sourceEnd":{"type":"object","properties":{"type":{"type":"string"}}}, + "targetEnd":{"type":"object","properties":{"type":{"type":"string"}}} + }, + "additionalProperties":false +}"#; + +const CLASSIFICATION_SCHEMA: &str = r#"{ + "$schema":"https://json-schema.org/draft/2020-12/schema", + "type":"object", + "properties":{"regulatedCategories":{"type":"array","items":{"type":"string"}}}, + "additionalProperties":false +}"#; + +const BOUNDARY_SCHEMA: &str = r#"{ + "$schema":"https://json-schema.org/draft/2020-12/schema", + "type":"object", + "properties":{"trust_level":{"type":"string"}}, + "additionalProperties":false +}"#; + +fn write(root: &Path, relative: &str, contents: &str) { + let path = root.join(relative); + fs::create_dir_all(path.parent().expect("fixture path has parent")).unwrap(); + fs::write(path, contents).unwrap(); +} + +fn document(id: &str, archetype: &str, record: &str, relationships: &[(&str, &str)]) -> String { + let rels = relationships + .iter() + .map(|(verb, target)| format!(" - target: \"{target}\"\n type: \"{verb}\"\n")) + .collect::(); + let rels = if rels.is_empty() { + String::new() + } else { + format!("relationships:\n{rels}") + }; + format!("---\nid: {id}\ntype: {archetype}\ntitle: {id}\n{record}{rels}---\n\n# {id}\n") +} + +fn world( + connection_record: &str, + category: &str, + boundary_record: Option<&str>, + crossing: bool, +) -> (TempDir, std::path::PathBuf) { + let temp = TempDir::new().unwrap(); + let module = temp.path().join("module"); + write(&module, "manifest.yaml", MANIFEST); + write(&module, "schemas/Connection.json", CONNECTION_SCHEMA); + write( + &module, + "schemas/Classification.json", + CLASSIFICATION_SCHEMA, + ); + write(&module, "schemas/TrustBoundary.json", BOUNDARY_SCHEMA); + + let scope = temp.path().join("repo"); + write( + &scope, + "spec/CONN-1.md", + &document( + "CONN-1", + "Connection", + connection_record, + &if crossing { + vec![("classified-as", "CLS-1"), ("crosses", "BOUNDARY-1")] + } else { + vec![("classified-as", "CLS-1")] + }, + ), + ); + write( + &scope, + "spec/CLS-1.md", + &document( + "CLS-1", + "Classification", + &format!("regulatedCategories: [{category}]\n"), + &[], + ), + ); + if let Some(record) = boundary_record { + write( + &scope, + "spec/BOUNDARY-1.md", + &document("BOUNDARY-1", "TrustBoundary", record, &[]), + ); + } + (temp, scope) +} + +fn run(scope: &Path, module: &Path, extra: &[&str]) -> Output { + let mut command = common::quire(); + command + .args(["relations", "--scope"]) + .arg(scope) + .arg("--module") + .arg(module) + .args(extra); + command.output().unwrap() +} + +fn run_repos(repos: &[(&str, &Path)], module: &Path, extra: &[&str]) -> Output { + let mut command = common::quire(); + command.arg("relations"); + for (identity, root) in repos { + command + .arg("--repo") + .arg(format!("{identity}={}", root.display())); + } + command.arg("--module").arg(module).args(extra); + command.output().unwrap() +} + +fn json(output: &Output) -> Value { + serde_json::from_slice(&output.stdout).unwrap_or_else(|error| { + panic!( + "stdout was not JSON ({error}): {}", + String::from_utf8_lossy(&output.stdout) + ) + }) +} + +#[test] +#[trace("FR-046-AC-1", "FR-046-AC-2", "FR-046-AC-5", "FR-046-AC-6")] +fn emits_the_canonical_health_flow_envelope_from_generic_relation_facts() { + let (temp, scope) = world( + "sourceEnd:\n type: ix://agent-ix/health-flow-fixture/PORT-SOURCE\ntargetEnd:\n type: ix://agent-ix/health-flow-fixture/PORT-TARGET\n", + "health", + Some("trust_level: untrusted\n"), + true, + ); + let output = run( + &scope, + &temp.path().join("module"), + &["--health-data-flows", "--json"], + ); + assert!( + output.status.success(), + "{}", + String::from_utf8_lossy(&output.stderr) + ); + let report = json(&output); + assert_eq!(report["schema"], "quire.health-data-flows/v1"); + assert_eq!( + report["output"], + json!({ + "name":"health-data-flows", + "kind":"record", + "description":"Health-data flow records; PLAT-1756 in the Data-Flow Model project owns the producer definition." + }) + ); + assert_eq!(report["flows"].as_array().unwrap().len(), 1); + assert!(report["gaps"].as_array().unwrap().is_empty()); + assert_eq!(report["flows"][0]["connection"]["id"], "CONN-1"); + assert_eq!(report["flows"][0]["source"]["id"], "PORT-SOURCE"); + assert_eq!(report["flows"][0]["destination"]["id"], "PORT-TARGET"); + assert_eq!(report["flows"][0]["source"]["repo"], Value::Null); + assert_eq!( + report["flows"][0]["source"]["declared_by"]["path"], + "spec/CONN-1.md" + ); + assert_eq!(report["flows"][0]["classifications"][0]["id"], "CLS-1"); + assert_eq!( + report["flows"][0]["crossings"][0]["boundary"]["id"], + "BOUNDARY-1" + ); + assert_eq!( + report["flows"][0]["crossings"][0]["trust_level"], + "untrusted" + ); + let encoded = String::from_utf8_lossy(&output.stdout); + let top_level = ["\"schema\"", "\"output\"", "\"flows\"", "\"gaps\""]; + let top_positions: Vec = top_level + .iter() + .map(|key| encoded.find(key).expect("field is serialized")) + .collect(); + assert!(top_positions.windows(2).all(|pair| pair[0] < pair[1])); + let flow_fields = [ + "\"connection\"", + "\"source\"", + "\"destination\"", + "\"classifications\"", + "\"crossings\"", + ]; + let flow_positions: Vec = flow_fields + .iter() + .map(|key| encoded.find(key).expect("flow field is serialized")) + .collect(); + assert!(flow_positions.windows(2).all(|pair| pair[0] < pair[1])); + let second = run( + &scope, + &temp.path().join("module"), + &["--health-data-flows", "--json", "--strict"], + ); + assert!(second.status.success()); + assert_eq!(output.stdout, second.stdout); +} + +#[test] +#[trace("FR-046-AC-5")] +fn multi_repo_references_keep_their_declared_member_identity() { + let temp = TempDir::new().unwrap(); + let module = temp.path().join("module"); + write(&module, "manifest.yaml", MANIFEST); + write(&module, "schemas/Connection.json", CONNECTION_SCHEMA); + write( + &module, + "schemas/Classification.json", + CLASSIFICATION_SCHEMA, + ); + write(&module, "schemas/TrustBoundary.json", BOUNDARY_SCHEMA); + let source = temp.path().join("source"); + let target = temp.path().join("target"); + write( + &source, + "spec/CONN-1.md", + &document( + "CONN-1", + "Connection", + "sourceEnd:\n type: ix://org/target/PORT-SOURCE\ntargetEnd:\n type: ix://org/target/PORT-TARGET\n", + &[ + ("classified-as", "ix://org/target/spec/CLS-1"), + ("crosses", "ix://org/target/spec/BOUNDARY-1"), + ], + ), + ); + write( + &target, + "spec/CLS-1.md", + &document( + "CLS-1", + "Classification", + "regulatedCategories: [health]\n", + &[], + ), + ); + write( + &target, + "spec/BOUNDARY-1.md", + &document( + "BOUNDARY-1", + "TrustBoundary", + "trust_level: untrusted\n", + &[], + ), + ); + let output = run_repos( + &[("org/source", &source), ("org/target", &target)], + &module, + &["--health-data-flows", "--json"], + ); + assert!( + output.status.success(), + "{}", + String::from_utf8_lossy(&output.stderr) + ); + let report = json(&output); + assert_eq!( + report["flows"][0]["connection"]["repo"], "org/source", + "{report}" + ); + assert_eq!(report["flows"][0]["source"]["repo"], "org/target"); + assert_eq!(report["flows"][0]["destination"]["repo"], "org/target"); + assert_eq!( + report["flows"][0]["classifications"][0]["repo"], + "org/target" + ); + assert_eq!( + report["flows"][0]["crossings"][0]["boundary"]["repo"], + "org/target" + ); +} + +#[test] +#[trace("FR-046-AC-3")] +fn reports_missing_endpoint_dangling_crossing_and_missing_trust_level() { + let (temp, scope) = world( + "targetEnd:\n type: ix://agent-ix/health-flow-fixture/PORT-TARGET\n", + "health", + None, + true, + ); + let output = run( + &scope, + &temp.path().join("module"), + &["--health-data-flows", "--json"], + ); + assert!( + output.status.success(), + "{}", + String::from_utf8_lossy(&output.stderr) + ); + let report = json(&output); + assert!(report["flows"].as_array().unwrap().is_empty()); + let missing = report["gaps"][0]["missing"].as_array().unwrap(); + assert!(missing + .iter() + .any(|item| item["field"] == "source" && item["reference"].is_null())); + assert!(missing + .iter() + .any(|item| item["field"] == "crossing" && item["reference"]["id"] == "BOUNDARY-1")); + + let (temp, scope) = world( + "sourceEnd:\n type: ix://agent-ix/health-flow-fixture/PORT-SOURCE\ntargetEnd:\n type: ix://agent-ix/health-flow-fixture/PORT-TARGET\n", + "health", + Some(""), + true, + ); + let output = run( + &scope, + &temp.path().join("module"), + &["--health-data-flows", "--json"], + ); + let report = json(&output); + assert!(report["gaps"][0]["missing"] + .as_array() + .unwrap() + .iter() + .any(|item| item["field"] == "trust_level")); +} + +#[test] +#[trace("FR-046-AC-4", "FR-046-AC-7")] +fn ignores_non_health_classifications_and_accepts_no_crossing() { + let (temp, scope) = world( + "sourceEnd:\n type: ix://agent-ix/health-flow-fixture/PORT-SOURCE\ntargetEnd:\n type: ix://agent-ix/health-flow-fixture/PORT-TARGET\n", + "financial", + None, + false, + ); + let output = run( + &scope, + &temp.path().join("module"), + &["--health-data-flows", "--json"], + ); + assert!( + output.status.success(), + "{}", + String::from_utf8_lossy(&output.stderr) + ); + let report = json(&output); + assert!(report["flows"].as_array().unwrap().is_empty()); + assert!(report["gaps"].as_array().unwrap().is_empty()); + + let (temp, scope) = world( + "sourceEnd:\n type: ix://agent-ix/health-flow-fixture/PORT-SOURCE\ntargetEnd:\n type: ix://agent-ix/health-flow-fixture/PORT-TARGET\n", + "health", + None, + false, + ); + let output = run( + &scope, + &temp.path().join("module"), + &["--health-data-flows", "--json"], + ); + assert!(output.status.success()); + let report = json(&output); + assert_eq!(report["flows"].as_array().unwrap().len(), 1); + assert!(report["flows"][0]["crossings"] + .as_array() + .unwrap() + .is_empty()); + assert!(report["gaps"].as_array().unwrap().is_empty()); +} + +#[test] +#[trace("FR-046-AC-8")] +fn strict_fails_only_after_emitting_a_complete_gapped_report() { + let (temp, scope) = world("", "health", None, false); + let output = run( + &scope, + &temp.path().join("module"), + &["--health-data-flows", "--strict", "--json"], + ); + assert_eq!(output.status.code(), Some(1)); + let report = json(&output); + assert_eq!(report["gaps"].as_array().unwrap().len(), 1); +} + +#[test] +#[trace("FR-046-AC-9")] +fn health_mode_conflicts_exit_three_without_a_report() { + let (temp, scope) = world("", "health", None, false); + for (mode, flag) in [ + ("--relation", "some-relation"), + ("--design", ""), + ("--flow", ""), + ] { + let mut args = vec!["--health-data-flows", "--json", mode]; + if !flag.is_empty() { + args.push(flag); + } + let output = run(&scope, &temp.path().join("module"), &args); + assert_eq!( + output.status.code(), + Some(3), + "mode {mode}: {}", + String::from_utf8_lossy(&output.stderr) + ); + assert!(output.stdout.is_empty(), "mode {mode} wrote a report"); + let stderr = String::from_utf8_lossy(&output.stderr); + assert!( + stderr.contains(mode) && stderr.contains("--health-data-flows"), + "{stderr}" + ); + } +} From 89cd7594e6accae571b8209f10bfe0f9525637b1 Mon Sep 17 00:00:00 2001 From: Agent IX Date: Mon, 16 Nov 2026 01:05:30 -0800 Subject: [PATCH 2/4] PLAT-1756: handle unavailable connection records --- reviews/plat-1756-code-review.md | 49 +++ reviews/plat-1756-gap-analysis.md | 55 +++ .../FR-046-health-data-flows-subcommand.md | 10 +- src/commands/relations.rs | 28 +- tests/cli_health_data_flows.rs | 379 ++++++++++++++++++ 5 files changed, 509 insertions(+), 12 deletions(-) create mode 100644 reviews/plat-1756-code-review.md create mode 100644 reviews/plat-1756-gap-analysis.md diff --git a/reviews/plat-1756-code-review.md b/reviews/plat-1756-code-review.md new file mode 100644 index 0000000..2649348 --- /dev/null +++ b/reviews/plat-1756-code-review.md @@ -0,0 +1,49 @@ +--- +id: SR-20261116045009 +title: code-review review — PLAT-1756 quire-cli +type: SpecReview +analysis: code-review +scope: agent-ix/quire-cli; src/commands/relations.rs; tests/cli_health_data_flows.rs; + FR-046; context ix://agent-ix/quire-rs/spec/functional/FR-084 and ix://agent-ix/spec-objects-architecture/spec/functional/FR-007 +review_set: subset +--- + +## Summary + +Reviewed the Rust CLI projection against merged FR-046 and the generic quire-rs FR-084 record contract. One concrete failure remains for a partially missing required connection endpoint because FR-084 suppresses the whole invalid record. + +## Verdict + +**FAIL** — a medium-severity projection defect remains. + +## Scope + +- Examined: FR-046-AC-1 through FR-046-AC-10; changed relation projection and CLI integration tests. +- Context only: quire-rs FR-084 record omission contract and architecture FR-007 required connection endpoints. +- Ticket: PLAT-1756; PR #212; reviewed published head `39ea93741fd79f2a52bd12d562861fdc6af2e3f6`. +- Applicable AssuranceProfile: none found in `spec/`. + +## Findings + +| ID | Severity | Summary | Refs | +| --- | --- | --- | --- | +| FND-001 | medium | When a real connection has only `targetEnd` authored, FR-084 omits the entire selected record because the Connection schema requires both endpoints; this projection then emits both `source` and `destination` as missing with null references. The test fixture makes both endpoint properties optional, so it misses the false gap for the authored destination. | src/commands/relations.rs:289-300,359-369 | + +## Evidence + +FR-084 says `record` is omitted when record validation fails. The architecture Connection schema requires both `sourceEnd` and `targetEnd` (and `flowDirection`). I reproduced this with only `targetEnd` authored: generic `quire relations --json` omitted the connection record, and `--health-data-flows --json` returned missing `destination` and `source`, both with null references. The new fixture Connection schema at `tests/cli_health_data_flows.rs:49-57` omits a `required` array, so it accepts partial records and cannot reveal this behavior. Source code uses only FR-084 report fields and does not read corpus documents; the other inspected projection paths match FR-046 shape and selection. Gates: fmt-check, all-target/all-feature Clippy, workspace tests, rustdoc, dist-test, deny, audit-unsafe, audit-thin-boundary, and spec traceability passed. The initial `make ci` stopped at cargo-deny because the default advisory lock is in a read-only path; deny and later gates passed using a task-owned writable Cargo home. `cargo audit` passed with one repository-allowed `RUSTSEC-2026-0486` warning for rustix 1.1.4. + +## Examined Units + +- `FR-046-AC-1` (examined): `quire relations --scope --module $M --health-data-flows --json` over a fixture module with `required_relations` for connection-to-classification and connection-to-trust-boundary facts, and `record_keys` selecting `sourceEnd`, `targetEnd`, `regulatedCategories`, and `trust_level`, emits a complete JSON envelope. The fixture model has one health-classified connection with source and destination record values and one declared boundary crossing. +- `FR-046-AC-2` (examined): The AC-1 envelope's `schema`, `output`, `flows`, `gaps`, `ModelDocument`, `DeclaredReference`, flow, crossing, and gap keys have the exact names, order, types, nullability, and closed shapes specified in this requirement; each reference carries repository identity and a source artifact path or `declared_by` document. +- `FR-046-AC-3` (examined): A health-classified connection with a missing source value, missing destination value, dangling crossing, or boundary without `trust_level` emits a gap naming the connection and missing reference, emits no complete entry for that connection, and substitutes no identifier or value. A connection with no declared crossing emits no boundary gap. +- `FR-046-AC-4` (examined): A connection carrying a declared category other than `health` is absent from the complete flow entries and gaps, even when another category is regulated. +- `FR-046-AC-5` (examined): Two runs over the same corpus produce byte-identical JSON. With multiple repositories, references retain each `--repo` identity and records, crossings, and gaps follow the specified order. +- `FR-046-AC-6` (examined): The emitted metadata's name, kind, and description exactly match the `health-data-flows` row in US pack FR-005, and the pack's catalog test accepts those values. +- `FR-046-AC-7` (examined): A module set with the required `required_relations` and record keys but no `flow_rules` can produce a record; a corpus with no health-classified connections succeeds with empty `flows` and `gaps`. +- `FR-046-AC-8` (examined): With gaps, default mode emits the full report and exits 0; with `--strict`, it emits the full report and exits 1. With no gaps, both modes emit the full report and exit 0, regardless of generic relation verification status or flow-report denials. +- `FR-046-AC-9` (examined): A request combining `--health-data-flows` with `--relation`, `--design`, or `--flow` exits 3, names the conflicting modes, and writes no report to stdout; requests in existing relations modes retain their prior outputs. +- `FR-046-AC-10` (examined): The CLI derives health selection and record structure only from the generic FR-084 relation report's `document`, `linked`, `dangling`, and selected `record` values; it reads no source files and does not alter the report used by `--flow`. +- `FR-084` (context_only): the generic relation report omits `record` when record validation fails. +- `FR-007` (context_only): a connection requires `sourceEnd`, `targetEnd`, and `flowDirection`. diff --git a/reviews/plat-1756-gap-analysis.md b/reviews/plat-1756-gap-analysis.md new file mode 100644 index 0000000..f127833 --- /dev/null +++ b/reviews/plat-1756-gap-analysis.md @@ -0,0 +1,55 @@ +--- +id: SR-20261116045010 +title: gap-analysis review — PLAT-1756 quire-cli +type: SpecReview +analysis: gap-analysis +scope: agent-ix/quire-cli; spec/functional/FR-046-health-data-flows-subcommand.md; + src/commands/relations.rs; tests/cli_health_data_flows.rs; context ix://agent-ix/quire-rs/spec/functional/FR-084 + and ix://agent-ix/spec-objects-architecture/spec/functional/FR-007 +review_set: subset +--- + +## Summary + +The computed matrix binds tests to FR-046 AC-1 through AC-9 and treats AC-10 as inspection-only. Review of the tagged tests found incomplete evidence for the exact nested wire-shape and ordering requirements. Plan completion was not assessed; optional semantic review was not requested. + +## Verdict + +**CONDITIONAL** — two medium evidence gaps remain. + +## Scope + +- Examined: FR-046-AC-1 through FR-046-AC-10; changed relation projection and CLI integration tests. +- Context only: quire-rs FR-084 record omission contract and architecture FR-007 required connection endpoints. +- Ticket: PLAT-1756; PR #212; reviewed published head `39ea93741fd79f2a52bd12d562861fdc6af2e3f6`. +- Applicable AssuranceProfile: none found in `spec/`. + +## Findings + +| ID | Severity | Summary | Refs | +| --- | --- | --- | --- | +| FND-001 | medium | The test checks the top-level schema value, exact output object, selected flow values, and key order for the envelope and flow. It does not assert exact key sets, order, types, or nullability for ModelDocument, DeclaredReference, crossings, gaps, and missing-reference objects, so those closed-shape requirements can regress without this AC test failing. | tests/cli_health_data_flows.rs:195-242 | +| FND-002 | medium | The determinism test emits one flow and one crossing, and the multi-repository test emits one flow with one reference of each kind. Those cases cannot fail when array sorting is removed or reversed, so the specified ordering across multiple flows, classifications, crossings, gaps, and missing references is not verified. | tests/cli_health_data_flows.rs:176-250,252-303 | + +## Evidence + +`quoin matrix --repo . --json` reports test binders for AC-1 through AC-9 and `method-without-symbol` for inspection-only AC-10. `quire matrix --scope . --format json` reports the same test bindings. The coverage gaps below are narrower than the marker coverage: the tests do not assert the full nested shape for AC-2 or exercise multiple values to verify AC-5 ordering. Reverse-gap and stub scan found no other unowned behavior or stubs. The full workspace tests, formatter, Clippy, rustdoc, and dist-test passed; remaining make-ci gates (deny, unsafe comments, thin boundary, and spec traceability) passed when rerun with a writable task-local Cargo home where needed. + +## Examined Units + +- `FR-046-AC-1` (examined): `quire relations --scope --module $M --health-data-flows --json` over a fixture module with `required_relations` for connection-to-classification and connection-to-trust-boundary facts, and `record_keys` selecting `sourceEnd`, `targetEnd`, `regulatedCategories`, and `trust_level`, emits a complete JSON envelope. The fixture model has one health-classified connection with source and destination record values and one declared boundary crossing. +- `FR-046-AC-2` (examined): The AC-1 envelope's `schema`, `output`, `flows`, `gaps`, `ModelDocument`, `DeclaredReference`, flow, crossing, and gap keys have the exact names, order, types, nullability, and closed shapes specified in this requirement; each reference carries repository identity and a source artifact path or `declared_by` document. +- `FR-046-AC-3` (examined): A health-classified connection with a missing source value, missing destination value, dangling crossing, or boundary without `trust_level` emits a gap naming the connection and missing reference, emits no complete entry for that connection, and substitutes no identifier or value. A connection with no declared crossing emits no boundary gap. +- `FR-046-AC-4` (examined): A connection carrying a declared category other than `health` is absent from the complete flow entries and gaps, even when another category is regulated. +- `FR-046-AC-5` (examined): Two runs over the same corpus produce byte-identical JSON. With multiple repositories, references retain each `--repo` identity and records, crossings, and gaps follow the specified order. +- `FR-046-AC-6` (examined): The emitted metadata's name, kind, and description exactly match the `health-data-flows` row in US pack FR-005, and the pack's catalog test accepts those values. +- `FR-046-AC-7` (examined): A module set with the required `required_relations` and record keys but no `flow_rules` can produce a record; a corpus with no health-classified connections succeeds with empty `flows` and `gaps`. +- `FR-046-AC-8` (examined): With gaps, default mode emits the full report and exits 0; with `--strict`, it emits the full report and exits 1. With no gaps, both modes emit the full report and exit 0, regardless of generic relation verification status or flow-report denials. +- `FR-046-AC-9` (examined): A request combining `--health-data-flows` with `--relation`, `--design`, or `--flow` exits 3, names the conflicting modes, and writes no report to stdout; requests in existing relations modes retain their prior outputs. +- `FR-046-AC-10` (examined): The CLI derives health selection and record structure only from the generic FR-084 relation report's `document`, `linked`, `dangling`, and selected `record` values; it reads no source files and does not alter the report used by `--flow`. +- `FR-084` (context_only): the generic relation report omits `record` when record validation fails. +- `FR-007` (context_only): a connection requires `sourceEnd`, `targetEnd`, and `flowDirection`. + +## Coverage + +The matrix and tests were inspected for all ten criteria. `Plan completion: not assessed`. Semantic review was skipped because it was not requested. diff --git a/spec/functional/FR-046-health-data-flows-subcommand.md b/spec/functional/FR-046-health-data-flows-subcommand.md index ddc4b75..0a7e5e0 100644 --- a/spec/functional/FR-046-health-data-flows-subcommand.md +++ b/spec/functional/FR-046-health-data-flows-subcommand.md @@ -73,9 +73,11 @@ model facts. The CLI does not determine whether a flow is legally permissible. - The `connection` field in a gap SHALL be a `ModelDocument`. - The `missing` field in a gap SHALL be a non-empty array. - Each missing-reference item SHALL have exactly `field` followed by `reference`. -- The `field` value in a missing-reference item SHALL be a string equal to one of `source`, `destination`, `crossing`, or `trust_level`. -- The `reference` value in a missing-reference item SHALL be a `DeclaredReference` or `null` when the corresponding reference identifier is absent. -- The CLI SHALL emit a gap for a health-classified connection when an endpoint record value is absent, an explicitly declared crossing is dangling, or a resolved boundary lacks `trust_level`. +- The `field` value in a missing-reference item SHALL be a string equal to one of `connection_record`, `source`, `destination`, `crossing`, or `trust_level`. +- The `reference` value in a missing-reference item SHALL be a `DeclaredReference` or `null` when the corresponding reference identifier is absent or the selected connection record is unavailable. +- When FR-084 omits a health-classified connection's selected record, the CLI SHALL emit a missing-reference item with `field` equal to `connection_record` and `reference` equal to `null`. +- When FR-084 omits a health-classified connection's selected record, the CLI SHALL NOT report either endpoint as missing because the report does not establish which endpoint value is absent. +- When the selected connection record is present, the CLI SHALL emit a gap for a missing endpoint record value, an explicitly declared dangling crossing, or a resolved boundary that lacks `trust_level`. - A connection with no declared crossing SHALL have no crossing entry. - A connection with no declared crossing SHALL NOT be treated as a missing boundary. - The CLI SHALL NOT emit a complete flow entry for a connection with any missing endpoint or boundary fact. @@ -116,7 +118,7 @@ model facts. The CLI does not determine whether a flow is legally permissible. |----|----------|--------------| | FR-046-AC-1 | `quire relations --scope --module $M --health-data-flows --json` over a fixture module with `required_relations` for connection-to-classification and connection-to-trust-boundary facts, and `record_keys` selecting `sourceEnd`, `targetEnd`, `regulatedCategories`, and `trust_level`, emits a complete JSON envelope. The fixture model has one health-classified connection with source and destination record values and one declared boundary crossing. | Test | | FR-046-AC-2 | The AC-1 envelope's `schema`, `output`, `flows`, `gaps`, `ModelDocument`, `DeclaredReference`, flow, crossing, and gap keys have the exact names, order, types, nullability, and closed shapes specified in this requirement; each reference carries repository identity and a source artifact path or `declared_by` document. | Test | -| FR-046-AC-3 | A health-classified connection with a missing source value, missing destination value, dangling crossing, or boundary without `trust_level` emits a gap naming the connection and missing reference, emits no complete entry for that connection, and substitutes no identifier or value. A connection with no declared crossing emits no boundary gap. | Test | +| FR-046-AC-3 | A health-classified connection whose selected FR-084 record is omitted emits a `connection_record` missing item with a null reference, without claiming either endpoint is missing; independently observed crossing gaps remain present. If no other missing facts exist, that gap has exactly one missing item. When the selected record is present but only one endpoint value is missing, the gap names only that endpoint; a dangling crossing or boundary without `trust_level` names its missing reference. Each case emits no complete entry and substitutes no identifier or value. A connection with no declared crossing emits no boundary gap. | Test | | FR-046-AC-4 | A connection carrying a declared category other than `health` is absent from the complete flow entries and gaps, even when another category is regulated. | Test | | FR-046-AC-5 | Two runs over the same corpus produce byte-identical JSON. With multiple repositories, references retain each `--repo` identity and records, crossings, and gaps follow the specified order. | Test | | FR-046-AC-6 | The emitted metadata's name, kind, and description exactly match the `health-data-flows` row in US pack FR-005, and the pack's catalog test accepts those values. | Test | diff --git a/src/commands/relations.rs b/src/commands/relations.rs index 3144dff..d853347 100644 --- a/src/commands/relations.rs +++ b/src/commands/relations.rs @@ -258,6 +258,7 @@ struct ConnectionFacts { source: Option, destination: Option, endpoint_facts_seen: bool, + connection_record_unavailable: bool, classifications: Vec, crossings: Vec, missing: Vec, @@ -307,6 +308,7 @@ fn project_health_data_flows(report: &RelationReport, scope: bool) -> anyhow::Re }; if is_health_classification(document) { facts.health_classified = true; + facts.connection_record_unavailable |= row.document.record.is_none(); facts.classifications.push(model_document(document)?); } if let Some(trust_level) = document @@ -356,17 +358,27 @@ fn project_health_data_flows(report: &RelationReport, scope: bool) -> anyhow::Re .document .take() .ok_or_else(|| anyhow::anyhow!("health flow has no connection document"))?; - if !facts.endpoint_facts_seen || facts.source.is_none() { + if facts.connection_record_unavailable { + facts + .missing + .retain(|missing| !matches!(missing.field, "source" | "destination")); facts.missing.push(MissingReference { - field: "source", - reference: None, - }); - } - if !facts.endpoint_facts_seen || facts.destination.is_none() { - facts.missing.push(MissingReference { - field: "destination", + field: "connection_record", reference: None, }); + } else { + if !facts.endpoint_facts_seen || facts.source.is_none() { + facts.missing.push(MissingReference { + field: "source", + reference: None, + }); + } + if !facts.endpoint_facts_seen || facts.destination.is_none() { + facts.missing.push(MissingReference { + field: "destination", + reference: None, + }); + } } sort_dedup_documents(&mut facts.classifications); sort_dedup_crossings(&mut facts.crossings); diff --git a/tests/cli_health_data_flows.rs b/tests/cli_health_data_flows.rs index 1146de5..2463117 100644 --- a/tests/cli_health_data_flows.rs +++ b/tests/cli_health_data_flows.rs @@ -56,6 +56,18 @@ const CONNECTION_SCHEMA: &str = r#"{ "additionalProperties":false }"#; +const REQUIRED_CONNECTION_SCHEMA: &str = r#"{ + "$schema":"https://json-schema.org/draft/2020-12/schema", + "type":"object", + "properties":{ + "sourceEnd":{"type":"object","properties":{"type":{"type":"string"}}}, + "targetEnd":{"type":"object","properties":{"type":{"type":"string"}}}, + "flowDirection":{"type":"string"} + }, + "required":["sourceEnd","targetEnd","flowDirection"], + "additionalProperties":false +}"#; + const CLASSIFICATION_SCHEMA: &str = r#"{ "$schema":"https://json-schema.org/draft/2020-12/schema", "type":"object", @@ -173,6 +185,63 @@ fn json(output: &Output) -> Value { }) } +fn assert_object_shape(value: &Value, encoded: &str, marker: &str, expected: &[&str]) { + let object = value.as_object().expect("value is an object"); + let mut actual: Vec<&str> = object.keys().map(String::as_str).collect(); + actual.sort_unstable(); + let mut expected_sorted = expected.to_vec(); + expected_sorted.sort_unstable(); + assert_eq!( + actual, expected_sorted, + "unexpected object keys at {marker}" + ); + + let marker_start = encoded.find(marker).expect("object marker is serialized"); + let object_start = marker_start + marker.len() - 1; + let bytes = encoded.as_bytes(); + let mut depth = 0usize; + let mut in_string = false; + let mut escaped = false; + let mut object_end = None; + for (offset, byte) in bytes.iter().enumerate().skip(object_start) { + if in_string { + if escaped { + escaped = false; + } else if *byte == b'\\' { + escaped = true; + } else if *byte == b'"' { + in_string = false; + } + continue; + } + match *byte { + b'"' => in_string = true, + b'{' => depth += 1, + b'}' => { + depth -= 1; + if depth == 0 { + object_end = Some(offset + 1); + break; + } + } + _ => {} + } + } + let object_text = &encoded[object_start..object_end.expect("object is closed")]; + let positions: Vec = expected + .iter() + .map(|key| { + object_text + .find(&format!("\"{key}\":")) + .unwrap_or_else(|| panic!("missing key {key} from {object_text}")) + }) + .collect(); + assert!( + positions.windows(2).all(|pair| pair[0] < pair[1]), + "wrong key order in {object_text}" + ); +} + #[test] #[trace("FR-046-AC-1", "FR-046-AC-2", "FR-046-AC-5", "FR-046-AC-6")] fn emits_the_canonical_health_flow_envelope_from_generic_relation_facts() { @@ -222,6 +291,84 @@ fn emits_the_canonical_health_flow_envelope_from_generic_relation_facts() { "untrusted" ); let encoded = String::from_utf8_lossy(&output.stdout); + assert_object_shape( + &report, + &encoded, + "{", + &["schema", "output", "flows", "gaps"], + ); + assert_object_shape( + &report["output"], + &encoded, + "\"output\":{", + &["name", "kind", "description"], + ); + assert_object_shape( + &report["flows"][0], + &encoded, + "\"flows\":[{", + &[ + "connection", + "source", + "destination", + "classifications", + "crossings", + ], + ); + assert_object_shape( + &report["flows"][0]["connection"], + &encoded, + "\"connection\":{", + &["repo", "id", "archetype", "path"], + ); + assert_object_shape( + &report["flows"][0]["source"], + &encoded, + "\"source\":{", + &["repo", "id", "archetype", "declared_by"], + ); + assert_object_shape( + &report["flows"][0]["source"]["declared_by"], + &encoded, + "\"declared_by\":{", + &["repo", "id", "archetype", "path"], + ); + assert_object_shape( + &report["flows"][0]["classifications"][0], + &encoded, + "\"classifications\":[{", + &["repo", "id", "archetype", "path"], + ); + assert_object_shape( + &report["flows"][0]["crossings"][0], + &encoded, + "\"crossings\":[{", + &["boundary", "trust_level"], + ); + assert_object_shape( + &report["flows"][0]["crossings"][0]["boundary"], + &encoded, + "\"boundary\":{", + &["repo", "id", "archetype", "path"], + ); + for document in [ + &report["flows"][0]["connection"], + &report["flows"][0]["classifications"][0], + &report["flows"][0]["crossings"][0]["boundary"], + ] { + assert!(document["repo"].is_null() || document["repo"].is_string()); + assert!(document["id"].is_string()); + assert!(document["archetype"].is_string()); + assert!(document["path"].is_string()); + } + assert!( + report["flows"][0]["source"]["repo"].is_null() + || report["flows"][0]["source"]["repo"].is_string() + ); + assert!(report["flows"][0]["source"]["id"].is_string()); + assert!(report["flows"][0]["source"]["archetype"].is_string()); + assert!(report["flows"][0]["source"]["declared_by"].is_object()); + assert!(report["flows"][0]["crossings"][0]["trust_level"].is_string()); let top_level = ["\"schema\"", "\"output\"", "\"flows\"", "\"gaps\""]; let top_positions: Vec = top_level .iter() @@ -324,6 +471,132 @@ fn multi_repo_references_keep_their_declared_member_identity() { ); } +#[test] +#[trace("FR-046-AC-5")] +fn sorts_multiple_flows_classifications_crossings_and_missing_references() { + let temp = TempDir::new().unwrap(); + let module = temp.path().join("module"); + write(&module, "manifest.yaml", MANIFEST); + write(&module, "schemas/Connection.json", CONNECTION_SCHEMA); + write( + &module, + "schemas/Classification.json", + CLASSIFICATION_SCHEMA, + ); + write(&module, "schemas/TrustBoundary.json", BOUNDARY_SCHEMA); + let scope = temp.path().join("repo"); + + let endpoints = "sourceEnd:\n type: ix://agent-ix/health-flow-fixture/PORT-SOURCE\ntargetEnd:\n type: ix://agent-ix/health-flow-fixture/PORT-TARGET\n"; + let mut multiple_refs = vec![ + ("classified-as", "CLS-Z"), + ("classified-as", "CLS-A"), + ("crosses", "BOUNDARY-Z"), + ("crosses", "BOUNDARY-A"), + ]; + write( + &scope, + "spec/a.md", + &document("CONN-Z", "Connection", endpoints, &multiple_refs), + ); + multiple_refs = vec![("classified-as", "CLS-M"), ("crosses", "BOUNDARY-M")]; + write( + &scope, + "spec/z.md", + &document("CONN-A", "Connection", endpoints, &multiple_refs), + ); + multiple_refs = vec![ + ("classified-as", "CLS-G"), + ("crosses", "BOUNDARY-Z-DANGLING"), + ("crosses", "BOUNDARY-A-DANGLING"), + ("crosses", "BOUNDARY-EMPTY"), + ]; + write( + &scope, + "spec/a-gap.md", + &document("CONN-GAP-Z", "Connection", endpoints, &multiple_refs), + ); + multiple_refs = vec![ + ("classified-as", "CLS-G"), + ("crosses", "BOUNDARY-Q-DANGLING"), + ("crosses", "BOUNDARY-P-DANGLING"), + ]; + write( + &scope, + "spec/z-gap.md", + &document("CONN-GAP-A", "Connection", endpoints, &multiple_refs), + ); + + for id in ["CLS-Z", "CLS-A", "CLS-M", "CLS-G"] { + write( + &scope, + &format!("spec/{id}.md"), + &document(id, "Classification", "regulatedCategories: [health]\n", &[]), + ); + } + for id in ["BOUNDARY-Z", "BOUNDARY-A", "BOUNDARY-M"] { + write( + &scope, + &format!("spec/{id}.md"), + &document(id, "TrustBoundary", "trust_level: untrusted\n", &[]), + ); + } + write( + &scope, + "spec/BOUNDARY-EMPTY.md", + &document("BOUNDARY-EMPTY", "TrustBoundary", "", &[]), + ); + + let output = run(&scope, &module, &["--health-data-flows", "--json"]); + assert!( + output.status.success(), + "{}", + String::from_utf8_lossy(&output.stderr) + ); + let report = json(&output); + let flows = report["flows"].as_array().unwrap(); + assert_eq!(flows.len(), 2); + assert_eq!(flows[0]["connection"]["id"], "CONN-A"); + assert_eq!(flows[1]["connection"]["id"], "CONN-Z"); + let classification_ids: Vec<&str> = flows[1]["classifications"] + .as_array() + .unwrap() + .iter() + .map(|document| document["id"].as_str().unwrap()) + .collect(); + assert_eq!(classification_ids, ["CLS-A", "CLS-Z"]); + let crossing_ids: Vec<&str> = flows[1]["crossings"] + .as_array() + .unwrap() + .iter() + .map(|crossing| crossing["boundary"]["id"].as_str().unwrap()) + .collect(); + assert_eq!(crossing_ids, ["BOUNDARY-A", "BOUNDARY-Z"]); + assert_eq!(report["gaps"].as_array().unwrap().len(), 2); + assert_eq!(report["gaps"][0]["connection"]["id"], "CONN-GAP-A"); + assert_eq!(report["gaps"][1]["connection"]["id"], "CONN-GAP-Z"); + let missing: Vec<(&str, Option<&str>)> = report["gaps"][1]["missing"] + .as_array() + .unwrap() + .iter() + .map(|item| { + ( + item["field"].as_str().unwrap(), + item["reference"]["id"].as_str(), + ) + }) + .collect(); + assert_eq!( + missing, + [ + ("crossing", Some("BOUNDARY-A-DANGLING")), + ("crossing", Some("BOUNDARY-Z-DANGLING")), + ("trust_level", Some("BOUNDARY-EMPTY")), + ] + ); + let second = run(&scope, &module, &["--health-data-flows", "--json"]); + assert_eq!(output.stdout, second.stdout); +} + #[test] #[trace("FR-046-AC-3")] fn reports_missing_endpoint_dangling_crossing_and_missing_trust_level() { @@ -349,10 +622,28 @@ fn reports_missing_endpoint_dangling_crossing_and_missing_trust_level() { assert!(missing .iter() .any(|item| item["field"] == "source" && item["reference"].is_null())); + assert!(!missing.iter().any(|item| item["field"] == "destination")); assert!(missing .iter() .any(|item| item["field"] == "crossing" && item["reference"]["id"] == "BOUNDARY-1")); + let (temp, scope) = world( + "sourceEnd:\n type: ix://agent-ix/health-flow-fixture/PORT-SOURCE\n", + "health", + None, + false, + ); + let output = run( + &scope, + &temp.path().join("module"), + &["--health-data-flows", "--json"], + ); + let report = json(&output); + let missing = report["gaps"][0]["missing"].as_array().unwrap(); + assert_eq!(missing.len(), 1); + assert_eq!(missing[0]["field"], "destination"); + assert!(missing[0]["reference"].is_null()); + let (temp, scope) = world( "sourceEnd:\n type: ix://agent-ix/health-flow-fixture/PORT-SOURCE\ntargetEnd:\n type: ix://agent-ix/health-flow-fixture/PORT-TARGET\n", "health", @@ -370,6 +661,94 @@ fn reports_missing_endpoint_dangling_crossing_and_missing_trust_level() { .unwrap() .iter() .any(|item| item["field"] == "trust_level")); + let encoded = String::from_utf8_lossy(&output.stdout); + let missing_item = report["gaps"][0]["missing"] + .as_array() + .unwrap() + .iter() + .find(|item| item["field"] == "trust_level") + .expect("missing trust level is represented"); + assert_object_shape( + &report["gaps"][0], + &encoded, + "\"gaps\":[{", + &["connection", "missing"], + ); + assert_object_shape( + &missing_item["reference"], + &encoded, + "\"reference\":{", + &["repo", "id", "archetype", "declared_by"], + ); + assert_object_shape( + &missing_item["reference"]["declared_by"], + &encoded, + "\"declared_by\":{", + &["repo", "id", "archetype", "path"], + ); +} + +#[test] +#[trace("FR-046-AC-3")] +fn an_invalid_connection_record_reports_unavailability_without_guessing_endpoints() { + let complete = "sourceEnd:\n type: ix://agent-ix/health-flow-fixture/PORT-SOURCE\ntargetEnd:\n type: ix://agent-ix/health-flow-fixture/PORT-TARGET\nflowDirection: source-to-target\n"; + let cases = [ + ( + "PORT-TARGET", + "sourceEnd:\n type: ix://agent-ix/health-flow-fixture/PORT-SOURCE\n", + ), + ( + "PORT-SOURCE", + "targetEnd:\n type: ix://agent-ix/health-flow-fixture/PORT-TARGET\n", + ), + ]; + for (endpoint_id, remaining_endpoint) in cases { + let mut record = complete.to_owned(); + let removed = if endpoint_id == "PORT-TARGET" { + "targetEnd:\n type: ix://agent-ix/health-flow-fixture/PORT-TARGET\n" + } else { + "sourceEnd:\n type: ix://agent-ix/health-flow-fixture/PORT-SOURCE\n" + }; + record = record.replace(removed, ""); + assert!(record.contains(remaining_endpoint)); + let (temp, scope) = world(&record, "health", None, false); + write( + &temp.path().join("module"), + "schemas/Connection.json", + REQUIRED_CONNECTION_SCHEMA, + ); + let output = run( + &scope, + &temp.path().join("module"), + &["--health-data-flows", "--json"], + ); + assert!( + output.status.success(), + "{}", + String::from_utf8_lossy(&output.stderr) + ); + let report = json(&output); + assert!(report["flows"].as_array().unwrap().is_empty()); + let gap = &report["gaps"][0]; + assert_eq!(gap["connection"]["id"], "CONN-1"); + assert_eq!(gap["missing"].as_array().unwrap().len(), 1); + assert_eq!(gap["missing"][0]["field"], "connection_record"); + assert!(gap["missing"][0]["reference"].is_null()); + let encoded = String::from_utf8_lossy(&output.stdout); + assert_object_shape(gap, &encoded, "\"gaps\":[{", &["connection", "missing"]); + assert_object_shape( + &gap["connection"], + &encoded, + "\"connection\":{", + &["repo", "id", "archetype", "path"], + ); + assert_object_shape( + &gap["missing"][0], + &encoded, + "\"missing\":[{", + &["field", "reference"], + ); + } } #[test] From d47d870ed714206ebf5451cf462361506ec4e407 Mon Sep 17 00:00:00 2001 From: Agent IX Date: Mon, 16 Nov 2026 01:29:45 -0800 Subject: [PATCH 3/4] PLAT-1756 preserve crossing gaps for unavailable records --- reviews/plat-1756-code-review.md | 8 ++++++++ reviews/plat-1756-gap-analysis.md | 16 ++++++++++++++++ tests/cli_health_data_flows.rs | 27 +++++++++++++++++++++++++++ 3 files changed, 51 insertions(+) diff --git a/reviews/plat-1756-code-review.md b/reviews/plat-1756-code-review.md index 2649348..ec0711d 100644 --- a/reviews/plat-1756-code-review.md +++ b/reviews/plat-1756-code-review.md @@ -47,3 +47,11 @@ FR-084 says `record` is omitted when record validation fails. The architecture C - `FR-046-AC-10` (examined): The CLI derives health selection and record structure only from the generic FR-084 relation report's `document`, `linked`, `dangling`, and selected `record` values; it reads no source files and does not alter the report used by `--flow`. - `FR-084` (context_only): the generic relation report omits `record` when record validation fails. - `FR-007` (context_only): a connection requires `sourceEnd`, `targetEnd`, and `flowDirection`. + +## Dispositions + +Round 1, published head 89cd7594e6accae571b8209f10bfe0f9525637b1. + +| FND | outcome | reason | +| --- | --- | --- | +| FND-001 | fixed | `project_health_data_flows` now detects a missing selected connection record from a health-classified relation, removes guessed endpoint gaps, and emits one `connection_record` item with a null reference. `an_invalid_connection_record_reports_unavailability_without_guessing_endpoints` uses a schema requiring both endpoints and flowDirection, then verifies the unavailable-record output for each missing endpoint. | diff --git a/reviews/plat-1756-gap-analysis.md b/reviews/plat-1756-gap-analysis.md index f127833..50cc371 100644 --- a/reviews/plat-1756-gap-analysis.md +++ b/reviews/plat-1756-gap-analysis.md @@ -53,3 +53,19 @@ The computed matrix binds tests to FR-046 AC-1 through AC-9 and treats AC-10 as ## Coverage The matrix and tests were inspected for all ten criteria. `Plan completion: not assessed`. Semantic review was skipped because it was not requested. + +## New findings (round 1) + +| ID | Severity | Summary | Refs | +| --- | --- | --- | --- | +| FND-003 | medium | AC-3 explicitly requires independently observed crossing gaps to remain in a gap when FR-084 omits the selected connection record. The implementation preserves those items, but the unavailable-record test supplies no crossing, so a regression that drops crossing gaps on this path would pass. | tests/cli_health_data_flows.rs:693-750 | + +## Dispositions + +Round 1, published head 89cd7594e6accae571b8209f10bfe0f9525637b1. + +| FND | outcome | reason | +| --- | --- | --- | +| FND-001 | fixed | `emits_the_canonical_health_flow_envelope_from_generic_relation_facts` now asserts closed, ordered object shapes for the envelope, output, flow, ModelDocument, DeclaredReference, crossing and boundary, including field types and nullable repository identity. | +| FND-002 | fixed | `sorts_multiple_flows_classifications_crossings_and_missing_references` now exercises reverse-authored multiple flows, classifications, crossings, gaps and missing references, asserts lexical output order, and compares repeat output byte-for-byte. | +| FND-003 | still-open | The unavailable-record test checks only `connection_record` by itself. Add an unavailable selected record and a dangling crossing in the same fixture, and assert both missing items remain in the emitted gap. The production code currently retains that crossing item, but no test protects the explicit AC-3 combination. | diff --git a/tests/cli_health_data_flows.rs b/tests/cli_health_data_flows.rs index 2463117..8fa229b 100644 --- a/tests/cli_health_data_flows.rs +++ b/tests/cli_health_data_flows.rs @@ -749,6 +749,33 @@ fn an_invalid_connection_record_reports_unavailability_without_guessing_endpoint &["field", "reference"], ); } + + let missing_target = "sourceEnd:\n type: ix://agent-ix/health-flow-fixture/PORT-SOURCE\nflowDirection: source-to-target\n"; + let (temp, scope) = world(missing_target, "health", None, true); + write( + &temp.path().join("module"), + "schemas/Connection.json", + REQUIRED_CONNECTION_SCHEMA, + ); + let output = run( + &scope, + &temp.path().join("module"), + &["--health-data-flows", "--json"], + ); + assert!( + output.status.success(), + "{}", + String::from_utf8_lossy(&output.stderr) + ); + let report = json(&output); + assert!(report["flows"].as_array().unwrap().is_empty()); + let missing = report["gaps"][0]["missing"].as_array().unwrap(); + assert_eq!(missing.len(), 2); + assert_eq!(missing[0]["field"], "connection_record"); + assert!(missing[0]["reference"].is_null()); + assert_eq!(missing[1]["field"], "crossing"); + assert_eq!(missing[1]["reference"]["id"], "BOUNDARY-1"); + assert_eq!(missing[1]["reference"]["declared_by"]["id"], "CONN-1"); } #[test] From 2acbe175188ecd4a83e3a7d717de18a08c0ef7d4 Mon Sep 17 00:00:00 2001 From: Agent IX Date: Mon, 16 Nov 2026 01:37:41 -0800 Subject: [PATCH 4/4] PLAT-1756 record final review dispositions --- reviews/plat-1756-code-review.md | 7 +++++++ reviews/plat-1756-gap-analysis.md | 9 +++++++++ 2 files changed, 16 insertions(+) diff --git a/reviews/plat-1756-code-review.md b/reviews/plat-1756-code-review.md index ec0711d..1a2ffce 100644 --- a/reviews/plat-1756-code-review.md +++ b/reviews/plat-1756-code-review.md @@ -55,3 +55,10 @@ Round 1, published head 89cd7594e6accae571b8209f10bfe0f9525637b1. | FND | outcome | reason | | --- | --- | --- | | FND-001 | fixed | `project_health_data_flows` now detects a missing selected connection record from a health-classified relation, removes guessed endpoint gaps, and emits one `connection_record` item with a null reference. `an_invalid_connection_record_reports_unavailability_without_guessing_endpoints` uses a schema requiring both endpoints and flowDirection, then verifies the unavailable-record output for each missing endpoint. | + + +Round 2, published head d47d870ed714206ebf5451cf462361506ec4e407. + +| FND | outcome | reason | +| --- | --- | --- | +| FND-001 | fixed | The production projection is unchanged from the round-1 fix; the required-connection-schema test still asserts the unavailable record produces one `connection_record` item and no guessed endpoint. Focused integration test passed at this head. | diff --git a/reviews/plat-1756-gap-analysis.md b/reviews/plat-1756-gap-analysis.md index 50cc371..02e0e96 100644 --- a/reviews/plat-1756-gap-analysis.md +++ b/reviews/plat-1756-gap-analysis.md @@ -69,3 +69,12 @@ Round 1, published head 89cd7594e6accae571b8209f10bfe0f9525637b1. | FND-001 | fixed | `emits_the_canonical_health_flow_envelope_from_generic_relation_facts` now asserts closed, ordered object shapes for the envelope, output, flow, ModelDocument, DeclaredReference, crossing and boundary, including field types and nullable repository identity. | | FND-002 | fixed | `sorts_multiple_flows_classifications_crossings_and_missing_references` now exercises reverse-authored multiple flows, classifications, crossings, gaps and missing references, asserts lexical output order, and compares repeat output byte-for-byte. | | FND-003 | still-open | The unavailable-record test checks only `connection_record` by itself. Add an unavailable selected record and a dangling crossing in the same fixture, and assert both missing items remain in the emitted gap. The production code currently retains that crossing item, but no test protects the explicit AC-3 combination. | + + +Round 2, published head d47d870ed714206ebf5451cf462361506ec4e407. + +| FND | outcome | reason | +| --- | --- | --- | +| FND-001 | fixed | The canonical output test continues to assert closed ordered shapes for the nested model and reference objects. | +| FND-002 | fixed | The multi-value test continues to assert ordering across multiple flows, classifications, crossings, gaps, and missing references, plus byte-identical repeated output. | +| FND-003 | fixed | The added invalid-record case includes a dangling boundary crossing; it asserts exactly two missing items (`connection_record` with null reference and the `crossing` reference to BOUNDARY-1 authored by CONN-1). The focused test passed. |