Merge branch 'opensearch-project:main' into remove/default

.github/workflows/lint.yml

@@ -24,4 +24,5 @@ jobs:
         with:
           node-version: 20.10.0
       - run: npm install
-      - run: npm run lint -- ../spec
+      - run: |
+          npm run lint:spec -- ../spec

.github/workflows/tools.yml

@@ -23,3 +23,4 @@ jobs:
           node-version: 20.10.0
       - run: npm install
       - run: npm run test
+      - run: npm run lint

DEVELOPER_GUIDE.md

@@ -45,6 +45,7 @@ spec
 │
 └── opensearch-openapi.yaml
 ```
+
 Every `.yaml` file is a valid OpenAPI 3 document. This means that you can use any OpenAPI 3 compatible tool to view and edit the files, and IDEs with OpenAPI support will provide you with autocompletion and validation in real-time.
 
 ## Grouping Operations
@@ -84,6 +85,14 @@ This repository includes several penAPI Specification Extensions to fill in any
 - `x-global`: Denotes that the parameter is a global parameter that is included in every operation. These parameters are listed in the [root file](spec/opensearch-openapi.yaml).
 - `x-default`: Contains the default value of a parameter. This is often used to override the default value specified in the schema, or to avoid accidentally changing the default value when updating a shared schema.
 
-## Linting
-We have a linter that validates every `yaml` file in the `./spec` folder to assure that they follow the guidelines we have set. Check out the [Linter](tools/README.md#linter) tool for more information on how to run it locally. Make sure to run the linter before submitting a PR.
+## Tools
+
+We authored a number of tools to merge and lint specs that live in [tools](tools/). All tools have tests (run with `npm run test`) and a linter (run with `npm run lint`).
+
+### Merger
+
+The spec merger "builds", aka combines various `.yaml` files into a complete OpenAPI spec. A [workflow](./.github/workflows/build.yml) publishes the output into [releases](https://github.com/opensearch-project/opensearch-api-specification/releases).
+
+### Linter
 
+The spec linter that validates every `.yaml` file in the `./spec` folder to assure that they follow the guidelines we have set. Check out the [Linter README](tools/README.md#linter) for more information on how to run it locally. Make sure to run the linter before submitting a PR.

tools/README.md

@@ -1,25 +1,34 @@
 # OpenSearch OpenAPI Tools
+
 This folder contains tools for the repo:
-- Merger: merges multiple OpenAPI files into one
-- Linter: validates files in the spec folder
+
+- [Merger](./merger/): merges multiple OpenAPI files into one
+- [Linter](./linter/): validates files in the spec folder
 
 ## Setup
+
 1. Install [Node.js](https://nodejs.org/en/learn/getting-started/how-to-install-nodejs)
 2. Run `npm install` in the `tools` folder
 
 ## Merger
+
 The merger tool merges the multi-file OpenSearch spec into a single file for programmatic use. It takes 2 parameters:
-- The path to the root folder of the multi-file spec
-- The path to the output file
+
+- the path to the root folder of the multi-file spec
+- the path to the output file
+
 Example:
+
 ```bash
 npm run merge -- ../spec ../build/opensearch-openapi.latest.yaml
 ```
 
 ## Linter
+
 The linter tool validates the OpenSearch spec files in the `spec` folder:
+
 ```bash
-npm run lint
+npm run lint:spec
 ```
+
 It will print out all the errors and warnings in the spec files. This tool in still in development, and it will be integrated into the CI/CD pipeline and run automatically with every PR.
-```

tools/eslint.config.mjs

@@ -0,0 +1,68 @@
+import path from 'path'
+import { fileURLToPath } from 'url'
+import { FlatCompat } from '@eslint/eslintrc'
+import pluginJs from '@eslint/js'
+
+// mimic CommonJS variables -- not needed if using CommonJS
+const _filename = fileURLToPath(import.meta.url)
+const _dirname = path.dirname(_filename)
+const compat = new FlatCompat({ baseDirectory: _dirname, recommendedConfig: pluginJs.configs.recommended })
+
+export default [
+  pluginJs.configs.recommended,
+  ...compat.extends('standard-with-typescript'),
+  {
+    files: ['**/*.{js,ts}'],
+    ignores: [
+      '**/eslint.config.mjs'
+    ],
+    rules: {
+      '@typescript-eslint/array-type': 'warn',
+      '@typescript-eslint/block-spacing': 'warn',
+      '@typescript-eslint/comma-dangle': 'warn',
+      '@typescript-eslint/comma-spacing': 'warn',
+      '@typescript-eslint/consistent-indexed-object-style': 'warn',
+      '@typescript-eslint/consistent-type-assertions': 'warn',
+      '@typescript-eslint/consistent-type-imports': 'warn',
+      '@typescript-eslint/dot-notation': 'warn',
+      '@typescript-eslint/explicit-function-return-type': 'warn',
+      '@typescript-eslint/indent': 'warn',
+      '@typescript-eslint/keyword-spacing': 'warn',
+      '@typescript-eslint/lines-between-class-members': 'warn',
+      '@typescript-eslint/member-delimiter-style': 'warn',
+      '@typescript-eslint/naming-convention': 'warn',
+      '@typescript-eslint/no-confusing-void-expression': 'warn',
+      '@typescript-eslint/no-dynamic-delete': 'warn',
+      '@typescript-eslint/no-invalid-void-type': 'warn',
+      '@typescript-eslint/no-non-null-assertion': 'warn',
+      '@typescript-eslint/no-unnecessary-type-assertion': 'warn',
+      '@typescript-eslint/no-unsafe-argument': 'warn',
+      '@typescript-eslint/no-unused-vars': 'warn',
+      '@typescript-eslint/object-curly-spacing': 'warn',
+      '@typescript-eslint/prefer-nullish-coalescing': 'warn',
+      '@typescript-eslint/quotes': 'warn',
+      '@typescript-eslint/require-array-sort-compare': 'warn',
+      '@typescript-eslint/semi': 'warn',
+      '@typescript-eslint/space-before-blocks': 'warn',
+      '@typescript-eslint/space-before-function-paren': 'warn',
+      '@typescript-eslint/space-infix-ops': 'warn',
+      '@typescript-eslint/strict-boolean-expressions': 'warn',
+      '@typescript-eslint/type-annotation-spacing': 'warn',
+      'array-bracket-spacing': 'warn',
+      'array-callback-return': 'warn',
+      curly: 'warn',
+      'eol-last': 'warn',
+      eqeqeq: 'warn',
+      'new-cap': 'warn',
+      'no-multi-spaces': 'warn',
+      'no-multiple-empty-lines': 'warn',
+      'no-return-assign': 'warn',
+      'no-useless-return': 'warn',
+      'object-curly-newline': 'warn',
+      'object-property-newline': 'warn',
+      'object-shorthand': 'warn',
+      'quote-props': 'warn',
+      'space-in-parens': 'warn'
+    }
+  }
+]

tools/jest.config.js

@@ -1,5 +1,5 @@
 /** @type {import('ts-jest').JestConfigWithTsJest} */
 module.exports = {
   preset: 'ts-jest',
-  testEnvironment: 'node',
-};
+  testEnvironment: 'node'
+}