provenance

package
v1.1.0 Latest Latest
Warning

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

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

Documentation

Overview

Package provenance implements Provenance Records functionality for LineSpec. Provenance Records are structured YAML artifacts that capture organizational intent, constraints, and reasoning behind system changes.

Index

Constants

This section is empty.

Variables

View Source 
var IDPattern = regexp.MustCompile(`^prov-(\d{4})-(\d{3})(?:-[a-z0-9-]+)?$`)

IDPattern is the regex for valid provenance record IDs: prov-YYYY-NNN or prov-YYYY-NNN-service-name

View Source 
var ValidStatuses = []Status{StatusOpen, StatusImplemented, StatusSuperseded, StatusDeprecated}

ValidStatuses contains all valid status values

Functions

func CurrentDate 

func CurrentDate() string

CurrentDate returns the current date in ISO 8601 format (YYYY-MM-DD)

func CurrentYear 

func CurrentYear() int

CurrentYear returns the current year as an integer

func GlobToRegex 

func GlobToRegex(glob string) string

GlobToRegex converts a glob pattern to a regex pattern

func IsValidID 

func IsValidID(id string) bool

IsValidID returns true if the ID matches the prov-YYYY-NNN format (with optional service suffix)

func MatchPattern 

func MatchPattern(filePath, pattern string) (bool, error)

MatchPattern checks if a file path matches a pattern (exact, glob, or regex)

func NextID 

func NextID(year int, existingIDs []string) string

NextID generates the next available ID for the given year

func ParseID 

func ParseID(id string) (year int, seq int, err error)

ParseID extracts year and sequence number from a valid ID

Types

type AssociatedSpec added in v1.1.0 

type AssociatedSpec struct {
	Path string `yaml:"path"`
	Type string `yaml:"type,omitempty"`
}

AssociatedSpec represents a proof artifact with optional type annotation

type CheckOptions 

type CheckOptions struct {
	Commit      string // Single commit to check (default: HEAD)
	Range       string // Range to check (e.g., SHA..SHA)
	Record      string // Check only against a specific record
	Staged      bool   // Check staged files instead of committed
	MessageFile string // Path to commit message file (for staged mode)
	ConfigFile  string // Path to custom .linespec.yml file
}

CheckOptions holds options for the check command

type Commands 

type Commands struct {
	Loader    *Loader
	Linter    *Linter
	Git       *Git
	Checker   *CommitChecker
	Formatter *Formatter
	Config    *ProvenanceConfig
	RepoRoot  string
}

Commands provides all provenance CLI commands

func NewCommands 

func NewCommands(config *ProvenanceConfig, repoRoot string, output *os.File, color bool) (*Commands, error)

NewCommands creates a new commands instance

func (*Commands) Check 

func (c *Commands) Check(opts CheckOptions) error

Check checks commits for violations

func (*Commands) Complete 

func (c *Commands) Complete(opts CompleteOptions) error

Complete marks a record as implemented

func (*Commands) Context added in v1.1.0 

func (c *Commands) Context(opts ContextOptions) error

Context retrieves provenance context for the given files

func (*Commands) Create 

func (c *Commands) Create(opts CreateOptions) error

Create creates a new provenance record

func (*Commands) Deprecate 

func (c *Commands) Deprecate(opts DeprecateOptions) error

Deprecate marks a record as deprecated

func (*Commands) Graph 

func (c *Commands) Graph(opts GraphOptions) error

Graph shows the provenance graph

func (*Commands) InstallHooks 

func (c *Commands) InstallHooks() error

InstallHooks installs git hooks

func (*Commands) Lint 

func (c *Commands) Lint(opts LintOptions) error

Lint runs the linter

func (*Commands) LockScope 

func (c *Commands) LockScope(opts LockScopeOptions) error

LockScope locks the scope of a record

func (*Commands) Status 

func (c *Commands) Status(opts StatusOptions) error

Status shows record status

type CommitChecker 

type CommitChecker struct {
	Git    *Git
	Loader *Loader
}

CommitChecker checks commits for provenance violations

func NewCommitChecker 

func NewCommitChecker(git *Git, loader *Loader) *CommitChecker

NewCommitChecker creates a new commit checker

func (*CommitChecker) AutoPopulateScope 

func (c *CommitChecker) AutoPopulateScope(record *Record) error

AutoPopulateScope populates affected_scope from git commits for a record

func (*CommitChecker) CheckCommit 

func (c *CommitChecker) CheckCommit(commit string) ([]Violation, error)

CheckCommit checks a single commit for violations

func (*CommitChecker) CheckForStaleScopeWarnings added in v1.0.3 

func (c *CommitChecker) CheckForStaleScopeWarnings(record *Record, changedFiles []string) []StaleScopeWarning

CheckForStaleScopeWarnings checks implemented records for files in affected_scope that haven't actually changed since the record was sealed

func (*CommitChecker) CheckRange 

func (c *CommitChecker) CheckRange(from, to string) ([]Violation, error)

CheckRange checks a range of commits for violations

func (*CommitChecker) CheckStaged added in v1.0.1 

func (c *CommitChecker) CheckStaged(messageFile string, commitTagRequired bool) ([]Violation, error)

CheckStaged checks staged files against provenance records referenced in a commit message

type CompleteOptions 

type CompleteOptions struct {
	RecordID   string
	Force      bool
	ConfigFile string // Path to custom .linespec.yml file
}

CompleteOptions holds options for the complete command

type ContextOptions added in v1.1.0 

type ContextOptions struct {
	Files      []string // File paths to check (positional args or --files)
	Format     string   // Output format: human (default), compact, json
	ConfigFile string   // Path to custom .linespec.yml file
}

ContextOptions holds options for the context command

type ContextRecord added in v1.1.0 

type ContextRecord struct {
	Record     *Record  // The record itself
	IsAncestor bool     // True if this record is only in ancestry, not directly matched
	Ancestors  []string // Chain of supersedes relationships (oldest first, i.e., the chain from current to oldest ancestor)
}

ContextRecord represents a record in the context output

type ContextResult added in v1.1.0 

type ContextResult struct {
	Files         []string         // Input files
	DirectMatches []*ContextRecord // Records that directly match the files
	Conflicts     []ScopeConflict  // Overlapping open records
}

ContextResult holds the complete context output

type CreateOptions 

type CreateOptions struct {
	Title      string
	Supersedes string
	Tags       []string
	NoEdit     bool
	IDSuffix   string // Service suffix for ID (e.g., "user-service" creates prov-YYYY-NNN-user-service)
	ConfigFile string // Path to custom .linespec.yml file
}

CreateOptions holds options for the create command

type DeprecateOptions 

type DeprecateOptions struct {
	RecordID   string
	Reason     string
	ConfigFile string // Path to custom .linespec.yml file
}

DeprecateOptions holds options for the deprecate command

type Formatter 

type Formatter struct {
	Output io.Writer
	Color  bool
}

Formatter handles output formatting for provenance commands

func NewFormatter 

func NewFormatter(output io.Writer, color bool) *Formatter

NewFormatter creates a new formatter

func (*Formatter) FormatCheckResult 

func (f *Formatter) FormatCheckResult(violations []Violation, staleWarnings []StaleScopeWarning, commit string)

FormatCheckResult formats the check command output

func (*Formatter) FormatCompleteSuccess 

func (f *Formatter) FormatCompleteSuccess(record *Record)

FormatCompleteSuccess formats the complete command success output

func (*Formatter) FormatContext added in v1.1.0 

func (f *Formatter) FormatContext(result *ContextResult)

FormatContext formats the context command output in human-readable format

func (*Formatter) FormatContextCompact added in v1.1.0 

func (f *Formatter) FormatContextCompact(result *ContextResult)

FormatContextCompact formats the context in a compact, token-efficient format

func (*Formatter) FormatContextJSON added in v1.1.0 

func (f *Formatter) FormatContextJSON(result *ContextResult) error

FormatContextJSON formats the context as JSON

func (*Formatter) FormatCreateSuccess 

func (f *Formatter) FormatCreateSuccess(record *Record, superseded string)

FormatCreateSuccess formats the create command success output

func (*Formatter) FormatError 

func (f *Formatter) FormatError(message string)

FormatError formats an error message

func (*Formatter) FormatGraph 

func (f *Formatter) FormatGraph(loader *Loader, filter string)

FormatGraph formats the provenance graph

func (*Formatter) FormatJSON 

func (f *Formatter) FormatJSON(data interface{}) error

FormatJSON outputs data as JSON

func (*Formatter) FormatLint 

func (f *Formatter) FormatLint(result *LintResult)

FormatLint formats lint results

func (*Formatter) FormatLockScopeSuccess 

func (f *Formatter) FormatLockScopeSuccess(record *Record, lockedPaths []string)

FormatLockScopeSuccess formats the lock-scope command success output

func (*Formatter) FormatStatus 

func (f *Formatter) FormatStatus(loader *Loader, enforcement string, filter string)

FormatStatus formats the status output

func (*Formatter) FormatStatusDetailed 

func (f *Formatter) FormatStatusDetailed(record *Record, loader *Loader)

FormatStatusDetailed formats detailed status for a single record

type Git 

type Git struct {
	RepoRoot string
}

Git provides git operations for provenance integration

func NewGit 

func NewGit(repoRoot string) *Git

NewGit creates a new Git helper

func (*Git) ExtractProvenanceIDs 

func (g *Git) ExtractProvenanceIDs(message string) []string

ExtractProvenanceIDs extracts provenance record IDs from a commit message Format: [prov-YYYY-NNN] or [prov-YYYY-NNN-service-name]

func (*Git) GetCommitMessage 

func (g *Git) GetCommitMessage(commit string) (string, error)

GetCommitMessage returns the commit message for a given commit

func (*Git) GetCommitsForRecord 

func (g *Git) GetCommitsForRecord(recordID string) ([]string, error)

GetCommitsForRecord returns all commits that reference a given record ID

func (*Git) GetCommitsInRange 

func (g *Git) GetCommitsInRange(from, to string) ([]string, error)

GetCommitsInRange returns all commits between two references

func (*Git) GetFilesChangedInCommits 

func (g *Git) GetFilesChangedInCommits(commits []string) ([]string, error)

GetFilesChangedInCommits returns all files changed across a set of commits

func (*Git) GetFilesChangedSince added in v1.0.3 

func (g *Git) GetFilesChangedSince(fromSHA, toSHA string) ([]string, error)

GetFilesChangedSince returns files that have changed between two SHAs

func (*Git) GetGitEmail 

func (g *Git) GetGitEmail() (string, error)

func (*Git) GetHeadSHA added in v1.0.3 

func (g *Git) GetHeadSHA() (string, error)

GetHeadSHA returns the SHA of the current HEAD commit

func (*Git) GetModifiedFiles 

func (g *Git) GetModifiedFiles(commit string) ([]string, error)

GetModifiedFiles returns files modified in a commit or commit range

func (*Git) GetStagedFiles added in v1.0.1 

func (g *Git) GetStagedFiles() ([]string, error)

GetStagedFiles returns files staged for commit

func (*Git) ReadCommitMessageFile added in v1.0.1 

func (g *Git) ReadCommitMessageFile(path string) (string, error)

ReadCommitMessageFile reads the commit message from a file

type GraphOptions 

type GraphOptions struct {
	Root       string // Start from specific record
	Filter     string // open | implemented | superseded | deprecated
	Format     string // human | json | dot
	ConfigFile string // Path to custom .linespec.yml file
}

GraphOptions holds options for the graph command

type Issue 

type Issue struct {
	RecordID string
	Field    string
	Message  string
	Severity Severity
}

Issue represents a validation issue found in a record

type JSONGraphNode 

type JSONGraphNode struct {
	ID           string          `json:"id"`
	Title        string          `json:"title"`
	Status       string          `json:"status"`
	Supersedes   string          `json:"supersedes,omitempty"`
	SupersededBy string          `json:"superseded_by,omitempty"`
	Children     []JSONGraphNode `json:"children,omitempty"`
}

JSONGraphNode represents a node in the graph for JSON output

func BuildJSONGraph 

func BuildJSONGraph(loader *Loader) []JSONGraphNode

BuildJSONGraph builds the graph for JSON output

type JSONIssue 

type JSONIssue struct {
	RecordID string `json:"record_id"`
	Field    string `json:"field"`
	Message  string `json:"message"`
	Severity string `json:"severity"`
}

JSONIssue represents a single issue for JSON output

type JSONLintResult 

type JSONLintResult struct {
	Enforcement string      `json:"enforcement"`
	Total       int         `json:"total"`
	Passed      int         `json:"passed"`
	Warnings    int         `json:"warnings"`
	Errors      int         `json:"errors"`
	Issues      []JSONIssue `json:"issues"`
}

JSONLintResult represents lint results for JSON output

type LintOptions 

type LintOptions struct {
	RecordID    string
	Enforcement string
	Format      string // human | json
	ConfigFile  string // Path to custom .linespec.yml file
}

LintOptions holds options for the lint command

type LintResult 

type LintResult struct {
	Issues       []Issue
	PassedCount  int
	WarningCount int
	ErrorCount   int
	HintCount    int
	Enforcement  string
}

LintResult contains the results of linting a record or set of records

func (*LintResult) Add 

func (r *LintResult) Add(issue Issue)

Add adds an issue to the result

func (*LintResult) HasErrors 

func (r *LintResult) HasErrors() bool

HasErrors returns true if there are any error-level issues

func (*LintResult) ToJSON 

func (r *LintResult) ToJSON() *JSONLintResult

ToJSON converts LintResult to JSONLintResult

type Linter 

type Linter struct {
	Loader            *Loader
	Enforcement       string // none | warn | strict
	CommitTagRequired bool
}

Linter validates Provenance Records according to the schema and enforcement rules

func NewLinter 

func NewLinter(loader *Loader, enforcement string) *Linter

NewLinter creates a new linter

func (*Linter) LintAll 

func (l *Linter) LintAll() *LintResult

LintAll validates all loaded records

func (*Linter) LintRecord 

func (l *Linter) LintRecord(recordID string) *LintResult

LintRecord validates a single record

type Loader 

type Loader struct {
	Records     []*Record
	RecordsByID map[string]*Record
	Dir         string
	SharedRepos []string
}

Loader handles loading and managing Provenance Records

func NewLoader 

func NewLoader(dir string, sharedRepos []string) *Loader

NewLoader creates a new provenance loader for the given directory

func (*Loader) BuildGraph 

func (l *Loader) BuildGraph() error

BuildGraph builds the ID index and validates relationships

func (*Loader) FilterByStatus 

func (l *Loader) FilterByStatus(status Status) []*Record

FilterByStatus returns records filtered by status

func (*Loader) FilterByTag 

func (l *Loader) FilterByTag(tag string) []*Record

FilterByTag returns records filtered by tag

func (*Loader) GetAllIDs 

func (l *Loader) GetAllIDs() []string

GetAllIDs returns all record IDs

func (*Loader) GetRecord 

func (l *Loader) GetRecord(id string) (*Record, bool)

GetRecord returns a record by ID

func (*Loader) GetSupersededChain 

func (l *Loader) GetSupersededChain(id string) []string

GetSupersededChain returns the chain of records that supersede the given one

func (*Loader) LoadAll 

func (l *Loader) LoadAll() error

LoadAll loads all provenance records from the configured directories

func (*Loader) LoadFile 

func (l *Loader) LoadFile(path string) (*Record, error)

LoadFile loads a single provenance record from a YAML file

func (*Loader) LoadFromDir 

func (l *Loader) LoadFromDir(dir string) error

LoadFromDir loads all .yml files from the given directory

func (*Loader) SaveRecord 

func (l *Loader) SaveRecord(record *Record) error

SaveRecord saves a record to its file path, preserving original YAML formatting

func (*Loader) UpdateSupersededBy 

func (l *Loader) UpdateSupersededBy()

UpdateSupersededBy updates the superseded_by field and status for all records that are superseded by other records

type LockScopeOptions 

type LockScopeOptions struct {
	RecordID   string
	DryRun     bool
	ConfigFile string // Path to custom .linespec.yml file
}

LockScopeOptions holds options for the lock-scope command

type ProvenanceConfig 

type ProvenanceConfig struct {
	Enforcement       string
	Dir               string
	SharedRepos       []string
	CommitTagRequired bool
	AutoAffectedScope bool
}

ProvenanceConfig holds provenance-related configuration

type Record 

type Record struct {
	// Required fields
	ID        string `yaml:"id"`
	Title     string `yaml:"title"`
	Status    Status `yaml:"status"`
	CreatedAt string `yaml:"created_at"`
	Author    string `yaml:"author"`

	// Intent and reasoning
	Intent      string   `yaml:"intent"`
	Constraints []string `yaml:"constraints"`

	// Scope
	AffectedScope  []string `yaml:"affected_scope"`
	ForbiddenScope []string `yaml:"forbidden_scope"`

	// Graph relationships
	Supersedes   string   `yaml:"supersedes"`
	SupersededBy string   `yaml:"superseded_by"`
	Related      []string `yaml:"related"`

	// Proof of completion
	SealedAtSHA      string           `yaml:"sealed_at_sha"`
	AssociatedSpecs  []AssociatedSpec `yaml:"associated_specs"`
	AssociatedTraces []string         `yaml:"associated_traces"`
	Monitors         []string         `yaml:"monitors"`

	// Tags
	Tags []string `yaml:"tags"`

	// File path (not stored in YAML, set during loading)
	FilePath string `yaml:"-"`
}

Record represents a single Provenance Record See PROVENANCE_RECORD_SCHEMA.md for full documentation

func (*Record) IsInScope 

func (r *Record) IsInScope(filePath string) (bool, error)

IsInScope returns true if the given file path matches the record's scope

func (*Record) IsMutableAfterImplemented 

func (r *Record) IsMutableAfterImplemented(fieldName string) bool

IsMutableAfterImplemented returns true if the field can be modified after status is 'implemented'

func (*Record) ScopeMode 

func (r *Record) ScopeMode() string

ScopeMode returns the scope mode based on affected_scope allowlist mode: affected_scope is non-empty observed mode: affected_scope is empty

type ScopeConflict added in v1.1.0 

type ScopeConflict struct {
	File      string   // The file with conflicting governance
	RecordIDs []string // The IDs of conflicting records
}

ScopeConflict represents two or more open records with overlapping scope

type Severity 

type Severity string

Severity represents the severity level of a validation issue 

const (
	SeverityError   Severity = "error"
	SeverityWarning Severity = "warning"
	SeverityHint    Severity = "hint"
)

type StaleScopeWarning added in v1.0.3 

type StaleScopeWarning struct {
	RecordID string
	File     string
	Message  string
}

StaleScopeWarning represents a warning about files in scope that haven't changed since sealing

type Status 

type Status string

Status represents the lifecycle state of a Provenance Record 

const (
	StatusOpen        Status = "open"
	StatusImplemented Status = "implemented"
	StatusSuperseded  Status = "superseded"
	StatusDeprecated  Status = "deprecated"
)

func (Status) IsValid 

func (s Status) IsValid() bool

IsValid returns true if the status is a known value

type StatusOptions 

type StatusOptions struct {
	RecordID   string
	Filter     string // open | implemented | superseded | deprecated | tag:xxx
	Format     string // human | json
	SaveScope  bool   // persist auto-populated scope to file
	ConfigFile string // Path to custom .linespec.yml file
}

StatusOptions holds options for the status command

type Violation 

type Violation struct {
	RecordID string
	File     string
	Commit   string
	Message  string
}

Violation represents a forbidden scope violation

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.