WIP: REfactor

Author: MaximilianSoerenPollak

docs/how-to/dashboards_and_quality_gates.rst

@@ -380,7 +380,7 @@ Result:
    results == [10, 5]
 
 get_just_metrics(...)
-~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~
 
 Purpose
 ^^^^^^^

docs/internals/requirements/implementation_state.rst

@@ -30,14 +30,14 @@ repositories.
 .. needpie:: Overall Metrics with Total incooperated
    :labels: without any link, overall with test link, overall with code, overall fully linked
    :colors: red, yellow, blue, green
-   :filter-func: src.extensions.score_metrics.traceability_dashboard.get_metrics_with_overall_total_considered(overall_metrics:with_test_link,overall_metrics:with_code_link,overall_metrics:fully_linked)
+   :filter-func: src.extensions.score_metrics.sphinx_filter.get_metrics_with_overall_total_considered(overall_metrics:with_test_link,overall_metrics:with_code_link,overall_metrics:fully_linked)
 
 
 
 .. needpie:: Metrics without any total incooperated
    :labels: tool req with test link, tool req with code, overall fully linked
    :colors: yellow, blue, green
-   :filter-func: src.extensions.score_metrics.traceability_dashboard.get_just_metrics(metrics_by_type:tool_req:with_test_link,metrics_by_type:tool_req:with_code_link,overall_metrics:fully_linked)
+   :filter-func: src.extensions.score_metrics.sphinx_filter.get_just_metrics(metrics_by_type:tool_req:with_test_link,metrics_by_type:tool_req:with_code_link,overall_metrics:fully_linked)
 
 
 .. Jump to evidence tables:

src/extensions/score_metamodel/checks/standards.py

@@ -16,13 +16,12 @@
 # ╙                                                          ╜
 # from sphinx.application import Sphinx
 
-from sphinx_needs.need_item import NeedItem
-
 from score_metrics.sphinx_filters import (
     generic_pie_items_by_tag,
     generic_pie_items_in_relationships,
     generic_pie_linked_items,
 )
+from sphinx_needs.need_item import NeedItem
 
 # from score_metamodel import (
 #    CheckLogger,

src/extensions/score_metrics/BUILD

@@ -1,3 +1,15 @@
+# *******************************************************************************
+# 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")
@@ -36,5 +48,8 @@ score_pytest(
     srcs = glob(["tests/*.py"]),
     pytest_config = "//:pyproject.toml",
     # All requirements already in the library so no need to have it double
-    deps = [":score_metrics"],
+    deps = [
+        ":score_metrics",
+        "@score_docs_as_code//src/extensions/score_metamodel",
+    ],
 )

src/extensions/score_metrics/__init__.py

@@ -1,12 +1,24 @@
+# *******************************************************************************
+# 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
+# *******************************************************************************
 import json
 import os
 from pathlib import Path
 from typing import Any
 
-from sphinx.application import Sphinx
-from sphinx_needs import logging
 from score_metrics.traceability_metrics import calculate_full_need_metrics
+from sphinx.application import Sphinx
 from sphinx.environment import BuildEnvironment
+from sphinx_needs import logging
 
 from src.extensions.score_metrics.traceability_metrics import CALCULATED_METRICS
 
@@ -24,7 +36,7 @@
 #     )
 #     set_default_include_external(include_external)
 #
-def calculate_need_metrics(app: Sphinx, env:BuildEnvironment) -> None:
+def calculate_need_metrics(app: Sphinx, env: BuildEnvironment) -> None:
     """
     This is the single source of truth for traceability metrics. It runs
     inside the Sphinx build so it has access to all needs (local + external)
@@ -37,7 +49,7 @@ def calculate_need_metrics(app: Sphinx, env:BuildEnvironment) -> None:
     calculate_full_need_metrics(app=app, include_external=include_external)
 
 
-def _write_metrics_json(app: Sphinx, exception: Any|None) -> None:
+def _write_metrics_json(app: Sphinx, exception: Any | None) -> None:
     """
     Write a schema-v1 metrics.json alongside needs.json in the build output.
     """
@@ -71,8 +83,8 @@ def setup(app: Sphinx) -> dict[str, str | bool]:
     )
 
     # _ = app.connect("config-inited", _configure_traceability_dashboard, priority=498)
-    _ = app.connect("env-updated", calculate_need_metrics, priority=550)
-    _ = app.connect("build-finished", _write_metrics_json, priority=501)
+    _ = app.connect("env-updated", calculate_need_metrics, priority=600)
+    _ = app.connect("build-finished", _write_metrics_json, priority=550)
 
     return {
         "version": "0.1",

src/extensions/score_metrics/sphinx_filters.py

@@ -38,8 +38,10 @@ def func(needs: list[NeedItem], results: list[int], **kwargs) -> None: ...
 """
 
 from __future__ import annotations
+from typing import Any
 
 from sphinx_needs.need_item import NeedItem
+from score_metrics.traceability_metrics import CALCULATED_METRICS
 
 
 def _matches_source_selector(need: NeedItem, selector: str) -> bool:
@@ -55,15 +57,15 @@ def _matches_source_selector(need: NeedItem, selector: str) -> bool:
 
 
 def generic_pie_linked_items(
-    needs: list[NeedItem], results: list[int], **kwargs: dict[str, str | int | float]
+    needs: list[NeedItem], results: list[int], **kwargs: Any
 ) -> None:
     """Count target IDs by whether they are linked by selected source needs.
 
     Arguments are passed via ``arg1`` (target ID prefix), ``arg2`` (source
     selector prefix, matched against source ``type`` and ``id``), and ``arg3``
     (link field name, default ``complies``).
     """
-    results = []
+    results.clear()
     id_prefix = str(kwargs.get("arg1", ""))
     source_selector = str(kwargs.get("arg2", ""))
     link_field = str(kwargs.get("arg3", "complies"))
@@ -90,14 +92,15 @@ def generic_pie_linked_items(
 
 
 def generic_pie_items_by_tag(
-    needs: list[NeedItem], results: list[int], **kwargs: dict[str, str | int | float]
+    needs: list[NeedItem], results: list[int], **kwargs: Any
 ) -> None:
     """Count tagged items split by whether selected source needs link them.
 
     Arguments are passed via ``arg1`` (tag), ``arg2`` (source selector prefix,
     matched against source ``type`` and ``id``), and ``arg3`` (link field
     name, default ``complies``).
     """
+    results.clear()
     tag = str(kwargs.get("arg1", ""))
     source_selector = str(kwargs.get("arg2", ""))
     link_field = str(kwargs.get("arg3", "complies"))
@@ -124,7 +127,7 @@ def generic_pie_items_by_tag(
 
 
 def generic_pie_items_in_relationships(
-    needs: list[NeedItem], results: list[int], **kwargs: dict[str, str | int | float]
+    needs: list[NeedItem], results: list[int], **kwargs: Any
 ) -> None:
     """Count items of a given type by how many container items reference them.
 
@@ -143,6 +146,7 @@ def generic_pie_items_in_relationships(
     Appends to *results*:
     ``[not_referenced_count, referenced_once_count, referenced_multiple_count]``
     """
+    results.clear()
     container_type = str(kwargs.get("arg1", ""))
     field = str(kwargs.get("arg2", ""))
     item_type = str(kwargs.get("arg3", ""))
@@ -167,9 +171,71 @@ def generic_pie_items_in_relationships(
     results.append(referenced_multiple)
 
 
-def get_metrics_from_generated_json(
-    needs: list[NeedItem], results: list[int], **kwargs: str | int | float
+def _get_key_values(results: list[int], argument_paths: list[str]):
+    """Append integer metric values selected by colon-separated paths.
+
+    Each path is resolved against ``CALCULATED_METRICS`` (for example:
+    ``"overall_metrics:total"``), converted to ``int``, and appended to
+    ``results``.
+    """
+    metrics_json = CALCULATED_METRICS
+    for raw_path in argument_paths:
+        path = raw_path.strip()
+        if not path:
+            continue
+
+        current: Any = metrics_json
+        for key in path.split(":"):
+            current = current[key]
+
+        results.append(int(current))
+
+
+def get_metrics_with_overall_total_considered(
+    needs: list[Any], results: list[int], **kwargs: Any
+) -> None:
+    """Append selected metrics and compute remainder from overall total.
+
+    This function appends ``overall_metrics:total`` first, then appends all
+    metrics referenced by ``kwargs`` values. Finally, it replaces the first
+    appended value with the remainder after subtracting all other appended
+    values.
+    """
+    results.clear()
+    metrics_json = CALCULATED_METRICS
+    results.append(int(metrics_json["overall_metrics"]["total"]))
+    _get_key_values(results, [str(value) for value in kwargs.values()])
+    results[0] -= sum(results[1:])
+    print(results)
+
+
+def get_metrics_with_custom_type_total_considered(
+    needs: list[Any], results: list[int], **kwargs: Any
 ) -> None:
-    metrics_json_path = str(kwargs.get("arg1", "_build/metrics.json"))
-    # TODO: Read the Metrics.json and give back the data
-    results
+    """Append selected metrics, optionally using a custom total path.
+
+    If the last kwarg value ends with ``":total"``, that path is used as
+    baseline total and all preceding paths are treated as components; the first
+    result becomes ``total - sum(components)``. Otherwise, all paths are simply
+    appended as-is.
+    """
+    # Get the 'total' that was specified as the first value
+
+    results.clear()
+    values = [str(value) for value in kwargs.values()]
+    if values[-1].endswith(":total"):
+        _get_key_values(results, [values[-1]])  # baseline total
+        _get_key_values(results, values[:-1])  # components
+        results[0] -= sum(results[1:])
+    else:
+        _get_key_values(results, values)
+
+
+def get_just_metrics(needs: list[Any], results: list[int], **kwargs: Any) -> None:
+    """Append selected metric values without any total/remainder calculation.
+
+    All kwarg values are interpreted as colon-separated metric paths and
+    appended to ``results`` in insertion order.
+    """
+    results.clear()
+    _get_key_values(results, [str(value) for value in kwargs.values()])