fix: address PR #484 review comments (dashboards, implementation_state, source_linker config)

Author: FScholPer

docs/how-to/dashboards_and_quality_gates.rst

@@ -38,40 +38,10 @@ repository can:
 Typical Setup
 -------------
 
-1. Add docs-as-code as a Bazel dependency as described in :ref:`setup`.
-2. Define the documentation target via the ``docs(...)`` macro.
-3. Provide process or upstream needs via the ``data`` argument when cross-repo
-   traceability is required.
-4. Provide implementation sources via ``scan_code`` so ``source_code_link`` can
-   be generated.
-5. Add test metadata so ``testlink`` and testcase needs can be generated.
-
-Minimal Consumer Example
-------------------------
-
-In ``BUILD``:
-
-.. code-block:: starlark
-
-   load("@score_docs_as_code//:docs.bzl", "docs")
-
-   filegroup(
-       name = "module_sources",
-       srcs = glob([
-           "src/**/*.py",
-           "src/**/*.cpp",
-           "src/**/*.h",
-           "src/**/*.rs",
-       ]),
-   )
-
-   docs(
-       source_dir = "docs",
-       data = [
-           "@score_process//:needs_json",
-       ],
-       scan_code = [":module_sources"],
-   )
+For details, see :ref:`setup`.
+
+Minimal Configuration Example
+-----------------------------
 
 In ``docs/conf.py``:
 
@@ -80,54 +50,16 @@ In ``docs/conf.py``:
    score_metamodel_requirement_types = "feat_req,comp_req,aou_req"
    score_metamodel_include_external_needs = False
 
-Use ``score_metamodel_include_external_needs = True`` only in repositories that
-intentionally aggregate traceability across dependencies, such as integration
-repositories.
-
-Configuration split:
-
-**Policy (conf.py):** What needs to filter and whether to aggregate externals.
-
-**Wiring (BUILD):** Which dependencies to pull and how the build executes.
-
-Example:
-
-.. code-block:: python
-
-   # docs/conf.py — policy
-   score_metamodel_requirement_types = "feat_req,comp_req"  # What types to include
-   score_metamodel_include_external_needs = False           # Aggregate or not
-
-.. code-block:: starlark
-
-   # BUILD — wiring
-   docs(
-       source_dir = "docs",
-       data = [
-           "@score_process//:needs_json",  # Which external sources to bring in
-       ],
-       scan_code = [":module_sources"],    # Which source files to scan
-   )
+Use ``score_metamodel_include_external_needs = True`` (aggregate_traceability_across_dependencies)
+only in repositories that intentionally aggregate requirements across module dependencies, such as
+integration repositories. Use ``False`` for module repositories to gate only on local traceability.
 
 Building the Dashboard
 ----------------------
 
-Run:
-
-.. code-block:: bash
-
-   bazel run //:docs
-
-This produces the HTML output.
-
-Run:
-
-.. code-block:: bash
-
-   bazel build //:needs_json
+After building/running any docs command (i.e. ``bazel build //:needs_json`` or ``bazel run //:docs_verify`` are the fastest):
 
-In this setup, the documentation build writes ``metrics.json`` via
-``score_metamodel``, and the ``needs_json`` artifact contains:
+The documentation build writes ``metrics.json`` via ``score_metamodel``, and the ``needs_json`` artifact contains:
 
 - ``bazel-bin/needs_json/_build/needs/needs.json``
 - ``bazel-bin/needs_json/_build/needs/metrics.json``
@@ -172,7 +104,8 @@ After building ``//:needs_json``, run the gate on the exported metrics:
 
 .. code-block:: bash
 
-   bazel run @score_docs_as_code//scripts_bazel:traceability_gate -- \
+   bazel run //:docs && \
+   bazel run //:traceability_gate -- \
       --metrics-json bazel-bin/needs_json/_build/needs/metrics.json \
       --min-req-code 70 \
       --min-req-test 70 \

docs/internals/requirements/implementation_state.rst

@@ -26,7 +26,7 @@ repositories.
 Overview
 --------
 
-.. needpie:: Requirements Status
+.. needpie:: Tool Requirements Status
    :labels: not implemented, implemented but incomplete traceability, fully linked
    :colors: red,yellow, green
    :filter-func: src.extensions.score_metamodel.checks.traceability_dashboard.pie_requirements_status(tool_req)
@@ -57,8 +57,8 @@ Implementation labels used on this page:
 
 Why multiple pies are shown:
 
-- ``Requirements with Codelinks`` shows implementation-to-source traceability.
-- ``Requirements with linked tests`` shows implementation-to-verification traceability.
+- ``Requirements with Codelinks`` shows requirement-to-implementation traceability.
+- ``Requirements with linked tests`` shows requirement-to-verification traceability.
 - ``Requirements fully linked`` is the strict roll-up (both links present).
 
 These are intentionally separate because they answer different diagnostics:

docs/internals/requirements/index.rst

@@ -18,7 +18,7 @@ Requirements
 This repository provides the docs-as-code tooling used by other SCORE
 repositories. The pages in this section therefore focus on two questions:
 
-1. Which process and tool requirements are covered by the docs-as-code tooling?
+1. Which process requirements are covered by the docs-as-code tooling?
 2. How is the tooling itself verified and qualified for downstream use?
 
 Actual product and module traceability is expected to live in consuming

docs/reference/commands.md

@@ -8,10 +8,10 @@
 
 | Target                                         | What it does                                                                                      |
 | ---------------------------------------------- | ------------------------------------------------------------------------------------------------- |
-| `bazel run //:docs`                            | Builds documentation (also writes `metrics.json`)               |
+| `bazel run //:docs`                            | Builds documentation (also writes `metrics.json` via the score_metamodel extension)               |
 | `bazel run //:docs_check`                      | Verifies documentation correctness                                                                |
 | `bazel run //:docs_combo`                      | Builds combined documentation with all external dependencies included                             |
-| `bazel run @score_docs_as_code//scripts_bazel:traceability_gate -- --metrics-json bazel-bin/needs_json/_build/needs/metrics.json --min-req-code 100 --min-req-test 100 --min-req-fully-linked 100 --min-tests-linked 100 --fail-on-broken-test-refs` | Reads the pre-computed metrics.json from the docs build and fails if coverage thresholds are not met |
+| `bazel run //:traceability_gate -- --metrics-json bazel-bin/needs_json/_build/needs/metrics.json --min-req-code 70 --min-req-test 70 --min-req-fully-linked 60 --min-tests-linked 70` | Reads the pre-computed metrics.json and fails if coverage thresholds are not met                   |
 | `bazel run //:live_preview`                    | Creates a live_preview of the documentation viewable in a local server                            |
 | `bazel run //:live_preview_combo_experimental` | Creates a live_preview of the full documentation with all dependencies viewable in a local server |
 | `bazel run //:ide_support`                     | Sets up a Python venv for esbonio (Remember to restart VS Code!)                                  |

src/extensions/score_source_code_linker/__init__.py

@@ -310,6 +310,10 @@ def setup_once(app: Sphinx):
         assert find_git_root()
 
     # Register & Run (if needed) parsing & saving of JSON caches
+    # Note: This extension now runs on both internal and external needs_json invocations.
+    # Both modes aggregate links from local sources and external dependencies, enabling
+    # unified traceability reporting in integration repositories. Impact on external needs
+    # invocations is minimal since they typically don't have local test logs or source code.
     setup_source_code_linker(app, ws_root)
     register_test_code_linker(app)
     register_combined_linker(app)
@@ -322,13 +326,28 @@ def setup_once(app: Sphinx):
 def setup(app: Sphinx) -> dict[str, str | bool]:
     # Esbonio will execute setup() on every iteration.
     # setup_once will only be called once.
-    app.add_config_value("KNOWN_GOOD_JSON", default="", rebuild="env", types=str)
-    app.add_config_value("score_sourcelinks_json", default="", rebuild="env", types=str)
+
+    # Config values for source code linking and testcase metadata integration
+    app.add_config_value(
+        "KNOWN_GOOD_JSON",
+        default="",
+        rebuild="env",
+        types=str,
+        description="Path to pre-generated source code links JSON (optional fallback)"
+    )
+    app.add_config_value(
+        "score_sourcelinks_json",
+        default="",
+        rebuild="env",
+        types=str,
+        description="Path to pre-generated source code links JSON from Bazel via SCORE_SOURCELINKS env var"
+    )
     app.add_config_value(
         "score_source_code_linker_plain_links",
         default=False,
         rebuild="env",
         types=bool,
+        description="If True, render links as plain text without GitHub URLs (useful for Bazel sandbox builds)"
     )
     setup_once(app)