diff --git a/CHANGELOG.md b/CHANGELOG.md index ba428f1..1c12878 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,24 @@ This module adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html --- +## [0.2.0] — 2026-06-10 + +Minor release. The indexer now captures the *members* of composite types, closing a gap where `get_symbol` and `search_symbols` could name a struct or interface but not describe its shape — most painfully, struct tags (env-var keys, json names) were invisible. + +### Added + +- **Struct fields in the index.** Each struct-type symbol now carries a `fields` array — field name, type, raw struct tag (backticks stripped), doc comment, and an `embedded` marker. `get_symbol` returns it; previously the signature was truncated to the bare `type X struct` header, so field names, types, and tags (e.g. `env:"EINHERJAR_PG_HOST"`) were dropped entirely. +- **Interface method sets in the index.** Each interface-type symbol now carries a `methods` array — method name, signature (without the leading `func`), and doc comment, including embedded interfaces. Consumers can now see what a port like `db-postgres` `Provider` actually requires. +- **Search by field/tag/method.** `search_symbols` now also matches a query against struct field names, field types, and struct tags, and against interface method names/signatures — so an env-var key or a method name resolves to the type that declares it. +- **`internal/index` test suite** covering field, tag, embedded-field, interface-method, and search-by-tag capture (the package previously had no tests). + +### Notes + +- The index schema gains two optional (`omitempty`) fields; `SchemaVersion` is unchanged because the change is additive and older consumers parse the new index unchanged. +- This is a pure indexer/schema change. The live server picks it up on its next image build, which re-runs `cmd/indexer` (see `Dockerfile`). A deployment that has not been rebuilt will still serve the older, member-less index. + +--- + ## [0.1.1] — 2026-05-29 Patch release. Two changes to `cmd/server` make the binary cleaner to run behind a unix socket on a reverse-proxied host, plus two repository-hygiene changes that follow from the same deployment exercise. diff --git a/README.md b/README.md index 0014d31..8733fd2 100644 --- a/README.md +++ b/README.md @@ -45,8 +45,8 @@ Cursor, Zed, and anything else that speaks MCP): |---|---| | `list_modules` | Enumerate every Einherjar module with its purpose and sub-packages | | `get_module` | Package doc, dependencies, sub-packages, key types, compliance counts; optional README | -| `search_symbols` | Find a type, function, or interface by name, doc text, sub-package, or module | -| `get_symbol` | Full signature, doc comment, and source location for one symbol | +| `search_symbols` | Find a type, function, or interface by name, doc text, sub-package, module — or by a struct field/tag or an interface method | +| `get_symbol` | Full signature, doc comment, and source location for one symbol — plus struct fields (with tags) and interface method sets | | `list_adrs` | List architectural decision records, optionally restricted to one module | | `get_adr` | Fetch a single ADR's markdown body | | `get_example` | Canonical usage snippet — pulled from module READMEs and from the synthetic `wire` conventions | diff --git a/internal/index/builder.go b/internal/index/builder.go index b66b1f8..06831d4 100644 --- a/internal/index/builder.go +++ b/internal/index/builder.go @@ -154,7 +154,14 @@ func collectSymbols(m *Module, sub, modDir string, fset *token.FileSet, p *doc.P if isInterface(t.Decl) { kind = "interface" } - m.Symbols = append(m.Symbols, newSymbol(m.Name, sub, kind, t.Name, t.Doc, t.Decl, fset, modDir)) + sym := newSymbol(m.Name, sub, kind, t.Name, t.Doc, t.Decl, fset, modDir) + switch underlying := typeSpecType(t.Decl).(type) { + case *ast.StructType: + sym.Fields = extractFields(fset, underlying) + case *ast.InterfaceType: + sym.Methods = extractIfaceMethods(fset, underlying) + } + m.Symbols = append(m.Symbols, sym) for _, f := range t.Funcs { m.Symbols = append(m.Symbols, newSymbol(m.Name, sub, "func", f.Name, f.Doc, f.Decl, fset, modDir)) } @@ -221,6 +228,95 @@ func isInterface(decl *ast.GenDecl) bool { return false } +// typeSpecType returns the underlying type expression of a single-type GenDecl +// (the RHS of `type X = `), or nil when the declaration is not a lone +// type spec. Used to tell struct/interface declarations apart from aliases and +// defined primitives so their members can be extracted. +func typeSpecType(decl *ast.GenDecl) ast.Expr { + if decl == nil { + return nil + } + for _, spec := range decl.Specs { + if ts, ok := spec.(*ast.TypeSpec); ok { + return ts.Type + } + } + return nil +} + +// extractFields flattens a struct's field list into index Fields, preserving +// declaration order, struct tags (backticks stripped), embedded markers, and +// per-field doc/line comments. A `x, y int` group yields one Field per name. +func extractFields(fset *token.FileSet, st *ast.StructType) []Field { + if st == nil || st.Fields == nil { + return nil + } + var out []Field + for _, f := range st.Fields.List { + typeStr := nodeString(fset, f.Type) + tag := "" + if f.Tag != nil { + tag = strings.Trim(f.Tag.Value, "`") + } + fdoc := fieldDoc(f) + if len(f.Names) == 0 { + // Embedded field: the type name is also the field name. + out = append(out, Field{Type: typeStr, Tag: tag, Doc: fdoc, Embedded: true}) + continue + } + for _, n := range f.Names { + out = append(out, Field{Name: n.Name, Type: typeStr, Tag: tag, Doc: fdoc}) + } + } + return out +} + +// extractIfaceMethods flattens an interface's method set into index Methods. +// Explicit methods carry their name and the signature without the leading +// `func`; embedded interfaces carry an empty name and the embedded type's name +// as the signature. +func extractIfaceMethods(fset *token.FileSet, it *ast.InterfaceType) []Method { + if it == nil || it.Methods == nil { + return nil + } + var out []Method + for _, f := range it.Methods.List { + mdoc := fieldDoc(f) + if len(f.Names) == 0 { + // Embedded interface (or type constraint element). + out = append(out, Method{Signature: nodeString(fset, f.Type), Doc: mdoc}) + continue + } + sig := strings.TrimPrefix(nodeString(fset, f.Type), "func") + for _, n := range f.Names { + out = append(out, Method{Name: n.Name, Signature: n.Name + sig, Doc: mdoc}) + } + } + return out +} + +func fieldDoc(f *ast.Field) string { + switch { + case f.Doc != nil: + return strings.TrimSpace(f.Doc.Text()) + case f.Comment != nil: + return strings.TrimSpace(f.Comment.Text()) + } + return "" +} + +// nodeString prints an AST node verbatim with no truncation — unlike +// formatNode, which deliberately strips type/func bodies for one-line +// signatures. Used for field types, tags, and interface method signatures. +func nodeString(fset *token.FileSet, node ast.Node) string { + var buf bytes.Buffer + cfg := printer.Config{Mode: printer.UseSpaces, Tabwidth: 4} + if err := cfg.Fprint(&buf, fset, node); err != nil { + return "" + } + return strings.TrimSpace(buf.String()) +} + var ( modulePathRe = regexp.MustCompile(`(?m)^module\s+(\S+)`) goVersionRe = regexp.MustCompile(`(?m)^go\s+(\S+)`) diff --git a/internal/index/builder_test.go b/internal/index/builder_test.go new file mode 100644 index 0000000..9e7fa9d --- /dev/null +++ b/internal/index/builder_test.go @@ -0,0 +1,149 @@ +package index + +import ( + "os" + "path/filepath" + "testing" +) + +// writeFixture lays down a single-module Einherjar-like repo under a temp root +// and returns the root path for Build to walk. +func writeFixture(t *testing.T) string { + t.Helper() + root := t.TempDir() + modDir := filepath.Join(root, "demo") + if err := os.MkdirAll(modDir, 0o755); err != nil { + t.Fatal(err) + } + write := func(name, body string) { + if err := os.WriteFile(filepath.Join(modDir, name), []byte(body), 0o644); err != nil { + t.Fatal(err) + } + } + write("go.mod", "module example.com/demo\n\ngo 1.26\n") + write("demo.go", `// Package demo is a build fixture. +package demo + +import "context" + +// Config holds settings. +type Config struct { + // Host is the bind address. + Host string `+"`"+`env:"DEMO_HOST" envDefault:"0.0.0.0"`+"`"+` + Port int `+"`"+`env:"DEMO_PORT"`+"`"+` + Inner +} + +// Inner is embedded into Config. +type Inner struct { + Name string +} + +// Store reads values. +type Store interface { + // Get fetches one value. + Get(ctx context.Context, id string) (string, error) + context.Context +} +`) + return root +} + +func findSymbol(t *testing.T, idx *Index, mod, name string) Symbol { + t.Helper() + m := idx.FindModule(mod) + if m == nil { + t.Fatalf("module %q not found", mod) + } + for _, s := range m.Symbols { + if s.Name == name { + return s + } + } + t.Fatalf("symbol %q not found in module %q", name, mod) + return Symbol{} +} + +func TestBuildCapturesStructFields(t *testing.T) { + idx, err := Build(writeFixture(t)) + if err != nil { + t.Fatal(err) + } + + cfg := findSymbol(t, idx, "demo", "Config") + if cfg.Kind != "type" { + t.Errorf("Config kind = %q, want type", cfg.Kind) + } + if len(cfg.Fields) != 3 { + t.Fatalf("Config has %d fields, want 3: %+v", len(cfg.Fields), cfg.Fields) + } + + host := cfg.Fields[0] + if host.Name != "Host" || host.Type != "string" { + t.Errorf("field[0] = %+v, want Host string", host) + } + if host.Tag != `env:"DEMO_HOST" envDefault:"0.0.0.0"` { + t.Errorf("Host tag = %q, want the env/envDefault tag (backticks stripped)", host.Tag) + } + if host.Doc != "Host is the bind address." { + t.Errorf("Host doc = %q", host.Doc) + } + + if port := cfg.Fields[1]; port.Name != "Port" || port.Tag != `env:"DEMO_PORT"` { + t.Errorf("field[1] = %+v, want Port with env tag", port) + } + + if inner := cfg.Fields[2]; !inner.Embedded || inner.Name != "" || inner.Type != "Inner" { + t.Errorf("field[2] = %+v, want embedded Inner", inner) + } +} + +func TestBuildCapturesInterfaceMethods(t *testing.T) { + idx, err := Build(writeFixture(t)) + if err != nil { + t.Fatal(err) + } + + store := findSymbol(t, idx, "demo", "Store") + if store.Kind != "interface" { + t.Errorf("Store kind = %q, want interface", store.Kind) + } + if len(store.Methods) != 2 { + t.Fatalf("Store has %d methods, want 2: %+v", len(store.Methods), store.Methods) + } + + get := store.Methods[0] + if get.Name != "Get" { + t.Errorf("method[0] name = %q, want Get", get.Name) + } + if get.Signature != "Get(ctx context.Context, id string) (string, error)" { + t.Errorf("Get signature = %q", get.Signature) + } + if get.Doc != "Get fetches one value." { + t.Errorf("Get doc = %q", get.Doc) + } + + if emb := store.Methods[1]; emb.Name != "" || emb.Signature != "context.Context" { + t.Errorf("method[1] = %+v, want embedded context.Context", emb) + } +} + +// A struct must be discoverable by one of its struct tags — the failure mode +// that motivated capturing fields in the first place. +func TestSearchSymbolsByStructTag(t *testing.T) { + idx, err := Build(writeFixture(t)) + if err != nil { + t.Fatal(err) + } + + got := idx.SearchSymbols("DEMO_HOST", 10) + found := false + for _, s := range got { + if s.Name == "Config" { + found = true + } + } + if !found { + t.Errorf("searching a struct tag did not surface its type; got %d results", len(got)) + } +} diff --git a/internal/index/index.go b/internal/index/index.go index b9c9e73..87613b3 100644 --- a/internal/index/index.go +++ b/internal/index/index.go @@ -77,15 +77,46 @@ type SubPackage struct { } // Symbol is one exported declaration (type, func, interface, const, var). +// +// For struct types Fields carries the field set (the Signature is only the +// one-line `type X struct` header, so without Fields the field names, types, +// and — crucially — struct tags would be lost). For interface types Methods +// carries the method set for the same reason. Both are empty for every other +// kind. type Symbol struct { - Module string `json:"module"` - SubPackage string `json:"subPackage"` - Kind string `json:"kind"` - Name string `json:"name"` - Signature string `json:"signature"` - Doc string `json:"doc"` - File string `json:"file"` - Line int `json:"line"` + Module string `json:"module"` + SubPackage string `json:"subPackage"` + Kind string `json:"kind"` + Name string `json:"name"` + Signature string `json:"signature"` + Doc string `json:"doc"` + File string `json:"file"` + Line int `json:"line"` + Fields []Field `json:"fields,omitempty"` + Methods []Method `json:"methods,omitempty"` +} + +// Field is one field of a struct-type Symbol. Name is empty for an embedded +// field (its type then appears in Type, with Embedded true). Tag is the raw +// struct tag with the surrounding backticks stripped (e.g. +// `env:"EINHERJAR_PG_HOST" envDefault:"postgres"`) — the single most useful +// thing a config consumer needs and the thing the old index dropped. +type Field struct { + Name string `json:"name,omitempty"` + Type string `json:"type"` + Tag string `json:"tag,omitempty"` + Doc string `json:"doc,omitempty"` + Embedded bool `json:"embedded,omitempty"` +} + +// Method is one method of an interface-type Symbol. Signature is the method +// as written without the leading func keyword (e.g. +// `GetExecutor(ctx context.Context) Executor`). For an embedded interface +// Name is empty and Signature is the embedded interface's name. +type Method struct { + Name string `json:"name,omitempty"` + Signature string `json:"signature"` + Doc string `json:"doc,omitempty"` } // ADR is one architectural decision record. @@ -157,8 +188,27 @@ func matches(s Symbol, needle string) bool { if needle == "" { return true } - return strings.Contains(strings.ToLower(s.Name), needle) || + if strings.Contains(strings.ToLower(s.Name), needle) || strings.Contains(strings.ToLower(s.Doc), needle) || strings.Contains(strings.ToLower(s.SubPackage), needle) || - strings.Contains(strings.ToLower(s.Module), needle) + strings.Contains(strings.ToLower(s.Module), needle) { + return true + } + // A struct is also findable by a field name, type, or tag — so a query + // like an env-var key or json field resolves to the type that declares it. + for _, f := range s.Fields { + if strings.Contains(strings.ToLower(f.Name), needle) || + strings.Contains(strings.ToLower(f.Type), needle) || + strings.Contains(strings.ToLower(f.Tag), needle) { + return true + } + } + // An interface is findable by a method it requires. + for _, mth := range s.Methods { + if strings.Contains(strings.ToLower(mth.Name), needle) || + strings.Contains(strings.ToLower(mth.Signature), needle) { + return true + } + } + return false } diff --git a/internal/tools/get_symbol.go b/internal/tools/get_symbol.go index 027707a..3e366d3 100644 --- a/internal/tools/get_symbol.go +++ b/internal/tools/get_symbol.go @@ -21,7 +21,7 @@ type getSymbolOutput struct { func registerGetSymbol(s *mcp.Server, idx *index.Index) { mcp.AddTool(s, &mcp.Tool{ Name: "get_symbol", - Description: "Fetch full signature, doc comment, and source location for one symbol. Returns every match across sub-packages — use the subPackage filter when ambiguous.", + Description: "Fetch full signature, doc comment, and source location for one symbol. For a struct type the result includes its fields (name, type, struct tag, doc); for an interface type it includes its method set. Returns every match across sub-packages — use the subPackage filter when ambiguous.", }, func(ctx context.Context, req *mcp.CallToolRequest, args getSymbolInput) (*mcp.CallToolResult, getSymbolOutput, error) { m := idx.FindModule(args.Module) if m == nil { diff --git a/internal/tools/search_symbols.go b/internal/tools/search_symbols.go index 89533b8..20408c6 100644 --- a/internal/tools/search_symbols.go +++ b/internal/tools/search_symbols.go @@ -22,7 +22,7 @@ type searchSymbolsOutput struct { func registerSearchSymbols(s *mcp.Server, idx *index.Index) { mcp.AddTool(s, &mcp.Tool{ Name: "search_symbols", - Description: "Search Einherjar's exported symbols (types, interfaces, funcs, methods, consts, vars) by name or doc text. Optionally filter by module or kind. Use when you need to find where a type or function lives.", + Description: "Search Einherjar's exported symbols (types, interfaces, funcs, methods, consts, vars) by name or doc text. Structs also match on a field name, field type, or struct tag (e.g. an env-var key); interfaces also match on a required method. Optionally filter by module or kind. Use when you need to find where a type, function, field, or tag lives.", }, func(ctx context.Context, req *mcp.CallToolRequest, args searchSymbolsInput) (*mcp.CallToolResult, searchSymbolsOutput, error) { all := idx.SearchSymbols(args.Query, args.Limit*4+25) filtered := all[:0]