feat: support filegroups in code targets

Author: AlexanderLanin

bzl/bundle_rules.bzl

@@ -75,7 +75,7 @@ CodeTargetSourcesInfo = provider(
 )
 
 def _source_files_from_attributes(ctx):
-    """Return files explicitly declared as source or header inputs by one rule."""
+    """Return files explicitly declared through source or header attributes."""
     source_files = []
     for attribute_name in ["srcs", "hdrs", "textual_hdrs"]:
         if not hasattr(ctx.rule.attr, attribute_name):
@@ -371,7 +371,7 @@ def _code_targets_sourcelinks_impl(ctx):
         for target in ctx.attr.code_targets
     ])
     if not source_files.to_list():
-        fail("code_targets must declare source files through srcs, hdrs, or textual_hdrs")
+        fail("code_targets must declare source files through filegroups, srcs, hdrs, or textual_hdrs")
 
     output = ctx.actions.declare_file(ctx.label.name + ".json")
     arguments = ctx.actions.args()

docs.bzl

@@ -79,9 +79,9 @@ def docs_bundle(name, source_dir = None, entry_doc = "index", bundles = [], scan
         }.
       scan_code: Deprecated. Explicit source files or filegroups to scan for
                  source-code links. Use `code_targets` for implementation targets.
-      code_targets: Implementation targets to scan for source-code links. Their
-                    source files and the source files of their dependencies are
-                    collected recursively.
+      code_targets: Implementation targets or filegroups to scan for source-code
+                    links. Implementation target source files and their dependencies
+                    are collected recursively; filegroups expand to their files.
       visibility: Target visibility.
       **kwargs: Additional attributes forwarded to the underlying rule.
     """
@@ -169,7 +169,9 @@ def docs(
       deps: Additional dependencies for the documentation build.
       scan_code: Deprecated. Explicit source files or filegroups to scan for source
                  code links. Use `code_targets` for implementation targets.
-      code_targets: Implementation targets to scan recursively for source code links.
+      code_targets: Implementation targets or filegroups to scan for source code
+                    links. Implementation targets are scanned recursively; filegroups
+                    expand to their files.
       test_sources: Optional list of repo-relative directory paths which will be used to filter testcases for documentation generation.
                     When empty (default), all testcases found in `bazel-testlogs` will be used.
       known_good: Optional label to a "known good" JSON file for source links.

docs/how-to/source_to_doc_links.rst

@@ -43,7 +43,7 @@ In your ``BUILD`` files, pass the implementation targets to the ``docs`` rule
 as ``code_targets``. Their ``srcs``, ``hdrs``, and ``textual_hdrs`` are scanned,
 including those of their ``deps`` recursively. This means that a
 ``cc_executable`` also covers source files from the ``cc_library`` targets it
-uses.
+uses. You may also pass filegroups; their files are scanned directly.
 
 .. code-block:: starlark
    :emphasize-lines: 14

docs/reference/bazel_macros.rst

@@ -73,12 +73,13 @@ Minimal example (root ``BUILD``)
   this function adds its own (but checks for conflicts).
 
 - ``code_targets`` (list of Bazel labels)
-  Implementation targets to scan for traceability tags (``req-Id:`` annotations).
-  Their declared ``srcs``, ``hdrs``, and ``textual_hdrs`` are collected through
-  their ``deps`` recursively. Each documentation bundle produces one cache for
-  its declared targets; Bazel reuses that cache while its inputs are unchanged.
-  The generated JSON is supplied to ``live_preview`` just like a normal
-  documentation build.
+  Implementation targets or filegroups to scan for traceability tags
+  (``req-Id:`` annotations). Implementation target ``srcs``, ``hdrs``, and
+  ``textual_hdrs`` are collected through their ``deps`` recursively; filegroups
+  expand to their files. Each documentation bundle produces one cache for its
+  declared targets; Bazel reuses that cache while its inputs are unchanged. The
+  generated JSON is supplied to ``live_preview`` just like a normal documentation
+  build.
 
 - ``scan_code`` (list of Bazel labels, deprecated)
   Explicit source files or filegroups to scan. Use ``code_targets`` for
@@ -171,11 +172,11 @@ Signature: ``docs_bundle(name, source_dir = None, entry_doc = "index", bundles =
    changing its canonical entry page.
 
 - ``code_targets`` (list of Bazel labels, optional)
-   Implementation targets whose ``srcs``, ``hdrs``, and ``textual_hdrs`` are
-   scanned for requirement tags. Sources from their ``deps`` are included
-   recursively, so declaring a ``cc_executable`` also scans the libraries it
-   uses. The bundle owns one cached scan result; Bazel only regenerates it when
-   its collected source inputs change.
+   Implementation targets or filegroups to scan for requirement tags.
+   Implementation target ``srcs``, ``hdrs``, and ``textual_hdrs`` are collected
+   recursively from their ``deps``; filegroups expand to their files. The bundle
+   owns one cached scan result; Bazel only regenerates it when its collected source
+   inputs change.
 
 - ``scan_code`` (list of Bazel labels, deprecated)
    Explicit source files or filegroups to scan. Prefer ``code_targets`` for

scripts_bazel/merge_sourcelinks.py

@@ -20,13 +20,70 @@
 import logging
 import sys
 from pathlib import Path
+from typing import cast
 
 from src.extensions.score_source_code_linker.helpers import parse_info_from_known_good
 
 logging.basicConfig(level=logging.INFO, format="%(message)s")
 logger = logging.getLogger(__name__)
 
 
+def _reference_key(reference: dict[str, object]) -> str:
+    """Return a stable, hashable representation of one source-link reference."""
+    # References are dictionaries and therefore cannot be added to ``seen`` directly.
+    # Sorting their JSON keys makes semantically identical dictionaries produce the
+    # same key even when their input key order differs.
+    return json.dumps(reference, sort_keys=True)
+
+
+def _merge_sourcelinks_file(
+    json_file: Path,
+    known_good: Path | None,
+    merged: list[dict[str, object]],
+    seen: set[str],
+) -> None:
+    """Add the unique references from one sourcelinks JSON file to ``merged``."""
+    with open(json_file, encoding="utf-8") as file:
+        data = cast(list[object], json.load(file))
+    if not data:
+        return
+
+    raw_metadata = data[0]
+    if not isinstance(raw_metadata, dict) or "repo_name" not in raw_metadata:
+        logger.warning(
+            f"Unexpected schema in sourcelinks file '{json_file}': "
+            "expected first element to be a metadata dict "
+            "with a 'repo_name' key. "
+        )
+        return
+    metadata = cast(dict[str, object], raw_metadata)
+    repo_name = metadata["repo_name"]
+    if not isinstance(repo_name, str):
+        logger.warning(
+            f"Unexpected schema in sourcelinks file '{json_file}': "
+            "expected metadata 'repo_name' to be a string. "
+        )
+        return
+
+    # A known-good file is optional for standalone builds that include
+    # documentation from external modules.  In that case, keep the metadata
+    # produced by the individual sourcelinks file.
+    if known_good and repo_name and repo_name != "local_repo":
+        hash, repo = parse_info_from_known_good(
+            known_good_json=known_good, repo_name=repo_name
+        )
+        metadata["hash"] = hash
+        metadata["url"] = repo
+
+    for raw_reference in data[1:]:
+        reference = cast(dict[str, object], raw_reference)
+        reference.update(metadata)
+        key = _reference_key(reference)
+        if key not in seen:
+            seen.add(key)
+            merged.append(reference)
+
+
 def main():
     parser = argparse.ArgumentParser(
         description="Merge multiple sourcelinks JSON files into one"
@@ -39,6 +96,7 @@ def main():
     )
     _ = parser.add_argument(
         "--known_good",
+        type=Path,
         help="Path to a required 'known good' JSON file (provided by Bazel).",
     )
     _ = parser.add_argument(
@@ -49,52 +107,15 @@ def main():
     )
 
     args = parser.parse_args()
-    all_files = [x for x in args.files if "known_good.json" not in str(x)]
-
-    merged = []
-    seen = set()
-    for json_file in all_files:
-        with open(json_file) as f:
-            data = json.load(f)
-            # If the file is empty e.g. '[]' there is nothing to parse, we continue
-            if not data:
-                continue
-            metadata = data[0]
-            if not isinstance(metadata, dict) or "repo_name" not in metadata:
-                logger.warning(
-                    f"Unexpected schema in sourcelinks file '{json_file}': "
-                    "expected first element to be a metadata dict "
-                    "with a 'repo_name' key. "
-                )
-                # As we can't deal with bad JSON structure we just skip it
-                continue
-            # A known-good file is optional for standalone builds that include
-            # documentation from external modules.  In that case, keep the
-            # metadata produced by the individual sourcelinks file.
-            if (
-                args.known_good
-                and metadata["repo_name"]
-                and metadata["repo_name"] != "local_repo"
-            ):
-                hash, repo = parse_info_from_known_good(
-                    known_good_json=args.known_good, repo_name=metadata["repo_name"]
-                )
-                metadata["hash"] = hash
-                metadata["url"] = repo
-            # In the case that 'metadata[repo_name]' is 'local_module'
-            # hash & url are already existing and empty inside of 'metadata'
-            # Therefore all 3 keys will be written to needlinks in each branch
-
-            for d in data[1:]:
-                d.update(metadata)
-            assert isinstance(data, list), repr(data)
-            for reference in data[1:]:
-                key = json.dumps(reference, sort_keys=True)
-                if key not in seen:
-                    seen.add(key)
-                    merged.append(reference)
-    with open(args.output, "w") as f:
-        json.dump(merged, f, indent=2, ensure_ascii=False)
+
+    merged: list[dict[str, object]] = []
+    seen: set[str] = set()
+    for json_file in args.files:
+        if "known_good.json" not in str(json_file):
+            _merge_sourcelinks_file(json_file, args.known_good, merged, seen)
+
+    with open(args.output, "w", encoding="utf-8") as file:
+        json.dump(merged, file, indent=2, ensure_ascii=False)
 
     logger.info(f"Merged {len(args.files)} files into {len(merged)} total references")
     return 0

src/tests/docs_bzl/scenarios/nested_bundles/BUILD

@@ -22,9 +22,22 @@ docs_bundle(
     code_targets = [
         ":example_binary",
         ":example_executable",
+        ":nested_filegroup_sources",
     ],
 )
 
+filegroup(
+    name = "filegroup_sources",
+    srcs = ["child/filegroup_source.py"],
+)
+
+# Intentionally reference the same file through a second filegroup to verify
+# that code_targets resolves nested filegroups without duplicate links.
+filegroup(
+    name = "nested_filegroup_sources",
+    srcs = [":filegroup_sources"],
+)
+
 py_binary(
     name = "example_binary",
     srcs = ["child/example.py"],

src/tests/docs_bzl/scenarios/nested_bundles/child/filegroup_source.py

@@ -0,0 +1,14 @@
+# *******************************************************************************
+# 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
+# *******************************************************************************
+
+# req-traceability: REQ_FILEGROUP

src/tests/docs_bzl/test_nested_bundles.py

@@ -53,6 +53,7 @@ def test_nested_bundles_render_and_preserve_metadata():
     assert {link["file"] for link in sourcelinks} == {
         "src/tests/docs_bzl/scenarios/nested_bundles/child/example.py",
         "src/tests/docs_bzl/scenarios/nested_bundles/child/example.cc",
+        "src/tests/docs_bzl/scenarios/nested_bundles/child/filegroup_source.py",
     }
     assert (result.build_dir / "concepts" / "example_bundle" / "index.html").is_file()
     assert (