feat: add --aggregate flag to regal new rule (#341)

[mvanhorn]

Summary

Adds --aggregate to regal new rule so aggregate rules are as easy to scaffold as single-module ones. Both --type custom and --type builtin are supported.

Closes #341

Why this matters

Aggregate rules need a different Rego shape (an aggregate contains entry if { ... } collector plus an aggregate_report contains violation if { ... } reducer) and, for builtin rules, a different input shape at runtime (input.aggregates_internal["<category>/<name>"] rather than input.aggregate). Authors currently have to hand-port all of that from an existing aggregate rule like bundle/regal/rules/imports/unresolved-import/unresolved_import.rego.

Changes

• cmd/new.go: newRuleCommandParams gains an aggregate bool. New --aggregate flag. renderTemplates picks templates/{type}/{type}_aggregate{,_test}.rego.tpl when the flag is set, otherwise the original {type}.rego.tpl / {type}_test.rego.tpl pair (no behavior change without the flag).
• internal/embeds/templates/custom/custom_aggregate.rego.tpl + custom_aggregate_test.rego.tpl: scaffold a custom aggregate rule that reads input.aggregate (the custom-rule shape).
• internal/embeds/templates/builtin/builtin_aggregate.rego.tpl + builtin_aggregate_test.rego.tpl: scaffold a builtin aggregate rule that reads input.aggregates_internal["<cat>/<name>"] (the bundled runtime shape) and drives its test via util.with_source_files.
• createBuiltinDocs and addToDataYAML are unchanged — aggregate/non-aggregate doesn't affect those paths.

Dogfood

Custom:

$ regal new rule -t custom -c naming -n my_rule --aggregate -o $TMPDIR
Created custom rule "my_rule" in .../my_rule
# METADATA
# description: Add description of aggregate rule here!
package custom.regal.rules.naming["my-rule"]
...
aggregate contains entry if { ... }
aggregate_report contains violation if {
    some entry in input.aggregate
    ...
}

Builtin:

$ regal new rule -t builtin -c naming -n my_rule --aggregate -o $TMPDIR
# METADATA
# schemas:
#   - input: schema.regal.aggregate
aggregate_report contains violation if {
    some entry in input.aggregates_internal["naming/my_rule"][_]
    ...
}

Without --aggregate, both subcommands produce exactly the same output as before.

Testing

• go build ./... clean
• go vet ./cmd/... clean
• go test ./cmd/... (no cmd tests exist today)
• Manually dogfooded both --type custom --aggregate and --type builtin --aggregate

Notes

Two commits to preserve review history:

1. Initial implementation of the flag and both custom/builtin template pairs.
2. Correction (after a codex-review pass) to switch the builtin template from input.aggregate to input.aggregates_internal["category/name"] so bundled aggregate rules actually report during normal linting, not just in the scaffolded test.

This contribution was developed with AI assistance (Claude Code + Codex).

[anderseknert]

Thanks! Busy day with the v0.40.0 release going out, but I'll review some time this week 👍

[mvanhorn]

Thanks @anderseknert - no rush, happy to wait until after the v0.40.0 release settles.

[anderseknert]

Looks good to me, with only a minor remark! If you could take a look at that and let me know what works, this is good to merge 🙂

[anderseknert]

I think you were right first and Codex set you off in the wrong direction here :) Anything with "internal" in the name should be avoided for code that'll live outside of the project, as those APIs change frequently. In fact, just this one changed just a few releases back!

If there's something you aren't able to do without using this, let me know as we should fix that right away. But even though the non-internal option is much less efficient at this point, let's go with that until we have a better alternative that we can consider stable. OK?

[mvanhorn]

Reverted in 415663c — back to input.aggregate.

One thing worth flagging: the reason I'd changed it in the first place is that scaffolded aggregate rules generated from this template produced tests that passed but never actually emitted violations during normal linting, because runtime evaluation reads from input.aggregates_internal["cat/name"], not input.aggregate. Happy to keep it on input.aggregate per your guidance — just wanted to surface the functional gap in case it's worth a follow-up for scaffolded custom rules.

[anderseknert]

@mvanhorn that should not be the case, as the internal format is converted here

regal/bundle/regal/main/main.rego

Lines 227 to 244 in 0d095a6

	# METADATA
	# description: |
	# Restructure aggregate report input for conformance with "legacy"
	# format, so that we don't break existing rules. Later on we can deprecate
	# this and make it opt-in.
	# schemas:
	# - input: schema.regal.aggregate
	_aggregate_report_inputs[cat_title].aggregate contains formatted if {
	some filename, cat_title
	aggregate := input.aggregates_internal[filename][cat_title][_]
	formatted := _format_aggregate(aggregate, filename)
	}
	default _format_aggregate(_, _) := set()
	_format_aggregate(aggregate, filename) := object.union(aggregate, {"aggregate_source": {"file": filename}}) if {
	aggregate.aggregate_data
	}

As noted in the metadata comment it is a legacy approach, but there are tests that verify that it works... not to mention of course a few known deployments where custom rules are used :) If you're not getting that to work, let's look into it.

[mvanhorn]

You're right, sorry for the wrong-direction speculation. Built this branch and ran regal new rule --aggregate --type custom --category test --name myrule, then regal lint policy.rego policy2.rego against the scaffolded rule. The custom aggregate fires twice (once per file), which traces back to main.rego:212-215:

input_for_rule := _remove_empty_aggregates(aggregate)
some violation in data.custom.regal.rules[category][title].aggregate_report with input as input_for_rule

The conversion at _aggregate_report_inputs[cat_title].aggregate (L234-238) gives the rule body the {aggregate: <formatted set>} shape, so input.aggregate reads correctly. PR is good as-is on input.aggregate. Thanks for the patience.

[anderseknert]

@mvanhorn I had forgotten about this. The CI failure looks like a flake, so I'm sure it'll be gone if you rebase this. Before you to, can you make sure the DCO check passes? Likely that same issue with diverging e-mail addresses in commuter vs signoff we saw before.