diff --git a/bazel/rules/rules_score/docs/_assets/scope_check.puml b/bazel/rules/rules_score/docs/_assets/scope_check.puml index 898dfe99..f74f0fd1 100644 --- a/bazel/rules/rules_score/docs/_assets/scope_check.puml +++ b/bazel/rules/rules_score/docs/_assets/scope_check.puml @@ -31,9 +31,10 @@ package "dependable_element" as de { } note bottom of outofscope - Rejected: "Not in certified scope - //third_party/foo:__subpackages__, - stopping at other" + Scope violation: + Unit //pkg:MyUnit depends on //other/unrelated:thing, + but the dependency is not in any certified scope + (package '//other/unrelated' is not covered). end note @enduml diff --git a/bazel/rules/rules_score/docs/tool_reference/scope_check.rst b/bazel/rules/rules_score/docs/tool_reference/scope_check.rst index e267fbfc..68e081eb 100644 --- a/bazel/rules/rules_score/docs/tool_reference/scope_check.rst +++ b/bazel/rules/rules_score/docs/tool_reference/scope_check.rst @@ -42,8 +42,8 @@ patterns: ``scope`` is for dependencies that are *not* explicitly named as ``implementation`` targets themselves (e.g. third-party libraries pulled in transitively) but are still known and accepted as part of the unit. Every -``unit`` and ``component`` also implicitly certifies its own explicitly named -targets (``implementation``, nested ``components``). +``unit`` also implicitly certifies its own ``implementation`` targets. +Components aggregate the scopes of their units and nested components. Scopes are collected transitively: a ``component``'s certified scope is the union of its own units' and nested components' scopes, and a @@ -57,14 +57,26 @@ What is checked For each ``unit``, an aspect (``cc_dependencies_aspect``) walks the ``deps`` / ``implementation_deps`` / ``exported_deps`` attributes of its ``implementation`` targets and collects every transitively reached label. -``dependable_element`` then checks each collected label against the tree of -certified scopes built from all ``scope`` declarations in the element: a -label is in scope if it (or an enclosing package / subpackage wildcard) was -declared somewhere. Any dependency that is not covered fails the check with: +``dependable_element`` checks each collected dependency label against the +combined certified scopes, including the units' own ``implementation`` +targets. A dependency is covered if any of the following applies: + +* Its exact target label is included. +* Its package is covered by a ``__pkg__`` declaration. +* Its package or an ancestor package is covered by a + ``__subpackages__`` declaration. + +All matches require the scope declaration and dependency to belong to +the same repository. + +Uncovered dependencies are reported as warnings when the enclosing +``dependable_element`` has ``maturity = "development"``; otherwise they +fail the build. Each message identifies the originating unit and dependency: .. code-block:: text - Not in certified scope