From ca18effe5a8551821e294c322d4800773974d9ee Mon Sep 17 00:00:00 2001 From: "frank.scholter_peres" Date: Thu, 23 Jul 2026 14:52:21 +0000 Subject: [PATCH 1/2] Add machine-readable module inspection record need type Adds the mod_insp need type to the metamodel with evidence and inspects extra links, documents the tool requirement, and adds option tests. Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> --- docs/internals/requirements/requirements.rst | 19 +++++ src/extensions/score_metamodel/metamodel.yaml | 43 ++++++++++ .../test_options_inspection_record.rst | 82 +++++++++++++++++++ 3 files changed, 144 insertions(+) create mode 100644 src/extensions/score_metamodel/tests/rst/options/test_options_inspection_record.rst diff --git a/docs/internals/requirements/requirements.rst b/docs/internals/requirements/requirements.rst index cec3ee611..751f16011 100644 --- a/docs/internals/requirements/requirements.rst +++ b/docs/internals/requirements/requirements.rst @@ -867,6 +867,25 @@ Testing * allow links to covered artifacts via ``covers`` * allow links to backing documents or work products via ``evidence`` and ``realizes`` +.. tool_req:: Support machine-readable inspection records + :id: tool_req__docs_inspection_record_need + :tags: Verification Evidence + :implemented: YES + :version: 1 + :satisfies: gd_req__verification_checks + :parent_covered: NO: process wording defines verification checks, while the tool models a first-class inspection record artifact. + + Docs-as-Code shall support a machine-readable inspection record need type. + + The need type shall: + + * use ``mod_insp`` as directive type + * classify the inspection by ``inspection_type`` and ``inspection_state`` + * record the checklist reference and reviewer list via ``checklist_ref`` and ``reviewers`` + * link the inspection to the verified module via ``belongs_to`` + * link the inspected artifacts via ``inspects`` + * allow links to backing evidence via ``evidence`` + 🧪 Tool Verification Reports ############################ diff --git a/src/extensions/score_metamodel/metamodel.yaml b/src/extensions/score_metamodel/metamodel.yaml index 606632156..794e36150 100644 --- a/src/extensions/score_metamodel/metamodel.yaml +++ b/src/extensions/score_metamodel/metamodel.yaml @@ -970,6 +970,46 @@ needs_types: - verification_report parts: 3 + # Formal inspection evidence modeled as a first-class artifact. + # req-Id: tool_req__docs_inspection_record_need + mod_insp: + title: Module Inspection Record + prefix: mod_insp__ + mandatory_options: + # req-Id: tool_req__docs_common_attr_safety + safety: ^(QM|ASIL_B)$ + # req-Id: tool_req__docs_common_attr_security + security: ^(YES|NO)$ + # req-Id: tool_req__docs_common_attr_status + status: ^(valid|invalid)$ + # req-Id: tool_req__docs_inspection_record_need + inspection_type: ^(requirements|architecture|implementation|traceability|safety_analysis|security_analysis|other)$ + inspection_state: ^(planned|in_review|rework_required|approved)$ + checklist_ref: ^.*$ + reviewers: ^.*$ + optional_options: + checklist_type: ^(req|arc|impl|safety|security|custom)$ + moderator: ^.*$ + approver: ^.*$ + findings_total: ^[0-9]+$ + findings_open: ^[0-9]+$ + pr_link: ^https://github\.com/[^/]+/[^/]+/pull/\d+$ + correction_issue: ^https://github\.com/[^/]+/[^/]+/issues/\d+$ + inspection_date: ^[0-9]{4}-[0-9]{2}-[0-9]{2}$ + mandatory_links: + # req-Id: tool_req__docs_inspection_record_need + belongs_to: mod + inspects: ANY + optional_links: + # req-Id: tool_req__docs_inspection_record_need + contains: ANY + evidence: ANY + approved_by: role + supported_by: role + tags: + - inspection + - verification_evidence + parts: 3 # https://eclipse-score.github.io/process_description/main/permalink.html?id=gd_temp__change_decision_record dec_rec: @@ -1109,6 +1149,9 @@ needs_extra_links: incoming: evidence_for outgoing: evidence + inspects: + incoming: inspected_by + outgoing: inspects ############################################################## # Graph Checks diff --git a/src/extensions/score_metamodel/tests/rst/options/test_options_inspection_record.rst b/src/extensions/score_metamodel/tests/rst/options/test_options_inspection_record.rst new file mode 100644 index 000000000..a9f5f65d3 --- /dev/null +++ b/src/extensions/score_metamodel/tests/rst/options/test_options_inspection_record.rst @@ -0,0 +1,82 @@ +.. + # ******************************************************************************* + # 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 + # ******************************************************************************* +#CHECK: check_options + + +.. Base architecture and requirement objects used by inspection record tests + +.. feat:: Inspection Feature + :id: feat__inspection_feature + :security: YES + :safety: ASIL_B + :status: valid + +.. comp:: Inspection Component + :id: comp__inspection_component + :security: YES + :safety: ASIL_B + :status: valid + :belongs_to: feat__inspection_feature + +.. mod:: Inspection Module + :id: mod__inspection_module + :security: YES + :safety: ASIL_B + :status: valid + :includes: comp__inspection_component + +.. comp_req:: Inspection Requirement + :id: comp_req__inspection__sample + :reqtype: Functional + :security: YES + :safety: ASIL_B + :status: valid + + Requirement text for inspection record tests. + + +.. Valid machine-readable inspection record need +#EXPECT-NOT[+2]: does not follow pattern + +.. mod_insp:: Inspection Record Valid + :id: mod_insp__inspection__valid + :safety: ASIL_B + :security: YES + :status: valid + :inspection_type: requirements + :inspection_state: approved + :checklist_ref: gd_chklst__req_inspection + :reviewers: reviewer_a,reviewer_b + :checklist_type: req + :findings_total: 1 + :findings_open: 0 + :inspection_date: 2026-06-24 + :belongs_to: mod__inspection_module + :inspects: comp_req__inspection__sample + + +.. Invalid inspection_state value in module inspection record +#EXPECT[+2]: mod_insp__inspection__bad_state.inspection_state (approved_late): does not follow pattern + +.. mod_insp:: Inspection Record Invalid State + :id: mod_insp__inspection__bad_state + :safety: ASIL_B + :security: YES + :status: invalid + :inspection_type: architecture + :inspection_state: approved_late + :checklist_ref: gd_chklst__arch_inspection_checklist + :reviewers: reviewer_a + :belongs_to: mod__inspection_module + :inspects: comp_req__inspection__sample From 91fc8185964299f7fa1a552bcf03f3c44cda73bd Mon Sep 17 00:00:00 2001 From: "frank.scholter_peres" Date: Mon, 3 Aug 2026 09:05:47 +0000 Subject: [PATCH 2/2] Address review: slim down mod_insp inspection record attributes Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> --- src/extensions/score_metamodel/metamodel.yaml | 10 +--------- .../rst/options/test_options_inspection_record.rst | 6 ++---- 2 files changed, 3 insertions(+), 13 deletions(-) diff --git a/src/extensions/score_metamodel/metamodel.yaml b/src/extensions/score_metamodel/metamodel.yaml index 794e36150..a6f9e68db 100644 --- a/src/extensions/score_metamodel/metamodel.yaml +++ b/src/extensions/score_metamodel/metamodel.yaml @@ -983,32 +983,24 @@ needs_types: # req-Id: tool_req__docs_common_attr_status status: ^(valid|invalid)$ # req-Id: tool_req__docs_inspection_record_need - inspection_type: ^(requirements|architecture|implementation|traceability|safety_analysis|security_analysis|other)$ + inspection_type: ^(requirements|architecture|implementation)$ inspection_state: ^(planned|in_review|rework_required|approved)$ checklist_ref: ^.*$ reviewers: ^.*$ optional_options: - checklist_type: ^(req|arc|impl|safety|security|custom)$ moderator: ^.*$ approver: ^.*$ - findings_total: ^[0-9]+$ - findings_open: ^[0-9]+$ - pr_link: ^https://github\.com/[^/]+/[^/]+/pull/\d+$ - correction_issue: ^https://github\.com/[^/]+/[^/]+/issues/\d+$ - inspection_date: ^[0-9]{4}-[0-9]{2}-[0-9]{2}$ mandatory_links: # req-Id: tool_req__docs_inspection_record_need belongs_to: mod inspects: ANY optional_links: # req-Id: tool_req__docs_inspection_record_need - contains: ANY evidence: ANY approved_by: role supported_by: role tags: - inspection - - verification_evidence parts: 3 # https://eclipse-score.github.io/process_description/main/permalink.html?id=gd_temp__change_decision_record diff --git a/src/extensions/score_metamodel/tests/rst/options/test_options_inspection_record.rst b/src/extensions/score_metamodel/tests/rst/options/test_options_inspection_record.rst index a9f5f65d3..fbd9b7255 100644 --- a/src/extensions/score_metamodel/tests/rst/options/test_options_inspection_record.rst +++ b/src/extensions/score_metamodel/tests/rst/options/test_options_inspection_record.rst @@ -58,10 +58,8 @@ :inspection_state: approved :checklist_ref: gd_chklst__req_inspection :reviewers: reviewer_a,reviewer_b - :checklist_type: req - :findings_total: 1 - :findings_open: 0 - :inspection_date: 2026-06-24 + :moderator: moderator_a + :approver: approver_a :belongs_to: mod__inspection_module :inspects: comp_req__inspection__sample