domain

package
v0.6.2 Latest Latest
Warning

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

 Go to latest Published: Mar 10, 2026 License: MIT Imports: 3 Imported by: 0

Documentation

Overview

Package domain defines the core types for the Code Certification System. These types have zero external dependencies and form the shared vocabulary used by all other packages.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func GenerateRunID added in v0.2.0 

func GenerateRunID(t time.Time) string

GenerateRunID creates a timestamp-based run identifier.

Types

type AgentConfig 

type AgentConfig struct {
	Enabled            bool             `yaml:"enabled"`
	ExplicitlyDisabled bool             `yaml:"-"` // Runtime-only: true when config explicitly sets enabled: false
	Provider           ProviderConfig   `yaml:"provider"`
	Models             ModelAssignments `yaml:"models"`
	RateLimit          RateLimitConfig  `yaml:"rate_limit"`
}

AgentConfig configures the optional agent-assisted review.

type AnalyzerConfig 

type AnalyzerConfig struct {
	GoVet         bool   `yaml:"go_vet"`         // Enable go vet (default: auto-detect)
	GoTest        bool   `yaml:"go_test"`        // Enable go test (default: auto-detect)
	GolangciLint  bool   `yaml:"golangci_lint"`  // Enable golangci-lint (default: auto-detect)
	ESLint        bool   `yaml:"eslint"`         // Enable eslint (default: auto-detect)
	CustomCommand string `yaml:"custom_command"` // Custom analyzer command
}

AnalyzerConfig defines settings for tool adapters.

type CertificationMode 

type CertificationMode int

CertificationMode determines whether certification results block merges. 

const (
	ModeAdvisory  CertificationMode = iota // Report findings, don't block
	ModeEnforcing                          // Block merges on configured failures
)

func (CertificationMode) String 

func (m CertificationMode) String() string

String returns the string representation of a CertificationMode.

type CertificationRecord 

type CertificationRecord struct {
	// Identity
	UnitID   UnitID   `json:"unit_id"`
	UnitType UnitType `json:"unit_type"`
	UnitPath string   `json:"unit_path"`

	// Policy
	PolicyVersion string `json:"policy_version"`

	// Result
	Status     Status          `json:"status"`
	Grade      Grade           `json:"grade"`
	Score      float64         `json:"score"`
	Confidence float64         `json:"confidence"`
	Dimensions DimensionScores `json:"dimensions,omitempty"`

	// Evidence
	Evidence     []Evidence `json:"evidence,omitempty"`
	Observations []string   `json:"observations,omitempty"`
	Actions      []string   `json:"actions,omitempty"`

	// Timestamps
	CertifiedAt time.Time `json:"certified_at"`
	ExpiresAt   time.Time `json:"expires_at"`

	// Metadata
	Source  string `json:"source"` // "deterministic", "agent", "combined"
	RunID   string `json:"run_id,omitempty"`
	Version int    `json:"version"` // record schema version
}

CertificationRecord is the complete trust record for a code unit.

type CertificationRun added in v0.2.0 

type CertificationRun struct {
	ID             string    `json:"id"`
	StartedAt      time.Time `json:"started_at"`
	CompletedAt    time.Time `json:"completed_at"`
	Commit         string    `json:"commit"`
	PolicyVersions []string  `json:"policy_versions,omitempty"`
	UnitsProcessed int       `json:"units_processed"`
	UnitsCertified int       `json:"units_certified"`
	UnitsFailed    int       `json:"units_failed"`
	OverallGrade   string    `json:"overall_grade"`
	OverallScore   float64   `json:"overall_score"`
}

CertificationRun captures metadata about a single certification invocation.

type Config 

type Config struct {
	Mode      CertificationMode `yaml:"mode"`
	Scope     ScopeConfig       `yaml:"scope"`
	Policies  PolicyConfig      `yaml:"policies"`
	Analyzers AnalyzerConfig    `yaml:"analyzers"`
	Agent     AgentConfig       `yaml:"agent"`
	Schedule  ScheduleConfig    `yaml:"schedule"`
	Expiry    ExpiryConfig      `yaml:"expiry"`
	Issues    IssueConfig       `yaml:"issues"`
}

Config is the top-level certification configuration.

func DefaultConfig 

func DefaultConfig() Config

DefaultConfig returns a Config with sensible defaults.

type Dimension 

type Dimension int

Dimension represents a quality dimension used for certification scoring. 

const (
	DimCorrectness                Dimension = iota // Code does what it claims
	DimMaintainability                             // Ease of future modification
	DimReadability                                 // Clarity and understandability
	DimTestability                                 // Ease of testing
	DimSecurity                                    // Security posture
	DimArchitecturalFitness                        // Alignment with architecture
	DimOperationalQuality                          // Production readiness
	DimPerformanceAppropriateness                  // Performance fitness
	DimChangeRisk                                  // Risk introduced by changes
)

func AllDimensions 

func AllDimensions() []Dimension

AllDimensions returns all 9 certification dimensions in canonical order.

func (Dimension) String 

func (d Dimension) String() string

String returns the string representation of a Dimension.

type DimensionScores 

type DimensionScores map[Dimension]float64

DimensionScores maps each dimension to a score between 0.0 and 1.0.

func (DimensionScores) WeightedAverage 

func (ds DimensionScores) WeightedAverage(weights DimensionWeights) float64

WeightedAverage computes the weighted average across all dimensions. If weights is nil, all dimensions are weighted equally.

type DimensionWeights 

type DimensionWeights map[Dimension]float64

DimensionWeights maps each dimension to its relative weight. A nil or empty weights map means equal weighting.

type EnforcingConfig 

type EnforcingConfig struct {
	BlockOnSeverity []string `yaml:"block_on_severity,omitempty"` // error, critical
	BlockOnStatus   []string `yaml:"block_on_status,omitempty"`   // decertified, probationary
	BlockPaths      []string `yaml:"block_paths,omitempty"`       // paths that must pass
	AllowPaths      []string `yaml:"allow_paths,omitempty"`       // paths exempt from blocking
}

EnforcingConfig controls what blocks merges in enforcing mode.

type Evidence 

type Evidence struct {
	Kind       EvidenceKind       `json:"kind"`
	Source     string             `json:"source"`            // Tool or provider name
	Passed     bool               `json:"passed"`            // Whether this evidence represents a pass
	Missing    bool               `json:"missing"`           // True if evidence was expected but not collected
	Summary    string             `json:"summary"`           // Human-readable summary
	Metrics    map[string]float64 `json:"metrics,omitempty"` // Typed metrics for policy evaluation
	Details    any                `json:"details,omitempty"` // Raw or normalized data (kept for backward compat)
	Timestamp  time.Time          `json:"timestamp"`
	Confidence float64            `json:"confidence"` // 0.0–1.0, how reliable is this evidence
}

Evidence represents a piece of evaluation data attached to a certification record.

type EvidenceKind 

type EvidenceKind int

EvidenceKind identifies the type of evidence collected. 

const (
	EvidenceKindLint           EvidenceKind = iota // Lint tool results
	EvidenceKindTypeCheck                          // Type checking results
	EvidenceKindTest                               // Test execution results
	EvidenceKindStaticAnalysis                     // Static analysis results
	EvidenceKindMetrics                            // Code metrics (complexity, size)
	EvidenceKindGitHistory                         // Git history analysis
	EvidenceKindStructural                         // AST-derived structural analysis
	EvidenceKindAgentReview                        // Agent-assisted review output
)

func ParseEvidenceKind added in v0.2.0 

func ParseEvidenceKind(s string) (EvidenceKind, error)

ParseEvidenceKind converts a string to an EvidenceKind.

func (EvidenceKind) String 

func (ek EvidenceKind) String() string

String returns the string representation of an EvidenceKind.

type ExpiryConfig 

type ExpiryConfig struct {
	DefaultWindowDays int `yaml:"default_window_days"`
	MinWindowDays     int `yaml:"min_window_days"`
	MaxWindowDays     int `yaml:"max_window_days"`
}

ExpiryConfig defines bounds for certification expiry windows.

type ExpiryFactors 

type ExpiryFactors struct {
	BaseWindowDays    int     `json:"base_window_days"`
	ChurnRate         float64 `json:"churn_rate"`    // Changes per time period (0.0–1.0+)
	TestCoverage      float64 `json:"test_coverage"` // 0.0–1.0
	Complexity        float64 `json:"complexity"`    // Cyclomatic complexity
	PriorPassCount    int     `json:"prior_pass_count"`
	PriorFailCount    int     `json:"prior_fail_count"`
	SecuritySensitive bool    `json:"security_sensitive"`
}

ExpiryFactors holds the inputs used to compute an expiry window.

type ExpiryWindow 

type ExpiryWindow struct {
	CertifiedAt time.Time `json:"certified_at"`
	ExpiresAt   time.Time `json:"expires_at"`
}

ExpiryWindow represents the time bounds of a certification.

func (ExpiryWindow) Duration 

func (w ExpiryWindow) Duration() time.Duration

Duration returns the total duration of the certification window.

func (ExpiryWindow) IsExpired 

func (w ExpiryWindow) IsExpired(at time.Time) bool

IsExpired returns true if the window has elapsed at the given time.

func (ExpiryWindow) RemainingAt 

func (w ExpiryWindow) RemainingAt(at time.Time) time.Duration

RemainingAt returns how much time is left at the given moment. Returns 0 if already expired.

type Grade 

type Grade int

Grade represents a letter grade computed from a certification score. 

const (
	GradeA      Grade = iota // 0.93+
	GradeAMinus              // 0.90+
	GradeBPlus               // 0.87+
	GradeB                   // 0.80+
	GradeC                   // 0.70+
	GradeD                   // 0.60+
	GradeF                   // < 0.60
)

func GradeFromScore 

func GradeFromScore(score float64) Grade

GradeFromScore converts a numeric score (0.0–1.0) to a letter grade.

func (Grade) String 

func (g Grade) String() string

String returns the letter grade string.

type IssueConfig 

type IssueConfig struct {
	Enabled  bool     `yaml:"enabled"`
	Labels   []string `yaml:"labels,omitempty"`
	Grouping string   `yaml:"grouping,omitempty"` // "single", "directory", "policy"
}

IssueConfig defines GitHub issue sync settings.

type ModelAssignments 

type ModelAssignments struct {
	Prescreen   string `yaml:"prescreen"`
	Review      string `yaml:"review"`
	Scoring     string `yaml:"scoring"`
	Decision    string `yaml:"decision"`
	Remediation string `yaml:"remediation"`
	Fallback    string `yaml:"fallback"`
}

ModelAssignments maps certification tasks to specific models.

type Override 

type Override struct {
	UnitID    UnitID         `json:"unit_id" yaml:"unit_id"`
	Action    OverrideAction `json:"action" yaml:"action"`
	Rationale string         `json:"rationale" yaml:"rationale"`
	Actor     string         `json:"actor" yaml:"actor"`
	Timestamp time.Time      `json:"timestamp" yaml:"timestamp"`
}

Override represents a manual governance action on a unit.

func (Override) Validate 

func (o Override) Validate() error

Validate checks that required fields are present.

type OverrideAction 

type OverrideAction int

OverrideAction specifies what a manual override does. 

const (
	OverrideExempt        OverrideAction = iota // Exclude unit from certification
	OverrideExtendWindow                        // Grant a longer trust window
	OverrideShortenWindow                       // Require more frequent re-evaluation
	OverrideForceReview                         // Force immediate recertification
)

func (OverrideAction) String 

func (a OverrideAction) String() string

String returns the string representation of an OverrideAction.

type PolicyConfig 

type PolicyConfig struct {
	Enabled  []string `yaml:"enabled,omitempty"`  // Pack names to enable (empty = all)
	Disabled []string `yaml:"disabled,omitempty"` // Pack names to disable
}

PolicyConfig controls which policy packs are active.

type PolicyPack 

type PolicyPack struct {
	Name         string       `json:"name" yaml:"name"`
	Version      string       `json:"version" yaml:"version"`
	Language     string       `json:"language,omitempty" yaml:"language,omitempty"`           // Empty = global (all languages)
	PathPatterns []string     `json:"path_patterns,omitempty" yaml:"path_patterns,omitempty"` // Glob patterns
	Rules        []PolicyRule `json:"rules" yaml:"rules"`
}

PolicyPack is a versioned set of certification rules.

func (PolicyPack) IsGlobal 

func (p PolicyPack) IsGlobal() bool

IsGlobal returns true if this policy applies to all languages.

type PolicyRule 

type PolicyRule struct {
	ID          string    `json:"id" yaml:"id"`
	Dimension   Dimension `json:"dimension" yaml:"dimension"`
	Description string    `json:"description" yaml:"description"`
	Severity    Severity  `json:"severity" yaml:"severity"`
	Threshold   float64   `json:"threshold,omitempty" yaml:"threshold,omitempty"` // Metric must be below this
	Metric      string    `json:"metric,omitempty" yaml:"metric,omitempty"`       // Which metric to evaluate
}

PolicyRule defines a single certification requirement.

type ProviderConfig 

type ProviderConfig struct {
	Type        string `yaml:"type"` // openrouter, openai, local
	BaseURL     string `yaml:"base_url"`
	APIKeyEnv   string `yaml:"api_key_env"` // Env var name (not the key itself)
	HTTPReferer string `yaml:"http_referer"`
	XTitle      string `yaml:"x_title"`
}

ProviderConfig defines the LLM provider settings.

type RateLimitConfig 

type RateLimitConfig struct {
	RequestsPerMinute  int `yaml:"requests_per_minute"`
	RetryMax           int `yaml:"retry_max"`
	RetryBackoffBaseMs int `yaml:"retry_backoff_base_ms"`
}

RateLimitConfig defines rate limiting for API calls.

type ScheduleConfig 

type ScheduleConfig struct {
	Nightly bool `yaml:"nightly"`
	Weekly  bool `yaml:"weekly"`
	Sweep   bool `yaml:"sweep"`
}

ScheduleConfig defines which scheduled workflows are enabled.

type ScopeConfig 

type ScopeConfig struct {
	Include []string `yaml:"include,omitempty"` // Glob patterns to include
	Exclude []string `yaml:"exclude,omitempty"` // Glob patterns to exclude
}

ScopeConfig defines which code paths are in/out of certification scope.

type Severity 

type Severity int

Severity indicates how serious a policy violation is. 

const (
	SeverityInfo     Severity = iota // Informational
	SeverityWarning                  // Minor issue
	SeverityError                    // Significant issue
	SeverityCritical                 // Must-fix issue
)

func ParseSeverity 

func ParseSeverity(s string) (Severity, error)

ParseSeverity converts a string to a Severity.

func (Severity) String 

func (s Severity) String() string

String returns the string representation of a Severity.

type SignoffConfig 

type SignoffConfig struct {
	RequiredPaths []string `yaml:"required_paths,omitempty"` // paths requiring signoff
	RequiredLabel string   `yaml:"required_label,omitempty"` // GitHub label for signoff
}

SignoffConfig controls human signoff requirements.

type Status 

type Status int

Status represents the certification status of a code unit. 

const (
	StatusCertified                 Status = iota // Fully compliant
	StatusCertifiedWithObservations               // Acceptable with minor issues
	StatusProbationary                            // Needs improvement within short window
	StatusExpired                                 // Certification window elapsed
	StatusDecertified                             // Fails policy requirements
	StatusExempt                                  // Excluded by explicit override
)

func ParseStatus 

func ParseStatus(s string) (Status, error)

ParseStatus converts a string to a Status.

func (Status) IsPassing 

func (s Status) IsPassing() bool

IsPassing returns true if the status represents a passing certification.

func (Status) String 

func (s Status) String() string

String returns the string representation of a Status.

type Unit 

type Unit struct {
	ID   UnitID
	Type UnitType
}

Unit represents a certifiable code unit with its identity and type.

func NewUnit 

func NewUnit(id UnitID, unitType UnitType) Unit

NewUnit creates a new Unit.

type UnitID 

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

UnitID is a stable identifier for a certifiable code unit. Format: <language>://<path>[#<symbol>] Examples: 

go://internal/service/sync.go#Apply
ts://src/parser/tokenize.ts#tokenizeDialogue
file://scripts/release.sh

func NewUnitID 

func NewUnitID(language, path, symbol string) UnitID

NewUnitID creates a new UnitID. If language is empty, "file" is used.

func ParseUnitID 

func ParseUnitID(s string) (UnitID, error)

ParseUnitID parses a string into a UnitID.

func (UnitID) Language 

func (id UnitID) Language() string

Language returns the language component of the ID.

func (UnitID) Path 

func (id UnitID) Path() string

Path returns the file path component of the ID.

func (UnitID) String 

func (id UnitID) String() string

String returns the canonical string representation of the UnitID.

func (UnitID) Symbol 

func (id UnitID) Symbol() string

Symbol returns the symbol component of the ID (may be empty).

type UnitType 

type UnitType int

UnitType identifies the kind of certifiable code unit. 

const (
	UnitTypeFile     UnitType = iota // A whole file
	UnitTypeFunction                 // A standalone function
	UnitTypeMethod                   // A method on a type
	UnitTypeClass                    // A class or type definition
	UnitTypeModule                   // A module (e.g. ES module)
	UnitTypePackage                  // A package (e.g. Go package)
)

func ParseUnitType 

func ParseUnitType(s string) (UnitType, error)

ParseUnitType converts a string to a UnitType.

func ParseUnitTypeOrDefault added in v0.6.2 

func ParseUnitTypeOrDefault(s string) UnitType

ParseUnitTypeOrDefault converts a string to a UnitType, returning UnitTypeFunction for unrecognized values.

func (UnitType) String 

func (ut UnitType) String() string

String returns the string representation of a UnitType.

type Violation 

type Violation struct {
	RuleID      string    `json:"rule_id"`
	PolicyName  string    `json:"policy_name"`
	Severity    Severity  `json:"severity"`
	Description string    `json:"description"`
	Dimension   Dimension `json:"dimension"`
}

Violation records a specific policy rule failure for a unit.

Source Files

View all Source files

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.