vibe-check analyze — Go-native package-level coupling metrics

[jflowers]

Summary

Add a vibe-check analyze command that computes package-level structural quality metrics for Go codebases using the Go-native toolchain.

RFC: https://github.com/orgs/unbound-force/discussions/483 — Group 1
Phase: P0 (Foundation)

Context

The metrics package (merged via PR #17) provides the universal coupling model — named metric types, the Adapter interface, ExternalAdapter with JSON-RPC 2.0 protocol, Registry, and JSON Schema validation. This issue builds the Go-native adapter and CLI on top of that foundation, making the metrics computable and accessible.

Architecture

vibe-check analyze [packages...]
        │
        ├── cmd/vibe-check/          CLI entry point (cobra)
        ├── internal/go/             Go-native adapter (implements metrics.Adapter)
        │     └── uses golang.org/x/tools/go/packages
        └── metrics/                 Universal model (already merged)
              ├── adapter.go         Adapter interface
              ├── compute.go         ComputeInstability, ComputeAbstractness, etc.
              ├── graph.go           ModuleGraph, ModuleResult
              └── values.go          Instability, Abstractness, Distance, LCOM

Metrics to Compute

Metric	Symbol	Description
Afferent Coupling	Ca	Number of packages that depend on this package
Efferent Coupling	Ce	Number of packages this package depends on
Instability	I	Ce / (Ca + Ce) — ranges from 0 (stable) to 1 (unstable)
Abstractness	A	Ratio of abstract types (interfaces) to total types
Distance from Main Sequence	D	|A + I − 1| — proximity to the ideal balance
Cohesion	LCOM	LCOM4 variant (Hitz & Montazeri, 1995)
Circular Dependencies	—	Detection of import cycles

Implementation

• Go adapter: Implements metrics.Adapter interface using golang.org/x/tools/go/packages for type-aware dependency resolution
• CLI: vibe-check analyze [packages...] using cobra
• Output: JSON conforming to metrics.ModuleGraph schema (validated by metrics.Validate)
• Registration: Go adapter registered in metrics.Registry at startup

CI Gate Flags

vibe-check analyze ./... \
  --max-instability=0.67 \
  --max-distance=0.3 \
  --no-circular-deps \
  --min-cohesion=0.5

Exit code non-zero if any threshold is violated.

JSON Output

{
  "schemaVersion": "1.0",
  "language": "go",
  "projectPath": "./...",
  "status": "complete",
  "modules": [
    {
      "path": "internal/analyzer",
      "afferentCoupling": 5,
      "efferentCoupling": 3,
      "instability": 0.375,
      "abstractness": 0.2,
      "distance": 0.425,
      "lcom": 2,
      "cycles": []
    }
  ],
  "warnings": []
}

Acceptance Criteria

• vibe-check analyze command implemented using cobra
• Go adapter implements metrics.Adapter interface
• Uses golang.org/x/tools/go/packages for dependency resolution
• All 7 metrics computed correctly (Ca, Ce, I, A, D, LCOM, circular deps)
• JSON output conforms to metrics.ModuleGraph schema (passes metrics.Validate)
• CI gate flags work (--max-instability, --max-distance, --no-circular-deps, --min-cohesion)
• Non-zero exit code on threshold violations
• Tests covering metric computation accuracy
• go build ./..., go test -race -count=1 ./..., golangci-lint run ./... all pass

Dependencies

• Depends on: Design universal multi-language coupling metrics model (Group 10 — architecture) #1 (completed) — universal coupling model (metrics package)

[jflowers]

Amendment: Language-Specific Extensions (Go Adapter)

Background

A gap analysis against the comprehensive Martin metrics framework identified two Go-specific metrics that are absent from the current scope but valuable for Go codebases:

Metric	Description	Source
Interface Width (Pike Metric)	Method count per interface. Go idiom favors narrow interfaces (1-2 methods); wider interfaces signal abstraction problems.	Rob Pike / Go Proverbs
Interface-to-Implementation Proximity	Whether interfaces are declared on the consumer side (idiomatic) vs. producer side. Consumer-side declaration is a Go best practice.	Go FAQ, Effective Go

Proposed Integration

These metrics are language-specific and do not belong in the universal ModuleResult schema. Instead, they should be carried via an extensions mechanism:

1. Schema Change (prerequisite — applies to all adapters)

Add an optional extensions field to the module item in modulegraph.schema.json:

"extensions": {
  "type": "object",
  "description": "Language-specific metrics not part of the universal model. Keys are namespaced by language (e.g., go.interfaceWidth)."
}

Remove "additionalProperties": false from the module item (or change it to allow extensions explicitly). The top-level ModuleGraph and Warning schemas remain strict.

2. Go Struct Change

Add to ModuleResult in metrics/graph.go:

// Extensions contains language-specific metrics that are not part of the
// universal model. Keys are namespaced by language (e.g., "go.interfaceWidth").
// Adapters populate this field; the core model does not interpret it.
Extensions map[string]any `json:"extensions,omitempty"`

3. Go Adapter Populates Extensions

The Go adapter (in internal/go/) populates:

• go.interfaceWidth — map[string]int mapping interface name to method count. Enables linting rules like "flag interfaces with >5 methods."
• go.interfaceProximity — map[string]string mapping interface name to "consumer" or "producer", based on whether the interface is declared in the same package as its primary implementation.

4. New Capability Constants

CapInterfaceWidth    Capability = "go.interfaceWidth"
CapInterfaceProximity Capability = "go.interfaceProximity"

These are optional capabilities — declared by the Go adapter but not required by the universal model.

Additional Acceptance Criteria

Appended to the existing criteria:

• ModuleResult.Extensions field added with omitempty JSON tag
• JSON schema updated to allow extensions object on module items
• Go adapter populates go.interfaceWidth for all exported interfaces
• Go adapter populates go.interfaceProximity for all exported interfaces
• go.interfaceWidth and go.interfaceProximity capabilities declared
• Extensions are validated as proper JSON objects (no schema enforcement on contents)
• Existing tests continue to pass (extensions field is optional)

Non-Goals

• No CI gate flags for extension metrics in this issue (can be added later)
• No changes to the universal Module or ModuleResult fields beyond Extensions
• No new Capability constants in the universal model — these live in the adapter package