Initial prototype of an ESLint-based validator of the Elasticsearch specification (#4400)

* Initial prototype of an ESLint-based validator of the Elasticsearch specification

* Add linter to make validate target

* Stop using mjs file extension

* Add testing framework

* Typo

* Fix ESM setup in spec repo

* Formatting cleanup

* Clarifications in README about writing rules

* Add invalid-node-types rule

* Appease the linter

* Add license headers

* Appease the linter again!

* Install validator dependencies in makefile

* Ignore new ESLint-related files in validate-pr script

* Attempt to short-circuit reporting tool when it gets an invalid file

* Debugging the validate-pr script to find an issue

* Skip markdown files in validate-pr script

Author: JoshMock

.github/validate-pr/index.js

@@ -90,7 +90,12 @@ async function run() {
     if (file.startsWith('specification/_spec_utils')) continue
     if (file.startsWith('specification/_doc_ids')) continue
     if (file.startsWith('specification/_json_spec')) continue
-    if (file === 'specification/tsconfig.json') continue
+    if (file.startsWith('specification/node_modules')) continue
+    if (file.endsWith('tsconfig.json')) continue
+    if (file.endsWith('eslint.config.js')) continue
+    if (file.endsWith('package.json')) continue
+    if (file.endsWith('package-lock.json')) continue
+    if (file.endsWith('.md')) continue
     if (getApi(file).endsWith('_types')) {
       const apis = specification.endpoints
         .filter(endpoint => endpoint.name.split('.').filter(s => !privateNames.includes(s))[0] === getApi(file).split('.')[0])

Makefile

@@ -2,6 +2,7 @@ SHELL := /bin/bash
 
 validate: ## Validate a given endpoint request or response
 	@node compiler/run-validations.js --api $(api) --type $(type) --branch $(branch)
+	@npm run lint --prefix specification
 
 validate-no-cache: ## Validate a given endpoint request or response without local cache
 	@node compiler/run-validations.js --api $(api) --type $(type) --branch $(branch) --no-cache
@@ -39,6 +40,8 @@ setup:	## Install dependencies for contrib target
 	@make clean-dep
 	@npm install --prefix compiler
 	@npm install --prefix typescript-generator
+	@npm install --prefix validator
+	@npm install --prefix specification
 	@npm install @redocly/cli
 
 clean-dep:	## Clean npm dependencies

docs/specification-structure.md

@@ -1,7 +1,7 @@
 # Specification structure
 
 The [`/specification`](../specification) folders follows a set of rules to
-keep the defintion easy to access and contribute, while maintaing
+keep the definition easy to access and contribute, while maintaining
 the generated schema consistent and useful for language generators.
 
 ## Rules
@@ -14,7 +14,7 @@ root of the [`/specification`](../specification) folder as well
 as inside the namespaces when necessary.
 
 You should decide if a type should go inside the top-level `_types`
-folder or inside a namespace (eg: `indices/_types`) on a case by case basis.
+folder or inside a namespace (e.g.: `indices/_types`) on a case by case basis.
 A good rule of thumb is that if a type is widely used in the specification,
 it should go in the top level `_types`, while if it's used only within
 a namespace or a few times in other namespaces, it could go inside the
@@ -29,8 +29,8 @@ end with `Request` or `Response`.
 
 ### Request and Response definitions
 
-Request and Reponse definitions should be placed by structly following
-the rest-api-spec structure.
+Request and Response definitions should be placed by strictly following
+the `rest-api-spec` structure.
 For example, the request and response definition for `indices.put_mapping`
 should go in [`/specification/indices/put_mapping`](../specification/indices/put_mapping).
 There are no requirements on the file name, but the type should be
@@ -45,4 +45,4 @@ For example: [`/specification/_global/search`](../specification/_global/search).
 ### Specification helpers
 
 The specification has a set of custom types used to define complex structures
-or behaviors. Those types must be placed in [`/specification/_spec_utils`](../specification/_spec_utils).
+or behaviors. Those types must be placed in [`/specification/_spec_utils`](../specification/_spec_utils).

specification/eslint.config.js

@@ -0,0 +1,37 @@
+/*
+ * 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 parser from '@typescript-eslint/parser'
+import validator from 'eslint-plugin-es-spec'
+import { defineConfig } from 'eslint/config'
+
+export default defineConfig({
+  files: ['**/*.ts'],
+  languageOptions: {
+    parser,
+    parserOptions: {
+      projectService: true,
+      tsconfigRootDir: import.meta.dirname
+    }
+  },
+  plugins: { 'es-spec-validator': validator },
+  rules: {
+    'es-spec-validator/single-key-dictionary-key-is-string': 'error',
+    'es-spec-validator/invalid-node-types': 'warn'
+  }
+})