dependable_element: symlink ancillary files and split requirements sections

Split the 'requirements' attribute handling into separate feature_requirements
and assumed_system_requirements sections, accepting both FeatureRequirementsInfo
and AssumedSystemRequirementsInfo providers on the requirements attr.

Restructure the index template accordingly:
- 'Assumed System' section: assumed_system_requirements + assumptions_of_use
- 'Software Architectural Level' section: feature_requirements + architectural_design + dependability_analysis
- Components are now referenced directly in the outer toctree (no intermediate components/index.rst)

Author: hoe-jo

bazel/rules/rules_score/private/dependable_element.bzl

@@ -280,6 +280,21 @@ def _process_artifact_files(ctx, artifact_name, label):
                 .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):
@@ -686,10 +701,8 @@ def _dependable_element_index_impl(ctx):
 
     # Process each well-known artifact type into symlinked output files and
     # toctree references for the index template.
-    # "requirements" covers both feature_requirements and component_requirements.
     artifact_types = [
         "assumptions_of_use",
-        "requirements",
         "architectural_design",
         "dependability_analysis",
         "checklists",
@@ -701,6 +714,24 @@ def _dependable_element_index_impl(ctx):
         output_files.extend(files)
         artifacts_by_type[artifact_name] = refs
 
+    # Collect feature_requirements refs from requirements targets that
+    # carry FeatureRequirementsInfo.
+    feature_req_refs = []
+    for req_target in ctx.attr.requirements:
+        if FeatureRequirementsInfo in req_target:
+            label_files, label_refs = _process_artifact_files(ctx, "feature_requirements", req_target)
+            output_files.extend(label_files)
+            feature_req_refs.extend(label_refs)
+
+    # Collect assumed_system_requirements refs from requirements targets that
+    # carry AssumedSystemRequirementsInfo.
+    assumed_system_req_refs = []
+    for req_target in ctx.attr.requirements:
+        if AssumedSystemRequirementsInfo in req_target:
+            label_files, label_refs = _process_artifact_files(ctx, "assumed_system_requirements", req_target)
+            output_files.extend(label_files)
+            assumed_system_req_refs.extend(label_refs)
+
     # Collect all units recursively from components
     all_units = _collect_units_recursive(ctx.attr.components)
 
@@ -746,18 +777,11 @@ def _dependable_element_index_impl(ctx):
         if CertifiedScope in dep:
             collected_certified_scopes.append(dep[CertifiedScope].transitive_scopes)
 
-    # Generate an intermediate components/index.rst that groups all component pages
-    # under a single "Components" navigation entry in the Sphinx sidebar.
+    # Reference component pages directly in the outer toctree, avoiding an
+    # intermediate components/index.rst that would repeat "Components" in the
+    # Sphinx sidebar navigation.
     if component_refs:
-        comp_index_rst = ctx.actions.declare_file(ctx.label.name + "/components/index.rst")
-        comp_index_underline = "=" * len("Components")
-        comp_toctree_entries = "\n   ".join(component_refs)
-        ctx.actions.write(
-            output = comp_index_rst,
-            content = "Components\n" + comp_index_underline + "\n\n.. toctree::\n   :maxdepth: 2\n\n   " + comp_toctree_entries + "\n",
-        )
-        output_files.append(comp_index_rst)
-        components_ref = "components/index"
+        components_ref = "\n   ".join(["components/" + name for name in component_refs])
     else:
         components_ref = ""
 
@@ -775,8 +799,9 @@ def _dependable_element_index_impl(ctx):
             "{title}": title,
             "{underline}": underline,
             "{components}": components_ref,
+            "{assumed_system_requirements}": "\n   ".join(assumed_system_req_refs),
             "{assumptions_of_use}": "\n   ".join(artifacts_by_type["assumptions_of_use"]),
-            "{requirements}": "\n   ".join(artifacts_by_type["requirements"]),
+            "{feature_requirements}": "\n   ".join(feature_req_refs),
             "{architectural_design}": "\n   ".join(artifacts_by_type["architectural_design"]),
             "{dependability_analysis}": "\n   ".join(artifacts_by_type["dependability_analysis"]),
             "{checklists}": "\n   ".join(artifacts_by_type["checklists"]),
@@ -1000,8 +1025,8 @@ _dependable_element_index = rule(
             ),
             "requirements": attr.label_list(
                 mandatory = True,
-                providers = [FeatureRequirementsInfo],
-                doc = "Feature requirements targets (feature_requirements only).",
+                providers = [[FeatureRequirementsInfo], [AssumedSystemRequirementsInfo]],
+                doc = "Feature or assumed system requirements targets.",
             ),
             "architectural_design": attr.label_list(
                 mandatory = True,

bazel/rules/rules_score/templates/dependable_element_index.template.rst

@@ -15,30 +15,25 @@
 Dependable element: {title}
 ===================={underline}
 
-Architectural Design
---------------------
-
-.. toctree::
-   :maxdepth: 2
-
-   {architectural_design}
-
-
-Assumptions of Use
-------------------
+Assumed System
+--------------
 
 .. toctree::
    :maxdepth: 2
 
+   {assumed_system_requirements}
    {assumptions_of_use}
 
-Requirements
-------------
+Software Architectural Level
+----------------------------
 
 .. toctree::
    :maxdepth: 2
 
-   {requirements}
+   {feature_requirements}
+   {architectural_design}
+   {dependability_analysis}
+
 
 Components
 ----------
@@ -49,16 +44,6 @@ Components
    {components}
 
 
-
-
-Dependability Analysis
-----------------------
-
-.. toctree::
-   :maxdepth: 2
-
-   {dependability_analysis}
-
 Checklists
 ----------
 

bazel/rules/rules_score/test/seooc_test.bzl

@@ -119,46 +119,51 @@ seooc_needs_provider_test = analysistest.make(
 # ============================================================================
 # Regression tests: correct index.rst resolution (multi-index scenario)
 #
-# These tests guard against a bug where _score_html_impl scanned all relocated
-# source files for any path ending with "/index.rst" and used the last match.
-# A dependable_element with components generates both:
-#   <name>/index.rst          (root – correct Sphinx entry point)
-#   <name>/components/index.rst  (sub-page – must NOT be the entry point)
-# The old code would pick the sub-page as the Sphinx entry point.
+# These tests guard against a bug where the wrong index.rst was picked as the
+# Sphinx entry point when multiple index.rst files are present in the output
+# tree (e.g. unit/index.rst, component/index.rst alongside the root index.rst).
+# The fix is to carry the correct File explicitly via SphinxIndexFileInfo rather
+# than scanning all output files for any path ending with "/index.rst".
 # ============================================================================
 
 def _seooc_multi_index_files_exist_test_impl(ctx):
     """
-    Given a dependable_element with at least one component,
-    When the _index rule generates its output file set,
-    Then both a root index.rst and a components/index.rst must be present,
-         confirming the fixture exercises the multi-index scenario.
+    Given a dependable_element with at least one component (which generates
+          multiple .rst files in subdirectories alongside the root index.rst),
+    When the _index rule finishes,
+    Then SphinxIndexFileInfo must be provided and its index_file must be the
+         root index.rst (not inside any subdirectory), confirming the correct
+         entry point is propagated explicitly rather than discovered by scanning.
     """
     env = analysistest.begin(ctx)
     target_under_test = analysistest.target_under_test(env)
 
-    # When: collect all output paths
-    files = target_under_test[DefaultInfo].files.to_list()
-    paths = [f.path for f in files]
+    # Then: SphinxIndexFileInfo provider must be present
+    asserts.true(
+        env,
+        SphinxIndexFileInfo in target_under_test,
+        "Expected SphinxIndexFileInfo provider to be present on the index target",
+    )
 
-    # Then: a components/index.rst sub-page exists
-    components_index_paths = [p for p in paths if p.endswith("components/index.rst")]
+    index_file = target_under_test[SphinxIndexFileInfo].index_file
+
+    # Then: the index file must be named index.rst
     asserts.true(
         env,
-        len(components_index_paths) >= 1,
-        "Expected a components/index.rst to be generated (fixture must have at least one component)",
+        index_file.basename == "index.rst",
+        "SphinxIndexFileInfo.index_file must be named index.rst, got: " + index_file.basename,
     )
 
-    # Then: a root index.rst (not inside components/) also exists
-    root_index_paths = [
-        p
-        for p in paths
-        if p.endswith("index.rst") and "components/" not in p
-    ]
+    # Then: the index file must be at the root of the output tree (no subdirectory in dirname)
+    # e.g. .../test_dependable_element_index/index.rst — the last path component of dirname
+    # must equal the target name, not a sub-page like "components" or "units".
+    parent = index_file.dirname.split("/")[-1]
     asserts.true(
         env,
-        len(root_index_paths) >= 1,
-        "Expected a root index.rst (outside components/) to be generated",
+        parent == ctx.attr.target_under_test.label.name,
+        "SphinxIndexFileInfo.index_file must sit directly under the target output dir, " +
+        "not in a subdirectory. dirname ends in '" + parent + "', expected '" +
+        ctx.attr.target_under_test.label.name + "'",
     )
 
     return analysistest.end(env)