Parse command line arguments in merger and linter.

.github/workflows/build.yml

@@ -25,9 +25,7 @@ jobs:
         run: |-
           mkdir -p ../build
           npm install
-          export ROOT_PATH=../spec
-          export OUTPUT_PATH=../build/opensearch-openapi.yaml
-          npm run merge -- $ROOT_PATH $OUTPUT_PATH
+          npm run merge -- --source ../spec --output ../build/opensearch-openapi.yaml
 
       - name: Extract Branch Name
         id: branch

.github/workflows/coverage-gather.yml

@@ -19,9 +19,7 @@ jobs:
         run: |-
           mkdir -p ../build
           npm install
-          export ROOT_PATH=../spec
-          export OUTPUT_PATH=../build/opensearch-openapi.yaml
-          npm run merge -- $ROOT_PATH $OUTPUT_PATH
+          npm run merge -- --source ../spec --output ../build/opensearch-openapi.yaml
       - name: Build and Run Docker Container
         run: |
           docker build coverage --tag opensearch-with-api-plugin

.github/workflows/lint.yml

@@ -25,4 +25,4 @@ jobs:
           node-version: 20.10.0
       - run: npm install
       - run: |
-          npm run lint:spec -- ../spec
+          npm run lint:spec -- --source ../spec

_plugins/openapi.rb

@@ -4,7 +4,7 @@ def self.generate(_site, _payload)
 
     Dir.chdir('tools') do
       system 'npm install'
-      system 'npm run merge -- ../spec ../_site/opensearch-openapi.yaml'
+      system 'npm run merge -- --source ../spec --output ../_site/opensearch-openapi.yaml'
     end
 
     @generated = true

tools/README.md

@@ -12,34 +12,36 @@ This folder contains tools for the repo:
 
 ## Merger
 
-The merger tool merges the multi-file OpenSearch spec into a single file for programmatic use. It takes 2 parameters:
+The merger tool merges the multi-file OpenSearch spec into a single file for programmatic use. 
 
-- the path to the root folder of the multi-file spec
-- the path to the output file
+It requires a path to the root folder of the multi-file spec (`--source`) and a path to the output file (`--output`).
 
 Example:
 
 ```bash
 mkdir -p ../build
-export ROOT_PATH=../spec
-export OUTPUT_PATH=../build/opensearch-openapi.yaml
-npm run merge -- $ROOT_PATH $OUTPUT_PATH
+npm run merge -- --source ../spec --output ../build/opensearch-openapi.yaml
 ```
 
 As a shortcut, if those parameters are not provided, the tool will use the default values:
+
 - `../spec` as the root path (i.e. the repo's [spec folder](../spec))
-- `../opensearch-openapi.yaml` as the output path
+- `../build/opensearch-openapi.yaml` as the output path
 
 ```bash
 npm run merge
 ```
 
+Run `npm run merge -- --help` for all options.
+
 ## Spec Linter
 
-The linter tool validates the OpenSearch spec files in the `spec` folder:
+The linter tool validates the OpenSearch multi-file spec, and will print out all the errors and warnings in it.
+
+It requires a path to the root folder of the multi-file spec (`--source`).
 
 ```bash
-npm run lint:spec
+npm run lint:spec -- --source ../spec
 ```
 
-It will print out all the errors and warnings in the spec files.
+Run `npm run lint:spec -- --help` for all options.

tools/linter/lint.ts

@@ -1,7 +1,16 @@
+import { Command, Option } from '@commander-js/extra-typings'
 import SpecValidator from './SpecValidator'
+import { resolve } from 'path'
 
-const root_folder = process.argv[2] ?? '../spec'
-const validator = new SpecValidator(root_folder)
+const command = new Command()
+  .description('Validate the OpenSearch multi-file spec.')
+  .addOption(new Option('-s, --source <path>', 'path to the root folder of the multi-file spec').default(resolve(__dirname, '../../spec')))
+  .allowExcessArguments(false)
+  .parse()
+
+const opts = command.opts()
+console.log(`Validating ${opts.source} ...`)
+const validator = new SpecValidator(opts.source)
 const errors = validator.validate()
 
 if (errors.length === 0) {

tools/merger/merge.ts

@@ -1,6 +1,16 @@
+import { Command, Option } from '@commander-js/extra-typings'
 import OpenApiMerger from './OpenApiMerger'
+import { resolve } from 'path'
 
-const root_path: string = process.argv[2] || '../spec'
-const output_path: string = process.argv[3] || '../opensearch-openapi.yaml'
-const merger = new OpenApiMerger(root_path)
-merger.merge(output_path)
+const command = new Command()
+  .description('Merges the multi-file OpenSearch spec into a single file for programmatic use.')
+  .addOption(new Option('-s, --source <path>', 'path to the root folder of the multi-file spec').default(resolve(__dirname, '../../spec')))
+  .addOption(new Option('-o, --output <path>', 'output file name').default(resolve(__dirname, '../../build/opensearch-openapi.yaml')))
+  .allowExcessArguments(false)
+  .parse()
+
+const opts = command.opts()
+const merger = new OpenApiMerger(opts.source)
+console.log(`Merging ${opts.source} into ${opts.output} ...`)
+merger.merge(opts.output)
+console.log('Done.')

tools/package.json

@@ -12,10 +12,12 @@
   },
   "dependencies": {
     "@apidevtools/swagger-parser": "^10.1.0",
+    "@commander-js/extra-typings": "^12.0.1",
     "@types/lodash": "^4.14.202",
     "@types/node": "^20.10.3",
     "ajv": "^8.13.0",
     "ajv-formats": "^3.0.1",
+    "commander": "^12.0.0",
     "lodash": "^4.17.21",
     "ts-node": "^10.9.1",
     "typescript": "^5.4.5",