Refactor logging and progress reporting

[slimbuck]

Summary

Overhauls splat-transform's logging stack with a renderer-agnostic core, richer progress reporting, and a new --verbose mode. The CLI, readers, writers, voxel ops and data-table ops are all migrated to the new API.

Changes

New logging architecture (src/lib/utils/logger.ts)

• Verbosity levels: quiet | normal | verbose, filtered centrally.
• Semantic event model (scopeStart / scopeEnd, barStart / barTick / barEnd, message, output) decoupled from presentation.
• Named, timed Group scopes with optional [N/T] indices.
• Determinate Bar progress handles with Disposable support (using bar = logger.bar(...)).
• Auto-cleanup of nested bars/scopes on parent close or unwindAll().

New text renderer (src/lib/utils/text-renderer.ts)

• Default human-readable renderer; one event per line, no TTY trickery.
• Injected sinks (write / output) so it works in Node CLI and browser/library contexts.
• Optional getMemoryUsage probe overlays [rss, heap, ab] on scope/bar end lines (drives the existing --mem flag).

Formatting helpers (src/lib/utils/fmt.ts)

• fmtTime, fmtBytes, fmtCount, fmtDistance for consistent
  human-readable output across the codebase.

CLI

• New --verbose flag for debug-level diagnostics.
• Replaces the bespoke logger shim and hrtime timing block with the new logger + TextRenderer.
• README updated to document --verbose, lod-meta.json outputs, and the null sink for analysis-only runs.

Library migration

• All readers (read-ply, read-sog, read-spz, read-ksplat, read-splat, read-lcc), writers (write-ply, write-sog, write-glb, write-html, write-csv, write-voxel, write-lod, write-compressed-ply, collision-glb, sparse-octree), voxel pipeline (voxelize, dilation, carve, fill-floor, fill-exterior, block-cleanup, filter-cluster, filter-floaters) and data-table ops (decimate, gaussian-aabb, k-means) now emit scopes, bars and messages through the shared logger.
• New helpers: data-table/sh-bands.ts (getSHBands) and writers/utils.ts, exported from lib/index.
• --filter-nan help text clarified: retains +Infinity in opacity and -Infinity in scale_*.

Test plan

• npm run build succeeds.
• splat-transform --help shows the new --verbose flag and updated format/output tables.
• Default run produces the expected scope/bar output on stderr with data still going to stdout.
• --quiet suppresses everything except warnings/errors.
• --verbose adds debug diagnostics.
• --mem adds the [rss, heap, ab] overlay on scope/bar ends.
• End-to-end conversions for PLY, SOG, SPZ, KSPLAT, GLB, HTML, CSV, voxel and LOD outputs still produce identical results to main.
• Library consumers (no Node sinks injected) still work without a renderer attached.

[Copilot]

Pull request overview

Refactors splat-transform logging into a renderer-agnostic event core with improved progress reporting, and migrates CLI + library codepaths to the new API (including --verbose and richer per-step grouping/bars).

Changes:

• Introduces LoggerCore event model + TextRenderer, plus shared formatting helpers (fmt*).
• Migrates readers/writers/voxel/data-table operations from the old progress logger to scoped groups + determinate bars.
• Adds SH-band detection helper (getSHBands/shRestNames) and tracks bytesWritten in writer implementations for size reporting.

Reviewed changes

Copilot reviewed 47 out of 48 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
tsconfig.json	Enables esnext.disposable typings for Disposable support.
src/lib/writers/write-voxel.ts	Migrates voxel writer to groups/bars; adds per-file size logging.
src/lib/writers/write-sog.ts	Adds silent/omitWritingGroup; logs sizes; uses shared SH-band helpers.
src/lib/writers/write-ply.ts	Adds Writing group + size logging.
src/lib/writers/write-lod.ts	Groups output steps; adds numbered per-unit groups; logs sizes.
src/lib/writers/write-html.ts	Adds Writing group + size logging; uses writeSog silent/omit options.
src/lib/writers/write-glb.ts	Uses shared SH-band helpers; adds Writing group + size logging.
src/lib/writers/write-csv.ts	Adds Writing group + size logging.
src/lib/writers/write-compressed-ply.ts	Uses shared SH-band helpers; adds Writing group + size logging.
src/lib/writers/utils.ts	New helper to standardize “filename (size)” log entries.
src/lib/writers/sparse-octree.ts	Replaces nested progress steps with a determinate bar.
src/lib/writers/index.ts	Re-exports new writer utility helper.
src/lib/writers/collision-glb.ts	Refactors progress/messages into structured groups + formatted counts.
src/lib/write.ts	Removes top-level “writing …” log; defers to per-writer Writing groups.
src/lib/voxel/voxelize.ts	Adds voxelizing progress bar (Z-batch based).
src/lib/voxel/filter-floaters.ts	Migrates to group-based logging + formatted summaries.
src/lib/voxel/filter-cluster.ts	Migrates to group-based logging + formatted summaries/warnings.
src/lib/voxel/fill-floor.ts	Removes old progress plumbing; adds debug diagnostics.
src/lib/voxel/fill-exterior.ts	Updates messages for new logger levels/style.
src/lib/voxel/dilation.ts	Replaces progress steps with a 3-tick bar.
src/lib/voxel/carve.ts	Standardizes warning text formatting.
src/lib/voxel/block-cleanup.ts	Updates debug message wording to match new stage naming.
src/lib/utils/text-renderer.ts	New line-oriented renderer for logger events (no TTY tricks).
src/lib/utils/logger.ts	New event-driven logger core with scopes/bars/verbosity + unwind semantics.
src/lib/utils/index.ts	Re-exports new logger types, renderer, and fmt helpers.
src/lib/utils/fmt.ts	New consistent human-readable formatting helpers.
src/lib/spatial/k-means.ts	Replaces progress steps with determinate bar; adjusts debug message.
src/lib/readers/read-spz.ts	Adds decode progress bar with batched updates.
src/lib/readers/read-splat.ts	Adds decode progress bar with batched updates.
src/lib/readers/read-sog.ts	Adds multi-pass decode bar; improves source lifecycle management.
src/lib/readers/read-ply.ts	Adds single decode bar across all PLY elements/rows.
src/lib/readers/read-lcc.ts	Adds unit-based decode bar; improves source open/close + env-file handling.
src/lib/readers/read-ksplat.ts	Adds decode progress bar with batched updates.
src/lib/read.ts	Updates docs/comments to reflect per-reader progress emission.
src/lib/process.ts	Adds filter groups with consistent “delta summary” end messages; uses getSHBands.
src/lib/io/write/zip-file-system.ts	Adds bytesWritten support on zip entry writer.
src/lib/io/write/memory-file-system.ts	Tracks bytesWritten for in-memory writer.
src/lib/io/write/file-system.ts	Extends Writer interface with bytesWritten.
src/lib/index.ts	Re-exports new fmt/logger/renderer items; adjusts exported IO types.
src/lib/data-table/sh-bands.ts	New shared SH-band detection helper + column-name constants.
src/lib/data-table/index.ts	Re-exports SH-band helpers.
src/lib/data-table/gaussian-aabb.ts	Uses fmtCount for clearer warnings.
src/lib/data-table/decimate.ts	Replaces progress steps with groups + bars; adds numbered iterations.
src/lib/data-table/data-table.ts	Adds byteLength convenience for memory reporting.
src/cli/node-file-system.ts	Imports IO types from lib barrel; improves writer accounting/partial write handling.
src/cli/node-device.ts	Switches adapter detection message to logger.info.
src/cli/index.ts	Installs TextRenderer; adds --verbose; restructures phase grouping + timing output.
README.md	Documents --verbose, lod-meta.json, and null sink output.

Comments suppressed due to low confidence (1)

src/lib/io/write/zip-file-system.ts:27

• ZipEntryWriter.write increments entry.sizeBytes / updates CRC before awaiting outputWriter.write(data). If the underlying write throws (or partially writes), bytesWritten and the entry footer metadata can become inconsistent. Consider updating sizeBytes/CRC only after the write succeeds (or handling rollback on failure).

        this.write = async (data: Uint8Array) => {
            entry.sizeBytes += data.length;
            entry.crc.update(data);
            await outputWriter.write(data);

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 47 out of 48 changed files in this pull request and generated 2 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 47 out of 48 changed files in this pull request and generated 2 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 47 out of 48 changed files in this pull request and generated 1 comment.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 47 out of 48 changed files in this pull request and generated 2 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 47 out of 48 changed files in this pull request and generated 2 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 47 out of 48 changed files in this pull request and generated 1 comment.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 47 out of 48 changed files in this pull request and generated 2 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 47 out of 48 changed files in this pull request and generated 1 comment.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.