sfga

type AccessorSFGA interface {
	// Config returns configuration data of the archive.
	Config() config.Config

	// Connect establishes a connection to the SQLite database and returns the
	// database handle or an error if the connection fails.
	Connect() (*sql.DB, error)

	// SetDb allows to change database of the archive.
	SetDb(path string)

	// Db returns connector to the database.
	Db() *sql.DB

	// Ping checks if database exists
	Ping() bool

	// Close terminates the database connection.
	Close() error

	// DbPath returns the path to the SFGA database file. If the file is not
	// yet available, it returns an empty string.
	DbPath() string

	// Version returns the version number of the SFGA schema.
	Version() string

	// IsCompatible returns back true if provided version is equal or larger
	// than the version of the database.
	IsCompatible(version string) bool
}

type Archive interface {
	arch.Packager
	AccessorSFGA
	Reader
	Writer
	Migrator
	Enricher
}

type Enricher interface {
	// InferBasionyms detects and creates basionym relationships by matching
	// stemmed epithets and original authorship across all names in the archive.
	// Behavior is controlled by Config.SkipBasionymsIfRelationsExist and
	// Config.CreateOriginalCombinations.
	InferBasionyms(ctx context.Context) error

	// AddParents builds a parent/child hierarchy from flat classification
	// fields (kingdom, phylum, class, etc.) in the taxon table. Works
	// in-place: deletes and re-inserts name, taxon, synonym, and
	// name_relation tables within a transaction. No-op if parent IDs
	// already exist or flat hierarchy is empty.
	AddParents(ctx context.Context) error
}

type Migrator interface {
	// Migrate brings the archive's schema up to the target version by
	// computing an Atlas diff between the live schema and the desired schema
	// (schema.sql at the target sflib tag) and applying only the necessary
	// changes. It operates on a copy written to dstDir so the source file is
	// never modified. Returns an Archive pointing at the migrated copy.
	Migrate(dstDir string) (Archive, error)
}

type Reader interface {
	LoadMeta() (*coldp.Meta, error)
	LoadAuthors(context.Context, chan<- coldp.Author) error
	LoadDistributions(context.Context, chan<- coldp.Distribution) error
	LoadMedia(context.Context, chan<- coldp.Media) error
	LoadNames(context.Context, chan<- coldp.Name) error
	LoadNameUsages(context.Context, chan<- coldp.NameUsage) error
	LoadNameRelationships(context.Context, chan<- coldp.NameRelation) error
	LoadReferences(context.Context, chan<- coldp.Reference) error
	LoadSpeciesEstimates(context.Context, chan<- coldp.SpeciesEstimate) error
	LoadSpeciesInteractions(context.Context, chan<- coldp.SpeciesInteraction) error
	LoadSynonyms(context.Context, chan<- coldp.Synonym) error
	LoadTaxonConceptRelations(context.Context, chan<- coldp.TaxonConceptRelation) error
	LoadTaxonProperties(context.Context, chan<- coldp.TaxonProperty) error
	LoadTaxa(context.Context, chan<- coldp.Taxon) error
	LoadTreatments(context.Context, chan<- coldp.Treatment) error
	LoadTypeMaterials(context.Context, chan<- coldp.TypeMaterial) error
	LoadVernaculars(context.Context, chan<- coldp.Vernacular) error
}

type Schema interface {
	// Fetch retrieves the SFGA schema based on the configured Git repository.
	// Returns the schema in bytes, and an error if retrieval fails or the
	// downloaded schema's SHA256 hash doesn't match the expected value.
	Fetch() ([]byte, error)
}

type Writer interface {
	// InsertMeta saves data from *coldp.Meta object to SFGA DB.
	InsertMeta(meta *coldp.Meta) error

	// InsertAuthors saves data from coldp.Author objects to SFGA DB.
	InsertAuthors(data []coldp.Author) error

	// InsertDistributions saves data from coldp.Distribution objects to
	// SFGA DB.
	InsertDistributions(data []coldp.Distribution) error

	// InsertMedia saves data from coldp.Media objects to SFGA DB.
	InsertMedia(data []coldp.Media) error

	// InsertNames saves data from coldp.Name objects to SFGA DB.
	InsertNames(data []coldp.Name) error

	// InsertNameRelations saves data from coldp.NameRelation objects to
	// SFGA Db.
	InsertNameRelations(data []coldp.NameRelation) error

	// InsertNameUsages saves data from coldp.NameUsage objects to
	// SFGA Db.
	InsertNameUsages(data []coldp.NameUsage) error

	// InsertReferences saves data from coldp.Reference objects to
	// SFGA Db.
	InsertReferences(data []coldp.Reference) error

	// InsertSpeciesEstimates saves data from  coldp.SpeciesEstimate objects to
	// SFGA Db.
	InsertSpeciesEstimates(data []coldp.SpeciesEstimate) error

	// InsertSpeciesInteractions saves data from coldp.SpeciesInteraction objects
	// to SFGA Db.
	InsertSpeciesInteractions(data []coldp.SpeciesInteraction) error

	// InsertSynonyms saves data from coldp.Synonym objects
	// to SFGA Db.
	InsertSynonyms(data []coldp.Synonym) error

	// InsertTaxa saves data from coldp.Taxon objects
	// to SFGA Db.
	InsertTaxa(data []coldp.Taxon) error

	// InsertTaxonConceptRelations saves data from coldp.TaxonConcepRelation
	// objects to SFGA Db.
	InsertTaxonConceptRelations(data []coldp.TaxonConceptRelation) error

	// InsertTaxonProperties saves data from coldp.TaxonProperty objects to SFGA
	// Db.
	InsertTaxonProperties(data []coldp.TaxonProperty) error

	// InsertTreatments saves data from coldp.Treatment objects to SFGA Db.
	InsertTreatments(data []coldp.Treatment) error

	// InsertTypeMaterials saves data from coldp.TypeMaterial objects to SFGA Db.
	InsertTypeMaterials(data []coldp.TypeMaterial) error

	// InsertVernaculars saves data from coldp.Vernacular objects to SFGA Db.
	InsertVernaculars(data []coldp.Vernacular) error
}