DocWire SDK Files

This release introduces a comprehensive overhaul of the SDK's diagnostic and testing infrastructure, centered around a new zero-cost logging framework, a powerful serialization system, and a fluent assertion utility. The error handling mechanism has been significantly enhanced to provide richer, more structured diagnostic messages. This release also modernizes all README.md examples, refactors core components for improved performance and thread-safety, and enhances the CI/CD pipeline.

The old logs fade, a silent, costly past,
New macros rise, expressive and fast.
With sinks and filters, a structured, clear design,
And fluent assertions, that truly align.
A core reforged, robust and so keen,
The finest framework, the best we have seen.
✨🚀🔧

• Features
• Modern Logging Framework: Replaced the legacy logger with a new zero-cost, structured logging system. It features a sink/filter architecture, JSON output, and expressive macros (log_entry, log_scope, log_forward) that are compiled out in release builds for zero performance overhead.
• Serialization Framework: Introduced a powerful, concept-based serialization framework to convert C++ types into a structured representation, used by the new logging and error systems.
• Fluent Assertion Utility: Added docwire::ensure, a zero-cost, exception-throwing assertion utility for writing expressive and robust release-build validations (e.g., ensure(value) > 5;).
• Safe Environment Variable Access: Introduced docwire::environment::get, a safe and convenient wrapper for accessing environment variables.

• Endian-Aware Binary Reader: Added binary::reader, a new utility for safely parsing little-endian binary data from any stream-like source.

• Improvements

• Refactored charset_converter: Overhauled the charset_converter for improved performance, correctness, and thread-safety by serializing iconv_open calls with a global mutex to resolve a data race in glibc.
• Refactored XLSBParser: The XLSBParser now uses the new binary::reader, resulting in cleaner, more robust, and endian-aware parsing logic.
• Optimized Test Suite: All API tests now run in a single process, significantly improving test suite performance, especially under sanitizers.

• CI Enhancements:

  • The CI build matrix has been simplified and made more robust.
  • Conditional execution for OpenAI tests is now supported via the run-tests:openai pull request label, manual dispatch options, and repository-specific schedule triggers.

• Refactor

• Enhanced Error Handling: The error handling framework has been refactored to use the new serialization system and support multiple context items, providing more detailed and structured diagnostic messages.

• Type Name Normalization: The type_name utility has been refined to more robustly handle C++ standard library implementation artifacts, improving cross-platform consistency.

• Fixes

• Fixed a bug where unique_identifier counters could be reset by moving the static member definition to a .cpp file, ensuring a single instance across shared libraries.
• Corrected a lambda capture issue in pix_cache to capture data_source by reference, improving correctness and performance.

• Prevented Leptonica error message accumulation by clearing the stderr buffer on each use.

• Documentation

• Modernized README: Replaced all full code examples in README.md with concise snippets that use the new ensure API for assertions. Each snippet now links to its corresponding full, verifiable source file in the tests/ directory.

• Updated Logging Section: The logging documentation has been completely rewritten to reflect the new framework's features and usage.

• Tests

• Log Sanitization: Automated tests now sanitize expected log output to robustly handle differences in function name formatting across compilers and platforms.
• README Snippet Verification: Added a new automated test to ensure all code snippets in README.md are consistent with their full source examples.