package plugin_test import ( "go/ast" "go/parser" "go/token" "io/fs" "maps" "os" "path/filepath" "reflect" "slices" "strings" "testing" "github.com/samcharles93/archie-core/internal/plugin" ) const ( engineRuleHeading = "## Plugin engine rule (strict)" engineRuleLink = "ARCHITECTURE.md#plugin-engine-rule-strict" ) func TestPluginEngineRuleIsCanonicalAndSharedByAgentInstructions(t *testing.T) { t.Parallel() repoRoot := filepath.Clean(filepath.Join("..", "..")) architecture := readTestFile(t, filepath.Join(repoRoot, "ARCHITECTURE.md")) if !strings.Contains(architecture, engineRuleHeading) { t.Fatalf("ARCHITECTURE.md does not contain canonical heading %q", engineRuleHeading) } claudePath := filepath.Join(repoRoot, "CLAUDE.md") agentsPath := filepath.Join(repoRoot, "AGENTS.md") claude := readTestFile(t, claudePath) if !strings.Contains(claude, engineRuleLink) { t.Fatalf("CLAUDE.md does not reference canonical plugin engine rule %q", engineRuleLink) } claudeInfo, err := os.Stat(claudePath) if err != nil { t.Fatalf("stat CLAUDE.md: %v", err) } agentsInfo, err := os.Stat(agentsPath) if err != nil { t.Fatalf("stat AGENTS.md: %v", err) } if !os.SameFile(claudeInfo, agentsInfo) { t.Fatal("AGENTS.md and CLAUDE.md must share one instruction source") } } func TestGenericPluginContractRemainsMetadataOnly(t *testing.T) { t.Parallel() pluginType := reflect.TypeFor[plugin.Plugin]() got := make([]string, 0, pluginType.NumMethod()) for method := range pluginType.Methods() { got = append(got, method.Name) } slices.Sort(got) want := []string{"Name", "Version"} if !slices.Equal(got, want) { t.Fatalf("plugin.Plugin methods = %v, want metadata-only contract %v; add typed capability family instead", got, want) } } func TestEveryEngineInterfaceHasTypedCapabilityAndFamilyOwner(t *testing.T) { t.Parallel() repoRoot := filepath.Clean(filepath.Join("..", "..")) families, err := inspectEngineFamilies(filepath.Join(repoRoot, "internal")) if err != nil { t.Fatal(err) } if len(families) == 0 { t.Fatal("no engine interfaces found; architecture check is not exercising the repository") } for _, family := range families { t.Run(family.packagePath+"."+family.engineName, func(t *testing.T) { t.Parallel() if !family.hasDomainMethod { t.Error("engine exposes only generic metadata; add typed capability methods") } if !family.hasOwner { t.Error("engine has no Registry or Manager family owner") } if !family.ownerRegisters { t.Error("engine family owner does not control provider registration") } if !family.ownerManages { t.Error("engine family owner does not return the registered engine type") } if !family.singleOwner { t.Error("one Registry or Manager must both register and return the engine type") } }) } } func TestEngineFamilyInspectionRejectsInvalidShapes(t *testing.T) { t.Parallel() tests := []struct { name string src string valid bool }{ { name: "typed family", src: `package fixture type Engine interface { Name() string; Version() string; Resolve(string) (string, error) } type Registry struct{} func (*Registry) Register(Engine) {} func (*Registry) Get(string) (Engine, bool) { return nil, false } `, valid: true, }, { name: "embedded typed family", src: `package fixture type Resolver interface { Resolve(string) (string, error) } type Engine interface { Resolver } type Registry struct{} func (*Registry) Register(Engine) {} func (*Registry) Get(string) (Engine, bool) { return nil, false } `, valid: true, }, { name: "metadata only", src: `package fixture type Engine interface { Name() string; Version() string } type Registry struct{} func (*Registry) Register(Engine) {} func (*Registry) Get(string) (Engine, bool) { return nil, false } `, }, { name: "lifecycle only", src: `package fixture type Engine interface { Name() string Version() string Start() error Health() string Stop() error } type Registry struct{} func (*Registry) Register(Engine) {} func (*Registry) Get(string) (Engine, bool) { return nil, false } `, }, { name: "embedded metadata only", src: `package fixture type Metadata interface { Name() string; Version() string } type Engine interface { Metadata } type Registry struct{} func (*Registry) Register(Engine) {} func (*Registry) Get(string) (Engine, bool) { return nil, false } `, }, { name: "unrelated owner methods", src: `package fixture type Engine interface { Resolve(string) (string, error) } type Registry struct{} func (*Registry) Register(string) {} func (*Registry) Get(string) (string, bool) { return "", false } `, }, { name: "split owners", src: `package fixture type Engine interface { Resolve(string) (string, error) } type Registry struct{} func (*Registry) Register(Engine) {} type Manager struct{} func (*Manager) Get(string) (Engine, bool) { return nil, false } `, }, { name: "pointer to engine interface", src: `package fixture type Engine interface { Resolve(string) (string, error) } type Registry struct{} func (*Registry) Register(*Engine) {} func (*Registry) Get(string) (*Engine, bool) { return nil, false } `, }, { name: "collection of engine interfaces", src: `package fixture type Engine interface { Resolve(string) (string, error) } type Registry struct{} func (*Registry) Register([]Engine) {} func (*Registry) Get(string) ([]Engine, bool) { return nil, false } `, }, } for _, tt := range tests { t.Run(tt.name, func(t *testing.T) { file, err := parser.ParseFile(token.NewFileSet(), tt.name+".go", tt.src, 0) if err != nil { t.Fatal(err) } families := engineFamiliesInPackage(".", ".", []*ast.File{file}) if len(families) != 1 { t.Fatalf("found %d engine families, want 1", len(families)) } family := families[0] got := family.hasDomainMethod && family.hasOwner && family.ownerRegisters && family.ownerManages && family.singleOwner if got != tt.valid { t.Fatalf("family validity = %t, want %t: %+v", got, tt.valid, family) } }) } } type engineFamily struct { packagePath string engineName string hasDomainMethod bool hasOwner bool ownerRegisters bool ownerManages bool singleOwner bool } func inspectEngineFamilies(root string) ([]engineFamily, error) { dirs := make(map[string]struct{}) err := filepath.WalkDir(root, func(path string, entry fs.DirEntry, walkErr error) error { if walkErr != nil { return walkErr } if entry.IsDir() { dirs[path] = struct{}{} } return nil }) if err != nil { return nil, err } var families []engineFamily for dir := range dirs { packages, err := parsePackageFiles(dir) if err != nil { return nil, err } for _, files := range packages { families = append(families, engineFamiliesInPackage(root, dir, files)...) } } slices.SortFunc(families, func(a, b engineFamily) int { return strings.Compare(a.packagePath+"."+a.engineName, b.packagePath+"."+b.engineName) }) return families, nil } func parsePackageFiles(dir string) (map[string][]*ast.File, error) { entries, err := os.ReadDir(dir) if err != nil { return nil, err } packages := make(map[string][]*ast.File) fileSet := token.NewFileSet() for _, entry := range entries { if entry.IsDir() || !strings.HasSuffix(entry.Name(), ".go") || strings.HasSuffix(entry.Name(), "_test.go") { continue } file, err := parser.ParseFile(fileSet, filepath.Join(dir, entry.Name()), nil, 0) if err != nil { return nil, err } packages[file.Name.Name] = append(packages[file.Name.Name], file) } return packages, nil } func engineFamiliesInPackage(root, dir string, files []*ast.File) []engineFamily { engines := make(map[string]bool) interfaces := make(map[string]*ast.InterfaceType) owners := make(map[string]bool) ownerMethods := make(map[string][]*ast.FuncDecl) for _, file := range files { for _, decl := range file.Decls { switch decl := decl.(type) { case *ast.GenDecl: for _, spec := range decl.Specs { typeSpec, ok := spec.(*ast.TypeSpec) if !ok { continue } if iface, ok := typeSpec.Type.(*ast.InterfaceType); ok { interfaces[typeSpec.Name.Name] = iface } if typeSpec.Name.Name == "Registry" || typeSpec.Name.Name == "Manager" { owners[typeSpec.Name.Name] = true } } case *ast.FuncDecl: receiver := receiverName(decl) if receiver != "Registry" && receiver != "Manager" { continue } ownerMethods[receiver] = append(ownerMethods[receiver], decl) } } } for name, iface := range interfaces { if strings.HasSuffix(name, "Engine") { engines[name] = hasDomainMethod(iface, interfaces, nil) } } packagePath, err := filepath.Rel(root, dir) if err != nil { packagePath = dir } out := make([]engineFamily, 0, len(engines)) for name, domainMethod := range engines { registers := false manages := false singleOwner := false for owner := range owners { ownerRegisters := ownerRegistersEngine(ownerMethods[owner], name) ownerManages := ownerReturnsEngine(ownerMethods[owner], name) registers = registers || ownerRegisters manages = manages || ownerManages singleOwner = singleOwner || ownerRegisters && ownerManages } out = append(out, engineFamily{ packagePath: filepath.ToSlash(packagePath), engineName: name, hasDomainMethod: domainMethod, hasOwner: len(owners) > 0, ownerRegisters: registers, ownerManages: manages, singleOwner: singleOwner, }) } return out } func hasDomainMethod( iface *ast.InterfaceType, interfaces map[string]*ast.InterfaceType, visiting map[string]bool, ) bool { genericMethods := []string{ "Health", "Manifest", "Name", "Start", "Stop", "Version", } for _, field := range iface.Methods.List { for _, name := range field.Names { if _, generic := slices.BinarySearch(genericMethods, name.Name); !generic { return true } } if len(field.Names) != 0 { continue } embedded, ok := field.Type.(*ast.Ident) if !ok || visiting[embedded.Name] { continue } embeddedInterface, ok := interfaces[embedded.Name] if !ok { continue } next := maps.Clone(visiting) if next == nil { next = make(map[string]bool) } next[embedded.Name] = true if hasDomainMethod(embeddedInterface, interfaces, next) { return true } } return false } func receiverName(decl *ast.FuncDecl) string { if decl.Recv == nil || len(decl.Recv.List) == 0 { return "" } switch receiver := decl.Recv.List[0].Type.(type) { case *ast.Ident: return receiver.Name case *ast.StarExpr: if ident, ok := receiver.X.(*ast.Ident); ok { return ident.Name } } return "" } func ownerRegistersEngine(methods []*ast.FuncDecl, engineName string) bool { for _, method := range methods { if method.Name.Name != "Register" || method.Type.Params == nil { continue } for _, field := range method.Type.Params.List { if expressionNamesType(field.Type, engineName) { return true } } } return false } func ownerReturnsEngine(methods []*ast.FuncDecl, engineName string) bool { for _, method := range methods { if method.Type.Results == nil { continue } for _, field := range method.Type.Results.List { if expressionNamesType(field.Type, engineName) { return true } } } return false } func expressionNamesType(expr ast.Expr, typeName string) bool { ident, ok := expr.(*ast.Ident) return ok && ident.Name == typeName } func readTestFile(t *testing.T, path string) string { t.Helper() data, err := os.ReadFile(path) if err != nil { t.Fatalf("read %s: %v", path, err) } return string(data) }