mirror of
https://github.com/Sea-Haven-Industries/procurement-ingest.git
synced 2026-09-30 15:23:13 +00:00
b89e98a879
Some checks are pending
Deploy / deploy (push) Waiting to run
* feat(api): Add @redocly/cli as a dev dependency
Signed-off-by: Adam Moussa <adam@seahavenind.com>
* feat(api): Add Redocly configuration file with custom rules
Signed-off-by: Adam Moussa <adam@seahavenind.com>
* chore(api): Redocly lint config + bring openapi.json into compliance
redocly.yaml from the Redocly guidelines builder, with three generated
rules corrected: response-contains-property had the status codes as the
required body fields (intent was the Error schema's top-level 'error';
403 exempt since API Gateway emits AWS's {message} shape, 501 not 503);
operation-4xx-problem-details-rfc7807 off (adopting RFC 7807 would be a
runtime + SHOC-contract change, decided against); the two inert casing
rules (parameter names, schema properties) removed because both name
sets are contract-pinned (gateway resource paths, DynamoDB items).
Spec changes, no runtime impact: operationIds renamed to method-prefixed
kebab-case (get-work-orders, post-work-order-comment, ...); tags added to
all 15 operations + root tags object (groups the Redoc sidebar); examples
on all six parameters; license field; server description punctuation; two
descriptions reworded to start capitalized. Real linter catches fixed:
the two x-planned ops were missing their {workOrderId} path parameter
and any 4xx response (403 added - true today, gateway rejects unsigned).
.redocly.lint-ignore.yaml pins the six deliberate exceptions: webhook
keys are the shipped SHOC contract event names (not renameable), and the
x-planned ops answer only 501 (no 2xx to document).
package.json: npm run lint:api. Verified: lint 0 errors, 675 pytest,
headless-Chrome render of the tagged docs page.
* feat(api): SHOC design-system theme for /docs (vendored fonts)
Themes the Redoc page with the canonical SHOC token set: Montserrat 600
headings / DM Sans body / JetBrains Mono code, primary #1c75bc, navy
#262262 sidebar text + right panel, #f9fafb background, 244px sidebar.
sortRequiredPropsFirst on; 200 responses pre-expanded.
Fonts ship as lambdas/api/fonts.css (latin woff2 subsets from
@fontsource 5.3.0, embedded as data URIs, ~90KB) and inline via a new
__FONTS_CSS__ placeholder with the same </style breakout guard --
the offline single-response invariant holds, nothing fetches Google
Fonts (test-pinned). Bundling cp + bundle-consistency pin + spec-drift
asset checks extended.
Verified: headless-Chrome render (theme + fonts applied), ruff, 675
pytest, cdk synth + staged-asset check.
* feat(api): SHOC gradient topbar on /docs
64px fixed header with the SHOC shell gradient token (#1b1f52 ->
#1c4f8f -> #1c75bc), Sea Haven wordmark in Montserrat 600, page name
right-aligned in DM Sans. Redoc's scrollYOffset: 64 keeps the sticky
sidebar and anchor scrolling clear of the fixed bar. Verified via
headless-Chrome render.
* style(api): normalize /docs header and right-panel blues
The right panel's #262262 is a purple-leaning navy that clashed with
the cyan-leaning gradient, and the bar's brightest point sat directly
over the dark panel. Right panel now uses #1b1f52 (the gradient's own
dark endpoint) and the gradient runs bright-to-dark so its dark end
lands flush on the panel -- no seam, one blue family. Verified via
headless-Chrome render.
* style(api): right-panel gradient on /docs via bundle-pinned override
Redoc's theme only takes solid colors (it derives shades from
rightPanel.backgroundColor), so the gradient (#1b3d79 -> #1b3068 ->
#1b1f52, continuing the topbar blend) rides as a CSS override on the
styled-components classes of the per-section right-panel divs
(.sc-iGgWBj.sc-gsFSXq + the .sc-dExYaf stub). Those names are
deterministic for the vendored 2.5.3 bundle (verified across loads) but
change on any Redoc bump: re-derive via headless probe (find elements
whose computed background equals the rightPanel color). If they stop
matching, the panel falls back to the solid #1b1f52 theme color --
cosmetic only. Verified via headless-Chrome render.
* feat(api): collapsible samples column on /docs
Redoc CE has no built-in panel toggle, so the topbar gains a Hide/Show
samples button that flips .samples-collapsed on <html>: the right-panel
divs hide (same bundle-pinned styled-components classes as the gradient
override) and each section's content half takes the full width. Choice
persists in localStorage; aria-pressed tracks state. If the pinned
classes stop matching after a Redoc bump the toggle goes inert --
cosmetic only. Both states verified via headless-Chrome render.
* ci(api): spec-lint CI gate + npm Dependabot coverage
New spec-lint job mirrors the local npm run lint:api so openapi.json
cannot drift from redocly.yaml with green CI. Dependabot gains the npm
ecosystem (package.json is new; nothing watched @redocly/cli).
* feat(api): docs finishing touches - x-tagGroups, favicon, docs:preview
x-tagGroups sections the Redoc sidebar (Read API / Meta / SHOC Feed);
inline data-URI SVG favicon (SHOC blue) stops the browser's follow-up
/favicon.ico request 403ing at the gateway; npm run docs:preview wraps
the real-handler local render (scripts/preview_docs.py); README gains a
docs-page architecture section covering the inline pattern, theme,
pinned-selector caveat, and tooling. Lint 0 errors, 675 pytest,
headless render verified.
---------
Signed-off-by: Adam Moussa <adam@seahavenind.com>
122 lines
3.3 KiB
YAML
122 lines
3.3 KiB
YAML
extends:
|
|
- recommended
|
|
rules:
|
|
# Proprietary internal license -- no SPDX identifier or public URL exists.
|
|
info-license-strict: off
|
|
rule/info-title-api:
|
|
subject:
|
|
type: Info
|
|
property: title
|
|
assertions:
|
|
pattern: /.*API.*/
|
|
rule/info-description:
|
|
subject:
|
|
type: Info
|
|
property: description
|
|
assertions:
|
|
defined: true
|
|
operation-4xx-response: error
|
|
# Off: the live contract is {"error": string} as plain application/json
|
|
# (serialization.py error_response). Adopting RFC 7807 would be a runtime
|
|
# + SHOC-contract change, decided against 2026-07-24.
|
|
operation-4xx-problem-details-rfc7807: off
|
|
operation-operationId: error
|
|
rule/operationId-casing:
|
|
subject:
|
|
type: Operation
|
|
property: operationId
|
|
assertions:
|
|
casing: kebab-case
|
|
rule/operationId-prefix:
|
|
subject:
|
|
type: Operation
|
|
property: operationId
|
|
assertions:
|
|
pattern: /^GET|PUT|POST|DELETE|OPTIONS|HEAD|PATCH|TRACE/i
|
|
rule/operation-summary-period:
|
|
subject:
|
|
type: Operation
|
|
property: summary
|
|
assertions:
|
|
pattern: /[^.]$/
|
|
path-not-include-query: error
|
|
# No parameter-casing rule: path parameter names (workOrderId, poNumber,
|
|
# siteCode) are camelCase by contract -- they are baked into the API Gateway
|
|
# resource paths and read by the handler's pathParameters lookup.
|
|
rule/params-must-include-examples:
|
|
severity: error
|
|
subject:
|
|
type: Parameter
|
|
assertions:
|
|
requireAny:
|
|
- example
|
|
- examples
|
|
no-http-verbs-in-paths: error
|
|
no-ambiguous-paths: error
|
|
path-segment-plural:
|
|
severity: error
|
|
exceptions:
|
|
- docs
|
|
- openapi.json
|
|
paths-kebab-case: error
|
|
no-invalid-schema-examples: error
|
|
# No schema-properties casing rule: property names mirror the DynamoDB
|
|
# items and the shipped SHOC webhook contract -- snake_case for WO/PO
|
|
# tables, camelCase for verified-sites (legacy, issue #24). Not lintable
|
|
# to one casing without a contract break.
|
|
# Error bodies must carry the top-level "error" field (the Error schema).
|
|
# 403 is exempt: it is emitted by API Gateway's SigV4 layer with AWS's
|
|
# {"message"} shape, not by the Lambda.
|
|
response-contains-property:
|
|
severity: error
|
|
names:
|
|
'400':
|
|
- error
|
|
'401':
|
|
- error
|
|
'404':
|
|
- error
|
|
'501':
|
|
- error
|
|
request-mime-type:
|
|
severity: error
|
|
allowedValues:
|
|
- application/json
|
|
response-mime-type:
|
|
severity: error
|
|
allowedValues:
|
|
- application/json
|
|
- text/html
|
|
no-server-example.com: error
|
|
rule/no-server-localhost:
|
|
subject:
|
|
type: Server
|
|
property: url
|
|
assertions:
|
|
notPattern: /(localhost|127.0.0.1)
|
|
operation-singular-tag: error
|
|
operation-tag-defined: error
|
|
rule/tag-description:
|
|
subject:
|
|
type: Tag
|
|
property: description
|
|
assertions:
|
|
defined: true
|
|
rule/description-capitalization:
|
|
subject:
|
|
type: any
|
|
property: description
|
|
assertions:
|
|
pattern: /^([A-Z]|true|seahaven-prod)/
|
|
rule/description-punctuation:
|
|
subject:
|
|
type: any
|
|
property: description
|
|
assertions:
|
|
pattern: /(\.|server)$/
|
|
rule/avoid-words-in-descriptions:
|
|
subject:
|
|
type: any
|
|
property: description
|
|
assertions:
|
|
notPattern: /(simply|easy|easily|just|obviously|notethat)/i
|