Repository navigation
fix: document raw JSON as objects and byte fields as base64 strings - #30123
Conversation
Part of DOCS-1122. Assisted-by: AI
72d7095 to
0283447
Compare
|
/coder-agents-review |
|
Chat: Review posted | View chat Review historydeep-review v0.13.0 | Round 5 | Last posted: Round 5, 14 findings (7 P3, 7 P4), APPROVE. Review Finding inventoryFinding inventory: PR #30123Findings
Contested and acknowledgedCRF-5 (P3, codersdk/chats.go:556) - Per-field object tags vs one .swaggo replace line
Round logRound 1Netero first pass: 3 P3, 1 P4, no P0, panel proceeded. Full panel (round 1): Ging-Go, Ryosuke, Melody, Pariston, Mafuuu, Gon, Leorio, Razor, wildcard Meruem (random draw). Focused size target 6-8 plus wildcard. Ging-Go and Mafuuu: no findings. Convergence: Meruem, Pariston, Ryosuke independently verified a Round 2Fix round (no files added or renamed, no exported signature changes, same goal, effective additions +16). Churn guard PROCEED: CRF-1..4, CRF-6..9 addressed; CRF-5 contested. Netero: no findings, one Note (CRF-16). Panel: Meruem, Pariston, Ryosuke (contested; reused R1 agents via message_agent), Leorio and Gon (doc comments touched), Razor (PR description changed), Ging-Go (.go changed), wildcard Mafuuu (random draw). Ging-TS not spawned: the only .ts change is generated Round 3Restructure round: the PR body was replaced with text describing a different change (idpsync params, x-example, TestEndpointsDocumented), which states a different goal. Code change since R2 (fcebe8e) only adds the Round 4Fix round (commit 8677a48 changes only the Round 5Fix round: head unchanged at 8677a48; only the PR description changed. Churn guard PROCEED: CRF-26 addressed. Netero: no findings (unchanged-diff skip not applied because round 4 was a panel round). Panel: Leorio (raised CRF-26), Pariston and Mafu-san (to reach the 3-reviewer minimum; PR text), wildcard Knov (random draw). No domain specialists: no files changed since round 4. All reviewers: no findings. All in-scope findings closed. Out-of-scope items CRF-12, 13, 14, 15, 17, 18, 20, 24, 25 remain for a human decision. Reviewed against 2255794..8677a48. About deep-reviewCRF = Coder Review Finding (P0-P4, Nit, Note)
|
There was a problem hiding this comment.
This PR adds swaggertype tags to seven json.RawMessage fields and three []byte fields so the API reference stops rendering them as integer arrays. Regenerating the docs at head reproduces the committed output. Findings: 6 P3, 3 P4.
Out of scope (needs a ticket or explicit acceptance by a human):
scripts/apitypings/main.go:138:json.RawMessagemaps tomap[string]string, soChatToolCallPart.args,DynamicTool.input_schema, andAuditLog.additional_fieldsare typedRecord<string, string>intypesGenerated.ts. TypeScript code that trusts the type treats nested objects, numbers, and booleans as strings.coderd/workspacebuilds.go:1059:GET /workspacebuilds/{workspacebuild}/stateis annotated@Success 200 {object} codersdk.WorkspaceBuild, but the handler writes the raw provisioner state bytes, so the reference documents a response body the endpoint never returns.codersdk/chats.go:583: theProviderMetadatacomment says "as raw JSON", which thejson.RawMessagetype already states.codersdk/chats.go:2222: theInputSchemacomment repeats theinput_schemakey that the struct tag already shows.
🤖 This review was automatically generated with Coder Agents.
Hide ProviderMetadata from the API reference like its internal-only siblings, and describe the any-JSON and base64 fields in their doc comments so the reference tells clients what to send. Part of DOCS-1122. Assisted-by: AI
|
/coder-agents-review |
There was a problem hiding this comment.
The new commit addresses 8 of the 9 round 1 findings: provider_metadata is hidden with swaggerignore, the any-JSON fields and the three base64 fields have field comments that reach the schema, and the PR description no longer proposes the untyped override. Regenerating the docs at 1e125cd reproduces the committed output. One P3 remains open: the .swaggo thread is reopened below. If it is not fixed in this PR and no ticket is linked, a human needs to accept the gap.
Out of scope (needs a ticket or explicit acceptance by a human):
codersdk/chats.go:639:StripInternalclearscontext_file_content,context_file_os,context_file_directory,skill_dir, andcontext_file_skill_meta_file, but those fields have noswaggerignore:"true", so the API reference lists response fields that clients never receive.coderd/templatebuilder/catalog.go:130: the catalog loader never checks a module variable'sdefaultagainst itstype, so a future manifest that breaks the new "Default is a JSON value that matches Type" comment loads without error. All 110 shipped defaults match today.
Notes:
site/src/api/typesGenerated.ts:10775: the new "can be any JSON value" comments now sit directly aboveRecord<string, string>types forToolResult.outputandTemplateBuilderModuleVariable.default, which makes the round 1 out-of-scopeapitypingsmapping visible on adjacent lines.
🤖 This review was automatically generated with Coder Agents.
Replace the per-field swaggertype tags on json.RawMessage with a single .swaggo replace so future raw JSON fields get the same treatment. The generated swagger.json is unchanged. Part of DOCS-1122. Assisted-by: AI
|
/coder-agents-review |
There was a problem hiding this comment.
The .swaggo thread is fixed in fcebe8e: replace encoding/json.RawMessage object now covers every raw JSON field, the PR's per-field tags are gone, and regenerating the docs reproduces the committed output. The PR body now describes a different change, so it needs to be restored. Findings: 1 P3, 3 P4.
Out of scope (needs a ticket or explicit acceptance by a human):
codersdk/audit.go:261:AuditLog.AdditionalFieldsandcodersdk/oauth2.go:565,673,761keepswaggertype:"object", which the new.swaggorule makes redundant, so the code shows two mechanisms for the same schema and suggests new fields still need the tag.coderd/coderdtest/swagger_test.go:59: nothing fails when a new[]bytefield lacksswaggertype:"string" format:"byte", so it renders as an integer array; 3 of 4 such fields were untagged before this PR.TestSDKFieldsFormattedalready assertsformattags for UUID and time fields and could assert this too..swaggo:9: the existingNullUUIDandNullTimecomments restate theirreplacelines instead of giving the reason.
In reply to IC_kwDOGkVX1s8AAAABgqCzkQ:
P3 [CRF-19] The PR body describes a different change, not this diff. (Netero)
The body lists idpsync organization path parameters, format(uuid) on ids query arrays, x-example header extensions, and a TestEndpointsDocumented check; git diff 2255794d65..HEAD | grep -ciE 'idpsync|x-example|TestEndpointsDocumented|format\(uuid\)' prints 0. Reviewers and the squash commit message would describe changes this PR does not contain. Restore the round 2 body and update it for fcebe8e: json.RawMessage now renders as object through the .swaggo rule, not per-field tags.
🤖
In reply to IC_kwDOGkVX1s8AAAABgqCzkQ:
P4 [CRF-23] The title says "with their real Swagger types", but object is not the real type of result, output, or default. (Leorio)
The title becomes the squash commit subject, and codersdk/chats.go:564 says the value "can be any JSON value". For example: fix: document raw JSON as objects and byte fields as base64 strings.
🤖
🤖 This review was automatically generated with Coder Agents.
Part of DOCS-1122. Assisted-by: AI
|
/coder-agents-review |
There was a problem hiding this comment.
Commit 8677a48 applies the .swaggo and Default comment fixes, and the title and body now describe this diff. Regenerating the docs reproduces the committed output. One P4 remains.
In reply to IC_kwDOGkVX1s8AAAABgqSKuQ:
P4 [CRF-26] The PR description says TemplateBuilderModuleVariable.default "can hold any JSON value", but the new comment at codersdk/templatebuilder.go:27 says it is a JSON string, number, or boolean. (Leorio)
TemplateBuilderVariableType has only string, number, and bool (codersdk/templatebuilder.go:18-20), so the comment is correct and the description is the one to change. For example: "ChatMessagePart.result and ToolResult.output can hold any JSON value, and TemplateBuilderModuleVariable.default holds a string, number, or boolean, so object is an approximation for all three and the field comments say so."
🤖
🤖 This review was automatically generated with Coder Agents.
|
/coder-agents-review |
There was a problem hiding this comment.
The PR description now matches the Default field comment, and no new findings were raised at 8677a48. All in-scope findings from earlier rounds are resolved. The out-of-scope items listed in earlier reviews still need a ticket or explicit acceptance by a human.
🤖 This review was automatically generated with Coder Agents.
Swagger renders
json.RawMessageand[]bytefields as integer arrays, so the API reference showed chat tool calls as"args": [0]even though tool arguments and results are JSON values.Render every
json.RawMessageas an object with one.swaggoreplace rule, and tag[]bytefields, which JSON-encode as base64,swaggertype:"string" format:"byte". This coversChatMessagePart.args,.result,.data,ToolResult.output,DynamicTool.input_schema, both workspace buildstatefields,TemplateBuilderModuleVariable.default, andCreateTestAuditLogRequest.additional_fields.ChatMessagePart.provider_metadatais internal only, so it is hidden withswaggerignore:"true"like its siblings.ChatMessagePart.resultandToolResult.outputcan hold any JSON value, andTemplateBuilderModuleVariable.defaultholds a string, number, or boolean, soobjectis an approximation for all three and the field comments say so. swag rejects an untyped.swaggooverride forjson.RawMessage.Part of DOCS-1122, split from #30121.
🤖 Built with AI assistance.