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.