Merge branch 'main' into fixing-index-create-partially

Author: pquentin

.github/validate-pr/index.js

@@ -86,6 +86,9 @@ async function run() {
 
   cd(tsValidationPath)
 
+  // Collect all APIs to validate
+  const apisToValidate = new Set()
+
   for (const file of specFiles) {
     if (file.startsWith('specification/_types')) continue
     if (file.startsWith('specification/_spec_utils')) continue
@@ -102,32 +105,35 @@ async function run() {
         .filter(endpoint => endpoint.name.split('.').filter(s => !privateNames.includes(s))[0] === getApi(file).split('.')[0])
         .map(endpoint => endpoint.name)
       for (const api of apis) {
-        const report = await getReport({
-          api,
-          'generate-report': false,
-          request: true,
-          response: true,
-          ci: false,
-          verbose: false
-        })
-        const [namespace, _method] = api.split('.')
-        // Asked to validate a specific API, so we only store that one
-        reports.set(api, report.get(namespace)[0])
+        apisToValidate.add(api)
       }
     } else {
       const api = getApi(file)
-      const report = await getReport({
-        api,
-        'generate-report': false,
-        request: true,
-        response: true,
-        ci: false,
-        verbose: false
-      })
-
-      const [namespace, _method] = api.split('.')
-      // Asked to validate a specific API, so we only store that one
-      reports.set(api, report.get(namespace)[0])
+      apisToValidate.add(api)
+    }
+  }
+
+  // Call getReport once with all APIs
+  if (apisToValidate.size > 0) {
+    const allApis = Array.from(apisToValidate).join(',')
+    const report = await getReport({
+      api: allApis,
+      'generate-report': false,
+      request: true,
+      response: true,
+      ci: false,
+      verbose: false
+    })
+
+    // Extract individual API reports from the combined result
+    for (const api of apisToValidate) {
+      const namespace = getNamespace(api)
+      if (report.has(namespace)) {
+        const namespaceReport = report.get(namespace).find(r => r.api === getName(api))
+        if (namespaceReport) {
+          reports.set(api, namespaceReport)
+        }
+      }
     }
   }
 
@@ -165,7 +171,6 @@ function getApi (file) {
   return file.split('/').slice(1, 3).filter(s => !privateNames.includes(s)).filter(Boolean).join('.')
 }
 
-
 function findBaselineReport(apiName, baselineValidation) {
   const [namespace, method] = apiName.split('.')
 

README.md

@@ -234,6 +234,9 @@ make validate api=xpack.info type=request branch=main
 
 # this will validate the xpack.info request and response types against the 8.15 branch
 make validate api=xpack.info branch=8.15
+
+# this will validate the xpack.info and search request and response types against the 8.15 branch
+make validate api=xpack.info,search branch=8.15
 ```
 
 The last command above will install all the dependencies and run, download

compiler/run-validations.js

@@ -78,8 +78,11 @@ async function run () {
     process.exit(1)
   }
 
-  if (!apis.includes(options.api)) {
-    spinner.fail(`The api '${options.api}' does not exists, did you mean '${closest(options.api, apis)}'?`)
+  const apiList = options.api.split(',').map(api => api.trim())
+  const invalidApis = apiList.filter(api => !apis.includes(api))
+  if (invalidApis.length > 0) {
+    const suggestions = invalidApis.map(api => `'${api}' (did you mean '${closest(api, apis)}'?)`).join(', ')
+    spinner.fail(`The following APIs do not exist: ${suggestions}`)
     process.exit(1)
   }
   // if the empty string it's because the make target wasn't configured with a type argument

docs/add-new-api.md

@@ -3,11 +3,11 @@
 It might happen that a new API in Elasticsearch is not yet defined
 in this repository, or we do have an endpoint definition in [`/specification/_json_spec`](../specification/_json_spec)
 but we don't have a type definition for it.
-In this document you will see how to add a new endpopint and how to add a new endpoint definition.
+In this document you will see how to add a new endpoint and how to add a new endpoint definition.
 
 ## How to add a new endpoint
 
-Add a new endpoint is straightforward, you only need to copy-paste the json rest-api-spec defintion
+Add a new endpoint is straightforward, you only need to copy-paste the json rest-api-spec definition
 from the Elasticsearch repository inside [`/specification/_json_spec`](../specification/_json_spec)
 and you are good to go.
 
@@ -17,10 +17,10 @@ or [here](https://github.com/elastic/elasticsearch/tree/7.x/x-pack/plugin/src/te
 ## How to add the definition of an endpoint
 
 Once you have added a new endpoint definition, the next step is to add its type definition.
-First of all, you should find the most approariate place inside [`/specification`](../specification)
+First of all, you should find the most appropriate place inside [`/specification`](../specification)
 where to put the new definition. The content of [`/specification`](../specification)
-tryied to mimic the Elasticsearch online documentation, so you can use it as inspiration.
-For example, the index document defintion can be found in [`/specification/_global/index`](../specification/_global/index).
+tried to mimic the Elasticsearch online documentation, so you can use it as inspiration.
+For example, the index document definition can be found in [`/specification/_global/index`](../specification/_global/index).
 
 Once you have found the best place for the new definition, you should create a new file for it.
 The filename should be the same of the type definition you are writing, for example:
@@ -40,16 +40,16 @@ you can define it in the same file where it's used, unless is a commonly used ty
 
 ### Add the endpoint request definition
 
-Request definitions are slighly different from other definitions.
+Request definitions are slightly different from other definitions.
 It is required that the request definition is named `Request`.
-A request definition is an interface and should contains three top level keys:
+A request definition is an interface and should contain these top level keys:
 
 - `urls`: the URL paths templates and allowed HTTP methods
 - `path_parts`: the path parameters (eg: `indices`, `id`...)
 - `query_parameters`: the query parameters (eg: `timeout`, `pipeline`...)
 - `body`: the body parameters (eg: `query` or user defined entities)
 
-Furthermore, every request definition **must** contain three JS Doc tags:
+Furthermore, every request definition **must** contain these JS Doc tags:
 
 - `@rest_spec_name`: the API name (eg: `search`, `indices.create`...).
 - `@availability` Which flavor of Elasticsearch is this API available for? (eg `stack` or `serverless`)
@@ -130,7 +130,7 @@ class Response {
 ```
 
 As you can see, for responses there are no custom top level keys, as the
-response definition represents the body of a succesful response.
+response definition represents the body of a successful response.
 
 #### Generics
 
@@ -172,7 +172,7 @@ class Response {
 Add an `examples` folder and `request` and `xxx_response` subfolders (where `xxx` is the relevant response code). The file names within these folders should be unique (for example,`DownsampleRequestExample1.yaml` not `RequestExample1.yaml`).
 
 These examples are for use in the API documentation and must adhere to the [OpenAPI 3.0 Example object specification](https://spec.openapis.org/oas/v3.0.3#example-object). They must have a `value` field that contains the request or response body.
-If there are multiple examples for the endpoint, they must each have a brief `summary` field, which is used as the label for the example. You can also optionaly provide an explanation in a `description` field.
+If there are multiple examples for the endpoint, they must each have a brief `summary` field, which is used as the label for the example. You can also optionally provide an explanation in a `description` field.
 In order to generate curl and console examples automatically, the request examples must also contain a `method_request`.
 
 For example:
@@ -197,5 +197,5 @@ value: |-
 ```
 
 NOTE: A good example covers a very common use case or demonstrates a more complex but critical use case.
-It involves realistic data sets ( rather than generic "hello world" values).
+It involves realistic data sets (rather than generic "hello world" values).
 If it requires detailed setup or explanations, however, it is more appropriate for coverage in longer-form narrative documentation.

docs/modeling-guide.md

@@ -148,7 +148,7 @@ property: UserDefinedValue
 
 ### Numbers
 
-The numeric type in TypeScript is `number`, but given that this specification targets mutliple languages,
+The numeric type in TypeScript is `number`, but given that this specification targets multiple languages,
 it offers a bunch of aliases that represent the type that should be used if the language supports it:
 
 ```ts
@@ -504,7 +504,7 @@ Code generators should track the `es_quirk` they implement and fail if a new unh
 
 ### Additional information
 
-If needed, you can specify additional information on each type with the approariate JSDoc tag.
+If needed, you can specify additional information on each type with the appropriate JSDoc tag.
 Following you can find a list of the supported tags:
 
 #### `@availability`

docs/specification-structure.md

@@ -30,6 +30,7 @@ end with `Request` or `Response`.
 ### Request and Response definitions
 
 Request and Response definitions should be placed by strictly following
+the rest-api-spec structure.
 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).

docs/validation-example.md

@@ -16,7 +16,7 @@ The example assumes that you have already performed the necessary steps to run a
 if not, take a look at the [README](../README.md).
 
 ```sh
-make validate api=index type=request branch=main
+make validate api=index branch=main
 ```
 
 You will see an output like the following:
@@ -82,7 +82,7 @@ open it with your favourite editor and perform the fix
 Finally run the validation again:
 
 ```sh
-make validate api=index type=request branch=main
+make validate api=index branch=main
 ```
 
 If there are no more errors, open a pull request with the fix.