labels: aggregate from package/subpackage/document scope, update CHANGELOG

Small follow-up to open-policy-agent#8613. I think carrying the labels from upper scopes
along makes this more powerful.

Signed-off-by: Stephan Renatus <stephan.renatus@gmail.com>

Author: srenatus

CHANGELOG.md

@@ -11,7 +11,18 @@ Rule annotations now support a `labels` field. Labels from all successfully eval
 rules are collected and included in each decision log entry as a top-level `rule_labels`
 array. Each element preserves the label map from one evaluated rule.
 
+Labels can be defined at package, document, rule, or subpackages scope. Package-scoped
+labels are inherited by all rules in the package. Subpackages-scoped labels apply to all
+rules in descendant packages. Document-scoped labels apply to all rules with the same
+name. All scopes are aggregated and deduplicated.
+
 ```rego
+# METADATA
+# scope: package
+# labels:
+#   service: authz
+package myapp
+
 # METADATA
 # labels:
 #   severity: low
@@ -22,10 +33,10 @@ allow if input.role == "admin"
 The resulting decision log entry will contain:
 
 ```json
-{"rule_labels": [{"severity": "low", "team": "platform"}]}
+{"rule_labels": [{"service": "authz"}, {"severity": "low", "team": "platform"}]}
 ```
 
-The runtime now processes metadata annotations by default.
+Both the runtime and the Go SDK now process metadata annotations by default.
 
 ## 1.16.1
 

docs/docs/policy-language.md

@@ -2668,10 +2668,11 @@ message := "welcome!" if allow
 ### Metadata `labels`
 
 The `labels` annotation is a map of arbitrary key-value pairs attached to a
-rule (or document). When rules with `labels` are successfully evaluated, their
-label sets are automatically recorded in decision log events under the
-`rule_labels` field. Labels from document-scoped and rule-scoped annotations
-are both collected.
+rule (or document, package, or subpackages scope). When rules with `labels` are
+successfully evaluated, their label sets are automatically recorded in decision
+log events under the `rule_labels` field. Labels from subpackages-scoped,
+package-scoped, document-scoped, and rule-scoped annotations are all collected
+and aggregated.
 
 ```rego
 # METADATA

v1/ast/annotations.go

@@ -544,7 +544,20 @@ func attachRuleAnnotations(mod *Module) {
 		cpy[i] = a.Copy(a.node)
 	}
 
+	// Collect package-scope labels to propagate to all rules.
+	var pkgLabels map[string]any
+	for _, a := range cpy {
+		if a.Scope == annotationScopePackage && len(a.Labels) > 0 {
+			pkgLabels = a.Labels
+			break
+		}
+	}
+
 	for _, rule := range mod.Rules {
+		if pkgLabels != nil {
+			rule.Annotations = append(rule.Annotations, &Annotations{Labels: pkgLabels})
+		}
+
 		var j int
 		var found bool
 		for i, a := range cpy {

v1/ast/compile.go

@@ -1852,6 +1852,30 @@ func (c *Compiler) setAnnotationSet() {
 		c.err(err)
 	}
 	c.annotationSet = as
+
+	// Propagate subpackages-scoped labels to rules in descendant packages.
+	for _, mod := range c.Modules {
+		subPkgAnnots := as.GetSubpackagesScope(mod.Package.Path)
+		if len(subPkgAnnots) == 0 {
+			continue
+		}
+		var subPkgLabels []map[string]any
+		for _, a := range subPkgAnnots {
+			if len(a.Labels) > 0 {
+				subPkgLabels = append(subPkgLabels, a.Labels)
+			}
+		}
+		if len(subPkgLabels) == 0 {
+			continue
+		}
+		for _, rule := range mod.Rules {
+			prepend := make([]*Annotations, len(subPkgLabels))
+			for i, labels := range subPkgLabels {
+				prepend[i] = &Annotations{Labels: labels}
+			}
+			rule.Annotations = append(prepend, rule.Annotations...)
+		}
+	}
 }
 
 // checkTypes runs the type checker on all rules. The type checker builds a

v1/topdown/evaluated_test.go

@@ -95,11 +95,12 @@ func TestEvaluatedRuleTracker(t *testing.T) {
 
 func TestEvaluatedRuleLabelsScopes(t *testing.T) {
 	tests := []struct {
-		note   string
-		module string
-		query  string
-		input  string
-		exp    []map[string]any
+		note    string
+		module  string
+		modules map[string]string
+		query   string
+		input   string
+		exp     []map[string]any
 	}{
 		{
 			note: "rule scope labels",
@@ -190,13 +191,108 @@ allow if input.role == "viewer"
 				{"id": "allow-admin"},
 			},
 		},
+		{
+			note: "package scope labels inherited by rules",
+			module: `# METADATA
+# scope: package
+# labels:
+#   service: auth
+package test
+
+# METADATA
+# labels:
+#   severity: high
+allow if input.role == "admin"
+`,
+			query: "data.test.allow",
+			exp: []map[string]any{
+				{"service": "auth"},
+				{"severity": "high"},
+			},
+		},
+		{
+			note: "package and document and rule scope all combine",
+			module: `# METADATA
+# scope: package
+# labels:
+#   service: auth
+package test
+
+# METADATA
+# scope: document
+# labels:
+#   component: authz
+
+# METADATA
+# labels:
+#   severity: high
+allow if input.role == "admin"
+`,
+			query: "data.test.allow",
+			exp: []map[string]any{
+				{"service": "auth"},
+				{"component": "authz"},
+				{"severity": "high"},
+			},
+		},
+		{
+			note: "both rules fire, both severities collected",
+			module: `package test
+
+# METADATA
+# labels:
+#   severity: high
+reasons contains "admin" if "admin" in input.roles
+
+# METADATA
+# labels:
+#   severity: low
+reasons contains "viewer" if "viewer" in input.roles
+`,
+			query: "data.test.reasons",
+			input: `{"roles": ["admin", "viewer"]}`,
+			exp: []map[string]any{
+				{"severity": "high"},
+				{"severity": "low"},
+			},
+		},
+		{
+			note: "subpackages scope labels inherited by rules in child packages",
+			modules: map[string]string{
+				"parent": `# METADATA
+# scope: subpackages
+# labels:
+#   org: acme
+package test
+`,
+				"child": `package test.authz
+
+# METADATA
+# labels:
+#   severity: high
+allow if input.role == "admin"
+`,
+			},
+			query: "data.test.authz.allow",
+			exp: []map[string]any{
+				{"org": "acme"},
+				{"severity": "high"},
+			},
+		},
 	}
 
 	for _, tc := range tests {
 		t.Run(tc.note, func(t *testing.T) {
-			mod := ast.MustParseModuleWithOpts(tc.module, ast.ParserOptions{ProcessAnnotation: true})
+			modules := make(map[string]*ast.Module)
+			if tc.modules != nil {
+				for name, src := range tc.modules {
+					modules[name] = ast.MustParseModuleWithOpts(src, ast.ParserOptions{ProcessAnnotation: true})
+				}
+			} else {
+				modules["test"] = ast.MustParseModuleWithOpts(tc.module, ast.ParserOptions{ProcessAnnotation: true})
+			}
 			c := ast.NewCompiler()
-			c.Compile(map[string]*ast.Module{"test": mod})
+			c.Compile(modules)
 			if c.Failed() {
 				t.Fatal(c.Errors)
 			}