Merge remote-tracking branch 'origin/main' into kderusso/move-query-rules-namespace

Author: pquentin

.github/labeler.yml

@@ -1,12 +1,15 @@
 documentation:
-  - '*.md'
+- changed-files:
+  - any-glob-to-any-file: '*.md'
 
 specification:
-  - 'specification/**/*'
+- changed-files:
+  - any-glob-to-any-file: 'specification/**/*'
 
 generator:typescript:
-  - 'typescript-generator/**/*'
+- changed-files:
+  - any-glob-to-any-file: 'typescript-generator/**/*'
 
 compiler:
-  - 'compiler/**/*'
-  - 'compiler-rs/**/*'
+- changed-files:
+  - any-glob-to-any-file: ['compiler/**/*', 'compiler-rs/**/*']

.github/workflows/code-format.yml

@@ -10,10 +10,10 @@ jobs:
     steps:
     - uses: actions/checkout@v4
 
-    - name: Use Node.js 20.x
-      uses: actions/setup-node@v1
+    - name: Use Node.js 20
+      uses: actions/setup-node@v4
       with:
-        node-version: 20.x
+        node-version: 20
 
     - name: Install
       run: |

.github/workflows/compiler.test.yml

@@ -13,10 +13,10 @@ jobs:
     steps:
       - uses: actions/checkout@v4
 
-      - name: Use Node.js 20.x
-        uses: actions/setup-node@v1
+      - name: Use Node.js 20
+        uses: actions/setup-node@v4
         with:
-          node-version: 20.x
+          node-version: 20
 
       - name: Install deps
         run: |

.github/workflows/generate.yml

@@ -34,10 +34,10 @@ jobs:
         token: ${{ secrets.PAT }}
         persist-credentials: true
 
-    - name: Setup Node 20.x
-      uses: actions/setup-node@v3
+    - name: Setup Node 20
+      uses: actions/setup-node@v4
       with:
-        node-version: 20.x
+        node-version: 20
         cache: npm
         cache-dependency-path: '**/package-lock.json'
 

.github/workflows/gh-pages-report.yml

@@ -16,10 +16,10 @@ jobs:
     steps:
     - uses: actions/checkout@v4
 
-    - name: Use Node.js 20.x
-      uses: actions/setup-node@v1
+    - name: Use Node.js 20
+      uses: actions/setup-node@v4
       with:
-        node-version: 20.x
+        node-version: 20
 
     - name: Install
       run: |

.github/workflows/labeler.yml

@@ -6,7 +6,7 @@ jobs:
   triage:
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/labeler@v3
+    - uses: actions/labeler@v5
       with:
         repo-token: "${{ secrets.GITHUB_TOKEN }}"
 

.github/workflows/linter.yml

@@ -10,10 +10,10 @@ jobs:
     steps:
     - uses: actions/checkout@v4
 
-    - name: Use Node.js 20.x
-      uses: actions/setup-node@v1
+    - name: Use Node.js 20
+      uses: actions/setup-node@v4
       with:
-        node-version: 20.x
+        node-version: 20
 
     - name: Install
       run: |

.github/workflows/update-rest-api-json.yml

@@ -12,17 +12,17 @@ jobs:
 
     strategy:
       matrix:
-        branch: ['main', '8.8', '8.7', '7.17']
+        branch: ['main', '8.13', '8.14', '7.17']
 
     steps:
       - uses: actions/checkout@v4
         with:
           ref: ${{ matrix.branch }}
 
-      - name: Use Node.js 20.x
-        uses: actions/setup-node@v1
+      - name: Use Node.js 20
+        uses: actions/setup-node@v4
         with:
-          node-version: 20.x
+          node-version: 20
 
       - name: Install deps
         run: |
@@ -43,19 +43,19 @@ jobs:
           git status --porcelain
 
       - name: Create Pull Request
-        uses: peter-evans/create-pull-request@v3
+        uses: peter-evans/create-pull-request@v6
         with:
           title: Update rest-api-spec ${{ matrix.branch }}
           body: 'As titled.'
           commit-message: 'Update rest-api-spec'
           labels: specification
           delete-branch: true
-          team-reviewers: elastic/clients-team
+          team-reviewers: elastic/devtools-team
           branch: automated/rest-api-spec-update-${{ matrix.branch }}
 
       - name: Open an issue if the action fails
         if: ${{ failure() }}
-        uses: nashmaniac/create-issue-action@v1.1
+        uses: nashmaniac/create-issue-action@v1.2
         with:
           title: rest-api-spec update failed
           token: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/validate-pr.yml

@@ -26,10 +26,10 @@ jobs:
           token: ${{ secrets.PAT }}
           ref: main
 
-      - name: Use Node.js 20.x
-        uses: actions/setup-node@v1
+      - name: Use Node.js 20
+        uses: actions/setup-node@v4
         with:
-          node-version: 20.x
+          node-version: 20
 
       - name: Install deps 1/2
         working-directory: ./clients-flight-recorder

Makefile

@@ -60,7 +60,10 @@ dump-routes: ## Create a new schema with all generics expanded
 contrib: | generate license-check spec-format-fix transform-to-openapi ## Pre contribution target
 
 lint-docs: ## Lint the OpenAPI documents
-	@npx @stoplight/spectral-cli lint output/openapi/elasticsearch-serverless-openapi.json
+	@npx @stoplight/spectral-cli lint output/openapi/*.json --ruleset .spectral.yaml
+
+lint-docs-serverless: ## Lint only the serverless OpenAPI document
+	@npx @stoplight/spectral-cli lint output/openapi/elasticsearch-serverless-openapi.json --ruleset .spectral.yaml
 
 help:  ## Display help
 	@awk 'BEGIN {FS = ":.*##"; printf "Usage:\n  make \033[36m<target>\033[0m\n"} /^[a-zA-Z_-]+:.*?##/ { printf "  \033[36m%-15s\033[0m %s\n", $$1, $$2 } /^##@/ { printf "\n\033[1m%s\033[0m\n", substr($$0, 5) } ' $(MAKEFILE_LIST)

README.md

@@ -69,7 +69,13 @@ Usage:
   spec-dangling-types  Generate the dangling types rreport
   setup            Install dependencies for contrib target
   clean-dep        Clean npm dependencies
+  transform-expand-generics  Create a new schema with all generics expanded
+  transform-to-openapi  Generate the OpenAPI definition from the compiled schema
+  filter-for-serverless  Generate the serverless version from the compiled schema
+  dump-routes      Create a new schema with all generics expanded
   contrib          Pre contribution target
+  lint-docs        Lint the OpenAPI documents
+  lint-docs-serverless  Lint only the serverless OpenAPI document
   help             Display help
 ```
 

docs/doc-comments-guide.md

@@ -4,12 +4,19 @@ A specification is not only about formalizing data structures, it's also about e
 
 Documentation of the TypeScript specification is made using [JSDoc](https://jsdoc.app/) comments, i.e. multiline comments starting with `/**` above a type or field declaration.
 
+The first phrase is used as the mandatory operation summary in the OpenAPI document.
+Refer to [API documentation guidelines](https://docs.elastic.dev/content-architecture/oas#summaries).
+
+NOTE: You must add a period or `\n` at the end of the phrase for it to parse correctly.
+The period will be properly omitted from the output OpenAPI document.
+
 Additional lines start with a `*` followed by a space. Long lines are allowed but it's better if text is formatted to a maximum of 120 characters per line.
 
 ## Example
 
 ```ts
 /**
+ * Get ranking evaluation.
  * Enables you to evaluate the quality of ranked search results over a set of typical search queries.
  * @rest_spec_name rank_eval
  * @availability stack since=6.2.0 stability=stable

output/openapi/elasticsearch-openapi.json

@@ -11783,7 +11783,8 @@
         "tags": [
           "indices.get_index_template"
         ],
-        "summary": "Returns information about one or more index templates",
+        "summary": "Get index templates",
+        "description": "Returns information about one or more index templates.",
         "externalDocs": {
           "url": "https://www.elastic.co/guide/en/elasticsearch/reference/master/indices-get-template.html"
         },
@@ -11815,7 +11816,7 @@
         "tags": [
           "indices.put_index_template"
         ],
-        "summary": "Creates or updates an index template",
+        "summary": "Create or update an index template",
         "description": "Index templates define settings, mappings, and aliases that can be applied automatically to new indices.",
         "externalDocs": {
           "url": "https://www.elastic.co/guide/en/elasticsearch/reference/master/indices-put-template.html"
@@ -11848,7 +11849,7 @@
         "tags": [
           "indices.put_index_template"
         ],
-        "summary": "Creates or updates an index template",
+        "summary": "Create or update an index template",
         "description": "Index templates define settings, mappings, and aliases that can be applied automatically to new indices.",
         "externalDocs": {
           "url": "https://www.elastic.co/guide/en/elasticsearch/reference/master/indices-put-template.html"
@@ -11881,8 +11882,8 @@
         "tags": [
           "indices.delete_index_template"
         ],
-        "summary": "The provided <index-template> may contain multiple template names separated by a comma",
-        "description": "If multiple template names are specified then there is no wildcard support and the provided names should match completely with existing templates.",
+        "summary": "Delete an index template",
+        "description": "The provided <index-template> may contain multiple template names separated by a comma. If multiple template names are specified then there is no wildcard support and the provided names should match completely with existing templates.",
         "externalDocs": {
           "url": "https://www.elastic.co/guide/en/elasticsearch/reference/master/indices-delete-template.html"
         },
@@ -11980,7 +11981,8 @@
         "tags": [
           "indices.get_template"
         ],
-        "summary": "Retrieves information about one or more index templates",
+        "summary": "Get index templates",
+        "description": "Retrieves information about one or more index templates.",
         "externalDocs": {
           "url": "https://www.elastic.co/guide/en/elasticsearch/reference/master/indices-get-template-v1.html"
         },
@@ -12009,7 +12011,7 @@
         "tags": [
           "indices.put_template"
         ],
-        "summary": "Creates or updates an index template",
+        "summary": "Create or update an index template",
         "description": "Index templates define settings, mappings, and aliases that can be applied automatically to new indices.",
         "externalDocs": {
           "url": "https://www.elastic.co/guide/en/elasticsearch/reference/master/indices-templates-v1.html"
@@ -12045,7 +12047,7 @@
         "tags": [
           "indices.put_template"
         ],
-        "summary": "Creates or updates an index template",
+        "summary": "Create or update an index template",
         "description": "Index templates define settings, mappings, and aliases that can be applied automatically to new indices.",
         "externalDocs": {
           "url": "https://www.elastic.co/guide/en/elasticsearch/reference/master/indices-templates-v1.html"
@@ -12136,7 +12138,8 @@
         "tags": [
           "indices.exists_template"
         ],
-        "summary": "Returns information about whether a particular index template exists",
+        "summary": "Check existence of index templates",
+        "description": "Returns information about whether a particular index template exists.",
         "externalDocs": {
           "url": "https://www.elastic.co/guide/en/elasticsearch/reference/master/indices-template-exists-v1.html"
         },
@@ -12975,7 +12978,8 @@
         "tags": [
           "indices.get_index_template"
         ],
-        "summary": "Returns information about one or more index templates",
+        "summary": "Get index templates",
+        "description": "Returns information about one or more index templates.",
         "externalDocs": {
           "url": "https://www.elastic.co/guide/en/elasticsearch/reference/master/indices-get-template.html"
         },
@@ -13426,7 +13430,8 @@
         "tags": [
           "indices.get_template"
         ],
-        "summary": "Retrieves information about one or more index templates",
+        "summary": "Get index templates",
+        "description": "Retrieves information about one or more index templates.",
         "externalDocs": {
           "url": "https://www.elastic.co/guide/en/elasticsearch/reference/master/indices-get-template-v1.html"
         },
@@ -14355,6 +14360,8 @@
         "tags": [
           "indices.simulate_index_template"
         ],
+        "summary": "Simulate an index",
+        "description": "Returns the index configuration that would be applied to the specified index from an existing index template.",
         "externalDocs": {
           "url": "https://www.elastic.co/guide/en/elasticsearch/reference/master/indices-simulate-index.html"
         },
@@ -14425,7 +14432,8 @@
         "tags": [
           "indices.simulate_template"
         ],
-        "summary": "Returns the index configuration that would be applied by a particular index template",
+        "summary": "Simulate an index template",
+        "description": "Returns the index configuration that would be applied by a particular index template.",
         "externalDocs": {
           "url": "https://www.elastic.co/guide/en/elasticsearch/reference/master/indices-simulate-template.html"
         },
@@ -14456,7 +14464,8 @@
         "tags": [
           "indices.simulate_template"
         ],
-        "summary": "Returns the index configuration that would be applied by a particular index template",
+        "summary": "Simulate an index template",
+        "description": "Returns the index configuration that would be applied by a particular index template.",
         "externalDocs": {
           "url": "https://www.elastic.co/guide/en/elasticsearch/reference/master/indices-simulate-template.html"
         },