Backport 5800 to 9.1

compiler/src/model/metamodel.ts

@@ -469,6 +469,8 @@ export class Endpoint {
     index?: string[]
     cluster?: string[]
   }
+
+  codegenExclude?: boolean
 }
 
 export class UrlTemplate {

compiler/src/model/utils.ts

@@ -634,7 +634,7 @@ export function hoistRequestAnnotations (
   request: model.Request, jsDocs: JSDoc[], mappings: Record<string, model.Endpoint>, response: model.TypeName | null
 ): void {
   const knownRequestAnnotations = [
-    'rest_spec_name', 'behavior', 'class_serializer', 'index_privileges', 'cluster_privileges', 'doc_id', 'availability', 'doc_tag', 'ext_doc_id'
+    'rest_spec_name', 'behavior', 'class_serializer', 'index_privileges', 'cluster_privileges', 'doc_id', 'availability', 'doc_tag', 'ext_doc_id', 'codegen_exclude'
   ]
   // in most of the cases the jsDocs comes in a single block,
   // but it can happen that the user defines multiple single line jsDoc.
@@ -720,6 +720,9 @@ export function hoistRequestAnnotations (
     } else if (tag === 'doc_tag') {
       assert(jsDocs, value.trim() !== '', `Request ${request.name.name}'s @doc_tag cannot be empty`)
       endpoint.docTag = value.trim()
+    } else if (tag === 'codegen_exclude') {
+      // Mark this endpoint to be excluded from client code generation
+      endpoint.codegenExclude = true
     } else {
       assert(jsDocs, false, `Unhandled tag: '${tag}' with value: '${value}' on request ${request.name.name}`)
     }

specification/_internal/delete_desired_balance/InternalDeleteDesiredBalanceRequest.ts

@@ -25,6 +25,7 @@ import { Duration } from '@_types/Time'
  *
  * @rest_spec_name _internal.delete_desired_balance
  * @availability stack stability=experimental visibility=private
+ * @codegen_exclude
  */
 export interface Request extends RequestBase {
   urls: [

specification/_internal/delete_desired_nodes/InternalDeleteDesiredNodesRequest.ts

@@ -25,6 +25,7 @@ import { Duration } from '@_types/Time'
  *
  * @rest_spec_name _internal.delete_desired_nodes
  * @availability stack stability=experimental visibility=private
+ * @codegen_exclude
  */
 export interface Request extends RequestBase {
   urls: [

specification/_internal/get_desired_balance/InternalGetDesiredBalanceRequest.ts

@@ -25,6 +25,7 @@ import { Duration } from '@_types/Time'
  *
  * @rest_spec_name _internal.get_desired_balance
  * @availability stack stability=experimental visibility=private
+ * @codegen_exclude
  */
 export interface Request extends RequestBase {
   urls: [

specification/_internal/get_desired_nodes/InternalGetDesiredNodesRequest.ts

@@ -25,6 +25,7 @@ import { Duration } from '@_types/Time'
  *
  * @rest_spec_name _internal.get_desired_nodes
  * @availability stack stability=experimental visibility=private
+ * @codegen_exclude
  */
 export interface Request extends RequestBase {
   urls: [

specification/_internal/prevalidate_node_removal/InternalPrevalidateNodeRemovalRequest.ts

@@ -25,6 +25,7 @@ import { Duration } from '@_types/Time'
  *
  * @rest_spec_name _internal.prevalidate_node_removal
  * @availability stack stability=experimental visibility=private
+ * @codegen_exclude
  */
 export interface Request extends RequestBase {
   urls: [

specification/_internal/update_desired_nodes/InternalUpdateDesiredNodesRequest.ts

@@ -27,6 +27,7 @@ import { UserDefinedValue } from '@spec_utils/UserDefinedValue'
  *
  * @rest_spec_name _internal.update_desired_nodes
  * @availability stack stability=experimental visibility=private
+ * @codegen_exclude
  */
 export interface Request extends RequestBase {
   urls: [

specification/eslint.config.js

@@ -38,6 +38,7 @@ export default defineConfig([
       'es-spec-validator/no-native-types': 'error',
       'es-spec-validator/invalid-node-types': 'error',
       'es-spec-validator/no-generic-number': 'error',
+      'es-spec-validator/codegen-exclude-on-request-only': 'error',
       'es-spec-validator/request-must-have-urls': 'error',
       'es-spec-validator/no-variants-on-responses': 'error',
       'es-spec-validator/no-inline-unions': 'error',
@@ -144,6 +145,7 @@ export default defineConfig([
             'behavior_meta',
             'class_serializer',
             'cluster_privileges',
+            'codegen_exclude',
             'codegen_name',
             'codegen_names',
             'doc_id',

typescript-generator/src/metamodel.ts

@@ -469,6 +469,8 @@ export class Endpoint {
     index?: string[]
     cluster?: string[]
   }
+
+  codegenExclude?: boolean
 }
 
 export class UrlTemplate {

validator/README.md

@@ -5,20 +5,21 @@ It is configured [in the specification directory](../specification/eslint.config
 
 ## Rules
 
-| Name                                  | Description                                                                                                                                                                                |
-|---------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| `single-key-dictionary-key-is-string` | `SingleKeyDictionary` keys must be strings.                                                                                                                                                |
-| `dictionary-key-is-string`            | `Dictionary` keys must be strings.                                                                                                                                                         |
-| `no-native-types`                     | TypeScript native utility types (`Record`, `Partial`, etc.) and collection types (`Map`, `Set`, etc.) are not allowed. Use spec-defined aliases like `Dictionary` instead.                 |
-| `invalid-node-types`                  | The spec uses a subset of TypeScript, so some types, clauses and expressions are not allowed.                                                                                              |
-| `no-generic-number`                   | Generic `number` type is not allowed outside of `_types/Numeric.ts`. Use concrete numeric types like `integer`, `long`, `float`, `double`, etc.                                            |
-| `request-must-have-urls`              | All Request interfaces extending `RequestBase` must have a `urls` property defining their endpoint paths and HTTP methods.                                                                 |
-| `no-variants-on-responses`            | `@variants` is only supported on Interface types, not on Request or Response classes. Use value_body pattern with `@codegen_name` instead.                                                 |
-| `no-inline-unions`                    | Inline union types (e.g., `field: A \| B`) are not allowed in properties/fields. Define a named type alias instead to improve code generation for statically-typed languages.              |
-| `prefer-tagged-variants`              | Union of class types should use tagged variants (`@variants internal` or `@variants container`) instead of inline unions for better deserialization support in statically-typed languages. |
-| `no-duplicate-type-names`             | All types must be unique across class and enum definitions.                                                                                                                                |
+| Name                                  | Description                                                                                                                                                                                    |
+|---------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `single-key-dictionary-key-is-string` | `SingleKeyDictionary` keys must be strings.                                                                                                                                                    |
+| `dictionary-key-is-string`            | `Dictionary` keys must be strings.                                                                                                                                                             |
+| `no-native-types`                     | TypeScript native utility types (`Record`, `Partial`, etc.) and collection types (`Map`, `Set`, etc.) are not allowed. Use spec-defined aliases like `Dictionary` instead.                     |
+| `invalid-node-types`                  | The spec uses a subset of TypeScript, so some types, clauses and expressions are not allowed.                                                                                                  |
+| `no-generic-number`                   | Generic `number` type is not allowed outside of `_types/Numeric.ts`. Use concrete numeric types like `integer`, `long`, `float`, `double`, etc.                                                |
+| `request-must-have-urls`              | All Request interfaces extending `RequestBase` must have a `urls` property defining their endpoint paths and HTTP methods.                                                                     |
+| `no-variants-on-responses`            | `@variants` is only supported on Interface types, not on Request or Response classes. Use value_body pattern with `@codegen_name` instead. Includes additional checks on variant tag use.                             |
+| `no-inline-unions`                    | Inline union types (e.g., `field: A \| B`) are not allowed in properties/fields. Define a named type alias instead to improve code generation for statically-typed languages.                  |
+| `prefer-tagged-variants`              | Union of class types should use tagged variants (`@variants internal` or `@variants container`) instead of inline unions for better deserialization support in statically-typed languages.     |
+| `no-duplicate-type-names`             | All types must be unique across class and enum definitions.                                                                                                                                    |
+| `no-all-string-literal-unions         | Unions consisting entirely of string literals (e.g., `"green" \| "yellow" \| "red"`) are not allowed, use enums instead.                                                                       | 
 | `jsdoc-endpoint-check`                | Validates JSDoc on endpoints in the specification. Ensuring consistent formatting. Some errors can be fixed with `--fix`.                                                                  |
-| `no-all-string-literal-unions         | Unions consisting entirely of string literals (e.g., `"green" \| "yellow" \| "red"`) are not allowed, use enums instead.                                                                   |                                                                                                                         |
+| `codegen-exclude-on-request-only`     | Ensures `@codegen_exclude` is only used on request definitions located in namespaced `specification/` files (i.e. files.                         |
 
 ## Usage
 

validator/eslint-plugin-es-spec.js

@@ -28,6 +28,7 @@ import preferTaggedVariants from './rules/prefer-tagged-variants.js'
 import noDuplicateTypeNames from './rules/no-duplicate-type-names.js'
 import noAllStringLiteralUnions from './rules/no-all-string-literal-unions.js'
 import jsdocEndpointCheck from './rules/jsdoc-endpoint-check.js'
+import codegenExcludeOnRequestOnly from './rules/codegen-exclude-on-request-only.js'
 
 export default {
   rules: {
@@ -40,8 +41,9 @@ export default {
     'no-variants-on-responses': noVariantsOnResponses,
     'no-inline-unions': noInlineUnions,
     'prefer-tagged-variants': preferTaggedVariants,
-    'no-all-string-literal-unions': noAllStringLiteralUnions,
     'no-duplicate-type-names': noDuplicateTypeNames,
-    'jsdoc-endpoint-check': jsdocEndpointCheck
+    'no-all-string-literal-unions': noAllStringLiteralUnions,
+    'jsdoc-endpoint-check': jsdocEndpointCheck,
+    'codegen-exclude-on-request-only': codegenExcludeOnRequestOnly
   }
 }

validator/rules/codegen-exclude-on-request-only.js

@@ -0,0 +1,58 @@
+/*
+ * Licensed to Elasticsearch B.V. under one or more contributor
+ * license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright
+ * ownership. Elasticsearch B.V. licenses this file to you under
+ * the Apache License, Version 2.0 (the "License"); you may
+ * not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+import { ESLintUtils } from '@typescript-eslint/utils'
+
+export const codegenExcludeOnRequestOnly = ESLintUtils.RuleCreator.withoutDocs({
+  name: 'codegen-exclude-on-request-only',
+  meta: {
+    type: 'problem',
+    docs: {
+      description: 'Ensures @codegen_exclude is only used on Request.ts files in specification/',
+      recommended: 'error'
+    },
+    messages: {
+      invalidUsage: '@codegen_exclude may only appear on Request definitions in specification/* (files named *Request.ts).'
+    },
+    schema: []
+  },
+  defaultOptions: [],
+  create (context) {
+    const sourceCode = context.getSourceCode()
+
+    function findCodegenExcludeComments () {
+      return sourceCode.getAllComments().filter(c => c.type === 'Block' && c.value.startsWith('*') && /@codegen_exclude\b/.test(c.value))
+    }
+
+    return {
+      Program (node) {
+        const filename = context.getFilename()
+        const allowed = /[\\/]specification[\\/][^\\/]+[\\/].*Request\.ts$/.test(filename)
+        const offending = findCodegenExcludeComments()
+        for (const c of offending) {
+          if (!allowed) {
+            context.report({ loc: c.loc, messageId: 'invalidUsage' })
+          }
+        }
+      }
+    }
+  }
+})
+
+export default codegenExcludeOnRequestOnly