Skip to content

feat(diagnostics): add strict mode, scanner failures and JSON diagnostics - #245

Merged
mahach666 merged 4 commits into
mainfrom
fix/parse-diagnostics-strict
Nov 16, 2026
Merged

mahach666 merged 4 commits into
mainfrom
fix/parse-diagnostics-strict

Conversation

@mahach666

Copy link
Copy Markdown
Collaborator

Completes the remaining #95 scope. Stacked on #243 (fix/parse-diagnostics-cli).

What changed

  • PropertyRecordScanner now records the first malformed length-prefixed string in FailureReason.
  • NwcDocument.Open turns that into the error-level property-scan-stopped diagnostic with the stream index and byte offset.
  • Added NwcReaderOptions.Strict (default false). When true, NwcDocument.Open throws InvalidDataException if any error-level diagnostic was recorded.
  • Document JSON (JsonExporter.Write) and assembly JSON (NwcAssembly.SaveJson) now include a diagnostics array with severity, code, message and optional stream index/offset.
  • Added DiagnosticsExportTests:
    • malformed property record produces property-scan-stopped;
    • Strict = true throws InvalidDataException;
    • document and assembly JSON contain the diagnostics.
  • Updated docs/public-api.md and CHANGELOG.md.

Files

  • src/NwcIO/Internal/Parsing/PropertyRecordScanner.cs
  • src/NwcIO/NwcReaderOptions.cs
  • src/NwcIO/NwcDocument.cs
  • src/NwcIO/Internal/Json/JsonExporter.cs
  • src/NwcIO/Model/NwcAssembly.cs
  • tests/NwcIO.Tests/DiagnosticsExportTests.cs
  • docs/public-api.md, CHANGELOG.md

Tests

  • 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

  • Mesh-skip diagnostics still lack stream index/offset, and strict-path (ModelGraphReader) skips are not counted.
  • Other exporters (IFC/GLB/OBJ/HTML) do not include diagnostics; only JSON.
  • Strict currently depends on error-level diagnostics; only property-scan-stopped is error-level today.

…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.
@mahach666

Copy link
Copy Markdown
Collaborator Author

Код-ревью — feat(diagnostics): add strict mode, scanner failures and JSON diagnostics (стек на #243)

Вердикт: approve-with-comments

Резюме ревьюеров

  • correctness: PR добавляет диагностику property-scan-stopped (Error) из PropertyRecordScanner, опцию NwcReaderOptions.Strict (бросает InvalidDataException при любой Error-диагностике) и массив diagnostics в JSON документа и сборки. С точки зрения корректности главный дефект в том, что FailureReason выставляется при любой неудачной пробной (speculative) попытке прочитать строку внутри намеренно отказоустойчивого (resync) сканера, который на самом деле никогда не останавливается. Поэтому Error и Strict срабатывают на штатных данных, а смещение в диагностике указывает на конец потока, а не на место дефекта. Тесты проверяют только заведомо битый поток и не покрывают ни ложные срабатывания, ни значения StreamIndex/ByteOffset.
  • robustness: PR добавляет диагностику property-scan-stopped (Error) из PropertyRecordScanner, опцию NwcReaderOptions.Strict (бросает InvalidDataException при любой Error-диагностике) и массив diagnostics в документном и сборочном JSON. Публичный API расширен обратно совместимо, JSON-вывод экранируется Utf8JsonWriter, инъекций нет. Главная проблема в том, что Error строится из «FailureReason» эвристического сканера с продолжением после ошибки: он срабатывает на валидных данных (null-строка -1, строки больше 64 КиБ) и на ложных кандидатах, из-за чего Strict ломает открытие корректных файлов. Само сообщение и ByteOffset описывают «остановку», которой нет, а тесты это не ловят (нет контрольного теста на валидном файле и нет проверки streamIndex/byteOffset).
  • tests-claims: PR добавляет диагностику property-scan-stopped (Error), опцию NwcReaderOptions.Strict и блок diagnostics в JSON документа и сборки. С точки зрения заявлений и тестов качество низкое. Диагностика называет «остановкой» то, чего сканер не делает, а ByteOffset всегда равен концу потока. Error выставляется по первому неудачному чтению в эвристическом сканере, так что Strict может отвергать валидные файлы. Три теста проверяют только наличие подстрок и тип исключения, а негативных и граничных сценариев нет.

Подтверждённые замечания (4)

1. [СРЕДНЯЯ] Error-диагностика и Strict строятся на эвристике сканера и срабатывают на валидных файлах — src/NwcIO/NwcDocument.cs:167 (robustness; уверенность high; проверка: trace:подтвердил, intent:подтвердил)

FailureReason выставляется внутри TryReadLengthPrefixedString при любом отвергнутом кандидате: сканер по построению скользит по потоку шагом 4 байта (_pos += 4) и продолжает работу после неудачи, а результат второго чтения в case 8 вообще игнорируется (TryReadLengthPrefixedString(ref pNext, out _)). Одновременно len == -1 считается «invalid length», хотя docs/format-notes.md (§1, §2.2) и LcObjectReader.ReadString определяют -1 как валидную null-строку, а лимит 65536 не существует в строгом ридере. Сканер запускается и для файлов, прочитанных через DbCache (segments != null), где потоки LcOaPartitionProps начинаются с [100][86] и классифицируются как SceneTree. Эти же файлы строгий ModelGraphReader читает без ошибок, но теперь получают Error-диагностику, а при Strict = true исключение. Это нарушает правило 1 владельца: эвристический признак «кандидат отвергнут» выдан за детерминированную ошибку формата.

Уточнение проверяющего: Диагностика 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.

if (scanner.FailureReason is not null)
{
    diagnostics.Add(new NwcDiagnostic(
        NwcDiagnosticSeverity.Error,
        "property-scan-stopped",

Исправление: Не поднимать Error по факту отвергнутого кандидата в сканере с повторным поиском. Минимум: не запускать сканер или не считать его сбой ошибкой, когда segments != null (строгий ридер уже все проверил), трактовать len == -1 как валидный null, понизить сканерную диагностику до Warning. Привязывать Strict только к детерминированным ошибкам формата.

2. [СРЕДНЯЯ] property-scan-stopped: сканер не останавливается, а ByteOffset всегда равен концу потока — src/NwcIO/NwcDocument.cs:172 (claims-vs-code; уверенность high; проверка: trace:подтвердил, intent:подтвердил)

PropertyRecordScanner.Scan после неудачного чтения строки не прекращает работу: кандидат отбрасывается, _pos += 4, цикл идёт до конца данных, а все следующие записи декодируются. Поэтому StoppedAt всегда лежит в пределах 7 байт от длины потока. Диагностика получает StoppedAt в текст и в ByteOffset, хотя реальная позиция дефекта известна только внутри FailureReason. Код property-scan-stopped, текст «Stopped at byte N», CHANGELOG, docs/public-api.md («a property scan that stopped on a malformed record») и тело PR («byte offset») описывают то, чего не происходит. Условие «scan stops before the end of a stream» из #95 для этого сканера невыполнимо.

Уточнение проверяющего: Сканер не останавливается на первом сбое, а пропускает кандидата и сканирует поток до конца. 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, затем _pos идёт 12, 16, 20 и цикл выходит. Итог: Message = «A length-prefixed string at byte 16 has invalid length -1. Stopped at byte 20.», ByteOffset = 20. В потоке 5 МБ с дефектом на байте 16 ByteOffset будет около 5 000 000, а сообщение скажет, что скан «остановился» там, хотя все записи после дефекта попали в PropertyRecords. Потребитель JSON/--report получает неверное смещение и ложное утверждение о потере данных.

$"{scanner.FailureReason} Stopped at byte {scanner.StoppedAt}.",
s.Index,
scanner.StoppedAt));

Исправление: Сохранять в сканере позицию первого сбоя и передавать её в NwcDiagnostic.ByteOffset. Переименовать код и текст («property-scan-failed»/«malformed string»), убрать «Stopped at». Либо действительно останавливать скан и тогда оставить StoppedAt.

3. [СРЕДНЯЯ] Error-диагностика и Strict срабатывают на пробных чтениях резинового сканера, который не останавливается — src/NwcIO/Internal/Parsing/PropertyRecordScanner.cs:192 (correctness; уверенность medium; проверка: trace:подтвердил, intent:подтвердил)

Scan() просматривает поток каждые 4 байта и пробует разобрать любую пару (x, 52|53) как запись; при неудаче делает _pos += 4 и идёт дальше (строка 170). Теперь TryReadLengthPrefixedString записывает FailureReason при любой неудаче такой пробы (строки 185 и 192), хотя сканер после неё успешно ресинхронизируется и разбирает все последующие записи. Диагностика property-scan-stopped с уровнем Error и Strict не отличают реальный сбой от ложного совпадения. Формат допускает -1 как null-строку (docs/format-notes.md, 2.2, Primitives), а StreamClassifier относит к SceneTree любой поток, начинающийся с [100][86] или содержащий LcRevit в первых 256 байтах. Это, в частности, потоки LcOaPartitionProps. На strict-path (DbCache) записи этого сканера не используются для построения дерева (SceneTreeBuilder.Build вызывается только при segments is null), а format-notes называют такой скан устаревшим. При этом отказ пробы теперь рушит Open под Strict.

Уточнение проверяющего: Диагностика property-scan-stopped (Error) формируется по FailureReason, который выставляется при любой неудачной пробной записи резинового сканера, хотя сканер после неё продолжает работу (_pos += 4) и не "останавливается". В результате без реального сбоя в NwcDocument.Diagnostics появляется ложный Error, а при NwcReaderOptions.Strict = true Open бросает InvalidDataException. Strict выключен по умолчанию, поэтому серьёзность medium, а не high. Диагностика вводит в заблуждение и ломает именно opt-in Strict-режим. Для DbCache-пути, где записи сканера не нужны, это особенно нежелательно.

Сценарий: Корректный поток [100][86] ... [101][53][-1] ... (узел класса 53 с null-именем, допустимый по грамматике) далее содержит валидные записи 53/52. Сканер на паре (101,53) читает len=-1, ставит FailureReason, сдвигается на 4 байта и разбирает все остальные записи без потерь. NwcDocument.Open всё равно добавляет Error property-scan-stopped (в --report и в JSON), а Open(..., new NwcReaderOptions { Strict = true }) бросает InvalidDataException на файле, который ModelGraphReader читает без ошибок. То же происходит при любом постороннем (x,52|53), за которым следует отрицательное число или значение больше 65536.

FailureReason ??= $"A length-prefixed string at byte {pos} has invalid length {len}.";

4. [СРЕДНЯЯ] Error по первому неудачному чтению эвристического сканера: ложные ошибки и Strict отвергает валидные модели — src/NwcIO/NwcDocument.cs:167 (correctness; уверенность medium; проверка: trace:подтвердил, intent:подтвердил)

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 (4 or 9 => _reader.ReadString()), а Username.Display и Username.Internal объявлены string?. Сканер же на -1 даёт «invalid length -1», в том числе на строке 129, где результат чтения refClass игнорируется. Негативного теста («валидный поток не даёт диагностики; Strict не бросает») нет.

Уточнение проверяющего: 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 «пусто для чисто разобранного файла»), а Open(path, new NwcReaderOptions { Strict = true }) бросает InvalidDataException. Офлайн-повтор логики сканера на потоке такой формы даёт ту же ошибку («invalid length -1»).

if (scanner.FailureReason is not null)
...
NwcDiagnosticSeverity.Error,
"property-scan-stopped",

Исправление: Фиксировать как диагностику только сбои, которые действительно означают потерю записей, например потерю синхронизации внутри уже принятой записи. Сбои проб-кандидатов не должны давать 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.
@mahach666
mahach666 changed the base branch from fix/parse-diagnostics-cli to main November 16, 2026 20:23
@mahach666
mahach666 merged commit 81732bc into main Nov 16, 2026
5 checks passed
@mahach666
mahach666 deleted the fix/parse-diagnostics-strict branch November 17, 2026 23:41
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant