mcp/internal/envspec/envspec.go

// Package envspec derives the real environment variables of Einherjar's
// component configs from the framework index — the single source of truth for
// which EINHERJAR_* vars exist, which are required, and what they default to.
//
// Every Einherjar component (db-postgres, web/server, core/logz, …) exposes a
// Config struct whose fields carry caarlos0/env tags. The indexer already
// captures those tags (index.Field.Tag); this package parses them so tools can
// build a correct global config, generate an accurate .env.example, and reject
// invented or misspelled var names — instead of anyone maintaining that list by
// hand and drifting from the framework.
package envspec

import (
	"reflect"
	"sort"
	"strings"

	"code.nochebuena.dev/einherjar/mcp/internal/index"
)

// Var is one environment variable declared by a component Config field.
type Var struct {
	Name       string `json:"name"`                 // e.g. EINHERJAR_PG_HOST
	Module     string `json:"module"`               // e.g. db-postgres
	SubPackage string `json:"subPackage,omitempty"` // e.g. server (empty at module root)
	Struct     string `json:"struct"`               // the declaring struct, e.g. Config
	Field      string `json:"field"`                // the Go field, e.g. Host
	Type       string `json:"type"`                 // the Go type, e.g. string
	Required   bool   `json:"required"`             // env:"...,required"
	Default    string `json:"default,omitempty"`    // envDefault:"..." (empty when none)
	HasDefault bool   `json:"hasDefault"`           // distinguishes "" default from no default
	Doc        string `json:"doc,omitempty"`        // field doc comment, if any
}

// ParseTag extracts the env var declared by a raw struct tag (backticks already
// stripped, as stored in the index). ok is false when the tag has no env key or
// the key is "-" (explicitly excluded, e.g. an http.RoundTripper field).
func ParseTag(tag string) (v struct {
	Name       string
	Required   bool
	Default    string
	HasDefault bool
}, ok bool) {
	st := reflect.StructTag(tag)
	raw, present := st.Lookup("env")
	if !present {
		return v, false
	}
	parts := strings.Split(raw, ",")
	name := strings.TrimSpace(parts[0])
	if name == "" || name == "-" {
		return v, false
	}
	v.Name = name
	for _, opt := range parts[1:] {
		if strings.TrimSpace(opt) == "required" {
			v.Required = true
		}
	}
	if def, has := st.Lookup("envDefault"); has {
		v.Default = def
		v.HasDefault = true
	}
	ok = true
	return v, ok
}

// varsForSymbol returns the env vars declared directly by a struct symbol's
// fields. Nested component-config fields (a field whose type is another Config,
// carrying no env tag of its own) are not expanded here — caller-facing helpers
// surface them because sibling structs are indexed independently.
func varsForSymbol(m index.Module, s index.Symbol) []Var {
	var out []Var
	for _, f := range s.Fields {
		parsed, ok := ParseTag(f.Tag)
		if !ok {
			continue
		}
		out = append(out, Var{
			Name:       parsed.Name,
			Module:     m.Name,
			SubPackage: s.SubPackage,
			Struct:     s.Name,
			Field:      f.Name,
			Type:       f.Type,
			Required:   parsed.Required,
			Default:    parsed.Default,
			HasDefault: parsed.HasDefault,
			Doc:        strings.TrimSpace(f.Doc),
		})
	}
	return out
}

// ForModule returns every env var declared by any struct in a module, across
// all its sub-packages (e.g. web yields web/server's EINHERJAR_SERVER_* plus
// web's EINHERJAR_SERVER_CORS_ORIGINS plus web/health's timeout). Returns nil
// when the module is unknown. Order is deterministic: sub-package, then struct,
// then declaration order.
func ForModule(idx *index.Index, module string) []Var {
	m := idx.FindModule(module)
	if m == nil {
		return nil
	}
	var out []Var
	for _, s := range m.Symbols {
		if s.Kind != "type" || len(s.Fields) == 0 {
			continue
		}
		out = append(out, varsForSymbol(*m, s)...)
	}
	return out
}

// FindStruct returns the env vars of one specific struct, identified by module,
// sub-package (empty for a module-root package), and struct name — the precise
// selector a scaffold uses to compose named component configs. Returns nil when
// no such struct is indexed.
func FindStruct(idx *index.Index, module, subPackage, name string) []Var {
	m := idx.FindModule(module)
	if m == nil {
		return nil
	}
	for _, s := range m.Symbols {
		if s.Kind == "type" && s.Name == name && s.SubPackage == subPackage {
			return varsForSymbol(*m, s)
		}
	}
	return nil
}

// All returns every env var declared anywhere in the framework, sorted by name.
func All(idx *index.Index) []Var {
	var out []Var
	for i := range idx.Modules {
		m := idx.Modules[i]
		for _, s := range m.Symbols {
			if s.Kind != "type" || len(s.Fields) == 0 {
				continue
			}
			out = append(out, varsForSymbol(m, s)...)
		}
	}
	sort.Slice(out, func(i, j int) bool { return out[i].Name < out[j].Name })
	return out
}

// KnownNames returns the set of every valid framework env-var name. It backs the
// config.unknown-env-var rule, which rejects any EINHERJAR_* tag that is not in
// this set (the exact bug class that shipped EINHERJAR_PG_DATABASE / _SERVER_ADDR).
func KnownNames(idx *index.Index) map[string]struct{} {
	names := map[string]struct{}{}
	for _, v := range All(idx) {
		names[v.Name] = struct{}{}
	}
	return names
}