Skip to content

feat(diagnostics): report skipped meshes and print diagnostics in --report - #243

Merged
mahach666 merged 2 commits into
mainfrom
fix/parse-diagnostics-cli
Nov 16, 2026
Merged

mahach666 merged 2 commits into
mainfrom
fix/parse-diagnostics-cli

Conversation

@mahach666

Copy link
Copy Markdown
Collaborator

Completes the CLI and mesh-skip parts of #95. Stacked on #232 (fix/parse-diagnostics).

What changed

  • MeshParser.Parse now has an overload that returns the number of skipped geometry records. Both the TOC and heuristic paths count out-of-range/malformed records; the fallback scan resets the counter so the same record is not counted twice.
  • NwcDocument.Open turns that count into the meshes-skipped diagnostic and merges it with ContainerTrailingGap into NwcDocument.Diagnostics.
  • nwcio --report prints Diagnostics: N plus [Severity] Code: message for:
    • single documents (NwcIO Execution Report),
    • folder assemblies (NwcIO Assembly Report),
    • .nwf assemblies (NwcIO NWF Assembly Report).
  • Added regression tests:
    • Parse_OutOfRangeVertexCount_ReportsSkippedRecord;
    • Open_OutOfRangeVertexCount_ReportsMeshesSkippedDiagnostic;
    • Report_PrintsDocumentDiagnostics (appends an unknown tail and checks ContainerTrailingGap on stderr).
  • Documented NwcDiagnostic and the diagnostics in docs/public-api.md and CHANGELOG.md.

Files

  • src/NwcIO/Internal/Parsing/MeshParser.cs
  • src/NwcIO/NwcDocument.cs
  • src/NwcIO.Cli/Program.cs
  • tests/NwcIO.Tests/MeshParserTests.cs
  • tests/NwcIO.Tests/CliArgumentValidationTests.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).
  • Diagnostics filter: 3 passed (parser count, document diagnostic, CLI --report).

Remaining limitations

  • The property-record scanner's stop/failure state is still not surfaced.
  • Diagnostics are not written to JSON export.
  • NwcReaderOptions.Strict (throw on error-level diagnostics) is not implemented.
  • Mesh-skip diagnostics carry no stream index or byte offset.
  • Skip counts from the strict DbCache path (ModelGraphReader) are not included; only MeshParser.

…eport

Add a MeshParser overload that counts skipped geometry records, turn that count into the NwcDocument meshes-skipped diagnostic, and merge it with the container trailing-gap diagnostic. Print NwcDocument/NwcAssembly diagnostics in the single-file, folder and .nwf --report paths. Add parser, document and CLI regression tests.
@mahach666

Copy link
Copy Markdown
Collaborator Author

Код-ревью — feat(diagnostics): report skipped meshes and print diagnostics in --report (стек на #232)

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

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

  • correctness: PR добавляет перегрузку MeshParser.Parse(..., out int skippedRecords), превращает счётчик в диагностику meshes-skipped в NwcDocument.Open, объединяет её с ContainerTrailingGap и печатает NwcDocument.Diagnostics/NwcAssembly.Diagnostics в nwcio --report (три места). С точки зрения корректности основная проблема в самом счётчике. Сброс skippedRecords перед эвристическим fallback выбрасывает точный подсчёт TOC-пути, а эвристический путь не видит усечённые или переразмеренные записи (в том числе фикстуру существующего теста Open_MalformedTocRecord_SkipsMesh). Он же считает любое выровненное int32 == 60 «пропущенной геометрией». Новые тесты проходят только через fallback и не проверяют счётчики TOC-пути. Обратная совместимость сохранена: старая сигнатура Parse осталась, мёртвый блок в Create безопасно удалён.
  • robustness: PR добавляет в MeshParser перегрузку со счётчиком пропущенных геометрических записей, превращает его в диагностику meshes-skipped в NwcDocument.Open, переносит ContainerTrailingGap из мёртвого кода в Create в живой Open и печатает диагностики в трёх вариантах --report. Публичный контракт не ломается (старая перегрузка Parse сохранена, MeshParser и так относится к "public but unsupported"), исключения и коды выхода не меняются. С точки зрения надёжности счётчик ненадёжен: при откате на эвристический скан он сбрасывает TOC-счёт (часть усечённых записей молча теряется) и считает любое int32 == 60 в любом потоке геометрической записью. Новые тесты проходят только за счёт эвристического fallback и не проверяют заявленный TOC-счёт; два из трёх мест печати в CLI тестами не покрыты, а в отчёте NWF часть записей теперь дублируется.
  • tests-claims: PR добавляет перегрузку MeshParser.Parse с out-счётчиком пропущенных записей, диагностику meshes-skipped и ContainerTrailingGap в NwcDocument.Open (заодно убирая мёртвый код из Create) и вывод диагностик в трёх вариантах nwcio --report. Реализация простая и в основном соответствует описанию, но заявление «оба пути (TOC и эвристика) считают пропущенные записи» выполняется не полностью: счётчик TOC сбрасывается при фолбэке, а эвристика не считает усечённые записи и, наоборот, считает любой случайный int32 == 60. Тесты по линзе слабые: единственный парсерный тест проходит и без инкрементов в TOC-пути, а для сборок (папка, NWF) и для «чистый файл — нет диагностик» тестов нет; в отчёте NWF ссылки теперь выводятся дважды.

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

1. [СРЕДНЯЯ] Новые тесты счёта пропусков проходят только за счёт эвристического fallback и не проверяют TOC-путь — tests/NwcIO.Tests/MeshParserTests.cs:80 (test-coverage; уверенность high; проверка: trace:подтвердил, intent:подтвердил)

PR заявляет, что счёт ведут и TOC-путь, и эвристический путь. В обоих новых тестах (Parse_OutOfRangeVertexCount_ReportsSkippedRecord и Open_OutOfRangeVertexCount_ReportsMeshesSkippedDiagnostic) единственная запись [0,94,0,60,1,0,0,0] даёт в ParseViaToc vCount = -1 (p2 = 0, p1 = 1 > (24-24)/12), то есть TOC-счётчик становится 1. Но meshes.Count == 0, поэтому Parse обнуляет skippedRecords = 0 и запускает ParseViaHeuristicScan, который на смещении i = 8 видит tag 60 и vCount = 1 и снова даёт 1. Итоговая единица получена целиком из эвристического скана. Оба skippedRecords++ в ParseViaToc можно удалить, и оба теста останутся зелёными. Сценарий, где TOC-счёт реально виден (TOC нашёл хотя бы один валидный mesh и пропустил другую запись), не покрыт; не покрыты и вызовы PrintDiagnostics для папочной сборки и .nwf (проверен только одиночный документ), и отсутствие шума (пустой список ничего не печатает).

Уточнение проверяющего: Замечание верно по сути, но это пробел в тестовом покрытии, а не дефект поведения. Оба новых теста проходят за счёт эвристического fallback, а счётчики TOC-пути (MeshParser.cs:168, 173) ничем не проверены. Сценарий «TOC нашёл валидный mesh и пропустил другую запись» (fallback не запускается) не покрыт. Не покрыты и CLI-вывод Diagnostics: для папочной сборки и .nwf. Высокая серьёзность завышена, так как продуктовый код корректен, поэтому оценка medium.

Сценарий: Удалить оба skippedRecords++ из ParseViaToc (или сломать условие vCount >= MinMeshVertices && vCount <= MaxPlausibleVertices): все новые тесты остаются зелёными, хотя TOC-путь перестал считать. Файл с двумя валидными TOC-записями и одной с p1 = 1 после удаления счётчика вернёт skipped = 0 без единого упавшего теста. Для двух тестов, которые заявлены как регрессионные для TOC-пути, это не то, что они проверяют.

var meshes = MeshParser.Parse(container, null, out int skipped);

Assert.Empty(meshes);
Assert.Equal(1, skipped);

Исправление: Добавить тест в стиле Parse_LastTocRecordWithOverlongLength_ParsesVerticesThatFit: одна валидная запись плюс одна с недопустимым числом вершин (fallback не запускается), ожидать skipped == 1 и 1 mesh. Добавить CLI-тесты --report для ProcessAssemblyDirectory и ProcessNwfAssembly и проверку, что без диагностик строка Diagnostics: не печатается.

Независимо нашли также: correctness

2. [СРЕДНЯЯ] Parse_OutOfRangeVertexCount_ReportsSkippedRecord не проверяет подсчёт в TOC-пути — tests/NwcIO.Tests/MeshParserTests.cs:80 (test-quality; уверенность high; проверка: trace:подтвердил, intent:подтвердил)

В тесте нет ни одного валидного меша, поэтому после TOC-прохода meshes.Count == 0, счётчик обнуляется (MeshParser.cs:46) и итог 1 даёт эвристический скан: на i=8 он видит 60 на смещении 12 и vCount=1 (<3). Инкременты, добавленные в ParseViaToc (стр. 166-174), тестом не покрыты: их можно удалить, и тест останется зелёным. Рядом (стр. 27 того же файла) автор сам отмечает, что «The first mesh prevents heuristic fallback from masking a skipped final record» — новый тест этот приём не использует. Тест Open_..._ReportsMeshesSkippedDiagnostic идёт тем же путём и проверяет только подстроку «geometry records were skipped», не число. Граничные случаи (NaN/Inf-координата, усечённая запись, vCount > 200000, смесь валидных и пропущенных записей, отсутствие диагностики на чистом файле) не проверяются.

Уточнение проверяющего: Описание в целом точное. Уточнение: проблема только в тестовом покрытии, ошибки в продуктовом коде нет. Тесты не покрывают счёт пропусков в ParseViaToc (MeshParser.cs:168 и 173), потому что эвристический откат при meshes.Count == 0 даёт тот же результат 1. Часть перечисленных граничных случаев (NaN/Inf, усечённая запись, vCount > 200000) является расширением просьбы, а не дефектом самого теста. Основной пробел — отсутствие кейса «валидный меш + пропущенная запись», где ожидается meshes.Count == 1 и skipped == 1.

Сценарий: Удаляем оба else { skippedRecords++; } в ParseViaToc: для chunk (0,94,0,60,1,0,0,0) эвристика всё равно насчитывает 1, и Parse_OutOfRangeVertexCount_ReportsSkippedRecord и Open_OutOfRangeVertexCount_ReportsMeshesSkippedDiagnostic проходят. Ошибка подсчёта в TOC-пути при наличии хотя бы одного валидного меша (реальный сценарий для частично битого файла) остаётся незамеченной.

var meshes = MeshParser.Parse(container, null, out int skipped);

Assert.Empty(meshes);
Assert.Equal(1, skipped);

Исправление: Добавить кейс: первая запись валидна (как в Parse_LastTocRecordWithOverlongLength...), вторая с p1/p2 вне диапазона, Assert: meshes.Count == 1 и skipped == 1; в Open-тесте проверять число в сообщении и Severity; добавить тест «корректный файл -> Assert.Empty(Diagnostics)».

3. [НИЗКАЯ] Сброс счётчика перед fallback теряет TOC-пропуски; усечённая запись не даёт диагностики — src/NwcIO/Internal/Parsing/MeshParser.cs:46 (correctness; уверенность high; проверка: trace:подтвердил, intent:подтвердил)

Если TOC-путь не нашёл ни одного меша, skippedRecords обнуляется и заменяется счётчиком эвристического сканера. Эвристика не считает запись, чей заявленный vCount не помещается в поток (ветка if (i + 16 + vBytes > data.Length) { continue; }, строки 212-215, без skippedRecords++). TOC-путь такие записи считает (vCount = -1 уходит в else и даёт skippedRecords++), но этот верный счёт выбрасывается. Итог зависит от того, нашёлся ли в файле хотя бы один валидный меш: усечённая запись рядом с валидной даёт предупреждение, а в одиночку молча пропадает. Комментарий в существующем тесте Parse_LastTocRecordWithOverlongLength_ParsesVerticesThatFit («first mesh prevents heuristic fallback from masking a skipped final record») показывает, что автор знает об этом маскировании.

Уточнение проверяющего: Утверждение верно: при нуле мешей из TOC счётчик пропусков заменяется счётом эвристики. Эвристика не считает запись, чей vCount в допустимом диапазоне, но не помещается в поток. Поэтому одиночная усечённая запись (например, вход (100, 0, 1224)) даёт 0 мешей без диагностики meshes-skipped, хотя TOC-путь её посчитал. Проблема только в полноте диагностики, потери данных нет. Серьёзность low, а не medium: затронут узкий случай, а Open по-прежнему возвращает пустой набор мешей.

Сценарий: Берём вход существующего теста Open_MalformedTocRecord_SkipsMesh(100, 0, 1224): chunk = int32[0,94,0,60,100,0,0,0], toc = [1,1,32,1224]. ParseViaToc: rLen = min(1224, 32) = 32, p1 = 100 не влезает в (32-24)/12 = 0, vCount = -1, skippedRecords = 1. Мешей 0, поэтому счётчик обнуляется. Эвристика на i = 8 видит tag = 60, vCount = 100 (в диапазоне), но 8+16+1200 > 32 и делает continue без счёта. Итог: NwcDocument.Open возвращает 0 мешей и в Diagnostics нет meshes-skipped, хотя геометрическая запись отброшена как malformed. nwcio --report ничего не покажет.

skippedRecords = 0;
ParseViaHeuristicScan(container, meshes, transforms, ref skippedRecords);

Исправление: Не затирать TOC-счёт: либо считать в эвристике и записи, не влезающие в поток, и не сбрасывать счётчик, либо оставить max(TOC-счёт, эвристический счёт) и покрыть тестом случай (100, 0, 1224).

4. [НИЗКАЯ] Сброс skippedRecords при откате на эвристику теряет TOC-счёт: усечённые записи по-прежнему пропадают без диагностики — src/NwcIO/Internal/Parsing/MeshParser.cs:46 (silent-failure; уверенность high; проверка: trace:подтвердил, intent:подтвердил)

Если TOC не дал ни одного mesh, счётчик обнуляется и считает только эвристический скан. В эвристике ветка i + 16 + vBytes > data.Length делает continue без инкремента, то есть усечённая запись (число вершин в допустимом диапазоне, но байт меньше заявленного) не считается. TOC-путь такую запись считал (vCount = -1), но этот счёт отброшен. Итог: самый типичный вид повреждения (обрезанный файл или запись) всё так же молча теряет геометрию, ради чего диагностика и вводилась. Утверждение в PR, что обе ветки считают malformed-записи, неверно для этого случая. Также не считаются ранние return в ParseViaToc (отвергнутый TOC, chunkCount > 5000, переполнение) и break при rLen < 0.

Уточнение проверяющего: Утверждение подтверждается для усечённых записей: при откате на эвристику счёт TOC-пути (в том числе усечённые записи, vCount = -1) отбрасывается, а эвристика усечённые кандидаты (стр. 212-215) не считает. В результате meshes-skipped не появляется для обрезанного файла без других mesh. Это пробел в новой диагностике, а не регрессия извлечения геометрии. Ранние return в ParseViaToc (отвергнутый TOC, chunkCount > 5000) и break при rLen < 0 тоже не считаются, но они описывают отказ от всего TOC, а не пропуск записи. Серьёзность низкая: диагностика неполна, данные не искажаются.

Сценарий: Берём уже существующую тестовую запись Open_MalformedTocRecord_SkipsMesh [InlineData(100, 0, 1224)]: chunk [0,94,0,60,100,0,0,0], TOC [1,1,32,1224]. TOC-путь: rLen = 32, p1 = 100 > (32-24)/12, vCount = -1, skippedRecords = 1. Mesh нет, счёт сбрасывается в 0; эвристика на i = 8 видит tag 60, vCount = 100 в диапазоне, i + 16 + 1200 > 32, continue без счёта. Результат: Meshes пуст, Diagnostics не содержит meshes-skipped, --report ничего не печатает. Если перед этой записью стоит один валидный mesh, диагностика появляется: поведение зависит от посторонней записи.

// The fallback replaces the TOC attempt, so do not count the same record twice.
skippedRecords = 0;
ParseViaHeuristicScan(container, meshes, transforms, ref skippedRecords);

Исправление: Не сбрасывать счёт молча: считать пропуски TOC-пути отдельно и брать максимум с эвристическим, либо считать в эвристике и усечённые кандидаты (ветку continue при выходе за конец данных), и фиксировать, что TOC отвергнут целиком, отдельной диагностикой.

@mahach666
mahach666 changed the base branch from fix/parse-diagnostics to main November 16, 2026 19:54
Re-apply meshes-skipped on top of MaxMeshVertices and transform-link parsing: the skipped count no longer drops TOC-path skips or ignores truncated records, the diagnostic names the configured cap, ContainerTrailingGap stays as on main, and the --report diagnostics print does not repeat NWF reference warnings. Add TOC-path, truncation, clean-file and CLI folder/manifest tests.
@mahach666
mahach666 merged commit 49fb067 into main Nov 16, 2026
7 of 8 checks passed
@mahach666
mahach666 deleted the fix/parse-diagnostics-cli 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