png_conform 0.1.3 → 0.1.5

data/TODO.structured-diagnostics/03c-format-aware-orchestration.md

@@ -0,0 +1,38 @@
+# 03c — Make orchestration format-aware
+
+## Purpose
+
+Route complete PNG, MNG, and JNG files through their own signatures and top-level sequence requirements so valid non-PNG inputs do not receive false PNG diagnostics.
+
+## Work
+
+- Give the active reader/orchestrator path one exact signature-to-format dispatch table for PNG (`89 50 4e 47 0d 0a 1a 0a`), MNG (`8a 4d 4e 47 0d 0a 1a 0a`), and JNG (`8b 4a 4e 47 0d 0a 1a 0a`). Preserve the detected format in validation context/result construction; an unknown signature emits its own cataloged signature diagnostic and does not trigger an arbitrary format's required-chunk findings.
+- Refactor `lib/png_conform/services/validation_orchestrator.rb` to dispatch top-level rules by detected format: PNG/APNG requires first `IHDR`, last `IEND`, and at least one `IDAT`; MNG requires first `MHDR` and last `MEND`; JNG requires first `JHDR`, last `IEND`, and at least one `JDAT`. Check actual first/last positions as well as presence, and emit the card 02 catalog IDs and format-specific citations through the canonical constructor.
+- Make `lib/png_conform/readers/streaming_reader.rb` recognize all three signatures and stop at the detected format's outer terminator (`IEND` for PNG/JNG, `MEND` for MNG), rather than rejecting or truncating an otherwise valid MNG/JNG stream. Keep `FullLoadReader` behavior covered so path-based validation continues to parse all three generic chunk streams.
+- Extend `spec/png_conform/services/validation_orchestrator_spec.rb` for each recognized and unknown signature, each format's missing/misplaced header and terminator, PNG's missing `IDAT`, JNG's missing `JDAT`, and the absence of irrelevant cross-format findings.
+- Add proposed `spec/png_conform/readers/format_dispatch_spec.rb`, `spec/integration/mng_validation_spec.rb`, and `spec/integration/jng_validation_spec.rb`. Build minimal complete files with valid CRCs in the focused specs; prove the public full-file path accepts valid `MHDR`/`MEND` and `JHDR`/`JDAT`/`IEND` streams with an empty diagnostic set. Keep `spec/integration/png_validation_spec.rb` as the PNG behavior-preservation proof.
+
+## Dependencies
+
+- Cards 01, 02, 03a, and 03b. This card owns `ValidationOrchestrator` and the reader format-dispatch specs after the shared diagnostic constructor and format validators are available.
+- Card 04 consumes the detected format and canonical top-level findings; card 05 consumes the full-file MNG/JNG integration path for goldens.
+
+## Done when
+
+- Exact PNG, MNG, and JNG signatures select the correct format, while an unknown signature yields a cataloged signature diagnostic without unrelated PNG/MNG/JNG missing-chunk findings.
+- Valid minimal PNG, MNG, and JNG files pass through the public full-file validation path with no diagnostics and the correct reported format.
+- Missing or misplaced PNG `IHDR`/`IEND`/`IDAT`, MNG `MHDR`/`MEND`, and JNG `JHDR`/`IEND`/`JDAT` produce only the applicable stable IDs, citations, severities, and chunk locations.
+- Streaming validation recognizes all three signatures, reads through the applicable outer terminator, and does not stop at an embedded MNG `IEND` before `MEND`.
+
+```bash
+bundle exec rspec spec/png_conform/services/validation_orchestrator_spec.rb \
+  spec/png_conform/readers/format_dispatch_spec.rb \
+  spec/integration/png_validation_spec.rb \
+  spec/integration/mng_validation_spec.rb \
+  spec/integration/jng_validation_spec.rb
+```
+
+## Status
+
+State: done
+PR: https://github.com/claricle/png_conform/pull/18

data/TODO.structured-diagnostics/04-report-migration.md

@@ -0,0 +1,40 @@
+# 04 — Unify Ruby, JSON, YAML, and text reports
+
+## Purpose
+
+Make the canonical diagnostic the only source for public machine and human output while adding it to existing report shapes with compatibility aliases for one documented transition.
+
+## Work
+
+- Update `PngConform::Models::ValidationResult` and `FileAnalysis#to_h` to expose the shared diagnostic projection without rebuilding or discarding fields. Add the upstream schema version at the contract-defined report location.
+- Update `JsonReporter` and `YamlReporter` to serialize that projection with stable diagnostic ordering and explicit absent-field policy. Normalize or omit volatile timestamps and host-specific paths as prescribed by the shared contract.
+- Update `TextReporter`, `SummaryReporter`, `VerboseReporter`, `VeryVerboseReporter`, `QuietReporter`, and `ColorReporter` to call the diagnostic’s human renderer, with reporter-specific filtering/color outside the diagnostic model.
+- Preserve check-command exit behavior: error-severity diagnostics make a result invalid; warnings/info do not. Keep missing-file and unexpected-process failures on the operational error path.
+- Preserve the existing Ruby readers `severity`, `message`, `chunk_type`, `chunk_offset`, `error_type`, `expected`, and `actual` as compatibility aliases for one documented transition.
+- Preserve the JSON fields actually emitted by `FileAnalysis#to_h` today: `severity` and `message`, with optional `chunk_type`, `expected`, and `actual`. Add the canonical diagnostic projection without removing or repurposing those fields. Treat any flattened `chunk_offset` or `error_type` JSON fields as deliberate new additive projections—not legacy keys—and document and pin their exact placement if they are introduced in addition to the canonical location/kind fields.
+- Update `README.adoc`, `docs/CLI_OPTIONS.adoc`, and `docs/ARCHITECTURE.adoc` with the schema/version, a structured example, location/citation semantics, and migration notes.
+
+## Dependencies
+
+- Cards 01 and 03a–03c.
+
+## Done when
+
+- Ruby API, JSON, and YAML expose the same diagnostic identity, severity, kind, citation, location, message, and context with JSON-safe values.
+- Focused model/reporter specs preserve every existing Ruby reader and the current five-field legacy JSON projection, and explicitly assert any newly added flattened `chunk_offset` or `error_type` projection as additive.
+- Text-family reporters render from the same object and preserve their documented filtering/color responsibilities.
+- Error/warning validity and CLI exit status remain covered, including operational failures that are not conformance diagnostics.
+- The documented examples match executable reporter output, identify every compatibility alias, define the transition boundary, and state the schema version.
+
+```bash
+bundle exec rspec spec/png_conform/models/validation_error_spec.rb \
+  spec/png_conform/models/validation_result_spec.rb \
+  spec/png_conform/models/file_analysis_spec.rb \
+  spec/png_conform/reporters \
+  spec/png_conform/commands/check_command_spec.rb
+```
+
+## Status
+
+State: done
+PR: https://github.com/claricle/png_conform/pull/19

data/TODO.structured-diagnostics/05-corpus-goldens.md

@@ -0,0 +1,42 @@
+# 05 — Pin corpus JSON and the release gate
+
+## Purpose
+
+Make the one-time schema transition reviewable and ensure future rule/report changes cannot silently alter diagnostics across the fixture corpus.
+
+## Work
+
+- Add `script/regenerate_diagnostic_goldens` with explicit `--write` and non-mutating `--check` modes. Process fixtures in bytewise sorted repo-relative order and reject unknown options or a dirty/partial target set.
+- Mirror all 180 PNG inputs under `spec/fixtures/diagnostics/pngsuite/` as canonical pretty JSON. Normalize input names to repo-relative paths and follow LensCore's timestamp/optional-field policy so repeated generation is byte-identical.
+- Add a small redistributable fixture set under the proposed `spec/fixtures/mng/` and `spec/fixtures/jng/` paths, with source, license, and expected-validity metadata recorded beside the fixtures. Include representative valid and invalid MNG/JNG structures that exercise their format-specific citations.
+- Mirror the MNG/JNG inputs under proposed `spec/fixtures/diagnostics/mng/` and `spec/fixtures/diagnostics/jng/` paths, and add proposed `spec/structured_diagnostics/corpus_spec.rb` to assert one-to-one cross-format input/golden coverage, parseability, schema version, deterministic ordering, and exact output equality. Include valid files with empty findings and invalid/edge files, using card 03c's format-aware full-file path rather than bypassing orchestration.
+- Perform exactly one intentional `--write` regeneration after cards 01, 02, 03a–03c, and 04 have `State: done` and the shared schema, format dispatch, and rendering policy are frozen. Then review the complete artifact diff once as a dedicated transition step; subsequent CI uses `--check` and never rewrites files.
+- Add the check to the existing Rake/CI path only after its runtime and memory usage are measured. Keep a targeted representative fixture subset for fast local development if the full corpus is too slow, but do not weaken the full CI acceptance gate.
+- Document regeneration and review procedure in `CONTRIBUTING.md`; update fixture counts only through the coverage assertion, not a hand-maintained magic number.
+
+## Dependencies
+
+- Cards 01–04, including card 03c's full-file format dispatch, and a frozen shared schema/ordering policy.
+- Suitable redistributable MNG/JNG samples and recorded license/provenance; the current checked-in corpus contains 180 PNG fixtures and no MNG/JNG fixtures.
+
+## Done when
+
+- Every checked-in PNG fixture and every newly licensed MNG/JNG fixture has exactly one deterministic structured JSON golden, including valid fixtures with no findings.
+- The MNG/JNG fixture metadata records a redistribution-compatible license, source, format, and expected validity, and the set exercises both format-specific diagnostic citations.
+- `--check` detects missing, extra, stale, reordered, schema-incompatible, or host-dependent golden output without writing files.
+- The one-time transition regeneration is isolated for human review, and later CI proves no unreviewed drift.
+- Contributor documentation explains targeted checks, full-corpus verification, and the controlled regeneration command.
+
+```bash
+bundle exec rspec spec/integration/png_validation_spec.rb \
+  spec/integration/mng_validation_spec.rb \
+  spec/integration/jng_validation_spec.rb
+script/regenerate_diagnostic_goldens --check
+bundle exec rspec spec/structured_diagnostics/corpus_spec.rb
+bundle exec rubocop
+```
+
+## Status
+
+State: done
+PR: https://github.com/claricle/png_conform/pull/12

data/TODO.structured-diagnostics/90-progress.md

@@ -0,0 +1,22 @@
+# Progress and handoff
+
+## Current state
+
+- Cards 01–05 are `done`. The structured diagnostics format from claricle/png_conform#9 is adopted end to end.
+- Reports are built on the shared LensCore contract, with the requirement catalog, format-aware orchestration (PNG/MNG/JNG) and canonical report output in place.
+- The corpus has one golden per checked-in fixture under `spec/fixtures/diagnostics/{pngsuite,idot,mng,jng}/`. Each golden is `ValidationResult#to_lens_report(filename: ...).to_h`, with every emitted diagnostic kept and no timestamp.
+- `script/regenerate_diagnostic_goldens` has `--write` and `--check` modes. `bundle exec rake diagnostics:check` runs `--check` and is part of the default `rake` task (spec, rubocop, check), so CI catches drift.
+- `spec/structured_diagnostics/corpus_spec.rb` asserts one-to-one fixture/golden coverage and exact output equality.
+- `CONTRIBUTING.md` documents targeted checks, full-corpus verification and the controlled `--write` regeneration and review steps.
+
+## Next executable action
+
+None for this effort. Regenerate goldens with `--write` only for an intended rule, report or schema change, review the full golden diff, then confirm with `bundle exec rake diagnostics:check`.
+
+## Blockers
+
+None.
+
+## Remaining gaps and risks
+
+- Dormant sources (`Services::ZlibValidator`, `Validators::StreamingIdatValidator`, `lib/png_conform/pipelines/`) remain excluded from the catalog unless a public contract is documented for them.

data/benchmarks/lib/benchmark_runner.rb

@@ -165,7 +165,7 @@ class BenchmarkRunner
     pct = (current.to_f / total * 100).round(1)
     bar_width = 40
     filled = (bar_width * current / total).to_i
-    bar = "=" * filled + " " * (bar_width - filled)
+    bar = ("=" * filled) + (" " * (bar_width - filled))
 
     print "\r  [#{bar}] #{pct}% (#{current}/#{total}) #{label}     "
     $stdout.flush

data/benchmarks/lib/metrics_collector.rb

@@ -46,8 +46,8 @@ class MetricsCollector
     tool_runs = runs_for_tool(tool)
     return nil if tool_runs.empty?
 
-    execution_times = tool_runs.map { |r| r[:execution_time] }.compact
-    memory_values = tool_runs.map { |r| r[:peak_memory] }.compact
+    execution_times = tool_runs.filter_map { |r| r[:execution_time] }
+    memory_values = tool_runs.filter_map { |r| r[:peak_memory] }
 
     {
       tool: tool,
@@ -118,7 +118,7 @@ class MetricsCollector
       total_runs: @runs.size,
       tools: tools,
       files_tested: @runs.map { |r| r[:file] }.uniq.size,
-      tool_statistics: tools.map { |tool| calculate_statistics(tool) }.compact,
+      tool_statistics: tools.filter_map { |tool| calculate_statistics(tool) },
     }
   end
 

data/benchmarks/lib/report_generator.rb

@@ -42,9 +42,9 @@ class ReportGenerator
     return "No benchmark data available.\n" if tools.empty?
 
     output = []
-    output << "=" * 80
+    output << ("=" * 80)
     output << "PNG Validation Tool Benchmark Comparison"
-    output << "=" * 80
+    output << ("=" * 80)
     output << ""
     output << "Configuration:"
     output << "  Files tested:     #{summary[:files_tested]} PNG files"
@@ -62,9 +62,9 @@ class ReportGenerator
     # Performance comparison (if we have 2 tools)
     if tools.size == 2
       comparison = metrics_collector.compare_tools(tools[0], tools[1])
-      output << "-" * 80
+      output << ("-" * 80)
       output << "PERFORMANCE SUMMARY"
-      output << "-" * 80
+      output << ("-" * 80)
       output << ""
       output << format_comparison_table(comparison)
       output << ""
@@ -73,9 +73,9 @@ class ReportGenerator
     end
 
     # Detailed statistics per tool
-    output << "-" * 80
+    output << ("-" * 80)
     output << "DETAILED STATISTICS"
-    output << "-" * 80
+    output << ("-" * 80)
     output << ""
 
     tools.each do |tool|
@@ -176,9 +176,8 @@ class ReportGenerator
   # Format comparison table for text output.
   def format_comparison_table(comparison)
     lines = []
-    lines << sprintf("%-15s %12s %12s %12s %8s",
-                     "Tool", "Avg Time", "Files/sec", "Peak Memory", "Winner")
-    lines << "-" * 80
+    lines << "Tool                Avg Time    Files/sec  Peak Memory   Winner"
+    lines << ("-" * 80)
 
     [comparison[:tool1], comparison[:tool2]].each do |tool|
       stats = comparison[:stats][tool]