feat(mcp): derive env vars from the framework's real struct tags

Minor to v1.1.0. Make the whole environment-variable surface derive from the indexed component-config tags instead of a hand-maintained list that drifts. Also folds in the scaffold-symbol fixes staged as v1.0.1 (never tagged); the generated scaffold compiles clean against einherjar v1.0.0. internal/envspec (new): - Parse index struct tags into env vars {name, module, struct, field, required, default}. One source of truth: ParseTag, ForModule, FindStruct, All, KnownNames. internal/tools: - get_config_env: list the real env vars a component config reads (or all). - check_env: flag unknown EINHERJAR_* names, required vars missing for the composed modules, and dead vars (set for an uncomposed module). - get_scaffold: .env.example is now DERIVED from the index — required vars uncommented with a dev value, defaulted vars commented with their default. The scaffold now composes logz.Config (Log logz.Config) so EINHERJAR_LOG_* are live and documented, not hardcoded/ignored (log format is env-driven). - validate_snippet: inject the real env-var name set into the rules package. internal/index/builtins (wire conventions): - Route the incremental "compose a component later" flow to get_config_env / check_env; distinguish framework EINHERJAR_* from app-owned APP_* (JWT). - Compose logz.Config in the config + Run() examples, to match the scaffold. internal/rules: - config.unknown-env-var (twelfth rule): reject an env:"EINHERJAR_*" struct tag the framework doesn't declare. No-op until the server injects the name set, so it never fires on incomplete knowledge. Fixed (was v1.0.1): scaffold health hook + wire builtin used logz.Logger (real: contracts/logging.Logger) and postgres.Component (hooks take Provider); env tags were EINHERJAR_SERVER_ADDR / EINHERJAR_PG_DATABASE (real: _HOST/_PORT / _PG_NAME). Tests: envspec unit tests; env tools against the real data/index.json; the rule. Verified by generating the scaffold, building it against local einherjar v1.0.0 (exit 0), and runtime-loading the composed logz.Config (EINHERJAR_LOG_LEVEL=DEBUG -> slog.LevelDebug, EINHERJAR_LOG_JSON=true). Version bumped to v1.1.0 (badge + serverVersion). No dependency changes.
2026-08-07 16:58:24 -06:00
parent a0b803cb40
commit 8c6cf2c27a
14 changed files with 1003 additions and 50 deletions
@@ -0,0 +1,157 @@
+// 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
+}