Merge branch 'main' into no-native-structures-validation

Author: l-trotta

.backportrc.json

@@ -1,6 +1,6 @@
 {
   "repoOwner": "elastic",
   "repoName": "elasticsearch-specification",
-  "targetBranchChoices": ["9.0", "8.19", "8.18", "8.17"],
+  "targetBranchChoices": ["9.1", "9.0", "8.19", "8.18"],
   "fork": false
 }

.github/validate-pr/index.js

@@ -27,6 +27,7 @@ import * as core from '@actions/core'
 import { copyFile } from 'fs/promises'
 import * as github from '@actions/github'
 import specification from '../../output/schema/schema.json' with { type: 'json' }
+import baselineValidation from '../../../clients-flight-recorder/recordings/types-validation/types-validation.json' with { type: 'json' }
 import { run as getReport } from '../../../clients-flight-recorder/scripts/types-validator/index.js'
 import {
   getNamespace,
@@ -81,10 +82,13 @@ async function run() {
   const specFiles = files.filter(
     (file) => file.includes('specification') && !file.includes('compiler/test')
   )
-  const table = []
+  const reports = new Map()
 
   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
@@ -101,53 +105,62 @@ 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
-        })
-        table.push(buildTableLine(api, report))
+        apisToValidate.add(api)
       }
     } else {
-      const report = await getReport({
-        api: getApi(file),
-        'generate-report': false,
-        request: true,
-        response: true,
-        ci: false,
-        verbose: false
-      })
-      table.push(buildTableLine(getApi(file), report))
+      const api = getApi(file)
+      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)
+        }
+      }
     }
   }
 
   cd(path.join(__dirname, '..', '..'))
 
-  table.sort((a, b) => {
-    if (a < b) return -1
-    if (a > b) return 1
-    return 0
-  })
+  // Compare current reports with baseline and find changes
+  const changedApis = []
+  for (const [apiName, report] of reports) {
+    const baselineReport = findBaselineReport(apiName, baselineValidation)
+    if (baselineReport && hasChanges(baselineReport, report, apiName)) {
+      changedApis.push({ api: apiName, baseline: baselineReport, current: report })
+    }
+  }
+  changedApis.sort((a, b) => a.api.localeCompare(b.api))
 
-  if (table.length > 0) {
-    let comment = `Following you can find the validation results for the API${table.length === 1 ? '' : 's'} you have changed.\n\n`
+  let comment = `Following you can find the validation changes against the target branch for the API${changedApis.length === 1 ? '' : 's'}.\n\n`
+  if (changedApis.length > 0) {
     comment += '| API | Status | Request | Response |\n'
     comment += '| --- | --- | --- | --- |\n'
-    for (const line of [...new Set(table)]) {
-      comment += line
+    for (const change of changedApis) {
+      comment += buildDiffTableLine(change)
     }
-    comment += `\nYou can validate ${table.length === 1 ? 'this' : 'these'} API${table.length === 1 ? '' : 's'} yourself by using the ${tick}make validate${tick} target.\n`
-
-    await octokit.rest.issues.createComment({
-      owner: 'elastic',
-      repo: 'elasticsearch-specification',
-      issue_number: context.payload.pull_request.number,
-      body: comment
-    })
+  } else {
+    comment += '**No changes detected**.\n'
   }
+  comment += `\nYou can validate ${changedApis.length === 1 ? 'this' : 'these'} API${changedApis.length === 1 ? '' : 's'} yourself by using the ${tick}make validate${tick} target.\n`
+  core.setOutput('comment_body', comment)
 
   core.info('Done!')
 }
@@ -156,35 +169,65 @@ function getApi (file) {
   return file.split('/').slice(1, 3).filter(s => !privateNames.includes(s)).filter(Boolean).join('.')
 }
 
-function buildTableLine (api, report) {
-  const apiReport = report.get(getNamespace(api)).find(r => r.api === getName(api))
-  return `| ${tick}${api}${tick} | ${generateStatus(apiReport)} | ${generateRequest(apiReport)} | ${generateResponse(apiReport)} |\n`
+function findBaselineReport(apiName, baselineValidation) {
+  const [namespace, method] = apiName.split('.')
+
+  if (!baselineValidation.namespaces[namespace]) {
+    return null
+  }
+
+  return baselineValidation.namespaces[namespace].apis.find(api => api.api === method)
 }
 
-function generateStatus (report) {
-  if (!report.diagnostics.hasRequestType || !report.diagnostics.hasResponseType) {
+function hasChanges(baselineReport, report) {
+  if (!report) return false
+
+  return baselineReport.status !== report.status ||
+         baselineReport.passingRequest !== report.passingRequest ||
+         baselineReport.passingResponse !== report.passingResponse
+}
+
+function buildDiffTableLine(change) {
+  const { api, baseline, current } = change
+
+  const status = generateStatus(current.status)
+  const request = generateRequest(current)
+  const response = generateResponse(current)
+
+  const baselineStatus = generateStatus(baseline.status)
+  const baselineRequest = generateRequest(baseline)
+  const baselineResponse = generateResponse(baseline)
+
+  const statusDiff = status !== baselineStatus ? `${baselineStatus} → ${status}` : status
+  const requestDiff = request !== baselineRequest ? `${baselineRequest} → ${request}` : request
+  const responseDiff = response !== baselineResponse ? `${baselineResponse} → ${response}` : response
+
+  return `| ${tick}${api}${tick} | ${statusDiff} | ${requestDiff} | ${responseDiff} |\n`
+}
+
+
+function generateStatus (status) {
+  if (status === 'missing_types' || status === 'missing_request_type' || status === 'missing_response_type') {
     return ':orange_circle:'
   }
-  if (report.totalRequest <= 0 || report.totalResponse <= 0) {
+  if (status === 'missing_test') {
     return ':white_circle:'
   }
-  if (report.diagnostics.request.length === 0 && report.diagnostics.response.length === 0) {
+  if (status === 'passing') {
     return ':green_circle:'
   }
   return ':red_circle:'
 }
 
 function generateRequest (r) {
-  if (r.totalRequest === -1) return 'Missing recording'
-  if (!r.diagnostics.hasRequestType) return 'Missing type'
-  if (r.totalRequest === 0) return 'Missing test'
+  if (r.status === 'missing_test') return 'Missing test'
+  if (r.status === 'missing_types' || r.status == 'missing_request_type') return 'Missing type'
   return `${r.passingRequest}/${r.totalRequest}`
 }
 
 function generateResponse (r) {
-  if (r.totalResponse === -1) return 'Missing recording'
-  if (!r.diagnostics.hasResponseType) return 'Missing type'
-  if (r.totalResponse === 0) return 'Missing test'
+  if (r.status === 'missing_test') return 'Missing test'
+  if (r.status === 'missing_types' || r.status == 'missing_response_type') return 'Missing type'
   return `${r.passingResponse}/${r.totalResponse}`
 }
 

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

@@ -13,7 +13,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        branch: ['main', '9.0', '8.19', '8.18', '8.17', '8.16', '7.17']
+        branch: ['main', '9.1', '9.0', '8.19', '8.18']
 
     steps:
       - uses: actions/checkout@v4
@@ -28,8 +28,7 @@ jobs:
       - name: Install deps
         run: |
           npm install --prefix .github/download-artifacts
-          npm install --prefix compiler
-          npm install --prefix typescript-generator
+          make setup
 
       - name: Download artifacts
         run: |
@@ -53,12 +52,3 @@ jobs:
           delete-branch: true
           reviewers: Anaethelion,ezimuel,flobernd,JoshMock,l-trotta,miguelgrinberg,picandocodigo,pquentin,swallez,technige
           branch: automated/rest-api-spec-update-${{ matrix.branch }}
-
-      - name: Open an issue if the action fails
-        if: ${{ failure() }}
-        uses: nashmaniac/[email protected]
-        with:
-          title: rest-api-spec update failed
-          token: ${{ secrets.GITHUB_TOKEN }}
-          labels: bug
-          body: The rest-api-spec action is currently failing, see [here](https://github.com/elastic/elasticsearch-specification/actions/workflows/update-rest-api-json.yml).

.github/workflows/validate-pr.yml

@@ -60,18 +60,25 @@ jobs:
           fi
           node scripts/upload-recording/download.js --branch $branch --git
           node scripts/clone-elasticsearch/index.js --branch $branch
-        env:
-          GCS_CREDENTIALS: ${{ secrets.GCS_CREDENTIALS }}
-
-      - name: Remove previous comment
-        uses: maheshrayas/action-pr-comment-delete@v1
-        with:
-          github_token: ${{ secrets.GITHUB_TOKEN }}
-          org: elastic
-          repo: elasticsearch-specification
-          user: github-actions[bot]
-          issue: ${{ github.event.number }}
 
       - name: Run validation
+        id: validation
         working-directory: ./elasticsearch-specification
         run: node .github/validate-pr --token ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Find existing comment
+        uses: peter-evans/find-comment@3eae4d37986fb5a8592848f6a574fdf654e61f9e # v3.1.0
+        id: find-comment
+        with:
+          issue-number: ${{ github.event.pull_request.number }}
+          comment-author: 'github-actions[bot]'
+          body-includes: 'Following you can find the validation changes'
+
+      - name: Create or update comment
+        uses: peter-evans/create-or-update-comment@71345be0265236311c031f5c7866368bd1eff043 # v4.0.0
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+          comment-id: ${{ steps.find-comment.outputs.comment-id }}
+          issue-number: ${{ github.event.pull_request.number }}
+          body: ${{ steps.validation.outputs.comment_body }}
+          edit-mode: replace

.gitignore

@@ -65,10 +65,7 @@ output/schema/schema
 # Test suite outputs
 compiler/test/**/output/
 
-# Temporary openAPI files
-output/openapi/elasticsearch-serverless-openapi.tmp*.json
-output/openapi/elasticsearch-serverless-openapi.examples.json
-output/openapi/elasticsearch-openapi.tmp*.json
-output/openapi/elasticsearch-openapi.examples.json
-output/openapi/elasticsearch-serverless-openapi-docs.json
-output/openapi/elasticsearch-openapi-docs.json
+# Temporary openAPI documentation files
+output/openapi/elasticsearch-serverless-openapi-docs*.json
+output/openapi/elasticsearch-openapi-docs*.json
+output/openapi/elasticsearch*.redirects.csv

CONTRIBUTING.md

@@ -39,7 +39,7 @@ Documents under the docs/ directory will help you to change the specification. T
  * [Fixing a definition, the complete story](docs/validation-example.md)
 
 
-## Send your pull request
+## Send your pull request from a branch
 
 To fix any style issues and generate the outputs (that we store in git), please run:
 
@@ -56,5 +56,4 @@ Then, follow those steps:
   - If the API is unusable without the change -> every supported version
   - If the API is usable, but fix is on the response side -> every supported version
   - If the API is usable, but fix is on the request side -> no backport, unless the API is _partially_ usable and the fix unlocks a missing feature that has no workaround
-
-
+- Send the pull request from a branch, **not a fork**

Makefile

@@ -43,6 +43,7 @@ setup:	## Install dependencies for contrib target
 	@npm install --prefix validator
 	@npm install --prefix specification
 	@npm install @redocly/cli
+	@npm install --prefix docs/examples
 
 clean-dep:	## Clean npm dependencies
 	@rm -rf compiler/node_modules
@@ -56,8 +57,10 @@ transform-to-openapi: ## Generate the OpenAPI definition from the compiled schem
 	@npm run transform-to-openapi -- --schema output/schema/schema.json --flavor serverless --output output/openapi/elasticsearch-serverless-openapi.json
 
 transform-to-openapi-for-docs: ## Generate the OpenAPI definition tailored for API docs generation
-	@npm run transform-to-openapi -- --schema output/schema/schema.json --flavor stack --lift-enum-descriptions --merge-multipath-endpoints --multipath-redirects --output output/openapi/elasticsearch-openapi-docs.json
-	@npm run transform-to-openapi -- --schema output/schema/schema.json --flavor serverless --lift-enum-descriptions --merge-multipath-endpoints --multipath-redirects --output output/openapi/elasticsearch-serverless-openapi-docs.json
+	@make generate-language-examples
+	@make generate
+	@npm run transform-to-openapi -- --schema output/schema/schema.json --flavor stack --lift-enum-descriptions --merge-multipath-endpoints --multipath-redirects --include-language-examples --output output/openapi/elasticsearch-openapi-docs.json
+	@npm run transform-to-openapi -- --schema output/schema/schema.json --flavor serverless --lift-enum-descriptions --merge-multipath-endpoints --multipath-redirects --include-language-examples --output output/openapi/elasticsearch-serverless-openapi-docs.json
 
 filter-for-serverless: ## Generate the serverless version from the compiled schema
 	@npm run --prefix compiler filter-by-availability -- --serverless --visibility=public --input ../output/schema/schema.json --output ../output/output/openapi/elasticsearch-serverless-openapi.json
@@ -66,23 +69,31 @@ dump-routes: ## Create a new schema with all generics expanded
 	@npm run dump-routes --prefix compiler
 
 overlay-docs: ## Apply overlays to OpenAPI documents
-	@npx bump overlay "output/openapi/elasticsearch-serverless-openapi.json" "docs/overlays/elasticsearch-serverless-openapi-overlays.yaml" > "output/openapi/elasticsearch-serverless-openapi.tmp1.json"
-	@npx bump overlay "output/openapi/elasticsearch-serverless-openapi.tmp1.json" "docs/overlays/elasticsearch-shared-overlays.yaml" > "output/openapi/elasticsearch-serverless-openapi.tmp2.json"
-	@npx @redocly/cli bundle output/openapi/elasticsearch-serverless-openapi.tmp2.json --ext json -o output/openapi/elasticsearch-serverless-openapi.examples.json
-	@npx bump overlay "output/openapi/elasticsearch-openapi.json" "docs/overlays/elasticsearch-openapi-overlays.yaml" > "output/openapi/elasticsearch-openapi.tmp1.json"
-	@npx bump overlay "output/openapi/elasticsearch-openapi.tmp1.json" "docs/overlays/elasticsearch-shared-overlays.yaml" > "output/openapi/elasticsearch-openapi.tmp2.json"
-	@npx @redocly/cli bundle output/openapi/elasticsearch-openapi.tmp2.json --ext json -o output/openapi/elasticsearch-openapi.examples.json
-	rm output/openapi/elasticsearch-serverless-openapi.tmp*.json
-	rm output/openapi/elasticsearch-openapi.tmp*.json
+	@npx bump overlay "output/openapi/elasticsearch-serverless-openapi-docs.json" "docs/overlays/elasticsearch-serverless-openapi-overlays.yaml" > "output/openapi/elasticsearch-serverless-openapi-docs.tmp1.json"
+	@npx bump overlay "output/openapi/elasticsearch-serverless-openapi-docs.tmp1.json" "docs/overlays/elasticsearch-shared-overlays.yaml" > "output/openapi/elasticsearch-serverless-openapi-docs.tmp2.json"
+	@npx @redocly/cli bundle output/openapi/elasticsearch-serverless-openapi-docs.tmp2.json --ext json -o output/openapi/elasticsearch-serverless-openapi-docs-final.json
+	@npx bump overlay "output/openapi/elasticsearch-openapi-docs.json" "docs/overlays/elasticsearch-openapi-overlays.yaml" > "output/openapi/elasticsearch-openapi-docs.tmp1.json"
+	@npx bump overlay "output/openapi/elasticsearch-openapi-docs.tmp1.json" "docs/overlays/elasticsearch-shared-overlays.yaml" > "output/openapi/elasticsearch-openapi-docs.tmp2.json"
+	@npx @redocly/cli bundle output/openapi/elasticsearch-openapi-docs.tmp2.json --ext json -o output/openapi/elasticsearch-openapi-docs-final.json
+	rm output/openapi/elasticsearch-serverless-openapi-docs.tmp*.json
+	rm output/openapi/elasticsearch-openapi-docs.tmp*.json
+
+generate-language-examples:
+	@node docs/examples/generate-language-examples.js
+	@npm run format:fix-examples --prefix compiler
+
+generate-language-examples-with-java:
+	@node docs/examples/generate-language-examples.js java
+	@npm run format:fix-examples --prefix compiler
 
 lint-docs: ## Lint the OpenAPI documents after overlays
 	@npx @redocly/cli lint "output/openapi/elasticsearch-*.json" --config "docs/linters/redocly.yaml" --format stylish --max-problems 500
 
-lint-docs-stateful: ## Lint only the elasticsearch-openapi.examples.json file
-	@npx @redocly/cli lint "output/openapi/elasticsearch-openapi.examples.json" --config "docs/linters/redocly.yaml" --format stylish --max-problems 500
+lint-docs-stateful: ## Lint only the elasticsearch-openapi-docs-final.json file
+	@npx @redocly/cli lint "output/openapi/elasticsearch-openapi-docs-final.json" --config "docs/linters/redocly.yaml" --format stylish --max-problems 500
 
 lint-docs-serverless: ## Lint only the serverless OpenAPI document after overlays
-	@npx @redocly/cli lint "output/openapi/elasticsearch-serverless-openapi.examples.json" --config "docs/linters/redocly.yaml" --format stylish --max-problems 500
+	@npx @redocly/cli lint "output/openapi/elasticsearch-serverless-openapi-docs-final.json" --config "docs/linters/redocly.yaml" --format stylish --max-problems 500
 
 contrib: | generate license-check spec-format-fix transform-to-openapi filter-for-serverless lint-docs ## Pre contribution target