Documentation
¶
Overview ¶
Package reconciler provides structural contract matching and go.mod replace directive generation for MuxCore third-party module imports.
When a module declares it implements "MediaLibrary" from "github.com/some-dev/contracts-media", the reconciler fetches both that repo and the canonical "github.com/Muxcore-Media/contracts-media", extracts the Go interface definitions via AST parsing, compares method signatures, and — if structurally compatible — generates a go.mod replace directive that normalizes the import to the canonical path.
This preserves Go's nominal type safety while honoring the MuxCore philosophy: contracts are patterns, not org-bound dependencies.
Index ¶
- func ApplyReplaceDirectives(workdir string, directives []ReplaceDirective) error
- func DryRun(declarations []Declaration) (string, error)
- func GenerateReplaceBlock(directives []ReplaceDirective) string
- func RegisteredCanonicals() map[string]CanonicalRepo
- type CanonicalRepo
- type Declaration
- type InterfaceSpec
- type MethodSpec
- type ModRequire
- type ReplaceDirective
- type Resolver
- type TypeSpec
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func ApplyReplaceDirectives ¶
func ApplyReplaceDirectives(workdir string, directives []ReplaceDirective) error
ApplyReplaceDirectives runs "go mod edit -replace" for each directive in a go.mod file. The workdir must contain the go.mod to modify.
Existing replace directives for the same old path are overwritten.
func DryRun ¶
func DryRun(declarations []Declaration) (string, error)
DryRun returns a human-readable report of what would be changed without modifying any files.
func GenerateReplaceBlock ¶
func GenerateReplaceBlock(directives []ReplaceDirective) string
GenerateReplaceBlock returns a multi-line string containing all replace directives in go.mod format. Useful for previewing or embedding in documentation.
func RegisteredCanonicals ¶
func RegisteredCanonicals() map[string]CanonicalRepo
RegisteredCanonicals returns all known canonical contract entries.
Types ¶
type CanonicalRepo ¶
type CanonicalRepo struct {
ImportPath string // Go module import path (e.g. "github.com/Muxcore-Media/contracts-media")
Version string // latest known version (e.g. "v1.0.0")
}
CanonicalRepo maps an interface name to its canonical Go module path. The reconciler uses this to know which Muxcore-Media contract repo is the authority for a given interface.
func Canonical ¶
func Canonical(interfaceName string) *CanonicalRepo
Canonical returns the canonical repo for a given interface name, or nil if the interface is not recognized as a MuxCore contract.
type Declaration ¶
type Declaration struct {
Repo string // Go module path (e.g. "github.com/some-dev/contracts-media")
Version string // semantic version tag (e.g. "v1.2.0")
Interface string // Go interface name (e.g. "MediaLibrary")
}
Declaration describes a contract a module claims to implement. This is what appears in a module's muxcore.json or ContractDeclaration list.
type InterfaceSpec ¶
type InterfaceSpec struct {
PackagePath string // the Go import path of the package
Name string // interface name
Methods []MethodSpec // methods (excluding embedded interfaces)
}
InterfaceSpec describes a Go interface for structural comparison.
func CloneAndParse ¶
func CloneAndParse(repoURL, version string) ([]InterfaceSpec, func(), error)
CloneAndParse clones a git repo to a temp directory, parses its Go source, and returns the extracted interface specs. The caller is responsible for cleanup via the returned cleanup function.
func FindInterface ¶
func FindInterface(specs []InterfaceSpec, name string) (*InterfaceSpec, error)
FindInterface finds a specific interface by name in a list of specs.
func ParseDir ¶
func ParseDir(dir string) ([]InterfaceSpec, error)
ParseDir parses all .go files in a directory and extracts exported interface definitions. Non-Go files and test files are skipped.
func ParseFile ¶
func ParseFile(filePath string) ([]InterfaceSpec, error)
ParseFile parses a single .go file and extracts exported interface definitions.
func (InterfaceSpec) Equal ¶
func (s InterfaceSpec) Equal(other InterfaceSpec) bool
Equal checks whether two interface specs are structurally identical. Package paths are NOT compared — only method names, parameter types, and return types matter. This is what makes third-party contracts compatible with canonical ones: same pattern, different origin.
type MethodSpec ¶
type MethodSpec struct {
Name string // method name
Params []TypeSpec // parameter types (receiver excluded)
Results []TypeSpec // return types
}
MethodSpec describes a single method in a Go interface.
type ModRequire ¶
ModRequire represents a single require directive in go.mod.
func ParseGoModFile ¶
func ParseGoModFile(modPath string) ([]ModRequire, error)
ParseGoModFile parses a go.mod file and returns all require directives.
type ReplaceDirective ¶
type ReplaceDirective struct {
OldPath string // the module path to replace
NewPath string // the canonical module path
Version string // version to pin (e.g. "v1.0.0")
}
ReplaceDirective represents a single go.mod replace directive.
func ParseReplaceDirective ¶
func ParseReplaceDirective(line string) (ReplaceDirective, error)
ParseReplaceDirective parses a "go mod edit -replace" output line.
func (ReplaceDirective) String ¶
func (d ReplaceDirective) String() string
String formats the directive as a go.mod replace line.
type Resolver ¶
type Resolver struct {
// CacheDir is where cloned contract repos are stored. Defaults to a
// temp directory. Set this if you want to cache across invocations.
CacheDir string
}
Resolver checks third-party contract declarations against canonical equivalents and generates go.mod replace directives when interfaces match.
func (*Resolver) Resolve ¶
func (r *Resolver) Resolve(decl Declaration) (*ReplaceDirective, error)
Resolve checks whether a module's contract declaration is compatible with the canonical contract repo for the same interface name.
It returns (nil, nil) when:
- The declaration already uses the canonical repo (no work needed)
- No canonical equivalent exists for this interface (not a MuxCore contract)
It returns a ReplaceDirective when:
- The declaration uses a non-canonical repo
- The interface in both repos is structurally identical
It returns an error when:
- The interface name isn't found in either repo
- The interfaces are structurally different (mismatch report)
- Either repo can't be fetched or parsed
func (*Resolver) ResolveAll ¶
func (r *Resolver) ResolveAll(decls []Declaration) ([]ReplaceDirective, []error)
ResolveAll processes a list of declarations and returns all applicable replace directives. Mismatches are collected as errors in the returned slice alongside successful directives.
type TypeSpec ¶
type TypeSpec struct {
Kind string // "ident", "selector", "star", "array", "slice", "map", "interface", "chan", "func", "struct"
Name string // package-local name (e.g. "MediaObject", "MediaFilter")
ImportPath string // for selectors: the package import path (e.g. "github.com/Muxcore-Media/contracts-media")
Elem *TypeSpec // element type for pointers, slices, arrays
Key *TypeSpec // key type for maps
Params []TypeSpec // for func types
Results []TypeSpec // for func types
Fields []TypeSpec // for struct types
}
TypeSpec describes a Go type for structural comparison. Only carries enough information to match signatures — two types with different package paths but identical structure are considered compatible.
Source Files