chore(api): update API skills and enforce doc formatting#4330
Merged
Conversation
Contributor
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: Path: .coderabbit.yaml Review profile: CHILL Plan: Pro Run ID: ⛔ Files ignored due to path filters (2)
📒 Files selected for processing (8)
✅ Files skipped from review due to trivial changes (4)
🚧 Files skipped from review as they are similar to previous changes (2)
📝 WalkthroughWalkthroughThis PR introduces a TypeScript linter system to format TypeSpec documentation comments as Markdown and reorganizes error handling documentation, then applies that formatting across 50+ API specification files. It also lets features explicitly clear unit cost by accepting ChangesDocumentation Formatting Tooling Infrastructure
Error Handling Documentation System
API Specification Documentation Formatting Consistent comment reformatting applied across all domains (50+ files):
Estimated code review effort🎯 2 (Simple) | ⏱️ ~12 minutes Possibly related PRs
Suggested reviewers
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
|
97bffa6 to
44df771
Compare
44df771 to
d1d2191
Compare
b2c8e96 to
4019f74
Compare
9ae5f9a to
8175eba
Compare
8175eba to
9aa48ec
Compare
Contributor
There was a problem hiding this comment.
Actionable comments posted: 8
🧹 Nitpick comments (2)
api/spec/packages/aip/src/features/feature.tsp (1)
59-64: ⚡ Quick winClarify what
nullmeans forunit_costupdatesSince Line 64 now allows
null, it’d help to state thatnullclears existingunit_cost, while omission leaves it unchanged.Suggested patch
/** * Optional per-unit cost configuration. Use "manual" for a fixed per-unit cost, or * "llm" to look up cost from the LLM cost database based on meter group-by - * properties. + * properties. Set to `null` to remove existing unit cost; omit to keep unchanged. */🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@api/spec/packages/aip/src/features/feature.tsp` around lines 59 - 64, Update the documentation for the unit_cost field on the Feature type to clarify update semantics: in the comment/JSDoc above the unit_cost?: FeatureUnitCost | null declaration, state that setting unit_cost to null will clear any existing unit_cost on the resource, while omitting unit_cost from an update request will leave the existing value unchanged; reference the field name unit_cost and the type FeatureUnitCost so readers know this applies to that property.api/spec/packages/aip/package.json (1)
19-21: 💤 Low valuePrettier in
dependenciesrather thandevDependencies.Typically, Prettier would live in
devDependenciessince it's a development tool. However, if theformatscript needs to be runnable in contexts where devDependencies aren't installed, this placement might be intentional. Worth double-checking if this was deliberate or if it should be moved todevDependencies.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@api/spec/packages/aip/package.json` around lines 19 - 21, The package.json currently lists "prettier" under "dependencies" which is meant for runtime packages; move "prettier" to "devDependencies" unless the "format" or other npm scripts must run in environments without devDependencies installed. Edit package.json to remove "prettier" from "dependencies" and add it under "devDependencies" (keeping the same version string "3.8.3"), and verify any scripts like "format" still work as intended after the change.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@api/spec/packages/aip/lib/rules/utils.js`:
- Around line 110-123: The opening doc-comment delimiter is not indented in
wrapMarkdownAsDocComment, causing the comment block to shift left; update the
function so the opening '/**' is prefixed with the indent variable in both the
non-empty branch (change '/**' to `${indent}/**` in the out array) and the
empty-case return (make the returned opening line include indent as well),
leaving the existing `${indent} *` and `${indent} */` lines unchanged so the
entire block preserves the requested indentation.
In `@api/spec/packages/aip/src/currencies/cost-bases/cost-basis.tsp`:
- Around line 27-29: Update the documentation string for the cost basis field
effective_from in cost-basis.tsp: change the phrase "will set to `now`" to "will
be set to `now`" so the sentence reads that if not provided it will be effective
immediately and will be set to `now` by the system; locate the effective_from
doc comment within the CostBasis (or related) type and apply this wording fix.
In `@api/spec/packages/aip/src/features/feature.tsp`:
- Around line 35-36: The doc comment for the feature's meter contains a
duplicated word ("and and"); locate the meter description in feature.tsp (the
comment above the meter property or within the Feature type definition) and
remove the duplicate so the sentence reads correctly (e.g., "The meter that the
feature is associated with and based on which usage is calculated. If not
specified, the feature is static.").
In `@api/spec/packages/aip/src/llmcost/prices.tsp`:
- Around line 98-103: The field effective_to is declared optional but the
comment claims "null = current", so update the type to reflect that null is a
valid value: change effective_to?: Shared.DateTime to explicitly allow null
(e.g., effective_to?: Shared.DateTime | null) and keep or adjust the JSDoc to
state "null = current" so the API type and comment are consistent; update any
related usages/validators of effective_to to accept null if needed.
In `@api/spec/packages/aip/src/productcatalog/addon.tsp`:
- Around line 8-10: Update the doc comment that currently references
effectiveFrom/effectiveTo to use the actual declared field names effective_from
and effective_to so the documentation matches the model; locate the comment near
the add-on status description (around the add-on model/docblock in addon.tsp)
and replace the camelCase references with the snake_case field names
(effective_from, effective_to) to keep generated docs consistent with the
implementation.
- Around line 92-96: The status documentation for add-ons is missing the case
where effectiveTo is unset; update the rules around effectiveFrom/effectiveTo
(referencing effectiveFrom, effectiveTo and the status values draft, active,
archived) so active is defined as: effectiveFrom is set and effectiveFrom <= now
and (effectiveTo is unset OR now < effectiveTo); keep draft = no effectiveFrom
and archived = effectiveTo <= now and ensure the wording clearly states that an
absent effectiveTo means the add-on is effective indefinitely.
In `@api/spec/packages/aip/src/productcatalog/plan.tsp`:
- Around line 88-94: Update the doc comment for plan status to use the exact
schema field names and enum values: replace camelCase with snake_case (use
effective_from and effective_to) and remove the non-enum term "inactive";
enumerate only the actual statuses (draft, active, archived, scheduled) and
their precise conditions (draft = no effective_from; active = effective_from <=
now < effective_to; archived = effective_to <= now; scheduled = now <
effective_from < effective_to), updating the comment near the Plan status/enum
definition (e.g., where the plan status is documented) accordingly.
In `@api/spec/packages/aip/src/productcatalog/unitconfig.tsp`:
- Around line 75-76: The documentation line containing both formulas should be
split into two sentences/lines to improve readability: change the run-on comment
"For divide: converted = raw / conversionFactor For multiply: converted = raw ×
conversionFactor" in unitconfig.tsp to two separate lines such as one line for
the divide formula and a second line for the multiply formula (the doc block
that explains conversion semantics near the unit conversion description in
unitconfig.tsp).
---
Nitpick comments:
In `@api/spec/packages/aip/package.json`:
- Around line 19-21: The package.json currently lists "prettier" under
"dependencies" which is meant for runtime packages; move "prettier" to
"devDependencies" unless the "format" or other npm scripts must run in
environments without devDependencies installed. Edit package.json to remove
"prettier" from "dependencies" and add it under "devDependencies" (keeping the
same version string "3.8.3"), and verify any scripts like "format" still work as
intended after the change.
In `@api/spec/packages/aip/src/features/feature.tsp`:
- Around line 59-64: Update the documentation for the unit_cost field on the
Feature type to clarify update semantics: in the comment/JSDoc above the
unit_cost?: FeatureUnitCost | null declaration, state that setting unit_cost to
null will clear any existing unit_cost on the resource, while omitting unit_cost
from an update request will leave the existing value unchanged; reference the
field name unit_cost and the type FeatureUnitCost so readers know this applies
to that property.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
Run ID: 02d5755f-c6d6-4b65-b0d5-eed39183e47e
⛔ Files ignored due to path filters (2)
api/spec/pnpm-lock.yamlis excluded by!**/pnpm-lock.yamlapi/v3/openapi.yamlis excluded by!**/openapi.yaml
📒 Files selected for processing (64)
.agents/skills/api/SKILL.md.agents/skills/api/rules/aip-193-errors.md.agents/skills/api/rules/inline-errors.md.agents/skills/api/rules/openmeter-error-types.mdapi/spec/package.jsonapi/spec/packages/aip/lib/index.jsapi/spec/packages/aip/lib/rules/docs.jsapi/spec/packages/aip/lib/rules/utils.jsapi/spec/packages/aip/package.jsonapi/spec/packages/aip/scripts/apply-doc-fixes.mjsapi/spec/packages/aip/src/apps/catalog.tspapi/spec/packages/aip/src/apps/external_invoicing.tspapi/spec/packages/aip/src/apps/stripe.tspapi/spec/packages/aip/src/billing/operations.tspapi/spec/packages/aip/src/billing/profile.tspapi/spec/packages/aip/src/billing/tax.tspapi/spec/packages/aip/src/common/parameters.tspapi/spec/packages/aip/src/common/properties.tspapi/spec/packages/aip/src/currencies/cost-bases/cost-basis.tspapi/spec/packages/aip/src/currencies/cost-bases/operations.tspapi/spec/packages/aip/src/currencies/currency.tspapi/spec/packages/aip/src/currencies/operations.tspapi/spec/packages/aip/src/customers/charges/charges.tspapi/spec/packages/aip/src/customers/charges/operations.tspapi/spec/packages/aip/src/customers/credits/adjustment.tspapi/spec/packages/aip/src/customers/credits/balance.tspapi/spec/packages/aip/src/customers/credits/grant.tspapi/spec/packages/aip/src/customers/credits/ledger.tspapi/spec/packages/aip/src/customers/credits/operations.tspapi/spec/packages/aip/src/customers/customer.tspapi/spec/packages/aip/src/customers/operations.tspapi/spec/packages/aip/src/entitlements/access.tspapi/spec/packages/aip/src/events/event.tspapi/spec/packages/aip/src/events/operations.tspapi/spec/packages/aip/src/features/cost.tspapi/spec/packages/aip/src/features/feature.tspapi/spec/packages/aip/src/features/operations.tspapi/spec/packages/aip/src/features/unitcost.tspapi/spec/packages/aip/src/governance/governance.tspapi/spec/packages/aip/src/invoices/invoice.tspapi/spec/packages/aip/src/invoices/party.tspapi/spec/packages/aip/src/konnect.tspapi/spec/packages/aip/src/llmcost/operations.tspapi/spec/packages/aip/src/llmcost/prices.tspapi/spec/packages/aip/src/meters/meter.tspapi/spec/packages/aip/src/meters/operations.tspapi/spec/packages/aip/src/meters/query.tspapi/spec/packages/aip/src/openmeter.tspapi/spec/packages/aip/src/productcatalog/addon.tspapi/spec/packages/aip/src/productcatalog/operations.tspapi/spec/packages/aip/src/productcatalog/plan.tspapi/spec/packages/aip/src/productcatalog/planaddon.tspapi/spec/packages/aip/src/productcatalog/price.tspapi/spec/packages/aip/src/productcatalog/ratecard.tspapi/spec/packages/aip/src/productcatalog/unitconfig.tspapi/spec/packages/aip/src/shared/address.tspapi/spec/packages/aip/src/shared/enums.tspapi/spec/packages/aip/src/shared/filters.tspapi/spec/packages/aip/src/shared/properties.tspapi/spec/packages/aip/src/subscriptions/operations.tspapi/spec/packages/aip/src/subscriptions/reference.tspapi/spec/packages/aip/src/subscriptions/subscription.tspapi/v3/api.gen.goapi/v3/test/openapi.test.yaml
mark-vass-konghq
approved these changes
May 11, 2026
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
2 participants
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 by CodeRabbit
Release Notes
Documentation
Improvements