diff --git a/bazel/rules/rules_score/docs/index.rst b/bazel/rules/rules_score/docs/index.rst index aa4246cc..4135f7fa 100644 --- a/bazel/rules/rules_score/docs/index.rst +++ b/bazel/rules/rules_score/docs/index.rst @@ -40,6 +40,7 @@ safety analysis to the top-level SEooC assembly. tool_reference/specs/bazel_component tool_reference/specs/class_design_implementation tool_reference/specs/component_internal_api + tool_reference/specs/component_public_api tool_reference/specs/component_sequence tool_reference/specs/sequence_internal_api diff --git a/validation/core/BUILD b/validation/core/BUILD index 8ff02994..b02efb8b 100644 --- a/validation/core/BUILD +++ b/validation/core/BUILD @@ -25,6 +25,7 @@ filegroup( "docs/specifications/bazel_component.md", "docs/specifications/class_design_implementation.md", "docs/specifications/component_internal_api.md", + "docs/specifications/component_public_api.md", "docs/specifications/component_sequence.md", "docs/specifications/sequence_internal_api.md", ], diff --git a/validation/core/docs/requirements/tool_requirements.trlc b/validation/core/docs/requirements/tool_requirements.trlc index bbe08621..87a1daa3 100644 --- a/validation/core/docs/requirements/tool_requirements.trlc +++ b/validation/core/docs/requirements/tool_requirements.trlc @@ -148,6 +148,27 @@ section "Tool Requirements" { } + section "Component Public API Validator" { + + ToolQualification.ToolRequirement ComponentPublicApiInterfaceDeclarationConsistency { + description = '''The validator shall report an error when a + public API interface declared in the component diagram is not + declared as an interface in the public API class diagram.''' + derived_from = [UseCases.Validate_Architecture_Specification_Documents] + satisfied_by = Verifier + } + + ToolQualification.ToolRequirement ComponentPublicApiSeoocRelationshipConsistency { + description = '''The validator shall report an error when a + public API interface declared in the component diagram is not + connected by an interface-binding relationship from the SEooC + in the component diagram.''' + derived_from = [UseCases.Validate_Architecture_Specification_Documents] + satisfied_by = Verifier + } + + } + section "Class Design Implementation Validator" { ToolQualification.ToolRequirement ClassDesignImplementationEntityConsistency { diff --git a/validation/core/docs/specifications/component_public_api.md b/validation/core/docs/specifications/component_public_api.md new file mode 100644 index 00000000..36c4e2bb --- /dev/null +++ b/validation/core/docs/specifications/component_public_api.md @@ -0,0 +1,101 @@ + + +# Component Public API Specification + +## Purpose + +This validator enforces consistency between public API interfaces in the +static design (component diagram) and interfaces declared by the public API +design (class diagram). + +It shall make sure that every public API interface declared by the static design +is also declared by the public API and is connected to the SEooC boundary. + +## What is Validated + +The validator compares static design diagrams with public API design diagrams. +It receives two indexed diagram inputs: + +| Input | Source | Meaning | +|---|---|---| +| `component_diagrams` | static design component diagram FlatBuffers | Public API interface references from the static design | +| `public_api_diagrams` | public API class diagram FlatBuffers | Public API interfaces declared by the class design | + +For this validator, a public API interface is a top-level interface declared in +the static design. Interfaces declared inside the SEooC, components, or units +are treated as internal API interfaces. + +### Interface Declaration Consistency + +Every public API interface declared in the static design diagram must resolve +to an interface declared in the public API class diagram. +*(Requirement: {requirement:downstream-ref}`Tools.ComponentPublicApiInterfaceDeclarationConsistency`)* + +The component public API interface is matched against public API interface +entries derived from the public API diagram. Matching is exact and +case-sensitive. + +```text +' static design diagram +package "Sample SEooC" as sample_seooc <> { +} + +interface "Sample Library API" as SampleLibraryAPI +sample_seooc )- SampleLibraryAPI + +' public API diagram +interface "Sample Library API" as SampleLibraryAPI <> { + +GetNumber(): int +} +``` + +### SEooC Relationship Consistency + +Every public API interface declared in the static design diagram must be +connected from the SEooC in the static design diagram. +*(Requirement: {requirement:downstream-ref}`Tools.ComponentPublicApiSeoocRelationshipConsistency`)* + +This item covers the SEooC boundary relation only. The interface declaration in +the public API diagram is covered by Interface Declaration Consistency. + +```text +' static design diagram +package "Sample SEooC" as sample_seooc <> { +} + +interface "Sample Library API" as SampleLibraryAPI +sample_seooc )- SampleLibraryAPI +``` + +The validator collects relationships from SEooC entities and checks whether the +public API interface is a relation target. Relations from components or units do +not satisfy this rule. + +## Failure Cases + +| Failure case | Validation rule | +|---|---| +| Missing public API interface declaration | Interface Declaration Consistency | +| Public API interface not connected from the SEooC | SEooC Relationship Consistency | + +## Debug Output + +The validator emits debug output containing: + +- public API interfaces declared in the static design +- public API interfaces referenced by SEooC relations +- public API identifiers available from the public API diagram + +Failure messages list the public API interface IDs that are missing or not +connected from the SEooC.