diff --git a/bazel/rules/rules_score/docs/index.rst b/bazel/rules/rules_score/docs/index.rst index ddff5ac6..e82120db 100644 --- a/bazel/rules/rules_score/docs/index.rst +++ b/bazel/rules/rules_score/docs/index.rst @@ -39,6 +39,7 @@ safety analysis to the top-level SEooC assembly. tool_reference/specs/bazel_component tool_reference/specs/component_sequence + tool_reference/specs/class_design_implementation .. toctree:: :maxdepth: 2 diff --git a/bazel/rules/rules_score/docs/requirements/use_cases.trlc b/bazel/rules/rules_score/docs/requirements/use_cases.trlc index bb40b259..96f310ed 100644 --- a/bazel/rules/rules_score/docs/requirements/use_cases.trlc +++ b/bazel/rules/rules_score/docs/requirements/use_cases.trlc @@ -163,4 +163,14 @@ section "Use Cases" { affected_tools = [Tools.Verifier, Tools.PlantumlParser, Tools.Bazel] } + ToolQualification.UseCase Validate_Unit_Specification_Documents { + description = ''' + As a software developer I want the build to verify that unit design + class and sequence diagrams are consistent with the corresponding + implementation artefacts so that unit-level design drift is + detected automatically during the build. + ''' + affected_tools = [Tools.Verifier, Tools.PlantumlParser, Tools.LibClang, Tools.Bazel] + } + } diff --git a/validation/core/BUILD b/validation/core/BUILD index 395bf590..f15fd5eb 100644 --- a/validation/core/BUILD +++ b/validation/core/BUILD @@ -23,6 +23,7 @@ filegroup( name = "specifications", srcs = [ "docs/specifications/bazel_component.md", + "docs/specifications/class_design_implementation.md", "docs/specifications/component_sequence.md", ], visibility = ["//visibility:public"], diff --git a/validation/core/docs/requirements/tool_requirements.trlc b/validation/core/docs/requirements/tool_requirements.trlc index 93dc6222..4dc8cba6 100644 --- a/validation/core/docs/requirements/tool_requirements.trlc +++ b/validation/core/docs/requirements/tool_requirements.trlc @@ -119,6 +119,90 @@ section "Tool Requirements" { } + section "Class Design Implementation Validator" { + + ToolQualification.ToolRequirement ClassDesignImplementationEntityConsistency { + description = '''The validator shall report an error when an + entity modeled in the unit design class diagram has no + corresponding entity in the implementation class diagram, or + when the matching implementation entity differs in entity + type. Consistency of type aliases, variables, methods, enum + literals, relationships, and template parameters is specified + by the dedicated requirements below.''' + derived_from = [UseCases.Validate_Unit_Specification_Documents] + satisfied_by = Verifier + } + + ToolQualification.ToolRequirement ClassDesignImplementationTemplateParameterConsistency { + description = '''The validator shall report an error when + template parameters modeled on a unit design entity or method + differ from the template parameters on the matching + implementation entity or method.''' + derived_from = [UseCases.Validate_Unit_Specification_Documents] + satisfied_by = Verifier + } + + ToolQualification.ToolRequirement ClassDesignImplementationTypeAliasConsistency { + description = '''The validator shall report an error when a + type alias modeled in a unit design entity is missing from the + matching implementation entity, or when the matching + implementation type alias differs in original type.''' + derived_from = [UseCases.Validate_Unit_Specification_Documents] + satisfied_by = Verifier + } + + ToolQualification.ToolRequirement ClassDesignImplementationVariableConsistency { + description = '''The validator shall report an error when a + variable modeled in a unit design entity is missing from the + matching implementation entity, or when the matching + implementation variable differs in data type, visibility, or + static flag.''' + derived_from = [UseCases.Validate_Unit_Specification_Documents] + satisfied_by = Verifier + } + + ToolQualification.ToolRequirement ClassDesignImplementationMethodConsistency { + description = '''The validator shall report an error when a + method modeled in a unit design entity is missing from the + matching implementation entity, or when the matching + implementation method differs in return type, visibility, + parameters, or method modifiers (`static`, `virtual`, + `abstract`, `override`, constructor, destructor, or + `noexcept`).''' + derived_from = [UseCases.Validate_Unit_Specification_Documents] + satisfied_by = Verifier + } + + ToolQualification.ToolRequirement ClassDesignImplementationEnumLiteralConsistency { + description = '''The validator shall report an error when an + enum literal modeled in a unit design enum is missing from the + matching implementation enum, or when the matching + implementation enum literal data differs from the unit design.''' + derived_from = [UseCases.Validate_Unit_Specification_Documents] + satisfied_by = Verifier + } + + ToolQualification.ToolRequirement ClassDesignImplementationRelationshipConsistency { + description = '''The validator shall report an error when a + relationship modeled in a unit design entity is missing from + the matching implementation entity, or when the matching + implementation relationship differs in source, target, or + relationship type.''' + derived_from = [UseCases.Validate_Unit_Specification_Documents] + satisfied_by = Verifier + } + + ToolQualification.ToolRequirement ClassDesignImplementationTypeNormalization { + description = '''The validator shall normalize namespace + separators, the `std::` type prefix, and pointer or reference + spacing before comparing entity references and type names + between unit design and implementation class diagrams.''' + derived_from = [UseCases.Validate_Unit_Specification_Documents] + satisfied_by = Verifier + } + + } + } } diff --git a/validation/core/docs/specifications/class_design_implementation.md b/validation/core/docs/specifications/class_design_implementation.md new file mode 100644 index 00000000..ade39e68 --- /dev/null +++ b/validation/core/docs/specifications/class_design_implementation.md @@ -0,0 +1,232 @@ + + +# Class Design Implementation Specification + +## Purpose + +This validator enforces consistency between the class model in the unit design +and the class model extracted from the implementation. + +It shall make sure that every class, member, method, enum literal, type alias, +and relationship modeled in the unit design exists in the implementation and is +compatible with it. + +Implementation-only entities and members are allowed. The unit design is the +validated contract. + +## What is Validated + +The validator compares unit design class diagrams with implementation class +diagrams produced by the C++ parser. It receives two indexed class-diagram +inputs: + +| Input | Source | Meaning | +|---|---|---| +| `design_classes` | `unit_design` class diagram FlatBuffers | Required class model from the unit design | +| `implementation_classes` | C++ parser class diagram FlatBuffers from `unit` implementation targets | Observed class model from implementation code | + +### Entity Presence and Type Consistency + +Every entity in the unit design class diagram must have a corresponding entity +in the implementation class diagram. Matching entities must have the same entity +type. +*(Requirement: {requirement:downstream-ref}`Tools.ClassDesignImplementationEntityConsistency`)* + +This item covers entity matching and entity type only. The consistency of data +contained by a matched entity is covered by the following type alias, variable, +method, enum literal, relationship, and template parameter items. + +```text +' unit design class diagram +package vehicle { + class "Transport" +} + +' implementation C++ code +namespace vehicle { + class Transport {} +} +``` + +### Template Parameter Consistency + +Template parameters modeled on unit design entities and methods must match the +template parameters on the corresponding implementation entities and methods. +*(Requirement: {requirement:downstream-ref}`Tools.ClassDesignImplementationTemplateParameterConsistency`)* + +```text +' unit design class diagram +class Repository { + + FindById(id: Key) : T +} + +' implementation C++ code +template +class Repository { + template + T FindById(Key id); +} +``` + +### Type Alias Consistency + +Every type alias modeled in the unit design entity must exist in the matching +implementation entity. The alias name and normalized original type must match. +*(Requirement: {requirement:downstream-ref}`Tools.ClassDesignImplementationTypeAliasConsistency`)* + +```text +' unit design class diagram +class "Transport" { + using Payload = std::uint8_t +} + +' implementation C++ code +class Transport { +public: + using Payload = std::uint8_t; +}; +``` + +### Variable Consistency + +Every variable modeled in the unit design entity must exist in the matching +implementation entity. The variable name, normalized data type, visibility, and +static flag must match. +*(Requirement: {requirement:downstream-ref}`Tools.ClassDesignImplementationVariableConsistency`)* + +```text +' unit design class diagram +class "Transport" { + - buffer: std::uint8_t* + {static} - instance_count: uint32_t +} + +' implementation C++ code +class Transport { +private: + std::uint8_t* buffer; + static std::uint32_t instance_count; +}; +``` + +### Method Consistency + +Every method modeled in the unit design entity must exist in the matching +implementation entity. The method name, visibility, parameters, and method +modifiers must match. For non-constructor/non-destructor methods, normalized +return type must also match. Method modifiers include `static`, `virtual`, +`abstract`, `override`, constructor, destructor, and `noexcept`. +*(Requirement: {requirement:downstream-ref}`Tools.ClassDesignImplementationMethodConsistency`)* + +Method lookup first tries the full normalized signature. If no exact signature +match exists and exactly one implementation method has the same name, that +method is compared to produce field-level diagnostics. If multiple same-named +implementation overloads exist, the design method is reported as missing because +the validator cannot safely choose a candidate. + +```text +' unit design class diagram +class "Transport" { + + Dispatch(mode: std::uint8_t, payload: vehicle::Payload): bool +} + +' implementation C++ code +bool Transport::Dispatch(std::uint8_t mode, vehicle::Payload payload) +``` + +### Enum Literal Consistency + +Every enum literal modeled in the unit design enum must exist in the matching +implementation enum. The full literal data must match. +*(Requirement: {requirement:downstream-ref}`Tools.ClassDesignImplementationEnumLiteralConsistency`)* + +```text +' unit design class diagram +enum "Mode" { + Startup + Shutdown +} + +' implementation C++ code +enum Mode { + Startup, + Shutdown, +}; +``` + +### Relationship Consistency + +Every relationship modeled on a unit design entity must exist on the matching +implementation entity. Source, target, and relationship type must match. +*(Requirement: {requirement:downstream-ref}`Tools.ClassDesignImplementationRelationshipConsistency`)* + +```text +' unit design class diagram +struct Payload {} +class Vehicle { + + Load(payload : Payload) +} +Vehicle ..> Payload + +' implementation C++ code +struct Payload {}; +class Vehicle { +public: + void Load(Payload payload); +}; +``` + +### Type Normalization + +Before comparing types, the validator applies limited normalization. +*(Requirement: {requirement:downstream-ref}`Tools.ClassDesignImplementationTypeNormalization`)* + +| Input form | Normalized form | +|---|---| +| `std::uint8_t` | `uint8_t` | +| `uint8_t *` | `uint8_t*` | +| `Payload &` | `Payload&` | + +## Failure Cases + +| Failure case | Validation rule | +|---|---| +| Missing implementation entity | Entity Presence and Type Consistency | +| Entity type mismatch | Entity Presence and Type Consistency | +| Entity template parameter mismatch | Template Parameter Consistency | +| Missing type alias | Type Alias Consistency | +| Type alias original type mismatch | Type Alias Consistency | +| Missing variable | Variable Consistency | +| Variable type, visibility, or static flag mismatch | Variable Consistency | +| Missing method | Method Consistency | +| Method return type, visibility, parameter, or modifier mismatch | Method Consistency | +| Method template parameter mismatch | Template Parameter Consistency | +| Missing enum literal | Enum Literal Consistency | +| Enum literal data mismatch | Enum Literal Consistency | +| Missing relationship | Relationship Consistency | +| Relationship source, target, or type mismatch | Relationship Consistency | + +## Debug Output + +The validator emits debug output containing: + +- the design entity ID being compared +- the implementation entity ID being compared +- detailed design entity snapshots at trace level +- detailed implementation entity snapshots at trace level +- type aliases, variables, methods, template parameters, enum literals, and + relationships for each matched entity + +Failure messages contain source file and source line information when available. +Missing or empty source metadata is rendered as ``.