docs(api): document filter parameter enums#4623
Merged
Merged
Conversation
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
koala73
force-pushed
the
codex/issue-4605-filter-enums
branch
from
July 1, 2026 21:22
f26b613 to
d38a93b
Compare
Contributor
Greptile SummaryThis PR documents OpenAPI filter parameter contracts by propagating proto enum/pattern definitions onto generated query parameter schemas across 53 files, fixing stale proto descriptions for BLS series IDs, HackerNews feed types, and tech event types.
Confidence Score: 4/5Safe to merge — changes are limited to generated documentation files, proto comments, and a new generation script; no runtime handler logic is touched. The change is well-scoped to docs/spec generation with thorough test coverage (155 passing tests). Two issues worth noting: the scripts/apply-openapi-filter-param-schemas.mjs — specifically the Important Files Changed
Flowchart%%{init: {'theme': 'neutral'}}%%
flowchart TD
A[proto definitions] -->|buf generate| B[src/generated stubs]
A -->|proto request schemas| C[collectTargets]
D[OPENAPI_FILTER_PARAM_SCHEMA_OVERRIDES] --> C
C --> E{per file}
E -->|.openapi.json| F[applyOpenApiFilterParamSchemas\nJSON object mutation\nJSON.stringify write]
E -->|.openapi.yaml| G[patchYamlText\nraw text patching\npreserves format]
F --> H[docs/api/*.openapi.json]
G --> I[docs/api/*.openapi.yaml]
I --> J[worldmonitor.openapi.yaml\nunified bundle]
H --> K[--check CI gate\nopenapi-filter-param-schemas.test.mjs]
J --> K
%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%%
flowchart TD
A[proto definitions] -->|buf generate| B[src/generated stubs]
A -->|proto request schemas| C[collectTargets]
D[OPENAPI_FILTER_PARAM_SCHEMA_OVERRIDES] --> C
C --> E{per file}
E -->|.openapi.json| F[applyOpenApiFilterParamSchemas\nJSON object mutation\nJSON.stringify write]
E -->|.openapi.yaml| G[patchYamlText\nraw text patching\npreserves format]
F --> H[docs/api/*.openapi.json]
G --> I[docs/api/*.openapi.yaml]
I --> J[worldmonitor.openapi.yaml\nunified bundle]
H --> K[--check CI gate\nopenapi-filter-param-schemas.test.mjs]
J --> K
Reviews (1): Last reviewed commit: "docs(api): document filter parameter enu..." | Re-trigger Greptile |
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
Comment on lines
+287
to
+296
| function processJsonFile(file, check) { | ||
| const before = readFileSync(file, 'utf8'); | ||
| const spec = JSON.parse(before); | ||
| applyOpenApiFilterParamSchemas(spec); | ||
| const after = JSON.stringify(spec); | ||
| if (before === after) return false; | ||
| if (check) return true; | ||
| writeFileSync(file, after); | ||
| return true; | ||
| } |
Contributor
There was a problem hiding this comment.
--check failures
JSON.stringify(spec) produces compact JSON with no trailing newline. The string comparison before === after therefore differs from the original whenever: (1) the file has a trailing newline (standard for text files), or (2) the file is pretty-printed. In both cases the --check gate would report every JSON file as "stale" and the write path would silently strip all formatting — even when no enum/pattern values actually changed. The YAML path avoids this by patching the raw text in-place; the JSON path should either use JSON.stringify(spec, null, 2) + '\n' to match a formatted baseline, or early-exit on the existing applyOpenApiFilterParamSchemas return value before the format-sensitive comparison.
koala73
force-pushed
the
codex/issue-4605-filter-enums
branch
from
July 1, 2026 21:29
d38a93b to
11a73c4
Compare
koala73
force-pushed
the
codex/issue-4605-filter-enums
branch
from
July 1, 2026 21:41
11a73c4 to
598423a
Compare
Contributor
|
Preview deployment for your docs. Learn more about Mintlify Previews.
💡 Tip: Enable Workflows to automatically generate PRs for you. |
koala73
added a commit
that referenced
this pull request
Jul 2, 2026
The per-service YAML specs (docs/api/*Service.openapi.yaml) and the served bundle (worldmonitor.openapi.yaml → public/openapi.yaml) carried only the entitlement 403s from the injector chain — never the auth half the per-service JSON specs already have. PR #4602 deferred per-op YAML auth surgery, and the sibling injectors (#4621/#4623/#4625/#4626) that later reached the YAML never backfilled it. This generalizes the bundle-only top-level insertion into a reusable injectYamlAuthContract() applied to BOTH the per-service YAML loop and the bundle, reaching full parity with injectJson(): - top-level securitySchemes (2 API-key, or 3 incl. BearerAuth when the artifact has a bearer-capable op — mirrors expectedSchemesForSpec) - root API-key security requirement - UnauthorizedError schema - per-operation 401 on authenticated ops (185), security:[] opt-outs on the 7 public RPCs, and BearerAuth stamping on the ~19 entitlement/premium ops Reuses the entitlement pass's YAML range-finders; js-yaml is used read-only to enumerate operation paths (handling the one multi-method path, /api/v2/shipping/webhooks); all writes stay formatting-preserving and additions-only. The narrower injectBundle() is removed. Scope note: widened from the plan's bundle-only DoD to all 34 per-service YAML after discovering they shared the identical gap (confirmed with the user). Verified: 401 parity 185 (per-service YAML) / 185 (bundle); idempotent (full Makefile injector chain re-run = 0 drift); per-service JSON byte-unchanged; 395 contract tests pass (incl. mcp-api-parity, doc-parity, deploy-config). Claude-Session: https://claude.ai/code/session_01EsjtheWqt8GxEZfd3DyTMu
koala73
added a commit
that referenced
this pull request
Jul 3, 2026
…e + per-service parity (#4650) (#4654) * fix(api): extend OpenAPI auth injection to all YAML artifacts (#4650) The per-service YAML specs (docs/api/*Service.openapi.yaml) and the served bundle (worldmonitor.openapi.yaml → public/openapi.yaml) carried only the entitlement 403s from the injector chain — never the auth half the per-service JSON specs already have. PR #4602 deferred per-op YAML auth surgery, and the sibling injectors (#4621/#4623/#4625/#4626) that later reached the YAML never backfilled it. This generalizes the bundle-only top-level insertion into a reusable injectYamlAuthContract() applied to BOTH the per-service YAML loop and the bundle, reaching full parity with injectJson(): - top-level securitySchemes (2 API-key, or 3 incl. BearerAuth when the artifact has a bearer-capable op — mirrors expectedSchemesForSpec) - root API-key security requirement - UnauthorizedError schema - per-operation 401 on authenticated ops (185), security:[] opt-outs on the 7 public RPCs, and BearerAuth stamping on the ~19 entitlement/premium ops Reuses the entitlement pass's YAML range-finders; js-yaml is used read-only to enumerate operation paths (handling the one multi-method path, /api/v2/shipping/webhooks); all writes stay formatting-preserving and additions-only. The narrower injectBundle() is removed. Scope note: widened from the plan's bundle-only DoD to all 34 per-service YAML after discovering they shared the identical gap (confirmed with the user). Verified: 401 parity 185 (per-service YAML) / 185 (bundle); idempotent (full Makefile injector chain re-run = 0 drift); per-service JSON byte-unchanged; 395 contract tests pass (incl. mcp-api-parity, doc-parity, deploy-config). Claude-Session: https://claude.ai/code/session_01EsjtheWqt8GxEZfd3DyTMu * fix(api): close JSON/YAML parity gaps in OpenAPI auth injector Follow-up hardening on the YAML auth-contract injector so it fully mirrors injectJson and stays convergent under source-of-truth edits: - Per-method entitlement stamping: injectYamlEntitlementContract now iterates every HTTP method of a gated path (via enumerateYamlOperations) instead of only the first, so a multi-method entitlement path gets the 403 + PRO-gated note on all methods, matching the JSON sibling. - Skip public paths in the entitlement pass, mirroring injectJson's isPublic-first branch (a public+entitlement overlap no longer stamps a stray ForbiddenError 403 on the YAML). - Auth pass now removes stale operation-level artifacts: a public op drops a leftover 401 (removeYamlUnauthorizedResponse), and a non-bearer op strips a leftover BearerAuth security block (removeYamlOperationSecurity), matching injectJson's delete-op.security / delete-op.responses['401']. - Fail closed when a path appears in both ENDPOINT_ENTITLEMENTS and PUBLIC_FORBIDDEN_GATES, which would otherwise oscillate the 403 body on every run and permanently break the pre-push freshness gate. Removed the now-unused first-method-only findYamlOperationRange. All fixes target latent reclassification cases; the 34 committed YAML artifacts + bundle are byte-unchanged (make-generate idempotent, --check clean) and all 246 contract tests pass. Co-Authored-By: Claude Opus 4.8 <[email protected]> Claude-Session: https://claude.ai/code/session_014Ua87UaGSbnHspLCZwfNZK * fix(api): close residual JSON/YAML parity gaps found in adversarial review Follow-up to the parity fixes, closing three latent divergences surfaced by adversarial validation (all dormant under the current config; the 34 YAML artifacts + bundle stay byte-unchanged and --check is clean): - Quoted-scalar descriptions: appendNoteToYamlScalar now inserts the entitlement/gate note INSIDE a single- or double-quoted description scalar instead of after the closing quote, which previously produced unparseable YAML for any gated op whose description the generator chose to quote (e.g. one containing ": "). The per-method stamping had widened this pre-existing hazard's blast radius. - ForbiddenError schema parity: set matchedEntitlementPath before the public-path opt-out so a spec whose only entitlement path is also public still emits the ForbiddenError schema, matching injectJson's public-agnostic hasEntitlementPath. - Public-forbidden-gate parity: skip non-public gate paths in the gate loop, mirroring injectJson which applies the bot-verification 403 only inside its isPublic branch (a non-public gate path now takes the authenticated 401 path instead of getting a stray bot 403). Validated end-to-end against synthetic fixtures (quoted single/double scalars, public-only entitlement spec, non-public gate path): output is valid YAML, idempotent, and matches the JSON contract. 246 contract tests still pass. Co-Authored-By: Claude Opus 4.8 <[email protected]> Claude-Session: https://claude.ai/code/session_014Ua87UaGSbnHspLCZwfNZK --------- Co-authored-by: Claude <[email protected]>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
_UNSPECIFIEDsentinels from public query-param enumsIssue coverage
Covers the 16 query/filter allow-list params called out in the issue scope, plus the two documented regex filters:
country_code, Cybertype/source/min_severity, Economicseries_id, Forecastdomain, Infrastructurestatus/type, Intelligencechokepoint_id/fuel_mode, Marketcountry_code, Militarytype/kind, Predictioncategory, Researchtype/feed_typecache_key, Tradecmd_codeLeads submit-contact.emailis a POST JSON body field with a dynamic free-domain deny-list, not a query/filter param in the 16-param scope. I left that body schema unchanged and called it out as a follow-up candidate rather than forcing an inaccurate enum/pattern.Fixes #4605.
Validation
make generatenode scripts/apply-openapi-filter-param-schemas.mjs --checknode --test tests/openapi-filter-param-schemas.test.mjs tests/openapi-security-contract.test.mjs tests/makefile-generate-plugin-path.test.mjs tests/generated-api-description-guard.test.mjs(156 tests/subtests passed)npm run typecheck:apigit diff --checkReview gates
$code-review-expert: pass, no blocking findings_UNSPECIFIEDsentinels from query-param enums