scoring

Documentation

Overview

Package scoring parses unified diffs and scores diff lines against AI candidate data. It is a pure domain package with no infrastructure dependencies. It receives parsed data and returns scores.

Index

• Constants
• func BuildNormalizedLineProviders(lineProviders map[string]map[string]map[string]struct{}) map[string]map[string]map[string]struct{}
• func BuildNormalizedSet(aiLines map[string]map[string]struct{}) map[string]map[string]struct{}
• func NormalizeWhitespace(s string) string
• func ScoreFiles(diff DiffResult, aiLines map[string]map[string]struct{}, ...) ([]FileScore, MatchStats)
• func ScoreFilesWithDeltas(diff DiffResult, aiLines map[string]map[string]struct{}, ...) ([]FileScore, MatchStats)
• type AddedGroup
• type AlignedLine
  • func AlignOrdered(claims []ClaimLine, added []string) (result []AlignedLine, ok bool)
• type ClaimLine
  • func NewClaimLines(lines []string) []ClaimLine
• type DeltaClaimGroup
• type DiffResult
  • func ParseDiff(diffBytes []byte) DiffResult
• type FileDiff
• type FileScore
• type LineStamp
• type MatchStats

Constants

const (
	AlignNone       = 0
	AlignExact      = 1
	AlignNormalized = 2
)

Alignment tiers mirror line-scoring tiers.

Functions

func BuildNormalizedLineProviders

func BuildNormalizedLineProviders(lineProviders map[string]map[string]map[string]struct{}) map[string]map[string]map[string]struct{}

BuildNormalizedLineProviders projects per-line provider ownership onto the whitespace-normalized line keys used by the tier-2 match. When multiple trimmed lines collapse to the same normalized form (different whitespace, same content), the providers from every contributing source are unioned so a tier-2 match credits any provider that emitted the underlying line in any whitespace form.

func BuildNormalizedSet

func BuildNormalizedSet(aiLines map[string]map[string]struct{}) map[string]map[string]struct{}

BuildNormalizedSet derives a whitespace-stripped line set from the AI candidate set. Each trimmed line is stripped of all whitespace and stored per file path.

func NormalizeWhitespace

func NormalizeWhitespace(s string) string

NormalizeWhitespace removes all whitespace characters from s. Used as a second-tier match when exact trimmed comparison fails, catching formatter/linter modifications like:

"func foo(){" vs "func foo() {"
"return   x+y" vs "return x + y"

func ScoreFiles

func ScoreFiles(
	diff DiffResult,
	aiLines map[string]map[string]struct{},
	providerTouchedFiles map[string]string,
	fileProvider map[string]string,
	lineProviders map[string]map[string]map[string]struct{},
) ([]FileScore, MatchStats)

ScoreFiles matches AI candidate maps against a parsed diff and returns per-file scores with match statistics. This is the v1 scorer and its behavior is frozen.

Parameters are plain maps. Callers unpack candidate data into these maps.

Matching is three-tier:

• Tier 1 (exact): trimmed line matches AI output exactly
• Tier 2 (formatted): matches after whitespace normalization
• Tier 3 (modified): in a contiguous group with tier 1 or 2 overlap

lineProviders is the per-line ownership map (file -> line -> providers that emitted the line). When set, each matched diff line credits every provider that contributed it, so ProviderLines reflects per-line evidence rather than a per-file "last writer wins" assignment. When lineProviders is nil (older callers or candidates built without per-line tracking), the scorer falls back to the per-file fileProvider value for every matched line.

func ScoreFilesWithDeltas

func ScoreFilesWithDeltas(
	diff DiffResult,
	aiLines map[string]map[string]struct{},
	providerTouchedFiles map[string]string,
	fileProvider map[string]string,
	lineProviders map[string]map[string]map[string]struct{},
	lineStamps map[string]map[string][]LineStamp,
	deltaGroups map[string][]DeltaClaimGroup,
) ([]FileScore, MatchStats)

ScoreFilesWithDeltas scores direct and tool-delta evidence per line. Match quality wins before recency in (ts, insert_seq, event_id) order. Delta groups establish alignment before competing for shared lines and cannot trigger modified-line inheritance. Unstamped direct evidence uses zero recency and a deterministic provider fallback.

Types

type AddedGroup

type AddedGroup struct {
	Lines []string // "+" lines with prefix stripped
	// NewStart is the new-file line number of Lines[0], or zero if unknown.
	NewStart int
}

AddedGroup is a contiguous block of added lines within a diff hunk.

type AlignedLine

type AlignedLine struct {
	ClaimIdx int // index into the claim slice, -1 when unmatched
	Tier     int // AlignExact, AlignNormalized, or AlignNone
}

AlignedLine is the per-added-line result of an alignment.

func AlignOrdered

func AlignOrdered(claims []ClaimLine, added []string) (result []AlignedLine, ok bool)

AlignOrdered matches each claim to at most one added line while preserving order. Exact matches anchor the result; normalized matches fill only the gaps between anchors. Ties prefer the earliest added-line position.

ok is false when the inputs exceed the alignment budget; the result is then nil and the caller must not attribute lines.

type ClaimLine

type ClaimLine struct {
	Text string // trimmed content
	Norm string // whitespace-normalized content
}

ClaimLine is one ordered occurrence of tool-produced text.

func NewClaimLines

func NewClaimLines(lines []string) []ClaimLine

NewClaimLines preserves line order and leaves blank claims unmatched.

type DeltaClaimGroup

type DeltaClaimGroup struct {
	Provider  string
	Ts        int64
	InsertSeq int64
	EventID   string
	Lines     []string
	// Historical marks a carry-forward claim for a modified file.
	Historical bool
}

DeltaClaimGroup contains one delta group's ordered claims and recency.

type DiffResult

type DiffResult struct {
	Files        []FileDiff // all files present in the diff
	FilesCreated []string   // paths created (from /dev/null)
	FilesDeleted []string   // paths deleted (to /dev/null)
	// Complete reports whether the entire diff was scanned.
	Complete bool
}

DiffResult holds the parsed output of a unified diff.

func ParseDiff

func ParseDiff(diffBytes []byte) DiffResult

ParseDiff extracts added lines, file operations, and new-file coordinates from a unified diff.

It recognizes:

• "--- /dev/null" + "+++ b/path" -> file created
• "--- a/path" + "+++ /dev/null" -> file deleted
• Lines starting with "+" (excluding the +++ header) -> added lines

Added groups record the first new-file line from their hunk header.

type FileDiff

type FileDiff struct {
	Path            string       // repo-relative file path
	Groups          []AddedGroup // contiguous groups of added lines
	DeletedNonBlank int          // count of deleted non-blank lines
}

FileDiff holds the added lines for a single file in a unified diff, grouped into contiguous runs.

type FileScore

type FileScore struct {
	Path                        string
	TotalLines                  int
	ExactLines                  int
	FormattedLines              int
	ModifiedLines               int
	ProviderOnlyLines           int
	HumanLines                  int
	ProviderLines               map[string]int // provider -> line-level AI lines
	ProviderOnlyLinesByProvider map[string]int // provider -> provider-only lines
	// DeltaExactLines and DeltaFormattedLines identify tool-delta matches.
	DeltaExactLines     int
	DeltaFormattedLines int
	// DeltaAlignmentRefused marks delta evidence that must degrade to touch.
	DeltaAlignmentRefused bool
	// ContestedLines counts lines where multiple evidence candidates
	// competed before winner selection.
	ContestedLines int
}

FileScore holds per-file attribution scores. Provider-only lines are reported separately and do not contribute to the headline percentage.

type LineStamp

type LineStamp struct {
	Provider  string
	Ts        int64
	InsertSeq int64
	EventID   string
}

LineStamp identifies one direct witness for a line.

type MatchStats

type MatchStats struct {
	ExactMatches           int
	NormalizedMatches      int
	ModifiedMatches        int
	ProviderOnlyMatches    int
	DeltaExactMatches      int
	DeltaNormalizedMatches int
	DeltaAlignmentsRefused int
	ContestedLines         int
}

MatchStats collects match counters from scoring. Callers combine these with EventStats from the events package.