Example of a custom JS spectral rule

tools/.tool-versions

@@ -1 +1,2 @@
 golang 1.23.0
+nodejs 16.18.0

tools/spectral/.spectral.yaml

@@ -2,6 +2,10 @@
 extends:
   - spectral:oas
 
+functionsDir: './functions'
+functions:
+  - path-name-collisions
+
 aliases:
   PathItem:
     - "$.paths[*]"
@@ -16,175 +20,183 @@ aliases:
     - "$.components.schemas[*].properties[?(@ && @.type)]"
 
 rules:
-  xgen-schema-properties-camel-case:
-    description:
-        All properties in the schema must be camelCase. http://go/ipa/112
-    severity: error
-    recommended: true
-    message: "`{{property}}` MUST follow camelCase"
-    given: "$.components.schemas..properties[*]~"
-    then:
-      function: pattern # casing?
-      functionOptions:
-        match: "/^[a-z$_]{1}[A-Z09$_]*/" # type: camel ?
-
-  xgen-schema-name-pascal-case:
-    description: OpenAPI Schema names should use PascalCase. PascalCase ensures consistency with OpenAPI generated code.
-    message: "`{{property}}` name must follow PascalCase. Please verify if you have provided valid @Schema(name='') annotation"
-    severity: error
-    given: "$.components.schemas[*]~"
-    then:
-      function: pattern # casing?
-      functionOptions:
-        match: "^[A-Z].*" # type: pascal ?
-
-  xgen-description:
-    description: "Use this field to describe the action performed by each specific API endpoint or property, to provide context for how to use it to the users of the API."
-    message: "{{error}}."
-    severity: error
-    given: "#DescribableObjects"
-    then:
-      - field: "description"
-        function: truthy
-      - field: "description"
-        function: pattern
-        functionOptions:
-          match: "/^[A-Z]/"
-      - field: "description"
-        function: pattern
-        functionOptions:
-          match: "\\.|\|$"
-
-  xgen-request-GET-no-body:
-    description: "A 'GET' request MUST NOT accept a 'body` parameter. http://go/ipa/104"
-    severity: error
-    given: $.paths..get.parameters..in
-    then:
-      function: pattern
-      functionOptions:
-        notMatch: "/^body$/"
-
-  xgen-request-DELETE-no-body:
-    description: "A 'DELETE' request MUST NOT accept a 'body` parameter. http://go/ipa/108"
-    severity: error
-    given: $.paths..delete.parameters..in
-    then:
-      function: pattern
-      functionOptions:
-        notMatch: "/^body$/"
-
-  xgen-docs-tags-alphabetical:
-    message: "Tags should be defined in alphabetical order."
-    description: "Many documentation tools show tags in the order they are defined, so defining them not in alphabetical order can look funny to API consumers."
-    severity: error
-    given: "$"
-    then:
-      field: "tags"
-      function: alphabetical
-      functionOptions:
-        keyedBy: "name"
-
-  xgen-docs-tags:
-    message: "{{error}}."
-    description: "Tags help group logic into conceptual groups instead of making end-users dig through URLs or lists of operation names."
-    severity: error
-    given: "$"
-    then:
-      field: "tags"
-      function: schema
-      functionOptions:
-        schema:
-          type: "array"
-          minItems: 1
-
-  xgen-docs-operation-tags:
-    message: "Operation should have non-empty `tags` array."
-    description:
-     "Once tags are defined they should be references in the operation, otherwise they will not be doing anything."
-    severity: error
-    given: "#OperationObject"
-    then:
-      field: "tags"
-      function: schema
-      functionOptions:
-        schema:
-          type: "array"
-          minItems: 1
-
-  xgen-docs-operationId-valid-in-url:
-    message: "operationId must only contain URL friendly characters."
-    description: "Most documentation tools use the operationId to produce URLs, so the characters used must be safe and legal when used in the URL."
-    severity: error
-    given: "#OperationObject"
-    then:
-      field: "operationId"
-      function: pattern
-      functionOptions:
-        match: "^[A-Za-z0-9-._~:/?#\\[\\]@!\\$&'()*+,;=]*$"
-
-  xgen-docs-parameter-examples-or-schema:
-    message: "No example or schema provided for {{property}}."
-    description: "Without providing a well defined schema or example(s) an API consumer will have a hard time knowing how to interact with this API."
-    severity: error
-    given: "$.paths[*]..parameters[*]"
-    then:
-      function: schema
-      functionOptions:
-        schema:
-          anyOf:
-            - required: ["example"]
-            - required: ["examples"]
-            - required: ["schema"]
-
-  x-xgen-hidden-env-format:
-    description: "Ensure x-xgen-hidden-env extension has the correct format. https://go/openapi-hidden-extension"
-    severity: error
-    given: "$..x-xgen-hidden-env"                    # Match anywhere in the document
-    then:
-      - field: envs
-        function: truthy
-      - field: envs
-        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 'additionalServices', 'targetService', 'allowDocsDiff', and 'docsSource'."
-    formats: ["oas3"]
-    given: "$.paths[*][*].x-xgen-soa-migration"
-    severity: error
-    then:
-      - field: targetService
-        function: truthy
-        message: "'targetService' must be provided."
-      - field: allowDocsDiff
-        function: pattern
-        functionOptions:
-          match: "^(true|false)$"
-        message: "'allowDocsDiff' must be true or false."
-      - field: docsSource
-        function: truthy
-        message: "'docsSource' must be provided."
-      - field: additionalServices
-        function: truthy
-        message: "'additionalServices' must be provided."
-      - field: additionalServices
-        function: pattern
-        functionOptions:
-          match: "^(mms)$"
-        message: "'additionalServices' must be 'mms' as no other services are supported."
-
-   no-slash-before-custom-method:
-    description: "Custom methods (e.g., ':applyItem') should not be preceded by a '/'."
-    message: "The path '{{path}}' contains a '/' before a custom method. Custom methods should not start with a '/'."
-    severity: error
+  no-overlapping-paths:
+    description: "Checks for overlapping paths with path parameters that may shadow each other."
     given: "$.paths"
+    message: "{{error}}"
+    severity: error
     then:
-      field: "@key"
-      function: pattern
-      functionOptions:
-        notMatch: "/[^/]+/:[a-zA-Z]+$"
+      function: "path-name-collisions"
+#
+#  xgen-request-GET-no-body:
+#    description: "A 'GET' request MUST NOT accept a 'body` parameter. http://go/ipa/104"
+#    severity: error
+#    given: $.paths..get.parameters..in
+#    then:
+#      function: pattern
+#      functionOptions:
+#        notMatch: "/^body$/"
+#
+#  xgen-schema-properties-camel-case:
+#    description:
+#        All properties in the schema must be camelCase. http://go/ipa/112
+#    severity: error
+#    recommended: true
+#    message: "`{{property}}` MUST follow camelCase"
+#    given: "$.components.schemas..properties[*]~"
+#    then:
+#      function: pattern # casing?
+#      functionOptions:
+#        match: "/^[a-z$_]{1}[A-Z09$_]*/" # type: camel ?
+#
+#  xgen-schema-name-pascal-case:
+#    description: OpenAPI Schema names should use PascalCase. PascalCase ensures consistency with OpenAPI generated code.
+#    message: "`{{property}}` name must follow PascalCase. Please verify if you have provided valid @Schema(name='') annotation"
+#    severity: error
+#    given: "$.components.schemas[*]~"
+#    then:
+#      function: pattern # casing?
+#      functionOptions:
+#        match: "^[A-Z].*" # type: pascal ?
+#
+#  xgen-description:
+#    description: "Use this field to describe the action performed by each specific API endpoint or property, to provide context for how to use it to the users of the API."
+#    message: "{{error}}."
+#    severity: error
+#    given: "#DescribableObjects"
+#    then:
+#      - field: "description"
+#        function: truthy
+#      - field: "description"
+#        function: pattern
+#        functionOptions:
+#          match: "/^[A-Z]/"
+#      - field: "description"
+#        function: pattern
+#        functionOptions:
+#          match: "\\.|\|$"
+#
+#  xgen-request-DELETE-no-body:
+#    description: "A 'DELETE' request MUST NOT accept a 'body` parameter. http://go/ipa/108"
+#    severity: error
+#    given: $.paths..delete.parameters..in
+#    then:
+#      function: pattern
+#      functionOptions:
+#        notMatch: "/^body$/"
+#
+#  xgen-docs-tags-alphabetical:
+#    message: "Tags should be defined in alphabetical order."
+#    description: "Many documentation tools show tags in the order they are defined, so defining them not in alphabetical order can look funny to API consumers."
+#    severity: error
+#    given: "$"
+#    then:
+#      field: "tags"
+#      function: alphabetical
+#      functionOptions:
+#        keyedBy: "name"
+#
+#  xgen-docs-tags:
+#    message: "{{error}}."
+#    description: "Tags help group logic into conceptual groups instead of making end-users dig through URLs or lists of operation names."
+#    severity: error
+#    given: "$"
+#    then:
+#      field: "tags"
+#      function: schema
+#      functionOptions:
+#        schema:
+#          type: "array"
+#          minItems: 1
+#
+#  xgen-docs-operation-tags:
+#    message: "Operation should have non-empty `tags` array."
+#    description:
+#     "Once tags are defined they should be references in the operation, otherwise they will not be doing anything."
+#    severity: error
+#    given: "#OperationObject"
+#    then:
+#      field: "tags"
+#      function: schema
+#      functionOptions:
+#        schema:
+#          type: "array"
+#          minItems: 1
+#
+#  xgen-docs-operationId-valid-in-url:
+#    message: "operationId must only contain URL friendly characters."
+#    description: "Most documentation tools use the operationId to produce URLs, so the characters used must be safe and legal when used in the URL."
+#    severity: error
+#    given: "#OperationObject"
+#    then:
+#      field: "operationId"
+#      function: pattern
+#      functionOptions:
+#        match: "^[A-Za-z0-9-._~:/?#\\[\\]@!\\$&'()*+,;=]*$"
+#
+#  xgen-docs-parameter-examples-or-schema:
+#    message: "No example or schema provided for {{property}}."
+#    description: "Without providing a well defined schema or example(s) an API consumer will have a hard time knowing how to interact with this API."
+#    severity: error
+#    given: "$.paths[*]..parameters[*]"
+#    then:
+#      function: schema
+#      functionOptions:
+#        schema:
+#          anyOf:
+#            - required: ["example"]
+#            - required: ["examples"]
+#            - required: ["schema"]
+#
+#  x-xgen-hidden-env-format:
+#    description: "Ensure x-xgen-hidden-env extension has the correct format. https://go/openapi-hidden-extension"
+#    severity: error
+#    given: "$..x-xgen-hidden-env"                    # Match anywhere in the document
+#    then:
+#      - field: envs
+#        function: truthy
+#      - field: envs
+#        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 'additionalServices', 'targetService', 'allowDocsDiff', and 'docsSource'."
+#    formats: ["oas3"]
+#    given: "$.paths[*][*].x-xgen-soa-migration"
+#    severity: error
+#    then:
+#      - field: targetService
+#        function: truthy
+#        message: "'targetService' must be provided."
+#      - field: allowDocsDiff
+#        function: pattern
+#        functionOptions:
+#          match: "^(true|false)$"
+#        message: "'allowDocsDiff' must be true or false."
+#      - field: docsSource
+#        function: truthy
+#        message: "'docsSource' must be provided."
+#      - field: additionalServices
+#        function: truthy
+#        message: "'additionalServices' must be provided."
+#      - field: additionalServices
+#        function: pattern
+#        functionOptions:
+#          match: "^(mms)$"
+#        message: "'additionalServices' must be 'mms' as no other services are supported."
+#
+#  no-slash-before-custom-method:
+#    description: "Custom methods (e.g., ':applyItem') should not be preceded by a '/'."
+#    message: "The path '{{path}}' contains a '/' before a custom method. Custom methods should not start with a '/'."
+#    severity: error
+#    given: "$.paths"
+#    then:
+#      field: "@key"
+#      function: pattern
+#      functionOptions:
+#        notMatch: "/[^/]+/:[a-zA-Z]+$"
 
 overrides:
   - files: # load sample data has an issue with different path param names for different VERBS