goextract

Documentation

Overview

Package goextract provides tools for extracting Go standard library API surface into versioned JSON registry files for use by the Code Pathfinder SAST engine.

Index

• Constants
• type Config
• type Constant
• type Extractor
  • func NewExtractor(cfg Config) *Extractor
  • func (e *Extractor) ExtractSinglePackage(packageDir, importPath string) (*Package, error)
  • func (e *Extractor) Run() error
• type Function
• type FunctionParam
• type Manifest
• type Package
• type PackageEntry
• type RegistryStats
• type ReturnValue
• type StructField
• type Type
• type TypeParam
• type Variable
• type VersionInfo

Constants

const GeneratorVersion = "1.0.0"

GeneratorVersion is the version of this extraction tool.

Types

type Config

type Config struct {
	// GoVersion is the Go version being extracted (e.g., "1.21", "1.26.0").
	GoVersion string
	// GOROOT is the path to the Go installation root (e.g., "/usr/local/go").
	GOROOT string
	// OutputDir is the directory where JSON registry files will be written.
	OutputDir string
}

Config holds the configuration for the stdlib extractor.

type Constant

type Constant struct {
	Name       string  `json:"name"`
	Type       string  `json:"type"`
	Value      string  `json:"value"`
	IsIota     bool    `json:"is_iota"`
	Confidence float32 `json:"confidence"`
	Docstring  string  `json:"docstring"`
}

Constant represents an exported constant declaration.

type Extractor

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

Extractor extracts the exported API surface of Go stdlib packages and writes versioned JSON registry files compatible with GoStdlibRegistry.

func NewExtractor

func NewExtractor(cfg Config) *Extractor

NewExtractor creates a new Extractor with the given configuration.

func (*Extractor) ExtractSinglePackage

func (e *Extractor) ExtractSinglePackage(packageDir, importPath string) (*Package, error)

ExtractSinglePackage extracts type metadata from a single Go package directory. Unlike Run (which processes the entire Go stdlib tree), this operates on a single directory path supplied by the caller (e.g., a `go mod download` cache path).

Parameters:

• packageDir: absolute path to the package source directory
• importPath: the Go import path (e.g., "gorm.io/gorm")

Files named *_test.go are excluded. Individual files that fail to parse (e.g., due to cgo directives or build-constrained syntax) are skipped silently so the method returns the best-effort API surface of the remaining files. Returns an error if packageDir cannot be read or contains no .go source files.

func (*Extractor) Run

func (e *Extractor) Run() error

Run executes the full extraction pipeline: discover packages, extract each one, write per-package JSON files, and write the manifest.

type Function

type Function struct {
	Name          string           `json:"name"`
	Signature     string           `json:"signature"`
	Params        []*FunctionParam `json:"params"`
	Returns       []*ReturnValue   `json:"returns"`
	IsVariadic    bool             `json:"is_variadic"`
	IsGeneric     bool             `json:"is_generic"`
	TypeParams    []*TypeParam     `json:"type_params"`
	ReceiverType  string           `json:"receiver_type"`
	Confidence    float32          `json:"confidence"`
	Docstring     string           `json:"docstring"`
	Deprecated    bool             `json:"deprecated"`
	DeprecatedMsg string           `json:"deprecated_msg"`
}

Function represents an exported function or method declaration.

type FunctionParam

type FunctionParam struct {
	Name       string `json:"name"`
	Type       string `json:"type"`
	IsVariadic bool   `json:"is_variadic"`
}

FunctionParam represents a single parameter in a function signature.

type Manifest

type Manifest struct {
	SchemaVersion    string          `json:"schema_version"`
	RegistryVersion  string          `json:"registry_version"`
	GoVersion        VersionInfo     `json:"go_version"`
	GeneratedAt      string          `json:"generated_at"`
	GeneratorVersion string          `json:"generator_version"`
	BaseURL          string          `json:"base_url"`
	Packages         []*PackageEntry `json:"packages"`
	Statistics       *RegistryStats  `json:"statistics"`
}

Manifest contains registry metadata and the ordered list of extracted packages. It is written as manifest.json in the output directory.

type Package

type Package struct {
	ImportPath  string               `json:"import_path"`
	GoVersion   string               `json:"go_version"`
	GeneratedAt string               `json:"generated_at"`
	Functions   map[string]*Function `json:"functions"`
	Types       map[string]*Type     `json:"types"`
	Constants   map[string]*Constant `json:"constants"`
	Variables   map[string]*Variable `json:"variables"`
}

Package represents the complete exported API surface of a single stdlib package. It is written as {pkg}_stdlib.json in the output directory.

type PackageEntry

type PackageEntry struct {
	ImportPath    string `json:"import_path"`
	Checksum      string `json:"checksum"`
	FileSize      int64  `json:"file_size"`
	FunctionCount int    `json:"function_count"`
	TypeCount     int    `json:"type_count"`
	ConstantCount int    `json:"constant_count"`
}

PackageEntry represents a single package's metadata entry in the manifest.

type RegistryStats

type RegistryStats struct {
	TotalPackages        int `json:"total_packages"`
	TotalFunctions       int `json:"total_functions"`
	TotalTypes           int `json:"total_types"`
	TotalConstants       int `json:"total_constants"`
	PackagesWithGenerics int `json:"packages_with_generics"`
}

RegistryStats contains aggregate statistics for all extracted packages.

type ReturnValue

type ReturnValue struct {
	Type string `json:"type"`
	Name string `json:"name"`
}

ReturnValue represents a single return value in a function signature.

type StructField

type StructField struct {
	Name     string `json:"name"`
	Type     string `json:"type"`
	Tag      string `json:"tag"`
	Exported bool   `json:"exported"`
}

StructField represents a single exported field in a struct type.

type Type

type Type struct {
	Name       string               `json:"name"`
	Kind       string               `json:"kind"`
	Methods    map[string]*Function `json:"methods"`
	Fields     []*StructField       `json:"fields"`
	Underlying string               `json:"underlying"`
	IsGeneric  bool                 `json:"is_generic"`
	TypeParams []*TypeParam         `json:"type_params"`
	Docstring  string               `json:"docstring"`
}

Type represents an exported type declaration (struct, interface, or alias).

type TypeParam

type TypeParam struct {
	Name       string `json:"name"`
	Constraint string `json:"constraint"`
}

TypeParam represents a generic type parameter (Go 1.18+).

type Variable

type Variable struct {
	Name       string  `json:"name"`
	Type       string  `json:"type"`
	Confidence float32 `json:"confidence"`
	Docstring  string  `json:"docstring"`
}

Variable represents an exported package-level variable declaration.

type VersionInfo

type VersionInfo struct {
	Major       int    `json:"major"`
	Minor       int    `json:"minor"`
	Patch       int    `json:"patch"`
	Full        string `json:"full"`
	ReleaseDate string `json:"release_date"`
}

VersionInfo contains the Go release version details.