From 8b32c8082380f5e75acea99a1b90d0b99cd8a451 Mon Sep 17 00:00:00 2001 From: "frank.scholter_peres" Date: Thu, 25 Jun 2026 14:12:21 +0000 Subject: [PATCH 1/2] docs: update tool requirement status for 7 implemented requirements Update implementation status from NO/PARTIAL to YES for tool requirements that are already enforced in code (metamodel.yaml + check_options.py): - tool_req__docs_saf_attrs_content: content mandatory_options on all safety types - tool_req__docs_saf_attrs_violates: violates mandatory_links on all safety types - tool_req__docs_saf_attr_fmea_fault_id: fault_id mandatory_options on FMEA types - tool_req__docs_saf_attr_dfa_failure_id: failure_id mandatory_options on DFA types - tool_req__docs_req_attr_validity_correctness: regex validation in metamodel.yaml - tool_req__docs_req_attr_validity_consistency: check_validity_consistency local check - tool_req__docs_doc_generic_mandatory: all attrs enforced as mandatory_options/links Each updated requirement now includes a :source_code_link: to the corresponding implementation file and an Implementation note. Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> --- docs/internals/requirements/requirements.rst | 73 ++++++++++++++------ 1 file changed, 52 insertions(+), 21 deletions(-) diff --git a/docs/internals/requirements/requirements.rst b/docs/internals/requirements/requirements.rst index edfa719a4..e6d228c6d 100644 --- a/docs/internals/requirements/requirements.rst +++ b/docs/internals/requirements/requirements.rst @@ -303,13 +303,14 @@ Versioning .. tool_req:: Mandatory attributes of Generic Documents :id: tool_req__docs_doc_generic_mandatory :tags: Documents - :implemented: PARTIAL - :version: 2 + :implemented: YES + :version: 3 :satisfies: gd_req__doc_attributes_manual, gd_req__change_attr_impact_safety, gd_req__doc_attr_status, :parent_covered: YES + :source_code_link: https://github.com/eclipse-score/docs-as-code/blob/main/src/extensions/score_metamodel/metamodel.yaml Enforce that each Generic Document ``doc__*`` has the following attributes: @@ -318,6 +319,10 @@ Versioning * safety * realizes + Implementation: All four attributes are enforced in ``metamodel.yaml`` — + ``status``, ``safety``, and ``security`` as ``mandatory_options`` with regex + validation, and ``realizes`` as ``mandatory_links`` to ``workproduct``. + .. tool_req:: Mandatory Document attributes :id: tool_req__docs_doc_attr :tags: Documents @@ -492,30 +497,38 @@ Versioning .. tool_req:: Enforce validity attribute correctness :id: tool_req__docs_req_attr_validity_correctness :tags: Requirements - :implemented: PARTIAL - :version: 1 + :implemented: YES + :version: 2 :parent_covered: YES :satisfies: gd_req__req_validity :status: valid + :source_code_link: https://github.com/eclipse-score/docs-as-code/blob/main/src/extensions/score_metamodel/metamodel.yaml Docs-as-Code shall enforce that the ``valid_from`` and ``valid_until`` attributes of stakeholder and feature requirements are correct. The format of a milestone is something like "v0.5" or "v1.0.1". No suffixes like "-SNAPSHOT" or "-beta" are allowed. + Implementation: Regex validation ``^v(0|[1-9]\d*)\.(0|[1-9]\d*)(\.( 0|[1-9]\d*))?$`` is enforced + as optional_options on ``stkh_req`` and ``feat_req`` types in ``metamodel.yaml``. + .. tool_req:: Enforce validity start is before end :id: tool_req__docs_req_attr_validity_consistency :tags: Requirements - :implemented: PARTIAL - :version: 1 + :implemented: YES + :version: 2 :parent_covered: YES :satisfies: gd_req__req_validity :status: valid + :source_code_link: https://github.com/eclipse-score/docs-as-code/blob/main/src/extensions/score_metamodel/checks/check_options.py Docs-as-Code shall enforce that ``valid_from`` is before ``valid_until`` attribute in stakeholder and feature requirements. We consider "from" is inclusive but "until" is exclusive, so from v0.5 until v1.0 means valid for v0.5 but not for v1.0. If either attribute is missing, no check is performed. + Implementation: ``check_validity_consistency`` local check in ``check_options.py`` + parses milestones and verifies ``valid_from < valid_until``. + ------------------------- 🔗 Links @@ -1073,73 +1086,91 @@ Testing .. tool_req:: Safety Analysis Mandatory Content :id: tool_req__docs_saf_attrs_content - :implemented: NO + :implemented: YES :tags: Safety Analysis - :version: 1 + :version: 2 :satisfies: gd_req__saf_argument :parent_covered: NO + :source_code_link: https://github.com/eclipse-score/docs-as-code/blob/main/src/extensions/score_metamodel/metamodel.yaml Docs-As-Code shall enforce needs of type :need:`tool_req__docs_saf_types` to have a non empty content. + Implementation: ``content: ^[\s\S]+$`` is defined as ``mandatory_options`` for + ``feat_saf_dfa``, ``comp_saf_dfa``, ``feat_saf_fmea``, and ``comp_saf_fmea`` + in ``metamodel.yaml``. The ``validate_options()`` function in ``check_options.py`` + enforces this at build time. + .. tool_req:: Safety Analysis Linkage Violates :id: tool_req__docs_saf_attrs_violates - :implemented: NO + :implemented: YES :tags: Safety Analysis - :version: 1 + :version: 2 :satisfies: gd_req__saf_linkage_check, gd_req__saf_linkage, gd_req__sec_linkage_check, :parent_covered: YES + :source_code_link: https://github.com/eclipse-score/docs-as-code/blob/main/src/extensions/score_metamodel/metamodel.yaml Docs-As-Code shall enforce that needs of type :need:`tool_req__docs_saf_types` have a `violates` links to at least one dynamic / static diagram according to the table. + Implementation: ``violates`` is defined as ``mandatory_links`` for all safety analysis + types in ``metamodel.yaml``. The ``validate_links()`` function in ``check_options.py`` + enforces the link is present and targets the correct type. .. table:: :widths: auto - ============= =================== + ============= ========================== Link Source Allowed Link Target - ============= =================== + ============= ========================== feat_saf_dfa feat_arc_sta comp_saf_dfa comp_arc_sta - feat_saf_fmea feat_arc_dyn - comp_saf_fmea comp_arc_dyn - ============= =================== + feat_saf_fmea feat_arc_dyn, feat_arc_sta + comp_saf_fmea comp_arc_dyn, comp_arc_sta + ============= ========================== .. tool_req:: FMEA: fault id attribute :id: tool_req__docs_saf_attr_fmea_fault_id - :implemented: NO + :implemented: YES :tags: Safety Analysis - :version: 1 + :version: 2 :satisfies: gd_req__saf_attr_fault_id :parent_covered: NO + :source_code_link: https://github.com/eclipse-score/docs-as-code/blob/main/src/extensions/score_metamodel/metamodel.yaml - Docs-As-Code shall enforce that needs of type DFA (see + Docs-As-Code shall enforce that needs of type FMEA (see :need:`tool_req__docs_saf_types`) have a `fault_id` attribute. Allowed values are listed as ID in tables at :need:`gd_guidl__dfa_failure_initiators`. + Implementation: ``fault_id: ^.*$`` is defined as ``mandatory_options`` for + ``feat_saf_fmea`` and ``comp_saf_fmea`` in ``metamodel.yaml``. + .. tool_req:: DFA: failure id attribute :id: tool_req__docs_saf_attr_dfa_failure_id - :implemented: NO + :implemented: YES :tags: Safety Analysis - :version: 1 + :version: 2 :satisfies: gd_req__saf_attr_failure_id :parent_covered: NO + :source_code_link: https://github.com/eclipse-score/docs-as-code/blob/main/src/extensions/score_metamodel/metamodel.yaml Docs-As-Code shall enforce that needs of type DFA (see - :need:`tool_req__docs_saf_types`) have a `fault_id` attribute. + :need:`tool_req__docs_saf_types`) have a `failure_id` attribute. Allowed values are listed as ID in tables at :need:`gd_guidl__dfa_failure_initiators`. + Implementation: ``failure_id: ^.*$`` is defined as ``mandatory_options`` for + ``feat_saf_dfa`` and ``comp_saf_dfa`` in ``metamodel.yaml``. + .. tool_req:: Failure Effect :id: tool_req__docs_saf_attr_fmea_failure_effect From a998bd35de7a4f05cd520d8c0e2260f9bcad956b Mon Sep 17 00:00:00 2001 From: "frank.scholter_peres" Date: Thu, 25 Jun 2026 14:21:16 +0000 Subject: [PATCH 2/2] docs: add line-specific source code links for implemented requirements Update :source_code_link: fields to point to specific line numbers in metamodel.yaml and check_options.py. Add inline RST hyperlinks in implementation notes so readers can click through to the exact code. Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> --- docs/internals/requirements/requirements.rst | 53 +++++++++++++------- 1 file changed, 36 insertions(+), 17 deletions(-) diff --git a/docs/internals/requirements/requirements.rst b/docs/internals/requirements/requirements.rst index e6d228c6d..fc843b4db 100644 --- a/docs/internals/requirements/requirements.rst +++ b/docs/internals/requirements/requirements.rst @@ -310,7 +310,7 @@ Versioning gd_req__change_attr_impact_safety, gd_req__doc_attr_status, :parent_covered: YES - :source_code_link: https://github.com/eclipse-score/docs-as-code/blob/main/src/extensions/score_metamodel/metamodel.yaml + :source_code_link: https://github.com/eclipse-score/docs-as-code/blob/main/src/extensions/score_metamodel/metamodel.yaml#L207-L223 Enforce that each Generic Document ``doc__*`` has the following attributes: @@ -319,7 +319,8 @@ Versioning * safety * realizes - Implementation: All four attributes are enforced in ``metamodel.yaml`` — + Implementation: All four attributes are enforced in + `metamodel.yaml L207-L223 `_ — ``status``, ``safety``, and ``security`` as ``mandatory_options`` with regex validation, and ``realizes`` as ``mandatory_links`` to ``workproduct``. @@ -502,15 +503,19 @@ Versioning :parent_covered: YES :satisfies: gd_req__req_validity :status: valid - :source_code_link: https://github.com/eclipse-score/docs-as-code/blob/main/src/extensions/score_metamodel/metamodel.yaml + :source_code_link: https://github.com/eclipse-score/docs-as-code/blob/main/src/extensions/score_metamodel/metamodel.yaml#L273 Docs-as-Code shall enforce that the ``valid_from`` and ``valid_until`` attributes of stakeholder and feature requirements are correct. The format of a milestone is something like "v0.5" or "v1.0.1". No suffixes like "-SNAPSHOT" or "-beta" are allowed. - Implementation: Regex validation ``^v(0|[1-9]\d*)\.(0|[1-9]\d*)(\.( 0|[1-9]\d*))?$`` is enforced - as optional_options on ``stkh_req`` and ``feat_req`` types in ``metamodel.yaml``. + Implementation: Regex validation ``^v(0|[1-9]\d*)\.(0|[1-9]\d*)(\.(0|[1-9]\d*))?$`` is enforced + as ``optional_options`` on ``stkh_req`` + (`L273 `_) + and ``feat_req`` + (`L311 `_) + in ``metamodel.yaml``. .. tool_req:: Enforce validity start is before end :id: tool_req__docs_req_attr_validity_consistency @@ -520,13 +525,14 @@ Versioning :parent_covered: YES :satisfies: gd_req__req_validity :status: valid - :source_code_link: https://github.com/eclipse-score/docs-as-code/blob/main/src/extensions/score_metamodel/checks/check_options.py + :source_code_link: https://github.com/eclipse-score/docs-as-code/blob/main/src/extensions/score_metamodel/checks/check_options.py#L283-L307 Docs-as-Code shall enforce that ``valid_from`` is before ``valid_until`` attribute in stakeholder and feature requirements. We consider "from" is inclusive but "until" is exclusive, so from v0.5 until v1.0 means valid for v0.5 but not for v1.0. If either attribute is missing, no check is performed. - Implementation: ``check_validity_consistency`` local check in ``check_options.py`` + Implementation: ``check_validity_consistency`` local check in + `check_options.py L283-L307 `_ parses milestones and verifies ``valid_from < valid_until``. @@ -1091,14 +1097,18 @@ Testing :version: 2 :satisfies: gd_req__saf_argument :parent_covered: NO - :source_code_link: https://github.com/eclipse-score/docs-as-code/blob/main/src/extensions/score_metamodel/metamodel.yaml + :source_code_link: https://github.com/eclipse-score/docs-as-code/blob/main/src/extensions/score_metamodel/metamodel.yaml#L709 Docs-As-Code shall enforce needs of type :need:`tool_req__docs_saf_types` to have a non empty content. Implementation: ``content: ^[\s\S]+$`` is defined as ``mandatory_options`` for - ``feat_saf_dfa``, ``comp_saf_dfa``, ``feat_saf_fmea``, and ``comp_saf_fmea`` - in ``metamodel.yaml``. The ``validate_options()`` function in ``check_options.py`` + ``feat_saf_dfa`` (`L709 `_), + ``comp_saf_dfa`` (`L736 `_), + ``feat_saf_fmea`` (`L764 `_), and + ``comp_saf_fmea`` (`L791 `_) + in ``metamodel.yaml``. The ``validate_options()`` function in + `check_options.py `_ enforces this at build time. @@ -1113,13 +1123,18 @@ Testing gd_req__saf_linkage, gd_req__sec_linkage_check, :parent_covered: YES - :source_code_link: https://github.com/eclipse-score/docs-as-code/blob/main/src/extensions/score_metamodel/metamodel.yaml + :source_code_link: https://github.com/eclipse-score/docs-as-code/blob/main/src/extensions/score_metamodel/metamodel.yaml#L710 Docs-As-Code shall enforce that needs of type :need:`tool_req__docs_saf_types` have a `violates` links to at least one dynamic / static diagram according to the table. - Implementation: ``violates`` is defined as ``mandatory_links`` for all safety analysis - types in ``metamodel.yaml``. The ``validate_links()`` function in ``check_options.py`` + Implementation: ``violates`` is defined as ``mandatory_links`` for + ``feat_saf_dfa`` (`L710 `_), + ``comp_saf_dfa`` (`L740 `_), + ``feat_saf_fmea`` (`L768 `_), and + ``comp_saf_fmea`` (`L795 `_) + in ``metamodel.yaml``. The ``validate_links()`` function in + `check_options.py `_ enforces the link is present and targets the correct type. .. table:: @@ -1143,7 +1158,7 @@ Testing :version: 2 :satisfies: gd_req__saf_attr_fault_id :parent_covered: NO - :source_code_link: https://github.com/eclipse-score/docs-as-code/blob/main/src/extensions/score_metamodel/metamodel.yaml + :source_code_link: https://github.com/eclipse-score/docs-as-code/blob/main/src/extensions/score_metamodel/metamodel.yaml#L758 Docs-As-Code shall enforce that needs of type FMEA (see :need:`tool_req__docs_saf_types`) have a `fault_id` attribute. @@ -1151,7 +1166,9 @@ Testing Allowed values are listed as ID in tables at :need:`gd_guidl__dfa_failure_initiators`. Implementation: ``fault_id: ^.*$`` is defined as ``mandatory_options`` for - ``feat_saf_fmea`` and ``comp_saf_fmea`` in ``metamodel.yaml``. + ``feat_saf_fmea`` (`L758 `_) + and ``comp_saf_fmea`` (`L785 `_) + in ``metamodel.yaml``. .. tool_req:: DFA: failure id attribute @@ -1161,7 +1178,7 @@ Testing :version: 2 :satisfies: gd_req__saf_attr_failure_id :parent_covered: NO - :source_code_link: https://github.com/eclipse-score/docs-as-code/blob/main/src/extensions/score_metamodel/metamodel.yaml + :source_code_link: https://github.com/eclipse-score/docs-as-code/blob/main/src/extensions/score_metamodel/metamodel.yaml#L702 Docs-As-Code shall enforce that needs of type DFA (see :need:`tool_req__docs_saf_types`) have a `failure_id` attribute. @@ -1169,7 +1186,9 @@ Testing Allowed values are listed as ID in tables at :need:`gd_guidl__dfa_failure_initiators`. Implementation: ``failure_id: ^.*$`` is defined as ``mandatory_options`` for - ``feat_saf_dfa`` and ``comp_saf_dfa`` in ``metamodel.yaml``. + ``feat_saf_dfa`` (`L702 `_) + and ``comp_saf_dfa`` (`L730 `_) + in ``metamodel.yaml``. .. tool_req:: Failure Effect