reconciler

package
v0.0.2 Latest Latest
Warning

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

 Go to latest Published: Sep 5, 2025 License: AGPL-3.0 Imports: 17 Imported by: 0

README

reconcile

Package reconcile provides complex multi-source data reconciliation with field-level authority and provenance tracking.

reconcile

import "github.com/agentstation/starmap/pkg/reconcile"

Package reconcile provides catalog synchronization and reconciliation capabilities. It handles merging data from multiple sources, detecting changes, and applying updates while respecting data authorities and merge strategies.

The reconciler coordinates fetching data from various sources, computing differences, and merging changes into a target catalog. It supports dry-run operations, changeset generation, and intelligent conflict resolution.

Example usage:

// Create a reconciler
r := NewReconciler(targetCatalog, sources)

// Perform reconciliation
changeset, err := r.Reconcile(ctx, options)
if err != nil {
    log.Fatal(err)
}

// Review changes
for _, change := range changeset.Changes {
    fmt.Printf("Change: %s %s\n", change.Type, change.ModelID)
}

// Apply changes if not dry-run
if !options.DryRun {
    err = r.Apply(changeset)
}

Index

func MatchesPattern

func MatchesPattern(fieldPath, pattern string) bool

MatchesPattern checks if a field path matches a pattern (supports * wildcards)

type ApplyStrategy

ApplyStrategy represents how to apply changes

type ApplyStrategy string


const (
    // ApplyAll applies all changes including removals
    ApplyAll ApplyStrategy = "all"

    // ApplyAdditive only applies additions and updates, never removes
    ApplyAdditive ApplyStrategy = "additive"

    // ApplyUpdatesOnly only applies updates to existing items
    ApplyUpdatesOnly ApplyStrategy = "updates-only"

    // ApplyAdditionsOnly only applies new additions
    ApplyAdditionsOnly ApplyStrategy = "additions-only"
)

type AuthorChangeset

AuthorChangeset represents changes to authors

type AuthorChangeset struct {
    Added   []catalogs.Author // New authors
    Updated []AuthorUpdate    // Updated authors
    Removed []catalogs.Author // Removed authors
}

func (*AuthorChangeset) HasChanges
func (a *AuthorChangeset) HasChanges() bool

HasChanges returns true if the author changeset contains any changes

func (*AuthorChangeset) Print
func (a *AuthorChangeset) Print()

Print outputs author changes in a human-readable format

type AuthorUpdate

AuthorUpdate represents an update to an existing author

type AuthorUpdate struct {
    ID       catalogs.AuthorID // ID of the author being updated
    Existing catalogs.Author   // Current author
    New      catalogs.Author   // New author
    Changes  []FieldChange     // Detailed list of field changes
}

type AuthorityBasedStrategy

AuthorityBasedStrategy uses field authorities to resolve conflicts

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

func (*AuthorityBasedStrategy) ResolveConflict
func (s *AuthorityBasedStrategy) ResolveConflict(field string, values map[SourceName]interface{}) (interface{}, SourceName, string)

ResolveConflict uses authorities to resolve conflicts

type AuthorityProvider

AuthorityProvider determines which source is authoritative for each field

type AuthorityProvider interface {
    // GetAuthority returns the authority configuration for a specific field
    GetAuthority(fieldPath string, resourceType ResourceType) *FieldAuthority

    // GetAuthorities returns all authorities for a resource type
    GetAuthorities(resourceType ResourceType) []FieldAuthority
}

func NewDefaultAuthorities
func NewDefaultAuthorities() AuthorityProvider

NewDefaultAuthorities creates a new DefaultAuthorities with standard configurations

func NewDefaultAuthorityProvider
func NewDefaultAuthorityProvider() AuthorityProvider

NewDefaultAuthorityProvider is an alias for NewDefaultAuthorities

type ChainEnhancer

ChainEnhancer allows chaining multiple enhancers with custom logic

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

func NewChainEnhancer
func NewChainEnhancer(priority int, enhancers ...Enhancer) *ChainEnhancer

NewChainEnhancer creates a new chain enhancer

func (*ChainEnhancer) CanEnhance
func (e *ChainEnhancer) CanEnhance(model catalogs.Model) bool

CanEnhance checks if any enhancer in the chain can enhance

func (*ChainEnhancer) Enhance
func (e *ChainEnhancer) Enhance(ctx context.Context, model catalogs.Model) (catalogs.Model, error)

Enhance applies all enhancers in sequence

func (*ChainEnhancer) EnhanceBatch
func (e *ChainEnhancer) EnhanceBatch(ctx context.Context, models []catalogs.Model) ([]catalogs.Model, error)

EnhanceBatch enhances multiple models

func (*ChainEnhancer) Name
func (e *ChainEnhancer) Name() string

Name returns the enhancer name

func (*ChainEnhancer) Priority
func (e *ChainEnhancer) Priority() int

Priority returns the priority

type ChangeType

ChangeType represents the type of change

type ChangeType string


const (
    ChangeTypeAdd    ChangeType = "add"
    ChangeTypeUpdate ChangeType = "update"
    ChangeTypeRemove ChangeType = "remove"
)

type Changeset

Changeset represents all changes between two catalogs

type Changeset struct {
    Models    *ModelChangeset    // Model changes
    Providers *ProviderChangeset // Provider changes
    Authors   *AuthorChangeset   // Author changes
    Summary   ChangesetSummary   // Summary statistics
}

func (*Changeset) Filter
func (c *Changeset) Filter(strategy ApplyStrategy) *Changeset

Filter filters the changeset based on the apply strategy

func (*Changeset) HasChanges
func (c *Changeset) HasChanges() bool

HasChanges returns true if the changeset contains any changes

func (*Changeset) IsEmpty
func (c *Changeset) IsEmpty() bool

IsEmpty returns true if the changeset contains no changes

func (*Changeset) Print
func (c *Changeset) Print()

Print outputs a detailed, human-readable view of the changeset

func (*Changeset) String
func (c *Changeset) String() string

String returns a human-readable summary of the changeset

type ChangesetSummary

ChangesetSummary provides summary statistics for a changeset

type ChangesetSummary struct {
    ModelsAdded      int
    ModelsUpdated    int
    ModelsRemoved    int
    ProvidersAdded   int
    ProvidersUpdated int
    ProvidersRemoved int
    AuthorsAdded     int
    AuthorsUpdated   int
    AuthorsRemoved   int
    TotalChanges     int
}

type Conflict

Conflict represents a merge conflict

type Conflict struct {
    Path      string      // Field path (e.g., "pricing.input")
    Base      interface{} // Original value
    Ours      interface{} // Our change
    Theirs    interface{} // Their change
    Type      ConflictType
    CanMerge  bool        // Whether automatic merge is possible
    Suggested interface{} // Suggested resolution
}

type ConflictInfo

ConflictInfo describes a conflict that was resolved

type ConflictInfo struct {
    Sources        []SourceName  // Sources that had conflicting values
    Values         []interface{} // The conflicting values
    Resolution     string        // How the conflict was resolved
    SelectedSource SourceName    // Which source was selected
}

type ConflictResolution

ConflictResolution defines how to resolve conflicts

type ConflictResolution string


const (
    ResolutionOurs      ConflictResolution = "ours"      // Always take our changes
    ResolutionTheirs    ConflictResolution = "theirs"    // Always take their changes
    ResolutionMerge     ConflictResolution = "merge"     // Try to merge if possible
    ResolutionBase      ConflictResolution = "base"      // Keep original value
    ResolutionNewest    ConflictResolution = "newest"    // Take the newest change
    ResolutionAuthority ConflictResolution = "authority" // Use field authorities
)

type ConflictResolver

ConflictResolver is a function that resolves conflicts

type ConflictResolver func(field string, values map[SourceName]interface{}) (interface{}, SourceName, string)

type ConflictType

ConflictType describes the type of conflict

type ConflictType string


const (
    ConflictTypeModified ConflictType = "modified" // Both sides modified the same field
    ConflictTypeDeleted  ConflictType = "deleted"  // One side deleted, other modified
    ConflictTypeAdded    ConflictType = "added"    // Both sides added different values
)

type CustomAuthorities

CustomAuthorities allows for custom field authority configurations

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

func NewCustomAuthorities
func NewCustomAuthorities() *CustomAuthorities

NewCustomAuthorities creates a new CustomAuthorities

func (*CustomAuthorities) AddAuthority
func (ca *CustomAuthorities) AddAuthority(resourceType ResourceType, authority FieldAuthority)

AddAuthority adds a field authority for a resource type

func (*CustomAuthorities) GetAuthorities
func (ca *CustomAuthorities) GetAuthorities(resourceType ResourceType) []FieldAuthority

GetAuthorities returns all authorities for a resource type

func (*CustomAuthorities) GetAuthority
func (ca *CustomAuthorities) GetAuthority(fieldPath string, resourceType ResourceType) *FieldAuthority

GetAuthority returns the authority configuration for a specific field

type CustomStrategy

CustomStrategy allows custom conflict resolution logic

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

func (*CustomStrategy) ResolveConflict
func (s *CustomStrategy) ResolveConflict(field string, values map[SourceName]interface{}) (interface{}, SourceName, string)

ResolveConflict uses custom resolver

type DefaultAuthorities

DefaultAuthorities provides standard field authorities

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

func (*DefaultAuthorities) GetAuthorities
func (da *DefaultAuthorities) GetAuthorities(resourceType ResourceType) []FieldAuthority

GetAuthorities returns all authorities for a resource type

func (*DefaultAuthorities) GetAuthority
func (da *DefaultAuthorities) GetAuthority(fieldPath string, resourceType ResourceType) *FieldAuthority

GetAuthority returns the authority configuration for a specific field

type Differ

Differ handles change detection between resources

type Differ interface {
    // DiffModels compares two sets of models and returns changes
    DiffModels(existing, new []catalogs.Model) *ModelChangeset

    // DiffProviders compares two sets of providers and returns changes
    DiffProviders(existing, new []catalogs.Provider) *ProviderChangeset

    // DiffAuthors compares two sets of authors and returns changes
    DiffAuthors(existing, new []catalogs.Author) *AuthorChangeset

    // DiffCatalogs compares two complete catalogs
    // Both catalogs only need to be readable
    DiffCatalogs(existing, new catalogs.Reader) *Changeset
}

func NewDiffer
func NewDiffer(opts ...DifferOption) Differ

NewDiffer creates a new Differ with default settings

type DifferOption

DifferOption is a functional option for configuring Differ

type DifferOption func(*differ)

func WithDeepComparison
func WithDeepComparison(enabled bool) DifferOption

WithDeepComparison enables/disables deep structural comparison

func WithIgnoredFields
func WithIgnoredFields(fields ...string) DifferOption

WithIgnoredFields sets fields to ignore during comparison

func WithProvenanceTracking
func WithProvenanceTracking(enabled bool) DifferOption

WithProvenanceTracking enables provenance tracking in diffs

type Enhancer

Enhancer defines the interface for model enrichment

type Enhancer interface {
    // Name returns the enhancer name
    Name() string

    // Enhance enhances a single model with additional data
    Enhance(ctx context.Context, model catalogs.Model) (catalogs.Model, error)

    // EnhanceBatch enhances multiple models efficiently
    EnhanceBatch(ctx context.Context, models []catalogs.Model) ([]catalogs.Model, error)

    // CanEnhance checks if this enhancer can enhance a specific model
    CanEnhance(model catalogs.Model) bool

    // Priority returns the priority of this enhancer (higher = applied first)
    Priority() int
}

type EnhancerPipeline

EnhancerPipeline manages a chain of enhancers

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

func NewEnhancerPipeline
func NewEnhancerPipeline(enhancers ...Enhancer) *EnhancerPipeline

NewEnhancerPipeline creates a new enhancer pipeline

func (*EnhancerPipeline) Enhance
func (p *EnhancerPipeline) Enhance(ctx context.Context, model catalogs.Model) (catalogs.Model, error)

Enhance applies all enhancers to a single model

func (*EnhancerPipeline) EnhanceBatch
func (p *EnhancerPipeline) EnhanceBatch(ctx context.Context, models []catalogs.Model) ([]catalogs.Model, error)

EnhanceBatch applies all enhancers to multiple models

func (*EnhancerPipeline) WithProvenance
func (p *EnhancerPipeline) WithProvenance(tracker ProvenanceTracker) *EnhancerPipeline

WithProvenance enables provenance tracking for enhancements

type FieldAuthority

FieldAuthority defines source priority for a specific field

type FieldAuthority struct {
    FieldPath string     `json:"field_path" yaml:"field_path"` // e.g., "pricing.input", "metadata.knowledge_cutoff"
    Source    SourceName `json:"source" yaml:"source"`         // Which source is authoritative
    Priority  int        `json:"priority" yaml:"priority"`     // Priority (higher = more authoritative)
}

func AuthorityByField
func AuthorityByField(fieldPath string, authorities []FieldAuthority) *FieldAuthority

AuthorityByField returns the highest priority authority for a given field path

func FilterAuthoritiesBySource
func FilterAuthoritiesBySource(authorities []FieldAuthority, sourceName SourceName) []FieldAuthority

FilterAuthoritiesBySource returns only the authorities for a specific source

type FieldChange

FieldChange represents a change to a specific field

type FieldChange struct {
    Path     string     // Field path (e.g., "pricing.input")
    OldValue string     // Previous value (string representation)
    NewValue string     // New value (string representation)
    Type     ChangeType // Type of change
    Source   SourceName // Source that caused the change (for provenance)
}

type FieldProvenance

FieldProvenance contains provenance history for a single field

type FieldProvenance struct {
    Current   ProvenanceInfo   // Current value and its source
    History   []ProvenanceInfo // Historical values
    Conflicts []ConflictInfo   // Any conflicts that were resolved
}

type Merger

Merger performs the actual merging of resources

type Merger interface {
    // MergeModels merges models from multiple sources
    MergeModels(sources map[SourceName][]catalogs.Model) ([]catalogs.Model, ProvenanceMap, error)

    // MergeProviders merges providers from multiple sources
    MergeProviders(sources map[SourceName][]catalogs.Provider) ([]catalogs.Provider, ProvenanceMap, error)

    // MergeField merges a single field using authorities
    MergeField(fieldPath string, values map[SourceName]interface{}) (interface{}, SourceName)

    // WithProvenance sets the provenance tracker
    WithProvenance(tracker ProvenanceTracker)
}

type MetadataEnhancer

MetadataEnhancer adds metadata from various sources

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

func NewMetadataEnhancer
func NewMetadataEnhancer(priority int) *MetadataEnhancer

NewMetadataEnhancer creates a new metadata enhancer

func (*MetadataEnhancer) CanEnhance
func (e *MetadataEnhancer) CanEnhance(model catalogs.Model) bool

CanEnhance checks if this enhancer can enhance a model

func (*MetadataEnhancer) Enhance
func (e *MetadataEnhancer) Enhance(ctx context.Context, model catalogs.Model) (catalogs.Model, error)

Enhance enhances a single model

func (*MetadataEnhancer) EnhanceBatch
func (e *MetadataEnhancer) EnhanceBatch(ctx context.Context, models []catalogs.Model) ([]catalogs.Model, error)

EnhanceBatch enhances multiple models

func (*MetadataEnhancer) Name
func (e *MetadataEnhancer) Name() string

Name returns the enhancer name

func (*MetadataEnhancer) Priority
func (e *MetadataEnhancer) Priority() int

Priority returns the priority

type ModelChangeset

ModelChangeset represents changes to models

type ModelChangeset struct {
    Added   []catalogs.Model // New models
    Updated []ModelUpdate    // Updated models
    Removed []catalogs.Model // Removed models
}

func (*ModelChangeset) HasChanges
func (m *ModelChangeset) HasChanges() bool

HasChanges returns true if the model changeset contains any changes

func (*ModelChangeset) Print
func (m *ModelChangeset) Print()

Print outputs model changes in a human-readable format

type ModelUpdate

ModelUpdate represents an update to an existing model

type ModelUpdate struct {
    ID       string         // ID of the model being updated
    Existing catalogs.Model // Current model
    New      catalogs.Model // New model
    Changes  []FieldChange  // Detailed list of field changes
}

type ModelsDevEnhancer

ModelsDevEnhancer enhances models with models.dev data

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

func NewModelsDevEnhancer
func NewModelsDevEnhancer(priority int) *ModelsDevEnhancer

NewModelsDevEnhancer creates a new models.dev enhancer

func (*ModelsDevEnhancer) CanEnhance
func (e *ModelsDevEnhancer) CanEnhance(model catalogs.Model) bool

CanEnhance checks if this enhancer can enhance a model

func (*ModelsDevEnhancer) Enhance
func (e *ModelsDevEnhancer) Enhance(ctx context.Context, model catalogs.Model) (catalogs.Model, error)

Enhance enhances a single model

func (*ModelsDevEnhancer) EnhanceBatch
func (e *ModelsDevEnhancer) EnhanceBatch(ctx context.Context, models []catalogs.Model) ([]catalogs.Model, error)

EnhanceBatch enhances multiple models

func (*ModelsDevEnhancer) Name
func (e *ModelsDevEnhancer) Name() string

Name returns the enhancer name

func (*ModelsDevEnhancer) Priority
func (e *ModelsDevEnhancer) Priority() int

Priority returns the priority

type Option

Option configures a Reconciler

type Option func(*reconciler) error

func WithAuthorities
func WithAuthorities(authorities AuthorityProvider) Option

WithAuthorities sets the field authorities

func WithEnhancers
func WithEnhancers(enhancers ...Enhancer) Option

WithEnhancers adds model enhancers to the pipeline

func WithProvenance
func WithProvenance(enabled bool) Option

WithProvenance enables field-level tracking

func WithStrategy
func WithStrategy(strategy Strategy) Option

WithStrategy sets the merge strategy

type ProvenanceAuditResult

ProvenanceAuditResult contains audit findings

type ProvenanceAuditResult struct {
    Valid       bool
    Issues      []string
    Warnings    []string
    Coverage    float64  // Percentage of fields with provenance
    Conflicts   int      // Number of unresolved conflicts
    MissingData []string // Fields without provenance
}

type ProvenanceAuditor

ProvenanceAuditor validates provenance tracking

type ProvenanceAuditor interface {
    // Audit checks provenance for completeness and consistency
    Audit(provenance ProvenanceMap) *ProvenanceAuditResult

    // ValidateAuthority ensures authority scores are valid
    ValidateAuthority(provenance ProvenanceMap) []string

    // CheckCoverage verifies all required fields have provenance
    CheckCoverage(provenance ProvenanceMap, requiredFields []string) []string
}

type ProvenanceInfo

ProvenanceInfo tracks the origin and history of a field value

type ProvenanceInfo struct {
    Source        SourceName  // Source that provided the value
    Field         string      // Field path
    Value         interface{} // The actual value
    Timestamp     time.Time   // When the value was set
    Authority     float64     // Authority score (0.0 to 1.0)
    Confidence    float64     // Confidence in the value (0.0 to 1.0)
    Reason        string      // Reason for selecting this value
    PreviousValue interface{} // Previous value if updated
}

type ProvenanceMap

ProvenanceMap tracks provenance for multiple resources

type ProvenanceMap map[string][]ProvenanceInfo // key is "resourceType:resourceID:fieldPath"

type ProvenanceReport

ProvenanceReport generates a human-readable provenance report

type ProvenanceReport struct {
    Resources map[string]ResourceProvenance // key is "resourceType:resourceID"
}

func GenerateReport
func GenerateReport(provenance ProvenanceMap) *ProvenanceReport

GenerateReport creates a provenance report from a ProvenanceMap

func (*ProvenanceReport) String
func (r *ProvenanceReport) String() string

String generates a string representation of the provenance report

type ProvenanceTracker

ProvenanceTracker manages provenance tracking during reconciliation

type ProvenanceTracker interface {
    // Track records provenance for a field
    Track(resourceType ResourceType, resourceID string, field string, info ProvenanceInfo)

    // GetProvenance retrieves provenance for a specific field
    GetProvenance(resourceType ResourceType, resourceID string, field string) []ProvenanceInfo

    // GetResourceProvenance retrieves all provenance for a resource
    GetResourceProvenance(resourceType ResourceType, resourceID string) map[string][]ProvenanceInfo

    // Export returns the complete provenance map
    Export() ProvenanceMap

    // Clear removes all provenance data
    Clear()
}

func NewProvenanceTracker
func NewProvenanceTracker(enabled bool) ProvenanceTracker

NewProvenanceTracker creates a new provenance tracker

type ProviderChangeset

ProviderChangeset represents changes to providers

type ProviderChangeset struct {
    Added   []catalogs.Provider // New providers
    Updated []ProviderUpdate    // Updated providers
    Removed []catalogs.Provider // Removed providers
}

func (*ProviderChangeset) HasChanges
func (p *ProviderChangeset) HasChanges() bool

HasChanges returns true if the provider changeset contains any changes

func (*ProviderChangeset) Print
func (p *ProviderChangeset) Print()

Print outputs provider changes in a human-readable format

type ProviderUpdate

ProviderUpdate represents an update to an existing provider

type ProviderUpdate struct {
    ID       catalogs.ProviderID // ID of the provider being updated
    Existing catalogs.Provider   // Current provider
    New      catalogs.Provider   // New provider
    Changes  []FieldChange       // Detailed list of field changes
}

type Reconciler

Reconciler is the main interface for reconciling data from multiple sources

type Reconciler interface {
    // ReconcileCatalogs merges multiple catalogs from different sources
    ReconcileCatalogs(ctx context.Context, sources map[SourceName]catalogs.Catalog) (*Result, error)

    // ReconcileModels merges models from multiple sources
    ReconcileModels(sources map[SourceName][]catalogs.Model) ([]catalogs.Model, ProvenanceMap, error)

    // ReconcileProviders merges providers from multiple sources
    ReconcileProviders(sources map[SourceName][]catalogs.Provider) ([]catalogs.Provider, ProvenanceMap, error)
}

func New
func New(opts ...Option) (Reconciler, error)

New creates a new Reconciler with options

type Resolution

Resolution represents a conflict resolution decision

type Resolution struct {
    Conflict Conflict
    Decision ConflictResolution
    Value    interface{}
    Reason   string
}

type ResourceProvenance

ResourceProvenance contains provenance for a single resource

type ResourceProvenance struct {
    Type   ResourceType
    ID     string
    Fields map[string]FieldProvenance
}

type ResourceType

ResourceType identifies the type of resource being merged

type ResourceType string


const (
    ResourceTypeModel    ResourceType = "model"
    ResourceTypeProvider ResourceType = "provider"
    ResourceTypeAuthor   ResourceType = "author"
)

type Result

Result represents the outcome of a reconciliation operation

type Result struct {
    // Success indicates if reconciliation completed successfully
    Success bool

    // Catalog is the reconciled catalog (if successful)
    Catalog catalogs.Catalog

    // Changeset contains all changes that were detected
    Changeset *Changeset

    // AppliedChanges contains changes that were actually applied
    AppliedChanges *Changeset

    // Errors contains any errors that occurred
    Errors []error

    // Warnings contains non-critical issues
    Warnings []string

    // Metadata about the reconciliation
    Metadata ResultMetadata

    // Provenance information for audit trail
    Provenance ProvenanceMap
}

func (*Result) HasChanges
func (r *Result) HasChanges() bool

HasChanges returns true if any changes were detected

func (*Result) HasErrors
func (r *Result) HasErrors() bool

HasErrors returns true if there were errors

func (*Result) HasWarnings
func (r *Result) HasWarnings() bool

HasWarnings returns true if there were warnings

func (*Result) IsSuccess
func (r *Result) IsSuccess() bool

IsSuccess returns true if the reconciliation was successful

func (*Result) Report
func (r *Result) Report() string

Report generates a detailed report of the reconciliation

func (*Result) Summary
func (r *Result) Summary() string

Summary returns a human-readable summary of the result

func (*Result) WasApplied
func (r *Result) WasApplied() bool

WasApplied returns true if changes were applied

type ResultBuilder

ResultBuilder helps construct Result objects

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

func NewResultBuilder
func NewResultBuilder() *ResultBuilder

NewResultBuilder creates a new ResultBuilder

func (*ResultBuilder) Build
func (b *ResultBuilder) Build() *Result

Build finalizes and returns the Result

func (*ResultBuilder) WithAppliedChanges
func (b *ResultBuilder) WithAppliedChanges(changeset *Changeset) *ResultBuilder

WithAppliedChanges sets the applied changes

func (*ResultBuilder) WithCatalog
func (b *ResultBuilder) WithCatalog(catalog catalogs.Catalog) *ResultBuilder

WithCatalog sets the reconciled catalog

func (*ResultBuilder) WithChangeset
func (b *ResultBuilder) WithChangeset(changeset *Changeset) *ResultBuilder

WithChangeset sets the detected changes

func (*ResultBuilder) WithDryRun
func (b *ResultBuilder) WithDryRun(dryRun bool) *ResultBuilder

WithDryRun marks this as a dry run

func (*ResultBuilder) WithError
func (b *ResultBuilder) WithError(err error) *ResultBuilder

WithError adds an error

func (*ResultBuilder) WithProvenance
func (b *ResultBuilder) WithProvenance(provenance ProvenanceMap) *ResultBuilder

WithProvenance sets the provenance map

func (*ResultBuilder) WithSources
func (b *ResultBuilder) WithSources(sources ...SourceName) *ResultBuilder

WithSources sets the sources that were reconciled

func (*ResultBuilder) WithStatistics
func (b *ResultBuilder) WithStatistics(stats ResultStatistics) *ResultBuilder

WithStatistics sets the result statistics

func (*ResultBuilder) WithStrategy
func (b *ResultBuilder) WithStrategy(strategy Strategy) *ResultBuilder

WithStrategy sets the reconciliation strategy

func (*ResultBuilder) WithWarning
func (b *ResultBuilder) WithWarning(warning string) *ResultBuilder

WithWarning adds a warning

type ResultMetadata

ResultMetadata contains metadata about the reconciliation process

type ResultMetadata struct {
    // StartTime when reconciliation started
    StartTime time.Time

    // EndTime when reconciliation completed
    EndTime time.Time

    // Duration of the reconciliation
    Duration time.Duration

    // Sources that were reconciled
    Sources []SourceName

    // Strategy used for reconciliation
    Strategy Strategy

    // DryRun indicates if this was a dry-run
    DryRun bool

    // Statistics about the reconciliation
    Stats ResultStatistics
}

type ResultStatistics

ResultStatistics contains statistics about the reconciliation

type ResultStatistics struct {
    // Number of resources processed
    ModelsProcessed    int
    ProvidersProcessed int
    AuthorsProcessed   int

    // Number of conflicts resolved
    ConflictsResolved int

    // Number of resources skipped
    ResourcesSkipped int

    // Performance metrics
    MergeTimeMs int64
    DiffTimeMs  int64
    ApplyTimeMs int64
    TotalTimeMs int64
}

type SourceName

SourceName represents the name/type of a data source

type SourceName string

Common source names

const (
    ProviderAPI   SourceName = "Provider APIs"
    ModelsDevGit  SourceName = "models.dev (git)"
    ModelsDevHTTP SourceName = "models.dev (http)"
    LocalCatalog  SourceName = "Local Catalog"
)

func (SourceName) String
func (sn SourceName) String() string

String returns the string representation of a source name

type SourcePriorityOrderStrategy

SourcePriorityOrderStrategy resolves conflicts using a fixed source precedence order. Sources earlier in the priority slice have higher precedence than sources later in the slice.

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

func (*SourcePriorityOrderStrategy) ResolveConflict
func (s *SourcePriorityOrderStrategy) ResolveConflict(field string, values map[SourceName]interface{}) (interface{}, SourceName, string)

ResolveConflict uses source priority order to resolve conflicts

type StrategicMerger

StrategicMerger implements strategic three-way merge

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

func NewStrategicMerger
func NewStrategicMerger(authorities AuthorityProvider, strategy Strategy) *StrategicMerger

NewStrategicMerger creates a new StrategicMerger

func (*StrategicMerger) MergeField
func (sm *StrategicMerger) MergeField(fieldPath string, values map[SourceName]interface{}) (interface{}, SourceName)

MergeField merges a single field using authorities

func (*StrategicMerger) MergeModels
func (sm *StrategicMerger) MergeModels(sources map[SourceName][]catalogs.Model) ([]catalogs.Model, ProvenanceMap, error)

MergeModels merges models from multiple sources

func (*StrategicMerger) MergeProviders
func (sm *StrategicMerger) MergeProviders(sources map[SourceName][]catalogs.Provider) ([]catalogs.Provider, ProvenanceMap, error)

MergeProviders merges providers from multiple sources

func (*StrategicMerger) WithProvenance
func (sm *StrategicMerger) WithProvenance(tracker ProvenanceTracker)

WithProvenance sets the provenance tracker

type Strategy

Strategy defines how reconciliation should be performed

type Strategy interface {
    // Name returns the strategy name
    Name() string

    // Description returns a human-readable description
    Description() string

    // ShouldMerge determines if resources should be merged
    ShouldMerge(resourceType ResourceType) bool

    // ResolveConflict determines how to resolve conflicts
    ResolveConflict(field string, values map[SourceName]interface{}) (interface{}, SourceName, string)

    // ValidateResult validates the reconciliation result
    ValidateResult(result *Result) error

    // GetApplyStrategy returns how changes should be applied
    GetApplyStrategy() ApplyStrategy
}

func NewAuthorityBasedStrategy
func NewAuthorityBasedStrategy(authorities AuthorityProvider) Strategy

NewAuthorityBasedStrategy creates a new authority-based strategy

func NewCustomStrategy
func NewCustomStrategy(name, description string, resolver ConflictResolver) Strategy

NewCustomStrategy creates a new custom strategy

func NewSourcePriorityOrderStrategy
func NewSourcePriorityOrderStrategy(priorityOrder []SourceName) Strategy

NewSourcePriorityOrderStrategy creates a new source priority order strategy. The priorityOrder slice determines precedence: earlier elements have higher priority.

func NewStrategyChain
func NewStrategyChain(strategies ...Strategy) Strategy

NewStrategyChain creates a new strategy chain

func NewUnionStrategy
func NewUnionStrategy() Strategy

NewUnionStrategy creates a new union strategy

type StrategyChain

StrategyChain combines multiple strategies with fallback

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

func (*StrategyChain) Description
func (s *StrategyChain) Description() string

Description returns a human-readable description

func (*StrategyChain) GetApplyStrategy
func (s *StrategyChain) GetApplyStrategy() ApplyStrategy

GetApplyStrategy returns the first strategy's apply strategy

func (*StrategyChain) Name
func (s *StrategyChain) Name() string

Name returns the strategy name

func (*StrategyChain) ResolveConflict
func (s *StrategyChain) ResolveConflict(field string, values map[SourceName]interface{}) (interface{}, SourceName, string)

ResolveConflict tries each strategy in order

func (*StrategyChain) ShouldMerge
func (s *StrategyChain) ShouldMerge(resourceType ResourceType) bool

ShouldMerge checks all strategies

func (*StrategyChain) ValidateResult
func (s *StrategyChain) ValidateResult(result *Result) error

ValidateResult validates using all strategies

type ThreeWayMerger

ThreeWayMerger performs three-way merges with conflict resolution

type ThreeWayMerger interface {
    // MergeModels performs a three-way merge on models
    MergeModels(base, ours, theirs catalogs.Model) (catalogs.Model, []Conflict, error)

    // MergeProviders performs a three-way merge on providers
    MergeProviders(base, ours, theirs catalogs.Provider) (catalogs.Provider, []Conflict, error)

    // MergeAuthors performs a three-way merge on authors
    MergeAuthors(base, ours, theirs catalogs.Author) (catalogs.Author, []Conflict, error)

    // ResolveConflicts applies a conflict resolution strategy
    ResolveConflicts(conflicts []Conflict, strategy ConflictResolution) []Resolution
}

func NewThreeWayMerger
func NewThreeWayMerger(authorities AuthorityProvider, strategy Strategy) ThreeWayMerger

NewThreeWayMerger creates a new three-way merger

type UnionStrategy

UnionStrategy combines all values without conflict resolution

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

func (*UnionStrategy) ResolveConflict
func (s *UnionStrategy) ResolveConflict(field string, values map[SourceName]interface{}) (interface{}, SourceName, string)

ResolveConflict in union strategy returns the first non-nil value in a deterministic order

type ValidationError

ValidationError represents a validation error

type ValidationError struct {
    ResourceType ResourceType
    ResourceID   string
    Field        string
    Message      string
}

type ValidationResult

ValidationResult represents the result of validating a catalog or changeset

type ValidationResult struct {
    Valid    bool
    Errors   []ValidationError
    Warnings []ValidationWarning
}

func (*ValidationResult) HasWarnings
func (v *ValidationResult) HasWarnings() bool

HasWarnings returns true if there are warnings

func (*ValidationResult) IsValid
func (v *ValidationResult) IsValid() bool

IsValid returns true if validation passed

func (*ValidationResult) String
func (v *ValidationResult) String() string

String returns a string representation of the validation result

type ValidationWarning

ValidationWarning represents a validation warning

type ValidationWarning struct {
    ResourceType ResourceType
    ResourceID   string
    Field        string
    Message      string
}

Generated by gomarkdoc

Documentation

Overview

Package reconciler provides catalog synchronization and reconciliation capabilities. It handles merging data from multiple sources, detecting changes, and applying updates while respecting data authorities and merge strategies.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func ConvertCatalogsMapToSources 

func ConvertCatalogsMapToSources(srcs map[sources.Type]catalogs.Catalog) []sources.Source

ConvertCatalogsMapToSources converts the old map format to sources slice for testing.

func NewMockSource 

func NewMockSource(sourceType sources.Type, catalog catalogs.Catalog) sources.Source

NewMockSource creates a new mock source for testing.

Types

type AuthorityStrategy 

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

AuthorityStrategy uses field authorities to resolve conflicts.

func (*AuthorityStrategy) ApplyStrategy 

func (s *AuthorityStrategy) ApplyStrategy() differ.ApplyStrategy

ApplyStrategy returns how changes should be applied.

func (*AuthorityStrategy) Description 

func (s *AuthorityStrategy) Description() string

Description returns a human-readable description.

func (*AuthorityStrategy) ResolveConflict 

func (s *AuthorityStrategy) ResolveConflict(field string, values map[sources.Type]any) (any, sources.Type, string)

ResolveConflict uses authorities to resolve conflicts.

func (*AuthorityStrategy) ShouldMerge 

func (s *AuthorityStrategy) ShouldMerge(resourceType sources.ResourceType) bool

ShouldMerge determines if resources should be merged.

func (*AuthorityStrategy) Type 

func (s *AuthorityStrategy) Type() StrategyType

Type returns the strategy type.

func (*AuthorityStrategy) ValidateResult 

func (s *AuthorityStrategy) ValidateResult(result *Result) error

ValidateResult validates the reconciliation result.

type Merger 

type Merger interface {
	// Models merges models from multiple sources
	Models(sources map[sources.Type][]catalogs.Model) ([]catalogs.Model, provenance.Map, error)

	// Providers merges providers from multiple sources
	Providers(sources map[sources.Type][]catalogs.Provider) ([]catalogs.Provider, provenance.Map, error)
}

Merger performs the actual merging of resources.

type Option 

type Option func(*options) error

Option is a function that configures a Reconciler.

func WithAuthorities 

func WithAuthorities(authorities authority.Authority) Option

WithAuthorities sets the field authorities.

func WithBaseline 

func WithBaseline(catalog catalogs.Catalog) Option

WithBaseline sets an existing catalog to compare against for change detection.

func WithEnhancers 

func WithEnhancers(enhancers ...enhancer.Enhancer) Option

WithEnhancers adds model enhancers to the pipeline.

func WithProvenance 

func WithProvenance(enabled bool) Option

WithProvenance enables field-level tracking.

func WithStrategy 

func WithStrategy(strategy Strategy) Option

WithStrategy sets the merge strategy.

type Reconciler 

type Reconciler interface {
	// Sources reconciles multiple catalogs from different sources
	// The primary source determines which models exist; other sources provide enrichment only
	Sources(ctx context.Context, primary sources.Type, srcs []sources.Source) (*Result, error)
}

Reconciler is the main interface for reconciling data from multiple sources.

func New 

func New(opts ...Option) (Reconciler, error)

New creates a new Reconciler with options.

type Result 

type Result struct {
	// Core data
	Catalog        catalogs.Catalog
	Changeset      *differ.Changeset
	AppliedChanges *differ.Changeset

	// Tracking maps
	ProviderAPICounts map[catalogs.ProviderID]int
	ModelProviderMap  map[string]catalogs.ProviderID

	// Metadata
	Metadata ResultMetadata

	// Provenance tracking
	Provenance provenance.Map

	// Issues
	Errors   []error
	Warnings []string
}

Result represents the outcome of a reconciliation operation.

func NewResult 

func NewResult() *Result

NewResult creates a new result with defaults.

func (*Result) Finalize 

func (r *Result) Finalize()

Finalize calculates duration and marks completion.

func (*Result) HasChanges 

func (r *Result) HasChanges() bool

HasChanges returns true if any changes were detected.

func (*Result) IsSuccess 

func (r *Result) IsSuccess() bool

IsSuccess returns true if the reconciliation was successful.

func (*Result) Summary 

func (r *Result) Summary() string

Summary returns a human-readable summary of the result.

func (*Result) WasApplied 

func (r *Result) WasApplied() bool

WasApplied returns true if changes were applied.

type ResultMetadata 

type ResultMetadata struct {
	// StartTime when reconciliation started
	StartTime time.Time

	// EndTime when reconciliation completed
	EndTime time.Time

	// Duration of the reconciliation
	Duration time.Duration

	// Sources that were reconciled
	Sources []sources.Type

	// Strategy used for reconciliation
	Strategy Strategy

	// DryRun indicates if this was a dry-run
	DryRun bool

	// Statistics about the reconciliation
	Stats ResultStatistics
}

ResultMetadata contains metadata about the reconciliation process.

type ResultStatistics 

type ResultStatistics struct {
	ModelsProcessed    int
	ProvidersProcessed int
	ConflictsResolved  int
	ResourcesSkipped   int
	TotalTimeMs        int64
}

ResultStatistics contains statistics about the reconciliation.

type SourceOrderStrategy 

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

SourceOrderStrategy resolves conflicts using a fixed source precedence order. Sources earlier in the priority slice have higher precedence than sources later in the slice.

func (*SourceOrderStrategy) ApplyStrategy 

func (s *SourceOrderStrategy) ApplyStrategy() differ.ApplyStrategy

ApplyStrategy returns how changes should be applied.

func (*SourceOrderStrategy) Description 

func (s *SourceOrderStrategy) Description() string

Description returns a human-readable description.

func (*SourceOrderStrategy) ResolveConflict 

func (s *SourceOrderStrategy) ResolveConflict(_ string, values map[sources.Type]any) (any, sources.Type, string)

ResolveConflict uses source priority order to resolve conflicts.

func (*SourceOrderStrategy) ShouldMerge 

func (s *SourceOrderStrategy) ShouldMerge(resourceType sources.ResourceType) bool

ShouldMerge determines if resources should be merged.

func (*SourceOrderStrategy) Type 

func (s *SourceOrderStrategy) Type() StrategyType

Type returns the strategy type.

func (*SourceOrderStrategy) ValidateResult 

func (s *SourceOrderStrategy) ValidateResult(result *Result) error

ValidateResult validates the reconciliation result.

type Strategy 

type Strategy interface {
	// Type returns the strategy type
	Type() StrategyType

	// Description returns a human-readable description
	Description() string

	// ShouldMerge determines if resources should be merged
	ShouldMerge(resourceType sources.ResourceType) bool

	// ResolveConflict determines how to resolve conflicts
	ResolveConflict(field string, values map[sources.Type]any) (any, sources.Type, string)

	// ValidateResult validates the reconciliation result
	ValidateResult(result *Result) error

	// ApplyStrategy returns how changes should be applied
	ApplyStrategy() differ.ApplyStrategy
}

Strategy defines how reconciliation should be performed.

func NewAuthorityStrategy 

func NewAuthorityStrategy(authorities authority.Authority) Strategy

NewAuthorityStrategy creates a new authority-based strategy.

func NewSourceOrderStrategy 

func NewSourceOrderStrategy(priorityOrder []sources.Type) Strategy

NewSourceOrderStrategy creates a new source priority order strategy. The priorityOrder slice determines precedence: earlier elements have higher priority.

type StrategyType 

type StrategyType string

StrategyType represents the type of reconciliation strategy. 

const (
	// StrategyTypeFieldAuthority uses field-specific authority scores to resolve conflicts.
	StrategyTypeFieldAuthority StrategyType = "field-authority"
	// StrategyTypeSourceOrder uses source ordering to resolve conflicts.
	StrategyTypeSourceOrder StrategyType = "source-order"
)

func (StrategyType) Name 

func (s StrategyType) Name() string

Name returns the name of the strategy type.

func (StrategyType) String 

func (s StrategyType) String() string

String returns the string representation of a strategy type.

type ValidationError 

type ValidationError struct {
	ResourceType sources.ResourceType
	ResourceID   string
	Field        string
	Message      string
}

ValidationError represents a validation error.

type ValidationResult 

type ValidationResult struct {
	Valid    bool
	Errors   []ValidationError
	Warnings []ValidationWarning
}

ValidationResult represents the result of validating a catalog or changeset.

func (*ValidationResult) HasWarnings 

func (v *ValidationResult) HasWarnings() bool

HasWarnings returns true if there are warnings.

func (*ValidationResult) IsValid 

func (v *ValidationResult) IsValid() bool

IsValid returns true if validation passed.

func (*ValidationResult) String 

func (v *ValidationResult) String() string

String returns a string representation of the validation result.

type ValidationWarning 

type ValidationWarning struct {
	ResourceType sources.ResourceType
	ResourceID   string
	Field        string
	Message      string
}

ValidationWarning represents a validation warning.

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.