From 9b2fb4a82caf191555ba01c3ffbcad90509c19a0 Mon Sep 17 00:00:00 2001 From: Sam Catlow Date: Tue, 15 Sep 2026 05:07:54 +1000 Subject: [PATCH] feat(configuration): report config keys no decode target consumed decodeTOML discarded toml.DecodeFile's metadata, so a misspelled or renamed key parsed, validated and silently did nothing. Document.UnknownKeys now carries the dotted key paths a loaded file's decode targets left undecoded. One file feeds two decode targets (&doc.Config and &doc.Scheduling), so a key legitimately owned by one shows up as undecoded in the other -- a key is only reported when both leave it undecoded (unknownKeys intersects the two sets), which is what keeps a valid [scheduling] block from being misreported as unknown on every config that uses it. YAML config sources are unchanged for now (no equivalent metadata hook in the yaml decoder); this covers the TOML path, which is what config.example.toml, every shipped deployments/*.toml profile, and install.sh's generated config.toml all use. --- .../infrastructure/configuration/decode.go | 38 ++++-- .../infrastructure/configuration/loader.go | 76 ++++++++++- .../configuration/scheduling.go | 14 +- .../configuration/unknown_keys_test.go | 127 ++++++++++++++++++ 4 files changed, 237 insertions(+), 18 deletions(-) create mode 100644 internal/infrastructure/configuration/unknown_keys_test.go diff --git a/internal/infrastructure/configuration/decode.go b/internal/infrastructure/configuration/decode.go index c0819bf36..79fd0b387 100644 --- a/internal/infrastructure/configuration/decode.go +++ b/internal/infrastructure/configuration/decode.go @@ -11,23 +11,43 @@ import ( "github.com/samcharles93/archie-core/internal/config" ) -func decodeConfigFile(path string, target any) error { +// decodeConfigFileKeys decodes path into target, dispatching on extension, +// additionally returning target's undecoded top-level keys for a TOML +// source (see decodeTOMLKeys). A YAML source has no equivalent hook yet +// (plan-config-drift.md step 1 note) and always reports none -- unchanged +// behaviour, not a claim of completeness. +func decodeConfigFileKeys(path string, target any) ([]string, error) { switch filepath.Ext(path) { case ".yaml", ".yml": - return decodeYAML(path, target) + return nil, decodeYAML(path, target) case ".toml": - return decodeTOML(path, target) + return decodeTOMLKeys(path, target) default: - return fmt.Errorf("%w: config file %s must end in .toml, .yaml, or .yml", ErrUnreadable, path) + return nil, fmt.Errorf("%w: config file %s must end in .toml, .yaml, or .yml", ErrUnreadable, path) } } -// decodeTOML decodes a TOML file into target. -func decodeTOML(path string, target any) error { - if _, err := toml.DecodeFile(path, target); err != nil { - return fmt.Errorf("%w: parsing %s: %w", ErrUnreadable, path, err) +// decodeTOMLKeys decodes a TOML file into target, additionally +// returning the top-level dotted key paths present in the file that +// target did not consume (toml.MetaData.Undecoded()). A single decode +// target's undecoded set is not by itself "unknown" -- see Hazard 1 in +// .local/issue-tracker/plan-config-drift.md, one file can legitimately +// feed more than one target -- callers combine this with the other +// target's undecoded set before treating anything as a real unknown key. +func decodeTOMLKeys(path string, target any) ([]string, error) { + meta, err := toml.DecodeFile(path, target) + if err != nil { + return nil, fmt.Errorf("%w: parsing %s: %w", ErrUnreadable, path, err) } - return nil + undecoded := meta.Undecoded() + if len(undecoded) == 0 { + return nil, nil + } + keys := make([]string, len(undecoded)) + for i, k := range undecoded { + keys[i] = k.String() + } + return keys, nil } // decodeYAML decodes a YAML file into target. diff --git a/internal/infrastructure/configuration/loader.go b/internal/infrastructure/configuration/loader.go index fbe6b1bfe..2ad08f4cb 100644 --- a/internal/infrastructure/configuration/loader.go +++ b/internal/infrastructure/configuration/loader.go @@ -5,6 +5,7 @@ import ( "log/slog" "os" "path/filepath" + "sort" "github.com/samcharles93/archie-core/internal/config" ) @@ -25,6 +26,15 @@ type Document struct { // Provenance lists the files that produced Config, in precedence order. Provenance Provenance + + // UnknownKeys lists dotted TOML key paths present in a loaded file that + // no decode target consumed (e.g. "containers.max_concurrancy" for a + // misspelled max_concurrency) -- present so a typo'd key is visible + // instead of silently parsing, validating and doing nothing. Sorted + // and de-duplicated. A missing key that a YAML config source carries + // is not yet detected here (plan-config-drift.md step 1 note); this + // is TOML-only for now. + UnknownKeys []string } // Loader reads configuration from files. The zero value is not usable; call @@ -151,27 +161,74 @@ func (l *Loader) ApplyOverlay(doc *Document, overrides map[string]any) (*Documen func (l *Loader) overlayFile(basePath, overlayPath string) (*Document, error) { doc := &Document{} - if err := decodeConfigFile(basePath, &doc.Config); err != nil { + cfgKeys, err := decodeConfigFileKeys(basePath, &doc.Config) + if err != nil { return nil, err } - if err := decodeSchedulingFile(basePath, &doc.Scheduling); err != nil { + schedKeys, err := decodeSchedulingFileKeys(basePath, &doc.Scheduling) + if err != nil { return nil, err } + doc.UnknownKeys = append(doc.UnknownKeys, unknownKeys(cfgKeys, schedKeys)...) doc.Provenance.record(Origin{Path: basePath, Role: RoleMain, Layer: LayerBase}) if overlayPath != "" { - if err := decodeConfigFile(overlayPath, &doc.Config); err != nil { + cfgKeys, err = decodeConfigFileKeys(overlayPath, &doc.Config) + if err != nil { return nil, err } - if err := decodeSchedulingFile(overlayPath, &doc.Scheduling); err != nil { + schedKeys, err = decodeSchedulingFileKeys(overlayPath, &doc.Scheduling) + if err != nil { return nil, err } + doc.UnknownKeys = append(doc.UnknownKeys, unknownKeys(cfgKeys, schedKeys)...) doc.Provenance.record(Origin{Path: overlayPath, Role: RoleMain, Layer: LayerOverlay}) } return l.finalize(doc) } +// unknownKeys returns the keys present in both a and b: one config file +// feeds more than one decode target (&doc.Config and &doc.Scheduling), so +// a key legitimately owned by one target decodes cleanly there and only +// shows up in the other target's undecoded set. Only a key neither target +// consumed is a real unknown key (Hazard 1, plan-config-drift.md). +func unknownKeys(a, b []string) []string { + if len(a) == 0 || len(b) == 0 { + return nil + } + inB := make(map[string]bool, len(b)) + for _, k := range b { + inB[k] = true + } + var out []string + for _, k := range a { + if inB[k] { + out = append(out, k) + } + } + return out +} + +// sortedUnique returns keys sorted and de-duplicated, so Document.UnknownKeys +// is deterministic across a base+overlay load that happens to name the same +// stray key in both files. +func sortedUnique(keys []string) []string { + if len(keys) == 0 { + return nil + } + seen := make(map[string]bool, len(keys)) + out := make([]string, 0, len(keys)) + for _, k := range keys { + if !seen[k] { + seen[k] = true + out = append(out, k) + } + } + sort.Strings(out) + return out +} + // Dir loads configuration from a directory tree: // // config.yaml daemon-level settings @@ -249,16 +306,23 @@ func (l *Loader) decodeMain(doc *Document, path string, isYAMLFile bool) error { } return decodeSchedulingFile(path, &doc.Scheduling) } - if err := decodeTOML(path, &doc.Config); err != nil { + cfgKeys, err := decodeTOMLKeys(path, &doc.Config) + if err != nil { return err } - return decodeSchedulingFile(path, &doc.Scheduling) + schedKeys, err := decodeSchedulingFileKeys(path, &doc.Scheduling) + if err != nil { + return err + } + doc.UnknownKeys = append(doc.UnknownKeys, unknownKeys(cfgKeys, schedKeys)...) + return nil } // finalize applies defaults, then validates. The order matters: validation // judges the effective configuration, including values the operator never // wrote. func (l *Loader) finalize(doc *Document) (*Document, error) { + doc.UnknownKeys = sortedUnique(doc.UnknownKeys) l.applyDefaults(&doc.Config) if err := Validate(&doc.Config); err != nil { return nil, err diff --git a/internal/infrastructure/configuration/scheduling.go b/internal/infrastructure/configuration/scheduling.go index 64a4347c8..0ae9b8de5 100644 --- a/internal/infrastructure/configuration/scheduling.go +++ b/internal/infrastructure/configuration/scheduling.go @@ -41,12 +41,20 @@ type schedulingDocument struct { } func decodeSchedulingFile(path string, target *SchedulingInput) error { + _, err := decodeSchedulingFileKeys(path, target) + return err +} + +// decodeSchedulingFileKeys is decodeSchedulingFile plus the file's +// undecoded top-level keys under this target (see decodeConfigFileKeys). +func decodeSchedulingFileKeys(path string, target *SchedulingInput) ([]string, error) { doc := schedulingDocument{Scheduling: *target} - if err := decodeConfigFile(path, &doc); err != nil { - return err + keys, err := decodeConfigFileKeys(path, &doc) + if err != nil { + return nil, err } *target = doc.Scheduling - return nil + return keys, nil } func applySchedulingOverlay(target *SchedulingInput, overrides map[string]any) error { diff --git a/internal/infrastructure/configuration/unknown_keys_test.go b/internal/infrastructure/configuration/unknown_keys_test.go new file mode 100644 index 000000000..f61bf24ac --- /dev/null +++ b/internal/infrastructure/configuration/unknown_keys_test.go @@ -0,0 +1,127 @@ +package configuration + +import ( + "os" + "path/filepath" + "testing" +) + +// minimalValidConfigTOML is enough to pass Validate on its own, so these tests +// isolate the unknown-key behaviour from unrelated validation failures. +const minimalValidConfigTOML = "bot_user = \"widget\"\nwork_dir = \"/base/work\"\n" + + "[agent]\nmode = \"inprocess\"\n" + +// TestUnknownKeysAreReported pins plan-config-drift.md step 1: a +// misspelled key must not parse, validate and silently do nothing. Today +// (before the fix) it loads with zero indication anything was ignored. +func TestUnknownKeysAreReported(t *testing.T) { + path := filepath.Join(t.TempDir(), "config.toml") + src := minimalValidConfigTOML + "[containers]\nmax_concurrancy = 4\n" // typo: concurrancy + if err := os.WriteFile(path, []byte(src), 0o600); err != nil { + t.Fatal(err) + } + + doc, err := New(nil).File(path) + if err != nil { + t.Fatalf("File: %v (an unknown key must not fail the load)", err) + } + if len(doc.UnknownKeys) == 0 { + t.Fatal("UnknownKeys is empty, want the typo'd key reported") + } + found := false + for _, k := range doc.UnknownKeys { + if k == "containers.max_concurrancy" { + found = true + } + } + if !found { + t.Errorf("UnknownKeys = %v, want it to contain %q", doc.UnknownKeys, "containers.max_concurrancy") + } +} + +// TestValidSchedulingBlockIsNotReportedAsUnknown pins Hazard 1 from +// plan-config-drift.md: one file feeds both &doc.Config and +// &doc.Scheduling. Reporting either target's Undecoded() verbatim would +// flag every config carrying a real [scheduling] block, since Config has +// no "scheduling" field and SchedulingInput has nothing else. +func TestValidSchedulingBlockIsNotReportedAsUnknown(t *testing.T) { + path := filepath.Join(t.TempDir(), "config.toml") + src := minimalValidConfigTOML + "[scheduling]\ninterval = \"60s\"\nmax_parallel = 4\n" + if err := os.WriteFile(path, []byte(src), 0o600); err != nil { + t.Fatal(err) + } + + doc, err := New(nil).File(path) + if err != nil { + t.Fatal(err) + } + if len(doc.UnknownKeys) != 0 { + t.Errorf("UnknownKeys = %v, want none: a valid [scheduling] block is not an unknown key", doc.UnknownKeys) + } + if doc.Scheduling.MaxParallel != 4 { + t.Errorf("Scheduling.MaxParallel = %d, want 4 (scheduling must still decode correctly)", doc.Scheduling.MaxParallel) + } +} + +// TestUnknownSchedulingKeyIsStillReported is the mirror of the Hazard 1 +// test: a typo inside [scheduling] must not be masked by the intersection +// logic that protects legitimate cross-target keys. +func TestUnknownSchedulingKeyIsStillReported(t *testing.T) { + path := filepath.Join(t.TempDir(), "config.toml") + src := minimalValidConfigTOML + "[scheduling]\nmax_parallell = 4\n" // typo: extra "l" + if err := os.WriteFile(path, []byte(src), 0o600); err != nil { + t.Fatal(err) + } + + doc, err := New(nil).File(path) + if err != nil { + t.Fatal(err) + } + found := false + for _, k := range doc.UnknownKeys { + if k == "scheduling.max_parallell" { + found = true + } + } + if !found { + t.Errorf("UnknownKeys = %v, want it to contain %q", doc.UnknownKeys, "scheduling.max_parallell") + } +} + +// TestExampleConfigHasNoUnknownKeys is the contract test the design +// promised: the checked-in template must never itself trip the detector. +func TestExampleConfigHasNoUnknownKeys(t *testing.T) { + doc, err := New(nil).File(filepath.Join("..", "..", "..", "config.example.toml")) + if err != nil { + t.Fatal(err) + } + if len(doc.UnknownKeys) != 0 { + t.Errorf("config.example.toml has unknown keys: %v", doc.UnknownKeys) + } +} + +// TestDeploymentOverlaysHaveNoUnknownKeys covers every shipped overlay +// profile the same way, loaded as they are in production: layered over +// config.example.toml via -config-overlay. +func TestDeploymentOverlaysHaveNoUnknownKeys(t *testing.T) { + base := filepath.Join("..", "..", "..", "config.example.toml") + dir := filepath.Join("..", "..", "..", "deployments") + entries, err := os.ReadDir(dir) + if err != nil { + t.Fatal(err) + } + for _, e := range entries { + if filepath.Ext(e.Name()) != ".toml" { + continue + } + t.Run(e.Name(), func(t *testing.T) { + doc, err := New(nil).Overlay(base, filepath.Join(dir, e.Name())) + if err != nil { + t.Fatal(err) + } + if len(doc.UnknownKeys) != 0 { + t.Errorf("%s has unknown keys: %v", e.Name(), doc.UnknownKeys) + } + }) + } +}