coupling

Documentation

Overview

Package coupling defines the Balanced Coupling classification types: Strength, Distance, Volatility, Explicitness, and the Classification index.

Index

• type Classification
• type Distance
• type Explicitness
• type Index
• type Severity
  • func BalanceResult(c Classification) Severity
• type Strength
• type Volatility

Types

type Classification

type Classification struct {
	Strength     Strength
	Distance     Distance
	Volatility   Volatility
	Explicitness Explicitness
	Severity     Severity
}

Classification holds the Balanced Coupling assessment for one graph edge. Strength and Distance are populated with high confidence; Volatility and Explicitness are derived from config subdomain/public globs. Severity is set by classify.Run for cross-boundary edges via BalanceResult.

type Distance

type Distance string

Distance measures how far apart two modules are in the ownership hierarchy.

const (
	DistanceSameModule           Distance = "same_module"
	DistanceCrossModuleSameOwner Distance = "cross_module_same_owner"
	DistanceCrossModuleDiffOwner Distance = "cross_module_different_owner"
	DistanceCrossDeployUnit      Distance = "cross_deploy_unit"
	DistanceUnknown              Distance = "unknown"
)

Distance constants (spec §18).

type Explicitness

type Explicitness string

Explicitness classifies whether the coupling is via a declared contract.

const (
	ExplicitnessExplicit Explicitness = "explicit"
	ExplicitnessImplicit Explicitness = "implicit"
	ExplicitnessUnknown  Explicitness = "unknown"
)

Explicitness constants. Derived from strength (contract→explicit, intrusive→implicit) or an extractor AST hint when present.

type Index

type Index map[string]Classification

Index maps each edge's canonical key (from + "\x00" + to + "\x00" + kind) to its Classification. Built by classify.Run; consumed by rules and metrics.

type Severity

type Severity string

Severity expresses the risk level of an imbalanced or intrusive coupling edge. Empty string means no finding (balanced).

const (
	SeverityNone     Severity = ""
	SeverityLow      Severity = "low"
	SeverityMedium   Severity = "medium"
	SeverityHigh     Severity = "high"
	SeverityCritical Severity = "critical"
)

Severity constants ordered from no finding to highest risk.

func BalanceResult

func BalanceResult(c Classification) Severity

BalanceResult applies the Khononov balance formula to a Classification and returns the advisory Severity for the edge. SeverityNone means the edge is balanced (no finding).

Severity table (spec §18):

• Intrusive: always surfaced, severity driven by distance/volatility.
• high strength + high distance + high volatility → critical.
• high strength + high distance + low/unknown volatility → medium.
• low strength + low distance + high volatility → medium (over-decoupled volatile seam).
• high strength + low distance → low (high cohesion, usually acceptable).
• low strength + high distance → low (loose coupling across a large boundary).
• low strength + low distance + low/unknown volatility → none (balanced).

type Strength

type Strength string

Strength classifies how a dependency is expressed at the API boundary.

const (
	StrengthContract   Strength = "contract"
	StrengthIntrusive  Strength = "intrusive"
	StrengthModel      Strength = "model"
	StrengthFunctional Strength = "functional"
	StrengthUnknown    Strength = "unknown"
)

Strength constants (spec §18). contract and intrusive are decided deterministically (config globs, visibility); model and functional come from SCIP symbol-kind heuristics — the Tranche-2 enrich workflow refines those labels under human review.

type Volatility

type Volatility string

Volatility classifies how likely a module's API is to change.

const (
	VolatilityHigh    Volatility = "high"
	VolatilityMedium  Volatility = "medium"
	VolatilityLow     Volatility = "low"
	VolatilityUnknown Volatility = "unknown"
)

Volatility constants derived from subdomain classification.