Repository navigation
feat(diagnostics): add strict mode, scanner failures and JSON diagnostics - #245
Conversation
…tics PropertyRecordScanner now records the first malformed length-prefixed string in FailureReason; NwcDocument turns it into an error-level property-scan-stopped diagnostic with stream index and offset. NwcReaderOptions.Strict throws InvalidDataException for error-level diagnostics. Document and assembly JSON export include the diagnostics array. Add strict, scanner and JSON regression tests.
Код-ревью — feat(diagnostics): add strict mode, scanner failures and JSON diagnostics (стек на #243)Вердикт: approve-with-comments Резюме ревьюеров
Подтверждённые замечания (4)1. [СРЕДНЯЯ] Error-диагностика и Strict строятся на эвристике сканера и срабатывают на валидных файлах — FailureReason выставляется внутри TryReadLengthPrefixedString при любом отвергнутом кандидате: сканер по построению скользит по потоку шагом 4 байта (_pos += 4) и продолжает работу после неудачи, а результат второго чтения в case 8 вообще игнорируется ( Уточнение проверяющего: Диагностика property-scan-stopped (Error) строится на эвристическом сканере, который по построению скользит по потоку и отвергает кандидатов. Она срабатывает и для файлов, прочитанных строгим ModelGraphReader (segments != null), и для валидных null-строк (len == -1). Это даёт ложный Error в Diagnostics/JSON/--report, а при явно включённом Strict (по умолчанию false) исключение на корректном файле. Серьёзность medium, потому что Strict opt-in, но ложный Error появляется без него. Сценарий: Валидный Revit .nwc (DbCache-путь), в потоке LcOaPartitionProps которого есть ключ класса 52 с null display-именем: [id][52][-1]["lcBare"] (именно такой кейс keyBare = Username(w, null, "lcBare") принят как валидный в HierarchyParserTests.cs:53), либо свойство типа 4 с null-значением [4][-1] (SyntheticTree: "4,9 string (null writes -1)"). HierarchyParser/ModelGraphReader такой файл читают без ошибок. PropertyRecordScanner на кандидате tag 52 видит len = -1, ставит FailureReason, NwcDocument добавляет Error property-scan-stopped. NwcDocument.Open(path, new NwcReaderOptions { Strict = true }) бросает InvalidDataException "A length-prefixed string at byte N has invalid length -1. Stopped at byte M." на корректном файле. Без Strict файл получает ложный Error в Diagnostics, --report и JSON. Исправление: Не поднимать Error по факту отвергнутого кандидата в сканере с повторным поиском. Минимум: не запускать сканер или не считать его сбой ошибкой, когда segments != null (строгий ридер уже все проверил), трактовать len == -1 как валидный null, понизить сканерную диагностику до Warning. Привязывать Strict только к детерминированным ошибкам формата. 2. [СРЕДНЯЯ] property-scan-stopped: сканер не останавливается, а ByteOffset всегда равен концу потока — PropertyRecordScanner.Scan после неудачного чтения строки не прекращает работу: кандидат отбрасывается, Уточнение проверяющего: Сканер не останавливается на первом сбое, а пропускает кандидата и сканирует поток до конца. StoppedAt всегда равен примерно длине потока, а не позиции дефекта. Диагностика property-scan-stopped из #245 передаёт это значение в текст и в NwcDiagnostic.ByteOffset, поэтому смещение неверно, а слово «Stopped» неточно. Данных это не теряет, это ошибка диагностики (нужна позиция первого сбоя, а код и текст стоит переименовать), поэтому severity medium, а не high. Сценарий: Собственный поток из теста PR: 24 байта [100][86][0][53][-1][0]. Недопустимая длина лежит на байте 16. Трассировка Scan: на байте 8 найден tag 53, чтение строки на 16 даёт len=-1, затем Исправление: Сохранять в сканере позицию первого сбоя и передавать её в NwcDiagnostic.ByteOffset. Переименовать код и текст («property-scan-failed»/«malformed string»), убрать «Stopped at». Либо действительно останавливать скан и тогда оставить StoppedAt. 3. [СРЕДНЯЯ] Error-диагностика и Strict срабатывают на пробных чтениях резинового сканера, который не останавливается —
Уточнение проверяющего: Диагностика Сценарий: Корректный поток [100][86] ... [101][53][-1] ... (узел класса 53 с null-именем, допустимый по грамматике) далее содержит валидные записи 53/52. Сканер на паре (101,53) читает len=-1, ставит 4. [СРЕДНЯЯ] Error по первому неудачному чтению эвристического сканера: ложные ошибки и Strict отвергает валидные модели — FailureReason теперь ставится в любой неудачной TryReadLengthPrefixedString, включая отбрасываемые кандидатов эвристического поиска (в докстринге: «searches forward resiliently»). Такой сбой заведомо не означает потерю данных, но поднимается до Error, а Error запускает исключение в Strict. Сканер при этом работает не только на старых потоках. StreamClassifier.cs:52 относит к SceneTree каждый поток, начинающийся с [100][86]. Корневые потоки LcOaPartitionProps (docs/format-notes.md §2.2.1, первый корень класса 86) именно так и начинаются. ModelGraphReader.Locate их не переклассифицирует, а цикл в NwcDocument.cs:163 идёт и на strict-пути. Строгий HierarchyParser допускает null-строки (-1) в значениях типа 4 и 9 ( Уточнение проверяющего: FailureReason в PropertyRecordScanner ставится при любой неудачной TryReadLengthPrefixedString, включая пробы кандидатов эвристического поиска и null-строки (-1), которые не означают потерю данных. NwcDocument превращает это в Error property-scan-stopped, а при Strict бросает InvalidDataException. Итог: возможны ложные Error и ложные отказы Strict на корректных файлах. Следует фиксировать диагностику только при реальной потере записи и добавить негативный тест. Серьёзность medium: Strict включается опционально, а диагностика ложноположительная, не искажает данные модели. Сценарий: Корневой поток LcOaPartitionProps модели Revit содержит вкладку с параметром типа 4 и значением null (-1; SyntheticTree описывает это как «null writes -1») или с параметром типа 8, у которого Username.Internal = null. Строгий ридер принимает файл. Сканер на case 4 (строка 89) или case 8 (строка 129) получает len=-1 и выставляет FailureReason. Итог: у корректно прочитанной модели Diagnostics содержит Error property-scan-stopped (противоречит критерию #95 «пусто для чисто разобранного файла»), а Исправление: Фиксировать как диагностику только сбои, которые действительно означают потерю записей, например потерю синхронизации внутри уже принятой записи. Сбои проб-кандидатов не должны давать Error. Добавить тест: валидный strict-путь с null-значениями (и RevitSample/SyntheticNwcFile) не создаёт property-scan-stopped и не бросает при Strict = true. |
Accept -1 as a valid null string, report the first malformed probe as a Warning with its real offset, do not emit it on the strict DbCache path, and let Strict open files whose only issue is a rejected heuristic probe.
Completes the remaining #95 scope. Stacked on #243 (
fix/parse-diagnostics-cli).What changed
PropertyRecordScannernow records the first malformed length-prefixed string inFailureReason.NwcDocument.Openturns that into the error-levelproperty-scan-stoppeddiagnostic with the stream index and byte offset.NwcReaderOptions.Strict(default false). When true,NwcDocument.OpenthrowsInvalidDataExceptionif any error-level diagnostic was recorded.JsonExporter.Write) and assembly JSON (NwcAssembly.SaveJson) now include adiagnosticsarray with severity, code, message and optional stream index/offset.DiagnosticsExportTests:property-scan-stopped;Strict = truethrowsInvalidDataException;docs/public-api.mdandCHANGELOG.md.Files
src/NwcIO/Internal/Parsing/PropertyRecordScanner.cssrc/NwcIO/NwcReaderOptions.cssrc/NwcIO/NwcDocument.cssrc/NwcIO/Internal/Json/JsonExporter.cssrc/NwcIO/Model/NwcAssembly.cstests/NwcIO.Tests/DiagnosticsExportTests.csdocs/public-api.md,CHANGELOG.mdTests
dotnet build NwcIO.slnx -c Release— success, 0 warnings, 0 errors.dotnet test NwcIO.slnx -c Release --no-build— full suite passes (exit 0).DiagnosticsExportTests: 3 passed.Remaining limitations
ModelGraphReader) skips are not counted.Strictcurrently depends on error-level diagnostics; onlyproperty-scan-stoppedis error-level today.