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.
This commit is contained in:
sam committed 2026-09-15 05:07:54 +10:00
1 parent 9942ac4487
commit 9b2fb4a82c
4 files changed
+237 -18

No files matched your search

@@ -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.
@@ -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
@@ -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 {
@@ -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)
}
})
}
}