api

Documentation

Overview

Package api is the public, library-shaped surface of Semantic Firewall. The CLI in cmd/sfw and the MCP server in the sibling semantic_firewall_mcp repo both consume it; everything in internal/cli is implementation glue that orchestrates flag parsing and process boundaries on top of the entry points defined here.

The entry points return the same JSON-serialisable types from pkg/models that the CLI prints, so callers can either marshal them directly or inspect the structured values in-process.

Index

• func CalculateTopologyDelta(oldT, newT *topology.FunctionTopology) (string, int)
• func CompareFunctions(funcName string, oldResult, newResult diff.FingerprintResult) models.FunctionDiff
• func Diff(oldPath, newPath string) (*models.DiffOutput, error)
• func DiffWithFS(fsys FileSystem, oldPath, newPath string) (*models.DiffOutput, error)
• func ShortFunctionName(fullName string) string
• type FileSystem
• type RealFileSystem
  • func (RealFileSystem) Abs(path string) (string, error)
  • func (RealFileSystem) Getwd() (string, error)
  • func (RealFileSystem) Open(name string) (fs.File, error)
  • func (RealFileSystem) ReadFile(name string) ([]byte, error)
  • func (RealFileSystem) Stat(name string) (os.FileInfo, error)
  • func (RealFileSystem) WalkDir(root string, fn fs.WalkDirFunc) error

Functions

func CalculateTopologyDelta

func CalculateTopologyDelta(oldT, newT *topology.FunctionTopology) (string, int)

CalculateTopologyDelta diffs two function topologies and returns a short human label plus a heuristic risk score. Adding goroutines, loops, or external calls weighs the score up; removing structure is neutral.

func CompareFunctions

func CompareFunctions(funcName string, oldResult, newResult diff.FingerprintResult) models.FunctionDiff

CompareFunctions reduces two FingerprintResult values to a FunctionDiff. When the canonical IR fingerprints match the function is preserved verbatim; otherwise the Zipper algorithm computes the structural delta, falling back to "modified" if SSA reconstruction fails.

func Diff

func Diff(oldPath, newPath string) (*models.DiffOutput, error)

Diff is the convenience entry point: it computes a semantic diff between two on-disk Go source files using the real filesystem. Either path may be empty or non-existent to represent an added or removed file.

func DiffWithFS

func DiffWithFS(fsys FileSystem, oldPath, newPath string) (*models.DiffOutput, error)

DiffWithFS performs a semantic diff against the supplied FileSystem so tests can drive the pipeline without touching disk. Behaviour is identical to Diff otherwise.

func ShortFunctionName

func ShortFunctionName(fullName string) string

ShortFunctionName strips package paths and qualifying identifiers from a Go SSA function name so it is readable in diffs and reports.

It handles three shapes:

• "fmt.Println" -> "Println"
• "pkg.(*Type).Method" / "(*pkg.Type).Method" -> "(*Type).Method"
• Generics like "pkg.Func[a/b.T]" -> "Func[a/b.T]"

Brackets and parens are tracked so qualified types inside generic parameters or receiver positions are preserved verbatim.

Types

type FileSystem

type FileSystem interface {
	Stat(name string) (os.FileInfo, error)
	Open(name string) (fs.File, error)
	Getwd() (string, error)
	Abs(path string) (string, error)
	WalkDir(root string, fn fs.WalkDirFunc) error
	ReadFile(name string) ([]byte, error)
}

FileSystem abstracts the OS file operations the analysis pipeline needs. Production code uses RealFileSystem; tests can substitute a mock to drive the pipeline without touching disk.

type RealFileSystem

type RealFileSystem struct{}

RealFileSystem is the production FileSystem implementation backed by the os and filepath packages. ReadFile bounds the read at models.MaxSourceFileSize so a hostile/oversize input cannot exhaust memory.

func (RealFileSystem) Abs

func (RealFileSystem) Abs(path string) (string, error)

func (RealFileSystem) Getwd

func (RealFileSystem) Getwd() (string, error)

func (RealFileSystem) Open

func (RealFileSystem) Open(name string) (fs.File, error)

func (RealFileSystem) ReadFile

func (RealFileSystem) ReadFile(name string) ([]byte, error)

func (RealFileSystem) Stat

func (RealFileSystem) Stat(name string) (os.FileInfo, error)

func (RealFileSystem) WalkDir

func (RealFileSystem) WalkDir(root string, fn fs.WalkDirFunc) error