Add streaming JSON adapters and regression contracts for all engines

.gitignore

@@ -56,3 +56,15 @@ m4/lt~obsolete.m4
 # can automatically generate from config.status script
 # (which is called by configure script))
 Makefile
+
+# Generated API test executables and Automake reports.
+/tests/*_api_tests
+/tests/pathhandler_tests
+/tests/*.log
+/tests/*.trs
+/tests/__pycache__/
+/build-aux/
+/config.h
+/config.h.in~
+/configure~
+/jsonbench-*.tar.gz

.sonarcloud.properties

@@ -0,0 +1,3 @@
+# Match the C++17 standard in src/Makefile.am and tests/Makefile.am.
+# Automatic analysis otherwise recommends newer-standard facilities.
+sonar.cfamily.reportingCppStandardOverride=c++17

Makefile.am

@@ -1,2 +1,4 @@
-SUBDIRS = src
-dist_doc_DATA = README
+SUBDIRS = src tests
+dist_doc_DATA = README
+EXTRA_DIST = docs/adapter-stack.md docs/adapter-stack-benchmark.json \
+             docs/jsoncons-sax.md docs/validation-results.md

README.md

@@ -179,6 +179,35 @@ tests/run_tests.sh           # all available engines
 tests/run_tests.sh SIMDJSON  # single engine
 ```
 
+The runner requires Python 3 (standard library only). Every selected engine
+runs the same regression matrix: explicit argument output, valid/invalid JSON,
+UTF-8, numeric ranges, size/limit boundaries, silent mode and repeated passes.
+Failures and unsupported-limit skips are reported separately; missing expected
+output is a failure. A JSONCONS-only run also compares applicable cases to YAJL
+when it is installed. Other engines' known defects remain visible as failures.
+
+The jsoncons adapter uses streaming SAX events, strict JSON syntax and lossless
+number events. See [the implementation and compatibility notes](docs/jsoncons-sax.md)
+and [validation results](docs/validation-results.md).
+
+To exercise the jsoncons C interface separately after configuring the project
+(use the same include flags as your normal build):
+
+```bash
+gcc -std=gnu11 -c tests/test_c_memory.c -o /tmp/jsonbench-test-c-memory.o
+g++ -std=c++17 ${CPPFLAGS:-} tests/jsoncons_api_tests.cpp src/jsonconsparser.cpp \
+  /tmp/jsonbench-test-c-memory.o -o /tmp/jsoncons_api_tests
+/tmp/jsoncons_api_tests
+```
+
+For memory-safety validation, add `-fsanitize=address,undefined
+-fno-omit-frame-pointer` to both compilation commands. For repeatable DOM/SAX/YAJL
+measurements, preserve a pre-change executable and run:
+
+```bash
+python3 tests/benchmark_jsoncons.py --baseline /path/to/jsonbench-before --binary src/jsonbench
+```
+
 ---
 
 ## TODO

configure.ac

@@ -3,6 +3,7 @@
 
 AC_PREREQ([2.69])
 AC_INIT([jsonbench], [0.2], [airween@gmail.com])
+AC_USE_SYSTEM_EXTENSIONS
 AC_CONFIG_SRCDIR([config.h.in])
 AC_CONFIG_AUX_DIR([build-aux])
 AC_CONFIG_HEADERS([config.h])
@@ -15,6 +16,7 @@ PKGPATH=$($PKG_CONFIG --variable pc_path pkg-config)
 # Checks for programs.
 AC_PROG_CXX
 AC_PROG_CC
+AC_CHECK_FUNCS([newlocale uselocale freelocale duplocale])
 
 JSONC_CFLAGS=""
 JSONC_LDADD=""
@@ -696,7 +698,7 @@ AC_CHECK_LIB([m], [powl], [], AC_MSG_ERROR([libm is not installed.], 1))
 
 # Checks for library functions.
 
-AC_CONFIG_FILES([Makefile src/Makefile])
+AC_CONFIG_FILES([Makefile src/Makefile tests/Makefile])
 AM_INIT_AUTOMAKE([-Wall -Werror foreign subdir-objects])
 
 AC_MSG_NOTICE([JSON library summary:])