//go:build !libheif

package builtin

// fileread_heic_stub.go -- 未启用 libheif 构建标签时的 HEIC 解码桩实现.
//
// 默认构建(不加任何 tag)使用此桩,无任何系统依赖,纯 Go 编译.
// 原始 HEIC 数据原样返回,不做格式转换.
//
// 影响:HEIC/HEIF/AVIF 图片将以原始格式传给 API,
// 若 API 端点不支持该格式则图片不可读.
// 对于不处理 HEIC 图片的场景(运维 Agent,代码 Agent 等),零影响.
//
// 升华改进(ELEVATED): 自定义 build tag 而非内置 cgo tag--
// 早期方案依赖 //go:build cgo,CGO 默认开启时自动拉入 libheif 依赖,
// SDK 消费方(如 flysafe)无法在不安装系统库的情况下干净编译.
// 改为自定义 tag libheif 后,消费方按需选择:
//   - 运维场景:go build ./...(无需任何额外操作)
//   - 仓储场景:go build -tags libheif ./...(+ apt install libheif-dev)
//
// 替代方案:<强制 CGO=0 才能避免依赖>
// - 否决:CGO=0 会影响消费方其他 CGO 库(如 go-sqlite3)的正常使用.

import (
	"fmt"
	"image"
)

// correctHEICToJPEG 在未启用 libheif 时直接返回原始数据(fail-open).
func correctHEICToJPEG(data []byte) ([]byte, string) {
	return data, "image/heic"
}

// decodeHEIC 在未启用 libheif 时始终返回错误(桩实现).
//
// 精妙之处(CLEVER): 桩返回 error 而非 panic--
// 调用方 correctHEICToJPEG 已经 fail-open 处理 decodeHEIC 的错误,
// 返回 error 不影响运行时行为,同时允许 TestRealHEIC_DecodeLibheif_Smoke
// 在非 libheif 构建下正常编译并通过(该测试本身就期望 error).
func decodeHEIC(_ []byte) (image.Image, error) {
	return nil, fmt.Errorf("libheif not enabled: rebuild with -tags libheif")
}