diff

Documentation

Overview

Package diff provides comparison utilities for evidence packs.

Index

• Constants
• func FormatJSONValue(v interface{}) string
• type ContentResult
  • func Content(p1, p2 *pack.Pack, artifactPath string) (*ContentResult, error)
• type ContentStatus
  • func (s ContentStatus) String() string
• type ErrDiffTooLarge
  • func (e ErrDiffTooLarge) Error() string
• type IntegrityErrorInfo
• type JSONChange
• type JSONChangeType
  • func (t JSONChangeType) String() string
• type LineDiff
  • func ComputeLineDiff(lines1, lines2 []string) []LineDiff
• type LineDiffType
• type PackInfo
• type Result
  • func Packs(p1, p2 *pack.Pack) *Result
  • func (r *Result) IsIdentical() bool
  • func (r *Result) Summary() Summary
• type Summary

Constants

const (
	// ContentIdentical means both artifacts have the same content.
	ContentIdentical ContentStatus = iota
	// ContentDifferent means the artifacts exist in both packs but have different content.
	ContentDifferent
	// ContentOnlyInPack1 means the artifact only exists in pack 1.
	ContentOnlyInPack1
	// ContentOnlyInPack2 means the artifact only exists in pack 2.
	ContentOnlyInPack2
	// ContentNotFound means the artifact doesn't exist in either pack.
	ContentNotFound
	// ContentIntegrityError means reading the artifact failed due to integrity check
	// (digest mismatch, size mismatch). This is a SECURITY-CRITICAL status that
	// indicates the pack may have been tampered with.
	ContentIntegrityError

	// JSON change types
	JSONAdded JSONChangeType = iota
	JSONRemoved
	JSONChanged

	// Line diff types
	LineEqual LineDiffType = iota
	LineAdded
	LineRemoved
)

const MaxDiffLines = 10000

MaxDiffLines is the maximum number of lines supported for text diff. Prevents quadratic memory/time DoS attacks via large inputs. For larger files, use external diff tools.

const MaxDiffMemoryBytes = 100 * 1024 * 1024

MaxDiffMemoryBytes is the maximum memory allowed for LCS table (100 MB).

Functions

func FormatJSONValue

func FormatJSONValue(v interface{}) string

FormatJSONValue formats a JSON value for display.

Types

type ContentResult

type ContentResult struct {
	Status ContentStatus

	// IsJSON indicates whether both artifacts were valid JSON.
	IsJSON bool

	// JSONChanges contains the structured diff for JSON content.
	// Only populated when IsJSON is true and Status is ContentDifferent.
	JSONChanges []JSONChange

	// TextDiff contains the line-based diff for text content.
	// Only populated when IsJSON is false and Status is ContentDifferent.
	TextDiff []LineDiff

	// IntegrityError contains details about the integrity failure.
	// Only populated when Status is ContentIntegrityError.
	// SECURITY: This indicates potential pack tampering - do not ignore.
	IntegrityError *IntegrityErrorInfo
}

ContentResult contains the result of comparing a specific artifact's content.

func Content

func Content(p1, p2 *pack.Pack, artifactPath string) (*ContentResult, error)

Content compares a specific artifact's content between two packs. SECURITY: If either pack has an integrity error (digest/size mismatch), this returns ContentIntegrityError instead of masking it as "missing".

type ContentStatus

type ContentStatus int

ContentStatus indicates the comparison status of an artifact.

func (ContentStatus) String

func (s ContentStatus) String() string

String returns a human-readable status description.

type ErrDiffTooLarge

type ErrDiffTooLarge struct {
	Lines1, Lines2 int
	Limit          int
}

ErrDiffTooLarge is returned when input exceeds diff size limits.

func (ErrDiffTooLarge) Error

func (e ErrDiffTooLarge) Error() string

type IntegrityErrorInfo

type IntegrityErrorInfo struct {
	// Pack indicates which pack had the integrity error ("pack1" or "pack2" or "both")
	Pack string
	// Code is the error code (e.g., "digest_mismatch", "size_mismatch")
	Code string
	// Message is the error message
	Message string
}

IntegrityErrorInfo contains details about an integrity verification failure.

type JSONChange

type JSONChange struct {
	Type     JSONChangeType
	Path     string      // JSON path (e.g., "root.nested.key" or "[0].field")
	OldValue interface{} // nil for added
	NewValue interface{} // nil for removed
}

JSONChange represents a single change in JSON content.

type JSONChangeType

type JSONChangeType int

JSONChangeType indicates the type of JSON change.

func (JSONChangeType) String

func (t JSONChangeType) String() string

String returns a human-readable change type.

type LineDiff

type LineDiff struct {
	Type LineDiffType
	Line string
}

LineDiff represents a single line in a text diff.

func ComputeLineDiff

func ComputeLineDiff(lines1, lines2 []string) []LineDiff

ComputeLineDiff computes a diff between two slices of lines using LCS. Returns an error if input is too large to prevent DoS attacks. For inputs exceeding MaxDiffLines, returns ErrDiffTooLarge.

type LineDiffType

type LineDiffType int

LineDiffType indicates the type of line difference.

type PackInfo

type PackInfo struct {
	Stream     string `json:"stream"`
	PackDigest string `json:"pack_digest"`
}

PackInfo contains identifying information about a pack.

type Result

type Result struct {
	Pack1 PackInfo `json:"pack1"`
	Pack2 PackInfo `json:"pack2"`

	Added     []string `json:"added"`     // Paths only in pack2
	Removed   []string `json:"removed"`   // Paths only in pack1
	Changed   []string `json:"changed"`   // Paths in both with different digests
	Unchanged []string `json:"unchanged"` // Paths in both with same digest
}

Result contains the differences between two packs.

func Packs

func Packs(p1, p2 *pack.Pack) *Result

Packs compares two packs and returns the differences.

func (*Result) IsIdentical

func (r *Result) IsIdentical() bool

IsIdentical returns true if the packs have no differences.

func (*Result) Summary

func (r *Result) Summary() Summary

Summary returns counts of each difference type.

type Summary

type Summary struct {
	Added     int `json:"added_count"`
	Removed   int `json:"removed_count"`
	Changed   int `json:"changed_count"`
	Unchanged int `json:"unchanged_count"`
}

Summary contains counts of differences.