schema

Documentation

Overview

Package schema defines the stable JSON output types for contextception. External consumers (e.g. the GitHub PR app) import this package to deserialize CLI JSON output without depending on internal packages.

Index

• type AggregateRisk
• type AnalysisOutput
• type BlastRadius
• type ChangeReport
• type ChangeSummary
• type ChangedFile
• type CouplingPair
• type ExternalDependency
• type HiddenCouplingEntry
• type IndexStats
• type LikelyModifyEntry
• type MustReadEntry
• type RelatedEntry
• type RiskTriage
• type TestEntry
• type TestSuggestion

Types

type AggregateRisk

type AggregateRisk struct {
	Score             int     `json:"score"`
	Percentile        int     `json:"percentile,omitempty"`
	RegressionRisk    string  `json:"regression_risk,omitempty"`
	TestCoverageRatio float64 `json:"test_coverage_ratio"`
}

AggregateRisk summarizes overall PR risk.

type AnalysisOutput

type AnalysisOutput struct {
	SchemaVersion    string                         `json:"schema_version"`
	Subject          string                         `json:"subject"`
	Confidence       float64                        `json:"confidence"`
	ConfidenceNote   string                         `json:"confidence_note,omitempty"`
	External         []string                       `json:"external"`
	MustRead         []MustReadEntry                `json:"must_read"`
	MustReadNote     string                         `json:"must_read_note,omitempty"`
	LikelyModify     map[string][]LikelyModifyEntry `json:"likely_modify"`
	LikelyModifyNote string                         `json:"likely_modify_note,omitempty"`
	Tests            []TestEntry                    `json:"tests"`
	TestsNote        string                         `json:"tests_note,omitempty"`
	Related          map[string][]RelatedEntry      `json:"related"`
	RelatedNote      string                         `json:"related_note,omitempty"`
	BlastRadius      *BlastRadius                   `json:"blast_radius,omitempty"`
	Hotspots         []string                       `json:"hotspots,omitempty"`
	CircularDeps     [][]string                     `json:"circular_deps,omitempty"`
	Stats            *IndexStats                    `json:"stats,omitempty"`
}

AnalysisOutput is the top-level output of the analysis engine (v3.2).

type BlastRadius

type BlastRadius struct {
	Level     string  `json:"level"`
	Detail    string  `json:"detail"`
	Fragility float64 `json:"fragility,omitempty"`
}

BlastRadius summarizes the overall risk profile of a change.

type ChangeReport

type ChangeReport struct {
	SchemaVersion string `json:"schema_version"`

	// The git ref range analyzed (e.g., "main..HEAD").
	RefRange string `json:"ref_range"`

	// Files changed in the diff.
	ChangedFiles []ChangedFile `json:"changed_files"`

	// Summary statistics about the change.
	Summary ChangeSummary `json:"summary"`

	// Aggregated blast radius across all changed files.
	BlastRadius *BlastRadius `json:"blast_radius"`

	// Combined must_read: files required to understand all changes.
	MustRead []MustReadEntry `json:"must_read"`

	// Combined likely_modify: additional files likely needing changes.
	LikelyModify map[string][]LikelyModifyEntry `json:"likely_modify"`

	// Combined test coverage for all changed files.
	Tests []TestEntry `json:"tests"`

	// Cross-file coupling: pairs of changed files that are structurally connected.
	Coupling []CouplingPair `json:"coupling,omitempty"`

	// Aggregated hotspots across all changed files.
	Hotspots []string `json:"hotspots,omitempty"`

	// Circular dependencies involving changed files.
	CircularDeps [][]string `json:"circular_deps,omitempty"`

	// Test coverage gaps: changed files with no direct test coverage.
	TestGaps []string `json:"test_gaps,omitempty"`

	// Hidden coupling: co-change partners not in the diff.
	HiddenCoupling []HiddenCouplingEntry `json:"hidden_coupling,omitempty"`

	// Risk triage: files grouped by risk tier.
	RiskTriage *RiskTriage `json:"risk_triage,omitempty"`

	// Aggregate risk score across all changed files.
	AggregateRisk *AggregateRisk `json:"aggregate_risk,omitempty"`

	// Test suggestions for high-risk untested files.
	TestSuggestions []TestSuggestion `json:"test_suggestions,omitempty"`

	// Index stats at time of analysis.
	Stats *IndexStats `json:"stats,omitempty"`
}

ChangeReport is the output of analyze-change: a PR-level impact report.

type ChangeSummary

type ChangeSummary struct {
	TotalFiles    int `json:"total_files"`
	Added         int `json:"added"`
	Modified      int `json:"modified"`
	Deleted       int `json:"deleted"`
	Renamed       int `json:"renamed"`
	IndexedFiles  int `json:"indexed_files"`
	TestFiles     int `json:"test_files"`
	HighRiskFiles int `json:"high_risk_files"`
}

ChangeSummary provides aggregate statistics about the change.

type ChangedFile

type ChangedFile struct {
	File   string `json:"file"`
	Status string `json:"status"`

	// Per-file blast radius (nil for deleted/unindexed files).
	BlastRadius *BlastRadius `json:"blast_radius,omitempty"`

	// Whether this file is indexed (new files may not be).
	Indexed bool `json:"indexed"`

	// Per-file risk scoring.
	RiskScore     int      `json:"risk_score,omitempty"`
	RiskTier      string   `json:"risk_tier,omitempty"`
	RiskFactors   []string `json:"risk_factors,omitempty"`
	RiskNarrative string   `json:"risk_narrative,omitempty"`
}

ChangedFile represents a single file in the diff with its individual analysis.

type CouplingPair

type CouplingPair struct {
	FileA     string `json:"file_a"`
	FileB     string `json:"file_b"`
	Direction string `json:"direction"`
}

CouplingPair represents two changed files that are structurally connected.

type ExternalDependency

type ExternalDependency struct {
	Specifier  string `json:"specifier"`
	Reason     string `json:"reason"`
	LineNumber int    `json:"line_number"`
}

ExternalDependency represents an import that resolved to an external package or stdlib.

type HiddenCouplingEntry

type HiddenCouplingEntry struct {
	ChangedFile string `json:"changed_file"`
	Partner     string `json:"partner"`
	Frequency   int    `json:"frequency"`
}

HiddenCouplingEntry represents a co-change partner not in the diff.

type IndexStats

type IndexStats struct {
	TotalFiles      int `json:"total_files"`
	TotalEdges      int `json:"total_edges"`
	UnresolvedCount int `json:"unresolved_count"`
}

IndexStats provides index health metadata at analysis time.

type LikelyModifyEntry

type LikelyModifyEntry struct {
	File       string   `json:"file"`
	Confidence string   `json:"confidence"`
	Signals    []string `json:"signals"`
	Symbols    []string `json:"symbols,omitempty"`
	Role       string   `json:"role,omitempty"`
}

LikelyModifyEntry represents a file likely to need modification.

type MustReadEntry

type MustReadEntry struct {
	File        string   `json:"file"`
	Symbols     []string `json:"symbols,omitempty"`
	Definitions []string `json:"definitions,omitempty"`
	Stable      bool     `json:"stable,omitempty"`
	Direction   string   `json:"direction,omitempty"`
	Role        string   `json:"role,omitempty"`
	Circular    bool     `json:"circular,omitempty"`
}

MustReadEntry represents a file in the must_read list with optional symbols and stable flag.

type RelatedEntry

type RelatedEntry struct {
	File    string   `json:"file"`
	Signals []string `json:"signals"`
}

RelatedEntry represents a related context file with its signals.

type RiskTriage

type RiskTriage struct {
	Critical []string `json:"critical"`
	Test     []string `json:"test"`
	Review   []string `json:"review"`
	Safe     []string `json:"safe"`
}

RiskTriage groups files by risk tier.

type TestEntry

type TestEntry struct {
	File   string `json:"file"`
	Direct bool   `json:"direct"`
}

TestEntry represents a test file with its tier (direct vs dependency).

type TestSuggestion

type TestSuggestion struct {
	File          string `json:"file"`
	SuggestedTest string `json:"suggested_test"`
	Reason        string `json:"reason"`
}

TestSuggestion suggests a test for a file missing coverage.