Review Rego snippets in docs and update to follow current best practices

[anderseknert]

Some things to consider for the review. Obviously up for discussion!

• Use := for file level assignments
• Prefer foo in bar over foo == bar[_] or foo[bar]
• Prefer some foo in bar over foo := bar[_], some foo, bar in baz over bar := baz[foo]
• Prefer every foo in bar { .. } over iteration with helper rules
• Prefer metadata annotations over comments on rules and packages

Additionally, we should use opa fmt for consistent formatting of snippets, and use opa check --strict to catch mistakes (unless of course that's what's being demonstrated in a snippet).

[johanfylling]

Perhaps we could update the build step (or add a linting step) for docs to automatically search for rego blocks and diff those against the output of opa fmt for that same block 🤔 .

[srenatus]

@johanfylling totally. unfortunately, there's another prereq to that: #4104 (now #4508)

[srenatus]

💭 Actually, we don't have to have opa fmt operate on things less-than-a-module if we integrate the check with live-blocks. The live-blocks scripts will at some point assemble the complete module, and feed it into opa eval, so we could also have an opa fmt check there.

[stale]

This issue has been automatically marked as inactive because it has not had any activity in the last 30 days.

[anderseknert]

This eventually culminated into the Rego Style Guide. Having a mix of styles in the docs could actually be good, I think, as long as the recommended path is documented somewhere. Closing this for now, but if someone feels that there are some particular part of our docs that need an update, do holler out!