HYPERFLEET-1024 - fix: address code review findings

- Guard empty version extraction in CI and release workflows
- Add semver-aware version comparison to reject downgrades
- Use env vars for step outputs in release workflow (script injection)
- Pin spectral-cli version in CI
- Fix CHANGELOG: correct Node.js runtime reference, RFC 9457
- Add language specifier to fenced code block in README
- Add linting docs to CONTRIBUTING.md and CLAUDE.md
- Add pipeline overview diagram for sprint presentation

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: mliptak0

.github/workflows/ci.yml

@@ -51,13 +51,21 @@ jobs:
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         run: |
           CURRENT=$(grep -oP '(?<=version: ")[^"]+' main.tsp)
+          if [ -z "$CURRENT" ]; then
+            echo "::error::Failed to extract version from main.tsp — check the @info decorator format" >&2
+            exit 1
+          fi
           LATEST=$(gh release list --limit 1 --json tagName --jq '.[0].tagName' 2>/dev/null | sed 's/^v//' || echo "")
           if [ -z "$LATEST" ]; then
             echo "No previous releases found — version check skipped"
             exit 0
           fi
+          HIGHEST=$(printf '%s\n%s\n' "$CURRENT" "$LATEST" | sort -V | tail -1)
           if [ "$CURRENT" = "$LATEST" ]; then
-            echo "Version '$CURRENT' matches latest release tag 'v$LATEST' — bump the version in main.tsp before merging."
+            echo "::error::Version '$CURRENT' matches latest release tag 'v$LATEST' — bump the version in main.tsp before merging."
+            exit 1
+          elif [ "$HIGHEST" != "$CURRENT" ]; then
+            echo "::error::Version '$CURRENT' is lower than latest release 'v$LATEST' — version in main.tsp must be strictly greater."
             exit 1
           fi
           echo "Version bump OK: $LATEST → $CURRENT"

.github/workflows/release.yml

@@ -29,6 +29,10 @@ jobs:
         id: version
         run: |
           VERSION=$(grep -oP '(?<=version: ")[^"]+' main.tsp)
+          if [ -z "$VERSION" ]; then
+            echo "::error::Failed to extract version from main.tsp — check the @info decorator format" >&2
+            exit 1
+          fi
           echo "version=$VERSION" >> "$GITHUB_OUTPUT"
           echo "tag=v$VERSION" >> "$GITHUB_OUTPUT"
 

CHANGELOG.md

@@ -18,7 +18,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Changed
 
 - Release workflow now triggers automatically on push to main instead of requiring a manual tag push; auto-creates annotated tag from version in `main.tsp` and attaches all four schema artifacts (`core-openapi.yaml`, `core-swagger.yaml`, `gcp-openapi.yaml`, `gcp-swagger.yaml`)
-- Bumped `actions/checkout` and `actions/setup-node` to v6 (Node.js 24 runtime)
+- Bumped `actions/checkout` and `actions/setup-node` to v6
 
 ### Fixed
 

CLAUDE.md

@@ -199,6 +199,7 @@ Before submitting changes:
 - [ ] Core Swagger builds: `./build-schema.sh core --swagger`
 - [ ] Schema files generated: `ls schemas/*/openapi.yaml`
 - [ ] No TypeSpec compilation errors (check output)
+- [ ] Schemas pass linting: `spectral lint schemas/core/openapi.yaml schemas/gcp/openapi.yaml`
 - [ ] Changes committed including schema updates
 - [ ] PR description references related issue
 

CONTRIBUTING.md

@@ -79,6 +79,22 @@ npm run build:gcp:swagger
 npm run build:all
 ```
 
+### Linting Schemas
+
+CI automatically lints OpenAPI schemas using a pinned version of [Spectral](https://github.com/stoplightio/spectral) installed locally in the workflow. For local linting during development, install Spectral globally:
+
+```bash
+npm install -g @stoplight/spectral-cli
+```
+
+Then lint the generated schemas:
+
+```bash
+spectral lint schemas/core/openapi.yaml schemas/gcp/openapi.yaml
+```
+
+The `.spectral.yaml` config at the repo root applies the `spectral:oas` ruleset.
+
 ### Validating Output
 
 After building, verify the generated schemas:

README.md

@@ -362,7 +362,7 @@ go get github.com/openshift-hyperfleet/hyperfleet-api-spec@v1.0.12
 
 To test locally against an unreleased branch, use a `replace` directive in your `go.mod`:
 
-```
+```go
 replace github.com/openshift-hyperfleet/hyperfleet-api-spec => /path/to/local/hyperfleet-api-spec
 ```