engine

Documentation

Index

• Constants
• func DefaultSeverity(onFail OnFail) string
• func FormatBrief(result AuditResult, env Environment) string
• func FormatEnvironment(env Environment) string
• func FormatJSON(result AuditResult) string
• func FormatText(result AuditResult, verbose bool) string
• func ResolveScope(scope Scope, projectRoot string) ([]string, error)
• type AuditResult
  • func RunAudit(contracts []*Contract, tags []string, projectRoot string) AuditResult
• type Check
• type CheckResult
  • func RunCheck(contract *Contract, check *Check, file, projectRoot string) CheckResult
• type CheckStatus
• type CommandAvailCheck
• type CommandCheck
• type Contract
  • func ParseContract(data []byte) (*Contract, error)
  • func ParseContractFile(path string) (*Contract, error)
  • func TopoSort(contracts []*Contract) ([]*Contract, error)
• type ContractType
• type EnvVarCheck
• type Environment
  • func DetectEnvironment() Environment
• type KeyCheck
• type OnFail
• type PathCheck
• type PathType
• type RegexCheck
• type Result
• type Scope
• type ScriptCheck
• type SkipIf

Constants

const (
	PathTypeFile      = types.PathTypeFile
	PathTypeDirectory = types.PathTypeDirectory
)

Re-export PathType constants.

const GlobalSentinel = "__global__"

GlobalSentinel is passed as the "file" for global-scope checks (no file context).

Functions

func DefaultSeverity

func DefaultSeverity(onFail OnFail) string

DefaultSeverity derives a severity string from an on_fail action.

func FormatBrief

func FormatBrief(result AuditResult, env Environment) string

FormatBrief renders an agent-consumable findings report from an audit result.

func FormatEnvironment

func FormatEnvironment(env Environment) string

FormatEnvironment renders the environment preamble for a brief report.

func FormatJSON

func FormatJSON(result AuditResult) string

FormatJSON returns the audit result as pretty-printed JSON.

func FormatText

func FormatText(result AuditResult, verbose bool) string

FormatText returns a human-readable audit report. verbose=true shows per-file results; false collapses to per-contract.

func ResolveScope

func ResolveScope(scope Scope, projectRoot string) ([]string, error)

ResolveScope returns the list of files the contract applies to. Uses git ls-files if available, falls back to filesystem glob.

Types

type AuditResult

type AuditResult struct {
	Results []CheckResult `json:"results"`
	Passed  int           `json:"passed"`
	Failed  int           `json:"failed"`
	Warned  int           `json:"warned"`
	Exempt  int           `json:"exempt"`
	Skipped int           `json:"skipped"`
	Halted  int           `json:"halted,omitempty"`
}

func RunAudit

func RunAudit(contracts []*Contract, tags []string, projectRoot string) AuditResult

RunAudit evaluates contracts whose tags match any of the given tags. An empty tags slice runs all contracts. The special tag "always" bypasses filtering.

type Check

type Check struct {
	Name   string  `yaml:"name"`
	OnFail OnFail  `yaml:"on_fail"`
	SkipIf *SkipIf `yaml:"skip_if"`

	// Brief-mode fields (optional). All omitted for existing contracts.
	Severity string   `yaml:"severity,omitempty"` // critical|high|medium|low|info
	Category string   `yaml:"category,omitempty"` // integrity|security|config|performance|network
	What     string   `yaml:"what,omitempty"`     // factual observation (no interpretation)
	Verify   string   `yaml:"verify,omitempty"`   // read-only verification command
	Affects  []string `yaml:"affects,omitempty"`  // paths, services, resources

	// Check modules (exactly one should be set)
	Command       *CommandCheck      `yaml:"command"`
	Script        *ScriptCheck       `yaml:"script"`
	RegexInFile   *RegexCheck        `yaml:"regex_in_file"`
	NoRegexInFile *RegexCheck        `yaml:"no_regex_in_file"`
	PathExists    *PathCheck         `yaml:"path_exists"`
	PathNotExists *PathCheck         `yaml:"path_not_exists"`
	YAMLKey       *KeyCheck          `yaml:"yaml_key"`
	JSONKey       *KeyCheck          `yaml:"json_key"`
	TOMLKey       *KeyCheck          `yaml:"toml_key"`
	EnvVar        *EnvVarCheck       `yaml:"env_var"`
	NoEnvVar      *EnvVarCheck       `yaml:"no_env_var"`
	CommandAvail  *CommandAvailCheck `yaml:"command_available"`
}

Check is a single assertion within a contract. Exactly one check module field should be set.

type CheckResult

type CheckResult struct {
	ContractID          string      `json:"contract_id"`
	ContractDescription string      `json:"contract_description"`
	CheckName           string      `json:"check_name"`
	Status              CheckStatus `json:"status"`
	Message             string      `json:"message"`
	File                string      `json:"file,omitempty"`
	OnFail              OnFail      `json:"on_fail,omitempty"`
	Evidence            string      `json:"evidence,omitempty"` // auto-captured stdout from check run
	Severity            string      `json:"severity,omitempty"` // derived or explicit
	Category            string      `json:"category,omitempty"`
	What                string      `json:"what,omitempty"`
	Verify              string      `json:"verify,omitempty"`
	Affects             []string    `json:"affects,omitempty"`
}

func RunCheck

func RunCheck(contract *Contract, check *Check, file, projectRoot string) CheckResult

RunCheck evaluates a single check against a file (or GlobalSentinel for global checks).

type CheckStatus

type CheckStatus string

CheckStatus is the outcome of a single check evaluation.

const (
	StatusPass   CheckStatus = "pass"
	StatusFail   CheckStatus = "fail"
	StatusWarn   CheckStatus = "warn"
	StatusExempt CheckStatus = "exempt"
	StatusSkip   CheckStatus = "skip"
	StatusHalt   CheckStatus = "halt" // protocol contracts: action must not proceed
)

type CommandAvailCheck

type CommandAvailCheck = types.CommandAvailCheck

Re-export shared check-input types from internal/types. This allows engine to import modules (which import types) without a cycle.

type CommandCheck

type CommandCheck = types.CommandCheck

Re-export shared check-input types from internal/types. This allows engine to import modules (which import types) without a cycle.

type Contract

type Contract struct {
	ID          string       `yaml:"id"`
	Description string       `yaml:"description"`
	Type        ContractType `yaml:"type"`
	Trigger     string       `yaml:"trigger,omitempty"` // protocol contracts: descriptive label for the gated action
	Tags        []string     `yaml:"-"`                 // custom unmarshal (scalar or list)
	Scope       Scope        `yaml:"-"`                 // custom unmarshal
	SkipIf      *SkipIf      `yaml:"skip_if"`
	Checks      []Check      `yaml:"checks"`
	Builtin     bool         `yaml:"-"`                    // set by loader, not in YAML
	System      bool         `yaml:"-"`                    // set by loader for ~/.config/contracts entries
	DependsOn   []string     `yaml:"depends_on,omitempty"` // contract IDs whose failures must be addressed first
}

func ParseContract

func ParseContract(data []byte) (*Contract, error)

func ParseContractFile

func ParseContractFile(path string) (*Contract, error)

func TopoSort

func TopoSort(contracts []*Contract) ([]*Contract, error)

TopoSort returns contracts in dependency order (Kahn's algorithm). Contracts with unknown depends_on IDs are treated as having no dependency. Returns error on cycle.

type ContractType

type ContractType string

ContractType is display-only metadata.

const (
	TypeAtomic    ContractType = "atomic"
	TypeDetective ContractType = "detective"
	TypeHolistic  ContractType = "holistic"
	TypeProtocol  ContractType = "protocol"
)

type EnvVarCheck

type EnvVarCheck = types.EnvVarCheck

Re-export shared check-input types from internal/types. This allows engine to import modules (which import types) without a cycle.

type Environment

type Environment struct {
	OS             string
	Cwd            string
	User           string
	AvailableTools []string
}

Environment captures the execution context for the report preamble.

func DetectEnvironment

func DetectEnvironment() Environment

DetectEnvironment auto-detects the current execution environment.

type KeyCheck

type KeyCheck = types.KeyCheck

Re-export shared check-input types from internal/types. This allows engine to import modules (which import types) without a cycle.

type OnFail

type OnFail string

OnFail action string — evaluator maps to context-appropriate behaviour.

const (
	OnFailFail             OnFail = "fail"
	OnFailWarn             OnFail = "warn"
	OnFailRequireExemption OnFail = "require_exemption"
	OnFailEscalate         OnFail = "escalate"    // ConspiracyOS: escalate to sysadmin
	OnFailHaltAgents       OnFail = "halt_agents" // ConspiracyOS: halt all agents
	OnFailAlert            OnFail = "alert"       // ConspiracyOS: alert
	OnFailHalt             OnFail = "halt"        // Protocol: block the action
)

type PathCheck

type PathCheck = types.PathCheck

Re-export shared check-input types from internal/types. This allows engine to import modules (which import types) without a cycle.

type PathType

type PathType = types.PathType

Re-export shared check-input types from internal/types. This allows engine to import modules (which import types) without a cycle.

type RegexCheck

type RegexCheck = types.RegexCheck

Re-export shared check-input types from internal/types. This allows engine to import modules (which import types) without a cycle.

type Result

type Result = types.Result

Re-export shared check-input types from internal/types. This allows engine to import modules (which import types) without a cycle.

type Scope

type Scope struct {
	Global  bool
	Paths   []string
	Exclude []string
}

type ScriptCheck

type ScriptCheck = types.ScriptCheck

Re-export shared check-input types from internal/types. This allows engine to import modules (which import types) without a cycle.

type SkipIf

type SkipIf = types.SkipIf

Re-export shared check-input types from internal/types. This allows engine to import modules (which import types) without a cycle.