fix(configio,codec): record export locale and refuse cross-locale silent label remap (#20)

Two changes that compose to close issue #4's silent-data-loss path:

1. enumNum no longer returns 0 when a compound sub-field's enum label
   can't be resolved. It returns an error and encodeVar / EncodeCompound
   propagate up to the user. This matches the loud behaviour
   resolveEnumWriteValue already had for top-level ENUMs and removes
   the case where a YAML label translated to a different locale
   silently writes the zero entry (SOGLIA Tipo flipping MINIMA↔MASSIMA
   was the worked example).

2. Export records `device.locale` in the YAML header. Import / diff /
   validate read it back through a small reconcileLocale helper:

     * file has no locale (legacy) → CLI default unchanged;
     * file has locale, user didn't pass --locale → adopt file's;
     * file has locale, user passed matching --locale → use it;
     * file has locale, user passed different --locale → return
       LocaleMismatchError unless --force-locale is set.

This keeps YAML files readable in the locale they were produced under
while making cross-locale round-trips a loud, opt-in event rather
than a silent corruption. The error names both locales and points
at --force-locale so the operator can either drop --locale (adopting
the file's) or keep theirs explicitly.

Closes #4

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: ale-rinaldi

cmd/mythy/diff.go

@@ -26,6 +26,7 @@ func newDiffCmd(cf *catalogFlags) *cobra.Command {
 	var format string
 	var noProgress bool
 	var includeAll bool
+	var forceLocale bool
 
 	cmd := &cobra.Command{
 		Use:   "diff <file>",
@@ -41,6 +42,9 @@ func newDiffCmd(cf *catalogFlags) *cobra.Command {
 			if err != nil {
 				return err
 			}
+			if err := reconcileLocale(cmd, parsed.Device.Locale, cf, forceLocale); err != nil {
+				return err
+			}
 			s, err := conn.build(ctx, cf)
 			if err != nil {
 				return err
@@ -72,6 +76,7 @@ func newDiffCmd(cf *catalogFlags) *cobra.Command {
 	cmd.Flags().BoolVar(&noProgress, "no-progress", false, "suppress the progress indicator (auto-suppressed when stderr isn't a TTY)")
 	cmd.Flags().BoolVar(&includeAll, "all", false,
 		"include runtime/state items (READONLY=YES, paths under Read/) — defaults to filtered to surface only configuration drift")
+	cmd.Flags().BoolVar(&forceLocale, "force-locale", false, "proceed even if --locale differs from the YAML's device.locale")
 	return cmd
 }
 

cmd/mythy/export.go

@@ -38,7 +38,8 @@ func newExportCmd(cf *catalogFlags) *cobra.Command {
 				includeSkip = true
 			}
 			b, err := configio.Export(ctx, s, configio.ExportOptions{
-				Scope: scope,
+				Scope:  scope,
+				Locale: cf.locale,
 				Filter: session.ExportFilter{
 					IncludeHidden:   includeHidden,
 					IncludeReadOnly: includeReadOnly,

cmd/mythy/import.go

@@ -13,7 +13,7 @@ import (
 
 func newImportCmd(cf *catalogFlags) *cobra.Command {
 	var conn connFlags
-	var dryRun, force, noProgress bool
+	var dryRun, force, noProgress, forceLocale bool
 	var includeSkip, includeHidden, includeAll, yesIUnderstand bool
 	var format string
 
@@ -31,6 +31,9 @@ func newImportCmd(cf *catalogFlags) *cobra.Command {
 			if err != nil {
 				return err
 			}
+			if err := reconcileLocale(cmd, parsed.Device.Locale, cf, forceLocale); err != nil {
+				return err
+			}
 			s, err := conn.build(ctx, cf)
 			if err != nil {
 				return err
@@ -105,6 +108,7 @@ func newImportCmd(cf *catalogFlags) *cobra.Command {
 	cmd.Flags().BoolVar(&includeHidden, "include-hidden", false, "allow writes to VISIBILITY=3 keys (Administrator subtree)")
 	cmd.Flags().BoolVar(&includeAll, "all", false, "shorthand for --include-skip --include-hidden")
 	cmd.Flags().BoolVar(&yesIUnderstand, "yes-i-understand", false, "confirm intent when an --include-* flag is set")
+	cmd.Flags().BoolVar(&forceLocale, "force-locale", false, "proceed even if --locale differs from the YAML's device.locale")
 	cmd.Flags().StringVar(&format, "format", "", "human|json|yaml (default: from MYTHY_FORMAT)")
 	return cmd
 }

cmd/mythy/locale_compat.go

@@ -0,0 +1,41 @@
+package main
+
+import (
+	"github.com/gridsociety/mythy/pkg/configio"
+	"github.com/spf13/cobra"
+)
+
+// reconcileLocale picks the effective --locale for a command that
+// consumes a YAML file (import / diff / validate). The decision is:
+//
+//   - no locale in YAML (legacy export): keep cf.locale unchanged.
+//   - locale in YAML, user didn't pass --locale explicitly: adopt
+//     the YAML's locale into cf.locale.
+//   - locale in YAML, user passed --locale matching: keep cf.locale.
+//   - locale in YAML, user passed --locale differing: return a typed
+//     LocaleMismatchError unless --force-locale is set.
+//
+// The flag-was-passed check uses cobra's Changed(): the locale flag
+// defaults to "en" (or MYTHY_LOCALE), and we want to distinguish "user
+// typed --locale=en" from "user typed nothing and en is the default".
+// "Changed" reports true only for explicit invocation.
+//
+// Reconciliation mutates cf.locale in place. Callers can rely on
+// cf.load() / connFlags.build() using the resolved value transparently.
+func reconcileLocale(cmd *cobra.Command, fileLocale string, cf *catalogFlags, forceLocale bool) error {
+	if fileLocale == "" {
+		return nil
+	}
+	explicit := cmd.Flags().Changed("locale")
+	if !explicit {
+		cf.locale = fileLocale
+		return nil
+	}
+	if cf.locale == fileLocale {
+		return nil
+	}
+	if forceLocale {
+		return nil
+	}
+	return &configio.LocaleMismatchError{FromFile: fileLocale, FromCLI: cf.locale}
+}

cmd/mythy/locale_compat_test.go

@@ -0,0 +1,77 @@
+package main
+
+import (
+	"errors"
+	"testing"
+
+	"github.com/gridsociety/mythy/pkg/configio"
+	"github.com/spf13/cobra"
+)
+
+// mkLocaleCmd sets up a minimal cobra.Command + catalogFlags with a
+// --locale flag wired exactly as the real subcommands do (default
+// "en", env MYTHY_LOCALE). args provides the CLI tokens after the
+// command name; pass nothing for "user did not specify --locale".
+func mkLocaleCmd(t *testing.T, args ...string) (*cobra.Command, *catalogFlags) {
+	t.Helper()
+	cf := &catalogFlags{}
+	cmd := &cobra.Command{Use: "x", RunE: func(*cobra.Command, []string) error { return nil }}
+	cmd.PersistentFlags().StringVar(&cf.locale, "locale", "en", "")
+	cmd.SetArgs(args)
+	if err := cmd.ParseFlags(args); err != nil {
+		t.Fatalf("ParseFlags: %v", err)
+	}
+	return cmd, cf
+}
+
+func TestReconcileLocaleLegacyFile(t *testing.T) {
+	cmd, cf := mkLocaleCmd(t)
+	if err := reconcileLocale(cmd, "", cf, false); err != nil {
+		t.Errorf("legacy export (no locale in file): err = %v, want nil", err)
+	}
+	if cf.locale != "en" {
+		t.Errorf("legacy export: cf.locale = %q, want unchanged 'en'", cf.locale)
+	}
+}
+
+func TestReconcileLocaleAdoptsFileLocaleWhenCLIImplicit(t *testing.T) {
+	cmd, cf := mkLocaleCmd(t)
+	if err := reconcileLocale(cmd, "it", cf, false); err != nil {
+		t.Errorf("err = %v, want nil", err)
+	}
+	if cf.locale != "it" {
+		t.Errorf("cf.locale = %q, want 'it' (adopted from file)", cf.locale)
+	}
+}
+
+func TestReconcileLocaleKeepsCLIWhenMatching(t *testing.T) {
+	cmd, cf := mkLocaleCmd(t, "--locale", "it")
+	if err := reconcileLocale(cmd, "it", cf, false); err != nil {
+		t.Errorf("err = %v, want nil", err)
+	}
+	if cf.locale != "it" {
+		t.Errorf("cf.locale = %q, want 'it'", cf.locale)
+	}
+}
+
+func TestReconcileLocaleErrorsOnExplicitMismatch(t *testing.T) {
+	cmd, cf := mkLocaleCmd(t, "--locale", "us")
+	err := reconcileLocale(cmd, "it", cf, false)
+	var lm *configio.LocaleMismatchError
+	if !errors.As(err, &lm) {
+		t.Fatalf("err = %v, want LocaleMismatchError", err)
+	}
+	if lm.FromFile != "it" || lm.FromCLI != "us" {
+		t.Errorf("error fields = %+v, want FromFile=it FromCLI=us", lm)
+	}
+}
+
+func TestReconcileLocaleForceLocaleBypassesMismatch(t *testing.T) {
+	cmd, cf := mkLocaleCmd(t, "--locale", "us")
+	if err := reconcileLocale(cmd, "it", cf, true); err != nil {
+		t.Errorf("--force-locale should bypass mismatch: err = %v", err)
+	}
+	if cf.locale != "us" {
+		t.Errorf("--force-locale must keep CLI value: cf.locale = %q, want 'us'", cf.locale)
+	}
+}

cmd/mythy/validate.go

@@ -21,26 +21,32 @@ type configFile struct {
 
 type configDevice struct {
 	Product string `yaml:"product"`
+	Locale  string `yaml:"locale"`
 }
 
 func newValidateCmd(cf *catalogFlags) *cobra.Command {
-	return &cobra.Command{
+	var forceLocale bool
+	cmd := &cobra.Command{
 		Use:   "validate <file>",
 		Short: "Validate a config YAML against the device's catalog (no connection)",
 		Args:  cobra.ExactArgs(1),
 		RunE: func(cmd *cobra.Command, args []string) error {
-			tpl, entry, err := cf.load()
-			if err != nil {
-				return err
-			}
 			data, err := os.ReadFile(args[0])
 			if err != nil {
 				return fmt.Errorf("read %s: %w", args[0], err)
 			}
-			var cfg configFile
-			if err := yaml.Unmarshal(data, &cfg); err != nil {
+			var cfgPeek configFile
+			if err := yaml.Unmarshal(data, &cfgPeek); err != nil {
 				return fmt.Errorf("parse YAML: %w", err)
 			}
+			if err := reconcileLocale(cmd, cfgPeek.Device.Locale, cf, forceLocale); err != nil {
+				return err
+			}
+			tpl, entry, err := cf.load()
+			if err != nil {
+				return err
+			}
+			cfg := cfgPeek
 			if cfg.MythyVersion != 1 {
 				return fmt.Errorf("unsupported mythy_version %d", cfg.MythyVersion)
 			}
@@ -72,4 +78,6 @@ func newValidateCmd(cf *catalogFlags) *cobra.Command {
 			return nil
 		},
 	}
+	cmd.Flags().BoolVar(&forceLocale, "force-locale", false, "proceed even if --locale differs from the YAML's device.locale")
+	return cmd
 }

pkg/codec/compound.go

@@ -157,9 +157,17 @@ func encodeVar(v catalog.ClassVar, val any, width int) ([]uint16, error) {
 		s, _ := val.(string)
 		return encodeStringChars(s, width), nil
 	case "ENUM", "ENUM_BYTE", "ENUM_WORD":
-		return []uint16{uint16(enumNum(val, v) & 0xFFFF)}, nil
+		n, err := enumNum(val, v)
+		if err != nil {
+			return nil, err
+		}
+		return []uint16{uint16(n & 0xFFFF)}, nil
 	case "ENUM_LONG":
-		u := uint64(enumNum(val, v))
+		n, err := enumNum(val, v)
+		if err != nil {
+			return nil, err
+		}
+		u := uint64(n)
 		return []uint16{uint16(u & 0xFFFF), uint16((u >> 16) & 0xFFFF)}, nil
 	}
 	return nil, fmt.Errorf("encodeVar: unknown TIPO %q", v.Tipo)
@@ -189,26 +197,32 @@ func toUint64(v any) uint64 {
 	return 0
 }
 
-func enumNum(val any, v catalog.ClassVar) int {
+// enumNum resolves a sub-field value to the integer wire encoding for
+// an ENUM family VAR. Strings are looked up against v.InlineEnum (the
+// per-VAR <RANGE> declarations); integers pass through. An
+// unresolvable string label returns an error rather than silently
+// defaulting to 0 — quietly zeroing on a typo, a locale-translated
+// label, or any other miss was the silent-data-loss path tracked in
+// issue #4.
+func enumNum(val any, v catalog.ClassVar) (int, error) {
 	switch x := val.(type) {
 	case string:
-		if v.InlineEnum != nil {
-			if n, err := v.InlineEnum.ValueFor(x); err == nil {
-				return n
-			}
+		if v.InlineEnum == nil {
+			return 0, fmt.Errorf("VAR %s has no inline enum to resolve label %q", v.Name, x)
 		}
-		return 0
+		n, err := v.InlineEnum.ValueFor(x)
+		if err != nil {
+			return 0, fmt.Errorf("VAR %s: %w", v.Name, err)
+		}
+		return n, nil
 	case int:
-		// YAML decoders typically produce `int` for small integers; the
-		// previous version of this switch only knew int64/uint64, so an
-		// integer enum value silently became 0.
-		return x
+		return x, nil
 	case int64:
-		return int(x)
+		return int(x), nil
 	case uint64:
-		return int(x)
+		return int(x), nil
 	}
-	return 0
+	return 0, fmt.Errorf("VAR %s: unsupported enum value type %T", v.Name, val)
 }
 
 // encodeStringChars encodes a string as `width` registers of NUL-padded

pkg/codec/compound_test.go

@@ -3,6 +3,7 @@ package codec_test
 import (
 	"path/filepath"
 	"reflect"
+	"strings"
 	"testing"
 
 	"github.com/gridsociety/mythy/pkg/catalog"
@@ -177,6 +178,42 @@ func TestEncodeCompoundHandlesEnumWord(t *testing.T) {
 	}
 }
 
+func TestEncodeCompoundErrorsOnUnresolvableEnumLabel(t *testing.T) {
+	// Issue #4: silently-zeroed enum labels (e.g. an Italian label
+	// landing in a US-locale template) corrupted compound writes
+	// without any error. enumNum now surfaces the failure; encodeVar
+	// propagates it; EncodeCompound returns it to the caller.
+	cls := &catalog.Class{
+		Name: "SOGLIA_T",
+		Dim:  3,
+		Vars: []catalog.ClassVar{
+			{
+				Name: "Tipo",
+				Tipo: "ENUM",
+				InlineEnum: &catalog.Enum{
+					Name: "TipoInline",
+					Entries: []catalog.EnumEntry{
+						{Value: 0, Label: "Minimum"},
+						{Value: 1, Label: "Maximum"},
+					},
+				},
+			},
+			{Name: "Pad", Tipo: "UWORD"},
+		},
+	}
+	in := map[string]any{"Tipo": "SOGLIA MASSIMA", "Pad": uint64(0)}
+	_, err := codec.EncodeCompound(in, cls, nil, nil)
+	if err == nil {
+		t.Fatal("expected error for unresolvable enum label, got nil")
+	}
+	if !strings.Contains(err.Error(), "Tipo") {
+		t.Errorf("error should name the offending VAR: %v", err)
+	}
+	if !strings.Contains(err.Error(), "SOGLIA MASSIMA") {
+		t.Errorf("error should quote the unresolved label: %v", err)
+	}
+}
+
 func TestEncodeCompoundHandlesINT(t *testing.T) {
 	// Issue #10: legacy SIF/SVF templates use TIPO="INT" for 16-bit
 	// signed integers. SIF5600.IdentificationResponse declares dim=5

pkg/configio/export.go

@@ -16,6 +16,12 @@ type ExportOptions struct {
 	Scope  string               // empty = whole device
 	Filter session.ExportFilter // READONLY/hidden defaults; SKIP always excluded
 
+	// Locale is recorded into device.locale in the YAML so import /
+	// diff / validate can detect cross-locale round-trips that would
+	// otherwise silently remap enum labels to zero. Empty means "don't
+	// record" (legacy behaviour); the CLI always passes a value.
+	Locale string
+
 	// Progress, when non-nil, is invoked once before each catalog leaf
 	// is read, and once more at the end with done == total and name == "".
 	// Use the final call to clear any in-progress UI. The full-device
@@ -106,6 +112,7 @@ func Export(ctx context.Context, s *session.Session, opts ExportOptions) ([]byte
 		Product:        s.Entry().Product,
 		Identification: s.Entry().Identification,
 		ExportedAt:     time.Now().Format(time.RFC3339),
+		Locale:         opts.Locale,
 	}
 	if id := s.Ident(); id != nil {
 		dev.Identification = int(id.Identification)