finding

Documentation

Overview

Package finding defines the Finding type and its sealed constructor. A finding represents one rule violation detected in the dependency graph.

Index

• type EdgeEvidence
• type Endpoint
• type Finding
  • func New(ruleID string, e graph.Edge, locs []graph.Location) Finding
• type Severity
• type Status

Types

type EdgeEvidence

type EdgeEvidence struct {
	From Endpoint `json:"from"`
	To   Endpoint `json:"to"`
	Kind string   `json:"kind"`
}

EdgeEvidence is the finding-level edge representation (spec §9). Distinct from graph.Edge: carries {module, path} endpoints, not kind:path IDs.

type Endpoint

type Endpoint struct {
	Module string `json:"module"`
	Path   string `json:"path"`
}

Endpoint identifies one side of a finding edge (resolved at diagnostic assembly).

type Finding

type Finding struct {
	ID           string            `json:"id"`
	Kind         string            `json:"kind"`
	RuleID       string            `json:"rule_id"`
	Status       Status            `json:"status"`
	Severity     Severity          `json:"severity"`
	Confidence   string            `json:"confidence"`
	Edge         EdgeEvidence      `json:"edge"`
	MatchedBy    map[string]string `json:"matched_by"`
	Locations    []graph.Location  `json:"locations"`
	Why          string            `json:"why"`
	Constraint   string            `json:"constraint"`
	Alternatives []string          `json:"allowed_alternatives,omitempty"`
}

Finding represents one rule violation detected in the dependency graph (spec §9/§12).

func New

func New(ruleID string, e graph.Edge, locs []graph.Location) Finding

New creates a Finding with a stable fingerprint ID derived from (ruleID, from, to, kind).

The ID is computed as hex(sha256(ruleID + "\x00" + from + "\x00" + to + "\x00" + kind)[:16]), producing a 32-character hex string. Line numbers do not affect the ID; the same violation found at different positions remains one finding, with all positions in Locations.

Kind defaults to "gate". Status defaults to "new". Edge.From.Path and Edge.To.Path are set to the bare repo-relative path (kind: prefix stripped). Edge.From.Module, Edge.To.Module, Severity, and MatchedBy are left zero — filled later by the rule and diagnostic assembly stage (engine Task 16).

type Severity

type Severity string

Severity represents the severity level of a finding.

const (
	SeverityCritical Severity = "critical"
	SeverityHigh     Severity = "high"
	SeverityMedium   Severity = "medium"
	SeverityLow      Severity = "low"
)

Severity constants (spec §9): critical > high > medium > low.

type Status

type Status string

Status represents the lifecycle state of a finding.

const (
	StatusNew           Status = "new"
	StatusBaseline      Status = "baseline"
	StatusExcepted      Status = "excepted"
	StatusExpiredExcept Status = "expired_exception"
	StatusFixed         Status = "fixed"
)

Status constants for finding lifecycle (spec §9).