Documentation
¶
Overview ¶
Package report builds DeveloperPeriodReport (schema omnidevx.developer-period/v1) from canonical events.
Aggregation is two-stage: BuildDaily reduces one day's events into a DailySummary; Rollup combines summaries covering a period into a report. Build is the one-call convenience that buckets events by day and runs both stages. The two-stage split matters because not every metric sums correctly across a day boundary — a session spanning midnight must be deduplicated by ID at rollup time, not double-counted per day — and because reprocessing with a changed formula should replay from stored daily summaries, never require recollection from raw session files.
Only additive, per-day event types are summarized here: ai.* session activity, devx.change.committed, and devx.contribution.recorded. Period-total events (devx.profile.snapshot, devx.contribution.snapshot) already describe an entire period rather than one day, so they are not decomposed into daily buckets; Rollup surfaces their presence as a DataQuality warning until a provider-specific merge rule is defined.
Metrics are split into combined and bySource views per source ("some metrics combine safely — sessions, cost, tokens with model retained; others do not — acceptance rate only with matching definitions"); every metric carries a Measurement recording whether it was observed or estimated, and from what confidence.
Index ¶
Constants ¶
const ( KindObserved = "observed" KindEstimated = "estimated" )
Measurement kinds.
const SchemaVersion = "omnidevx.developer-period/v1"
SchemaVersion is the schema this package's DeveloperPeriodReport implements.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type DailySummary ¶
type DailySummary struct {
Date time.Time
Combined map[string]float64
BySource map[string]map[string]float64
Snapshots int // period-total events seen but not summarized (see package doc)
// contains filtered or unexported fields
}
DailySummary is one day's reduction of canonical events: additive metric counts plus enough per-source bookkeeping for Rollup to merge many days into a period report without re-reading raw events.
func BuildDaily ¶
func BuildDaily(events []omnidevx.Event, day time.Time) *DailySummary
BuildDaily reduces one day's events into a DailySummary. day identifies the UTC calendar day being summarized; events outside [day, day+24h) are ignored so callers can pass a pre-bucketed slice or the full event set interchangeably.
type DataQuality ¶
type DataQuality struct {
CoverageScore float64 `json:"coverageScore"`
Warnings []string `json:"warnings,omitempty"`
}
DataQuality reports how complete a report's coverage is.
type DeveloperPeriodReport ¶
type DeveloperPeriodReport struct {
SchemaVersion string `json:"schemaVersion"`
Subject Subject `json:"subject"`
Period omnidevx.Period `json:"period"`
Sources []SourceCoverage `json:"sources"`
Metrics MetricSet `json:"metrics"`
Quality DataQuality `json:"quality"`
}
DeveloperPeriodReport is the analytical source of truth for one person's activity over one period, combining every source that observed them. It is a presentation-agnostic artifact: DevFolio's contributor profile summarizes and links to this, never recomputes it.
func Build ¶
Build reduces events into a DeveloperPeriodReport for one subject and period. It buckets events by UTC calendar day, reduces each day with BuildDaily, and rolls the summaries up with Rollup — the same path a caller replaying cached DailySummary artifacts would take, so reprocessing with a changed formula never requires recollection.
func Rollup ¶
func Rollup(dailies []*DailySummary, subject Subject, period omnidevx.Period) *DeveloperPeriodReport
Rollup combines DailySummary values into one DeveloperPeriodReport. Summaries outside period are ignored so callers can pass a cached superset without re-filtering first.
type Measurement ¶
type Measurement struct {
Kind string `json:"kind"`
Method string `json:"method,omitempty"`
Confidence float64 `json:"confidence"`
}
Measurement records how a metric value was derived. Every metric in this package is a direct sum of observed event attributes, so Kind is always KindObserved; estimated metrics (e.g. inferred AI contribution ratios) belong to a future analytics layer built on top of these reports.
type Metric ¶
type Metric struct {
Value float64 `json:"value"`
Unit string `json:"unit,omitempty"`
Measurement Measurement `json:"measurement"`
}
Metric is one named value with the provenance behind it.
type MetricSet ¶
type MetricSet struct {
Combined map[string]Metric `json:"combined"`
BySource map[string]map[string]Metric `json:"bySource"`
}
MetricSet holds the cross-source combined view alongside the per-source breakdown. A metric that does not combine safely across sources (see package doc) appears in BySource only.
type SourceCoverage ¶
type SourceCoverage struct {
Source omnidevx.Source `json:"source"`
EventCount int `json:"eventCount"`
CollectionModes []omnidevx.CollectionMode `json:"collectionModes"`
MinConfidence float64 `json:"minConfidence"`
}
SourceCoverage summarizes what one source contributed to a report.
Source Files