Skip to content

Latest commit

 

History

History
155 lines (116 loc) · 8 KB

README.md

File metadata and controls

155 lines (116 loc) · 8 KB

oape Plugin

AI-driven OpenShift operator development tools, following OpenShift and Kubernetes API conventions.

Commands

/oape:init

Clones an allowed OpenShift operator repository by short name into the current directory so that subsequent /oape:* commands can operate immediately.

Usage:

/oape:init cert-manager-operator

What it does:

  1. Prechecks -- Validates the short name argument, required tools (git, gh), and GitHub authentication.
  2. Repository Resolution -- Matches the short name against the allowlist (case-insensitive, with partial match disambiguation).
  3. Clone -- Runs git clone --filter=blob:none into the current working directory. If the directory already exists with the correct remote, reuses it.
  4. Verify -- Changes into the cloned directory and reports the Go module and detected framework.

/oape:api-generate

Reads an OpenShift enhancement proposal PR, extracts the required API changes, and generates compliant Go type definitions in the correct paths of the current OpenShift operator repository.

Usage:

/oape:api-generate https://github.com/openshift/enhancements/pull/1234

What it does:

  1. Prechecks -- Validates the PR URL, required tools (gh, go, git), GitHub authentication, repository type (must be an OpenShift operator repo with openshift/api dependency), and PR accessibility. Fails immediately if any precheck fails.
  2. Knowledge Refresh -- Fetches and internalizes the latest OpenShift and Kubernetes API conventions before generating any code.
  3. Enhancement Analysis -- Reads the enhancement proposal to extract API group, version, kinds, fields, validation requirements, feature gate info, and whether it is a configuration or workload API.
  4. Code Generation -- Generates or modifies Go type definitions following conventions derived from the authoritative documents and patterns from the existing codebase.
  5. FeatureGate Registration -- Adds FeatureGate to features.go when applicable.

/oape:api-generate-tests

Generates .testsuite.yaml integration test files for OpenShift API type definitions. Reads Go types, CRD manifests, and validation markers to produce comprehensive test suites.

Usage:

/oape:api-generate-tests api/v1alpha1/myresource_types.go

What it does:

  1. Prechecks -- Verifies the repository, identifies target API types, and checks for CRD manifests.
  2. Type Analysis -- Reads Go types to extract fields, validation markers, enums, unions, immutability rules, and feature gates.
  3. Test Generation -- Generates test cases covering: minimal valid create, valid/invalid field values, update scenarios, immutable fields, singleton name validation, discriminated unions, feature-gated fields, and status subresource tests.
  4. File Output -- Writes .testsuite.yaml files following the repo's existing naming and directory conventions.

/oape:api-implement

Reads an OpenShift enhancement proposal PR, extracts the required implementation logic, and generates complete controller/reconciler code following controller-runtime and operator-sdk conventions.

Usage:

/oape:api-implement https://github.com/openshift/enhancements/pull/1234

What it does:

  1. Prechecks -- Validates the PR URL, required tools (gh, go, git, make), GitHub authentication, repository type (controller-runtime or library-go), and PR accessibility.
  2. Knowledge Refresh -- Fetches and internalizes the latest controller-runtime patterns and operator best practices.
  3. Enhancement Analysis -- Reads the enhancement proposal to extract business logic requirements, reconciliation workflow, conditions, events, and error handling.
  4. Pattern Detection -- Identifies the controller layout pattern used in the repository.
  5. Code Generation -- Generates complete Reconcile() logic, SetupWithManager, finalizer handling, status updates, and event recording.
  6. Controller Registration -- Adds the new controller to the manager.

Typical Workflow:

# Clone the operator repository (if not already cloned)
/oape:init cert-manager-operator

# Generate the API types
/oape:api-generate https://github.com/openshift/enhancements/pull/1234

# Generate integration tests for the new types
/oape:api-generate-tests api/v1alpha1/myresource_types.go

# Generate the controller implementation
/oape:api-implement https://github.com/openshift/enhancements/pull/1234

/oape:review

Performs a "Principal Engineer" level code review that verifies code changes against Jira requirements.

Usage:

/oape:review OCPBUGS-12345
/oape:review OCPBUGS-12345 origin/release-4.15

What it does:

  1. Fetches Jira Issue -- Retrieves the ticket details and acceptance criteria
  2. Analyzes Git Diff -- Gets changes between base ref and HEAD
  3. Reviews Code -- Applies four review modules:
    • Golang Logic & Safety: Intent matching, execution traces, edge cases, context usage, concurrency, error handling
    • Bash Scripts: Safety patterns, variable quoting, temp file handling
    • Operator Metadata (OLM): RBAC updates, finalizer handling
    • Build Consistency: Generation drift detection
  4. Generates Report -- Returns structured JSON with verdict, issues, and fix prompts
  5. Applies Fixes Automatically -- When issues are found, invokes implement-review-fixes.md to apply the suggested code changes in severity order (CRITICAL first), then verifies the build still passes

/oape:e2e-generate

Generates e2e test artifacts for any OpenShift operator repository by discovering the repo structure and analyzing the git diff from a base branch.

Usage:

# Generate e2e tests for changes since main
/oape:e2e-generate main

# Use a specific base branch and custom output directory
/oape:e2e-generate origin/release-4.18 --output .work

What it does:

  1. Prechecks -- Validates the base branch argument, required tools (git, go), repository type (must be an OpenShift operator repo with controller-runtime or library-go), and verifies a non-empty git diff.
  2. Discovery -- Detects framework (controller-runtime vs library-go), API types, CRDs, existing e2e test patterns, install mechanism (OLM or manual), operator namespace, and sample CRs.
  3. Diff Analysis -- Categorizes changed files (API types, controllers, CRDs, RBAC, samples) and reads diff hunks to understand specific changes.
  4. Generation -- Produces four files in output/e2e_<repo-name>/:
    • test-cases.md -- Test scenarios with context, prerequisites, install, CR deployment, diff-specific tests, verification, cleanup
    • execution-steps.md -- Step-by-step oc commands
    • e2e_test.go or e2e_test.sh -- Go (Ginkgo) or bash test code matching the repo's existing e2e pattern
    • e2e-suggestions.md -- Coverage recommendations

Supports:

  • controller-runtime operators (Ginkgo e2e) -- e.g., cert-manager-operator, external-secrets-operator
  • library-go operators (bash e2e) -- e.g., secrets-store-csi-driver-operator
  • Operators with in-repo API types or external types from openshift/api

See e2e-test-generator/ for fixture templates and pattern documentation.

Prerequisites

  • go -- Go toolchain
  • git -- Git
  • gh (GitHub CLI) -- installed and authenticated (for api-generate, api-implement, review)
  • make -- Make (for api-implement)
  • curl -- For fetching Jira issues (for review)
  • oc -- OpenShift CLI (recommended, for running generated execution steps)
  • Must be run from within an OpenShift operator repository

Conventions Enforced