LCORE-1958: Add Spectral OpenAPI linting (verify + CI)

Add .spectral.yaml, make lint-openapi (optional npx locally), wire into verify,
GitHub workflow to regenerate-check docs/openapi.json and run Spectral, and
CONTRIBUTING prerequisites for Node. Extend contributing doc with Spectral
section.

Author: syedriko

.github/workflows/openapi_spectral.yaml

@@ -0,0 +1,42 @@
+# OpenAPI: regenerate check (Spectral + committed docs/openapi.json drift).
+# - scripts/generate_openapi_schema.py builds the spec from FastAPI (app.main).
+# - CI fails if docs/openapi.json does not match generator output (run locally:
+#   uv run scripts/generate_openapi_schema.py docs/openapi.json).
+name: OpenAPI (Spectral)
+
+on:
+  - push
+  - pull_request
+
+jobs:
+  spectral:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: read
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          python-version: "3.12"
+      - name: Install dependencies
+        # Same pattern as local dev (CONTRIBUTING.md): dev + llslibdev for a full app import.
+        run: uv sync --group dev --group llslibdev
+      - name: Install PDM
+        # scripts/generate_openapi_schema.py asserts OpenAPI info.version matches `pdm show --version`.
+        run: uv pip install pdm
+      - name: Verify docs/openapi.json matches generator
+        run: |
+          set -euo pipefail
+          uv run python scripts/generate_openapi_schema.py /tmp/openapi-generated.json
+          if ! diff -u docs/openapi.json /tmp/openapi-generated.json; then
+            echo "::error::docs/openapi.json is out of date. Regenerate with: uv run scripts/generate_openapi_schema.py docs/openapi.json"
+            exit 1
+          fi
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+      - name: Spectral lint
+        run: npx --yes @stoplight/spectral-cli@6 lint docs/openapi.json --fail-severity error --display-only-failures

.spectral.yaml

@@ -0,0 +1,9 @@
+# Spectral (OpenAPI) — https://meta.stoplight.io/docs/spectral/
+#
+# Full Stoplight OAS ruleset. `oas3-valid-media-example` is off: examples in
+# docs/openapi.json are often partial and produced ~600 warnings with little
+# signal until examples are aligned with schemas. Re-enable when tightening
+# examples (set to "warn" or "error").
+extends: spectral:oas
+rules:
+  oas3-valid-media-example: off

CONTRIBUTING.md

@@ -18,6 +18,7 @@
     * [Pre-commit hook settings](#pre-commit-hook-settings)
 * [Code coverage measurement](#code-coverage-measurement)
 * [Linters](#linters)
+    * [OpenAPI (Spectral)](#openapi-spectral)
     * [Type hints checks](#type-hints-checks)
     * [Ruff](#ruff)
     * [Pylint](#pylint)
@@ -48,6 +49,7 @@
 - git
 - Python 3.12 or 3.13
 - pip
+- **Node.js** (18 or newer; **npm** and **`npx`** ship with Node). **`make verify`** runs **`lint-openapi`**, which calls **`npx --yes @stoplight/spectral-cli@6`** (see `Makefile`). If **`npx`** is not installed, **`lint-openapi` is skipped** with a message so **`make verify` still succeeds** locally; install Node to run the OpenAPI check. **CI** always runs Spectral (see `.github/workflows/openapi_spectral.yaml`).
 
 The development requires at least [Python 3.12](https://docs.python.org/3/whatsnew/3.12.html) due to significant improvement on performance, optimizations which benefit modern ML, AI, LLM, NL stacks, and improved asynchronous processing capabilities. It is also possible to use Python 3.13.
 
@@ -57,6 +59,7 @@ The development requires at least [Python 3.12](https://docs.python.org/3/whatsn
 
 1. `pip install --user uv`
 1. `uv --version` -- should return no error
+1. Install [Node.js](https://nodejs.org/en/download) (LTS is fine) or use your OS package manager, e.g. Fedora: `sudo dnf install nodejs`, macOS with [Homebrew](https://brew.sh/): `brew install node`. Confirm `node --version` and `npx --version` work. CI uses Node 22 for Spectral (see `.github/workflows/openapi_spectral.yaml`).
 
 
 
@@ -217,6 +220,10 @@ Code coverage reports are generated in JSON and also in format compatible with [
 
 _Black_, _Ruff_, Pyright, _Pylint_, __Pydocstyle__, __Mypy__, and __Bandit__ tools are used as linters. There are a bunch of linter rules enabled for this repository. All of them are specified in `pyproject.toml`, such as in sections `[tool.ruff]` and `[tool.pylint."MESSAGES CONTROL"]`. Some specific rules can be disabled using `ignore` parameter (empty now).
 
+### OpenAPI (Spectral)
+
+OpenAPI is linted with [Spectral](https://stoplight.io/open-api/) via **`npx --yes @stoplight/spectral-cli@6`** in the **`lint-openapi`** target (`make lint-openapi`, part of **`make verify`**). If **`npx`** is missing, **`lint-openapi`** skips Spectral locally; install **Node.js** to run it (see [Prerequisites](#prerequisites) and [Tooling installation](#tooling-installation)). **CI** always runs the Spectral step. If you introduce a **new** router tag (`APIRouter(tags=[...])`), you must also extend the global tag list in `src/app/main.py` and regenerate `docs/openapi.json`. See **[docs/contributing/openapi-tags-and-spectral.md](docs/contributing/openapi-tags-and-spectral.md)**.
+
 
 ### Type hints checks
 

Makefile

@@ -113,13 +113,21 @@ docstyle:	## Check the docstring style using Docstyle checker
 ruff:	## Check source code using Ruff linter
 	uv run ruff check src tests --per-file-ignores=tests/*:S101 --per-file-ignores=scripts/*:S101
 
+lint-openapi: ## Lint docs/openapi.json (Spectral OAS ruleset; fail on error)
+	@if command -v npx >/dev/null 2>&1; then \
+		npx --yes @stoplight/spectral-cli@6 lint docs/openapi.json --fail-severity error --display-only-failures; \
+	else \
+		echo "lint-openapi: skipping Spectral (npx not found). Install Node.js for OpenAPI lint locally; CI still runs it."; \
+	fi
+
 verify:	## Run all linters
 	$(MAKE) black
 	$(MAKE) pylint
 	$(MAKE) pyright
 	$(MAKE) ruff
 	$(MAKE) docstyle
 	$(MAKE) check-types
+	$(MAKE) lint-openapi
 
 distribution-archives:	## Generate distribution archives to be uploaded into Python registry
 	rm -rf dist

docs/contributing/openapi-tags-and-spectral.md

@@ -13,3 +13,15 @@ The schema generator **`scripts/generate_openapi_schema.py`** passes **`tags=app
 ```bash
 uv run scripts/generate_openapi_schema.py docs/openapi.json
 ```
+
+## Linting (`make lint-openapi`)
+
+Spectral is configured in **`.spectral.yaml`** (extends `spectral:oas`). Run:
+
+```bash
+make lint-openapi
+```
+
+This is part of **`make verify`**. If **`npx`** is not on your **`PATH`**, the Makefile **skips** Spectral and prints a short message so **`make verify`** can still pass; install Node.js to run the check locally. **CI** (`.github/workflows/openapi_spectral.yaml`) always runs Spectral. Failures are driven by **error**-severity rules.
+
+The rule **`oas3-valid-media-example`** (examples must match schemas) is **turned off** in **`.spectral.yaml`** because the generated spec carries many partial examples and produced hundreds of noisy warnings. Turn it back on when examples are brought in line with schemas.