fix: surface best-matching variant for union validation errors (#172) (#213)

* fix: surface best-matching variant for union validation errors (#172)

Zod v4 reports union failures as one issue per variant. For
QueryDslQueryContainer (61 variants) and similar discriminated unions,
this produced unactionable output: text mode collapsed to "Invalid
input → at query", and JSON mode emitted 61 nested error objects where
the one meaningful error was buried among "received undefined" noise
from non-matching discriminators.

simplifyZodIssues walks ZodError.issues and, for each invalid_union,
picks the variant whose errors reach the deepest path -- the reliable
signal that the discriminator matched and validation failed on a real
nested field. The chosen variant replaces the union issue inline;
recursion handles nested unions (e.g. bool.must clauses).

formatIssuesText renders the flat list as readable "✖ message → at
path" lines, replacing z.prettifyError on the validation path.

* fix: add SPDX header to zod-error.ts

Author: MattDevy

src/factory.ts

@@ -11,6 +11,7 @@ import type { ResolvedConfig, CommandPolicy } from './config/types.ts'
 import { getResolvedConfig } from './config/store.ts'
 import { extractSchemaArgs, validateSchemaArgs } from './lib/schema-args.ts'
 import type { SchemaArgDefinition } from './lib/schema-args.ts'
+import { simplifyZodIssues, formatIssuesText } from './lib/zod-error.ts'
 import { renderText, formatHandlerError } from './output.ts'
 
 /** pre-built schema for coercing string → number, reused per option invocation */
@@ -730,8 +731,8 @@ export function defineCommand<T extends z.ZodType> (config: CommandConfig<T>): O
           parsed.rawBodyValues = rawBodyValues
         }
       } else {
+        const issues = simplifyZodIssues(result.error.issues)
         if (jsonFormat === true) {
-          const issues = result.error.issues
           process.stderr.write(JSON.stringify({
             error: {
               code: 'input_validation_failed',
@@ -742,7 +743,7 @@ export function defineCommand<T extends z.ZodType> (config: CommandConfig<T>): O
           // throw to prevent handler execution - mirrors cmd.error() behaviour
           throw Object.assign(new Error('input_validation_failed'), { exitCode: 1 })
         }
-        return cmd.error(`input validation failed:\n${z.prettifyError(result.error)}`)
+        return cmd.error(`input validation failed:\n${formatIssuesText(issues)}`)
       }
     }
     if (allRaw['dryRun'] === true) {

src/lib/zod-error.ts

@@ -0,0 +1,115 @@
+/*
+ * Copyright Elasticsearch B.V. and contributors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { z } from 'zod'
+
+/**
+ * Tools for turning Zod v4 validation errors into concise, actionable output.
+ *
+ * Union schemas (e.g. the 61-variant `QueryDslQueryContainer`) produce a single
+ * `invalid_union` issue whose `errors` array contains one sub-list per variant.
+ * All-but-one of those sub-lists are `"received undefined"` noise from variants
+ * whose discriminator key isn't present. `simplifyZodIssues` replaces each
+ * `invalid_union` with the sub-list of the variant most likely to have been
+ * intended, picked by depth heuristic (see `scoreVariant`). The result is a
+ * flat list of issues suitable for rendering to text or emitting as JSON.
+ */
+
+type Issue = z.core.$ZodIssue
+type InvalidUnionIssue = Extract<Issue, { code: 'invalid_union' }>
+
+function isInvalidUnion (issue: Issue): issue is InvalidUnionIssue {
+  return issue.code === 'invalid_union'
+}
+
+/**
+ * Scores a variant's issue list as a candidate for "the user meant this variant".
+ *
+ * Higher is better. The dominant signal is the deepest path reached: a matched
+ * discriminator lets validation descend into nested fields, producing longer
+ * paths than the shallow `"received undefined"` emitted when a variant's
+ * discriminator key is absent from the input.
+ */
+function scoreVariant (issues: readonly Issue[]): number {
+  if (issues.length === 0) return -Infinity
+  let maxDepth = 0
+  let undefinedCount = 0
+  for (const issue of issues) {
+    if (issue.path.length > maxDepth) maxDepth = issue.path.length
+    if (issue.code === 'invalid_type' && issue.message.includes('received undefined')) {
+      undefinedCount++
+    }
+  }
+  // Depth dominates. Fewer undefined messages and fewer total issues break ties.
+  return maxDepth * 1000 - undefinedCount * 10 - issues.length
+}
+
+function pickBestVariant (variants: readonly (readonly Issue[])[]): readonly Issue[] | undefined {
+  if (variants.length === 0) return undefined
+  let bestIdx = 0
+  let bestScore = scoreVariant(variants[0] as Issue[])
+  for (let i = 1; i < variants.length; i++) {
+    const s = scoreVariant(variants[i] as Issue[])
+    if (s > bestScore) {
+      bestScore = s
+      bestIdx = i
+    }
+  }
+  return variants[bestIdx]
+}
+
+function prefixPath (issue: Issue, prefix: readonly PropertyKey[]): Issue {
+  if (prefix.length === 0) return issue
+  return { ...issue, path: [...prefix, ...issue.path] } as Issue
+}
+
+/**
+ * Recursively collapses `invalid_union` issues to their most likely intended
+ * variant. Non-union issues pass through unchanged (with paths preserved).
+ *
+ * If a union has no variants (defensive) or picking a best variant is not
+ * possible, the original `invalid_union` issue is preserved so information
+ * isn't silently lost.
+ */
+export function simplifyZodIssues (issues: readonly Issue[]): Issue[] {
+  const out: Issue[] = []
+  for (const issue of issues) {
+    if (isInvalidUnion(issue) && Array.isArray(issue.errors) && issue.errors.length > 0) {
+      const best = pickBestVariant(issue.errors)
+      if (best !== undefined && best.length > 0) {
+        const prefixed = best.map(sub => prefixPath(sub, issue.path))
+        out.push(...simplifyZodIssues(prefixed))
+        continue
+      }
+    }
+    out.push(issue)
+  }
+  return out
+}
+
+function formatPath (path: readonly PropertyKey[]): string {
+  if (path.length === 0) return '(root)'
+  let s = ''
+  for (const seg of path) {
+    if (typeof seg === 'number') {
+      s += `[${seg}]`
+    } else {
+      s += s === '' ? String(seg) : `.${String(seg)}`
+    }
+  }
+  return s
+}
+
+/**
+ * Renders a flat list of issues as human-readable text. Each issue is two lines:
+ *   ✖ <message>
+ *     → at <path>
+ */
+export function formatIssuesText (issues: readonly Issue[]): string {
+  if (issues.length === 0) return '✖ Invalid input'
+  return issues
+    .map(i => `✖ ${i.message}\n  → at ${formatPath(i.path)}`)
+    .join('\n')
+}

test/factory.test.ts

@@ -1418,6 +1418,71 @@ describe('defineCommand', () => {
       assert.match(err, /input validation failed/)
       assert.match(err, /address\.zipCode/)
     })
+
+    it('union-typed field surfaces the matching variant instead of all variants (#172)', async () => {
+      // Mirrors QueryDslQueryContainer-style validation: many variants, only
+      // one of which the user's input aligns with.
+      const schema = z.object({
+        query: z.union([
+          z.object({ bool: z.object({ must: z.array(z.unknown()) }) }),
+          z.object({ match_all: z.object({}) }),
+          z.object({ term: z.object({ category: z.object({ value: z.string() }) }) }),
+          z.object({ range: z.object({ field: z.string() }) }),
+        ])
+      })
+      const filePath = join(tmpDir, 'union-error.json')
+      writeFileSync(filePath, JSON.stringify({ query: { term: { category: 'canyon' } } }))
+      const cmd = defineCommand({
+        name: 'search',
+        description: 'Search',
+        input: schema,
+        handler: () => ({}),
+      })
+      const err = await captureErrAsync(cmd, ['--input-file', filePath])
+      assert.match(err, /input validation failed/)
+      assert.match(err, /query\.term\.category/)
+      assert.match(err, /expected object/i)
+      // None of the shallow "received undefined" discriminator noise leaks out
+      assert.ok(!/received undefined/.test(err),
+        `discriminator noise leaked: ${err}`)
+      // And none of the non-matching variant keys surface as errors
+      assert.ok(!/bool|match_all|range/.test(err),
+        `non-matching variants leaked: ${err}`)
+    })
+
+    it('JSON mode emits a single actionable issue for union failures (#172)', async () => {
+      const schema = z.object({
+        query: z.union([
+          z.object({ bool: z.object({ must: z.array(z.unknown()) }) }),
+          z.object({ match_all: z.object({}) }),
+          z.object({ term: z.object({ category: z.object({ value: z.string() }) }) }),
+          z.object({ range: z.object({ field: z.string() }) }),
+        ])
+      })
+      const filePath = join(tmpDir, 'union-json-error.json')
+      writeFileSync(filePath, JSON.stringify({ query: { term: { category: 'canyon' } } }))
+      const cmd = defineCommand({
+        name: 'search',
+        description: 'Search',
+        input: schema,
+        handler: () => ({}),
+      })
+      const { stderr } = await invokeCapturingStreams(cmd, ['--json'], ['--input-file', filePath])
+      const parsed = JSON.parse(stderr) as {
+        error: {
+          code: string
+          message: string
+          issues: Array<{ code: string; path: Array<string|number>; message: string }>
+        }
+      }
+      assert.equal(parsed.error.code, 'input_validation_failed')
+      assert.equal(parsed.error.issues.length, 1,
+        `expected exactly one issue, got ${parsed.error.issues.length}: ${JSON.stringify(parsed.error.issues)}`)
+      const [issue] = parsed.error.issues
+      assert.equal(issue.code, 'invalid_type')
+      assert.deepEqual(issue.path, ['query', 'term', 'category'])
+      assert.match(issue.message, /expected object/i)
+    })
   })
 
   describe('relaxed validation for JSON body fields (#156)', () => {

test/lib/zod-error.test.ts

@@ -0,0 +1,159 @@
+/*
+ * Copyright Elasticsearch B.V. and contributors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { describe, it } from 'node:test'
+import assert from 'node:assert/strict'
+import { z } from 'zod'
+import { simplifyZodIssues, formatIssuesText } from '../../src/lib/zod-error.ts'
+
+/**
+ * Helper: run a schema against input and return the raw issues produced by Zod.
+ * Using real Zod errors keeps tests honest about the issue shapes we rely on.
+ */
+function issuesFor (schema: z.ZodType, input: unknown): readonly z.core.$ZodIssue[] {
+  const r = schema.safeParse(input)
+  if (r.success) throw new Error('expected validation to fail')
+  return r.error.issues
+}
+
+describe('simplifyZodIssues', () => {
+  it('passes non-union issues through unchanged', () => {
+    const schema = z.object({ name: z.string() })
+    const raw = issuesFor(schema, { name: 42 })
+    const simplified = simplifyZodIssues(raw)
+    assert.equal(simplified.length, 1)
+    assert.equal(simplified[0].code, 'invalid_type')
+    assert.deepEqual(simplified[0].path, ['name'])
+  })
+
+  it('collapses invalid_union to the variant whose errors reach deepest', () => {
+    // Mimics a discriminated-ish union: only one branch's shape matches
+    // the shape of the input, so the correct variant to surface is `term`.
+    const schema = z.object({
+      query: z.union([
+        z.object({ bool: z.object({ must: z.array(z.unknown()) }) }),
+        z.object({ match_all: z.object({}) }),
+        z.object({ term: z.object({ category: z.object({ value: z.string() }) }) }),
+      ])
+    })
+    const raw = issuesFor(schema, { query: { term: { category: 'canyon' } } })
+    const simplified = simplifyZodIssues(raw)
+    // The deepest issue is "expected object, received string" at query.term.category
+    const deepest = simplified.find(i => i.path.length >= 3)
+    assert.ok(deepest, `expected a deep issue, got: ${JSON.stringify(simplified)}`)
+    assert.deepEqual(deepest.path, ['query', 'term', 'category'])
+    assert.equal(deepest.code, 'invalid_type')
+    assert.match(deepest.message, /expected object/i)
+    // No 'received undefined' noise from non-matching variants
+    for (const i of simplified) {
+      assert.ok(!/received undefined/.test(i.message),
+        `leaked discriminator noise: ${i.message} at ${JSON.stringify(i.path)}`)
+    }
+  })
+
+  it('flattens nested unions recursively', () => {
+    // outer union picks `outer.nested` variant -> inner union picks the variant
+    // whose object matches the input shape.
+    const schema = z.object({
+      outer: z.union([
+        z.object({ simple: z.string() }),
+        z.object({
+          nested: z.union([
+            z.object({ a: z.object({ value: z.string() }) }),
+            z.object({ b: z.object({ value: z.string() }) }),
+          ])
+        }),
+      ])
+    })
+    const raw = issuesFor(schema, { outer: { nested: { a: 'bad' } } })
+    const simplified = simplifyZodIssues(raw)
+    const deepest = simplified.find(i => i.path.includes('a'))
+    assert.ok(deepest, `expected nested-a issue, got: ${JSON.stringify(simplified)}`)
+    assert.deepEqual(deepest.path, ['outer', 'nested', 'a'])
+    // No invalid_union should remain after flattening
+    assert.ok(simplified.every(i => i.code !== 'invalid_union'),
+      'invalid_union leaked through')
+  })
+
+  it('prepends union issue path to chosen variant sub-issues', () => {
+    const schema = z.object({
+      wrapper: z.object({
+        q: z.union([
+          z.object({ term: z.object({ field: z.string() }) }),
+          z.object({ match: z.object({ field: z.string() }) }),
+        ])
+      })
+    })
+    const raw = issuesFor(schema, { wrapper: { q: { term: { field: 42 } } } })
+    const simplified = simplifyZodIssues(raw)
+    const target = simplified.find(i => i.code === 'invalid_type')
+    assert.ok(target)
+    assert.deepEqual(target.path, ['wrapper', 'q', 'term', 'field'])
+  })
+
+  it('preserves the original issue when no variants are available', () => {
+    // A union with empty errors array (the rare "multiple match" case). We
+    // construct it manually since there is no schema shape that produces it
+    // in a stable way.
+    const fabricated: z.core.$ZodIssue = {
+      code: 'invalid_union',
+      path: ['root'],
+      message: 'Invalid input',
+      errors: []
+    } as z.core.$ZodIssue
+    const simplified = simplifyZodIssues([fabricated])
+    assert.equal(simplified.length, 1)
+    assert.equal(simplified[0].code, 'invalid_union')
+  })
+
+  it('handles multiple top-level issues independently', () => {
+    const schema = z.object({
+      a: z.union([z.object({ x: z.string() }), z.object({ y: z.string() })]),
+      b: z.number(),
+    })
+    const raw = issuesFor(schema, { a: { x: 1 }, b: 'bad' })
+    const simplified = simplifyZodIssues(raw)
+    // Both fields represented: b directly, a via its best variant
+    assert.ok(simplified.some(i => i.path[0] === 'b' && i.code === 'invalid_type'))
+    assert.ok(simplified.some(i => i.path[0] === 'a'))
+  })
+})
+
+describe('formatIssuesText', () => {
+  it('renders one issue as two lines', () => {
+    const out = formatIssuesText([
+      { code: 'invalid_type', path: ['name'], message: 'expected string, received number' } as z.core.$ZodIssue
+    ])
+    assert.equal(out, '✖ expected string, received number\n  → at name')
+  })
+
+  it('joins multiple issues with newlines', () => {
+    const out = formatIssuesText([
+      { code: 'invalid_type', path: ['name'], message: 'A' } as z.core.$ZodIssue,
+      { code: 'invalid_type', path: ['count'], message: 'B' } as z.core.$ZodIssue,
+    ])
+    assert.equal(out.split('\n').length, 4)
+    assert.match(out, /at name/)
+    assert.match(out, /at count/)
+  })
+
+  it('formats nested paths with dots and array indices with brackets', () => {
+    const out = formatIssuesText([
+      { code: 'invalid_type', path: ['a', 'b', 0, 'c'], message: 'boom' } as z.core.$ZodIssue
+    ])
+    assert.match(out, /at a\.b\[0\]\.c/)
+  })
+
+  it('renders empty list as generic message', () => {
+    assert.equal(formatIssuesText([]), '✖ Invalid input')
+  })
+
+  it('renders root-level issues with "(root)" path', () => {
+    const out = formatIssuesText([
+      { code: 'invalid_type', path: [], message: 'broken' } as z.core.$ZodIssue
+    ])
+    assert.match(out, /at \(root\)/)
+  })
+})