lint

Documentation

Index

• func All() []string
• func MatchGlob(pattern, path string) bool
• func Register(name string, constructor func() Module)
• func ResolveCacheDir(rootDir string, configDir string) string
• type Cache
  • func (c *Cache) Clear() error
  • func (c *Cache) Get(key string, maxAge time.Duration) ([]Finding, bool)
  • func (c *Cache) Key(content []byte, moduleName string, configJSON string) string
  • func (c *Cache) Put(key string, findings []Finding) error
• type CacheTTLModule
• type ConfigurableModule
• type Delta
  • func (d *Delta) ChangedFiles(ctx context.Context) (map[string]bool, error)
• type Engine
  • func NewEngine(cfg config.LintConfig, rootDir string, moduleNames []string, ...) (*Engine, error)
  • func (e *Engine) CollectFiles() ([]FileInfo, error)
  • func (e *Engine) ModuleNames() []string
  • func (e *Engine) Run(ctx context.Context, files []FileInfo) ([]Finding, error)
  • func (e *Engine) RunWithStats(ctx context.Context, files []FileInfo) ([]Finding, []ModuleStats, error)
• type FileInfo
  • func FilterByDelta(files []FileInfo, changedSet map[string]bool) []FileInfo
• type Finding
• type Module
  • func Get(name string) (Module, error)
• type ModuleStats
• type Severity
  • func (s Severity) String() string

Functions

func All

func All() []string

All returns sorted names of all registered modules.

func MatchGlob

func MatchGlob(pattern, path string) bool

MatchGlob matches a glob pattern supporting ** against a forward-slash path. Patterns and paths should use "/" separators. Exported wrapper so modules can reuse the engine's glob semantics.

func Register

func Register(name string, constructor func() Module)

Register adds a module constructor to the global registry. Called from init() in each module file.

func ResolveCacheDir

func ResolveCacheDir(rootDir string, configDir string) string

ResolveCacheDir determines the cache directory using the following precedence:

1. STAGEFREIGHT_CACHE_DIR env var (used as-is, caller controls the path)
2. configDir from .stagefreight.yml cache_dir (resolved relative to rootDir)
3. os.UserCacheDir()/stagefreight/<project-hash>/lint (XDG-aware default)

The project hash is a truncated SHA-256 of the absolute rootDir path, keeping per-project caches isolated without long nested directory names.

Types

type Cache

type Cache struct {
	Dir     string
	Enabled bool
}

Cache provides content-addressed lint result caching. Dir is the resolved cache directory (call ResolveCacheDir to compute it).

func (*Cache) Clear

func (c *Cache) Clear() error

Clear removes the entire cache directory.

func (*Cache) Get

func (c *Cache) Get(key string, maxAge time.Duration) ([]Finding, bool)

Get retrieves cached findings. Returns nil, false on cache miss. maxAge controls TTL: 0 means no expiry (content-only modules), >0 expires entries older than the duration (external-state modules).

func (*Cache) Key

func (c *Cache) Key(content []byte, moduleName string, configJSON string) string

Key computes a cache key from file content, module name, and config.

func (*Cache) Put

func (c *Cache) Put(key string, findings []Finding) error

Put stores findings in the cache.

type CacheTTLModule

type CacheTTLModule interface {
	CacheTTL() time.Duration
}

CacheTTLModule controls time-based cache expiry.

Modules that do not implement this interface are cached forever.

Semantics:

>0  → cache with expiry (e.g. 5*time.Minute)
 0  → cache forever (content-hash only)
<0  → never cache (always re-run)

type ConfigurableModule

type ConfigurableModule interface {
	Module
	Configure(opts map[string]any) error
}

ConfigurableModule is implemented by modules that accept YAML options. The engine calls Configure after construction if the module's config section contains an options map.

type Delta

type Delta struct {
	RootDir      string
	TargetBranch string
	Verbose      bool
}

Delta detects changed files relative to a baseline.

func (*Delta) ChangedFiles

func (d *Delta) ChangedFiles(ctx context.Context) (map[string]bool, error)

ChangedFiles returns the list of files changed relative to the baseline. In CI mode, it diffs against STAGEFREIGHT_TARGET_BRANCH (or auto-detects). Locally, it diffs against HEAD (uncommitted + staged changes) plus committed changes not in the default branch. Returns nil (scan everything) if git is unavailable or no baseline exists.

type Engine

type Engine struct {
	Config  config.LintConfig
	RootDir string
	Modules []Module
	Cache   *Cache
	Verbose bool

	CacheHits   atomic.Int64
	CacheMisses atomic.Int64
}

Engine orchestrates lint modules across files.

func NewEngine

func NewEngine(cfg config.LintConfig, rootDir string, moduleNames []string, skipNames []string, verbose bool, cache *Cache) (*Engine, error)

NewEngine creates a lint engine with the selected modules.

func (*Engine) CollectFiles

func (e *Engine) CollectFiles() ([]FileInfo, error)

CollectFiles walks the root directory and returns FileInfo for all regular files.

func (*Engine) ModuleNames

func (e *Engine) ModuleNames() []string

ModuleNames returns the names of all active modules in this engine.

func (*Engine) Run

func (e *Engine) Run(ctx context.Context, files []FileInfo) ([]Finding, error)

Run executes all modules against the given files and returns findings.

func (*Engine) RunWithStats

func (e *Engine) RunWithStats(ctx context.Context, files []FileInfo) ([]Finding, []ModuleStats, error)

RunWithStats executes all modules and returns findings plus per-module statistics.

type FileInfo

type FileInfo struct {
	Path    string // relative path from repo root
	AbsPath string // absolute path on disk
	Size    int64
}

FileInfo is passed to each module for inspection.

func FilterByDelta

func FilterByDelta(files []FileInfo, changedSet map[string]bool) []FileInfo

FilterByDelta filters a file list to only include changed files. If changedSet is nil, returns all files (full scan).

type Finding

type Finding struct {
	File     string
	Line     int
	Column   int
	Module   string
	Severity Severity
	Message  string
}

Finding represents a single lint result.

type Module

type Module interface {
	Name() string
	Check(ctx context.Context, file FileInfo) ([]Finding, error)
	DefaultEnabled() bool
	AutoDetect() []string // glob patterns that trigger auto-enable
}

Module is the interface every lint check implements.

func Get

func Get(name string) (Module, error)

Get returns a new instance of the named module.

type ModuleStats

type ModuleStats struct {
	Name     string
	Files    int
	Cached   int
	Findings int
	Critical int
	Warnings int
}

ModuleStats holds per-module scan statistics.

type Severity

type Severity int

Severity indicates how serious a finding is.

const (
	SeverityInfo Severity = iota
	SeverityWarning
	SeverityCritical
)

func (Severity) String

func (s Severity) String() string