Not clear why metadata attribute `entrypoint` requires `scope: rule`

[anderseknert]

Having worked on some Regal rules around metadata annotations recently, and the ambiguous-scope rule specifically, I was surprised to see that the entrypoint attribute worked for annotations scoped to rule. AFAIK, an entrypoint will always point to the "whole" rule — in other words the document. I thought it was just an oversight, and a (by all means, harmless) bug that something silly like defining an incremental rule where one is entrypoint: true and the other is entrypoint: false was allowed, as clearly both will be evaluated when one of them is marked as an entrypoint?

But now that I tried to change the scope to document, that's apparently a parser error 🤔

package policy

import rego.v1

# METADATA
# entrypoint: true
# scope: document
allow = true

1 error occurred: p.rego:5: rego_parse_error: annotation entrypoint applied to non-rule or package scope 'document'

Which had me check the documentation on entrypoint, and the docs confirm this too:

This value is false by default, and can only be used at rule or package scope.

So while this isn't a bug in the sense that something isn't working as intended or documented — this doesn't seem right to me? Isn't an entrypoint on a rule always scoped to the whole rule (i.e. the document) rather than a specific rule definition?

[tsandall]

Agreed that entrypoint is applicable to document or package (or I suppose, subpackages) but rule does not make sense (and similarly, if we had a file scope, it wouldn't make sense either.) I'm guessing this was just an oversight in the original implementation.

After having used annotations a fair amount recently I would say that having to specify the scope is a bit of a pain and most often felt with the document scope. It's just another thing that users can get wrong.

I wonder if we could default the scope differently than we already do today... the current defaults are based on the place in the file, e.g., preceeding a package makes it package scope and preceeding a rule makes it rule scope. Instead of using the file location, what if each type of annotation had a required scope... then the default/inferred scope would be the maximum scope of all the annotations in the METADATA snippet.

[johanfylling]

Changing the default scope of annotations is a semantic change. Would this be a v1 feature? Or, to not risk pushing that release back even further with additional changes, even v2 (assuming we tighten the major version cadence)?

[stale[bot]]

This issue has been automatically marked as inactive because it has not had any activity in the last 30 days. Although currently inactive, the issue could still be considered and actively worked on in the future. More details about the use-case this issue attempts to address, the value provided by completing it or possible solutions to resolve it would help to prioritize the issue.