refactor: expose bundle target metadata

bzl/bundle_rules.bzl

@@ -38,7 +38,10 @@ load("@score_docs_as_code//:bzl/basics.bzl", "join_path")
 DocsBundleInfo = provider(
     doc = "A documentation bundle with its source and placement metadata.",
     fields = {
-        "entries": "Ordered entries, one per source directory, including its final documentation-tree location.",
+        # Each entry carries the source and placement information needed by
+        # the runtime manifest, plus the identity and direct-target metadata
+        # of the bundle that declared it.
+        "entries": "Ordered entries with source, placement, and direct-target metadata.",
         "own_source_files": "This bundle's direct source files, excluding nested bundles.",
         "source_dir_execroot_path": "Execution-root-relative path of this bundle's direct source root.",
         "sourcelinks": "Source-code-link JSON files together with their owning repository.",
@@ -53,6 +56,7 @@ CodeTargetSourcesInfo = provider(
     doc = "Source files collected from an implementation target and its dependencies.",
     fields = {
         "sources": "Depset of direct and transitive source files.",
+        "kind": "Bazel rule kind of the selected code target.",
     },
 )
 
@@ -82,6 +86,10 @@ def _collect_code_target_sources_impl(target, ctx):
             direct = _source_files_from_attributes(ctx),
             transitive = dependency_sources,
         ),
+        # The aspect follows dependencies to collect source files, but the
+        # manifest needs the kind of the target explicitly selected by the
+        # bundle rather than the kinds of those transitive dependencies.
+        kind = ctx.rule.kind,
     )]
 
 _collect_code_target_sources = aspect(
@@ -216,10 +224,15 @@ def _rebase_bundle_entry(entry, mount_at, attach_to):
     bundle's aggregate data would associate the same file with unrelated
     mounts, so the mounts resolver could select the wrong destination.
     """
-    is_bundle_root = not entry.mount_at
-    if is_bundle_root:
+    if not entry.mount_at:
+        # The child bundle's own root has not been placed below the parent yet.
+        # Its default attachment is therefore the parent directory's index;
+        # an explicit attach_to still overrides that default.
         rebased_attach_to = attach_to or _parent_index_docname(mount_at)
     else:
+        # This entry is already below another location in the child bundle.
+        # Keep its attachment relative to that location and prefix the whole
+        # placement with the mount point chosen by the parent.
         rebased_attach_to = join_path(mount_at, entry.attach_to)
 
     return struct(
@@ -236,6 +249,16 @@ def _rebase_bundle_entry(entry, mount_at, attach_to):
         # Preserve the explicit file allowlist when the entry is rebased.
         files = entry.files,
         data = entry.data,
+        # Rebasing changes only placement. Keep the declaring bundle identity
+        # and direct targets attached to the source entry as it moves through
+        # the composition graph.
+        bundle_label = entry.bundle_label,
+        bundle_name = entry.bundle_name,
+        code_targets = entry.code_targets,
+        # This entry is now part of a parent composition. It may have been the
+        # root of its own standalone bundle, but it is a child entry here and
+        # must be handled as a mounted source rather than as the parent's root.
+        root_bundle = False,
     )
 
 def _entries_visible_through(ctx, child):
@@ -283,6 +306,15 @@ def _docs_bundle_impl(ctx):
     source_dir_execroot_path = ""
     own_external_runfiles = []
     own_data = depset(direct = ctx.files.data)
+    own_bundle_label = str(ctx.label)
+    own_bundle_name = ctx.label.name
+    own_code_targets = [
+        struct(
+            label = str(target.label),
+            type = target[CodeTargetSourcesInfo].kind,
+        )
+        for target in ctx.attr.code_targets
+    ]
 
     # The macro validates this combination before creating the rule; retain
     # the rule-level check for callers of the internal helper as well.
@@ -310,6 +342,13 @@ def _docs_bundle_impl(ctx):
             # Directory mounts discover all supported files below this root.
             files = [],
             data = own_data,
+            bundle_label = own_bundle_label,
+            bundle_name = own_bundle_name,
+            # This direct entry belongs to the current composition's root
+            # bundle. _rebase_bundle_entry changes this to false if a parent
+            # embeds the bundle as a child.
+            root_bundle = True,
+            code_targets = own_code_targets,
         ))
         own_source_files.extend(ctx.files.source_dir_globbed)
         # Local sources are read directly from the workspace by ``bazel run``.
@@ -342,6 +381,13 @@ def _docs_bundle_impl(ctx):
             # original source root and therefore visits only declared files.
             files = source_files,
             data = own_data,
+            bundle_label = own_bundle_label,
+            bundle_name = own_bundle_name,
+            # This direct entry belongs to the current composition's root
+            # bundle. _rebase_bundle_entry changes this to false if a parent
+            # embeds the bundle as a child.
+            root_bundle = True,
+            code_targets = own_code_targets,
         ))
         own_source_files.extend(ctx.files.source_targets)
         # Explicit artifacts outside the workspace source tree need to be
@@ -363,6 +409,13 @@ def _docs_bundle_impl(ctx):
             # Pure-data entries have no documentation source allowlist.
             files = [],
             data = own_data,
+            bundle_label = own_bundle_label,
+            bundle_name = own_bundle_name,
+            # This direct entry belongs to the current composition's root
+            # bundle. _rebase_bundle_entry changes this to false if a parent
+            # embeds the bundle as a child.
+            root_bundle = True,
+            code_targets = own_code_targets,
         ))
 
     child_source_files = []
@@ -427,6 +480,9 @@ _docs_bundle = rule(
         "bundle_mount_ats": attr.string_list(),
         "bundle_attach_tos": attr.string_list(),
         "data": attr.label_list(allow_files = True),
+        # The aspect preserves the selected target's rule kind while
+        # recursively collecting its source files for source-link generation.
+        "code_targets": attr.label_list(aspects = [_collect_code_target_sources]),
     },
     doc = "Internal rule that carries bundle files and their documentation-tree locations.",
 )
@@ -440,6 +496,7 @@ def create_bundle(
     source_dir = None,
     entry_doc = "index",
     data = [],
+    code_targets = [],
     visibility = None,
     **kwargs):
     """Create a bundle from directory-discovered files and source targets.
@@ -459,6 +516,7 @@ def create_bundle(
         bundle_mount_ats = [bundle.mount_at for bundle in parsed_bundles],
         bundle_attach_tos = [bundle.attach_to for bundle in parsed_bundles],
         data = data,
+        code_targets = code_targets,
         visibility = visibility,
         **kwargs
     )

bzl/mount_rules.bzl

@@ -16,8 +16,8 @@ Conversion of documentation bundles from Bazel into mount metadata.
 
 load("@score_docs_as_code//:bzl/bundle_rules.bzl", "DocsBundleInfo")
 
-def _mounts_manifest_impl(ctx):
-    """Generate the canonical Sphinx mount manifest."""
+def _composition_manifest_impl(ctx):
+    """Generate the bundle composition manifest."""
     bundle_info = ctx.attr.bundle[DocsBundleInfo]
     entries = bundle_info.entries
 
@@ -35,6 +35,22 @@ def _mounts_manifest_impl(ctx):
             # tree rather than a workspace or external-repository directory.
             "generated": entry.generated,
             "data": [f.path for f in entry.data.to_list()],
+            # Keep identity and direct-target metadata in the same manifest as
+            # placement so all runtime consumers use one composition snapshot.
+            "root_bundle": entry.root_bundle,
+            "bundle": {
+                "label": entry.bundle_label,
+                "name": entry.bundle_name,
+                # Each direct target contributes its Bazel label and rule kind
+                # to the bundle metadata consumed by Python.
+                "code_targets": [
+                    {
+                        "label": target.label,
+                        "type": target.type,
+                    }
+                    for target in entry.code_targets
+                ],
+            },
         }
         # Explicit source targets are mounted as a file allowlist. Directory
         # bundles omit this key and retain the existing recursive behavior.
@@ -46,18 +62,19 @@ def _mounts_manifest_impl(ctx):
     ctx.actions.write(out, json.encode({"mounts": json_mounts}))
     return [DefaultInfo(files = depset([out]))]
 
-_create_mounts_manifest = rule(
-    implementation = _mounts_manifest_impl,
+_composition_manifest = rule(
+    implementation = _composition_manifest_impl,
     attrs = {
         "bundle": attr.label(providers = [DocsBundleInfo]),
     },
-    doc = "Writes a Sphinx mount manifest from reusable documentation bundles.",
+    doc = "Writes the composition consumed by runtime documentation tools.",
 )
 
-def create_mounts_manifest(name, bundle):
-    """Create a Sphinx mount manifest from reusable documentation bundles."""
-    _create_mounts_manifest(
+def create_composition_manifest(name, bundle, visibility = None):
+    """Create a common mount and bundle-metadata manifest."""
+    _composition_manifest(
         name = name,
         bundle = bundle,
+        visibility = visibility,
     )
     return ":" + name

docs.bzl

@@ -65,7 +65,7 @@ load(
 )
 load(
     "@score_docs_as_code//:bzl/mount_rules.bzl",
-    "create_mounts_manifest",
+    "create_composition_manifest",
 )
 # Keep the low-level action behind this name so this macro owns the shared
 # Sphinx policy while ``needs_rules.bzl`` owns Bazel's input/output plumbing.
@@ -306,6 +306,7 @@ def _declare_docs_bundle(
         entry_doc = entry_doc,
         bundles = bundles,
         data = bundle_data,
+        code_targets = code_targets,
         visibility = visibility,
         **kwargs
     )
@@ -554,19 +555,6 @@ def docs(
     # list-valued attributes such as ``data`` and ``tools``.
     metamodel_label = [metamodel] if metamodel else []
 
-    mounts_manifest = None
-    if bundles:
-        mounts_bundle = create_bundle(
-            name = "_docs_mounts",
-            bundles = bundles,
-            visibility = ["//visibility:private"],
-        )
-        mounts_manifest = create_mounts_manifest(
-            name = "_mounts_manifest",
-            bundle = mounts_bundle,
-        )
-    mounts_manifest_label = [mounts_manifest] if mounts_manifest else []
-
     deps = _sphinx_deps(deps)
     deps = deps + [
         Label("//src:plantuml_for_python"),
@@ -587,6 +575,13 @@ def docs(
         visibility = ["//visibility:public"],
         tags = ["manual"]
     )
+    # The runtime manifest must be generated from the actual root bundle. The
+    # root entry carries the project's direct code_targets and gives Python a
+    # complete composition snapshot alongside the nested mounts.
+    mounts_manifest = create_composition_manifest(
+        name = "_mounts_manifest",
+        bundle = ":docs_bundle",
+    )
     _declare_bundle_local_needs(
         name = "docs_bundle",
         source_dir_globbed = root_bundle.source_dir_globbed,
@@ -616,7 +611,7 @@ def docs(
     docs_data = (
         data + external_needs + metamodel_label +
         [":sourcelinks_json", ":_external_docs_runfiles"] +
-        mounts_manifest_label
+        [mounts_manifest]
     )
     if config_is_generated:
         # A source configuration is read from the workspace; only the

src/docs_cli/cli.py

@@ -111,6 +111,13 @@ def add_watch_dir(path: Path) -> None:
             watch_dirs.append(path_string)
 
     for spec in manifest.mounts:
+        # The root entry describes the primary source tree already passed to
+        # Sphinx. It is present so Python receives complete bundle metadata,
+        # but it is not an additional external mount for live preview. In
+        # particular, its data paths are action inputs and must not be
+        # reinterpreted as generated files below bazel-bin.
+        if spec.root_bundle:
+            continue
         # A data-only bundle has no source directory. Passing its empty
         # ``src_root`` to resolve_walk_dir would watch the workspace root,
         # which makes sphinx-autobuild observe unrelated files (including its

src/docs_cli/dirty_build_test.py

@@ -177,16 +177,56 @@ def test_mounted_watch_dirs_match_sphinx_mount_paths(tmp_path: Path) -> None:
         json.dumps(
             {
                 "mounts": [
+                    {
+                        "src_root": "primary/docs",
+                        "runtime_path": "primary/docs",
+                        "mount_at": "",
+                        "attach_to": "",
+                        "entry_doc": "index",
+                        "external": False,
+                        "repository": "",
+                        "generated": False,
+                        "data": ["bazel-out/k8-fastbuild/bin/primary/generated.rst"],
+                        "root_bundle": True,
+                        "bundle": {
+                            "label": "@@//:root_bundle",
+                            "name": "root_bundle",
+                            "code_targets": [],
+                        },
+                    },
                     {
                         "src_root": "extensions/local/docs",
                         "runtime_path": "extensions/local/docs",
                         "mount_at": "local",
+                        "attach_to": "",
+                        "entry_doc": "index",
+                        "external": False,
+                        "repository": "",
+                        "generated": False,
+                        "data": [],
+                        "root_bundle": False,
+                        "bundle": {
+                            "label": "@@//:local_bundle",
+                            "name": "local_bundle",
+                            "code_targets": [],
+                        },
                     },
                     {
                         "src_root": "external/vendor+/docs",
                         "runtime_path": "../vendor+/docs",
                         "mount_at": "external",
+                        "attach_to": "",
+                        "entry_doc": "index",
                         "external": True,
+                        "repository": "vendor+",
+                        "generated": False,
+                        "data": [],
+                        "root_bundle": False,
+                        "bundle": {
+                            "label": "@@vendor+//:docs_bundle",
+                            "name": "docs_bundle",
+                            "code_targets": [],
+                        },
                     },
                 ]
             }
@@ -214,7 +254,18 @@ def test_mounted_watch_dirs_use_data_directories_for_pure_data_bundles(
                         "src_root": "",
                         "runtime_path": "__data__/pkg/data_bundle",
                         "mount_at": "generated",
+                        "attach_to": "",
+                        "entry_doc": "index",
+                        "external": False,
+                        "repository": "",
+                        "generated": False,
                         "data": ["bazel-out/k8-fastbuild/bin/pkg/generated/index.rst"],
+                        "root_bundle": False,
+                        "bundle": {
+                            "label": "@@//:data_bundle",
+                            "name": "data_bundle",
+                            "code_targets": [],
+                        },
                     }
                 ]
             }

src/docs_cli/main_test.py

@@ -11,6 +11,7 @@
 # SPDX-License-Identifier: Apache-2.0
 # *******************************************************************************
 
+import json
 from pathlib import Path
 from unittest.mock import Mock
 
@@ -163,7 +164,29 @@ def test_live_preview_uses_port_and_bundle_watches(
     monkeypatch.setenv("ACTION", "live_preview")
     manifest = workspace / "runfiles/mounts.json"
     manifest.write_text(
-        '{"mounts": [{"src_root": "extra/docs", "runtime_path": "extra/docs", "mount_at": "extra"}]}'
+        json.dumps(
+            {
+                "mounts": [
+                    {
+                        "src_root": "extra/docs",
+                        "runtime_path": "extra/docs",
+                        "mount_at": "extra",
+                        "attach_to": "",
+                        "entry_doc": "index",
+                        "external": False,
+                        "repository": "",
+                        "generated": False,
+                        "data": [],
+                        "root_bundle": False,
+                        "bundle": {
+                            "label": "@@//:extra_bundle",
+                            "name": "extra_bundle",
+                            "code_targets": [],
+                        },
+                    }
+                ]
+            }
+        )
     )
     monkeypatch.setenv("MOUNTS_MANIFEST", "mounts.json")
     autobuild = Mock()