proto

Documentation

Overview

Package proto implements the CKG parser for `.proto` files (schema 1.9 W3a).

Design (schema-1.9-spec §6.4): dependency-free hand-rolled lexer + recursive- descent parser. The proto3 grammar is small enough that pulling in tree-sitter is overkill, but we cross-checked our token set + production list against the community grammar at github.com/coder3101/tree-sitter-proto/blob/main/grammar.js so production names and token boundaries align with mainstream tooling.

Scope (W3a): emit nodes/edges for service/rpc/message/enum/field/package. gRPC server/client detection in Go/TS lives in W3b/W3c — out of scope here. The parser produces parse.ParseResult exactly like every other language parser; the cross-language linker can later wire up rpc_calls/listens_on against these proto nodes by qualified-name suffix match.

Index

• type Parser
  • func New(srcRoot string) *Parser
  • func (p *Parser) Extensions() []string
  • func (p *Parser) ParseFile(path string, src []byte) (*parse.ParseResult, error)
  • func (p *Parser) Resolve(results []*parse.ParseResult) (*parse.ResolvedGraph, error)

Types

type Parser

type Parser struct {
	// contains filtered or unexported fields
}

Parser implements parse.Parser for `.proto` files. Stateless across files — safe for concurrent ParseFile dispatch from buildpipe.

V0 produces a flat node set (Service, Method, MessageType, Field, Enum, Package, File) with `defines` + `contains` parent/child wiring. Cross-file resolution (`uses_type` from rpc Request/Response → MessageType nodes in other proto files) happens in Resolve.

func New

func New(srcRoot string) *Parser

New returns a Parser rooted at srcRoot (used for relative file paths so Node.FilePath is consistent with the other language parsers).

func (*Parser) Extensions

func (p *Parser) Extensions() []string

Extensions reports the file extensions this parser handles.

func (*Parser) ParseFile

func (p *Parser) ParseFile(path string, src []byte) (*parse.ParseResult, error)

ParseFile runs Pass 1 over a single `.proto` file.

Recovery strategy: malformed declarations are skipped at the top-level recovery boundary (skipToTopLevel). The parser never returns an error for in-file syntax — it falls through to the next top-level keyword. This matches the "best-effort INFERRED" handling spec §6.4 calls for, and means a single bad proto file in a monorepo doesn't break the build.

func (*Parser) Resolve

func (p *Parser) Resolve(results []*parse.ParseResult) (*parse.ResolvedGraph, error)

Resolve unions per-file results and wires `uses_type` edges from rpc methods to MessageType nodes whose qualified_name matches the pending target. Same-file matches stay EXTRACTED; cross-file matches are tagged INFERRED (mirrors the Solidity / TypeScript resolvers).

proto3 type names inside a service block can be:

• bare ("EchoRequest"): resolves against the file's own package first, then any other proto's package.
• fully-qualified (".pkg.sub.EchoRequest" or "pkg.sub.EchoRequest"): resolves by exact qname match.

We try the package-prefixed form first, then bare-name fallback. Multiple candidates are kept ordered (deterministic — sorted by ID) and the first wins. Ambiguity beyond that is tagged AMBIGUOUS so audits can surface it.