feat(builders): variadic WithMutation for slice-returning factories

[sourcehawk]

Description

Closes #123

WithMutation now accepts a variadic list of mutations, so mutation factories that
return []Mutation compose directly inside a fluent builder chain instead of forcing
a for _, m := range factory() { b = b.WithMutation(m) } break. The change is a pure
widening: every existing single-argument WithMutation(x) call compiles and behaves
exactly as before, and no methods are added or removed.

Changes

• Widen WithMutation to WithMutation(ms ...Mutation) on all 5 generic builders
  (base, static, workload, task, integration).
• Widen WithMutation on all 25 primitive builders (21 typed primitives + 4
  unstructured wrappers); mutations register in argument order, and WithMutation()
  with no arguments is a no-op.
• Update GoDoc on every widened method and document the variadic form (with the
  WithMutation(factory()...) spread pattern) in docs/primitives.md and
  docs/custom-resource.md.

Testing

• TDD: added generic-builder subtests (pkg/generic/builder_static_test.go) and
  statefulset subtests (pkg/primitives/statefulset/builder_test.go) covering
  multi-argument registration order, slice spread, and the zero-argument no-op.
• make all (build, lint, format, go test ./...) and make build-examples both pass.

[Copilot]

Pull request overview

This PR widens the builder API across the framework to allow registering multiple mutations in a single fluent call by making WithMutation variadic, enabling direct composition with slice-returning mutation factories (e.g. WithMutation(factory()...)).

Changes:

• Updated generic builders (BaseBuilder, and the workload/static/task/integration wrappers) so WithMutation accepts ...Mutation and preserves registration order (with zero-arg as a no-op).
• Updated primitive builders (typed primitives + unstructured wrappers) so WithMutation accepts ...Mutation and registers mutations in argument order.
• Added/updated documentation and tests to cover variadic registration, slice spreading, ordering, and the zero-arg no-op.

Reviewed changes

Copilot reviewed 34 out of 34 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
pkg/primitives/unstructured/workload/builder.go	Make WithMutation variadic for unstructured workload builder.
pkg/primitives/unstructured/task/builder.go	Make WithMutation variadic for unstructured task builder.
pkg/primitives/unstructured/static/builder.go	Make WithMutation variadic for unstructured static builder and update method docs.
pkg/primitives/unstructured/integration/builder.go	Make WithMutation variadic for unstructured integration builder.
pkg/primitives/statefulset/builder.go	Make WithMutation variadic for StatefulSet builder.
pkg/primitives/statefulset/builder_test.go	Add tests for variadic ordering, slice spread, and zero-arg no-op.
pkg/primitives/serviceaccount/builder.go	Make WithMutation variadic for ServiceAccount builder.
pkg/primitives/service/builder.go	Make WithMutation variadic for Service builder.
pkg/primitives/secret/builder.go	Make WithMutation variadic for Secret builder.
pkg/primitives/rolebinding/builder.go	Make WithMutation variadic for RoleBinding builder.
pkg/primitives/role/builder.go	Make WithMutation variadic for Role builder.
pkg/primitives/replicaset/builder.go	Make WithMutation variadic for ReplicaSet builder.
pkg/primitives/pvc/builder.go	Make WithMutation variadic for PVC builder.
pkg/primitives/pv/builder.go	Make WithMutation variadic for PV builder.
pkg/primitives/pod/builder.go	Make WithMutation variadic for Pod builder.
pkg/primitives/pdb/builder.go	Make WithMutation variadic for PodDisruptionBudget builder.
pkg/primitives/networkpolicy/builder.go	Make WithMutation variadic for NetworkPolicy builder.
pkg/primitives/job/builder.go	Make WithMutation variadic for Job builder.
pkg/primitives/ingress/builder.go	Make WithMutation variadic for Ingress builder.
pkg/primitives/hpa/builder.go	Make WithMutation variadic for HPA builder.
pkg/primitives/deployment/builder.go	Make WithMutation variadic for Deployment builder.
pkg/primitives/daemonset/builder.go	Make WithMutation variadic for DaemonSet builder.
pkg/primitives/cronjob/builder.go	Make WithMutation variadic for CronJob builder.
pkg/primitives/configmap/builder.go	Make WithMutation variadic for ConfigMap builder.
pkg/primitives/clusterrolebinding/builder.go	Make WithMutation variadic for ClusterRoleBinding builder.
pkg/primitives/clusterrole/builder.go	Make WithMutation variadic for ClusterRole builder.
pkg/generic/builder_workload.go	Propagate variadic WithMutation through generic workload builder wrapper.
pkg/generic/builder_task.go	Propagate variadic WithMutation through generic task builder wrapper.
pkg/generic/builder_static.go	Propagate variadic WithMutation through generic static builder wrapper.
pkg/generic/builder_static_test.go	Add tests for variadic mutation registration semantics on generic static builder.
pkg/generic/builder_integration.go	Propagate variadic WithMutation through generic integration builder wrapper.
pkg/generic/builder_base.go	Implement variadic WithMutation in the generic base builder (append in order; zero args no-op).
docs/primitives.md	Document variadic WithMutation, ordering, and slice spread pattern for primitives.
docs/custom-resource.md	Update custom resource wrapper docs to show variadic WithMutation and slice-returning factories.