refactor(module-verification-report): split, tests, docs

src/extensions/docs/index.rst

@@ -70,6 +70,14 @@ Extensions
       Architecture and design of the ``score_mounts`` bridge extension.
       :ref:`Mounts Extension Internals<score_mounts_internals>`
 
+   .. grid-item-card::
+
+      Module Verification Report
+      ^^^
+      The ``.. module-verification-report::`` directive that expands
+      into the standard per-module verification report body.
+      :ref:`Module Verification Report<module_verification_report>`
+
 
 .. toctree::
    :maxdepth: 1
@@ -81,3 +89,4 @@ Extensions
    Extension Guide <extension_guide>
    Sync TOML <sync_toml>
    mounts_internals
+   module_verification_report

src/extensions/docs/module_verification_report.rst

@@ -0,0 +1,112 @@
+..
+   # *******************************************************************************
+   # 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
+   # *******************************************************************************
+
+.. _module_verification_report:
+
+Module Verification Report extension
+====================================
+
+``score_module_verification_report`` provides the
+``.. module-verification-report::`` directive, which expands into the
+standard per-module verification report: a feature summary, a component
+overview table, and one detailed section per component. Traceability is
+resolved by sphinx-needs at render time — the directive only emits
+``.. needtable::`` / ``.. needpie::`` widgets with the right filters.
+
+The extension is part of the :ref:`score_sphinx_bundle<extensions>`.
+No external config file is required for the common case.
+
+Typical usage (``verification_report/module_verification_report.rst``):
+
+.. code-block:: rst
+
+   .. module-verification-report::
+      :module-id: mod__mymodule
+      :components: comp__mymodule_a, comp__mymodule_b
+
+.. _mvr_directive:
+
+Options
+-------
+
+.. list-table::
+   :header-rows: 1
+   :widths: 22 12 66
+
+   * - Option
+     - Required
+     - Description
+
+   * - ``:module-id:``
+     - yes
+     - sphinx-needs id of the ``.. mod::`` need (e.g. ``mod__mymodule``).
+       Drives defaults for ``:feature-id:`` and ``:component-prefix:``.
+
+   * - ``:components:``
+     - yes
+     - Comma-separated list of ``.. comp::`` need ids. Multi-line values
+       are supported. Optional ``[version==N]`` qualifiers are stripped.
+
+   * - ``:feature-id:``
+     - no
+     - sphinx-needs id of the ``.. feat::`` need. Default:
+       ``feat__<module-short>`` (derived from ``:module-id:``).
+
+   * - ``:component-prefix:``
+     - no
+     - Prefix stripped from each component id to derive its slug (used
+       for section headings and document-id matching). Default:
+       ``comp__<module-short>_``.
+
+   * - ``:safety:``
+     - yes
+     - ASIL classification of the module. One of ``QM`` or ``ASIL_B``.
+
+   * - ``:security:``
+     - yes
+     - Whether the module is security-relevant. One of ``YES`` or ``NO``.
+
+   * - ``:status:``
+     - yes
+     - Review status of the report. One of ``valid`` or ``invalid``.
+
+   * - ``:verification-method:``
+     - yes
+     - Free-text description of how the module was verified, e.g.
+       ``test_and_inspection``.
+
+   * - ``:version:``
+     - no
+     - Version of the emitted ``mod_ver_report`` need. Default: ``1``.
+
+Metamodel validation
+--------------------
+
+``:safety:``, ``:security:``, ``:status:``, ``:verification-method:`` and
+``:version:`` are not just directive options — the directive uses them to
+emit a single sphinx-needs ``mod_ver_report`` need (id
+``mod_vrep__<module-short>__report``, linked ``belongs_to`` the module's
+``.. mod::`` need). This need type, its id format and the allowed values
+for each option are declared in ``score_metamodel``'s ``metamodel.yaml``
+(``mod_ver_report`` entry).
+
+Every generated need is checked against that definition by the
+``score_metamodel`` Sphinx extension as part of the regular build. If any
+value does not match the expected pattern (e.g. ``:safety: ASIL_D``, which
+is not one of ``QM``/``ASIL_B``), a mandatory option is missing, or the id
+does not follow the required ``<prefix>__<abbreviation>__<element>``
+scheme, ``score_metamodel`` reports a warning. Since the documentation
+build runs Sphinx with ``-W`` (warnings treated as errors), any such
+mismatch aborts the build instead of silently producing an inconsistent
+report.

src/extensions/score_module_verification_report/BUILD

@@ -0,0 +1,52 @@
+# *******************************************************************************
+# 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
+# *******************************************************************************
+load("@aspect_rules_py//py:defs.bzl", "py_library")
+load("@docs_as_code_hub_env//:requirements.bzl", "all_requirements")
+load("//:score_pytest.bzl", "score_pytest")
+
+filegroup(
+    name = "sources",
+    srcs = glob(["*.py"]),
+)
+
+filegroup(
+    name = "tests",
+    srcs = glob(["tests/*.py"]),
+)
+
+filegroup(
+    name = "all_sources",
+    srcs = [
+        ":sources",
+        ":tests",
+    ],
+    visibility = ["//visibility:public"],
+)
+
+py_library(
+    name = "score_module_verification_report",
+    srcs = [":sources"],
+    imports = ["."],
+    visibility = ["//visibility:public"],
+    deps = all_requirements + [
+        "@score_docs_as_code//src/helper_lib",
+    ],
+)
+
+score_pytest(
+    name = "score_module_verification_report_tests",
+    size = "small",
+    srcs = glob(["tests/*.py"]),
+    deps = [":score_module_verification_report"],
+    pytest_config = "//:pyproject.toml",
+)

src/extensions/score_module_verification_report/__init__.py

@@ -0,0 +1,77 @@
+# *******************************************************************************
+# 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
+# *******************************************************************************
+"""Sphinx extension that generates the per-module verification report body.
+
+Usage in RST::
+
+    .. module-verification-report::
+       :module-id: mod__baselibs
+       :feature-id: feat__baselibs
+       :safety: ASIL_B
+       :security: YES
+       :status: valid
+       :verification-method: test_and_inspection
+       :components: comp__baselibs_json,
+                    comp__baselibs_bit_manipulation,
+                    comp__baselibs_containers
+
+``safety``/``security``/``status``/``verification-method`` are the
+mandatory options of the sphinx-needs ``mod_ver_report`` need type (see
+metamodel.yaml). The directive emits one such need
+(``belongs_to: module-id``) so the report is machine-readable and its
+links are validated by score_metamodel's generic need-link checks —
+not just rendered RST.
+
+Implementation is split across:
+
+* :mod:`.templates`   — RST templates + default workproduct lists + CSS
+* :mod:`.rendering`   — template expansion / report body assembly
+* :mod:`.directive`   — the ``ModuleVerificationReportDirective`` class
+* :mod:`.consistency_checks` — ``build-finished`` validation that every
+  component is properly linked in the needs graph
+
+Testcase back-links rendered by this directive are annotated with a
+``(passed)`` / ``(failed)`` result badge by
+``score_source_code_linker``'s ``doctree-resolved`` hook, not by this
+extension.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from .consistency_checks import (
+    check_consistency,
+    init_registry,
+    merge_registry,
+    purge_registry,
+)
+from .directive import ModuleVerificationReportDirective
+
+
+def setup(app: Any) -> dict:
+    app.add_directive("module-verification-report", ModuleVerificationReportDirective)
+    app.add_config_value(
+        "mvr_coverage_lcov",
+        "bazel-out/_coverage/_coverage_report.dat",
+        "env",
+    )
+    app.connect("env-before-read-docs", init_registry)
+    app.connect("env-purge-doc", purge_registry)
+    app.connect("env-merge-info", merge_registry)
+    app.connect("build-finished", check_consistency)
+    return {
+        "version": "0.9",
+        "parallel_read_safe": True,
+        "parallel_write_safe": True,
+    }