WIP: Enable saving of metrics to global var

Author: MaximilianSoerenPollak

docs/conf.py

@@ -10,6 +10,7 @@
 #
 # SPDX-License-Identifier: Apache-2.0
 # *******************************************************************************
+import matplotlib
 
 project = "Score Docs-as-Code"
 project_url = "https://eclipse-score.github.io/docs-as-code/"
@@ -18,3 +19,4 @@
 extensions = [
     "score_sphinx_bundle",
 ]
+matplotlib.rcParamsDefault["savefig.bbox"] = "tight"

docs/how-to/dashboards_and_quality_gates.rst

@@ -151,6 +151,296 @@ For a new consumer repository:
 4. Introduce modest thresholds in CI.
 5. Raise thresholds over time as the repository matures.
 
+..
+ ╓                                                           ╖
+ ║ .. The Following part has been generated by Copilot       ║
+ ╙                                                           ╜
+
+Metrics Needpie functions
+=========================
+
+Overview
+--------
+
+These helpers read values from a nested dictionary named ``CALCULATED_METRICS``.
+A metric is selected by a **colon-separated path**, for example:
+
+- ``overall_metrics:total``
+- ``overall_metrics:with_test_link``
+- ``types:bug:total``
+
+All resolved values are converted to ``int`` and appended to a mutable
+``results`` list passed by the caller.
+
+The ``needs`` parameter is accepted for integration compatibility, but it is not
+used by the current implementations.
+
+Path format
+-----------
+
+Paths are split using ``:`` and then resolved step by step.
+
+Example:
+
+.. code-block:: text
+
+   path = "overall_metrics:total"
+
+is resolved like:
+
+.. code-block:: python
+
+   current = CALCULATED_METRICS
+   current = current["overall_metrics"]
+   current = current["total"]
+
+Function reference
+------------------
+
+_get_key_values(results, argument_paths)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Purpose
+^^^^^^^
+
+Internal helper that appends metric values for a list of paths.
+
+Behavior
+^^^^^^^^
+
+1. Iterate over each item in ``argument_paths``.
+2. Strip whitespace.
+3. Skip empty paths.
+4. Resolve the path inside ``CALCULATED_METRICS``.
+5. Convert to integer and append to ``results``.
+
+Notes
+^^^^^
+
+- Modifies ``results`` in place.
+- Does not return a new list.
+- Raises ``KeyError`` if a path key does not exist.
+- Raises ``ValueError`` if a resolved value cannot be converted to ``int``.
+
+get_metrics_with_overall_total_considered(...)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Purpose
+^^^^^^^
+
+Compute a remainder against global overall total.
+
+Behavior
+^^^^^^^^
+
+1. Append ``CALCULATED_METRICS["overall_metrics"]["total"]`` as first value.
+2. Append each metric referenced by ``kwargs.values()``.
+3. Replace the first value with:
+
+   ``overall_total - sum(all other appended values)``
+
+Typical use case
+^^^^^^^^^^^^^^^^
+
+Use this when your pie/chart needs an "Other" bucket based on the global total.
+
+Example
+^^^^^^^
+
+Assume:
+
+.. code-block:: python
+
+   CALCULATED_METRICS = {
+       "overall_metrics": {
+           "total": 100,
+           "with_test_link": 30,
+           "with_review": 20,
+       }
+   }
+
+Call:
+
+.. code-block:: python
+
+   results = []
+   get_metrics_with_overall_total_considered(
+       needs=[],
+       results=results,
+       a="overall_metrics:with_test_link",
+       b="overall_metrics:with_review",
+   )
+
+Result:
+
+.. code-block:: python
+
+   # Step 1 append total: [100]
+   # Step 2 append selected: [100, 30, 20]
+   # Step 3 remainder:       [50, 30, 20]
+   results == [50, 30, 20]
+
+get_metrics_with_custom_type_total_considered(...)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Purpose
+^^^^^^^
+
+Support custom total path if provided as the last kwarg value.
+
+Behavior
+^^^^^^^^
+
+If the **last** provided path ends with ``:total``:
+
+1. Append that last path as baseline total.
+2. Append all preceding paths as components.
+3. Replace the first value with:
+
+   ``baseline_total - sum(components)``
+
+Otherwise:
+
+- Append all provided paths directly (no subtraction).
+
+Important ordering rule
+^^^^^^^^^^^^^^^^^^^^^^^
+
+The special total path must be the **last** kwarg value, for example:
+
+.. code-block:: python
+
+   get_metrics_with_custom_type_total_considered(
+       needs=[],
+       results=results,
+       part_a="types:feature:done",
+       part_b="types:feature:in_progress",
+       total="types:feature:total",  # must be last
+   )
+
+Example with custom total
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Assume:
+
+.. code-block:: python
+
+   CALCULATED_METRICS = {
+       "types": {
+           "feature": {
+               "total": 40,
+               "done": 10,
+               "in_progress": 5,
+           }
+       }
+   }
+
+Call:
+
+.. code-block:: python
+
+   results = []
+   get_metrics_with_custom_type_total_considered(
+       needs=[],
+       results=results,
+       done="types:feature:done",
+       in_progress="types:feature:in_progress",
+       total="types:feature:total",
+   )
+
+Result:
+
+.. code-block:: python
+
+   # baseline total: 40
+   # components: 10, 5
+   # remainder: 40 - (10 + 5) = 25
+   results == [25, 10, 5]
+
+Example without custom total
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Call:
+
+.. code-block:: python
+
+   results = []
+   get_metrics_with_custom_type_total_considered(
+       needs=[],
+       results=results,
+       done="types:feature:done",
+       in_progress="types:feature:in_progress",
+   )
+
+Result:
+
+.. code-block:: python
+
+   # no subtraction mode
+   results == [10, 5]
+
+get_just_metrics(...)
+~~~~~~~~~~~~~~~~~~~~
+
+Purpose
+^^^^^^^
+
+Append only the selected metric values.
+
+Behavior
+^^^^^^^^
+
+- Interprets each kwarg value as a path.
+- Resolves and appends each value.
+- No total baseline and no remainder calculation.
+
+Example
+^^^^^^^
+
+.. code-block:: python
+
+   results = []
+   get_just_metrics(
+       needs=[],
+       results=results,
+       a="overall_metrics:with_test_link",
+       b="overall_metrics:with_review",
+   )
+   # results might become [30, 20]
+
+How to use these functions correctly
+------------------------------------
+
+1. Pass a mutable list in ``results`` (usually ``[]`` initially).
+2. Provide metric paths through keyword argument values.
+3. Use colon-separated keys (``a:b:c``), not dot notation.
+4. For custom-total mode, ensure the total path is the last kwarg value.
+5. Expect in-place mutation of ``results``.
+
+Common pitfalls
+---------------
+
+- Empty kwargs in custom-total function can lead to index errors
+  (because ``values[-1]`` is accessed).
+- Invalid paths raise ``KeyError``.
+- Non-integer values raise ``ValueError`` during ``int(...)`` conversion.
+- ``print(results)`` currently causes side effects during execution; remove if
+  quiet behavior is preferred in production.
+
+Testing recommendations
+-----------------------
+
+Add unit tests for:
+
+- Basic path resolution with one and multiple paths.
+- Whitespace and empty-path handling.
+- Overall total remainder logic.
+- Custom total behavior when last path ends with ``:total``.
+- Behavior when no custom total is provided.
+- Error handling for missing keys and non-integer values.
+- Empty ``kwargs`` behavior in custom-total function.
+
+
 Related Guides
 --------------
 

docs/internals/requirements/implementation_state.rst

@@ -27,11 +27,19 @@ repositories.
 .. --------
 ..
 
-.. needpie:: Tool Requirements Status
-   :labels: total, linked with code
-   :colors: blue, yellow
-   :filter-func: src.extensions.score_metrics.traceability_dashboard.get_linked_metrics_for_type(_build/metrics,overall_metrics:total;overall_metrics:with_test_link)
-..
+.. 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)
+
+
+
+.. 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)
+
+
 .. Jump to evidence tables:
 ..
 .. - :ref:`Tool Requirement Implementation and Links table <tooling_coverage_table_impl_links>`