ci: add Spectral as a second lint gate - #129
LukasParke wants to merge 7 commits into
Conversation
- Remove duplicate inline X-Plex-* header parameters on the three universal transcode operations and /:/timeline (operation-parameters-unique), referencing the existing component parameters instead - Fix resolution pattern ^\d[x:]\d$ -> ^\d+[x:]\d+$ so real values like 1080x1080 validate (videoResolution/photoResolution) - Fix invalid examples: 'Burn' -> 'burn' (enum), string examples typed as numbers, array parameters with scalar examples, Guid.id multi-example map -> JSON Schema examples array, Policy.value type mismatch - Change /library/file url parameter format from non-standard 'url' to 'uri' - Remove unused components: Title, Type schemas and the 500 response redocly lint: 16 errors / 148 warnings -> 0 errors / 118 warnings
- Add pr_validation.yaml: Redocly lint (strict config in redocly.yaml, pre-existing violations baselined in .redocly.lint-ignore.yaml so the count can only shrink) plus an oasdiff breaking-change gate that fails unless the PR carries the 'breaking-change' label - Elevate operation-4xx-response, invalid-example, unused-component, and ambiguous-path rules to error severity for new violations - Fix sdk_generation.yaml paths filter: './plex-api-spec.yaml' never matched, so spec pushes did not trigger generation (masked by the cron)
…ject
/library/sections/{sectionId}/autocomplete, /common, and /firstCharacters
declared inline 'type' (and 'sort' on firstCharacters) query parameters
that the form/explode mediaQuery object parameter already serializes,
so the same query key was documented twice per operation. The mediaQuery
versions are also better typed: 'type' is the MediaType enum and 'sort'
is a string supporting modifiers like duration:desc (the inline 'sort'
was implausibly typed integer).
This also made oasdiff's parameter matching nondeterministic (phantom
breaking changes on identical specs), which would have broken the CI
breaking-change gate.
- Declare the Authentication, Users, and Plex tags used by the four plex.tv-hosted operations (/user, /users/signin, /users, /resources) and group them under a new 'Plex.tv' tag group (operation-tag-defined) - Add info.description and info.contact (info-description, info-contact) - Add .spectral.yaml: spectral:oas ruleset with oas3-operation-security-defined disabled, since this document is OpenAPI 3.1 where role names in security requirement arrays are legal for non-OAuth2 schemes and Spectral implements the 3.0 semantics
Evaluated vacuum, Spectral, and Scalar CLI against the spec: - Scalar: structural validation only, no lint rules; spec already passes - vacuum: fast, but default ruleset is ~1,400 findings of mostly inapplicable style noise (kebab-case paths, description-duplication) - Spectral: highest signal; caught undeclared tags and missing info fields that Redocly's recommended set does not cover Spectral joins Redocly in the lint job with --fail-severity=warn, so any warning fails. Redocly stays as the primary gate: it is the only tool with per-pointer ignore-file baselining, and it catches classes the others missed (duplicate parameters, invalid examples).
|
Important Review skippedAuto reviews are disabled on base/target branches other than the default branch. Please check the settings in the CodeRabbit UI or the ⚙️ Run configurationConfiguration used: Repository UI Review profile: ASSERTIVE Plan: Pro Plus Run ID: You can disable this status message by setting the Use the checkbox below for a quick retry:
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
fce5878 to
63028ef
Compare
|
Agent: Retired after rebasing onto the post-#117 main. The two spec issues Spectral caught (undeclared tags, missing info fields) were fixed by the regeneration, and validate.yml now runs Redocly + Speakeasy + vacuum. On the regenerated spec, Spectral's remaining output is 306 invalid-example errors (already reported by Redocly, pending a generator-side fix), 167 OpenAPI 3.1 false positives (oas3-operation-security-defined implements 3.0 semantics), and 2 trailing-slash warnings already ratcheted in redocly.yaml. A fourth linter whose every rule would need disabling to go green adds maintenance cost with no signal, so it stays out. |
1 participant
Stacked on #128. Evaluated three additional validation tools against the spec, per request; the winner joins CI.
Evaluation
document validate)paths-kebab-caseon paths Plex defines,description-duplication,camel-case-properties)spectral:oas)Spectral's real findings, fixed here:
operation-tag-defined: the four plex.tv-hosted operations (/user,/users/signin,/users,/resources) used tags (Authentication,Users,Plex) never declared in the globaltagslist. Now declared with descriptions and grouped under a new Plex.tv tag group.info-description/info-contact:infohad neither. Added a concise description (JSON-via-Acceptguidance, link to plexapi.dev) and a contact pointing at this repo.The 89 false positives are
oas3-operation-security-definedcomplaining aboutshared user/adminin security requirement arrays on thetokenapiKey scheme. That rule implements OpenAPI 3.0 semantics (array must be empty for non-OAuth2 schemes); this document is 3.1, where role names are explicitly allowed. Disabled in.spectral.yamlwith a comment.CI
Spectral runs in the existing lint job with
--fail-severity=warn(any warning fails). Verified locally: clean spec passes; an op with an undeclared tag fails with exit 1.Redocly stays as the primary gate rather than being replaced: it is the only tool of the four with per-pointer ignore-file baselining (the ratchet), and it caught whole classes the others missed (duplicate parameters, schema-invalid examples). Spectral covers the rule families Redocly's recommended set lacks. Both run in seconds.