guards

Documentation

Overview

Package guards finds the "why" layer of a flow: If branches that terminate the function with an error. Semantic guards (business conditions, permission gates, validation) become decision nodes with explicit fail exits; mechanical `if err != nil` propagation only marks the failing call as fallible. The classifier errs toward mechanical: a missed guard is a smaller failure than a noisy map.

Index

• func Annotate(f *graph.Flow, p *loader.Program)
• func ExtractDTOs(f *graph.Flow)
• func FieldValidations(fn *ssa.Function) map[string]string
• func SuccessResponse(fn *ssa.Function) string
• func ValidationChecks(call *ssa.Call) string
• type ExitError
  • func (e ExitError) Display() string
  • func (e ExitError) Key() string
• type Guard
  • func Analyze(p *loader.Program, fn *ssa.Function) []Guard

Functions

func Annotate

func Annotate(f *graph.Flow, p *loader.Program)

func ExtractDTOs

func ExtractDTOs(f *graph.Flow)

ExtractDTOs fills the root node's request/response contracts, including per-field validation rules gathered from the handler body.

func FieldValidations

func FieldValidations(fn *ssa.Function) map[string]string

FieldValidations maps request-struct field names to their rules, from every validation call inside fn (feeds the request-body table).

func SuccessResponse

func SuccessResponse(fn *ssa.Function) string

SuccessResponse reports how fn completes successfully over HTTP: a return-position response call with a constant status below 400 ("HTTP 200"). Empty when the function does not respond that way.

func ValidationChecks

func ValidationChecks(call *ssa.Call) string

ValidationChecks renders what a validation call enforces, e.g. "phone — required, length(11, 11), digit". Empty when call is not a recognized validation entrypoint.

Types

type ExitError

type ExitError struct {
	Kind    string // "sentinel" | "message" | "unknown"
	Name    string // sentinel var name
	Message string // verbatim format string, incl. non-ASCII and %s/%v verbs
	Pos     token.Pos
}

ExitError identifies the error a fail branch returns.

func (ExitError) Display

func (e ExitError) Display() string

Display renders the exit for humans: sentinel name, else message, else a generic marker.

func (ExitError) Key

func (e ExitError) Key() string

Key is the dedupe identity used when unifying with error_exits.

type Guard

type Guard struct {
	CondText string
	StmtPos  token.Pos // enclosing if-statement: dedupe key and display pos
	// OrderPos is the layout anchor: for `if err := call(); err != nil`
	// the guard logically runs AFTER the call it checks, even though the
	// if-keyword precedes it on the line.
	OrderPos  token.Pos
	FailWhen  bool // condition value that takes the exit branch
	PassBlock *ssa.BasicBlock
	Exit      ExitError
	Uses      []string // module calls (same function) feeding the condition
	// UsesFns: the SSA functions behind Uses — annotate exempts them from
	// drop rules (guard evidence must never be filtered away).
	UsesFns    []*ssa.Function
	Mechanical bool
	// CondFromAST: condition text came from source (false = raw SSA form).
	CondFromAST bool
	// FailedCall is set for mechanical guards: the call whose error is
	// being propagated (its node gets the fallible badge).
	FailedCall *ssa.Function
	// Checks: validation rules this guard enforces, when its condition is
	// a validation call.
	Checks string
	// Branch: set by annotate when BOTH sides of a gate hold work — an
	// exclusive either/or path split.
	Branch bool
	// Gate: neither branch exits, but one side holds work the other skips
	// ("if !whiteListClient { call accounting }"). PassBlock is the working
	// side (settled by annotate, which sees the flow); SkipBlock the other.
	// For gates FailWhen is the condition value that SKIPS the work.
	Gate      bool
	SkipBlock *ssa.BasicBlock
}

Guard is one If whose one branch terminates the function with an error.

func Analyze

func Analyze(p *loader.Program, fn *ssa.Function) []Guard

Analyze finds guards in fn, deduplicated by source if-statement (&&/|| lower to several SSA branches). Functions that cannot return an error have no guards by definition.