config

Documentation

Overview

Package config provides functionality to load and validate the Reconify configuration

Index

• Constants
• type CSVParserCfg
• type Config
  • func Load(path string) (*Config, error)
  • func (c *Config) Validate() []error
• type DuplicatePolicy
• type IndexCfg
• type Pair
  • func (p Pair) Counterparts() []string
• type ParserCfg
  • func (p ParserCfg) ResolvedDuplicatePolicy() DuplicatePolicy
• type PassConfig
  • func (p PassConfig) ResolvedGroupBy() string
• type ResultMode
• type Source

Constants

const (
	PassTypeReferenceOneToOne  = "reference_one_to_one"
	PassTypeNameTokensOneToOne = "name_tokens_one_to_one"
	PassTypeOneToMany          = "one_to_many"
	PassTypeManyToMany         = "many_to_many"
)

Pass type constants for recognized matching strategies.

const (
	GroupByReference = "reference"
	GroupByName      = "name"
	GroupByGroupKey  = "group_key"
)

GroupBy constants for grouped passes.

Types

type CSVParserCfg

type CSVParserCfg = ParserCfg

CSVParserCfg is kept as an alias for existing Go callers.

type Config

type Config struct {
	Version  int               `yaml:"version"`
	Timezone string            `yaml:"timezone"`
	Index    IndexCfg          `yaml:"index,omitempty"`
	Sources  map[string]Source `yaml:"sources"`
	Pairs    map[string]Pair   `yaml:"pairs"`
}

Config represents the root configuration structure

func Load

func Load(path string) (*Config, error)

Load reads and parses a YAML configuration file

func (*Config) Validate

func (c *Config) Validate() []error

Validate performs structural validation on the configuration

type DuplicatePolicy

type DuplicatePolicy string

DuplicatePolicy controls how transactions sharing the same GroupKey are handled.

const (
	// DuplicatePolicyFlag surfaces duplicates via WriteDuplicate; all rows
	// participate in matching. Default when duplicate_policy is unset.
	DuplicatePolicyFlag DuplicatePolicy = "flag"
	// DuplicatePolicyKeep treats each duplicate as a distinct row; all rows
	// participate in matching; WriteDuplicate is never called.
	DuplicatePolicyKeep DuplicatePolicy = "keep"
	// DuplicatePolicyMerge collapses duplicates to the first-seen row per
	// GroupKey before matching; WriteDuplicate is never called.
	DuplicatePolicyMerge DuplicatePolicy = "merge"
	// DuplicatePolicyLatest collapses duplicates to the last-seen row per
	// GroupKey (by file order) before matching; WriteDuplicate is never called.
	DuplicatePolicyLatest DuplicatePolicy = "latest"
)

type IndexCfg

type IndexCfg struct {
	// Backend is one of: memory, disk, auto, partitioned.
	// Default (empty) is memory.
	Backend string `yaml:"backend,omitempty"`
	// SpillDir is the directory used for disk index temporary files.
	// Ignored when Backend=memory.
	SpillDir string `yaml:"spill_dir,omitempty"`
	// AutoMaxRightFileMB is the threshold (in MB) for Backend=auto.
	// If right file size exceeds this value, disk backend is selected.
	// Default (0) is 2048 MB.
	AutoMaxRightFileMB int64 `yaml:"auto_max_right_file_mb,omitempty"`
	// MaxMemoryMB is the maximum estimated resident memory for index selection.
	// Zero leaves memory uncapped for backwards compatibility.
	MaxMemoryMB int64 `yaml:"max_memory_mb,omitempty"`
	// MaxTempDiskMB is the maximum estimated temporary storage for disk or
	// partitioned indexing. Zero leaves the configured budget uncapped, but the
	// selector still checks actual free space.
	MaxTempDiskMB int64 `yaml:"max_temp_disk_mb,omitempty"`
	// PartitionCount controls the number of hash partitions for the bounded-memory
	// backend. Zero uses the default (32); positive values must be at least 2.
	PartitionCount int `yaml:"partition_count,omitempty"`
}

IndexCfg controls which right-side index backend ReconcileStreaming uses.

type Pair

type Pair struct {
	Left                 string `yaml:"left"`
	Right                string `yaml:"right"`
	DateWindow           string `yaml:"date_window"`
	AmountToleranceMinor int64  `yaml:"amount_tolerance_minor"`
	NameMode             string `yaml:"name_mode"`
	// NameMatchThreshold is the minimum Jaccard token-overlap score (0 < x < 1)
	// a candidate must exceed (strictly) for a name_mode=tokens match. Defaults
	// to 0.5 when unset. 1.0 is rejected by validation: since the comparison is
	// strict (score > threshold) and a Jaccard score never exceeds 1.0, a
	// threshold of exactly 1.0 would silently match nothing.
	NameMatchThreshold float64 `yaml:"name_match_threshold,omitempty"`
	// Rights lists multiple counterpart sources reconciled against Left in order:
	// unmatched left transactions from one pass feed into the next. Mutually
	// exclusive with Right — set exactly one of the two. Use Counterparts() to
	// read the resolved list regardless of which field was set.
	Rights []string `yaml:"rights,omitempty"`
	// Passes defines an explicit ordered list of matching strategies. When set,
	// passes run in order and each pass only sees rows left unmatched by earlier
	// passes. Omitting Passes preserves legacy behavior: reference matching
	// followed by optional name_mode=tokens. When Passes is set, name_mode=tokens
	// is rejected — add a name_tokens_one_to_one pass explicitly instead.
	Passes []PassConfig `yaml:"passes,omitempty"`
	// ResultMode controls which events the result writer emits for this pair.
	// Valid values: "all" (default), "exceptions_only", "summary_only".
	// The CLI flag --result-mode overrides this when explicitly provided.
	ResultMode ResultMode `yaml:"result_mode,omitempty"`
}

Pair defines a reconciliation pair configuration

func (Pair) Counterparts

func (p Pair) Counterparts() []string

Counterparts returns the ordered list of counterpart source names for this pair, regardless of whether Right or Rights was configured. Single-counterpart configs (Right set, Rights empty) return a one-element slice — callers should treat that as equivalent to today's behavior.

type ParserCfg

type ParserCfg struct {
	Type        string `yaml:"type"`
	DateCol     string `yaml:"date_col"`
	DateLayout  string `yaml:"date_layout"`
	TZ          string `yaml:"tz"`
	AmountCol   string `yaml:"amount_col"`
	Decimal     string `yaml:"decimal"`
	Thousands   string `yaml:"thousands"`
	Multiplier  int64  `yaml:"multiplier"`
	CurrencyCol string `yaml:"currency_col,omitempty"`
	NameCol     string `yaml:"name_col,omitempty"`
	RefCol      string `yaml:"ref_col,omitempty"`
	// GroupCol is the duplicate/grouping key column. It is independent of RefCol:
	// RefCol is the matching key, GroupCol is the key used to detect duplicates
	// (e.g. an invoice number shared by several installment payments that each
	// have a unique RefCol value). Falls back to RefCol when empty.
	GroupCol string `yaml:"group_col,omitempty"`
	Sheet    string `yaml:"sheet,omitempty"`
	// SkipRaw skips the per-row Raw map[string]string allocation.
	// Set to true for large files to reduce allocator pressure.
	// Default false preserves the Raw field on every Transaction.
	SkipRaw bool `yaml:"skip_raw,omitempty"`
	// DuplicatePolicy controls how transactions sharing the same GroupKey are handled.
	// Valid values: "flag" (default), "keep", "merge", "latest".
	DuplicatePolicy DuplicatePolicy `yaml:"duplicate_policy,omitempty"`
}

ParserCfg defines source parsing configuration for CSV, JSON, and XLSX files.

func (ParserCfg) ResolvedDuplicatePolicy

func (p ParserCfg) ResolvedDuplicatePolicy() DuplicatePolicy

ResolvedDuplicatePolicy returns the configured policy, defaulting to DuplicatePolicyFlag when the field is empty (preserves backward compatibility).

type PassConfig

type PassConfig struct {
	Type    string `yaml:"type"`
	GroupBy string `yaml:"group_by,omitempty"`
}

PassConfig defines a single matching pass within a pair's pipeline. Passes run in configured order; each pass only sees rows left unmatched by earlier passes.

func (PassConfig) ResolvedGroupBy

func (p PassConfig) ResolvedGroupBy() string

ResolvedGroupBy returns the configured group_by key, defaulting to GroupByReference when the field is empty.

type ResultMode

type ResultMode string

ResultMode controls which reconciliation events are emitted by the result writer.

const (
	// ResultModeAll emits every event: matches, diffs, unmatched, duplicates. Default.
	ResultModeAll ResultMode = "all"
	// ResultModeExceptionsOnly suppresses clean matches; emits unmatched, diffs,
	// duplicates, ambiguous groups, and grouped/N:M exception events.
	ResultModeExceptionsOnly ResultMode = "exceptions_only"
	// ResultModeSummaryOnly suppresses all item events; only the summary is emitted.
	ResultModeSummaryOnly ResultMode = "summary_only"
)

type Source

type Source struct {
	FilePattern string    `yaml:"file_pattern"`
	Parser      ParserCfg `yaml:"parser"`
}

Source defines a data source configuration