Read x-scalekit-docs-operation-rank for API sidebar ordering#765
Conversation
Load operation sort rules from the OpenAPI spec extension at build time so Scalar orders :external and :search paths after id-based routes. Includes updated API spec with user external_id REST endpoints.
WalkthroughThe PR updates the Scalekit OpenAPI spec (JSON and YAML) with new paths ( ChangesOpenAPI Spec and Operation Ranking
Estimated code review effort🎯 4 (Complex) | ⏱️ ~60 minutes Possibly related PRs
Suggested reviewers
🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Comment |
|
This change is mostly build tooling for API sidebar ordering, and the refreshed OpenAPI spec auto-renders into the API reference — so no hand-authoring is strictly required there. One thing worth a look: the spec adds new "manage membership by external ID" SDK methods ( If you'd like that guide update drafted, mention @ekline-ai. |
✅ Deploy Preview for scalekit-starlight ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 8
🤖 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 `@public/api/scalekit.scalar.json`:
- Around line 929-931: Do not edit the public/api/scalekit.scalar.json file
directly. Instead, locate the upstream OpenAPI source specification and fix the
schema misalignments there: ensure the v1usersCreateMembership schema includes
the membership property that is marked as required in the create request, and
align property names between request examples and schema definitions (for
example, use roles instead of role where the schema defines roles). After
correcting the upstream source, regenerate the public/api/scalekit.scalar.json
artifact. Apply these same fixes to all affected sections mentioned in lines
1022-1028, 1108-1110, and 1238-1244.
- Around line 330-385: The `/api/v1/connected_accounts/details` endpoint's 200
response references the
`connected_accountsGetConnectedAccountByIdentifierResponse` schema, which
includes `authorization_details` fields that expose credentials, contradicting
the endpoint's description of not exposing credentials. Since this is a
generated artifact under public/api/**, do not edit this file directly. Instead,
locate and fix the upstream OpenAPI source definition (likely in a proto file or
OpenAPI YAML source) to use a credential-free response schema for the details
endpoint that excludes authorization_details, then regenerate the
public/api/scalekit.scalar.json artifact from the corrected upstream source.
- Around line 7474-7482: The `secret_access_key` and `session_token` fields in
the schema are marked as `readOnly: true` (indicating they are response-only
fields) but their descriptions explicitly state they are "Never returned in
public API responses", which is contradictory. Remove these sensitive fields
from the public response schema entirely since they should never be exposed, or
replace them with non-sensitive masked versions if needed. However, since the
comment notes that direct edits to `public/api/**` specs are temporary, locate
and update the upstream OpenAPI source specification instead and regenerate this
artifact file rather than editing it directly.
- Around line 5497-5514: In the getUserSessions examples across all SDK samples
(Node.js, Python, Go, and Java), replace the user ID parameter from "user_123"
to "usr_user_123" to match the documented path parameter requirement with the
usr_ prefix. Additionally, update the status filter value from "ACTIVE" to
"active" to match the documented lowercase status values. These same changes
should also be applied to the similar examples in the specified line range
5550-5567. Note that these are temporary fixes in the artifact file, and the
proper solution is to update the upstream OpenAPI source definition and
regenerate this scalekit.scalar.json artifact.
- Around line 97-105: The connection_names parameter has a documented limit of
20 items in its description but the schema definition lacks the corresponding
maxItems constraint to enforce this limit. Add maxItems: 20 to the schema object
that defines the array type for the connection_names parameter to ensure
generated validators properly enforce the documented maximum count restriction.
Note that per the review comment, this is a temporary fix and the upstream
OpenAPI source should be updated and regenerated instead of directly editing
this artifact file.
- Around line 3425-3462: Fix the inconsistent field and enum naming between the
endpoint documentation and schema definitions in the
GetOrganizationSessionPolicy and related endpoints. Ensure the field name is
consistently `session_policy` across all endpoint descriptions and schema
definitions (not `policy_source`), and standardize enum values to uppercase
format (`APPLICATION`, `CUSTOM`, `MINUTES`) throughout the schemas referenced by
`organizationsGetOrganizationSessionPolicyResponse` and related responses. Per
the coding guidelines, locate and fix these inconsistencies in the upstream
OpenAPI source file, then regenerate this public/api/scalekit.scalar.json
artifact to propagate the corrections.
In `@public/api/scalekit.scalar.yaml`:
- Around line 276-287: The `connection_names` query parameter schema lacks
enforcement of the documented "Max 20 names per request" constraint. In the
schema section of the `connection_names` parameter definition, add a `maxItems`
constraint set to 20 to the array items definition. This will ensure that
generated validators and SDK contracts properly enforce the maximum limit of 20
connection names per request, making the schema consistent with the documented
API behavior.
In `@src/utils/openapiOperationRank.ts`:
- Around line 18-24: The getPathRank function assumes that the incoming
OperationRankConfig has a valid structure with path-segments as an iterable
array of objects with numeric rank properties, but the config is unvalidated
JSON from a spec extension. Add validation of the OperationRankConfig payload
before it is used in getPathRank by checking that path-segments is an array (if
present), that each rule has a valid match string and numeric rank value. This
validation should happen at the source where the JSON is deserialized into
OperationRankConfig (around lines 34-37) to ensure malformed extensions cannot
cause runtime errors or NaN comparator results that break API sidebar ordering.
🪄 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: ASSERTIVE
Plan: Pro
Run ID: b267229c-0cea-4242-8771-471234d6210e
📒 Files selected for processing (4)
public/api/scalekit.scalar.jsonpublic/api/scalekit.scalar.yamlsrc/pages/apis.astrosrc/utils/openapiOperationRank.ts
📜 Review details
⏰ Context from checks skipped due to timeout. (3)
- GitHub Check: Redirect rules - scalekit-starlight
- GitHub Check: Header rules - scalekit-starlight
- GitHub Check: Pages changed - scalekit-starlight
🧰 Additional context used
📓 Path-based instructions (15)
**/*.{js,ts,tsx,jsx,py,java,cs,go,cpp,c,rb,php,swift,kt,scala,rs,m,mm,groovy,gradle,xml,json}
📄 CodeRabbit inference engine (.cursor/rules/comment-standards.mdc)
Comments should not duplicate the code - avoid comments that simply restate what the code does; comments should add value beyond what's obvious from reading the code
Files:
src/utils/openapiOperationRank.tspublic/api/scalekit.scalar.json
**/*.{js,ts,tsx,jsx,py,java,cs,go,cpp,c,rb,php,swift,kt,scala,rs,m,mm,groovy}
📄 CodeRabbit inference engine (.cursor/rules/comment-standards.mdc)
**/*.{js,ts,tsx,jsx,py,java,cs,go,cpp,c,rb,php,swift,kt,scala,rs,m,mm,groovy}: Good comments do not excuse unclear code - refactor the code to be self-explanatory instead of using comments to explain poorly written code; use better variable names, function names, and code structure
Comments should dispel confusion, not cause it - ensure comments clarify rather than obscure the code's purpose; avoid cryptic or joke comments
Explain unidiomatic code in comments - comment on code that might seem unnecessary or redundant and document why you chose a specific pattern over more common alternatives, especially when it deviates from team conventions
Provide links to the original source of copied code - always attribute code copied from external sources with URLs to Stack Overflow answers, GitHub repositories, or documentation
Include links to external references where helpful - reference standards, RFCs, and official documentation; link to relevant specifications when implementing protocols
Add comments when fixing bugs - document bug fixes with context about the issue, reference issue trackers and bug reports, and explain workarounds and their limitations
Use comments to mark incomplete implementations - use standard formats for TODO, FIXME, and NOTE comments with context about what needs to be done and reference issue trackers when possible
Always document public APIs with function/class comments - explain the purpose, parameters, return values, and exceptions; include usage examples for complex functions
Include file headers with copyright information, license, and authorship - provide a brief description of the file's purpose and document dependencies and requirements
Files:
src/utils/openapiOperationRank.ts
**/*.{js,ts,tsx,jsx}
📄 CodeRabbit inference engine (.cursor/rules/comment-standards.mdc)
Use JSDoc standards for all function, class, and complex logic comments in JavaScript/TypeScript - include parameter descriptions (
@param), return values (@returns), types (@type), and descriptions; document exceptions and edge cases
Files:
src/utils/openapiOperationRank.ts
**/*.{ts,tsx}
📄 CodeRabbit inference engine (CLAUDE.md)
**/*.{ts,tsx}: Prefer interface for defining object shapes in TypeScript
Use camelCase for variable names
Files:
src/utils/openapiOperationRank.ts
**/*.{ts,tsx,py,go,java,mdx,md}
📄 CodeRabbit inference engine (CLAUDE.md)
**/*.{ts,tsx,py,go,java,mdx,md}: Use the exact SDK variable names: Node.js (scalekit), Python (scalekit_client), Go (scalekitClient), Java (scalekitClient)
Never hard-code secrets or API keys in code examples; use environment variables
Include security comments that state the threat, why the pattern is required, and what can go wrong if omitted
Files:
src/utils/openapiOperationRank.ts
**/*.{ts,tsx,py,go,java}
📄 CodeRabbit inference engine (CLAUDE.md)
**/*.{ts,tsx,py,go,java}: Use JSDoc/JavaDoc/docstring standards for function, class, and complex logic comments with parameter descriptions, return values, and types
Comments should not duplicate the code; explain what the code does conceptually, not literally
Use better variable names and structure instead of comments to explain poorly written code
Explain unidiomatic or redundant code in comments; clarify why a specific pattern was chosen
Document exceptions and edge cases in code comments
Include links to external references (standards, RFCs, official documentation) in comments where helpful
Add comments when fixing bugs; reference issue trackers
Use standard formats for TODO, FIXME, and NOTE comments
Files:
src/utils/openapiOperationRank.ts
**/*.{ts,tsx,js,json}
📄 CodeRabbit inference engine (CLAUDE.md)
Use
pnpmfor package management
Files:
src/utils/openapiOperationRank.tspublic/api/scalekit.scalar.json
**/*.{ts,tsx,js,jsx,py,go,java}
📄 CodeRabbit inference engine (AGENTS.md)
**/*.{ts,tsx,js,jsx,py,go,java}: Comments should not duplicate the code; comments should add value beyond what's obvious. Use better variable names and structure instead of using comments to explain poorly written code
Don't use comments to excuse unclear code. Comments should dispel confusion, not cause it. Ensure comments clarify rather than obscure purpose
Explain unidiomatic code in comments: comment on code that might seem unnecessary or redundant; explain why you chose a specific pattern
Use JSDoc/JavaDoc/docstring standards for function, class, and complex logic comments including parameter descriptions, return values, types, and descriptions
Document exceptions and edge cases in code comments
Include links to external references in code comments where helpful (standards, RFCs, official documentation)
Add comments when fixing bugs; reference issue trackers
Use standard formats for TODO, FIXME, and NOTE comments in code
Files:
src/utils/openapiOperationRank.ts
**/*.{md,mdx,astro,ts}
📄 CodeRabbit inference engine (CONTRIBUTING.md)
**/*.{md,mdx,astro,ts}: Usepnpm pretty-quick --stagedvia pre-commit git hook to auto-format all staged.md,.mdx,.astro,.tsfiles with Prettier
Runpnpm formatto auto-format all.md,.mdx,.astro,.tsfiles before pushing changes
Files:
src/utils/openapiOperationRank.tssrc/pages/apis.astro
**
⚙️ CodeRabbit configuration file
**: # CLAUDE.md - Scalekit Documentation GuideOverview
This file is the single source of truth for all documentation standards and AI assistant guidelines in this repository. All documentation must adhere to the rules defined below.
Core Principles
Documentation-first development
Every feature must include comprehensive, user-focused documentation. Documentation is not an afterthought but a first-class deliverable that guides implementation. All code changes require corresponding documentation updates.
Git workflow
- Do NOT include
Co-Authored-Bylines in commit messages- At the start of a fresh session, before making any changes, ask the user: "Do you want me to cut a new branch or work on the current branch?"
- Never force push (
git push --forceorgit push -f). If a push fails, stop and clearly explain the reason it failed — do not attempt workarounds without user confirmation.- For commit, push, and PR creation, spawn a subagent using the Haiku model to handle it. The pre-push hook generates large logs and PR creation output adds unnecessary noise to the main session context.
- Once the user confirms local testing works, or explicitly asks to commit and push, commit all changes, push the branch, and open a PR against
main. The PR must include:
- A crisp description of the changes
- A preview link in the format:
https://deploy-preview-{PR_NUMBER}--scalekit-starlight.netlify.app/{path-to-changed-page}/SDK variable names (critical)
CRITICAL: Use the exact variable names below in all documentation and code examples.
- Node.js:
scalekit- Python:
scalekit_client- Go:
scalekitClient- Java:
scalekitClientMulti-Language SDK Consistency
All code examples MUST include Node.js, Python, Go, and Java implementations with consistent variable naming conventions. Examples must show both success and error handling paths. Security implications must be explained for each implementation....
Files:
src/utils/openapiOperationRank.tssrc/pages/apis.astropublic/api/scalekit.scalar.jsonpublic/api/scalekit.scalar.yaml
**/*.{ts,js,mjs}
⚙️ CodeRabbit configuration file
**/*.{ts,js,mjs}: Do NOT enforce code-commenting style rules on these files.
Specifically, do not flag:
- Comments that "duplicate" or restate what the code does.
- Missing comments on bug fixes, workarounds, or issue references.
- Missing inline documentation or explanatory comments.
Code comments are at the author's discretion.
Files:
src/utils/openapiOperationRank.ts
**/*.astro
📄 CodeRabbit inference engine (CLAUDE.md)
Follow Astro + Starlight framework conventions for documentation projects
Files:
src/pages/apis.astro
**/*.{astro,tsx,css}
📄 CodeRabbit inference engine (CLAUDE.md)
Maintain compatibility with Tailwind CSS styling in documentation projects
Files:
src/pages/apis.astro
public/api/**
📄 CodeRabbit inference engine (CLAUDE.md)
Generated OpenAPI/Swagger specs MUST be placed in
public/api/directory; direct edits to spec files are temporary and will be overwrittenAPI specifications are generated from the
scalekit-inc/scalekitrepository. Generated OpenAPI/Swagger specs MUST be placed inpublic/api/directory. Direct edits to spec files inpublic/api/are temporary and will be overwritten. All API reference changes MUST be made in thescalekit-inc/scalekitrepository
Files:
public/api/scalekit.scalar.jsonpublic/api/scalekit.scalar.yaml
**/*.{yml,yaml,md,mdx}
📄 CodeRabbit inference engine (.cursor/rules/browsecentral-labels.mdc)
**/*.{yml,yaml,md,mdx}: BrowseCentral labels should be maximum 3-5 words - keep concise but add context when needed
BrowseCentral labels should be action-oriented - start with verbs when possible
BrowseCentral labels should be specific and clear - add context when simple labels are ambiguous
BrowseCentral labels should be outcome-focused - describe what users accomplish and the context
BrowseCentral labels should use 'Action + Object' pattern (e.g., 'Invite users', 'Restrict sign-up', 'Set up SCIM')
BrowseCentral labels should use feature names (e.g., 'Enterprise SSO', 'Passwordless quickstart')
BrowseCentral labels should describe task completion (e.g., 'Run migrations', 'Migrate auth', 'Merge identities')
BrowseCentral labels should include specific context when needed (e.g., 'Configure Scalekit MCP server', 'Validate incoming API requests')
BrowseCentral labels should use integration context when applicable (e.g., 'Build MCP auth with your existing auth system')
BrowseCentral labels should avoid instructional prefixes: 'How to', 'Guide to', 'Implement', 'Configure', 'Learn', 'Understand'
BrowseCentral labels should avoid verbose phrases: 'Step-by-step guide', 'Complete tutorial', 'Detailed documentation'
BrowseCentral labels should avoid weak verbs: 'Enable', 'Allow', 'Provide', 'Support'
Files:
public/api/scalekit.scalar.yaml
🧠 Learnings (4)
📚 Learning: 2026-02-25T12:04:06.383Z
Learnt from: saif-at-scalekit
Repo: scalekit-inc/developer-docs PR: 445
File: src/pages/apis.astro:63-64
Timestamp: 2026-02-25T12:04:06.383Z
Learning: In the developer-docs repository, all Astro pages are intended to render in light mode. Enforce this by setting localStorage.colorMode = 'light' globally to ensure a consistent light theme across the site, including Scalar API reference pages. This should be treated as a deliberate, project-wide style decision rather than a per-page override; verify no page uses a conflicting color mode and document any exception in developer docs.
Applied to files:
src/pages/apis.astro
📚 Learning: 2026-02-10T05:32:55.501Z
Learnt from: saif-at-scalekit
Repo: scalekit-inc/developer-docs PR: 424
File: public/api/scalekit.scalar.json:3451-3457
Timestamp: 2026-02-10T05:32:55.501Z
Learning: In scalekit-inc/developer-docs, public/api/scalekit.scalar.json is a generated OpenAPI artifact. Reviewers should not edit generated JSON directly. If inconsistencies arise (e.g., /api/v1/permissions type param description vs. enum), address them in release/PR notes for short-term visibility and implement long-term fixes by updating the generator or source templates, not by modifying the generated file.
Applied to files:
public/api/scalekit.scalar.json
📚 Learning: 2026-03-29T07:52:28.008Z
Learnt from: saif-at-scalekit
Repo: scalekit-inc/developer-docs PR: 546
File: public/api/scalekit.scalar.json:3511-3563
Timestamp: 2026-03-29T07:52:28.008Z
Learning: In this repo (scalekit-inc/developer-docs), do not edit any generated OpenAPI spec files directly under public/api/** (including public/api/scalekit.scalar.json). If a review finds ambiguity in the generated OpenAPI contract for a file under public/api/**, open an upstream issue in scalekit-inc/scalekit describing the contract change, link that issue back to the original PR comment/thread, and then resolve the review thread after the upstream issue link has been posted.
Applied to files:
public/api/scalekit.scalar.json
📚 Learning: 2026-03-12T11:57:08.067Z
Learnt from: saif-at-scalekit
Repo: scalekit-inc/developer-docs PR: 488
File: public/api/scalekit.scalar.yaml:3666-3707
Timestamp: 2026-03-12T11:57:08.067Z
Learning: Ignore YAMLlint braces warnings for generated OpenAPI YAML files under public/api/** (e.g., schema: { }). The generator produces this formatting and Scalar parses it correctly. Reviewers should not block PRs on this style-only finding.
Applied to files:
public/api/scalekit.scalar.yaml
🪛 ast-grep (0.44.0)
src/utils/openapiOperationRank.ts
[warning] 31-31: Filesystem path is not a string literal; a request-/variable-derived path can enable path traversal. Validate and normalize the path before use.
Context: fs.readFileSync(specPath, 'utf8')
Note: [CWE-22] Improper Limitation of a Pathname to a Restricted Directory ('Path Traversal').
(detect-non-literal-fs-filename-typescript)
🪛 Checkov (3.3.1)
public/api/scalekit.scalar.json
[medium] 97-101: Ensure that arrays have a maximum number of items
(CKV_OPENAPI_21)
public/api/scalekit.scalar.yaml
[medium] 277-281: Ensure that arrays have a maximum number of items
(CKV_OPENAPI_21)
🪛 YAMLlint (1.37.1)
public/api/scalekit.scalar.yaml
[error] 1856-1856: too many blank lines (3 > 2)
(empty-lines)
[error] 3116-3116: too many blank lines (3 > 2)
(empty-lines)
🔇 Additional comments (3)
src/pages/apis.astro (1)
6-17: LGTM!Also applies to: 208-208
public/api/scalekit.scalar.json (1)
13315-13323: 🎯 Functional CorrectnessThe ranking utility correctly handles partial path segments using substring matching. The
getPathRankfunction usespathStr.includes(rule.match), so:externaland:searchmatchers will properly identify segments likeusers:externalandorganizations:search. No functional issue exists.> Likely an incorrect or invalid review comment.public/api/scalekit.scalar.yaml (1)
13615-13621: LGTM!
Scalar embeds sorter functions via Function.toString(), which drops closure variables. Use new Function() so path-rank config is inlined in the body.
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 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 `@src/utils/openapiOperationRank.ts`:
- Around line 61-77: The getMethodRank function returns Number.POSITIVE_INFINITY
for unrecognized HTTP methods, which causes methodComparison to become NaN when
both a.method and b.method are unknown (Infinity - Infinity = NaN). Replace the
Number.POSITIVE_INFINITY return value in getMethodRank with a finite sentinel
value (such as a large number like 999) so that when both methods are unknown,
the subtraction will result in 0 and allow the comparator to properly fall
through to the path-rank tie-breaker logic.
🪄 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: ASSERTIVE
Plan: Pro
Run ID: 0787399b-31e9-4532-a5b7-d97425f2d66c
📒 Files selected for processing (1)
src/utils/openapiOperationRank.ts
📜 Review details
⏰ Context from checks skipped due to timeout. (3)
- GitHub Check: Redirect rules - scalekit-starlight
- GitHub Check: Header rules - scalekit-starlight
- GitHub Check: Pages changed - scalekit-starlight
🧰 Additional context used
📓 Path-based instructions (11)
**/*.{js,ts,tsx,jsx,py,java,cs,go,cpp,c,rb,php,swift,kt,scala,rs,m,mm,groovy,gradle,xml,json}
📄 CodeRabbit inference engine (.cursor/rules/comment-standards.mdc)
Comments should not duplicate the code - avoid comments that simply restate what the code does; comments should add value beyond what's obvious from reading the code
Files:
src/utils/openapiOperationRank.ts
**/*.{js,ts,tsx,jsx,py,java,cs,go,cpp,c,rb,php,swift,kt,scala,rs,m,mm,groovy}
📄 CodeRabbit inference engine (.cursor/rules/comment-standards.mdc)
**/*.{js,ts,tsx,jsx,py,java,cs,go,cpp,c,rb,php,swift,kt,scala,rs,m,mm,groovy}: Good comments do not excuse unclear code - refactor the code to be self-explanatory instead of using comments to explain poorly written code; use better variable names, function names, and code structure
Comments should dispel confusion, not cause it - ensure comments clarify rather than obscure the code's purpose; avoid cryptic or joke comments
Explain unidiomatic code in comments - comment on code that might seem unnecessary or redundant and document why you chose a specific pattern over more common alternatives, especially when it deviates from team conventions
Provide links to the original source of copied code - always attribute code copied from external sources with URLs to Stack Overflow answers, GitHub repositories, or documentation
Include links to external references where helpful - reference standards, RFCs, and official documentation; link to relevant specifications when implementing protocols
Add comments when fixing bugs - document bug fixes with context about the issue, reference issue trackers and bug reports, and explain workarounds and their limitations
Use comments to mark incomplete implementations - use standard formats for TODO, FIXME, and NOTE comments with context about what needs to be done and reference issue trackers when possible
Always document public APIs with function/class comments - explain the purpose, parameters, return values, and exceptions; include usage examples for complex functions
Include file headers with copyright information, license, and authorship - provide a brief description of the file's purpose and document dependencies and requirements
Files:
src/utils/openapiOperationRank.ts
**/*.{js,ts,tsx,jsx}
📄 CodeRabbit inference engine (.cursor/rules/comment-standards.mdc)
Use JSDoc standards for all function, class, and complex logic comments in JavaScript/TypeScript - include parameter descriptions (
@param), return values (@returns), types (@type), and descriptions; document exceptions and edge cases
Files:
src/utils/openapiOperationRank.ts
**/*.{ts,tsx}
📄 CodeRabbit inference engine (CLAUDE.md)
**/*.{ts,tsx}: Prefer interface for defining object shapes in TypeScript
Use camelCase for variable names
Files:
src/utils/openapiOperationRank.ts
**/*.{ts,tsx,py,go,java,mdx,md}
📄 CodeRabbit inference engine (CLAUDE.md)
**/*.{ts,tsx,py,go,java,mdx,md}: Use the exact SDK variable names: Node.js (scalekit), Python (scalekit_client), Go (scalekitClient), Java (scalekitClient)
Never hard-code secrets or API keys in code examples; use environment variables
Include security comments that state the threat, why the pattern is required, and what can go wrong if omitted
Files:
src/utils/openapiOperationRank.ts
**/*.{ts,tsx,py,go,java}
📄 CodeRabbit inference engine (CLAUDE.md)
**/*.{ts,tsx,py,go,java}: Use JSDoc/JavaDoc/docstring standards for function, class, and complex logic comments with parameter descriptions, return values, and types
Comments should not duplicate the code; explain what the code does conceptually, not literally
Use better variable names and structure instead of comments to explain poorly written code
Explain unidiomatic or redundant code in comments; clarify why a specific pattern was chosen
Document exceptions and edge cases in code comments
Include links to external references (standards, RFCs, official documentation) in comments where helpful
Add comments when fixing bugs; reference issue trackers
Use standard formats for TODO, FIXME, and NOTE comments
Files:
src/utils/openapiOperationRank.ts
**/*.{ts,tsx,js,json}
📄 CodeRabbit inference engine (CLAUDE.md)
Use
pnpmfor package management
Files:
src/utils/openapiOperationRank.ts
**/*.{ts,tsx,js,jsx,py,go,java}
📄 CodeRabbit inference engine (AGENTS.md)
**/*.{ts,tsx,js,jsx,py,go,java}: Comments should not duplicate the code; comments should add value beyond what's obvious. Use better variable names and structure instead of using comments to explain poorly written code
Don't use comments to excuse unclear code. Comments should dispel confusion, not cause it. Ensure comments clarify rather than obscure purpose
Explain unidiomatic code in comments: comment on code that might seem unnecessary or redundant; explain why you chose a specific pattern
Use JSDoc/JavaDoc/docstring standards for function, class, and complex logic comments including parameter descriptions, return values, types, and descriptions
Document exceptions and edge cases in code comments
Include links to external references in code comments where helpful (standards, RFCs, official documentation)
Add comments when fixing bugs; reference issue trackers
Use standard formats for TODO, FIXME, and NOTE comments in code
Files:
src/utils/openapiOperationRank.ts
**/*.{md,mdx,astro,ts}
📄 CodeRabbit inference engine (CONTRIBUTING.md)
**/*.{md,mdx,astro,ts}: Usepnpm pretty-quick --stagedvia pre-commit git hook to auto-format all staged.md,.mdx,.astro,.tsfiles with Prettier
Runpnpm formatto auto-format all.md,.mdx,.astro,.tsfiles before pushing changes
Files:
src/utils/openapiOperationRank.ts
**
⚙️ CodeRabbit configuration file
**: # CLAUDE.md - Scalekit Documentation GuideOverview
This file is the single source of truth for all documentation standards and AI assistant guidelines in this repository. All documentation must adhere to the rules defined below.
Core Principles
Documentation-first development
Every feature must include comprehensive, user-focused documentation. Documentation is not an afterthought but a first-class deliverable that guides implementation. All code changes require corresponding documentation updates.
Git workflow
- Do NOT include
Co-Authored-Bylines in commit messages- At the start of a fresh session, before making any changes, ask the user: "Do you want me to cut a new branch or work on the current branch?"
- Never force push (
git push --forceorgit push -f). If a push fails, stop and clearly explain the reason it failed — do not attempt workarounds without user confirmation.- For commit, push, and PR creation, spawn a subagent using the Haiku model to handle it. The pre-push hook generates large logs and PR creation output adds unnecessary noise to the main session context.
- Once the user confirms local testing works, or explicitly asks to commit and push, commit all changes, push the branch, and open a PR against
main. The PR must include:
- A crisp description of the changes
- A preview link in the format:
https://deploy-preview-{PR_NUMBER}--scalekit-starlight.netlify.app/{path-to-changed-page}/SDK variable names (critical)
CRITICAL: Use the exact variable names below in all documentation and code examples.
- Node.js:
scalekit- Python:
scalekit_client- Go:
scalekitClient- Java:
scalekitClientMulti-Language SDK Consistency
All code examples MUST include Node.js, Python, Go, and Java implementations with consistent variable naming conventions. Examples must show both success and error handling paths. Security implications must be explained for each implementation....
Files:
src/utils/openapiOperationRank.ts
**/*.{ts,js,mjs}
⚙️ CodeRabbit configuration file
**/*.{ts,js,mjs}: Do NOT enforce code-commenting style rules on these files.
Specifically, do not flag:
- Comments that "duplicate" or restate what the code does.
- Missing comments on bug fixes, workarounds, or issue references.
- Missing inline documentation or explanatory comments.
Code comments are at the author's discretion.
Files:
src/utils/openapiOperationRank.ts
🪛 OpenGrep (1.23.0)
src/utils/openapiOperationRank.ts
[ERROR] 56-84: new Function() with dynamic input can execute arbitrary code. Avoid dynamic code evaluation entirely, or use a safe alternative.
(coderabbit.code-injection.new-function-js)
🔇 Additional comments (2)
src/utils/openapiOperationRank.ts (2)
66-73: 🎯 Functional CorrectnessInline
getPathRankreuses the unvalidated config shape.This inlined copy assumes
config['path-segments']is iterable and eachrule.rankis a finite number; a malformed extension yieldsNaNranks here too. Same concern already raised on the module-levelgetPathRank.
56-84: 🔒 Security & PrivacyConfig source is committed; risk is mitigated.
loadOperationRankConfigreads the rank configuration frompublic/api/scalekit.scalar.json(a committed file), not external or user input. Thex-scalekit-docs-operation-rankextension values are simple strings and numbers. Since the source is trusted at build-time and the payload is well-formed, the theoretical serialization risk (script tag or Unicode breaking the HTML context) is effectively mitigated.
scalekit-inc#640) Adds a tip to the connection setup guide noting that localhost redirect URIs are supported during development and staging. The MCP server can run on localhost as long as the MCP client can reach it. Relates to Pylon issue scalekit-inc#765.
2 participants
Summary
x-scalekit-docs-operation-rankextension.operationsSorter, so paths containing:externaland:searchsort after id-based routes (e.g.GET /users/{id}beforeGET /users/{external_id}).scalekit.scalarAPI spec copied from the scalekit repo, with userexternal_idREST endpoints and the operation-rank extension.Changes
src/utils/openapiOperationRank.ts— loads rank config from the spec, exposescreateOperationsSorter.src/pages/apis.astro— uses the shared sorter instead of inlinelocaleCompare-only logic.public/api/scalekit.scalar.{json,yaml}— refreshed spec with external_id user endpoints andx-scalekit-docs-operation-rank.Test plan
GET /users/{id}beforeGET /users/{external_id}and search routesSummary by CodeRabbit
Release Notes
New Features
get,patch,delete)Documentation