reporting

Documentation

Overview

Package reporting assembles per-file scores into aggregate attribution results. It is a pure domain package with no infrastructure dependencies.

Index

• func AILines(fs *FileScoreInput) int
• func CommitEvidence(files []FileAttributionOutput) (level string, fallbackCount int)
• func EvidenceExplanation(level string, fallbackCount int) string
• func RenderDiagnosticNote(in DiagnosticsInput) string
• type AggregateResult
  • func AggregatePercent(scores []FileScoreInput, providerModel map[string]string, filesTouched int) AggregateResult
• type CheckpointDiagnostics
• type CheckpointResult
  • func BuildCheckpointResult(in CheckpointResultInput) CheckpointResult
• type CheckpointResultInput
• type CommitResult
  • func BuildCommitResult(in CommitResultInput) CommitResult
• type CommitResultInput
• type DiagnosticsInput
• type EventStatsInput
• type EvidenceClass
  • func CollectFileEvidence(fs FileScoreInput, touch TouchOrigin, isCarryForward bool) []EvidenceClass
  • func ResolveFileEvidence(fs FileScoreInput, touch TouchOrigin, isCarryForward bool) EvidenceClass
• type FileAttributionOutput
• type FileChangeOutput
• type FileScoreInput
• type MatchStatsInput
• type ProviderAttribution
• type TouchOrigin

Functions

func AILines

func AILines(fs *FileScoreInput) int

AILines returns the total AI lines (exact + formatted + modified) for a single file score input.

func CommitEvidence

func CommitEvidence(files []FileAttributionOutput) (level string, fallbackCount int)

CommitEvidence computes the evidence level, score, and fallback count from per-file evidence using a weighted formula.

Line-evidence score (0-1): LineScore = (1.00*Exact + 0.85*Normalized + 0.55*Modified) / max(1, AILines) File-evidence penalty (0-1): FallbackPenalty = (0.18*Tpd + 0.30*Tpc + 0.25*CF + 0.35*D) / max(1, AIFiles) Combined score: Score = clamp(LineScore - FallbackPenalty, 0, 1)

Buckets:

High:   Score >= 0.75
Medium: 0.45 <= Score < 0.75
Low:    Score < 0.45

Thresholds may be tuned as the evaluation corpus grows.

func EvidenceExplanation

func EvidenceExplanation(level string, fallbackCount int) string

EvidenceExplanation returns a short sentence explaining the evidence level.

func RenderDiagnosticNote

func RenderDiagnosticNote(in DiagnosticsInput) string

RenderDiagnosticNote produces a human-readable diagnostic note explaining why a particular AI percentage was computed. When AI% is 0 it identifies which pipeline stage had no data. When AI% > 0 and non-exact matches contributed, it breaks down the match tiers.

Types

type AggregateResult

type AggregateResult struct {
	Percent        float64
	TotalLines     int
	AILines        int
	ExactLines     int // tier 1: exact trimmed match
	ModifiedLines  int // tier 0 with hunk overlap
	FormattedLines int // tier 2: whitespace-normalized match
	FilesTouched   int // unique files in the diff
	Providers      []ProviderAttribution
}

AggregateResult contains the full attribution breakdown produced by AggregatePercent. The Percent field is the headline number; the remaining fields support richer commit trailers and diagnostics.

func AggregatePercent

func AggregatePercent(scores []FileScoreInput, providerModel map[string]string, filesTouched int) AggregateResult

AggregatePercent reduces per-file scores into a single AggregateResult with provider breakdown sorted by AI lines (descending), then name.

type CheckpointDiagnostics

type CheckpointDiagnostics struct {
	EventsConsidered int
	EventsAssistant  int
	PayloadsLoaded   int
	AIToolEvents     int
	Note             string
}

CheckpointDiagnostics holds event stats and a diagnostic note for checkpoint-only blame results.

type CheckpointResult

type CheckpointResult struct {
	CheckpointID   string
	FilesAITouched int
	FilesTotal     int
	FilesEdited    []FileChangeOutput
	Diagnostics    CheckpointDiagnostics
}

CheckpointResult is the attribution result for a checkpoint without a linked commit. It reports AI activity but has no line-level scores.

func BuildCheckpointResult

func BuildCheckpointResult(in CheckpointResultInput) CheckpointResult

BuildCheckpointResult assembles a checkpoint-only attribution result. Checkpoint blame has no diff and no line-level scoring - it reports which files were touched by AI and event-level diagnostics.

type CheckpointResultInput

type CheckpointResultInput struct {
	CheckpointID string
	TouchedFiles map[string]bool // AI-touched file paths
	EventStats   EventStatsInput // for diagnostics
}

CheckpointResultInput holds the narrow inputs for assembling a checkpoint-only attribution result (no diff, no line-level scoring).

type CommitResult

type CommitResult struct {
	AIExactLines     int
	AIFormattedLines int
	AIModifiedLines  int
	AILines          int // exact + formatted + modified
	HumanLines       int
	TotalLines       int
	AIPercentage     float64 // (exact + formatted + modified) / total * 100
	FilesAITouched   int
	FilesTotal       int // created + edited (excludes deleted)
	FilesCreated     []FileChangeOutput
	FilesEdited      []FileChangeOutput
	FilesDeleted     []FileChangeOutput
	Files            []FileAttributionOutput
	ProviderDetails  []ProviderAttribution
	Evidence         string // evidence-strength level: "High", "Medium", "Low"
	FallbackCount    int    // number of AI-attributed files with provider-touch or weaker evidence
}

CommitResult is the full attribution breakdown for a single commit, produced by BuildCommitResult.

func BuildCommitResult

func BuildCommitResult(in CommitResultInput) CommitResult

BuildCommitResult assembles a full commit attribution result from scored file data, diff metadata, and candidate metadata. It builds per-file attribution rows, headline totals, file change lists, and provider details.

type CommitResultInput

type CommitResultInput struct {
	FileScores        []FileScoreInput       // one per diff file, in diff order
	FilesCreated      []string               // paths created (from /dev/null)
	FilesDeleted      []string               // paths deleted (to /dev/null)
	TouchedFiles      map[string]bool        // AI-touched file paths (for AI flag on file changes)
	ProviderModels    map[string]string      // provider -> model
	FileTouchOrigins  map[string]TouchOrigin // per-file touch provenance (for evidence classification)
	CarryForwardFiles map[string]bool        // files attributed via carry-forward
}

CommitResultInput holds the narrow inputs needed to assemble a full commit attribution result from scored data and diff metadata.

type DiagnosticsInput

type DiagnosticsInput struct {
	EventStats EventStatsInput
	MatchStats MatchStatsInput
	AIPercent  float64
}

DiagnosticsInput combines event stats, match stats, and the computed AI percentage for rendering the diagnostic note.

type EventStatsInput

type EventStatsInput struct {
	EventsConsidered int
	EventsAssistant  int
	PayloadsLoaded   int
	AIToolEvents     int
}

EventStatsInput carries event-processing counters into reporting.

type EvidenceClass

type EvidenceClass string

EvidenceClass describes how a file's AI attribution was determined. Internal taxonomy for the evaluation harness and detailed diagnostics. User-facing output uses factual notes rather than exposing raw classes.

const (
	EvidenceExact          EvidenceClass = "exact"           // trimmed exact line match
	EvidenceNormalized     EvidenceClass = "normalized"      // whitespace-normalized match
	EvidenceModified       EvidenceClass = "modified"        // overlap-based modified attribution
	EvidenceProviderTouch  EvidenceClass = "provider_touch"  // explicit file-edit tool event from provider
	EvidenceProviderCoarse EvidenceClass = "provider_coarse" // session-level linkage without direct file-edit event
	EvidenceCarryForward   EvidenceClass = "carry_forward"   // attributed from previous checkpoint window
	EvidenceDeletion       EvidenceClass = "deletion"        // inferred from bash rm / provider deletion
	EvidenceNone           EvidenceClass = "none"            // no AI evidence (human file)
)

func CollectFileEvidence

func CollectFileEvidence(fs FileScoreInput, touch TouchOrigin, isCarryForward bool) []EvidenceClass

CollectFileEvidence returns all evidence classes that contributed to a file's attribution. Used by the evaluation harness to track which evidence paths were active, not just which one won.

func ResolveFileEvidence

func ResolveFileEvidence(fs FileScoreInput, touch TouchOrigin, isCarryForward bool) EvidenceClass

ResolveFileEvidence determines the primary evidence class for a file based on its scored lines, touch origin, and carry-forward status. Returns the highest-quality evidence class that applies.

type FileAttributionOutput

type FileAttributionOutput struct {
	Path             string
	AIExactLines     int
	AIFormattedLines int
	AIModifiedLines  int
	HumanLines       int
	TotalLines       int
	DeletedNonBlank  int
	AIPercent        float64         // (exact + formatted + modified) / total * 100
	PrimaryEvidence  EvidenceClass   // highest-quality evidence for display
	AllEvidence      []EvidenceClass // all contributing evidence classes (for evaluation)
}

FileAttributionOutput holds per-file attribution scores in the commit result.

type FileChangeOutput

type FileChangeOutput struct {
	Path string
	AI   bool
}

FileChangeOutput records whether a file change was performed by AI.

type FileScoreInput

type FileScoreInput struct {
	Path            string
	TotalLines      int
	ExactLines      int
	FormattedLines  int
	ModifiedLines   int
	HumanLines      int
	ProviderLines   map[string]int // provider -> AI lines for this file
	DeletedNonBlank int            // deleted non-blank lines (display only, not attributed)
}

FileScoreInput is the narrow input shape for a single file's score data.

type MatchStatsInput

type MatchStatsInput struct {
	ExactMatches      int
	NormalizedMatches int
	ModifiedMatches   int
}

MatchStatsInput carries match counters from scoring into reporting.

type ProviderAttribution

type ProviderAttribution struct {
	Provider string
	Model    string // empty if unknown
	AILines  int
}

ProviderAttribution holds per-provider AI line counts.

type TouchOrigin

type TouchOrigin string

TouchOrigin describes how a file entered the AI-touched set. The orchestrator derives this from the candidates produced by the events package.

const (
	TouchOriginProviderEdit TouchOrigin = "provider_edit" // explicit file-edit tool event (Cursor, Kiro, etc.)
	TouchOriginLineLevel    TouchOrigin = "line_level"    // Claude Edit/Write with payload content
	TouchOriginDeletion     TouchOrigin = "deletion"      // bash rm or provider deletion event
	TouchOriginCoarse       TouchOrigin = "coarse"        // session-level linkage only
)