gopkg

Documentation

Overview

Package gopkg is the native Go adapter. It uses stdlib go/ast and go/parser: free, exact, no bindings, and the reason M0 ships without tree-sitter (spec §3.3).

Instrumentation for the Go adapter: a scratch copy of the tree is rewritten so that each changed function reports its own calls and returns. Lives here, with the parser, rather than in the engine — the engine knows only that some adapters rewrite and some attach through the environment.

Index

• func Hash(norm []byte) string
• type Adapter
  • func New() *Adapter
  • func (a *Adapter) CallEdges(path string, src []byte) ([]bundle.Edge, error)
  • func (a *Adapter) Comments(path string, src []byte) ([]bundle.Comment, error)
  • func (a *Adapter) Extensions() []string
  • func (a *Adapter) Instrument(scratchRoot string, ids, context []bundle.SymbolID) (trace.Instrumented, error)
  • func (a *Adapter) Name() string
  • func (a *Adapter) Normalise(src []byte) ([]byte, error)
  • func (a *Adapter) ParseSymbols(path string, src []byte) ([]bundle.Symbol, error)
  • func (a *Adapter) PublicSurface(path string, src []byte) ([]bundle.SurfaceItem, error)
  • func (a *Adapter) ResolveIdentifier(path string, src []byte, line int, name string) (bundle.Resolution, error)
  • func (a *Adapter) RiskMarkers(path string, src []byte, syms []bundle.Symbol) ([]bundle.RiskMarker, error)
  • func (a *Adapter) ShimSpec(syms []bundle.SymbolID) (trace.ShimSpec, error)

Functions

func Hash

func Hash(norm []byte) string

Hash is the fingerprint function: sha256 over normalised source (spec §6.4).

Types

type Adapter

type Adapter struct{}

func New

func New() *Adapter

func (*Adapter) CallEdges

func (a *Adapter) CallEdges(path string, src []byte) ([]bundle.Edge, error)

CallEdges resolves intra-file calls exactly; cross-file callees are emitted with an unqualified target for the extractor to resolve repo-wide.

func (*Adapter) Comments

func (a *Adapter) Comments(path string, src []byte) ([]bundle.Comment, error)

Comments returns every comment in the file with its line span.

func (*Adapter) Extensions

func (a *Adapter) Extensions() []string

func (*Adapter) Instrument

func (a *Adapter) Instrument(scratchRoot string, ids, context []bundle.SymbolID) (trace.Instrumented, error)

Instrument rewrites a scratch copy of the tree, adding a deferred probe to the top of each changed function. It implements trace.Rewriter: Go cannot be instrumented by dropping in a file and setting an environment variable, so the work lives here, beside the parser that understands the language, rather than in the engine.

The repository itself is never written to. Instrumentation is a property of a trace run, not of the code under audit.

func (*Adapter) Name

func (a *Adapter) Name() string

func (*Adapter) Normalise

func (a *Adapter) Normalise(src []byte) ([]byte, error)

Normalise strips comments and collapses whitespace while preserving identifiers: reformatting must not invalidate a fingerprint, renaming must.

func (*Adapter) ParseSymbols

func (a *Adapter) ParseSymbols(path string, src []byte) ([]bundle.Symbol, error)

ParseSymbols returns every declaration in the file with line spans, docs, body comments, outbound call sites and a normalised fingerprint.

func (*Adapter) PublicSurface

func (a *Adapter) PublicSurface(path string, src []byte) ([]bundle.SurfaceItem, error)

PublicSurface reports the things that break other people when they change: exported declarations, HTTP routes, environment variables and CLI flags.

func (*Adapter) ResolveIdentifier

func (a *Adapter) ResolveIdentifier(path string, src []byte, line int, name string) (bundle.Resolution, error)

ResolveIdentifier says what a name means inside the declaration containing a line: where it was introduced, what it was introduced from, where it is written and read, and — for a call — where it goes.

It is a scope walk, not a text search, because the two disagree constantly. In one real function here, `sym := pc.Symbol_` makes sym derived from a parameter, `p := func(...)` makes p a local closure that a text search reports as a call, and `strings` is a package that a text search reports as a local. A reader clicking those three names deserves three different answers.

It is honest about its own limits: this resolves within one declaration and against the file's imports. It is not a type checker, so a field selected off a value is reported as a field without claiming to know the value's type.

func (*Adapter) RiskMarkers

func (a *Adapter) RiskMarkers(path string, src []byte, syms []bundle.Symbol) ([]bundle.RiskMarker, error)

RiskMarkers runs the AST predicates from spec §6.5. Each predicate is small, mechanical and returns zero or more markers — no scoring, no prose.

func (*Adapter) ShimSpec

func (a *Adapter) ShimSpec(syms []bundle.SymbolID) (trace.ShimSpec, error)

ShimSpec instruments Go by rewriting a scratch copy of the tree: each named symbol gets a deferred probe at function entry. Only the changed set is touched, which is why M2 is nearly free once M0 exists (spec §9.1).