scip

package
v0.4.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 8, 2026 License: Apache-2.0 Imports: 9 Imported by: 0

Documentation

Overview

Package scip reads SCIP (Sourcegraph Code Intelligence Protocol) indexes and projects them into one fixed fact schema.

SCIP is the language-neutral index format a per-language indexer writes: scip-go, scip-typescript, scip-python, scip-java and scip-rust each emit an index.scip file describing the documents they indexed, the symbols those documents define, and every occurrence of a symbol in a document. The format is one protobuf schema for every language, so a reader written once serves all of them; only the symbol scheme and the document's language string differ.

This package has three parts, and the mine stage of the bootstrap loop uses all three:

  • The wire decode reads the SCIP index: Unmarshal and ReadFile decode the gzipped protobuf an indexer wrote into the Index model in wire.go. It reads the schema with encoding/protowire rather than a generated binding, so the package takes no dependency beyond the protobuf runtime the module already has; the decode test reads a fixture a real indexer wrote, so the field numbers are guarded against a real indexer's output.
  • The symbol grammar parses a SCIP symbol string (ParseSymbol) into its scheme, package and descriptors, per the grammar the SCIP schema documents.
  • The fixed fact schema s0 projects an Index into facts (Facts) and checks that a fact stream conforms to the schema (Check). SchemaS0 names every relation and its arity; a fact is one relation applied to arguments with the source span it came from.

Index

Constants

View Source 
const (
	SchemaS0Name    = "s0"
	SchemaS0Version = "1"
)

SchemaS0Name and SchemaS0Version name the schema the facts carry.

View Source 
const (
	RoleDefinition        int32 = 0x1
	RoleImport            int32 = 0x2
	RoleWriteAccess       int32 = 0x4
	RoleReadAccess        int32 = 0x8
	RoleGenerated         int32 = 0x10
	RoleTest              int32 = 0x20
	RoleForwardDefinition int32 = 0x40
)

SymbolRole is the bitset SCIP sets on an occurrence. The values are the bits the SCIP schema assigns; a role is present when its bit is set.

Variables

View Source 
var DeclaredLanguages = []string{"go", "typescript", "python", "java", "rust"}

DeclaredLanguages is the language set the mine stage covers: the indexers that exist for the bootstrap loop, one per language a foreign repository is most likely to be written in. A repository whose index reports a language outside this set is refused rather than silently half-mined.

View Source 
var SchemaS0 = map[string]int{
	"schema":       2,
	"language":     1,
	"document":     1,
	"symbol":       4,
	"occurrence":   4,
	"relationship": 4,
}

SchemaS0 is the fixed fact schema the mine stage emits. It is fixed so that every stage downstream of the mine stage reads the same relations no matter which language a foreign repository is written in: the reorientation stage (#538) compares two repositories only through these names.

The relation set is the smallest one that still carries the two things the induce stage needs: what the repository declares (its public surface) and what it uses. A symbol's suffix comes from the SCIP symbol grammar, not from a language-specific kind, so the same relation serves all five languages.

Functions

func Check 

func Check(facts []Fact) error

Check verifies that a fact stream conforms to SchemaS0: every relation is one the schema declares, every relation has its declared arity, and the stream is not empty. It returns the first offending fact. An empty fact stream is a finding, not a pass: a gate over zero facts would report clean without looking.

func SymbolSuffix 

func SymbolSuffix(symbol string) string

SymbolSuffix is the grammar suffix of a symbol's last descriptor, or "unspecified" when the symbol does not parse. It derives the symbol's kind from the symbol string alone, so it needs no per-language kind table.

Types

type Descriptor 

type Descriptor struct {
	Name          string
	Disambiguator string
	Suffix        Suffix
}

Descriptor is one node in a symbol's fully qualified name. Name is the identifier and Suffix is the character that ended it in the grammar.

type Document 

type Document struct {
	RelativePath string
	Language     string
	Occurrences  []Occurrence
	Symbols      []SymbolInformation
}

Document is one indexed source file.

type Fact 

type Fact struct {
	Relation string
	Args     []string
	// Span is the document and 0-based line the fact was extracted from. It is
	// empty for facts about the index itself (schema, the language list).
	Span SourceSpan
}

A Fact is one relation from the fixed schema s0 applied to arguments. The span records where the fact came from, so a checker can point at the source line that produced a bad fact rather than only at the fact.

func Facts 

func Facts(index Index, languages []string) ([]Fact, error)

Facts projects a decoded index into the fixed fact schema s0. languages is the declared coverage set: a document whose language is not in it is refused, so an index built by an indexer this stage does not know fails loudly instead of contributing a partial fact set.

Facts is deterministic: the same index yields the same facts in the same order, so two runs over one repository compare equal, which is what the reorientation stage relies on.

func (Fact) String 

func (f Fact) String() string

String renders a fact the way the bootstrap archive stores it, one fact per line: the relation, then each argument separated by tabs, then the source.

type Index 

type Index struct {
	Metadata  Metadata
	Documents []Document
}

Index is a decoded SCIP index.

func ReadFile 

func ReadFile(path string) (Index, error)

ReadFile decodes the SCIP index a .scip file holds. A SCIP file is the Index message gzipped; a little endian gzip stream is the only framing.

func Unmarshal 

func Unmarshal(data []byte) (Index, error)

Unmarshal decodes SCIP index bytes, gzipped or not. An indexer always gzips, but a fixture and an in-memory index are sometimes raw, so both are accepted.

type Metadata 

type Metadata struct {
	ToolName    string
	ToolVersion string
	ProjectRoot string
}

Metadata is the index's metadata: which tool wrote it and where its root is.

type Occurrence 

type Occurrence struct {
	Symbol      string
	SymbolRoles int32
	Range       Range
}

Occurrence is one appearance of a symbol in a document.

func (Occurrence) HasRole 

func (o Occurrence) HasRole(role int32) bool

HasRole reports whether the occurrence carries the role bit.

type Range 

type Range struct {
	StartLine      int32
	StartCharacter int32
	EndLine        int32
	EndCharacter   int32
}

Range is a half-open [start, end) source range, 0-based.

type Relationship 

type Relationship struct {
	Symbol           string
	IsReference      bool
	IsImplementation bool
	IsTypeDefinition bool
	IsDefinition     bool
}

Relationship is a named edge from a symbol to another symbol.

type SourceSpan 

type SourceSpan struct {
	Document string
	Line     int
}

SourceSpan names the document and 0-based line a fact was extracted from.

type Suffix 

type Suffix int

Suffix is the grammar's node-kind marker: the character that ends a symbol descriptor and says what the descriptor names. 

const (
	SuffixUnspecified Suffix = iota
	SuffixNamespace
	SuffixType
	SuffixTerm
	SuffixMethod
	SuffixTypeParameter
	SuffixParameter
	SuffixMeta
	SuffixMacro
)

The descriptor suffixes the SCIP symbol grammar defines.

func (Suffix) String 

func (s Suffix) String() string

String returns the grammar's name for the suffix.

type Symbol 

type Symbol struct {
	Local   bool
	LocalID string

	Scheme      string
	Manager     string
	Package     string
	Version     string
	Descriptors []Descriptor
}

Symbol is a parsed SCIP symbol string. A local symbol has Local set and only LocalID; every other symbol has a scheme, a package, and one or more descriptors forming its fully qualified name.

func ParseSymbol 

func ParseSymbol(text string) (Symbol, error)

ParseSymbol parses a SCIP symbol string per the grammar scip.proto documents: 

<symbol>   ::= <scheme> ' ' <package> ' ' (<descriptor>)+ | 'local ' <local-id>
<package>  ::= <manager> ' ' <package-name> ' ' <version>

A space inside a name is escaped as two spaces and a backtick as two backticks; a name containing a suffix character is wrapped in backticks.

func (Symbol) PackagePath 

func (s Symbol) PackagePath() string

PackagePath is the package part of the symbol, "manager/name@version".

type SymbolInformation 

type SymbolInformation struct {
	Symbol        string
	Kind          int32
	Documentation []string
	Relationships []Relationship
}

SymbolInformation is what the index knows about a symbol, a document defines.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.