diff --git a/validation/core/docs/specifications/bazel_component.md b/validation/core/docs/specifications/bazel_component.md new file mode 100644 index 0000000..a7ff4ac --- /dev/null +++ b/validation/core/docs/specifications/bazel_component.md @@ -0,0 +1,111 @@ + + +# Bazel Component Specification + +## Purpose + +Define the consistency rules between the indexed Bazel architecture and the +indexed PlantUML component diagram. + +This validator checks whether the same SEooC packages, components, and units +exist on both sides after model normalization. + +## What is Validated + +A dependable element must be defined both in Bazel and in PlantUML. The validator checks: + +- top-level dependable element: PlantUML `package <>` vs. Bazel dependable element +- names: PlantUML `alias` when present, otherwise `id` vs. Bazel target name +- components: PlantUML `<>` vs. Bazel component under the expected parent +- units: PlantUML `<>` vs. Bazel unit under the expected component +- parent context must match +- matching is case-insensitive + +In the common case, components nested directly under the dependable element use +the dependable element alias as parent. More deeply nested components use their +immediate enclosing component alias as parent. + +## Failure Cases + +### Missing in PlantUML + +Validation fails when Bazel defines a dependable element, component, or unit +that is not present in the PlantUML diagram. + +This includes cases where the name exists in PlantUML but under the wrong +parent, or with the wrong stereotype. + +### Extra in PlantUML + +Validation fails when PlantUML contains a dependable element, component, or +unit that does not have a corresponding definition in Bazel. + +This ensures the diagram does not introduce additional structure beyond what is +declared in the Bazel architecture. + +## Debug Output + +The validator appends a debug log containing: + +- all diagram entities +- filtered entity counts +- all normalized PlantUML keys +- all normalized Bazel keys + +## Example + +In Bazel BUILD files, the same structure can be declared like this: + +```starlark +component( + name = "component_example", + components = [ + "//bazel/rules/rules_score/examples/seooc/unit_1:unit_1", + "//bazel/rules/rules_score/examples/seooc/unit_2:unit_2", + ], +) + +dependable_element( + name = "safety_software_seooc_example", + components = [":component_example"], +) + +unit( + name = "unit_1", +) + +unit( + name = "unit_2", +) +``` + +When exported into the indexed Bazel architecture, these targets produce keys such as: + +If the Bazel architecture JSON contains: + +- dependable element: `safety_software_seooc_example` -> key: `("safety_software_seooc_example", None)` +- component: `@//bazel/rules/rules_score/examples/seooc:component_example` -> key: `("component_example", Some("safety_software_seooc_example"))` +- unit: `@//bazel/rules/rules_score/examples/seooc/unit_1:unit_1` -> key: `("unit_1", Some("component_example"))` +- unit: `@//bazel/rules/rules_score/examples/seooc/unit_2:unit_2` -> key: `("unit_2", Some("component_example"))` + +then PlantUML must contain entities with the same normalized keys: + +```plantuml +package "Sample Seooc" as safety_software_seooc_example <> { + component "Component Example" as component_example <> { + component "Unit 1" as unit_1 <> + component "Unit 2" as unit_2 <> + } +} +``` diff --git a/validation/core/docs/specifications/component_sequence.md b/validation/core/docs/specifications/component_sequence.md new file mode 100644 index 0000000..b65ebd0 --- /dev/null +++ b/validation/core/docs/specifications/component_sequence.md @@ -0,0 +1,70 @@ + + +# Component Sequence Specification + +## Purpose + +Define the intended consistency rules between component-diagram units and the +participants observed in sequence diagrams. + +This validator checks whether unit aliases from component diagrams match the +set of used participants collected from sequence diagrams. + +## What is Validated + +Component-diagram units and sequence-diagram participants must match. The validator checks: + +- unit aliases from the component diagram vs. participant aliases used in sequence diagrams +- matching is case-sensitive + +## Failure Cases + +### Missing sequence participant + +Validation fails when a unit alias defined in the component diagram does not +appear among the participants used in the sequence diagrams. + +### Unexpected sequence participant + +Validation fails when a sequence diagram uses a participant alias that does not +correspond to any unit alias declared in the component diagram. + +## Debug Output + +The validator emits a debug view containing: + +- expected unit aliases +- observed caller/callee participants + +## Example + +If the component diagram defines the unit aliases `unit_1` and `unit_2`, then +the sequence diagrams must use the same participant aliases. + +```plantuml +' component diagram +package "Package A" as package_a <> { + component "Component A" as component_a <> { + component "Unit 1" as unit_1 <> + component "Unit 2" as unit_2 <> + } +} + +' sequence diagram +participant "Unit 1" as unit_1 +participant "Unit 2" as unit_2 + +unit_1 -> unit_2 : SendSignal +unit_2 --> unit_1 : Ack +```