rule

package
v0.511.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Sep 7, 2026 License: Apache-2.0 Imports: 5 Imported by: 0

README

Domain Rule Module

Rule contracts, registration, and finding types for audit evaluation.

Files

File Responsibility
rule.go Defines finding severity, finding metadata, and skip reasons for loaded-but-inapplicable rules (dialect_mismatch)
registry.go Registers statement/global rules, enforces rule IDs, evaluates them deterministically, and reports whether a rule ID is Loaded via Contains
registry_test.go Verifies registry behavior, ID enforcement, Loaded Contains, and deterministic execution
catalog/README.md Documents the explanation-oriented shipped-rule catalog module
ddl/README.md Documents the Tier-1 DDL rule catalog module
dml/README.md Documents the Tier-1 DML rule catalog module

Exports

  • Level
  • Finding
  • FindingExplanation
  • ExplanationMetadata
  • Location
  • StatementRule
  • GlobalRule
  • Registry
  • NewRegistry()
  • Contains(id string) bool
  • RegisterStatement(rule StatementRule) error
  • RegisterGlobal(rule GlobalRule) error

Dependencies

  • Upstream: internal/application/audit, domain report aggregation, and future rule implementations
  • Downstream: internal/domain/spec

Update Rule

  • If members/interfaces/dependencies change, update this file in same change.

Documentation

Overview

Package rule defines rule registration and evaluation infrastructure. input: domain statements and registered statement/global rule implementations output: deterministic finding collection and Loaded rule-ID membership for the audit engine pos: domain rule registry and execution coordination note: if this file changes, update this header and module README.md.

Package rule defines domain findings and rule-engine types. input: rule evaluation details, source-location metadata, and statement/global rule implementations output: normalized findings, skip reasons for loaded-but-inapplicable rules, and registry-facing rule contracts pos: domain rule vocabulary and execution contracts shared across audit evaluation note: if this file changes, update this header and module README.md.

Index

Constants

This section is empty.

Variables

View Source 
var (
	// ErrEmptyRuleID indicates a rule was registered without an ID.
	ErrEmptyRuleID = errors.New("rule ID must not be empty")
	// ErrDuplicateRuleID indicates a rule ID was registered more than once.
	ErrDuplicateRuleID = errors.New("duplicate rule ID")
	// ErrRuleIDMismatch indicates a rule emitted a finding with a conflicting rule ID.
	ErrRuleIDMismatch = errors.New("finding rule ID does not match registered rule ID")
)

Functions

This section is empty.

Types

type ExplanationMetadata added in v0.6.2 

type ExplanationMetadata struct {
	Status string `json:"status,omitempty"`
	Note   string `json:"note,omitempty"`
}

ExplanationMetadata describes how metadata availability affected a finding explanation.

type Finding 

type Finding struct {
	RuleID         string              `json:"rule_id"`
	Level          Level               `json:"level"`
	Message        string              `json:"message"`
	StatementIndex int                 `json:"statement_index,omitempty"`
	StatementKind  string              `json:"statement_kind,omitempty"`
	Location       *Location           `json:"location,omitempty"`
	Suggestion     string              `json:"suggestion,omitempty"`
	Metadata       map[string]any      `json:"metadata,omitempty"`
	Explanation    *FindingExplanation `json:"explanation,omitempty"`
}

Finding is the domain result produced by a rule.

type FindingExplanation added in v0.6.2 

type FindingExplanation struct {
	Summary    string               `json:"summary,omitempty"`
	Why        string               `json:"why,omitempty"`
	Risk       string               `json:"risk,omitempty"`
	Suggestion string               `json:"suggestion,omitempty"`
	Metadata   *ExplanationMetadata `json:"metadata,omitempty"`
}

FindingExplanation captures additive explanation data for one finding.

type GlobalRule 

type GlobalRule interface {
	ID() string
	EvaluateAll(ctx context.Context, statements []spec.Statement) ([]Finding, error)
}

GlobalRule evaluates the full statement batch.

type Level 

type Level string

Level describes how severe a finding is. 

const (
	LevelBlocker Level = "blocker"
	LevelWarning Level = "warning"
	LevelNotice  Level = "notice"
)

type Location 

type Location struct {
	Line   int `json:"line,omitempty"`
	Column int `json:"column,omitempty"`
}

Location identifies a source span when available.

type Registry 

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

Registry stores rule registrations in deterministic order.

func NewRegistry 

func NewRegistry() *Registry

NewRegistry creates an empty rule registry.

func (*Registry) Contains added in v0.511.0 

func (r *Registry) Contains(id string) bool

Contains reports whether a statement or global rule ID is Loaded.

func (*Registry) EvaluateGlobal 

func (r *Registry) EvaluateGlobal(ctx context.Context, statements []spec.Statement) ([]Finding, error)

EvaluateGlobal applies global rules in registration order.

func (*Registry) EvaluateStatement 

func (r *Registry) EvaluateStatement(ctx context.Context, statement spec.Statement) ([]Finding, error)

EvaluateStatement applies all matching statement rules in registration order.

func (*Registry) EvaluateStatementDetailed added in v0.19.0 

func (r *Registry) EvaluateStatementDetailed(ctx context.Context, statement spec.Statement) (StatementEvaluation, error)

EvaluateStatementDetailed applies all statement rules and returns findings alongside skipped-rule metadata for rules that did not apply with an inferable reason.

func (*Registry) LoadedStatementRuleCount added in v0.19.0 

func (r *Registry) LoadedStatementRuleCount() int

LoadedStatementRuleCount returns the number of registered statement rules.

func (*Registry) RegisterGlobal 

func (r *Registry) RegisterGlobal(rule GlobalRule) error

RegisterGlobal appends a global rule to the registry.

func (*Registry) RegisterStatement 

func (r *Registry) RegisterStatement(rule StatementRule) error

RegisterStatement appends a statement rule to the registry.

type SkipReason added in v0.19.0 

type SkipReason string

SkipReason describes why a loaded rule did not apply to a statement. 

const (
	// SkipReasonDialectMismatch indicates the rule targets a different dialect.
	SkipReasonDialectMismatch SkipReason = "dialect_mismatch"
)

type SkippedRule added in v0.19.0 

type SkippedRule struct {
	RuleID string     `json:"rule_id"`
	Reason SkipReason `json:"reason"`
}

SkippedRule records one loaded rule that did not apply to a specific statement.

type StatementEvaluation added in v0.19.0 

type StatementEvaluation struct {
	Findings       []Finding     `json:"findings,omitempty"`
	Skipped        []SkippedRule `json:"skipped,omitempty"`
	AppliedRuleIDs []string      `json:"-"` // all rules where AppliesTo() returned true
}

StatementEvaluation holds the result of evaluating all statement rules against one statement.

type StatementRule 

type StatementRule interface {
	ID() string
	AppliesTo(statement spec.Statement) bool
	Evaluate(ctx context.Context, statement spec.Statement) ([]Finding, error)
}

StatementRule evaluates one statement at a time.

Source Files

View all Source files

Directories

Path Synopsis
Package catalog defines explanation-oriented metadata for shipped audit rules.
 Package catalog defines explanation-oriented metadata for shipped audit rules.
Package ddl defines Tier-1 DDL rules.
 Package ddl defines Tier-1 DDL rules.
Package dml defines Tier-1 DML rules.
 Package dml defines Tier-1 DML rules.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.