Change required scope of entrypoint from rule to document

And automatically change implied `scope` from `rule` to `document` when
no `scope` is provided (on rule metadata).

Whether this can be included in a "normal" release, or will have to wait
until OPA 1.0, I'll let others decide. But I think it's worth pointing out
that this is a breaking change to address a **bug**, and that a scope of
`rule` makes no sense for an entrypoint.

One alternative could perhaps be to only change this behavior when
`import rego.v1` is included in a file, as that's meant to be a glimpse
of the future anyway. But at this time, no such considerations have been
taken.

Fixes open-policy-agent#6798

Signed-off-by: Anders Eknert <anders@styra.com>

ast/annotations.go

@@ -417,7 +417,7 @@ func (a *Annotations) Copy(node Node) *Annotations {
  return &cpy
 }
 
-// toObject constructs an AST Object from a.
+// toObject constructs an AST Object from the annotation.
 func (a *Annotations) toObject() (*Object, *Error) {
  obj := NewObject()
 
@@ -556,7 +556,11 @@ func attachAnnotationsNodes(mod *Module) Errors {
  if a.Scope == "" {
  switch a.node.(type) {
  case *Rule:
- a.Scope = annotationScopeRule
+ if a.Entrypoint {
+ a.Scope = annotationScopeDocument
+ } else {
+ a.Scope = annotationScopeRule
+ }
  case *Package:
  a.Scope = annotationScopePackage
  case *Import:
@@ -596,8 +600,9 @@ func validateAnnotationScopeAttachment(a *Annotations) *Error {
 }
 
 func validateAnnotationEntrypointAttachment(a *Annotations) *Error {
- if a.Entrypoint && !(a.Scope == annotationScopeRule || a.Scope == annotationScopePackage) {
- return NewError(ParseErr, a.Loc(), "annotation entrypoint applied to non-rule or package scope '%v'", a.Scope)
+ if a.Entrypoint && !(a.Scope == annotationScopeDocument || a.Scope == annotationScopePackage) {
+ return NewError(
+ ParseErr, a.Loc(), "annotation entrypoint applied to non-document or package scope '%v'", a.Scope)
  }
  return nil
 }

ast/annotations_test.go

@@ -10,6 +10,88 @@ import (
  "testing"
 )
 
+func TestEntrypointAnnotationScopeRequirements(t *testing.T) {
+ tests := []struct {
+ note string
+ module string
+ expectError bool
+ expectScope string
+ }{
+ {
+ note: "package scope explicit",
+ module: `# METADATA
+# entrypoint: true
+# scope: package
+package foo`,
+ expectError: false,
+ expectScope: "package",
+ },
+ {
+ note: "package scope implied",
+ module: `# METADATA
+# entrypoint: true
+package foo`,
+ expectError: false,
+ expectScope: "package",
+ },
+ {
+ note: "subpackages scope explicit",
+ module: `# METADATA
+# entrypoint: true
+# scope: subpackages
+package foo`,
+ expectError: true,
+ },
+ {
+ note: "document scope explicit",
+ module: `package foo
+# METADATA
+# entrypoint: true
+# scope: document
+foo := true`,
+ expectError: false,
+ expectScope: "document",
+ },
+ {
+ note: "document scope implied",
+ module: `package foo
+# METADATA
+# entrypoint: true
+foo := true`,
+ expectError: false,
+ expectScope: "document",
+ },
+ {
+ note: "rule scope explicit",
+ module: `package foo
+# METADATA
+# entrypoint: true
+# scope: rule
+foo := true`,
+ expectError: true,
+ },
+ }
+
+ for _, tc := range tests {
+ t.Run(tc.note, func(t *testing.T) {
+ module, err := ParseModuleWithOpts("test.rego", tc.module, ParserOptions{ProcessAnnotation: true})
+ if err != nil {
+ if !tc.expectError {
+ t.Errorf("unexpected error: %v", err)
+ }
+ return
+ }
+ if tc.expectError {
+ t.Fatalf("expected error")
+ }
+ if tc.expectScope != module.Annotations[0].Scope {
+ t.Fatalf("expected scope %q, got %q", tc.expectScope, module.Annotations[0].Scope)
+ }
+ })
+ }
+
+}
+
 // Test of example code in docs/content/annotations.md
 func ExampleAnnotationSet_Flatten() {
  modules := [][]string{

cmd/build_test.go

@@ -653,7 +653,7 @@ p2 := 2
  "entrypoint":"test/p2",
  "module":"/policy.wasm",
  "annotations":[{
- "scope":"rule",
+ "scope":"document",
  "title":"P2",
  "entrypoint":true
  }]
@@ -742,15 +742,15 @@ bar := "baz"
  "entrypoint":"test/foo/bar",
  "module":"/policy.wasm",
  "annotations":[{
- "scope":"rule",
+ "scope":"document",
  "title":"BAR",
  "entrypoint":true
  }]
  },{
  "entrypoint":"test/p2",
  "module":"/policy.wasm",
  "annotations":[{
- "scope":"rule",
+ "scope":"document",
  "title":"P2",
  "entrypoint":true
  }]
@@ -767,10 +767,10 @@ package test
 # METADATA
 # title: P doc
 # scope: document
+# entrypoint: true
 
 # METADATA
 # title: P
-# entrypoint: true
 p := 1
 `,
  },
@@ -784,11 +784,11 @@ p := 1
  "module":"/policy.wasm",
  "annotations":[{
  "scope":"document",
- "title":"P doc"
+ "title":"P doc",
+ "entrypoint":true
  },{
  "scope":"rule",
- "title":"P",
- "entrypoint":true
+ "title":"P"
  }]
  }]
 }

compile/compile.go

@@ -255,20 +255,20 @@ func (c *Compiler) WithRegoVersion(v ast.RegoVersion) *Compiler {
  return c
 }
 
-func addEntrypointsFromAnnotations(c *Compiler, ar []*ast.AnnotationsRef) error {
- for _, ref := range ar {
+func addEntrypointsFromAnnotations(c *Compiler, arefs []*ast.AnnotationsRef) error {
+ for _, aref := range arefs {
  var entrypoint ast.Ref
- scope := ref.Annotations.Scope
+ scope := aref.Annotations.Scope
 
- if ref.Annotations.Entrypoint {
+ if aref.Annotations.Entrypoint {
  // Build up the entrypoint path from either package path or rule.
  switch scope {
  case "package":
- if p := ref.GetPackage(); p != nil {
+ if p := aref.GetPackage(); p != nil {
  entrypoint = p.Path
  }
- case "rule":
- if r := ref.GetRule(); r != nil {
+ case "document":
+ if r := aref.GetRule(); r != nil {
  entrypoint = r.Ref().GroundPrefix()
  }
  default:

compile/compile_test.go

@@ -2106,7 +2106,7 @@ q = true`,
  Annotations: []*ast.Annotations{
  {
  Title: "My P rule",
- Scope: "rule",
+ Scope: "document",
  Entrypoint: true,
  },
  },
@@ -2366,7 +2366,7 @@ func TestCompilerRegoEntrypointAnnotations(t *testing.T) {
  wantEntrypoints map[string]struct{}
  }{
  {
- note: "rule annotation",
+ note: "implied document scope annotation",
  entrypoints: []string{},
  modules: map[string]string{
  "test.rego": `

docs/content/policy-language.md

@@ -2687,8 +2687,12 @@ Since the `document` scope annotation applies to all rules with the same name in
 and the `package` and `subpackages` scope annotations apply to all packages with a matching path, metadata blocks with
 these scopes are applied over all files with applicable package- and rule paths.
 As there is no ordering across files in the same package, the `document`, `package`, and `subpackages` scope annotations
-can only be specified **once** per path.
-The `document` scope annotation can be applied to any rule in the set (i.e., ordering does not matter.)
+can only be specified **once** per path. The `document` scope annotation can be applied to any rule in the set (i.e.,
+ordering does not matter.)
+
+An `entrypoint` annotation implies a `scope` of either `package` or `document`. When `entrypoint` is set to `true` on a
+rule, the `scope` is automatically set to `document` if not explicitly provided. Setting the `scope` to `rule` will
+result in an error, as an entrypoint always applies to the whole document.
 
 #### Example
 
@@ -2708,6 +2712,17 @@ allow if {
 allow if {
  x == 2
 }
+
+# METADATA
+# entrypoint: true
+# description: |
+# `scope` annotation automatically set to `document`
+# as that is required for entrypoints
+message := "welcome!" if allow
+```
+
+```live:rego/metadata/scope:package:read_only
+
 ```
 
 ### Title
@@ -2890,7 +2905,8 @@ allow if {
 ### Entrypoint
 
 The `entrypoint` annotation is a boolean used to mark rules and packages that should be used as entrypoints for a policy.
-This value is false by default, and can only be used at `rule` or `package` scope.
+This value is false by default, and can only be used at `document` or `package` scope. When used on a rule with no
+explicit `scope` set, the presence of an `entrypoint` annotation will automatically set the scope to `document`.
 
 The `build` and `eval` CLI commands will automatically pick up annotated entrypoints; you do not have to specify them with
 [`--entrypoint`](../cli/#options-1).