reporting

package
v0.3.5 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Apr 21, 2026 License: MIT Imports: 3 Imported by: 0

Documentation

Overview

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

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func AILines 

func AILines(fs *FileScoreInput) int

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

func AssembleCheckpointNotes added in v0.3.4 

func AssembleCheckpointNotes(pipelineNote string) []string

AssembleCheckpointNotes is the checkpoint-only equivalent of AssembleCommitNotes. Checkpoint attribution has no line-level scoring, no fallback count, and no per-file evidence classes, so the result is just the pipeline-state note wrapped in a slice (or nil when empty). Kept as a named helper so the CLI's call sites do not sprout ad-hoc "wrap a string in a slice" code.

func AssembleCommitNotes added in v0.3.4 

func AssembleCommitNotes(pipelineNote string, cr CommitResult) []string

AssembleCommitNotes builds the combined notes bundle for a commit attribution. The pipeline-state note (if non-empty) leads; factual notes derived from the commit result (weaker fallback signals, carry-forward, deletion inference) follow.

Used by both the CLI's attribution-display command and the push payload builder so both surfaces emit the same bundle. The wire shape is `notes []string`; the CLI display iterates the same slice and formats it as a bulleted list.

func CommitEvidence added in v0.2.3 

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 added in v0.2.3 

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
	Notes            []string
}

CheckpointDiagnostics holds event stats and diagnostic notes for checkpoint-only blame results. Notes carries the pipeline-state message wrapped as a slice so the shape matches the commit-path AttributionDiagnostics - both CLI display and push paths iterate the same slice.

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 added in v0.2.3 

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 added in v0.2.3 

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 added in v0.2.3 

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 added in v0.2.3 

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
)

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.