refactor!: move generated plugin clients to top-level plugins/

Delete the hand-written v4 plugins/{ism,security} clients and promote the
spec-generated tree from opensearchapi/plugins/ to top-level plugins/
(import path .../v5/plugins/<name>). The generated clients cover all 25
plugins and supersede the 2 hand-written ones. Retarget cmd/osgen
(DefaultPluginsImportBase, importPathForGroup) and the Makefile to emit at
plugins/, and add plugins/ to the check-gen diff.

BREAKING CHANGE: plugin import paths move from
github.com/opensearch-project/opensearch-go/v4/plugins/{ism,security} to
github.com/opensearch-project/opensearch-go/v5/plugins/<name>.

Signed-off-by: Sean Chittenden <sean.chittenden@crowdstrike.com>

Author: sean-

.github/workflows/check-gen.yml

@@ -17,7 +17,7 @@ jobs:
         run: make -j gen
       - name: Check for diff
         run: |
-          if ! git diff --exit-code internal/path/builders_gen.go internal/path/builders_gen_test.go opensearchapi/; then
+          if ! git diff --exit-code internal/path/builders_gen.go internal/path/builders_gen_test.go opensearchapi/ plugins/; then
             echo "::warning::Generated code is out of date. Run 'make gen' and commit the result."
             exit 1
           fi

.golangci.yml

@@ -162,7 +162,7 @@ linters:
         path: opensearchtransport/opensearchtransport.go
       - linters:
           - dupl
-        path: (-params\.go|api_indices|api_dangling\.go|api_point_in_time\.go|rethrottle\.go|api_cat-.*\.go|plugins/security/api_\w+.go|plugins/security/api_.*-patch.go|_gen\.go)
+        path: (-params\.go|api_indices|api_dangling\.go|api_point_in_time\.go|rethrottle\.go|api_cat-.*\.go|_gen\.go)
       # Generated code emits long lines from upstream spec descriptions, table
       # rows, and inline struct literals that lose readability if wrapped at the
       # template level.

DEVELOPER_GUIDE.md

@@ -385,7 +385,7 @@ make gh.checks.failed     # Only failed checks
 
 ## Code Generation
 
-The `cmd/osgen` tool generates typed path builder structs (`internal/path/`) and API consumer files (`opensearchapi/`, `opensearchapi/plugins/`) from the published [OpenSearch API specification](https://github.com/opensearch-project/opensearch-api-specification). It reads `x-operation-group`, `x-version-added`, `x-version-deprecated`, `x-version-removed`, and `x-error-responses` extensions from the spec to produce version-aware Go source.
+The `cmd/osgen` tool generates typed path builder structs (`internal/path/`) and API consumer files (`opensearchapi/`, `plugins/`) from the published [OpenSearch API specification](https://github.com/opensearch-project/opensearch-api-specification). It reads `x-operation-group`, `x-version-added`, `x-version-deprecated`, `x-version-removed`, and `x-error-responses` extensions from the spec to produce version-aware Go source.
 
 The `opensearchapi/` package is the code-generated v5 API surface, produced by `cmd/osgen` from the spec. See `opensearchapi/README.md` for usage and `UPGRADING.md` for migration guidance.
 

Makefile

@@ -160,7 +160,7 @@ OPENAPI_SPEC_URL := https://github.com/opensearch-project/opensearch-api-specifi
 # Generated code output directories.
 GEN_PATH_DIR    := $(REPO_ROOT)/internal/path
 GEN_OSAPI_DIR   := $(REPO_ROOT)/opensearchapi
-GEN_PLUGINS_DIR := $(GEN_OSAPI_DIR)/plugins
+GEN_PLUGINS_DIR := $(REPO_ROOT)/plugins
 
 # Version filtering defaults for code generation.
 # Override on the command line to scope generated code to a version window:

UPGRADING.md

@@ -205,7 +205,7 @@ client, err := opensearchapi.NewClient(opensearchapi.Config{...})
 - Optional `Params` are `*Params` pointer fields (nil-safe; pass `&opensearchapi.IndexParams{...}` to set).
 - Optional boolean query parameters are `*bool` so a deliberate `false` can be sent over the wire.
 - Multi-index `Req` types use `Index []string` (the spec spelling); v4's hand-written `Indices` is renamed.
-- Plugin APIs (k-NN, ML, Security, ISM, etc.) live in `opensearchapi/plugins/`.
+- Plugin APIs (k-NN, ML, Security, ISM, etc.) live in top-level `plugins/<name>` packages, imported as `github.com/opensearch-project/opensearch-go/v5/plugins/<name>`. v4's hand-written plugin clients (`opensearch-go/v4/plugins/{ism,security}`) are replaced by generated, spec-driven clients covering all 25 plugins; the package qualifier (e.g. `ism.X`) is unchanged.
 
 For the full v4 -> v5 surface delta and the optional forward-compatible `replace` directive, see [`opensearchapi/MIGRATING.md`](opensearchapi/MIGRATING.md). For everyday usage (errors, routing, response handling) see [`opensearchapi/README.md`](opensearchapi/README.md).
 

cmd/osgen/README.md

@@ -89,7 +89,7 @@ Generates API consumer files into `opensearchapi/` and plugin directories.
 | `-spec`                          | required | Path to the combined OpenAPI spec YAML                                      |
 | `-out`                           | required | Output directory for core API files (e.g. `opensearchapi/`)       |
 | `-pkg`                           | required | Go package name for generated files (e.g. `opensearchapi`)                  |
-| `-plugins-out`                   | (none)   | Output directory for plugin files (e.g. `opensearchapi/plugins/`) |
+| `-plugins-out`                   | (none)   | Output directory for plugin files (e.g. `plugins/`) |
 | `-groups`                        | (all)    | Comma-separated `x-operation-group` filter                                  |
 | `-min-version`                   | `epoch`  | Minimum OpenSearch version (default operator: `>=`)                         |
 | `-max-version`                   | `latest` | Maximum OpenSearch version (default operator: `<=`)                         |
@@ -111,7 +111,7 @@ go run . api \
   -spec ../../opensearch-openapi.yaml \
   -out ../../opensearchapi \
   -pkg opensearchapi \
-  -plugins-out ../../opensearchapi/plugins
+  -plugins-out ../../plugins
 ```
 
 Generate a single operation:

cmd/osgen/api_cmd.go

@@ -36,7 +36,7 @@ func runAPI() error {
 	specPath := fs.String("spec", "", "path to OpenAPI spec YAML (single combined file)")
 	groups := fs.String("groups", "", "comma-separated x-operation-group names (empty = all)")
 	outDir := fs.String("out", "", "output directory for core API files (opensearchapi/)")
-	pluginsDir := fs.String("plugins-out", "", "output directory for plugin files (opensearchapi/plugins/)")
+	pluginsDir := fs.String("plugins-out", "", "output directory for plugin files (plugins/)")
 	pkg := fs.String("pkg", opensearchAPIPkgName, "Go package name for core API output")
 	minVer := fs.String("min-version", versionEpoch, "minimum OpenSearch version (default operator: >=)")
 	maxVer := fs.String("max-version", versionLatest, "maximum OpenSearch version (default operator: <=)")
@@ -54,7 +54,7 @@ func runAPI() error {
 	}
 
 	if *specPath == "" || *outDir == "" {
-		return fmt.Errorf("usage: osgen api -spec <openapi-spec.yaml> -out <dir/> [-pkg <name>] -plugins-out <opensearchapi/plugins/>")
+		return fmt.Errorf("usage: osgen api -spec <openapi-spec.yaml> -out <dir/> [-pkg <name>] -plugins-out <plugins/>")
 	}
 
 	var filter map[string]bool

cmd/osgen/emit/build.go

@@ -1350,11 +1350,12 @@ func routeOp(group, outDir, pluginsDir string) (string, string) {
 
 func importPathForGroup(group, corePkg, modulePath string) string {
 	prefix := groupPrefixIR(group)
-	core := coreImportPath(corePkg, modulePath)
 	if coreGroupPrefixes[prefix] {
-		return core
+		return coreImportPath(corePkg, modulePath)
 	}
-	return core + "/plugins/" + prefix
+	// Plugin packages are siblings of the core package at the module root,
+	// not nested under it.
+	return modulePath + "/" + ir.DefaultPluginsSubpath + "/" + prefix
 }
 
 // coreImportPath returns the full import path for the core API package.

cmd/osgen/ir/defaults.go

@@ -23,6 +23,11 @@ const (
 	// DefaultCoreImportPath is the full Go import path for the core API package.
 	DefaultCoreImportPath = ModulePath + "/" + DefaultCoreSubpath
 
+	// DefaultPluginsSubpath is the relative path (within the module) where the
+	// generated plugin packages live. Plugins are siblings of the core package
+	// at the module root, not nested under it.
+	DefaultPluginsSubpath = "plugins"
+
 	// DefaultPluginsImportBase is the import-path prefix for plugin packages.
-	DefaultPluginsImportBase = DefaultCoreImportPath + "/plugins"
+	DefaultPluginsImportBase = ModulePath + "/" + DefaultPluginsSubpath
 )

cmd/osgen/naming_test.go

@@ -58,7 +58,7 @@ func TestTitleSegment(t *testing.T) {
 
 // TestPathBuilderName verifies the mapping from x-operation-group to path
 // builder struct name. These struct names appear in internal/path/builders_gen.go
-// and are referenced by consumer files in opensearchapi/ and opensearchapi/plugins/ via their
+// and are referenced by consumer files in opensearchapi/ and plugins/ via their
 // GetRequest() methods. The naming must stay deterministic across regeneration.
 func TestPathBuilderName(t *testing.T) {
 	t.Parallel()
@@ -198,19 +198,19 @@ func TestOperationFilename(t *testing.T) {
 		{name: "core leaf", group: "search", want: "opensearchapi/search_gen.go"},
 		{name: "core dotted", group: "indices.create", want: "opensearchapi/indices-create_gen.go"},
 		{name: "_core stripped", group: "_core.search", want: "opensearchapi/search_gen.go"},
-		{name: "plugin leaf", group: "knn.stats", want: "opensearchapi/plugins/knn/stats_gen.go"},
-		{name: "plugin underscore", group: "ism.add_policy", want: "opensearchapi/plugins/ism/add_policy_gen.go"},
+		{name: "plugin leaf", group: "knn.stats", want: "plugins/knn/stats_gen.go"},
+		{name: "plugin underscore", group: "ism.add_policy", want: "plugins/ism/add_policy_gen.go"},
 		{
 			name:  "plugin multi word",
 			group: "security.reload_http_certificates",
-			want:  "opensearchapi/plugins/security/reload_http_certificates_gen.go",
+			want:  "plugins/security/reload_http_certificates_gen.go",
 		},
 	}
 
 	for _, tt := range tests {
 		t.Run(tt.name, func(t *testing.T) {
 			t.Parallel()
-			_, dir := routeOperation(tt.group, ir.DefaultCoreSubpath, ir.DefaultCoreSubpath+"/plugins")
+			_, dir := routeOperation(tt.group, ir.DefaultCoreSubpath, ir.DefaultPluginsSubpath)
 			got := dir + "/" + operationFilename(tt.group) + genFileSuffix
 			require.Equal(t, tt.want, got)
 		})