feat(mcp): index struct fields and interface method sets

Minor release. The indexer named composite types but could not describe
their shape: every declaration was truncated at the first brace, so a
struct symbol carried only its `type X struct` header and an interface
symbol only its `type X interface` header. Field names, field types, and
— most painfully — struct tags such as `env:"EINHERJAR_PG_HOST"` were
dropped, as were the method sets of every port interface. An assistant
could be told that `db-postgres` has a `Config` and a `Provider`, but not
what env vars configure the one or what methods the other requires. This
change captures both.

internal/index (schema):
- Symbol gains two optional fields. `fields` ([]Field) carries a struct's
  field set — name, type, raw struct tag (surrounding backticks stripped),
  doc comment, and an `embedded` marker. `methods` ([]Method) carries an
  interface's method set — name, signature without the leading `func`, and
  doc comment, including embedded interfaces. Both are omitempty and absent
  for every other kind.
- SchemaVersion is deliberately unchanged. The two additions are additive
  and omitempty, so an older consumer parses the new index unchanged; per
  the existing rule the constant only bumps on a breaking format change.

internal/index (builder):
- collectSymbols now inspects each type's TypeSpec and, for a *ast.StructType
  or *ast.InterfaceType, fills the new Symbol members. A grouped field
  declaration (`x, y int`) yields one Field per name; an embedded field or
  interface yields an entry with an empty name.
- New helpers: typeSpecType (underlying type expr of a lone type spec),
  extractFields, extractIfaceMethods, fieldDoc (doc comment or trailing
  line comment), and nodeString — a non-truncating printer used for field
  types, tags, and method signatures, distinct from formatNode which keeps
  truncating to produce the one-line header.

internal/index (search):
- matches() now also tests the query against struct field names, field
  types, and struct tags, and against interface method names and
  signatures. A query like an env-var key or a method name now resolves to
  the type that declares it.

internal/tools:
- get_symbol and search_symbols descriptions updated to advertise the new
  struct-field and interface-method coverage. No input/output schema change
  beyond the additive Symbol fields, which get_symbol already returns whole.

internal/index (tests):
- New builder_test.go — the package previously had no tests. Builds a
  temporary module fixture and asserts capture of struct fields (with tags
  and docs), embedded fields, interface methods (with signatures and docs),
  embedded interfaces, and discovery of a struct by one of its struct tags
  (the failure mode that motivated the change).

Docs:
- CHANGELOG.md gains an [Unreleased] entry; README.md tool table updated to
  state that get_symbol returns struct fields and interface methods and
  that search_symbols matches fields, tags, and methods.

No new dependencies. The committed data/index.json placeholder is untouched
— the index is regenerated at image build (Dockerfile runs cmd/indexer),
so a deployment must be rebuilt to serve the richer index; a server still
running the prior image keeps serving the older, member-less one.
This commit is contained in:
2026-06-10 16:35:24 +00:00
parent e23e86b06c
commit 1586ed4d52
7 changed files with 328 additions and 15 deletions

View File

@@ -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 = <expr>`), 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+)`)