Add ESLint rule to restrict @codegen_exclude usage to Request.ts files

Author: Anaethelion

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',

validator/README.md

@@ -19,6 +19,7 @@ It is configured [in the specification directory](../specification/eslint.config
 | `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`.                                                                  |
+| `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: {
@@ -42,6 +43,7 @@ export default {
     'prefer-tagged-variants': preferTaggedVariants,
     'no-duplicate-type-names': noDuplicateTypeNames,
     'no-all-string-literal-unions': noAllStringLiteralUnions,
-    'jsdoc-endpoint-check': jsdocEndpointCheck
+    '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

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

@@ -0,0 +1,85 @@
+/*
+ * 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 { RuleTester } from '@typescript-eslint/rule-tester'
+import rule from '../rules/codegen-exclude-on-request-only.js'
+
+const ruleTester = new RuleTester({
+  languageOptions: {
+    parserOptions: {
+      projectService: {
+        allowDefaultProject: ['*.ts*'],
+        defaultProject: 'tsconfig.json'
+      },
+      tsconfigRootDir: new URL('../../specification/', import.meta.url).pathname
+    }
+  }
+})
+
+ruleTester.run('codegen-exclude-on-request-only', rule, {
+  valid: [
+    {
+      name: 'namespaced Request file with @codegen_exclude',
+      filename: new URL('../../specification/ilm/put_lifecycle/PutLifecycleRequest.ts', import.meta.url).pathname,
+      code: `
+        /**
+         * Some endpoint
+         * @rest_spec_name ilm.put_lifecycle
+         * @codegen_exclude
+         */
+        export interface Request {}
+      `
+    },
+    {
+      name: 'request without tag in any file',
+      filename: new URL('../../specification/ilm/put_lifecycle/PutLifecycleRequest.ts', import.meta.url).pathname,
+      code: `
+        export interface Request {}
+      `
+    }
+  ],
+  invalid: [
+    {
+      name: 'non-namespaced file under specification with @codegen_exclude',
+      filename: new URL('../../specification/SomeFile.ts', import.meta.url).pathname,
+      code: `
+        /**
+         * @codegen_exclude
+         */
+        export interface Something {}
+      `,
+      errors: [
+        { messageId: 'invalidUsage' }
+      ]
+    },
+    {
+      name: 'namespaced Response file with @codegen_exclude',
+      filename: new URL('../../specification/ilm/put_lifecycle/PutLifecycleResponse.ts', import.meta.url).pathname,
+      code: `
+        /**
+         * @codegen_exclude
+         */
+        export interface Response {}
+      `,
+      errors: [
+        { messageId: 'invalidUsage' }
+      ]
+    }
+  ]
+})