[rules score] decouble unit name from bazel name

Author: hoe-jo

bazel/rules/rules_score/docs/rule_reference.rst

@@ -668,7 +668,11 @@ diagram.
    * - ``name``
      - string
      - yes
-     - Target name; **must match** the ``<<unit>>`` name in the static PlantUML diagram
+     - Target name; **must match** the ``<<unit>>`` name in the static PlantUML diagram unless ``design_name`` is set
+   * - ``design_name``
+     - string
+     - no
+     - Name to match against the static PlantUML diagram instead of ``name`` (default: ``name``)
    * - ``unit_design``
      - label list
      - yes
@@ -730,7 +734,11 @@ diagram.
    * - ``name``
      - string
      - yes
-     - Target name; **must match** the ``<<component>>`` name in the static PlantUML diagram
+     - Target name; **must match** the ``<<component>>`` name in the static PlantUML diagram unless ``design_name`` is set
+   * - ``design_name``
+     - string
+     - no
+     - Name to match against the static PlantUML diagram instead of ``name`` (default: ``name``)
    * - ``requirements``
      - label list
      - yes

bazel/rules/rules_score/docs/user_guide/architectural_design.rst

@@ -449,6 +449,24 @@ component
         tests        = [],
     )
 
+Decoupling the Bazel Target Name from the Diagram Alias
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+By default the consistency check matches a ``unit``/``component`` against the
+PlantUML diagram by its Bazel target name. Pass ``design_name`` to match
+against a different alias instead — useful when the Bazel target name must
+follow a repo-wide naming convention that differs from the architecture diagram:
+
+.. code-block:: starlark
+
+    unit(
+        name           = "unit_1_impl",
+        design_name    = "unit_1",  # matches "unit_1" in the PlantUML diagram
+        unit_design    = ["//unit_1/docs:unit_design"],
+        implementation = [":unit_1_lib"],
+        tests          = [":unit_1_test"],
+    )
+
 Dynamic Architecture
 ----------------------
 

bazel/rules/rules_score/private/architecture_aspect.bzl

@@ -40,9 +40,9 @@ def _collect_current_architecture_aspect_impl(target, ctx):
 
             # Check if it's a unit or a component
             if UnitInfo in comp:
-                current_units.append(comp_label)
+                current_units.append({"label": comp_label, "design_name": comp[UnitInfo].design_name})
             elif ComponentInfo in comp:
-                current_components.append(comp_label)
+                current_components.append({"label": comp_label, "design_name": comp[ComponentInfo].design_name})
 
             if CurrentArchitectureProviderInfo in comp:
                 nested_info = comp[CurrentArchitectureProviderInfo]

bazel/rules/rules_score/private/component.bzl

@@ -325,6 +325,7 @@ def _component_impl(ctx):
         # ComponentInfo: lobster traceability files for requirements, architecture, and tests; propagated up to dependable_element
         ComponentInfo(
             name = ctx.label.name,
+            design_name = ctx.attr.design_name or ctx.label.name,
             requirements = req_lobster_depset,
             requirements_transitive = req_lobster_transitive_depset,
             components = components_depset,
@@ -360,6 +361,10 @@ _component_test = rule(
     implementation = _component_impl,
     doc = "Defines a software component composed of multiple units for S-CORE process compliance",
     attrs = {
+        "design_name": attr.string(
+            default = "",
+            doc = "Name matched against the PlantUML component-diagram alias; defaults to name.",
+        ),
         "requirements": attr.label_list(
             default = [],
             providers = [[ComponentRequirementsInfo], [FeatureRequirementsInfo]],
@@ -408,6 +413,7 @@ def component(
         requirements = None,
         components = [],
         test_case_coverage_lock = None,
+        design_name = None,
         testonly = True,
         **kwargs):
     """Define a software component following S-CORE process guidelines.
@@ -437,6 +443,9 @@ def component(
             If provided, the component rule generates test_case_coverage.lobster by comparing
             computed test coverage against the committed lock. Enables `.update`
             target for refreshing coverage.
+        design_name: Optional name matched against the PlantUML component-diagram
+            alias, decoupled from the Bazel target name (analogous to py_binary's
+            `main`). Defaults to name.
         testonly: If true, only testonly targets can depend on this component.
         visibility: Bazel visibility specification for the component target.
 
@@ -459,6 +468,7 @@ def component(
         components = components,
         tests = tests,
         test_case_coverage_lock = test_case_coverage_lock,
+        design_name = design_name or "",
         testonly = testonly,
         **kwargs
     )

bazel/rules/rules_score/private/dependable_element.bzl

@@ -977,9 +977,9 @@ def _collect_architecture_components(ctx):
     de_units = []
     for comp in ctx.attr.components:
         if ComponentInfo in comp:
-            de_components.append(str(comp.label))
+            de_components.append({"label": str(comp.label), "design_name": comp[ComponentInfo].design_name})
         elif UnitInfo in comp:
-            de_units.append(str(comp.label))
+            de_units.append({"label": str(comp.label), "design_name": comp[UnitInfo].design_name})
 
     de_entry = {}
     if de_components:

bazel/rules/rules_score/private/unit.bzl

@@ -147,6 +147,7 @@ def _unit_impl(ctx):
         CertifiedScope(transitive_scopes = depset(ctx.attr.scope)),
         UnitInfo(
             name = ctx.label.name,
+            design_name = ctx.attr.design_name or ctx.label.name,
             unit_design = design_depset,
             unit_design_static_fbs = design_static_fbs_depset,
             unit_design_dynamic_fbs = design_dynamic_fbs_depset,
@@ -169,6 +170,10 @@ def _unit_impl(ctx):
 # ============================================================================
 
 _unit_attrs = {
+    "design_name": attr.string(
+        default = "",
+        doc = "Name matched against the PlantUML component-diagram alias; defaults to name.",
+    ),
     "unit_design": attr.label_list(
         default = [],
         providers = [UnitDesignInfo],
@@ -223,6 +228,7 @@ def unit(
         implementation,
         tests,
         scope = [],
+        design_name = None,
         testonly = True,
         **kwargs):
     """Define a software unit following S-CORE process guidelines.
@@ -243,6 +249,9 @@ def unit(
             but not explicitly named in the implementation list. Default is empty list.
         tests: List of labels to Bazel test targets (cc_test, rust_test, etc.)
             that verify the unit implementation.
+        design_name: Optional name matched against the PlantUML component-diagram
+            alias, decoupled from the Bazel target name (analogous to py_binary's
+            `main`). Defaults to name.
         testonly: If true, only testonly targets can depend on this unit. Set to true
             when the unit depends on testonly targets like tests.
         visibility: Bazel visibility specification for the unit target.
@@ -274,6 +283,7 @@ def unit(
         implementation = implementation,
         scope = scope,
         tests = tests,
+        design_name = design_name or "",
         testonly = testonly,
         **kwargs
     )

bazel/rules/rules_score/providers.bzl

@@ -76,6 +76,7 @@ UnitInfo = provider(
     doc = "Provider for unit artifacts.",
     fields = {
         "name": "Name of the unit target.",
+        "design_name": "Name used to match this unit against its PlantUML component-diagram alias; defaults to name.",
         "unit_design": "Depset of design artifact files (PlantUML diagrams, RST documents, etc.).",
         "unit_design_static_fbs": "Depset of FlatBuffers binaries generated from static unit_design diagrams.",
         "unit_design_dynamic_fbs": "Depset of FlatBuffers binaries generated from dynamic unit_design diagrams.",
@@ -163,6 +164,7 @@ ComponentInfo = provider(
     doc = "Provider for component artifacts.",
     fields = {
         "name": "Name of the component target.",
+        "design_name": "Name used to match this component against its PlantUML component-diagram alias; defaults to name.",
         "requirements": "Depset of component requirement traceability files (.lobster) collected from this component's own ComponentRequirementsInfo targets only (CompReq kind); not rolled up from nested components. Does not include feature or assumed-system requirement files. Consumed only by dependable_element's test-case-coverage-lock check. Includes `derived_from` tracing targets, including any AoU references within it (resolved only at the dependable_element level).",
         "requirements_transitive": "Depset of component requirement traceability files (.lobster), rolled up transitively from this component and all nested components. Consumed by dependable_element to build the aggregated 'Component Requirements' traceability report tier.",
         "components": "Depset of nested component and/or unit Targets that comprise this component.",

bazel/rules/rules_score/test/BUILD

@@ -836,6 +836,49 @@ dependable_element(
     deps = [],
 )
 
+# Regression test for design_name: the unit's Bazel target name
+# ("design_name_unit_bazel_target") differs from the alias matched against
+# the PlantUML component diagram ("design_name_unit"), decoupled via the
+# design_name attribute.
+architectural_design(
+    name = "arch_design_design_name_example",
+    static = ["fixtures/design_name_example.puml"],
+)
+
+unit(
+    name = "design_name_unit_bazel_target",
+    testonly = True,
+    design_name = "design_name_unit",
+    scope = ["//:mock_lib1"],
+    tests = [],
+    unit_design = [":test_unit_design"],
+    implementation = [":mock_lib1"],
+)
+
+component(
+    name = "design_name_component",
+    testonly = True,
+    components = [":design_name_unit_bazel_target"],
+    requirements = [
+        ":comp_req",
+        ":feat_req",
+    ],
+    tests = [],
+)
+
+dependable_element(
+    name = "design_name_example_lib",
+    architectural_design = [":arch_design_design_name_example"],
+    assumptions_of_use = [":aous"],
+    components = [":design_name_component"],
+    dependability_analysis = [":dependability_analysis_target"],
+    integrity_level = "B",
+    maturity = "development",
+    requirements = [":feat_req"],
+    tests = [],
+    deps = [],
+)
+
 unit(
     name = "seooc_test_unit",
     testonly = True,

bazel/rules/rules_score/test/fixtures/design_name_example.puml

@@ -0,0 +1,22 @@
+' *******************************************************************************
+' 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
+' *******************************************************************************
+
+@startuml design_name_example
+
+package "Design Name Example" as design_name_example_lib <<SEooC>> {
+    component "Design Name Component" as design_name_component <<component>> {
+        component "Design Name Unit" as design_name_unit <<unit>>
+    }
+}
+
+@enduml

validation/core/docs/specifications/bazel_component.md

@@ -29,13 +29,15 @@ checks below operate on that merged view regardless of how many static files
 contributed to it. See the `architectural_design` rule reference for the
 cross-file merge rules.
 
-All comparisons are case-insensitive: both Bazel target short names and
-PlantUML aliases/IDs are normalized to lowercase before matching, so a Bazel
-target `Component_X` matches a PlantUML entity `as COMPONENT_X`. Names are
-derived from the PlantUML `alias` when present, otherwise from the `id`. On
-the Bazel side, IDs are generated from the target's short name (the part
-after the last `:` in the label), also lowercased. Parent aliases are
-lowercased the same way when resolving parent-child relationships.
+All comparisons are case-insensitive: both Bazel entity keys and PlantUML
+aliases/IDs are normalized to lowercase before matching, so a Bazel entity
+`Component_X` matches a PlantUML entity `as COMPONENT_X`. Names are derived
+from the PlantUML `alias` when present, otherwise from the `id`. On the
+Bazel side, each `unit`/`component` entry carries a `design_name` (the
+`design_name` attribute passed to the `unit`/`component` macro, defaulting
+to the target's short name) which is used as the entity key, also
+lowercased. Parent aliases are lowercased the same way when resolving
+parent-child relationships.
 
 ### Dependable Element Consistency
 
@@ -112,7 +114,9 @@ immediate enclosing component alias as parent.
 
 Every Bazel label must define a target name. A label such as `@//pkg:` (a
 colon with nothing following it) has no target name and is rejected with a
-`[Design]` error before any entity matching happens.
+`[Design]` error before any entity matching happens -- this check runs
+independently of `design_name`, so a malformed label is still rejected even
+though `design_name` is the actual match key.
 
 ### Duplicate Entity Detection