ContractKit (VS Code extension)

Language support for ContractKit .ck contract files in VS Code and Cursor. Includes syntax highlighting, completion, hover, go-to-definition, document symbols, and live diagnostics from a Language Server.

Features

• Syntax highlighting via TextMate grammar (syntaxes/ck.tmLanguage.json)
• Auto-completion for built-in types, modifiers, keywords, HTTP methods, content types, security blocks, and cross-file model references
• Hover information for built-in types and referenced models
• Go-to-definition — jumps from a model reference to its contract declaration, or from a service: reference (e.g. PaymentsService.foo) to its entry in the file's options { services { ... } } block. Resolves across any indexed .ck file in the workspace. Placing the cursor on the method segment (the foo in PaymentsService.foo) jumps straight to that method in the TypeScript service source. The service's module path is resolved relative to the TS plugin's server.baseDir (from contractkit.config.json) via the generated server's package.json imports map or the nearest tsconfig.json compilerOptions.paths, mapping the compiled .js back to .ts.
• Document symbols outline — contract and operation declarations show in the breadcrumb / outline panel
• Workspace symbols (Cmd+T) — jump to any contract, route, or service declaration across the workspace, filtered by query
• Document formatting — Format Document runs the ContractKit prettier printer over the file
• Document links — Cmd+click on https://, file://, and relative ./ paths inside string literals (e.g. plugin extension templates)
• Folding ranges — collapse contract, operation, options, and inline object blocks; consecutive comment lines fold as a region
• Find all references / Document highlights — right-click → Find All References, or Cmd+F2 to highlight every occurrence of a model or service name in the current document
• CodeLens reference counts — every model and service declaration shows a "N references" lens that opens the references peek view on click
• Rename Symbol (F2) — renames a model or service across every file in the workspace. Validates the new name is a legal ContractKit identifier and rejects collisions with existing symbols.
• Code Actions — quick-fixes for missing-override (insert override), spurious-override (remove override), and unknown-model (offer fuzzy-matched name suggestions) diagnostics
• Signature help — parameter docs inside scalar constraint calls like string(min=...), int(min, max), discriminated(by=...)
• Inlay hints — show inherited field names next to a model declaration that has bases (e.g. contract Admin: User & { displays + name, email inline)
• Semantic tokens — precise classification of keywords, modifiers, scalar types, model names (as class), and service names (as interface) for richer highlighting
• Live diagnostics — parser errors and warnings as you type, now with stable diagnostic codes that quick-fixes dispatch on
• Cross-file model index — referenced models from other open .ck files participate in completion and hover
• ContractKit Explorer view in the Explorer sidebar — browse every endpoint and model across the workspace, grouped by file/area/HTTP method (or flat). Tooltips show description, source location, and per-group warning counts.
• Filter & grouping — title-bar buttons let you filter by path/name/method/sdk/service and switch the grouping mode (persisted per workspace)
• Right-click actions on tree nodes — Reveal in Editor, Copy Path (METHOD /route), Copy as cURL
• API preview panel — click any tree node to open a Stoplight-style detail panel beside the editor showing description, params, request/response schemas (with inline-expandable model refs), security badges, plugin extensions, and source-jump buttons. Lives refreshes on edit.
• Overview endpoints list — the API Overview page shows a collapsible list of every operation grouped by area (method badge, route, and optional human-readable name). Areas auto-expand when there are three or fewer; click any row to open that operation in its own panel.
• Markdown in descriptions — description: blocks render with paragraphs, headings, lists, fenced code, bold/italic, inline code, and http(s) links (in the preview panel and tree tooltips).
• Try-it-out — every operation card includes a collapsible form prefilled with the schema's path params, query, headers, and (for JSON bodies) an editable body textarea. Send button fires the request from the extension host (Node fetch, full network access), shows status/headers/body in-place.
• Status bar — left-aligned entry shows the API title, endpoint and model counts, and a warning badge. Click to open the preview.

Requires VS Code or Cursor 1.105.1+.

Which files are indexed

Cross-file features (go-to-definition, references, rename, the Explorer, the preview, and cross-file diagnostics) work from an index of .ck files on disk. A file is indexed when:

1. Git doesn't ignore it. The index reads .gitignore files at every level, plus .git/info/exclude, so .ck copies in dist/, build/, or any other ignored folder stay out. node_modules and .git are always skipped. Global excludes (core.excludesFile) are not read.
2. Its config compiles it. When the nearest contractkit.config.json above the file lists patterns and its rootDir contains the file, the file is indexed only if one of those patterns matches it, the same set contractkit compiles. With no config, no patterns, or a rootDir that doesn't contain the file, only rule 1 applies.

A file open in the editor is always indexed while it's open. Editing a .gitignore or a config re-indexes the workspace, and so does Refresh Explorer.

Installation

The extension is workspace-internal and built/installed from source:

# From the repo root
pnpm run vscode:install

# To uninstall
pnpm run vscode:uninstall

The install script packages the extension with vsce, then installs the resulting .vsix into the local code (or cursor) binary.

Settings

Commands

Right-click on tree nodes also surfaces Reveal in Editor, Copy Path, and Copy as cURL (operations only).

Architecture

The extension is split into a thin client and a Language Server, communicating over LSP.

Maintaining the syntax grammar

The TextMate grammar must accept the same character classes as the Ohm parser. When packages/contractkit/src/contractkit.ohm changes, update syntaxes/ck.tmLanguage.json accordingly and re-run pnpm run vscode:install to reload locally.