Closes #13

tests/README.md

@@ -54,6 +54,17 @@ found; insufficient payloads are checked through signal validity.
 
 ## Parser coverage
 
+Structured diagnostic tests cover severity, code, supplied path, and physical
+line numbers for skipped syntax and immediate/deferred errors; warnings preceding
+an error are retained, and failed parses return an empty database. Common headers
+and namespace symbol lists stay quiet. Tests also check file-open errors, fresh
+parse sessions, and compatibility with the legacy throwing API.
+The diagnostic audit also covers 15 unsupported-statement variants, all namespace
+termination forms, CRLF and missing final newlines, relative paths with spaces,
+first-error stopping, deferred diagnostic ordering, duplicate definitions/values,
+selector ranges, overlaps, and preservation of supported decoding and metadata.
+On Linux, reading a directory exercises the distinct `FileReadError` path.
+
 Parser tests cover standard and extended CAN IDs, whitespace, payload storage
 boundaries, missing fields, malformed and overflowing numbers, reserved ID bits,
 error paths and line numbers, and integration with signals and comments.