semantic

type AssertionResult struct {
	AssertionURN string `json:"assertion_urn,omitempty"` // URN identifying the assertion
	Type         string `json:"type"`                    // FRESHNESS, SCHEMA, DATA_QUALITY
}

type CacheConfig struct {
	TTL time.Duration
}

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

type ColumnContext struct {
	// Basic info
	Name        string `json:"name"`
	Description string `json:"description,omitempty"`

	// Classification
	Tags          []string       `json:"tags,omitempty"`
	GlossaryTerms []GlossaryTerm `json:"glossary_terms,omitempty"`

	// Sensitivity
	IsPII       bool `json:"is_pii,omitempty"`
	IsSensitive bool `json:"is_sensitive,omitempty"`

	// Business metadata
	BusinessName string `json:"business_name,omitempty"`

	// InheritedFrom is set when metadata was inherited from upstream lineage.
	InheritedFrom *InheritedMetadata `json:"inherited_from,omitempty"`
}

type ColumnIdentifier struct {
	TableIdentifier
	Column string `json:"column"`
}

type DataContractStatus struct {
	Status           string            `json:"status"` // PASSING or FAILING
	AssertionResults []AssertionResult `json:"assertion_results,omitempty"`
}

type Deprecation struct {
	Deprecated bool       `json:"deprecated"`
	Note       string     `json:"note,omitempty"`
	Actor      string     `json:"actor,omitempty"`
	DecommDate *time.Time `json:"decommission_date,omitempty"`
}

type DocumentResult struct {
	URN     string `json:"urn"`
	Title   string `json:"title"`
	SubType string `json:"sub_type,omitempty"`
	Snippet string `json:"snippet,omitempty"`
	// Body is the full, untruncated document content. It is populated only by a
	// single-document read (GetDocument), where the whole point is to return the
	// complete content a search snippet elides; the relevance-search paths
	// (SearchDocuments, GetRelatedDocuments) leave it empty and populate the
	// bounded Snippet instead, so a multi-result search does not carry N full
	// bodies.
	Body string `json:"body,omitempty"`
	// Status is the publication state (PUBLISHED/UNPUBLISHED). The upstream search
	// applies no status filter, so a consumer carries this to exclude drafts.
	Status string `json:"status,omitempty"`
	// ShowInGlobalContext reports whether the document is meant to appear in global
	// search. The upstream search returns documents regardless of this flag, so a
	// search consumer must filter on it to honor a steward's choice to hide a document.
	ShowInGlobalContext bool     `json:"show_in_global_context"`
	RelatedAssetURNs    []string `json:"related_asset_urns,omitempty"`
}

type DocumentSearcher interface {
	// SearchDocuments ranks context documents by relevance to query; a query of "*"
	// lists all (an empty query does not list). Results carry ShowInGlobalContext and
	// Status so the caller can filter to globally-visible, published documents. limit
	// caps results (0 means the provider default).
	SearchDocuments(ctx context.Context, query string, limit int) ([]DocumentResult, error)

	// GetRelatedDocuments returns the context documents linked to an entity URN (the
	// reverse of a document's related assets), for entity-keyed discovery. Results
	// carry the same fields as SearchDocuments so the caller applies the same filter.
	GetRelatedDocuments(ctx context.Context, urn string) ([]DocumentResult, error)

	// GetDocument reads one context document by its URN, returning the full
	// untruncated body (in DocumentResult.Body) so an agent can dereference a
	// urn:li:document:<id> reference search emitted to the complete content. A URN
	// that resolves to no document returns ErrDocumentNotFound, which the fetch
	// surface maps to a structured not-found rather than an error.
	GetDocument(ctx context.Context, urn string) (*DocumentResult, error)

	// BrowseDocuments enumerates context documents for the browse surface (#695):
	// the offset/limit page of the complete document set plus the total document
	// count, so an agent can page the whole corpus to audit, dedup, or migrate it.
	// Unlike SearchDocuments this applies NO relevance threshold and NO
	// visibility/status filter: every document is enumerable (drafts and hidden
	// documents included), so the returned page and total describe the same complete
	// set. Results carry the same fields as SearchDocuments (a bounded Snippet, not
	// the full Body) since a listing shows what each document is, not its contents.
	BrowseDocuments(ctx context.Context, offset, limit int) (docs []DocumentResult, total int, err error)
}

type Domain struct {
	URN         string `json:"urn"`
	Name        string `json:"name"`
	Description string `json:"description,omitempty"`
}

type FieldFilter struct {
	// Field is the filter field (e.g., "fieldPaths", "fieldTags", "platform", "owners").
	Field string `json:"field"`

	// Values to match against.
	Values []string `json:"values"`

	// Condition is the match operator: CONTAIN, EQUAL (default), IN, EXISTS.
	Condition string `json:"condition,omitempty"`

	// Negated inverts the filter (exclude matching entities).
	Negated bool `json:"negated,omitempty"`
}

type GlossaryTerm struct {
	URN         string `json:"urn"`
	Name        string `json:"name"`
	Description string `json:"description,omitempty"`
}

type Incident struct {
	URN         string `json:"urn"`
	Type        string `json:"type"`
	Title       string `json:"title"`
	Description string `json:"description,omitempty"`
	State       string `json:"state"`
	Created     int64  `json:"created,omitempty"`
}

type InheritedMetadata struct {
	// SourceURN is the DataHub URN of the upstream dataset.
	SourceURN string `json:"source_urn"`

	// SourceColumn is the column name in the upstream dataset.
	SourceColumn string `json:"source_column"`

	// Hops is the distance from the target dataset (1 = direct upstream).
	Hops int `json:"hops"`

	// MatchMethod indicates how the column was matched.
	// Values: "column_lineage", "name_exact", "name_transformed", "alias"
	MatchMethod string `json:"match_method"`
}

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

type LineageDirection string

type LineageEdge struct {
	URN            string `json:"urn"`
	Type           string `json:"type,omitempty"`
	TransformLogic string `json:"transform_logic,omitempty"`
}

type LineageEntity struct {
	URN      string        `json:"urn"`
	Type     string        `json:"type"`
	Name     string        `json:"name"`
	Platform string        `json:"platform,omitempty"`
	Depth    int           `json:"depth"`
	Parents  []LineageEdge `json:"parents,omitempty"`
	Children []LineageEdge `json:"children,omitempty"`
	Context  *TableContext `json:"context,omitempty"`
}

type LineageInfo struct {
	Direction LineageDirection `json:"direction"`
	Entities  []LineageEntity  `json:"entities"`
	MaxDepth  int              `json:"max_depth"`
}

type NoopProvider struct{}

type Owner struct {
	URN   string    `json:"urn"`
	Type  OwnerType `json:"type"`
	Name  string    `json:"name,omitempty"`
	Email string    `json:"email,omitempty"`
}

type OwnerType string

type Provider interface {
	// Name returns the provider name.
	Name() string

	// GetTableContext retrieves semantic context for a table.
	GetTableContext(ctx context.Context, table TableIdentifier) (*TableContext, error)

	// GetColumnContext retrieves semantic context for a single column.
	GetColumnContext(ctx context.Context, column ColumnIdentifier) (*ColumnContext, error)

	// GetColumnsContext retrieves semantic context for all columns of a table.
	GetColumnsContext(ctx context.Context, table TableIdentifier) (map[string]*ColumnContext, error)

	// GetLineage retrieves lineage information for a table.
	GetLineage(ctx context.Context, table TableIdentifier, direction LineageDirection, maxDepth int) (*LineageInfo, error)

	// GetGlossaryTerm retrieves a glossary term by URN.
	GetGlossaryTerm(ctx context.Context, urn string) (*GlossaryTerm, error)

	// SearchTables searches for tables matching the filter.
	SearchTables(ctx context.Context, filter SearchFilter) ([]TableSearchResult, error)

	// GetCuratedQueryCount returns the number of curated/saved queries for a dataset.
	GetCuratedQueryCount(ctx context.Context, urn string) (int, error)

	// Close releases resources.
	Close() error
}

type SanitizeConfig struct {
	// MaxLength is the maximum length for strings (default: 2000).
	MaxLength int

	// StripInjectionPatterns removes detected injection patterns instead of flagging.
	StripInjectionPatterns bool

	// LogInjectionAttempts enables logging of detected injection attempts.
	LogInjectionAttempts bool
}

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

type SearchFilter struct {
	Query    string   `json:"query"`
	Platform string   `json:"platform,omitempty"`
	Tags     []string `json:"tags,omitempty"`
	Domain   string   `json:"domain,omitempty"`
	Owner    string   `json:"owner,omitempty"`
	Limit    int      `json:"limit,omitempty"`
	Offset   int      `json:"offset,omitempty"`

	// EntityTypes restricts search to specific entity types (e.g., "DATASET", "DASHBOARD").
	// If empty, defaults to the DataHub client's DefaultEntityType.
	EntityTypes []string `json:"entity_types,omitempty"`

	// Mode selects the search strategy: "keyword" (default) or "semantic".
	Mode string `json:"mode,omitempty"`

	// Filters provides advanced field-level filtering (e.g., by column name, column tag).
	// All filters are AND'd together. These map directly to DataHub's searchAcrossEntities
	// orFilters and support fields like fieldPaths, fieldTags, fieldGlossaryTerms, etc.
	Filters []FieldFilter `json:"filters,omitempty"`
}

type StructuredProperty struct {
	QualifiedName string `json:"qualified_name"`
	DisplayName   string `json:"display_name,omitempty"`
	Values        []any  `json:"values"`
}

type TableContext struct {
	// Basic info
	URN         string `json:"urn,omitempty"`
	Description string `json:"description,omitempty"`

	// Ownership
	Owners []Owner `json:"owners,omitempty"`

	// Classification
	Tags          []string       `json:"tags,omitempty"`
	GlossaryTerms []GlossaryTerm `json:"glossary_terms,omitempty"`
	Domain        *Domain        `json:"domain,omitempty"`

	// Status
	Deprecation *Deprecation `json:"deprecation,omitempty"`

	// Quality
	QualityScore *float64 `json:"quality_score,omitempty"`

	// Metadata
	CustomProperties map[string]string `json:"custom_properties,omitempty"`
	LastModified     *time.Time        `json:"last_modified,omitempty"`

	// Structured properties (DataHub 1.4.x)
	StructuredProperties []StructuredProperty `json:"structured_properties,omitempty"`

	// Incidents (DataHub 1.4.x)
	ActiveIncidents int        `json:"active_incidents,omitempty"`
	Incidents       []Incident `json:"incidents,omitempty"`

	// Data contracts (DataHub 1.4.x)
	DataContract *DataContractStatus `json:"data_contract,omitempty"`
}

type TableIdentifier struct {
	Catalog string `json:"catalog,omitempty"`
	Schema  string `json:"schema"`
	Table   string `json:"table"`
}

type TableSearchResult struct {
	URN          string   `json:"urn"`
	Name         string   `json:"name"`
	Platform     string   `json:"platform,omitempty"`
	Description  string   `json:"description,omitempty"`
	Tags         []string `json:"tags,omitempty"`
	Domain       string   `json:"domain,omitempty"`
	MatchedField string   `json:"matched_field,omitempty"`
}

type URNResolver interface {
	// ResolveURN converts a URN to a table identifier.
	ResolveURN(ctx context.Context, urn string) (*TableIdentifier, error)

	// BuildURN creates a URN from a table identifier.
	BuildURN(ctx context.Context, table TableIdentifier) (string, error)
}