docs: missing_docs audit bookkeeping and OpenAPI path-parsing fix - #446
docs: missing_docs audit bookkeeping and OpenAPI path-parsing fix#446hongyi-chen wants to merge 3 commits into
Conversation
Fix parse_openapi_paths() to accept YAML-quoted path keys. Every parameterized endpoint looked absent from the spec, producing 6 false positives this run. Map GeminiEnterprise (dogfood -> GA), the three new TUI-only slash commands, agents.voice.voice_input_hold_key, and the x-internal messaging/events endpoints. Prune the two removed slash commands. Regenerate the surface snapshot. Co-Authored-By: Oz <oz-agent@warp.dev>
hongyi-chen
added
the
documentation
Warp Agent Staging
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
Narrow this PR to the audit-script parser fix, the API internal mappings, and the snapshot regen, so it doesn't conflict with #430's edits to the same regions of feature_surface_map.md. Co-Authored-By: Oz <oz-agent@warp.dev>
|
I'm starting a first review of this pull request. You can view the conversation on Warp. I completed the review and no human review was requested for this pull request. Comment Powered by Oz |
#407 merged a dedicated Gemini Enterprise BYOLLM page (byollm-gemini-enterprise.mdx) and split BYOLLM into a landing page plus per-host pages. Point the missing_docs surface map's GeminiEnterprise entry at that dedicated page instead of the old single bring-your-own-llm.mdx, and drop this PR's now-redundant Gemini prose (resolved via the merge of main). The API-audit false-positive/regex fix is handled separately in #446. Co-Authored-By: Oz <oz-agent@warp.dev>
![oz-for-oss[bot]](https://avatars.githubusercontent.com/in/3450139?s=60&v=4){kind=small}
There was a problem hiding this comment.
Overview
This PR updates missing_docs audit bookkeeping, maps internal orchestration messaging/lifecycle API endpoints, refreshes the surface snapshot, and fixes OpenAPI path parsing for quoted parameterized YAML keys. I found no correctness blockers, no material spec drift to check because spec_context.md contains no approved or repository spec context, and no security findings.
Concerns
- One non-blocking test coverage suggestion is inline.
Verdict
Found: 0 critical, 0 important, 1 suggestions
Approve
Comment /oz-review on this pull request to retrigger a review (up to 3 times on the same pull request).
Powered by Oz
| paths = set() | ||
| for match in re.finditer(r"(?m)^\s{2}(/[^\s:]+):", openapi_text): | ||
| paths.add(_normalize_path_params(match.group(1))) | ||
| for match in re.finditer(r"""(?m)^\s{2}(?:'(/[^']+)'|"(/[^"]+)"|(/[^\s:'"]+)):""", openapi_text): |
There was a problem hiding this comment.
💡 [SUGGESTION] Add a regression test for quoted parameterized OpenAPI paths (single- and double-quoted) so this parser bug cannot recur.
3 participants
Summary
Companion bookkeeping PR for a
missing_docsdrift-watch run: an audit-script bug fix, the API surface-map entries, and the regenerated snapshot.Both audits exited 0 with no skipped audits and
unaccounted: none.Scope note: overlap with #430
This PR originally also mapped
GeminiEnterprise, the three new TUI-only slash commands, andagents.voice.voice_input_hold_key. #430 already covers all three, so those hunks have been removed to avoid conflicting edits to the same regions offeature_surface_map.md. What's left here is disjoint from #430, so the two can merge in either order.Consequence while both are open: running the audit on this branch alone still reports 1 feature, 4 slash command, and 2 setting findings. Those are #430's to close. The standing coverage audit keeps flagging them until it merges, so nothing is lost if this PR lands first.
One thing worth checking on #430: it maps
GeminiEnterprise -> bring-your-own-llm.mdx, but #407 has since merged a dedicatedbyollm-gemini-enterprise.mdxpage. That may be the better target now.Audit-script bug: quoted OpenAPI path keys
parse_openapi_paths()matched^\s{2}(/[^\s:]+):, which only recognizes unquoted YAML path keys. Any path containing a{param}is emitted quoted, because YAML reads a leading{as a flow mapping:Every parameterized endpoint therefore looked absent from the spec. The substring fallback didn't save it either, since it compares the handler's param name against the spec's (
{id}vs{scheduleId}).That produced 6 false-positive findings in this run:
GET /agent/artifacts/{uid}plus all five/agent/schedules/{id}operations. All six are, and were, in the released spec.The regex now accepts single-quoted, double-quoted, and bare keys. Effect on the accounting:
api_routesspec_coveredwent 9 → 22, and API findings went 15 → 2.Surface map: API endpoints
Mapped
internalwith rationale, each verified againstx-internal: truein warp-server'spublic_api/openapi.yaml:POST /agent/messages,GET /agent/messages/{run_id},POST /agent/messages/{id}/read,POST /agent/messages/{id}/delivered,GET /agent/events,POST /agent/events/{run_id}— marked internal upstream, so warp-server's publish filter strips them. They back the agent messaging tools and the documentedoz run messageCLI, but the REST surface itself isn't released.GET /agent/events/stream— absent from the canonical spec entirely and registered only on the RTC host.Snapshot
Regenerated with
--update-snapshot. Diff mode reports 0 surface changes and 0 changelog items to verify.Deferred findings
Nothing from this run was silently dropped. What remains open, and why:
2 API endpoints awaiting the release sync (medium)
GET /agent/artifacts/{artifactUid}/downloadandGET /agent/run-by-external-referenceare public upstream (nox-internalmarker) but missing fromdevelopers/agent-api-openapi.yaml. They are deliberately not mappedinternal— the finding should keep firing until the spec actually contains them. warp-server's release-gatedsync_public_openapi_to_docsworkflow is the authoritative publisher and will bring them in; #445 makes the docs-side fallback safe if it's needed sooner.32 terminology findings (low)
Owned by the
style_lintskill, whichmissing_docsexplicitly defers to for pure wording issues. They cluster into four families: "warp ai", "ai credits", "agent-mode", and "warp terminal", spread across 32 files with several different owners. Fixing them here would produce a wide, low-signal diff; they belong in a dedicatedstyle_lintsweep.1 new server-side agent tool (low)
report_external_reference(changelog #14072) records an external resource such as a Linear issue as anEXTERNAL_REFERENCEartifact. Verified no docs change is needed: Warp doesn't document individual server-side agent tools —report_pr,notify_user,finish_task, andwait_for_eventsall have no public pages either. Tracked by the snapshot.11 changelog items verified as already covered or not doc-worthy
Of 13 flagged items, 5 became sibling PRs (#438, #439, #440, #441, #442). The rest:
FileBackedExecutionProfilesis an internal persistence-backend detail already on the ignore list;agents.execution_profilesis documented.report_external_referenceitem above.Conversation: https://staging.warp.dev/conversation/53c4f3f8-39bb-46c1-a5c0-66b467db0439
Run: https://oz.staging.warp.dev/runs/019fb91e-74a0-73f4-ac72-f2d88c32fab5
This PR was generated with Oz.
Co-Authored-By: Oz oz-agent@warp.dev