Add shared validation error formatting support

Author: shengzhangscore

tools/metamodel/common/source_location.rs

@@ -39,6 +39,13 @@ impl SourceLocation {
                     return normalize_source_path(relative.to_string_lossy().as_ref());
                 }
             }
+
+            // TODO: Do not store that absolute sandbox path as the source
+            // location. Source locations should be stable across actions, for
+            // example repo-relative.
+            if let Some(relative) = strip_bazel_execroot_prefix(self.file.as_ref()) {
+                return relative;
+            }
         }
 
         normalize_source_path(self.file.as_ref())
@@ -53,6 +60,11 @@ fn normalize_source_path(path: &str) -> String {
     path.strip_prefix("./").unwrap_or(path).to_string()
 }
 
+fn strip_bazel_execroot_prefix(path: &str) -> Option<String> {
+    let (_, relative) = path.split_once("/execroot/_main/")?;
+    Some(normalize_source_path(relative))
+}
+
 impl fmt::Display for SourceLocation {
     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
         write!(f, "{}:{}", self.display_file(), self.line)

validation/core/BUILD

@@ -53,6 +53,7 @@ rust_library(
         "src/readers/mod.rs",
         "src/readers/sequence_diagram_reader.rs",
         "src/results/diagnostics.rs",
+        "src/results/error_models.rs",
         "src/results/mod.rs",
         "src/validators/bazel_component_validator.rs",
         "src/validators/class_design_implementation_validator.rs",
@@ -74,6 +75,7 @@ rust_library(
     visibility = ["//visibility:public"],
     deps = [
         "//tools/metamodel/class:class_diagram",
+        "//tools/metamodel/common:source_location",
         "//tools/metamodel/component:component_diagram",
         "//tools/metamodel/sequence:sequence_diagram",
         "//tools/serialization/flatbuffers/class:class_fbs",

validation/core/integration_test/README.md

@@ -72,7 +72,7 @@ produced in layer 1. No copying or re-parsing occurs; the underlying Bazel
 action cache entry is reused.
 
 A `filegroup` named `case_data` then bundles the `fbs` target together with the
-static fixture files (`architecture.json`, `expected.json` or `expected.yaml`),
+static fixture files (`architecture.json` and `expected.yaml`),
 making the whole case available as a single Bazel dependency.
 
 For `ComponentInternalApi` and `SequenceInternalApi` suites, cases include
@@ -96,7 +96,7 @@ The shared `test_framework` library provides the following helpers:
 | Helper | Description |
 |--------|-------------|
 | `collect_case_fbs_files(suite, case, category)` | Returns sorted absolute paths to every `.fbs.bin` in a category subdirectory |
-| `load_expected_fixture(suite, case)` | Deserializes `expected.json` into `ExpectedFixture` |
+| `load_expected_fixture(suite, case)` | Deserializes `expected.yaml` into `ExpectedFixture` |
 | `load_expected_yaml_fixture(suite, case)` | Deserializes `expected.yaml` into `ExpectedFixture` |
 | `run_validation_profile(case_name, profile, input_bundle)` | Writes a profile-owned input bundle, spawns the CLI binary, and returns `CliRunResult` |
 | `assert_cli_result(case, expected, result)` | Asserts exit code and checks each string in `error_contains` against the log |
@@ -120,7 +120,7 @@ design/component_diagram.fbs.bin        ← in ArchitecturalDesignInfo.static
 component/component_diagram.fbs.bin     ← symlink → file above
 
         │  filegroup case_data
-        │  → bundles fbs + architecture.json + expected.json
+        │  → bundles fbs + architecture.json + expected.yaml
         ▼
 //.../bazel_component:bazel_component_test_data ← aggregated across all cases
 
@@ -149,7 +149,7 @@ the validator under test.
 ├── BUILD                 # architectural_design + provider_fbs_fixture_bundle + case_data
 ├── component_diagram.puml
 ├── architecture.json     # Bazel build-graph snapshot (components/units)
-└── expected.json
+└── expected.yaml
 ```
 
 ### ComponentClass cases
@@ -159,7 +159,7 @@ the validator under test.
 ├── BUILD                 # architectural_design + unit_design + provider_fbs_fixture_bundle + case_data
 ├── component_diagram.puml
 ├── class_diagram.puml    # one or more; multi-file: class_diagram_part1.puml, ...
-└── expected.json
+└── expected.yaml
 ```
 
 ### ClassDesignImplementation cases
@@ -180,7 +180,7 @@ the validator under test.
 ├── BUILD                 # architectural_design + provider_fbs_fixture_bundle + case_data
 ├── component_diagram.puml
 ├── sequence_diagram.puml
-└── expected.json
+└── expected.yaml
 ```
 
 ### ComponentInternalApi cases
@@ -190,7 +190,7 @@ the validator under test.
 ├── BUILD                 # architectural_design + provider_fbs_fixture_bundle + case_data
 ├── component_diagram.puml
 ├── internal_api_diagram.puml
-└── expected.json
+└── expected.yaml
 ```
 
 ### SequenceInternalApi cases
@@ -201,16 +201,13 @@ the validator under test.
 ├── component_diagram.puml
 ├── sequence_diagram.puml
 ├── internal_api_diagram.puml
-└── expected.json
+└── expected.yaml
 ```
 
-### `expected.json` / `expected.yaml` format
+### `expected.yaml` format
 
-```json
-{
-  "should_pass": true,
-  "error_contains": []
-}
+```yaml
+should_pass: true
 ```
 
 | Field | Type | Description |
@@ -220,9 +217,7 @@ the validator under test.
 
 The framework uses **substring matching** for `error_contains`, so entries do
 not need to reproduce exact formatting — just enough context to uniquely
-identify the error. Existing suites use `expected.json`; the
-`class_design_implementation` suite uses `expected.yaml` so larger multi-line
-error fragments stay readable.
+identify the error.
 
 ## Running the tests
 
@@ -236,7 +231,6 @@ Run a single suite:
 
 ```bash
 bazel test //validation/core/integration_test/bazel_component:integration_test
-bazel test //validation/core/integration_test/component_class:integration_test
 bazel test //validation/core/integration_test/component_sequence:integration_test
 bazel test //validation/core/integration_test/component_internal_api:component_internal_api_integration_test
 bazel test //validation/core/integration_test/sequence_internal_api:sequence_internal_api_integration_test
@@ -253,16 +247,15 @@ bazel test //validation/core/integration_test/class_design_implementation:integr
 2. Add the `.puml` source file(s) and — for `bazel_component` — an
    `architecture.json`.
 
-3. Write `expected.json` or `expected.yaml`. For negative cases add the error
+3. Write `expected.yaml`. For negative cases add the error
   substrings you expect to see in the CLI log.
 
 4. Create a `BUILD` file following the pattern of an existing case in the same
    suite.
 
 5. Add the new `case_data` target to the matching filegroup in
   [`BUILD`](BUILD) (`bazel_component_test_data`,
-  `component_class_test_data`, `component_sequence_test_data`,
-  `component_internal_api_test_data`, `sequence_internal_api_test_data`,
+  `component_sequence_test_data`, `component_internal_api_test_data`, `sequence_internal_api_test_data`,
   or `class_design_implementation_test_data`).
 
 6. Add a `#[test]` function in the matching suite file, such as

validation/core/integration_test/src/lib.rs

@@ -15,6 +15,6 @@ mod test_framework;
 
 pub use test_framework::{
     assert_cli_result, case_file_path, collect_case_fbs_files, load_expected_fixture,
-    load_expected_yaml_fixture, normalize_yaml_result, run_validation_profile, CliRunResult,
-    ExpectedFixture, ValidationIntegrationCase,
+    normalize_yaml_result, run_validation_profile, CliRunResult, ExpectedFixture,
+    ValidationIntegrationCase,
 };

validation/core/integration_test/src/test_framework.rs

@@ -114,14 +114,6 @@ pub fn collect_case_fbs_files(suite_dir: &str, case_dir: &str, category: &str) -
     matches
 }
 
-pub fn load_expected_fixture(suite_dir: &str, case_dir: &str) -> ExpectedFixture {
-    let expected_json = read_case_file(&format!(
-        "validation/core/integration_test/{suite_dir}/{case_dir}/expected.json"
-    ));
-
-    serde_json::from_str(&expected_json).expect("failed to parse expected fixture")
-}
-
 pub fn load_expected_yaml_fixture(suite_dir: &str, case_dir: &str) -> ExpectedFixture {
     let expected_yaml = read_case_file(&format!(
         "validation/core/integration_test/{suite_dir}/{case_dir}/expected.yaml"
@@ -169,6 +161,10 @@ fn is_source_file_line(line: &str) -> bool {
     line.starts_with(DESIGN_SOURCE_FILE_LABEL) || line.starts_with(IMPLEMENT_SOURCE_FILE_LABEL)
 }
 
+pub fn load_expected_fixture(suite_dir: &str, case_dir: &str) -> ExpectedFixture {
+    load_expected_yaml_fixture(suite_dir, case_dir)
+}
+
 pub fn assert_cli_result(case_dir: &str, expected: &ExpectedFixture, result: &CliRunResult) {
     assert_eq!(
         result.success, expected.should_pass,

validation/core/src/lib.rs

@@ -23,4 +23,4 @@ mod results;
 mod validators;
 
 pub use profiles::{read_profile_inputs, run_profile, Profile, ProfileInputs, ProfileRun};
-pub use results::{Diagnostics, ValidationResult};
+pub use results::{Diagnostics, ErrorBuilder, ErrorCategory, ValidationResult};

validation/core/src/models/class_diagram_models.rs

@@ -15,7 +15,7 @@
 
 use std::collections::{BTreeMap, BTreeSet};
 
-use class_diagram::{ClassDiagram as ClassDiagramInput, EntityType, SimpleEntity};
+use class_diagram::{ClassDiagram as ClassDiagramInput, EntityType, SimpleEntity, SourceLocation};
 
 use crate::ValidationResult;
 
@@ -67,6 +67,7 @@ impl ClassEntityIndex {
 pub struct InternalApiInterface {
     pub id: String,
     pub method_names: BTreeSet<String>,
+    pub source_location: SourceLocation,
 }
 
 /// Indexed internal-API data prepared for validators.
@@ -93,6 +94,7 @@ impl InternalApiIndex {
                         .map(|method| method.name.clone())
                         .filter(|name| !name.is_empty())
                         .collect(),
+                    source_location: entity.source_location.clone(),
                 };
 
                 interfaces.push(interface);

validation/core/src/readers/mod.rs

@@ -13,7 +13,7 @@
 
 //! Input readers for Bazel JSON and PlantUML-derived FlatBuffer artifacts.
 
-use component_diagram::SourceLocation;
+use source_location::SourceLocation;
 
 mod bazel_reader;
 mod class_diagram_reader;

validation/core/src/results/error_models.rs

@@ -0,0 +1,125 @@
+// *******************************************************************************
+// Copyright (c) 2026 Contributors to the Eclipse Foundation
+//
+// See the NOTICE file(s) distributed with this work for additional
+// information regarding copyright ownership.
+//
+// This program and the accompanying materials are made available under the
+// terms of the Apache License Version 2.0 which is available at
+// <https://www.apache.org/licenses/LICENSE-2.0>
+//
+// SPDX-License-Identifier: Apache-2.0
+// *******************************************************************************
+
+//! Shared error message formatting helpers for validation results.
+
+use std::fmt::Write;
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum ErrorCategory {
+    Design,
+    Class,
+    Member,
+    Implementation,
+    Naming,
+    Interface,
+    Method,
+    Coverage,
+}
+
+impl ErrorCategory {
+    fn as_tag(self) -> &'static str {
+        match self {
+            Self::Design => "Design",
+            Self::Class => "Class",
+            Self::Member => "Member",
+            Self::Implementation => "Implementation",
+            Self::Naming => "Naming",
+            Self::Interface => "Interface",
+            Self::Method => "Method",
+            Self::Coverage => "Coverage",
+        }
+    }
+}
+
+fn uppercase_first_char(value: impl Into<String>) -> String {
+    let mut value = value.into();
+
+    if let Some((index, first_char)) = value.char_indices().next() {
+        let upper = first_char.to_uppercase().to_string();
+        value.replace_range(index..index + first_char.len_utf8(), &upper);
+    }
+
+    value
+}
+
+fn normalize_sentence_case(value: impl Into<String>) -> String {
+    let mut value = uppercase_first_char(value);
+
+    if !value.ends_with('.') {
+        value.push('.');
+    }
+
+    value
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct ErrorBuilder {
+    category: ErrorCategory,
+    title: Option<String>,
+    fields: Vec<(String, String)>,
+    fix: Option<String>,
+}
+
+impl ErrorBuilder {
+    pub fn new(category: ErrorCategory) -> Self {
+        Self {
+            category,
+            title: None,
+            fields: Vec::new(),
+            fix: None,
+        }
+    }
+
+    pub fn title(mut self, title: impl Into<String>) -> Self {
+        self.title = Some(normalize_sentence_case(title));
+        self
+    }
+
+    pub fn field(mut self, key: impl Into<String>, value: impl Into<String>) -> Self {
+        self.fields.push((uppercase_first_char(key), value.into()));
+        self
+    }
+
+    pub fn fix(mut self, fix: impl Into<String>) -> Self {
+        self.fix = Some(normalize_sentence_case(fix));
+        self
+    }
+
+    pub fn build(self) -> String {
+        let label_width = self
+            .fields
+            .iter()
+            .map(|(key, _)| key.len())
+            .chain(self.fix.iter().map(|_| "Fix".len()))
+            .max()
+            .unwrap_or(0);
+
+        let title = self.title.unwrap_or_default();
+        let mut message = String::new();
+        write!(&mut message, "[{}] {title}", self.category.as_tag())
+            .expect("writing to String cannot fail");
+
+        for (key, value) in self.fields {
+            write!(&mut message, "\n  {key:label_width$} : {value}")
+                .expect("writing to String cannot fail");
+        }
+
+        if let Some(fix) = self.fix {
+            write!(&mut message, "\n  {:label_width$} : {fix}", "Fix")
+                .expect("writing to String cannot fail");
+        }
+
+        message
+    }
+}

validation/core/src/results/mod.rs

@@ -14,8 +14,10 @@
 //! Validation execution results.
 
 mod diagnostics;
+mod error_models;
 
 pub use diagnostics::Diagnostics;
+pub use error_models::{ErrorBuilder, ErrorCategory};
 
 #[derive(Debug, Default)]
 pub struct ValidationResult {