CLOUDP-271224: Add spectral rules and validation for soa migration

.github/workflows/required-spec-validations.yml

@@ -33,7 +33,7 @@ jobs:
           id: spectral-validation
           env:
             SPECTRAL_VERSION: ${{ inputs.spectral_version }}
-          run: npx -- @stoplight/spectral-cli@"${SPECTRAL_VERSION}" lint openapi-foas.yaml --ruleset=.spectral.yaml # we will update this to lint the FOAS in CLOUDP-263186
+          run: npx -- @stoplight/spectral-cli@"${SPECTRAL_VERSION}" lint openapi-foas.yaml --ruleset=tools/spectral/.spectral.yaml
         - name: Install Go
           uses: actions/setup-go@0a12ed9d6a96ab950c8f026ed9f722fe0da7ef32
           with:

.github/workflows/spectral-lint.yml

@@ -0,0 +1,35 @@
+name: Spectral Lint Commited OpenAPI Spec
+
+# Trigger the workflow on pull requests and pushes to the main branch
+on:
+  pull_request:
+    paths: 
+      - 'tools/spectral/**'
+      - 'openapi/**.yaml'
+      - '.spectral.yaml'
+  push:
+    branches:
+      - main
+    paths: 
+      - 'tools/spectral/**'
+      - 'openapi/**.yaml'
+      - '.spectral.yaml'
+
+jobs:
+  spectral-lint:
+    runs-on: ubuntu-latest
+
+    steps:
+      # Checkout the code
+      - name: Checkout repository
+        uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332
+        with:
+          sparse-checkout: |
+            openapi/
+            tools/spectral
+      - name: Spectral action
+        uses: stoplightio/spectral-action@2ad0b9302e32a77c1caccf474a9b2191a8060d83
+        with:
+          # Path to the OpenAPI spec files and openapi/v2.yaml
+          file_glob: openapi/v2.yaml
+          spectral_ruleset: tools/spectral/.spectral.yaml

.spectral.yaml → tools/spectral/.spectral.yaml

@@ -155,6 +155,34 @@ rules:
         function: pattern
         functionOptions:
           match: "^(dev|qa|stage|prod)(,(dev|qa|stage|prod))*$"
+
+  soa-migration-extension:
+    description: "Ensure the x-xgen-soa-migration extension is valid."
+    message: "The x-xgen-soa-migration extension must include 'service_name', 'allow_diff', and 'source_service' should only be present when 'allow_diff' is true."
+    formats: ["oas3"]
+    given: "$.paths[*][*].x-xgen-soa-migration"
+    severity: error
+    then:
+      - field: service_name
+        function: truthy
+        message: "'service_name' must be provided."
+      - field: allow_diff
+        function: pattern
+        functionOptions:
+          match: "^(true|false)$"
+        message: "'allow_diff' must be true or false."
+      - function: falsy
+        field: source_service
+        message: "'source_service' should not exist when 'allow_diff' is false."
+        when:
+          field: allow_diff
+          pattern: "^false$"
+      - function: truthy
+        field: source_service
+        message: "'source_service' must be provided when 'allow_diff' is true."
+        when:
+          field: allow_diff
+          pattern: "^true$"
 
 overrides:
   - files: # load sample data has an issue with different path param names for different VERBS

tools/spectral/Makefile

@@ -0,0 +1,32 @@
+# A Self-Documenting Makefile: http://marmelab.com/blog/2016/02/29/auto-documented-makefile.html
+
+SPECTRAL_VERSION=${SPECTRAL_VERSION:-6.11.1}
+
+.PHONY: deps
+deps:  ## Download go module dependencies
+	@echo "==> Installing npx..."
+	npm install -g npx
+
+
+.PHONY: devtools
+devtools:  ## Install dev tools
+	@echo "==> Installing dev tools..."
+	npm install -g @stoplight/spectral-cli@"${SPECTRAL_VERSION}"
+
+.PHONY: setup
+setup: deps devtools ## Set up dev env
+
+.PHONY: linterr
+linterr: ## Run spectral linter on foas
+	@echo "==> Running spectral linter"
+	npx -- @stoplight/spectral-cli@"${SPECTRAL_VERSION}" lint ../../openapi/v2.yaml --ruleset=.spectral.yaml
+
+.PHONY: lintwarn
+lintwarn: ## Run spectral linter on foas
+	@echo "==> Running spectral linter"
+	npx -- @stoplight/spectral-cli@"${SPECTRAL_VERSION}" lint ../../openapi/v2.yaml --ruleset=.spectral.yaml --fail-severity=warn
+
+.PHONY: help
+.DEFAULT_GOAL := help
+help:
+	@grep -h -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m%-30s\033[0m %s\n", $$1, $$2}'