feat(cli): render decode error with line context, source, and caret

Author: johannschopplich

packages/cli/src/conversion.ts

@@ -85,38 +85,27 @@ export async function decodeToJson(config: {
   if (config.expandPaths === 'safe') {
     const toonContent = await readInput(config.input)
 
-    let data: unknown
-    try {
-      const decodeOptions: DecodeOptions = {
-        indent: config.indent,
-        strict: config.strict,
-        expandPaths: config.expandPaths,
-      }
-      data = decode(toonContent, decodeOptions)
-    }
-    catch (error) {
-      throw new Error(`Failed to decode TOON: ${error instanceof Error ? error.message : String(error)}`)
+    const decodeOptions: DecodeOptions = {
+      indent: config.indent,
+      strict: config.strict,
+      expandPaths: config.expandPaths,
     }
+    const data = decode(toonContent, decodeOptions)
 
     await writeStreamingJson(jsonStringifyLines(data, config.indent), config.output)
   }
   else {
-    try {
-      const lineSource = readLinesFromSource(config.input)
+    const lineSource = readLinesFromSource(config.input)
 
-      const decodeStreamOptions: DecodeStreamOptions = {
-        indent: config.indent,
-        strict: config.strict,
-      }
+    const decodeStreamOptions: DecodeStreamOptions = {
+      indent: config.indent,
+      strict: config.strict,
+    }
 
-      const events = decodeStream(lineSource, decodeStreamOptions)
-      const jsonChunks = jsonStreamFromEvents(events, config.indent)
+    const events = decodeStream(lineSource, decodeStreamOptions)
+    const jsonChunks = jsonStreamFromEvents(events, config.indent)
 
-      await writeStreamingJson(jsonChunks, config.output)
-    }
-    catch (error) {
-      throw new Error(`Failed to decode TOON: ${error instanceof Error ? error.message : String(error)}`)
-    }
+    await writeStreamingJson(jsonChunks, config.output)
   }
 
   if (config.output) {

packages/cli/src/format-error.ts

@@ -0,0 +1,70 @@
+import { ToonDecodeError } from '../../toon/src/index.ts'
+
+export interface FormatErrorOptions {
+  isVerbose: boolean
+}
+
+// #region Public API
+
+export function formatError(error: unknown, options: FormatErrorOptions): string {
+  const sections: string[] = []
+
+  if (error instanceof ToonDecodeError && error.line !== undefined) {
+    sections.push(formatDecodeError(error))
+  }
+  else {
+    sections.push(String(error))
+  }
+
+  if (options.isVerbose) {
+    const causeChain = formatCauseChain(error)
+    if (causeChain) {
+      sections.push(causeChain)
+    }
+
+    if (error instanceof Error && error.stack) {
+      sections.push(error.stack)
+    }
+  }
+
+  return sections.join('\n\n')
+}
+
+// #endregion
+
+// #region Internal renderers
+
+function formatDecodeError(error: ToonDecodeError): string {
+  const linePrefix = `Line ${error.line}: `
+  const messageWithoutPrefix = error.message.startsWith(linePrefix)
+    ? error.message.slice(linePrefix.length)
+    : error.message
+
+  const header = `Failed to decode TOON at line ${error.line}: ${messageWithoutPrefix}`
+
+  if (error.source === undefined) {
+    return header
+  }
+
+  const visibleSource = error.source.replace(/\t/g, '→')
+  const firstNonWhitespaceIndex = visibleSource.search(/\S/)
+  const gutter = `  ${error.line} | `
+  const caretIndent = ' '.repeat(gutter.length + Math.max(firstNonWhitespaceIndex, 0))
+
+  return `${header}\n\n${gutter}${visibleSource}\n${caretIndent}^`
+}
+
+function formatCauseChain(error: unknown): string {
+  const causeLines: string[] = []
+  let current: unknown = error instanceof Error ? error.cause : undefined
+
+  while (current instanceof Error) {
+    const name = current.name || 'Error'
+    causeLines.push(`Caused by: ${name}: ${current.message}`)
+    current = current.cause
+  }
+
+  return causeLines.join('\n')
+}
+
+// #endregion

packages/cli/src/index.ts

@@ -8,6 +8,7 @@ import { consola } from 'consola'
 import { DEFAULT_DELIMITER, DELIMITERS } from '../../toon/src/index.ts'
 import pkg from '../package.json' with { type: 'json' }
 import { decodeToJson, encodeToToon } from './conversion.ts'
+import { formatError } from './format-error.ts'
 import { detectMode } from './utils.ts'
 
 const { name, version } = pkg
@@ -67,6 +68,11 @@ const args: ArgsDef = {
     description: 'Show token statistics',
     default: false,
   },
+  verbose: {
+    type: 'boolean',
+    description: 'Show full stack traces and cause chains for errors',
+    default: false,
+  },
 } as const
 
 export const mainCommand: CommandDef<ArgsDef> = defineCommand({
@@ -142,7 +148,7 @@ export const mainCommand: CommandDef<ArgsDef> = defineCommand({
       }
     }
     catch (error) {
-      consola.error(error)
+      consola.error(formatError(error, { isVerbose: args.verbose === true }))
       process.exit(1)
     }
   },

packages/cli/test/format-error.test.ts

@@ -0,0 +1,78 @@
+import { describe, expect, it } from 'vitest'
+import { ToonDecodeError } from '../../toon/src/index'
+import { formatError } from '../src/format-error'
+
+describe('formatError', () => {
+  it('renders a decode error with line and source as a header, source line, and caret', () => {
+    const error = new ToonDecodeError(
+      'Tabs are not allowed in indentation in strict mode',
+      { line: 2, source: '\tb: 1' },
+    )
+
+    const output = formatError(error, { isVerbose: false })
+
+    expect(output).toBe(
+      'Failed to decode TOON at line 2: Tabs are not allowed in indentation in strict mode\n'
+      + '\n'
+      + '  2 | →b: 1\n'
+      + '      ^',
+    )
+  })
+
+  it('renders a decode error without source as a header only', () => {
+    const error = new ToonDecodeError('Something went wrong', { line: 5 })
+
+    const output = formatError(error, { isVerbose: false })
+
+    expect(output).toBe('Failed to decode TOON at line 5: Something went wrong')
+  })
+
+  it('appends the cause chain under verbose mode', () => {
+    const cause = new SyntaxError('Unterminated string: missing closing quote')
+    const error = new ToonDecodeError(
+      'Unterminated string: missing closing quote',
+      { line: 2, source: 'greeting: "hello', cause },
+    )
+
+    const output = formatError(error, { isVerbose: true })
+
+    expect(output).toContain('Failed to decode TOON at line 2:')
+    expect(output).toContain('  2 | greeting: "hello')
+    expect(output).toContain('Caused by: SyntaxError: Unterminated string: missing closing quote')
+  })
+
+  it('appends the stack trace under verbose mode and omits it otherwise', () => {
+    const error = new ToonDecodeError('Boom', { line: 1, source: 'x' })
+    error.stack = 'ToonDecodeError: Line 1: Boom\n    at fakeFrame (file.ts:1:1)'
+
+    const verbose = formatError(error, { isVerbose: true })
+    const quiet = formatError(error, { isVerbose: false })
+
+    expect(verbose).toContain('at fakeFrame (file.ts:1:1)')
+    expect(quiet).not.toContain('at fakeFrame')
+  })
+
+  it('renders a generic Error as its message only when not verbose', () => {
+    const error = new Error('something went wrong')
+
+    const output = formatError(error, { isVerbose: false })
+
+    expect(output).toBe('Error: something went wrong')
+  })
+
+  it('places the caret under the first non-whitespace character of the source line', () => {
+    const error = new ToonDecodeError(
+      'Indentation must be exact multiple of 2, but found 3 spaces',
+      { line: 2, source: '   b: 1' },
+    )
+
+    const output = formatError(error, { isVerbose: false })
+
+    expect(output).toBe(
+      'Failed to decode TOON at line 2: Indentation must be exact multiple of 2, but found 3 spaces\n'
+      + '\n'
+      + '  2 |    b: 1\n'
+      + '         ^',
+    )
+  })
+})

packages/cli/test/index.test.ts

@@ -230,6 +230,48 @@ describe('toon CLI', () => {
         cleanup()
       }
     })
+
+    it('renders a TOON decode error with line context, source, and caret', async () => {
+      const cleanup = mockStdin('a:\n\tb: 1\n')
+
+      const consolaError = vi.spyOn(consola, 'error').mockImplementation(() => undefined)
+      const exitSpy = vi.mocked(process.exit)
+
+      try {
+        await runCli({ rawArgs: ['--decode'] })
+
+        expect(exitSpy).toHaveBeenCalledWith(1)
+        const errorCall = consolaError.mock.calls.at(0)
+        expect(errorCall).toBeDefined()
+        const [rendered] = errorCall!
+        expect(rendered).toEqual(expect.stringContaining('Failed to decode TOON at line 2:'))
+        expect(rendered).toEqual(expect.stringContaining('  2 | →b: 1'))
+        expect(rendered).toEqual(expect.stringContaining('      ^'))
+        expect(rendered).not.toEqual(expect.stringMatching(/^\s+at \S+/m))
+      }
+      finally {
+        cleanup()
+      }
+    })
+
+    it('includes the stack trace when --verbose is passed', async () => {
+      const cleanup = mockStdin('a:\n\tb: 1\n')
+
+      const consolaError = vi.spyOn(consola, 'error').mockImplementation(() => undefined)
+
+      try {
+        await runCli({ rawArgs: ['--decode', '--verbose'] })
+
+        const errorCall = consolaError.mock.calls.at(0)
+        expect(errorCall).toBeDefined()
+        const [rendered] = errorCall!
+        expect(rendered).toEqual(expect.stringContaining('Failed to decode TOON at line 2:'))
+        expect(rendered).toEqual(expect.stringMatching(/at \S+/))
+      }
+      finally {
+        cleanup()
+      }
+    })
   })
 
   describe('stdin with options', () => {