feat(spectral): introduce severity overrides and handle pygeoapi

- add overrideSeverity ruleset function and connect a pygeoapi-specific override rule
- add may-have-info-x-api-type rule with docs/examples and clearer downgrade messaging
- switch jest to swc-backed ts testing and align tsconfig and build outputs
- switch jest config to CommonJS/node16 to allow proper imports

Author: milkshakeuk

.gitignore

@@ -3,4 +3,4 @@
 .cache
 coverage/
 node_modules/
-dist/
+dist/

.swcrc

@@ -0,0 +1,7 @@
+{
+  "jsc": {
+    "parser": {
+      "syntax": "typescript"
+    }
+  }
+}

docs/spectral-rules/index.md

@@ -15,25 +15,67 @@ As well as the rules described herein, the UKHSA ruleset includes the [recommend
 
 Where rules been adopted from from existing open source API rulesets a link is supplied on the relevant rule page.
 
+## Pygeoapi severity overrides
+
+Some definitions (for example, produced by pygeoapi) cannot yet meet every **MUST** requirement in the ruleset. When an OpenAPI document is marked with `info.x-api-type: pygeoapi`, the ruleset automatically downgrades the following error-level rules to `warn`:
+
+- `must-define-a-format-for-integer-types`
+- `must-define-a-format-for-number-types`
+- `must-define-security-schemes`
+- `must-have-info-api-audience`
+- `must-have-info-contact-email`
+- `must-have-info-value-chain`
+- `must-have-info-version`
+- `must-specify-default-response`
+- `must-use-camel-case-for-property-names`
+- `must-use-camel-case-for-query-parameters`
+- `must-use-https-protocol-only`
+- `must-use-problem-json-as-default-response`
+- `must-use-problem-json-for-errors`
+- `must-use-valid-version-info-schema`
+
+Other rules continue to run normally, so pygeoapi definitions should still be linted and improved where possible. Rules already at `warn` are not changed.
+
+### `info.x-api-type` values
+
+To make intent explicit, the `info.x-api-type` field can be treated as an enum in API definitions to indicate the API category:
+
+- `standard` – default behavior; no overrides applied.
+- `pygeoapi` – pygeoapi-based definitions; error-level rules listed above are downgraded to `warn`.
+
+If you omit `info.x-api-type`, the ruleset assumes the API is `standard`.
+
+See also: [MAY have info.x-api-type][6].
+
+When generating a definition from a local pygeoapi instance, you can inject the `info.x-api-type` flag during export so relaxed severities will be applied. The example below wraps the `pygeoapi openapi generate` command in Docker, binds your local configuration, and uses `yq` to add `info.x-api-type: pygeoapi` before writing the result to `openapi-pygeoapi.yml`.
+
+```sh
+docker run --entrypoint= --rm -p 5000:80 \
+  --mount type=bind,src=./pygeoapi-config.yml,dst=/pygeoapi/config.yml \
+  -e PYGEOAPI_CONFIG=/pygeoapi/config.yml geopython/pygeoapi:latest \
+  sh -c 'pygeoapi openapi generate $PYGEOAPI_CONFIG'  \
+| yq '.info += {"x-api-type": "pygeoapi"}' - > openapi-pygeoapi.yml
+```
+
 ## How to use the rules
 
 ### Install Spectral
 
-[Spectral][6] is a flexible JSON/YAML linter for creating automated style guides, with baked in support for OpenAPI (v3.1, v3.0, and v2.0), Arazzo v1.0, as well as AsyncAPI v2.x.
+[Spectral][7] is a flexible JSON/YAML linter for creating automated style guides, with baked in support for OpenAPI (v3.1, v3.0, and v2.0), Arazzo v1.0, as well as AsyncAPI v2.x.
 
 Install Spectral globally or as a dev dependency.
 
 ```sh
 npm install @stoplight/spectral-cli --save-dev
 ```
 
-Read the [official spectral documentation][7] for more installation options.
+Read the [official spectral documentation][8] for more installation options.
 
 ### Run Spectral against your OpenAPI definition
 
 Run Spectral against your OpenAPI definition, referencing the spectral ruleset.
 
-You must install the ruleset as via [npm package][8] and then reference that, bear in mind the UKHSA ruleset npm package is hosted in github so please read Github's documentation [Installing a GitHub npm package][9].
+You must install the ruleset as via [npm package][9] and then reference that, bear in mind the UKHSA ruleset npm package is hosted in github so please read Github's documentation [Installing a GitHub npm package][10].
 
 ```sh
 npm install @ukhsa-collaboration/spectral-rules --save-dev
@@ -104,7 +146,7 @@ jobs:
           # npx spectral lint "@(openapi|swagger|*api)*.{json,yml,yaml}" -r ${{ GITHUB.WORKSPACE }}/node_modules/@ukhsa-collaboration/spectral-rules/.spectral.yaml -f github-actions
 ```
 
-The above example uses [glob syntax][10] to target only OpenAPI specification files.
+The above example uses [glob syntax][11] to target only OpenAPI specification files.
 
 The glob pattern `@(openapi|swagger|*api)*.{json,yml,yaml}` matches:
 
@@ -125,21 +167,22 @@ The global pattern does not match:
 
 | Tool | Description |
 | - | - |
-| [VS Code Extension][11] | Official spectral VS Code extension provides real time linting / intellisense on your OpenAPI definition. |
-| [Github Action][12] | Official spectral Github action provides ability to lint your OpenAPI definition in CI/CD workflows. |
+| [VS Code Extension][12] | Official spectral VS Code extension provides real time linting / intellisense on your OpenAPI definition. |
+| [Github Action][13] | Official spectral Github action provides ability to lint your OpenAPI definition in CI/CD workflows. |
 
-Read the [official spectral documentation][13] for more development workflows.
+Read the [official spectral documentation][14] for more development workflows.
 
 [1]: ../api-guidelines/index.md
 [2]: https://docs.stoplight.io/docs/spectral/0a73453054745-recommended-or-all
 [3]: https://docs.stoplight.io/docs/spectral/4dec24461f3af-open-api-rules
 [4]: https://github.com/stoplightio/spectral-documentation
 [5]: https://swagger.io/specification/
-[6]: https://docs.stoplight.io/docs/spectral
-[7]: https://docs.stoplight.io/docs/spectral/b8391e051b7d8-installation
-[8]: https://meta.stoplight.io/docs/spectral/7895ff1196448-sharing-and-distributing-rulesets#npm
-[9]: https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-npm-registry#installing-a-package
-[10]: https://github.com/mrmlnc/fast-glob
-[11]: https://marketplace.visualstudio.com/items?itemName=stoplight.spectral
-[12]: https://github.com/marketplace/actions/spectral-linting
-[13]: https://docs.stoplight.io/docs/spectral/ecaa0fd8a950d-workflows
+[6]: may/may-have-info-x-api-type.md
+[7]: https://docs.stoplight.io/docs/spectral
+[8]: https://docs.stoplight.io/docs/spectral/b8391e051b7d8-installation
+[9]: https://meta.stoplight.io/docs/spectral/7895ff1196448-sharing-and-distributing-rulesets#npm
+[10]: https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-npm-registry#installing-a-package
+[11]: https://github.com/mrmlnc/fast-glob
+[12]: https://marketplace.visualstudio.com/items?itemName=stoplight.spectral
+[13]: https://github.com/marketplace/actions/spectral-linting
+[14]: https://docs.stoplight.io/docs/spectral/ecaa0fd8a950d-workflows

docs/spectral-rules/may/index.md

@@ -0,0 +1,10 @@
+---
+includeInBreadcrumbs: true
+eleventyNavigation:
+  parent: spectral-rules
+  key: may
+---
+
+# MAY
+
+Spectral rules categorised as **MAY** highlight optional practices. They can be adopted when they add value or context, and teams should weigh them based on preference, consumer needs, or implementation constraints.

docs/spectral-rules/may/may-have-info-x-api-type.md

@@ -0,0 +1,33 @@
+# **MAY** have info.x-api-type
+
+APIs **MAY** include an `info.x-api-type` field to indicate the API category. When present, the value **MUST** be either `standard` or `pygeoapi`. If the field is omitted, the ruleset assumes the API is `standard`.
+
+> [!IMPORTANT]
+> Using `info.x-api-type: pygeoapi` signals pygeoapi-based definitions and enables conditional severity downgrades for certain rules. See [1].
+
+## Valid Examples
+
+```yaml
+info:
+  title: Test Results API
+  version: 1.0.0
+  x-api-type: standard
+```
+
+```yaml
+info:
+  title: Geospatial API
+  version: 1.0.0
+  x-api-type: pygeoapi
+```
+
+## Invalid Example
+
+```yaml
+info:
+  title: Something
+  version: 1.0.0
+  x-api-type: experimental-non-pygeoapi
+```
+
+[1]: ../index.md#pygeoapi-severity-overrides

docs/spectral-rules/may/may.11tydata.json

@@ -0,0 +1,5 @@
+{
+  "sectionKey": "spectral-rules",
+  "layout": "sub-navigation",
+  "caption": "MAY"
+}

docs/spectral-rules/must/must-define-a-format-for-integer-types.md

@@ -2,6 +2,9 @@
 
 `integer` properties **MUST** have a format defined (`int32`, `int64`, or `bigint`).
 
+> [!IMPORTANT]
+> For openapi definitions marked with `info.x-api-type: pygeoapi`, this rule’s severity is automatically set to `warn` by the `override-severity-pygeoapi` rule. See [1].
+
 ## Invalid Example
 
 ```yaml
@@ -29,6 +32,7 @@ requestBody:
             format: int32
 ```
 
-[Zalando Guideline 171][1]
+[Zalando Guideline 171][2]
 
-[1]: https://opensource.zalando.com/restful-api-guidelines/#171
+[1]: ../index.md#pygeoapi-severity-overrides
+[2]: https://opensource.zalando.com/restful-api-guidelines/#171

docs/spectral-rules/must/must-define-a-format-for-number-types.md

@@ -2,6 +2,9 @@
 
 `number` properties **MUST** have a format defined (`float`, `double`, or `decimal`).
 
+> [!IMPORTANT]
+> For openapi definitions marked with `info.x-api-type: pygeoapi`, this rule’s severity is automatically set to `warn` by the `override-severity-pygeoapi` rule. See [1].
+
 ## Invalid Example
 
 ```yaml
@@ -29,6 +32,7 @@ requestBody:
             format: float
 ```
 
-[Zalando Guideline 171][1]
+[Zalando Guideline 171][2]
 
-[1]: https://opensource.zalando.com/restful-api-guidelines/#171
+[1]: ../index.md#pygeoapi-severity-overrides
+[2]: https://opensource.zalando.com/restful-api-guidelines/#171

docs/spectral-rules/must/must-define-security-schemes.md

@@ -2,6 +2,9 @@
 
 All APIs **MUST** have a security scheme defined.
 
+> [!IMPORTANT]
+> For openapi definitions marked with `info.x-api-type: pygeoapi`, this rule’s severity is automatically set to `warn` by the `override-severity-pygeoapi` rule. See [1].
+
 If an API doesn't have a security scheme defined, it means the entire API is open to the public. That's probably not what you want, even if all the data is read-only. Setting lower rate limits for the public and letting known consumers use more resources is a handy path to monetization, and helps know who your power users are when changes need feedback or migration, even if not just good practice.
 
 ## Valid Example
@@ -22,6 +25,7 @@ components:
             tests:write: submit test results
 ```
 
-[UKHSA Guidelines Security][1]
+[UKHSA Guidelines Security][2]
 
-[1]: ../../api-guidelines/security.md#authentication
+[1]: ../index.md#pygeoapi-severity-overrides
+[2]: ../../api-guidelines/security.md#authentication

docs/spectral-rules/must/must-have-info-api-audience.md

@@ -2,6 +2,9 @@
 
 The `info` object **MUST** have an `x-audience` that matches at least one of these values:
 
+> [!IMPORTANT]
+> For openapi definitions marked with `info.x-api-type: pygeoapi`, this rule’s severity is automatically set to `warn` by the `override-severity-pygeoapi` rule. See [1].
+
 | audience | Use case |
 | - | - |
 | `company-internal` | for internal use only with UKHSA |
@@ -16,3 +19,5 @@ info:
   title: Test Results Api
   x-audience: public-external
 ```
+
+[1]: ../index.md#pygeoapi-severity-overrides