Merge branch 'main' into feature/failure-attributes

Author: ANegm-ETAS

.gitignore

@@ -26,3 +26,4 @@ __pycache__/
 
 # bug: This file is created in repo root on test discovery.
 /consumer_test.log
+.clwb

.pre-commit-config.yaml

@@ -35,22 +35,26 @@ repos:
         language: system
         pass_filenames: false
         files: '(^|/)(MODULE\.bazel|.*\.bzl|BUILD(\.bazel)?)$'
-
-  - repo: https://github.com/rhysd/actionlint
-    rev: v1.7.11
-    hooks:
       - id: actionlint
-        args:
-          # Disable shellcheck and pyflakes for now, to enforce consistent behavior.
-          - -shellcheck=
-          - -pyflakes=
-
-  - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.15.9
-    hooks:
+        name: actionlint
+        # Disable shellcheck and pyflakes for now, to enforce consistent behavior.
+        entry: tools/run_tool.sh actionlint -shellcheck= -pyflakes=
+        language: system
+        require_serial: true
+        types: [yaml]
+        files: ^\.github/workflows/
       - id: ruff-check
-        args: [ --fix ]
+        name: ruff-check
+        entry: tools/run_tool.sh ruff check --fix
+        language: system
+        require_serial: true
+        types: [python]
       - id: ruff-format
+        name: ruff-format
+        entry: tools/run_tool.sh ruff format
+        language: system
+        require_serial: true
+        types: [python]
 
   # Note: this is super slow, therefore it is last
   - repo: local

BUILD

@@ -26,3 +26,15 @@ docs(
     ],
     source_dir = "docs",
 )
+
+# bazel run //:shellcheck
+alias(
+    name = "shellcheck",
+    actual = "@score_devcontainer//tools:shellcheck",
+)
+
+# bazel run //:actionlint
+alias(
+    name = "actionlint",
+    actual = "@score_devcontainer//tools:actionlint",
+)

MODULE.bazel

@@ -70,3 +70,6 @@ http_file(
 )
 
 bazel_dep(name = "score_process", version = "1.5.4")
+
+# Provide the tools from the devcontainer to Bazel
+bazel_dep(name = "score_devcontainer", version = "1.5.0")

MODULE.bazel.lock

@@ -125,7 +125,7 @@ def _missing_requirements(deps):
         fail(msg)
     fail("This case should be unreachable?!")
 
-def docs(source_dir = "docs", data = [], deps = [], scan_code = [], known_good = None):
+def docs(source_dir = "docs", data = [], deps = [], scan_code = [], known_good = None, metamodel = None):
     """Creates all targets related to documentation.
 
     By using this function, you'll get any and all updates for documentation targets in one place.
@@ -135,13 +135,24 @@ def docs(source_dir = "docs", data = [], deps = [], scan_code = [], known_good =
       data: Additional data files to include in the documentation build.
       deps: Additional dependencies for the documentation build.
       scan_code: List of code targets to scan for source code links.
+      known_good: Optional label to a "known good" JSON file for source links.
+      metamodel: Optional label to a metamodel.yaml file. When set, the extension loads this
+                 file instead of the default metamodel shipped with score_metamodel.
     """
 
     call_path = native.package_name()
 
     if call_path != "":
         fail("docs() must be called from the root package. Current package: " + call_path)
 
+    metamodel_data = []
+    metamodel_env = {}
+    metamodel_opts = []
+    if metamodel != None:
+        metamodel_data = [metamodel]
+        metamodel_env = {"SCORE_METAMODEL_YAML": "$(location " + str(metamodel) + ")"}
+        metamodel_opts = ["--define=score_metamodel_yaml=$(location " + str(metamodel) + ")"]
+
     module_deps = deps
     deps = deps + _missing_requirements(deps)
     deps = deps + [
@@ -152,7 +163,7 @@ def docs(source_dir = "docs", data = [], deps = [], scan_code = [], known_good =
     sphinx_build_binary(
         name = "sphinx_build",
         visibility = ["//visibility:private"],
-        data = data,
+        data = data + metamodel_data,
         deps = deps,
     )
 
@@ -187,19 +198,19 @@ def docs(source_dir = "docs", data = [], deps = [], scan_code = [], known_good =
     data_with_docs_sources = _rewrite_needs_json_to_docs_sources(data)
     additional_combo_sourcelinks = _rewrite_needs_json_to_sourcelinks(data)
     _merge_sourcelinks(name = "merged_sourcelinks", sourcelinks = [":sourcelinks_json"] + additional_combo_sourcelinks, known_good = known_good)
-    docs_data = data + [":sourcelinks_json"]
-    combo_data = data_with_docs_sources + [":merged_sourcelinks"]
+    docs_data = data + metamodel_data + [":sourcelinks_json"]
+    combo_data = data_with_docs_sources + metamodel_data + [":merged_sourcelinks"]
 
     docs_env = {
         "SOURCE_DIRECTORY": source_dir,
         "DATA": str(data),
         "SCORE_SOURCELINKS": "$(location :sourcelinks_json)",
-    }
+    } | metamodel_env
     docs_sources_env = {
         "SOURCE_DIRECTORY": source_dir,
         "DATA": str(data_with_docs_sources),
         "SCORE_SOURCELINKS": "$(location :merged_sourcelinks)",
-    }
+    } | metamodel_env
     if known_good:
         docs_env["KNOWN_GOOD_JSON"] = "$(location "+ known_good + ")"
         docs_sources_env["KNOWN_GOOD_JSON"] = "$(location "+ known_good + ")"
@@ -293,16 +304,24 @@ def docs(source_dir = "docs", data = [], deps = [], scan_code = [], known_good =
             "--jobs",
             "auto",
             "--define=external_needs_source=" + str(data),
+            "--define=score_sourcelinks_json=$(location :sourcelinks_json)",
+            "--define=score_source_code_linker_plain_links=1",
         ],
         formats = ["needs"],
         sphinx = ":sphinx_build",
-        tools = data,
+        tools = data + [":sourcelinks_json"],
         visibility = ["//visibility:public"],
         # Persistent workers cause stale symlinks after dependency version
         # changes, corrupting the Bazel cache.
         allow_persistent_workers = False,
     )
 
+    native.alias(
+        name = "traceability_gate",
+        actual = "@score_docs_as_code//scripts_bazel:traceability_gate",
+        tags = ["cli_help=Enforce traceability coverage thresholds:\nbazel run //:traceability_gate -- --metrics-json bazel-bin/needs_json/_build/needs/metrics.json"],
+    )
+
 def _sourcelinks_json(name, srcs):
     """
     Creates a target that generates a JSON file with source code links.

docs.bzl

@@ -0,0 +1,145 @@
+..
+   # *******************************************************************************
+   # 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
+   # *******************************************************************************
+
+Build Dashboards and Quality Gates
+==================================
+
+Use this guide in repositories that consume docs-as-code as a Bazel
+dependency.
+
+Goals:
+
+1. Publish traceability dashboards from repository needs.
+2. Export machine-readable metrics.
+3. Enforce CI thresholds with ``traceability_gate``.
+
+What You Get
+------------
+
+With the ``docs(...)`` macro and ``score_metamodel`` extension enabled, your
+repository can:
+
+- build an HTML dashboard from its own Sphinx needs,
+- include external needs from other repositories when desired,
+- export ``needs.json`` and ``metrics.json`` for machine-readable reporting,
+- gate CI on traceability thresholds via ``traceability_gate``.
+
+Typical Setup
+-------------
+
+For details, see :ref:`setup`.
+
+Minimal Configuration Example
+-----------------------------
+
+In ``docs/conf.py``:
+
+.. code-block:: python
+
+   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 requirements across module dependencies, such as
+integration repositories. Use ``False`` for module repositories to gate only on
+local traceability.
+
+Building the Dashboard
+----------------------
+
+After building/running any docs command (i.e. ``bazel build //:needs_json`` or ``bazel run //:docs_check`` are the fastest):
+
+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``
+
+The dashboard charts and the CI gate both use the same computed metrics.
+
+Inputs for Linkage Metrics
+--------------------------
+
+To get meaningful dashboard and gate values, consumer repositories typically
+need three inputs:
+
+1. Requirement and architecture needs in the documentation itself.
+2. Source code references via :doc:`source_to_doc_links`.
+3. Test metadata via :doc:`test_to_doc_links`.
+
+If one of those inputs is missing, the related chart or gate metric will remain
+empty or low.
+
+Choosing Local vs Aggregated Views
+----------------------------------
+
+There are two common modes:
+
+**Module repository**
+
+- Set ``score_metamodel_include_external_needs = False``.
+- Gate only on the needs owned by the repository itself.
+- Use this for per-module implementation progress and traceability.
+
+**Integration repository**
+
+- Set ``score_metamodel_include_external_needs = True``.
+- Aggregate requirements across module dependencies when that is the intended
+  repository purpose.
+- Use this for system or integration-level dashboards.
+
+CI Quality Gate
+---------------
+
+Any docs build (``bazel run //:docs``, ``bazel run //:docs_check``, etc.)
+writes ``metrics.json`` alongside the build output. Run the gate on the
+exported metrics:
+
+.. code-block:: bash
+
+   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 \
+      --min-req-fully-linked 60 \
+      --min-tests-linked 70
+
+In CI, wire targets through Bazel dependencies so test execution and
+docs generation happen before the gate target.
+
+In larger repositories, define a dedicated wrapper target for your standard
+gate thresholds so CI calls a single Bazel target.
+
+Useful flags:
+
+- ``--require-all-links`` for strict 100 percent gating
+
+Recommended Rollout
+-------------------
+
+For a new consumer repository:
+
+1. Start with local-only metrics.
+2. Enable ``scan_code`` and verify ``source_code_link`` coverage first.
+3. Add test metadata and verify ``testlink`` coverage.
+4. Introduce modest thresholds in CI.
+5. Raise thresholds over time as the repository matures.
+
+Related Guides
+--------------
+
+- :ref:`setup`
+- :doc:`other_modules`
+- :doc:`source_to_doc_links`
+- :doc:`test_to_doc_links`