Debugging Indexers
Relevant source files
The following files were used as context for generating this wiki page:
Debugging indexers is a critical part of the SCIP ecosystem. Because SCIP is a transmission format designed to ease the creation of producers, the protocol provides several tools and subcommands to inspect, validate, and verify the correctness of generated indexes. These tools help developers identify off-by-one errors in ranges, non-canonical symbols, or structural issues within the Protobuf payload.
Sources: DESIGN.md:20-22, Development.md:46-48
Inspection and Validation Tools
The scip CLI provides several subcommands specifically for developers working on new indexers. These tools allow for both high-level statistical overviews and low-level structural analysis.
The print and lint Commands
scip print: Used to inspect the binary Protobuf output in a human-readable format. It can emit colorful textual output or JSON.scip lint: Performs well-formedness checks on an index. It identifies correctness issues, such as missing symbol information for occurrences or redundant relationships. It is primarily intended for indexer authors.
Sources: Development.md:49-65, cmd/scip/lint.go:15-22
Statistical Analysis
The scip stats command generates a JSON report containing metrics about the index, which helps identify if an indexer is producing an expected volume of data.
| Metric | Description |
|---|---|
documents | Total number of documents in the index. |
linesOfCode | Total lines of code across all indexed files. |
occurrences | Total number of occurrences (definitions and references). |
definitions | Count of occurrences marked with the Definition role. |
documentSizes | Statistics (mean, max, percentiles) of the document payload sizes in bytes. |
Sources: cmd/scip/stats.go:81-89, cmd/scip/stats.go:102-125
Validation Logic (Linting)
The linting system builds a symbolic representation of the index to find inconsistencies. The following diagram illustrates the flow of the lint command as it processes an index.
The diagram shows the sequential validation phases performed by the lint command to ensure internal consistency of the SCIP index.
Sources: cmd/scip/lint.go:37-75
Common Linting Errors
The lint tool catches several technical violations of the SCIP schema:
- Empty Strings: Checks for empty symbol names or document paths where they are required.
- Non-Canonical Symbols: Ensures symbol strings follow the strict SCIP grammar.
- Broken Relationships: Flags symbols that reference related symbols not present in the index or external symbols.
- Duplicate Information: Detects repeated
SymbolInformationfor the same symbol or overlapping occurrences.
Sources: cmd/scip/lint.go:200-280
Snapshot Testing
Snapshot testing is the primary method for verifying the semantic correctness of an indexer. It involves rendering a SCIP index into a "pretty-printed" text format where symbols and roles are shown as comments directly inside the source code.
Rendering Snapshots
The FormatSnapshot function reads the original source file and interleaves SCIP data using a specific comment syntax (e.g., # for Python/Repro).
This sequence shows how SCIP metadata is merged with source text to create a human-verifiable snapshot.
Sources: bindings/go/scip/testutil/format.go:61-90
Snapshot Syntax Features
^(Caret): Points to the exact range of an occurrence on the line above.⌄ enclosing_range_start: Indicates the beginning of an AST node's enclosing range.role: Displays whether the occurrence is adefinition,reference, orforward_definition.documentation: Includes docstrings or override documentation associated with the symbol.
Sources: bindings/go/scip/testutil/format.go:115-180
Internal Testing with Reprolang
For investigating SCIP to LSIF desugaring or testing new SCIP semantics, the project uses reprolang. This is a small, verbose language specifically designed for SCIP CLI testing.
- Small Scope: Reprolang produces much smaller LSIF indexes than real-world languages, making it easier to manually inspect the data flow.
- Absolute Paths: The command
go test ./cmd/scip -update-snapshots -debug-snapshot-abspathsallows generating snapshots that can be uploaded to a local Sourcegraph instance for live testing.
Sources: Development.md:15-18, Development.md:83-93, cmd/scip/main_test.go:71-75
Summary
Debugging SCIP indexers relies on a combination of automated structural linting and human-readable snapshot testing. By using scip lint to ensure schema compliance and scip print or snapshot formatting to verify semantic accuracy, developers can ensure high-fidelity code navigation. The inclusion of reprolang further assists in isolating indexer logic from the complexities of production programming languages.
Sources: DESIGN.md:37-38, Development.md:46-50