Design universal multi-language coupling metrics model (Group 10 — architecture)

[jflowers]

Summary

Design a universal, language-agnostic coupling metrics model that all language-specific analyzers will target. This architectural design must precede the Go-native gaze coupling implementation (Group 1) to ensure extensibility.

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

Context

We plan to support coupling metrics across multiple languages (Go natively, Python via snake-eyes, TS/JS in future). Rather than building Go-only metrics and retrofitting, we design the universal model first.

Design Requirements

Two-Layer Architecture

• Layer 1 — Universal Metrics Model: Language-agnostic data structures for Ca, Ce, Instability, Abstractness, Distance-from-main-sequence, cohesion, and circular dependency information.
• Layer 2 — Language Adapters: Each language provides an analyzer that emits the universal model. Go is built-in (native); external languages use a protocol to pipe JSON conforming to the universal schema.

External Analyzer Protocol

• External analyzers (e.g., snake-eyes for Python) produce JSON output conforming to the universal schema.
• Gaze invokes the external analyzer binary, reads its stdout, and merges results into the unified report.
• Protocol contract: input = list of paths; output = JSON array of package-level metrics.

JSON Schema

The unified output must include a language field per package entry:

{
  "packages": [
    {
      "language": "go",
      "path": "internal/analyzer",
      "ca": 5,
      "ce": 3,
      "instability": 0.375,
      "abstractness": 0.2,
      "distance": 0.425,
      "cohesion": 0.72,
      "circular_deps": []
    }
  ]
}

Acceptance Criteria

• Universal metrics model documented (types/interfaces in Go, plus prose spec)
• JSON schema definition for the unified coupling output with language field
• External analyzer protocol documented (invocation contract, stdin/stdout format, error handling)
• Go adapter implemented as the reference (native, no external binary)
• Integration point for future Python (snake-eyes) and TS/JS adapters defined
• Architecture decision record (ADR) written

Dependencies

• Blocks: All other coupling metric issues (Go-native Group 1, Python Group 10-python, TS/JS Group 10-ts/js)
• Repo: Primary design lands in gaze; protocol spec shared across repos

Notes

This is the foundational design issue. The Go-native implementation (Group 1) should be opened as a follow-up that depends on this design being accepted.

[jflowers]

Completed by PR #17 — the metrics package implements the universal coupling metrics model (Layer 1) with Module type, named metric types, Adapter interface, ExternalAdapter with JSON-RPC 2.0 protocol, Registry, JSON Schema validation, and security hardening. All 30+ tasks from the OpenSpec change are implemented and tested.