analysis

Documentation

Index

• func CountBySeverity(findings []core.Finding) (errors, warnings, infos int)
• func FormatFindings(findings []core.Finding, style FindingStyle, header string) string
• func RegisteredAnalyzerIDs() []string
• func RuleAnalyzersCheck(idx *knowledge.Index) []string
• type Discovery
• type FileSet
• type FindingStyle
• type Result
• type Scope
  • func ParseScope(s string) Scope
• type Session
  • func NewSession(repo vcs.Repository, commitMsg string, index *knowledge.Index, ...) *Session
  • func (s *Session) Analyze(scope Scope, status *vcs.Status, files FileSet) Result
  • func (s *Session) Discover(scope Scope, status *vcs.Status, files FileSet) *Discovery
  • func (s *Session) Load(d *Discovery) *core.AnalysisContext
• type StageRunner
  • func NewStageRunner(cfg *core.AnalysisConfig) *StageRunner
  • func (r *StageRunner) Register(a core.Analyzer)
  • func (r *StageRunner) RunStages(ctx *core.AnalysisContext) []core.Finding

Functions

func CountBySeverity

func CountBySeverity(findings []core.Finding) (errors, warnings, infos int)

CountBySeverity returns the number of findings at each severity level.

func FormatFindings

func FormatFindings(findings []core.Finding, style FindingStyle, header string) string

FormatFindings renders findings as a text block in the given style, prefixed by header when that is non-empty. It returns the empty string for an empty finding set, so a caller can test the rendered result rather than the slice.

func RegisteredAnalyzerIDs

func RegisteredAnalyzerIDs() []string

RegisteredAnalyzerIDs returns the id of every analyzer declared in analyzerSpecs, across every scope. It reads the spec table directly rather than constructing each analyzer and calling ID(): one builder (the commit emoji analyzer) does real I/O and can return nil, which would silently drop that id from any collection built by constructing first and asking second.

func RuleAnalyzersCheck

func RuleAnalyzersCheck(idx *knowledge.Index) []string

RuleAnalyzersCheck reports every rule whose analyzers: list names an id with no registered analyzer. Matches validate.Check's shape so callers pass it as an extra check instead of validate importing this package.

Types

type Discovery

type Discovery struct {
	Sources       core.SourceProvider
	ChangedFiles  []core.FileChange
	GitHistory    []core.GitCommitEntry
	StagedRenames []core.Rename
}

Discovery holds intermediate project state gathered before building the full AnalysisContext. Separating discovery from loading allows callers to inspect or modify the discovered state before analysis.

type FileSet

type FileSet int

FileSet selects how Discover populates ChangedFiles: from git's worktree status (the fast path the Stop hook and pre-commit hook rely on) or by walking every source file in the project tree (a whole-repo governance run, which the tooling never gets from git status on a clean tree).

const (
	// FileSetChanged populates ChangedFiles from git's worktree status.
	FileSetChanged FileSet = iota
	// FileSetAll populates ChangedFiles by walking the full source tree via
	// Sources, regardless of git status.
	FileSetAll
)

type FindingStyle

type FindingStyle string

FindingStyle selects the layout FormatFindings renders.

const (
	// StyleCLI is the flush-left, uppercase-severity layout the CLI commands
	// print for a human or a git hook to read on stderr.
	StyleCLI FindingStyle = "cli"
	// StyleHook is the indented, lowercase-severity layout embedded in the
	// additionalContext a Claude Code hook emits.
	StyleHook FindingStyle = "hook"
)

type Result

type Result struct {
	// Findings are the findings a caller should act on.
	Findings []core.Finding
	// SuppressedGenerated is how many findings fell in generated files.
	SuppressedGenerated int
}

Result is what one analysis run produced: the findings that survived suppression, plus how many were dropped for living in a generated file. The count is carried rather than discarded because a silent suppression is worse than an inflated total - a reader has to know the panel is filtered.

type Scope

type Scope int

Scope controls which analyzers run and what context is built.

const (
	// ScopeFull runs all registered analyzers with full project context.
	ScopeFull Scope = iota
	// ScopeCommit runs static + AST + commit analyzers for pre-commit hooks.
	ScopeCommit
	// ScopeChanged runs static + AST + arch analyzers over the changed
	// files, skipping external-tool delegation (golangci-lint).
	ScopeChanged
)

func ParseScope

func ParseScope(s string) Scope

ParseScope converts a scope flag string to a Scope value. Unrecognized values, including the empty string, default to ScopeFull.

type Session

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

Session orchestrates the analysis lifecycle: discovery, context loading, and analysis. It replaces ad-hoc entry points with a single path so all callers go through the same code.

func NewSession

func NewSession(
	repo vcs.Repository,
	commitMsg string,
	index *knowledge.Index,
	cfg *config.GovernanceConfig,
) *Session

NewSession creates a session for repo. repo may be nil when no git repository is available (e.g. vcs.Open returned vcs.ErrNoRepository); the session then runs with no git history and no changed-file discovery rather than failing. When cfg is nil, default config is used with the recommended preset applied.

func (*Session) Analyze

func (s *Session) Analyze(scope Scope, status *vcs.Status, files FileSet) Result

Analyze runs the analyzers for scope and returns the findings a caller should act on, plus the count suppressed for generated files. status is the already-computed worktree status; pass nil to let Session read it itself. files selects git-status vs. a full source-tree walk.

func (*Session) Discover

func (s *Session) Discover(scope Scope, status *vcs.Status, files FileSet) *Discovery

Discover gathers project-state information (changed files, git history, staged renames) and returns a Discovery. This phase does no AST parsing.

func (*Session) Load

func (s *Session) Load(d *Discovery) *core.AnalysisContext

Load builds a full AnalysisContext from a Discovery, including AST cache population. Callers may modify the Discovery between Discover and Load.

type StageRunner

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

StageRunner runs registered analyzers grouped by stage.

why: cfg once lived in a second, empty *core.AnalysisContext built only to carry it and prone to drift from the real context RunStages evaluates; storing cfg directly removes that duplicate.

func NewStageRunner

func NewStageRunner(cfg *core.AnalysisConfig) *StageRunner

NewStageRunner creates an empty stage runner with the given config. Analyzers are registered via Register.

func (*StageRunner) Register

func (r *StageRunner) Register(a core.Analyzer)

func (*StageRunner) RunStages

func (r *StageRunner) RunStages(ctx *core.AnalysisContext) []core.Finding

RunStages executes enabled analyzers in stage order, returning findings.

why: a core.InPlaceAnalyzer already mutates ctx.Findings itself; appending its return on top would double it, so the marker check makes that contract explicit instead of an unenforced convention.