diff --git a/.nextchanges/air/unknown-config-field-errors.md b/.nextchanges/air/unknown-config-field-errors.md new file mode 100644 index 00000000000..af6cc2773bd --- /dev/null +++ b/.nextchanges/air/unknown-config-field-errors.md @@ -0,0 +1 @@ +* `air run` now names the YAML path of an unknown config field, suggests the closest field, and notes when a field may need a newer CLI. ([#7528](https://github.com/databricks/cli/pull/7528)) diff --git a/cmd/air/runconfig.go b/cmd/air/runconfig.go index 4bd8cf00bae..b66d704a4af 100644 --- a/cmd/air/runconfig.go +++ b/cmd/air/runconfig.go @@ -643,6 +643,8 @@ type configField struct { // freeForm marks a user-keyed map (parameters/secrets/env_variables): no // children, yet any sub-path into it is valid. freeForm bool + // isList marks a list field, whose YAML items each match children. + isList bool children []configField // nil for a leaf } @@ -725,15 +727,7 @@ func cutLast(s, sep string) (before, after string, found bool) { // unknownConfigFieldError reports an unresolvable segment, naming the valid // siblings and, when one is close enough, a suggestion. func unknownConfigFieldError(parent configField, part string, matched []string) error { - names := make([]string, 0, len(parent.children)) - for _, c := range parent.children { - if c.hidden { - continue - } - names = append(names, configLeafName(c.path)) - } - slices.Sort(names) - + names := visibleConfigChildNames(parent) msg := fmt.Sprintf("unknown config field %q", configHelpRoot+"."+strings.Join(matched, ".")) if suggestion, ok := closestConfigField(part, names); ok { msg += fmt.Sprintf("; did you mean %q?", suggestion) @@ -741,6 +735,18 @@ func unknownConfigFieldError(parent configField, part string, matched []string) return fmt.Errorf("%s\n\nfields under %q are: %s", msg, parent.path, strings.Join(names, ", ")) } +// visibleConfigChildNames returns the sorted YAML names of parent's documented children. +func visibleConfigChildNames(parent configField) []string { + names := make([]string, 0, len(parent.children)) + for _, c := range parent.children { + if !c.hidden { + names = append(names, configLeafName(c.path)) + } + } + slices.Sort(names) + return names +} + // closestConfigField returns the nearest candidate by edit distance, if one is // close enough to be worth suggesting. func closestConfigField(name string, candidates []string) (string, bool) { @@ -798,6 +804,10 @@ func describeStruct(t reflect.Type, prefix string) []configField { continue } + elem := f.Type + for elem.Kind() == reflect.Pointer { + elem = elem.Elem() + } field := configField{ path: prefix + "." + name, typeName: configTypeName(f.Type), @@ -805,6 +815,7 @@ func describeStruct(t reflect.Type, prefix string) []configField { help: f.Tag.Get("help"), hidden: f.Tag.Get("hidden") == "yes", freeForm: freeFormConfigFields[name], + isList: elem.Kind() == reflect.Slice, } if nested := underlyingConfigStruct(f.Type); nested != nil && !field.freeForm { field.children = describeStruct(nested, field.path) diff --git a/cmd/air/runconfig_load.go b/cmd/air/runconfig_load.go index 2e05e1b50e6..2f32170214e 100644 --- a/cmd/air/runconfig_load.go +++ b/cmd/air/runconfig_load.go @@ -12,6 +12,7 @@ import ( "strings" "sync" + "github.com/databricks/cli/internal/build" "go.yaml.in/yaml/v3" ) @@ -98,6 +99,9 @@ func readRunConfigDocument(path string) (*yaml.Node, []byte, error) { } func finishRunConfigLoad(path string, document *yaml.Node, validationYAML []byte) (*runConfig, error) { + if err := checkUnknownConfigFields(path, document); err != nil { + return nil, err + } // Validate before stripping comments so YAML errors retain source line numbers. cfg, err := decodeRunConfigReader(bytes.NewReader(validationYAML), path) if err != nil { @@ -125,6 +129,117 @@ func finishRunConfigLoad(path string, document *yaml.Node, validationYAML []byte return cfg, nil } +// unknownConfigKey is a YAML key absent from the run config schema. +type unknownConfigKey struct { + line int + key string + parent configField +} + +// checkUnknownConfigFields reports every YAML key missing from the run config +// schema by its YAML path, so users see the field they wrote rather than the +// strict decoder's Go type names. +func checkUnknownConfigFields(path string, document *yaml.Node) error { + msg := describeUnknownConfigKeys(collectUnknownConfigKeys(document.Content[0], configSchema(), nil), true) + if msg == "" { + return nil + } + return fmt.Errorf("invalid config %s: %s", path, msg) +} + +// describeUnknownConfigKeys renders unknown keys for an error message, or "" +// if there are none. withLines is false for --override values, whose line +// numbers point into the flag rather than the config file. +func describeUnknownConfigKeys(unknown []unknownConfigKey, withLines bool) string { + if len(unknown) == 0 { + return "" + } + + blocks := make([]string, 0, len(unknown)) + suggestUpdate := false + for _, u := range unknown { + names := visibleConfigChildNames(u.parent) + fieldPath := strings.TrimPrefix(u.parent.path+"."+u.key, configHelpRoot+".") + block := fmt.Sprintf("unknown field %q", fieldPath) + if withLines { + block = fmt.Sprintf("line %d: %s", u.line, block) + } + if suggestion, ok := closestConfigField(u.key, names); ok { + block += fmt.Sprintf("; did you mean %q?", suggestion) + } else { + suggestUpdate = true + } + block += fmt.Sprintf("\nfields under %q are: %s", u.parent.path, strings.Join(names, ", ")) + // `-h` rejects hidden legacy paths, so only point at documented ones. + if !u.parent.hidden { + block += fmt.Sprintf("\nrun \"databricks air run -h %s\" for details", u.parent.path) + } + blocks = append(blocks, block) + } + + msg := strings.Join(blocks, "\n\n") + if len(blocks) > 1 { + msg = fmt.Sprintf("%d unknown fields\n\n%s", len(blocks), msg) + } + // Some unknown keys are deliberately unsupported (e.g. priority, _bases_), + // so the newer-CLI explanation is only a possibility. + if suggestUpdate { + msg += fmt.Sprintf("\n\nif a field comes from newer documentation, it may need a newer CLI than version %s; run 'databricks version --check'", build.GetInfo().Version) + } + return msg +} + +// collectUnknownConfigKeys walks node against schema and returns unknown with +// every unknown key appended. Non-object and free-form fields, and values whose +// shape doesn't match the schema, are left to the decoder's type errors. +func collectUnknownConfigKeys(node *yaml.Node, schema configField, unknown []unknownConfigKey) []unknownConfigKey { + if node.Kind == yaml.AliasNode { + node = node.Alias + } + if len(schema.children) == 0 || schema.freeForm { + return unknown + } + switch node.Kind { + case yaml.SequenceNode: + if !schema.isList { + return unknown + } + item := schema + item.isList = false + for _, n := range node.Content { + unknown = collectUnknownConfigKeys(n, item, unknown) + } + case yaml.MappingNode: + if schema.isList { + return unknown + } + for i := 0; i < len(node.Content); i += 2 { + key, value := node.Content[i], node.Content[i+1] + // The decoder folds "<<: *anchor" (or a list of anchors) into this + // mapping, so the merged keys belong to schema. + if key.ShortTag() == "!!merge" { + sources := []*yaml.Node{value} + if value.Kind == yaml.SequenceNode { + sources = value.Content + } + for _, source := range sources { + unknown = collectUnknownConfigKeys(source, schema, unknown) + } + continue + } + child, ok := findConfigChild(schema.children, key.Value) + if !ok { + unknown = append(unknown, unknownConfigKey{line: key.Line, key: key.Value, parent: schema}) + continue + } + unknown = collectUnknownConfigKeys(value, child, unknown) + } + default: + // A scalar where an object is expected is a type error the decoder reports. + } + return unknown +} + func codeSourceFieldPresent(document *yaml.Node, field string) bool { codeSource, _ := mappingValue(document.Content[0], "code_source") if codeSource == nil || codeSource.Kind != yaml.MappingNode { diff --git a/cmd/air/runconfig_override.go b/cmd/air/runconfig_override.go index 3fbccd076cb..341e809a169 100644 --- a/cmd/air/runconfig_override.go +++ b/cmd/air/runconfig_override.go @@ -4,7 +4,6 @@ import ( "context" "errors" "fmt" - "slices" "strings" "github.com/databricks/cli/libs/cmdio" @@ -65,16 +64,8 @@ func checkOverridePath(parts []string, node configField, fullPath string) error name := parts[0] child, ok := findConfigChild(node.children, name) if !ok { - names := make([]string, 0, len(node.children)) - for _, c := range node.children { - if c.hidden { - continue - } - names = append(names, configLeafName(c.path)) - } - slices.Sort(names) return fmt.Errorf("invalid --override %q: %q is not a known field; available fields are: %s", - fullPath, name, strings.Join(names, ", ")) + fullPath, name, strings.Join(visibleConfigChildNames(node), ", ")) } if len(parts) == 1 { return nil @@ -103,11 +94,18 @@ func applyOverrides(ctx context.Context, document *yaml.Node, entries []override return errors.New("run config must be a YAML mapping") } + schema := configSchema() + for _, e := range entries { value, err := parseOverrideNode(e.raw) if err != nil { return fmt.Errorf("invalid --override %q: cannot parse value %q: %w", e.path, e.raw, err) } + // Check the value here: once spliced into the file's tree, its keys carry + // line numbers from the override string, not the config file. + if msg := describeUnknownConfigKeys(collectUnknownConfigKeys(value, overrideTargetField(schema, e.path), nil), false); msg != "" { + return fmt.Errorf("invalid --override %q: %s", e.path, msg) + } parts := strings.Split(e.path, ".") current := root @@ -144,6 +142,19 @@ func applyOverrides(ctx context.Context, document *yaml.Node, entries []override return nil } +// overrideTargetField resolves a path already accepted by checkOverridePath. +// Paths into a free-form map resolve to the map, which has no schema below it. +func overrideTargetField(schema configField, path string) configField { + field := schema + for part := range strings.SplitSeq(path, ".") { + if field.freeForm { + break + } + field, _ = findConfigChild(field.children, part) + } + return field +} + func parseOverrideNode(raw string) (*yaml.Node, error) { var document yaml.Node if err := yaml.Unmarshal([]byte(raw), &document); err != nil { diff --git a/cmd/air/runconfig_test.go b/cmd/air/runconfig_test.go index e2d4b47c934..2954ecfa770 100644 --- a/cmd/air/runconfig_test.go +++ b/cmd/air/runconfig_test.go @@ -9,6 +9,7 @@ import ( "strings" "testing" + "github.com/databricks/cli/internal/build" "github.com/databricks/cli/internal/testutil" "github.com/databricks/cli/libs/cmdctx" "github.com/stretchr/testify/assert" @@ -137,8 +138,8 @@ func TestLoadRunConfig_CodeSourceErrors(t *testing.T) { {"flattened error path", "code_source:\n root_path: \"\"\n", "code_source.root_path cannot be empty"}, {"nested error path", "code_source:\n snapshot:\n root_path: \"\"\n", "code_source.snapshot.root_path cannot be empty"}, {"null snapshot", "code_source:\n snapshot: null\n", "code_source.snapshot.root_path cannot be empty"}, - {"unknown flattened field", "code_source:\n root_path: src\n bogus: true\n", "field bogus not found"}, - {"unknown nested field", "code_source:\n snapshot:\n root_path: src\n bogus: true\n", "field bogus not found"}, + {"unknown flattened field", "code_source:\n root_path: src\n bogus: true\n", `unknown field "code_source.bogus"`}, + {"unknown nested field", "code_source:\n snapshot:\n root_path: src\n bogus: true\n", `unknown field "code_source.snapshot.bogus"`}, } for _, tt := range tests { @@ -326,6 +327,163 @@ func TestLoadRunConfig_UnknownFieldRejected(t *testing.T) { } } +func TestLoadRunConfig_UnknownFieldMessages(t *testing.T) { + tests := []struct { + name string + yaml string + wantParts []string + denyParts []string + }{ + { + name: "top-level typo", + yaml: minimalConfig + "envronment:\n version: 6\n", + wantParts: []string{ + `line 7: unknown field "envronment"; did you mean "environment"?`, + `fields under "config" are: code_source, command, compute,`, + `run "databricks air run -h config" for details`, + }, + denyParts: []string{"runConfig", "newer documentation"}, + }, + { + name: "nested typo", + yaml: minimalConfig + "code_source:\n rot_path: .\n", + wantParts: []string{ + `line 8: unknown field "code_source.rot_path"; did you mean "root_path"?`, + `fields under "config.code_source" are: git, include_paths, remote_volume, root_path`, + `run "databricks air run -h config.code_source" for details`, + }, + denyParts: []string{"codeSourceConfig", "newer documentation"}, + }, + { + name: "list item typo", + yaml: minimalConfig + "permissions:\n - user_name: a@example.test\n levl: CAN_VIEW\n", + wantParts: []string{`line 9: unknown field "permissions.levl"; did you mean "level"?`}, + }, + { + name: "no close match suggests a newer CLI", + yaml: minimalConfig + "code_source:\n root_path: .\n fancy_new_option: true\n", + wantParts: []string{ + `line 9: unknown field "code_source.fancy_new_option"` + "\n", + "if a field comes from newer documentation, it may need a newer CLI than version " + build.GetInfo().Version + "; run 'databricks version --check'", + }, + denyParts: []string{"did you mean"}, + }, + { + // priority is intentionally unsupported, so the newer-CLI hint must stay hedged. + name: "dropped priority field", + yaml: minimalConfig + "priority: 1\n", + wantParts: []string{ + `line 7: unknown field "priority"` + "\n", + "if a field comes from newer documentation, it may need a newer CLI", + }, + denyParts: []string{"did you mean", "update the Databricks CLI"}, + }, + { + name: "hidden parent omits help pointer", + yaml: minimalConfig + "code_source:\n snapshot:\n rot_path: .\n", + wantParts: []string{ + `line 9: unknown field "code_source.snapshot.rot_path"; did you mean "root_path"?`, + `fields under "config.code_source.snapshot" are: `, + }, + denyParts: []string{"databricks air run -h"}, + }, + { + name: "every unknown field is reported", + yaml: "envronment: {}\n" + minimalConfig + "compute2: {}\ncode_source:\n rot_path: .\n", + wantParts: []string{ + ": 3 unknown fields\n", + `line 1: unknown field "envronment"`, + `line 8: unknown field "compute2"`, + `line 10: unknown field "code_source.rot_path"`, + }, + }, + } + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + _, err := loadRunConfig(writeConfig(t, tt.yaml)) + require.Error(t, err) + for _, part := range tt.wantParts { + assert.Contains(t, err.Error(), part) + } + for _, part := range tt.denyParts { + assert.NotContains(t, err.Error(), part) + } + }) + } +} + +func TestLoadRunConfig_ShapeMismatchLeftToDecoder(t *testing.T) { + tests := []struct { + name string + yaml string + }{ + {"list document", "- experiment_name: x\n- bogus: 1\n"}, + {"list where object expected", "experiment_name: my-run\ncommand: python train.py\ncompute: [{foo: 1}]\n"}, + {"object where list expected", minimalConfig + "permissions: {levl: CAN_VIEW}\n"}, + } + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + _, err := loadRunConfig(writeConfig(t, tt.yaml)) + require.ErrorContains(t, err, "cannot unmarshal") + assert.NotContains(t, err.Error(), "unknown field") + assert.NotContains(t, err.Error(), "newer documentation") + }) + } +} + +func TestLoadRunConfigWithOverrides_UnknownFieldInValue(t *testing.T) { + tests := []struct { + name string + override string + wantParts []string + }{ + { + name: "object value", + override: "compute={foo: 1}", + wantParts: []string{ + `invalid --override "compute": unknown field "compute.foo"` + "\n", + `fields under "config.compute" are: `, + "newer documentation", + }, + }, + { + name: "list value", + override: "permissions=[{levl: CAN_VIEW}]", + wantParts: []string{`invalid --override "permissions": unknown field "permissions.levl"; did you mean "level"?`}, + }, + } + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + _, err := loadRunConfigWithOverrides(t.Context(), writeConfig(t, minimalConfig), []string{tt.override}) + require.Error(t, err) + for _, part := range tt.wantParts { + assert.Contains(t, err.Error(), part) + } + assert.NotContains(t, err.Error(), "line ") + assert.NotContains(t, err.Error(), "invalid config") + }) + } +} + +func TestLoadRunConfig_KnownFieldsAcceptedByUnknownFieldCheck(t *testing.T) { + tests := []struct { + name string + yaml string + }{ + {"hidden legacy code_source keys", "code_source:\n type: snapshot\n snapshot:\n root_path: src\n"}, + {"free-form maps", "parameters:\n lr: {nested: 1}\nenv_variables:\n ANY_NAME: x\n"}, + {"merge key", "permissions:\n - <<: {level: CAN_VIEW}\n user_name: a@example.test\n"}, + {"merge key list", "permissions:\n - <<: [{level: CAN_VIEW}, {user_name: a@example.test}]\n"}, + {"merge key from alias", "permissions:\n - &grant {level: CAN_VIEW, user_name: a@example.test}\n - <<: *grant\n user_name: b@example.test\n"}, + } + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + _, err := loadRunConfig(writeConfig(t, minimalConfig+tt.yaml)) + require.NoError(t, err) + }) + } +} + func TestLoadRunConfig_ErrorLineNumbersUseSource(t *testing.T) { path := writeConfig(t, `# first comment # second comment @@ -339,12 +497,12 @@ unknown_field: true t.Run("without overrides", func(t *testing.T) { _, err := loadRunConfig(path) - require.ErrorContains(t, err, "line 8: field unknown_field") + require.ErrorContains(t, err, `line 8: unknown field "unknown_field"`) }) t.Run("with overrides", func(t *testing.T) { _, err := loadRunConfigWithOverrides(t.Context(), path, []string{"compute.num_accelerators=2"}) - require.ErrorContains(t, err, "line 8: field unknown_field") + require.ErrorContains(t, err, `line 8: unknown field "unknown_field"`) }) }