Skip to content

Language Support

Jump to bottom
Lisa edited this page Dec 25, 2025 · 6 revisions

Language Support

CKB works with any language, but the depth of analysis varies based on available tooling.

How CKB Analyzes Code

CKB combines multiple sources of code intelligence:

Source What it provides Speed
SCIP Index Pre-computed symbol map with all definitions, references, and relationships Instant
LSP Real-time queries to a language server Fast (may timeout on large queries)
Git Blame, history, churn, ownership Fast
Heuristics File patterns, naming conventions, import scanning Instant

The SCIP index is the key differentiator. Languages with a SCIP indexer get precise, complete analysis. Languages without one fall back to LSP or heuristics.

Support Tiers

Standard Tier (SCIP available)

Full code intelligence with precise, pre-computed data.

Features:

  • Precise symbol search (no false positives)
  • Complete reference finding
  • Accurate call graphs (callers and callees)
  • Impact analysis with confidence scores
  • Dead code detection
  • Symbol justification (keep/investigate/remove)

Languages:

Language Indexer Install
Go scip-go go install github.com/sourcegraph/scip-go/cmd/scip-go@latest
TypeScript/JavaScript scip-typescript npm install -g @sourcegraph/scip-typescript
Python scip-python pip install scip-python
Java scip-java scip-java docs
Kotlin scip-java scip-java docs (Gradle plugin required)
Rust rust-analyzer rust-analyzer docs
C/C++ scip-clang scip-clang releases
Dart scip_dart dart pub global activate scip_dart (note: underscore, not hyphen)
Ruby scip-ruby scip-ruby docs
C# scip-dotnet scip-dotnet docs (.NET 8+)
PHP scip-php scip-php docs (PHP 8.2+)

Run ckb index to auto-detect your language and run the appropriate indexer.

Language Quality Tiers (v7.3)

CKB classifies languages into quality tiers based on indexer maturity, known issues, and accuracy metrics. This helps you understand what to expect from each language.

Tier Overview

Tier Guarantee Languages
Tier 1 (Full) Full support, all features, stable Go
Tier 2 (Standard) Full support, known edge cases TypeScript, JavaScript, Python
Tier 3 (Basic) Basic support, callgraph may be incomplete Rust, Java, Kotlin, C++, Ruby, Dart
Tier 4 (Experimental) Experimental, use with caution C#, PHP

Known Issues by Language

Go (Tier 1)

  • No known issues
  • Full support with scip-go

TypeScript/JavaScript (Tier 2)

  • Monorepo with multiple tsconfig may need --infer-tsconfig
  • Path aliases require tsconfig.json
  • Dynamic imports may not be tracked
  • CommonJS require() patterns may have incomplete resolution

Python (Tier 2)

  • Virtual environments must be activated or detected
  • Dynamic imports (importlib) not tracked
  • Type stubs may not be fully resolved

Rust (Tier 3)

  • Macro expansions may have incomplete references
  • Proc macros may not be fully analyzed

Java/Kotlin (Tier 3)

  • Gradle projects may need build task first
  • Annotation processors may have incomplete resolution
  • Kotlin extension functions may have incomplete resolution

C++ (Tier 3)

  • Requires compile_commands.json
  • Templates may have incomplete resolution
  • Macros can affect accuracy

Ruby (Tier 3)

  • Sorbet types improve accuracy
  • Metaprogramming may not be tracked

Dart (Tier 3)

  • Flutter projects need flutter pub get first

C# (Tier 4)

  • Requires .NET 8+ SDK
  • Source generators may have incomplete resolution

PHP (Tier 4)

  • Requires PHP 8.2+
  • Dynamic calls may not be tracked

Quality Assessment API

Use the /meta/languages endpoint to get quality metrics for your project:

curl http://localhost:8080/meta/languages

Response includes:

  • tier: 1-4 rating based on language maturity
  • quality: ok, degraded, partial, or unknown
  • refAccuracy: Estimated reference accuracy (0-1)
  • callGraphQuality: Call graph completeness
  • knownIssues: Language-specific issues to watch for
  • recommendations: Suggestions to improve quality

Python Environment Detection

CKB detects Python virtual environments to provide better recommendations:

curl http://localhost:8080/meta/python-env

If no venv is active, CKB will recommend activating one before indexing:

source .venv/bin/activate && ckb index

TypeScript Monorepo Detection

CKB detects TypeScript monorepo configurations:

curl http://localhost:8080/meta/typescript-monorepo

Detects:

  • pnpm workspaces (pnpm-workspace.yaml)
  • Yarn/npm workspaces (package.json with workspaces)
  • Lerna (lerna.json)
  • Nx (nx.json)
  • Per-package tsconfig status

For monorepos, CKB recommends using scip-typescript --infer-tsconfig.

Fast Tier (LSP/tree-sitter only)

Real-time analysis via language server or tree-sitter. Good for navigation, but slower and less complete for large queries.

Features:

  • Symbol search (may have gaps)
  • Go to definition
  • Find references (within open scope)
  • Limited call graph support

Missing compared to Standard:

  • Complete cross-file reference finding
  • Accurate call graphs
  • Impact analysis confidence
  • Dead code detection

When you're in this tier:

  • Language has an LSP server but no SCIP indexer
  • SCIP indexer exists but isn't installed
  • SCIP index wasn't generated yet

How to check: Run ckb status - if you see "SCIP: not available" but "LSP: available", you're in Fast tier.

Minimal Tier (Heuristics only)

File-based analysis using patterns and naming conventions. Works for any language but limited depth.

Features:

  • Module detection (finds package boundaries)
  • Import scanning (understands dependencies)
  • File role classification (test, config, entrypoint)
  • Architecture overview (module graph)
  • Git-based features (ownership, hotspots, blame)

Missing compared to Fast:

  • Symbol-level navigation
  • Reference finding
  • Call graphs

When you're in this tier:

  • No SCIP indexer available
  • No LSP server configured
  • Unsupported or niche language

Feature Matrix

Feature Standard Fast Minimal
Symbol search Precise Partial -
Go to definition Yes Yes -
Find all references Complete Partial -
Call graph Yes Limited -
Impact analysis High confidence Low confidence -
Dead code detection Yes - -
Module detection Yes Yes Yes
Architecture overview Yes Yes Yes
Ownership (CODEOWNERS) Yes Yes Yes
Ownership (git blame) Yes Yes Yes
Hotspot detection Yes Yes Yes
File role classification Yes Yes Yes

Upgrading Your Tier

From Minimal to Fast

Configure an LSP server in .ckb/config.json:

{
  "lsp": {
    "servers": {
      "your-language": {
        "command": "your-language-server",
        "args": ["--stdio"]
      }
    }
  }
}

From Fast to Standard

  1. Install the SCIP indexer for your language (see table above)
  2. Run ckb index or the indexer directly
  3. Verify with ckb status

Special Cases

C/C++

C++ requires a compilation database (compile_commands.json) because the indexer needs to know compiler flags, include paths, and preprocessor defines.

Generate it with:

# CMake
cmake -DCMAKE_EXPORT_COMPILE_COMMANDS=ON -B build .

# Meson
meson setup build

# Make (via Bear)
bear -- make

The compilation database is typically created in build/ or similar. CKB searches common locations automatically.

Then run: scip-clang --compdb-path=build/compile_commands.json

Note: scip-clang must run from the project root directory, even if compile_commands.json is in a subdirectory.

Multi-language Projects

CKB supports one SCIP index per project. For polyglot repos:

  1. Index the primary language
  2. Other languages fall back to LSP or heuristics
  3. Git-based features (ownership, hotspots) work for all files

Future versions may support merging multiple SCIP indexes.

Generated Code

Generated files (protobuf, GraphQL, etc.) should be generated before indexing:

go generate ./...
ckb index

Otherwise generated symbols won't appear in the index.

Checking Your Setup

# See what's available
ckb status

# Diagnose issues
ckb doctor

Example output for Standard tier:

Backends:
  SCIP: available (47,832 symbols indexed)
  LSP: available (go language server)
  Git: available (1,247 commits)

Example output for Fast tier:

Backends:
  SCIP: not available (run 'ckb index' to generate)
  LSP: available (typescript-language-server)
  Git: available (892 commits)

Tier-Specific Diagnostics (v7.2)

Use ckb doctor --tier to check if your environment is ready for a specific analysis tier:

# Check enhanced tier requirements
ckb doctor --tier enhanced

# Check full tier requirements (SCIP + LSP)
ckb doctor --tier full

Example output:

CKB Doctor - Enhanced Tier Requirements
=============================================

Go: Y Ready
  Y scip-go v1.0.0

TypeScript: N Not Ready
  N scip-typescript not found
    Suggested install: npm install -g @sourcegraph/scip-typescript

Summary: 1/2 languages ready for enhanced tier.

What it shows:

  • Which tools are installed for each detected language
  • Tool versions and paths
  • Missing tools with install commands
  • Per-language tier status (ready or not ready)

Tier names: You can use either naming convention:

  • basic or fast — Tree-sitter only
  • enhanced or standard — SCIP indexers
  • full — SCIP + LSP servers

This is useful when setting up a new machine or troubleshooting why certain capabilities aren't available.

Adding Support for New Languages

If your language has a SCIP indexer that CKB doesn't know about:

  1. Run the indexer manually to generate index.scip
  2. CKB will detect and use it automatically
  3. Consider opening an issue to add it to ckb index

If no SCIP indexer exists for your language:

Summary

Your situation Tier What to do
Indexer installed, index generated Standard You're all set
Indexer available, not installed Fast Run ckb index
No indexer, but LSP available Fast Configure LSP in config
No indexer, no LSP Minimal Git features still work

Most popular languages have SCIP indexers. Run ckb index and you'll likely get Standard tier automatically.

Related Pages

Clone this wiki locally