Inspecting Data (print & snapshot)
Relevant source files
The following files were used as context for generating this wiki page:
Inspecting data is a critical workflow in the SCIP ecosystem, providing developers and indexer authors with tools to visualize, verify, and debug the contents of SCIP indices. Because SCIP indices are stored in a compact binary Protobuf format, they are not human-readable in their raw form. The scip CLI provides two primary mechanisms for inspection: the print command for quick debugging of index contents and the snapshot command for generating stable, text-based representations of indices used for regression testing.
These tools allow for the identification of indexer bugs, verification of code navigation data (definitions, references, and implementations), and the tracking of changes in index semantics over time. Sources: Development.md:46-52, README.md:16-18
The print Command
The print command is the primary tool for ad-hoc debugging of SCIP indices. It converts the binary Protobuf data into a human-readable format. By default, it provides a colorized textual output, but it also supports JSON output for programmatic consumption.
Functionality and Logic
The command reads a SCIP index file (typically index.scip) and iterates through its components, including metadata, documents, and external symbols. It provides a high-level view of the index structure without requiring the local source code to be present.
This diagram shows the flow of data when using the scip print command. Sources: cmd/scip/main.go:21, CHANGELOG.md:126-128
Key Features
| Feature | Description | Source |
|---|---|---|
| Colorized Output | Provides visual highlights for different SCIP entities. Can be disabled via --color=false or NO_COLOR=1. | CHANGELOG.md:111-113 |
| JSON Support | Emits JSON instead of text using the --json flag. | CHANGELOG.md:126-128 |
| Streaming Support | Built on Go bindings that support streaming parsing for better memory management. | CHANGELOG.md:133-136 |
The snapshot Command
The snapshot command generates a "pretty-printed" version of the source code interleaved with SCIP information. This is specifically designed for snapshot testing, where the output is checked into version control and compared against future runs to detect regressions.
Snapshot Generation Architecture
Unlike print, the snapshot command requires access to the original source files. It reads the SCIP index to find occurrences and then reads the corresponding source code on disk to create a merged view.
The snapshot generation process involves merging binary index data with local source code. Sources: bindings/go/scip/testutil/format.go:27-50
Interleaving Logic
The formatting logic iterates through the source code line by line. For every SCIP Occurrence, it inserts a comment line (using configurable syntax) directly below the code line. These comments use carets (^) to point to the exact range of the occurrence and provide details such as:
- Symbol Name: The unique SCIP symbol string.
- Role: Whether the occurrence is a definition, reference, or forward definition.
- Documentation: Documentation strings or overrides.
- Diagnostics: Any warnings or errors associated with that range.
- Enclosing Ranges: Visual markers (
⌄and⌃) for the start and end of scopes.
Sources: bindings/go/scip/testutil/format.go:88-158, CHANGELOG.md:129-131
Snapshot Configuration
Snapshots can be customized using CLI flags to accommodate different language syntaxes and project structures.
| Flag | Purpose | Default |
|---|---|---|
--comment-syntax | Defines the string used for inline comments (e.g., //, #, --). | // |
--project-root | Overrides the project root path stored in the index metadata. | Index Metadata |
--from | Path to the SCIP index file to snapshot. | index.scip |
Sources: cmd/scip/main.go:81-105, CHANGELOG.md:129-131
Implementation Details (Go Bindings)
The core logic for data inspection resides in the testutil package within the Go bindings.
FormatSnapshots Function
The FormatSnapshots function in format.go is the entry point for generating multiple snapshots from an index. It handles the resolution of the localSourcesRoot, which defaults to the path in the index metadata but can be overridden if the index was generated on a different machine.
Sources: bindings/go/scip/testutil/format.go:27-56
Range Comparison
To ensure stable and predictable snapshot output, occurrences must be sorted before interleaving. SCIP uses a specific comparison logic for ranges:
- Primary: Start line
- Secondary: Start character
- Tertiary: Range length (multiline vs. single line)
- Quaternary: End line and character
Sources: bindings/go/scip/testutil/format.go:207-224
Summary
Data inspection via print and snapshot provides the transparency needed to build and maintain high-quality SCIP indexers. While print serves as a quick window into the binary index, snapshot provides a robust, source-anchored view suitable for automated testing and detailed manual review of code intelligence metadata. Sources: Development.md:46-52, README.md:16-18