[rules score] clean up deps in sphinx build

Author: hoe-jo

bazel/rules/rules_score/private/architectural_design.bzl

@@ -174,7 +174,6 @@ def _architectural_design_impl(ctx):
         SphinxSourcesInfo(
             srcs = sphinx_srcs,
             deps = sphinx_srcs,
-            ancillary = depset(),
         ),
     ]
 

bazel/rules/rules_score/private/assumptions_of_use.bzl

@@ -89,7 +89,6 @@ def _assumptions_of_use_impl(ctx):
         SphinxSourcesInfo(
             srcs = all_srcs,
             deps = depset(transitive = transitive),
-            ancillary = depset(),
         ),
     ]
 

bazel/rules/rules_score/private/component.bzl

@@ -207,7 +207,6 @@ def _component_impl(ctx):
         SphinxSourcesInfo(
             srcs = req_sphinx_depset,
             deps = sphinx_depset,
-            ancillary = depset(),
         ),
     ]
 

bazel/rules/rules_score/private/dependability_analysis.bzl

@@ -30,23 +30,21 @@ load("//bazel/rules/rules_score/private:lobster_config.bzl", "format_lobster_sou
 # Private Helpers
 # ============================================================================
 
-def _collect_analysis_providers(sa, rst_srcs_list, rst_deps_list, rst_ancillary_list, lobster_files):
+def _collect_analysis_providers(sa, rst_srcs_list, rst_deps_list, lobster_files):
     """Collect analysis providers from a single sub-analysis target.
 
     Updates the provided lists/dicts in-place.
 
     Args:
-        sa:                  A sub-analysis target (fmea or security).
-        rst_srcs_list:       List of depsets to extend with SphinxSourcesInfo.srcs.
-        rst_deps_list:       List of depsets to extend with SphinxSourcesInfo.deps.
-        rst_ancillary_list:  List of depsets to extend with SphinxSourcesInfo.ancillary.
-        lobster_files:       Dict to update with AnalysisInfo.lobster_files
-                             (canonical name → File).
+        sa:            A sub-analysis target (fmea or security).
+        rst_srcs_list: List of depsets to extend with SphinxSourcesInfo.srcs.
+        rst_deps_list: List of depsets to extend with SphinxSourcesInfo.deps.
+        lobster_files: Dict to update with AnalysisInfo.lobster_files
+                       (canonical name → File).
     """
     if SphinxSourcesInfo in sa:
         rst_srcs_list.append(sa[SphinxSourcesInfo].srcs)
         rst_deps_list.append(sa[SphinxSourcesInfo].deps)
-        rst_ancillary_list.append(sa[SphinxSourcesInfo].ancillary)
     if AnalysisInfo in sa:
         lobster_files.update(sa[AnalysisInfo].lobster_files)
 
@@ -76,7 +74,6 @@ def _dependability_analysis_impl(ctx):
 
     rst_srcs_transitive = [dfa_rst_files]
     rst_deps_transitive = [dfa_rst_files]
-    rst_ancillary_transitive = []
     lobster_files = {}  # canonical name → File, merged from all sub-analyses
 
     # -------------------------------------------------------------------------
@@ -85,15 +82,15 @@ def _dependability_analysis_impl(ctx):
     fmea_output_files = []
     for sa in ctx.attr.fmea:
         fmea_output_files.append(sa[DefaultInfo].files)
-        _collect_analysis_providers(sa, rst_srcs_transitive, rst_deps_transitive, rst_ancillary_transitive, lobster_files)
+        _collect_analysis_providers(sa, rst_srcs_transitive, rst_deps_transitive, lobster_files)
 
     # -------------------------------------------------------------------------
     # Collect from security_analysis targets
     # -------------------------------------------------------------------------
     security_output_files = []
     for sa in ctx.attr.security_analysis:
         security_output_files.append(sa[DefaultInfo].files)
-        _collect_analysis_providers(sa, rst_srcs_transitive, rst_deps_transitive, rst_ancillary_transitive, lobster_files)
+        _collect_analysis_providers(sa, rst_srcs_transitive, rst_deps_transitive, lobster_files)
 
     # Architectural design sphinx deps (optional)
     if ctx.attr.arch_design and SphinxSourcesInfo in ctx.attr.arch_design:
@@ -185,7 +182,6 @@ def _dependability_analysis_impl(ctx):
         SphinxSourcesInfo(
             srcs = all_rst_srcs,
             deps = all_rst_deps,
-            ancillary = depset(transitive = rst_ancillary_transitive),
         ),
     ]
 

bazel/rules/rules_score/private/dependable_element.bzl

@@ -121,7 +121,7 @@ _INTEGRITY_LEVEL_RANK = {level: rank for rank, level in enumerate(_INTEGRITY_LEV
 # ============================================================================
 
 def _get_sphinx_files(target):
-    return target[SphinxSourcesInfo].srcs.to_list()
+    return target[SphinxSourcesInfo].deps.to_list()
 
 def _filter_doc_files(files):
     """Filter files to only include documentation files.
@@ -249,13 +249,17 @@ def _process_artifact_files(ctx, artifact_name, label):
     output_files = []
     index_refs = []
 
-    # Get and filter files
+    # deps contains all files to symlink (own srcs + transitive children);
+    # srcs are the toctree entries for this rule only.
     all_files = _get_sphinx_files(label)
     doc_files = _filter_doc_files(all_files)
 
     if not doc_files:
         return (output_files, index_refs)
 
+    # Build a lookup of srcs paths so we know which files are toctree entries.
+    srcs_paths = {f.path: True for f in label[SphinxSourcesInfo].srcs.to_list()}
+
     # Find common directory to preserve hierarchy
     common_dir = _find_common_directory(doc_files)
 
@@ -273,28 +277,13 @@ def _process_artifact_files(ctx, artifact_name, label):
         )
         output_files.append(output_file)
 
-        # Add to index if it's a document file
-        if _is_document_file(artifact_file):
+        # Add to toctree index only for files directly owned by this rule.
+        if _is_document_file(artifact_file) and artifact_file.path in srcs_paths:
             doc_ref = (artifact_name + "/" + relative_path) \
                 .replace(".rst", "") \
                 .replace(".md", "")
             index_refs.append(doc_ref)
 
-    # Symlink ancillary files (present for sub-toctrees / .. uml:: resolution,
-    # but NOT added to the outer toctree index).
-    if SphinxSourcesInfo in label:
-        for anc_file in label[SphinxSourcesInfo].ancillary.to_list():
-            if anc_file.extension not in ["rst", "md", "puml", "plantuml", "png", "svg", "inc", "json"]:
-                continue
-            relative_path = _compute_relative_path(anc_file, _find_common_directory([anc_file]))
-            output_file = _create_artifact_symlink(
-                ctx,
-                artifact_name,
-                anc_file,
-                relative_path,
-            )
-            output_files.append(output_file)
-
     return (output_files, index_refs)
 
 def _process_artifact_type(ctx, artifact_name):

bazel/rules/rules_score/private/fmea.bzl

@@ -281,12 +281,13 @@ def _fmea_impl(ctx):
     for f in root_cause_lobster_files:
         lobster_files["root_causes.lobster"] = f
 
-    # detail_rsts are ancillary: they must be present next to fmea.rst for the
-    # sub-toctree to resolve, but they are NOT top-level toctree entries.
+    # detail_rsts are NOT top-level toctree entries (they live in sub-toctrees
+    # within fmea.rst), but they must be present in the Sphinx tree. They go
+    # into deps so dependable_element symlinks them alongside toctree files.
     toctree_files = [f for f in output_files if f not in detail_rsts]
     all_sphinx_srcs = depset(toctree_files)
 
-    sphinx_deps = [all_sphinx_srcs]
+    sphinx_deps = [all_sphinx_srcs, depset(detail_rsts)]
     if ctx.attr.arch_design and SphinxSourcesInfo in ctx.attr.arch_design:
         sphinx_deps.append(ctx.attr.arch_design[SphinxSourcesInfo].deps)
 
@@ -301,7 +302,6 @@ def _fmea_impl(ctx):
         SphinxSourcesInfo(
             srcs = all_sphinx_srcs,
             deps = depset(transitive = sphinx_deps),
-            ancillary = depset(detail_rsts),
         ),
     ]
 

bazel/rules/rules_score/private/requirements.bzl

@@ -123,7 +123,6 @@ def _requirements_impl(ctx):
         SphinxSourcesInfo(
             srcs = sphinx_srcs,
             deps = depset(transitive = transitive_sphinx),
-            ancillary = depset(),
         ),
     ]
 

bazel/rules/rules_score/private/unit.bzl

@@ -96,7 +96,6 @@ def _unit_impl(ctx):
         SphinxSourcesInfo(
             srcs = all_files,
             deps = depset(transitive = [all_files] + sphinx_design_deps),
-            ancillary = depset(),
         ),
     ]
 

bazel/rules/rules_score/private/unit_design.bzl

@@ -95,7 +95,6 @@ def _unit_design_impl(ctx):
         SphinxSourcesInfo(
             srcs = all_source_files,
             deps = all_source_files,
-            ancillary = depset(),
         ),
     ]
 

bazel/rules/rules_score/providers.bzl

@@ -49,11 +49,19 @@ SphinxSourcesInfo = provider(
     builds, including reStructuredText, Markdown, PlantUML diagrams, and
     image files. Rules that produce documentation artifacts should provide
     this to enable integration with sphinx_module and dependable_element.
+
+    Semantics:
+      srcs — Files directly owned/generated by this rule. Only these are
+             used as top-level toctree entries by dependable_element.
+             For leaf rules (no children), srcs == deps.
+      deps — All files needed in the Sphinx tree: own srcs plus all
+             transitive files from children. dependable_element symlinks
+             everything in deps into the output tree. Parent/container
+             rules bubble up children's deps into their own deps field.
     """,
     fields = {
-        "srcs": "Depset of direct source files for Sphinx documentation (.rst, .md, .puml, .plantuml, .svg, .png, etc.)",
-        "deps": "Depset of transitive Sphinx source files collected from all direct and transitive dependencies.",
-        "ancillary": "Depset of files that must be physically present in the Sphinx tree (e.g. for sub-toctrees or .. uml:: directives) but are NOT top-level toctree entries.",
+        "srcs": "Depset of files directly owned by this rule (.rst, .md, .puml, etc.). Used by dependable_element as toctree entries.",
+        "deps": "Depset of all files needed in the Sphinx tree — own srcs plus transitive deps from all children. For leaf rules, equals srcs.",
     },
 )