feat: implement cronjob primitive by sourcehawk · Pull Request #19 · sourcehawk/operator-component-framework

sourcehawk · 2026-03-22T03:10:46Z

Implements the cronjob Kubernetes resource primitive following the pattern established by the existing ConfigMap and Deployment primitives.

Summary

Adds cronjob primitive package under pkg/primitives/cronjob/
Implements required lifecycle interfaces
Includes editors, mutator, flavors, and builder

Checklist

Compiles cleanly
Tests pass
Follows naming conventions in CONTEXT.md
Does not modify shared files

Copilot

Pull request overview

Adds a new cronjob primitive to the Operator Component Framework, extending the primitives layer with first-class support for reconciling Kubernetes batch/v1 CronJobs (builder/resource, mutator + editors, flavors), plus accompanying docs and an example.

Changes:

Introduces pkg/primitives/cronjob with builder/resource lifecycle integration, mutation planning/apply, flavors, and default handlers.
Adds new mutation editors for CronJobSpec and JobSpec under pkg/mutation/editors.
Adds docs and an end-to-end example; also updates repo lint config and a few existing test files.

Reviewed changes

Copilot reviewed 24 out of 24 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
pkg/primitives/cronjob/resource.go	CronJob primitive resource wrapper around generic IntegrationResource
pkg/primitives/cronjob/mutator.go	Plan/apply mutator for CronJob + containers/initContainers editing
pkg/primitives/cronjob/handlers.go	Default operational + suspension handlers for CronJob
pkg/primitives/cronjob/flavors.go	Field-application flavors for labels/annotations + pod template metadata
pkg/primitives/cronjob/builder.go	Fluent builder wiring defaults, mutations, flavors, handlers, extractors
pkg/primitives/cronjob/mutator_test.go	Extensive mutator behavior tests (ordering, selectors, nil-safety, etc.)
pkg/primitives/cronjob/handlers_test.go	Tests for default operational/suspension handlers
pkg/primitives/cronjob/flavors_test.go	Tests for flavor behavior and ordering
pkg/primitives/cronjob/builder_test.go	Builder validation and option wiring tests
pkg/mutation/editors/cronjobspec.go	New typed editor for `batchv1.CronJobSpec`
pkg/mutation/editors/cronjobspec_test.go	Tests for CronJobSpecEditor methods
pkg/mutation/editors/jobspec.go	New typed editor for `batchv1.JobSpec`
pkg/mutation/editors/jobspec_test.go	Tests for JobSpecEditor methods
pkg/component/suite_test.go	Removes revive nolint from dot-imports
pkg/component/component_test.go	Removes revive nolint from dot-imports
internal/generic/resource_task_test.go	Removes dupl nolint marker
internal/generic/resource_integration_test.go	Removes dupl nolint marker
examples/cronjob-primitive/resources/cronjob.go	Example resource factory assembling CronJob primitive with features/flavors
examples/cronjob-primitive/main.go	Runnable fake-client reconciliation demo exercising feature/suspend flows
examples/cronjob-primitive/features/mutations.go	Example feature mutations using the cronjob mutator/editors
examples/cronjob-primitive/app/controller.go	Example controller wiring a CronJob-backed component
examples/cronjob-primitive/README.md	Documentation for running and understanding the example
docs/primitives/cronjob.md	New primitive documentation for CronJob
.golangci.yml	Updates golangci-lint v2 config layout, enabled linters, and exclusions

pkg/mutation/editors/cronjobspec.go

.golangci.yml

docs/primitives/cronjob.md

pkg/primitives/cronjob/handlers.go

pkg/primitives/cronjob/mutator_test.go

Copilot

Pull request overview

Copilot reviewed 24 out of 24 changed files in this pull request and generated 3 comments.

.golangci.yml

docs/primitives/cronjob.md

pkg/primitives/cronjob/resource.go

sourcehawk · 2026-03-22T13:30:29Z

Claude Review Cycle 1 Complete

Addressed:

docs/primitives/cronjob.md line 9: Fixed capabilities table to use OperationPending instead of Pending to match the actual status value from concepts.OperationalStatusPending
pkg/primitives/cronjob/resource.go line 27: Added resource_test.go with comprehensive resource-level tests covering Identity, Object, Mutate (baseline, with mutation, feature ordering, custom field applicator + error), ConvergingStatus (custom handler, default pending, default operational), DeleteOnSuspend (custom handler, default false), Suspend (default handler, custom handler), SuspensionStatus (custom handler, default suspending, default suspended), ExtractData, and ExtractData error

Intentionally ignored:

.golangci.yml line 10: Comment asks to update PR description/checklist or move shared file changes to a separate PR. This is a PR description concern, not a code change. The .golangci.yml change (upgrading to valid v2 config) was a necessary prerequisite for the cronjob primitive to build correctly and is already in a prior commit.

Copilot

Pull request overview

Copilot reviewed 25 out of 25 changed files in this pull request and generated 2 comments.

.golangci.yml

pkg/primitives/cronjob/mutator.go

JobSpecEditor provides typed methods for Job spec fields (completions, parallelism, backoff limit, etc.). CronJobSpecEditor provides typed methods for CronJob spec fields (schedule, concurrency policy, time zone, etc.). The suspend field is intentionally excluded from CronJobSpecEditor as it is managed by the framework's suspension system. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Implements the CronJob primitive using IntegrationBuilder with Operational and Suspendable concepts. Key behaviors: - Operational status based on LastScheduleTime (Pending vs Operational) - Suspension via spec.suspend=true (DeleteOnSuspend=false) - Full pod-template mutation pipeline: metadata, cronjob spec, job spec, pod template metadata, pod spec, containers, init containers - Flavors for preserving labels, annotations, and pod template metadata Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Documents the Integration lifecycle, mutation pipeline ordering, editors (CronJobSpec, JobSpec, PodSpec, Container, ObjectMeta), operational status semantics, and suspension behavior. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Demonstrates building a CronJob resource with version-gated mutations, tracing/metrics features, field preservation flavors, suspension via spec.suspend, and data extraction. Uses the shared ExampleApp CRD and a fake client for standalone execution. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

- Fix container field paths in docs mutation ordering table to use full CronJob path (spec.jobTemplate.spec.template.spec.containers) - Use correct OperationPending status name in docs to match framework constant - Explicitly convert LastScheduleTime to UTC before formatting timestamp - Fix range variable address-of footgun in mutator_test.go findEnv helper Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Fix capabilities table in cronjob.md to use `OperationPending` instead of `Pending` to match the actual status value from the concepts package. Add resource_test.go for the cronjob primitive covering Identity, Object, Mutate, feature ordering, custom field applicator, ConvergingStatus, DeleteOnSuspend, Suspend, SuspensionStatus, and ExtractData. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

sourcehawk · 2026-03-23T00:43:18Z

approved

Copilot

Pull request overview

Copilot reviewed 25 out of 25 changed files in this pull request and generated 3 comments.

docs/primitives/cronjob.md

.golangci.yml

pkg/primitives/cronjob/mutator.go

…tive

The FeatureMutator interface in internal/generic used an unexported beginFeature() method, which meant primitive mutators in external packages (cronjob, deployment, configmap) could never satisfy the interface. The type assertion in ApplyMutations always returned false, so feature boundaries were silently skipped for all primitives. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

sourcehawk · 2026-03-23T02:58:11Z

Claude Review Cycle 1 Complete

Addressed:

beginFeature() unexported method bug (mutator.go:64): Exported beginFeature() → BeginFeature() on the FeatureMutator interface and all three primitive mutators (cronjob, deployment, configmap). The unexported method meant the interface could never be satisfied by types outside internal/generic, so ApplyMutations silently skipped all feature boundaries. Updated all call sites and tests.

Intentionally ignored:

Doc || table delimiters (cronjob.md:13): Invalid — the tables in the file already use standard single-pipe | format. No || delimiters exist.
.golangci.yml shared file / PR description checklist (.golangci.yml:21): Valid observation about PR description accuracy, but not a code change. The .golangci.yml timeout change was a necessary build fix. Shared test file changes were required for the BeginFeature export.

Copilot

Pull request overview

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

docs/primitives/cronjob.md

Rephrase the note about spec.suspend to acknowledge that Raw() can be used to set it, while still recommending the framework's suspend mechanism. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

sourcehawk · 2026-03-24T02:12:51Z

Claude Review Cycle 1 Complete

Addressed:

docs/primitives/cronjob.md:138 — Rephrased the spec.suspend note to clarify that no typed helper is provided but Raw() can be used, while recommending the framework's suspend mechanism.

Intentionally ignored:
None

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Copilot

Pull request overview

Copilot reviewed 33 out of 33 changed files in this pull request and generated 4 comments.

pkg/primitives/cronjob/flavors_test.go

internal/generic/mutate_helper.go

…semantics - Add require.NoError checks for Builder.Build() in all three TestMutate_OrderingAndFlavors subtests to fail clearly on builder validation errors instead of risking nil dereferences. - Add comment in ApplyMutations explaining why BeginFeature is not called before the first mutation (newMutator creates the initial scope). Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

sourcehawk · 2026-03-24T17:23:36Z

Claude Review Cycle 1 Complete

Addressed:

flavors_test.go:37 — Added require.NoError check for Builder.Build() in "flavors run after baseline applicator" test
flavors_test.go:67 — Added require.NoError check for Builder.Build() in "flavors run in registration order" test
flavors_test.go:83 — Added require.NoError check for Builder.Build() in "flavor error is returned with context" test
mutate_helper.go:48 — Added comment documenting that BeginFeature() is intentionally not called before the first mutation because newMutator() creates the initial planning scope

Intentionally ignored:
None

…tive

Apply the same pattern from deployment/configmap: NewMutator no longer creates an initial feature plan. BeginFeature must be called before registering mutations. Also fix mutate_helper to call BeginFeature before every mutation (including the first). Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Copilot

Pull request overview

Copilot reviewed 33 out of 33 changed files in this pull request and generated no new comments.

…tive Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Align with framework-wide SSA refactor: remove DefaultFieldApplicator, WithCustomFieldApplicator, WithFieldApplicationFlavor, flavors.go, and update tests to use Object() output instead of empty structs in Mutate(). Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

sourcehawk requested a review from Copilot March 22, 2026 03:44

Copilot started reviewing on behalf of sourcehawk March 22, 2026 03:45 View session

Copilot AI reviewed Mar 22, 2026

View reviewed changes

sourcehawk requested a review from Copilot March 22, 2026 13:21

Copilot started reviewing on behalf of sourcehawk March 22, 2026 13:22 View session

Copilot AI reviewed Mar 22, 2026

View reviewed changes

.golangci.yml Show resolved Hide resolved

docs/primitives/cronjob.md Outdated Show resolved Hide resolved

pkg/primitives/cronjob/resource.go Show resolved Hide resolved

Copilot AI review requested due to automatic review settings March 22, 2026 19:48

Copilot started reviewing on behalf of sourcehawk March 22, 2026 19:49 View session

Copilot AI reviewed Mar 22, 2026

View reviewed changes

.golangci.yml Show resolved Hide resolved

pkg/primitives/cronjob/mutator.go Outdated Show resolved Hide resolved

Copilot AI review requested due to automatic review settings March 23, 2026 00:42

Copilot started reviewing on behalf of sourcehawk March 23, 2026 00:42 View session

sourcehawk and others added 11 commits March 23, 2026 00:43

update golangci-lint to be valid v2

009f807

address linter warnings

e244f20

preserve server-managed metadata in default field applicator

7c8e5ac

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Add timeout setting for golangci-lint

ad7dbb0

Update pkg/primitives/cronjob/mutator.go

5058194

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

sourcehawk force-pushed the feature/cronjob-primitive branch from 563d078 to 5058194 Compare March 23, 2026 00:43

Copilot AI reviewed Mar 23, 2026

View reviewed changes

docs/primitives/cronjob.md Outdated Show resolved Hide resolved

.golangci.yml Show resolved Hide resolved

pkg/primitives/cronjob/mutator.go Outdated Show resolved Hide resolved

sourcehawk and others added 2 commits March 23, 2026 02:54

Merge remote-tracking branch 'origin/main' into feature/cronjob-primi…

c65f548

…tive

fix linter

8f1e3a4

sourcehawk requested review from Copilot and removed request for Copilot March 24, 2026 02:10

Copilot AI reviewed Mar 24, 2026

View reviewed changes

docs/primitives/cronjob.md Outdated Show resolved Hide resolved

docs: clarify spec.suspend note in cronjob documentation

498d264

Rephrase the note about spec.suspend to acknowledge that Raw() can be used to set it, while still recommending the framework's suspend mechanism. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Copilot started reviewing on behalf of sourcehawk March 24, 2026 02:13 View session

Copilot started reviewing on behalf of sourcehawk March 24, 2026 02:16 View session

Copilot started reviewing on behalf of sourcehawk March 24, 2026 02:17 View session

style: format cronjob docs with prettier

7b7bbd2

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Copilot AI review requested due to automatic review settings March 24, 2026 17:15

Copilot started reviewing on behalf of sourcehawk March 24, 2026 17:15 View session

sourcehawk requested review from Copilot and removed request for Copilot March 24, 2026 17:17

Copilot started reviewing on behalf of sourcehawk March 24, 2026 17:18 View session

sourcehawk requested review from Copilot and removed request for Copilot March 24, 2026 17:18

Copilot started reviewing on behalf of sourcehawk March 24, 2026 17:18 View session

sourcehawk requested review from Copilot and removed request for Copilot March 24, 2026 17:19

Copilot AI reviewed Mar 24, 2026

View reviewed changes

Copilot started reviewing on behalf of sourcehawk March 24, 2026 17:20 View session

sourcehawk and others added 2 commits March 24, 2026 17:51

Merge remote-tracking branch 'origin/main' into feature/cronjob-primi…

5dec6ad

…tive

Copilot AI review requested due to automatic review settings March 24, 2026 17:58

Copilot started reviewing on behalf of sourcehawk March 24, 2026 17:58 View session

Copilot AI reviewed Mar 24, 2026

View reviewed changes

sourcehawk and others added 2 commits March 25, 2026 14:04

Merge remote-tracking branch 'origin/main' into feature/cronjob-primi…

9fffcc4

…tive Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Conversation

sourcehawk commented Mar 22, 2026

Summary

Checklist

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

sourcehawk commented Mar 22, 2026

Claude Review Cycle 1 Complete

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

sourcehawk commented Mar 23, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

sourcehawk commented Mar 23, 2026

Claude Review Cycle 1 Complete

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

sourcehawk commented Mar 24, 2026

Claude Review Cycle 1 Complete

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

sourcehawk commented Mar 24, 2026

Claude Review Cycle 1 Complete

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants