compare

type Comparison struct {
	Target             int          `json:"target"`
	Equal              bool         `json:"equal"`
	PagesEqual         bool         `json:"pages_equal"`
	Summary            Summary      `json:"summary"`
	DirectoriesAdded   []string     `json:"directories_added"`
	DirectoriesRemoved []string     `json:"directories_removed"`
	Files              []FileChange `json:"files"`
	Pages              []PageChange `json:"pages"`
}

type DocumentInfo struct {
	Number  int    `json:"number"`
	ID      string `json:"id"`
	Title   string `json:"title,omitempty"`
	Author  string `json:"author,omitempty"`
	Subject string `json:"subject,omitempty"`
	Creator string `json:"creator,omitempty"`
}

type File struct {
	Path      string `json:"path"`
	Size      uint64 `json:"size"`
	SHA256    string `json:"sha256"`
	Kind      string `json:"kind"`
	XMLSHA256 string `json:"xml_sha256,omitempty"`
	XMLNote   string `json:"xml_note,omitempty"`
}

type FileChange struct {
	Status       string        `json:"status"`
	Before       *File         `json:"before,omitempty"`
	After        *File         `json:"after,omitempty"`
	XMLChanges   []ValueChange `json:"xml_changes,omitempty"`
	XMLTruncated bool          `json:"xml_truncated,omitempty"`
	// XMLView 保存有大小限制的规范化 XML 行对照；字段差异仍由 XMLChanges 提供。
	XMLView       *XMLView `json:"xml_view,omitempty"`
	BeforePreview string   `json:"before_preview,omitempty"`
	AfterPreview  string   `json:"after_preview,omitempty"`
}

type Input struct {
	Name        string         `json:"name"`
	Size        int64          `json:"size"`
	Documents   int            `json:"documents"`
	Files       []File         `json:"files"`
	Directories []string       `json:"directories"`
	Pages       []Page         `json:"pages"`
	Metadata    []DocumentInfo `json:"metadata"`
}

type Options struct {
	// Baseline 是从 0 开始的输入索引，其他文件分别与该基准比较。
	Baseline int `json:"baseline_index"`
	// PageMatch 为 auto（默认）或 number。自动匹配优先关联相同页面内容或
	// 唯一的相同非空文字，再结合定位点和文字相似度配对修改页。
	PageMatch string `json:"page_match"`
	// PageMap 手工指定各目标相对基准的原始页码，例如 "2:3,4:5"。
	// 两侧页码不能重复，必须在所选范围内；仅适用于 auto 匹配。
	PageMap string `json:"page_map,omitempty"`
	// Pages 指定各输入中从 1 开始的全局页码，例如 "1-3,5"。
	// 空值选择全部页面；包内文件对比始终覆盖所有条目。
	Pages string `json:"pages,omitempty"`
	// Visual 启用像素对比及页面预览，默认内嵌图片。
	Visual bool `json:"visual"`
	// DPI 默认为 72；PixelTolerance 是每个颜色通道允许的差值，范围为 0–255。
	DPI            float64 `json:"dpi"`
	PixelTolerance int     `json:"pixel_tolerance"`
	// MinRegionPixels 过滤较小的视觉区域，不改变原始像素统计和相同判定。
	// 零值按 1 处理，即保留所有变化区域。
	MinRegionPixels int `json:"min_region_pixels"`
	// MaxXMLBytes 限制每个 XML 的结构分析大小，默认为 8 MiB。超过上限时
	// 仍计算文件摘要，并明确记录未进行结构比较。
	MaxXMLBytes int64 `json:"max_xml_bytes"`
	// MaxXMLStructureBytes 限制单个 XML 字段表的估算大小，默认 32 MiB。
	// 每次只保留当前文件两侧的字段表，比较后释放。
	MaxXMLStructureBytes int64 `json:"max_xml_structure_bytes"`
	// MaxChanges 限制每个 XML 的差异明细条数，默认为 200。
	MaxChanges int `json:"max_changes"`
	// MaxPagePixels 和 MaxTotalPixels 限制单页与累计视觉工作量，默认分别为 1000 万和 10 亿。
	MaxPagePixels  int64 `json:"max_page_pixels"`
	MaxTotalPixels int64 `json:"max_total_pixels"`
	// MaxPreviewBytes 限制所有预览图累计编码后的 PNG 字节数，默认 64 MiB。
	// MaxReportBytes 限制保留的报告数据和最终输出字节数，默认 256 MiB。
	MaxPreviewBytes int64 `json:"max_preview_bytes"`
	MaxReportBytes  int64 `json:"max_report_bytes"`
	// BaselineCacheBytes 限制基准页 RGBA 缓存，默认 64 MiB；-1 禁用。
	// 缓存命中不重复扣渲染像素预算，超过容量的单页不会缓存。
	BaselineCacheBytes int64 `json:"baseline_cache_bytes"`
	// ImageWriter 可将每张 PNG 写入外部存储并返回相对图片 URL。
	// 返回地址必须为安全的相对路径；零值将图片以 base64 内嵌。
	// 外部图片的创建和失败清理由调用方负责，写入错误会终止比较。
	ImageWriter func([]byte) (string, error) `json:"-"`
	// contains filtered or unexported fields
}

type Page struct {
	Number         int     `json:"number"`
	Document       int     `json:"document"`
	PageInDocument int     `json:"page_in_document"`
	Width          float64 `json:"width_mm"`
	Height         float64 `json:"height_mm"`
	Text           string  `json:"text"`
	ContentSHA256  string  `json:"content_sha256"`
	// Selected 标记是否属于 Options.Pages。未选中的页面只保留序号，
	// 不提取文字、尺寸或内容摘要，也不参与配对和渲染。
	Selected bool `json:"selected"`
}

type PageChange struct {
	Status string `json:"status"`
	Before int    `json:"before,omitempty"`
	After  int    `json:"after,omitempty"`
	Moved  bool   `json:"moved"`
	// Match 记录实际采用的配对依据，独立于页面是否发生变化。
	Match          PageMatchInfo `json:"match"`
	TextChanged    bool          `json:"text_changed"`
	SizeChanged    bool          `json:"size_changed"`
	TextDiff       []TextSpan    `json:"text_diff,omitempty"`
	TextDiffCoarse bool          `json:"text_diff_coarse,omitempty"`
	Visual         *VisualChange `json:"visual,omitempty"`
}

type PageMatchInfo struct {
	Method string `json:"method"`
	// TextSimilarity 仅用于 text_similarity，范围为 0–1，是文字特征相似度，
	// 不代表页面相同的概率或视觉相似度。
	TextSimilarity float64 `json:"text_similarity,omitempty"`
	// SearchLimited 表示相似度搜索达到工作量上限；只标记随后顺序配对或未匹配的页面。
	SearchLimited bool `json:"search_limited,omitempty"`
}

type PagePair struct {
	Before int `json:"before"`
	After  int `json:"after"`
}

type PageRange struct{ First, Last int }

type Report struct {
	SchemaVersion string       `json:"schema_version"`
	ToolVersion   string       `json:"tool_version"`
	Baseline      int          `json:"baseline"`
	Options       Options      `json:"options"`
	Inputs        []Input      `json:"inputs"`
	Comparisons   []Comparison `json:"comparisons"`
}

type Summary struct {
	FilesAdded         int `json:"files_added"`
	FilesRemoved       int `json:"files_removed"`
	FilesModified      int `json:"files_modified"`
	FilesMoved         int `json:"files_moved"`
	PagesAdded         int `json:"pages_added"`
	PagesRemoved       int `json:"pages_removed"`
	PagesModified      int `json:"pages_modified"`
	PagesMoved         int `json:"pages_moved"`
	VisualPagesChanged int `json:"visual_pages_changed"`
}

type TextSpan struct {
	Kind string `json:"kind"`
	Text string `json:"text"`
}

type ValueChange struct {
	Path   string  `json:"path"`
	Before *string `json:"before,omitempty"`
	After  *string `json:"after,omitempty"`
}

type VisualChange struct {
	ChangedPixels int64   `json:"changed_pixels"`
	TotalPixels   int64   `json:"total_pixels"`
	Ratio         float64 `json:"ratio"`
	// Bounds 是变化像素的整体矩形，采用半开区间 [x0,y0,x1,y1)。
	Bounds              [4]int         `json:"bounds"`
	BeforePNG           string         `json:"before_png,omitempty"`
	AfterPNG            string         `json:"after_png,omitempty"`
	DiffPNG             string         `json:"diff_png,omitempty"`
	Width               int            `json:"width"`
	Height              int            `json:"height"`
	Regions             []VisualRegion `json:"regions,omitempty"`
	RegionCount         int            `json:"region_count"`
	RegionsTruncated    bool           `json:"regions_truncated,omitempty"`
	IgnoredRegionPixels int64          `json:"ignored_region_pixels"`
}

type VisualRegion struct {
	Bounds        [4]int `json:"bounds"`
	ChangedPixels int64  `json:"changed_pixels"`
}

type XMLView struct {
	Kind   string         `json:"kind"`
	Blocks []XMLViewBlock `json:"blocks,omitempty"`
	Coarse bool           `json:"coarse,omitempty"`
	Note   string         `json:"note,omitempty"`
}

type XMLViewBlock struct {
	Equal  bool          `json:"equal"`
	Folded bool          `json:"folded"`
	Lines  []XMLViewLine `json:"lines"`
}

type XMLViewLine struct {
	BeforeNumber int    `json:"before_number"`
	AfterNumber  int    `json:"after_number"`
	Before       string `json:"before,omitempty"`
	After        string `json:"after,omitempty"`
}