From baf23e21cffcf796dcd1fd5896d05403d0ff8822 Mon Sep 17 00:00:00 2001 From: Raushan Singh Date: Fri, 8 May 2026 16:47:39 +0530 Subject: [PATCH] OAPE-687: update api-implement and api-generate after running benchmarking tool across few EPs --- plugins/oape/commands/api-generate.md | 30 +++++++++++++++++++++++ plugins/oape/commands/api-implement.md | 34 ++++++++++++++++++++++++++ 2 files changed, 64 insertions(+) diff --git a/plugins/oape/commands/api-generate.md b/plugins/oape/commands/api-generate.md index ad2bf51..b5d0569 100644 --- a/plugins/oape/commands/api-generate.md +++ b/plugins/oape/commands/api-generate.md @@ -458,6 +458,32 @@ Generate or modify Go type definitions based on the enhancement proposal. This m types, new fields, modifications to existing fields, enum types, discriminated unions, or type registration. +#### Pre-generation traceability check + +Before writing any code, list every field/type being added, modified, or removed. For each one, +cite the specific sentence or section in the input sources that requires it. If a change cannot +be traced to a specific requirement, do NOT make it. + +#### File scope guard + +Only create or modify files under `api/` or type-definition directories (e.g., `features/`). +If you are about to write a file under `controllers/`, `pkg/controller/`, `internal/controller/`, +`pkg/operator/`, `cmd/`, or `bindata/`, STOP — that belongs in `api-implement`, not here. + +**Hard deny-list — NEVER create or modify files matching ANY of these patterns:** +- `controllers/**` or `pkg/controller/**` or `internal/controller/**` (controller logic) +- `pkg/operator/**` (operator logic) +- `cmd/**` or `main.go` (entrypoints and scheme registration) +- `bindata/**` (static resource manifests) +- `**/constant.go` or `**/constants.go` outside `api/` (controller constants) +- `**/networkpolicies.go`, `**/federation.go`, `**/template.go` (implementation files) + +Even if new API fields imply controller behavior (e.g., new fields need env vars, new types need +resource builders), do NOT generate those files. Only generate the types and note the implied +controller work in the summary under "Deferred to api-implement". + +#### Generation rules + For every marker, tag, or convention applied: derive it from the fetched convention documents (Phase 1) or the existing code (Phase 4). Conventions take precedence when both differ. Existing patterns not covered by conventions (e.g., mechanical code-gen markers) should be replicated for @@ -552,6 +578,10 @@ When failing, provide a clear error message explaining: 5. **Idempotent**: Running this command multiple times with the same inputs should produce the same result (though it should warn if files already exist). 6. **Minimal changes**: Only generate what the input sources specify. Do not add extra fields, types, or features not described. 7. **Surgical edits**: When modifying existing files, only change what the input sources require. Preserve all unrelated code, comments, and formatting. For modifications to existing fields, clearly document what changed and why in the output summary. +8. **API types only — no controller code**: This command MUST only create or modify files in API-layer directories (`api/`, `features/`, type definition files). Do NOT create or modify files in controller directories (`controllers/`, `pkg/controller/`, `internal/controller/`, `pkg/operator/`, `cmd/`, `bindata/`). If the EP describes controller behavior, note it in the summary under "Deferred to api-implement" but generate zero controller code. +9. **No invented fields**: Do NOT add fields, types, or enum values that the input sources do not explicitly specify. If the EP adds field X, only add field X — do not also add a related field Y you think "should" exist. +10. **No restructuring**: Do NOT rename existing fields, change pointer-vs-value semantics on existing fields, or move fields between structs unless the input sources explicitly require it. When the EP says "remove field X", only remove field X. Do NOT modernize, reformat, or "improve" existing comments, type names, or field ordering on untouched fields. +11. **No controller-layer files**: Do NOT create files under `controllers/`, `pkg/controller/`, `bindata/`, `cmd/`, or `pkg/operator/`. This includes constants files, helper files, and resource builders that serve controller logic. If new API fields imply controller wiring, list the implied work in the summary — do not generate it. ## Arguments diff --git a/plugins/oape/commands/api-implement.md b/plugins/oape/commands/api-implement.md index 42c90ba..ee9ad9d 100644 --- a/plugins/oape/commands/api-implement.md +++ b/plugins/oape/commands/api-implement.md @@ -628,6 +628,27 @@ find "$REPO_ROOT" -type f -name 'starter.go' -not -path '*/vendor/*' | head -5 ### Phase 5: Read Existing Controller Code for Context +#### 5.1 Find existing controller for the target resource + +```bash +# Search for an existing controller that already reconciles the target resource type. +# Check Reconcile/Sync methods, SetupWithManager, and For() calls for the target Kind. +grep -r "For(&.*{}\|()\|Reconcile.*" "$REPO_ROOT" --include='*.go' -l | grep -v vendor | grep -v _output | head -10 +``` + +```thinking +CRITICAL: If an existing controller already reconciles this resource type, I MUST modify it +rather than create a new controller file. I will: +1. Read ALL files in the existing controller's package (controller.go, constants.go, helpers, resource builders) +2. Add new logic into the existing Reconcile/Sync flow +3. Add constants to existing constant files, not new ones +4. Add resource builders to existing builder files, not new ones + +I only create a NEW controller file when NO existing controller handles this resource type. +``` + +#### 5.2 Read existing controller patterns + ```bash # Find sample controller based on OPERATOR_TYPE if [ "$OPERATOR_TYPE" = "library-go" ]; then @@ -656,8 +677,16 @@ I MUST read existing controller(s) and extract these EXACT patterns to replicate 10. **Resource creation** - How dependent resources are created 11. **Error handling** - How errors are wrapped and returned 12. **Constants** - Where constants are defined (same file, separate file) +13. **Resource builder files** - Are there template.go / builder files that construct Jobs, Deployments, etc.? Read ALL files in the controller package, not just the main controller file. +14. **Function signatures** - Do builder functions accept individual params or whole spec structs? Match their style when adding new parameters. I will replicate these patterns EXACTLY in generated code. + +**CRITICAL pre-generation checklist:** +- For each new spec field, find the existing file where its parent resource is built/used. Modify THAT file — do not create a new file. +- If constants already exist in a constants file, add new constants there. +- If the controller already has a builder function for the resource type (e.g., getJobTemplate, buildDeployment), add parameters to that function. +- Only create new files for genuinely new resource types or controllers that have no existing equivalent. ``` --- @@ -1387,6 +1416,11 @@ The command MUST FAIL and STOP immediately if ANY of the following are true: 9. **Status-first**: Always use Status().Update() for status changes 10. **Finalizer safety**: Add before external resources, remove after cleanup 11. **Event recording**: Record events for user-visible state changes +12. **Integrate, don't duplicate**: Most EPs add functionality to EXISTING controllers. Before creating any new controller file, search for an existing controller that already reconciles the same resource type. If one exists, modify it to add the new behavior — add logic to existing Reconcile/Sync methods, add helpers to existing resource-builder files, add constants to existing constant files. Only create a NEW controller when no existing controller handles the target resource type, or the EP explicitly specifies a new controller. +13. **No invented logic**: Do NOT add controller behavior (constants, helper files, resource builders) that the input sources do not describe. If the EP only adds API fields, only wire those fields into the existing reconciliation — do not create standalone feature files. +14. **Wire new fields into existing flows**: When the EP adds fields to an existing type, find the existing code that builds or uses that type (e.g., Job templates, Deployment specs, container env vars) and wire the new fields there. Do not create a separate file per new field — add the logic inline where the resource is already being constructed. +15. **Update scheme and imports**: When new API types are introduced (e.g., `routev1`, `networkingv1`), update `cmd/*/main.go` or equivalent entrypoints to register the new scheme and add the import. Also update any `pkg/client/` setup files that initialize shared schemes. +16. **Update existing resource builders**: If the repo has template/builder files that construct Jobs, Deployments, or other resources, modify those files to pass through new spec fields (e.g., add parameters to existing builder functions, add env vars to existing container specs). Do not create parallel builder files. ## Arguments