CLOUDP 329998: IPA package configuration (#846)

Co-authored-by: Wojciech Trocki <[email protected]>
Co-authored-by: Lovisa Berggren <[email protected]>

Author: 3 people

.github/dependabot.yml

@@ -22,3 +22,10 @@ updates:
       day: tuesday
     commit-message:
       prefix: "chore"
+  - package-ecosystem: npm
+    directory: "/tools/spectral/ipa"
+    schedule:
+      interval: weekly
+      day: tuesday
+    commit-message:
+      prefix: "chore"

.github/workflows/code-health-tools.yml

@@ -64,7 +64,7 @@ jobs:
         run: |
           npm run gen-ipa-docs
           if [[ -n $(git status --porcelain) ]]; then
-            echo "IPA docs not up to date, please run 'npm run gen-ipa-docs' and commit the changes"
+            echo "IPA docs or NPM dependencies not up to date, please run 'npm run gen-ipa-docs' and 'npm install' then commit the changes"
             exit 1
           fi
           exit 0

.gitignore

@@ -14,8 +14,7 @@
 *.env
 
 /tools/postman/openapi
-/tools/postman/node_modules
-/node_modules
+**/*node_modules
 
 # Tool generated files
 *.idea

package-lock.json

@@ -32,7 +32,6 @@
         "@stoplight/spectral-ruleset-bundler": "^1.6.3",
         "apache-arrow": "^21.0.0",
         "dotenv": "^17.2.0",
-        "ember-inflector": "^6.0.0",
         "eslint-plugin-jest": "^29.0.1",
         "inflection": "^3.0.2",
         "markdown-table": "^3.0.4",

package.json

@@ -1,6 +1,7 @@
 # MongoDB API Spectral Validation
 
-A set of custom validator rules for the MongoDB Atlas Programmatic API, adhering to API Standards (IPA)
+A set of custom validation rules for the MongoDB Atlas Programmatic API, adhering to MongoDB API standards - [Improvement Proposal for APIs](https://mongodb.github.io/ipa/) (IPA).
+
 ## Structure
 
 - **/ipa** - Contains custom Spectral rulesets covering MongoDB API standards.

tools/spectral/README.md

@@ -2,6 +2,19 @@
 
 The IPA validation uses [Spectral](https://docs.stoplight.io/docs/spectral/9ffa04e052cc1-spectral-cli) to validate the [MongoDB Atlas Admin API OpenAPI Specification](https://github.com/mongodb/openapi/tree/main/openapi). The rules cover MongoDB's [Improvement Proposal for APIs](https://mongodb.github.io/ipa/) (IPA), which are best-practices for API design.
 
+
+## Quick Links
+
+| Site                        | Link                                                                                                     |
+| --------------------------- | -------------------------------------------------------------------------------------------------------- |
+| MongoDB API Standards (IPA) | [https://mongodb.github.io/ipa/](https://mongodb.github.io/ipa/)                                         |
+| Installation & Usage           | [IPA README](https://github.com/mongodb/openapi/tree/main/tools/spectral/ipa#readme) |
+| Implemented Rules           | [Ruleset Documentation](https://github.com/mongodb/openapi/tree/main/tools/spectral/ipa/rulesets#readme) |
+| Spectral Docs               | [Spectral](https://docs.stoplight.io/docs/spectral/674b27b261c3c-overview)                               |
+| Contributing                | [CONTRIBUTING.md](https://github.com/mongodb/openapi/blob/main/tools/spectral/CONTRIBUTING.md)           |
+| Changelog                   | [CHANGELOG.md](https://github.com/mongodb/openapi/blob/main/tools/spectral/CHANGELOG.md)                 |
+| Issues                      | [https://github.com/mongodb/openapi/issues](https://github.com/mongodb/openapi/issues)                   |
+
 ## Running Locally
 
 ### Prerequisites
@@ -19,30 +32,20 @@ npm run ipa-validation
 
 This command will run Spectral CLI for the ruleset [ipa-spectral.yaml](https://github.com/mongodb/openapi/blob/main/tools/spectral/ipa/ipa-spectral.yaml) on the raw [v2.yaml](https://github.com/mongodb/openapi/blob/main/openapi/.raw/v2.yaml) OpenAPI spec.
 
-The Spectral CLI can also be used to run the validation on any valid OpenAPI file (`json` or `yaml`).
-
-```
-spectral lint {path/to/oas/file} --ruleset=./tools/spectral/ipa/ipa-spectral.yaml
-```
-
 ## Integrating IPA Validations
 
 To incorporate the IPA Spectral ruleset for OpenAPI specification validation in your repositories, you can follow these implementation approaches:
 
 ### Installation Options
 
-#### Server-based Installation
-
-You can reference our ruleset directly in your `.spectral.yaml` file without installation:
-
+#### Package-based Installation (**TO BE RELEASED**)
+Run:
 ```
-extends:
-- https://raw.githubusercontent.com/mongodb/openapi/<latest-git-commit-sha>/tools/spectral/ipa/ipa-spectral.yaml
+npm install @mongodb-js/ipa-validation-ruleset
 ```
 
-#### Package-based Installation
-
-Not supported yet
+#### Limitations
+The IPA Validation Framework uses third party dependencies for certain rules. With this approach, [server based installation](https://docs.stoplight.io/docs/spectral/7895ff1196448-sharing-and-distributing-rulesets#http-server) is not supported. Instead, use the recommended package-based installation or clone the repo.
 
 ### Integration Methods
 
@@ -52,7 +55,7 @@ Create a `.spectral.yaml` file that extends our ruleset:
 
 ```
 extends:
-- https://raw.githubusercontent.com/mongodb/openapi/<latest-git-commit-sha>/tools/spectral/ipa/ipa-spectral.yaml
+- "@mongodb/ipa-validation-ruleset"
 ```
 
 For more information about how to extend rulesets, see the [web page](https://meta.stoplight.io/docs/spectral/83527ef2dd8c0-extending-rulesets).
@@ -63,7 +66,7 @@ You can override specific rules from our ruleset by adding them to your local `.
 
 ```
 extends:
-- https://raw.githubusercontent.com/mongodb/openapi/<latest-git-commit-sha>/tools/spectral/ipa/ipa-spectral.yaml
+- "@mongodb/ipa-validation-ruleset"
 
 overrides:
     - files: