goast

package
v0.1.0-dev.20260818001638 Latest Latest
Warning

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

 Go to latest Published: Aug 18, 2026 License: Apache-2.0 Imports: 22 Imported by: 0

Documentation

Overview

Package goast provides Go AST operations as a Starlark receiver.

+devlore:access=immediate

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type CallArg 

type CallArg struct {
	Position    int    `starlark:"position"`
	StringValue string `starlark:"string_value"`
	IdentName   string `starlark:"ident_name"`
}

CallArg holds information about a call argument.

type CallResult 

type CallResult struct {
	Name      string    `starlark:"name"`
	Qualifier string    `starlark:"qualifier"`
	FullName  string    `starlark:"full_name"`
	Line      int       `starlark:"line"`
	Args      []CallArg `starlark:"args"`
}

CallResult holds information about a function/method call.

type CallableResult 

type CallableResult struct {
	Name    string        `starlark:"name"`
	Doc     string        `starlark:"doc"`
	Params  []ParamDetail `starlark:"params"`
	Returns string        `starlark:"returns"`
}

CallableResult holds information about a function type declaration.

type CommentDecl 

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

CommentDecl represents a floating comment not attached to any declaration.

func (*CommentDecl) DeclComment 

func (cd *CommentDecl) DeclComment() DocComment

DeclComment returns nil — the comment IS the declaration, not attached to one.

Returns:

  • `DocComment`: always the zero value.

func (*CommentDecl) DeclKind 

func (cd *CommentDecl) DeclKind() string

DeclKind returns "comment".

+devlore:property

Returns:

  • `string`: always "comment".

func (*CommentDecl) DeclName 

func (cd *CommentDecl) DeclName() string

DeclName returns empty — floating comments have no name.

Returns:

  • `string`: always the empty string.

func (*CommentDecl) DeclStyle 

func (cd *CommentDecl) DeclStyle() CommentStyle

DeclStyle returns the comment style.

Returns:

  • `CommentStyle`: the comment's style.

func (*CommentDecl) Style 

func (cd *CommentDecl) Style() CommentStyle

Style returns the comment style.

Returns:

  • `CommentStyle`: the comment's style.

func (*CommentDecl) Text 

func (cd *CommentDecl) Text() string

Text returns the comment text without // prefix.

Returns:

  • `string`: the rendered comment text.

type CommentStyle 

type CommentStyle int

CommentStyle identifies how a comment is classified for formatting. 

const (
	// StyleCopyright is an SPDX + Copyright header. Verbatim.
	StyleCopyright CommentStyle = iota
	// StyleDelineator is a separator line (3+ repeated =, -, ~, *). Verbatim.
	StyleDelineator
	// StyleRegionMarker is a region/endregion marker. Verbatim.
	StyleRegionMarker
	// StyleSectionHeader is a short label like "// Fallible actions". Verbatim.
	StyleSectionHeader
	// StylePackageDoc is a package-level doc comment. Taxonomy pipeline, summary/body split.
	StylePackageDoc
	// StyleImportDoc is an import declaration doc comment.
	StyleImportDoc
	// StyleProse is a multi-line floating comment. go/doc/comment fill and wrap.
	StyleProse
	// StyleFuncDoc is a function/method doc comment. Taxonomy pipeline.
	StyleFuncDoc
	// StyleGenDeclDoc is a type/var/const doc comment. Taxonomy pipeline.
	StyleGenDeclDoc
)

type ComplianceViolation 

type ComplianceViolation struct {
	Name    string `starlark:"name"`
	Kind    string `starlark:"kind"`
	Message string `starlark:"message"`
}

ComplianceViolation represents a single style check result.

type CompositeResult 

type CompositeResult struct {
	TypeName string         `starlark:"type_name"`
	Line     int            `starlark:"line"`
	Fields   map[string]any `starlark:"fields"`
}

CompositeResult holds information about a composite literal.

type ConstDetail 

type ConstDetail struct {
	Name  string `starlark:"name"`
	Value string `starlark:"value"`
	Line  int    `starlark:"line"`
}

ConstDetail holds information about a single constant.

type ConstEntryDetail 

type ConstEntryDetail struct {
	Name  string `starlark:"name"`
	Value string `starlark:"value"`
}

ConstEntryDetail holds name and value for a single constant in a group.

Mirrors the go/ast field-struct shape: data is read directly off exported fields, which the starlark bridge projects as read-only properties (no getters, no codegen).

type ConstGroupResult 

type ConstGroupResult struct {
	TypeName  string        `starlark:"type_name"`
	File      string        `starlark:"file"`
	Constants []ConstDetail `starlark:"constants"`
}

ConstGroupResult holds information about a typed const group.

type Consumes 

type Consumes struct {
	Min   int      // minimum count (0 for optional, 1 for required)
	Max   int      // maximum count (-1 for unbounded)
	Types []string // allowed block types: "Paragraph", "Heading", "Code", "List"
}

Consumes defines what block types a production accepts and how many. Parsed from ABNF-like notation in schema config.

func ParseConsumes 

func ParseConsumes(s string) (Consumes, error)

ParseConsumes parses an ABNF-like consumes string into a Consumes struct.

Grammar: 

consumes = [repeat] types
repeat   = "*"            → min=0, max=-1
         | number "*"     → min=number, max=-1
         | number "*" number → min=first, max=second
types    = type *("/" type)
         | "(" type *("/" type) ")"
type     = "Paragraph" | "Heading" | "Code" | "List"

Examples: 

"Paragraph"              → {1, 1, [Paragraph]}
"Paragraph / Heading"    → {1, 1, [Paragraph, Heading]}
"*Paragraph"             → {0, -1, [Paragraph]}
"*(Paragraph / Code)"    → {0, -1, [Paragraph, Code]}
"1*Paragraph"            → {1, -1, [Paragraph]}
"0*1Paragraph"           → {0, 1, [Paragraph]}
"0*1Paragraph List"      → sequence (not yet supported — use separate elements)

func (Consumes) Matches 

func (c Consumes) Matches(blockType string) bool

Matches returns true if the given block type is in the allowed set.

type Decl 

type Decl interface {
	DeclName() string
	DeclKind() string
	DeclComment() DocComment
	DeclStyle() CommentStyle
}

Decl is any top-level declaration in source order.

type DepsResult 

type DepsResult struct {
	Files         []FileDep `starlark:"files"`
	ModulePath    string    `starlark:"module_path"`
	AllImports    []string  `starlark:"all_imports"`
	InternalDeps  []string  `starlark:"internal_deps"`
	ExternalDeps  []string  `starlark:"external_deps"`
	StdlibDeps    []string  `starlark:"stdlib_deps"`
	InternalCount int       `starlark:"internal_count"`
	ExternalCount int       `starlark:"external_count"`
	StdlibCount   int       `starlark:"stdlib_count"`
}

DepsResult holds aggregated dependency information for a path.

type DocComment 

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

DocComment is the mutable doc comment attached to a declaration.

func (DocComment) Style 

func (dc DocComment) Style() CommentStyle

Style returns the comment style.

Returns:

  • `CommentStyle`: the comment's style.

func (DocComment) Text 

func (dc DocComment) Text() any

Text returns the comment text without // prefix, or nil if no comment is present.

Returns:

  • `any`: the rendered comment text as a `string`, or nil when no comment is present.

type FieldDetail 

type FieldDetail struct {
	Name        string `starlark:"name"`
	JSONName    string `starlark:"json_name"`
	Type        string `starlark:"type"`
	Required    bool   `starlark:"required"`
	Description string `starlark:"description"`
	Embedded    bool   `starlark:"embedded"`
}

FieldDetail holds information about a struct field.

type FileDep 

type FileDep struct {
	Path         string         `starlark:"path"`
	Package      string         `starlark:"package"`
	Imports      []ImportDetail `starlark:"imports"`
	InternalDeps []string       `starlark:"internal_deps"`
	ExternalDeps []string       `starlark:"external_deps"`
	StdlibDeps   []string       `starlark:"stdlib_deps"`
}

FileDep holds dependency information for a single file.

type FileMetric 

type FileMetric struct {
	Path          string `starlark:"path"`
	LOC           int    `starlark:"loc"`
	SLOC          int    `starlark:"sloc"`
	Comments      int    `starlark:"comments"`
	Blanks        int    `starlark:"blanks"`
	Functions     int    `starlark:"functions"`
	Methods       int    `starlark:"methods"`
	Structs       int    `starlark:"structs"`
	Interfaces    int    `starlark:"interfaces"`
	Types         int    `starlark:"types"`
	Constants     int    `starlark:"constants"`
	Variables     int    `starlark:"variables"`
	Imports       int    `starlark:"imports"`
	TestFunctions int    `starlark:"test_functions"`
}

FileMetric holds code metrics for a single file.

type FuncDecl 

type FuncDecl struct {
	Name    string        `starlark:"name"`    // function/method name
	Params  []ParamDetail `starlark:"params"`  // parameters
	Returns string        `starlark:"returns"` // return type string
	// contains filtered or unexported fields
}

FuncDecl represents a function or method declaration.

func (*FuncDecl) Comment 

func (fd *FuncDecl) Comment() DocComment

Comment returns the doc comment.

Returns:

  • `DocComment`: the function's doc comment.

func (*FuncDecl) DeclComment 

func (fd *FuncDecl) DeclComment() DocComment

DeclComment returns the doc comment.

Returns:

  • `DocComment`: the function's doc comment.

func (*FuncDecl) DeclKind 

func (fd *FuncDecl) DeclKind() string

DeclKind returns "func" or "method".

+devlore:property

Returns:

  • `string`: "method" when the declaration has a receiver, otherwise "func".

func (*FuncDecl) DeclName 

func (fd *FuncDecl) DeclName() string

DeclName returns the function or method name.

Returns:

  • `string`: the declared name.

func (*FuncDecl) DeclStyle 

func (fd *FuncDecl) DeclStyle() CommentStyle

DeclStyle returns the comment style.

Returns:

  • `CommentStyle`: the doc comment's style.

func (*FuncDecl) ReceiverType 

func (fd *FuncDecl) ReceiverType() string

ReceiverType returns the receiver type name, or empty for top-level functions.

Returns:

  • `string`: the receiver type name, or the empty string for a top-level function.

type FuncResult 

type FuncResult struct {
	Name       string            `starlark:"name"`
	Returns    string            `starlark:"returns"`
	Params     []ParamDetail     `starlark:"params"`
	TypeParams []TypeParamDetail `starlark:"type_params"`
	File       string            `starlark:"file"`
	Line       int               `starlark:"line"`
	Doc        string            `starlark:"doc"`
	Scope      string            `starlark:"scope"`
}

FuncResult holds information about a top-level function declaration.

type GenDeclNode 

type GenDeclNode struct {
	Name    string             `starlark:"name"`    // declared name (first spec)
	Methods []*FuncDecl        `starlark:"methods"` // methods on this type (TYPE decls)
	Entries []ConstEntryDetail `starlark:"entries"` // const entries (CONST decls)
	// contains filtered or unexported fields
}

GenDeclNode represents a general declaration (type, var, const, import).

Wraps *ast.GenDecl. One entry per GenDecl in the tree, regardless of how many specs it contains.

func (*GenDeclNode) Comment 

func (gd *GenDeclNode) Comment() DocComment

Comment returns the doc comment.

Returns:

  • `DocComment`: the declaration's doc comment.

func (*GenDeclNode) DeclComment 

func (gd *GenDeclNode) DeclComment() DocComment

DeclComment returns the doc comment.

Returns:

  • `DocComment`: the declaration's doc comment.

func (*GenDeclNode) DeclKind 

func (gd *GenDeclNode) DeclKind() string

DeclKind returns "type", "var", "const", or "import".

+devlore:property

Returns:

  • `string`: the lowercased token kind.

func (*GenDeclNode) DeclName 

func (gd *GenDeclNode) DeclName() string

DeclName returns the name of the first spec (type name, var name, const name, or "import").

Returns:

  • `string`: the declared name.

func (*GenDeclNode) DeclStyle 

func (gd *GenDeclNode) DeclStyle() CommentStyle

DeclStyle returns the comment style.

Returns:

  • `CommentStyle`: the doc comment's style.

func (*GenDeclNode) GetMethod 

func (gd *GenDeclNode) GetMethod(name string) *FuncDecl

GetMethod returns a method by name, or nil if not found.

Parameters:

  • `name`: the method name to look up.

Returns:

  • `*FuncDecl`: the matching method, or nil.

func (*GenDeclNode) Kind 

func (gd *GenDeclNode) Kind() token.Token

Kind returns the token type (token.TYPE, token.VAR, token.CONST, token.IMPORT).

Returns:

  • `token.Token`: the declaration's token kind.

func (*GenDeclNode) Specs 

func (gd *GenDeclNode) Specs() []ast.Spec

Specs returns the underlying ast.Spec slice.

Returns:

  • `[]ast.Spec`: the declaration's specs.

type ImportDetail 

type ImportDetail struct {
	Path  string `starlark:"path"`
	Alias string `starlark:"alias"`
	Line  int    `starlark:"line"`
}

ImportDetail holds information about a single import.

type LineViolation 

type LineViolation struct {
	Line    int    `starlark:"line"`
	Message string `starlark:"message"`
}

LineViolation holds a single line-width check result.

type Match 

type Match struct {
	Slot   string
	Item   string
	Score  float64
	Forced bool // assigned by elimination, not by score
}

Match represents a slot-to-item assignment produced by assignSlots.

type MethodResult 

type MethodResult struct {
	Name         string            `starlark:"name"`
	ReceiverType string            `starlark:"receiver_type"`
	Returns      string            `starlark:"returns"`
	Params       []ParamDetail     `starlark:"params"`
	TypeParams   []TypeParamDetail `starlark:"type_params"`
	File         string            `starlark:"file"`
	Line         int               `starlark:"line"`
	Doc          string            `starlark:"doc"`
	Scope        string            `starlark:"scope"`
}

MethodResult holds information about a method declaration.

type MetricsResult 

type MetricsResult struct {
	Files              []FileMetric `starlark:"files"`
	FileCount          int          `starlark:"file_count"`
	TotalLOC           int          `starlark:"total_loc"`
	TotalSLOC          int          `starlark:"total_sloc"`
	TotalComments      int          `starlark:"total_comments"`
	TotalBlanks        int          `starlark:"total_blanks"`
	TotalFunctions     int          `starlark:"total_functions"`
	TotalMethods       int          `starlark:"total_methods"`
	TotalStructs       int          `starlark:"total_structs"`
	TotalInterfaces    int          `starlark:"total_interfaces"`
	TotalTypes         int          `starlark:"total_types"`
	TotalConstants     int          `starlark:"total_constants"`
	TotalVariables     int          `starlark:"total_variables"`
	TotalImports       int          `starlark:"total_imports"`
	TotalTestFunctions int          `starlark:"total_test_functions"`
}

MetricsResult holds aggregated code metrics for a path.

type ParamDetail 

type ParamDetail struct {
	Name     string `starlark:"name"`
	Type     string `starlark:"type"`
	Variadic bool   `starlark:"variadic"`
	Doc      string `starlark:"doc"`
}

ParamDetail holds information about a function parameter.

type Production 

type Production interface {
	Execute(blocks []comment.Block, cursor int, elem doctaxonomy.SchemaElement, ctx styleContext) (output []comment.Block, next int)
}

Production transforms a slice of comment blocks according to a schema element. It consumes blocks starting at cursor, produces output blocks, and returns the new cursor position.

func NewProduction 

func NewProduction(elem doctaxonomy.SchemaElement) (Production, error)

NewProduction creates a Production from a schema element's production type and consumes string.

type Provider 

type Provider struct {
	op.ProviderBase
	// contains filtered or unexported fields
}

Provider provides Go AST operations as a Starlark receiver.

+devlore:access=immediate

func NewProvider 

func NewProvider(ctx *op.RuntimeEnvironment) *Provider

NewProvider creates a new Provider. Validates that all six comment styles have handlers in the merged config. Missing styles are repaired from defaults with a warning. Declares interest in the "config" variable so the resolver populates it from the [application.Application]'s source maps at construction time.

func (*Provider) Callable 

func (p *Provider) Callable(path, name string) (CallableResult, error)

Callable introspects a named function type declaration and returns its parameter list, return type, and doc comment (including directives).

func (*Provider) Calls 

func (p *Provider) Calls(scope, name string) ([]CallResult, error)

Calls returns function/method calls within a scope.

+devlore:defaults name=

func (*Provider) CheckLineWidth 

func (p *Provider) CheckLineWidth(content string, width int) ([]LineViolation, error)

CheckLineWidth checks content for line-width violations.

Reports over-long lines and under-filled comment lines (where the next word would fit on the current line without exceeding width).

func (*Provider) Composites 

func (p *Provider) Composites(scope, typeName string) ([]CompositeResult, error)

Composites returns composite literals within a scope.

+devlore:defaults typeName=

func (*Provider) ConstGroups 

func (p *Provider) ConstGroups(path, typeName string) ([]ConstGroupResult, error)

ConstGroups returns typed const groups from Go source files.

+devlore:defaults typeName=

func (*Provider) Deps 

func (p *Provider) Deps(path string) (DepsResult, error)

Deps analyzes import dependencies for Go source files at the given path.

func (*Provider) Format 

func (p *Provider) Format(code string) (string, error)

Format formats Go source code via go/format.

func (*Provider) Funcs 

func (p *Provider) Funcs(path, name string) ([]FuncResult, error)

Funcs returns function declarations (non-method) from Go source.

The path parameter accepts either a file/directory path or Go source content directly.

+devlore:defaults name=

func (*Provider) LoadSourceFile 

func (p *Provider) LoadSourceFile(path string) (*SourceFile, error)

LoadSourceFile reads a Go source file from disk and parses it into a semantic tree organized by declaration kind. The returned SourceFile supports iteration, name-based lookup, and style operations (Reformat, Save, CheckStyle). Styling config (schemas, spacing rules, line width) is read from context.

Parameters:

  • path: the file path to read.

Returns:

  • *SourceFile: the semantic tree.
  • error: non-nil if the file cannot be read or parsed.

func (*Provider) Methods 

func (p *Provider) Methods(path, name, receiverType, returns string) ([]MethodResult, error)

Methods returns method declarations from Go source.

The path parameter accepts either a file/directory path or Go source content directly.

+devlore:defaults name=,receiverType=,returns=

func (*Provider) Metrics 

func (p *Provider) Metrics(path string) (MetricsResult, error)

Metrics computes code metrics for Go source files at the given path.

func (*Provider) RawString 

func (p *Provider) RawString(scope string) (string, error)

RawString extracts the first backtick string literal from a scope.

func (*Provider) Render 

func (p *Provider) Render(template string, data any) (string, error)

Render executes a Go text/template against data and returns go/format-formatted Go source code.

func (*Provider) ReturnString 

func (p *Provider) ReturnString(scope string) (string, error)

ReturnString extracts the string literal from a return statement in a scope.

func (*Provider) ReturnStrings 

func (p *Provider) ReturnStrings(scope string) ([]string, error)

ReturnStrings extracts string elements from a []string{...} return statement in a scope.

func (*Provider) SortDeclarations 

func (p *Provider) SortDeclarations(path, scope, order string) (string, error)

SortDeclarations reorders function/method declarations within a scope of a Go file.

Preserves doc comments and blank lines attached to each declaration. Returns the modified file content.

func (*Provider) Structs 

func (p *Provider) Structs(path string) ([]StructResult, error)

Structs returns struct definitions from Go source files.

func (*Provider) TypeDoc 

func (p *Provider) TypeDoc(path, name string) (string, error)

TypeDoc returns the doc comment for a named type declaration.

+devlore:defaults name=

type SourceFile 

type SourceFile struct {
	PackageName string         `starlark:"package_name"` // package name
	Types       []*GenDeclNode `starlark:"types"`        // type declarations
	Vars        []*GenDeclNode `starlark:"vars"`         // var declarations
	Consts      []*GenDeclNode `starlark:"consts"`       // const declarations
	Funcs       []*FuncDecl    `starlark:"funcs"`        // top-level functions (no receiver)
	Decls       []Decl         `starlark:"decls"`        // all declarations in source order
	// contains filtered or unexported fields
}

SourceFile is the semantic tree for a single Go source file.

Mirrors the go/ast field-struct shape: parsed data is exposed on exported fields (which the starlark bridge projects as read-only properties), while methods are reserved for actions (Cleanup/Save) and parameterized lookups (GetType/GetFunc). The exported fields are precomputed at LoadSourceFile and immutable thereafter.

func LoadSourceFile 

func LoadSourceFile(content string) (*SourceFile, error)

LoadSourceFile parses Go source content and builds a semantic tree.

Parameters:

  • `content`: the Go source text to parse.

Returns:

  • `*SourceFile`: the constructed semantic tree.
  • `error`: non-nil if the content fails to parse, or a floating comment cannot be classified.

func (*SourceFile) CheckCompliance 

func (sf *SourceFile) CheckCompliance() []ComplianceViolation

CheckCompliance reports style violations. No mutation, no I/O.

Returns:

  • `[]ComplianceViolation`: one entry per violation; empty when the tree is compliant.

func (*SourceFile) Cleanup 

func (sf *SourceFile) Cleanup()

Cleanup dispatches the single styler for each declaration based on its node type.

func (*SourceFile) GetFunc 

func (sf *SourceFile) GetFunc(name string) *FuncDecl

GetFunc returns a function declaration by name, or nil if not found.

Parameters:

  • `name`: the function name to look up.

Returns:

  • `*FuncDecl`: the matching function, or nil.

func (*SourceFile) GetType 

func (sf *SourceFile) GetType(name string) *GenDeclNode

GetType returns a type GenDecl by name, or nil if not found.

Parameters:

  • `name`: the type name to look up.

Returns:

  • `*GenDeclNode`: the matching type declaration, or nil.

func (*SourceFile) Name 

func (sf *SourceFile) Name() string

Name returns the filename.

Returns:

  • `string`: the source file's name.

func (*SourceFile) Save 

func (sf *SourceFile) Save() error

Save serializes the tree to the original file.

Returns:

  • `error`: any error from writing the file.

func (*SourceFile) SaveAs 

func (sf *SourceFile) SaveAs(path string) error

SaveAs serializes the tree to the specified path.

Parameters:

  • `path`: the destination file path.

Returns:

  • `error`: any error from writing the file.

type SpacingRules 

type SpacingRules struct {
	AfterPackage        int `yaml:"after_package"`
	AfterImports        int `yaml:"after_imports"`
	BetweenFunctions    int `yaml:"between_functions"`
	BetweenMethods      int `yaml:"between_methods"`
	BeforeTypeMethods   int `yaml:"before_type_methods"`
	AroundRegionMarkers int `yaml:"around_region_markers"`
	AroundDelineators   int `yaml:"around_delineators"`
}

SpacingRules controls blank lines between declarations.

Named settings following the JetBrains IDEA model. Each value is the number of blank lines to insert in that context.

func DefaultSpacingRules 

func DefaultSpacingRules() SpacingRules

DefaultSpacingRules returns spacing rules with all settings at 1 blank line.

Returns:

  • `SpacingRules`: spacing rules with every setting at 1.

type StructResult 

type StructResult struct {
	Name   string        `starlark:"name"`
	File   string        `starlark:"file"`
	Line   int           `starlark:"line"`
	Fields []FieldDetail `starlark:"fields"`
}

StructResult holds information about a struct type declaration.

type TypeParamDetail 

type TypeParamDetail struct {
	Name       string   `starlark:"name"`
	Constraint []string `starlark:"constraint"`
}

TypeParamDetail holds a generic type parameter and its constraint's type-set members.

For `[T *starlark.Function | string]`, Name is "T" and Constraint is ["*starlark.Function", "string"]. A non-union constraint such as `[T any]` yields a single member ("any"); an approximation term `~int` keeps its `~` prefix.

Source Files

View all Source files

Directories

Path Synopsis
Package doctaxonomy defines the documentation schema the goast provider enforces.
 Package doctaxonomy defines the documentation schema the goast provider enforces.

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.