Add comprehensive ERRORS.md documenting error message sourcing and reliability

[devin-ai-integration]

Add Comprehensive ERRORS.md Documentation

Overview

This PR adds comprehensive documentation analyzing how error messages are sourced and their reliability in the parseQueryDetailed function and related parsing functions, specifically focusing on the feat/wasm-only-v17 branch implementation.

What's Added

• ERRORS.md: A detailed analysis document covering:
  • Complete error message source chain from PostgreSQL parser to JavaScript API
  • PgQueryError structure and field reliability assessment
  • WASM wrapper implementation details
  • JavaScript/TypeScript API layer analysis
  • Verification methods and recommendations for developers

Key Findings

Error Message Reliability: ✅ HIGHLY RELIABLE

The analysis confirms that error messages in parseQueryDetailed are highly reliable because they:

1. Originate directly from PostgreSQL's parser - Same error system used by PostgreSQL server
2. Preserve all original error information - Complete chain with no data loss
3. Use proper memory management - Safe string duplication and cleanup
4. Include comprehensive location info - Accurate line numbers and cursor positions
5. Maintain consistency - Same structure across C/WASM/JavaScript boundary

Error Source Chain

PostgreSQL Parser (ErrorData) 
    ↓ 
libpg_query C Layer (PgQueryError)
    ↓
WASM Wrapper (WasmDetailedResult) 
    ↓
JavaScript API (Error object)

Documentation Highlights

• Complete traceability of error messages from source to API
• Reliability assessment for each error field (message, cursorpos, lineno, funcname, filename)
• Memory safety analysis showing proper error handling
• Developer recommendations for using error information effectively
• Code examples demonstrating proper error handling patterns

Impact

This documentation provides developers with confidence in using parseQueryDetailed for production applications, particularly SQL editors and query analysis tools that require reliable error reporting.

Testing

The analysis is based on direct code inspection of:

• PostgreSQL error handling mechanisms (PG_TRY/PG_CATCH)
• libpg_query C implementation (pg_query_parse.c)
• WASM wrapper (wasm_wrapper.c)
• JavaScript API (wasm/index.js)

---

Link to Devin run: https://app.devin.ai/sessions/9f2a7df62f434dc79c33e348c13f39ad

Requested by: Dan Lynch ([email protected])

[devin-ai-integration]

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

• Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
• Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

• Disable automatic comment and CI monitoring