Extend METADATA scopes to include "file" scope

[tsandall]

Currently we have subpackages, package, document, and rule scoped annotations. These each of their own valid use cases however none of them are ideal for applying annotations to all nodes in the current file. The package scope can work however if multiple files contribute to the same package then we generate an error. It would be useful to have a file scope. The file scope annotation should precede the package directive (however the 'package' scope directive should still be the default.)

[anderseknert]

Some thoughts:

• I tend to think of metadata comments as documenting the "public API" of Rego policies (similar to Javadocs, Go docs, etc). While a file scope makes sense in an editor, what would it mean for a tool that generate docs from metadata annotations? In that context, you wouldn't know which file it referred to. I guess they could just skip anything scoped to file.
• How would this work with things like --optimize, where files are merged, renamed and whatnot? The annotations are kept in the process, but they would now apply to a different context than they did before.
• More of a note, but just like with the rule scope, attributes like entrypoint should not be allowed for this scope.

[stale]

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.