Feat/centralize verification metrics

docs/how-to/dashboards_and_quality_gates.rst

@@ -76,6 +76,21 @@ The documentation build writes ``metrics.json`` via ``score_metrics``, and the `
 
 The dashboard charts and the CI gate both use the same computed metrics.
 
+``metrics.json`` Content
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+The exported file contains a versioned set of fields:
+
+- ``schema_version`` – schema version identifier.
+- ``generated_by`` – identifier of the producer that generated this file.
+- ``overall_metrics`` – requirement coverage aggregated over all requirement types.
+- ``metrics_by_type`` – the same coverage numbers per requirement type.
+- ``tests`` – testcase linkage statistics, including broken test references.
+- ``verification_metrics`` – per-component verification status and coverage metrics
+  for use by verification reports. Contains status distribution (valid, valid_inspected,
+  invalid) and test coverage (fully_covered, partially_covered, not_covered) for
+  both requirements and architecture elements, organized by component ID.
+
 Inputs for Linkage Metrics
 --------------------------
 

scripts_bazel/traceability_metrics_schema.json

@@ -40,6 +40,17 @@
     },
     "tests": {
       "$ref": "#/$defs/testMetrics"
+    },
+    "verification_metrics": {
+      "type": "object",
+      "description": "Per-component verification status and coverage metrics for verification reports.",
+      "additionalProperties": {
+        "$ref": "#/$defs/componentVerificationMetrics"
+      },
+      "propertyNames": {
+        "type": "string",
+        "minLength": 1
+      }
     }
   },
   "$defs": {
@@ -134,6 +145,67 @@
       "type": "number",
       "minimum": 0,
       "maximum": 100
+    },
+    "componentVerificationMetrics": {
+      "type": "object",
+      "description": "Verification metrics for a single component.",
+      "additionalProperties": false,
+      "properties": {
+        "requirements": {
+          "$ref": "#/$defs/statusAndCoverageMetrics"
+        },
+        "architecture": {
+          "$ref": "#/$defs/statusAndCoverageMetrics"
+        }
+      }
+    },
+    "statusAndCoverageMetrics": {
+      "type": "object",
+      "description": "Status distribution and test coverage metrics.",
+      "additionalProperties": false,
+      "properties": {
+        "status": {
+          "type": "object",
+          "description": "Count by status value.",
+          "additionalProperties": false,
+          "properties": {
+            "valid": {
+              "type": "integer",
+              "minimum": 0
+            },
+            "valid_inspected": {
+              "type": "integer",
+              "minimum": 0
+            },
+            "invalid": {
+              "type": "integer",
+              "minimum": 0
+            }
+          }
+        },
+        "coverage": {
+          "type": "object",
+          "description": "Test coverage by verification links.",
+          "additionalProperties": false,
+          "properties": {
+            "fully_covered": {
+              "type": "integer",
+              "minimum": 0,
+              "description": "Items with fully_verifies_back link."
+            },
+            "partially_covered": {
+              "type": "integer",
+              "minimum": 0,
+              "description": "Items with only partially_verifies_back link."
+            },
+            "not_covered": {
+              "type": "integer",
+              "minimum": 0,
+              "description": "Items with no verification links."
+            }
+          }
+        }
+      }
     }
   }
 }

src/extensions/score_metrics/BUILD

@@ -39,6 +39,7 @@ py_library(
     # TODO: Figure out if all requirements are needed or if we can break it down a bit
     deps = all_requirements + [
         "@score_docs_as_code//src/helper_lib",
+        "@score_docs_as_code//src/extensions/score_sphinx_needs_templates",
     ],
 )
 

src/extensions/score_metrics/sphinx_filters.py

@@ -42,8 +42,35 @@ def func(needs: list[NeedItem], results: list[int], **kwargs) -> None: ...
 from typing import Any
 
 from score_metrics.traceability_metrics import CALCULATED_METRICS
+
+# Import the public version-scoping helper for filtering by valid_from
+from score_sphinx_needs_templates import req_in_report_version
 from sphinx_needs.need_item import NeedItem
 
+# Import shared verification metrics helpers
+from src.helper_lib.verification_metrics import (
+    count_coverage_filtered,
+    count_status_filtered,
+)
+
+
+def _arg(kwargs: dict[str, Any], name: str, default: str = "") -> str:
+    """Return a filter-func argument without surrounding whitespace and quotes.
+
+    sphinx-needs splits the argument string on ``,`` and passes the parts
+    verbatim, so ``f("a", "b")`` arrives as ``'"a"'`` and ``' "b"'``.
+    """
+    return str(kwargs.get(name, default)).strip().strip("\"'")
+
+
+def _version_arg(kwargs: dict[str, Any]) -> str | None:
+    """Return ``arg3`` as a version, with ``_`` turned back into ``.``.
+
+    sphinx-needs resolves the module with ``rsplit(".", 1)`` over the whole
+    call, so a version such as ``v1.0`` must be passed as ``v1_0``.
+    """
+    return _arg(kwargs, "arg3").replace("_", ".") or None
+
 
 def _matches_source_selector(need: NeedItem, selector: str) -> bool:
     """Return whether a need matches a source selector.
@@ -247,3 +274,69 @@ def get_non_overlapping_link_metrics(
     only_code = with_code - fully
 
     results.extend([remaining, only_test, only_code, fully])
+
+
+def get_component_status_metrics(
+    needs: list[Any], results: list[int], **kwargs: Any
+) -> None:
+    """Get status distribution for a component's requirements or architecture.
+
+    Arguments are passed via ``arg1`` .. ``arg4``:
+        - ``arg1`` – component_id: The component ID (e.g., "comp__my_component")
+        - ``arg2`` – category: Either "requirements" or "architecture"
+        - ``arg3`` – version: Optional, see :func:`_version_arg`
+        - ``arg4`` – safety: Optional safety class, e.g. ``ASIL_B`` or ``QM``
+
+    Returns ``[valid, valid_inspected, invalid]`` without a safety class,
+    ``[valid_inspected, valid, invalid]`` for an ASIL class and
+    ``[valid, invalid]`` for ``QM``, where ``valid_inspected`` counts as
+    ``valid`` because QM Needs are not formally inspected.
+    """
+    results.clear()
+    safety = _arg(kwargs, "arg4") or None
+    status = count_status_filtered(
+        needs,
+        _arg(kwargs, "arg1"),
+        _arg(kwargs, "arg2", "requirements"),
+        _version_arg(kwargs),
+        req_in_report_version,
+        safety,
+    )
+
+    if safety == "QM":
+        results.extend([status["valid"] + status["valid_inspected"], status["invalid"]])
+    elif safety:
+        results.extend([status["valid_inspected"], status["valid"], status["invalid"]])
+    else:
+        results.extend([status["valid"], status["valid_inspected"], status["invalid"]])
+
+
+def get_component_coverage_metrics(
+    needs: list[Any], results: list[int], **kwargs: Any
+) -> None:
+    """Get verification coverage for a component's requirements or architecture.
+
+    Uses the verification coverage axis (fully_verifies_back / partially_verifies_back),
+    not the link coverage axis (testlink / source_code_link).
+
+    Arguments are the same as for :func:`get_component_status_metrics`.
+
+    Returns [fully_covered, partially_covered, not_covered].
+    """
+    results.clear()
+    coverage = count_coverage_filtered(
+        needs,
+        _arg(kwargs, "arg1"),
+        _arg(kwargs, "arg2", "requirements"),
+        _version_arg(kwargs),
+        req_in_report_version,
+        _arg(kwargs, "arg4") or None,
+    )
+
+    results.extend(
+        [
+            coverage["fully_covered"],
+            coverage["partially_covered"],
+            coverage["not_covered"],
+        ]
+    )