Skip to content

refactor(cli): merge folder and NWF assembly pipelines - #246

Merged
mahach666 merged 3 commits into
mainfrom
fix/assembly-pipeline-merge
Nov 16, 2026
Merged

mahach666 merged 3 commits into
mainfrom
fix/assembly-pipeline-merge

Conversation

@mahach666

Copy link
Copy Markdown
Collaborator

Fixes #102. Stacked on #234 (fix/nwf-pipeline-report).

What changed

  • Extracted one ProcessAssembly(NwcAssembly, …) method that owns the assembly export, clash, TimeLiner, profiler, raycast and report steps.
  • ProcessAssemblyDirectory now only computes the folder default output, loads NwcAssembly.LoadFromDirectory, and calls ProcessAssembly(..., isNwf: false).
  • ProcessNwfAssembly now only computes the .nwf default output and calls ProcessAssembly(..., isNwf: true); the shared method loads NwcAssembly.OpenNwf when no assembly is preloaded.
  • Report labels are preserved: NwcIO Assembly Report with Assembly:/Models: for folders, NwcIO NWF Assembly Report with NWF File:/Loaded Models: for .nwf. The summary line keeps Assembly vs NWF Assembly.
  • Default output paths are unchanged (<dir>/<dirname>_assembly.glb and <nwf>.glb).
  • Added AssemblyPipelineTests.FolderAndNwf_UseTheSameReportPipeline, which runs both inputs with --report --bvh-stats and checks the respective headings, Total Materials: and BVH Nodes:.

Files

  • src/NwcIO.Cli/Program.cs
  • tests/NwcIO.Tests/AssemblyPipelineTests.cs
  • 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).
  • AssemblyPipelineTests: 1 passed.

Remaining limitations

  • The shared method still takes the long explicit-path parameter list; grouping them into an options record remains a follow-up.
  • The change is a refactor; no new CLI options were added.

Use one ProcessAssembly(NwcAssembly, ...) implementation for both inputs. The folder path only loads NwcAssembly.LoadFromDirectory; the .nwf path only loads NwcAssembly.OpenNwf and computes its default output. Report headers, labels, default output paths and exports stay unchanged; add a regression test that runs both inputs with --report --bvh-stats.
Record that folder and .nwf inputs now use the same ProcessAssembly implementation.
@mahach666

Copy link
Copy Markdown
Collaborator Author

Код-ревью — refactor(cli): merge folder and NWF assembly pipelines (стек на #234)

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

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

  • correctness: PR сводит две копии конвейера (папка и .nwf) в один ProcessAssembly и оставляет в обёртках только вычисление пути вывода по умолчанию и загрузку сборки для папки. Я сравнил тела обоих методов на базе fix(cli): report materials and BVH stats for NWF assemblies #234 через diff: они различались только загрузчиком, путём по умолчанию и заголовком отчёта. Общий метод это сохраняет: пути по умолчанию, ярлыки отчёта и строка итога совпадают с прежними, XRef-предупреждения для папки пусты (UnresolvedXRefs/SkippedXRefs заполняет только OpenNwf), исключения по-прежнему ловятся в try в Run. Логических ошибок в изменённом коде я не нашёл. Замечания касаются неточного CHANGELOG и того, что тест не проверяет заявленную неизменность путей вывода по умолчанию.
  • robustness: PR сливает два почти идентичных тела ProcessAssemblyDirectory и ProcessNwfAssembly в один приватный ProcessAssembly(...) в src/NwcIO.Cli/Program.cs; публичный API, коды возврата и обработка исключений в Main не затронуты. Я сравнил удалённое тело папки с телом NWF на базе fix(cli): report materials and BVH stats for NWF assemblies #234: различия только в заголовке отчёта, строках Assembly:/Models: против NWF File:/Loaded Models:, предупреждениях по xref (для папки списки пусты) и в префиксе итоговой строки, так что поведение сохранено, порядок позиционных аргументов в обоих вызовах совпадает с сигнатурой. Рефакторинг чистый, с точки зрения надёжности, безопасности и совместимости регрессий нет; замечания касаются слабой проверки заявленных инвариантов тестами и неточного описания в CHANGELOG.
  • tests-claims: PR сливает два почти одинаковых конвейера ProcessAssemblyDirectory и ProcessNwfAssembly в один ProcessAssembly. Я сверил тела обоих методов на базе fix(cli): report materials and BVH stats for NWF assemblies #234 и на голове PR: по коду это честный перенос тела NWF-метода, поведение сохранено, а xref-предупреждения для папки всегда пусты. Основные замечания связаны с линзой «тесты и заявления»: единственный новый тест проверяет только наличие подписей на пустой модели и проходит и на базе fix(cli): report materials and BVH stats for NWF assemblies #234, часть заявленных инвариантов (путь вывода по умолчанию, строка-итог, предупреждения о xref) не покрыта, а запись в CHANGELOG описывает сигнатуру и разделение загрузки не так, как реализовано.

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

1. [НИЗКАЯ] Тест не проверяет заявленную неизменность путей вывода по умолчанию — tests/NwcIO.Tests/AssemblyPipelineTests.cs:19 (test-coverage; уверенность high; проверка: trace:подтвердил, intent:подтвердил)

В PR и в CHANGELOG заявлено, что пути вывода по умолчанию не изменились (

/_assembly.glb для папки и .glb для .nwf). Эта логика осталась в обёртках ProcessAssemblyDirectory (Program.cs:1040-1043) и ProcessNwfAssembly (Program.cs:1411-1414) и дальше передаётся в общий метод как outputPath!. Новый тест в обоих запусках передаёт явный второй аргумент (folder.json и nwf.json), поэтому ветка с путём по умолчанию не выполняется. Других тестов на неё тоже нет: git grep по tests/ на _assembly и ChangeExtension ничего не находит. Вторая слабость: для .nwf проверяется только подстрока Loaded Models:, а не число компонентных файлов, так что вспомогательный WriteNwfWithXRefs мог бы не разрешить ссылку на a.nwc и тест всё равно прошёл бы.

Уточнение проверяющего: Тест FolderAndNwf_UseTheSameReportPipeline не покрывает пути вывода по умолчанию (оба запуска передают явный выходной файл) и для .nwf проверяет только наличие подстроки Loaded Models:, а не число загруженных файлов. Это пробел покрытия рефакторинга, а не регрессия: логика путей по умолчанию PR не менялась, а только перенесена в обёртки.

Сценарий: Если в ProcessNwfAssembly заменить Path.ChangeExtension(nwfPath, ".glb") на другое выражение или в ProcessAssemblyDirectory испортить имя _assembly.glb, все тесты останутся зелёными: запуск nwcio fed.nwf без выходного аргумента и nwcio <dir> без выходного аргумента никто не проверяет. Пользовательский вывод по умолчанию изменится незаметно, хотя критерий приёмки issue #102 требует его сохранить. Аналогично, если разрешение XRef в тестовом .nwf сломается, придёт предупреждение unresolved reference, а Loaded Models: всё равно напечатается и проверка пройдёт.

var folder = Run([directory, Path.Combine(directory, "folder.json"), "--report", "--bvh-stats"]);
...
var nwfRun = Run([nwf, Path.Combine(directory, "nwf.json"), "--report", "--bvh-stats"]);

Исправление: Добавить в тест запуски без выходного аргумента для папки и .nwf и проверить существование _assembly.glb и fed.glb. Для .nwf проверить строку Loaded Models: 2 (component files: 1) и отсутствие Warning: unresolved reference.

2. [НИЗКАЯ] Заявленная метка итоговой строки (Assembly и NWF Assembly) не закреплена ни одним тестом — src/NwcIO.Cli/Program.cs:1363 (test-coverage; уверенность high; проверка: trace:подтвердил, intent:подтвердил)

PR утверждает, что итоговая строка сохраняет различие Assembly и NWF Assembly, и вводит для этого тернарный оператор по isNwf. Новый тест AssemblyPipelineTests.FolderAndNwf_UseTheSameReportPipeline всегда запускается с --report, поэтому ветка с итоговой строкой в нём не исполняется. Единственный существующий тест для папки (CliStdoutJsonTests.ExportFolderToStdout_...) проверяет Assert.Contains("Assembly '", errText), а эта подстрока входит и в NWF Assembly '. Для папки метка Assembly фактически нигде не проверяется.

Уточнение проверяющего: Для входа-папки без --report метка "Assembly" проверяется нестрого: Assert.Contains("Assembly '") проходит и на "NWF Assembly '". Для .nwf метка закреплена тестом CliStdoutJsonTests.cs:240. Пробел касается только папки, а не обеих меток.

Сценарий: ProcessAssemblyDirectory или само выражение начнёт выдавать NWF Assembly 'dir': 1 models ... для входа-папки без --report (например, isNwf перепутан в этом выражении или остался дефолт isNwf = true). ExportFolderToStdout_ProducesPureValidJsonAndDirectsSummaryToStderr останется зелёным, потому что "Assembly '" содержится в "NWF Assembly '", и новый тест тоже зелёный, потому что работает только через --report. Скрипты, разбирающие stderr, получат неверную метку, а CI этого не заметит.

$"{(isNwf ? "NWF Assembly" : "Assembly")} '{assembly.Name}': {assembly.Models.Count} models, ...

Исправление: Добавить в новый тест прогон без --report и проверить, что stderr/stdout для папки начинается с Assembly ' и не содержит NWF Assembly, а для .nwf содержит NWF Assembly '. Либо усилить существующий folder-тест до Assert.StartsWith/DoesNotContain("NWF").

3. [НИЗКАЯ] Тест проверяет только подписи на пустой модели, а не поведение слитого конвейера — tests/NwcIO.Tests/AssemblyPipelineTests.cs:32 (test-quality; уверенность high; проверка: trace:подтвердил, intent:подтвердил)

Фикстура строится из NwcDocument.Create() без мешей и материалов, а все ассерты — Assert.Contains на текст подписи. Значения (Total Materials, BVH Nodes, число загруженных моделей) не проверяются. Тест не доказывает, что компонент .nwf реально разрешился. Против базы #234 тест проходит без изменений, так как подписи и блоки BVH/Total Materials там уже были в теле NWF-метода.

Уточнение проверяющего: Тест является дымовым: он проверяет только наличие подписей отчёта на пустой модели. Он не ловит регрессии значений (Models.Count - 1, NodeCount, число материалов), не подтверждает, что xref в .nwf разрешился, и не доказывает слияние конвейеров, потому что проходит и против базы #234. Папочный и NWF-сценарии объединены в один [Fact]. Вывод о том, что BVH-статистика не исполняется при пустой модели, верен, но следствие у него умеренное.

Сценарий: Пустой документ даёт AllMeshes.Count == 0, и NwcSpatialIndex (конструктор строит дерево только при _entries.Length > 0) печатает «BVH Nodes: 0 (0 leaves, max depth 0)», то есть статистика BVH не исполняется. Если в слитом методе подменить значения (например, напечатать LeafCount вместо NodeCount) или потерять Models.Count - 1 в NWF-ветке, тест останется зелёным. Если xref в fed.nwf не разрешится (TryResolve вернёт false), отчёт напечатает «Loaded Models: 1 (component files: 0)» плюс «Warning: unresolved reference», и тест всё равно пройдёт: нет ассерта на «Loaded Models: 2 (component files: 1)» и на отсутствие предупреждения. Папочный запуск не проверяет строку «Models:». Оба сценария к тому же склеены в один [Fact]: падение первого скроет второй.

NwcDocument.Create().Save(model);
...
Assert.Contains("Loaded Models:", nwfRun.StdErr);
Assert.Contains("BVH Nodes:", nwfRun.StdErr);

Исправление: Взять модель хотя бы с одной мешью и материалом и проверять значения: «Loaded Models: 2 (component files: 1)», «Total Materials: 1», «BVH Nodes: 1 (1 leaves, …)», строку «Models: 1» для папки; убедиться, что в NWF-отчёте нет «Warning: unresolved reference». Разнести папку и NWF по двум тестам.

4. [НИЗКАЯ] Заявленные инварианты (путь вывода по умолчанию, строка-итог, xref-предупреждения) не покрыты тестами — src/NwcIO.Cli/Program.cs:1363 (missing-tests; уверенность high; проверка: trace:подтвердил, intent:подтвердил)

PR заявляет «Default output paths are unchanged» и сохранение строки-итога «Assembly»/«NWF Assembly», но тестов на это нет. Ветка isNwf ? "NWF Assembly" : "Assembly" в строке-итоге для папки не отличима существующим тестом: подстрока «Assembly '» входит и в «NWF Assembly '». Новый тест гоняет только --report, где строка-итог не печатается. Путь по умолчанию (<dir>/<dirname>_assembly.glb и <nwf>.glb) вычисляется в обёртках (строки 1042 и 1413), но ни один тест не вызывает CLI без выходного пути (git grep «_assembly.glb» по tests пуст). Цикл по UnresolvedXRefs/SkippedXRefs теперь общий (строки 1345-1352), и для него в тестах CLI нет ни одного ассерта «Warning: unresolved reference». Критерий issue #102 «строка-итог для .nwf содержит число материалов» тоже ничем не проверяется: тест NWF-stdout смотрит только «NWF Assembly '» и «exported to '-'».

Уточнение проверяющего: Рефакторинг объединил пайплайны папки и .nwf без новых регрессионных тестов на сохраняемые инварианты: пути вывода по умолчанию, различие "Assembly" и "NWF Assembly" в строке-итоге (существующий ассерт "Assembly '" не отличает их), предупреждения об xref и число материалов в итоге для .nwf. Это старый пробел покрытия, а не регрессия PR (предупреждения об xref в тестах CLI не покрыты и в базе #234). Серьёзность низкая.

Сценарий: Если вызов из ProcessAssemblyDirectory потеряет isNwf: false (в сигнатуре значение по умолчанию true), то cli <folder> - напечатает «NWF Assembly '…'», а CliStdoutJsonTests.cs:181 (Assert.Contains("Assembly '", errText)) останется зелёным. Если обёртка перестанет подставлять <dir>/<dirname>_assembly.glb или <nwf>.glb, ни один тест этого не заметит. Если из итоговой строки NWF пропадёт число материалов, тоже ничего не упадёт.

$"{(isNwf ? "NWF Assembly" : "Assembly")} '{assembly.Name}': {assembly.Models.Count} models, {assembly.AllMeshes.Count} meshes, {assembly.AllMaterials.Count} materials exported to '{outputPath}' in {sw.ElapsedMilliseconds} ms."

Исправление: Добавить тесты: запуск папки и .nwf без выходного пути (проверить создание <dir>/<dirname>_assembly.glb и <nwf>.glb); запуск без --report с точной проверкой строки-итога «Assembly '…': N models, M meshes, K materials» против «NWF Assembly '…'» (через StartsWith); .nwf с неразрешённым xref и с xref не-.nwc, проверка двух предупреждений.

@mahach666
mahach666 changed the base branch from fix/nwf-pipeline-report to main November 16, 2026 20:33
@mahach666
mahach666 merged commit 4a7ff26 into main Nov 16, 2026
5 of 6 checks passed
@mahach666
mahach666 deleted the fix/assembly-pipeline-merge 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.

CLI: merge duplicated folder/NWF assembly pipelines (NWF path already ignores --bvh-stats and drops material counts)

1 participant